# GhostPaw Codex

> GhostPaw Codex is an open-source MCP server for knowledge and memory. Local agent memory that stores beliefs with sources, certainty and revision history. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, Linux, macOS, Windows, self-hosted
- **Website:** https://codex.ghostpaw.dev
- **Repository:** https://github.com/ghostpawjs/codex
- **MCP Registry name:** io.github.GhostPawJS/codex
- **Categories:** knowledge and memory
- **Listing updated:** 2026-11-14

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

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

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `retire_belief`: Deletes a belief and its whole lineage.

## 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

- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Nautilus Compass Memory](https://ai-powered.com/mcp/nautilus-compass-memory): Nautilus Compass Memory is an open-source MCP server for knowledge and memory.
- [note1](https://ai-powered.com/mcp/note1): note1 is an MCP server for productivity.
- [MedXpert 图书馆连接器（通用版）](https://ai-powered.com/mcp/medxpert): MedXpert 图书馆连接器（通用版） is an open-source MCP server for knowledge and memory.
- [Context Nest](https://ai-powered.com/mcp/context-nest): Context Nest is a freemium MCP server for knowledge and memory.
- [Tulsa Ecosystem Map](https://ai-powered.com/mcp/tulsa-ecosystem-map): Tulsa Ecosystem Map is a free MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/ghostpaw-codex
