@botbotgo/agent-harness 0.0.154 → 0.0.155

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

@@ -0,0 +1,371 @@
+import path from "node:path";
+import { extractMessageText } from "../../../utils/message-content.js";
+import { createResolvedModel } from "../../adapter/model/model-providers.js";
+import { FileBackedStore } from "./store.js";
+import { compileModel } from "../../../workspace/resource-compilers.js";
+import { resolveRefId } from "../../../workspace/support/workspace-ref-utils.js";
+const FORMATION_EVENT_TYPES = new Set(["run.state.changed", "approval.resolved"]);
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : undefined;
+}
+function asBoolean(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
+function asPositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+function asNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+function asMemoryScopes(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const scopes = value
+        .filter((item) => typeof item === "string")
+        .filter((item) => ["thread", "agent", "workspace", "user", "project"].includes(item));
+    return scopes.length > 0 ? Array.from(new Set(scopes)) : undefined;
+}
+function normalizeScopeList(scopes) {
+    return Array.from(new Set(scopes));
+}
+function asStrategy(value) {
+    return value === "rules" || value === "model" ? value : undefined;
+}
+export function readRuntimeMemoryFormationConfig(runtimeMemory, workspaceRoot) {
+    if (runtimeMemory?.enabled !== true) {
+        return undefined;
+    }
+    const formation = asRecord(runtimeMemory.formation);
+    const hotPath = asRecord(formation?.hotPath);
+    const manager = asRecord(formation?.manager);
+    const background = asRecord(formation?.background);
+    const ingestion = asRecord(runtimeMemory.ingestion);
+    const workspaceBaseName = path.basename(workspaceRoot) || "agent-harness";
+    const resolved = {
+        enabled: true,
+        hotPath: {
+            enabled: asBoolean(hotPath?.enabled) ?? true,
+        },
+        manager: {
+            enabled: asBoolean(manager?.enabled) ?? true,
+            strategy: asStrategy(manager?.strategy) ?? "rules",
+            modelRef: asNonEmptyString(manager?.modelRef),
+            maxContextRecords: asPositiveInteger(manager?.maxContextRecords) ?? 12,
+        },
+        background: {
+            enabled: asBoolean(background?.enabled) ?? true,
+            maxMessagesPerRun: asPositiveInteger(background?.maxMessagesPerRun) ?? asPositiveInteger(ingestion?.maxMessagesPerRun) ?? 40,
+            scopes: normalizeScopeList(asMemoryScopes(background?.scopes) ?? ["thread"]),
+            stateStorePath: asNonEmptyString(background?.stateStorePath) ?? `${workspaceBaseName}-memory-formation-state.json`,
+            writeOnApprovalResolution: asBoolean(background?.writeOnApprovalResolution) ?? asBoolean(ingestion?.writeOnApprovalResolution) ?? true,
+            writeOnRunCompletion: asBoolean(background?.writeOnRunCompletion) ?? asBoolean(ingestion?.writeOnRunCompletion) ?? true,
+        },
+    };
+    if (!resolved.hotPath.enabled && !resolved.background.enabled) {
+        return undefined;
+    }
+    return 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(", ");
+}
+export function createBackgroundMemoryCandidates(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 userContext = latestUser ?? "No durable user context captured.";
+    const assistantContext = latestAssistant ?? "No durable assistant response captured.";
+    const approvals = summarizeApprovals(input.approvals);
+    const summarySeed = latestUser ?? latestAssistant ?? `Run ${input.runId}`;
+    const baseSummary = summarySeed.length > 120 ? `${summarySeed.slice(0, 117)}...` : summarySeed;
+    const sourceRefBase = `runtime://threads/${input.thread.threadId}/runs/${input.runId}/background-reflection`;
+    return input.scopes.map((scope) => ({
+        kind: "episodic",
+        scope,
+        sourceType: "runtime-reflection",
+        sourceRef: `${sourceRefBase}#${scope}`,
+        summary: `${baseSummary} (${scope})`,
+        content: [
+            `Run ${input.runId} completed for thread ${input.thread.threadId}.`,
+            `Trigger: ${input.trigger}.`,
+            `Latest user context: ${userContext}`,
+            `Latest assistant context: ${assistantContext}`,
+            `Approvals: ${approvals}`,
+        ].join("\n"),
+        confidence: 0.72,
+        observedAt: input.recordedAt,
+        tags: ["background-reflection", "langmem-aligned", scope, input.trigger],
+    }));
+}
+function normalizeKind(value, fallback) {
+    if (value === "semantic" || value === "episodic" || value === "procedural") {
+        return value;
+    }
+    return fallback;
+}
+function normalizeScope(value, fallback) {
+    if (value === "thread" || value === "agent" || value === "workspace" || value === "user" || value === "project") {
+        return value;
+    }
+    return fallback;
+}
+function normalizeTags(value, fallback) {
+    if (!Array.isArray(value)) {
+        return fallback;
+    }
+    const tags = value.filter((item) => typeof item === "string" && item.trim().length > 0);
+    return tags.length > 0 ? tags : fallback;
+}
+function normalizeConfidence(value, fallback) {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+        return fallback;
+    }
+    return Math.min(1, Math.max(0, value));
+}
+function extractText(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "object" && value !== null && "content" in value && typeof value.content === "string") {
+        return String(value.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 renderManagerPrompt(input) {
+    const existing = input.existingRecords.length === 0
+        ? "(none)"
+        : input.existingRecords
+            .map((record) => `- scope=${record.scope}; kind=${record.kind}; summary=${record.summary}; status=${record.status}; content=${record.content.replace(/\s+/g, " ").slice(0, 220)}`)
+            .join("\n");
+    return [
+        "You are the runtime memory manager.",
+        "Decide whether a candidate should be stored as durable memory and refine it if appropriate.",
+        "Return JSON only.",
+        "",
+        "Rules:",
+        '- Store only durable reusable knowledge. Reject transient chatter, scratchpad, or duplication without added value.',
+        '- Prefer semantic/episodic/procedural kinds only.',
+        '- Prefer scopes thread/agent/workspace/user/project only.',
+        '- If the candidate should not be stored, return {"store": false, "reason": "..."}',
+        '- If it should be stored, return {"store": true, "content": "...", "summary": "...", "kind": "...", "scope": "...", "tags": ["..."], "confidence": 0.0}',
+        "",
+        `threadId=${input.threadId}`,
+        `runId=${input.runId}`,
+        "",
+        "Candidate:",
+        JSON.stringify(input.candidate, null, 2),
+        "",
+        "Existing relevant records:",
+        existing,
+    ].join("\n");
+}
+export async function runModelMemoryManager(input) {
+    const resolvedModel = await createResolvedModel(input.model, input.modelResolver);
+    const invoker = resolvedModel;
+    if (typeof invoker.invoke !== "function") {
+        return input.candidates;
+    }
+    const transformed = [];
+    for (const candidate of input.candidates) {
+        const prompt = renderManagerPrompt({
+            candidate,
+            threadId: input.threadId,
+            runId: input.runId,
+            existingRecords: input.existingRecords,
+        });
+        const response = await invoker.invoke(prompt, {});
+        const parsed = tryParseJsonObject(extractText(response) ?? "");
+        if (!parsed) {
+            transformed.push(candidate);
+            continue;
+        }
+        if (parsed.store === false) {
+            continue;
+        }
+        transformed.push({
+            ...candidate,
+            content: typeof parsed.content === "string" && parsed.content.trim().length > 0 ? parsed.content.trim() : candidate.content,
+            summary: typeof parsed.summary === "string" && parsed.summary.trim().length > 0 ? parsed.summary.trim() : candidate.summary,
+            kind: normalizeKind(parsed.kind, normalizeKind(candidate.kind, undefined)),
+            scope: normalizeScope(parsed.scope, normalizeScope(candidate.scope, undefined)),
+            tags: normalizeTags(parsed.tags, candidate.tags),
+            confidence: normalizeConfidence(parsed.confidence, candidate.confidence),
+            observedAt: candidate.observedAt ?? input.recordedAt,
+        });
+    }
+    return transformed;
+}
+export function createRuntimeMemoryManager(input) {
+    return {
+        async transform({ candidates, binding, threadId, runId, recordedAt, existingRecords }) {
+            if (input.config.manager.enabled !== true || candidates.length === 0) {
+                return candidates;
+            }
+            const contextRecords = existingRecords
+                .filter((record) => record.status === "active")
+                .slice(-input.config.manager.maxContextRecords);
+            if (input.config.manager.strategy !== "model") {
+                return candidates;
+            }
+            if (!binding.langchainAgentParams?.model) {
+                return candidates;
+            }
+            const primaryModel = (() => {
+                if (!input.config.manager.modelRef) {
+                    return binding.langchainAgentParams.model;
+                }
+                const configured = input.workspace.models.get(resolveRefId(input.config.manager.modelRef));
+                return configured ? compileModel(configured) : binding.langchainAgentParams.model;
+            })();
+            return runModelMemoryManager({
+                workspace: input.workspace,
+                binding,
+                model: primaryModel,
+                candidates,
+                threadId,
+                runId,
+                recordedAt,
+                existingRecords: contextRecords,
+                modelResolver: input.modelResolver,
+            });
+        },
+    };
+}
+function fingerprintMessages(messages, scopes) {
+    const serialized = messages
+        .map((message) => `${message.role}\n${message.createdAt}\n${extractMessageText(message.content)}`)
+        .join("\n---\n");
+    return `${scopes.join(",")}::${serialized}`;
+}
+export class RuntimeMemoryFormationSync {
+    persistence;
+    config;
+    writer;
+    stateStore;
+    options;
+    pending = new Set();
+    syncChain = Promise.resolve();
+    name = "runtime-memory-formation-sync";
+    constructor(persistence, config, writer, runRoot, stateStore = new FileBackedStore(path.join(runRoot, config.background.stateStorePath)), options = {}) {
+        this.persistence = persistence;
+        this.config = config;
+        this.writer = writer;
+        this.stateStore = stateStore;
+        this.options = options;
+    }
+    shouldHandle(event) {
+        if (!this.config.background.enabled || !FORMATION_EVENT_TYPES.has(event.eventType)) {
+            return false;
+        }
+        if (event.eventType === "approval.resolved") {
+            return this.config.background.writeOnApprovalResolution;
+        }
+        return this.config.background.writeOnRunCompletion && event.payload.state === "completed";
+    }
+    async handleEvent(event) {
+        if (!this.shouldHandle(event)) {
+            return;
+        }
+        const trigger = event.eventType === "approval.resolved" ? "approval.resolved" : "run.completed";
+        const task = this.syncChain
+            .then(() => this.reflectRun(event.threadId, event.runId, trigger, event.timestamp))
+            .catch(() => {
+            // Fail open: reflection should not block runtime progress.
+        });
+        this.syncChain = task
+            .catch(() => {
+            // Fail open: reflection should not block runtime progress.
+        })
+            .finally(() => {
+            this.pending.delete(task);
+        });
+        this.pending.add(task);
+    }
+    async reflectRun(threadId, runId, trigger, recordedAt) {
+        const [thread, run, allMessages, approvals] = await Promise.all([
+            this.persistence.getSession(threadId),
+            this.persistence.getRun(runId),
+            this.persistence.listThreadMessages(threadId, this.config.background.maxMessagesPerRun),
+            this.persistence.getRunApprovals(threadId, runId),
+        ]);
+        if (!thread || !run) {
+            return;
+        }
+        const messages = allMessages.filter((message) => message.runId === runId);
+        if (messages.length === 0) {
+            return;
+        }
+        const fingerprint = fingerprintMessages(messages, this.config.background.scopes);
+        const namespace = ["memories", "formation", "threads", threadId, "runs"];
+        const cursor = await this.stateStore.get(namespace, runId);
+        const existing = cursor?.value;
+        if (existing?.fingerprint === fingerprint && existing.trigger === trigger) {
+            return;
+        }
+        const candidates = createBackgroundMemoryCandidates({
+            thread,
+            runId,
+            agentId: run.agentId ?? thread.agentId,
+            trigger,
+            recordedAt,
+            messages,
+            approvals,
+            scopes: this.config.background.scopes,
+        });
+        if (candidates.length === 0) {
+            return;
+        }
+        await this.writer({
+            candidates,
+            threadId,
+            runId,
+            agentId: run.agentId ?? thread.agentId,
+            userId: this.options.userId,
+            projectId: this.options.projectId,
+            recordedAt,
+        });
+        await this.stateStore.put(namespace, runId, {
+            fingerprint,
+            candidateCount: candidates.length,
+            syncedAt: new Date().toISOString(),
+            trigger,
+        });
+    }
+    async close() {
+        await Promise.allSettled(Array.from(this.pending));
+    }
+}

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

@@ -14,6 +14,7 @@ type PersistMemoryRecordsOptions = {
 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 getMemoryRecord(store: StoreLike, scope: MemoryScope, recordId: string): Promise<MemoryRecord | null>;
 export declare function persistStructuredMemoryRecords(options: PersistMemoryRecordsOptions): Promise<{
     records: MemoryRecord[];
     decisions: MemoryDecision[];

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

@@ -375,6 +375,15 @@ export async function listMemoryRecordsForScopes(store, scopes) {
     const all = await Promise.all(scopes.map((scope) => listStoredRecords(store, scope)));
     return all.flat();
 }
+export async function getMemoryRecord(store, scope, recordId) {
+    const entry = await store.get(buildScopeNamespace(scope), `${recordId}.json`);
+    const record = entry?.value;
+    if (typeof record !== "object" || !record || Array.isArray(record)) {
+        return null;
+    }
+    const candidate = record;
+    return typeof candidate.id === "string" && typeof candidate.content === "string" ? candidate : null;
+}
 export async function persistStructuredMemoryRecords(options) {
     const existingRecords = await listStoredRecords(options.store);
     const persistedRecords = [];

package/dist/runtime/harness/system/store.d.ts

@@ -49,4 +49,31 @@ export declare class FileBackedStore {
     delete(namespace: string[], key: string): Promise<void>;
     listNamespaces(options?: Parameters<InMemoryStore["listNamespaces"]>[0]): Promise<string[][]>;
 }
+export declare class SqliteBackedStore {
+    readonly filePath: string;
+    private readonly db;
+    constructor(filePath: string);
+    batch(operations: Array<Record<string, unknown>>): Promise<readonly unknown[]>;
+    get(namespace: string[], key: string): Promise<{
+        value: unknown;
+        key: string;
+        namespace: string[];
+        createdAt: Date;
+        updatedAt: Date;
+    } | null>;
+    private getSync;
+    search(namespacePrefix: string[]): Promise<Array<{
+        value: unknown;
+        key: string;
+        namespace: string[];
+        createdAt: Date;
+        updatedAt: Date;
+        score?: number;
+    }>>;
+    put(namespace: string[], key: string, value: Record<string, any>, _index?: false | string[]): Promise<void>;
+    private putSync;
+    delete(namespace: string[], key: string): Promise<void>;
+    private deleteSync;
+    listNamespaces(): Promise<string[][]>;
+}
 export declare function createInMemoryStore(): StoreLike;

package/dist/runtime/harness/system/store.js

@@ -1,6 +1,9 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdirSync } from "node:fs";
 import path from "node:path";
 import { InMemoryStore } from "@langchain/langgraph";
+import Database from "better-sqlite3";
+const NAMESPACE_SEPARATOR = "\u001f";
 function encodeValue(value) {
     if (value instanceof Date) {
         return {
@@ -50,6 +53,18 @@ function decodeValue(value) {
     }
     return value;
 }
+function serializeNamespace(namespace) {
+    return namespace.join(NAMESPACE_SEPARATOR);
+}
+function parseRow(row) {
+    return {
+        value: decodeValue(JSON.parse(row.value_json)),
+        key: row.key,
+        namespace: JSON.parse(row.namespace_json),
+        createdAt: new Date(row.created_at),
+        updatedAt: new Date(row.updated_at),
+    };
+}
 export class FileBackedStore {
     filePath;
     delegate = new InMemoryStore();
@@ -131,6 +146,87 @@ export class FileBackedStore {
         });
     }
 }
+export class SqliteBackedStore {
+    filePath;
+    db;
+    constructor(filePath) {
+        this.filePath = filePath;
+        mkdirSync(path.dirname(filePath), { recursive: true });
+        this.db = new Database(filePath);
+        this.db.pragma("journal_mode = WAL");
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS store_entries (
+        namespace TEXT NOT NULL,
+        namespace_json TEXT NOT NULL,
+        key TEXT NOT NULL,
+        value_json TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        PRIMARY KEY (namespace, key)
+      );
+      CREATE INDEX IF NOT EXISTS idx_store_entries_namespace ON store_entries(namespace);
+    `);
+    }
+    async batch(operations) {
+        const results = this.db.transaction((items) => items.map((operation) => {
+            const namespace = Array.isArray(operation.namespace) ? operation.namespace.filter((item) => typeof item === "string") : [];
+            const key = typeof operation.key === "string" ? operation.key : "";
+            if ("value" in operation) {
+                this.putSync(namespace, key, operation.value);
+                return undefined;
+            }
+            if (operation.delete === true) {
+                this.deleteSync(namespace, key);
+                return undefined;
+            }
+            return this.getSync(namespace, key);
+        }))(operations);
+        return results;
+    }
+    async get(namespace, key) {
+        return this.getSync(namespace, key);
+    }
+    getSync(namespace, key) {
+        const row = this.db.prepare(`SELECT namespace, namespace_json, key, value_json, created_at, updated_at
+       FROM store_entries
+       WHERE namespace = ? AND key = ?`).get(serializeNamespace(namespace), key);
+        return row ? parseRow(row) : null;
+    }
+    async search(namespacePrefix) {
+        const prefix = serializeNamespace(namespacePrefix);
+        const rows = this.db.prepare(`SELECT namespace, namespace_json, key, value_json, created_at, updated_at
+       FROM store_entries
+       WHERE namespace = ? OR namespace LIKE ?
+       ORDER BY namespace ASC, key ASC`).all(prefix, `${prefix}${NAMESPACE_SEPARATOR}%`);
+        return rows.map((row) => parseRow(row));
+    }
+    async put(namespace, key, value, _index) {
+        this.putSync(namespace, key, value);
+    }
+    putSync(namespace, key, value) {
+        const now = new Date().toISOString();
+        const serializedNamespace = serializeNamespace(namespace);
+        const encodedValue = JSON.stringify(encodeValue(value));
+        this.db.prepare(`INSERT INTO store_entries (namespace, namespace_json, key, value_json, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(namespace, key) DO UPDATE SET
+         namespace_json = excluded.namespace_json,
+         value_json = excluded.value_json,
+         updated_at = excluded.updated_at`).run(serializedNamespace, JSON.stringify(namespace), key, encodedValue, now, now);
+    }
+    async delete(namespace, key) {
+        this.deleteSync(namespace, key);
+    }
+    deleteSync(namespace, key) {
+        this.db.prepare(`DELETE FROM store_entries WHERE namespace = ? AND key = ?`).run(serializeNamespace(namespace), key);
+    }
+    async listNamespaces() {
+        const rows = this.db.prepare(`SELECT DISTINCT namespace_json
+       FROM store_entries
+       ORDER BY namespace ASC`).all();
+        return rows.map((row) => JSON.parse(row.namespace_json));
+    }
+}
 export function createInMemoryStore() {
     return new InMemoryStore();
 }

package/dist/runtime/harness.d.ts

@@ -29,6 +29,11 @@ export declare class AgentHarnessRuntime {
     private readonly unregisterRuntimeMemorySync;
     private readonly mem0IngestionSync;
     private readonly unregisterMem0IngestionSync;
+    private readonly mem0SemanticRecall;
+    private readonly runtimeMemoryFormationConfig;
+    private readonly runtimeMemoryManager;
+    private readonly runtimeMemoryFormationSync;
+    private readonly unregisterRuntimeMemoryFormationSync;
     private readonly resolvedRuntimeAdapterOptions;
     private readonly healthMonitor;
     private readonly recoveryConfig;
@@ -43,6 +48,7 @@ export declare class AgentHarnessRuntime {
     private closed;
     private readonly backgroundEventRuntime;
     private readonly runtimeEventOperations;
+    private resolveRuntimeMemoryVectorStore;
     private defaultRunRoot;
     private getDefaultRuntimeEntryAgentId;
     private resolveSelectedAgentId;
@@ -99,6 +105,14 @@ export declare class AgentHarnessRuntime {
     private resolveRecallScopes;
     private matchesRecallScope;
     private getMemoryScopeBoost;
+    private memoryFreshnessBoost;
+    private scoreStructuredRecord;
+    private normalizeMemoryDedupKey;
+    private inferMem0MemoryKind;
+    private inferMem0MemoryScope;
+    private createMem0MemoryRecord;
+    private rankRecallCandidates;
+    private rebuildRuntimeMemoryVectorIndex;
     private buildRuntimeMemoryContext;
     private persistRuntimeMemoryCandidates;
     private persistStructuredMemoryCandidates;