@botbotgo/agent-harness 0.0.281 → 0.0.283

package/README.md

@@ -524,7 +524,7 @@ Use `normalizeUserChatInput(...)` when a product already has chat-style user mes
 import { memorize, recall } from "@botbotgo/agent-harness";
 
 await memorize(runtime, {
-  threadId: "thread-123",
+  sessionId: "session-123",
   records: [
     {
       content: "The release checklist requires a smoke test before publish.",
@@ -685,6 +685,7 @@ Core workspace files:
 - `config/catalogs/embedding-models.yaml`
 - `config/catalogs/vector-stores.yaml`
 - `config/catalogs/stores.yaml`
+- `config/knowledge/knowledge-runtime.yaml`
 - `config/runtime/runtime-memory.yaml`
 - `config/catalogs/backends.yaml`
 - `config/catalogs/tools.yaml`
@@ -703,12 +704,16 @@ Discovery rules:
 
 Example workspaces:
 
-- `examples/hello-skill-app/` keeps the smallest local tool + skill workspace
-- `examples/local-scheduled-task-app/` runs recurring prompt-driven tasks with a local `node-llama-cpp` GGUF workspace and one local tool
-- `examples/multimodal-app/` keeps the smallest image-plus-PDF example and sends both through one `request(...)` call
-- `examples/plan-and-run-app/` keeps the smallest public-API planning example and prints both the plan and the observed execution steps
-- `examples/runtime-flow-demo/` runs one real hosted-model request and exports a Mermaid flowchart from runtime plus upstream events
-- `examples/protocol-hello-world/` shows the same minimal direct agent wired to ACP, A2A, and AG-UI hello-world transport samples
+- prefixes indicate complexity order, where `00_` is the simplest starting point
+- `examples/00_local-tools-and-skills/` is the Local Tools and Skills Example: the smallest local tool + skill workspace
+- `examples/01_multimodal-request/` is the Multimodal Request Example: the smallest image-plus-PDF request flow
+- `examples/02_subagent-planning/` is the Subagent Planning Example: a compact planning flow with one subagent, tools, and trace output
+- `examples/03_protocol-surfaces/` is the Protocol Surfaces Example: the same minimal direct agent wired to ACP, ACP stdio, A2A, AG-UI, and runtime MCP
+- `examples/04_local-model-tool-calling/` is the Local Model Tool Calling Example: one local GGUF-backed task loop plus one local tool
+- `examples/05_runtime-trace-export/` is the Runtime Trace Export Example: one real run plus Mermaid flow export from runtime and upstream events
+- `examples/06_repository-analysis/` is the Repository Analysis Example: repo analysis around one workspace-local tool plus embedding-backed indexing
+- `examples/07_multi-agent-research/` is the Multi-Agent Research Example: the most complete multi-agent research workspace with reusable backends, skills, and local tools
+- `examples/08_long-term-memory-learning/` is the Long-Term Memory Learning Example: repeated requests that store durable memory, inspect recall, and make later answers more context-aware
 
 Workspace-local tool modules in `resources/tools/` should be exported with `tool({...})`.
 Any other local module shape is not supported, and unsupported shapes are rejected at load time.
@@ -870,6 +875,12 @@ Keep bootstrap context in `config/agent-context.md`. Keep resumable execution st
 - `formation.manager` for rule-driven or model-driven candidate normalization before persistence
 - `formation.background` for reflection after run completion or approval resolution
 
+### `config/knowledge/knowledge-runtime.yaml`
+
+Use this singleton when the same durable-memory policy should also run outside `AgentHarnessRuntime`, such as a standalone knowledge worker or knowledge server.
+
+`KnowledgeRuntime` mirrors the durable policy shape on purpose. Keep `RuntimeMemory` for runtime-owned defaults, and keep `KnowledgeRuntime` as the externalizable mirror when a separate knowledge service needs the same memorize/recall policy.
+
 ### `config/catalogs/backends.yaml`
 
 Use reusable backend presets so filesystem and `/memories/*` topology stays in YAML:
@@ -961,7 +972,7 @@ spec:
       maxFileSizeMb: 10
       sessionStorage:
         enabled: true
-        rootDir: "{runRoot}/threads/{threadId}/filesystem"
+        rootDir: "{runRoot}/sessions/{sessionId}/filesystem"
     middleware: []
     systemPrompt: Answer simple requests directly.
 ```
@@ -1068,7 +1079,7 @@ ACP transport notes:
 - `serveAcpHttp(runtime)` exposes JSON-RPC over HTTP plus SSE runtime events so remote operator surfaces can connect without importing the runtime in-process.
 - ACP transport validation now covers the reference-client core flow: capability discovery, request submit, session lookup, request lookup, invalid-JSON handling, notification calls without response ids, stdio JSON-RPC, and HTTP plus SSE runtime notifications.
 - Cross-protocol conformance now has an explicit regression gate as well: ACP submission, A2A task lookup and continuation, and runtime MCP inspection must all project the same persisted `sessionId` / `requestId` runtime records instead of drifting into surface-specific identifiers or side stores.
-- For the thinnest editor or CLI starter, begin with `agent-harness acp serve --workspace . --transport stdio` and mirror the `examples/protocol-hello-world/app/acp-stdio-hello-world.mjs` wire shape. Applications that want an in-process reference client can use `createAcpStdioClient(...)` to issue JSON-RPC requests and route runtime notifications without hand-rolling line parsing.
+- For the thinnest editor or CLI starter, begin with `agent-harness acp serve --workspace . --transport stdio` and mirror the `examples/03_protocol-surfaces/app/acp-stdio/main.mjs` wire shape. Applications that want an in-process reference client can use `createAcpStdioClient(...)` to issue JSON-RPC requests and route runtime notifications without hand-rolling line parsing.
 - `serveA2aHttp(runtime)` exposes an A2A-compatible HTTP JSON-RPC bridge plus agent card discovery, mapping both existing methods such as `message/send` and A2A v1.0 PascalCase methods such as `SendMessage`, `SendStreamingMessage`, `GetTask`, `ListTasks`, `CancelTask`, `SubscribeToTask`, `GetAgentCard`, `GetExtendedAgentCard`, and task push-notification config methods onto the existing session/request runtime surface. The bridge now advertises both `1.0` and `0.3` JSON-RPC interfaces, answers `HEAD` / `OPTIONS` discovery on the agent-card path, sets supported-version discovery headers, can optionally expose registry URLs plus detached signed-card metadata for surrounding discovery systems, validates `A2A-Version`, records `A2A-Extensions` into runtime invocation metadata, publishes `TASK_STATE_*` statuses plus the `{ task }` `SendMessage` wrapper, streams an initial `{ task }` snapshot plus later `{ statusUpdate }` payloads over SSE for v1 streaming methods, and can send best-effort webhook task snapshots for configured push notification receivers.
 - `serveAgUiHttp(runtime)` exposes an AG-UI-compatible HTTP SSE bridge that projects runtime lifecycle, text output, upstream thinking, step progress, and tool calls onto `RUN_*`, `TEXT_MESSAGE_*`, `THINKING_TEXT_MESSAGE_*`, `STEP_*`, and `TOOL_CALL_*` events for UI clients.
 - `createRuntimeMcpServer(runtime)` and `serveRuntimeMcpOverStdio(runtime)` expose the persisted runtime control surface itself as MCP tools, including sessions, requests, approvals, artifacts, events, and package export helpers.

package/README.zh.md

@@ -495,7 +495,7 @@ const result = await request(runtime, {
 import { memorize, recall } from "@botbotgo/agent-harness";
 
 await memorize(runtime, {
-  threadId: "thread-123",
+  sessionId: "session-123",
   records: [
     {
       content: "The release checklist requires a smoke test before publish.",
@@ -648,6 +648,7 @@ await stop(runtime);
 - `config/catalogs/embedding-models.yaml`
 - `config/catalogs/vector-stores.yaml`
 - `config/catalogs/stores.yaml`
+- `config/knowledge/knowledge-runtime.yaml`
 - `config/runtime/runtime-memory.yaml`
 - `config/catalogs/backends.yaml`
 - `config/catalogs/tools.yaml`
@@ -666,12 +667,16 @@ await stop(runtime);
 
 示例工作区：
 
-- `examples/hello-skill-app/` 保留最小的本地 tool + skill 工作区
-- `examples/local-scheduled-task-app/` 展示如何用本地 `node-llama-cpp` GGUF 工作区和一个本地 tool 执行周期性 prompt 任务
-- `examples/multimodal-app/` 保留最小的图片 + PDF 示例，并通过一次 `request(...)` 调用发送
-- `examples/plan-and-run-app/` 保留最小的公开 API 规划示例，并同时打印规划步骤和真实执行步骤
-- `examples/runtime-flow-demo/` 会跑一次真实 hosted model 请求，并把 runtime 与 upstream events 导出为 Mermaid flowchart
-- `examples/protocol-hello-world/` 展示同一个最小 direct agent 的 ACP、A2A 与 AG-UI 三种 hello-world 传输示例
+- 前缀表示复杂度顺序，`00_` 是最简单的起点
+- `examples/00_local-tools-and-skills/` 是 Local Tools and Skills Example：最小的本地 tool + skill 工作区
+- `examples/01_multimodal-request/` 是 Multimodal Request Example：最小的图片 + PDF 请求流
+- `examples/02_subagent-planning/` 是 Subagent Planning Example：带一个 subagent、工具和 trace 输出的紧凑规划流程
+- `examples/03_protocol-surfaces/` 是 Protocol Surfaces Example：同一个最小 direct agent 的 ACP、ACP stdio、A2A、AG-UI 和 runtime MCP 示例
+- `examples/04_local-model-tool-calling/` 是 Local Model Tool Calling Example：一个本地 GGUF task loop 加一个本地 tool
+- `examples/05_runtime-trace-export/` 是 Runtime Trace Export Example：一次真实运行，加上 runtime 与 upstream events 的 Mermaid 导出
+- `examples/06_repository-analysis/` 是 Repository Analysis Example：围绕一个工作区本地 tool 和 embedding 索引的仓库分析示例
+- `examples/07_multi-agent-research/` 是 Multi-Agent Research Example：最完整的多 agent 研究工作区，包含可复用 backend、skill 和本地 tool
+- `examples/08_long-term-memory-learning/` 是 Long-Term Memory Learning Example：通过多次 request 写入 durable memory、检查 recall，并让后续回答更懂上下文
 
 `resources/tools/` 下的工作区本地工具模块应统一用 `tool({...})` 导出。
 不支持历史/兼容写法，任何不带该导出形式的工具模块都会在工作区加载时被拒绝。
@@ -829,6 +834,12 @@ spec:
 - `formation.manager`：持久化前的规则式或模型式 candidate 归一化
 - `formation.background`：在 run 完成或 approval resolve 后做 reflection
 
+### `config/knowledge/knowledge-runtime.yaml`
+
+当同一套 durable-memory policy 还需要运行在 `AgentHarnessRuntime` 之外，例如独立 knowledge worker 或 knowledge server 时，使用这个单例对象。
+
+`KnowledgeRuntime` 故意镜像 durable policy 的主形状。`RuntimeMemory` 继续承载 runtime 内部默认值；而当外部 knowledge service 也需要同一套 memorize/recall policy 时，再保留 `KnowledgeRuntime` 作为可外置的镜像对象。
+
 ### `config/catalogs/backends.yaml`
 
 可复用的后端预设，使文件系统与 `/memories/*` 拓扑保留在 YAML 中：
@@ -918,7 +929,7 @@ spec:
       maxFileSizeMb: 10
       sessionStorage:
         enabled: true
-        rootDir: "{runRoot}/threads/{threadId}/filesystem"
+        rootDir: "{runRoot}/sessions/{sessionId}/filesystem"
     middleware: []
     systemPrompt: Answer simple requests directly.
 ```
@@ -1025,7 +1036,7 @@ ACP transport 说明：
 - `serveAcpHttp(runtime)` 提供基于 HTTP 的 JSON-RPC 与 SSE runtime events，适合远程界面或独立控制面接入。
 - ACP transport 现已覆盖核心参考客户端流程验证：capability discovery、request submit、session lookup、request lookup、invalid JSON 处理、无 id notification 不返回响应，以及 stdio JSON-RPC 与 HTTP + SSE runtime notifications。
 - 现在还额外有一条跨协议一致性回归门：ACP 发起的 request、A2A 读取或继续的 task，以及 runtime MCP 暴露的检查结果，必须始终指向同一组持久化 `sessionId` / `requestId` 运行时记录，不能漂移成各协议各自维护的标识体系。
-- 如果要从最薄的一层 editor / CLI starter 开始，优先用 `agent-harness acp serve --workspace . --transport stdio`，并直接参考 `examples/protocol-hello-world/app/acp-stdio-hello-world.mjs` 的 wire shape。需要在应用内使用 reference client 时，可直接用 `createAcpStdioClient(...)` 发起 JSON-RPC 请求并分流 runtime notifications，避免每个 sidecar 自己重写 line parsing。
+- 如果要从最薄的一层 editor / CLI starter 开始，优先用 `agent-harness acp serve --workspace . --transport stdio`，并直接参考 `examples/03_protocol-surfaces/app/acp-stdio/main.mjs` 的 wire shape。需要在应用内使用 reference client 时，可直接用 `createAcpStdioClient(...)` 发起 JSON-RPC 请求并分流 runtime notifications，避免每个 sidecar 自己重写 line parsing。
 - `serveA2aHttp(runtime)` 提供 A2A HTTP JSON-RPC bridge 与 agent card discovery，同时兼容 `message/send` 这类旧方法，以及 `SendMessage`、`SendStreamingMessage`、`GetTask`、`ListTasks`、`CancelTask`、`SubscribeToTask`、`GetAgentCard`、`GetExtendedAgentCard` 与 task push-notification config 这类 A2A v1.0 方法，并统一映射到现有 session/request 运行记录。bridge 现在会同时声明 `1.0` 与 `0.3` 两个 JSON-RPC interface、在 agent card 路径上响应 `HEAD` / `OPTIONS` discovery、写出支持版本的 discovery headers、可选暴露 registry URL 与 detached signed-card metadata 供外围发现系统使用、校验 `A2A-Version`、把 `A2A-Extensions` 记录进 runtime invocation metadata、发布 `TASK_STATE_*` 状态与 `SendMessage` 的 `{ task }` wrapper、在 v1 streaming 方法上先通过 SSE 输出 `{ task }` 初始快照，再输出 `{ statusUpdate }` 增量状态，并可向已配置的 webhook receiver 发送 best-effort task push notifications。
 - `serveAgUiHttp(runtime)` 提供 AG-UI HTTP SSE bridge，把 runtime 生命周期、文本输出、upstream thinking、step 进度与 tool call 投影成 `RUN_*`、`TEXT_MESSAGE_*`、`THINKING_TEXT_MESSAGE_*`、`STEP_*` 与 `TOOL_CALL_*` 事件，便于 UI 客户端直接接入。
 - `createRuntimeMcpServer(runtime)` 与 `serveRuntimeMcpOverStdio(runtime)` 会把持久化 runtime 控制面本身暴露成 MCP tools，包括 sessions、requests、approvals、artifacts、events 与 package export helpers。

package/dist/config/catalogs/stores.yaml

@@ -8,7 +8,7 @@ spec:
     name: default
     description: Default sqlite-backed store preset for runtime-managed agent state and durable memory.
     storeKind: SqliteStore
-    path: store.sqlite
+    path: knowledge/records.sqlite
 
   # agent-harness feature: reusable checkpointer preset for resumable execution state.
   - kind: Checkpointer

package/dist/config/catalogs/vector-stores.yaml

@@ -13,7 +13,7 @@ spec:
     storeKind: LibSQLVectorStore
     # LangChain aligned feature: libSQL connection URL.
     # Local SQLite files use the `file:` prefix.
-    url: file:.agent/vector-store.db
+    url: file:.agent/knowledge/vectors.sqlite
     # LangChain aligned feature: target table and embedding column.
     table: rag_chunks
     column: embedding

package/dist/config/knowledge/knowledge-runtime.yaml

@@ -0,0 +1,60 @@
+## agent-harness feature: schema version for this declarative config object.
+apiVersion: agent-harness/v1alpha1
+## agent-harness feature: standalone durable knowledge runtime defaults.
+## This object mirrors the runtime memory policy shape for future knowledge workers or servers.
+kind: KnowledgeRuntime
+metadata:
+  ## agent-harness feature: stable singleton name for the default knowledge runtime object.
+  name: default
+spec:
+  ## agent-harness feature: enable or disable standalone durable knowledge policy.
+  enabled: true
+  store:
+    ## agent-harness feature: primary durable store used by the standalone knowledge runtime.
+    ref: store/default
+  vectorStore:
+    ## agent-harness feature: optional semantic retrieval substrate for standalone knowledge recall.
+    ref: vector-store/default
+  embeddingModel:
+    ## agent-harness feature: default embedding model used with the configured vector store.
+    ref: embedding-model/default
+  namespaces:
+    ## agent-harness feature: stable namespace roots shared with runtime memory policy.
+    users: memories/users/{userId}
+    projects: memories/projects/{projectId}
+    sessions: memories/sessions/{sessionId}
+    agents: memories/agents/{agentId}
+    workspaces: memories/workspaces/{workspaceId}
+  retrieval:
+    ## agent-harness feature: bounded retrieval defaults for standalone knowledge recall.
+    defaultTopK: 5
+    maxPromptMemories: 8
+  consolidation:
+    ## agent-harness feature: background consolidation and retention defaults.
+    dedupe: true
+    decay:
+      enabled: true
+      maxAgeDays: 180
+  formation:
+    ## agent-harness feature: LangMem-style formation defaults shared with the standalone module.
+    hotPath:
+      enabled: true
+    manager:
+      enabled: true
+      strategy: rules
+      maxContextRecords: 12
+    background:
+      enabled: true
+      scopes:
+        - thread
+      stateStorePath: knowledge/formation-state.json
+      maxMessagesPerRun: 40
+      writeOnApprovalResolution: true
+      writeOnRunCompletion: true
+  mem0:
+    ## agent-harness feature: optional Mem0 OSS ingestion defaults for standalone knowledge extraction.
+    enabled: false
+    apiKeyEnv: MEM0_API_KEY
+    appId: agent-harness
+    stateStorePath: knowledge/mem0-sync-state.json
+    maxMessagesPerRun: 200

package/dist/config/runtime/runtime-memory.yaml

@@ -30,7 +30,7 @@ spec:
   namespaces:
     users: memories/users/{userId}
     projects: memories/projects/{projectId}
-    threads: memories/threads/{threadId}
+    sessions: memories/sessions/{sessionId}
     agents: memories/agents/{agentId}
     workspaces: memories/workspaces/{workspaceId}
 
@@ -78,7 +78,7 @@ spec:
       enabled: true
       scopes:
         - thread
-      stateStorePath: runtime-memory-formation-state.json
+      stateStorePath: knowledge/formation-state.json
       maxMessagesPerRun: 40
       writeOnApprovalResolution: true
       writeOnRunCompletion: true
@@ -92,5 +92,5 @@ spec:
     enabled: false
     apiKeyEnv: MEM0_API_KEY
     appId: agent-harness
-    stateStorePath: mem0-sync-state.json
+    stateStorePath: knowledge/mem0-sync-state.json
     maxMessagesPerRun: 200

package/dist/contracts/runtime.d.ts

@@ -281,6 +281,15 @@ export type MemorizeInput = {
     projectId?: string;
     recordedAt?: string;
 };
+export type KnowledgeRuntimeContext = {
+    sessionId?: string;
+    requestId?: string;
+    agentId?: string;
+    workspaceId: string;
+    userId?: string;
+    projectId?: string;
+    recordedAt?: string;
+};
 export type MemorizeResult = {
     records: MemoryRecord[];
     decisions: MemoryDecision[];

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { AgentHarnessAcpServer, AgentHarnessRuntime, cancelRun, createAgentHarness, createAcpServer, createAcpStdioClient, createRuntimeMcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportFlow, exportSequence, exportRequestPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getOperatorOverview, getRequest, getHealth, listMemories, listRequestTraceItems, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listRequestEvents, listSessionSummaries, listSessions, memorize, normalizeUserChatInput, request, recall, removeMemory, resolveApproval, serveA2aHttp, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveRuntimeMcpOverStdio, serveToolsOverStdio, subscribe, stop, updateMemory, } from "./api.js";
+export { createKnowledgeModule, readKnowledgeRuntimeConfig } from "./knowledge/index.js";
 export type { AcpApproval, AcpArtifact, AcpEventNotification, AcpJsonRpcError, AcpJsonRpcRequest, AcpJsonRpcResponse, AcpJsonRpcSuccess, AcpRequestRecord, AcpRunRequestParams, AcpServerCapabilities, AcpSessionRecord, AcpStdioClient, AcpStdioClientOptions, } from "./acp.js";
 export type { Approval, ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, NormalizeUserChatInputOptions, OperatorOverview, PublicRunListeners, RequestArtifactListing, RequestEvent, RequestEventType, RequestPackage, RequestPackageInput, RequestFlowGraphInput, RequestResult, RequestTraceItem, RecallInput, RecallResult, RemoveMemoryInput, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationReplayInput, RuntimeEvaluationReplayResult, SessionListSummary, RuntimeSessionPackage, RuntimeSessionPackageInput, UpdateMemoryInput, UserChatInput, UserChatMessage, } from "./api.js";
+export type { KnowledgeListInput, KnowledgeMemorizeInput, KnowledgeModule, KnowledgeModuleDependencies, KnowledgeRecallInput, KnowledgeRuntimeConfig, KnowledgeRuntimeContext, } from "./knowledge/index.js";
 export type { A2aAgentCard, A2aHttpServer, A2aHttpServerOptions, A2aTask, A2aTaskState, AcpHttpServer, AcpHttpServerOptions, AcpStdioServer, AcpStdioServerOptions, AgUiEvent, AgUiHttpServer, AgUiHttpServerOptions, AgUiRunAgentInput, } from "./api.js";
 export type { RuntimeMcpServerOptions, ToolMcpServerOptions } from "./mcp.js";
 export { tool } from "./tools.js";

package/dist/index.js

@@ -1,2 +1,3 @@
 export { AgentHarnessAcpServer, AgentHarnessRuntime, cancelRun, createAgentHarness, createAcpServer, createAcpStdioClient, createRuntimeMcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportFlow, exportSequence, exportRequestPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getOperatorOverview, getRequest, getHealth, listMemories, listRequestTraceItems, getSession, listAgentSkills, listArtifacts, listApprovals, listRequests, listRequestEvents, listSessionSummaries, listSessions, memorize, normalizeUserChatInput, request, recall, removeMemory, resolveApproval, serveA2aHttp, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveRuntimeMcpOverStdio, serveToolsOverStdio, subscribe, stop, updateMemory, } from "./api.js";
+export { createKnowledgeModule, readKnowledgeRuntimeConfig } from "./knowledge/index.js";
 export { tool } from "./tools.js";

package/dist/init-project.js

@@ -69,11 +69,14 @@ ${providerEnvLine}npm run start -- "Research the latest model serving stack for
 
 - \`src/run.mjs\`: minimal launcher
 - \`config/\`: workspace runtime and agent topology
+- \`config/knowledge/knowledge-runtime.yaml\`: optional standalone durable-knowledge policy mirror
 - \`resources/\`: place local \`tool({...})\` tools and skills here as your product grows
 
 ## Customize
 
 - change \`config/catalogs/models.yaml\` to switch models or providers
+- keep \`config/runtime/runtime-memory.yaml\` for runtime-owned durable memory defaults
+- keep \`config/knowledge/knowledge-runtime.yaml\` when the same policy should also run in a standalone knowledge worker or server
 - add local \`tool({...})\` tools under \`resources/tools/\`
 - add product-specific skills under \`resources/skills/\`
 - edit the prompts in \`config/agents/\` to turn this into your own product
@@ -140,11 +143,11 @@ spec:
   enabled: true
   store:
     kind: SqliteStore
-    path: runtime-memory.sqlite
+    path: knowledge/records.sqlite
   namespaces:
     users: memories/users/{userId}
     projects: memories/projects/{projectId}
-    threads: memories/threads/{threadId}
+    sessions: memories/sessions/{sessionId}
     agents: memories/agents/{agentId}
     workspaces: memories/workspaces/{workspaceId}
   retrieval:
@@ -176,7 +179,7 @@ spec:
       enabled: true
       scopes:
         - thread
-      stateStorePath: runtime-memory-formation-state.json
+      stateStorePath: knowledge/formation-state.json
       maxMessagesPerRun: 40
       writeOnApprovalResolution: true
       writeOnRunCompletion: true
@@ -186,7 +189,49 @@ spec:
     enabled: false
     apiKeyEnv: MEM0_API_KEY
     appId: ${projectSlug}
-    stateStorePath: mem0-sync-state.json
+    stateStorePath: knowledge/mem0-sync-state.json
+    maxMessagesPerRun: 200
+`;
+}
+function renderKnowledgeRuntimeYaml(projectSlug) {
+    return `apiVersion: agent-harness/v1alpha1
+kind: KnowledgeRuntime
+metadata:
+  name: default
+spec:
+  enabled: true
+  store:
+    kind: SqliteStore
+    path: knowledge/records.sqlite
+  namespaces:
+    users: memories/users/{userId}
+    projects: memories/projects/{projectId}
+    sessions: memories/sessions/{sessionId}
+    agents: memories/agents/{agentId}
+    workspaces: memories/workspaces/{workspaceId}
+  retrieval:
+    defaultTopK: 5
+    maxPromptMemories: 8
+  formation:
+    hotPath:
+      enabled: true
+    manager:
+      enabled: true
+      strategy: rules
+      maxContextRecords: 12
+    background:
+      enabled: true
+      scopes:
+        - thread
+      stateStorePath: knowledge/formation-state.json
+      maxMessagesPerRun: 40
+      writeOnApprovalResolution: true
+      writeOnRunCompletion: true
+  mem0:
+    enabled: false
+    apiKeyEnv: MEM0_API_KEY
+    appId: ${projectSlug}
+    stateStorePath: knowledge/mem0-sync-state.json
     maxMessagesPerRun: 200
 `;
 }
@@ -346,6 +391,7 @@ export async function initProject(projectRoot, projectName, options = {}) {
         ["config/runtime/workspace.yaml", renderWorkspaceYaml()],
         ["config/agent-context.md", renderAgentContext(resolved)],
         ["config/catalogs/models.yaml", renderModelsYaml(resolved)],
+        ["config/knowledge/knowledge-runtime.yaml", renderKnowledgeRuntimeYaml(projectSlug)],
         ["config/runtime/runtime-memory.yaml", renderRuntimeMemoryYaml(projectSlug)],
         ["config/catalogs/backends.yaml", renderBackendsYaml()],
         ["config/catalogs/tools.yaml", renderToolsYaml(resolved)],

package/dist/knowledge/config.d.ts

@@ -0,0 +1,11 @@
+import type { ResolvedMem0Config } from "../runtime/harness/system/mem0-ingestion-sync.js";
+import { type ResolvedRuntimeMemoryFormationConfig } from "../runtime/harness/system/runtime-memory-manager.js";
+import { type ResolvedRuntimeMemoryMaintenanceConfig, type ResolvedRuntimeMemoryPolicyConfig } from "../runtime/harness/system/runtime-memory-policy.js";
+export type KnowledgeRuntimeConfig = {
+    enabled: boolean;
+    policy: ResolvedRuntimeMemoryPolicyConfig | null;
+    maintenance: ResolvedRuntimeMemoryMaintenanceConfig | null;
+    formation: ResolvedRuntimeMemoryFormationConfig | null;
+    mem0: ResolvedMem0Config | null;
+};
+export declare function readKnowledgeRuntimeConfig(runtimeMemory: Record<string, unknown> | undefined, workspaceRoot: string): KnowledgeRuntimeConfig;

package/dist/knowledge/config.js

@@ -0,0 +1,32 @@
+import { readRuntimeMemoryFormationConfig, } from "../runtime/harness/system/runtime-memory-manager.js";
+import { readRuntimeMemoryMaintenanceConfig, readRuntimeMemoryPolicyConfig, } from "../runtime/harness/system/runtime-memory-policy.js";
+import { readMem0RuntimeConfig } from "../runtime/harness/system/mem0-ingestion-sync.js";
+function asObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+}
+function readKnowledgeRuntimeSpec(source) {
+    const typed = asObject(source);
+    if (!typed) {
+        return undefined;
+    }
+    const kind = typeof typed.kind === "string" ? typed.kind : undefined;
+    const hasTypedEnvelope = typeof typed.apiVersion === "string" || !!asObject(typed.metadata);
+    if (kind === "KnowledgeRuntime" || kind === "RuntimeMemory") {
+        return asObject(typed.spec);
+    }
+    if (hasTypedEnvelope && asObject(typed.spec)) {
+        return asObject(typed.spec);
+    }
+    return typed;
+}
+export function readKnowledgeRuntimeConfig(runtimeMemory, workspaceRoot) {
+    const runtimeMemorySpec = readKnowledgeRuntimeSpec(runtimeMemory);
+    const enabled = runtimeMemorySpec?.enabled === true;
+    return {
+        enabled,
+        policy: readRuntimeMemoryPolicyConfig(runtimeMemorySpec, workspaceRoot) ?? null,
+        maintenance: readRuntimeMemoryMaintenanceConfig(runtimeMemorySpec) ?? null,
+        formation: readRuntimeMemoryFormationConfig(runtimeMemorySpec, workspaceRoot) ?? null,
+        mem0: readMem0RuntimeConfig(runtimeMemorySpec, workspaceRoot) ?? null,
+    };
+}

package/dist/knowledge/contracts.d.ts

@@ -0,0 +1,45 @@
+import type { KnowledgeRuntimeContext, ListMemoriesInput, ListMemoriesResult, MemoryCandidate, MemoryKind, MemoryRecord, MemoryScope, MemorizeInputRecord, MemorizeResult, RecallResult, RemoveMemoryInput, UpdateMemoryInput } from "../contracts/types.js";
+export type { KnowledgeRuntimeContext } from "../contracts/types.js";
+import type { ResolvedRuntimeMemoryMaintenanceConfig, ResolvedRuntimeMemoryPolicyConfig } from "../runtime/harness/system/runtime-memory-policy.js";
+import type { StoreLike } from "../runtime/harness/system/store.js";
+import type { VectorStoreRuntimeLike } from "../runtime/support/llamaindex.js";
+import type { Mem0SearchInput, Mem0SearchResult } from "../runtime/harness/system/mem0-ingestion-sync.js";
+export type KnowledgeMemorizeInput = {
+    records: MemorizeInputRecord[];
+    storeCandidateLog?: boolean;
+};
+export type KnowledgeRecallInput = {
+    query: string;
+    scopes?: MemoryScope[];
+    kinds?: MemoryKind[];
+    topK?: number;
+    includeStale?: boolean;
+};
+export type KnowledgeListInput = Omit<ListMemoriesInput, "sessionId" | "agentId" | "workspaceId" | "userId" | "projectId">;
+export type KnowledgeNamespaceResolver = (scope: MemoryScope, context: KnowledgeRuntimeContext) => string[];
+export type KnowledgeVectorStore = Pick<VectorStoreRuntimeLike, "similaritySearch" | "addDocuments" | "delete">;
+export type KnowledgeMem0Recall = {
+    search(input: Mem0SearchInput): Promise<Mem0SearchResult[]>;
+};
+export type KnowledgeCandidateTransformer = (input: {
+    candidates: MemoryCandidate[];
+    context: KnowledgeRuntimeContext;
+    existingRecords: MemoryRecord[];
+}) => Promise<MemoryCandidate[]>;
+export type KnowledgeModuleDependencies = {
+    store: StoreLike;
+    policy: ResolvedRuntimeMemoryPolicyConfig | null;
+    maintenanceConfig: ResolvedRuntimeMemoryMaintenanceConfig | null;
+    resolveNamespace: KnowledgeNamespaceResolver;
+    resolveVectorStore: () => Promise<KnowledgeVectorStore | null>;
+    transformCandidates?: KnowledgeCandidateTransformer;
+    getMem0SemanticRecall?: () => KnowledgeMem0Recall | null | undefined;
+};
+export type KnowledgeModule = {
+    memorize(input: KnowledgeMemorizeInput, context: KnowledgeRuntimeContext): Promise<MemorizeResult>;
+    recall(input: KnowledgeRecallInput, context: KnowledgeRuntimeContext): Promise<RecallResult>;
+    buildPromptContext(input: KnowledgeRecallInput, context: KnowledgeRuntimeContext): Promise<string | undefined>;
+    list(input: KnowledgeListInput, context: KnowledgeRuntimeContext): Promise<ListMemoriesResult>;
+    update(input: UpdateMemoryInput, context: KnowledgeRuntimeContext): Promise<MemoryRecord>;
+    remove(input: RemoveMemoryInput, context: KnowledgeRuntimeContext): Promise<MemoryRecord>;
+};

package/dist/knowledge/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/knowledge/index.d.ts

@@ -0,0 +1,4 @@
+export { readKnowledgeRuntimeConfig } from "./config.js";
+export type { KnowledgeRuntimeConfig } from "./config.js";
+export type { KnowledgeListInput, KnowledgeMemorizeInput, KnowledgeModule, KnowledgeModuleDependencies, KnowledgeNamespaceResolver, KnowledgeRecallInput, KnowledgeRuntimeContext, } from "./contracts.js";
+export { createKnowledgeModule, DefaultKnowledgeModule } from "./module.js";

package/dist/knowledge/index.js

@@ -0,0 +1,2 @@
+export { readKnowledgeRuntimeConfig } from "./config.js";
+export { createKnowledgeModule, DefaultKnowledgeModule } from "./module.js";

package/dist/knowledge/module.d.ts

@@ -0,0 +1,21 @@
+import type { ListMemoriesResult, MemoryCandidate, MemoryRecord, MemorizeResult, RecallResult, UpdateMemoryInput, RemoveMemoryInput } from "../contracts/types.js";
+import type { KnowledgeListInput, KnowledgeMemorizeInput, KnowledgeModule, KnowledgeModuleDependencies, KnowledgeRecallInput, KnowledgeRuntimeContext } from "./contracts.js";
+export declare class DefaultKnowledgeModule implements KnowledgeModule {
+    private readonly deps;
+    constructor(deps: KnowledgeModuleDependencies);
+    memorize(input: KnowledgeMemorizeInput, context: KnowledgeRuntimeContext): Promise<MemorizeResult>;
+    recall(input: KnowledgeRecallInput, context: KnowledgeRuntimeContext): Promise<RecallResult>;
+    buildPromptContext(input: KnowledgeRecallInput, context: KnowledgeRuntimeContext): Promise<string | undefined>;
+    list(input: KnowledgeListInput | undefined, context: KnowledgeRuntimeContext): Promise<ListMemoriesResult>;
+    update(input: UpdateMemoryInput, context: KnowledgeRuntimeContext): Promise<MemoryRecord>;
+    remove(input: RemoveMemoryInput, context: KnowledgeRuntimeContext): Promise<MemoryRecord>;
+    memorizeCandidates(candidates: MemoryCandidate[], context: KnowledgeRuntimeContext, options: {
+        storeCandidateLog: boolean;
+    }): Promise<MemorizeResult>;
+    private refreshAfterWrite;
+    private appendMemoryDigest;
+    private refreshStructuredMemoryScope;
+    private rebuildVectorIndex;
+    private rankRecallCandidates;
+}
+export declare function createKnowledgeModule(dependencies: KnowledgeModuleDependencies): DefaultKnowledgeModule;