codex-agent-mem

Quickstart

This is the shortest path from clone to a working local setup.

1. Clone and install

PowerShell / Windows

git clone https://github.com/MarceloCaporale/codex-agent-mem.git
cd codex-agent-mem
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .[dev]

bash / macOS / Linux

git clone https://github.com/MarceloCaporale/codex-agent-mem.git
cd codex-agent-mem
python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

2. Verify the package

codex-agent-mem-smoke

codex-agent-mem-smoke

That should insert a sample turn into a local SQLite database and verify retrieval.

3. Generate Codex config

codex-agent-mem-bootstrap-codex --db-path "$HOME/.codex_agent_mem/codex_agent_mem.db"

codex-agent-mem-bootstrap-codex --db-path C:\Users\YOU\.codex_agent_mem\codex_agent_mem.db

Paste the generated output into ~/.codex/config.toml. The snippet already includes read-only MCP tool approvals plus a defensive MCP idle timeout for non-interactive Codex runs.

If you also want automatic AGENTS.md reinjection, add --sync-project-doc to the notify command before --db-path.

4. Optional local services

Start the inspection API:

codex-agent-mem-api --db-path "$HOME/.codex_agent_mem/codex_agent_mem.db"

codex-agent-mem-api --db-path C:\Users\YOU\.codex_agent_mem\codex_agent_mem.db

Then open the local inspector:

http://127.0.0.1:37770/ui

Start the MCP server:

codex-agent-mem-mcp --db-path "$HOME/.codex_agent_mem/codex_agent_mem.db"

codex-agent-mem-mcp --db-path C:\Users\YOU\.codex_agent_mem\codex_agent_mem.db

5. Rebuild the generated continuity block manually

codex-agent-mem-refresh-context --db-path "$HOME/.codex_agent_mem/codex_agent_mem.db" --project-key YOUR_PROJECT --cwd /path/to/project

codex-agent-mem-refresh-context --db-path C:\Users\YOU\.codex_agent_mem\codex_agent_mem.db --project-key YOUR_PROJECT --cwd C:\Path\To\Project

6. Run full checks

ruff check .
python -m compileall src
pytest -q
python -m build

This site is open source. Improve this page.