Librarian is a local, Codex-only federated code memory. It builds a deterministic Tree-sitter/SQLite graph across an explicit set of local Git repositories, augments that graph with evidence-validated Codex findings, and exposes the result through a read-only CLI and MCP server.

V1 targets macOS and Linux. It never runs repository builds, tests, dependency hooks, or project code while indexing, and librarian ask produces answers or plans only—it does not edit repositories.

• Go 1.25 or newer
• CGO enabled and a local C compiler (Apple Clang or GCC/Clang)
• Git
• The codex CLI, authenticated with codex login

Install the current checkout:

CGO_ENABLED=1 go install .

Initialize a catalog whose child directories contain Git worktrees:

librarian init /absolute/path/to/catalog

Initialization confirms discovered repositories, writes librarian.toml, installs local .agents/skills/librarian and .librarian integration in each repository, registers the global Codex stdio MCP server, performs the first complete refresh, and atomically publishes a snapshot.

Selected source is sent to Codex through the user's existing Codex authentication for semantic analysis. The SQLite database, graph, Markdown memory, evidence, and findings remain local.

librarian repo discover|list|add|remove
librarian refresh [--repo <id-or-alias>] [--full] [--resume <run-id>]
librarian status [--json]
librarian search|context|path|impact|get ... [--json]
librarian ask "<question>" [--repo <id-or-alias>] [--json]
librarian mcp
librarian codex install|status|uninstall
librarian doctor

The graph uses logical references such as librarian://catalog/<catalog-id>/repo/<repo-id>. MCP tools accept those logical URIs and stable entity IDs, never arbitrary filesystem paths or SQL.

The catalog's authoritative repository list is librarian.toml. Complete immutable snapshots live under .librarian/snapshots, with .librarian/current atomically selecting the active one. Each repository receives:

.librarian/
  repository.toml
  status.json
  managed.json
.agents/skills/librarian/
  SKILL.md
  agents/openai.yaml
  references/catalog.toml
  managed.json

Only those exact generated paths are added to the repository's real Git info/exclude. Existing .agents content is preserved. Librarian refuses to overwrite tracked, edited, unmanaged, or cross-catalog collisions.

go test ./...
go test -race ./...
go vet ./...
CGO_ENABLED=1 go build .

Normal tests use a fake Codex client. Live Codex calls are opt-in through the installed CLI.