Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
fix(mcp): report remember as submitted for extraction, not stored (#5678)
t0saki2d9114dbf77d
diff --git a/docs/en/agent-integrations/16-capability-reference.md b/docs/en/agent-integrations/16-capability-reference.mdindex a24812b22..6d0242c06 100644--- a/docs/en/agent-integrations/16-capability-reference.md+++ b/docs/en/agent-integrations/16-capability-reference.md@@ -87,7 +87,7 @@ Every MCP-based integration exposes the same server-defined tools and keeps no cBehavior to know before relying on a tool:-- **`remember`** creates a one-shot session named `mcp-store-<id>`, adds the messages, and commits it at once. It is the only MCP tool that commits. No MCP tool commits the agent's current conversation; that is the job of the automatic hooks.+- **`remember`** creates a one-shot session named `mcp-store-<id>`, adds the messages, and commits it at once. It is the only MCP tool that commits. It returns as soon as the commit is accepted, with the `task_id` of the background extraction; extraction then decides which memories to create or update. No MCP tool commits the agent's current conversation; that is the job of the automatic hooks.- **`find` and `search`**: `find` is a fast search without session context. `search` can take a `session_id` and run intent analysis (`retrieval.enable_intent`, on by default). `find` with `context_type="skill"` returns one hit per skill package, pointing at its `SKILL.md`, from both the user's and the account's skills.- **`write` and `edit`** can write only under `viking://resources`, `viking://user`, and `viking://agent`. A new file must end in `.md`, `.txt`, `.json`, `.yaml`, `.yml`, `.toml`, `.py`, `.js`, or `.ts`. The user's `skills/`, `peers/`, `privacy/`, and `sessions/` directories are read-only. A write under `viking://agent/skills` is accepted but skips skill installation, so use `add_skill` for skills.- **`add_resource` with a local path** returns a signed upload URL (valid for 600 seconds by default). The model must upload the file to it, for example with a shell command; ingestion then starts on its own. Remote URLs are ingested directly.diff --git a/docs/en/guides/06-mcp-integration.md b/docs/en/guides/06-mcp-integration.mdindex 899154ec9..ff627796e 100644--- a/docs/en/guides/06-mcp-integration.md+++ b/docs/en/guides/06-mcp-integration.md@@ -131,7 +131,7 @@ The built-in MCP tools are listed below. Use the connected server's `tools/list`| `read` | Read one or more `viking://` URIs. PNG, JPEG, GIF, and WebP return native MCP image content; WAV, MP3, FLAC, OGG, and M4A return native audio content. Video is not supported because MCP has no standard video content block | `uris` (single string or array), `offset`, `limit` (text lines) || `list` | List entries under a `viking://` directory | `uri`, `recursive`, `offset`, `limit`, `sort_by`, `sort_order` (optional) || `tree` | Show the recursive directory tree under a `viking://` URI, indented by depth — use when you need a full picture of the file tree (prefer `list` for a single level, `glob` for filename patterns) | `uri` (optional), `level_limit` (default 3), `node_limit` (default 1000), `offset`, `limit`, `include_abstract` (optional — also show each directory's summary; for a skill directory that is its name and description) |-| `remember` | Store messages into long-term memory (triggers extraction) | `messages` (list of `{role, content}`) |+| `remember` | Submit messages for long-term memory extraction; returns the background extraction `task_id` right away | `messages` (list of `{role, content}`) || `write` | Write text to a `viking://` file (create/overwrite/append). Parent directories are created automatically; use `read` first to see current content before overwriting, and prefer `edit` for changing part of an existing file. Skill packages are not maintained this way: the caller's own `skills/` subtree is refused, and a write under `viking://agent/skills` produces a plain file that skips skill installation — use `add_skill` | `uri`, `content`, `mode` (optional: `replace` default — overwrites or creates if missing; `append` — appends or creates if missing; `create` — fails if it exists), `wait` (optional, block until re-indexed), `timeout` (optional), `acl` (optional) || `edit` | Replace an exact string with new text in an existing `viking://` file — for targeted changes instead of a full rewrite. The file is left unchanged if `old_string` is not found, or matches multiple times while `replace_all` is false. Editing a file inside a skill package does not re-run skill installation — use `add_skill` | `uri`, `old_string`, `new_string`, `replace_all` (optional), `wait` (optional, block until re-indexed), `timeout` (optional) || `add_resource` | Add a local file or URL as a resource (local files trigger a progressive upload flow) | `path`, `temp_file_id` (optional), `description` (optional), `watch_interval` (optional, minutes — auto-refresh cadence for remote URLs), `processing_mode` (optional: `semantic_and_vectors` default, or `vectors_only` to skip VLM semantic understanding and only vectorize current files), `to` (optional, target `viking://resources/...` URI; if omitted when `watch_interval > 0`, the watch auto-binds to the resource's created URI), `args` (optional parser-specific options, including `{"parse_mode":"no_split"}` to parse each source document into one Markdown body, `{"feishu_access_token":"u-..."}` for one-time Feishu user-token imports, or access/refresh tokens plus an optional `feishu_app_id` / `feishu_app_secret` pair for Feishu user-token watches), `acl` (optional) |diff --git a/docs/zh/agent-integrations/16-capability-reference.md b/docs/zh/agent-integrations/16-capability-reference.mdindex 010b8f781..1405b48ba 100644--- a/docs/zh/agent-integrations/16-capability-reference.md+++ b/docs/zh/agent-integrations/16-capability-reference.md@@ -87,7 +87,7 @@使用前需要了解的行为:-- **`remember`** 会创建一个名为 `mcp-store-<id>` 的一次性会话,写入消息后立即提交。它是唯一会提交的 MCP 工具。没有任何 MCP 工具会提交 Agent 当前的对话,那是自动 hook 的工作。+- **`remember`** 会创建一个名为 `mcp-store-<id>` 的一次性会话,写入消息后立即提交。它是唯一会提交的 MCP 工具。提交被接受后它立刻返回,结果里带后台记忆提取任务的 `task_id`;提取过程再决定新建或更新哪些记忆。没有任何 MCP 工具会提交 Agent 当前的对话,那是自动 hook 的工作。- **`find` 与 `search`**:`find` 是不带会话上下文的快速检索。`search` 可以传 `session_id`,并做意图分析(`retrieval.enable_intent`,默认开启)。`find` 传 `context_type="skill"` 时,每个 skill 包只返回一条命中,指向它的 `SKILL.md`,范围包括用户自己的和账户共享的 skill。- **`write` 与 `edit`** 只能写 `viking://resources`、`viking://user` 和 `viking://agent`。新文件的扩展名必须是 `.md`、`.txt`、`.json`、`.yaml`、`.yml`、`.toml`、`.py`、`.js` 或 `.ts`。用户的 `skills/`、`peers/`、`privacy/` 和 `sessions/` 目录只读。写入 `viking://agent/skills` 不会被拒绝,但会跳过 skill 安装流程,skill 请用 `add_skill`。- **`add_resource` 传本地路径**时返回一个签名上传 URL(默认 600 秒有效)。模型需要把文件上传到这个 URL,例如用一条 shell 命令;上传后自动开始入库。远程 URL 会直接入库。diff --git a/docs/zh/guides/06-mcp-integration.md b/docs/zh/guides/06-mcp-integration.mdindex a3cfc7fcf..ef51464b8 100644--- a/docs/zh/guides/06-mcp-integration.md+++ b/docs/zh/guides/06-mcp-integration.md@@ -127,7 +127,7 @@ claude mcp add --transport http openviking \| `read` | 读取一个或多个 `viking://` URI 的内容。PNG、JPEG、GIF、WebP 返回 MCP 原生图片内容;WAV、MP3、FLAC、OGG、M4A 返回原生音频内容。MCP 没有标准视频内容块,因此暂不支持视频 | `uris`(单个字符串或数组), `offset`, `limit`(文本行数) || `list` | 列出 `viking://` 目录下的条目 | `uri`, `recursive`(可选) || `tree` | 以缩进形式展示 `viking://` URI 下的递归目录树——当需要全面了解文件树结构时使用(单层列表用 `list`,按文件名查找用 `glob`) | `uri`(可选), `level_limit`(默认 3), `node_limit`(默认 1000), `include_abstract`(可选——同时展示每个目录的摘要;skill 目录的摘要就是它的名字和描述) |-| `remember` | 存储消息到长期记忆(触发记忆提取) | `messages`(`{role, content}` 列表) |+| `remember` | 提交消息做长期记忆提取;立即返回后台任务的 `task_id`,提取结果可能什么都不保留 | `messages`(`{role, content}` 列表) || `write` | 向 `viking://` 文件写入文本(创建/覆盖/追加)。自动创建缺失的父目录;覆盖前请先用 `read` 查看当前内容;只改文件局部时优先用 `edit`。skill 包不要用它维护:调用方自己的 `skills/` 子树会被拒绝,写 `viking://agent/skills` 则生成绕过安装流程的普通文件,请改用 `add_skill` | `uri`, `content`, `mode`(可选:默认 `replace` — 覆盖或在缺失时创建,`append` — 追加或在缺失时创建,`create` — 已存在则失败), `wait`(可选,阻塞直到重建索引完成), `timeout`(可选), `acl`(可选) || `edit` | 在已有 `viking://` 文件中把精确字符串替换为新文本——用于局部修改,避免整文件重写。若 `old_string` 找不到、或匹配多处且 `replace_all` 为 false,则编辑失败且文件保持不变。编辑 skill 包内的文件不会重新触发 skill 安装流程,请改用 `add_skill` | `uri`, `old_string`, `new_string`, `replace_all`(可选), `wait`(可选,阻塞直到重建索引完成), `timeout`(可选) || `add_resource` | 添加本地文件或 URL 作为资源(本地文件触发渐进式上传流) | `path`, `temp_file_id`(可选), `description`(可选), `watch_interval`(可选,分钟数 — 远程 URL 的自动刷新周期), `processing_mode`(可选:默认 `semantic_and_vectors`;传 `vectors_only` 时跳过 VLM 语义理解,只向量化当前文件), `to`(可选,目标 `viking://resources/...` URI;`watch_interval > 0` 时若省略 `to`,watch 将自动绑定到本次 add 创建的资源 URI), `args`(可选,特定 parser 参数,包括 `{"parse_mode":"no_split"}` 用于正常解析但每个源文档只生成一个 Markdown 正文、飞书一次性用户 token 导入使用 `{"feishu_access_token":"u-..."}`,或飞书用户 token watch 使用 access/refresh token,并可选传入 `feishu_app_id` / `feishu_app_secret`), `acl`(可选) |diff --git a/examples/openclaw-plugin/README.md b/examples/openclaw-plugin/README.mdindex 1b0450347..7c2263f8a 100644--- a/examples/openclaw-plugin/README.md+++ b/examples/openclaw-plugin/README.md@@ -245,7 +245,7 @@ Use it as a complement to auto-capture, not a replacement:- auto-capture still preserves ordinary conversation flow and batches extraction for cost and latency- `memory_store` is for explicit durable-memory intent such as "remember my main project is X" or "save this preference"-- if `memory_store` commits but extracts 0 memories, check the OpenViking server extraction/model configuration; the explicit path triggered extraction, but the extractor did not produce a memory+- if `memory_store` commits but extracts 0 memories, it returns `action: "failed"` with `error: "no_memories_extracted"` and the agent tells the user no new memory was created; possible causes are that the content is already stored, extraction is disabled, or the extraction/model configuration needs checking### What `compact()` doesdiff --git a/examples/openclaw-plugin/README_CN.md b/examples/openclaw-plugin/README_CN.mdindex b896a37d0..84ed287b3 100644--- a/examples/openclaw-plugin/README_CN.md+++ b/examples/openclaw-plugin/README_CN.md@@ -260,7 +260,7 @@ preflight 阶段的 `assemble()` 并不是简单地把旧聊天记录塞回来- auto-capture 继续负责普通对话流,并通过批处理平衡成本和延迟- `memory_store` 面向明确的长期记忆意图,例如“记住我的主项目是 X”或“保存这个偏好”-- 如果 `memory_store` 已提交但抽取出 0 条记忆,应检查 OpenViking 服务端抽取模型/配置;显式路径已经触发抽取,但 extractor 没有产出记忆+- 如果 `memory_store` 已提交但抽取出 0 条记忆,工具会返回 `action: "failed"` 和 `error: "no_memories_extracted"`,Agent 会告诉用户没有新增记忆;可能是内容已经存过、抽取未开启,或需要检查 OpenViking 服务端抽取模型/配置### `compact()` 负责什么diff --git a/examples/openclaw-plugin/plugin/openviking-memory-tools.ts b/examples/openclaw-plugin/plugin/openviking-memory-tools.tsindex c8cc6ea7f..7044240ef 100644--- a/examples/openclaw-plugin/plugin/openviking-memory-tools.ts+++ b/examples/openclaw-plugin/plugin/openviking-memory-tools.ts@@ -176,15 +176,34 @@ export function registerOpenVikingMemoryTools(deps: OpenVikingMemoryToolsDeps):}if (memoriesCount === 0) {deps.logger.warn(- `openviking: memory_store committed but 0 memories extracted (sessionId=${sessionId}). ` +- "Check OpenViking server logs for embedding/extract errors (e.g. 401 API key, or extraction pipeline).",- );- } else {- deps.logger.info?.(- `openviking: memory_store committed, memories=${memoriesCount}, ` +- `trace_id=${commitResult.trace_id ?? "none"}`,+ `openviking: memory_store committed but 0 memories extracted (sessionId=${sessionId}), ` ++ `trace_id=${commitResult.trace_id ?? "none"}. ` ++ "No memory was created or updated. Check memory.extraction_enabled, VLM configuration/API keys, or whether the content is already stored.",);+ return {+ content: [{+ type: "text",+ text: `Memory extraction completed for session ${sessionId}, but created or updated no memory. ` ++ "The content may already be stored, memory extraction may be disabled, or the extractor found nothing new to store. " ++ "Tell the user no new memory was created." ++ (commitResult.trace_id ? ` (trace_id=${commitResult.trace_id})` : ""),+ }],+ details: {+ action: "failed",+ sessionId,+ status: commitResult.status,+ error: "no_memories_extracted",+ memoriesCount,+ archived: commitResult.archived ?? false,+ traceId: commitResult.trace_id,+ usedTempSession,+ },+ };}+ deps.logger.info?.(+ `openviking: memory_store committed, memories=${memoriesCount}, ` ++ `trace_id=${commitResult.trace_id ?? "none"}`,+ );return {content: [{diff --git a/examples/openclaw-plugin/tests/ut/tools.test.ts b/examples/openclaw-plugin/tests/ut/tools.test.tsindex 95c8ad878..456ed94ba 100644--- a/examples/openclaw-plugin/tests/ut/tools.test.ts+++ b/examples/openclaw-plugin/tests/ut/tools.test.ts@@ -531,6 +531,50 @@ describe("Tool: memory_store (behavioral)", () => {expect(result.details).toMatchObject({ traceId: "trace-memory-store" });});+ it("returns a tool-visible failure when commit extracts zero memories", async () => {+ const openVikingTransport = vi.fn(async (url: string) => {+ if (url.endsWith("/api/v1/system/status")) {+ return okResponse({ user: "default" });+ }+ if (url.includes("/messages")) {+ return okResponse({ session_id: "sess-1" });+ }+ if (url.endsWith("/commit")) {+ return okResponse({+ status: "completed",+ archived: true,+ memories_extracted: {},+ trace_id: "trace-zero",+ });+ }+ return okResponse({});+ });++ const { factoryTools, api } = setupPlugin();+ (api as any).openVikingTransport = openVikingTransport;+ contextEnginePlugin.register(api as any);+ const tool = factoryTools.get("memory_store")!({+ sessionId: "runtime-session",+ sessionKey: "agent:main:main",+ });++ const result = await tool.execute("tc-memory-store-zero", {+ text: "Remember this important thing",+ });++ expect(result.content[0].text).toContain("created or updated no memory");+ expect(result.content[0].text).toContain("no new memory was created");+ expect(result.content[0].text).toContain("trace_id=trace-zero");+ expect(result.content[0].text).not.toContain("Stored");+ expect(result.details).toMatchObject({+ action: "failed",+ error: "no_memories_extracted",+ memoriesCount: 0,+ archived: true,+ traceId: "trace-zero",+ });+ });+it("uses a temporary session by default instead of the current tool session", async () => {const openVikingTransport = vi.fn(async (url: string) => {if (url.endsWith("/api/v1/system/status")) {diff --git a/examples/pi-coding-agent-extension/README.md b/examples/pi-coding-agent-extension/README.mdindex 718dfc828..9f4aa4e82 100644--- a/examples/pi-coding-agent-extension/README.md+++ b/examples/pi-coding-agent-extension/README.md@@ -313,7 +313,7 @@ Against a current server, that is these 15:| `openviking_read` | Read one or more `viking://` file URIs, with line-based `offset`/`limit` || `openviking_list` | List one sorted page under a `viking://` directory || `openviking_tree` | Show a recursive directory tree, optionally with abstracts |-| `openviking_remember` | Store messages as long-term memory and commit them for extraction |+| `openviking_remember` | Submit messages for long-term memory extraction; returns the background extraction `task_id` right away || `openviking_write` | Write text to a `viking://` file || `openviking_edit` | Replace an exact string in an existing `viking://` file || `openviking_add_resource` | Ingest a URL, repository or local file as a resource |diff --git a/examples/pi-coding-agent-extension/tests/fixtures/mcp-tools-list.json b/examples/pi-coding-agent-extension/tests/fixtures/mcp-tools-list.jsonindex 3e7d0ee62..f59c4e05d 100644--- a/examples/pi-coding-agent-extension/tests/fixtures/mcp-tools-list.json+++ b/examples/pi-coding-agent-extension/tests/fixtures/mcp-tools-list.json@@ -334,7 +334,7 @@},{"name": "remember",- "description": "Store information into OpenViking long-term memory. Use when the user says 'remember this', shares preferences, important facts, or decisions worth persisting.",+ "description": "Submit information for OpenViking long-term memory extraction. Use when the user says 'remember this', shares preferences, important facts, or decisions worth persisting. Extraction runs in the background and decides which memories to create or update.","inputSchema": {"properties": {"messages": {diff --git a/openviking/server/mcp_endpoint.py b/openviking/server/mcp_endpoint.pyindex c9a8b377b..f6faba5c1 100644--- a/openviking/server/mcp_endpoint.py+++ b/openviking/server/mcp_endpoint.py@@ -1165,7 +1165,7 @@ class StoreMessage(BaseModel):@_mcp_error_results()@mcp.tool(annotations=_DESTRUCTIVE_TOOL_ANNOTATIONS)async def remember(messages: list[StoreMessage]) -> str:- """Store information into OpenViking long-term memory. Use when the user says 'remember this', shares preferences, important facts, or decisions worth persisting."""+ """Submit information for OpenViking long-term memory extraction. Use when the user says 'remember this', shares preferences, important facts, or decisions worth persisting. Extraction runs in the background and decides which memories to create or update."""import uuidfrom openviking.message.part import TextPart@@ -1174,6 +1174,7 @@ async def remember(messages: list[StoreMessage]) -> str:ctx = _get_ctx()session_id = f"mcp-store-{uuid.uuid4().hex[:12]}"session = await service.sessions.get(session_id, ctx, auto_create=True)+ added = 0for msg in messages:if msg.content:add_async = getattr(session, "add_message_async", None)@@ -1181,8 +1182,17 @@ async def remember(messages: list[StoreMessage]) -> str:await add_async(msg.role, [TextPart(text=msg.content)])else:session.add_message(msg.role, [TextPart(text=msg.content)])- await service.sessions.commit_async(session_id, ctx)- return f"Stored {len(messages)} message(s) and committed for memory extraction."+ added += 1+ result = await service.sessions.commit_async(session_id, ctx)+ task_id = result.get("task_id")+ if not task_id:+ reason = result.get("reason") or result.get("status") or "unknown"+ return f"Nothing was committed for memory extraction (reason: {reason})."+ return (+ f"Submitted {added} message(s) for memory extraction (session {session_id}, "+ f"task_id={task_id}). Extraction runs in the background and decides which memories "+ "to create or update."+ )# -- write -----------------------------------------------------------------diff --git a/tests/server/test_mcp_endpoint.py b/tests/server/test_mcp_endpoint.pyindex efc16f6be..5dd7f9d62 100644--- a/tests/server/test_mcp_endpoint.py+++ b/tests/server/test_mcp_endpoint.py@@ -1289,8 +1289,9 @@ async def test_list_reports_more_entries(service):async def test_store_single_message(service):result = await remember(messages=[StoreMessage(role="user", content="The sky is blue")])- assert "stored" in result.lower()- assert "1 message" in result+ assert "Submitted 1 message(s) for memory extraction" in result+ assert "task_id=" in result+ assert "decides which memories to create or update" in resultasync def test_store_batch_messages(service):@@ -1300,8 +1301,45 @@ async def test_store_batch_messages(service):StoreMessage(role="assistant", content="Noted, your favorite color is blue."),])- assert "stored" in result.lower()- assert "2 message" in result+ assert "Submitted 2 message(s)" in result+++async def test_store_reports_extraction_in_progress(service, monkeypatch):+ monkeypatch.setattr(+ service.sessions,+ "commit_async",+ AsyncMock(return_value={"session_id": "s", "status": "accepted", "task_id": "task-123"}),+ )++ result = await remember(messages=[StoreMessage(role="user", content="The sky is blue")])++ assert "Submitted 1 message(s) for memory extraction" in result+ assert "task_id=task-123" in result+ assert "session mcp-store-" in result+ assert "runs in the background" in result+ assert "decides which memories to create or update" in result+ assert "committed for memory extraction" not in result+++async def test_store_reports_skipped_commit(service, monkeypatch):+ monkeypatch.setattr(+ service.sessions,+ "commit_async",+ AsyncMock(+ return_value={+ "session_id": "s",+ "status": "skipped",+ "task_id": None,+ "reason": "no_messages",+ }+ ),+ )++ result = await remember(messages=[StoreMessage(role="user", content="")])++ assert "Nothing was committed" in result+ assert "no_messages" in result+ assert "Submitted" not in resultasync def test_store_does_not_autofill_peer_id_from_ctx(service, monkeypatch):@@ -1340,7 +1378,11 @@ async def test_store_skips_empty_message_content(service, monkeypatch):fake_session = FakeSession()monkeypatch.setattr(service.sessions, "get", AsyncMock(return_value=fake_session))- monkeypatch.setattr(service.sessions, "commit_async", AsyncMock())+ monkeypatch.setattr(+ service.sessions,+ "commit_async",+ AsyncMock(return_value={"status": "accepted", "task_id": "task-1"}),+ )result = await remember(messages=[@@ -1349,7 +1391,7 @@ async def test_store_skips_empty_message_content(service, monkeypatch):])- assert "2 message" in result+ assert "Submitted 1 message(s)" in resultassert len(fake_session.messages) == 1role, parts, peer_id, created_at = fake_session.messages[0]assert role == "assistant"