alexandria-wiki 0.36.0

Local-first single-user knowledge engine — accumulates gathered knowledge and exposes it via MCP to connected agents like Claude Code.

Alexandria

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.

Install

pip install alexandria-wiki          # core
pip install "alexandria-wiki[pdf]"   # + PDF support
pip install "alexandria-wiki[all]"   # + PDF + YouTube transcripts

Or with uv:

uvx alexandria-wiki
# or
uv tool install alexandria-wiki

Quick Start

# 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

# 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 start

Sources

Alexandria ingests from 14 source types:

Source	Command
Local file	alxia ingest ~/file.md
PDF	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 sync

MCP Integration

Alexandria 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-code

After 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 7219

CLI Reference

alxia 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

Architecture

• 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 cleanup removes 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

docker build -t alexandria .
docker run -v ~/.alexandria:/data alexandria init
docker run -v ~/.alexandria:/data alxia status

Development

git clone [e-mail]: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 tag

License

MIT