z-code-memory-plugin

Long-term semantic memory for ZCode, powered by OpenViking — 中文说明见 README_CN.md。

The OpenViking MCP server alone only gives ZCode the memory tools. This plugin adds the lifecycle hooks that make the memory work on its own: relevant context is recalled at session start and on every prompt, the conversation is captured and committed as it happens, and viking:// database paths are kept away from filesystem tools. It is a thin, ZCode-native packaging of upstream's shared runtime and its ZCode host adapter — no behavior is forked.

What it installs

Piece	Kind	What it does
SessionStart hook	recall	Replays any writes queued while offline, injects a workspace profile.
UserPromptSubmit hook	recall	Searches OpenViking for the prompt and injects an <openviking-context> block.
PreToolUse hook (Read|Glob|Grep)	guard	Denies tool calls aimed at viking:// virtual URIs with a hint to use the MCP read tool instead.
Stop hook	capture	Reads the unseen turns from ZCode's rollout transcript (~/.zcode/cli/rollout/model-io-<sessionId>.jsonl), appends them to the session, and commits. Writes are asynchronous and queued with retry when the server is unreachable.
openviking MCP server	tools	The shared stdio→HTTP proxy: search, find, read, remember, add_resource, forget, … with identity headers.
openviking-memory skill	guidance	When and how to use the memory tools.
/ov-status command	diagnostics	Config, identity, toggles, and recent hook activity in one screen.

Requirements

• ZCode with the plugin system (Settings → Plugin Management).
• Node.js ≥ 18 on PATH (hooks are node … commands).
• A reachable OpenViking server. The recommended setup is the ov CLI login, which writes ~/.openviking/ovcli.conf; environment variables work too.

Install

1. Open Settings → Plugin Management → Discover, press +.
2. Add the marketplace from this repository: shenhuanjie/z-code-memory-plugin (a Git URL or a local checkout path works as well).
3. Install z-code-memory-plugin. It is enabled by default, and a plugin that contributes hooks enables ZCode's hook runner automatically.
4. Start a new session. Run /ov-status to confirm.

Configuration

One resolver serves the hooks, the MCP proxy, and /ov-status. Layers, from highest to lowest priority: OPENVIKING_* environment variables → workspace registry → <workspace>/.openviking/config.json → plugin.zcode in ~/.openviking/ovcli.conf → defaults.

Commonly used environment variables:

Variable	Purpose
OPENVIKING_MCP_URL (alias OPENVIKING_URL, OPENVIKING_BASE_URL)	Server base URL. Without any config the plugin falls back to http://127.0.0.1:1933.
OPENVIKING_API_KEY (alias OPENVIKING_BEARER_TOKEN)	API key when the server is not in trusted mode.
OPENVIKING_AUTH_MODE	trusted or api_key.
OPENVIKING_MEMORY_ENABLED	Master switch for the hooks (1/0).
OPENVIKING_AUTO_RECALL / OPENVIKING_AUTO_CAPTURE	Toggle recall injection / conversation capture separately.
OPENVIKING_PEER_ID	Pin the memory peer instead of deriving it from the workspace.
OPENVIKING_WRITE_PATH_ASYNC	1 (default) answers the Stop hook before the network round-trip; 0 waits.
OPENVIKING_DEBUG	1 records a hook log (path printed by /ov-status).
OPENVIKING_TIMEOUT_MS	Per-request timeout for hook calls.

To give a directory its own memory peer, create .openviking/config.json inside it:

{"version": 1, "peer": {"id": "my-project"}}

Secrets belong in ovcli.conf or the environment — never in workspace files or this plugin's settings.

ZCode-specific notes

ZCode's hook set is fixed at seven events and has no PreCompact, SessionEnd, or subagent hooks, so capture happens on Stop only, driven by the rollout transcript — which doubles as the recovery source for missed Stop events. ZCode validates hook stdout against a strict schema and discards documents containing unknown keys, so this adapter never emits Claude-Code-specific fields.

Troubleshooting

• /ov-status — configuration layers, identity, toggles, and the freshest hook-state files (~/.openviking/hook-state/zcode/). The state file of a session should refresh on every Stop.
• Set OPENVIKING_DEBUG=1 and rerun; the hook log captures every request and error. Captures that fail are queued on disk and replayed at the next session start.
• MCP tools missing: check Settings → MCP for the openviking server.

Development

node --test          # 44 tests: capture planning, rollout parsing, uri guard, async writes
node scripts/sync-from-upstream.mjs <path-to-OpenViking-checkout>

Everything executable is vendored from the upstream repository; see UPSTREAM.md for the pinned commit, the file mapping, and the two packaging-level adaptations (plugin-root expansion owner, Windows test home). Bug fixes belong upstream — sync, don't fork.

License

Apache-2.0, as upstream.