Persistent memory MCP server for Codex, local-first and SQLite-backed.

🇺🇸 English • 🇪🇸 Español • 🇩🇪 Deutsch

Quick Start • Documentation • Automatic Mode • Architecture Design • How It Works • MCP Search Tools • System Requirements • Contributing • License

---

codex-mem preserves project memory across Codex sessions with a practical progressive retrieval workflow.

Quick Start

One-command automated install:

npm run mcp:install

Installer options:

bash scripts/install-mcp.sh --help
bash scripts/install-mcp.sh --dry-run
bash scripts/install-mcp.sh --dry-run --no-register
bash scripts/install-mcp.sh --name codex-mem --db-path .memory/codex-mem.db

Automatic workflow helpers:

npm run auto:mode -- start --ingest --project codex-mem
npm run auto:mode -- end --summary "Completed MCP setup docs and tests."
npm run auto:mode -- commit
npm run auto:install-hooks -- --project codex-mem

Manual install path:

npm install
export MEMORY_DB_PATH=.memory/codex-mem.db
npm run migrate
npm run mcp:start

VS Code MCP setup values:

• Name: codex-mem
• Transport: STDIO
• Command: npm
• Arguments: run, mcp:start, --silent
• Environment variable: MEMORY_DB_PATH=.memory/codex-mem.db
• Working directory: absolute path to your codex-mem repository

Documentation

Root

• README.md
• CONTRIBUTING.md
• LICENSE
• scripts/install-mcp.sh
• scripts/auto-memory.sh
• scripts/install-git-hooks.sh
• SECURITY.md
• CHANGELOG.md
• .env.example

GitHub Collaboration

• .github/ISSUE_TEMPLATE/bug_report.yml
• .github/ISSUE_TEMPLATE/feature_request.yml
• .github/ISSUE_TEMPLATE/config.yml
• .github/pull_request_template.md

Docs Index

• docs/README.md

Planning and Product

• docs/project-plan.md
• docs/roadmap.md
• docs/requirements.md
• docs/mvp-spec.md
• docs/delivery-plan.md
• docs/implementation-kickoff.md

Architecture and Design

• docs/architecture.md
• docs/architecture-diagram.mmd
• docs/data-model.md
• docs/data-model-diagram.mmd
• docs/technical-design.md
• docs/runtime-decision.md

API and Operations

• docs/mcp-api-spec.md
• docs/auto-mode.md
• docs/auto-capture-wrapper.md
• docs/setup-guide.md
• docs/usage-guide.md
• docs/troubleshooting.md
• docs/operations-runbook.md
• docs/security-baseline.md
• docs/test-strategy.md

Project Logs

• docs/decisions.md
• docs/session-log.md

Internationalization

• docs/i18n/README.es.md
• docs/i18n/README.de.md

Brand Assets

• docs/public/codex-mem.png
• docs/public/codex-mem-wordmark.svg

Automatic Mode

codex-mem currently supports a practical semi-automatic workflow:

npm run auto:mode -- start --project codex-mem --ingest
npm run auto:mode -- end --project codex-mem --summary "Session handoff summary."
npm run auto:mode -- commit --project codex-mem
npm run auto:install-hooks -- --project codex-mem

See full details in docs/auto-mode.md.

Architecture Design

flowchart LR
  User["User / Codex Session"] --> MCP["MCP Interface"]
  MCP --> Service["Memory Service"]

  Service --> Policy["Policy Layer"]
  Policy --> Storage["Storage Layer (SQLite + FTS)"]

  Service --> Ingest["Ingestion Layer"]
  Ingest --> Sources["Project Sources (docs, logs)"]
  Ingest --> Policy

  Service --> Search["Search Flow"]
  Search --> Storage

  Service --> Timeline["Timeline Flow"]
  Timeline --> Storage

  Service --> Details["Details Flow"]
  Details --> Storage

  Service --> Save["Save Flow"]
  Save --> Policy

  subgraph LocalRuntime["Local Runtime"]
    MCP
    Service
    Policy
    Storage
    Ingest
  end

Loading

How It Works

1. save_memory stores key decisions, fixes, and constraints.
2. search returns compact index entries for low-cost discovery.
3. timeline expands context around anchor entries.
4. get_entries fetches full details only for selected IDs.
5. ingest_docs imports docs with source/hash dedupe.
6. retention_dry_run reports cleanup candidates without deleting data.

MCP Search Tools

Recommended retrieval flow:

1. search
2. timeline
3. get_entries

Available MCP tools:

• save_memory
• search
• timeline
• get_entries
• ingest_docs
• retention_dry_run

System Requirements

• Node.js 20+
• npm
• Local filesystem write access for .memory/
• SQLite runtime support (via bundled dependency)

Contributing

1. Fork the repository
2. Create a feature branch
3. Add or update tests
4. Update docs for behavior changes
5. Open a pull request

See CONTRIBUTING.md.

License

Licensed under AGPL-3.0.

See LICENSE.