@botbotgo/agent-harness 0.0.154 → 0.0.156

package/README.md

@@ -118,7 +118,7 @@ That means:
 
 The runtime provides:
 
-- `createAgentHarness(workspaceRoot)`, `run(...)`, `memorize(...)`, `recall(...)`, `resolveApproval(...)`, `subscribe(...)`, inspection methods, and `stop(...)`
+- `createAgentHarness(workspaceRoot)`, `run(...)`, `memorize(...)`, `recall(...)`, `listMemories(...)`, `updateMemory(...)`, `removeMemory(...)`, `resolveApproval(...)`, `subscribe(...)`, inspection methods, and `stop(...)`
 - YAML-defined workspace assembly for routing, models, tools, stores, backends, MCP, recovery, and maintenance
 - backend-adapted execution with current LangChain v1 and DeepAgents adapters
 - local `resources/tools/` `tool({...})` modules and `resources/skills/` discovery
@@ -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
 
@@ -413,10 +414,13 @@ const recalled = await recall(runtime, {
 });
 ```
 
-Use `memorize(...)` and `recall(...)` when an application needs a stable public runtime memory surface without importing internal `runtime/harness/system/*` modules.
+Use `memorize(...)`, `recall(...)`, `listMemories(...)`, `updateMemory(...)`, and `removeMemory(...)` when an application needs a stable public runtime memory surface without importing internal `runtime/harness/system/*` modules.
 
 - `memorize(...)` returns stable `MemoryRecord` and `MemoryDecision` results while leaving merge, review, archive, and storage layout runtime-managed
 - `recall(...)` returns ranked `MemoryRecord` items filtered by runtime memory scope and kind
+- `listMemories(...)` returns stable `MemoryRecord` items for inspection and admin workflows, defaulting to `active` records unless status filters are provided
+- `updateMemory(...)` edits one durable memory record by `memoryId` without exposing internal store namespaces
+- `removeMemory(...)` deletes one durable memory record by `memoryId` and rebuilds runtime-managed projections
 - app-specific knowledge taxonomy, review UI, and admin surfaces still belong in the application layer
 
 ### Let The Runtime Route
@@ -466,6 +470,7 @@ The runtime event stream includes:
 
 ```ts
 import {
+  deleteSession,
   getSession,
   getApproval,
   listSessions,
@@ -484,6 +489,10 @@ if (approval) {
     decision: "approve",
   });
 }
+
+if (session && session.currentState === "completed") {
+  await deleteSession(runtime, session.sessionId);
+}
 ```
 
 These methods return runtime-facing records, not raw checkpoint or backend objects.
@@ -547,6 +556,13 @@ Core workspace files:
 - `resources/tools/`
 - `resources/skills/`
 
+Discovery rules:
+
+- every YAML document under `config/**` is discovered recursively; filenames and subfolders are organizational only
+- YAML object semantics come from `kind`, `metadata.name` or `id`, and object content rather than the file path
+- local tools are auto-discovered from `resources/tools/**/*.js|*.mjs|*.cjs` when they export `tool({...})`
+- skills are auto-discovered from `resources/skills/**/SKILL.md`
+
 Workspace-local tool modules in `resources/tools/` should be exported with `tool({...})`.
 Any other local module shape is not supported, and unsupported shapes are rejected at load time.
 
@@ -562,7 +578,7 @@ There are three main configuration layers:
 
 - runtime policy in `config/runtime/workspace.yaml`
 - reusable object catalogs in `config/catalogs/*.yaml`
-- agent assembly in `config/agents/*.yaml`
+- agent assembly in `config/**/*.yaml`
 
 ### Backend Guidance
 
@@ -632,7 +648,7 @@ Use this file for shared bootstrap memory loaded at agent construction time.
 
 Keep stable project context here. Treat it as startup context, not mutable long-term memory.
 
-### `config/catalogs/models.yaml`
+### Models Catalogs In `config/**`
 
 Use named chat-model presets:
 
@@ -648,7 +664,9 @@ spec:
 
 These load as `model/default`.
 
-### `config/catalogs/embedding-models.yaml`
+You can place `kind: Models` catalogs anywhere under `config/`; `config/catalogs/models.yaml` is only the recommended layout.
+
+### Embedding Model Catalogs In `config/**`
 
 Use named embedding-model presets for retrieval-oriented tools.
 
@@ -666,8 +684,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 +701,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:
@@ -733,10 +757,12 @@ spec:
 
 `spec[].kind` can be omitted here; catalog entries default to `McpServer`.
 
-### `config/agents/*.yaml`
+### Agents In `config/**`
 
 Agents always use `kind: Agent` plus `spec.backend`.
 
+Agent YAML can live anywhere under `config/`; `config/agents/*.yaml` is the recommended layout, not a loader requirement.
+
 Use two sections:
 
 - `spec.runtime` for harness-owned runtime placement such as `spec.runtime.runRoot`

package/README.zh.md

@@ -118,7 +118,7 @@ AI 让 agent 逻辑、工具调用和工作流代码更容易生成，真正更
 
 运行时提供：
 
-- `createAgentHarness(workspaceRoot)`、`run(...)`、`memorize(...)`、`recall(...)`、`resolveApproval(...)`、`subscribe(...)`、各类查询方法，以及 `stop(...)`
+- `createAgentHarness(workspaceRoot)`、`run(...)`、`memorize(...)`、`recall(...)`、`listMemories(...)`、`updateMemory(...)`、`removeMemory(...)`、`resolveApproval(...)`、`subscribe(...)`、各类查询方法，以及 `stop(...)`
 - 以 YAML 描述的工作区装配：路由、模型、工具、存储、后端、MCP、恢复与维护等
 - 通过适配器对接当前的 LangChain v1 与 DeepAgents 执行
 - 本地 `resources/tools/` 中 `tool({...})` 工具模块与 `resources/skills/` 的发现
@@ -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
@@ -384,10 +386,13 @@ const recalled = await recall(runtime, {
 });
 ```
 
-当应用需要稳定的公开 runtime memory 接口，而不想依赖内部 `runtime/harness/system/*` 模块时，使用 `memorize(...)` 与 `recall(...)`。
+当应用需要稳定的公开 runtime memory 接口，而不想依赖内部 `runtime/harness/system/*` 模块时，使用 `memorize(...)`、`recall(...)`、`listMemories(...)`、`updateMemory(...)` 与 `removeMemory(...)`。
 
 - `memorize(...)` 返回稳定的 `MemoryRecord` 与 `MemoryDecision` 结果，而 merge、review、archive 与存储布局仍由 runtime 内部托管
 - `recall(...)` 返回按相关性排序、并按 scope / kind 过滤后的 `MemoryRecord`
+- `listMemories(...)` 返回稳定的 `MemoryRecord`，用于 inspection / admin 场景；如果不传 status 过滤器，默认只返回 `active`
+- `updateMemory(...)` 通过 `memoryId` 更新单条 durable memory，而不暴露内部 store namespace
+- `removeMemory(...)` 通过 `memoryId` 删除单条 durable memory，并重建运行时托管的 projection
 - 业务知识分类、review UI 与管理后台仍应留在应用层
 
 ### 由运行时路由
@@ -437,6 +442,7 @@ const result = await run(runtime, {
 
 ```ts
 import {
+  deleteSession,
   getApproval,
   getSession,
   listApprovals,
@@ -455,6 +461,10 @@ if (approval) {
     decision: "approve",
   });
 }
+
+if (session && session.currentState === "completed") {
+  await deleteSession(runtime, session.sessionId);
+}
 ```
 
 这些方法返回面向运行时的记录，而非原始 checkpoint 或后端对象。
@@ -518,6 +528,13 @@ await stop(runtime);
 - `resources/tools/`
 - `resources/skills/`
 
+发现规则：
+
+- `config/**` 下的所有 YAML 文档都会被递归发现；文件名与子目录只用于组织，不参与语义
+- YAML 对象语义由 `kind`、`metadata.name` 或 `id` 以及对象内容决定，而不是由文件路径决定
+- 本地工具会从 `resources/tools/**/*.js|*.mjs|*.cjs` 中自动发现，前提是模块导出 `tool({...})`
+- skills 会从 `resources/skills/**/SKILL.md` 自动发现
+
 `resources/tools/` 下的工作区本地工具模块应统一用 `tool({...})` 导出。
 不支持历史/兼容写法，任何不带该导出形式的工具模块都会在工作区加载时被拒绝。
 
@@ -527,7 +544,7 @@ await stop(runtime);
 - agent 再按名字白名单选择 tools 与 skills
 - `config/runtime/workspace.yaml` 中的运行时策略
 - `config/catalogs/*.yaml` 中的可复用对象目录
-- `config/agents/*.yaml` 中的 agent 装配
+- `config/**/*.yaml` 中的 agent 装配
 
 ### Backend 选择建议
 
@@ -600,7 +617,7 @@ spec:
 
 在此放置稳定的项目上下文；视为启动上下文，而非可变长期记忆。
 
-### `config/catalogs/models.yaml`
+### `config/**` 下的 Models Catalog
 
 命名聊天模型预设：
 
@@ -616,7 +633,9 @@ spec:
 
 加载为 `model/default`。
 
-### `config/catalogs/embedding-models.yaml`
+`kind: Models` catalog 可以放在 `config/` 下任意位置；`config/catalogs/models.yaml` 只是推荐布局。
+
+### `config/**` 下的 Embedding Model Catalog
 
 面向检索类工具的命名嵌入模型预设。
 
@@ -634,8 +653,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 +664,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 中：
@@ -693,10 +724,12 @@ spec:
 
 这里可以省略 `spec[].kind`；catalog 项会默认按 `McpServer` 处理。
 
-### `config/agents/*.yaml`
+### `config/**` 下的 Agent YAML
 
 Agent 始终使用 `kind: Agent` 以及 `spec.backend`。
 
+Agent YAML 可以放在 `config/` 下任意位置；`config/agents/*.yaml` 是推荐布局，不是 loader 的硬性要求。
+
 两个区块：
 
 - `spec.runtime`：harness 侧运行时放置，例如 `spec.runtime.runRoot`

package/dist/api.d.ts

@@ -1,11 +1,11 @@
-import type { CancelOptions, InvocationEnvelope, MemorizeInput, MemorizeResult, MessageContent, RecallInput, RecallResult, RequestRecord, RequestSummary, ResumeOptions, RunDecisionOptions, RunResult, RunStartOptions, RuntimeHealthSnapshot, RuntimeAdapterOptions, SessionRecord, SessionSummary, WorkspaceLoadOptions } from "./contracts/types.js";
+import type { CancelOptions, InvocationEnvelope, ListMemoriesInput, ListMemoriesResult, MemoryRecord, MemorizeInput, MemorizeResult, MessageContent, RecallInput, RecallResult, RemoveMemoryInput, RequestRecord, RequestSummary, ResumeOptions, RunDecisionOptions, RunResult, RunStartOptions, RuntimeHealthSnapshot, RuntimeAdapterOptions, SessionRecord, SessionSummary, UpdateMemoryInput, WorkspaceLoadOptions } from "./contracts/types.js";
 import { AgentHarnessRuntime } from "./runtime/harness.js";
 import type { InventoryAgentRecord, InventorySkillRecord } from "./runtime/harness/system/inventory.js";
 import type { RequirementAssessmentOptions } from "./runtime/harness/system/skill-requirements.js";
 import type { ToolMcpServerOptions } from "./mcp.js";
 export { AgentHarnessRuntime } from "./runtime/harness.js";
 export { createUpstreamTimelineReducer } from "./upstream-events.js";
-export type { MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, RecallInput, RecallResult, } from "./contracts/types.js";
+export type { ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, RecallInput, RecallResult, RemoveMemoryInput, UpdateMemoryInput, } from "./contracts/types.js";
 type PublicApprovalRecord = {
     approvalId: string;
     pendingActionId: string;
@@ -57,6 +57,9 @@ export declare function normalizeUserChatInput(input: UserChatInput, options?: N
 export declare function run(runtime: AgentHarnessRuntime, options: PublicRunOptions): Promise<PublicRunResult>;
 export declare function memorize(runtime: AgentHarnessRuntime, input: MemorizeInput): Promise<MemorizeResult>;
 export declare function recall(runtime: AgentHarnessRuntime, input: RecallInput): Promise<RecallResult>;
+export declare function listMemories(runtime: AgentHarnessRuntime, input?: ListMemoriesInput): Promise<ListMemoriesResult>;
+export declare function updateMemory(runtime: AgentHarnessRuntime, input: UpdateMemoryInput): Promise<MemoryRecord>;
+export declare function removeMemory(runtime: AgentHarnessRuntime, input: RemoveMemoryInput): Promise<MemoryRecord>;
 export declare function subscribe(runtime: AgentHarnessRuntime, listener: Parameters<AgentHarnessRuntime["subscribe"]>[0]): () => void;
 export declare function listSessions(runtime: AgentHarnessRuntime, filter?: Parameters<AgentHarnessRuntime["listThreads"]>[0]): Promise<SessionSummary[]>;
 export declare function listRequests(runtime: AgentHarnessRuntime, filter?: {

package/dist/api.js

@@ -134,6 +134,15 @@ export async function memorize(runtime, input) {
 export async function recall(runtime, input) {
     return runtime.recall(input);
 }
+export async function listMemories(runtime, input = {}) {
+    return runtime.listMemories(input);
+}
+export async function updateMemory(runtime, input) {
+    return runtime.updateMemory(input);
+}
+export async function removeMemory(runtime, input) {
+    return runtime.removeMemory(input);
+}
 export function subscribe(runtime, listener) {
     return runtime.subscribe(listener);
 }

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/runtime.d.ts

@@ -195,6 +195,37 @@ export type RecallInput = {
 export type RecallResult = {
     items: MemoryRecord[];
 };
+export type ListMemoriesInput = {
+    scopes?: MemoryScope[];
+    kinds?: MemoryKind[];
+    status?: MemoryRecordStatus[];
+    threadId?: string;
+    agentId?: string;
+    workspaceId?: string;
+    userId?: string;
+    projectId?: string;
+    limit?: number;
+};
+export type ListMemoriesResult = {
+    items: MemoryRecord[];
+};
+export type UpdateMemoryInput = {
+    memoryId: string;
+    content?: string;
+    summary?: string;
+    status?: MemoryRecordStatus;
+    confidence?: number;
+    expiresAt?: string | null;
+    sourceType?: string;
+    sourceRefs?: string[];
+    tags?: string[];
+    observedAt?: string;
+    lastConfirmedAt?: string;
+    provenance?: Record<string, unknown>;
+};
+export type RemoveMemoryInput = {
+    memoryId: string;
+};
 /**
  * Operator-facing projection of tool execution policy already compiled into a binding.
  * This summarizes existing timeout, retry, validation, and retry-safety hints without

package/dist/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/index.d.ts

@@ -1,5 +1,5 @@
-export { AgentHarnessRuntime, cancelRun, createAgentHarness, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, getAgent, getApproval, getRequest, getHealth, getSession, listAgentSkills, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
-export type { MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, NormalizeUserChatInputOptions, RecallInput, RecallResult, UserChatInput, UserChatMessage, } from "./api.js";
+export { AgentHarnessRuntime, cancelRun, createAgentHarness, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, getAgent, getApproval, getRequest, getHealth, listMemories, getSession, listAgentSkills, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveToolsOverStdio, subscribe, stop, updateMemory, } from "./api.js";
+export type { ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, NormalizeUserChatInputOptions, RecallInput, RecallResult, RemoveMemoryInput, UpdateMemoryInput, UserChatInput, UserChatMessage, } from "./api.js";
 export type { ToolMcpServerOptions } from "./mcp.js";
 export { tool } from "./tools.js";
 export type { UpstreamTimelineProjection, UpstreamTimelineReducer } from "./upstream-events.js";

package/dist/index.js

@@ -1,2 +1,2 @@
-export { AgentHarnessRuntime, cancelRun, createAgentHarness, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, getAgent, getApproval, getRequest, getHealth, getSession, listAgentSkills, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, resolveApproval, run, serveToolsOverStdio, subscribe, stop, } from "./api.js";
+export { AgentHarnessRuntime, cancelRun, createAgentHarness, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, getAgent, getApproval, getRequest, getHealth, listMemories, getSession, listAgentSkills, listApprovals, listRequests, listSessions, memorize, normalizeUserChatInput, recall, removeMemory, resolveApproval, run, serveToolsOverStdio, subscribe, stop, updateMemory, } from "./api.js";
 export { tool } from "./tools.js";

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.155";

package/dist/package-version.js

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

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);
+    }
+}