GhostPaw Codex

@ghostpaw/codex

出典、確信度、改訂履歴を備えた信念としてのエージェントメモリ。

npm install @ghostpaw/codex

AI エージェント向けの、根拠に基づいたローカルメモリです。SQLite ファイル 1 つで動作し、ランタイム依存関係はありません。

Codex は、エージェントが信じていることを、出典、確信度、証拠数、減衰、改訂履歴を備えた主張として保存します。エージェントは記憶する前に検索し、追記するのではなく確認または訂正して、古くなった信念、薄れつつある信念、根拠が弱い信念を把握できます。TypeScript ライブラリ、MCP サーバー、CLI、エージェントスキルとして動作し、すべて同じ 7 つのツールから生成されます。

ウェブサイト：codex.ghostpaw.dev

Node.js 24 以降が必要です（組み込みの node:sqlite を使用します）。

30 秒で始める

MCP サーバー

以下のすべてのクライアントは、同じ stdio サーバー npx -y @ghostpaw/codex mcp を起動します。GHOSTPAW_CODEX_DB 環境変数（絶対パス）または --db <path> で指定しない限り、信念は ~/.ghostpaw/codex.db に保存されます。

Claude Code

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

または、スキルもインストールするプラグインとして：

/plugin marketplace add GhostPawJS/codex
/plugin install ghostpaw-codex@ghostpaw-codex

Codex CLI（~/.codex/config.toml）

[mcp_servers.ghostpaw-codex]
command = "npx"
args = ["-y", "@ghostpaw/codex", "mcp"]

Cursor（.cursor/mcp.json）、Claude Desktop（claude_desktop_config.json）、またはプロジェクトの .mcp.json：

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

Claude Desktop のユーザーは、最新の GitHub リリースから server.mcpb をインストールすることもできます。コンテナ環境向けに Dockerfile も含まれています： docker build -t ghostpaw-codex . && docker run -i --rm -v codex:/data ghostpaw-codex。

サーバーは MCP 2026-07-28（ステートレス、server/discover）と、initialize ベースの各リビジョン 2025-11-25、2025-06-18、2025-03-26、2024-11-05 に対応しています。

CLI

npx -y @ghostpaw/codex remember_belief --claim "Deploys go out on Tuesdays" --source explicit --category procedure
npx -y @ghostpaw/codex search_codex --query "when do we deploy"
npx -y @ghostpaw/codex tools              # list tools
npx -y @ghostpaw/codex describe revise_belief

ghostpaw-codex バイナリを使用するには、グローバルにインストールします：npm i -g @ghostpaw/codex。 ghostpaw-codex mcp で stdio サーバーを起動します。

エージェントスキル

SKILL.md（リポジトリのルート）と skills/codex/SKILL.md はAgent Skills形式に準拠しており、npm パッケージに含まれています。skills/codex/ をエージェントのスキルフォルダーにコピーするか、内容を出力します：

npx -y @ghostpaw/codex skill > SKILL.md

ライブラリ

npm install @ghostpaw/codex

import { DatabaseSync } from 'node:sqlite';
import { initCodexTables, read, write } from '@ghostpaw/codex';

const db = new DatabaseSync('codex.db');
initCodexTables(db);

const { id } = write.remember(db, {
  claim: 'The API uses GraphQL with a REST fallback.',
  source: 'explicit',
  category: 'fact',
});
write.confirmBelief(db, id);
write.correctBelief(db, id, {
  claim: 'The API uses GraphQL exclusively; REST was retired.',
  source: 'observed',
  category: 'fact',
});

read.recall(db, 'graphql api'); // ranked, lineage-aware
read.listFlags(db);             // stale, fading, low-trust, single-evidence

同じツールを任意の LLM SDK に組み込めます。各ツールには JSON Schema が付属しています：

import { tools } from '@ghostpaw/codex';

for (const tool of tools.codexTools) {
  // tool.name, tool.description, tool.inputSchema, tool.handler(db, input)
}

または、MCP サーバーを独自のプロセスに組み込みます：

import { createCodexMcpServer } from '@ghostpaw/codex/mcp';
const server = createCodexMcpServer({ dbPath: './codex.db' });

なぜ MEMORY.md ではないのか？

Markdown のメモリファイルは、うまくいかなくなるまでは機能します。

• 増える一方です。 エージェントは追記しても、削除することはほとんどありません。その結果、ファイル全体が毎回のプロンプトに含まれます。Codex はクエリに合致する少数の信念を返します（FTS5 とローカル埋め込みをランクで統合）。
• 矛盾が積み重なります。 「REST を使っています」と「REST は廃止されました」が並んで残ります。Codex は書き込みのたびに類似項目を検出し、修正内容で古い信念を置き換えながら、系譜を保持します。
• すべてが同じように正しく見えます。 推測と確認済みの事実は、文章では同じように読めます。Codex は情報源（明示、観察、抽出、推論）、確実性、証拠の数を追跡し、古くなった情報や裏付けの弱い情報にフラグを付けます。
• 時間の要素がありません。 Codex は情報の鮮度を減衰させるため、古い信念がいつの間にか振る舞いを左右するのではなく、確認のために表示されます。
• 同時編集の問題があります。 2 つのエージェントが 1 つのファイルに書き込むと、互いの変更を上書きしてしまいます。Codex は WAL モードの SQLite データベースです。

ローカルに保存されるため、コピー、バックアップ、任意の SQLite ツールでの確認ができる単一のファイルで利用できます。サーバーも、API キーも、ネットワークも必要ありません。

ツール

ツール	機能
search_codex	アクティブな信念を対象とする、語彙的検索と意味検索を組み合わせた想起
review_codex	ダッシュボード：フラグ、ステータス、傾向、ログ
inspect_codex_item	1 つの信念の詳細：指標、系譜、近接する信念
remember_belief	情報源、カテゴリ、来歴とともに主張を記録
revise_belief	確認、修正、忘却、保留、または統合
retire_belief	プライバシー保護または整理のための完全削除
dismiss_proximity	近接する 2 つの信念が意図的に区別されていることを記録

結果は、エンティティ、次のステップのヒント、復旧方法のアドバイスを含む構造化形式（outcome: success | no_op | needs_clarification | error）です。MCP サーバー、CLI、SKILL.md、プラグインマニフェストはこのレジストリから生成され（npm run surfaces）、CI で差分がないか確認されます。

パフォーマンス

ファイルベースのデータベースに 10,000 件の信念を格納し、Node 24.14.0、Linux、Intel Xeon（共有クラウド vCPU）で npm run bench を実行して計測しました。

操作	p50	p95
search_codex（ツール）	3.6 ms	5.0 ms
MCP tools/call の検索、stdio フレーミングを含む	3.8 ms	4.2 ms
read.recall	3.7 ms	4.8 ms
inspect_codex_item	3.5 ms	3.8 ms
write.remember（近接スキャンを含む）	4.5 ms	5.6 ms
review_codex	11.7 ms	13.2 ms

コールドスタート（プロセス起動から最初の応答までの中央値）：--version は 26 ms、MCP server/discover は 24 ms、10,000 件の信念を格納したファイルに対する初回の検索は 53 ms です。ディスク上で 10,000 件の信念を登録するには 2.2 秒かかります。

gzip サイズとコールドスタートの中央値は budgets.json で予算が設定され、npm run check によって適用されます。

モデル

概念	目的
信念	確実性、証拠、来歴、減衰、改訂の系譜を伴う主張
却下記録	意味的に近い 2 つの信念が意図的に区別されていることを記録
フラグ	派生する注意喚起シグナル：古さ、減衰、信頼度の低さ、証拠が 1 件のみ、または不足
近接性	書き込み時に検出される、信念間の意味的な近さ
系譜	修正と置換による改訂の連鎖、およびバージョン差分

状態は切り替えるのではなく、導出されます。鮮度、強度、確認の優先度、フラグは読み取り時に計算されます。

パッケージの構成

インポート	内容
@ghostpaw/codex	initCodexTables、read、write、tools、skills、soul、すべての型
@ghostpaw/codex/mcp	createCodexMcpServer、serveCodexMcp、汎用 MCP サーバーヘルパー
ghostpaw-codex (bin)	CLI：ツール、説明、呼び出し、ツールごとのフラグ、mcp、skill
dist/mcp-server.js	スタンドアロンの stdio MCP サーバーエントリポイント（MCP Bundle と Dockerfile で使用）
SKILL.md、skills/codex/	17 件のワークフローリファレンスを含むエージェントスキル

ESM と CommonJS に対応し、どちらにも型宣言が用意されています。

ドキュメント

ドキュメント	対象読者
HUMAN.md	read / write API を使用する開発者
LLM.md	soul、tools、skills を連携させるエージェントの構築者
docs/README.md	アーキテクチャ：モデル、不変条件、スコアリング、ソースの構成
docs/entities/	各エンティティの公開 API を正確に一覧したマニュアル
CHANGELOG.md	リリース履歴

開発

npm install
npm run check   # types, lint, zero-deps, tests, build, surfaces, size, API, consumer, startup, ratchet
npm run bench   # hot-path benchmarks at 10,000 beliefs
npm run surfaces  # regenerate SKILL.md, plugin manifests, server.json, mcpb manifest

npm run check は、ローカルと CI の両方で唯一のゲートです。サイズ予算 （budgets.json）と公開 API スナップショット（api-surface.json）を増やすには、 コミットメッセージに明示的な承認タグが必要です。このリポジトリでは .nvmrc により Node 24.14.0 に固定されています。

サポート

このパッケージがプロジェクトに役立つ場合は、メンテナンスへのスポンサーをご検討ください。

---

Anonyfox • MIT License