io.github.GhostPawJS由 GitHub 账号 GhostPawJS 发布v0.6.4更新于 Nov 5, 2026
Local belief and memory engine with evidence, certainty, and honest revision history.
本地信念与记忆引擎，让助手保存带来源、确定度和修订历史的论断，并可搜索、审阅和修订这些记忆。
Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。
参照 仓库 中的启动说明。
[GhostPaw codex: When one agent saves a wrong fact, every agent trusts it.]
[npm] [CI] [site] [runtime deps] [MCP Registry] [node] [license] [@ghostpaw/codex on AI Agents Listing]
Agent memory as beliefs with a source, a certainty and a revision history.
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+.
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:
linux-arm64:
darwin-arm64:
darwin-x64:
windows-x64 (PowerShell):
To keep ~/.local/bin on PATH in new shells, append it to ~/.profile once (this is the only step that edits a startup file):
To pin a release instead of taking the latest, pass --version:
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:
For aqua, define a
github_release package in aqua.yaml:
codex-registry.yaml:
Install scripts verify SHA256SUMS. To verify a downloaded archive's build attestation:
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.
The npm package requires Node 24+:
Requires Node 24+:
See Library usage.
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 <path> says otherwise.
Claude Code
or as a plugin, which also installs the skill:
Codex CLI (~/.codex/config.toml)
Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json)
or a project .mcp.json:
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.
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.
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 <path>, --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 object; explicit flags override its fields.
Database selection uses --db, GHOSTPAW_CODEX_DB, then ~/.ghostpaw/codex.db.
Opening the default database prints using default db <path> once on stderr.
Suppress the notice with --quiet or GHOSTPAW_QUIET=1. Commands that do not open a database print no notice.
Top-level help shows the resolved path. Version output starts with
ghostpaw-codex and identifies binary target, npm or library execution.
ghostpaw-codex skill prints the full skill reference. Use
ghostpaw-codex skill --list to list workflow guides and
ghostpaw-codex skill capture-beliefs-well to read a guide. skill --help
shows these forms; unknown guide names include a suggestion.
Errors and recovery hints go to stderr. Clarification prints the question and missing flags to stderr. With --json, usage and internal errors also print
{ok:false,error:{code,message}} to stdout. Tool results retain their full
shape. Legacy tools [--json], describe <tool>, call <tool> [JSON|-]
and <tool_name> --parameter value keep their existing exit codes.
completions bash, completions zsh and completions fish print shell scripts.
File input is opt-in for each CLI argument. When an argument's help lists
(@file, @- stdin, @@ literal @), @path reads a UTF-8 file, @- reads
stdin, and @@text passes the literal value @text.
No current Codex argument enables this option: flags and positional values
keep leading @ and @@ as written. For long claims, pass a JSON object
through stdin with - (see the example above).
SKILL.md (repo root) and skills/codex/SKILL.md follow the
Agent Skills format and ship in the npm package.
Copy skills/codex/ into your agent's skills folder, or print it:
Wire the same tools into any LLM SDK. Each tool carries a JSON Schema:
Or embed the MCP server in your own process:
The live demo runs the library in your browser against an in-memory SQLite database. Each view below opens a different part of it:
A markdown memory file works until it doesn't:
It stays local: one file you can copy, back up or inspect with any SQLite tool. No server, no API key, no network.
Results are structured (outcome: success | no_op | needs_clarification | error) with entities, next-step hints and recovery advice. The MCP server,
CLI, SKILL.md and plugin manifests are generated from this registry
(npm run surfaces) and drift-checked in CI.
Measured with npm run bench on Node 24.14.0, Linux, Intel Xeon (shared
cloud vCPU), 10,000 beliefs in a file-backed database:
Cold start (process spawn to first response, median): --version 26 ms,
MCP server/discover 24 ms, first search against the 10,000-belief file
53 ms. Seeding 10,000 beliefs takes 2.2 s on disk.
Gzip sizes and cold-start medians are budgeted in budgets.json and enforced
by npm run check.
State is derived, never toggled: freshness, strength, review priority and flags are computed at read time.
ESM and CommonJS, with type declarations for both.
npm run check is the single gate, locally and in CI. Size budgets
(budgets.json) and the public API snapshot (api-surface.json) can only
grow with an explicit approval tag in the commit message. The repo is pinned
to Node 24.14.0 via .nvmrc.
If this package helps your project, consider sponsoring its maintenance:
Search is lexical: FTS5 bm25 plus hashed character-trigram similarity, with
IDF-like token weighting and a 55% relative cutoff. It does not provide semantic
understanding. In corpora of at least 20 active beliefs, queries matching only common terms return at most three results
with a partial_match warning.
Aliases are off by default (the table starts empty). Add directed, one-hop aliases when query vocabulary differs from stored claims:
The library equivalents are write.addQueryAlias(db, term, alias, options?),
write.removeQueryAlias(db, term, alias) (returns whether removed), and
read.listQueryAliases(db) (sorted { term, alias, createdAt } records).
Both words are normalized with normalizeClaim and must be distinct single words.
Adding an existing pair preserves its creation time; options.now sets the time
on first insertion. Expansion is deduplicated and never follows alias chains;
the query vector uses the original query.
Belief records include provenanceSources, an append-only list of distinct origin
references. Every write with --provenance adds a reference, including duplicate
adds and unchanged corrections. Corrections and merges carry all sources forward.
The legacy provenance field remains readable with its existing single-value
behavior; use provenanceSources for the complete history.
Superseded-belief errors and belief show identify the current active successor.
Library details also expose activeSuccessorId, while supersededBy retains the
immediate lineage link. Correcting to the same normalized claim and metadata
returns no_op. A merge into --successor-id can omit --claim.
belief --help lists belief verbs. review flags --now +8d and
review flags --now 2026-11-10 accept the same date formats as deferral, including
historical dates and epoch milliseconds. Relative day offsets also accept -3d
and 30d. Calendar dates and relative days use local end of day.
New CLI and MCP database files use mode 0600; newly created parent directories
use 0700. Existing permissions are preserved. On first upgrade, legacy active
normalized duplicates consolidate into the oldest id, preserving summed evidence,
source references and lineage. Later --allow-duplicate additions remain separate.
Merge fan-in alone does not trigger unstable; repeated corrections still do.
Search treats punctuation literally; wrap the whole query in double quotes for a phrase.
Use search --fts 'alpha OR beta' for raw FTS5 syntax, or
search note --prefix "project:" to filter claims by a case-insensitive prefix
after leading whitespace. A query is required with --prefix. Library recall
options and search tool inputs also accept fts and prefix.
Default search ranks claims whose entity before the first colon matches the leading
query tokens first, ignoring case and treating spaces and hyphens alike (for example,
Agentpreneur: ... for Agentpreneur state files routine memory db). This also
applies with --prefix; --fts and quoted phrase ranking remain unchanged.
Review status integrity remains the percentage of active beliefs with certainty at least 0.7. The new, unconfirmed count covers beliefs with one evidence item younger than seven days; it overlaps the existing strength counts.
Review: review status --by-prefix counts active claim prefixes; review duplicates --limit 20 lists nearby active pairs immediately, honoring dismissals.
来源：README.md，提交 54fc4fe
Search active beliefs by natural language query. Returns ranked matches with recall scores and transparency metadata. Use when: Use this to find beliefs about a topic before acting on them. Always search before creating a new belief to avoid duplicates. Not for: Do not use this for browsing all beliefs — use review_codex with the status or flags view instead.
ftslimitquery必填prefixsourcecategoryminScoreLoad a codex review surface: flags for beliefs needing attention, status for portfolio health, log for recent activity, trends for time-based patterns, or duplicates for nearby active pairs. Use when: Use this when you need an overview of the codex state rather than a specific belief. Start with flags for maintenance, status for a dashboard, or log for recent changes. Not for: Do not use this to find a specific belief by topic — use search_codex instead. Do not use this to inspect one belief deeply — use inspect_codex_item.
nowview必填limitbyPrefixInspect one belief in full detail: certainty, freshness, strength, source, category, lineage chain, proximity to similar beliefs, and version diff when applicable. Use when: Use this after finding a belief through search_codex or review_codex to understand it deeply before deciding whether to confirm, correct, or forget it. Not for: Do not use this for bulk browsing — use review_codex for lists. Do not call this without a specific belief id.
beliefId必填Capture a belief from a claim, source, and category. Reuses active normalized duplicates unless allowDuplicate is set, and detects nearby beliefs. Use when: Use this when a new proposition should enter the codex. Always search first to check whether the belief already exists — prefer confirming or correcting an existing belief over creating a duplicate. Not for: Do not use this to update an existing belief. Use revise_belief with the correct, confirm, or merge action instead.
claim必填source必填category必填certaintyprovenanceallowDuplicateRevise an existing belief: confirm it still holds, correct it with a new claim, merge multiple beliefs into one, forget it from active recall, or defer its next flag review. Use when: Use this after inspecting a belief to act on it. Choose the action that matches the situation: confirm for reinforcement, correct for changed understanding, merge for consolidation, forget for removal from active recall, defer for postponing review. Not for: Do not use this to create a new belief — use remember_belief. Do not use this to permanently delete a belief — use retire_belief.
claimaction必填sourcebeliefIdcategorybeliefIdscertaintyprovenancesuccessorIddeferredUntilWARNING: 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. Use when: Use this only for privacy cleanup or hard erasure. The belief and all of its lineage (predecessors and successors) will be destroyed. Not for: Do not use this for normal belief lifecycle — use revise_belief with the forget action to preserve the audit trail.
beliefId必填Record that two beliefs are not meaningfully related despite proximity detection. Uses exponential backoff — the pair will resurface less frequently with each dismissal. Use when: Use this after inspecting two proximate beliefs and determining they are not duplicates or in conflict. The dismissal suppresses the pair in future proximity results. Not for: Do not use this if the beliefs are genuinely related — instead use revise_belief to merge, correct, or forget one of them.
beliefA必填beliefB必填已满足适用检查项的 90%
该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。
请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。
ghostpaw-codex --helpcurl -fsSL https://raw.githubusercontent.com/GhostPawJS/codex/main/install.sh | sh -s -- --target linux-x64 && export PATH="$HOME/.local/bin:$PATH"curl -fsSL https://raw.githubusercontent.com/GhostPawJS/codex/main/install.sh | sh -s -- --target linux-arm64 && export PATH="$HOME/.local/bin:$PATH"curl -fsSL https://raw.githubusercontent.com/GhostPawJS/codex/main/install.sh | sh -s -- --target darwin-arm64 && export PATH="$HOME/.local/bin:$PATH"curl -fsSL https://raw.githubusercontent.com/GhostPawJS/codex/main/install.sh | sh -s -- --target darwin-x64 && export PATH="$HOME/.local/bin:$PATH"irm https://raw.githubusercontent.com/GhostPawJS/codex/main/install.ps1 | iexecho 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profilecurl -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 --versionghostpaw-codex 0.6.0 (binary, linux-x64)$ ghostpaw-codex --version --short0.6.0$ ghostpaw-codex --version --json{"name":"ghostpaw-codex","version":"0.6.0","variant":"binary","target":"linux-x64"}mise use -g github:GhostPawJS/codexubi --project GhostPawJS/codex --exe ghostpaw-codex --in ~/.local/bineget GhostPawJS/codexregistries: - name: codex type: local path: codex-registry.yamlpackages: - name: GhostPawJS/[email protected] registry: codexpackages: - 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-codexgh attestation verify <archive> -R GhostPawJS/codexnpm install -g @ghostpaw/codexnpx -y @ghostpaw/codex --helpnpm install @ghostpaw/codeximport { initCodexTables, read, write } from '@ghostpaw/codex';claude mcp add ghostpaw-codex -- ghostpaw-codex mcp/plugin marketplace add GhostPawJS/codex/plugin install ghostpaw-codex@ghostpaw-codex[mcp_servers.ghostpaw-codex]command = "ghostpaw-codex"args = ["mcp"]{ "mcpServers": { "ghostpaw-codex": { "command": "ghostpaw-codex", "args": ["mcp"] } }}{ "mcpServers": { "ghostpaw-codex": { "command": "/absolute/path/to/ghostpaw-codex", "args": ["mcp"], "env": { "GHOSTPAW_CODEX_DB": "/absolute/path/to/.ghostpaw/codex.db" } } }}ghostpaw-codex search <query> [--limit N --min-score N --category C --source S]ghostpaw-codex review <flags|status|log|trends> [--limit N --now N]ghostpaw-codex belief add <claim> --source S --category C [--certainty N --provenance P]ghostpaw-codex belief show <beliefId>ghostpaw-codex belief retire <beliefId>ghostpaw-codex belief confirm|correct|forget|defer <beliefId> [flags]ghostpaw-codex belief merge <beliefIds...> [flags]ghostpaw-codex proximity dismiss <beliefA> <beliefB>ghostpaw-codex mcp|skill|tools|describe|call|completions|version|helpghostpaw-codex belief add "Deploys go out on Tuesdays" --source explicit --category procedureghostpaw-codex search "when do we deploy" --json | jq '.data.results'printf '%s' '{"beliefId":1}' | ghostpaw-codex belief show - --jsonghostpaw-codex skill > SKILL.mdnpm install @ghostpaw/codeximport { 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-awareread.listFlags(db); // stale, fading, low-trust, single-evidenceimport { tools } from '@ghostpaw/codex';
for (const tool of tools.codexTools) { // tool.name, tool.description, tool.inputSchema, tool.handler(db, input)}import { createCodexMcpServer } from '@ghostpaw/codex/mcp';const server = createCodexMcpServer({ dbPath: './codex.db' });npm installnpm run check # types, lint, zero-deps, tests, build, surfaces, size, API, consumer, startup, ratchetnpm run bench # hot-path benchmarks at 10,000 beliefsnpm run surfaces # regenerate SKILL.md, plugin manifests, server.json, mcpb manifestghostpaw-codex alias add class warriorghostpaw-codex alias listghostpaw-codex alias remove class warrior