openviking-memory

# OpenViking Memory OpenViking is a long-term semantic memory store addressed by `viking://` URIs. This client has no lifecycle hooks, so nothing is recalled or captured automatically — you drive both halves of the loop with the `openviking` MCP tools. Core tools, available on every supported deployment: - Recall: `find`, `search`, `read`, `list`, `grep`, `glob` - Persist: `remember`, `add_resource` - Maintain: `forget`, `health` Some deployments register more than the core set — `tree`, `write`, `edit`, `list_watches`, `cancel_watch`. These are optional: which ones exist depends on the server version and hosting mode (the managed cloud service trims some of them). Check the session's registered tool list; if any optional tool is present, read [references/optional-tools.md](references/optional-tools.md) before using it. Never call a tool that is not registered, and do not fall back to raw HTTP. If no OpenViking tools are registered at all, continue without memory. ## Recall: at task start 1. Decide whether the request warrants memory. Retrieve for executable or multi-step work, anything touching a system you may have seen before, and recovery from failures. Skip retrieval for small talk and one-off trivia. 2. Build one concise query from the task goal, domain objects, intended operation, and constraints. After a failure, include the failed operation and the stable part of the error message. 3. Call `find` (fast, ranked results with URI + abstract + score) with `limit` around 5-10. Use `search` when deeper intent analysis helps, or use `search` with `mode="context"` for a server-assembled, token-budgeted context block. In list mode, scope with `target_uri` when you know where to look, e.g. `viking://~/memories/experiences` for prior task experience. `viking://~` is the home alias for your own user root; a server that predates the alias rejects every `viking://~` URI with `INVALID_URI`. Against such a server use the explicit `viking://user/<user_id>/...` root taken from a URI already visible in this session, or drop `target_uri` and keep the hits whose URI contains `/memories/experiences/`. Never guess a user ID. 4. Judge results by task and environment fit, not title similarity. `read` the one to three exact file URIs likely to change how you execute. Ignore sidecar files such as `.abstract.md`, `.overview.md`, and `.relations.json`. 5. If nothing relevant comes back, proceed without memory. Make at most one focused follow-up search when execution fails for a materially new reason. Treat retrieved memory as advisory. Priority order: system and developer instructions, the current user request, current environment and tool evidence, then memory. Verify commands, paths, and versions against the present task; prior success never authorizes a destructive action now. ## Persist: during and after work Because capture is not automatic here, durable information is lost unless you store it. When you encounter something worth keeping, persist it in the same session: - `remember(messages)` — the default. Pass the key exchange or a short factual summary as role-tagged messages; the server extracts and files memories (preferences, entities, events, experience) on its own. Use it when the user says "remember this", states a lasting preference or decision, or when a hard-won lesson (root cause, working procedure, environment quirk) emerges. - `add_resource` — to import external documents or URLs as searchable resources. Use it for any file, URL, or repo the user hands you; never copy its text into a file with `write` instead. - When you need a note you author at a known location (under `viking://~/` — your own user root — or `viking://resources/`), the optional `write` / `edit` tools cover that — see [references/optional-tools.md](references/optional-tools.md). If they are not registered, fall back to `remember`. What to persist: stable preferences and conventions, environment facts, decisions with their rationale, and reusable procedures or fixes. What not to persist: secrets and credentials, transient state, speculation, or bulk transcript dumps — store conclusions, not scrollback. ### File resources deliberately Resource directory rules do not apply to Memory; use `remember` or session commit and let the extraction system organize it. Before `add_resource`, keep the existing Resource layout and account policy, choose shared versus identity-private scope, and avoid duplicate source roots. Use `parent` for a new source and exact `to` for refresh. ## Example User asks to fix a failing deployment: 1. `find` with query `deployment image pull failure private registry`, `target_uri: "viking://~/memories/experiences"`. 2. `read` the most relevant experience URI; check its assumptions against the current cluster before applying its steps. 3. Fix the issue, verify the live result. 4. `remember` a short summary of the root cause and the working fix so the next session can recall it.