the-librarian

The Librarian

The Librarian is a living, markdown-native knowledge graph for AI agents — with a resident curator that tends it. It is a markdown+git vault of three note types — memories, handoffs, and references — linked into a graph by [[wikilinks]]; a resident "librarian" curates the collection as it grows, filing each new memory where it belongs, linking it to its neighbours, and organising the whole for retrieval, not just storage. It's all plain files you can read, edit, and reorganise yourself (in the dashboard or in Obsidian); git gives it history; nothing is locked in a database.

Practically, that makes it a portable memory + handoff layer for AI agents: served to any harness over MCP as 7 verbs, taught to agents by one ≤2KB primer, with an explicit cross-harness handoff surface so work started in one harness (Claude Code, Codex, Hermes, OpenCode, Pi) can be packaged into a single document and picked up cleanly in another.

It runs as a small self-hosted server, reachable locally or over the network.

Harness integrations

Run the server, then add one config block per harness. Claude Code, Codex, and OpenCode need no plugin code at all — the MCP config (plus, for OpenCode, one instructions line pointing at the server's GET /primer.md) is a full integration. Hermes and Pi get thin in-tree adapters. Each harness's exact config and install steps live in its README:

Harness	Integration	Shape
Claude Code	integrations/claude	MCP config; optional plugin adds 4 slash commands
Codex	integrations/codex	MCP config block in ~/.codex/config.toml — no code
OpenCode	integrations/opencode	MCP config + one remote-URL instructions line — no code
Hermes	integrations/hermes	Python MemoryProvider (stdlib-only) proxying the 7 verbs
Pi	integrations/pi	Pi extension: primer hook + 7 native tool proxies

All five teach the model the same protocols: the primer rides each harness's thinnest native channel (MCP instructions where honored, a one-hook adapter where not), and the 7 tools carry protocol-bearing descriptions that render in every harness.

Features

• Durable memory — recall / remember / flag_memory over one shared, curated corpus with project-key scoping and a three-state (active / proposed / archived) model.
• Cross-harness handoffs — store_handoff packages the work in a five-section document; claim_handoff claims it atomically in another agent / harness.
• References — long-form background material (specs, papers, manuals) uploaded by the admin, chunk-indexed with persistently cached embeddings so a 500KB document is searchable end-to-end via search_references — deliberately not auto-recalled.
• Memory curator — one curator, one prompt core, one apply rule: routine operations (create/update/merge) auto-apply above a single confidence threshold; destructive ones (archive/split) always become human-reviewed proposals.
• Dashboard as the complete admin surface — memory browser, proposal + flag queues, curator config/chat/run history, vault explorer/editor (Obsidian-lite: tree, rendered markdown, wikilinks, backlinks, validated editing), and history/diff/rollback backed by the server-owned git repo — operators never need git or Obsidian.

Markdown-native and dependency-light: memories are plain [[wikilinked]] notes in a git-backed vault, recall runs over a disposable in-memory index (keyword + vector + backlinks, RRF-fused) rebuilt from the vault — no external database to run.

Quick start

Docker (recommended for a VPS)

cp .env.example .env   # optional — auth/secret vars auto-generate
docker compose --env-file .env -f docker/docker-compose.yml up -d --build

A fresh install needs zero auth/secret env vars: LIBRARIAN_ADMIN_TOKEN and LIBRARIAN_SECRET_KEY auto-generate on first boot (watch the log for the one-time values), and you enable owner login from the dashboard. Full deploy guide: DEPLOYMENT.md.

Then connect a harness: pick yours under integrations/ and add the config block from its README.

Local dev (two services)

Requirements: Node 22.5+ and pnpm 9.15.x via Corepack: