@botbotgo/agent-harness 0.0.152 → 0.0.154

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
@@ -389,6 +389,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

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,36 @@ const result = await run(runtime, {
 - `invocation.inputs`：结构化运行时输入
 - `invocation.attachments`：当前后端可解释的类附件负载
 
+### 写入与召回 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

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/contracts/runtime.d.ts

@@ -118,6 +118,83 @@ 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: MemoryKind;
+    scope: MemoryScope;
+    content: string;
+    summary: string;
+    status: MemoryRecordStatus;
+    confidence: number;
+    createdAt: string;
+    observedAt: string;
+    lastConfirmedAt: string;
+    expiresAt?: string;
+    sourceType: string;
+    sourceRefs: string[];
+    tags: string[];
+    provenance: Record<string, unknown>;
+    revision: number;
+    supersedes: string[];
+    conflictsWith: string[];
+};
+export type MemoryDecision = {
+    action: MemoryDecisionAction;
+    reason: string;
+    recordId?: string;
+    kind?: MemoryRecord["kind"];
+    scope?: MemoryScope;
+    confidence?: number;
+    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/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/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.151";
+export declare const AGENT_HARNESS_VERSION = "0.0.153";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.151";
+export const AGENT_HARNESS_VERSION = "0.0.153";

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

@@ -0,0 +1,12 @@
+import type { MemoryScope } from "../../../contracts/types.js";
+import type { ResolvedRuntimeMemoryMaintenanceConfig } from "./runtime-memory-policy.js";
+import type { StoreLike } from "./store.js";
+export declare function consolidateStructuredMemoryScope(input: {
+    store: StoreLike;
+    namespace: string[];
+    scope: MemoryScope;
+    title: string;
+    maxEntries: number;
+    config: ResolvedRuntimeMemoryMaintenanceConfig | undefined;
+    now?: string;
+}): Promise<void>;

package/dist/runtime/harness/system/runtime-memory-consolidation.js

@@ -0,0 +1,51 @@
+import { listMemoryRecordsForScopes, rebuildStructuredMemoryProjections } from "./runtime-memory-records.js";
+function normalizeText(value) {
+    return value.toLowerCase().replace(/\s+/g, " ").trim();
+}
+function sortByLastConfirmed(records) {
+    return [...records].sort((left, right) => left.lastConfirmedAt.localeCompare(right.lastConfirmedAt));
+}
+export async function consolidateStructuredMemoryScope(input) {
+    const now = input.now ?? new Date().toISOString();
+    const records = sortByLastConfirmed(await listMemoryRecordsForScopes(input.store, [input.scope]));
+    const updates = new Map();
+    if (input.config?.dedupe !== false) {
+        const activeRecords = records.filter((record) => record.status === "active");
+        const seen = new Map();
+        for (const record of activeRecords) {
+            const identity = `${record.canonicalKey}:${normalizeText(record.content)}`;
+            const prior = seen.get(identity);
+            if (!prior) {
+                seen.set(identity, record);
+                continue;
+            }
+            const archived = {
+                ...prior,
+                status: "archived",
+                lastConfirmedAt: now,
+                supersedes: Array.from(new Set([...prior.supersedes, record.id])),
+                revision: prior.revision + 1,
+            };
+            updates.set(archived.id, archived);
+            seen.set(identity, record);
+        }
+    }
+    if (typeof input.config?.maxAgeDays === "number" && input.config.maxAgeDays > 0) {
+        const threshold = Date.parse(now) - input.config.maxAgeDays * 24 * 60 * 60 * 1000;
+        for (const record of records) {
+            if (record.status !== "active") {
+                continue;
+            }
+            const updated = Date.parse(record.lastConfirmedAt);
+            if (Number.isFinite(updated) && updated < threshold) {
+                updates.set(record.id, {
+                    ...record,
+                    status: "stale",
+                    revision: record.revision + 1,
+                });
+            }
+        }
+    }
+    await Promise.all(Array.from(updates.values()).map((record) => input.store.put(["memories", "records", input.scope], `${record.id}.json`, record)));
+    await rebuildStructuredMemoryProjections(input.store, input.namespace, input.title, input.scope, input.maxEntries);
+}

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

@@ -12,7 +12,13 @@ export type ResolvedRuntimeMemoryPolicyConfig = {
         project: string;
     };
 };
+export type ResolvedRuntimeMemoryMaintenanceConfig = {
+    enabled: true;
+    dedupe: boolean;
+    maxAgeDays?: number;
+};
 export declare function normalizeLangMemMemoryKind(kind: string | undefined): "semantic" | "episodic" | "procedural";
 export declare function readRuntimeMemoryPolicyConfig(runtimeMemory: Record<string, unknown> | undefined, workspaceRoot: string): ResolvedRuntimeMemoryPolicyConfig | undefined;
+export declare function readRuntimeMemoryMaintenanceConfig(runtimeMemory: Record<string, unknown> | undefined): ResolvedRuntimeMemoryMaintenanceConfig | undefined;
 export declare function resolveMemoryNamespace(template: string, values: Record<string, string | undefined>): string[];
 export declare function scoreMemoryText(query: string, content: string, scopeBoost?: number): number;

package/dist/runtime/harness/system/runtime-memory-policy.js

@@ -43,6 +43,21 @@ export function readRuntimeMemoryPolicyConfig(runtimeMemory, workspaceRoot) {
         },
     };
 }
+export function readRuntimeMemoryMaintenanceConfig(runtimeMemory) {
+    if (runtimeMemory?.enabled !== true) {
+        return undefined;
+    }
+    const consolidation = asRecord(runtimeMemory.consolidation);
+    const decay = asRecord(consolidation?.decay);
+    return {
+        enabled: true,
+        dedupe: consolidation?.dedupe !== false,
+        ...(asBoolean(decay?.enabled) !== false && asPositiveInteger(decay?.maxAgeDays) ? { maxAgeDays: asPositiveInteger(decay?.maxAgeDays) } : {}),
+    };
+}
+function asBoolean(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
 export function resolveMemoryNamespace(template, values) {
     const rendered = template.replace(/\{([a-zA-Z0-9_]+)\}/g, (_match, key) => values[key] ?? key);
     return rendered

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

@@ -0,0 +1,21 @@
+import type { MemoryCandidate, MemoryDecision, MemoryRecord, MemoryScope } from "../../../contracts/types.js";
+import type { StoreLike } from "./store.js";
+type PersistMemoryRecordsOptions = {
+    store: StoreLike;
+    candidates: MemoryCandidate[];
+    threadId: string;
+    runId: string;
+    agentId: string;
+    workspaceId: string;
+    userId: string;
+    projectId: string;
+    recordedAt: string;
+};
+export declare function renderMemoryRecordsMarkdown(title: string, records: MemoryRecord[]): string;
+export declare function rebuildStructuredMemoryProjections(store: StoreLike, namespace: string[], title: string, scope: MemoryScope, maxEntries: number): Promise<void>;
+export declare function listMemoryRecordsForScopes(store: StoreLike, scopes: MemoryScope[]): Promise<MemoryRecord[]>;
+export declare function persistStructuredMemoryRecords(options: PersistMemoryRecordsOptions): Promise<{
+    records: MemoryRecord[];
+    decisions: MemoryDecision[];
+}>;
+export {};

package/dist/runtime/harness/system/runtime-memory-records.js

@@ -0,0 +1,405 @@
+import { createHash } from "node:crypto";
+import { normalizeLangMemMemoryKind } from "./runtime-memory-policy.js";
+const MEMORY_SCOPES = ["thread", "agent", "workspace", "user", "project"];
+function normalizeScope(scope) {
+    if (scope === "agent" || scope === "workspace" || scope === "user" || scope === "project") {
+        return scope;
+    }
+    return "thread";
+}
+function normalizeSummary(candidate) {
+    const value = candidate.summary?.trim() || candidate.content.trim().split("\n")[0] || candidate.content.trim();
+    return value.slice(0, 240);
+}
+function createFingerprint(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+function normalizeConfidence(value) {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+        return 0.5;
+    }
+    return Math.min(1, Math.max(0, value));
+}
+function normalizeSourceRef(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function createCanonicalKey(candidate, kind, scope) {
+    const sourceRef = normalizeSourceRef(candidate.sourceRef);
+    if (sourceRef) {
+        return `${kind}:${scope}:source:${createFingerprint(sourceRef)}`;
+    }
+    const base = normalizeSummary(candidate).toLowerCase().replace(/\s+/g, " ").trim();
+    return `${kind}:${scope}:summary:${createFingerprint(base)}`;
+}
+function buildScopeNamespace(scope) {
+    return ["memories", "records", scope];
+}
+function normalizeTextForCompare(value) {
+    return value.toLowerCase().replace(/\s+/g, " ").trim();
+}
+function tokenize(value) {
+    return new Set(value
+        .toLowerCase()
+        .split(/[^a-z0-9_]+/i)
+        .map((token) => token.trim())
+        .filter((token) => token.length > 2));
+}
+function jaccardSimilarity(left, right) {
+    const leftTokens = tokenize(left);
+    const rightTokens = tokenize(right);
+    if (leftTokens.size === 0 || rightTokens.size === 0) {
+        return 0;
+    }
+    let intersection = 0;
+    for (const token of leftTokens) {
+        if (rightTokens.has(token)) {
+            intersection += 1;
+        }
+    }
+    const union = new Set([...leftTokens, ...rightTokens]).size;
+    return union === 0 ? 0 : intersection / union;
+}
+function hasNegationSignal(value) {
+    const normalized = ` ${normalizeTextForCompare(value)} `;
+    return (normalized.includes(" not ") ||
+        normalized.includes(" no ") ||
+        normalized.includes(" never ") ||
+        normalized.includes(" without ") ||
+        normalized.includes(" do not ") ||
+        normalized.includes(" does not ") ||
+        normalized.includes(" did not "));
+}
+function mergeUniqueStrings(left, right) {
+    return Array.from(new Set([...left, ...right].filter((item) => item.trim().length > 0)));
+}
+function mergeRecordContent(left, right) {
+    const normalizedLeft = normalizeTextForCompare(left);
+    const normalizedRight = normalizeTextForCompare(right);
+    if (normalizedLeft === normalizedRight) {
+        return left;
+    }
+    if (normalizedLeft.includes(normalizedRight)) {
+        return left;
+    }
+    if (normalizedRight.includes(normalizedLeft)) {
+        return right;
+    }
+    return `${left.trim()}\n\n${right.trim()}`;
+}
+function createMemoryRecord(candidate, options) {
+    const kind = normalizeLangMemMemoryKind(candidate.kind);
+    const scope = normalizeScope(candidate.scope);
+    const canonicalKey = createCanonicalKey(candidate, kind, scope);
+    const id = createFingerprint([
+        canonicalKey,
+        candidate.content.trim(),
+        options.threadId,
+        options.runId,
+        options.agentId,
+        options.recordedAt,
+    ].join("\n"));
+    const sourceRef = normalizeSourceRef(candidate.sourceRef);
+    return {
+        id,
+        canonicalKey,
+        kind,
+        scope,
+        content: candidate.content.trim(),
+        summary: normalizeSummary(candidate),
+        status: "active",
+        confidence: normalizeConfidence(candidate.confidence),
+        createdAt: options.recordedAt,
+        observedAt: candidate.observedAt ?? options.recordedAt,
+        lastConfirmedAt: options.recordedAt,
+        sourceType: candidate.sourceType?.trim() || "tool-output",
+        sourceRefs: sourceRef ? [sourceRef] : [],
+        tags: candidate.tags ?? [],
+        provenance: {
+            threadId: options.threadId,
+            runId: options.runId,
+            agentId: options.agentId,
+            workspaceId: options.workspaceId,
+            userId: options.userId,
+            projectId: options.projectId,
+            ...(candidate.provenance ?? {}),
+        },
+        revision: 1,
+        supersedes: [],
+        conflictsWith: [],
+    };
+}
+function isSameRecordContent(left, right) {
+    return normalizeTextForCompare(left.content) === normalizeTextForCompare(right.content);
+}
+function refreshRecord(existing, incoming, recordedAt) {
+    return {
+        ...existing,
+        summary: incoming.summary.length > existing.summary.length ? incoming.summary : existing.summary,
+        confidence: Math.max(existing.confidence, incoming.confidence),
+        observedAt: incoming.observedAt,
+        lastConfirmedAt: recordedAt,
+        sourceRefs: mergeUniqueStrings(existing.sourceRefs, incoming.sourceRefs),
+        tags: mergeUniqueStrings(existing.tags, incoming.tags),
+        provenance: {
+            ...existing.provenance,
+            refreshedFrom: incoming.provenance,
+            lastRefreshRunId: incoming.provenance.runId,
+            lastRefreshThreadId: incoming.provenance.threadId,
+        },
+        revision: existing.revision + 1,
+    };
+}
+function mergeRecord(existing, incoming, recordedAt) {
+    return {
+        ...existing,
+        content: mergeRecordContent(existing.content, incoming.content),
+        summary: incoming.summary.length >= existing.summary.length ? incoming.summary : existing.summary,
+        confidence: Math.max(existing.confidence, incoming.confidence),
+        observedAt: incoming.observedAt,
+        lastConfirmedAt: recordedAt,
+        sourceRefs: mergeUniqueStrings(existing.sourceRefs, incoming.sourceRefs),
+        tags: mergeUniqueStrings(existing.tags, incoming.tags),
+        provenance: {
+            ...existing.provenance,
+            mergedFrom: incoming.provenance,
+            lastMergeRunId: incoming.provenance.runId,
+            lastMergeThreadId: incoming.provenance.threadId,
+        },
+        revision: existing.revision + 1,
+    };
+}
+function markConflicted(record, conflictingRecordId, recordedAt) {
+    return {
+        ...record,
+        status: "conflicted",
+        lastConfirmedAt: recordedAt,
+        conflictsWith: mergeUniqueStrings(record.conflictsWith, [conflictingRecordId]),
+        revision: record.revision + 1,
+    };
+}
+function createReviewRecord(existing, incoming, recordedAt) {
+    return {
+        ...incoming,
+        status: "pending_review",
+        conflictsWith: mergeUniqueStrings(incoming.conflictsWith, [existing.id]),
+        lastConfirmedAt: recordedAt,
+    };
+}
+async function listStoredRecords(store, scope) {
+    const scopes = scope ? [scope] : MEMORY_SCOPES;
+    const docs = await Promise.all(scopes.map((currentScope) => store.search(buildScopeNamespace(currentScope))));
+    return docs
+        .flat()
+        .map((entry) => entry.value)
+        .filter((record) => typeof record?.id === "string" && typeof record.content === "string");
+}
+function findMatchingRecord(existingRecords, incoming) {
+    const exact = existingRecords.find((record) => record.scope === incoming.scope && isSameRecordContent(record, incoming));
+    if (exact) {
+        return exact;
+    }
+    const sourceRefMatch = existingRecords.find((record) => record.scope === incoming.scope &&
+        incoming.sourceRefs.some((sourceRef) => record.sourceRefs.includes(sourceRef)));
+    if (sourceRefMatch) {
+        return sourceRefMatch;
+    }
+    return existingRecords.find((record) => record.scope === incoming.scope && record.canonicalKey === incoming.canonicalKey);
+}
+function evaluateDecision(existing, incoming, recordedAt) {
+    if (!existing) {
+        return {
+            decision: {
+                action: "store",
+                reason: "Stored as a new durable memory record.",
+                recordId: incoming.id,
+                kind: incoming.kind,
+                scope: incoming.scope,
+                confidence: incoming.confidence,
+                maintenance: "dedupe",
+                reviewRequired: false,
+            },
+            primaryRecord: incoming,
+            additionalRecords: [],
+        };
+    }
+    if (isSameRecordContent(existing, incoming)) {
+        const refreshed = refreshRecord(existing, incoming, recordedAt);
+        return {
+            decision: {
+                action: "refresh",
+                reason: "Refreshed an exact durable memory match.",
+                recordId: refreshed.id,
+                kind: refreshed.kind,
+                scope: refreshed.scope,
+                confidence: refreshed.confidence,
+                maintenance: "none",
+                reviewRequired: false,
+            },
+            primaryRecord: refreshed,
+            additionalRecords: [],
+        };
+    }
+    if (existing.canonicalKey === incoming.canonicalKey ||
+        incoming.sourceRefs.some((sourceRef) => existing.sourceRefs.includes(sourceRef))) {
+        if (hasNegationSignal(existing.content) !== hasNegationSignal(incoming.content)) {
+            const conflictedExisting = markConflicted(existing, incoming.id, recordedAt);
+            const pendingReview = createReviewRecord(conflictedExisting, incoming, recordedAt);
+            return {
+                decision: {
+                    action: "review",
+                    reason: "Detected conflicting durable memory with the same canonical identity.",
+                    recordId: pendingReview.id,
+                    kind: pendingReview.kind,
+                    scope: pendingReview.scope,
+                    confidence: pendingReview.confidence,
+                    maintenance: "review",
+                    reviewRequired: true,
+                },
+                primaryRecord: conflictedExisting,
+                additionalRecords: [pendingReview],
+            };
+        }
+        const similarity = jaccardSimilarity(existing.summary, incoming.summary);
+        if (similarity >= 0.45) {
+            const merged = mergeRecord(existing, incoming, recordedAt);
+            return {
+                decision: {
+                    action: "merge",
+                    reason: "Merged a matching durable memory record with compatible additions.",
+                    recordId: merged.id,
+                    kind: merged.kind,
+                    scope: merged.scope,
+                    confidence: merged.confidence,
+                    maintenance: "merge",
+                    reviewRequired: false,
+                },
+                primaryRecord: merged,
+                additionalRecords: [],
+            };
+        }
+        const conflictedExisting = markConflicted(existing, incoming.id, recordedAt);
+        const pendingReview = createReviewRecord(conflictedExisting, incoming, recordedAt);
+        return {
+            decision: {
+                action: "review",
+                reason: "Detected conflicting durable memory with the same canonical identity.",
+                recordId: pendingReview.id,
+                kind: pendingReview.kind,
+                scope: pendingReview.scope,
+                confidence: pendingReview.confidence,
+                maintenance: "review",
+                reviewRequired: true,
+            },
+            primaryRecord: conflictedExisting,
+            additionalRecords: [pendingReview],
+        };
+    }
+    return {
+        decision: {
+            action: "store",
+            reason: "Stored as a new durable memory record.",
+            recordId: incoming.id,
+            kind: incoming.kind,
+            scope: incoming.scope,
+            confidence: incoming.confidence,
+            maintenance: "dedupe",
+            reviewRequired: false,
+        },
+        primaryRecord: incoming,
+        additionalRecords: [],
+    };
+}
+async function putRecordWithIndexes(store, record, updatedAt) {
+    const canonicalKeyId = createFingerprint(record.canonicalKey);
+    await store.put(buildScopeNamespace(record.scope), `${record.id}.json`, record);
+    await store.put(["memories", "indexes", "canonical", record.scope], `${canonicalKeyId}-${record.id}.json`, {
+        canonicalKey: record.canonicalKey,
+        recordId: record.id,
+        scope: record.scope,
+        kind: record.kind,
+        updatedAt,
+    });
+    await Promise.all(record.sourceRefs.map((sourceRef) => {
+        const sourceRefId = createFingerprint(sourceRef);
+        return store.put(["memories", "indexes", "source-ref", record.scope], `${sourceRefId}-${record.id}.json`, {
+            sourceRef,
+            recordId: record.id,
+            scope: record.scope,
+            kind: record.kind,
+            updatedAt,
+        });
+    }));
+}
+export function renderMemoryRecordsMarkdown(title, records) {
+    const lines = [`# ${title}`, ""];
+    if (records.length === 0) {
+        lines.push("(none)", "");
+        return lines.join("\n");
+    }
+    for (const record of records) {
+        lines.push(`## ${record.summary}`);
+        lines.push(`- kind: ${record.kind}`);
+        lines.push(`- scope: ${record.scope}`);
+        lines.push(`- status: ${record.status}`);
+        lines.push(`- confidence: ${record.confidence.toFixed(2)}`);
+        if (record.tags.length > 0) {
+            lines.push(`- tags: ${record.tags.join(", ")}`);
+        }
+        lines.push("");
+        lines.push(record.content);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+export async function rebuildStructuredMemoryProjections(store, namespace, title, scope, maxEntries) {
+    const records = (await listStoredRecords(store, scope))
+        .filter((record) => record.status === "active")
+        .sort((left, right) => left.lastConfirmedAt.localeCompare(right.lastConfirmedAt))
+        .slice(-maxEntries);
+    await store.put(namespace, "structured-memory.md", {
+        content: `${renderMemoryRecordsMarkdown(title, records)}\n`,
+        items: records,
+    });
+    const grouped = new Map();
+    for (const record of records) {
+        const current = grouped.get(record.kind) ?? [];
+        current.push(record);
+        grouped.set(record.kind, current);
+    }
+    await Promise.all(Array.from(grouped.entries()).map(([kind, items]) => store.put(namespace, `${kind}.md`, {
+        content: `${renderMemoryRecordsMarkdown(`${title} (${kind})`, items)}\n`,
+        items,
+    })));
+}
+export async function listMemoryRecordsForScopes(store, scopes) {
+    const all = await Promise.all(scopes.map((scope) => listStoredRecords(store, scope)));
+    return all.flat();
+}
+export async function persistStructuredMemoryRecords(options) {
+    const existingRecords = await listStoredRecords(options.store);
+    const persistedRecords = [];
+    const decisions = [];
+    for (const candidate of options.candidates) {
+        const incoming = createMemoryRecord(candidate, options);
+        const existing = findMatchingRecord(existingRecords, incoming);
+        const evaluated = evaluateDecision(existing, incoming, options.recordedAt);
+        const recordsToWrite = [evaluated.primaryRecord, ...evaluated.additionalRecords];
+        for (const record of recordsToWrite) {
+            await putRecordWithIndexes(options.store, record, options.recordedAt);
+            const existingIndex = existingRecords.findIndex((item) => item.id === record.id);
+            if (existingIndex >= 0) {
+                existingRecords[existingIndex] = record;
+            }
+            else {
+                existingRecords.push(record);
+            }
+        }
+        await options.store.put(["memories", "decisions", options.threadId, options.runId], `${evaluated.decision.recordId ?? incoming.id}.json`, evaluated.decision);
+        decisions.push(evaluated.decision);
+        persistedRecords.push(...recordsToWrite);
+    }
+    return {
+        records: persistedRecords,
+        decisions,
+    };
+}

package/dist/runtime/harness.d.ts

@@ -1,4 +1,4 @@
-import type { ApprovalRecord, CancelOptions, HarnessEvent, HarnessStreamItem, RuntimeHealthSnapshot, MessageContent, RunRecord, RunStartOptions, RestartConversationOptions, RuntimeAdapterOptions, ResumeOptions, RunOptions, RunResult, RunSummary, ThreadSummary, ThreadRecord, WorkspaceBundle } from "../contracts/types.js";
+import type { ApprovalRecord, CancelOptions, HarnessEvent, HarnessStreamItem, RuntimeHealthSnapshot, MessageContent, RunRecord, RunStartOptions, RestartConversationOptions, RuntimeAdapterOptions, ResumeOptions, RunOptions, RunResult, RunSummary, MemorizeInput, MemorizeResult, RecallInput, RecallResult, ThreadSummary, ThreadRecord, WorkspaceBundle } from "../contracts/types.js";
 import { type ToolMcpServerOptions } from "../mcp.js";
 import { type InventoryAgentRecord, type InventorySkillRecord } from "./harness/system/inventory.js";
 import type { RequirementAssessmentOptions } from "./harness/system/skill-requirements.js";
@@ -20,6 +20,7 @@ export declare class AgentHarnessRuntime {
     private readonly defaultStore;
     private readonly runtimeMemoryStore;
     private readonly runtimeMemoryPolicy;
+    private readonly runtimeMemoryMaintenanceConfig;
     private readonly routingRules;
     private readonly routingDefaultAgentId?;
     private readonly threadMemorySync;
@@ -61,6 +62,8 @@ export declare class AgentHarnessRuntime {
         threadId?: string;
         state?: RunSummary["state"];
     }): Promise<RunSummary[]>;
+    memorize(input: MemorizeInput): Promise<MemorizeResult>;
+    recall(input: RecallInput): Promise<RecallResult>;
     getRun(runId: string): Promise<RunRecord | null>;
     private getSession;
     getThread(threadId: string): Promise<ThreadRecord | null>;
@@ -92,8 +95,13 @@ export declare class AgentHarnessRuntime {
     private finalizeCancelledRun;
     private invokeWithHistory;
     private resolveMemoryNamespace;
+    private getWorkspaceId;
+    private resolveRecallScopes;
+    private matchesRecallScope;
+    private getMemoryScopeBoost;
     private buildRuntimeMemoryContext;
     private persistRuntimeMemoryCandidates;
+    private persistStructuredMemoryCandidates;
     private appendMemoryDigest;
     private resolvePersistedRunPriority;
     private enqueuePendingRunSlot;

package/dist/runtime/harness.js

@@ -30,7 +30,9 @@ import { describeWorkspaceInventory, getAgentInventoryRecord, listAgentSkills as
 import { createDefaultHealthSnapshot, isInventoryEnabled, isThreadMemorySyncEnabled, } from "./harness/runtime-defaults.js";
 import { Mem0IngestionSync, readMem0RuntimeConfig } from "./harness/system/mem0-ingestion-sync.js";
 import { renderMemoryCandidatesMarkdown } from "./harness/system/runtime-memory-candidates.js";
-import { normalizeLangMemMemoryKind, readRuntimeMemoryPolicyConfig, resolveMemoryNamespace, scoreMemoryText, } from "./harness/system/runtime-memory-policy.js";
+import { listMemoryRecordsForScopes, persistStructuredMemoryRecords, } from "./harness/system/runtime-memory-records.js";
+import { consolidateStructuredMemoryScope } from "./harness/system/runtime-memory-consolidation.js";
+import { normalizeLangMemMemoryKind, readRuntimeMemoryMaintenanceConfig, readRuntimeMemoryPolicyConfig, resolveMemoryNamespace, scoreMemoryText, } from "./harness/system/runtime-memory-policy.js";
 import { resolveRuntimeAdapterOptions } from "./support/runtime-adapter-options.js";
 import { initializeHarnessRuntime, reclaimExpiredClaimedRuns as reclaimHarnessExpiredClaimedRuns, recoverStartupRuns as recoverHarnessStartupRuns, isStaleRunningRun as isHarnessStaleRunningRun, } from "./harness/run/startup-runtime.js";
 import { streamHarnessRun } from "./harness/run/stream-run.js";
@@ -59,6 +61,7 @@ export class AgentHarnessRuntime {
     defaultStore;
     runtimeMemoryStore;
     runtimeMemoryPolicy;
+    runtimeMemoryMaintenanceConfig;
     routingRules;
     routingDefaultAgentId;
     threadMemorySync;
@@ -123,6 +126,8 @@ export class AgentHarnessRuntime {
             : undefined;
         this.runtimeMemoryStore = resolveStoreFromConfig(this.stores, runtimeMemoryStoreConfig, runRoot) ?? this.defaultStore;
         this.runtimeMemoryPolicy = readRuntimeMemoryPolicyConfig(this.defaultRuntimeEntryBinding?.harnessRuntime.runtimeMemory, this.workspace.workspaceRoot) ?? null;
+        this.runtimeMemoryMaintenanceConfig =
+            readRuntimeMemoryMaintenanceConfig(this.defaultRuntimeEntryBinding?.harnessRuntime.runtimeMemory) ?? null;
         this.resolvedRuntimeAdapterOptions = resolveRuntimeAdapterOptions({
             workspace,
             runtimeAdapterOptions,
@@ -238,6 +243,78 @@ export class AgentHarnessRuntime {
     async listRuns(filter) {
         return this.persistence.listRuns(filter);
     }
+    async memorize(input) {
+        const binding = this.defaultRuntimeEntryBinding;
+        if (!binding) {
+            throw new Error("memorize requires a runtime entry binding.");
+        }
+        if (!Array.isArray(input.records)) {
+            throw new Error("memorize requires input.records to be an array.");
+        }
+        const candidates = input.records
+            .filter((record) => typeof record === "object" && record !== null)
+            .filter((record) => record.noStore !== true);
+        if (candidates.length === 0) {
+            return { records: [], decisions: [] };
+        }
+        if (candidates.some((record) => typeof record.content !== "string" || record.content.trim().length === 0)) {
+            throw new Error("memorize requires every record to include non-empty content.");
+        }
+        if (candidates.some((record) => (record.scope ?? "thread") === "thread") && !input.threadId) {
+            throw new Error("memorize requires threadId when storing thread-scoped memory.");
+        }
+        const recordedAt = input.recordedAt ?? new Date().toISOString();
+        const runId = input.runId ?? createPersistentId(new Date(recordedAt));
+        const threadId = input.threadId ?? `memory-api-${runId}`;
+        return this.persistStructuredMemoryCandidates(binding, {
+            candidates: candidates.map((record) => ({ ...record, content: record.content.trim() })),
+            threadId,
+            runId,
+            agentId: input.agentId ?? binding.agent.id,
+            userId: input.userId,
+            projectId: input.projectId,
+            recordedAt,
+            storeCandidateLog: true,
+        });
+    }
+    async recall(input) {
+        const binding = this.defaultRuntimeEntryBinding;
+        if (!binding) {
+            throw new Error("recall requires a runtime entry binding.");
+        }
+        if (typeof input.query !== "string" || input.query.trim().length === 0) {
+            throw new Error("recall requires a non-empty query.");
+        }
+        const workspaceId = this.getWorkspaceId(binding);
+        const agentId = input.agentId ?? binding.agent.id;
+        const userId = input.userId ?? "default";
+        const projectId = input.projectId ?? workspaceId;
+        const scopes = this.resolveRecallScopes(input);
+        const topK = typeof input.topK === "number" && Number.isInteger(input.topK) && input.topK > 0
+            ? input.topK
+            : (this.runtimeMemoryPolicy?.retrieval.defaultTopK ?? 5);
+        const kinds = input.kinds?.length ? new Set(input.kinds) : null;
+        const items = (await listMemoryRecordsForScopes(this.runtimeMemoryStore, scopes))
+            .filter((record) => this.matchesRecallScope(record, {
+            threadId: input.threadId,
+            agentId,
+            workspaceId: input.workspaceId ?? workspaceId,
+            userId,
+            projectId,
+        }))
+            .filter((record) => (input.includeStale ? record.status === "active" || record.status === "stale" : record.status === "active"))
+            .filter((record) => (kinds ? kinds.has(record.kind) : true))
+            .map((record) => ({
+            record,
+            score: scoreMemoryText(input.query.trim(), `${record.summary}\n${record.content}`, this.getMemoryScopeBoost(record.scope)) +
+                Math.max(0, 1 - ((Date.now() - Date.parse(record.lastConfirmedAt)) / (1000 * 60 * 60 * 24 * 365))) +
+                record.confidence,
+        }))
+            .sort((left, right) => right.score - left.score)
+            .slice(0, topK)
+            .map(({ record }) => record);
+        return { items };
+    }
     async getRun(runId) {
         return this.persistence.getRun(runId);
     }
@@ -387,8 +464,7 @@ export class AgentHarnessRuntime {
         }
     }
     resolveMemoryNamespace(scope, binding, options = {}) {
-        const workspaceRoot = binding.harnessRuntime.workspaceRoot ?? this.workspace.workspaceRoot;
-        const workspaceId = path.basename(workspaceRoot) || "default";
+        const workspaceId = this.getWorkspaceId(binding);
         const template = this.runtimeMemoryPolicy?.namespaces[scope] ?? `memories/${scope}s/{${scope}Id}`;
         return resolveMemoryNamespace(template, {
             threadId: options.threadId,
@@ -398,34 +474,82 @@ export class AgentHarnessRuntime {
             projectId: options.projectId ?? workspaceId,
         });
     }
+    getWorkspaceId(binding) {
+        const workspaceRoot = binding.harnessRuntime.workspaceRoot ?? this.workspace.workspaceRoot;
+        return path.basename(workspaceRoot) || "default";
+    }
+    resolveRecallScopes(input) {
+        if (Array.isArray(input.scopes) && input.scopes.length > 0) {
+            return Array.from(new Set(input.scopes));
+        }
+        const scopes = new Set(["thread", "agent", "workspace"]);
+        if (input.userId) {
+            scopes.add("user");
+        }
+        if (input.projectId) {
+            scopes.add("project");
+        }
+        return Array.from(scopes);
+    }
+    matchesRecallScope(record, filters) {
+        if (record.scope === "thread") {
+            return typeof filters.threadId === "string" && String(record.provenance.threadId ?? "") === filters.threadId;
+        }
+        if (record.scope === "agent") {
+            return String(record.provenance.agentId ?? "") === filters.agentId;
+        }
+        if (record.scope === "workspace") {
+            return String(record.provenance.workspaceId ?? filters.workspaceId) === filters.workspaceId;
+        }
+        if (record.scope === "user") {
+            return String(record.provenance.userId ?? "default") === filters.userId;
+        }
+        return String(record.provenance.projectId ?? filters.workspaceId) === filters.projectId;
+    }
+    getMemoryScopeBoost(scope) {
+        if (scope === "thread") {
+            return 4;
+        }
+        if (scope === "agent") {
+            return 2;
+        }
+        if (scope === "workspace") {
+            return 1;
+        }
+        return 0;
+    }
     async buildRuntimeMemoryContext(binding, threadId, input) {
-        const threadNamespace = this.resolveMemoryNamespace("thread", binding, { threadId });
-        const agentNamespace = this.resolveMemoryNamespace("agent", binding);
-        const workspaceNamespace = this.resolveMemoryNamespace("workspace", binding);
-        const docs = await Promise.all([
-            this.runtimeMemoryStore.get(threadNamespace, "durable-summary.md"),
-            this.runtimeMemoryStore.get(threadNamespace, "tool-memory.md"),
-            this.runtimeMemoryStore.get(threadNamespace, "semantic.md"),
-            this.runtimeMemoryStore.get(threadNamespace, "episodic.md"),
-            this.runtimeMemoryStore.get(threadNamespace, "procedural.md"),
-            this.runtimeMemoryStore.get(agentNamespace, "procedural.md"),
-            this.runtimeMemoryStore.get(workspaceNamespace, "semantic.md"),
-            this.runtimeMemoryStore.get(workspaceNamespace, "procedural.md"),
-        ]);
         const query = typeof input === "string" ? input : JSON.stringify(input ?? "");
-        const ranked = docs
-            .map((doc, index) => {
-            const content = doc?.value?.content;
-            if (typeof content !== "string" || content.trim().length === 0) {
-                return null;
+        const ranked = (await listMemoryRecordsForScopes(this.runtimeMemoryStore, ["thread", "agent", "workspace"]))
+            .filter((record) => {
+            if (record.status !== "active") {
+                return false;
+            }
+            if (record.scope === "thread") {
+                return String(record.provenance.threadId ?? "") === threadId;
+            }
+            if (record.scope === "agent") {
+                return String(record.provenance.agentId ?? "") === binding.agent.id;
             }
-            const scopeBoost = index < 5 ? 4 : index === 5 ? 2 : 1;
+            return true;
+        })
+            .map((record) => {
+            const scopeBoost = record.scope === "thread" ? 4 : record.scope === "agent" ? 2 : 1;
+            const freshnessBoost = Math.max(0, 1 - ((Date.now() - Date.parse(record.lastConfirmedAt)) / (1000 * 60 * 60 * 24 * 365)));
             return {
-                content: content.trim(),
-                score: scoreMemoryText(query, content, scopeBoost),
+                content: [
+                    `# Durable ${record.scope[0].toUpperCase()}${record.scope.slice(1)} Memory`,
+                    "",
+                    `- summary: ${record.summary}`,
+                    `- kind: ${record.kind}`,
+                    `- scope: ${record.scope}`,
+                    `- confidence: ${record.confidence.toFixed(2)}`,
+                    "",
+                    record.content,
+                ].join("\n"),
+                score: scoreMemoryText(query, `${record.summary}\n${record.content}`, scopeBoost) + freshnessBoost + record.confidence,
             };
         })
-            .filter((value) => Boolean(value))
             .sort((left, right) => right.score - left.score)
             .slice(0, this.runtimeMemoryPolicy?.retrieval.maxPromptMemories ?? 8);
         if (ranked.length === 0) {
@@ -443,26 +567,77 @@ export class AgentHarnessRuntime {
         if (candidates.length === 0) {
             return;
         }
-        const threadCandidates = candidates.filter((candidate) => (candidate.scope ?? "thread") === "thread");
-        const workspaceCandidates = candidates.filter((candidate) => (candidate.scope ?? "thread") === "workspace");
-        const agentCandidates = candidates.filter((candidate) => (candidate.scope ?? "thread") === "agent");
-        await this.runtimeMemoryStore.put(["memories", "candidates", threadId], `${runId}.json`, {
-            runId,
-            threadId,
-            storedAt: new Date().toISOString(),
+        await this.persistStructuredMemoryCandidates(binding, {
             candidates,
+            threadId,
+            runId,
+            agentId: binding.agent.id,
+            recordedAt: new Date().toISOString(),
+            storeCandidateLog: true,
+        });
+    }
+    async persistStructuredMemoryCandidates(binding, input) {
+        const workspaceId = this.getWorkspaceId(binding);
+        const userId = input.userId ?? "default";
+        const projectId = input.projectId ?? workspaceId;
+        const threadCandidates = input.candidates.filter((candidate) => (candidate.scope ?? "thread") === "thread");
+        const workspaceCandidates = input.candidates.filter((candidate) => (candidate.scope ?? "thread") === "workspace");
+        const agentCandidates = input.candidates.filter((candidate) => (candidate.scope ?? "thread") === "agent");
+        if (input.storeCandidateLog) {
+            await this.runtimeMemoryStore.put(["memories", "candidates", input.threadId], `${input.runId}.json`, {
+                runId: input.runId,
+                threadId: input.threadId,
+                storedAt: input.recordedAt,
+                candidates: input.candidates,
+            });
+        }
+        const persisted = await persistStructuredMemoryRecords({
+            store: this.runtimeMemoryStore,
+            candidates: input.candidates,
+            threadId: input.threadId,
+            runId: input.runId,
+            agentId: input.agentId,
+            workspaceId,
+            userId,
+            projectId,
+            recordedAt: input.recordedAt,
         });
         const writes = [];
         if (threadCandidates.length > 0) {
-            writes.push(this.appendMemoryDigest(this.resolveMemoryNamespace("thread", binding, { threadId }), "tool-memory.md", threadCandidates, 12, "Thread Tool Memory"));
+            writes.push(this.appendMemoryDigest(this.resolveMemoryNamespace("thread", binding, { threadId: input.threadId }), "tool-memory.md", threadCandidates, 12, "Thread Tool Memory"));
+            writes.push(consolidateStructuredMemoryScope({
+                store: this.runtimeMemoryStore,
+                namespace: this.resolveMemoryNamespace("thread", binding, { threadId: input.threadId }),
+                title: "Thread Structured Memory",
+                scope: "thread",
+                maxEntries: 12,
+                config: this.runtimeMemoryMaintenanceConfig ?? undefined,
+            }));
         }
         if (workspaceCandidates.length > 0) {
             writes.push(this.appendMemoryDigest(this.resolveMemoryNamespace("workspace", binding), "tool-memory.md", workspaceCandidates, 20, "Workspace Tool Memory"));
+            writes.push(consolidateStructuredMemoryScope({
+                store: this.runtimeMemoryStore,
+                namespace: this.resolveMemoryNamespace("workspace", binding),
+                title: "Workspace Structured Memory",
+                scope: "workspace",
+                maxEntries: 20,
+                config: this.runtimeMemoryMaintenanceConfig ?? undefined,
+            }));
         }
         if (agentCandidates.length > 0) {
             writes.push(this.appendMemoryDigest(this.resolveMemoryNamespace("agent", binding), "tool-memory.md", agentCandidates, 20, "Agent Tool Memory"));
+            writes.push(consolidateStructuredMemoryScope({
+                store: this.runtimeMemoryStore,
+                namespace: this.resolveMemoryNamespace("agent", binding),
+                title: "Agent Structured Memory",
+                scope: "agent",
+                maxEntries: 20,
+                config: this.runtimeMemoryMaintenanceConfig ?? undefined,
+            }));
         }
         await Promise.all(writes);
+        return persisted;
     }
     async appendMemoryDigest(namespace, key, candidates, maxEntries, title) {
         const existing = await this.runtimeMemoryStore.get(namespace, key);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.152",
+  "version": "0.0.154",
   "description": "Workspace runtime for multi-agent applications",
   "type": "module",
   "packageManager": "npm@10.9.2",