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 (includes PDF)
pip install "alexandria-wiki[all]" # + YouTube transcripts, Telegram bot, watch
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
# 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 start
Sources
Alexandria 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 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 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
docker build -t alexandria .
docker run -v ~/.alexandria:/data alexandria init
docker run -v ~/.alexandria:/data alxia status
Development
git 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 tag
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for alexandria-wiki 0.38.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| alexandria_wiki-0.38.1.tar.gz | 1.1 MB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| alexandria_wiki-0.38.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.4 MB
Release files / alexandria_wiki-0.38.1.tar.gz
| Download URL | alexandria_wiki-0.38.1.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a67aa5cdac3e7a7d7a3084f03b6bec5299c66f2b97e7466332e29dc91fd8a60e
|
|
BLAKE2b-256 checksum How to use checksums |
1b0b4bd3bc63664f30c002452de936a11f8cb92f5d0b35c41af63bdc003341c4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / alexandria_wiki-0.38.1-py3-none-any.whl
| Download URL | alexandria_wiki-0.38.1-py3-none-any.whl |
|---|---|
| Size | 325.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
eeffa8084d5291ac28de052401bf215274fa2662ac0e60dd813c7089ef17859c
|
|
BLAKE2b-256 checksum How to use checksums |
8d44dafe160654d93abf7ac5a7e50e086481eaab5e86b4bf019a8c1d5a138b78
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Security for alexandria-wiki 0.38.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
