Give your AI coding agent a persistent, citable knowledge base. alexandria ingests papers, articles, code, and conversations into a local wiki with verified quote citations — and exposes it over MCP so Claude Code, Cursor, Codex, and other MCP-capable agents can retroactively query, cross-reference, and synthesize everything you've ever fed it.
pip install alexandria-wiki && alxia init
alxia ingest https://arxiv.org/abs/2307.03172
alxia mcp install claude-code
# now ask your agent — the knowledge is there, with citations back to source
Live belief graph from a real vault — 668 nodes, 500 edges. Blue =
code-derived, yellow = topic hubs, orange = web, green = papers.
Generate your own with alxia export <dir> --format graph.
Three things alexandria does that most "feed-your-LLM-a-folder" tools don't:
- Durable across sessions. Knowledge accumulates in
~/.alexandria/; every ingest is a staged, verified write, not a regenerate-from-scratch pass. - Every claim has a citation. A deterministic verifier checks that each footnote maps to a verbatim quote in the original source via SHA-256 anchors — no hallucinated references.
- Belief revision, not just retrieval. Structured claims with
supersession chains. Ask
alxia why <topic>and you get what was believed, what superseded it, and why.
alexandria is not a chat client. Interactive conversations happen in your existing MCP-capable agent (Claude Code, Cursor, Codex). alexandria is the knowledge engine those agents connect to.
pip install alexandria-wiki # core (includes PDF)
pip install "alexandria-wiki[all]" # + YouTube transcripts, Telegram bot, watchOr with uv:
uvx alexandria-wiki
# or
uv tool install alexandria-wiki# 1. Initialize
alxia init
# 2. Connect to Claude Code (one-time setup)
alxia mcp install claude-code # register MCP server
alxia hooks install claude-code # auto-capture conversations
# 3. Restart Claude Code — Alexandria tools are now available
# 4. Ingest from anywhere
alxia ingest ~/Documents/paper.pdf
alxia ingest https://arxiv.org/abs/2407.09450
alxia ingest ./my-project # whole directory
alxia ingest epappas/alexandria # GitHub repo
alxia ingest ~/.claude/projects/*/session.jsonl # conversation
# 5. Query your knowledge
alxia query "What do you know?"
# Bonus: one-line capability report (paste-ready for a README badge)
alxia bench
# → 864 pages · 15,589 beliefs across 3,804 topics · 1,664 verified
# ingests · search 41ms / 386ms P95 · citation-verified rate: 99.9%
# Optional: interactive belief-graph viewer (zero-CDN, self-contained HTML)
alxia export ~/alexandria-graph --format graph
open ~/alexandria-graph/graph.html
# Ingest is async and runs on Haiku regardless of your session model —
# batch loads never block the conversation or burn Opus quota.
# Inspect or control jobs from the CLI:
alxia jobs list # what's running / queued / recent
alxia jobs tail <job_id> # stream a job's progress
alxia jobs cancel <job_id> # cooperative cancel; committed pages stay
# Optional: install as a Claude Code / Cursor / Codex skill for an
# always-on "/alexandria" command that orients your agent before grep
alxia skill install claude-code
# Optional: chat with your knowledge base from your phone via Telegram
pip install "alexandria-wiki[bot]"
alxia secrets set telegram_bot_token # paste BotFather token
# then add your Telegram user ID to ~/.alexandria/config.toml under
# [bot].telegram_allowlist = [123456789]
alxia bot startAlexandria ingests from 14 source types:
| Source | Command |
|---|---|
| Local file | alxia ingest ~/file.md |
alxia ingest ~/paper.pdf |
|
| URL (HTML) | alxia ingest https://example.com/article |
| Code (.py/.ts/.rs/.go/.tf/.yml) | alxia ingest main.py (AST extraction) |
| Directory | alxia ingest ./my-project |
| Git repo | alxia ingest https://github.com/owner/repo |
| GitHub shorthand | alxia ingest owner/repo |
| Conversation | alxia ingest ~/.claude/projects/*/session.jsonl |
| GitHub (events) | alxia source add github --name repo --owner x --repo y |
| RSS/Atom | alxia source add rss --name blog --feed-url https://example.com/feed |
| YouTube | alxia source add youtube --name talks --urls "https://youtu.be/abc" |
| Notion | alxia source add notion --name wiki --token-ref key --page-ids "abc" |
| HuggingFace | alxia source add huggingface --name models --repos "meta-llama/Llama-3-8b" |
| Obsidian/Folder | alxia source add folder --name vault --path ~/ObsidianVault |
| Zip/Tar | alxia source add archive --name papers --path ~/papers.zip |
| IMAP | alxia source add imap --name mail --imap-host imap.gmail.com --imap-user me |
| Clipboard | alxia paste --title "note" --content "quick thought" |
After adding sources, pull everything with:
alxia syncAlexandria exposes your knowledge to AI agents via the Model Context Protocol.
# Register with Claude Code (one-time)
alxia mcp install claude-code
# Install conversation capture hooks (one-time)
alxia hooks install claude-code
# Restart Claude Code — done. Verify:
alxia mcp status
alxia hooks verify claude-codeAfter setup, Claude Code has 20 Alexandria tools:
| Category | Tools |
|---|---|
| Navigate | guide, overview, list, search, grep, read, follow |
| History | history, why, timeline, events |
| Git | git_log, git_show, git_blame |
| Sources | sources, subscriptions |
| Write | ingest, query, belief_add, belief_supersede |
For other MCP clients:
alxia mcp serve-http --port 7219alxia init Initialize ~/.alexandria/
alxia status Operational dashboard
alxia doctor Health checks
alxia ingest <source> Ingest file, dir, URL, repo, or conversation
alxia query <question> LLM-powered answers from your knowledge base
alxia why <topic> Belief explainability + provenance
alxia lint Find wiki rot (stale citations)
alxia synthesize Generate temporal digest
alxia source add <type> Add a source adapter
alxia source list List configured sources
alxia sync Pull from all sources
alxia subscriptions poll Poll RSS + IMAP
alxia subscriptions list Show pending items
alxia workspace use <slug> Switch workspace
alxia project create <name> Create a project workspace
alxia secrets set <ref> Store an encrypted secret
alxia beliefs cleanup Dedup beliefs and remove orphans
alxia hooks install <client> Install capture hooks
alxia capture conversation Capture an agent session
alxia eval run Run quality metrics (M1-M5)
alxia daemon start Start background scheduler
alxia logs show View structured logs
- SQLite + filesystem hybrid: filesystem is source of truth for documents, SQLite for search/metadata/events
- Hybrid search: FTS5 BM25 + recency decay + belief support scoring (no vectors, no RAG — the agent IS the retriever)
- AST extraction: Python, TypeScript, Rust, Go, Terraform, Ansible, YAML parsed into structured beliefs
- Hostile verifier: every wiki write is verified before commit (citations, quote anchors, cascade policy)
- Belief revision: structured claims with supersession chains and provenance
- Conversation capture: auto-captures Claude Code sessions with artifact extraction (papers, repos)
- Self-awareness: Alexandria can answer questions about its own state and capabilities
- Document dedup: content-hash check skips re-ingest of unchanged files
- Belief integrity: supersede-all-then-restore prevents duplicates;
alxia beliefs cleanupremoves orphans - AES-256-GCM vault: encrypted secrets with PBKDF2 key derivation
- Structured JSONL logging with run_id correlation
- 10 schema migrations applied automatically on init
See docs/architecture/ for the 20 architecture documents.
docker build -t alexandria .
docker run -v ~/.alexandria:/data alexandria init
docker run -v ~/.alexandria:/data alxia statusgit clone git@github.com:epappas/alexandria.git
cd alexandria
uv sync --dev
uv run pytest tests/ # 352+ tests
./scripts/build.sh # test + build
./scripts/publish.sh # test + build + PyPI + git tagMIT