Codex Memory

Local Markdown-backed memory tools for Codex and other MCP-capable agents.

Codex Memory keeps durable agent knowledge in ordinary Markdown files, builds local indexes for retrieval, and exposes the result through both a CLI and an MCP server. It is designed for local-first use: your memory vault and session transcripts stay on your machine unless you share them yourself.

Features

• Markdown memory vault with simple YAML front matter.

• CLI commands for doctor, write, read, search, reindex, hygiene, and weekly-hygiene.

• MCP tools: search_memory, read_memory, write_memory, reindex_memory, and memory_hygiene.

• Local keyword retrieval with SQLite and an optional Tantivy helper.

• Optional semantic retrieval when CODEX_MEMORY_ENABLE_SEMANTIC=1.

• Local browser tools for recent sessions, agent monitoring, and report-board drafting.

• Codex hook entrypoints for session-start context and stop-time candidate capture.

Related MCP server: Caduceus Memory MCP

Install

Use Python 3.12 or newer.

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

Build the optional Tantivy keyword helper:

cd rust/codex-memory-keyword
cargo build --release

The Python implementation still works without the helper, but keyword search is faster after it is built.

Quick Start

Copy the synthetic example vault to a writable location:

cp -R examples/memories /tmp/codex-memory-demo

Run the basic workflow:

PYTHONPATH=src python3 -m codex_memory --memory-root /tmp/codex-memory-demo doctor
PYTHONPATH=src python3 -m codex_memory --memory-root /tmp/codex-memory-demo reindex --force
PYTHONPATH=src python3 -m codex_memory --memory-root /tmp/codex-memory-demo search "demo workflow" --status active,risk_pending
PYTHONPATH=src python3 -m codex_memory --memory-root /tmp/codex-memory-demo hygiene

Create a new candidate memory:

PYTHONPATH=src python3 -m codex_memory --memory-root /tmp/codex-memory-demo write \
  --title "Demo candidate" \
  --body "A short note for later review." \
  --keyword Codex

Configuration

Defaults are intentionally home-relative and overrideable:

• CODEX_MEMORY_ROOT: memory vault root. Defaults to ~/.codex/memories.

• CODEX_MEMORY_SERVICE_ROOT: source checkout root used to find the optional Rust keyword helper. Defaults to the repository root in editable installs.

• CODEX_MEMORY_ENABLE_SEMANTIC=1: enables semantic indexing/search.

• CODEX_MEMORY_TRANSCRIPT_ROOTS: extra transcript roots for session and hook tests, separated by the platform path separator.

• CODEX_MEMORY_PROJECT_SPECIFIC_TERMS: comma-separated local lint terms used to flag records that should be filed under a concrete project instead of a shared knowledge-base project.

Every CLI command also accepts --memory-root.

MCP Server

Start the MCP server with:

codex-memory-mcp

Example MCP client command configuration:

{
  "command": "codex-memory-mcp",
  "env": {
    "CODEX_MEMORY_ROOT": "/absolute/path/to/your/memories"
  }
}

Available MCP tools:

• search_memory(query, project?, type?, status?, limit=5, mode?, diagnostics=false)

• read_memory(id_or_path)

• write_memory(record, update_id?)

• reindex_memory(force=false)

• memory_hygiene(stale_days=30)

status accepts comma-separated values such as active,risk_pending. read_memory and write_memory reject absolute paths or .. traversal outside the configured vault.

Local Browser Tools

All browser tools bind to 127.0.0.1 by default.

PYTHONPATH=src python3 -m codex_memory --memory-root /tmp/codex-memory-demo sessions ui --no-open
PYTHONPATH=src python3 -m codex_memory --memory-root /tmp/codex-memory-demo agents ui --no-open
PYTHONPATH=src python3 -m codex_memory --memory-root /tmp/codex-memory-demo reports ui --no-open

• sessions ui reads recent Codex JSONL transcripts from ~/.codex/sessions and any extra CODEX_MEMORY_TRANSCRIPT_ROOTS.

• agents ui derives parent/subagent status summaries from local transcripts.

• reports ui searches the memory vault, lets you select/edit candidate material, and exports Markdown under report-board-output/.

These tools do not write transcripts, do not call external services, and do not publish a network-facing endpoint unless you explicitly bind them elsewhere.

Hooks

The package exposes two CLI hook commands:

codex-memory --memory-root /absolute/path/to/memories hook-session-start
codex-memory --memory-root /absolute/path/to/memories hook-stop

hook-session-start ensures the vault layout exists and returns compact startup guidance. hook-stop reads an allowed local transcript and writes an inbox candidate only when it sees reusable-experience signals such as blockers, verified fixes, durable rules, or unresolved risks.

Memory Format

Records are Markdown files with front matter:

---
id: mem-demo-workflow
title: Demo workflow
project: demo-project
type: workflow
status: active
keywords:
  - Codex
  - demo
source: example
---
# Demo workflow

Use this record as searchable local context.

Supported type values are candidate, project_profile, long_term_rule, issue, build_flow, protocol, script, hardware_risk, and workflow. Supported status values are candidate, active, risk_pending, and archived.

Privacy

Do not publish your real memory vault or session transcripts. This repository contains only code and synthetic examples. See docs/privacy.md for the full local-data boundary.

Development

Run the Python tests:

PYTHONPATH=src python3 -m unittest discover -s tests

Run the Rust helper tests:

cd rust/codex-memory-keyword
cargo test

Optional live-vault retrieval checks are skipped unless explicitly enabled:

CODEX_MEMORY_LIVE_GOLDEN=1 CODEX_MEMORY_LIVE_ROOT=/path/to/memories \
  PYTHONPATH=src python3 -m unittest \
  tests.test_markdown_store.MarkdownStoreTests.test_live_vault_golden_queries_when_enabled

License

MIT.