@botbotgo/agent-harness 0.0.281 → 0.0.283

package/dist/runtime/harness.js

@@ -10,7 +10,7 @@ import { getConcurrencyConfig, getRecoveryConfig, getRoutingDefaultAgentId, getR
 import { createHarnessEvent, inferRoutingBindings, renderRuntimeFailure, } from "./support/harness-support.js";
 import { ThreadMemorySync } from "./harness/system/thread-memory-sync.js";
 import { RuntimeMemorySync, readRuntimeMemorySyncConfig } from "./harness/system/runtime-memory-sync.js";
-import { FileBackedStore } from "./harness/system/store.js";
+import { SqliteBackedStore } from "./harness/system/store.js";
 import { HealthMonitor, readHealthMonitorConfig, } from "./harness/system/health-monitor.js";
 import { normalizeInvocationEnvelope, normalizeRunPriority, resolveRunListeners, } from "./harness/run/helpers.js";
 import { emitHarnessEvent, } from "./harness/events/events.js";
@@ -32,17 +32,16 @@ import { describeWorkspaceInventory, getAgentInventoryRecord, listAgentSkills as
 import { createDefaultHealthSnapshot, isInventoryEnabled, isThreadMemorySyncEnabled, } from "./harness/runtime-defaults.js";
 import { Mem0IngestionSync, Mem0SemanticRecall, readMem0RuntimeConfig, } from "./harness/system/mem0-ingestion-sync.js";
 import { createRuntimeMemoryManager, RuntimeMemoryFormationSync, readRuntimeMemoryFormationConfig, } from "./harness/system/runtime-memory-manager.js";
-import { renderMemoryCandidatesMarkdown } from "./harness/system/runtime-memory-candidates.js";
-import { findMemoryRecordById, getMemoryRecord, listMemoryRecordsForScopes, persistStructuredMemoryRecords, removeMemoryRecord, updateMemoryRecord, } 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 { readRuntimeMemoryMaintenanceConfig, readRuntimeMemoryPolicyConfig, resolveMemoryNamespace, } from "./harness/system/runtime-memory-policy.js";
 import { resolveRuntimeAdapterOptions } from "./support/runtime-adapter-options.js";
+import { resolveKnowledgeStorePath } from "./support/runtime-layout.js";
 import { initializeHarnessRuntime, reclaimExpiredClaimedRuns as reclaimHarnessExpiredClaimedRuns, recoverStartupRuns as recoverHarnessStartupRuns, isStaleRunningRun as isHarnessStaleRunningRun, } from "./harness/run/startup-runtime.js";
 import { traceStartupStage } from "./startup-tracing.js";
 import { normalizeProcessExecutablePath } from "./support/runtime-env.js";
 import { streamHarnessRun } from "./harness/run/stream-run.js";
 import { defaultRequestedAgentId, prepareRunStart } from "./harness/run/start-run.js";
 import { buildRequestInspectionRecord, buildSessionInspectionRecord, deleteSessionRecord, deleteThreadRecord, getPublicApproval, listPublicApprovals, } from "./harness/run/thread-records.js";
+import { createKnowledgeModule } from "../knowledge/index.js";
 const ACTIVE_RUN_STATES = [
     "queued",
     "claimed",
@@ -196,6 +195,7 @@ export class AgentHarnessRuntime {
     mem0SemanticRecall;
     runtimeMemoryFormationConfig;
     runtimeMemoryManager;
+    knowledgeModule;
     runtimeMemoryFormationSync;
     unregisterRuntimeMemoryFormationSync;
     resolvedRuntimeAdapterOptions;
@@ -257,11 +257,11 @@ export class AgentHarnessRuntime {
         normalizeProcessExecutablePath();
         this.runtimeEntryBindings = inferRoutingBindings(this.workspace).runtimeEntryBindings;
         this.defaultRuntimeEntryBinding = this.runtimeEntryBindings[0];
-        this.defaultRunRootValue = this.defaultRuntimeEntryBinding?.harnessRuntime.runRoot ?? `${this.workspace.workspaceRoot}/run-data`;
+        this.defaultRunRootValue = this.defaultRuntimeEntryBinding?.harnessRuntime.runRoot ?? `${this.workspace.workspaceRoot}/.agent`;
         const runRoot = this.defaultRunRoot();
         this.persistence = new SqlitePersistence(runRoot);
         const defaultStoreConfig = this.defaultRuntimeEntryBinding?.harnessRuntime.store;
-        this.defaultStore = resolveStoreFromConfig(this.stores, defaultStoreConfig, runRoot) ?? new FileBackedStore(`${runRoot}/store.json`);
+        this.defaultStore = resolveStoreFromConfig(this.stores, defaultStoreConfig, runRoot) ?? new SqliteBackedStore(resolveKnowledgeStorePath(runRoot));
         const runtimeMemoryStoreConfig = typeof this.defaultRuntimeEntryBinding?.harnessRuntime.runtimeMemory?.store === "object" &&
             this.defaultRuntimeEntryBinding?.harnessRuntime.runtimeMemory?.store
             ? this.defaultRuntimeEntryBinding.harnessRuntime.runtimeMemory.store
@@ -292,12 +292,12 @@ export class AgentHarnessRuntime {
         this.routingDefaultAgentId = getRoutingDefaultAgentId(workspace.refs);
         if (isThreadMemorySyncEnabled(workspace)) {
             this.threadMemorySync = new ThreadMemorySync(this.persistence, this.runtimeMemoryStore, {
-                resolveThreadNamespace: (threadId) => {
+                resolveThreadNamespace: (sessionId) => {
                     const binding = this.defaultRuntimeEntryBinding;
                     if (!binding) {
-                        return ["memories", "threads", threadId];
+                        return ["memories", "sessions", sessionId];
                     }
-                    return this.resolveMemoryNamespace("thread", binding, { threadId });
+                    return this.resolveMemoryNamespace("thread", binding, { sessionId });
                 },
             });
             this.unregisterThreadMemorySync = this.eventBus.registerProjection(this.threadMemorySync);
@@ -309,12 +309,12 @@ export class AgentHarnessRuntime {
         const runtimeMemorySyncConfig = readRuntimeMemorySyncConfig(this.defaultRuntimeEntryBinding?.harnessRuntime.runtimeMemory);
         if (runtimeMemorySyncConfig) {
             this.runtimeMemorySync = new RuntimeMemorySync(this.persistence, this.runtimeMemoryStore, runtimeMemorySyncConfig, {
-                resolveThreadNamespace: (threadId) => {
+                resolveThreadNamespace: (sessionId) => {
                     const binding = this.defaultRuntimeEntryBinding;
                     if (!binding) {
-                        return ["memories", "threads", threadId];
+                        return ["memories", "sessions", sessionId];
                     }
-                    return this.resolveMemoryNamespace("thread", binding, { threadId });
+                    return this.resolveMemoryNamespace("thread", binding, { sessionId });
                 },
             });
             this.unregisterRuntimeMemorySync = this.eventBus.registerProjection(this.runtimeMemorySync);
@@ -345,17 +345,54 @@ export class AgentHarnessRuntime {
                     modelResolver: this.resolvedRuntimeAdapterOptions.modelResolver,
                 })
                 : null;
+        this.knowledgeModule = createKnowledgeModule({
+            store: this.runtimeMemoryStore,
+            policy: this.runtimeMemoryPolicy,
+            maintenanceConfig: this.runtimeMemoryMaintenanceConfig,
+            resolveNamespace: (scope, context) => {
+                const binding = this.defaultRuntimeEntryBinding;
+                if (!binding) {
+                    const identifier = scope === "thread"
+                        ? context.sessionId
+                        : scope === "agent"
+                            ? context.agentId
+                            : scope === "workspace"
+                                ? context.workspaceId
+                                : scope === "user"
+                                    ? context.userId ?? "default"
+                                    : context.projectId ?? context.workspaceId;
+                    return ["memories", `${scope}s`, identifier ?? "default"];
+                }
+                return this.resolveMemoryNamespace(scope, binding, {
+                    sessionId: context.sessionId,
+                    agentId: context.agentId,
+                    userId: context.userId,
+                    projectId: context.projectId,
+                });
+            },
+            resolveVectorStore: () => this.resolveRuntimeMemoryVectorStore(),
+            transformCandidates: this.runtimeMemoryManager && this.defaultRuntimeEntryBinding
+                ? ({ candidates, context, existingRecords }) => this.runtimeMemoryManager.transform({
+                    candidates,
+                    binding: this.defaultRuntimeEntryBinding,
+                    threadId: context.sessionId ?? `memory-api-${context.requestId ?? "unknown"}`,
+                    runId: context.requestId ?? createPersistentId(new Date(context.recordedAt ?? new Date().toISOString())),
+                    recordedAt: context.recordedAt ?? new Date().toISOString(),
+                    existingRecords,
+                })
+                : undefined,
+            getMem0SemanticRecall: () => this.mem0SemanticRecall,
+        });
         if (runtimeMemoryFormationConfig) {
-            this.runtimeMemoryFormationSync = new RuntimeMemoryFormationSync(this.persistence, runtimeMemoryFormationConfig, (input) => this.persistStructuredMemoryCandidates(this.defaultRuntimeEntryBinding, {
-                candidates: input.candidates,
-                threadId: input.threadId,
-                runId: input.runId,
+            this.runtimeMemoryFormationSync = new RuntimeMemoryFormationSync(this.persistence, runtimeMemoryFormationConfig, (input) => this.knowledgeModule.memorizeCandidates(input.candidates, {
+                sessionId: input.threadId,
+                requestId: input.runId,
                 agentId: input.agentId,
+                workspaceId: this.getWorkspaceId(this.defaultRuntimeEntryBinding),
                 userId: input.userId,
                 projectId: input.projectId,
                 recordedAt: input.recordedAt,
-                storeCandidateLog: false,
-            }).then(() => undefined), runRoot);
+            }, { storeCandidateLog: false }).then(() => undefined), runRoot);
             this.unregisterRuntimeMemoryFormationSync = this.eventBus.registerProjection(this.runtimeMemoryFormationSync);
         }
         else {
@@ -480,35 +517,17 @@ export class AgentHarnessRuntime {
         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.");
-        }
-        const sessionId = input.sessionId;
-        const requestId = input.requestId;
-        if (candidates.some((record) => (record.scope ?? "thread") === "thread") && !sessionId) {
-            throw new Error("memorize requires sessionId when storing thread-scoped memory.");
-        }
-        const recordedAt = input.recordedAt ?? new Date().toISOString();
-        const runId = requestId ?? createPersistentId(new Date(recordedAt));
-        const threadId = sessionId ?? `memory-api-${runId}`;
-        return this.persistStructuredMemoryCandidates(binding, {
-            candidates: candidates.map((record) => ({ ...record, content: record.content.trim() })),
-            threadId,
-            runId,
+        return this.knowledgeModule.memorize({
+            records: input.records,
+            storeCandidateLog: true,
+        }, {
+            sessionId: input.sessionId,
+            requestId: input.requestId,
             agentId: input.agentId ?? binding.agent.id,
+            workspaceId: this.getWorkspaceId(binding),
             userId: input.userId,
             projectId: input.projectId,
-            recordedAt,
-            storeCandidateLog: true,
+            recordedAt: input.recordedAt,
         });
     }
     async recall(input) {
@@ -516,129 +535,46 @@ export class AgentHarnessRuntime {
         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 sessionId = input.sessionId;
-        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 this.rankRecallCandidates(binding, {
-            query: input.query.trim(),
-            scopes,
-            kinds,
-            topK,
-            includeStale: input.includeStale === true,
-            filters: {
-                threadId: sessionId,
-                agentId,
-                workspaceId: input.workspaceId ?? workspaceId,
-                userId,
-                projectId,
-            },
-        }))
-            .slice(0, topK)
-            .map(({ record }) => record);
-        return { items };
+        return this.knowledgeModule.recall(input, {
+            sessionId: input.sessionId,
+            agentId: input.agentId ?? binding.agent.id,
+            workspaceId: input.workspaceId ?? this.getWorkspaceId(binding),
+            userId: input.userId,
+            projectId: input.projectId,
+        });
     }
     async listMemories(input = {}) {
         const binding = this.defaultRuntimeEntryBinding;
         if (!binding) {
             throw new Error("listMemories requires a runtime entry binding.");
         }
-        const sessionId = input.sessionId;
-        const workspaceId = this.getWorkspaceId(binding);
-        const scopes = Array.isArray(input.scopes) && input.scopes.length > 0
-            ? Array.from(new Set(input.scopes))
-            : ["thread", "agent", "workspace", "user", "project"];
-        const kinds = input.kinds?.length ? new Set(input.kinds) : null;
-        const statuses = input.status?.length ? new Set(input.status) : new Set(["active"]);
-        const limit = typeof input.limit === "number" && Number.isInteger(input.limit) && input.limit > 0
-            ? input.limit
-            : Number.POSITIVE_INFINITY;
-        const items = (await listMemoryRecordsForScopes(this.runtimeMemoryStore, scopes))
-            .filter((record) => statuses.has(record.status))
-            .filter((record) => !kinds || kinds.has(record.kind))
-            .filter((record) => this.matchesMemoryFilters(record, {
-            threadId: sessionId,
+        return this.knowledgeModule.list(input, {
+            sessionId: input.sessionId,
             agentId: input.agentId,
-            workspaceId: input.workspaceId ?? workspaceId,
+            workspaceId: input.workspaceId ?? this.getWorkspaceId(binding),
             userId: input.userId,
             projectId: input.projectId,
-        }))
-            .sort((left, right) => right.lastConfirmedAt.localeCompare(left.lastConfirmedAt))
-            .slice(0, limit);
-        return { items };
+        });
     }
     async updateMemory(input) {
         const binding = this.defaultRuntimeEntryBinding;
         if (!binding) {
             throw new Error("updateMemory requires a runtime entry binding.");
         }
-        if (typeof input.memoryId !== "string" || input.memoryId.trim().length === 0) {
-            throw new Error("updateMemory requires a non-empty memoryId.");
-        }
-        const existing = await findMemoryRecordById(this.runtimeMemoryStore, input.memoryId.trim());
-        if (!existing) {
-            throw new Error(`Memory record not found: ${input.memoryId}`);
-        }
-        const updatedAt = new Date().toISOString();
-        const nextContent = typeof input.content === "string"
-            ? input.content.trim()
-            : existing.content;
-        if (nextContent.length === 0) {
-            throw new Error("updateMemory requires content to remain non-empty.");
-        }
-        const next = {
-            ...existing,
-            content: nextContent,
-            summary: typeof input.summary === "string"
-                ? input.summary.trim() || this.summarizeMemoryContent(nextContent)
-                : (typeof input.content === "string" ? this.summarizeMemoryContent(nextContent) : existing.summary),
-            status: input.status ?? existing.status,
-            confidence: typeof input.confidence === "number" ? Math.max(0, Math.min(1, input.confidence)) : existing.confidence,
-            expiresAt: input.expiresAt === undefined ? existing.expiresAt : (input.expiresAt ?? undefined),
-            sourceType: typeof input.sourceType === "string" && input.sourceType.trim().length > 0 ? input.sourceType.trim() : existing.sourceType,
-            sourceRefs: Array.isArray(input.sourceRefs)
-                ? Array.from(new Set(input.sourceRefs.map((item) => item.trim()).filter((item) => item.length > 0)))
-                : existing.sourceRefs,
-            tags: Array.isArray(input.tags)
-                ? Array.from(new Set(input.tags.map((item) => item.trim()).filter((item) => item.length > 0)))
-                : existing.tags,
-            observedAt: typeof input.observedAt === "string" && input.observedAt.trim().length > 0 ? input.observedAt : existing.observedAt,
-            lastConfirmedAt: typeof input.lastConfirmedAt === "string" && input.lastConfirmedAt.trim().length > 0
-                ? input.lastConfirmedAt
-                : updatedAt,
-            provenance: input.provenance ? { ...existing.provenance, ...input.provenance } : existing.provenance,
-            revision: existing.revision + 1,
-        };
-        await updateMemoryRecord(this.runtimeMemoryStore, next, updatedAt);
-        await this.rebuildRuntimeMemoryVectorIndex();
-        await this.refreshStructuredMemoryScope(binding, next);
-        return next;
+        return this.knowledgeModule.update(input, {
+            agentId: binding.agent.id,
+            workspaceId: this.getWorkspaceId(binding),
+        });
     }
     async removeMemory(input) {
         const binding = this.defaultRuntimeEntryBinding;
         if (!binding) {
             throw new Error("removeMemory requires a runtime entry binding.");
         }
-        if (typeof input.memoryId !== "string" || input.memoryId.trim().length === 0) {
-            throw new Error("removeMemory requires a non-empty memoryId.");
-        }
-        const existing = await findMemoryRecordById(this.runtimeMemoryStore, input.memoryId.trim());
-        if (!existing) {
-            throw new Error(`Memory record not found: ${input.memoryId}`);
-        }
-        await removeMemoryRecord(this.runtimeMemoryStore, existing.scope, existing.id);
-        await this.rebuildRuntimeMemoryVectorIndex();
-        await this.refreshStructuredMemoryScope(binding, existing);
-        return existing;
+        return this.knowledgeModule.remove(input, {
+            agentId: binding.agent.id,
+            workspaceId: this.getWorkspaceId(binding),
+        });
     }
     async getRequest(requestId) {
         const request = await this.persistence.getRun(requestId);
@@ -1002,7 +938,7 @@ export class AgentHarnessRuntime {
         const workspaceId = this.getWorkspaceId(binding);
         const template = this.runtimeMemoryPolicy?.namespaces[scope] ?? `memories/${scope}s/{${scope}Id}`;
         return resolveMemoryNamespace(template, {
-            threadId: options.threadId,
+            sessionId: options.sessionId,
             agentId: options.agentId ?? binding.agent.id,
             workspaceId,
             userId: options.userId ?? "default",
@@ -1013,339 +949,16 @@ export class AgentHarnessRuntime {
         const workspaceRoot = binding.harnessRuntime.workspaceRoot ?? this.workspace.workspaceRoot;
         return path.basename(workspaceRoot) || "default";
     }
-    summarizeMemoryContent(content) {
-        return (content.trim().split("\n")[0] || content.trim()).slice(0, 240);
-    }
-    matchesMemoryFilters(record, filters) {
-        const sessionId = String(record.provenance.sessionId ?? record.provenance.threadId ?? "");
-        if (filters.threadId && sessionId !== filters.threadId) {
-            return false;
-        }
-        if (filters.agentId && record.provenance.agentId !== filters.agentId) {
-            return false;
-        }
-        if (filters.workspaceId && record.provenance.workspaceId !== filters.workspaceId) {
-            return false;
-        }
-        if (filters.userId && record.provenance.userId !== filters.userId) {
-            return false;
-        }
-        if (filters.projectId && record.provenance.projectId !== filters.projectId) {
-            return false;
-        }
-        return true;
-    }
-    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.sessionId ?? 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;
-    }
-    memoryFreshnessBoost(value) {
-        return Math.max(0, 1 - ((Date.now() - Date.parse(value)) / (1000 * 60 * 60 * 24 * 365)));
-    }
-    scoreStructuredRecord(query, record) {
-        return (scoreMemoryText(query, `${record.summary}\n${record.content}`, this.getMemoryScopeBoost(record.scope)) +
-            this.memoryFreshnessBoost(record.lastConfirmedAt) +
-            record.confidence);
-    }
-    normalizeMemoryDedupKey(record) {
-        return `${record.scope}::${record.summary.toLowerCase().replace(/\s+/g, " ").trim()}::${record.content.toLowerCase().replace(/\s+/g, " ").trim()}`;
-    }
-    inferMem0MemoryKind(hit) {
-        const candidates = [
-            ...hit.categories,
-            typeof hit.metadata.kind === "string" ? hit.metadata.kind : undefined,
-            typeof hit.metadata.memoryType === "string" ? hit.metadata.memoryType : undefined,
-        ].filter((value) => typeof value === "string" && value.trim().length > 0);
-        for (const candidate of candidates) {
-            const kind = normalizeLangMemMemoryKind(candidate);
-            if (kind === "semantic" || kind === "episodic" || kind === "procedural") {
-                return kind;
-            }
-        }
-        return "semantic";
-    }
-    inferMem0MemoryScope(hit, filters) {
-        const metadataScope = typeof hit.metadata.scope === "string" ? hit.metadata.scope : undefined;
-        if (metadataScope === "thread" || metadataScope === "agent" || metadataScope === "workspace" || metadataScope === "user" || metadataScope === "project") {
-            return metadataScope;
-        }
-        if (typeof hit.metadata.threadId === "string" && filters.threadId && hit.metadata.threadId === filters.threadId) {
-            return "thread";
-        }
-        if (hit.agentId === filters.agentId || hit.metadata.agentId === filters.agentId) {
-            return "agent";
-        }
-        return "workspace";
-    }
-    createMem0MemoryRecord(hit, filters) {
-        const scope = this.inferMem0MemoryScope(hit, filters);
-        const kind = this.inferMem0MemoryKind(hit);
-        const summary = hit.memory.split("\n")[0]?.trim() || hit.memory;
-        return {
-            id: `mem0:${hit.id}`,
-            canonicalKey: `mem0:${hit.id}`,
-            kind,
-            scope,
-            content: hit.memory,
-            summary: summary.slice(0, 240),
-            status: "active",
-            confidence: Math.max(0, Math.min(1, hit.score || 0.5)),
-            createdAt: hit.createdAt,
-            observedAt: hit.createdAt,
-            lastConfirmedAt: hit.updatedAt,
-            sourceType: "mem0-search",
-            sourceRefs: [`mem0:${hit.id}`],
-            tags: hit.categories,
-            provenance: {
-                source: "mem0",
-                sessionId: typeof hit.metadata.sessionId === "string"
-                    ? hit.metadata.sessionId
-                    : typeof hit.metadata.threadId === "string"
-                        ? hit.metadata.threadId
-                        : filters.threadId,
-                requestId: (typeof hit.metadata.requestId === "string"
-                    ? hit.metadata.requestId
-                    : typeof hit.metadata.runId === "string"
-                        ? hit.metadata.runId
-                        : undefined),
-                agentId: hit.agentId ?? (typeof hit.metadata.agentId === "string" ? hit.metadata.agentId : filters.agentId),
-                workspaceId: filters.workspaceId,
-                userId: filters.userId,
-                projectId: filters.projectId,
-                ...hit.metadata,
-            },
-            revision: 1,
-            supersedes: [],
-            conflictsWith: [],
-        };
-    }
-    async rankRecallCandidates(binding, input) {
-        const structuredRecords = await listMemoryRecordsForScopes(this.runtimeMemoryStore, input.scopes);
-        const ranked = structuredRecords
-            .filter((record) => this.matchesRecallScope(record, input.filters))
-            .filter((record) => (input.includeStale ? record.status === "active" || record.status === "stale" : record.status === "active"))
-            .filter((record) => (input.kinds ? input.kinds.has(record.kind) : true))
-            .map((record) => ({
-            record,
-            score: this.scoreStructuredRecord(input.query, record),
-        }));
-        const deduped = new Map();
-        for (const item of ranked) {
-            deduped.set(this.normalizeMemoryDedupKey(item.record), item);
-        }
-        const vectorStore = await this.resolveRuntimeMemoryVectorStore();
-        if (vectorStore) {
-            try {
-                const vectorHits = await vectorStore.similaritySearch(input.query, Math.max(input.topK, this.runtimeMemoryPolicy?.retrieval.maxPromptMemories ?? input.topK));
-                for (const hit of vectorHits) {
-                    const metadata = typeof hit.metadata === "object" && hit.metadata && !Array.isArray(hit.metadata)
-                        ? hit.metadata
-                        : {};
-                    const recordId = typeof metadata.recordId === "string" ? metadata.recordId : undefined;
-                    const scope = metadata.scope;
-                    if (!recordId || (scope !== "thread" && scope !== "agent" && scope !== "workspace" && scope !== "user" && scope !== "project")) {
-                        continue;
-                    }
-                    const canonical = await getMemoryRecord(this.runtimeMemoryStore, scope, recordId);
-                    if (!canonical) {
-                        continue;
-                    }
-                    if (!this.matchesRecallScope(canonical, input.filters)) {
-                        continue;
-                    }
-                    if (input.includeStale ? canonical.status !== "active" && canonical.status !== "stale" : canonical.status !== "active") {
-                        continue;
-                    }
-                    if (input.kinds && !input.kinds.has(canonical.kind)) {
-                        continue;
-                    }
-                    const key = this.normalizeMemoryDedupKey(canonical);
-                    const score = this.scoreStructuredRecord(input.query, canonical) + (typeof hit.score === "number" ? hit.score : 0);
-                    const existing = deduped.get(key);
-                    if (!existing || score > existing.score) {
-                        deduped.set(key, { record: canonical, score });
-                    }
-                }
-            }
-            catch {
-                // Fail open to lexical/runtime ranking.
-            }
-        }
-        const supportsMem0Scope = input.scopes.some((scope) => scope === "thread" || scope === "agent" || scope === "workspace");
-        if (!this.mem0SemanticRecall || !supportsMem0Scope) {
-            return Array.from(deduped.values()).sort((left, right) => right.score - left.score);
-        }
-        try {
-            const hits = await this.mem0SemanticRecall.search({
-                query: input.query,
-                topK: Math.max(input.topK, this.runtimeMemoryPolicy?.retrieval.maxPromptMemories ?? input.topK),
-                agentId: input.filters.agentId,
-                threadId: input.filters.threadId,
-            });
-            for (const hit of hits) {
-                const record = this.createMem0MemoryRecord(hit, input.filters);
-                if (!input.scopes.includes(record.scope)) {
-                    continue;
-                }
-                if (input.kinds && !input.kinds.has(record.kind)) {
-                    continue;
-                }
-                const key = this.normalizeMemoryDedupKey(record);
-                if (deduped.has(key)) {
-                    continue;
-                }
-                deduped.set(key, {
-                    record,
-                    score: this.scoreStructuredRecord(input.query, record) + Math.max(0, Math.min(1, hit.score)) * 4,
-                });
-            }
-            return Array.from(deduped.values()).sort((left, right) => right.score - left.score);
-        }
-        catch {
-            return Array.from(deduped.values()).sort((left, right) => right.score - left.score);
-        }
-    }
-    async rebuildRuntimeMemoryVectorIndex() {
-        const vectorStore = await this.resolveRuntimeMemoryVectorStore();
-        if (!vectorStore) {
-            return;
-        }
-        const records = (await listMemoryRecordsForScopes(this.runtimeMemoryStore, ["thread", "agent", "workspace", "user", "project"]))
-            .filter((record) => record.status === "active");
-        try {
-            await vectorStore.delete({ deleteAll: true });
-            if (records.length === 0) {
-                return;
-            }
-            await vectorStore.addDocuments(records.map((record) => ({
-                pageContent: `${record.summary}\n${record.content}`,
-                metadata: {
-                    recordId: record.id,
-                    scope: record.scope,
-                    kind: record.kind,
-                    status: record.status,
-                    sessionId: record.provenance.sessionId ?? record.provenance.threadId,
-                    agentId: record.provenance.agentId,
-                    workspaceId: record.provenance.workspaceId,
-                    userId: record.provenance.userId,
-                    projectId: record.provenance.projectId,
-                    confidence: record.confidence,
-                    lastConfirmedAt: record.lastConfirmedAt,
-                },
-            })));
-        }
-        catch {
-            // Fail open: vector indexing must not break durable memory writes.
-        }
-    }
-    async refreshStructuredMemoryScope(binding, record) {
-        const provenance = record.provenance;
-        const maxEntries = record.scope === "thread" ? 12 : 20;
-        const titleByScope = {
-            thread: "Thread Structured Memory",
-            agent: "Agent Structured Memory",
-            workspace: "Workspace Structured Memory",
-            user: "User Structured Memory",
-            project: "Project Structured Memory",
-        };
-        await consolidateStructuredMemoryScope({
-            store: this.runtimeMemoryStore,
-            namespace: this.resolveMemoryNamespace(record.scope, binding, {
-                threadId: provenance.sessionId,
-                agentId: provenance.agentId,
-                userId: provenance.userId,
-                projectId: provenance.projectId,
-            }),
-            title: titleByScope[record.scope],
-            scope: record.scope,
-            maxEntries,
-            config: this.runtimeMemoryMaintenanceConfig ?? undefined,
-        });
-    }
     async buildRuntimeMemoryContext(binding, threadId, input) {
         const query = typeof input === "string" ? input : JSON.stringify(input ?? "");
-        const workspaceId = this.getWorkspaceId(binding);
-        const ranked = (await this.rankRecallCandidates(binding, {
+        return this.knowledgeModule.buildPromptContext({
             query,
-            scopes: ["thread", "agent", "workspace", "user", "project"],
-            kinds: null,
             topK: this.runtimeMemoryPolicy?.retrieval.maxPromptMemories ?? 8,
-            includeStale: false,
-            filters: {
-                threadId,
-                agentId: binding.agent.id,
-                workspaceId,
-                userId: "default",
-                projectId: workspaceId,
-            },
-        }))
-            .map((record) => {
-            const scopeBoost = record.record.scope === "thread"
-                ? 4
-                : record.record.scope === "agent"
-                    ? 3
-                    : record.record.scope === "user"
-                        ? 2
-                        : 1;
-            return {
-                content: [
-                    `# Durable ${record.record.scope[0].toUpperCase()}${record.record.scope.slice(1)} Memory`,
-                    "",
-                    `- summary: ${record.record.summary}`,
-                    `- kind: ${record.record.kind}`,
-                    `- scope: ${record.record.scope}`,
-                    `- confidence: ${record.record.confidence.toFixed(2)}`,
-                    "",
-                    record.record.content,
-                ].join("\n"),
-                score: scoreMemoryText(query, `${record.record.summary}\n${record.record.content}`, scopeBoost) +
-                    this.memoryFreshnessBoost(record.record.lastConfirmedAt) +
-                    record.record.confidence,
-            };
-        })
-            .sort((left, right) => right.score - left.score)
-            .slice(0, this.runtimeMemoryPolicy?.retrieval.maxPromptMemories ?? 8);
-        if (ranked.length === 0) {
-            return undefined;
-        }
-        return ranked.map((entry) => entry.content).join("\n\n");
+        }, {
+            sessionId: threadId,
+            agentId: binding.agent.id,
+            workspaceId: this.getWorkspaceId(binding),
+        });
     }
     async persistRuntimeMemoryCandidates(binding, threadId, runId, value) {
         if (!Array.isArray(value) || value.length === 0) {
@@ -1360,144 +973,13 @@ export class AgentHarnessRuntime {
         if (candidates.length === 0) {
             return;
         }
-        await this.persistStructuredMemoryCandidates(binding, {
-            candidates,
-            threadId,
-            runId,
+        await this.knowledgeModule.memorizeCandidates(candidates, {
+            sessionId: threadId,
+            requestId: runId,
             agentId: binding.agent.id,
+            workspaceId: this.getWorkspaceId(binding),
             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 existingRecords = await listMemoryRecordsForScopes(this.runtimeMemoryStore, ["thread", "agent", "workspace", "user", "project"]);
-        const transformedCandidates = this.runtimeMemoryManager
-            ? await this.runtimeMemoryManager.transform({
-                candidates: input.candidates,
-                binding,
-                threadId: input.threadId,
-                runId: input.runId,
-                recordedAt: input.recordedAt,
-                existingRecords,
-            })
-            : input.candidates;
-        const threadCandidates = transformedCandidates.filter((candidate) => (candidate.scope ?? "thread") === "thread");
-        const workspaceCandidates = transformedCandidates.filter((candidate) => (candidate.scope ?? "thread") === "workspace");
-        const agentCandidates = transformedCandidates.filter((candidate) => (candidate.scope ?? "thread") === "agent");
-        const userCandidates = transformedCandidates.filter((candidate) => (candidate.scope ?? "thread") === "user");
-        const projectCandidates = transformedCandidates.filter((candidate) => (candidate.scope ?? "thread") === "project");
-        if (input.storeCandidateLog) {
-            await this.runtimeMemoryStore.put(["memories", "candidates", input.threadId], `${input.runId}.json`, {
-                runId: input.runId,
-                threadId: input.threadId,
-                storedAt: input.recordedAt,
-                candidates: transformedCandidates,
-            });
-        }
-        const persisted = await persistStructuredMemoryRecords({
-            store: this.runtimeMemoryStore,
-            candidates: transformedCandidates,
-            threadId: input.threadId,
-            runId: input.runId,
-            agentId: input.agentId,
-            workspaceId,
-            userId,
-            projectId,
-            recordedAt: input.recordedAt,
-        });
-        await this.rebuildRuntimeMemoryVectorIndex();
-        const writes = [];
-        if (threadCandidates.length > 0) {
-            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,
-            }));
-        }
-        if (userCandidates.length > 0) {
-            writes.push(this.appendMemoryDigest(this.resolveMemoryNamespace("user", binding, { userId }), "tool-memory.md", userCandidates, 20, "User Tool Memory"));
-            writes.push(consolidateStructuredMemoryScope({
-                store: this.runtimeMemoryStore,
-                namespace: this.resolveMemoryNamespace("user", binding, { userId }),
-                title: "User Structured Memory",
-                scope: "user",
-                maxEntries: 20,
-                config: this.runtimeMemoryMaintenanceConfig ?? undefined,
-            }));
-        }
-        if (projectCandidates.length > 0) {
-            writes.push(this.appendMemoryDigest(this.resolveMemoryNamespace("project", binding, { projectId }), "tool-memory.md", projectCandidates, 20, "Project Tool Memory"));
-            writes.push(consolidateStructuredMemoryScope({
-                store: this.runtimeMemoryStore,
-                namespace: this.resolveMemoryNamespace("project", binding, { projectId }),
-                title: "Project Structured Memory",
-                scope: "project",
-                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);
-        const existingItems = Array.isArray(existing?.value?.items)
-            ? ((existing?.value).items ?? [])
-            : [];
-        const merged = [...existingItems];
-        for (const candidate of candidates) {
-            if (merged.some((entry) => entry.content === candidate.content && (entry.scope ?? "thread") === (candidate.scope ?? "thread"))) {
-                continue;
-            }
-            merged.push(candidate);
-        }
-        const recent = merged.slice(-maxEntries);
-        const taxonomyGroups = new Map();
-        for (const candidate of recent) {
-            const kind = normalizeLangMemMemoryKind(candidate.kind);
-            const existing = taxonomyGroups.get(kind) ?? [];
-            existing.push({ ...candidate, kind });
-            taxonomyGroups.set(kind, existing);
-        }
-        await this.runtimeMemoryStore.put(namespace, key, {
-            content: `${renderMemoryCandidatesMarkdown(title, recent)}\n`,
-            items: recent,
-        });
-        await Promise.all(Array.from(taxonomyGroups.entries()).map(async ([kind, items]) => {
-            await this.runtimeMemoryStore.put(namespace, `${kind}.md`, {
-                content: `${renderMemoryCandidatesMarkdown(`${title} (${kind})`, items)}\n`,
-                items,
-            });
-        }));
+        }, { storeCandidateLog: true });
     }
     async resolvePersistedRunPriority(threadId, runId) {
         const persisted = await this.persistence.getRunRequest(threadId, runId);