@botbotgo/agent-harness 0.0.154 → 0.0.155

package/README.md

@@ -291,6 +291,7 @@ If you want the shortest possible mental model:
 - structured output and multimodal content preservation in run results
 - MCP bridge support for agent-declared MCP servers
 - MCP server support for exposing harness tools outward
+- optional `mem0` semantic recall augmentation over canonical SQLite durable memory
 
 ### Runtime Strengths
 
@@ -666,8 +667,8 @@ kind: Stores
 spec:
   - kind: Store
     name: default
-    storeKind: FileStore
-    path: store.json
+    storeKind: SqliteStore
+    path: store.sqlite
   - kind: Checkpointer
     name: default
     checkpointerKind: MemorySaver
@@ -683,6 +684,12 @@ Use this singleton file for runtime-owned durable long-term memory defaults.
 
 Keep bootstrap context in `config/agent-context.md`. Keep resumable execution state in the checkpointer. Use `RuntimeMemory` for durable memory policy and retrieval defaults.
 
+`RuntimeMemory` also carries LangMem-style formation defaults:
+
+- `formation.hotPath` for immediate write-time capture
+- `formation.manager` for rule-driven or model-driven candidate normalization before persistence
+- `formation.background` for reflection after run completion or approval resolution
+
 ### `config/catalogs/backends.yaml`
 
 Use reusable DeepAgents backend presets so filesystem and `/memories/*` topology stays in YAML:

package/README.zh.md

@@ -360,6 +360,8 @@ const result = await run(runtime, {
 - `invocation.inputs`：结构化运行时输入
 - `invocation.attachments`：当前后端可解释的类附件负载
 
+可选地，runtime memory 还可以在 SQLite canonical durable memory 之上叠加 `mem0` 语义召回增强，用于更强的长期知识命中，而不改变正式知识记录的 contract。
+
 ### 写入与召回 durable runtime memory
 
 ```ts
@@ -634,8 +636,8 @@ kind: Stores
 spec:
   - kind: Store
     name: default
-    storeKind: FileStore
-    path: store.json
+    storeKind: SqliteStore
+    path: store.sqlite
   - kind: Checkpointer
     name: default
     checkpointerKind: MemorySaver
@@ -645,6 +647,18 @@ spec:
     path: checkpoints.sqlite
 ```
 
+### `config/runtime/runtime-memory.yaml`
+
+这个单例文件用于配置 runtime 持有的 durable long-term memory 默认值。
+
+把稳定启动上下文放在 `config/agent-context.md`，把可恢复执行状态留给 checkpointer，把长期记忆策略与检索默认值放在 `RuntimeMemory`。
+
+`RuntimeMemory` 也承载 LangMem 风格的 formation 默认值：
+
+- `formation.hotPath`：运行中的即时捕获
+- `formation.manager`：持久化前的规则式或模型式 candidate 归一化
+- `formation.background`：在 run 完成或 approval resolve 后做 reflection
+
 ### `config/catalogs/backends.yaml`
 
 可复用的 DeepAgents 后端预设，使文件系统与 `/memories/*` 拓扑保留在 YAML 中：

package/dist/config/catalogs/stores.yaml

@@ -6,9 +6,9 @@ spec:
   # agent-harness feature: reusable store preset for agent backends that need a durable key-value store.
   - kind: Store
     name: default
-    description: Default file-backed store preset for runtime-managed agent state.
-    storeKind: FileStore
-    path: store.json
+    description: Default sqlite-backed store preset for runtime-managed agent state and durable memory.
+    storeKind: SqliteStore
+    path: store.sqlite
 
   # agent-harness feature: reusable checkpointer preset for resumable execution state.
   - kind: Checkpointer

package/dist/config/catalogs/vector-stores.yaml

@@ -9,7 +9,7 @@ spec:
     # LangChain v1 Features
     # ====================
     # LangChain aligned feature: concrete vector store implementation.
-    # The built-in runtime currently supports `LibSQLVectorStore` for SQLite/libSQL-backed vector retrieval.
+    # The built-in runtime currently supports `LibSQLVectorStore`, `QdrantVectorStore`, and `LlamaIndexSimpleVectorStore`.
     storeKind: LibSQLVectorStore
     # LangChain aligned feature: libSQL connection URL.
     # Local SQLite files use the `file:` prefix.
@@ -23,3 +23,10 @@ spec:
     # ======================
     # Retrieval tools use this to resolve their default embeddings when indexing or querying this vector store.
     embeddingModelRef: embedding-model/default
+
+  - name: qdrant
+    storeKind: QdrantVectorStore
+    host: 127.0.0.1
+    port: 6333
+    collection: runtime_memory
+    embeddingModelRef: embedding-model/default

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

@@ -66,6 +66,23 @@ spec:
     writeOnApprovalResolution: true
     writeOnRunCompletion: true
 
+  # agent-harness feature: LangMem-style memory formation defaults for hot-path and background reflection.
+  formation:
+    hotPath:
+      enabled: true
+    manager:
+      enabled: true
+      strategy: rules
+      maxContextRecords: 12
+    background:
+      enabled: true
+      scopes:
+        - thread
+      stateStorePath: runtime-memory-formation-state.json
+      maxMessagesPerRun: 40
+      writeOnApprovalResolution: true
+      writeOnRunCompletion: true
+
   # agent-harness feature: optional thread snapshot projection for operational state and pending approvals.
   threadMemorySync:
     enabled: true

package/dist/contracts/workspace.d.ts

@@ -52,9 +52,12 @@ export type ParsedVectorStoreObject = {
     id: string;
     kind: string;
     url?: string;
+    host?: string;
+    port?: number;
     authToken?: string;
     table?: string;
     column?: string;
+    collection?: string;
     embeddingModelRef?: string;
     metadata?: Record<string, unknown>;
     sourcePath: string;
@@ -112,9 +115,12 @@ export type CompiledVectorStore = {
     id: string;
     kind: string;
     url?: string;
+    host?: string;
+    port?: number;
     authToken?: string;
     table?: string;
     column?: string;
+    collection?: string;
     embeddingModelRef?: string;
     runtimeValue: string;
 };

package/dist/init-project.js

@@ -138,6 +138,9 @@ metadata:
   name: default
 spec:
   enabled: true
+  store:
+    kind: SqliteStore
+    path: runtime-memory.sqlite
   namespaces:
     users: memories/users/{userId}
     projects: memories/projects/{projectId}
@@ -162,6 +165,21 @@ spec:
     backgroundConsolidation: true
     writeOnApprovalResolution: true
     writeOnRunCompletion: true
+  formation:
+    hotPath:
+      enabled: true
+    manager:
+      enabled: true
+      strategy: rules
+      maxContextRecords: 12
+    background:
+      enabled: true
+      scopes:
+        - thread
+      stateStorePath: runtime-memory-formation-state.json
+      maxMessagesPerRun: 40
+      writeOnApprovalResolution: true
+      writeOnRunCompletion: true
   threadMemorySync:
     enabled: true
   mem0:

package/dist/package-version.d.ts

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

package/dist/package-version.js

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

package/dist/runtime/harness/system/mem0-ingestion-sync.d.ts

@@ -1,4 +1,4 @@
-import { type Message as Mem0Message } from "mem0ai";
+import { type Memory as Mem0Memory, type Message as Mem0Message } from "mem0ai";
 import type { HarnessEvent, HarnessEventProjection } from "../../../contracts/types.js";
 import type { RuntimePersistence } from "../../../persistence/types.js";
 import { type StoreLike } from "./store.js";
@@ -19,8 +19,26 @@ export type ResolvedMem0Config = {
 };
 type Mem0ClientLike = {
     add(messages: Mem0Message[], options?: Record<string, unknown>): Promise<unknown>;
+    search(query: string, options?: Record<string, unknown>): Promise<Mem0Memory[]>;
+};
+export type Mem0ClientFactory = (config: ResolvedMem0Config) => Promise<Mem0ClientLike> | Mem0ClientLike;
+export type Mem0SearchInput = {
+    query: string;
+    topK: number;
+    agentId?: string;
+    threadId?: string;
+};
+export type Mem0SearchResult = {
+    id: string;
+    memory: string;
+    score: number;
+    categories: string[];
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+    agentId?: string;
+    runId?: string;
 };
-type Mem0ClientFactory = (config: ResolvedMem0Config) => Promise<Mem0ClientLike> | Mem0ClientLike;
 export declare function readMem0RuntimeConfig(runtimeMemory: Record<string, unknown> | undefined, workspaceRoot: string): ResolvedMem0Config | undefined;
 export declare class Mem0IngestionSync implements HarnessEventProjection {
     private readonly persistence;
@@ -39,4 +57,12 @@ export declare class Mem0IngestionSync implements HarnessEventProjection {
     private syncRun;
     close(): Promise<void>;
 }
+export declare class Mem0SemanticRecall {
+    private readonly config;
+    private readonly clientFactory;
+    private clientPromise;
+    constructor(config: ResolvedMem0Config, clientFactory?: Mem0ClientFactory);
+    private getClient;
+    search(input: Mem0SearchInput): Promise<Mem0SearchResult[]>;
+}
 export {};

package/dist/runtime/harness/system/mem0-ingestion-sync.js

@@ -69,7 +69,10 @@ export function readMem0RuntimeConfig(runtimeMemory, workspaceRoot) {
     };
 }
 async function createDefaultMem0Client(config) {
-    const apiKey = process.env[config.apiKeyEnv];
+    const apiKey = process.env[config.apiKeyEnv]?.trim();
+    if (!apiKey && config.host) {
+        return createSelfHostedMem0Client(config);
+    }
     if (!apiKey) {
         throw new Error(`runtimeMemory.mem0 is enabled but environment variable ${config.apiKeyEnv} is not set`);
     }
@@ -82,6 +85,47 @@ async function createDefaultMem0Client(config) {
         ...(config.projectId ? { projectId: config.projectId } : {}),
     });
 }
+function normalizeMem0Host(host) {
+    return host.replace(/\/+$/, "");
+}
+async function selfHostedMem0Request(config, pathname, options = {}) {
+    if (!config.host) {
+        throw new Error("Self-hosted mem0 client requires runtimeMemory.mem0.host.");
+    }
+    const response = await fetch(`${normalizeMem0Host(config.host)}${pathname}`, {
+        method: options.method ?? "GET",
+        headers: {
+            "Content-Type": "application/json",
+        },
+        ...(options.body ? { body: JSON.stringify(options.body) } : {}),
+    });
+    if (!response.ok) {
+        throw new Error(`Self-hosted mem0 request failed: ${response.status} ${response.statusText}`);
+    }
+    return response.json();
+}
+function createSelfHostedMem0Client(config) {
+    return {
+        async add(messages, options = {}) {
+            return selfHostedMem0Request(config, "/v1/memories/", {
+                method: "POST",
+                body: {
+                    messages,
+                    ...options,
+                },
+            });
+        },
+        async search(query, options = {}) {
+            return selfHostedMem0Request(config, "/v1/memories/search/", {
+                method: "POST",
+                body: {
+                    query,
+                    ...options,
+                },
+            });
+        },
+    };
+}
 export class Mem0IngestionSync {
     persistence;
     config;
@@ -179,3 +223,70 @@ export class Mem0IngestionSync {
         await Promise.allSettled(Array.from(this.pending));
     }
 }
+function toIsoString(value) {
+    if (value instanceof Date && !Number.isNaN(value.getTime())) {
+        return value.toISOString();
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = new Date(value);
+        return Number.isNaN(parsed.getTime()) ? undefined : parsed.toISOString();
+    }
+    return undefined;
+}
+export class Mem0SemanticRecall {
+    config;
+    clientFactory;
+    clientPromise = null;
+    constructor(config, clientFactory = createDefaultMem0Client) {
+        this.config = config;
+        this.clientFactory = clientFactory;
+    }
+    async getClient() {
+        if (!this.clientPromise) {
+            this.clientPromise = Promise.resolve(this.clientFactory(this.config));
+        }
+        return this.clientPromise;
+    }
+    async search(input) {
+        if (input.query.trim().length === 0 || input.topK <= 0) {
+            return [];
+        }
+        const client = await this.getClient();
+        const records = await client.search(input.query, {
+            top_k: input.topK,
+            limit: input.topK,
+            app_id: this.config.appId,
+            ...(input.agentId ? { agent_id: input.agentId } : {}),
+            ...(input.threadId && this.config.userIdPrefix ? { user_id: `${this.config.userIdPrefix}${input.threadId}` } : {}),
+        });
+        return records
+            .map((record) => {
+            const memory = typeof record.memory === "string" && record.memory.trim().length > 0
+                ? record.memory.trim()
+                : typeof record.data?.memory === "string" && record.data.memory.trim().length > 0
+                    ? record.data.memory.trim()
+                    : "";
+            if (!memory) {
+                return null;
+            }
+            const createdAt = toIsoString(record.created_at) ?? new Date(0).toISOString();
+            const updatedAt = toIsoString(record.updated_at) ?? createdAt;
+            return {
+                id: record.id,
+                memory,
+                score: typeof record.score === "number" && Number.isFinite(record.score) ? record.score : 0,
+                categories: Array.isArray(record.categories)
+                    ? record.categories.filter((item) => typeof item === "string" && item.trim().length > 0)
+                    : [],
+                metadata: typeof record.metadata === "object" && record.metadata && !Array.isArray(record.metadata)
+                    ? { ...record.metadata }
+                    : {},
+                createdAt,
+                updatedAt,
+                agentId: typeof record.agent_id === "string" && record.agent_id.trim().length > 0 ? record.agent_id : undefined,
+                runId: typeof record.run_id === "string" && record.run_id.trim().length > 0 ? record.run_id : undefined,
+            };
+        })
+            .filter((record) => record !== null);
+    }
+}

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

@@ -0,0 +1,90 @@
+import type { CompiledAgentBinding, CompiledModel, HarnessEvent, HarnessEventProjection, InternalApprovalRecord, MemoryCandidate, MemoryRecord, MemoryScope, ThreadSummary, TranscriptMessage, WorkspaceBundle } from "../../../contracts/types.js";
+import type { RuntimePersistence } from "../../../persistence/types.js";
+import { type StoreLike } from "./store.js";
+export type ResolvedRuntimeMemoryFormationConfig = {
+    enabled: true;
+    hotPath: {
+        enabled: boolean;
+    };
+    manager: {
+        enabled: boolean;
+        strategy: "rules" | "model";
+        modelRef?: string;
+        maxContextRecords: number;
+    };
+    background: {
+        enabled: boolean;
+        maxMessagesPerRun: number;
+        scopes: MemoryScope[];
+        stateStorePath: string;
+        writeOnApprovalResolution: boolean;
+        writeOnRunCompletion: boolean;
+    };
+};
+type RuntimeMemoryFormationWriter = (input: {
+    candidates: MemoryCandidate[];
+    threadId: string;
+    runId: string;
+    agentId: string;
+    userId?: string;
+    projectId?: string;
+    recordedAt: string;
+}) => Promise<void>;
+type RuntimeMemoryFormationOptions = {
+    userId?: string;
+    projectId?: string;
+};
+type RuntimeMemoryManagerLike = {
+    transform(input: {
+        candidates: MemoryCandidate[];
+        binding: CompiledAgentBinding;
+        threadId: string;
+        runId: string;
+        recordedAt: string;
+        existingRecords: MemoryRecord[];
+    }): Promise<MemoryCandidate[]>;
+};
+export declare function readRuntimeMemoryFormationConfig(runtimeMemory: Record<string, unknown> | undefined, workspaceRoot: string): ResolvedRuntimeMemoryFormationConfig | undefined;
+export declare function createBackgroundMemoryCandidates(input: {
+    thread: ThreadSummary;
+    runId: string;
+    agentId: string;
+    trigger: "approval.resolved" | "run.completed";
+    recordedAt: string;
+    messages: TranscriptMessage[];
+    approvals: InternalApprovalRecord[];
+    scopes: MemoryScope[];
+}): MemoryCandidate[];
+export declare function runModelMemoryManager(input: {
+    workspace: WorkspaceBundle;
+    binding: CompiledAgentBinding;
+    model: CompiledModel;
+    candidates: MemoryCandidate[];
+    threadId: string;
+    runId: string;
+    recordedAt: string;
+    existingRecords: MemoryRecord[];
+    modelResolver?: (modelId: string) => unknown;
+}): Promise<MemoryCandidate[]>;
+export declare function createRuntimeMemoryManager(input: {
+    workspace: WorkspaceBundle;
+    binding: CompiledAgentBinding;
+    config: ResolvedRuntimeMemoryFormationConfig;
+    modelResolver?: (modelId: string) => unknown;
+}): RuntimeMemoryManagerLike;
+export declare class RuntimeMemoryFormationSync implements HarnessEventProjection {
+    private readonly persistence;
+    private readonly config;
+    private readonly writer;
+    private readonly stateStore;
+    private readonly options;
+    private readonly pending;
+    private syncChain;
+    readonly name = "runtime-memory-formation-sync";
+    constructor(persistence: RuntimePersistence, config: ResolvedRuntimeMemoryFormationConfig, writer: RuntimeMemoryFormationWriter, runRoot: string, stateStore?: StoreLike, options?: RuntimeMemoryFormationOptions);
+    shouldHandle(event: HarnessEvent): boolean;
+    handleEvent(event: HarnessEvent): Promise<void>;
+    private reflectRun;
+    close(): Promise<void>;
+}
+export {};