@botbotgo/agent-harness 0.0.151 → 0.0.153

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

@@ -66,6 +66,10 @@ spec:
     writeOnApprovalResolution: true
     writeOnRunCompletion: true
 
+  # agent-harness feature: optional thread snapshot projection for operational state and pending approvals.
+  threadMemorySync:
+    enabled: true
+
   # agent-harness feature: optional Mem0 OSS ingestion engine for automatic long-term knowledge extraction.
   mem0:
     enabled: false

package/dist/contracts/runtime.d.ts

@@ -118,6 +118,40 @@ export type MemoryCandidate = {
     noStore?: boolean;
     provenance?: Record<string, unknown>;
 };
+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";
+    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;
+};
 /**
  * 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/init-project.js

@@ -162,6 +162,8 @@ spec:
     backgroundConsolidation: true
     writeOnApprovalResolution: true
     writeOnRunCompletion: true
+  threadMemorySync:
+    enabled: true
   mem0:
     enabled: false
     apiKeyEnv: MEM0_API_KEY

package/dist/package-version.d.ts

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

package/dist/package-version.js

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

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,18 @@
+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;
+    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,402 @@
+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,
+            ...(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/system/runtime-memory-sync.d.ts

@@ -8,17 +8,25 @@ export type ResolvedRuntimeMemorySyncConfig = {
     backgroundConsolidation: boolean;
     maxMessagesPerRun: number;
 };
+type RuntimeMemorySyncOptions = {
+    resolveThreadNamespace?: (threadId: string) => string[];
+    resolveRunNamespace?: (threadId: string) => string[];
+};
 export declare function readRuntimeMemorySyncConfig(runtimeMemory: Record<string, unknown> | undefined): ResolvedRuntimeMemorySyncConfig | undefined;
 export declare class RuntimeMemorySync implements HarnessEventProjection {
     private readonly persistence;
     readonly store: StoreLike;
     private readonly config;
+    private readonly options;
     private readonly pending;
     private syncChain;
     readonly name = "runtime-memory-sync";
-    constructor(persistence: RuntimePersistence, store: StoreLike, config: ResolvedRuntimeMemorySyncConfig);
+    constructor(persistence: RuntimePersistence, store: StoreLike, config: ResolvedRuntimeMemorySyncConfig, options?: RuntimeMemorySyncOptions);
     shouldHandle(event: HarnessEvent): boolean;
     handleEvent(event: HarnessEvent): Promise<void>;
     private syncRun;
+    private resolveThreadNamespace;
+    private resolveRunNamespace;
     close(): Promise<void>;
 }
+export {};

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

@@ -100,13 +100,15 @@ export class RuntimeMemorySync {
     persistence;
     store;
     config;
+    options;
     pending = new Set();
     syncChain = Promise.resolve();
     name = "runtime-memory-sync";
-    constructor(persistence, store, config) {
+    constructor(persistence, store, config, options = {}) {
         this.persistence = persistence;
         this.store = store;
         this.config = config;
+        this.options = options;
     }
     shouldHandle(event) {
         if (!RUNTIME_MEMORY_EVENT_TYPES.has(event.eventType)) {
@@ -161,8 +163,8 @@ export class RuntimeMemorySync {
             approvals,
         });
         await Promise.all([
-            this.store.put(["memories", "runs", threadId], `${runId}.summary.md`, { content: `${summaryMarkdown}\n` }),
-            this.store.put(["memories", "runs", threadId], `${runId}.record.json`, {
+            this.store.put(this.resolveRunNamespace(threadId), `${runId}.summary.md`, { content: `${summaryMarkdown}\n` }),
+            this.store.put(this.resolveRunNamespace(threadId), `${runId}.record.json`, {
                 kind: "summary",
                 scope: "thread",
                 threadId,
@@ -185,7 +187,13 @@ export class RuntimeMemorySync {
             capturedAt,
             messages,
         });
-        await this.store.put(["memories", "threads", threadId], "durable-summary.md", { content: `${digestMarkdown}\n` });
+        await this.store.put(this.resolveThreadNamespace(threadId), "durable-summary.md", { content: `${digestMarkdown}\n` });
+    }
+    resolveThreadNamespace(threadId) {
+        return this.options.resolveThreadNamespace ? this.options.resolveThreadNamespace(threadId) : ["memories", "threads", threadId];
+    }
+    resolveRunNamespace(threadId) {
+        return this.options.resolveRunNamespace ? this.options.resolveRunNamespace(threadId) : ["memories", "runs", threadId];
     }
     async close() {
         await Promise.allSettled(Array.from(this.pending));

package/dist/runtime/harness/system/thread-memory-sync.d.ts

@@ -1,14 +1,18 @@
 import type { HarnessEvent, HarnessEventProjection } from "../../../contracts/types.js";
 import type { RuntimePersistence } from "../../../persistence/types.js";
+type ThreadMemorySyncOptions = {
+    resolveThreadNamespace?: (threadId: string) => string[];
+};
 export declare class ThreadMemorySync implements HarnessEventProjection {
     private readonly persistence;
     private readonly store?;
+    private readonly options;
     private readonly pending;
     private syncChain;
     readonly name = "thread-memory-sync";
     constructor(persistence: RuntimePersistence, store?: {
         put: (namespace: string[], key: string, value: Record<string, any>) => Promise<void>;
-    } | undefined);
+    } | undefined, options?: ThreadMemorySyncOptions);
     shouldHandle(event: HarnessEvent): boolean;
     handleEvent(event: HarnessEvent): Promise<void>;
     private syncThread;

package/dist/runtime/harness/system/thread-memory-sync.js

@@ -6,11 +6,11 @@ function excerpt(message) {
     const normalized = extractMessageText(message.content).replace(/\s+/g, " ").trim();
     return normalized.length > 240 ? `${normalized.slice(0, 237)}...` : normalized;
 }
-function renderStatusMarkdown(thread, messages) {
+function renderThreadSnapshotMarkdown(thread, messages, approvals) {
     const userMessages = messages.filter((message) => message.role === "user");
     const assistantMessages = messages.filter((message) => message.role === "assistant");
     return [
-        "# Thread Status",
+        "# Thread Snapshot",
         "",
         `- thread_id: ${thread.threadId}`,
         `- latest_run_id: ${thread.latestRunId}`,
@@ -24,15 +24,17 @@ function renderStatusMarkdown(thread, messages) {
         "## Recent Assistant Message",
         excerpt(assistantMessages.at(-1)),
         "",
+        ...formatOpenApprovalsSection(approvals),
     ].join("\n");
 }
-function renderOpenApprovalsMarkdown(approvals) {
+function formatOpenApprovalsSection(approvals) {
+    const lines = ["## Open Approvals", ""];
     if (approvals.length === 0) {
-        return ["# Open Approvals", "", "(none)", ""].join("\n");
+        lines.push("(none)", "");
+        return lines;
     }
-    const lines = ["# Open Approvals", ""];
     for (const approval of approvals) {
-        lines.push(`## ${approval.approvalId}`);
+        lines.push(`### ${approval.approvalId}`);
         lines.push(`- pending_action_id: ${approval.pendingActionId}`);
         lines.push(`- tool: ${approval.toolName}`);
         lines.push(`- run_id: ${approval.runId}`);
@@ -40,7 +42,10 @@ function renderOpenApprovalsMarkdown(approvals) {
         lines.push(`- allowed: ${approval.allowedDecisions.join(", ")}`);
         lines.push("");
     }
-    return lines.join("\n");
+    return lines;
+}
+function resolveThreadNamespace(threadId, resolver) {
+    return resolver ? resolver(threadId) : ["memories", "threads", threadId];
 }
 const THREAD_MEMORY_EVENT_TYPES = new Set([
     "run.state.changed",
@@ -52,12 +57,14 @@ const THREAD_MEMORY_EVENT_TYPES = new Set([
 export class ThreadMemorySync {
     persistence;
     store;
+    options;
     pending = new Set();
     syncChain = Promise.resolve();
     name = "thread-memory-sync";
-    constructor(persistence, store) {
+    constructor(persistence, store, options = {}) {
         this.persistence = persistence;
         this.store = store;
+        this.options = options;
     }
     shouldHandle(event) {
         return THREAD_MEMORY_EVENT_TYPES.has(event.eventType);
@@ -93,10 +100,9 @@ export class ThreadMemorySync {
         if (!this.store) {
             return;
         }
-        await Promise.all([
-            this.store.put(["memories", "threads", threadId], "status.md", { content: `${renderStatusMarkdown(thread, messages)}\n` }),
-            this.store.put(["memories", "threads", threadId], "open-approvals.md", { content: `${renderOpenApprovalsMarkdown(pendingApprovals)}\n` }),
-        ]);
+        await this.store.put(resolveThreadNamespace(threadId, this.options.resolveThreadNamespace), "snapshot.md", {
+            content: `${renderThreadSnapshotMarkdown(thread, messages, pendingApprovals)}\n`,
+        });
     }
     async close() {
         await Promise.allSettled(Array.from(this.pending));

package/dist/runtime/harness.d.ts

@@ -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;

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,
@@ -144,7 +149,15 @@ export class AgentHarnessRuntime {
         this.routingRules = getRoutingRules(workspace.refs);
         this.routingDefaultAgentId = getRoutingDefaultAgentId(workspace.refs);
         if (isThreadMemorySyncEnabled(workspace)) {
-            this.threadMemorySync = new ThreadMemorySync(this.persistence, this.runtimeMemoryStore);
+            this.threadMemorySync = new ThreadMemorySync(this.persistence, this.runtimeMemoryStore, {
+                resolveThreadNamespace: (threadId) => {
+                    const binding = this.defaultRuntimeEntryBinding;
+                    if (!binding) {
+                        return ["memories", "threads", threadId];
+                    }
+                    return this.resolveMemoryNamespace("thread", binding, { threadId });
+                },
+            });
             this.unregisterThreadMemorySync = this.eventBus.registerProjection(this.threadMemorySync);
         }
         else {
@@ -153,7 +166,15 @@ export class AgentHarnessRuntime {
         }
         const runtimeMemorySyncConfig = readRuntimeMemorySyncConfig(this.defaultRuntimeEntryBinding?.harnessRuntime.runtimeMemory);
         if (runtimeMemorySyncConfig) {
-            this.runtimeMemorySync = new RuntimeMemorySync(this.persistence, this.runtimeMemoryStore, runtimeMemorySyncConfig);
+            this.runtimeMemorySync = new RuntimeMemorySync(this.persistence, this.runtimeMemoryStore, runtimeMemorySyncConfig, {
+                resolveThreadNamespace: (threadId) => {
+                    const binding = this.defaultRuntimeEntryBinding;
+                    if (!binding) {
+                        return ["memories", "threads", threadId];
+                    }
+                    return this.resolveMemoryNamespace("thread", binding, { threadId });
+                },
+            });
             this.unregisterRuntimeMemorySync = this.eventBus.registerProjection(this.runtimeMemorySync);
         }
         else {
@@ -383,33 +404,37 @@ export class AgentHarnessRuntime {
         });
     }
     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;
             }
-            const scopeBoost = index < 5 ? 4 : index === 5 ? 2 : 1;
+            if (record.scope === "agent") {
+                return String(record.provenance.agentId ?? "") === binding.agent.id;
+            }
+            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) {
@@ -430,21 +455,54 @@ export class AgentHarnessRuntime {
         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");
+        const recordedAt = new Date().toISOString();
         await this.runtimeMemoryStore.put(["memories", "candidates", threadId], `${runId}.json`, {
             runId,
             threadId,
-            storedAt: new Date().toISOString(),
+            storedAt: recordedAt,
             candidates,
         });
+        await persistStructuredMemoryRecords({
+            store: this.runtimeMemoryStore,
+            candidates,
+            threadId,
+            runId,
+            agentId: binding.agent.id,
+            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(consolidateStructuredMemoryScope({
+                store: this.runtimeMemoryStore,
+                namespace: this.resolveMemoryNamespace("thread", binding, { 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);
     }

package/package.json

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