Skip to content
MCP server

GhostPaw Codex

Local agent memory that stores beliefs with sources, certainty and revision history

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, Linux, macOS
Runs
Locally
Version
0.6.5
Listing updated
3 days ago

About GhostPaw Codex

GhostPaw Codex is an open-source MCP server for knowledge and memory. It runs locally on your machine and is started by your AI client.

Codex is built around one failure: when an agent saves a wrong fact, every later agent trusts it. Instead of appending lines to a markdown file, each belief is a row with a claim, a category, a source (explicit, observed, distilled or inferred), a certainty and an evidence count. Starting certainty follows the source: 90% explicit, 80% observed, 50% inferred.

Corrections replace rather than pile up. A corrected belief is marked superseded and drops out of recall, while the new one records its lineage with a before and after diff. Freshness decays from the last confirmation, so a belief unconfirmed for 90 days shows about 37% freshness and is flagged stale. Inferred and distilled beliefs, and single-evidence ones, are flagged for review after a seven-day grace period. Retiring a belief deletes it and its whole lineage.

Everything lives in one SQLite file (default ~/.ghostpaw/codex.db, changed with GHOSTPAW_CODEX_DB). Recall is lexical, using full-text search and character-trigram similarity, so no embedding model is called. It is MIT licensed with zero runtime dependencies, and ships as a release binary, an npm package needing Node.js 24 or newer, an .mcpb bundle, a CLI and a library. The README says all surfaces are generated from the same seven tools.

Install

Run in a terminal

claude mcp add codex -- npx -y @ghostpaw/codex

Add to claude_desktop_config.json

{
  "mcpServers": {
    "codex": {
      "command": "npx",
      "args": [
        "-y",
        "@ghostpaw/codex"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "codex": {
      "command": "npx",
      "args": [
        "-y",
        "@ghostpaw/codex"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "codex": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@ghostpaw/codex"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "codex": {
      "command": "npx",
      "args": [
        "-y",
        "@ghostpaw/codex"
      ]
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "codex": {
      "command": "npx",
      "args": [
        "-y",
        "@ghostpaw/codex"
      ]
    }
  }
}

Configuration

  • GHOSTPAW_CODEX_DBSQLite database path (default: ~/.ghostpaw/codex.db)
  • GHOSTPAW_CODEX_DBSQLite database path (default: ~/.ghostpaw/codex.db)

Tools this server provides (1)

Taken from the project documentation; the running server may differ.

retire_belief
Deletes a belief and its whole lineage.

What it does

Sourced beliefs
Each belief carries a source, certainty and evidence count.
Revision lineage
Corrections supersede old beliefs and keep a before and after diff.
Freshness decay
Unconfirmed beliefs lose freshness and are flagged stale.
Review flags
Highlights low-trust, single-evidence, stale and fading beliefs.
Lexical recall
Full-text and trigram search with no embedding model.
Single SQLite file
Stores all memory locally in one database.
Hard delete
Retire removes a belief and its whole lineage.

Good for

  • Give coding agents shared memory they can correct
  • Find stale or weakly evidenced facts before relying on them
  • Replace a markdown memory file with auditable records
  • Keep agent memory fully local with no embedding service
  • Delete sensitive facts completely from memory

Pricing

Open source

Free, MIT licence

Prices change. Check codex.ghostpaw.dev before you buy.

GhostPaw Codex FAQ

Where is data stored?

In one local SQLite file, by default ~/.ghostpaw/codex.db, configurable with GHOSTPAW_CODEX_DB.

Does it call an embedding model?

No. Recall uses full-text search and character-trigram similarity.

What does it cost?

It is free under the MIT licence.

What does it need to run?

The release binary includes its runtime; npm and library use need Node.js 24 or newer.

Is GhostPaw Codex free?

Yes. GhostPaw Codex is open source, so you can use and self-host it for free.

How do I add GhostPaw Codex to Claude Code?

Run this command in your terminal: claude mcp add codex -- npx -y @ghostpaw/codex

What are the best alternatives to GhostPaw Codex?

The closest alternatives to GhostPaw Codex are Codebase Memory, XERJ, Claude Code Ultimate Guide, Nautilus Compass Memory and note1.

Alternatives to GhostPaw Codex

  1. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  2. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  3. MCP server for searching the Claude Code Ultimate Guide from any MCP client

    Runs locally
    • Open source
    • 6.5K GitHub stars
    • AI models and LLM tooling
  4. Local-first long-term memory layer for AI agents, served over MCP

    Not checked yet
    • 5 tools
    • Remote
    • Open source
    • 1.3K GitHub stars
    • Knowledge and memory
  5. note1

    MCP server

    MCP server giving AI assistants search and summaries across your note1 meetings

    • 4 tools
    • Remote
    • Free trial
    • 1 GitHub star
    • Productivity