Persistent memory MCP server for Codex

Local first Codex memory via an MCP server backed by SQLite, with progressive retrieval tools for search, timeline context, and full entry details.

Harllens George | 2026-02-20

codex-mem logo. codex-mem wordmark.

codex-mem is a local first, SQLite backed MCP server for OpenAI Codex workflows. It preserves useful memory across Codex sessions so decisions, constraints, and fixes do not disappear between runs.

What this is

This is a practical MCP server that stores project memory locally in SQLite and exposes retrieval tools that fit day to day coding sessions.

Who it is for

  • Developers using OpenAI Codex in terminal or editor workflows
  • Teams that want local memory instead of hosted memory services
  • Builders who need repeatable handoffs between sessions

Get it

Compatibility

  • MCP-compatible clients and workflows (including Codex setups using MCP)
  • SQLite local storage with no external database requirement
  • Local-first usage pattern for controlled storage and retention

Why this matters

Most agent sessions are short lived. The moment a terminal closes, the project context often resets. The result is repeated explanations, repeated mistakes, and slow handoffs.

codex-mem solves that with a simple contract:

  • Store small, high signal memory entries (decisions, fixes, constraints).
  • Retrieve progressively, not by dumping everything into context.
  • Keep data local in a SQLite database you control.

What it gives you

Core capabilities:

  • SQLite storage with full text search for fast retrieval.
  • Progressive discovery flow: search, expand context, then fetch full details.
  • Doc ingestion with source hash dedupe, so re runs are safe.
  • Retention reporting so memory does not become noise.
  • Optional automation helpers to capture handoff summaries and commits.

Quick start

One command install

From the repository root:

npm run mcp:install

Manual setup

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

VS Code MCP settings

These values match the repo defaults:

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

How retrieval works (progressive by design)

Instead of always loading full records, the recommended flow is:

  1. search: find matching entries quickly.
  2. timeline: expand context around an anchor entry.
  3. get_entries: fetch full details only for selected IDs.

That pattern stays fast as your memory grows.

MCP tools (high level)

Common tools you will use:

  • save_memory: store a new memory entry.
  • search: discovery, compact results.
  • timeline: context around an anchor.
  • get_entries: full details for selected IDs.
  • ingest_docs: import docs with dedupe.
  • retention_dry_run: report cleanup candidates.

Automatic mode (optional)

If you want a light workflow wrapper:

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

Common mistakes to avoid

  • Storing secrets in memory entries. Keep secrets in proper secret managers or local env files.
  • Saving long dumps. Prefer short, structured notes with a clear title and one to three key points.
  • Skipping retention. Run retention reports periodically so the database stays high signal.

Links