/hindsight-docs

Codex

⚠️ Superseded by the Coding Agents plugin

The Codex CLI integration is superseded by the Coding Agents plugin — one package covering Claude Code, Codex, opencode, Kilo, Cursor, Copilot, Grok, Antigravity, Devin and Cline and other CLI agents, with a per-repo memory bank they all share instead of one bank per agent.

This page and the published package still work; they are no longer developed. To switch:

cd /path/to/your/repo
npx @vectorize-io/hindsight-coding-agents install codex --import-conversations

Two things move, and nothing else does.

Your server moves automatically. install reads ~/.hindsight/codex.json and keeps the same apiUrl and token — an empty URL still means the local daemon — so you are not silently switched to Hindsight Cloud. Pass --server to change it.

Your conversations are re-imported from local transcripts by --import-conversations, as new documents. They are not copied from the old bank: that bank's default was a single static bank shared by every project, and its documents record only a session id, so working out which ones belong to this repo means reading the local transcripts anyway.

Nothing else carries over. The old recall* and retain* settings, missions and bank-naming options describe a pipeline this package replaced. Bank naming changes too — one bank per repo, shared by every agent. See Migrating from the per-agent plugins. View Changelog →

Persistent memory for Codex CLI using Hindsight. Three Python hook scripts automatically recall relevant context before each prompt and retain conversations after each turn — no changes to your Codex workflow required.

Quick Start

💡 Recommended: Hindsight Cloud

Sign up free for a Hindsight Cloud API key — no self-hosting, no local daemon to manage.

curl -fsSL https://hindsight.vectorize.io/get-codex | bash

The installer will guide you through choosing Cloud or local-daemon mode and configuring your connection. Once installed, start a new Codex session — memory is live.

To uninstall:

curl -fsSL https://hindsight.vectorize.io/get-codex | bash -s -- --uninstall

Features

• Auto-recall — on every user prompt, queries Hindsight for relevant memories and injects them as additionalContext (invisible to the transcript, visible to Codex)
• Auto-retain — after each Codex response, stores the conversation transcript to Hindsight for future recall
• Dynamic bank IDs — supports per-project memory isolation based on the working directory
• Session-level upsert — uses the session ID as the document ID so re-running the same session updates rather than duplicates stored content
• Zero dependencies — pure Python stdlib, no pip install required

Architecture

The plugin uses three Codex hook events:

On UserPromptSubmit, the hook reads the prompt, queries Hindsight for the most relevant memories, and outputs a hookSpecificOutput.additionalContext block. Codex prepends this to the conversation before sending it to the model:

<hindsight_memories>
Relevant memories from past conversations...
Current time - 2026-03-27 09:14

- Project uses FastAPI with asyncpg — not SQLAlchemy [world] (2026-03-26)
- Preferred testing framework: pytest with pytest-asyncio [experience] (2026-03-26)
</hindsight_memories>

On Stop, the hook reads the session transcript, strips previously injected memory tags (to prevent feedback loops), and POSTs the conversation to Hindsight asynchronously.

Connection Modes

1. External API (recommended)

Connect to a running Hindsight server (cloud or self-hosted):

{
  "hindsightApiUrl": "https://api.hindsight.vectorize.io",
  "hindsightApiToken": "hsk_your_token"
}

2. Local Daemon

Run hindsight-embed locally. The session_start.py hook will detect it on apiPort (default 9077). The daemon is not auto-started by the Codex plugin — start it separately:

uvx hindsight-embed

Then leave hindsightApiUrl empty in your config and the plugin will connect to http://localhost:9077.

Configuration

Settings are loaded from ~/.hindsight/codex.json. Every setting can also be overridden via environment variable.

Loading order (later entries win):

1. Built-in defaults
2. Plugin settings.json (at ~/.hindsight/codex/settings.json)
3. User config (~/.hindsight/codex.json)
4. Environment variables

Connection

Memory Bank

Auto-Recall

Auto-Retain

Debug

Per-Project Memory

To give each project its own isolated memory bank, enable dynamic bank IDs:

{
  "dynamicBankId": true,
  "dynamicBankGranularity": ["agent", "project"]
}

With this config, running Codex in ~/projects/api and ~/projects/frontend stores and recalls memories separately. Bank IDs are derived from the working directory path.

Troubleshooting

Hooks not firing: Check that ~/.codex/config.toml contains codex_hooks = true under [features]. Re-run the installer to fix this automatically.

No memories recalled: Recall returns results only after something has been retained. Either complete one Codex session first, or seed your bank manually using the cookbook example.

Memory not being stored: retainEveryNTurns defaults to 10 — retain only fires every 10 turns. While testing, add "retainEveryNTurns": 1 to ~/.hindsight/codex.json.

Debug mode: Add "debug": true to ~/.hindsight/codex.json to see what Hindsight is doing on each turn:

[Hindsight] Recalling from bank 'codex', query length: 42
[Hindsight] Injecting 3 memories
[Hindsight] Retaining to bank 'codex', doc 'sess-abc123', 2 messages, 847 chars

High latency on recall: Use "recallBudget": "low" or reduce recallMaxTokens to speed up recall queries.