Codex OpenViking Memory

简体中文 · Setup · Directory template · Architecture · Security

A macOS and Windows bridge that lets Codex propose small memory summaries, ask the human to choose, and submit only the selected summaries to OpenViking. Version 0.2.0 adds native macOS Keychain credentials and a clean personal-context directory template alongside Windows DPAPI support.

The model judges whether a current human statement has lasting value. Local hooks enforce confirmation and submission boundaries. The read-only MCP server provides eight scoped tools without exposing a write tool. Chat transcripts are not the capture payload.

Requirements

• Node.js 22 or later; no npm runtime dependencies.

• macOS with its native Keychain, or Windows with PowerShell 7 (pwsh) and DPAPI. The unified installer selects the operating-system path; Linux provisioning is not supported.

• An existing OpenViking server and an ordinary user credential for the configured account and user. The installer does not deploy OpenViking.

• A Codex client that can load a local plugin, execute UserPromptSubmit and Stop hooks, run a local stdio MCP server, and let the model invoke a local command.

• A native question/input tool if you want selectable confirmation cards. This tool is supplied by the client, not by this project, and may be absent or restricted in some clients or modes. Exact typed confirmation remains available.

Related MCP server: Convorel

Install and activate

git clone https://github.com/daizhonggeng/codex-openviking-memory.git
cd codex-openviking-memory
node scripts/install.mjs --server-url https://memory.example.com --account example-account --user example-user

Enter the ordinary user's API key in the hidden local prompt. Do not put it in a command line, chat, repository, or issue. The API key and local vault key use macOS Keychain or Windows DPAPI. Data stays outside the checkout: ~/Library/Application Support/CodexOpenVikingMemory on macOS and %LOCALAPPDATA%/CodexOpenVikingMemory on Windows. --write-url can select a separate write origin; it defaults to --server-url.

The installer generates a local marketplace/plugin, an MCP configuration snippet, and a supportive model-rule fragment. Installation does not automatically activate them in Codex. Follow the printed locations to add the generated local marketplace and enable its plugin, then import the generated MCP configuration into your client. Reload the client/session as needed and verify that both hook events and the read-only MCP server are available. The installer does not silently modify your existing Codex configuration or AGENTS.md.

See setup and activation for the complete checklist, configuration, credential handling, and offline installer options. Hook responses inject the memory-review rules dynamically; the generated AGENTS.fragment.md is optional supporting guidance, not an assumed global installation.

Personal-context directory template

Both installers initialize knowledge/ under the data directory from templates/personal-context/, preserving files that already exist. This connects the earlier personal-context organization—PROFILE.md, PREFERENCES.md, CURRENT.md, numbered topic folders, record guides, and six blank record templates—to the bridge as a generic navigation structure. The template contains no user facts.

The local directory and remote knowledge remain separate. template map describes how local relative paths correspond to viking://user/<user>/resources/personal-context/; native confirmed memories stay under viking://user/<user>/memories/. Initializing or mapping creates no remote resource, uploads no files, writes no memory, and does not add Git-based knowledge persistence. See the template guide.

How a memory is saved

1. A human sends a normal message. The model considers its meaning in context and may decide that nothing should be saved.

2. For a useful fact, preference, current goal, or reusable lesson, the model writes a minimal candidate JSON file and invokes propose.

3. The candidate is encrypted locally. The model shows its actual returned ID and summary and asks for a choice using the client's native question tool when available.

4. The human explicitly selects a supported save response or types exactly save candidate ID or 保存候选 ID, replacing ID with the actual ID.

5. UserPromptSubmit recognizes the human confirmation; Stop submits the approved batch using the pinned upstream capture scripts through a restricted transport.

6. Check status, then verify extraction/readback through read-only MCP before saying that the memory is fully available.

An ordinary request, a quoted instruction, a tool result, or a model-generated "save" message is not human authorization. The hook recognizes a strict confirmation format; it does not make the semantic decision to save. A question card can help collect a choice only when the client's reply reaches the hook in a supported form. If that integration is unavailable, ask the human to send the exact text command; do not simulate a click or silently approve.

Commands

Run these commands from the source checkout on either platform. Replace CONFIG_PATH with the installer-created config.json path. To use the installed copy, replace ./bin/cli.mjs with the quoted absolute runtime/bin/cli.mjs path printed by the installer.

node ./bin/cli.mjs --help
node ./bin/cli.mjs doctor --config "CONFIG_PATH"
node ./bin/cli.mjs propose --config "CONFIG_PATH" --input "CANDIDATE_JSON_PATH"
node ./bin/cli.mjs status --config "CONFIG_PATH" --id ACTUAL_CANDIDATE_ID
node ./bin/cli.mjs mcp --config "CONFIG_PATH"
node ./bin/cli.mjs template init --config "CONFIG_PATH"
node ./bin/cli.mjs template map --config "CONFIG_PATH"

Candidate input has exactly these fields:

{
  "summary": "The user prefers brief answers with explicit verification results.",
  "kind": "preference",
  "source": "current-human-statement"
}

Allowed kinds are profile, preference, current, and knowledge. The example is sample data, not an asserted fact about the person installing the project. Keep candidate input files outside the checkout; they contain sensitive plaintext until you remove them. See command reference.

Read-only MCP

The bridge exposes health, find, search, read, list, tree, grep, and glob. Access is limited to the configured user's native memories and resources/personal-context/ subtree. Searches use mode="list" without session_id. No remember, capture, raw-session upload, or general write tool is exposed. Server authorization remains necessary in addition to these local checks.

Development and verification

node --test
npm run verify:vendor

Tests use temporary directories and mocked network/transport. Platform-specific tests cover Windows DPAPI installation and macOS Keychain installation with synthetic secrets; macOS checks require a native macOS runner. The CI configuration targets Linux, Windows, and macOS on Node.js 22/24. Its presence is not a claim that a particular run passed. Tests do not prove server compatibility, a client's hook/card integration, or live extraction. See testing and the release checklist.

License and source

This project is licensed under AGPL-3.0-only. It includes an unchanged, deliberately limited subset of the OpenViking Codex memory example at v0.5.1.1. See NOTICE and vendor provenance for the pinned tree, file hashes, and source scope. Retain the license and corresponding source when redistributing; modified network deployments must also respect the AGPL source-offer requirements.