codex-agent-mem

codex-agent-mem: persistent local memory for MCP clients

Ask DeepWiki

Other languages: Español Deutsch Português do Brasil 中文 日本語

Portable, auditable, local-first MCP memory for MCP-compatible AI agents and coding workflows.

codex-agent-mem keeps durable project memory outside the model runtime, compresses continuity into smaller working packs, and carries forward operational state so MCP-compatible AI agents can resume with less repetition, fewer false “done” claims, and more control over what stays in context.

Everything is stored and processed locally by this MCP: SQLite database, FTS index, snapshots, telemetry metadata, and the optional inspector UI. codex-agent-mem does not send your memory, project data, prompts, or telemetry to any external server. MCP clients may still expose tool results to the model or service you configure, so treat retrieved memory as local tool output handed to that client.

Born for Codex and GPT workflows, codex-agent-mem has grown into a portable MCP memory layer for MCP-compatible runtimes including Codex CLI/Desktop, Claude Code, Google Gemini CLI, Qwen Code workflows using Ollama models, and other local or third-party CLI agent stacks. Validation is tracked per client/runtime and evidence level. Model-specific details stay in the validation docs so the README can describe the public surface without overclaiming one runtime.

codex-agent-mem lives locally, keeps memory auditable and pull-based, and does not send your stored memory to any external service.

Public baseline. Built in small, testable slices and still evolving, but already aligned for real use.

What’s new in v1.0.x

Latest releases: v1.0.2 Identity + Scope Patch v1.0.1 Transport + Local Security Hotfix v1.0.0 Low-Impact Runtime

Snapshot (synthetic v1.0 fixtures)

Scenario Profile Source tokens Pack tokens Saved not_modified Tools Lazy init Read-only
Small project continuity minimal 1,841 253 86.26% true 4 false->true true
Medium agent workflow minimal 4,855 270 94.44% true 4 false->true true
Large repeated audit minimal 9,731 269 97.24% true 4 false->true true
Sub-agent handoff example minimal 6,523 276 95.77% true 4 false->true true

Across these reproducible fixtures, repeated operational context was reduced from ~22,950 source tokens to ~1,068 memory-pack tokens, an approximate 95.35% reduction. This is not a universal guarantee; it shows the effect when an agent would otherwise resend the same project continuity.

Tools=4 refers to the pre-session-aware minimal profile used by these fixtures. In v1.0.1, minimal also includes mem_session_list, mem_scope_resolve, and mem_bootstrap_context, and the standard profile exposes 20 tools for broader retrieval, governance, and audit workflows.

Runtime validation snapshot

Runtime Setup Observed metrics Result
Writable MCP default Codex/Gemini/Claude local daemon bridges, read_only=false; full where writable tools are required mem_note_create wrote indexed manual notes and mem_search / mem_context_pack recovered them; mem_snapshot_create(project_key, label, session_id) recorded high-confidence provenance Writable manual-note and snapshot-provenance smokes passed
Codex Desktop Codex Desktop, MCP stdio, explicit retrieval-only minimal, read-only, compact synthetic v1.0 fixtures ~22,950 source tokens -> ~1,068 pack tokens, ~95.35% repeated-context reduction, not_modified=true on repeated packs Retrieval-only MCP validation plus public reproducible verification; writable continuity is covered by the writable default row
Codex CLI / codex exec Codex CLI MCP stdio path, short-lived / ephemeral execution same local MCP server and config style as Desktop; short-lived CLI lifecycle validated separately from the long-lived Desktop host behavior Validated Codex CLI path
Google Gemini CLI codex-agent-mem MCP stdio, explicit retrieval-only standard, read-only; compact when structured payloads are visible, otherwise verbose stable process, request counter increased as expected, object-root payloads verified where visible Retrieval-only MCP validation with client-exposure caveat
Claude Code Claude Opus 4.7, codex-agent-mem MCP stdio only, explicit retrieval-only standard, read-only, compact requests 3 -> 8, lazy init false -> true, same_db_process_count=2 with one Claude Code host active, spawn_storm_warning=false, mem_search count=2 Retrieval-only MCP validation passed
Qwen Code Qwen Code 0.15.0, local Ollama, qwen3.6:latest, explicit retrieval-only standard, read-only, compact real MCP calls to mem_context_pack, mem_search, mem_open_work, mem_completion_check, mem_health_runtime; requests 8, lazy init true, spawn_storm_warning=false, not_modified=true Retrieval-only local MCP validation passed
Qwen local model smokes Qwen Code 0.15.0 with Ollama models qwen3.6:35b-a3b-q8_0 and qwen3.5:9b both models answered CLI smoke tests and invoked mem_health_runtime through MCP stdio; retrieval-only read_only=true, clean stdin_eof exits Retrieval-only local model smokes passed
DeepSeek-V3.2 Qwen Code 0.15.0, deepseek-v3.2:cloud through Ollama Cloud, explicit retrieval-only standard, read-only, compact real MCP calls to mem_context_pack, mem_search, mem_health_runtime; requests 6, spawn_storm_warning=false, not_modified=true Retrieval-only cloud-backed MCP validation passed
Minimax M2.5 Qwen Code 0.15.0, minimax-m2.5:cloud through Ollama Cloud, explicit retrieval-only standard, read-only, compact real MCP calls to mem_context_pack, mem_search, mem_health_runtime; requests 6, not_modified=true Retrieval-only cloud-backed MCP validation passed
Kimi Code CLI Kimi Code CLI 1.38.0, codex-agent-mem MCP stdio, explicit retrieval-only standard, read-only, compact kimi mcp test codex-agent-mem connected and listed the expected standard-profile tools; Kimi K2.5 / Kimi K2.6 full model tool-call validation remains in continuous evaluation Retrieval-only MCP connection validated; model-run validation not claimed
Grok / xAI Protocol-level compatibility note MCP stdio / JSON-RPC protocol behavior reviewed Protocol note

Grok / xAI is listed as a protocol-level compatibility note, not live model tool-call validation. The live validated rows are the MCP client/model pairs measured directly: Codex Desktop/CLI, Google Gemini CLI, Claude Code, Qwen Code, Qwen local model smokes, DeepSeek-V3.2 through Ollama Cloud, Minimax M2.5 through Ollama Cloud, and Kimi Code CLI connection validation. More generally, codex-agent-mem is model-agnostic at the MCP layer; new pairs are added as their live measurements are captured.

Verifiable Results

codex-agent-mem includes a reproducible verification sandbox and a public evidence export for v1.0.0. The fixture approach is intentional: the MCP optimizes repeatable operational-context handling, so the public evidence keeps the repeated context controlled instead of turning the benchmark into a different conversation every run.

The public v1.0.x evidence combines reproducible verification fixtures with live MCP runtime validation across the runtimes listed above. It reports context compression, repeated-pack avoidance with known_pack_hash, lazy initialization, minimal tool surface, explicit read-only mode safety, response diet, local telemetry, closure control, and a sub-agent handoff example.

See: Verification Evidence and v1.0.0 Results.

Claude Code and claude-mem

codex-agent-mem runs in Claude Code as a standard MCP stdio server. It does not install session-start hooks, stop hooks, or automatic post-turn summarization. Memory is retrieved on demand through MCP tools such as mem_context_pack, mem_search, mem_open_work, and mem_completion_check.

If you already use claude-mem, both tools can technically coexist. For lower-overhead, lower-latency workflows, use one active memory layer at a time. In local validation with one Claude Code host active, codex-agent-mem alone kept the runtime compact (same_db_process_count=2, spawn_storm_warning=false). Running it alongside claude-mem increased visible tool surface to 61 tools, added a session-start memory block of about 6,995 tokens, and showed post-turn stop-hook delays. This does not break codex-agent-mem, but it makes results harder to compare and can increase overhead and latency.

Use codex-agent-mem when you prefer local-first, auditable, pull-based memory with explicit retrieval and deterministic closure checks. Use additional memory plugins only when you intentionally want their automatic hook-based behavior.

For token-sensitive Claude Code workflows, codex-agent-mem is designed for low overhead by default: no session-start injection, no stop-hook summarization, compact responses, explicit budgets, and pack_hash / not_modified short-circuiting for unchanged packs.

Optional companion: clean-process-ended

codex-agent-mem v1.0.1 and clean-process-ended (GitHub) v0.7.2 work independently, but they solve adjacent problems in local agent workflows.

Together they improve end-of-task workflows: recover context, finish the work, check local process state, and store compact close evidence without making either MCP a hard dependency of the other.

What you get

Continuity

Closure Control

Governance and Audit

Key docs: AGENTS.md Quickstart Codex Integration Codex Desktop Note Support Matrix Design Decisions

Built for long audits, multi-step project continuity, and workflows where the real failure mode is not only forgetting decisions, but also dropping scope, losing blockers, and declaring completion too early.

Status

1.0.2 is the current 1.0.x maintenance release. 1.0.0 remains the public verification baseline for the reproducible metrics below.

What works today:

What is intentionally not in scope yet:

Why this repository exists

Installation model

codex-agent-mem is installed as a local Python package and exposed to MCP-compatible clients through stdio commands.

The stable pattern is:

  1. install the package
  2. point the MCP client at the installed command
  3. keep the memory database local and auditable

Codex-specific notify and mcp_servers snippets are generated by codex-agent-mem-bootstrap-codex; other MCP clients use their own configuration files.

Quickstart

If you want the shortest path from clone to a working local setup:

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]
codex-agent-mem-smoke
codex-agent-mem-bootstrap-codex --db-path C:\Users\YOU\.codex_agent_mem\codex_agent_mem.db

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]
codex-agent-mem-smoke
codex-agent-mem-bootstrap-codex --db-path "$HOME/.codex_agent_mem/codex_agent_mem.db"

For Codex, paste the generated snippet into ~/.codex/config.toml. For other MCP clients, use the common stdio command in Configure MCP clients.

Install

Option A: pipx from GitHub

Install directly from the repository URL:

pipx install "git+https://github.com/MarceloCaporale/codex-agent-mem.git"
codex-agent-mem-smoke

pipx install "git+https://github.com/MarceloCaporale/codex-agent-mem.git"
codex-agent-mem-smoke

Option B: local development install

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]
pytest -q
codex-agent-mem-smoke

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]
pytest -q
codex-agent-mem-smoke

Configure MCP clients

The MCP server entry point is the same for every compatible client:

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

Point your MCP-capable client at that installed stdio command. The validated public v1.0.x paths include Codex CLI/Desktop, Claude Code, Google Gemini CLI, Qwen Code with local Qwen models through Ollama, DeepSeek-V3.2 and Minimax M2.5 through Ollama Cloud, plus Kimi Code CLI connection validation.

Codex helper

Generate a ready-to-paste snippet:

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

For Codex, that prints the notify block, the [mcp_servers."codex-agent-mem"] block, an explicit stdio idle-timeout, and MCP tool approvals you can paste into ~/.codex/config.toml.

For long-lived Codex Desktop sessions, prefer a longer MCP idle timeout such as --idle-timeout-seconds 1800 so the Desktop thread is less likely to keep a closed stdio transport. For short CLI or codex exec runs, 300 seconds is usually enough and keeps cleanup faster.

Automatic AGENTS.md reinjection is now opt-in. Add --sync-project-doc to the notify command only if you want generated working-memory blocks written back into the working directory.

How agents should use it

Once configured, the agent should use codex-agent-mem proactively when continuity matters. You should not need to repeat “use the memory MCP” every few turns.

Recommended pattern:

This is where the practical token economy comes from: compact continuity first, targeted expansion only when needed, and no repeated pack when nothing changed.

Example files live under examples/codex, with Ollama workflow notes under examples/ollama.

Run locally

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:

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

The current MCP transport is stdio. That means one process per host connection is normal; it is not a singleton daemon. The defensive idle timeout is there to let unused or orphaned instances exit cleanly.

Recommended defaults: use a longer timeout for Codex Desktop sessions, for example 1800 seconds, and a shorter timeout for CLI/ephemeral runs, for example 300 seconds.

Manually rebuild the generated continuity block for one directory:

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

Quick verification

Run the smoke test:

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

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

That inserts a sample turn, extracts observations, and verifies recent retrieval and project brief generation.

Token efficiency: what saves tokens now

This is token efficiency for agent workflows, not magic compression. codex-agent-mem improves the token economy by reducing repeated project context, reusing unchanged packs through known_pack_hash, and letting agents expand only the memory they need.

Approximate token savings

In plain language: this usually aims to cut down the amount of repeated context you have to replay, not to eliminate it completely.

What we can say honestly from local validation:

Examples from the public v1.0 verification sandbox:

Important: this is not a fixed guarantee per prompt. If the compact pack is not actually smaller than the source context, codex-agent-mem skips reinjection instead of pretending it saved tokens.

What this helps catch now

Repository layout

Documentation map

Release surface

This repository includes:

Author

Created and maintained by Marcelo Caporale.

This site is open source. Improve this page.