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(memory): replace source_trajectories with StoredLink for trajectory-experience linking (#2222)
yangxinxin-728fb9d9b5ec9
diff --git a/openviking/prompts/templates/memory/experiences.yaml b/openviking/prompts/templates/memory/experiences.yamlindex 21f3b1930..f0b6fd7ab 100644--- a/openviking/prompts/templates/memory/experiences.yaml+++ b/openviking/prompts/templates/memory/experiences.yaml@@ -39,6 +39,9 @@ fields:- MACHINE READABILITY (IMPERATIVE VOICE): Address the future agent directly using commanding imperatives (e.g., "Ask the user for X", "Call tool Y").- ABSTRACTION MANDATE: Strip away specific entities, IDs, user names, or raw text from the past trajectory. Use generalized abstract descriptions so the rule applies universally.- FAILURE INTEGRATION: Translate past mistakes into strict negative constraints. These MUST be placed exclusively in the 'Reflect' section.+ - EXECUTION-FIRST PRINCIPLE: 'Approach' steps MUST describe direct tool invocations only. Strip all "I will now do X" / "I have completed X" communication steps.+ - CONDITIONAL BRANCH PRESERVATION: Capture full decision trees as explicit IF/THEN/ELSE branches. NEVER collapse divergent user-driven branches into a single terminal action.+ - ATOMIC SCOPE: Each experience MUST cover exactly ONE user intent and its associated tool-invocation sequence. Multiple distinct user intents → SEPARATE experiences. A 'Situation' listing more than one user goal is a violation: split immediately. Hard limit: if 'Approach' would exceed 8 bullets, STOP and split.- STRICT FORMATTING: Use exactly the 3 headings above in this order. Use concise markdown bullets (-) for every section. No numbered lists, no introductory sentences, no conversational filler, and no closing paragraphs. Token efficiency is critical.merge_op: replacediff --git a/openviking/session/compressor_v2.py b/openviking/session/compressor_v2.pyindex 9a4e6b3e3..9da95107b 100644--- a/openviking/session/compressor_v2.py+++ b/openviking/session/compressor_v2.py@@ -20,9 +20,9 @@ from openviking.core.namespace import (from openviking.message import Messagefrom openviking.server.identity import RequestContextfrom openviking.session.memory import ExtractLoop, MemoryUpdater-from openviking.session.memory.dataclass import ResolvedOperations+from openviking.session.memory.dataclass import ResolvedOperations, StoredLinkfrom openviking.session.memory.memory_isolation_handler import MemoryIsolationHandler-from openviking.session.memory.memory_updater import ExtractContext, MemoryUpdateResult+from openviking.session.memory.memory_updater import ExtractContext, MemoryUpdateResult, write_stored_linksfrom openviking.session.memory.utils.json_parser import JsonUtilsfrom openviking.session.memory.utils.memory_file_utils import MemoryFileUtilsfrom openviking.session.memory.utils.uri import render_template@@ -38,7 +38,6 @@ from openviking_cli.utils.config import get_openviking_configlogger = get_logger(__name__)-MAX_SOURCE_TRAJECTORIES = 5 # keep only the most recent N trajectory URIs per experience_MEMORY_LOCK_RETRY_WARNING_INTERVAL_SECONDS = 10.0ExtractPostApply = Callable[[MemoryUpdateResult, Dict[str, List[str]], Any], Awaitable[None]]@@ -905,15 +904,13 @@ class SessionCompressorV2:operations.delete_file_contents.append(old_mf)tracer.info(f"[supersedes] '{supersedes_name}' → queued for delete: {old_uri}")- # Map inherited source_trajectories to the new (superseding) URI only.+ # Inherit traj URIs from old exp's links (exp→traj, derived_from) to the new URI only.if new_uri:- existing = old_mf.extra_fields.get("source_trajectories", [])- if isinstance(existing, list):- inherited = list(existing)- elif isinstance(existing, str) and existing.strip():- inherited = [line.strip() for line in existing.splitlines() if line.strip()]- else:- inherited = []+ inherited = [+ link.get("to_uri", "")+ for link in old_mf.links+ if link.get("link_type") == "derived_from" and link.get("to_uri", "")+ ]if inherited:inheritance_map[new_uri] = inheritedexcept Exception as e:@@ -929,10 +926,10 @@ class SessionCompressorV2:viking_fs,lock_handle: Optional[Any] = None,) -> None:- """Append traj_uris to the source_trajectories list of each experience file.+ """Write bidirectional StoredLinks between traj_uris and each exp file.- This is the system-side management of source_trajectories — the LLM never- outputs this field; the pipeline appends the batch after a write or edit.+ Called after experience write/edit. The LLM never outputs these links;+ the pipeline appends them so the relationship is always system-managed."""normalized_traj_uris = [uri for uri in traj_uris if uri]if not normalized_traj_uris:@@ -976,34 +973,32 @@ class SessionCompressorV2:ctx,viking_fs,) -> None:+ from datetime import timezone+ from openviking.session.memory.merge_op.link_merge import merge_links+raw = await viking_fs.read_file(exp_uri, ctx=ctx) or ""mf = MemoryFileUtils.read(raw, uri=exp_uri)- existing = mf.extra_fields.get("source_trajectories", [])- if isinstance(existing, list):- uris = list(existing)- elif isinstance(existing, str) and existing.strip():- uris = [line.strip() for line in existing.splitlines() if line.strip()]- else:- uris = []-- changed = False- for traj_uri in traj_uris:- if traj_uri not in uris:- uris.append(traj_uri)- changed = True-- if len(uris) > MAX_SOURCE_TRAJECTORIES:- uris = uris[-MAX_SOURCE_TRAJECTORIES:]- changed = True-- if changed:- mf.extra_fields["source_trajectories"] = uris- new_raw = MemoryFileUtils.write(mf)- await viking_fs.write_file(exp_uri, new_raw, ctx=ctx)- tracer.info(f"[source_traj] appended {len(traj_uris)} trajectories -> {exp_uri}")+ # exp→traj: one directed edge per trajectory.+ # write_stored_links writes it to exp.links (forward) and traj.backlinks (reverse) automatically.+ now = datetime.now(timezone.utc).isoformat()+ links = [+ StoredLink(from_uri=exp_uri, to_uri=t, link_type="derived_from", weight=1.0, created_at=now)+ for t in traj_uris+ ]++ new_exp_links = merge_links(mf.links, [l.model_dump() for l in links])+ links_changed = len(new_exp_links) != len(mf.links)+ mf.links = new_exp_links++ if links_changed:+ await viking_fs.write_file(exp_uri, MemoryFileUtils.write(mf), ctx=ctx)+ tracer.info(f"[agent_link] wrote exp→traj links -> {exp_uri} (traj_count={len(traj_uris)})")else:- tracer.info(f"[source_traj] already present, skip: {exp_uri}")+ tracer.info(f"[agent_link] links already present, skip: {exp_uri}")++ # Write traj.backlinks — exp_uri already handled above+ await write_stored_links(links, ctx, viking_fs, skip_uris={exp_uri})async def _build_memory_diff(self,diff --git a/openviking/session/memory/agent_experience_context_provider.py b/openviking/session/memory/agent_experience_context_provider.pyindex 8fbe354a0..12d7492c0 100644--- a/openviking/session/memory/agent_experience_context_provider.py+++ b/openviking/session/memory/agent_experience_context_provider.py@@ -61,7 +61,9 @@ The source trajectories are for reference only — do NOT include or modify them## What to output-For each distinct behavioral pattern in the trajectory, output an experience entry with:+For each distinct user intent in the trajectory, output a SEPARATE experience entry. A single trajectory may contain multiple user intents — you MUST produce one entry per intent, not one entry for the whole trajectory.++Each entry:- `experience_name`: the name of the experience (new or existing)- `content`: the full experience content (rewrite holistically, incorporating old + new)- `supersedes`: the `experience_name` of an older experience this one replaces — set ONLY when the new name is genuinely different and broader. Leave empty otherwise.@@ -73,8 +75,8 @@ The system handles create vs update automatically:## Rules-- **One experience per distinct pattern.** Multiple experiences are only valid for genuinely independent behavioral patterns with different triggers and action sequences.-- **No near-duplicates.** Merge experiences that share the same trigger or approach into one.+- **One experience per distinct user intent.** If a trajectory covers N different user goals (e.g., cancel + modify + add baggage), output N separate entries — never merge them into one.+- **Split over merge.** When in doubt whether two patterns belong together, split them. Only merge with an existing experience when it covers the EXACT same user intent and tool sequence.- **Consistent naming language.** All `experience_name` values in one output must use the same language.- **Do NOT use `delete_uris`** for experience operations — use `supersedes` instead.- Follow field descriptions in the schema.@@ -117,18 +119,16 @@ All memory content must be written in {output_language}.async def _load_source_trajectories(self,exp_uri: str,- exp_meta: Dict,+ links: List[Dict],viking_fs: VikingFS,ctx: RequestContext,) -> List[Dict]:- """Load the most recent source trajectories for a candidate experience."""- raw = exp_meta.get("source_trajectories", [])- if isinstance(raw, list):- uris = [str(u).strip() for u in raw if str(u).strip()]- elif isinstance(raw, str):- uris = [line.strip() for line in raw.splitlines() if line.strip()]- else:- uris = []+ """Load the most recent source trajectories for a candidate experience from its links."""+ uris = [+ link.get("to_uri", "")+ for link in (links or [])+ if link.get("link_type") == "derived_from" and link.get("to_uri", "")+ ]recent_uris = uris[-MAX_SOURCE_TRAJS:]results = []@@ -238,7 +238,7 @@ All memory content must be written in {output_language}.if idx < SOURCE_TRAJ_TOP_K and viking_fs:source_trajs = await self._load_source_trajectories(- exp_uri, mf.extra_fields, viking_fs, ctx+ exp_uri, mf.links, viking_fs, ctx)for source_idx, source_result in enumerate(source_trajs):source_uri = source_result["uri"]@@ -264,6 +264,7 @@ All memory content must be written in {output_language}."Treat `candidate_experience` as existing memories you may update, replace, or skip.","Treat `candidate_source_trajectory` as reference-only context for understanding a candidate experience; do not modify it directly.","Based on the above, decide whether to **Update**, **Replace**, **Create**, or **Skip**. Output JSON only.",+ "A single trajectory covering multiple user intents MUST produce multiple entries.",]),}diff --git a/openviking/session/memory/memory_updater.py b/openviking/session/memory/memory_updater.pyindex 2d4021b8b..e901d20f5 100644--- a/openviking/session/memory/memory_updater.py+++ b/openviking/session/memory/memory_updater.py@@ -38,6 +38,47 @@ from openviking_cli.utils import get_loggerlogger = get_logger(__name__)+async def write_stored_links(+ links: List[StoredLink],+ ctx: RequestContext,+ viking_fs: Any,+ skip_uris: Optional[set] = None,+) -> None:+ """Write StoredLinks to their endpoint files' links/backlinks fields.++ For each link: from_uri's ``links`` receives the forward link;+ to_uri's ``backlinks`` receives the reverse reference.+ Files listed in skip_uris are skipped (caller handles them in the same write).+ """+ from openviking.session.memory.merge_op.link_merge import merge_links++ skip = skip_uris or set()+ file_links: Dict[str, Dict[str, List[StoredLink]]] = {}+ for link in links:+ if link.from_uri not in skip:+ file_links.setdefault(link.from_uri, {"links": [], "backlinks": []})+ file_links[link.from_uri]["links"].append(link)+ if link.to_uri not in skip:+ file_links.setdefault(link.to_uri, {"links": [], "backlinks": []})+ file_links[link.to_uri]["backlinks"].append(link)++ for uri, link_groups in file_links.items():+ try:+ content = await viking_fs.read_file(uri, ctx=ctx)+ if not content:+ continue+ mf = MemoryFileUtils.read(content, uri=uri)+ if link_groups["links"]:+ mf.links = merge_links(mf.links, [l.model_dump() for l in link_groups["links"]])+ if link_groups["backlinks"]:+ mf.backlinks = merge_links(+ mf.backlinks, [l.model_dump() for l in link_groups["backlinks"]]+ )+ await viking_fs.write_file(uri, MemoryFileUtils.write(mf), ctx=ctx)+ except Exception as e:+ tracer.error(f"Failed to apply links to {uri}: {e}")++class ExtractContext:"""Extract context for template rendering."""@@ -475,9 +516,9 @@ class MemoryUpdater:metadata[field.name] = new_value# Preserve system-managed metadata from the old file that is not- # covered by the schema (e.g. source_trajectories). These fields- # are written by the system, never by the LLM, so they would be- # silently dropped on every Update without this copy.+ # covered by the schema. These fields are written by the system,+ # never by the LLM, so they would be silently dropped on every+ # Update without this copy.if old_content and old_content.extra_fields:schema_field_names = {f.name for f in schema.fields} | {"content", "memory_type"}for key, val in old_content.extra_fields.items():@@ -563,66 +604,13 @@ class MemoryUpdater:ctx: RequestContext,deleted_uris: Optional[set[str]] = None,) -> None:- """Apply links to endpoint files that are NOT in the current upsert batch.-- Links go into from_uri's "links" field; backlinks go into to_uri's "backlinks" field.- """- from openviking.session.memory.merge_op.link_merge import merge_links-+ """Apply links to endpoint files that are NOT in the current upsert batch."""viking_fs = self._get_viking_fs()if not viking_fs:return-- # Collect URIs of files being upserted (links handled in _apply_upsert)- upserted_uris = set()- deleted_uris = deleted_uris or set()- for op in result.written_uris + result.edited_uris:- upserted_uris.add(op)-- skipped_uris = upserted_uris | deleted_uris-- # Group remaining links by target file and field- # file_links[uri]["links"] = forward links, file_links[uri]["backlinks"] = backlinks- file_links: Dict[str, Dict[str, List[StoredLink]]] = {}- for link in resolved_links:- # Forward link -> from_uri's "links"- if link.from_uri not in skipped_uris:- file_links.setdefault(link.from_uri, {"links": [], "backlinks": []})- file_links[link.from_uri]["links"].append(link)- # Backlink -> to_uri's "backlinks"- if link.to_uri not in skipped_uris:- file_links.setdefault(link.to_uri, {"links": [], "backlinks": []})- file_links[link.to_uri]["backlinks"].append(link)-- # Apply links to each remaining file- for uri, link_groups in file_links.items():- try:- content = await viking_fs.read_file(uri, ctx=ctx)- if not content:- continue- mf = MemoryFileUtils.read(content, uri=uri)-- # Merge links- if link_groups["links"]:- merged_links = merge_links(- mf.links,- [link.model_dump() for link in link_groups["links"]],- )- mf.links = merged_links-- # Merge backlinks- if link_groups["backlinks"]:- merged_backlinks = merge_links(- mf.backlinks,- [link.model_dump() for link in link_groups["backlinks"]],- )- mf.backlinks = merged_backlinks-- # Re-serialize with updated links- new_full_content = MemoryFileUtils.write(mf)- await viking_fs.write_file(uri, new_full_content, ctx=ctx)- except Exception as e:- tracer.error(f"Failed to apply links to existing file {uri}: {e}")+ upserted_uris = set(result.written_uris + result.edited_uris)+ skip = upserted_uris | (deleted_uris or set())+ await write_stored_links(resolved_links, ctx, viking_fs, skip_uris=skip)async def _apply_delete(self, uri: str, ctx: RequestContext) -> None:"""Apply delete operation (uri is already a string)."""diff --git a/tests/integration/test_agent_memory_e2e.py b/tests/integration/test_agent_memory_e2e.pyindex e75cbfc6d..e9dd2eb0f 100644--- a/tests/integration/test_agent_memory_e2e.py+++ b/tests/integration/test_agent_memory_e2e.py@@ -201,6 +201,7 @@ def _entry_uri(entry: dict) -> str:def _collect_source_trajectories(client: LocalClient, exp_entries: List[dict]) -> List[str]:+ """Collect traj URIs from experience forward links (exp→traj, derived_from)."""all_uris: List[str] = []for entry in exp_entries:exp_uri = _entry_uri(entry)@@ -208,12 +209,12 @@ def _collect_source_trajectories(client: LocalClient, exp_entries: List[dict]) -continueraw = run_async(client.read(exp_uri)) or ""mf = MemoryFileUtils.read(raw) if raw else None- metadata = mf.extra_fields if mf else {}- source = metadata.get("source_trajectories", [])- if isinstance(source, list):- all_uris.extend(str(u).strip() for u in source if str(u).strip())- elif isinstance(source, str):- all_uris.extend(line.strip() for line in source.splitlines() if line.strip())+ if not mf:+ continue+ for link in mf.links:+ to_uri = link.get("to_uri", "")+ if link.get("link_type") == "derived_from" and to_uri:+ all_uris.append(to_uri)return list(dict.fromkeys(all_uris))diff --git a/tests/session/memory/test_agent_experience_context_provider.py b/tests/session/memory/test_agent_experience_context_provider.pyindex 0083f6178..f92a98474 100644--- a/tests/session/memory/test_agent_experience_context_provider.py+++ b/tests/session/memory/test_agent_experience_context_provider.py@@ -91,6 +91,7 @@ async def test_agent_experience_prefetch_includes_structured_read_results():"viking://agent/agent_sample_9/memories/experiences/personal_experience_sharing_conversation_flow.md": SimpleNamespace(extra_fields={"experience_name": "personal_experience_sharing_conversation_flow"},content="line one\nline two",+ links=[],)}diff --git a/tests/session/memory/test_compressor_v2.py b/tests/session/memory/test_compressor_v2.pyindex 3f5e9e2b7..44a54b7af 100644--- a/tests/session/memory/test_compressor_v2.py+++ b/tests/session/memory/test_compressor_v2.py@@ -656,26 +656,29 @@ class TestCompressorV2:exp_uri = "viking://agent/default/memories/experiences/debug.md"events: List[str] = []+ traj_uri = "viking://agent/default/memories/trajectories/traj-1.md"+class FakeVikingFS:def __init__(self):- self.content = MemoryFileUtils.write(- MemoryFile(- uri="viking://agent/default/memories/experiences/debug.md",- content="debug login issue",- extra_fields={"source_trajectories": ["traj-0"]},- )- )+ self.files = {+ exp_uri: MemoryFileUtils.write(+ MemoryFile(uri=exp_uri, content="debug login issue")+ ),+ traj_uri: MemoryFileUtils.write(+ MemoryFile(uri=traj_uri, content="traj content")+ ),+ }def _uri_to_path(self, uri: str, ctx=None) -> str:return f"/local/default/agent/default/memories/experiences/{uri.rsplit('/', 1)[-1]}"async def read_file(self, uri: str, ctx=None):events.append("read")- return self.content+ return self.files.get(uri, "")async def write_file(self, uri: str, content: str, ctx=None):events.append("write")- self.content = content+ self.files[uri] = contenthandle = SimpleNamespace(id="handle-1", locks=[])@@ -696,17 +699,29 @@ class TestCompressorV2:with patch("openviking.storage.transaction.get_lock_manager", return_value=lock_manager):await compressor._append_trajectories_to_experiences([exp_uri],- ["traj-1"],+ [traj_uri],ctx,viking_fs,)- mf = MemoryFileUtils.read(viking_fs.content, uri=exp_uri)- assert mf.extra_fields["source_trajectories"] == ["traj-0", "traj-1"]+ # exp: exp.links 有指向 traj 的边(exp→traj, derived_from)+ exp_mf = MemoryFileUtils.read(viking_fs.files[exp_uri], uri=exp_uri)+ assert "source_trajectories" not in exp_mf.extra_fields+ assert any(l.get("to_uri") == traj_uri for l in exp_mf.links), "exp.links should point to traj"+ assert exp_mf.backlinks == [], "exp should have no backlinks"++ # traj: write_stored_links 写入 traj.backlinks(同一条边的 to 端)+ traj_mf = MemoryFileUtils.read(viking_fs.files[traj_uri], uri=traj_uri)+ assert traj_mf.links == [], "traj should have no forward links"+ assert any(l.get("from_uri") == exp_uri for l in traj_mf.backlinks), "traj.backlinks should reference exp"++ # event order: lock → read exp → write exp → read traj → write traj → releaseassert events == ["exact:/local/default/agent/default/memories/experiences/debug.md",- "read",- "write",+ "read", # exp read+ "write", # exp write (exp.links)+ "read", # traj read (write_stored_links)+ "write", # traj write (traj.backlinks)"release",]