ov-experience-memory ยท diff
v2026.7.9 to git:20260811.00f3738
91 added, 131 removed. Audit A to A.
---
name: ov-experience-memory
- description: >
- Use OpenViking experience memories during task execution. Search relevant
- experiences with search_experience, read selected experiences with
- read_experience, and leave standard tool parts in the committed session so
- OpenViking can report recall and injection usage.
- version: 2026.7.9
- tags:
- - openviking
- - experience-memory
- - agent-memory
- - usage-reporting
+ description: Retrieve and apply OpenViking Experience memories through the Agent runtime's generic OpenViking search and read tools. Use before or during executable, multi-step, or tool-based work such as coding, file or data changes, configuration, deployment, workflow execution, and failure recovery when prior operational guidance could improve reliability. Do not use for casual chat or simple factual questions.
---
# OpenViking Experience Memory
- Use this skill when the current user request starts or continues an executable
- task, especially tasks involving tools, files, code changes, data operations,
- workflow decisions, or multi-step actions.
-
- Do not use this skill for casual chat, pure explanation, or one-off factual Q&A
- that does not require operational guidance.
-
- ## Runtime Contract
-
- The agent runtime must expose two tools with these exact names:
-
- - `search_experience`
- - `read_experience`
-
- OpenViking usage reporting recognizes only completed tool parts with these exact
- tool names. Calls to generic `find`, `search`, `read`, `ov_search`, or `ov_read`
- do not count as experience recall or injection events.
-
- ## Tool: search_experience
-
- Purpose: search reusable execution experiences from the OpenViking experience
- library before assembling task context.
-
- Input schema:
-
- ```json
- {
- "query": "string",
- "limit": 5
- }
- ```
-
- Output schema:
-
- ```json
- {
- "results": [
- {
- "uri": "viking://user/<current_user_id>/memories/experiences/example.md",
- "title": "example",
- "score": 0.82,
- "snippet": "Short summary or matched situation"
- }
- ]
- }
- ```
-
- Implementation:
-
- The runtime tool calls OpenViking `POST /api/v1/search/find` with `target_uri`
- fixed to the current-user shorthand `viking://user/memories/experiences/`.
- Callers provide only `query` and optional `limit`; they cannot override or pass
- `target_uri`. OpenViking resolves the fixed shorthand against the authenticated
- request user. Return only canonical experience memory URIs for that user; never
- hardcode `default` or another user ID.
-
- Usage reporting:
-
- A completed `search_experience` tool part is counted as an experience recall
- event for every `results[].uri` value.
-
- ## Tool: read_experience
+ Use prior task Experience as advisory operational guidance. Keep the current
+ user request, current environment, and verified tool results authoritative.
+ Experience retrieval supplements normal context retrieval; it does not replace
+ user memory, events, preferences, session archives, resources, or Agent Skills.
- Purpose: read the full Markdown body of a selected experience and inject it into
- the agent prompt as task execution guidance.
+ ## Preconditions
- Input schema:
+ - Use only OpenViking tools that are actually registered in the current Agent
+ runtime.
+ - Require both a semantic search capability and an exact URI read capability.
+ - If either capability is unavailable, continue without Experience. Do not
+ invent a tool call, fabricate a ToolPart, or replace the Agent tool call with
+ direct HTTP or CLI access.
+ - Do not substitute broad memory `recall` for a search scoped to the Experience
+ root. Continue using the runtime's normal recall and retrieval flows when the
+ task also needs user facts, events, decisions, prior conversation, or domain
+ resources.
- ```json
- {
- "uri": "viking://user/<current_user_id>/memories/experiences/example.md"
- }
- ```
+ ## Select Runtime Tools
- Output schema:
+ Choose the registered names that match the current runtime:
- ```json
- {
- "uri": "viking://user/<current_user_id>/memories/experiences/example.md",
- "content": "Experience Markdown body"
- }
- ```
+ | Runtime | Search | Read |
+ | --- | --- | --- |
+ | OpenViking MCP, Codex, Claude Code | `find` or `search` | `read` |
+ | OpenCode | `openviking_find` or `openviking_search` | `openviking_read` |
+ | OpenClaw | `ov_search` | `ov_read` or `ov_multi_read` |
- Implementation:
+ The host may display MCP names with a namespace such as
+ `mcp__openviking__find`. Use the exact registered name and schema shown by the
+ runtime. Prefer `find` for a fast task-start lookup and `search` when session
+ context or deeper intent analysis is useful.
- Call OpenViking `GET /api/v1/content/read?uri=<encoded_uri>` for the selected
- experience URI. Always pass the canonical URI returned by `search_experience`;
- do not construct a URI with a hardcoded user ID. The returned content should be
- inserted into the prompt as operational guidance, not as user profile facts.
+ ## Retrieval Workflow
- Usage reporting:
+ 1. Decide whether the request is an executable task. Retrieve Experience for
+ planning, tool use, environment changes, multi-step workflows, or recovery
+ from a failed attempt. Skip retrieval for casual conversation and simple
+ knowledge answers.
+ 2. Build one concise query containing the task goal, domain object, intended
+ operation, and important constraints. After a failure, include the failed
+ operation and stable error signature.
+ 3. Search only the current user's Experience root:
- A completed `read_experience` tool part is counted as an experience injection
- event for `tool_input.uri` or `tool_output.uri`. In this design, reading an
- experience through `read_experience` means the experience was injected into the
- prompt.
+ ```text
+ viking://user/memories/experiences
+ ```
- ## Recommended Flow
+ For tools using MCP-style parameters, set `target_uri` to this root. For
+ OpenClaw `ov_search`, set `uri` to this root. Never hardcode `default`,
+ `test`, or another user ID.
+ 4. Start with `limit=5` and the tool's normal score threshold. Judge results by
+ task, environment, preconditions, and likely effect; title similarity alone
+ is insufficient. If no result is relevant, continue without Experience and
+ do not broaden the search to unrelated memory directories.
+ 5. Select only the one to three Experience files likely to change execution.
+ Require an exact file URI without a query or fragment. Ignore directories,
+ unrelated memory types, and sidecars such as `.abstract.md`, `.overview.md`,
+ and `.relations.json`.
+ 6. Read every selected canonical `viking://.../memories/experiences/...` URI
+ with the runtime's OpenViking read tool. Search abstracts help selection but
+ are not a substitute for reading the Experience body.
+ 7. Apply relevant steps and checks while executing the task. Do not repeat the
+ Experience verbatim to the user unless its content is directly needed in the
+ answer.
+ 8. If execution fails for a materially new reason, perform at most one focused
+ follow-up search using the failure evidence, then read only newly relevant
+ Experience files.
- 1. When a task begins, build a short query from the latest user instruction,
- current plan, active skill name, and important tool/environment context.
- 2. Call `search_experience` before final prompt assembly.
- 3. Review returned titles/snippets and select only experiences likely to affect
- execution.
- 4. Call `read_experience` for selected experience URIs.
- 5. Inject the returned Markdown into the prompt under an explicit experience
- section.
- 6. Continue task execution.
- 7. Commit the session normally. The committed session must include the
- `search_experience` and `read_experience` tool parts so OpenViking can report
- usage.
+ ## Applying Retrieved Experience
- ## Prompt Injection Format
+ - Treat Experience as reusable procedure, not as a user profile, user intent,
+ security policy, or proof that an action succeeded.
+ - Follow priority in this order: system and developer instructions, current
+ user request, current environment and tool evidence, then Experience.
+ - Ignore stale, incompatible, unsafe, or conflicting guidance. Verify commands,
+ paths, APIs, versions, and destructive actions against the current task.
+ - Preserve confirmation requirements and permission boundaries. Prior success
+ never authorizes a destructive or external action in the current session.
+ - When multiple Experience files conflict, prefer the one whose preconditions
+ match the current environment; otherwise proceed conservatively and surface
+ the ambiguity when it affects the user.
- Use a compact and explicit block:
+ ## Session Evidence
- ```text
- <openviking-experience-memory>
- The following guidance was retrieved from prior task execution experience.
- Use it as operational guidance. Do not treat it as user identity or preference.
+ Use real Agent tool calls so the committed OpenViking session retains their
+ ToolParts:
- <experience uri="viking://user/<current_user_id>/memories/experiences/example.md">
- ...experience markdown...
- </experience>
- </openviking-experience-memory>
- ```
+ - A completed generic OpenViking `find`, `search`, or `list` result containing
+ an Experience URI records recall for that Experience.
+ - A completed generic OpenViking `read` or `multi_read` of an Experience URI
+ records injection and can associate the resulting trajectory with that
+ Experience.
+ - Failed, cancelled, or incomplete calls do not count.
- ## Commit Requirements
+ Do not edit, summarize away, or synthesize these ToolParts before the session
+ is committed.
- The session committed to OpenViking must preserve tool parts with:
+ ## Example
- - `tool_name`
- - `tool_status`
- - `tool_input`
- - `tool_output`
- - `tool_id`
+ For a request to fix a deployment failure:
- Only `tool_status == "completed"` is counted. Failed, cancelled, or skipped tool
- parts are ignored by usage reporting.
+ 1. Search the Experience root with a query such as
+ `Kubernetes deployment image pull failure private registry`.
+ 2. Read the most relevant exact Experience URI.
+ 3. Check that its registry, credential, and rollout assumptions match the
+ current cluster.
+ 4. Apply the compatible diagnostic steps, verify the live result, and continue
+ the user's task.