Codex-Mem

Codex-Mem is a Codex-native memory service inspired by claude-mem.

It reads real Codex session artifacts from ~/.codex, turns them into searchable observations and summaries, stores them in SQLite, and exposes that data through:

• a local CLI
• a local HTTP API
• a stdio MCP server

What You Can Do With It

• ingest Codex rollout files from ~/.codex/sessions
• search past work by keyword
• inspect timeline context around a memory hit
• fetch full stored observations
• build a compact context block for a project
• expose the same retrieval flow to MCP-compatible clients

Current Status

This repository is the working v1.

Implemented today:

• Codex rollout ingestion
• heuristic observation and session summary generation
• SQLite-backed storage
• local HTTP API
• stdio MCP server

Not implemented yet:

• LLM-based summarization
• automatic startup context injection into Codex
• full Claude-Mem hook parity

Tech Stack

• Language: Python 3.9+
• Storage: SQLite
• CLI: argparse
• HTTP API: http.server
• Tests: unittest
• Install style: source checkout or editable local package

Project Layout

codex_mem/
  cli.py          CLI entrypoint
  ingest.py       Codex session discovery and ingestion
  normalize.py    Event normalization
  summarize.py    Heuristic summary + observation generation
  storage.py      SQLite schema and queries
  server.py       HTTP API
  mcp.py          stdio MCP server
  skill_install.py Installer and MCP registration helpers
scripts/
  install_codex_skill.py  Install the packaged Codex skill
  run_codex_mem_mcp.py    Repo-local MCP launcher
skills/
  codex-mem/      Packaged Codex skill bundle
tests/
  fixtures/       Sample Codex rollout data
docs/
  README.md       Detailed setup and usage guide

Prerequisites

Before you start, make sure you have:

• Python 3.9 or newer
• a local Codex installation that writes data to ~/.codex
• permission to read your local ~/.codex directory

Optional but recommended:

• git, if you want to clone the repository
• a Python virtual environment

Download The Project

You can get the project in either of these ways.

Option 1: Clone the Repository

Replace <repo-url> with the repository URL where this project is hosted.

git clone <repo-url> codex-mem
cd codex-mem

Option 2: Download a ZIP Archive

1. Download the repository ZIP from your Git host.
2. Extract it.
3. Open a terminal in the extracted folder.

Example:

cd /path/to/codex-mem

Install It

Recommended: Use a Virtual Environment

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -e .

That installs the package in editable mode and gives you the codex-mem command.

Windows PowerShell:

py -3 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

If PowerShell blocks activation, run:

Set-ExecutionPolicy -Scope Process Bypass

then activate the environment again.

No-Install Option

You can also run the project directly from the source tree:

python3 -m codex_mem --help

First-Time Quick Start

If you just want to prove the project works end-to-end:

python3 -m codex_mem ingest
python3 -m codex_mem search "memory"
python3 -m codex_mem context --cwd "$PWD"
python3 -m codex_mem serve --port 37777

If you installed the package with pip install -e ., you can use:

codex-mem ingest
codex-mem search "memory"
codex-mem context --cwd "$PWD"
codex-mem serve --port 37777

Install As A Codex Skill

If you want Codex to use this as an actual skill instead of just a standalone tool, run:

python3 scripts/install_codex_skill.py

Windows PowerShell:

py -3 scripts\install_codex_skill.py

That installer:

• copies the packaged skill to ~/.codex/skills/codex-mem
• registers a local MCP server named codex-mem
• copies a self-contained runtime snapshot into the installed skill
• points Codex at the installed launcher inside ~/.codex/skills/codex-mem/runtime

To test the install without touching your real Codex home:

python3 scripts/install_codex_skill.py --codex-home /tmp/test-codex-home/.codex

After installation, verify MCP registration:

codex mcp get codex-mem --json

After a successful install, the installed skill no longer depends on the original GitHub checkout staying on disk. Re-run the installer when you want to upgrade to a newer version.

How Codex-Mem Finds Data

By default, Codex-Mem reads from:

~/.codex

That is where Codex session rollouts and SQLite state files normally live.

By default, Codex-Mem writes its own database to:

./.codex-mem/codex_mem.db

This means:

• source data comes from your Codex home
• Codex-Mem’s own index lives inside the current working directory

You can override both locations with:

• --codex-home
• --data-dir

Example:

python3 -m codex_mem --codex-home ~/.codex --data-dir ./local-memory ingest

CLI Commands

Top-level help:

python3 -m codex_mem --help

Available commands:

• ingest
• search
• timeline
• context
• serve
• mcp

1. Ingest Codex Sessions

Scan ~/.codex/sessions, normalize the sessions, and store searchable memory.

python3 -m codex_mem ingest

Example output:

{
  "sessions_seen": 5,
  "sessions_ingested": 5,
  "sessions_skipped": 0,
  "events_written": 3288,
  "observations_written": 1174
}

2. Search Memory

Search observations and session summaries.

python3 -m codex_mem search "sqlite"

Restrict results to a project root:

python3 -m codex_mem search "mcp" --cwd "$PWD"

Search only observations:

python3 -m codex_mem search "timeline" --type observations --limit 5

3. View Timeline Around A Memory

Use an observation id:

python3 -m codex_mem timeline --observation-id 1

Or let Codex-Mem find the first matching observation:

python3 -m codex_mem timeline --query "sqlite"

4. Build A Context Block

Generate a compact markdown context block for recent work:

python3 -m codex_mem context --cwd "$PWD"

That output is designed to be dropped into an agent prompt or startup context.

5. Start The HTTP API

python3 -m codex_mem serve --host 127.0.0.1 --port 37777 --watch

--watch tells Codex-Mem to keep re-ingesting new or changed session files while the server is running.

6. Start The MCP Server

python3 -m codex_mem mcp

Or with background re-ingest enabled:

python3 -m codex_mem mcp --watch

This runs a stdio MCP server suitable for MCP-capable clients.

HTTP API

When you run:

python3 -m codex_mem serve --port 37777

you get these endpoints:

• GET /api/health
• POST /api/ingest
• GET /api/search?query=...
• GET /api/timeline?observation_id=...
• POST /api/observations/batch
• GET /api/context?cwd=...

HTTP Examples

Health check:

curl http://127.0.0.1:37777/api/health

Search:

curl "http://127.0.0.1:37777/api/search?query=sqlite&limit=5"

Build context:

curl "http://127.0.0.1:37777/api/context?cwd=$(pwd)"

Re-run ingest:

curl -X POST http://127.0.0.1:37777/api/ingest \
  -H "Content-Type: application/json" \
  -d '{}'

Fetch observations in batch:

curl -X POST http://127.0.0.1:37777/api/observations/batch \
  -H "Content-Type: application/json" \
  -d '{"ids":[1,2,3]}'

MCP Tool Surface

The stdio MCP server currently exposes these tools:

• search_memory
• get_timeline
• get_observations
• build_context
• ingest_sessions

These map directly to the same underlying storage and ingest logic used by the CLI and HTTP API.

Skill Package

This repository now includes a packaged Codex skill bundle at:

skills/codex-mem

It contains:

• SKILL.md
• agents/openai.yaml
• references/setup.md

The MCP launcher used for Codex registration lives at:

~/.codex/skills/codex-mem/runtime/run_codex_mem_mcp.py

During installation, a runtime copy of the codex_mem package is also written to:

~/.codex/skills/codex-mem/runtime/codex_mem

Example MCP Smoke Test

You can verify the MCP server from a terminal:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | python3 -m codex_mem mcp

You should see a JSON-RPC initialize response followed by a tools/list response.

Development

Run the full test suite:

python3 -m unittest discover -s tests -v

Run a single test module:

python3 -m unittest tests.test_mcp -v

Run the skill installer helper in a safe temporary Codex home:

python3 scripts/install_codex_skill.py --codex-home /tmp/test-codex-home/.codex

GitHub Release Notes

If you publish this on GitHub, the user-facing install path is now:

git clone <repo-url> codex-mem
cd codex-mem
python3 scripts/install_codex_skill.py
codex mcp get codex-mem --json

Windows PowerShell:

git clone <repo-url> codex-mem
cd codex-mem
py -3 scripts\install_codex_skill.py
codex mcp get codex-mem --json

Recommended release checklist:

• tag a release
• keep the README install command near the top of the repo
• mention Python 3.9+ and the Codex CLI as prerequisites
• tell users to rerun the installer after upgrading to a new version

Compile the package as a syntax smoke test:

python3 -m compileall codex_mem

Troubleshooting

ingest returns zero sessions

Check whether Codex has actually written local sessions:

ls ~/.codex/sessions

If that directory is missing or empty, Codex-Mem has nothing to ingest yet.

Permission errors when reading ~/.codex

Make sure the user running Codex-Mem can read:

• ~/.codex/sessions
• ~/.codex/state_*.sqlite

Search returns no useful results

Run ingest again first:

python3 -m codex_mem ingest

Then try a broader query or remove the --cwd filter.

I want the database somewhere else

Use --data-dir:

python3 -m codex_mem --data-dir /tmp/codex-mem-data ingest

I want to point at another Codex home

Use --codex-home:

python3 -m codex_mem --codex-home /path/to/other/.codex ingest

More Documentation

For a longer operational walkthrough, see docs/README.md.

For the design and implementation history, see:

• 2026-03-17-codex-mem-design.md
• 2026-03-17-codex-mem.md