Metadata-Version: 2.4
Name: alexandria-wiki
Version: 0.37.3
Summary: Local-first single-user knowledge engine — accumulates gathered knowledge and exposes it via MCP to connected agents like Claude Code.
Project-URL: Repository, https://github.com/epappas/alexandria
Project-URL: Documentation, https://github.com/epappas/alexandria/tree/main/docs
Author-email: Evangelos Pappas <epappas@evalonlabs.com>
License: MIT
License-File: LICENSE
Keywords: agentic,knowledge-base,llm,mcp,personal-knowledge,wiki
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.40.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: feedparser>=6.0.0
Requires-Dist: markdownify>=0.12.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pymupdf>=1.24.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.15.0
Provides-Extra: all
Requires-Dist: claude-code-sdk>=0.0.20; extra == 'all'
Requires-Dist: pymupdf>=1.24.0; extra == 'all'
Requires-Dist: python-hcl2>=4.0.0; extra == 'all'
Requires-Dist: python-telegram-bot>=21.0; extra == 'all'
Requires-Dist: watchdog>=4.0.0; extra == 'all'
Requires-Dist: youtube-transcript-api>=0.6.0; extra == 'all'
Provides-Extra: bot
Requires-Dist: python-telegram-bot>=21.0; extra == 'bot'
Provides-Extra: claude
Requires-Dist: claude-code-sdk>=0.0.20; extra == 'claude'
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: hcl
Requires-Dist: python-hcl2>=4.0.0; extra == 'hcl'
Provides-Extra: pdf
Provides-Extra: watch
Requires-Dist: watchdog>=4.0.0; extra == 'watch'
Provides-Extra: youtube
Requires-Dist: youtube-transcript-api>=0.6.0; extra == 'youtube'
Description-Content-Type: text/markdown

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

```bash
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
```

![alexandria belief graph](docs/assets/graph.png)

*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

```bash
pip install alexandria-wiki          # core (includes PDF)
pip install "alexandria-wiki[all]"   # + YouTube transcripts, Telegram bot, watch
```

Or with uv:

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

## Quick Start

```bash
# 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` |
| **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:

```bash
alxia sync
```

## MCP Integration

Alexandria exposes your knowledge to AI agents via the [Model Context Protocol](https://modelcontextprotocol.io/).

```bash
# 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:
```bash
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

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

## Development

```bash
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
