Skip to content

KeystoneScience/codex-mem

BranchesTags

Repository files navigation

Codex-mem

Persistent memory for Codex CLI, Claude Code, and MCP clients.

Codex-mem is a Codex-first port of claude-mem by Alex Newman (@thedotmack). The upstream project got the core memory architecture right. This repo carries that work forward for Codex with official Codex integration surfaces, passive MEMORY.md recall, and one-line setup.

NOTICE explains the upstream credit and license continuity.

Quick Start

Codex CLI

npx codex-mem-cli@latest codex setup

After setup, start Codex normally:

codex

That one command:

  • installs Bun, uv, and runtime dependencies if needed
  • copies the runtime into a stable local install directory
  • updates ~/.codex/config.toml with notify and [mcp_servers.codex_mem]
  • preserves and chains an existing notify command when it can do so safely
  • starts the worker and verifies health before exiting

npm note: the registry package is codex-mem-cli because codex-mem is already taken on npm. The GitHub project and installed CLI command are both codex-mem.

Claude Code

Codex-mem still carries forward the upstream Claude Code integration model. If you want the original Claude plugin workflow, install upstream claude-mem or adapt the plugin assets in this repo to your Claude plugin environment.

OpenClaw Gateway

Install the OpenClaw integration with:

curl -fsSL https://install.cmem.ai/openclaw.sh | bash

Why It Exists

  • Codex CLI can read MCP memory today, but write capture needs Codex-native ingestion surfaces.
  • claude-mem already proved the worker, search, and progressive-recall model.
  • Codex-mem adds notify, codex exec --json, and codex app-server capture so the same memory architecture works well in Codex.

Key Features

  • Persistent cross-session memory with SQLite, FTS5, and optional vector search
  • Codex-native ingestion via notify, exec --json, and app-server
  • Token-efficient recall through bootstrap_memory, search, timeline, and get_observations
  • Root MEMORY.md projections for passive recall in Codex
  • Web viewer on http://localhost:37777
  • Privacy controls including <private> stripping before persistence

Documentation

📚 View Full Documentation - Browse on official website

Getting Started

Best Practices

Architecture

Configuration & Development

How It Works

Core Components:

  1. 5 Lifecycle Hooks - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)
  2. Smart Install - Cached dependency checker (pre-hook script, not a lifecycle hook)
  3. Worker Service - HTTP API on port 37777 with web viewer UI and 10 search endpoints, managed by Bun
  4. SQLite Database - Stores sessions, observations, summaries
  5. mem-search Skill - Natural language queries with progressive disclosure
  6. Chroma Vector Database - Hybrid semantic + keyword search for intelligent context retrieval

See Architecture Overview for details.

MCP Search Tools

Codex-mem provides intelligent memory search through 4 MCP tools following a token-efficient 4-step workflow pattern:

The Workflow:

  1. bootstrap_memory - Build a compact memory brief for the current project/task
  2. search - Get compact index with IDs (~50-100 tokens/result)
  3. timeline - Get chronological context around interesting results
  4. get_observations - Fetch full details ONLY for filtered IDs (~500-1,000 tokens/result)

How It Works:

  • Claude and Codex can use MCP tools to search your memory
  • Start with bootstrap_memory when resuming work in a new session
  • Prefer passing cwd for repo-aware recall; project alone is a legacy fallback
  • Start with search to get an index of results
  • Use timeline to see what was happening around specific observations
  • Use get_observations to fetch full details for relevant IDs
  • ~10x token savings by filtering before fetching details

Available MCP Tools:

  1. bootstrap_memory - Compact project memory brief with follow-up observation IDs and repo-aware scoping via cwd/repoRoot
  2. search - Search memory index with full-text queries, filters by type/date/project
  3. timeline - Get chronological context around a specific observation or query
  4. get_observations - Fetch full observation details by IDs (always batch multiple IDs)

Example Usage:

// Step 1: Build a brief
bootstrap_memory(goal="resume auth refactor", cwd="/path/to/repo")

// Step 2: Search for index
search(query="authentication bug", type="bugfix", limit=10)

// Step 3: Review index, identify relevant IDs (e.g., #123, #456)

// Step 4: Fetch full details
get_observations(ids=[123, 456])

See Search Tools Guide for the upstream workflow background.

Codex CLI

Quick install for Codex CLI:

npx codex-mem-cli@latest codex setup

That one command:

  • copies the bundled runtime to ~/.claude-mem/codex
  • installs Bun, uv, and runtime dependencies if needed
  • updates ~/.codex/config.toml with notify plus [mcp_servers.codex_mem]
  • preserves and chains an existing notify command when it is a standard string-array config
  • starts the worker and verifies health on http://127.0.0.1:37777

Health check after install:

npx codex-mem-cli@latest codex doctor

After setup, keep using codex normally. The viewer stays available at http://localhost:37777.

Manual / advanced setup:

The worker now supports three Codex ingestion lanes:

  1. notify for stock Codex CLI turn-complete capture
  2. exec --json for CI / automation ingestion
  3. app-server for higher-fidelity streamed events

Safe MCP setup today (stdio transport):

[mcp_servers.codex_mem]
command = "/ABS/PATH/TO/node"
args = ["/Users/YOU/.claude-mem/codex/scripts/mcp-server.cjs"]
enabled = true
required = false

Codex notify example:

notify = ["/ABS/PATH/TO/node", "/Users/YOU/.claude-mem/codex/scripts/codex-notify.js"]

Automation / CI ingest example:

codex exec --json "implement X" | node ~/.claude-mem/codex/scripts/bun-runner.js ~/.claude-mem/codex/scripts/worker-service.cjs codex exec-json

Passive recall:

  • Enable CLAUDE_MEM_MEMORY_MD_ENABLED=true to keep a root MEMORY.md projection updated.
  • Add "MEMORY.md" to Codex project_doc_fallback_filenames if you want Codex to load that projection automatically.

System Requirements

  • Node.js: 18.0.0 or higher
  • Claude Code: Latest version with plugin support
  • Bun: JavaScript runtime and process manager (auto-installed if missing)
  • uv: Python package manager for vector search (auto-installed if missing)
  • SQLite 3: For persistent storage (bundled)

Windows Setup Notes

If you see an error like:

npm : The term 'npm' is not recognized as the name of a cmdlet

Make sure Node.js and npm are installed and added to your PATH. Download the latest Node.js installer from https://nodejs.org and restart your terminal after installation.

Configuration

Settings are managed in ~/.claude-mem/settings.json (auto-created with defaults on first run). That path is inherited from the upstream claude-mem architecture for compatibility.

See the Configuration Guide for all available settings and examples.

Development

See the Development Guide for build instructions, testing, and contribution workflow.

Publishing

The npm package name is codex-mem-cli.

For the first npm release of a new package, add an NPM_TOKEN repository secret and run the publish workflow on a v* tag.

After the package exists on npm, you can switch to npm trusted publishing for KeystoneScience/codex-mem and .github/workflows/npm-publish.yml, then remove NPM_TOKEN.

Manual publish still works:

npm adduser
npm publish --access public --provenance

Troubleshooting

If experiencing issues, describe the problem to Claude and the troubleshoot skill will automatically diagnose and provide fixes.

See the Troubleshooting Guide for common issues and solutions.

Bug Reports

Create comprehensive bug reports with the automated generator:

cd ~/.claude/plugins/marketplaces/thedotmack
npm run bug-report

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes with tests
  4. Update documentation
  5. Submit a Pull Request

See Development Guide for contribution workflow.

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

Copyright (C) 2025 Alex Newman (@thedotmack). All rights reserved.

See the LICENSE file for full details.

What This Means:

  • You can use, modify, and distribute this software freely
  • If you modify and deploy on a network server, you must make your source code available
  • Derivative works must also be licensed under AGPL-3.0
  • There is NO WARRANTY for this software

Note on Ragtime: The ragtime/ directory is licensed separately under the PolyForm Noncommercial License 1.0.0. See ragtime/LICENSE for details.

Support

Built with Claude Agent SDK | Powered by Claude Code | Made with TypeScript

About

Persistent memory for Codex CLI, Claude Code, and MCP clients

Topics

memory mcp developer-tools codex claude-code

Resources

Readme

License

View license
Activity

Stars

5 stars

Watchers

1 watching

Forks

2 forks
Report repository

Releases 1

v11.0.0 Latest
Mar 7, 2026

Packages

 
 
 

Contributors

Languages