@botbotgo/agent-harness 0.0.306 → 0.0.307

package/README.md

@@ -942,6 +942,8 @@ The default repository shape uses:
 - `KnowledgeRuntime`: hot path + background formation + long-term maintenance
 - `ProceduralMemoryRuntime`: background formation + scheduled or idle maintenance
 
+In the shipped runtime, explicit durable facts such as “remember I moved to the United States” still go to `KnowledgeRuntime` and land in `knowledge/knowledge.sqlite`. Background procedural learning writes its own store and state files under the same data root, such as `knowledge/procedural-memory.sqlite` and `knowledge/procedural-memory-state.json`.
+
 For DeepAgents-backed workspaces, keep upstream context compaction upstream-owned and use procedural memory only as a background learning layer.
 
 ### `config/catalogs/backends.yaml`

package/README.zh.md

@@ -910,6 +910,8 @@ spec:
 - `KnowledgeRuntime`：hot path + 后台形成 + 长期养护
 - `ProceduralMemoryRuntime`：后台形成 + 定时或空闲整理
 
+在当前已发布的 runtime 里，像“请记住我最近搬到了美国”这种显式 durable fact 仍然走 `KnowledgeRuntime`，并写入 `knowledge/knowledge.sqlite`。后台 procedural learning 会在同一个 data root 下单独写自己的 store 与 state 文件，例如 `knowledge/procedural-memory.sqlite` 和 `knowledge/procedural-memory-state.json`。
+
 对于 `backend: deepagent` 的工作区，应继续把 context compaction 留给上游 DeepAgents，只把 procedural memory 当作后台学习层使用。
 
 ### `config/catalogs/backends.yaml`

package/dist/package-version.d.ts

@@ -1 +1 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.305";
+export declare const AGENT_HARNESS_VERSION = "0.0.306";

package/dist/package-version.js

@@ -1 +1 @@
-export const AGENT_HARNESS_VERSION = "0.0.305";
+export const AGENT_HARNESS_VERSION = "0.0.306";

package/dist/procedural/index.d.ts

@@ -1,2 +1,3 @@
 export { readProceduralMemoryRuntimeConfig } from "./config.js";
+export { createBackgroundProceduralCandidates, createProceduralMemoryManager, ProceduralMemoryFormationSync, } from "./manager.js";
 export type { ProceduralMemoryBackgroundConfig, ProceduralMemoryFormationConfig, ProceduralMemoryMaintenanceConfig, ProceduralMemoryMaintenanceIdleConfig, ProceduralMemoryMaintenanceScheduleConfig, ProceduralMemoryProviderConfig, ProceduralMemoryRetrievalConfig, ProceduralMemoryRuntimeConfig, } from "./config.js";

package/dist/procedural/index.js

@@ -1 +1,2 @@
 export { readProceduralMemoryRuntimeConfig } from "./config.js";
+export { createBackgroundProceduralCandidates, createProceduralMemoryManager, ProceduralMemoryFormationSync, } from "./manager.js";

package/dist/procedural/manager.d.ts

@@ -0,0 +1,59 @@
+import type { CompiledAgentBinding, HarnessEvent, HarnessEventProjection, InternalApprovalRecord, MemoryCandidate, MemoryRecord, SessionSummary, TranscriptMessage, WorkspaceBundle } from "../contracts/types.js";
+import type { RuntimePersistence } from "../persistence/types.js";
+import { type StoreLike } from "../runtime/harness/system/store.js";
+import type { ProceduralMemoryRuntimeConfig } from "./config.js";
+type ProceduralMemoryWriter = (input: {
+    candidates: MemoryCandidate[];
+    sessionId: string;
+    requestId: string;
+    agentId: string;
+    userId?: string;
+    projectId?: string;
+    recordedAt: string;
+}) => Promise<void>;
+type ProceduralMemoryFormationOptions = {
+    userId?: string;
+    projectId?: string;
+};
+type ProceduralMemoryManagerLike = {
+    transform(input: {
+        candidates: MemoryCandidate[];
+        binding: CompiledAgentBinding;
+        sessionId: string;
+        requestId: string;
+        recordedAt: string;
+        existingRecords: MemoryRecord[];
+    }): Promise<MemoryCandidate[]>;
+};
+export declare function createBackgroundProceduralCandidates(input: {
+    session: SessionSummary;
+    requestId: string;
+    agentId: string;
+    trigger: "approval.resolved" | "request.completed";
+    recordedAt: string;
+    messages: TranscriptMessage[];
+    approvals: InternalApprovalRecord[];
+    focus: string[];
+}): MemoryCandidate[];
+export declare function createProceduralMemoryManager(input: {
+    workspace: WorkspaceBundle;
+    binding: CompiledAgentBinding;
+    config: ProceduralMemoryRuntimeConfig;
+    modelResolver?: (modelId: string) => unknown;
+}): ProceduralMemoryManagerLike;
+export declare class ProceduralMemoryFormationSync implements HarnessEventProjection {
+    private readonly persistence;
+    private readonly config;
+    private readonly writer;
+    private readonly stateStore;
+    private readonly options;
+    private readonly pending;
+    private syncChain;
+    readonly name = "procedural-memory-formation-sync";
+    constructor(persistence: RuntimePersistence, config: ProceduralMemoryRuntimeConfig, writer: ProceduralMemoryWriter, runtimeRoot: string, stateStore?: StoreLike, options?: ProceduralMemoryFormationOptions);
+    shouldHandle(event: HarnessEvent): boolean;
+    handleEvent(event: HarnessEvent): Promise<void>;
+    private reflectRun;
+    close(): Promise<void>;
+}
+export {};

package/dist/procedural/manager.js

@@ -0,0 +1,345 @@
+import path from "node:path";
+import { extractMessageText } from "../utils/message-content.js";
+import { createResolvedModel } from "../runtime/adapter/model/model-providers.js";
+import { FileBackedStore } from "../runtime/harness/system/store.js";
+import { compileModel } from "../workspace/resource-compilers.js";
+import { resolveRefId } from "../workspace/support/workspace-ref-utils.js";
+import { renderProceduralMemoryManagerPrompt } from "../runtime/support/runtime-prompts.js";
+const FORMATION_EVENT_TYPES = new Set([
+    "request.state.changed",
+    "approval.resolved",
+]);
+function excerpt(message) {
+    if (!message?.content) {
+        return undefined;
+    }
+    const normalized = extractMessageText(message.content).replace(/\s+/g, " ").trim();
+    if (!normalized) {
+        return undefined;
+    }
+    return normalized.length > 240 ? `${normalized.slice(0, 237)}...` : normalized;
+}
+function summarizeApprovals(approvals) {
+    if (approvals.length === 0) {
+        return "No approvals were recorded in this run.";
+    }
+    return approvals
+        .map((approval) => `${approval.toolName} (${approval.status})`)
+        .join(", ");
+}
+function fingerprintMessages(messages, focus) {
+    const serialized = messages
+        .map((message) => `${message.role}\n${message.createdAt}\n${extractMessageText(message.content)}`)
+        .join("\n---\n");
+    return `${focus.join(",")}::${serialized}`;
+}
+function selectRelatedContextRecords(candidate, existingRecords, maxRecords) {
+    const candidateText = `${candidate.summary ?? ""}\n${candidate.content}`.toLowerCase().trim();
+    if (!candidateText) {
+        return existingRecords.slice(0, maxRecords);
+    }
+    return existingRecords
+        .filter((record) => record.status === "active")
+        .map((record) => {
+        let score = 0;
+        const recordText = `${record.summary}\n${record.content}`.toLowerCase();
+        if (candidate.scope && record.scope === candidate.scope) {
+            score += 2;
+        }
+        if (recordText.includes(candidateText) || candidateText.includes(recordText)) {
+            score += 4;
+        }
+        const candidateTokens = new Set(candidateText.split(/[^a-z0-9_\u4e00-\u9fff]+/iu).filter((token) => token.length > 1));
+        const recordTokens = new Set(recordText.split(/[^a-z0-9_\u4e00-\u9fff]+/iu).filter((token) => token.length > 1));
+        let shared = 0;
+        for (const token of candidateTokens) {
+            if (recordTokens.has(token)) {
+                shared += 1;
+            }
+        }
+        score += shared;
+        return { record, score };
+    })
+        .filter((item) => item.score > 0)
+        .sort((left, right) => right.score - left.score || right.record.lastConfirmedAt.localeCompare(left.record.lastConfirmedAt))
+        .slice(0, maxRecords)
+        .map((item) => item.record);
+}
+function extractText(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value !== "object" || value === null) {
+        return undefined;
+    }
+    if ("content" in value && typeof value.content === "string") {
+        return String(value.content);
+    }
+    const kwargs = "kwargs" in value && typeof value.kwargs === "object" && value.kwargs !== null
+        ? value.kwargs
+        : undefined;
+    if (typeof kwargs?.content === "string") {
+        return kwargs.content;
+    }
+    return undefined;
+}
+function tryParseJsonObject(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        const match = text.match(/\{[\s\S]*\}/);
+        if (!match) {
+            return null;
+        }
+        try {
+            const parsed = JSON.parse(match[0]);
+            return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+function asString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function asNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function asStringArray(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const items = value
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+    return items.length > 0 ? Array.from(new Set(items)) : undefined;
+}
+function normalizeScope(value) {
+    return value === "session" || value === "agent" || value === "workspace" || value === "user" || value === "project"
+        ? value
+        : undefined;
+}
+function normalizeCandidateOutputs(parsed, candidate) {
+    const rawOutputs = Array.isArray(parsed.mutations)
+        ? parsed.mutations.filter((item) => typeof item === "object" && item !== null && !Array.isArray(item))
+        : [parsed];
+    return rawOutputs.map((output) => ({
+        ...candidate,
+        kind: "procedural",
+        scope: normalizeScope(output.scope) ?? candidate.scope ?? "workspace",
+        summary: asString(output.summary) ?? candidate.summary,
+        content: asString(output.content) ?? candidate.content,
+        confidence: asNumber(output.confidence) ?? candidate.confidence ?? 0.72,
+        tags: asStringArray(output.tags) ?? candidate.tags,
+    })).filter((item) => typeof item.content === "string" && item.content.trim().length > 0);
+}
+export function createBackgroundProceduralCandidates(input) {
+    const latestUser = excerpt(input.messages.filter((message) => message.role === "user").at(-1));
+    const latestAssistant = excerpt(input.messages.filter((message) => message.role === "assistant").at(-1));
+    const transcriptPreview = input.messages
+        .slice(-6)
+        .map((message) => `${message.role}: ${excerpt(message) ?? "(empty)"}`)
+        .join("\n");
+    const approvals = summarizeApprovals(input.approvals);
+    const sourceRef = `runtime://sessions/${input.session.sessionId}/requests/${input.requestId}/procedural-reflection`;
+    return [{
+            kind: "procedural",
+            scope: "workspace",
+            sourceType: "runtime-transcript",
+            sourceRef,
+            summary: latestUser ?? latestAssistant ?? `Procedural reflection for ${input.requestId}`,
+            content: [
+                "Completed run transcript evidence for procedural memory extraction.",
+                `Trigger: ${input.trigger}`,
+                `Focus: ${input.focus.join(", ")}`,
+                "",
+                "Latest user message:",
+                latestUser ?? "(none)",
+                "",
+                "Latest assistant response:",
+                latestAssistant ?? "(none)",
+                "",
+                "Recent transcript excerpt:",
+                transcriptPreview || "(none)",
+                "",
+                "Approval snapshot:",
+                approvals,
+            ].join("\n"),
+            confidence: 0.64,
+            observedAt: input.recordedAt,
+            tags: ["procedural-background-extraction", input.trigger, ...input.focus],
+        }];
+}
+async function runProceduralMemoryManager(input) {
+    let resolvedModel;
+    try {
+        resolvedModel = await createResolvedModel(input.model, input.modelResolver);
+    }
+    catch {
+        return input.candidates;
+    }
+    const invoker = resolvedModel;
+    if (typeof invoker.invoke !== "function") {
+        return input.candidates;
+    }
+    const transformed = [];
+    for (const candidate of input.candidates) {
+        const prompt = renderProceduralMemoryManagerPrompt({
+            candidate,
+            sessionId: input.sessionId,
+            requestId: input.requestId,
+            focus: input.focus,
+            existingRecords: selectRelatedContextRecords(candidate, input.existingRecords, input.maxContextRecords ?? input.existingRecords.length),
+        });
+        let response;
+        try {
+            response = await invoker.invoke(prompt, {});
+        }
+        catch {
+            continue;
+        }
+        const parsed = tryParseJsonObject(extractText(response) ?? "");
+        if (!parsed || parsed.store === false) {
+            continue;
+        }
+        transformed.push(...normalizeCandidateOutputs(parsed, candidate));
+    }
+    return transformed;
+}
+export function createProceduralMemoryManager(input) {
+    return {
+        async transform({ candidates, binding, sessionId, requestId, recordedAt, existingRecords }) {
+            if (input.config.enabled !== true || candidates.length === 0) {
+                return candidates;
+            }
+            if (!binding.langchainAgentParams?.model) {
+                return candidates;
+            }
+            const providerModelRef = asString(input.config.provider?.options?.modelRef);
+            const primaryModel = (() => {
+                if (!providerModelRef) {
+                    return binding.langchainAgentParams.model;
+                }
+                const configured = input.workspace.models.get(resolveRefId(providerModelRef));
+                return configured ? compileModel(configured) : binding.langchainAgentParams.model;
+            })();
+            return runProceduralMemoryManager({
+                workspace: input.workspace,
+                binding,
+                model: primaryModel,
+                candidates,
+                sessionId,
+                requestId,
+                recordedAt,
+                existingRecords: existingRecords.filter((record) => record.status === "active"),
+                focus: input.config.formation?.background?.scopeHints ?? ["workflow_patterns", "debugging_lessons", "reusable_procedures"],
+                maxContextRecords: 8,
+                modelResolver: input.modelResolver,
+            });
+        },
+    };
+}
+export class ProceduralMemoryFormationSync {
+    persistence;
+    config;
+    writer;
+    stateStore;
+    options;
+    pending = new Set();
+    syncChain = Promise.resolve();
+    name = "procedural-memory-formation-sync";
+    constructor(persistence, config, writer, runtimeRoot, stateStore = new FileBackedStore(path.join(runtimeRoot, config.formation?.background?.stateStorePath ?? "knowledge/procedural-memory-state.json")), options = {}) {
+        this.persistence = persistence;
+        this.config = config;
+        this.writer = writer;
+        this.stateStore = stateStore;
+        this.options = options;
+    }
+    shouldHandle(event) {
+        const background = this.config.formation?.background;
+        if (!background?.enabled || !FORMATION_EVENT_TYPES.has(event.eventType)) {
+            return false;
+        }
+        if (event.eventType === "approval.resolved") {
+            return background.writeOnApprovalResolution;
+        }
+        return background.writeOnRequestCompletion && event.payload.state === "completed";
+    }
+    async handleEvent(event) {
+        if (!this.shouldHandle(event)) {
+            return;
+        }
+        const trigger = event.eventType === "approval.resolved" ? "approval.resolved" : "request.completed";
+        const task = this.syncChain
+            .then(() => this.reflectRun(event.sessionId, event.requestId, trigger, event.timestamp))
+            .catch(() => {
+            // Fail open: procedural reflection should not block runtime progress.
+        });
+        this.syncChain = task
+            .catch(() => {
+            // Fail open: procedural reflection should not block runtime progress.
+        })
+            .finally(() => {
+            this.pending.delete(task);
+        });
+        this.pending.add(task);
+    }
+    async reflectRun(sessionId, requestId, trigger, recordedAt) {
+        const background = this.config.formation?.background;
+        if (!background) {
+            return;
+        }
+        const [session, run, allMessages, approvals] = await Promise.all([
+            this.persistence.getSession(sessionId),
+            this.persistence.getRequest(requestId),
+            this.persistence.listSessionMessages(sessionId, background.maxMessagesPerRequest),
+            this.persistence.getRequestApprovals(sessionId, requestId),
+        ]);
+        if (!session || !run) {
+            return;
+        }
+        const messages = allMessages.filter((message) => message.requestId === requestId);
+        if (messages.length === 0) {
+            return;
+        }
+        const fingerprint = fingerprintMessages(messages, background.scopeHints);
+        const namespace = ["memories", "formation", "sessions", sessionId, "requests"];
+        const cursor = await this.stateStore.get(namespace, requestId);
+        const existing = cursor?.value;
+        if (existing?.fingerprint === fingerprint && existing.trigger === trigger) {
+            return;
+        }
+        const candidates = createBackgroundProceduralCandidates({
+            session,
+            requestId,
+            agentId: run.agentId ?? session.agentId,
+            trigger,
+            recordedAt,
+            messages,
+            approvals,
+            focus: background.scopeHints,
+        });
+        await this.writer({
+            candidates,
+            sessionId,
+            requestId,
+            agentId: run.agentId ?? session.agentId,
+            userId: this.options.userId,
+            projectId: this.options.projectId,
+            recordedAt,
+        });
+        await this.stateStore.put(namespace, requestId, {
+            fingerprint,
+            candidateCount: candidates.length,
+            syncedAt: new Date().toISOString(),
+            trigger,
+        });
+    }
+    async close() {
+        await Promise.allSettled(Array.from(this.pending));
+    }
+}

package/dist/resources/prompts/runtime/procedural-memory-manager.md

@@ -0,0 +1,40 @@
+You are deciding whether a completed run should produce reusable procedural memory.
+
+Focus areas:
+{{focus}}
+
+Session:
+{{sessionId}}
+
+Request:
+{{requestId}}
+
+Candidate:
+{{candidateJson}}
+
+Existing procedural memory:
+{{existingRecords}}
+
+Return exactly one JSON object.
+
+Rules:
+- Store only reusable experience, tactics, workflows, debugging lessons, or failure-prevention guidance.
+- Ignore pure personal facts, profile facts, location changes, and one-off durable knowledge facts unless they imply a reusable procedure.
+- Prefer concise, imperative procedural guidance that can help a future run act better.
+- Avoid duplicating existing procedural memory.
+- Default kind must be "procedural".
+- Use scope "workspace" for repo/workspace habits, "project" for broader project rules, "agent" for agent-specific operating habits, and "user" only when the reusable procedure is clearly personal to the user.
+
+If there is no reusable procedural lesson, return:
+{"store":false}
+
+If there is a reusable lesson, return:
+{
+  "store": true,
+  "summary": "short summary",
+  "content": "clear reusable procedure or lesson",
+  "kind": "procedural",
+  "scope": "workspace",
+  "tags": ["workflow_patterns"],
+  "confidence": 0.78
+}

package/dist/runtime/harness.d.ts

@@ -36,6 +36,12 @@ export declare class AgentHarnessRuntime {
     private readonly knowledgeModule;
     private readonly runtimeMemoryFormationSync;
     private readonly unregisterRuntimeMemoryFormationSync;
+    private readonly proceduralMemoryConfig;
+    private readonly proceduralMemoryStore;
+    private readonly proceduralMemoryManager;
+    private readonly proceduralMemoryModule;
+    private readonly proceduralMemoryFormationSync;
+    private readonly unregisterProceduralMemoryFormationSync;
     private readonly resolvedRuntimeAdapterOptions;
     private readonly scheduleManager;
     private readonly healthMonitor;

package/dist/runtime/harness.js

@@ -35,7 +35,7 @@ import { Mem0IngestionSync, Mem0SemanticRecall, readMem0RuntimeConfig, } from ".
 import { createRuntimeMemoryManager, RuntimeMemoryFormationSync, readRuntimeMemoryFormationConfig, } from "./harness/system/runtime-memory-manager.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 { resolveKnowledgeStorePath, resolveProceduralMemoryStorePath } from "./support/runtime-layout.js";
 import { SystemScheduleManager } from "./scheduling/system-schedule-manager.js";
 import { initializeHarnessRuntime, reclaimExpiredClaimedRequests as reclaimHarnessExpiredClaimedRequests, recoverStartupRequests as recoverHarnessStartupRequests, isStaleRunningRequest as isHarnessStaleRunningRequest, } from "./harness/run/startup-runtime.js";
 import { traceStartupStage } from "./startup-tracing.js";
@@ -44,6 +44,7 @@ import { streamHarnessRun } from "./harness/run/stream-run.js";
 import { defaultRequestedAgentId, prepareRunStart } from "./harness/run/start-run.js";
 import { buildRequestInspectionRecord, buildSessionInspectionRecord, deleteSessionRecord, getPublicApproval, listPublicApprovals, } from "./harness/run/session-records.js";
 import { createKnowledgeModule } from "../knowledge/index.js";
+import { createProceduralMemoryManager, ProceduralMemoryFormationSync, readProceduralMemoryRuntimeConfig, } from "../procedural/index.js";
 const ACTIVE_REQUEST_STATES = [
     "queued",
     "claimed",
@@ -132,6 +133,17 @@ function toPublicHarnessStreamItem(item) {
             return item;
     }
 }
+function mergeMemoryItems(...groups) {
+    const merged = new Map();
+    for (const group of groups) {
+        for (const item of group) {
+            if (!merged.has(item.id)) {
+                merged.set(item.id, item);
+            }
+        }
+    }
+    return Array.from(merged.values());
+}
 function normalizeSessionListText(content, limit) {
     if (!content) {
         return undefined;
@@ -216,6 +228,12 @@ export class AgentHarnessRuntime {
     knowledgeModule;
     runtimeMemoryFormationSync;
     unregisterRuntimeMemoryFormationSync;
+    proceduralMemoryConfig;
+    proceduralMemoryStore;
+    proceduralMemoryManager;
+    proceduralMemoryModule;
+    proceduralMemoryFormationSync;
+    unregisterProceduralMemoryFormationSync;
     resolvedRuntimeAdapterOptions;
     scheduleManager;
     healthMonitor;
@@ -461,6 +479,82 @@ export class AgentHarnessRuntime {
             this.runtimeMemoryFormationSync = null;
             this.unregisterRuntimeMemoryFormationSync = () => { };
         }
+        const proceduralMemoryConfig = readProceduralMemoryRuntimeConfig(this.defaultRuntimeEntryBinding?.harnessRuntime.proceduralMemory);
+        this.proceduralMemoryConfig = proceduralMemoryConfig?.enabled ? proceduralMemoryConfig : null;
+        const proceduralStoreConfig = this.proceduralMemoryConfig?.store && Object.keys(this.proceduralMemoryConfig.store).length > 0
+            ? this.proceduralMemoryConfig.store
+            : {
+                kind: "SqliteStore",
+                path: resolveProceduralMemoryStorePath(runtimeRoot),
+            };
+        this.proceduralMemoryStore = this.proceduralMemoryConfig
+            ? resolveStoreFromConfig(this.stores, proceduralStoreConfig, runtimeRoot) ?? null
+            : null;
+        this.proceduralMemoryManager =
+            this.defaultRuntimeEntryBinding && this.proceduralMemoryConfig
+                ? createProceduralMemoryManager({
+                    workspace: this.workspace,
+                    binding: this.defaultRuntimeEntryBinding,
+                    config: this.proceduralMemoryConfig,
+                    modelResolver: this.resolvedRuntimeAdapterOptions.modelResolver,
+                })
+                : null;
+        this.proceduralMemoryModule =
+            this.proceduralMemoryConfig && this.proceduralMemoryStore
+                ? createKnowledgeModule({
+                    store: this.proceduralMemoryStore,
+                    policy: null,
+                    maintenanceConfig: null,
+                    resolveNamespace: (scope, context) => {
+                        const binding = this.defaultRuntimeEntryBinding;
+                        if (!binding) {
+                            const identifier = scope === "session"
+                                ? context.sessionId
+                                : scope === "agent"
+                                    ? context.agentId
+                                    : scope === "workspace"
+                                        ? context.workspaceId
+                                        : scope === "user"
+                                            ? context.userId ?? "default"
+                                            : context.projectId ?? context.workspaceId;
+                            return ["procedural", `${scope}s`, identifier ?? "default"];
+                        }
+                        return this.resolveMemoryNamespace(scope, binding, {
+                            sessionId: context.sessionId,
+                            agentId: context.agentId,
+                            userId: context.userId,
+                            projectId: context.projectId,
+                        });
+                    },
+                    resolveVectorStore: async () => null,
+                    transformCandidates: this.proceduralMemoryManager && this.defaultRuntimeEntryBinding
+                        ? ({ candidates, context, existingRecords }) => this.proceduralMemoryManager.transform({
+                            candidates,
+                            binding: this.defaultRuntimeEntryBinding,
+                            sessionId: context.sessionId ?? `procedural-api-${context.requestId ?? "unknown"}`,
+                            requestId: context.requestId ?? createPersistentId(new Date(context.recordedAt ?? new Date().toISOString())),
+                            recordedAt: context.recordedAt ?? new Date().toISOString(),
+                            existingRecords,
+                        })
+                        : undefined,
+                })
+                : null;
+        if (this.proceduralMemoryConfig && this.proceduralMemoryModule) {
+            this.proceduralMemoryFormationSync = new ProceduralMemoryFormationSync(this.persistence, this.proceduralMemoryConfig, (input) => this.proceduralMemoryModule.memorizeCandidates(input.candidates, {
+                sessionId: input.sessionId,
+                requestId: input.requestId,
+                agentId: input.agentId,
+                workspaceId: this.getWorkspaceId(this.defaultRuntimeEntryBinding),
+                userId: input.userId,
+                projectId: input.projectId,
+                recordedAt: input.recordedAt,
+            }, { storeCandidateLog: false }).then(() => undefined), runtimeRoot);
+            this.unregisterProceduralMemoryFormationSync = this.eventBus.registerProjection(this.proceduralMemoryFormationSync);
+        }
+        else {
+            this.proceduralMemoryFormationSync = null;
+            this.unregisterProceduralMemoryFormationSync = () => { };
+        }
         this.recoveryConfig = getRecoveryConfig(workspace.refs);
         this.concurrencyConfig = getConcurrencyConfig(workspace.refs);
         const healthConfig = readHealthMonitorConfig(workspace);
@@ -514,6 +608,9 @@ export class AgentHarnessRuntime {
             scheduleBackgroundTask: (task) => this.scheduleBackgroundStartupTask(task),
         });
         this.scheduleBackgroundStartupTask(traceStartupStage("runtime.initialize.startupRecovery", () => this.recoverStartupRequests()));
+        if (this.proceduralMemoryStore) {
+            await this.proceduralMemoryStore.listNamespaces();
+        }
         this.initialized = true;
     }
     subscribe(listener) {
@@ -604,26 +701,44 @@ export class AgentHarnessRuntime {
         if (!binding) {
             throw new Error("recall requires a runtime entry binding.");
         }
-        return this.knowledgeModule.recall(input, {
+        const context = {
             sessionId: input.sessionId,
             agentId: input.agentId ?? binding.agent.id,
             workspaceId: input.workspaceId ?? this.getWorkspaceId(binding),
             userId: input.userId,
             projectId: input.projectId,
-        });
+        };
+        const [knowledge, procedural] = await Promise.all([
+            this.knowledgeModule.recall(input, context),
+            this.proceduralMemoryModule && this.proceduralMemoryConfig?.retrieval?.enabled !== false
+                ? this.proceduralMemoryModule.recall(input, context)
+                : Promise.resolve({ items: [] }),
+        ]);
+        return {
+            items: mergeMemoryItems(knowledge.items, procedural.items),
+        };
     }
     async listMemories(input = {}) {
         const binding = this.defaultRuntimeEntryBinding;
         if (!binding) {
             throw new Error("listMemories requires a runtime entry binding.");
         }
-        return this.knowledgeModule.list(input, {
+        const context = {
             sessionId: input.sessionId,
             agentId: input.agentId,
             workspaceId: input.workspaceId ?? this.getWorkspaceId(binding),
             userId: input.userId,
             projectId: input.projectId,
-        });
+        };
+        const [knowledge, procedural] = await Promise.all([
+            this.knowledgeModule.list(input, context),
+            this.proceduralMemoryModule
+                ? this.proceduralMemoryModule.list(input, context)
+                : Promise.resolve({ items: [] }),
+        ]);
+        return {
+            items: mergeMemoryItems(knowledge.items, procedural.items),
+        };
     }
     async updateMemory(input) {
         const binding = this.defaultRuntimeEntryBinding;
@@ -1029,27 +1144,40 @@ export class AgentHarnessRuntime {
         return path.basename(workspaceRoot) || "default";
     }
     async buildRuntimeMemoryContext(binding, sessionId, input) {
-        if (!this.runtimeMemoryPolicy) {
+        if (!this.runtimeMemoryPolicy && !this.proceduralMemoryModule) {
             return undefined;
         }
         const query = extractMessageText(input ?? "").trim();
         if (!query) {
             return undefined;
         }
-        const promptRecall = await this.knowledgeModule.buildPromptRecall({
-            query,
-            topK: this.runtimeMemoryPolicy?.retrieval.maxPromptMemories ?? 8,
-        }, {
+        const context = {
             sessionId,
             agentId: binding.agent.id,
             workspaceId: this.getWorkspaceId(binding),
-        });
-        if (!promptRecall.context?.trim()) {
+        };
+        const proceduralTopK = this.proceduralMemoryConfig?.retrieval?.maxPromptItems ?? 4;
+        const [knowledgeRecall, proceduralRecall] = await Promise.all([
+            this.runtimeMemoryPolicy
+                ? this.knowledgeModule.buildPromptRecall({
+                    query,
+                    topK: this.runtimeMemoryPolicy?.retrieval.maxPromptMemories ?? 8,
+                }, context)
+                : Promise.resolve({ items: [], context: undefined }),
+            this.proceduralMemoryModule && this.proceduralMemoryConfig?.retrieval?.enabled !== false
+                ? this.proceduralMemoryModule.buildPromptRecall({
+                    query,
+                    topK: proceduralTopK,
+                }, context)
+                : Promise.resolve({ items: [], context: undefined }),
+        ]);
+        const promptParts = [knowledgeRecall.context?.trim(), proceduralRecall.context?.trim()].filter((value) => !!value);
+        if (promptParts.length === 0) {
             return undefined;
         }
         return {
-            prompt: promptRecall.context,
-            items: promptRecall.items,
+            prompt: promptParts.join("\n\n"),
+            items: mergeMemoryItems(knowledgeRecall.items, proceduralRecall.items),
         };
     }
     async persistRuntimeMemoryCandidates(binding, sessionId, requestId, value) {
@@ -1374,11 +1502,13 @@ export class AgentHarnessRuntime {
         this.unregisterRuntimeMemorySync();
         this.unregisterMem0IngestionSync();
         this.unregisterRuntimeMemoryFormationSync();
+        this.unregisterProceduralMemoryFormationSync();
         await Promise.allSettled(Array.from(this.backgroundTasks));
         await this.sessionMemorySync?.close();
         await this.runtimeMemorySync?.close();
         await this.mem0IngestionSync?.close();
         await this.runtimeMemoryFormationSync?.close();
+        await this.proceduralMemoryFormationSync?.close();
         await closeMcpClientsForWorkspace(this.workspace);
         this.initialized = false;
     }

package/dist/runtime/support/runtime-prompts.d.ts

@@ -28,3 +28,10 @@ export declare function renderRuntimeMemoryMutationReconciliationPrompt(input: {
     candidate: MemoryCandidate;
     existingRecords: MemoryRecord[];
 }): string;
+export declare function renderProceduralMemoryManagerPrompt(input: {
+    candidate: MemoryCandidate;
+    sessionId: string;
+    requestId: string;
+    focus: string[];
+    existingRecords: MemoryRecord[];
+}): string;

package/dist/runtime/support/runtime-prompts.js

@@ -53,3 +53,17 @@ export function renderRuntimeMemoryMutationReconciliationPrompt(input) {
         existingRecords: existing,
     });
 }
+export function renderProceduralMemoryManagerPrompt(input) {
+    const existing = input.existingRecords.length === 0
+        ? "(none)"
+        : input.existingRecords
+            .map((record) => `- scope=${record.scope}; kind=${record.kind}; status=${record.status}; summary=${record.summary}; content=${record.content.replace(/\s+/g, " ").slice(0, 220)}`)
+            .join("\n");
+    return renderBundledTemplate("prompts/runtime/procedural-memory-manager.md", {
+        sessionId: input.sessionId,
+        requestId: input.requestId,
+        focus: input.focus.join(", "),
+        candidateJson: JSON.stringify(input.candidate, null, 2),
+        existingRecords: existing,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.306",
+  "version": "0.0.307",
   "description": "Workspace runtime for multi-agent applications",
   "license": "MIT",
   "type": "module",