Aletheia

• 对单个声明的主张使用 symbol，对文件中的单个事物使用 contains。只有在任何更改都应触发重新检查时，才使用 file。
• Recall 会显示 symbol 和 contains 证据当前所在的位置，例如 (store.go:15-21)。Go 声明的完整范围由 go/parser 获取。在其他语言中，symbol 锚点会根据关键字（如 function、class、def、fn 等）找到声明所在行；它并非密封锚点，因此无法跟随代码移动。
• 移动代码。 Go 的 symbol 锚点会使用声明的指纹进行密封（symbol:store.go::Store.Get@3f9a…）。指纹会忽略注释和排版。
  • 原地编辑： 永远不会使锚点失效。只要声明仍在原文件中，就根本不会检查指纹。
  • 声明被移动： 如果声明离开原文件，Aletheia 会在项目中搜索它。如果恰好有一个同名声明的指纹与之相同，记忆会以 [moved: old.go → new.go] 的形式返回，并附上新行号；verify <id> --reseal 会记录新路径。
  • 无法确定的情况仍会过期并隐藏： 代码在移动过程中发生变化、存在多个匹配副本，或主张点名了旧文件。
  • Go 代码中的 contains 锚点： 如果某个锚点在单个声明中匹配，remember 会为该声明添加一个密封的 symbol 锚点。随后 contains 锚点会随声明移动，但只有当其模式在新位置仍与该声明内的内容匹配时才会如此。
• 在 contains 模式中，一串空格可以匹配任意数量的空格或制表符，因此重新排版不会使其失效。
• 主张中提到的文件会自动获得一个 exists: 锚点。
• 让锚点指向路径：描述代码的作用（“Tokens are issued by IssueToken”），而不是代码的位置。点名符号所在文件的主张会在代码移动时失效，保存时 remember 会说明这一点。
• 如果 contains 锚点只匹配到注释，remember 会发出警告，因为注释可能保持不变，而代码已经发生变化。
• 没有锚点的记忆会以 [?] 形式返回，排序低于已验证的事实，并会在 90 天后过期，除非再次确认。

记忆过期时，重新检查主张，然后：

aletheia verify 3f9a1c --reseal                                   # still true: refresh the evidence
aletheia remember "…new claim…" --anchor … --supersedes 3f9a1c   # changed: replace it

如果 contains、exists 或 symbol 锚点不再成立，--reseal 会拒绝操作，因此错误主张无法在无提示的情况下被认可。

aletheia map "<topic>" 会列出与某个主题最相关的文件，并附上各文件中的关键声明及其当前行号：

optimizer/fold.go: fold.Visit 15-311, fold 10-13, toFloat 329-335
builtin/builtin.go: Builtins 35-1081, Index 18

文件首先按照其路径和声明名称与主题的匹配程度排序，排序方式与 Aider 的仓库地图相同。隐藏文件、依赖文件和生成文件会被跳过。对于有关构建、测试或发布的问题，以及不指定主题的概览，地图会从构建文件开始：build and CI: go.mod, Makefile, scripts/, .github/workflows/ci.yml。钩子会在会话的第一个提示词中发送地图，大小根据项目而定：源文件少于 25 个时不发送，之后发送 300 或 600 个令牌（可通过 --map-budget N 覆盖）。

Aletheia 通过标准输入输出使用 MCP，提供四种工具（recall、remember、get、verify），也可作为普通 CLI 使用，因此任何能够运行 shell 命令的 Agent 都可以使用它。

{
  "mcpServers": {
    "aletheia": { "command": "aletheia", "args": ["serve", "--dir", "/absolute/path/to/your-project"] }
  }
}

如果没有全局安装，请使用 "command": "npx", "args": ["-y", "@firatmio/aletheia", "serve", "--dir", "…"]。服务会从 --dir 指定的位置，或从客户端启动它的目录查找 .aletheia/。如果项目中没有该目录，这些工具会说明如何设置，而不会报错；运行 aletheia init 后即可开始工作。

---
id: "3f9a1c"
claim: "Auth tokens are issued by IssueToken, HS256 with a 15 minute expiry"
confidence: 0.8
status: "active"
source: "claude-code"
created: "2026-10-21T09:12:44Z"
updated: "2026-10-21T09:12:44Z"
tags:
  - "auth"
anchors:
  - "symbol:src/auth/jwt.go::IssueToken@7370a7fe3669256c"
  - "contains:src/auth/jwt.go::jwt\\.SigningMethodHS256"
---
Refresh tokens are handled separately, by RefreshToken.

@7370a7fe3669256c 后缀是经过封存的指纹；如果 IssueToken 移动，它能让这条记忆跟随其移动。

可以手动编辑记忆，在拉取请求中审查，也可以用 grep 搜索。它们只是文件。

aletheia init [dir] [--agents] [--claude-hooks]
aletheia remember <claim> [--anchor SPEC]... [--body TEXT|-] [--tag T]... [--ttl 30d]
                  [--confidence 0.8] [--supersedes ID]... [--source NAME] [--force]
aletheia remember - [--source NAME] [--force]            # several at once: one JSON object per line on stdin
aletheia recall [query] [--budget N] [--limit N] [--full] [--stale] [--tag T] [--session ID] [--json]
aletheia get <id> [--json]
aletheia verify [id] [--reseal] [--ttl 30d] [--json]   # exits 1 if anything is stale (CI-friendly)
aletheia map [topic] [--budget 600]
aletheia hook [--budget N] [--map-budget N] [--dry-run [prompt]]   # Claude Code hook; every command takes --help
aletheia lethe [--days 30] [--apply] [--json]            # archive superseded and long-stale memories
aletheia stats [--json]
aletheia serve [--dir DIR]                               # MCP server on stdio
aletheia version

每个命令都支持 --help，也支持 --dir DIR（或 ALETHEIA_DIR），以便从其他位置指定项目。

如果声明与现有记忆重复或高度相似，remember 会以退出码 3 退出，并指出对应记忆，让 Agent 可以用 --supersedes 取代它。

remember - 可在一次调用中保存多条记忆。每行标准输入都是一个 JSON 对象，包含 MCP 工具所需的键；每条记忆会单独保存：

aletheia remember - <<'EOF'
{"claim": "Builtins are registered in builtin/registry.go", "anchors": ["symbol:builtin/registry.go::Builtins"]}
{"claim": "go.mod targets Go 1.18", "anchors": ["contains:go.mod::^go 1\\.18$"], "tags": ["toolchain"]}
EOF

它会按顺序逐行打印结果。全部保存成功时退出码为 0；只有冲突导致失败时退出码为 3；其他情况退出码为 1。正则表达式在经过 shell 时即使其中的 \\ 变成了 \（1\.18），仍会被接受。MCP remember 工具接受与 memories 相同的对象。

• **绝不执行任何内容。**锚点只读取文件；没有“运行此命令以验证”的锚点。
• **操作范围不超出项目。**锚点路径均为相对路径，无法逃出根目录，包括通过符号链接逃出。
• **记忆是数据，不是指令。**MCP 服务会告知 Agent 这一点，CLAUDE.md / AGENTS.md 中的说明也会再次强调。
• **无网络、无遥测、无依赖。**这是一个仅使用 Go 标准库的静态二进制文件。它启动的唯一程序是在 init 期间运行的 git check-ignore，用于检查 CLAUDE.md 是否被忽略。
• **隐私：**Aletheia 不收集任何信息。钩子会在你的机器上读取提示词和会话记录，代码地图记忆会在 .aletheia/ 中保留提示词的缩短副本。详见隐私政策。