0b17a67c70
* feat(codex): add Hindsight memory integration for OpenAI Codex CLI
Hooks-based integration that gives Codex CLI long-term memory via Hindsight.
Three hooks keep memory in sync: SessionStart (daemon pre-warm), UserPromptSubmit
(recall + context injection), Stop (retain conversation to memory).
Key differences from the Claude Code integration:
- Codex transcript format: JSONL with {msg: {type, message}} (user_message/agent_message)
- No CODEX_PLUGIN_ROOT env var — install.sh writes hooks.json with absolute paths
- State stored in ~/.hindsight/codex/state/ (not CLAUDE_PLUGIN_DATA)
- No async: true in hooks (not supported by Codex)
- No SessionEnd event
- hooks.json written to ~/.codex/hooks.json with codex_hooks = true in config.toml
* fix(codex): fix transcript parser for actual Codex disk format
Codex stores sessions as rollout-*.jsonl with response_item entries:
User: {type:response_item, payload:{type:message, role:user, content:[{type:input_text, text:...}]}}
Assistant: {type:response_item, payload:{type:message, role:assistant, phase:final_answer, content:[{type:output_text, text:...}]}}
Previous parser expected an undocumented {msg:{type:user_message}} format from the Rust protocol spec
that does not match the actual on-disk storage format.
* feat(codex): add reflect mode to UserPromptSubmit hook
Add recallMode config option (default: 'recall') that switches the
UserPromptSubmit hook between:
- 'recall': existing behavior, fast raw facts list
- 'reflect': agentic synthesis loop, returns coherent prose answer
Also adds reflect() method to HindsightClient and HINDSIGHT_RECALL_MODE
env var override. Reflect uses a 25s timeout (vs 10s for recall).
* feat(codex): auto mode for recall/reflect selection
Add recallMode: 'auto' (new default) that picks the operation per-query:
- Synthesis patterns (what do you know, what's my, summarize, etc.) → reflect
- All other prompts → recall (fast, raw facts, better for code tasks)
* feat(codex): add automated test suite and finalize recall-only mode
* docs(codex): add docs page and sidebar entry for Codex CLI integration
|
||
|---|---|---|
| .. | ||
| hooks | ||
| scripts | ||
| tests | ||
| install.sh | ||
| README.md | ||
| settings.json | ||
Hindsight for OpenAI Codex CLI
Long-term memory for OpenAI Codex CLI — remembers your projects, preferences, and past sessions across every conversation.
How it works
Three Codex hooks keep memory in sync automatically:
| Hook | Action |
|---|---|
SessionStart |
Warms up the Hindsight server in the background |
UserPromptSubmit |
Recalls relevant memories and injects them into context |
Stop |
Retains the conversation to long-term memory |
Requirements
- OpenAI Codex CLI v0.116.0 or later (hooks support)
- Python 3.9+ (for hook scripts)
- Hindsight: Hindsight Cloud or local
hindsight-embed
Installation
git clone https://github.com/vectorize-io/hindsight
cd hindsight/hindsight-integrations/codex
./install.sh
The installer:
- Copies scripts to
~/.hindsight/codex/scripts/ - Writes
~/.codex/hooks.jsonwith absolute paths to the scripts - Adds
codex_hooks = trueto~/.codex/config.toml
Uninstall
./install.sh --uninstall
Configuration
The default config is written to ~/.hindsight/codex/settings.json on first install.
For personal overrides (stable across updates), create ~/.hindsight/codex.json:
{
"hindsightApiUrl": "https://api.hindsight.vectorize.io",
"hindsightApiToken": "your-api-key",
"bankId": "my-codex-memory"
}
Hindsight Cloud
{
"hindsightApiUrl": "https://api.hindsight.vectorize.io",
"hindsightApiToken": "your-api-key"
}
Local daemon (hindsight-embed)
Set an LLM API key and Hindsight will start the local server automatically:
export OPENAI_API_KEY=sk-your-key
# or
export ANTHROPIC_API_KEY=your-key
Configuration options
| Key | Default | Description |
|---|---|---|
hindsightApiUrl |
"" |
External API URL (empty = local daemon) |
hindsightApiToken |
null |
API token for Hindsight Cloud |
bankId |
"codex" |
Memory bank identifier |
bankMission |
(set) | Guides what facts Hindsight retains |
autoRecall |
true |
Inject memories before each prompt |
autoRetain |
true |
Store conversations after each turn |
retainMode |
"full-session" |
"full-session" or "chunked" |
retainEveryNTurns |
10 |
Retain every N turns (1 = every turn) |
recallBudget |
"mid" |
Recall depth: "low", "mid", "high" |
recallMaxTokens |
1024 |
Max tokens for injected memories |
dynamicBankId |
false |
Separate bank per project/session |
dynamicBankGranularity |
["agent", "project"] |
Fields for dynamic bank ID |
debug |
false |
Log debug info to stderr |
Environment variable overrides
All settings can also be set via environment variables:
export HINDSIGHT_API_URL=https://api.hindsight.vectorize.io
export HINDSIGHT_API_TOKEN=your-api-key
export HINDSIGHT_BANK_ID=my-project
export HINDSIGHT_DEBUG=true
How memory works
Recall — before each prompt, Hindsight searches your memory bank for facts relevant to what you're about to ask. Found memories are injected as context so Codex has continuity across sessions.
Retain — after each turn, Codex's conversation is stored to Hindsight. The memory engine extracts facts, relationships, and experiences — so you don't need to re-explain your stack, preferences, or past decisions.
Dynamic bank IDs
To keep separate memory per project:
{
"dynamicBankId": true,
"dynamicBankGranularity": ["agent", "project"]
}
This creates banks like codex::my-project automatically, using the working directory name.
Troubleshooting
Memory not appearing: Enable debug mode ("debug": true) and check stderr output.
Server not starting: Set hindsightApiUrl to use an external server, or ensure uvx is on PATH for local daemon mode.
Hooks not firing: Check that ~/.codex/config.toml contains codex_hooks = true under [features], and that your Codex CLI version supports hooks (v0.116.0+).