Skip to content

Commit 17dea04

Browse files
0xble0xble
authored
feat(examples): add Codex memory plugin example (#1080)
* feat(examples): add Codex memory plugin example * fix(codex-memory-plugin): wait for delete consistency Wait for memory_forget deletions to settle before reporting success so the Codex adapter does not claim a delete while content/read can still see the memory in the same context. * docs(examples): add Codex plugin QA evidence * feat(examples): make Codex memory plugin hook-first * fix(api): harden filesystem content checks * fix(tests): use concrete fake embedder in quick start lite * refactor(examples): simplify codex memory plugin * fix(examples): tighten Codex MCP config * test(examples): guard fake embedder dimensions * fix(examples): route Codex memory MCP by configured user
1 parent f9867be commit 17dea04

File tree

8 files changed

+621
-58
lines changed

8 files changed

+621
-58
lines changed

‎examples/codex-memory-plugin/.codex-plugin/plugin.json‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"name": "openviking-memory",
3+
"description": "Explicit OpenViking memory tools for Codex via MCP.",
4+
"interface": {
5+
"displayName": "OpenViking Memory",
6+
"shortDescription": "OpenViking memory tools for Codex",
7+
"longDescription": "Adds explicit OpenViking MCP tools for manual memory recall, store, forget, and health checks.",
8+
"developerName": "OpenViking",
9+
"category": "productivity",
10+
"capabilities": [
11+
"Memory recall",
12+
"Manual memory storage",
13+
"Manual memory deletion"
14+
],
15+
"websiteURL": "https://github.com/volcengine/OpenViking"
16+
}
17+
}

‎examples/codex-memory-plugin/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
node_modules/
2+
servers/

‎examples/codex-memory-plugin/.mcp.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"mcpServers": {
3+
"openviking-memory": {
4+
"command": "node",
5+
"args": [
6+
"servers/memory-server.js"
7+
],
8+
"cwd": "."
9+
}
10+
}
11+
}

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

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# OpenViking Memory MCP Server for Codex
2+
3+
Small Codex MCP example for explicit OpenViking memory operations.
4+
5+
This example intentionally stays MCP-only:
6+
7+
- no lifecycle hooks
8+
- no background capture worker
9+
- no writes to `~/.codex`
10+
- no checked-in build output
11+
12+
Codex gets four tools:
13+
14+
- `openviking_recall`
15+
- `openviking_store`
16+
- `openviking_forget`
17+
- `openviking_health`
18+
19+
## Files
20+
21+
- `.codex-plugin/plugin.json`: plugin metadata
22+
- `.mcp.json`: MCP server wiring for Codex
23+
- `src/memory-server.ts`: MCP server source
24+
- `package.json`: build and start scripts
25+
- `tsconfig.json`: TypeScript build config
26+
27+
## Prerequisites
28+
29+
- Codex CLI
30+
- OpenViking server
31+
- Node.js 22+
32+
33+
Start OpenViking before using the MCP server:
34+
35+
```bash
36+
openviking-server --config ~/.openviking/ov.conf
37+
```
38+
39+
## Build
40+
41+
```bash
42+
cd examples/codex-memory-plugin
43+
npm install
44+
npm run build
45+
```
46+
47+
## Install in Codex
48+
49+
Use the built server:
50+
51+
```bash
52+
codex mcp add openviking-memory -- \
53+
node /ABS/PATH/TO/OpenViking/examples/codex-memory-plugin/servers/memory-server.js
54+
```
55+
56+
Or copy `.mcp.json` into a Codex workspace and adjust the `cwd` path if needed.
57+
58+
## Config
59+
60+
The server reads OpenViking connection settings from `~/.openviking/ov.conf`.
61+
62+
Supported environment overrides:
63+
64+
- `OPENVIKING_CONFIG_FILE`: alternate `ov.conf` path
65+
- `OPENVIKING_API_KEY`: API key override
66+
- `OPENVIKING_ACCOUNT`: account identity, default from `ov.conf`
67+
- `OPENVIKING_USER`: user identity, default from `ov.conf`
68+
- `OPENVIKING_AGENT_ID`: agent identity, default `codex`
69+
- `OPENVIKING_TIMEOUT_MS`: HTTP timeout, default `15000`
70+
- `OPENVIKING_RECALL_LIMIT`: recall result limit, default `6`
71+
- `OPENVIKING_SCORE_THRESHOLD`: recall threshold, default `0.01`
72+
73+
## Tools
74+
75+
### `openviking_recall`
76+
77+
Search OpenViking memory.
78+
79+
Parameters:
80+
81+
- `query`: search query
82+
- `target_uri`: optional search scope, default `viking://user/memories`
83+
- `limit`: optional max results
84+
- `score_threshold`: optional minimum score
85+
86+
### `openviking_store`
87+
88+
Store a memory by creating a short OpenViking session, adding the text, and
89+
committing the session. Memory creation is extraction-dependent; the tool
90+
reports when OpenViking commits the session but extracts zero memory items.
91+
92+
Parameters:
93+
94+
- `text`: information to store
95+
- `role`: optional message role, default `user`
96+
97+
### `openviking_forget`
98+
99+
Delete an exact memory URI. This example intentionally does not auto-delete by
100+
query; use `openviking_recall` first, then pass the exact URI.
101+
102+
Parameters:
103+
104+
- `uri`: exact `viking://user/.../memories/...` or `viking://agent/.../memories/...` URI
105+
106+
### `openviking_health`
107+
108+
Check server reachability.
109+
110+
## Remove
111+
112+
```bash
113+
codex mcp remove openviking-memory
114+
```

‎examples/codex-memory-plugin/package.json‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
{
2+
"name": "codex-openviking-memory",
3+
"version": "0.1.0",
4+
"description": "OpenViking memory MCP server for Codex",
5+
"type": "module",
6+
"scripts": {
7+
"build": "tsc",
8+
"dev": "tsc --watch",
9+
"start": "node ./servers/memory-server.js"
10+
},
11+
"dependencies": {
12+
"@modelcontextprotocol/sdk": "^1.12.1",
13+
"zod": "^4.3.6"
14+
},
15+
"devDependencies": {
16+
"@types/node": "^22.0.0",
17+
"typescript": "^5.7.0"
18+
}
19+
}

0 commit comments

Comments
 (0)