Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

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.yaml
index 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: replace
diff --git a/openviking/session/compressor_v2.py b/openviking/session/compressor_v2.py
index 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 Message
from openviking.server.identity import RequestContext
from openviking.session.memory import ExtractLoop, MemoryUpdater
-from openviking.session.memory.dataclass import ResolvedOperations
+from openviking.session.memory.dataclass import ResolvedOperations, StoredLink
from 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_links
from openviking.session.memory.utils.json_parser import JsonUtils
from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
from openviking.session.memory.utils.uri import render_template
@@ -38,7 +38,6 @@ from openviking_cli.utils.config import get_openviking_config
logger = get_logger(__name__)
-MAX_SOURCE_TRAJECTORIES = 5 # keep only the most recent N trajectory URIs per experience
_MEMORY_LOCK_RETRY_WARNING_INTERVAL_SECONDS = 10.0
ExtractPostApply = 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] = inherited
except 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.py
index 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.py
index 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_logger
logger = 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.py
index 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]) -
continue
raw = 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.py
index 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.py
index 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] = content
handle = 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 → release
assert 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",
]