Skip to content

Commit 01036e2

Browse files
ZaynJarvisZaynJarvis
committed
docs(plugin/codex): put installation first
1 parent 8f135a3 commit 01036e2

3 files changed

Lines changed: 168 additions & 115 deletions

File tree

‎docs/en/agent-integrations/01-overview.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,8 @@ OpenViking can act as the long-term memory and context backend for many agent ru
88
|-------------|----------|
99
| **Claude Code** | [Claude Code Memory Plugin](./02-claude-code.md) — auto-recall + auto-capture via hooks, no MCP tool calls required from the model |
1010
| **OpenClaw** | [OpenClaw Plugin](./03-openclaw.md) — context-engine + hooks + tools + runtime manager, deep lifecycle integration |
11-
| **Codex / OpenCode** | [Other community plugins](./04-other-plugins.md) — MCP-only and tool-mechanism variants |
11+
| **Codex** | [Codex Memory Plugin](./04-other-plugins.md#codex-memory-plugin) — lifecycle hooks for auto-recall, incremental capture, and pre-compact commit |
12+
| **OpenCode** | [Other community plugins](./04-other-plugins.md) — explicit-tool and context-injection variants |
1213
| **Cursor / Trae / Manus / Claude Desktop / ChatGPT / …** | [MCP Integration Guide](../guides/06-mcp-integration.md) — point any MCP-compatible client at the built-in `/mcp` endpoint |
1314
| **Hermes Agent (Nous Research)** | [Hermes — OpenViking memory provider](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking) — first-class OpenViking memory provider, no plugin install needed |
1415

@@ -17,7 +18,7 @@ OpenViking can act as the long-term memory and context backend for many agent ru
1718
The plugins listed here go beyond what a generic MCP client can do:
1819

1920
- **Generic MCP clients** call OpenViking on demand through tools the model decides to invoke. Setup is one config snippet.
20-
- **Hooks-based plugins** (Claude Code, OpenClaw) drive recall and capture from runtime lifecycle events — every prompt, every turn, session start/end, compact, subagent spawn. The model doesn't need to "remember to recall."
21+
- **Hooks-based plugins** (Claude Code, Codex, OpenClaw) drive recall and capture from runtime lifecycle events — every prompt, every turn, session start/end, compact, subagent spawn. The model doesn't need to "remember to recall."
2122

2223
For agents whose runtime exposes hooks or a context-engine slot, the hooks-based path is usually the better default.
2324

‎docs/en/agent-integrations/04-other-plugins.md‎

Lines changed: 58 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,70 @@
22

33
The repo also ships several community/experimental plugins beyond the headline Claude Code and OpenClaw integrations. They differ in target runtime, integration depth, and maintenance status — read each one's README before adopting.
44

5-
## Codex Memory MCP Server
5+
## Codex Memory Plugin
66

77
Source: [examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin)
88

9-
A minimal MCP-only server for [Codex](https://github.com/openai/codex). Intentionally narrow scope:
9+
[Codex](https://github.com/openai/codex) integration with lifecycle hooks and explicit MCP tools. It follows the same install-first shape as the [Claude Code integration](./02-claude-code.md), but uses Codex hook events.
1010

11-
- no lifecycle hooks
12-
- no background capture worker
13-
- no writes to `~/.codex`
14-
- no checked-in build output
11+
### Install
1512

16-
Codex gets four explicit memory tools: `find`, `remember`, plus a couple more.
13+
```bash
14+
node --version # >= 22
15+
codex --version # >= 0.124.0
16+
codex features list | grep codex_hooks
17+
```
1718

18-
If you only need explicit memory operations from Codex (no auto-recall or auto-capture), this is the simplest option.
19+
From an OpenViking checkout:
20+
21+
```bash
22+
mkdir -p /tmp/ov-codex-mp/.claude-plugin
23+
ln -s "$(pwd)/examples/codex-memory-plugin" /tmp/ov-codex-mp/openviking-memory
24+
cat > /tmp/ov-codex-mp/.claude-plugin/marketplace.json <<'EOF'
25+
{
26+
"name": "openviking-codex-local",
27+
"plugins": [
28+
{ "name": "openviking-memory", "source": "./openviking-memory" }
29+
]
30+
}
31+
EOF
32+
33+
codex plugin marketplace add /tmp/ov-codex-mp
34+
cat >> ~/.codex/config.toml <<'EOF'
35+
36+
[plugins."openviking-memory@openviking-codex-local"]
37+
enabled = true
38+
EOF
39+
40+
cd examples/codex-memory-plugin
41+
npm install
42+
npm run build
43+
```
44+
45+
### Configure
46+
47+
Use `~/.openviking/ovcli.conf`, shared with the `ov` CLI:
48+
49+
```jsonc
50+
{
51+
"url": "https://ov.example.com",
52+
"api_key": "<your-key>",
53+
"account": "default",
54+
"user": "<your-user>"
55+
}
56+
```
57+
58+
Environment variables win over files. Use `OPENVIKING_CLI_CONFIG_FILE` for an alternate `ovcli.conf`; `OPENVIKING_API_KEY` and `OPENVIKING_BEARER_TOKEN` are equivalent.
59+
60+
### What it does
61+
62+
- Auto-recall on `UserPromptSubmit`
63+
- Incremental capture on `Stop`
64+
- Commit before compaction on `PreCompact`
65+
- Orphan cleanup on `SessionStart` startup/clear
66+
- Manual MCP tools: `openviking_recall`, `openviking_store`, `openviking_forget`, `openviking_health`
67+
68+
Full behavior and validation details are in the [plugin README](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin).
1969

2070
## OpenCode plugins
2171

‎examples/codex-memory-plugin/README.md‎

Lines changed: 107 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,113 @@ This is the Codex counterpart to [`claude-code-memory-plugin`](../claude-code-me
1212

1313
It also exposes explicit MCP tools (`openviking_recall`, `openviking_store`, `openviking_forget`, `openviking_health`) for manual use.
1414

15+
## Quick Start
16+
17+
Installation is first here, matching the shape of the [Claude Code integration doc](../../docs/en/agent-integrations/02-claude-code.md).
18+
19+
### 1. Install prerequisites
20+
21+
```bash
22+
node --version # >= 22
23+
codex --version # >= 0.124.0
24+
```
25+
26+
Make sure `codex_hooks` is enabled:
27+
28+
```bash
29+
codex features list | grep codex_hooks
30+
```
31+
32+
### 2. Install the plugin
33+
34+
The plugin lives at `examples/codex-memory-plugin/`.
35+
36+
```bash
37+
mkdir -p /tmp/ov-codex-mp/.claude-plugin
38+
ln -s /abs/path/to/OpenViking/examples/codex-memory-plugin /tmp/ov-codex-mp/openviking-memory
39+
cat > /tmp/ov-codex-mp/.claude-plugin/marketplace.json <<'EOF'
40+
{
41+
"name": "openviking-codex-local",
42+
"plugins": [
43+
{ "name": "openviking-memory", "source": "./openviking-memory" }
44+
]
45+
}
46+
EOF
47+
48+
codex plugin marketplace add /tmp/ov-codex-mp
49+
cat >> ~/.codex/config.toml <<'EOF'
50+
51+
[plugins."openviking-memory@openviking-codex-local"]
52+
enabled = true
53+
EOF
54+
```
55+
56+
For local development, pre-populate Codex's plugin cache so it resolves immediately:
57+
58+
```bash
59+
INSTALL_DIR=~/.codex/plugins/cache/openviking-codex-local/openviking-memory
60+
mkdir -p "$INSTALL_DIR"
61+
cp -R /abs/path/to/OpenViking/examples/codex-memory-plugin "$INSTALL_DIR/0.2.0"
62+
```
63+
64+
### 3. Build the MCP server
65+
66+
```bash
67+
cd examples/codex-memory-plugin
68+
npm install
69+
npm run build
70+
```
71+
72+
### 4. Configure OpenViking
73+
74+
Use the same client config file as the `ov` CLI:
75+
76+
```jsonc
77+
// ~/.openviking/ovcli.conf
78+
{
79+
"url": "https://ov.example.com",
80+
"api_key": "<your-key>",
81+
"account": "default",
82+
"user": "<your-user>"
83+
}
84+
```
85+
86+
Local server mode works without this file; the plugin falls back to `http://127.0.0.1:1933`.
87+
88+
### 5. Start Codex
89+
90+
```bash
91+
codex
92+
```
93+
94+
First MCP launch installs runtime deps; later launches reuse them.
95+
96+
## Configuration
97+
98+
Resolution priority, highest to lowest:
99+
100+
1. Environment variables: `OPENVIKING_URL`, `OPENVIKING_API_KEY` / `OPENVIKING_BEARER_TOKEN`, `OPENVIKING_ACCOUNT`, `OPENVIKING_USER`, `OPENVIKING_AGENT_ID`
101+
2. `ovcli.conf`: `~/.openviking/ovcli.conf` or `OPENVIKING_CLI_CONFIG_FILE`
102+
3. `ov.conf`: `~/.openviking/ov.conf` or `OPENVIKING_CONFIG_FILE`
103+
4. Built-in defaults
104+
105+
Auth is sent as `Authorization: Bearer <key>` plus legacy `X-API-Key` during migration.
106+
107+
Optional Codex-specific tuning can live under `codex` in `ovcli.conf`:
108+
109+
```jsonc
110+
{
111+
"url": "https://ov.example.com",
112+
"api_key": "...",
113+
"codex": {
114+
"agentId": "codex",
115+
"recallLimit": 6,
116+
"captureAssistantTurns": false,
117+
"autoCommitOnCompact": true
118+
}
119+
}
120+
```
121+
15122
## Architecture
16123

17124
```
@@ -127,111 +234,6 @@ Unlike Claude Code, **Codex does not support `decision: "approve"`**; only `deci
127234

128235
Source: [`codex-rs/hooks/schema/generated/`](https://github.com/openai/codex/tree/main/codex-rs/hooks/schema/generated).
129236

130-
## Quick Start
131-
132-
### 1. Install Node.js 22+ and Codex 0.124+
133-
134-
```bash
135-
node --version # >= 22
136-
codex --version # >= 0.124.0
137-
```
138-
139-
Make sure `codex_hooks` is enabled (it's stable since April 2026):
140-
141-
```bash
142-
codex features list | grep codex_hooks
143-
# codex_hooks stable true
144-
```
145-
146-
### 2. Configure OpenViking client
147-
148-
The plugin reads connection settings from `~/.openviking/ovcli.conf` (the same file the `ov` CLI uses). For a cloud OpenViking deployment:
149-
150-
```jsonc
151-
{
152-
"url": "https://ov.example.com",
153-
"api_key": "<your-key>",
154-
"account": "default",
155-
"user": "<your-user>"
156-
}
157-
```
158-
159-
For a local server, omit `url` and the plugin will fall back to `~/.openviking/ov.conf`'s `server.host` / `server.port`.
160-
161-
Plugin-specific overrides go in an optional `codex` section:
162-
163-
```jsonc
164-
{
165-
"url": "https://ov.example.com",
166-
"api_key": "...",
167-
"codex": {
168-
"agentId": "codex",
169-
"recallLimit": 6,
170-
"captureMode": "semantic",
171-
"captureAssistantTurns": false,
172-
"autoCommitOnCompact": true
173-
}
174-
}
175-
```
176-
177-
### 3. Install the plugin
178-
179-
The plugin lives at `examples/codex-memory-plugin/` in the OpenViking repo. Once a marketplace ships it, install with:
180-
181-
```bash
182-
codex plugin marketplace add <marketplace-source>
183-
# then enable in ~/.codex/config.toml:
184-
# [plugins."openviking-memory@<marketplace-name>"]
185-
# enabled = true
186-
```
187-
188-
For local development, point a tiny marketplace fixture at this directory:
189-
190-
```bash
191-
mkdir -p /tmp/ov-codex-mp/.claude-plugin
192-
ln -s /abs/path/to/OpenViking/examples/codex-memory-plugin /tmp/ov-codex-mp/openviking-memory
193-
cat > /tmp/ov-codex-mp/.claude-plugin/marketplace.json <<'EOF'
194-
{
195-
"name": "openviking-codex-local",
196-
"plugins": [
197-
{ "name": "openviking-memory", "source": "./openviking-memory" }
198-
]
199-
}
200-
EOF
201-
codex plugin marketplace add /tmp/ov-codex-mp
202-
203-
# Enable the plugin
204-
cat >> ~/.codex/config.toml <<'EOF'
205-
206-
[plugins."openviking-memory@openviking-codex-local"]
207-
enabled = true
208-
EOF
209-
210-
# Codex installs plugins lazily — for fastest iteration, copy the plugin into
211-
# the cache so it resolves immediately:
212-
INSTALL_DIR=~/.codex/plugins/cache/openviking-codex-local/openviking-memory
213-
mkdir -p "$INSTALL_DIR"
214-
cp -R /abs/path/to/OpenViking/examples/codex-memory-plugin "$INSTALL_DIR/0.2.0"
215-
```
216-
217-
### 4. Build the MCP server
218-
219-
```bash
220-
cd examples/codex-memory-plugin
221-
npm install
222-
npm run build
223-
```
224-
225-
The MCP server compiles to `servers/memory-server.js`, which `start-memory-server.mjs` launches via the bootstrapped runtime.
226-
227-
### 5. Start a Codex session
228-
229-
```bash
230-
codex
231-
```
232-
233-
The first session installs runtime deps; subsequent sessions skip reinstall.
234-
235237
## Validation SOP
236238

237239
This is the canonical end-to-end validation for an OpenViking plugin. Run it after any plugin change.

0 commit comments

Comments
 (0)