anchor-db

README

AnchorDB

AnchorDB is a local code-memory service for Git repositories.

This is experimental software. The core ideas are stable enough to use locally, but the storage format, APIs, and ergonomics may still change as the project is refined.

It stores durable notes attached to files, spans, and symbols, then exposes that data through:

• anchord for HTTP and the web viewer
• anchorctl for shell workflows and scripts
• anchordb-mcp for MCP hosts such as Claude Code

AnchorDB is primarily useful as durable working memory for coding agents. It gives an agent or a human a place to store code-local warnings, debugging notes, TODOs, handoff context, and rationale that should stay attached to the implementation instead of disappearing into chat history.

Use Cases

AnchorDB is best suited for:

• AI agents that need to read context before editing a file or symbol
• agent handoffs where one run should leave precise notes for the next run
• long debugging sessions where repros and findings should stay attached to code
• human review notes on risky paths such as billing, auth, migrations, or retry logic
• local or team workflows that want both a web viewer and an MCP surface over the same code memory

The main workflows are:

• anchordb-mcp for coding agents
• anchorctl for scripts, shells, and CI
• anchord for browsing code, anchors, comments, and diffs in a browser

How It Works

AnchorDB stores anchors.

Each anchor contains:

• repo metadata
• a note body and kind
• a file path
• a line and column range
• selected text plus surrounding context
• an optional symbol path

When files change, AnchorDB re-resolves anchors using the saved span, text context, and symbol information. Tree-sitter improves symbol extraction and relocation, but the system still works without it.

Built-in symbol extractors:

• Go
• Python
• JavaScript
• TypeScript

Install

Install the binaries into your Go bin directory:

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

To install from a local checkout instead:

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

Check where Go installs binaries with:

go env GOBIN
go env GOPATH

Quick Start

Start the server:

anchord -db ./anchor.db -sync-interval 30s

Register a repo:

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

Create an anchor:

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

Open the viewer:

http://127.0.0.1:7740/

Start the MCP server:

anchordb-mcp --db ./anchor.db

CLI

anchorctl talks to the running HTTP server.

It reads the base URL from ANCHOR_DB_URL. Default:

http://127.0.0.1:7740

Repo Commands

Add a repo:

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

List repos:

anchorctl repo list

Get one repo:

anchorctl repo get --id repo_123

Sync one repo:

anchorctl repo sync --id repo_123

Remove one repo:

anchorctl repo remove --id repo_123

Anchor Commands

List anchors:

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

Get one anchor:

anchorctl anchor get --id anchor_123

Create an anchor:

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

Update anchor metadata:

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

Archive an anchor:

anchorctl anchor close --id anchor_123

Reopen an anchor:

anchorctl anchor reopen --id anchor_123

Re-run anchor resolution:

anchorctl anchor resolve --id anchor_123

Context, Comments, Search

Get file or symbol context:

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

List comments:

anchorctl comment list --anchor-id anchor_123

Add a comment:

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

Full-text search:

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

All CLI commands return JSON.

HTTP API

Default listen address:

http://127.0.0.1:7740

Endpoints

• 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/context
• GET /v1/search
• GET /view

Common Requests

Create a repo:

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

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

Response:

{
  "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"
}

Create an anchor:

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"]
}

Update an anchor:

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"]
}

Close, reopen, or resolve an anchor:

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

Read file context:

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

Full-text search:

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

Add a comment:

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

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

All API responses are JSON. Validation failures return:

{
  "error": "message"
}

MCP

anchordb-mcp serves the same data over MCP stdio and reads the SQLite database directly. It does not require anchord to be running.

Run it:

anchordb-mcp --db ./anchor.db

Claude Code Setup

On Linux or WSL, Anthropic currently documents two install paths for Claude Code:

• native installer: curl -fsSL https://claude.ai/install.sh | bash
• npm installer: npm install -g @anthropic-ai/claude-code

After Claude Code is installed, add AnchorDB as a stdio MCP server:

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

Useful follow-up commands:

claude mcp list
claude mcp get anchordb

Inside Claude Code, use /mcp to inspect configured MCP servers and their status.

Notes:

• --scope project stores the configuration in .mcp.json for the current project
• --scope local keeps it private to your local project setup
• --scope user makes it available across projects on your machine
• everything after -- is the actual server command and its arguments

Equivalent .mcp.json entry:

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

Once connected, a coding agent can:

• read anchor context before editing a file
• search previous notes and comments
• create or update anchors during debugging
• leave handoff notes for the next run

MCP Tools

• 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_get
• anchor_comments
• anchor_file_view

MCP Resources

• 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://anchor/{anchor_id}
• anchordb://comments/{anchor_id}

Viewer

The web viewer shows:

• a repo file list
• the selected file with highlighted anchor ranges
• anchor cards and threaded comments
• the Git working-tree diff for that file

Highlighted lines mark anchor coverage. The diff panel shows the actual Git diff for the selected file.

Storage

AnchorDB stores data in SQLite.

The same database can be used by:

• anchord
• anchorctl
• anchordb-mcp

Typical local path:

./anchor.db