Skip to content

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

perf(memory): streamline extraction prompts and deduplicate inputs (#6120)

DuTao84cc2b412a7e
diff --git a/openviking/prompts/templates/memory/trajectories.yaml b/openviking/prompts/templates/memory/trajectories.yaml
index 9f0115586..d912beab1 100644
--- a/openviking/prompts/templates/memory/trajectories.yaml
+++ b/openviking/prompts/templates/memory/trajectories.yaml
@@ -11,7 +11,7 @@ embedding_template: |-
{{ retrieval_anchor }}
directory: "viking://user/{{ user_space }}/memories/trajectories"
-filename_template: "{{ trajectory_name|lower }}_{{ extract_context.get_session_timestamp() }}.md"
+filename_template: "{{ trajectory_name|lower }}_{{ extract_context.get_session_timestamp() }}{{ extract_context.get_source_archive_suffix() }}.md"
enabled: true
operation_mode: "add_only"
stage: agent
diff --git a/openviking/session/memory/agent_experience_context_provider.py b/openviking/session/memory/agent_experience_context_provider.py
index b570a5b6c..c8df6ef44 100644
--- a/openviking/session/memory/agent_experience_context_provider.py
+++ b/openviking/session/memory/agent_experience_context_provider.py
@@ -35,6 +35,10 @@ EXPERIENCE_MEMORY_TYPE = "experiences"
SEARCH_TOP_K = 5
SOURCE_TRAJ_TOP_K = 3 # only attach source_trajectories for the top-3 candidates
MAX_SOURCE_TRAJS = 3 # max trajectories to load per experience
+# Hide storage bookkeeping only in read-only grounding sent to the model.
+_SOURCE_TRAJECTORY_HIDDEN_FIELDS = frozenset(
+ {"backlinks", "source_archive_uri", "last_update_trace_id", "version"}
+)
def _is_directory_not_found_error(exc: Exception) -> bool:
@@ -146,7 +150,11 @@ All memory content must be written in {output_language}.
try:
raw = await viking_fs.read_file(uri, ctx=ctx) or ""
mf = MemoryFileUtils.read(raw, uri=uri)
- result = mf.to_metadata()
+ result = {
+ key: value
+ for key, value in mf.to_metadata().items()
+ if key not in _SOURCE_TRAJECTORY_HIDDEN_FIELDS
+ }
result["content"] = mf.content
result["uri"] = uri
results.append(result)
diff --git a/openviking/session/memory/extract_loop.py b/openviking/session/memory/extract_loop.py
index 38c6896ae..75cbd6271 100644
--- a/openviking/session/memory/extract_loop.py
+++ b/openviking/session/memory/extract_loop.py
@@ -271,16 +271,14 @@ class ExtractLoop:
self.context_provider.instruction()
)
output_contract = self._output_protocol.render_contract(self._output_context)
+ context_rules = self._output_protocol.render_context_rules(self._output_context)
messages.append(
{
"role": "system",
"content": f"""
{provider_instruction}
{reference_rules}
-## Read Format Rules
-- The read tool accepts `uri`, optional `offset` (0-indexed), and optional `limit`.
-- Read content is returned in Claude Code format: each visible line is prefixed with `line_number<TAB>`.
-- When you copy text from read results into SEARCH/REPLACE or DELETE operations, copy the exact text after the line-number prefix. Never include the line-number prefix itself in `search`, `replace`, or `delete`.
+{context_rules}
{output_contract}
""",
}
diff --git a/openviking/session/memory/extraction_output_protocol/base.py b/openviking/session/memory/extraction_output_protocol/base.py
index 7da0bf0c7..878a53e05 100644
--- a/openviking/session/memory/extraction_output_protocol/base.py
+++ b/openviking/session/memory/extraction_output_protocol/base.py
@@ -11,6 +11,8 @@ from typing import Any
from pydantic import BaseModel
from openviking.session.memory.dataclass import MemoryFile, MemoryTypeSchema
+from openviking.session.memory.extraction_output_protocol import prompt_fragments as prompts
+from openviking.session.memory.merge_op import FieldType, MergeOp
class ExtractionOutputProtocolError(ValueError):
@@ -34,12 +36,42 @@ class ExtractionOutputContext:
available_tools: tuple[str, ...] = ()
template_context: dict[str, Any] = field(default_factory=dict)
+ @property
+ def inspection_tools(self) -> tuple[str, ...]:
+ """Native inspection tools in canonical prompt order."""
+ return tuple(name for name in ("search", "read") if name in self.available_tools)
+
+ @property
+ def add_only(self) -> bool:
+ """Whether every selected schema only creates new memory records."""
+ return bool(self.schemas) and all(
+ getattr(schema, "operation_mode", "upsert") == "add_only" for schema in self.schemas
+ )
+
+ @property
+ def supports_string_patch(self) -> bool:
+ """Whether an upsert schema exposes an existing string's edit/drop methods."""
+ return any(
+ getattr(schema, "operation_mode", "upsert") != "add_only"
+ and any(
+ field.field_type == FieldType.STRING and field.merge_op == MergeOp.PATCH
+ for field in getattr(schema, "fields", ())
+ )
+ for schema in self.schemas
+ )
+
class ExtractionOutputProtocol(ABC):
"""Render and parse one model-facing extraction output protocol."""
name: str
+ def render_context_rules(self, context: ExtractionOutputContext) -> str:
+ """Render shared read/patch guidance without exposing unavailable tools."""
+ read_rules = prompts.READ_FORMAT_RULES if "read" in context.inspection_tools else ""
+ patch_rules = prompts.PATCH_CONTEXT_RULES if context.supports_string_patch else ""
+ return "".join((read_rules, patch_rules))
+
@abstractmethod
def render_contract(self, context: ExtractionOutputContext) -> str:
"""Render the output API/schema shown to the model."""
diff --git a/openviking/session/memory/extraction_output_protocol/json_protocol.py b/openviking/session/memory/extraction_output_protocol/json_protocol.py
index b08f0608c..7e5f9e8d7 100644
--- a/openviking/session/memory/extraction_output_protocol/json_protocol.py
+++ b/openviking/session/memory/extraction_output_protocol/json_protocol.py
@@ -7,6 +7,7 @@ from __future__ import annotations
import json
from typing import Any
+from openviking.session.memory.extraction_output_protocol import prompt_fragments as prompts
from openviking.session.memory.extraction_output_protocol.base import (
ExtractionOutputContext,
ExtractionOutputProtocol,
@@ -50,23 +51,15 @@ class JsonExtractionOutputProtocol(ExtractionOutputProtocol):
)
def render_reference_rules(self, context: ExtractionOutputContext) -> str:
- rules = """
-## Page ID Rules
-- Every memory item you create or edit MUST include "page_id".
-- For existing items, use the page_id shown in read/search results.
-- For new items, assign a unique page_id >= 100.
-- When editing an existing item, reuse its existing page_id.
-- To delete an existing item, add an entry to `delete_ids` using its page_id.
-- `delete_ids` deletes the whole item: use it only if every substantive fact is in scope; otherwise MUST use DELETE blocks for affected lines, preserving the rest and not inferring scope from the file name/topic.
-- For canonical merges, set `replacement_page_id` to the surviving page that should inherit the deleted page's existing links/backlinks; for pure deletes, set `replacement_page_id` to null.
-"""
- if context.link_enabled:
- rules += """
-## Link Rules
-- Link fields `f` and `t` must reference these page_id values.
-- Only create links when the relationship is meaningful and clear from the conversation. Do NOT force links between unrelated items.
-"""
- return rules
+ link_rules = prompts.JSON_LINK_RULES if context.link_enabled else ""
+ if context.add_only:
+ return "".join((prompts.JSON_ADD_ONLY_REFERENCE_RULES, link_rules))
+ removal_rule = (
+ prompts.JSON_PATCH_REMOVAL_RULE
+ if context.supports_string_patch
+ else prompts.JSON_FULL_REMOVAL_RULE
+ )
+ return "".join((prompts.JSON_UPSERT_REFERENCE_RULES, removal_rule, link_rules))
def parse(
self, content: str, context: ExtractionOutputContext
@@ -78,7 +71,9 @@ class JsonExtractionOutputProtocol(ExtractionOutputProtocol):
)
def render_final_instruction(self, context: ExtractionOutputContext) -> str:
- fields = ["delete_ids", *context.operations_model.model_fields]
+ fields = list(context.operations_model.model_fields)
+ if not context.add_only:
+ fields = ["delete_ids", *fields]
skeleton = json.dumps(
{name: [] for name in dict.fromkeys(fields)},
ensure_ascii=False,
diff --git a/openviking/session/memory/extraction_output_protocol/prompt_fragments.py b/openviking/session/memory/extraction_output_protocol/prompt_fragments.py
new file mode 100644
index 000000000..474279d83
--- /dev/null
+++ b/openviking/session/memory/extraction_output_protocol/prompt_fragments.py
@@ -0,0 +1,172 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Immutable prompt blocks selected by the extraction output protocols.
+
+Keep model-facing wording here and capability decisions in the renderers. Tuple
+blocks contain individual contract lines; string blocks retain section spacing.
+"""
+
+READ_FORMAT_RULES = """
+## Read Format Rules
+- The read tool accepts `uri`, optional `offset` (0-indexed), and optional `limit`.
+- Read content is returned in Claude Code format: each visible line is prefixed with `line_number<TAB>`.
+"""
+PATCH_CONTEXT_RULES = """
+## Patch Context Rules
+- When copying numbered memory context into SEARCH/REPLACE or DELETE operations, copy only the exact text after `line_number<TAB>`. Never include the line-number prefix itself in `search`, `replace`, or `delete`.
+"""
+
+PYTHON_FORMAT_RULES = (
+ "## Output Format: restricted Python memory SDK",
+ "Return only Python code, optionally wrapped in one ```python code fence.",
+ "The code is interpreted as a restricted DSL and cannot access Python modules, files, or the network.",
+)
+PYTHON_CONTENT_RULE = (
+ "Never return memory content as bare Markdown; all changes must be arguments to SDK calls."
+)
+PYTHON_STRING_LITERAL_RULE = (
+ 'ALWAYS use a triple-quoted string ("""...""") for EVERY natural-language argument '
+ "(e.g. content, summary, goal), even one-liners. "
+ "Prose frequently contains apostrophes (e.g. Evan's), quotes, colons, or dates that break "
+ 'single- or double-quoted literals. Inside triple quotes, escape any literal """ and '
+ "backslash; never put a real newline inside a single- or double-quoted string."
+)
+PYTHON_COMMIT_RULE = (
+ "You may end the program with sdk.commit(); when present it must be the final call. "
+ "If there are no changes, return only sdk.commit()."
+)
+PYTHON_METHODS_HEADER = ("", "Available write methods for this extraction:")
+PYTHON_ADD_ONLY_PREAMBLE = (
+ *PYTHON_FORMAT_RULES,
+ PYTHON_CONTENT_RULE,
+ "Create new memories only, with complete field values; do not modify or delete existing memories.",
+ PYTHON_STRING_LITERAL_RULE,
+ "Only keyword arguments are accepted by create and set.",
+ PYTHON_COMMIT_RULE,
+ *PYTHON_METHODS_HEADER,
+)
+PYTHON_UPSERT_PREAMBLE = (
+ *PYTHON_FORMAT_RULES,
+ "The SDK is write-only. Use the system-provided existing-object bindings; never emit "
+ "sdk.search(), sdk.read(), or sdk.existing().",
+ PYTHON_CONTENT_RULE,
+ "Existing objects shown by the system may use obj.update(field=value, ...) to set complete "
+ "scalar/immutable fields, or obj.delete(replacement=None).",
+ "To change an existing string field, update it through the object's field attribute. Use the "
+ "real field name (e.g. content), NOT the literal word 'field':",
+ " - obj.content.update(new_value): replace the whole field with a complete new string.",
+ "A field attribute is a write handle only; you cannot read it as a string or call str methods on it.",
+ "For string fields marked [replace], always pass the complete new value to "
+ "obj.content.update(), including unchanged text, even for a small change.",
+)
+PYTHON_PATCH_RULES = (
+ " - obj.content.edit(search=..., replace=...): replace one exact snippet in an editable string (merge_op=patch).",
+ " - obj.content.drop(text=...): delete one exact snippet in an editable string (merge_op=patch).",
+ "edit()/drop() may be chained, e.g. obj.content.edit(search='a', replace='b').drop(text='c'); do not mix them with .update() in one chain.",
+ "Each search= (and drop text=) MUST be copied verbatim from the current field value shown in the object's sdk.existing(...) binding, and must occur exactly once. If the snippet appears more than once, include an adjacent unique line just before or after it so the match is unique. Never use text from the conversation or the new facts you intend to add as a search anchor; that text is not in the current content and the edit will fail.",
+ "edit()/drop() only work on an existing memory's editable string field (merge_op=patch); new memories from create/set must be given complete field values.",
+ "For existing editable strings (merge_op=patch), prefer the smallest unique edit()/drop(). Do not rewrite the entire field just to add or change a few facts; large full-content rewrites are more likely to be truncated or malformed. Use obj.content.update() only when most of such an editable string changes.",
+ 'Use triple-quoted strings ("""...""") for every search=/replace=/text= snippet too.',
+)
+PYTHON_UPSERT_FOOTER = (
+ PYTHON_STRING_LITERAL_RULE,
+ "Only keyword arguments are accepted by create, set, and obj.update(); "
+ "a field's update() takes one positional string.",
+ PYTHON_COMMIT_RULE,
+ "Use the system-provided existing-object variable names exactly as shown. "
+ "When a newly created memory is the replacement, assign its create call to "
+ "a variable first, for example: canonical = sdk.create_<type>(...); "
+ "duplicate_1.delete(replacement=canonical). Never recreate or rebind an "
+ "existing object with sdk.existing().",
+ *PYTHON_METHODS_HEADER,
+)
+PYTHON_LINK_RULES = (
+ "",
+ "## Link Rules",
+ "- Create links between memories when they have a meaningful and clear relationship "
+ "(e.g. an event mentioning a person/entity, a preference about a place/activity). "
+ "Do NOT force links between unrelated items.",
+ "- Use obj.link(target, link_type='related_to', weight=0.5, match_text='<word>', "
+ "description='') as a standalone "
+ "statement after both objects exist.",
+ "- match_text must be a single exact word that appears in the source object's content. "
+ "It is where the link anchor is inserted. Choose the most specific identifying word "
+ "(e.g. a person's name, a place, an activity).",
+ "- link_type uses lowercase snake_case: related_to (default), belongs_to, "
+ "derived_from, caused_by, contradicts, evolved_from.",
+ "- For a newly created object, assign the create/set call to a variable first, then "
+ "call .link() on it (see the preamble); existing objects use their provided variable names.",
+ "- Links are optional; only create them when the relationship is explicit in the "
+ "conversation. Do not link every memory to every other memory.",
+ "",
+ "Example — linking a newly created memory to another new one and to an existing binding "
+ "(replace create_<type>/fields with methods and fields from the contract above):",
+ "```python",
+ "obj_a = sdk.create_<type_a>(...) # a new memory, assigned to a variable",
+ "obj_b = sdk.create_<type_b>(...) # another new memory",
+ 'obj_a.link(obj_b, link_type="related_to", match_text="<word_in_obj_a>")',
+ 'obj_a.link(existing_1, link_type="related_to", match_text="<word_in_obj_a>")',
+ "```",
+)
+PYTHON_LINKS_DISABLED = ("Links are disabled; obj.link(...) is unavailable.",)
+PYTHON_SINGLETON_UPDATE_RULE = (
+ " To change an already-shown existing object, update that object instead of calling set again."
+)
+PYTHON_ADD_ONLY_REFERENCE_RULES = """
+## Memory Object Rules
+- Create collection memories with listed sdk.create_<memory_type>(...) methods.
+- Set a single-file memory with its listed sdk.set_<memory_type>(...) method; each target scope has only one such object.
+"""
+PYTHON_UPSERT_REFERENCE_RULES = """
+## Memory Object Rules
+- Update or delete an existing memory only through its system-provided bound object; never pass or construct a URI.
+- Create collection memories with listed sdk.create_<memory_type>(...) methods.
+- Set a single-file memory with its listed sdk.set_<memory_type>(...) method; each target scope has only one such object.
+- Existing-object immutable fields are preserved by the system. URI identity fields may be
+ updated when their schema allows it; changing one renames the memory object.
+- If a rename target already exists, do not rename over it. Inspect both supplied objects, update the
+ canonical target with every distinct fact, then delete the source with replacement=target.
+- For canonical merges, use duplicate.delete(replacement=canonical); for pure deletes, call delete() without replacement.
+- delete(replacement=canonical) discards the duplicate's content entirely and keeps only the canonical. Before deleting a duplicate, first fold every distinct valid fact it holds into the canonical using its schema-supported update methods; merging or compacting must never drop a unique fact that only the duplicate recorded.
+"""
+PYTHON_PATCH_REMOVAL_RULE = (
+ "- delete() removes the whole object; use obj.content.drop(text=...) "
+ "(with the real field name) for partial removal only on [editable string] "
+ "fields. For [replace] fields, update the complete remaining value, "
+ "preserving every unaffected fact.\n"
+)
+PYTHON_FULL_REMOVAL_RULE = (
+ "- delete() removes the whole object. To remove only some content, update "
+ "the complete affected field with its remaining value, preserving every "
+ "unaffected fact.\n"
+)
+
+JSON_ADD_ONLY_REFERENCE_RULES = """
+## Page ID Rules
+- Every new memory item MUST include a unique "page_id" >= 100.
+- Create new memories only, with complete field values; do not modify or delete existing memories.
+"""
+JSON_UPSERT_REFERENCE_RULES = """
+## Page ID Rules
+- Every memory item you create or edit MUST include "page_id".
+- For existing items, use the page_id shown in the supplied memory context.
+- For new items, assign a unique page_id >= 100.
+- When editing an existing item, reuse its existing page_id.
+- To delete an existing item, add an entry to `delete_ids` using its page_id.
+- `delete_ids` deletes the whole item: use it only if every substantive fact is in scope; never infer scope from the file name/topic.
+- For canonical merges, set `replacement_page_id` to the surviving page that should inherit the deleted page's existing links/backlinks; for pure deletes, set `replacement_page_id` to null.
+"""
+JSON_PATCH_REMOVAL_RULE = (
+ "- For partial removal on patch fields, use DELETE blocks for affected "
+ "lines, preserving the rest. For replace fields, rewrite the complete "
+ "remaining field value, preserving every unaffected fact.\n"
+)
+JSON_FULL_REMOVAL_RULE = (
+ "- For partial removal, rewrite the complete affected field with its "
+ "remaining value, preserving every unaffected fact.\n"
+)
+JSON_LINK_RULES = """
+## Link Rules
+- Link fields `f` and `t` must reference these page_id values.
+- Only create links when the relationship is meaningful and clear from the conversation. Do NOT force links between unrelated items.
+"""
diff --git a/openviking/session/memory/extraction_output_protocol/python_protocol.py b/openviking/session/memory/extraction_output_protocol/python_protocol.py
index 0b44a3dac..0bce203d6 100644
--- a/openviking/session/memory/extraction_output_protocol/python_protocol.py
+++ b/openviking/session/memory/extraction_output_protocol/python_protocol.py
@@ -14,7 +14,8 @@ from dataclasses import dataclass, field
from typing import Any, get_args, get_origin
from openviking.core.peer_id import safe_peer_id
-from openviking.session.memory.dataclass import MemoryFile, MemoryTypeSchema
+from openviking.session.memory.dataclass import MemoryField, MemoryFile, MemoryTypeSchema
+from openviking.session.memory.extraction_output_protocol import prompt_fragments as prompts
from openviking.session.memory.extraction_output_protocol.base import (
ExtractionOutputContext,
ExtractionOutputProtocol,
@@ -71,68 +72,6 @@ _SAFE_STRING_METHODS = {
# applied to the would-be result size before any allocation.
_MAX_EXPRESSION_SIZE = 1_000_000
_REPEATABLE_SEQUENCES = (str, bytes, list, tuple)
-_CONTRACT_PREAMBLE = (
- "## Output Format: restricted Python memory SDK",
- "Return only Python code, optionally wrapped in one ```python code fence.",
- "The code is interpreted as a restricted DSL and cannot access Python modules, files, or the network.",
- "The SDK is write-only. To inspect memories, call the native search/read tools before returning the program; never emit sdk.search(), sdk.read(), or sdk.existing() (only the system binds existing objects).",
- "Never return memory content as bare Markdown; all changes must be arguments to SDK calls.",
- "Existing objects shown by the system may use obj.update(field=value, ...) to set complete "
- "scalar/immutable fields, obj.delete(replacement=None),",
- "and, when links are enabled, obj.link(target, link_type='related_to', weight=0.5, match_text=None, description='').",
- "To change an existing string field, edit it through the object's field attribute. Use the "
- "real field name (e.g. content), NOT the literal word 'field':",
- " - obj.content.update(new_value): replace the whole field with a complete new string.",
- " - obj.content.edit(search=..., replace=...): replace one exact snippet in an editable string (merge_op=patch).",
- " - obj.content.drop(text=...): delete one exact snippet in an editable string (merge_op=patch).",
- "edit()/drop() may be chained, e.g. obj.content.edit(search='a', replace='b').drop(text='c'); do not mix them with .update() in one chain.",
- "A field attribute is a write handle only; you cannot read it as a string or call str methods on it.",
- "Each search= (and drop text=) MUST be copied verbatim from the current field value shown in the object's sdk.existing(...) binding, and must occur exactly once. If the snippet appears more than once, include an adjacent unique line just before or after it so the match is unique. Never use text from the conversation or the new facts you intend to add as a search anchor; that text is not in the current content and the edit will fail.",
- "edit()/drop() only work on an existing memory's editable string field (merge_op=patch); new memories from create/set must be given complete field values.",
- "For existing editable strings (merge_op=patch), prefer the smallest unique edit()/drop(). Do not rewrite the entire field just to add or change a few facts; large full-content rewrites are more likely to be truncated or malformed. Use obj.content.update() only when most of such an editable string changes. For string fields marked [replace], always pass the complete new value to obj.content.update(), even for a small change; edit()/drop() are unavailable.",
- 'ALWAYS use a triple-quoted string ("""...""") for EVERY natural-language argument '
- "(content, summary, goal, and every search=/replace=/text= snippet), even one-liners. "
- "Prose frequently contains apostrophes (e.g. Evan's), quotes, colons, or dates that break "
- 'single- or double-quoted literals. Inside triple quotes, escape any literal """ and '
- "backslash; never put a real newline inside a single- or double-quoted string.",
- "Only keyword arguments are accepted by create, set, and obj.update(); a field's update() takes one positional string.",
- "You may end the program with sdk.commit(); when present it must be the final call. If there are no changes, return only sdk.commit().",
- "Use the system-provided existing-object variable names exactly as shown. When a newly "
- "created memory must be referenced by delete(replacement=...) or link(...), assign the "
- "create call to a variable first, for example: canonical = sdk.create_<type>(...); "
- "duplicate_1.delete(replacement=canonical). Never recreate or rebind an existing object "
- "with sdk.existing().",
- "",
- "Available write methods for this extraction:",
-)
-
-_LINK_RULES = (
- "",
- "## Link Rules",
- "- Create links between memories when they have a meaningful and clear relationship "
- "(e.g. an event mentioning a person/entity, a preference about a place/activity). "
- "Do NOT force links between unrelated items.",
- "- Use obj.link(target, link_type='related_to', match_text='<word>') as a standalone "
- "statement after both objects exist.",
- "- match_text must be a single exact word that appears in the source object's content. "
- "It is where the link anchor is inserted. Choose the most specific identifying word "
- "(e.g. a person's name, a place, an activity).",
- "- link_type uses lowercase snake_case: related_to (default), belongs_to, "
- "derived_from, caused_by, contradicts, evolved_from.",
- "- For a newly created object, assign the create/set call to a variable first, then "
- "call .link() on it (see the preamble); existing objects use their provided variable names.",
- "- Links are optional; only create them when the relationship is explicit in the "
- "conversation. Do not link every memory to every other memory.",
- "",
- "Example — linking a newly created memory to another new one and to an existing binding "
- "(replace create_<type>/fields with methods and fields from the contract above):",
- "```python",
- "obj_a = sdk.create_<type_a>(...) # a new memory, assigned to a variable",
- "obj_b = sdk.create_<type_b>(...) # another new memory",
- 'obj_a.link(obj_b, link_type="related_to", match_text="<word_in_obj_a>")',
- 'obj_a.link(existing_1, link_type="related_to", match_text="<word_in_obj_a>")',
- "```",
-)
@dataclass(slots=True)
@@ -171,17 +110,48 @@ class PythonExtractionOutputProtocol(ExtractionOutputProtocol):
self._type_counts: dict[str, int] = {}
self._context_counts: dict[str, int] = {}
self._last_error_allows_tool_retry = False
+ self._inspection_tools: tuple[str, ...] = ()
+ self._supports_string_patch = False
+
+ def _capture_prompt_capabilities(self, context: ExtractionOutputContext) -> None:
+ """Keep retry guidance aligned even when parse runs without render_contract."""
+ self._inspection_tools = context.inspection_tools
+ self._supports_string_patch = context.supports_string_patch
def render_contract(self, context: ExtractionOutputContext) -> str:
_validate_alias_uniqueness(context.schemas)
- lines = list(_CONTRACT_PREAMBLE)
- for schema in context.schemas:
- lines.extend(self._render_schema_contract(context, schema))
- if not context.link_enabled:
- lines.append("Links are disabled; obj.link(...) is unavailable.")
- else:
- lines.extend(_LINK_RULES)
- return "\n".join(lines)
+ self._capture_prompt_capabilities(context)
+ schema_rules = (
+ line
+ for schema in context.schemas
+ for line in self._render_schema_contract(context, schema)
+ )
+ link_rules = (
+ prompts.PYTHON_LINK_RULES if context.link_enabled else prompts.PYTHON_LINKS_DISABLED
+ )
+ return "\n".join((*self._render_contract_preamble(context), *schema_rules, *link_rules))
+
+ @staticmethod
+ def _render_contract_preamble(context: ExtractionOutputContext) -> tuple[str, ...]:
+ if context.add_only:
+ return prompts.PYTHON_ADD_ONLY_PREAMBLE
+ inspection_rules = PythonExtractionOutputProtocol._render_inspection_rules(context)
+ patch_rules = prompts.PYTHON_PATCH_RULES if context.supports_string_patch else ()
+ return (
+ *prompts.PYTHON_UPSERT_PREAMBLE,
+ *inspection_rules,
+ *patch_rules,
+ *prompts.PYTHON_UPSERT_FOOTER,
+ )
+
+ @staticmethod
+ def _render_inspection_rules(context: ExtractionOutputContext) -> tuple[str, ...]:
+ if not context.inspection_tools:
+ return ()
+ return (
+ f"To inspect memories, call the available native {'/'.join(context.inspection_tools)} "
+ "tool before returning the program.",
+ )
def _render_schema_contract(
self, context: ExtractionOutputContext, schema: MemoryTypeSchema
@@ -211,14 +181,7 @@ class PythonExtractionOutputProtocol(ExtractionOutputProtocol):
lines.append(" - Memory type rules:\n" + str(schema_description).strip())
if verb == "set":
lines.extend(self._render_singleton_rules(context, schema, identity_fields))
- merge_ops = {
- field.name: (
- "editable string: obj.field.edit/drop/update"
- if field.merge_op == MergeOp.PATCH and field.field_type == FieldType.STRING
- else field.merge_op.value
- )
- for field in schema.fields
- }
+ merge_ops = {field.name: _field_write_mode(schema, field) for field in schema.fields}
schema_fields = {field.name: field for field in schema.fields}
for name, _type_name, description in fields:
if name in merge_ops:
@@ -243,56 +206,69 @@ class PythonExtractionOutputProtocol(ExtractionOutputProtocol):
identity_fields: tuple[str, ...],
) -> list[str]:
type_alias = _identifier_alias(schema.memory_type)
- lines = [
+ singleton_rule = (
f" - {type_alias} is a SINGLETON per identity: sdk.create_{type_alias}() "
f"does not exist, and sdk.set_{type_alias}() must appear AT MOST ONCE for each "
"identity in the whole program. Never call it twice for the same identity (e.g. the same "
"peer_id). If several people or sections belong to one identity, put them all as separate "
"H1 sections inside a SINGLE content argument of one call — different headings or person "
- "names do NOT create separate identities. To change an already-shown existing object, "
- "edit that object instead of calling set again."
+ "names do NOT create separate identities."
+ )
+ update_rule = (
+ "" if schema.operation_mode == "add_only" else prompts.PYTHON_SINGLETON_UPDATE_RULE
+ )
+ identity_rules = PythonExtractionOutputProtocol._render_singleton_identity_rules(
+ context, type_alias, identity_fields
+ )
+ return [f"{singleton_rule}{update_rule}", *identity_rules]
+
+ @staticmethod
+ def _render_singleton_identity_rules(
+ context: ExtractionOutputContext, type_alias: str, identity_fields: tuple[str, ...]
+ ) -> list[str]:
+ scope = context.role_scope
+ if scope is None or "peer_id" not in identity_fields:
+ return []
+ self_rules = (
+ [
+ f" - Current self identity: exactly one sdk.set_{type_alias}() call "
+ "without peer_id; combine all content sections into its single content argument."
+ ]
+ if scope.user_ids
+ else []
+ )
+ peer_rules = [
+ f" - Current identity peer_id={peer_id!r}: exactly one "
+ f"sdk.set_{type_alias}(peer_id={peer_id!r}, ...) call; combine every "
+ "person and section for this peer_id into that one content argument."
+ for peer_id in scope.peer_ids
]
- if "peer_id" in identity_fields and context.role_scope is not None:
- if context.role_scope.user_ids:
- lines.append(
- f" - Current self identity: exactly one sdk.set_{type_alias}() call "
- "without peer_id; combine all content sections into its single content argument."
- )
- for peer_id in context.role_scope.peer_ids:
- lines.append(
- f" - Current identity peer_id={peer_id!r}: exactly one "
- f"sdk.set_{type_alias}(peer_id={peer_id!r}, ...) call; combine every "
- "person and section for this peer_id into that one content argument."
- )
- return lines
+ return [*self_rules, *peer_rules]
def render_reference_rules(self, context: ExtractionOutputContext) -> str:
- del context
- return """
-## Memory Object Rules
-- Update or delete an existing memory only through its system-provided bound object; never pass or construct a URI.
-- Create collection memories with listed sdk.create_<memory_type>(...) methods.
-- Set a single-file memory with its listed sdk.set_<memory_type>(...) method; each target scope has only one such object.
-- Existing-object immutable fields are preserved by the system. URI identity fields may be
- updated when their schema allows it; changing one renames the memory object.
-- If a rename target already exists, do not rename over it. Read both objects, update the
- canonical target with every distinct fact, then delete the source with replacement=target.
-- delete() removes the whole object; use obj.content.drop(text=...) (with the real field name) when only some content must go and the rest stays.
-- For canonical merges, use duplicate.delete(replacement=canonical); for pure deletes, call delete() without replacement.
-- delete(replacement=canonical) discards the duplicate's content entirely and keeps only the canonical. Before deleting a duplicate, first fold every distinct valid fact it holds into the canonical (e.g. canonical.content.edit(...)); merging or compacting must never drop a unique fact that only the duplicate recorded.
-"""
+ if context.add_only:
+ return prompts.PYTHON_ADD_ONLY_REFERENCE_RULES
+ removal_rule = (
+ prompts.PYTHON_PATCH_REMOVAL_RULE
+ if context.supports_string_patch
+ else prompts.PYTHON_FULL_REMOVAL_RULE
+ )
+ return "".join((prompts.PYTHON_UPSERT_REFERENCE_RULES, removal_rule))
def parse(
self, content: str, context: ExtractionOutputContext
) -> tuple[Any | None, str | None]:
self._last_error_allows_tool_retry = False
+ self._capture_prompt_capabilities(context)
try:
code = _extract_python_code(content)
compiler = _PythonProgramCompiler(context=context, protocol=self)
operations = compiler.compile(code)
return operations, None
except ExtractionOutputProtocolError as exc:
- self._last_error_allows_tool_retry = exc.allow_tool_retry
+ self._last_error_allows_tool_retry = exc.allow_tool_retry and bool(
+ self._inspection_tools
+ )
return None, str(exc)
except Exception as exc:
return None, str(exc)
@@ -318,16 +294,22 @@ class PythonExtractionOutputProtocol(ExtractionOutputProtocol):
"`duplicate_1.delete(replacement=canonical)`."
)
if error and _is_string_literal_syntax_error(error):
+ argument_examples = (
+ "content, summary, goal, and every search=/replace=/text= snippet"
+ if self._supports_string_patch
+ else "content, summary, goal"
+ )
quote_guidance = (
" If the error is about a string literal, the offending line is shown above; a "
"quote or newline inside prose likely ended the string early. Rewrite every "
- "natural-language argument (content, summary, goal, and every search=/replace=/"
- 'text= snippet) as a triple-quoted string ("""...""") so embedded quotes and '
+ f"natural-language argument ({argument_examples}) as a triple-quoted string "
+ '("""...""") so embedded quotes and '
"newlines stay inside the literal."
)
if self.keep_tools_enabled_after_parse_error(error):
tool_guidance = (
- " The memory SDK is write-only. Call the available native search/read tool now; "
+ " The memory SDK is write-only. Call the available native "
+ f"{'/'.join(self._inspection_tools)} tool now; "
"after its result is returned, update the system-provided object variable. "
"Do not emit sdk.search(), sdk.read(), or construct a memory URI in Python."
)
@@ -1578,6 +1560,16 @@ def _visible_memory_fields(
return fields
+def _field_write_mode(schema: MemoryTypeSchema, memory_field: MemoryField) -> str:
+ """Describe only the string operations available for this schema field."""
+ if memory_field.field_type == FieldType.STRING:
+ if schema.operation_mode == "add_only":
+ return "complete string"
+ if memory_field.merge_op == MergeOp.PATCH:
+ return "editable string: obj.field.edit/drop/update"
+ return memory_field.merge_op.value
+
+
def _field_type_name(field_type: FieldType) -> str:
return {
FieldType.STRING: "str",
diff --git a/openviking/session/memory/memory_updater.py b/openviking/session/memory/memory_updater.py
index 591f42486..6247600d9 100644
--- a/openviking/session/memory/memory_updater.py
+++ b/openviking/session/memory/memory_updater.py
@@ -9,6 +9,7 @@ to the storage system.
from __future__ import annotations
+import hashlib
import re
from dataclasses import dataclass
from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple
@@ -217,6 +218,7 @@ class ExtractContext:
chunk_meta: Optional[Dict[int, ChunkMeta]] = None,
*,
split_long_text_messages: bool = True,
+ source_archive_uri: str = "",
):
if chunk_meta is None:
if split_long_text_messages:
@@ -227,6 +229,7 @@ class ExtractContext:
self.messages = messages
self.chunk_meta = chunk_meta
self.page_id_map = PageIdMap()
+ self.source_archive_uri = (source_archive_uri or "").rstrip("/")
@classmethod
def _build_extraction_messages(
@@ -405,6 +408,17 @@ class ExtractContext:
continue
return datetime.now().strftime("%Y%m%d%H%M%S")
+ def get_source_archive_suffix(self) -> str:
+ """Namespace filenames by their full source archive without exposing its path.
+
+ Keep legacy naming for callers outside session commits that have no archive.
+ The suffix is stable across retries, not a new random record identifier.
+ """
+ if not self.source_archive_uri:
+ return ""
+ digest = hashlib.sha256(self.source_archive_uri.encode("utf-8")).hexdigest()[:16]
+ return f"_{digest}"
+
def get_event_content(
self, ranges_str: str, summary: str | None, ratio_threshold: float = 0.2
) -> str:
diff --git a/openviking/session/memory/session_extract_context_provider.py b/openviking/session/memory/session_extract_context_provider.py
index 8fa4f2612..ef3020e60 100644
--- a/openviking/session/memory/session_extract_context_provider.py
+++ b/openviking/session/memory/session_extract_context_provider.py
@@ -69,9 +69,12 @@ class SessionExtractContextProvider(ExtractContextProvider):
transaction_handle=None,
memory_registry: MemoryTypeRegistry | None = None,
vlm_config: Optional["VLMHandle"] = None,
+ *,
+ source_archive_uri: str = "",
):
self.messages = list(messages) if isinstance(messages, list) else messages
self.latest_archive_overview = latest_archive_overview
+ self._source_archive_uri = source_archive_uri
self._output_language = self._detect_language()
self._registry = memory_registry # Lazy defaults if no account snapshot was supplied.
self._schema_directories = None
@@ -115,6 +118,7 @@ class SessionExtractContextProvider(ExtractContextProvider):
self._extract_context = ExtractContext(
self.messages if isinstance(self.messages, list) else [],
split_long_text_messages=self.split_long_text_messages_for_extraction,
+ source_archive_uri=self._source_archive_uri,
)
return self._extract_context
diff --git a/openviking/session/train/components/rollout_artifact_recorder.py b/openviking/session/train/components/rollout_artifact_recorder.py
index 39f0d209e..f6e6f97d7 100644
--- a/openviking/session/train/components/rollout_artifact_recorder.py
+++ b/openviking/session/train/components/rollout_artifact_recorder.py
@@ -831,22 +831,12 @@ def _safe_fragment(value: Any) -> str:
def _build_commit_messages(rollout: Rollout) -> list[dict[str, Any]]:
- """Build the full message list as sent to session.commit.
-
- Matches the message assembly in session_commit._commit_one:
- [case_spec] + rollout.messages + [evaluation]
- """
+ """Record exactly the normalized message list sent to session.commit."""
from openviking.session.train.components.session_commit import (
- _case_spec_message_to_request,
- _evaluation_message_to_request,
- _message_to_request,
+ _build_commit_messages as build_commit_messages,
)
- messages: list[dict[str, Any]] = [_case_spec_message_to_request(rollout)]
- for msg in rollout.messages:
- messages.append(_message_to_request(msg))
- messages.append(_evaluation_message_to_request(rollout))
- return messages
+ return build_commit_messages(rollout)
def _format_commit_messages_markdown(messages: list[dict[str, Any]]) -> str:
diff --git a/openviking/session/train/components/session_commit.py b/openviking/session/train/components/session_commit.py
index b2a003cf1..563893ef3 100644
--- a/openviking/session/train/components/session_commit.py
+++ b/openviking/session/train/components/session_commit.py
@@ -84,8 +84,7 @@ class SessionCommitPolicyTrainer:
label="train_start",
enabled=self.show_progress,
description=(
- f"Processing {len(rollout_list)} rollouts, "
- f"concurrency={self.commit_concurrency}"
+ f"Processing {len(rollout_list)} rollouts, concurrency={self.commit_concurrency}"
),
concurrency=self.commit_concurrency,
)
@@ -126,11 +125,7 @@ class SessionCommitPolicyTrainer:
session_id = _session_id_for_rollout(rollout, run_id=self.run_id)
stage = "prepare_messages"
try:
- messages = (
- [_case_spec_message_to_request(rollout)]
- + [_message_to_request(message) for message in rollout.messages]
- + [_evaluation_message_to_request(rollout)]
- )
+ messages = _build_commit_messages(rollout)
stage = "create_session"
await self.client.create_session(
session_id=session_id,
@@ -232,7 +227,6 @@ class SessionCommitPolicyTrainer:
"error": str(exc),
}
-
async def _record_event(
self,
event: str,
@@ -370,6 +364,7 @@ def _rollout_score(rollout: Rollout) -> float:
return 0.0
return float(rollout.evaluation.score)
+
def _task_error(task: dict[str, Any] | None) -> str | None:
if task is None:
return None
@@ -495,6 +490,68 @@ def _case_input_payload(case_input: dict[str, Any]) -> dict[str, Any]:
return {key: case_input[key] for key in allowed_keys if key in case_input}
+def _build_commit_messages(rollout: Rollout) -> list[dict[str, Any]]:
+ """Build the extraction input without changing the original rollout/evaluation."""
+ return (
+ [_case_spec_message_to_request(rollout)]
+ + [
+ _message_to_request(message)
+ for message in rollout.messages
+ if not _is_duplicate_tau2_reward_message(message, rollout.evaluation)
+ ]
+ + [_evaluation_message_to_request(rollout)]
+ )
+
+
+def _is_evaluation_report_copy(text: str, report: Any) -> bool:
+ """Match full JSON report copies, not additional feedback or partial evidence."""
+ if not isinstance(report, (dict, list)):
+ return False
+ try:
+ parsed = json.loads(text)
+ except (TypeError, ValueError):
+ return False
+ # Ignore JSON whitespace/key order, but do not conflate booleans with numbers.
+ return json.dumps(parsed, sort_keys=True) == json.dumps(report, sort_keys=True)
+
+
+def _without_evaluation_report_copies(values: list[str], report: Any) -> list[str]:
+ return [value for value in values if not _is_evaluation_report_copy(value, report)]
+
+
+def _is_duplicate_tau2_reward_message(message: Any, evaluation: RubricEvaluation | None) -> bool:
+ """Drop only the known Tau2 wrapper when every fact is in OutcomeEvaluation."""
+ if (
+ evaluation is None
+ or getattr(message, "id", "") != "tau2-reward"
+ or message.role != "user"
+ or len(message.parts) != 1
+ or getattr(message.parts[0], "type", None) != "text"
+ ):
+ return False
+ lines = message.parts[0].text.split("\n", 2)
+ if (
+ len(lines) != 3
+ or lines[0] != f"task_success: {evaluation.passed}"
+ or not lines[1].startswith("task_reward: ")
+ or not lines[2].startswith("evaluation report: ")
+ ):
+ return False
+ try:
+ reward = json.loads(lines[1].removeprefix("task_reward: "))
+ except ValueError:
+ return False
+ return (
+ isinstance(reward, (int, float))
+ and not isinstance(reward, bool)
+ and reward == evaluation.score
+ and _is_evaluation_report_copy(
+ lines[2].removeprefix("evaluation report: "),
+ evaluation.metadata.get("evaluation_result"),
+ )
+ )
+
+
def _evaluation_message_to_request(rollout: Rollout) -> dict[str, Any]:
text = (
"# OpenViking OutcomeEvaluation\n\n"
@@ -521,21 +578,27 @@ def _evaluation_payload_json(rollout: Rollout) -> str:
def _evaluation_payload(evaluation: RubricEvaluation | None) -> dict[str, Any] | None:
if evaluation is None:
return None
- return {
- "passed": evaluation.passed,
- "score": evaluation.score,
- "feedback": evaluation.feedback,
- "criterion_results": [
+ report = evaluation.metadata.get("evaluation_result")
+ criteria = []
+ for result in evaluation.criterion_results:
+ evidence = _without_evaluation_report_copies(result.evidence, report)
+ if len(evidence) < len(result.evidence):
+ evidence.append("See evaluation.metadata.evaluation_result.")
+ criteria.append(
{
"criterion_name": result.criterion_name,
"passed": result.passed,
"score": result.score,
- "feedback": result.feedback,
- "evidence": result.evidence,
+ "feedback": _without_evaluation_report_copies(result.feedback, report),
+ "evidence": evidence,
"metadata": result.metadata,
}
- for result in evaluation.criterion_results
- ],
+ )
+ return {
+ "passed": evaluation.passed,
+ "score": evaluation.score,
+ "feedback": _without_evaluation_report_copies(evaluation.feedback, report),
+ "criterion_results": criteria,
"metadata": evaluation.metadata,
}
diff --git a/openviking/session/train/components/trajectory_analyzer.py b/openviking/session/train/components/trajectory_analyzer.py
index a758d5e14..6066d670b 100644
--- a/openviking/session/train/components/trajectory_analyzer.py
+++ b/openviking/session/train/components/trajectory_analyzer.py
@@ -168,8 +168,7 @@ class TrajectoryRolloutAnalyzer:
if self.vlm is None:
if self.vlm_resolver is None:
raise RuntimeError(
- "TrajectoryRolloutAnalyzer requires a VLM resolver "
- "for account-owned work"
+ "TrajectoryRolloutAnalyzer requires a VLM resolver for account-owned work"
)
vlm_config = await self.vlm_resolver.get_vlm(ctx.account_id)
@@ -179,6 +178,7 @@ class TrajectoryRolloutAnalyzer:
include_trajectories=include_trajectories,
include_session_skills=include_session_skills,
vlm_config=vlm_config,
+ source_archive_uri=source_archive_uri,
)
consumed_experience_uris = collect_read_experience_uris(messages, ctx=ctx)
phase_result = await self._run_trajectory_extract_phase(
diff --git a/tests/session/memory/test_agent_experience_context_provider.py b/tests/session/memory/test_agent_experience_context_provider.py
index c17a6bd85..1a0660c66 100644
--- a/tests/session/memory/test_agent_experience_context_provider.py
+++ b/tests/session/memory/test_agent_experience_context_provider.py
@@ -6,6 +6,8 @@ from unittest.mock import AsyncMock, patch
import pytest
+from openviking.message import Message
+from openviking.message.part import TextPart
from openviking.server.identity import RequestContext, Role
from openviking.session.memory.agent_experience_context_provider import (
AgentExperienceContextProvider,
@@ -13,13 +15,13 @@ from openviking.session.memory.agent_experience_context_provider import (
from openviking.session.memory.agent_trajectory_context_provider import (
AgentTrajectoryContextProvider,
)
+from openviking.session.memory.dataclass import MemoryFile
from openviking.session.memory.memory_isolation_handler import MemoryIsolationHandler
from openviking.session.memory.memory_updater import ExtractContext
from openviking.session.memory.session_extract_context_provider import (
SessionExtractContextProvider,
)
-from openviking.message import Message
-from openviking.message.part import TextPart
+from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
from openviking_cli.session.user_id import UserIdentifier
@@ -112,6 +114,8 @@ async def test_agent_experience_prefetch_starts_with_conversation_and_new_trajec
@pytest.mark.asyncio
async def test_agent_experience_prefetch_includes_structured_read_results():
+ experience_uri = "viking://user/user_sample_9/memories/experiences/personal_experience_sharing_conversation_flow.md"
+ source_uri = "viking://user/user_sample_9/memories/trajectories/previous_discussion.md"
provider = AgentExperienceContextProvider(
messages=[],
trajectory_summary="album release party discussion",
@@ -124,11 +128,25 @@ async def test_agent_experience_prefetch_includes_structured_read_results():
provider._viking_fs = AsyncMock()
provider._transaction_handle = None
- provider.search_files = AsyncMock(
- return_value=[
- "viking://user/user_sample_9/memories/experiences/personal_experience_sharing_conversation_flow.md"
- ]
+ provider.search_files = AsyncMock(return_value=[experience_uri])
+ source = MemoryFile(
+ uri=source_uri,
+ memory_type="trajectories",
+ content="# Previous discussion\nComplete procedure and failure evidence.",
+ backlinks=[{"from_uri": experience_uri, "link_type": "derived_from"}],
+ extra_fields={
+ "trajectory_name": "previous_discussion",
+ "outcome": "success",
+ "task_query": "Discuss the album release party.",
+ "retrieval_anchor": "Stage: final_response; Boundary: completed discussion.",
+ "case_name": "discussion_case",
+ "source_archive_uri": "viking://session/previous/archive/001",
+ "last_update_trace_id": "source-trace-id",
+ "version": 3,
+ },
)
+ stored_source = MemoryFileUtils.write(source)
+ provider._viking_fs.read_file.return_value = stored_source
read_result = {
"experience_name": "personal_experience_sharing_conversation_flow",
@@ -138,10 +156,10 @@ async def test_agent_experience_prefetch_includes_structured_read_results():
}
provider.read_file = AsyncMock(return_value=read_result)
provider._read_file_contents = {
- "viking://user/user_sample_9/memories/experiences/personal_experience_sharing_conversation_flow.md": SimpleNamespace(
+ experience_uri: SimpleNamespace(
extra_fields={"experience_name": "personal_experience_sharing_conversation_flow"},
content="line one\nline two",
- links=[],
+ links=[{"to_uri": source_uri, "link_type": "derived_from"}],
)
}
@@ -151,12 +169,31 @@ async def test_agent_experience_prefetch_includes_structured_read_results():
messages = await provider.prefetch()
assert any(msg.get("role") == "user" for msg in messages)
- assert add_tool_call_pair.call_count == 2
+ assert add_tool_call_pair.call_count == 3
assert (
add_tool_call_pair.call_args_list[1].kwargs["result"]["context_role"]
== "candidate_experience"
)
assert add_tool_call_pair.call_args_list[1].kwargs["result"]["page_id"] == 1
+ assert add_tool_call_pair.call_args_list[1].kwargs["result"] == {
+ **read_result,
+ "uri": experience_uri,
+ "context_role": "candidate_experience",
+ }
+ source_result = add_tool_call_pair.call_args_list[2].kwargs["result"]
+ assert source_result == {
+ "trajectory_name": source.extra_fields["trajectory_name"],
+ "outcome": source.extra_fields["outcome"],
+ "task_query": source.extra_fields["task_query"],
+ "retrieval_anchor": source.extra_fields["retrieval_anchor"],
+ "case_name": source.extra_fields["case_name"],
+ "memory_type": "trajectories",
+ "content": source.content,
+ "uri": source_uri,
+ "context_role": "candidate_source_trajectory",
+ }
+ assert MemoryFileUtils.read(stored_source, uri=source_uri).to_metadata() == source.to_metadata()
+ provider._viking_fs.write_file.assert_not_awaited()
@pytest.mark.asyncio
@@ -177,11 +214,14 @@ async def test_agent_experience_prefetch_missing_experience_dir_returns_empty_ca
provider._transaction_handle = None
provider.search_files = AsyncMock(return_value=[])
- with patch(
- "openviking.session.memory.agent_experience_context_provider.tracer.error"
- ) as tracer_error, patch(
- "openviking.session.memory.agent_experience_context_provider.add_tool_call_pair_to_messages"
- ) as add_tool_call_pair:
+ with (
+ patch(
+ "openviking.session.memory.agent_experience_context_provider.tracer.error"
+ ) as tracer_error,
+ patch(
+ "openviking.session.memory.agent_experience_context_provider.add_tool_call_pair_to_messages"
+ ) as add_tool_call_pair,
+ ):
messages = await provider.prefetch()
assert messages[-1]["role"] == "user"
diff --git a/tests/session/memory/test_extraction_output_protocol.py b/tests/session/memory/test_extraction_output_protocol.py
index 95ddce247..07e67d1af 100644
--- a/tests/session/memory/test_extraction_output_protocol.py
+++ b/tests/session/memory/test_extraction_output_protocol.py
@@ -239,6 +239,8 @@ def test_python_contract_includes_link_rules_when_enabled():
assert "## Link Rules" in contract
assert "obj.link(target" in contract
+ assert "weight=0.5" in contract
+ assert "description=''" in contract
assert "match_text" in contract
assert "obj_a.link(" in contract
assert "assign the create/set call to a variable first" in contract
@@ -280,12 +282,64 @@ def test_python_field_description_keeps_dsl_patch_instructions():
schema.fields[1].description = "Write content in {{ language.upper() }}."
context = _context([schema], template_context={"language": "en"})
- contract = create_extraction_output_protocol("python").render_contract(context)
+ protocol = create_extraction_output_protocol("python")
+ contract = protocol.render_contract(context)
assert "content [editable string: obj.field.edit/drop/update]: Write content in EN." in contract
assert "obj.content.edit(search=..., replace=...)" in contract
assert "PATCH operation for" not in contract
assert "Use a DELETE block" not in contract
+ assert "copied verbatim" in contract
+ assert "occur exactly once" in contract
+ assert "## Patch Context Rules" in protocol.render_context_rules(context)
+
+
[email protected]("output_format", ["python", "json"])
+def test_output_contract_preserves_core_add_only_and_upsert_capabilities(output_format):
+ context = _context([_preference_schema(operation_mode="add_only")], available_tools=())
+ protocol = create_extraction_output_protocol(output_format)
+ contract = protocol.render_contract(context)
+ rules = protocol.render_reference_rules(context)
+ assert "Create new memories only, with complete field values" in contract + rules
+ assert protocol.render_context_rules(context) == ""
+ for unsupported in (
+ "obj.update",
+ "obj.content.edit",
+ "obj.content.drop",
+ "replacement=",
+ ):
+ assert unsupported not in contract + rules + protocol.render_final_instruction(context)
+ assert "delete_ids" not in rules + protocol.render_final_instruction(context)
+
+ program = (
+ 'sdk.create_preferences(topic="editor", content="""Use Vim""", score=1)\nsdk.commit()'
+ if output_format == "python"
+ else '{"preferences": [{"page_id": 100, "topic": "editor", "content": "Use Vim", "score": 1}]}'
+ )
+ operations, error = protocol.parse(program, context)
+ assert error is None
+ assert operations.preferences[0].content == "Use Vim"
+
+ # A mixed batch must retain upsert/delete support, without teaching patches
+ # from an add-only schema or exposing inspection tools it does not have.
+ mixed = _context(
+ [_preference_schema(operation_mode="add_only"), _project_schema()], available_tools=()
+ )
+ rules = protocol.render_reference_rules(mixed)
+ contract = protocol.render_contract(mixed)
+ assert "replacement" in rules
+ assert "preserving every unaffected fact" in rules
+ assert protocol.render_context_rules(mixed) == ""
+ if output_format == "python":
+ assert "obj.content.update(" in contract
+ assert "obj.delete(replacement=None)" in contract
+ assert "obj.content.edit" not in contract
+ assert "obj.content.drop" not in contract
+ assert "call the available native" not in contract.lower()
+ assert "never drop a unique fact" in rules
+ else:
+ assert "When editing an existing item" in rules
+ assert "DELETE blocks" not in rules
@pytest.mark.asyncio
@@ -323,6 +377,8 @@ async def test_default_python_extract_loop_passes_language_to_field_descriptions
assert f"Preferences in {language}." in prompt
assert f"Write content in {language}." in prompt
assert "{{ language }}" not in prompt
+ assert "## Read Format Rules" not in prompt
+ assert "## Patch Context Rules" in prompt
def test_python_contract_omits_link_rules_when_disabled():
@@ -1189,6 +1245,13 @@ def test_python_builtin_content_edit_respects_merge_op_and_offers_valid_repair(m
assert operations is not None
assert operations.model_dump()[memory_type][0]["content"]["blocks"]
else:
+ contract = protocol.render_contract(context)
+ rules = protocol.render_reference_rules(context)
+ assert "obj.content.update(" in contract
+ assert "obj.content.edit(" not in contract
+ assert "obj.content.drop(" not in contract
+ assert "delete(replacement=canonical)" in rules
+ assert "never drop a unique fact" in rules
assert operations is None
assert error is not None
assert "merge_op=replace" in error
@@ -1599,7 +1662,7 @@ def test_python_read_search_errors_keep_native_tools_available_for_retry(
assert error_fragment in error
assert protocol.keep_tools_enabled_after_parse_error(error)
retry = protocol.render_format_retry(error)
- assert "native search/read tool" in retry
+ assert "native read tool" in retry
assert "Do not emit sdk.search(), sdk.read()" in retry
diff --git a/tests/session/memory/test_memory_react.py b/tests/session/memory/test_memory_react.py
index 4b52b444f..6b79d3331 100644
--- a/tests/session/memory/test_memory_react.py
+++ b/tests/session/memory/test_memory_react.py
@@ -824,8 +824,9 @@ class TestExtractLoopFinalJsonRetry:
initial_system_prompt = system_prompts[0]
assert "`delete_ids` deletes the whole item" in initial_system_prompt
assert "only if every substantive fact is in scope" in initial_system_prompt
- assert "otherwise MUST use DELETE blocks" in initial_system_prompt
- assert "not inferring scope from the file name/topic" in initial_system_prompt
+ assert "rewrite the complete affected field" in initial_system_prompt
+ assert "DELETE blocks" not in initial_system_prompt
+ assert "never infer scope from the file name/topic" in initial_system_prompt
@pytest.mark.asyncio
async def test_python_protocol_retries_then_raises_on_empty_response(self):
diff --git a/tests/session/train/test_train_framework.py b/tests/session/train/test_train_framework.py
index 655f94fdc..a45964b08 100644
--- a/tests/session/train/test_train_framework.py
+++ b/tests/session/train/test_train_framework.py
@@ -4,6 +4,7 @@
from __future__ import annotations
import asyncio
+import copy
import json
from dataclasses import dataclass, field
from pathlib import Path
@@ -16,6 +17,7 @@ from openviking.message import Message, TextPart
from openviking.session.memory.dataclass import StoredLink
from openviking.session.train import (
Case,
+ CriterionResult,
Experience,
ExperienceSet,
ListCaseLoader,
@@ -1228,6 +1230,9 @@ class FakeSessionCommitClient:
@pytest.mark.asyncio
async def test_session_commit_policy_trainer_records_commit_trace_id():
from openviking.session.train import SessionCommitPolicyTrainer
+ from openviking.session.train.components.rollout_artifact_recorder import (
+ _build_commit_messages,
+ )
client = FakeSessionCommitClient()
trainer = SessionCommitPolicyTrainer(
@@ -1244,6 +1249,40 @@ async def test_session_commit_policy_trainer_records_commit_trace_id():
evaluation=RubricEvaluation(passed=True, score=1.0, criterion_results=[], feedback=[]),
metadata={"data_split": "unit", "task_no": 7, "execution_metadata": {"epoch": 3}},
)
+ report = {
+ "reward": 1.0,
+ "action_checks": [
+ {"action": {"name": "cancel", "arguments": {"id": "r1"}}, "action_match": True}
+ ],
+ "db_check": {"db_match": True},
+ "info": {"note": "reservation cancelled"},
+ }
+ raw_report = json.dumps(report)
+ rollout.evaluation.metadata["evaluation_result"] = report
+ rollout.evaluation.feedback = [raw_report, "Distinct evaluator feedback."]
+ rollout.evaluation.criterion_results = [
+ CriterionResult(
+ criterion_name="tau2_reward",
+ passed=True,
+ score=1.0,
+ feedback=[raw_report, "Action verified."],
+ evidence=[json.dumps(report, indent=2), "Independent evidence."],
+ )
+ ]
+ rollout.messages.append(
+ Message(
+ id="tau2-reward",
+ role="user",
+ parts=[
+ TextPart(
+ text=f"task_success: True\ntask_reward: 1.0\nevaluation report: {raw_report}"
+ )
+ ],
+ )
+ )
+ for message in rollout.messages:
+ message.created_at = "2026-10-12T12:00:00+00:00"
+ original = copy.deepcopy(rollout)
result = await trainer.train_rollouts([rollout], _policy_set())
@@ -1264,6 +1303,28 @@ async def test_session_commit_policy_trainer_records_commit_trace_id():
},
)
]
+ submitted = client.messages[commit_result["session_id"]]
+ assert submitted == _build_commit_messages(rollout)
+ assert len(submitted) == 3 # CaseSpec, conversation, one OutcomeEvaluation.
+ payload = json.loads(
+ submitted[-1]["parts"][0]["text"].split("```json\n", 1)[1].rsplit("```", 1)[0]
+ )["evaluation"]
+ assert payload["metadata"]["evaluation_result"] == report
+ assert payload["feedback"] == ["Distinct evaluator feedback."]
+ assert payload["criterion_results"][0]["feedback"] == ["Action verified."]
+ assert payload["criterion_results"][0]["evidence"] == [
+ "Independent evidence.",
+ "See evaluation.metadata.evaluation_result.",
+ ]
+ assert rollout == original
+
+ # Additional information is not a duplicate: keep the complete reward
+ # message rather than dropping details not present in the canonical report.
+ rollout.messages[-1].parts[0].text += "\nAdditional failure detail."
+ assert (
+ _build_commit_messages(rollout)[-2]["parts"][0]["text"]
+ == rollout.messages[-1].parts[0].text
+ )
@pytest.mark.asyncio
diff --git a/tests/session/train/test_trajectory_analyzer_component.py b/tests/session/train/test_trajectory_analyzer_component.py
index 4bfcddae4..fe9e13842 100644
--- a/tests/session/train/test_trajectory_analyzer_component.py
+++ b/tests/session/train/test_trajectory_analyzer_component.py
@@ -3,12 +3,14 @@
from __future__ import annotations
+import hashlib
from types import SimpleNamespace
import pytest
from openviking.message import Message, TextPart, ToolPart
from openviking.session.memory.dataclass import ResolvedOperation, ResolvedOperations
+from openviking.session.memory.utils import generate_uri
from openviking.session.train import (
Case,
CriterionResult,
@@ -57,6 +59,21 @@ class FakeExtractLoop:
FakeExtractLoop.created.append(self)
async def run(self):
+ provider = self.kwargs["context_provider"]
+ # Exercise context rebuilding before rendering filenames: provenance
+ # must survive message preparation as well as initial construction.
+ await provider.prepare_extraction_messages()
+ schema = next(
+ schema
+ for schema in provider.get_memory_schemas(self.kwargs["ctx"])
+ if schema.memory_type == "trajectories"
+ )
+ uri = generate_uri(
+ schema,
+ {"trajectory_name": "task"},
+ user_space="u",
+ extract_context=provider.get_extract_context(),
+ )
return (
ResolvedOperations(
upsert_operations=[
@@ -69,7 +86,7 @@ class FakeExtractLoop:
"content": "# task\nbody",
},
memory_type="trajectories",
- uris=["viking://user/u/memories/trajectories/task_20260607120000.md"],
+ uris=[uri],
page_id=100,
)
],
@@ -217,13 +234,16 @@ async def test_trajectory_rollout_analyzer_extracts_and_persists_trajectory(monk
created_loop = FakeExtractLoop.created[0]
assert created_loop._transaction_handle is None
provider = created_loop.kwargs["context_provider"]
+ assert provider.get_extract_context().source_archive_uri == context.source_archive_uri
assert provider._transaction_handle is None
assert provider._vlm_config is account_vlm
assert [
schema.memory_type for schema in provider.get_memory_schemas(context.request_context)
] == ["trajectories"]
assert len(fs.writes) == 1
- assert fs.writes[0][0] == "viking://user/u/memories/trajectories/task_20260607120000.md"
+ archive_digest = hashlib.sha256(context.source_archive_uri.encode("utf-8")).hexdigest()[:16]
+ expected_uri = f"viking://user/u/memories/trajectories/task_20260607120000_{archive_digest}.md"
+ assert fs.writes[0][0] == expected_uri
assert '"case_name": "case"' in fs.writes[0][1]
assert (
'"source_archive_uri": "viking://user/u/sessions/s1/history/archive_001"' in fs.writes[0][1]
@@ -236,12 +256,31 @@ async def test_trajectory_rollout_analyzer_extracts_and_persists_trajectory(monk
assert len(analysis.trajectories) == 1
traj = analysis.trajectories[0]
assert traj.name == "task"
+ assert traj.uri == expected_uri
assert traj.outcome == "success"
assert traj.retrieval_anchor == "Stage: final"
assert traj.metadata["case_name"] == "case"
assert analysis.evaluation.passed is True
assert analysis.metadata["policy_snapshot_id"] == "snapshot"
+ # Replaying the same source keeps its filename; another session/archive
+ # must not collide even when the task name and business timestamp are equal.
+ repeated = await analyzer.analyze(rollout, context)
+ assert repeated.trajectories[0].uri == expected_uri
+ for source_archive_uri in (
+ "viking://user/u/sessions/s2/history/archive_001",
+ "viking://user/u/sessions/s1/history/archive_002",
+ ):
+ other = await analyzer.analyze(
+ rollout,
+ TrajectoryAnalyzerContext(
+ request_context=context.request_context,
+ source_archive_uri=source_archive_uri,
+ ),
+ )
+ assert other.trajectories[0].uri != expected_uri
+ assert other.trajectories[0].content == traj.content
+
@pytest.mark.asyncio
async def test_trajectory_rollout_analyzer_extracts_skill_without_persisting_trajectory(
diff --git a/tests/unit/session/memory/test_extract_loop_match_text.py b/tests/unit/session/memory/test_extract_loop_match_text.py
index 53fbad82e..18a529499 100644
--- a/tests/unit/session/memory/test_extract_loop_match_text.py
+++ b/tests/unit/session/memory/test_extract_loop_match_text.py
@@ -1208,18 +1208,21 @@ class TestPageIdInstruction:
system_content = loop._call_llm.await_args.args[0][0]["content"]
assert "## Page ID Rules" in system_content
- assert "## Read Format Rules" in system_content
+ assert "## Read Format Rules" not in system_content
assert 'Every memory item you create or edit MUST include "page_id".' in system_content
assert (
"The read tool accepts `uri`, optional `offset` (0-indexed), and optional `limit`."
- in system_content
+ not in system_content
)
- assert "each visible line is prefixed with `line_number<TAB>`" in system_content
+ assert "each visible line is prefixed with `line_number<TAB>`" not in system_content
assert (
"Never include the line-number prefix itself in `search`, `replace`, or `delete`."
+ not in system_content
+ )
+ assert (
+ "For existing items, use the page_id shown in the supplied memory context."
in system_content
)
- assert "For existing items, use the page_id shown in read/search results." in system_content
assert "For new items, assign a unique page_id >= 100." in system_content
assert "When editing an existing item, reuse its existing page_id." in system_content
assert "Link fields" not in system_content
@@ -1283,10 +1286,10 @@ class TestPageIdInstruction:
system_content = loop._call_llm.await_args.args[0][0]["content"]
assert "## Page ID Rules" in system_content
- assert "## Read Format Rules" in system_content
+ assert "## Read Format Rules" not in system_content
assert "## Link Rules" in system_content
assert "Link fields `f` and `t` must reference these page_id values." in system_content
- assert "each visible line is prefixed with `line_number<TAB>`" in system_content
+ assert "each visible line is prefixed with `line_number<TAB>`" not in system_content
assert "Only create links when the relationship is meaningful" in system_content