GhostPaw Codex

@ghostpaw/codex

Agent memory as beliefs with a source, a certainty and a revision history.

ghostpaw-codex --help

Local, evidence-backed memory for agents. One SQLite file, zero runtime dependencies.

Codex stores what an agent believes as claims with a source, a certainty, evidence counts, decay and an honest revision history. Agents search before they remember, confirm or correct instead of appending, and see which beliefs are stale, fading or weakly evidenced. It runs as a TypeScript library, an MCP server, a CLI and an Agent Skill, all generated from the same seven tools.

Website: codex.ghostpaw.dev

The release binary includes its runtime. npm and library use require Node.js 24+.

Install

Release binary (default)

Each line downloads the latest release asset, checks it against the release's SHA256SUMS and installs ghostpaw-codex into ~/.local/bin. On Linux and macOS the trailing export puts that folder on PATH for the current shell only: neither the line nor install.sh edits ~/.profile or any other shell startup file. The Windows script adds its folder to the user PATH (open a new terminal afterwards).

linux-x64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/codex/main/install.sh | sh -s -- --target linux-x64 && export PATH="$HOME/.local/bin:$PATH"

linux-arm64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/codex/main/install.sh | sh -s -- --target linux-arm64 && export PATH="$HOME/.local/bin:$PATH"

darwin-arm64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/codex/main/install.sh | sh -s -- --target darwin-arm64 && export PATH="$HOME/.local/bin:$PATH"

darwin-x64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/codex/main/install.sh | sh -s -- --target darwin-x64 && export PATH="$HOME/.local/bin:$PATH"

windows-x64 (PowerShell):

irm https://raw.githubusercontent.com/GhostPawJS/codex/main/install.ps1 | iex

To keep ~/.local/bin on PATH in new shells, append it to ~/.profile once (this is the only step that edits a startup file):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile

To pin a release instead of taking the latest, pass --version:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/codex/main/install.sh | sh -s -- --target linux-x64 --version 0.6.0 && export PATH="$HOME/.local/bin:$PATH"

$ ghostpaw-codex --version

ghostpaw-codex 0.6.0 (binary, linux-x64) $ ghostpaw-codex --version --short 0.6.0 $ ghostpaw-codex --version --json {"name":"ghostpaw-codex","version":"0.6.0","variant":"binary","target":"linux-x64"}

variant is binary, npm or library; target is null outside the release binary.

A session with the 0.5.2 linux-x64 binary against a small database of five beliefs:

The same session as an animated GIF.

Other release installers:

mise use -g github:GhostPawJS/codex

ubi --project GhostPawJS/codex --exe ghostpaw-codex --in ~/.local/bin eget GhostPawJS/codex

For aqua, define a github_release package in aqua.yaml:

registries:

• name: codex type: local path: codex-registry.yaml

packages:

• name: GhostPawJS/codex@v0.6.0 registry: codex

codex-registry.yaml:

packages:

• type: github_release repo_owner: GhostPawJS repo_name: codex asset: ghostpaw-codex-{{trimV .Version}}-{{.OS}}-{{.Arch}}.tar.gz format: tar.gz replacements: { amd64: x64 } overrides:
• goos: windows asset: ghostpaw-codex-{{trimV .Version}}-windows-{{.Arch}}.zip format: zip files:
• name: ghostpaw-codex

Install scripts verify SHA256SUMS. To verify a downloaded archive's build attestation:

gh attestation verify <archive> -R GhostPawJS/codex

Set GHOSTPAW_VERIFY=attestation for attestation verification in install.sh. Binaries are unsigned; macOS binaries carry an ad-hoc signature. For a browser download on macOS, remove quarantine with xattr -d com.apple.quarantine /path/to/ghostpaw-codex. Linux binaries require glibc 2.28+; use npx on Alpine. See the binary build workflow.

Approximate sizes for 0.5.2 (Node 26.12.1 inside each binary):

The npm package is about 920 KB unpacked and needs Node 24+. Every release is installed and run on ubuntu-24.04, macos-15 and windows-2025 by the install check.

npx / npm (for npm-based environments)

The npm package requires Node 24+:

npm install -g @ghostpaw/codex

npx -y @ghostpaw/codex --help

Library (for harnesses embedding it in code)

Requires Node 24+:

npm install @ghostpaw/codex

import { initCodexTables, read, write } from '@ghostpaw/codex';

See Library usage.

30-second quickstart

MCP server

Every client below starts the same stdio server: ghostpaw-codex mcp. Use the full executable path if its folder is not on PATH. For npm-based environments, use npx -y @ghostpaw/codex mcp. Beliefs live in ~/.ghostpaw/codex.db unless the GHOSTPAW_CODEX_DB environment variable (absolute path) or --db says otherwise.

Claude Code

claude mcp add ghostpaw-codex -- ghostpaw-codex mcp

or as a plugin, which also installs the skill:

/plugin marketplace add GhostPawJS/codex

/plugin install ghostpaw-codex@ghostpaw-codex

Codex CLI (~/.codex/config.toml)

[mcp_servers.ghostpaw-codex]

command = "ghostpaw-codex" args = ["mcp"]

Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json) or a project .mcp.json:

{

"mcpServers": { "ghostpaw-codex": { "command": "ghostpaw-codex", "args": ["mcp"] } } }

Cline (MCP Servers → Configure MCP Servers, cline_mcp_settings.json). VS Code often starts without ~/.local/bin on PATH, so use the absolute path that echo "$HOME/.local/bin/ghostpaw-codex" prints (PowerShell: "$env:LOCALAPPDATA\Programs\ghostpaw\bin\ghostpaw-codex.exe"). Merge the entry into the existing mcpServers. Settings file locations, the cline mcp add form and checks: llms-install.md. For Cline CLI 3.x, cline config mcp lists the configured servers.

{

"mcpServers": { "ghostpaw-codex": { "command": "/absolute/path/to/ghostpaw-codex", "args": ["mcp"], "env": { "GHOSTPAW_CODEX_DB": "/absolute/path/to/.ghostpaw/codex.db" } } } }

Claude Desktop users can also install server.mcpb from the latest GitHub release. A Dockerfile is included for container hosts: docker build -t ghostpaw-codex . && docker run -i --rm -v codex:/data ghostpaw-codex.

The server speaks MCP 2026-07-28 (stateless, server/discover) and the initialize-based revisions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.

CLI

ghostpaw-codex search <query> [--limit N --min-score N --category C --source S]

ghostpaw-codex review [--limit N --now N] ghostpaw-codex belief add --source S --category C [--certainty N --provenance P] ghostpaw-codex belief show ghostpaw-codex belief retire ghostpaw-codex belief confirm|correct|forget|defer [flags] ghostpaw-codex belief merge [flags] ghostpaw-codex proximity dismiss ghostpaw-codex mcp|skill|tools|describe|call|completions|version|help

Belief additions include a nearest-belief hint when an active belief has similarity of at least 0.7; use it to confirm or merge related claims.

WARNING: belief retire hard-deletes the whole lineage (the belief and all its predecessors/successors) and cannot be undone. Use belief forget for soft removal that keeps lineage. Every retire invocation warns on stderr.

--json is accepted on every read command, including all review views, belief show, alias list, tools, describe, version, help and skill guides. Set GHOSTPAW_OUTPUT=json to opt all commands into JSON output as if --json were passed. Other values or an unset variable preserve default output, including when stdout is piped or a TTY.

Global flags can appear anywhere: --db , --json, --quiet, --compact, --help/-h, --version/-V/-v, --no-color. NO_COLOR is accepted; output uses no terminal colors. Noun-verb commands print short text by default, including when stdout is piped. Search and review lists show one belief per line: id claim [certainty source strength]. Flags append reason codes; the log shows id type claim. Add, show, correct and merge show aligned detail fields and nearby beliefs. Status and trends show aligned key: value lines. --json prints the full tool result and --compact removes JSON indentation. Legacy tool invocation keeps its JSON output. --quiet prints only result ids for search, review flags and log, and the affected belief id for writes; status, trends and version print nothing.

Use help belief, belief --help or belief correct --help for schema-derived help. Each revision verb accepts only the flags it uses. Correction takes --claim; forgetting also accepts --successor-id. Deferral accepts --deferred-until as YYYY-MM-DD, DD.MM.YYYY, today, tomorrow, +3d, an ISO date-time with timezone, or epoch milliseconds. Calendar dates resolve to local end of day and must be in the future. Array flags repeat, kebab-case flags map to schema properties, and values are literal, including leading @. Use JSON stdin (-) for long input. -- ends flags. A positional -, or piped stdin with no arguments, reads a JSON ob