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
feat(session): expose memory diff uri (#2789)
Qin Haojie5f8547a48a6a
diff --git a/docs/en/api/05-sessions.md b/docs/en/api/05-sessions.mdindex 7837639da..a523fc2d9 100644--- a/docs/en/api/05-sessions.md+++ b/docs/en/api/05-sessions.md@@ -1231,6 +1231,7 @@ if task != nil {"result": {"session_id": "a1b2c3d4","archive_uri": "viking://user/alice/sessions/a1b2c3d4/history/archive_001",+ "memory_diff_uri": "viking://user/alice/sessions/a1b2c3d4/history/archive_001/memory_diff.json","memories_extracted": {"profile": 1,"preferences": 2,@@ -1379,7 +1380,7 @@ viking://user/{user_id}/sessions/{session_id}/| +-- .abstract.md # Written in Phase 2 (background)| +-- .overview.md # Written in Phase 2 (background)| +-- .meta.json # Archive metadata- | +-- memory_diff.json # Written in Phase 2 (background, on memory changes)+ | +-- memory_diff.json # Written when long-term memory extraction completes| +-- .done # Phase 2 completion marker| +-- .failed.json # Phase 2 failure marker+-- archive_002/@@ -1387,7 +1388,7 @@ viking://user/{user_id}/sessions/{session_id}/### memory_diff.json Structure-Each commit writes a `memory_diff.json` to the archive directory, recording all memory changes for auditing and rollback:+When long-term memory extraction runs successfully, the commit writes a `memory_diff.json` to the archive directory, recording all memory changes for auditing and rollback:```json{@@ -1436,7 +1437,7 @@ Each commit writes a `memory_diff.json` to the archive directory, recording all| `summary.total_updates` | int | Number of modified memories || `summary.total_deletes` | int | Number of deleted memories |-An empty `memory_diff.json` (all counts zero) is written even when no memory operations occurred.+An empty `memory_diff.json` (all counts zero) is written when long-term memory extraction runs but produces no memory operations.---diff --git a/docs/zh/api/05-sessions.md b/docs/zh/api/05-sessions.mdindex ea54e3af4..4ed7ed3ac 100644--- a/docs/zh/api/05-sessions.md+++ b/docs/zh/api/05-sessions.md@@ -1205,6 +1205,7 @@ if task != nil {"result": {"session_id": "a1b2c3d4","archive_uri": "viking://user/alice/sessions/a1b2c3d4/history/archive_001",+ "memory_diff_uri": "viking://user/alice/sessions/a1b2c3d4/history/archive_001/memory_diff.json","memories_extracted": {"profile": 1,"preferences": 2,@@ -1351,7 +1352,7 @@ viking://user/{user_id}/sessions/{session_id}/│ ├── .abstract.md # Phase 2 写入(后台)│ ├── .overview.md # Phase 2 写入(后台)│ ├── .meta.json # 归档元数据- │ ├── memory_diff.json # Phase 2 写入(后台,记忆变更时)+ │ ├── memory_diff.json # 长记忆抽取完成时写入│ ├── .done # Phase 2 完成标记│ └── .failed.json # Phase 2 失败标记└── archive_002/@@ -1359,7 +1360,7 @@ viking://user/{user_id}/sessions/{session_id}/### memory_diff.json 数据结构-每次提交会在归档目录写入 `memory_diff.json`,记录所有记忆变更,便于审计和回溯:+长记忆抽取成功运行时,会在归档目录写入 `memory_diff.json`,记录所有记忆变更,便于审计和回溯:```json{@@ -1408,7 +1409,7 @@ viking://user/{user_id}/sessions/{session_id}/| `summary.total_updates` | int | 修改记忆数 || `summary.total_deletes` | int | 删除记忆数 |-即使没有记忆操作,也会写入空结构的 `memory_diff.json`(所有计数为零)。+如果长记忆抽取已运行但没有产生记忆操作,也会写入空结构的 `memory_diff.json`(所有计数为零)。---diff --git a/openviking/session/compressor_v2.py b/openviking/session/compressor_v2.pyindex 9ba691b22..5d220d87b 100644--- a/openviking/session/compressor_v2.py+++ b/openviking/session/compressor_v2.py@@ -283,7 +283,6 @@ class SessionCompressorV2:telemetry.set("memory.extract.skipped", 0)from openviking.storage.transaction import get_lock_manager, init_lock_manager- from openviking.storage.viking_fs import get_viking_fs# 初始化锁管理器(仅在有 AGFS 时使用锁机制)viking_fs = get_viking_fs()@@ -381,33 +380,36 @@ class SessionCompressorV2:if operations is None:tracer.info("No memory operations generated")- return []-- updater = self._get_or_create_updater(registry, transaction_handle)+ result = MemoryUpdateResult()+ else:+ updater = self._get_or_create_updater(registry, transaction_handle)- # Apply operations with isolation_handler- result = await updater.apply_operations(- operations,- ctx,- extract_context=extract_context,- isolation_handler=isolation_handler,- )+ # Apply operations with isolation_handler+ result = await updater.apply_operations(+ operations,+ ctx,+ extract_context=extract_context,+ isolation_handler=isolation_handler,+ )- tracer.info(- f"Applied memory operations: written={len(result.written_uris)}, "- f"edited={len(result.edited_uris)}, deleted={len(result.deleted_uris)}, "- f"errors={len(result.errors)}"- )+ tracer.info(+ f"Applied memory operations: written={len(result.written_uris)}, "+ f"edited={len(result.edited_uris)}, deleted={len(result.deleted_uris)}, "+ f"errors={len(result.errors)}"+ )# Write memory_diff.json to archive directoryif archive_uri and viking_fs:- memory_diff = await self._build_memory_diff(- result=result,- operations=operations,- viking_fs=viking_fs,- ctx=ctx,- archive_uri=archive_uri,- )+ if operations is None:+ memory_diff = self._empty_memory_diff(archive_uri)+ else:+ memory_diff = await self._build_memory_diff(+ result=result,+ operations=operations,+ viking_fs=viking_fs,+ ctx=ctx,+ archive_uri=archive_uri,+ )await viking_fs.write_file(uri=f"{archive_uri}/memory_diff.json",content=json.dumps(memory_diff, ensure_ascii=False, indent=4),@@ -474,6 +476,23 @@ class SessionCompressorV2:except Exception as e:logger.warning(f"Failed to release transaction lock: {e}")+ @staticmethod+ def _empty_memory_diff(archive_uri: str = "") -> Dict[str, Any]:+ return {+ "archive_uri": archive_uri,+ "extracted_at": datetime.utcnow().isoformat() + "Z",+ "operations": {+ "adds": [],+ "updates": [],+ "deletes": [],+ },+ "summary": {+ "total_adds": 0,+ "total_updates": 0,+ "total_deletes": 0,+ },+ }+@tracer(ignore_result=True)async def extract_execution_memories(self,diff --git a/openviking/session/session.py b/openviking/session/session.pyindex 9585e7393..c36df4689 100644--- a/openviking/session/session.py+++ b/openviking/session/session.py@@ -1272,6 +1272,7 @@ class Session:memories_extracted: Dict[str, int] = {}extracted_skill_results: list[dict] = []active_count_updated = 0+ memory_diff_uri: Optional[str] = Nonetelemetry = OperationTelemetry(operation="session_commit_phase2", enabled=True)archive_index = self._archive_index_from_uri(archive_uri)redo_task_id: Optional[str] = None@@ -1483,6 +1484,14 @@ class Session:if extraction_error is not None:raise extraction_error+ if long_term_has_work and self._viking_fs:+ candidate_memory_diff_uri = f"{archive_uri}/memory_diff.json"+ if await self._viking_fs.exists(+ candidate_memory_diff_uri,+ ctx=self.ctx,+ ):+ memory_diff_uri = candidate_memory_diff_uri+total_extracted = 0for label, result in zip(extraction_labels[1:], _results[1:], strict=True):if isinstance(result, dict):@@ -1580,30 +1589,34 @@ class Session:# would have raised above and marked the archive .failed.json.await self._write_done_file(archive_uri, first_message_id, last_message_id)- await tracker.complete(- task_id,- {- "session_id": self.session_id,- "archive_uri": archive_uri,- "memories_extracted": memories_extracted,- "session_skills_extracted": len(extracted_skill_results),- "session_skill_uris": [- item.get("uri") or item.get("root_uri")- for item in extracted_skill_results- if isinstance(item, dict) and (item.get("uri") or item.get("root_uri"))- ],- "active_count_updated": active_count_updated,- "token_usage": {- "llm": dict(self._meta.llm_token_usage),- "embedding": dict(self._meta.embedding_token_usage),- "total": {- "total_tokens": self._meta.llm_token_usage["total_tokens"]- + self._meta.embedding_token_usage["total_tokens"],- "cached_tokens": self._meta.llm_token_usage["cached_tokens"],- "reasoning_tokens": self._meta.llm_token_usage["reasoning_tokens"],- },+ result_payload = {+ "session_id": self.session_id,+ "archive_uri": archive_uri,+ "memories_extracted": memories_extracted,+ "session_skills_extracted": len(extracted_skill_results),+ "session_skill_uris": [+ item.get("uri") or item.get("root_uri")+ for item in extracted_skill_results+ if isinstance(item, dict) and (item.get("uri") or item.get("root_uri"))+ ],+ "active_count_updated": active_count_updated,+ "token_usage": {+ "llm": dict(self._meta.llm_token_usage),+ "embedding": dict(self._meta.embedding_token_usage),+ "total": {+ "total_tokens": self._meta.llm_token_usage["total_tokens"]+ + self._meta.embedding_token_usage["total_tokens"],+ "cached_tokens": self._meta.llm_token_usage["cached_tokens"],+ "reasoning_tokens": self._meta.llm_token_usage["reasoning_tokens"],},},+ }+ if memory_diff_uri:+ result_payload["memory_diff_uri"] = memory_diff_uri++ await tracker.complete(+ task_id,+ result_payload,account_id=self.ctx.account_id,user_id=self.ctx.user.user_id,)diff --git a/tests/server/test_api_sessions.py b/tests/server/test_api_sessions.pyindex 5aaed5880..8fe4ecba0 100644--- a/tests/server/test_api_sessions.py+++ b/tests/server/test_api_sessions.py@@ -771,6 +771,7 @@ async def test_compress_session(client: httpx.AsyncClient):body = resp.json()assert body["status"] == "ok"assert body["result"]["status"] == "accepted"+ assert "memory_diff_uri" not in body["result"]assert "usage" not in bodyassert "telemetry" not in bodydiff --git a/tests/session/test_session_commit.py b/tests/session/test_session_commit.pyindex 5bc75be1f..c8424a8c2 100644--- a/tests/session/test_session_commit.py+++ b/tests/session/test_session_commit.py@@ -47,6 +47,7 @@ class TestCommit:assert result.get("status") == "accepted"assert "session_id" in resultassert result.get("task_id") is not None+ assert "memory_diff_uri" not in resultassert "memories_extracted" not in resultasync def test_commit_extracts_memories(@@ -59,6 +60,17 @@ class TestCommit:# Wait for background memory extraction to completetask_result = await _wait_for_task(task_id)assert task_result["status"] == "completed"+ assert (+ task_result["result"]["memory_diff_uri"]+ == f"{task_result['result']['archive_uri']}/memory_diff.json"+ )+ memory_diff = json.loads(+ await session_with_messages._viking_fs.read_file(+ task_result["result"]["memory_diff_uri"],+ ctx=session_with_messages.ctx,+ )+ )+ assert memory_diff["archive_uri"] == task_result["result"]["archive_uri"]assert "memories_extracted" in task_result["result"]memory_counts = task_result["result"]["memories_extracted"]assert isinstance(memory_counts, dict)@@ -96,6 +108,7 @@ class TestCommit:assert task_result["result"]["session_skill_uris"] == ["viking://user/test/skills/code-review"]+ assert "memory_diff_uri" not in task_result["result"]session_with_messages._session_compressor.extract_long_term_memories.assert_not_awaited()session_with_messages._session_compressor.extract_execution_memories.assert_awaited_once()call_kwargs = (@@ -131,6 +144,7 @@ class TestCommit:assert task_result["status"] == "completed"assert task_result["result"]["memories_extracted"] == {}assert task_result["result"]["session_skills_extracted"] == 0+ assert "memory_diff_uri" not in task_result["result"]session_with_messages._session_compressor.extract_long_term_memories.assert_awaited_once()session_with_messages._session_compressor.extract_execution_memories.assert_not_awaited()@@ -156,6 +170,7 @@ class TestCommit:assert task_result["status"] == "completed"assert task_result["result"]["session_skills_extracted"] == 0assert task_result["result"]["session_skill_uris"] == []+ assert "memory_diff_uri" not in task_result["result"]session_with_messages._session_compressor.extract_long_term_memories.assert_awaited_once()session_with_messages._session_compressor.extract_execution_memories.assert_awaited_once()call_kwargs = (