GhostPaw Codex

@ghostpaw/codex

以信念形式保存 Agent 记忆，包含来源、确信度和修订历史。

npm install @ghostpaw/codex

为 AI Agent 提供本地、有证据支持的记忆。只需一个 SQLite 文件，运行时零依赖。

Codex 将 Agent 的信念保存为声明，记录其来源、确信度、证据数量、衰减情况和真实的修订历史。Agent 会先搜索再记忆，通过确认或纠正而不是追加来更新信息，并能查看哪些信念已经过时、逐渐淡化或证据不足。它以 TypeScript 库、MCP 服务、CLI 和 Agent Skill 的形式运行，全部由同一组七个工具生成。

网站：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

也可以作为插件使用，它还会安装 skill：

/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 服务。

Agent Skill

（仓库根目录中的）SKILL.md 和 skills/codex/SKILL.md 遵循 Agent Skills 格式，并随 npm 包一同发布。 将 skills/codex/ 复制到 Agent 的 skills 文件夹，或将其打印出来：

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

将相同的工具接入任意大模型 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 记忆文件迟早会出问题：

• 只会越变越大。 Agent 会不断追加，很少删除，文件最终会出现在每个提示词中。Codex 会返回与查询匹配的少数几条信念（FTS5 加本地嵌入，按排名融合）。
• 矛盾不断累积。 “我们使用 REST”与“REST 已弃用”并列存在。Codex 会在每次写入时检测近似重复项；修正内容会取代旧信念，同时保留其沿袭关系。
• 所有内容看起来都一样可信。 猜测和已确认的事实在文字中看起来并无二致。Codex 会追踪来源（明确、观察所得、提炼所得、推断所得）、确定性和证据数量，并标记过时或缺乏支持的内容。
• 没有时间维度。 Codex 会降低内容的新鲜度，因此旧信念会被提出来供人审查，而不是悄悄影响行为。
• 并发编辑。 两个 Agent 同时写入一个文件会互相覆盖。Codex 是一个采用 WAL 模式的 SQLite 数据库。

它会保留在本地：这是一个文件，你可以复制、备份，或使用任何 SQLite 工具查看。 无需服务端、API 密钥或网络。

工具

工具	功能
search_codex	在活跃信念中进行词法与语义混合检索
review_codex	仪表板：标记、状态、趋势、日志
inspect_codex_item	查看一条信念的完整信息：指标、沿袭关系、邻近信念
remember_belief	记录一条主张及其来源、类别和溯源信息
revise_belief	确认、更正、遗忘、延后处理或合并
retire_belief	为保护隐私或清理内容而彻底删除
dismiss_proximity	将两条邻近信念标记为有意区分

结果采用结构化格式（outcome: success | no_op | needs_clarification | error），包含实体、后续步骤提示和恢复建议。MCP 服务、CLI、SKILL.md 和插件清单均由此注册表生成（npm run surfaces），并在 CI 中进行漂移检查。

性能

使用 Node 24.14.0、Linux、Intel Xeon（共享云 vCPU），在文件数据库中存储 10,000 条信念时，通过 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 s。

Gzip 大小和冷启动中位数的预算定义在 budgets.json 中，并通过 npm run check 强制执行。

模型

概念	用途
信念	一条带有确定性、证据、溯源信息、衰减和修订沿袭关系的主张
排除记录	记录两条语义相近的信念有意保持区分
标记	派生的关注信号：过时、减弱、低可信度、单一证据或缺口
邻近度	信念之间的语义接近程度，在写入时检测
沿袭关系	更正和取代操作形成的修订链，包含版本差异

状态均为派生结果，从不切换：新鲜度、强度、审查优先级和标记均在读取时计算。

包的导出内容

导入项	内容
@ghostpaw/codex	initCodexTables、read、write、tools、skills、soul、所有类型
@ghostpaw/codex/mcp	createCodexMcpServer、serveCodexMcp、通用 MCP 服务端辅助函数
ghostpaw-codex（bin）	CLI：tools、describe、call、各工具的标志、mcp、skill
dist/mcp-server.js	独立的 stdio MCP 服务端入口（由 MCP Bundle 和 Dockerfile 使用）
SKILL.md、skills/codex/	Agent Skill，包含 17 个工作流参考

支持 ESM 和 CommonJS，并为两者提供类型声明。

文档

文档	读者
HUMAN.md	使用 read / write API 的开发者
LLM.md	将 soul、tools 和 skills 接入的 Agent 构建者
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 许可证