@botbotgo/agent-harness 0.0.153 → 0.0.155

package/README.md

@@ -118,7 +118,7 @@ That means:
 
 The runtime provides:
 
-- `createAgentHarness(workspaceRoot)`, `run(...)`, `resolveApproval(...)`, `subscribe(...)`, inspection methods, and `stop(...)`
+- `createAgentHarness(workspaceRoot)`, `run(...)`, `memorize(...)`, `recall(...)`, `resolveApproval(...)`, `subscribe(...)`, inspection methods, and `stop(...)`
 - YAML-defined workspace assembly for routing, models, tools, stores, backends, MCP, recovery, and maintenance
 - backend-adapted execution with current LangChain v1 and DeepAgents adapters
 - local `resources/tools/` `tool({...})` modules and `resources/skills/` discovery
@@ -291,6 +291,7 @@ If you want the shortest possible mental model:
 - structured output and multimodal content preservation in run results
 - MCP bridge support for agent-declared MCP servers
 - MCP server support for exposing harness tools outward
+- optional `mem0` semantic recall augmentation over canonical SQLite durable memory
 
 ### Runtime Strengths
 
@@ -389,6 +390,36 @@ const result = await run(
 
 Use `normalizeUserChatInput(...)` when a product already has chat-style user messages and wants to project one user turn onto the stable `run(..., { input, invocation })` surface without introducing a separate harness-owned chat API.
 
+### Store And Recall Durable Runtime Memory
+
+```ts
+import { memorize, recall } from "@botbotgo/agent-harness";
+
+await memorize(runtime, {
+  threadId: "thread-123",
+  records: [
+    {
+      content: "The release checklist requires a smoke test before publish.",
+      summary: "Run a smoke test before publish",
+      scope: "workspace",
+      kind: "procedural",
+      sourceRef: "docs/release-checklist.md",
+    },
+  ],
+});
+
+const recalled = await recall(runtime, {
+  query: "What does the release checklist require?",
+  scopes: ["workspace"],
+});
+```
+
+Use `memorize(...)` and `recall(...)` when an application needs a stable public runtime memory surface without importing internal `runtime/harness/system/*` modules.
+
+- `memorize(...)` returns stable `MemoryRecord` and `MemoryDecision` results while leaving merge, review, archive, and storage layout runtime-managed
+- `recall(...)` returns ranked `MemoryRecord` items filtered by runtime memory scope and kind
+- app-specific knowledge taxonomy, review UI, and admin surfaces still belong in the application layer
+
 ### Let The Runtime Route
 
 ```ts
@@ -636,8 +667,8 @@ kind: Stores
 spec:
   - kind: Store
     name: default
-    storeKind: FileStore
-    path: store.json
+    storeKind: SqliteStore
+    path: store.sqlite
   - kind: Checkpointer
     name: default
     checkpointerKind: MemorySaver
@@ -653,6 +684,12 @@ Use this singleton file for runtime-owned durable long-term memory defaults.
 
 Keep bootstrap context in `config/agent-context.md`. Keep resumable execution state in the checkpointer. Use `RuntimeMemory` for durable memory policy and retrieval defaults.
 
+`RuntimeMemory` also carries LangMem-style formation defaults:
+
+- `formation.hotPath` for immediate write-time capture
+- `formation.manager` for rule-driven or model-driven candidate normalization before persistence
+- `formation.background` for reflection after run completion or approval resolution
+
 ### `config/catalogs/backends.yaml`
 
 Use reusable DeepAgents backend presets so filesystem and `/memories/*` topology stays in YAML:

package/README.zh.md

@@ -118,7 +118,7 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 
 运行时提供：
 
-- `createAgentHarness(workspaceRoot)`、`run(...)`、`resolveApproval(...)`、`subscribe(...)`、各类查询方法，以及 `stop(...)`
+- `createAgentHarness(workspaceRoot)`、`run(...)`、`memorize(...)`、`recall(...)`、`resolveApproval(...)`、`subscribe(...)`、各类查询方法，以及 `stop(...)`
 - 以 YAML 描述的工作区装配：路由、模型、工具、存储、后端、MCP、恢复与维护等
 - 通过适配器对接当前的 LangChain v1 与 DeepAgents 执行
 - 本地 `resources/tools/` 中 `tool({...})` 工具模块与 `resources/skills/` 的发现
@@ -360,6 +360,38 @@ const result = await run(runtime, {
 - `invocation.inputs`：结构化运行时输入
 - `invocation.attachments`：当前后端可解释的类附件负载
 
+可选地，runtime memory 还可以在 SQLite canonical durable memory 之上叠加 `mem0` 语义召回增强，用于更强的长期知识命中，而不改变正式知识记录的 contract。
+
+### 写入与召回 durable runtime memory
+
+```ts
+import { memorize, recall } from "@botbotgo/agent-harness";
+
+await memorize(runtime, {
+  threadId: "thread-123",
+  records: [
+    {
+      content: "The release checklist requires a smoke test before publish.",
+      summary: "Run a smoke test before publish",
+      scope: "workspace",
+      kind: "procedural",
+      sourceRef: "docs/release-checklist.md",
+    },
+  ],
+});
+
+const recalled = await recall(runtime, {
+  query: "What does the release checklist require?",
+  scopes: ["workspace"],
+});
+```
+
+当应用需要稳定的公开 runtime memory 接口，而不想依赖内部 `runtime/harness/system/*` 模块时，使用 `memorize(...)` 与 `recall(...)`。
+
+- `memorize(...)` 返回稳定的 `MemoryRecord` 与 `MemoryDecision` 结果，而 merge、review、archive 与存储布局仍由 runtime 内部托管
+- `recall(...)` 返回按相关性排序、并按 scope / kind 过滤后的 `MemoryRecord`
+- 业务知识分类、review UI 与管理后台仍应留在应用层
+
 ### 由运行时路由
 
 ```ts
@@ -604,8 +636,8 @@ kind: Stores
 spec:
   - kind: Store
     name: default
-    storeKind: FileStore
-    path: store.json
+    storeKind: SqliteStore
+    path: store.sqlite
   - kind: Checkpointer
     name: default
     checkpointerKind: MemorySaver
@@ -615,6 +647,18 @@ spec:
     path: checkpoints.sqlite
 ```
 
+### `config/runtime/runtime-memory.yaml`
+
+这个单例文件用于配置 runtime 持有的 durable long-term memory 默认值。
+
+把稳定启动上下文放在 `config/agent-context.md`，把可恢复执行状态留给 checkpointer，把长期记忆策略与检索默认值放在 `RuntimeMemory`。
+
+`RuntimeMemory` 也承载 LangMem 风格的 formation 默认值：
+
+- `formation.hotPath`：运行中的即时捕获
+- `formation.manager`：持久化前的规则式或模型式 candidate 归一化
+- `formation.background`：在 run 完成或 approval resolve 后做 reflection
+
 ### `config/catalogs/backends.yaml`
 
 可复用的 DeepAgents 后端预设，使文件系统与 `/memories/*` 拓扑保留在 YAML 中：

package/dist/api.d.ts

@@ -1,10 +1,11 @@
-import type { CancelOptions, InvocationEnvelope, MessageContent, RequestRecord, RequestSummary, ResumeOptions, RunDecisionOptions, RunResult, RunStartOptions, RuntimeHealthSnapshot, RuntimeAdapterOptions, SessionRecord, SessionSummary, WorkspaceLoadOptions } from "./contracts/types.js";
+import type { CancelOptions, InvocationEnvelope, MemorizeInput, MemorizeResult, MessageContent, RecallInput, RecallResult, RequestRecord, RequestSummary, ResumeOptions, RunDecisionOptions, RunResult, RunStartOptions, RuntimeHealthSnapshot, RuntimeAdapterOptions, SessionRecord, SessionSummary, WorkspaceLoadOptions } from "./contracts/types.js";
 import { AgentHarnessRuntime } from "./runtime/harness.js";
 import type { InventoryAgentRecord, InventorySkillRecord } from "./runtime/harness/system/inventory.js";
 import type { RequirementAssessmentOptions } from "./runtime/harness/system/skill-requirements.js";
 import type { ToolMcpServerOptions } from "./mcp.js";
 export { AgentHarnessRuntime } from "./runtime/harness.js";
 export { createUpstreamTimelineReducer } from "./upstream-events.js";
+export type { MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, RecallInput, RecallResult, } from "./contracts/types.js";
 type PublicApprovalRecord = {
     approvalId: string;
     pendingActionId: string;
@@ -54,6 +55,8 @@ export declare function createAgentHarness(): Promise<AgentHarnessRuntime>;
 export declare function createAgentHarness(workspaceRoot: string, options?: CreateAgentHarnessOptions): Promise<AgentHarnessRuntime>;
 export declare function normalizeUserChatInput(input: UserChatInput, options?: NormalizeUserChatInputOptions): Pick<RunStartOptions, "input" | "invocation">;
 export declare function run(runtime: AgentHarnessRuntime, options: PublicRunOptions): Promise<PublicRunResult>;
+export declare function memorize(runtime: AgentHarnessRuntime, input: MemorizeInput): Promise<MemorizeResult>;
+export declare function recall(runtime: AgentHarnessRuntime, input: RecallInput): Promise<RecallResult>;
 export declare function subscribe(runtime: AgentHarnessRuntime, listener: Parameters<AgentHarnessRuntime["subscribe"]>[0]): () => void;
 export declare function listSessions(runtime: AgentHarnessRuntime, filter?: Parameters<AgentHarnessRuntime["listThreads"]>[0]): Promise<SessionSummary[]>;
 export declare function listRequests(runtime: AgentHarnessRuntime, filter?: {

package/dist/api.js

@@ -128,6 +128,12 @@ export function normalizeUserChatInput(input, options = {}) {
 export async function run(runtime, options) {
     return toPublicRunResult(await runtime.run(toInternalRunOptions(options)));
 }
+export async function memorize(runtime, input) {
+    return runtime.memorize(input);
+}
+export async function recall(runtime, input) {
+    return runtime.recall(input);
+}
 export function subscribe(runtime, listener) {
     return runtime.subscribe(listener);
 }

package/dist/config/catalogs/stores.yaml

@@ -6,9 +6,9 @@ spec:
   # agent-harness feature: reusable store preset for agent backends that need a durable key-value store.
   - kind: Store
     name: default
-    description: Default file-backed store preset for runtime-managed agent state.
-    storeKind: FileStore
-    path: store.json
+    description: Default sqlite-backed store preset for runtime-managed agent state and durable memory.
+    storeKind: SqliteStore
+    path: store.sqlite
 
   # agent-harness feature: reusable checkpointer preset for resumable execution state.
   - kind: Checkpointer

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

@@ -9,7 +9,7 @@ spec:
     # LangChain v1 Features
     # ====================
     # LangChain aligned feature: concrete vector store implementation.
-    # The built-in runtime currently supports `LibSQLVectorStore` for SQLite/libSQL-backed vector retrieval.
+    # The built-in runtime currently supports `LibSQLVectorStore`, `QdrantVectorStore`, and `LlamaIndexSimpleVectorStore`.
     storeKind: LibSQLVectorStore
     # LangChain aligned feature: libSQL connection URL.
     # Local SQLite files use the `file:` prefix.
@@ -23,3 +23,10 @@ spec:
     # ======================
     # Retrieval tools use this to resolve their default embeddings when indexing or querying this vector store.
     embeddingModelRef: embedding-model/default
+
+  - name: qdrant
+    storeKind: QdrantVectorStore
+    host: 127.0.0.1
+    port: 6333
+    collection: runtime_memory
+    embeddingModelRef: embedding-model/default

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

@@ -66,6 +66,23 @@ spec:
     writeOnApprovalResolution: true
     writeOnRunCompletion: true
 
+  # agent-harness feature: LangMem-style memory formation defaults for hot-path and background reflection.
+  formation:
+    hotPath:
+      enabled: true
+    manager:
+      enabled: true
+      strategy: rules
+      maxContextRecords: 12
+    background:
+      enabled: true
+      scopes:
+        - thread
+      stateStorePath: runtime-memory-formation-state.json
+      maxMessagesPerRun: 40
+      writeOnApprovalResolution: true
+      writeOnRunCompletion: true
+
   # agent-harness feature: optional thread snapshot projection for operational state and pending approvals.
   threadMemorySync:
     enabled: true

package/dist/contracts/runtime.d.ts

@@ -118,13 +118,14 @@ export type MemoryCandidate = {
     noStore?: boolean;
     provenance?: Record<string, unknown>;
 };
+export type MemoryKind = "semantic" | "episodic" | "procedural";
 export type MemoryScope = "thread" | "agent" | "workspace" | "user" | "project";
 export type MemoryRecordStatus = "active" | "stale" | "conflicted" | "archived" | "pending_review";
 export type MemoryDecisionAction = "reject" | "store" | "merge" | "refresh" | "supersede" | "archive" | "review";
 export type MemoryRecord = {
     id: string;
     canonicalKey: string;
-    kind: "semantic" | "episodic" | "procedural";
+    kind: MemoryKind;
     scope: MemoryScope;
     content: string;
     summary: string;
@@ -152,6 +153,48 @@ export type MemoryDecision = {
     maintenance?: "none" | "dedupe" | "merge" | "review";
     reviewRequired?: boolean;
 };
+export type MemorizeInputRecord = {
+    content: string;
+    summary?: string;
+    kind?: MemoryKind;
+    scope?: MemoryScope;
+    confidence?: number;
+    tags?: string[];
+    sourceType?: string;
+    sourceRef?: string;
+    observedAt?: string;
+    sensitivity?: string;
+    provenance?: Record<string, unknown>;
+    noStore?: boolean;
+};
+export type MemorizeInput = {
+    records: MemorizeInputRecord[];
+    threadId?: string;
+    runId?: string;
+    agentId?: string;
+    userId?: string;
+    projectId?: string;
+    recordedAt?: string;
+};
+export type MemorizeResult = {
+    records: MemoryRecord[];
+    decisions: MemoryDecision[];
+};
+export type RecallInput = {
+    query: string;
+    scopes?: MemoryScope[];
+    kinds?: MemoryKind[];
+    topK?: number;
+    includeStale?: boolean;
+    threadId?: string;
+    agentId?: string;
+    workspaceId?: string;
+    userId?: string;
+    projectId?: string;
+};
+export type RecallResult = {
+    items: MemoryRecord[];
+};
 /**
  * Operator-facing projection of tool execution policy already compiled into a binding.
  * This summarizes existing timeout, retry, validation, and retry-safety hints without

package/dist/contracts/workspace.d.ts

@@ -52,9 +52,12 @@ export type ParsedVectorStoreObject = {
     id: string;
     kind: string;
     url?: string;
+    host?: string;
+    port?: number;
     authToken?: string;
     table?: string;
     column?: string;
+    collection?: string;
     embeddingModelRef?: string;
     metadata?: Record<string, unknown>;
     sourcePath: string;
@@ -112,9 +115,12 @@ export type CompiledVectorStore = {
     id: string;
     kind: string;
     url?: string;
+    host?: string;
+    port?: number;
     authToken?: string;
     table?: string;
     column?: string;
+    collection?: string;
     embeddingModelRef?: string;
     runtimeValue: string;
 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { AgentHarnessRuntime, cancelRun, createAgentHarness, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, getAgent, getApproval, getRequest, getHealth, getSession, listAgentSkills, listApprovals, listRequests, listSessions, normalizeUserChatInput, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
-export type { NormalizeUserChatInputOptions, UserChatInput, UserChatMessage } from "./api.js";
+export { AgentHarnessRuntime, cancelRun, createAgentHarness, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, getAgent, getApproval, getRequest, getHealth, getSession, listAgentSkills, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export type { MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, NormalizeUserChatInputOptions, RecallInput, RecallResult, UserChatInput, UserChatMessage, } from "./api.js";
 export type { ToolMcpServerOptions } from "./mcp.js";
 export { tool } from "./tools.js";
 export type { UpstreamTimelineProjection, UpstreamTimelineReducer } from "./upstream-events.js";

package/dist/index.js

@@ -1,2 +1,2 @@
-export { AgentHarnessRuntime, cancelRun, createAgentHarness, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, getAgent, getApproval, getRequest, getHealth, getSession, listAgentSkills, listApprovals, listRequests, listSessions, normalizeUserChatInput, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export { AgentHarnessRuntime, cancelRun, createAgentHarness, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, getAgent, getApproval, getRequest, getHealth, getSession, listAgentSkills, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
 export { tool } from "./tools.js";

package/dist/init-project.js

@@ -138,6 +138,9 @@ metadata:
   name: default
 spec:
   enabled: true
+  store:
+    kind: SqliteStore
+    path: runtime-memory.sqlite
   namespaces:
     users: memories/users/{userId}
     projects: memories/projects/{projectId}
@@ -162,6 +165,21 @@ spec:
     backgroundConsolidation: true
     writeOnApprovalResolution: true
     writeOnRunCompletion: true
+  formation:
+    hotPath:
+      enabled: true
+    manager:
+      enabled: true
+      strategy: rules
+      maxContextRecords: 12
+    background:
+      enabled: true
+      scopes:
+        - thread
+      stateStorePath: runtime-memory-formation-state.json
+      maxMessagesPerRun: 40
+      writeOnApprovalResolution: true
+      writeOnRunCompletion: true
   threadMemorySync:
     enabled: true
   mem0:

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.152";
+export declare const AGENT_HARNESS_VERSION = "0.0.154";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.152";
+export const AGENT_HARNESS_VERSION = "0.0.154";

package/dist/runtime/harness/system/mem0-ingestion-sync.d.ts

@@ -1,4 +1,4 @@
-import { type Message as Mem0Message } from "mem0ai";
+import { type Memory as Mem0Memory, type Message as Mem0Message } from "mem0ai";
 import type { HarnessEvent, HarnessEventProjection } from "../../../contracts/types.js";
 import type { RuntimePersistence } from "../../../persistence/types.js";
 import { type StoreLike } from "./store.js";
@@ -19,8 +19,26 @@ export type ResolvedMem0Config = {
 };
 type Mem0ClientLike = {
     add(messages: Mem0Message[], options?: Record<string, unknown>): Promise<unknown>;
+    search(query: string, options?: Record<string, unknown>): Promise<Mem0Memory[]>;
+};
+export type Mem0ClientFactory = (config: ResolvedMem0Config) => Promise<Mem0ClientLike> | Mem0ClientLike;
+export type Mem0SearchInput = {
+    query: string;
+    topK: number;
+    agentId?: string;
+    threadId?: string;
+};
+export type Mem0SearchResult = {
+    id: string;
+    memory: string;
+    score: number;
+    categories: string[];
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+    agentId?: string;
+    runId?: string;
 };
-type Mem0ClientFactory = (config: ResolvedMem0Config) => Promise<Mem0ClientLike> | Mem0ClientLike;
 export declare function readMem0RuntimeConfig(runtimeMemory: Record<string, unknown> | undefined, workspaceRoot: string): ResolvedMem0Config | undefined;
 export declare class Mem0IngestionSync implements HarnessEventProjection {
     private readonly persistence;
@@ -39,4 +57,12 @@ export declare class Mem0IngestionSync implements HarnessEventProjection {
     private syncRun;
     close(): Promise<void>;
 }
+export declare class Mem0SemanticRecall {
+    private readonly config;
+    private readonly clientFactory;
+    private clientPromise;
+    constructor(config: ResolvedMem0Config, clientFactory?: Mem0ClientFactory);
+    private getClient;
+    search(input: Mem0SearchInput): Promise<Mem0SearchResult[]>;
+}
 export {};

package/dist/runtime/harness/system/mem0-ingestion-sync.js

@@ -69,7 +69,10 @@ export function readMem0RuntimeConfig(runtimeMemory, workspaceRoot) {
     };
 }
 async function createDefaultMem0Client(config) {
-    const apiKey = process.env[config.apiKeyEnv];
+    const apiKey = process.env[config.apiKeyEnv]?.trim();
+    if (!apiKey && config.host) {
+        return createSelfHostedMem0Client(config);
+    }
     if (!apiKey) {
         throw new Error(`runtimeMemory.mem0 is enabled but environment variable ${config.apiKeyEnv} is not set`);
     }
@@ -82,6 +85,47 @@ async function createDefaultMem0Client(config) {
         ...(config.projectId ? { projectId: config.projectId } : {}),
     });
 }
+function normalizeMem0Host(host) {
+    return host.replace(/\/+$/, "");
+}
+async function selfHostedMem0Request(config, pathname, options = {}) {
+    if (!config.host) {
+        throw new Error("Self-hosted mem0 client requires runtimeMemory.mem0.host.");
+    }
+    const response = await fetch(`${normalizeMem0Host(config.host)}${pathname}`, {
+        method: options.method ?? "GET",
+        headers: {
+            "Content-Type": "application/json",
+        },
+        ...(options.body ? { body: JSON.stringify(options.body) } : {}),
+    });
+    if (!response.ok) {
+        throw new Error(`Self-hosted mem0 request failed: ${response.status} ${response.statusText}`);
+    }
+    return response.json();
+}
+function createSelfHostedMem0Client(config) {
+    return {
+        async add(messages, options = {}) {
+            return selfHostedMem0Request(config, "/v1/memories/", {
+                method: "POST",
+                body: {
+                    messages,
+                    ...options,
+                },
+            });
+        },
+        async search(query, options = {}) {
+            return selfHostedMem0Request(config, "/v1/memories/search/", {
+                method: "POST",
+                body: {
+                    query,
+                    ...options,
+                },
+            });
+        },
+    };
+}
 export class Mem0IngestionSync {
     persistence;
     config;
@@ -179,3 +223,70 @@ export class Mem0IngestionSync {
         await Promise.allSettled(Array.from(this.pending));
     }
 }
+function toIsoString(value) {
+    if (value instanceof Date && !Number.isNaN(value.getTime())) {
+        return value.toISOString();
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = new Date(value);
+        return Number.isNaN(parsed.getTime()) ? undefined : parsed.toISOString();
+    }
+    return undefined;
+}
+export class Mem0SemanticRecall {
+    config;
+    clientFactory;
+    clientPromise = null;
+    constructor(config, clientFactory = createDefaultMem0Client) {
+        this.config = config;
+        this.clientFactory = clientFactory;
+    }
+    async getClient() {
+        if (!this.clientPromise) {
+            this.clientPromise = Promise.resolve(this.clientFactory(this.config));
+        }
+        return this.clientPromise;
+    }
+    async search(input) {
+        if (input.query.trim().length === 0 || input.topK <= 0) {
+            return [];
+        }
+        const client = await this.getClient();
+        const records = await client.search(input.query, {
+            top_k: input.topK,
+            limit: input.topK,
+            app_id: this.config.appId,
+            ...(input.agentId ? { agent_id: input.agentId } : {}),
+            ...(input.threadId && this.config.userIdPrefix ? { user_id: `${this.config.userIdPrefix}${input.threadId}` } : {}),
+        });
+        return records
+            .map((record) => {
+            const memory = typeof record.memory === "string" && record.memory.trim().length > 0
+                ? record.memory.trim()
+                : typeof record.data?.memory === "string" && record.data.memory.trim().length > 0
+                    ? record.data.memory.trim()
+                    : "";
+            if (!memory) {
+                return null;
+            }
+            const createdAt = toIsoString(record.created_at) ?? new Date(0).toISOString();
+            const updatedAt = toIsoString(record.updated_at) ?? createdAt;
+            return {
+                id: record.id,
+                memory,
+                score: typeof record.score === "number" && Number.isFinite(record.score) ? record.score : 0,
+                categories: Array.isArray(record.categories)
+                    ? record.categories.filter((item) => typeof item === "string" && item.trim().length > 0)
+                    : [],
+                metadata: typeof record.metadata === "object" && record.metadata && !Array.isArray(record.metadata)
+                    ? { ...record.metadata }
+                    : {},
+                createdAt,
+                updatedAt,
+                agentId: typeof record.agent_id === "string" && record.agent_id.trim().length > 0 ? record.agent_id : undefined,
+                runId: typeof record.run_id === "string" && record.run_id.trim().length > 0 ? record.run_id : undefined,
+            };
+        })
+            .filter((record) => record !== null);
+    }
+}

package/dist/runtime/harness/system/runtime-memory-manager.d.ts

@@ -0,0 +1,90 @@
+import type { CompiledAgentBinding, CompiledModel, HarnessEvent, HarnessEventProjection, InternalApprovalRecord, MemoryCandidate, MemoryRecord, MemoryScope, ThreadSummary, TranscriptMessage, WorkspaceBundle } from "../../../contracts/types.js";
+import type { RuntimePersistence } from "../../../persistence/types.js";
+import { type StoreLike } from "./store.js";
+export type ResolvedRuntimeMemoryFormationConfig = {
+    enabled: true;
+    hotPath: {
+        enabled: boolean;
+    };
+    manager: {
+        enabled: boolean;
+        strategy: "rules" | "model";
+        modelRef?: string;
+        maxContextRecords: number;
+    };
+    background: {
+        enabled: boolean;
+        maxMessagesPerRun: number;
+        scopes: MemoryScope[];
+        stateStorePath: string;
+        writeOnApprovalResolution: boolean;
+        writeOnRunCompletion: boolean;
+    };
+};
+type RuntimeMemoryFormationWriter = (input: {
+    candidates: MemoryCandidate[];
+    threadId: string;
+    runId: string;
+    agentId: string;
+    userId?: string;
+    projectId?: string;
+    recordedAt: string;
+}) => Promise<void>;
+type RuntimeMemoryFormationOptions = {
+    userId?: string;
+    projectId?: string;
+};
+type RuntimeMemoryManagerLike = {
+    transform(input: {
+        candidates: MemoryCandidate[];
+        binding: CompiledAgentBinding;
+        threadId: string;
+        runId: string;
+        recordedAt: string;
+        existingRecords: MemoryRecord[];
+    }): Promise<MemoryCandidate[]>;
+};
+export declare function readRuntimeMemoryFormationConfig(runtimeMemory: Record<string, unknown> | undefined, workspaceRoot: string): ResolvedRuntimeMemoryFormationConfig | undefined;
+export declare function createBackgroundMemoryCandidates(input: {
+    thread: ThreadSummary;
+    runId: string;
+    agentId: string;
+    trigger: "approval.resolved" | "run.completed";
+    recordedAt: string;
+    messages: TranscriptMessage[];
+    approvals: InternalApprovalRecord[];
+    scopes: MemoryScope[];
+}): MemoryCandidate[];
+export declare function runModelMemoryManager(input: {
+    workspace: WorkspaceBundle;
+    binding: CompiledAgentBinding;
+    model: CompiledModel;
+    candidates: MemoryCandidate[];
+    threadId: string;
+    runId: string;
+    recordedAt: string;
+    existingRecords: MemoryRecord[];
+    modelResolver?: (modelId: string) => unknown;
+}): Promise<MemoryCandidate[]>;
+export declare function createRuntimeMemoryManager(input: {
+    workspace: WorkspaceBundle;
+    binding: CompiledAgentBinding;
+    config: ResolvedRuntimeMemoryFormationConfig;
+    modelResolver?: (modelId: string) => unknown;
+}): RuntimeMemoryManagerLike;
+export declare class RuntimeMemoryFormationSync implements HarnessEventProjection {
+    private readonly persistence;
+    private readonly config;
+    private readonly writer;
+    private readonly stateStore;
+    private readonly options;
+    private readonly pending;
+    private syncChain;
+    readonly name = "runtime-memory-formation-sync";
+    constructor(persistence: RuntimePersistence, config: ResolvedRuntimeMemoryFormationConfig, writer: RuntimeMemoryFormationWriter, runRoot: string, stateStore?: StoreLike, options?: RuntimeMemoryFormationOptions);
+    shouldHandle(event: HarnessEvent): boolean;
+    handleEvent(event: HarnessEvent): Promise<void>;
+    private reflectRun;
+    close(): Promise<void>;
+}
+export {};