lorebook

A local-first temporal knowledge graph for your AI agents, as an MCP server. No Docker. No accounts. No API keys. One command.

npx lorebook --dir ~/my-kb     # or: bunx lorebook --dir ~/my-kb

Lorebook is an answer to Graphiti/Zep for personal use: your agents save facts with validity intervals ("main-pc has an ultrawide — since March"), search them with hybrid semantic + keyword retrieval, and supersede them when the world changes — all stored as plain text you can grep, diff, and sync with git. Embeddings run on-device (a ~33MB ONNX model, downloaded once and cached in ~/.cache/lore/models — set LORE_MODEL_CACHE to relocate it).

Register with your harness

Claude Code: claude mcp add lorebook -- npx lorebook --dir ~/my-kb (Codex / Gemini CLI / OpenCode: add the same stdio command to their MCP config.)

60-second tour

1. npx lorebook init --dir ~/my-kb
2. Ask your agent to remember something: it calls kb_save with the episode and its extracted facts.
3. Ask about it tomorrow: kb_search returns compact, cited facts — live ones first, superseded ones on request, point-in-time with as_of.

Graph viewer

lorebook ui --dir ~/my-kb        # opens http://127.0.0.1:7777
lorebook ui --dir ~/my-kb --open # ...and launches your browser

An animated, read-only force-graph of the knowledge base — served locally, fully offline, zero dependencies. Entities are circles sized by how many live facts touch them; click one to expand its neighbors and see its card. The as_of scrubber replays the graph through time: superseded facts dim, retracted ones disappear. Binds 127.0.0.1 only. Change the port with --port or $LORE_UI_PORT.

Agent rules

Copy the ready-made rules block from docs/rules-snippet.md into your AI rules file. It covers: search before assuming, durable-facts test, entity reuse, predicate vocabulary, immediate conflict resolution, and kb_doctor on request.

Performance

Measured on a local Linux machine with the stub embedder (384-dim, hash-based):

| Corpus size | Index time | p50 search | p95 search | |-------------|-----------|-----------|-----------| | 50k facts + 2k entities + 5k episodes | ~5.4s | 38.7ms | 66.5ms |

Budget: p95 < 500ms at 50k facts. Benchmark asserts this in CI (bun scripts/bench.ts --assert). Real-model numbers are similar (embedding is cached after first run).

Troubleshooting

• First call is slow / "downloading" appears to hang — the ONNX model (~33MB) downloads on first use, then is cached in ~/.cache/lore/models. Subsequent runs are fast. Don't interrupt the first run.
• Search says "keyword-only mode" — the embedder failed to load (no network on first download, or a corrupt cache). Delete ~/.cache/lore/models and run any command again to re-download cleanly.
• Check the version — lorebook --version. See all commands with lorebook --help.

Status

Published on npm as lorebook. Feature-complete (M1–M4): store, hybrid search, temporal filters, graph expansion, entity cards, timelines, conflict detection, kb_resolve, kb_doctor. CI: Linux+macOS × Bun+Node.