AnchorDB

AnchorDB

面向 AI 编码 Agent 的代码记忆。 AnchorDB 是一个 MCP 服务，可存储附加到特定代码（文件、行范围、符号）的备注，并在代码移动时让备注继续附着在对应位置。Agent 在一个会话中积累的上下文，在下一个会话中仍然可用。

将 Claude Code、Cursor 或任何 Model Context Protocol 宿主连接到它，Agent 就能在编辑前了解某个变通方案为何存在，也能为后来者留下备注。一切都保留在本地：一个 SQLite 文件、你的 git 仓库，不进行网络调用。

curl -fsSL https://raw.githubusercontent.com/jolovicdev/anchor-db/master/install.sh | sh
claude mcp add anchordb -- anchordb-mcp --db ~/.anchordb/anchor.db

无需账号、API 密钥，也无需在后台运行任何程序。唯一的要求是 git；预构建的二进制文件支持 Linux、macOS 和 Windows，也可通过容器镜像或Go 安装使用。

三种接入方式，共享同一份数据：

anchordb-mcp	面向编码 Agent 的 MCP 服务。直接与 SQLite 通信，无需守护进程。
anchorctl	面向 Shell、脚本和 CI 的命令行客户端。
anchord	HTTP API 和网页查看器，可在浏览器中查看代码和备注。

原因

聊天记录不是保存你对代码库了解的好地方。它会被刷走，也没有附着在任何对象上，而且下一个会话开始时一片空白。

在源码中写注释会好一些，但你不能到处都写，而且很多重要信息不适合放在文件里：尚未修复的 Bug 的复现步骤、看似显而易见的重构为何行不通、上次有人改动这个重试循环时出了什么问题，以及你上次做到哪里。

AnchorDB 将这些备注保存在代码旁边，而不是代码内部，并在代码移动时跟随代码。固定到某个函数的备注，在重命名函数、调整文件顺序或将其移到另一个包后，仍然会附着在该函数上。

使用场景

• 应在编辑文件或符号前读取上下文的编码 Agent
• Agent 交接，一个运行实例为下一个实例留下精确的备注
• 长时间调试会话，将复现步骤和发现附加到代码
• 对高风险路径的审查备注——计费、身份验证、迁移、重试逻辑
• 决策原因比做出决策的人存续更久的任何代码库

工作原理

AnchorDB 存储 anchors。

每个 anchor 包含：

• 仓库元数据
• 备注正文和类型
• 文件路径
• 行和列范围
• 选中的文本及其周围上下文
• 可选的符号路径

文件发生更改时，AnchorDB 会根据已保存的范围、文本上下文和符号信息重新解析 anchor。Tree-sitter 可以改进符号提取和位置迁移，但即使没有它，系统仍能正常工作。

解析会按确定性从高到低依次尝试策略，并在找到可靠结果后停止：

1. 精确范围——记录的行仍包含记录的文本。
2. Git 行映射——每个 anchor 都会记录其行号所依据的提交，因此 git diff 能准确指出这些行的去向。当文本匹配只能猜测时，这种方式仍能确定位置；它能区分找到重复代码块的正确副本和找到第一个副本。应用映射前始终会根据存储的文本进行验证，因此即使效果退化，也不会错误地附加 anchor。
3. 符号匹配——符号路径相同，并根据其主体保留程度评分。
4. 文本和上下文匹配——在文件其他位置查找记录的文本，并根据周围上下文排序。

如果这些策略都无法定位某个 anchor，它会被标记为 stale，并保留最后的已知位置。由于可以查看差异，过时的 anchor 能指出其代码是原地重写还是直接删除。解析按路径进行，各路径的失败彼此隔离，因此一个无法解析的文件不会阻止仓库中其余文件同步。

在此功能出现之前写入的 anchor 没有记录基础提交；它们会跳过 Git 步骤，改用文本匹配。

分诊

过时锚点会进入队列，而非无路可走。AnchorDB 会按可能的新位置为每个锚点排序，并提供置信度分数和代码预览，让你选择并接受其中一个：

anchorctl anchor stale --repo-id repo_123
anchorctl anchor candidates --id anchor_123
anchorctl anchor relocate --id anchor_123 --candidate 0

重新定位时，会从文件中重新读取代码片段，在新位置重新推导符号，并将锚点重新基准到当前提交，因此下一次自动处理时可以再次通过 git 跟踪它。若要重新固定到建议中没有的位置，请指定明确的范围：

anchorctl anchor relocate --id anchor_123 --start-line 42 --end-line 58

Agent 也可以通过 MCP 使用同一套流程（anchor_stale、anchor_candidates、anchor_relocate），这样重构代码的运行也能重新固定留下的注释。在 Web 查看器中，每个过时锚点都会显示一个审查面板。

历史记录

每次移动、过时和更新都会记录其原因和置信度，并且这些历史记录随处可读：

anchorctl anchor events --id anchor_123

它能回答“这条注释为什么在这里？”——例如 created，然后是 moved · git line mapping，再然后是 stale · the anchored lines were deleted or restructured。没有任何变化的解析过程不会记录，因此历史记录始终只包含有用信息。

路径始终按相对于仓库的路径解释，并限制在仓库范围内：试图越出根目录、通过符号链接跳出根目录或读取 .git 的请求都会被拒绝。出于同样的原因，也会拒绝会被解析为命令行选项的 Git 引用。

内置符号提取器：

• Go
• Python
• JavaScript
• TypeScript

安装

git 是唯一的运行时依赖。每个版本都提供适用于 Linux、macOS 和 Windows 的预构建二进制文件，因此只有从源代码构建时才需要 Go 工具链。

只需 anchordb-mcp 即可通过编码 Agent 使用 AnchorDB。anchorctl 和 anchord 分别提供命令行客户端和 Web 查看器。

下载二进制文件

Linux 和 macOS：

curl -fsSL https://raw.githubusercontent.com/jolovicdev/anchor-db/master/install.sh | sh

这会为你的平台下载归档文件，根据发布校验和进行验证，并安装到 ~/.local/bin。设置 ANCHORDB_INSTALL_DIR 可将其安装到其他位置；设置 ANCHORDB_VERSION 可固定版本。

若要手动安装，请从发布页面下载适用于你平台的归档文件，解压后将二进制文件移到你的 PATH 中。每个版本中的 checksums.txt 都列出了所有归档文件的校验和。

使用 Go

需要 Go 1.25 或更高版本。

go install github.com/jolovicdev/anchor-db/cmd/anchordb-mcp@latest
go install github.com/jolovicdev/anchor-db/cmd/anchorctl@latest
go install github.com/jolovicdev/anchor-db/cmd/anchord@latest

从本地检出目录安装：

go install ./cmd/anchordb-mcp ./cmd/anchorctl ./cmd/anchord

如果之后找不到已安装的命令，说明 Go bin 目录不在你的 PATH 中：

go env GOBIN          # if empty, binaries are in $(go env GOPATH)/bin
export PATH="$PATH:$(go env GOPATH)/bin"

使用 Docker

docker run --rm -i \
  -v ~/.anchordb:/data \
  -v /path/to/repo:/path/to/repo \
  ghcr.io/jolovicdev/anchor-db:latest

锚点会记录仓库的绝对路径，因此每个仓库都要挂载到它在主机上的相同路径——否则，数据库中存储的路径将与容器可见的路径不匹配。只有在 CI 或沙盒环境中，使用容器才值得折腾；其他情况下，在主机上使用二进制文件更简单。

验证

anchordb-mcp --version

数据库的存放位置

一个数据库可以容纳多个仓库。稳定的用户专属位置通常就很好：

mkdir -p ~/.anchordb

在以下命令中使用 ~/.anchordb/anchor.db。不要将其放进仓库——它是本地状态数据，不是源代码，也不应纳入 git。

使用编码 Agent 安装

如果你更希望由 Agent 来完成这项工作，请让它查看此代码库并说“安装这个”。以下步骤可直接照做。

1. 检查前置条件。 运行 go version（需要 1.25+）和 git --version。如果未安装 Go，请停止并先询问，再安装工具链。

2. 安装 MCP 服务。

go install github.com/jolovicdev/anchor-db/cmd/anchordb-mcp@latest

3. 查找二进制文件。 运行 go env GOBIN；如果为空，则使用 $(go env GOPATH)/bin。在步骤 5 中使用绝对路径，不要编辑 shell 配置文件。

4. 选择数据库路径。 运行 mkdir -p ~/.anchordb，并使用 ~/.anchordb/anchor.db。不要将它放在用户的代码库内。

5. 注册服务。 对于 Claude Code：

claude mcp add anchordb -- /absolute/path/to/anchordb-mcp --db /absolute/path/to/anchor.db

对于使用 mcpServers JSON 的任何宿主，将 Claude Code 设置 中显示的条目合并进去，不要覆盖现有内容。仅使用绝对路径；大多数宿主不会展开 ~。

6. 验证。 anchordb-mcp --version 应输出版本号。重启宿主，并确认工具列表中出现 anchor_context。如果没有出现，说明配置未生效：请检查你编辑的是正在运行的宿主所用配置，并确认宿主已完全重启。

7. 注册代码库，使用 repo_add 工具，或运行：

anchorctl repo add --name <name> --path /path/to/repo

将返回的 repo ID 告知用户；大多数命令都需要它。

妥善使用

先阅读，再编辑。修改文件前，使用 repo ID 和文件路径调用 anchor_context。锚点记录的是代码中没有说明的内容——某个变通方案为何存在、函数遵循什么不变量、上次出了什么问题。跳过这一步，就容易再次引入同一个 Bug。

记录持久且不明显的信息。好的锚点包括：类型未强制执行的约束、某个看似合理的简化方案为何不可行、尚未修复的 Bug 的复现方法，以及中途停止任务时的交接状态。将 author 设置为可识别你身份的值，例如 agent://claude。

跳过代码中已有说明的内容。重复说明函数签名的注释只会制造噪声，而噪声会淹没重要的锚点。

重新固定失效的锚点。重构后，针对代码库调用 anchor_stale。使用 anchor_candidates 查看建议的新位置，再使用 anchor_relocate 接受其中一个；如果你知道更合适的位置，也可以提供明确的行范围。遗留失效锚点会让下一次运行的效果更差。

不要提交数据库；未经询问，不要删除由他人创建的锚点。

快速入门

启动服务：

anchord --db ~/.anchordb/anchor.db

注册代码库：

anchorctl repo add --name demo --path /path/to/repo

创建锚点：

anchorctl anchor create \
  --repo-id repo_123 \
  --ref WORKTREE \
  --path internal/service/run.go \
  --start-line 42 \
  --start-col 1 \
  --end-line 49 \
  --end-col 2 \
  --kind warning \
  --title "Retry must stay idempotent" \
  --body "This path duplicated writes during incident 2026-02-14." \
  --author human://alice

打开查看器：

http://127.0.0.1:7740/

启动 MCP 服务：

anchordb-mcp --db ~/.anchordb/anchor.db

CLI

anchorctl 与正在运行的 HTTP 服务通信。

它从 ANCHOR_DB_URL 读取基础 URL。默认值：

http://127.0.0.1:7740

代码库命令

添加代码库：

anchorctl repo add --name demo --path /path/to/repo

列出代码库：

anchorctl repo list

获取单个代码库：

anchorctl repo get --id repo_123

同步单个代码库：

anchorctl repo sync --id repo_123

移除单个代码库：

anchorctl repo remove --id repo_123

锚点命令

列出锚点：

anchorctl anchor list --repo-id repo_123 --path internal/api/server.go --limit 20 --offset 0

获取单个锚点：

anchorctl anchor get --id anchor_123

创建锚点：

anchorctl anchor create \
  --repo-id repo_123 \
  --ref WORKTREE \
  --path internal/api/server.go \
  --start-line 40 \
  --start-col 1 \
  --end-line 52 \
  --end-col 2 \
  --kind warning \
  --title "Keep request validation strict" \
  --body "This handler should reject empty repo_id values." \
  --author human://alice

更新锚点元数据：

anchorctl anchor update \
  --id anchor_123 \
  --kind handoff \
  --title "Next step" \
  --body "Trace the retry path before changing the timeout logic." \
  --author agent://planner \
  --tags billing,handoff

归档锚点：

anchorctl anchor close --id anchor_123

重新打开锚点：

anchorctl anchor reopen --id anchor_123

重新运行锚点解析：

anchorctl anchor resolve --id anchor_123

上下文、评论和搜索

获取文件或符号上下文：

anchorctl context --repo-id repo_123 --ref WORKTREE --path internal/api/server.go --symbol "*Server.handleRepos"

列出评论：

anchorctl comment list --anchor-id anchor_123

添加评论：

anchorctl comment add --anchor-id anchor_123 --author human://alice --body "Confirmed in production replay."

全文搜索：

anchorctl search --query retry --repo-id repo_123 --path internal/api/server.go

查询会被视为字面文本，因此 C++、don't 或 retry (v2) 这类标点较多的词也可以安全搜索。多个词会按 AND 关系组合；末尾加上 * 可执行前缀搜索：

anchorctl search --query "retry idempot*" --repo-id repo_123

所有 CLI 命令均返回 JSON。

HTTP API

默认监听地址：

http://127.0.0.1:7740

端点

• GET /health
• GET /v1/repos
• POST /v1/repos
• GET /v1/repos/{repo_id}
• POST /v1/repos/{repo_id}/sync
• DELETE /v1/repos/{repo_id}
• GET /v1/anchors
• POST /v1/anchors
• GET /v1/anchors/{anchor_id}
• PATCH /v1/anchors/{anchor_id}
• POST /v1/anchors/{anchor_id}/close
• POST /v1/anchors/{anchor_id}/reopen
• POST /v1/anchors/{anchor_id}/resolve
• GET /v1/anchors/{anchor_id}/comments
• POST /v1/anchors/{anchor_id}/comments
• GET /v1/anchors/{anchor_id}/events
• GET /v1/anchors/{anchor_id}/candidates
• POST /v1/anchors/{anchor_id}/relocate
• GET /v1/stale
• GET /v1/context
• GET /v1/search
• GET /view

常见请求

创建仓库：

POST /v1/repos
Content-Type: application/json

{
  "name": "demo",
  "path": "/path/to/repo"
}

响应：

{
  "id": "repo_123",
  "name": "demo",
  "root_path": "/path/to/repo",
  "default_ref": "abc123...",
  "created_at": "2026-03-11T10:00:00Z",
  "updated_at": "2026-03-11T10:00:00Z"
}

创建锚点：

POST /v1/anchors
Content-Type: application/json

{
  "repo_id": "repo_123",
  "ref": "WORKTREE",
  "path": "internal/service/run.go",
  "start_line": 42,
  "start_col": 1,
  "end_line": 49,
  "end_col": 2,
  "kind": "warning",
  "title": "Retry must stay idempotent",
  "body": "This path duplicated writes during incident 2026-02-14.",
  "author": "human://alice",
  "tags": ["billing", "warning"]
}

更新锚点：

PATCH /v1/anchors/anchor_123
Content-Type: application/json

{
  "kind": "handoff",
  "title": "Next step",
  "body": "Check the retry path before changing timeout handling.",
  "author": "agent://planner",
  "tags": ["billing", "handoff"]
}

关闭、重新打开或解决锚点：

POST /v1/anchors/anchor_123/close
POST /v1/anchors/anchor_123/reopen
POST /v1/anchors/anchor_123/resolve

读取文件上下文：

GET /v1/context?repo_id=repo_123&ref=WORKTREE&path=internal/service/run.go&symbol=*Runner.Run

全文搜索：

GET /v1/search?query=retry&repo_id=repo_123&path=internal/service/run.go&limit=20&offset=0

添加评论：

POST /v1/anchors/anchor_123/comments
Content-Type: application/json

{
  "author": "human://alice",
  "body": "Confirmed in staging replay."
}

所有 API 响应均为 JSON。验证失败时返回：

{
  "error": "message"
}

MCP

anchordb-mcp 通过 MCP stdio 提供相同的数据，并直接读取 SQLite 数据库。它无需 anchord 运行。

运行：

anchordb-mcp --db ~/.anchordb/anchor.db

Claude Code 设置

在 Linux 或 WSL 上，Anthropic 目前为 Claude Code 记录了两种安装方式：

• 原生安装程序：curl -fsSL https://claude.ai/install.sh | bash
• npm 安装程序：npm install -g @anthropic-ai/claude-code

安装 Claude Code 后，将 AnchorDB 添加为 stdio MCP 服务：

claude mcp add anchordb --scope project -- /absolute/path/to/anchordb-mcp --db /absolute/path/to/anchor.db

可用的后续命令：

claude mcp list
claude mcp get anchordb

在 Claude Code 中，使用 /mcp 查看已配置的 MCP 服务及其状态。

注意：

• --scope project 会将配置存储在当前项目的 .mcp.json 中
• --scope local 会将配置仅保留在本地项目设置中
• --scope user 会使其在你计算机上的所有项目中可用
• -- 后面的所有内容都是实际的服务命令及其参数

等效的 .mcp.json 条目：

{
  "mcpServers": {
    "anchordb": {
      "command": "/absolute/path/to/anchordb-mcp",
      "args": ["--db", "/absolute/path/to/anchor.db"]
    }
  }
}

连接后，编码 Agent 可以：

• 在编辑文件前读取锚点上下文
• 搜索以往的笔记和评论
• 在调试期间创建或更新锚点
• 为下次运行留下交接备注

MCP 工具

• repo_add
• anchor_repos
• repo_get
• repo_sync
• repo_remove
• anchor_context
• anchor_create
• anchor_update
• anchor_close
• anchor_reopen
• anchor_resolve
• anchor_comment
• anchor_search
• anchor_text_search
• anchor_events
• anchor_stale
• anchor_candidates
• anchor_relocate
• anchor_get
• anchor_comments
• anchor_file_view

MCP 资源

• anchordb://repos
• anchordb://repo/{repo_id}
• anchordb://context/{repo_id}{?ref,path,symbol}
• anchordb://search{?query,repo_id,path,symbol,kind,limit,offset}
• anchordb://anchors/{repo_id}{?path,symbol,status,limit,offset}
• anchordb://file/{repo_id}{?ref,path}
• anchordb://events/{anchor_id}
• anchordb://anchor/{anchor_id}
• anchordb://comments/{anchor_id}

查看器

Web 查看器会显示：

• 仓库文件列表
• 所选文件及高亮显示的锚点范围
• 锚点卡片和串接评论
• 该文件的 Git 工作树差异

高亮行标示锚点覆盖范围。差异面板会显示所选文件的实际 Git 差异。

存储

所有内容都存储在一个 SQLite 数据库中——包括锚点、评论、历史记录和全文搜索索引。无需服务端，也无需外部依赖；任何数据都不会离开本机。

三个二进制文件都读取同一个文件：

anchord --db ~/.anchordb/anchor.db
anchorctl repo list                 # via anchord
anchordb-mcp --db ~/.anchordb/anchor.db

请将它存放在仓库之外。这是本地状态，不是源代码。

备份时，可在没有写入操作时复制该文件，也可以使用 sqlite3 anchor.db ".backup anchor-backup.db"。

故障排查

症状	原因	修复方法
command not found: anchordb-mcp	Go bin 目录不在 PATH 中	export PATH="$PATH:$(go env GOPATH)/bin"，或使用绝对路径
MCP 主机未列出该服务	配置未重新加载	完全重启主机；检查 claude mcp list
not a git repository	路径不是 Git 工作副本	执行 git init，或指向实际的仓库根目录
path escapes repository root	路径位于仓库外，或符号链接指向仓库外	使用相对于仓库的路径
invalid git ref	引用以 - 开头	使用提交 SHA、分支名称或 WORKTREE
重构后锚点显示为 stale	代码移动范围超出自动匹配能力	运行分诊循环：anchorctl anchor stale
anchorctl 返回 connection refused	anchord 未运行	启动它，或使用无需守护进程的 MCP 工具
搜索精确短语时没有结果	搜索词采用 AND 逻辑	尝试减少搜索词，或使用前缀：retry idempot*

版本管理

AnchorDB 遵循语义化版本规范。所有三个二进制文件报告相同的 版本：

anchord --version
anchorctl version
anchordb-mcp --version

数据库架构会在打开时自动向前迁移。早期版本创建的锚点仍可正常工作；在支持 Git 感知解析之前写入的锚点，会回退到文本匹配，直到下次成功解析。

每个带标签的版本都会在目标平台上构建其二进制文件，发布涵盖每个归档文件的 checksums.txt，并将匹配的多架构镜像推送到 ghcr.io/jolovicdev/anchor-db。

许可证

MIT。请参阅 LICENSE。