@remnic/plugin-codex 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +104 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# @remnic/plugin-codex
|
|
2
|
+
|
|
3
|
+
Native [OpenAI Codex CLI](https://github.com/openai/codex) plugin for [Remnic](https://github.com/joshuaswarren/remnic) memory. Wires Codex's session hooks, MCP server, skills, and memory-extension into a running Remnic daemon so every Codex session gets persistent long-term memory automatically.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
Three discrete steps. None is automated end-to-end today; each writes to a different place.
|
|
8
|
+
|
|
9
|
+
1. **Mint a Remnic-side bearer token, record the connector, and install the phase-2 consolidation guide.**
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
remnic connectors install codex-cli
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
This writes `~/.remnic/connectors/codex-cli.json` (Remnic's connector-state file), stores a bearer token, and calls `@remnic/core`'s `installCodexMemoryExtension` which materializes `~/.codex/memories_extensions/remnic/instructions.md` (the local-only phase-2 consolidation guide; see the file-table row below). It does NOT write `~/.codex/config.toml` and it does NOT deploy `.codex-plugin/`, `hooks/`, or `skills/`.
|
|
16
|
+
|
|
17
|
+
2. **Add Remnic as an MCP server in `~/.codex/config.toml`.** Paste the TOML block from the "MCP setup" section below, replacing `{{REMNIC_TOKEN}}` with the token from step 1. Without this step Codex has no way to talk to the Remnic daemon.
|
|
18
|
+
|
|
19
|
+
3. **Install this package and load it through Codex's plugin system** so the hooks, skills, and `.codex-plugin` manifest are actually active:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npm install -g @remnic/plugin-codex
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Consult Codex's plugin docs for the exact load mechanism your install supports (symlink into `~/.codex/plugins/`, marketplace install, etc.). Until this step runs, the session hooks and skills aren't active and you won't get auto-recall / auto-observe.
|
|
26
|
+
|
|
27
|
+
## What ships
|
|
28
|
+
|
|
29
|
+
The package is **data + one small runtime materializer** (no runtime JS beyond the memory-materializer helper; the actual plugin install is driven by `@remnic/core`):
|
|
30
|
+
|
|
31
|
+
| File / dir | Purpose |
|
|
32
|
+
|---|---|
|
|
33
|
+
| `.codex-plugin/plugin.json` | Plugin manifest |
|
|
34
|
+
| `hooks/hooks.json` + `hooks/bin/*.sh` | Codex session-lifecycle hooks (recall, observe, session-end) |
|
|
35
|
+
| `skills/` | `remnic-recall`, `remnic-remember`, `remnic-search`, `remnic-status`, `remnic-entities`, `remnic-memory-workflow` — invocable from Codex chats |
|
|
36
|
+
| `memories_extensions/remnic/` | Codex phase-2 consolidation instructions — tells the Codex compactor sub-agent to treat Remnic's on-disk Markdown as an authoritative local memory source when it builds `MEMORY.md`. Local-only (no MCP, no network); runtime recall/observe still flow through the hooks above. |
|
|
37
|
+
| `.mcp.json` | MCP server config pointing Codex at `http://localhost:4318/mcp` |
|
|
38
|
+
| `bin/materialize.cjs` | Runtime entrypoint invoked exclusively by the Codex `Stop` hook (`hooks/bin/session-end.sh`) to refresh `~/.codex/memories` from the Remnic store at the end of a session. Not an installer, and not wired into any `remnic` CLI command. |
|
|
39
|
+
|
|
40
|
+
## What you get at runtime
|
|
41
|
+
|
|
42
|
+
Once installed and a Remnic daemon is running (`remnic daemon start`):
|
|
43
|
+
|
|
44
|
+
- **Auto-recall** on `SessionStart` and on every `UserPromptSubmit` — relevant memories are injected before Codex's first turn and before each subsequent user turn.
|
|
45
|
+
- **Auto-observe** on `PostToolUse` for the `Bash` tool and on `Stop` (session end) — new facts, decisions, and entities touched by shell work (or accumulated through the session) are buffered for extraction automatically.
|
|
46
|
+
- **Memory skills** — invoke `/remnic-recall`, `/remnic-search`, `/remnic-remember`, `/remnic-entities`, `/remnic-status` directly in Codex chats.
|
|
47
|
+
- **Cross-agent sharing** — the same memory store is shared with every other Remnic-connected agent (Claude Code, OpenClaw, Replit, Hermes, etc.), so what one agent learns is available to all.
|
|
48
|
+
|
|
49
|
+
## MCP setup
|
|
50
|
+
|
|
51
|
+
The plugin expects a Remnic daemon reachable at `http://localhost:4318/mcp` with a bearer token. Codex reads MCP servers from `~/.codex/config.toml`; add the following block (this is step 2 of the Install flow above — `remnic connectors install codex-cli` does NOT write it for you):
|
|
52
|
+
|
|
53
|
+
```toml
|
|
54
|
+
[mcp_servers.remnic]
|
|
55
|
+
url = "http://127.0.0.1:4318/mcp"
|
|
56
|
+
bearer_token_env_var = "REMNIC_AUTH_TOKEN"
|
|
57
|
+
http_headers = { "X-Engram-Client-Id" = "codex" }
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Then export the token Codex looks up. `remnic token generate` prints a multi-line status block (not just the raw token), so either:
|
|
61
|
+
|
|
62
|
+
Copy the `Token:` value from:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
remnic token generate codex-cli
|
|
66
|
+
# → Generated token for codex-cli:
|
|
67
|
+
# Token: <paste this into REMNIC_AUTH_TOKEN>
|
|
68
|
+
# Created: ...
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
and set it in your shell profile:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
export REMNIC_AUTH_TOKEN="<paste the token value here>"
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Or extract it in one line with `awk`:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
export REMNIC_AUTH_TOKEN=$(remnic token generate codex-cli | awk '/^ *Token:/ {print $2}')
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
See `docs/integration/connector-setup.md` in the Remnic repo for the canonical snippet.
|
|
84
|
+
|
|
85
|
+
## Agent note
|
|
86
|
+
|
|
87
|
+
If you're an AI agent scaffolding a Codex integration: **do not** hand-edit `~/.codex/` directly. The full setup has two components:
|
|
88
|
+
|
|
89
|
+
1. `remnic connectors install codex-cli` (drives `@remnic/core`'s `installCodexMemoryExtension`) handles the MCP config, token rotation, and writes `memories_extensions/remnic/instructions.md`. It does NOT deploy `.codex-plugin/`, `hooks/`, or `skills/`.
|
|
90
|
+
2. Load this package into Codex via Codex's own plugin loader to activate the hooks and skills.
|
|
91
|
+
|
|
92
|
+
`bin/materialize.cjs` is a runtime helper called only by the Codex `Stop` hook to refresh `~/.codex/memories` from the live Remnic store at session end; it's not an installer and not wired into any `remnic` CLI command, so re-running it manually won't recover a broken plugin install.
|
|
93
|
+
|
|
94
|
+
## Related
|
|
95
|
+
|
|
96
|
+
- [`@remnic/cli`](https://www.npmjs.com/package/@remnic/cli) — daemon lifecycle + installer
|
|
97
|
+
- [`@remnic/plugin-claude-code`](https://www.npmjs.com/package/@remnic/plugin-claude-code) — same idea, for Anthropic Claude Code
|
|
98
|
+
- [`@remnic/plugin-openclaw`](https://www.npmjs.com/package/@remnic/plugin-openclaw) — OpenClaw memory-slot plugin
|
|
99
|
+
- Connector guide: [docs/integration/connector-setup.md](https://github.com/joshuaswarren/remnic/blob/main/docs/integration/connector-setup.md) in the repo
|
|
100
|
+
- Source + issues: <https://github.com/joshuaswarren/remnic>
|
|
101
|
+
|
|
102
|
+
## License
|
|
103
|
+
|
|
104
|
+
MIT. See the root [LICENSE](https://github.com/joshuaswarren/remnic/blob/main/LICENSE) file.
|