Axon

Your documents, answerable. On your hardware.

Drop in PDFs, code, spreadsheets, or URLs — ask anything, get cited answers from a local LLM. Nothing leaves your machine.

[](https://pypi.org/project/axon-rag/) [](https://www.python.org/downloads/) [](https://github.com/jyunming/Axon/actions/workflows/ci.yml) [](https://github.com/jyunming/Axon/blob/main/LICENSE) [](https://github.com/psf/black)

---

🤔 Why Axon?

Most RAG tools make you choose between cloud power and data privacy. Axon is local-first — full capability with zero egress when you run on Ollama or vLLM; cloud providers (OpenAI, Gemini, Grok, GitHub Copilot, Ollama Cloud) stay optional.

• 🔒 Private by default — local inference via Ollama or vLLM is the recommended path; cloud providers (OpenAI, Gemini, Grok, GitHub Copilot, Ollama Cloud) remain opt-in. No telemetry. Strict offline / air-gap mode shuts every outbound call off entirely.
• 📄 Ingest anything — 54 file formats (PDF, DOCX, Jupyter, code, images, URLs) in one command. SHA-256 dedup skips unchanged files.
• 🤖 Works in your tools — @axon in Copilot Chat, MCP for Claude Code / Codex / Gemini CLI / Cursor, Graph panel in VS Code or your browser.
• 🤝 Built for teams — share your knowledge base with signed, revocable read-only keys. Sealed (AES-256-GCM encrypted) sharing works safely through OneDrive, Dropbox, and Google Drive. Per-user permissions, full audit trail, no extra infrastructure. [Quick setup →](#sealed-sharing-quick-start)
• 🕸️ See your knowledge as a graph — interactive 3D entity-relationship graph. Embedded webview in VS Code; opens in your browser everywhere else. Click any node to inspect its supporting chunks and source excerpt.
• 🔬 Production-grade retrieval — hybrid search, reranking, HyDE, multi-query expansion, and automatic web fallback. Zero manual tuning.

---

✨ Capabilities

🔍 Retrieval

• Hybrid semantic + keyword search
• HyDE, multi-query, step-back, query decomposition
• Sentence-window context retrieval
• BGE reranker for second-pass precision
• Web fallback via Brave Search (CRAG-Lite)
• Smart per-question query routing
• Structured citations — sources + citations arrays with character offsets (Claude / OpenAI compatible)

🧠 Graph Intelligence

• GraphRAG — entity/relation/community graph (local / global / hybrid)
• Dynamic Graph — bi-temporal SQLite facts with valid_at + invalid_at
• Federated — weighted RRF over multiple backends, tunable per query
• Point-in-time queries (v0.3.2) — --graph-retrieve "..." --graph-at TS
• Conflict inspection (v0.3.2) — --graph-conflicts surfaces status='conflicted' facts
• RAPTOR — hierarchical corpus summaries · Code Graph via AST · 3D webview

📥 Ingest Everything

• 54 file formats — PDF, DOCX, XLSX, PPTX, Jupyter, images, 24 code formats
• URL ingestion — any public web page
• SHA-256 dedup skips unchanged files
• Stale detection for modified sources
• 4 content-aware chunking strategies

🔧 LLMs & Embeddings

• Local: Ollama, vLLM
• Cloud (API key): OpenAI, Gemini, xAI Grok, GitHub Copilot, Ollama Cloud
• Hot-swap provider and model — no restart needed
• Streaming on all providers
• 4 embedding providers; BGE-M3 for multilingual

🏗️ Projects & Privacy

• Isolated knowledge base per project, with nesting
• Federated search across projects (@projects, @mounts, @store)
• Strict offline / air-gapped mode — zero outbound calls
• AxonStore — signed read-only sharing across OS users

☁️ Cloud-Drive Sharing

Sealed (AES-256-GCM encrypted) sharing works through any cloud sync drive. Files are ciphertext on disk — cloud providers see only encrypted bytes.

• OneDrive Personal / Business
• Dropbox
• Google Drive (Mirror mode)

→ [Sharing Guide](docs/SHARING.md) | [Quick Setup →](#sealed-sharing-quick-start)

🛡️ Governance & Agents

• Governance Console — full audit trail of every query
• Graceful maintenance states: normal → draining → readonly → offline
• REST API — 73 endpoints with Swagger docs at /docs
• MCP server — 51 tools for Claude Code, Codex, Gemini, Cursor, Copilot
• @axon VS Code chat participant with Graph and Governance panels

---

⚡ Quick Start

pip install "axon-rag[starter]"   # Python 3.10+. Includes UI, sealed sharing, extra loaders.
axon                              # First run auto-launches the setup wizard, then drops into the REPL.

That's it. The wizard configures your LLM provider, embedding model, and retrieval defaults; subsequent runs go straight to the REPL.

See it run — first-run wizard, ingest, and a cited query

If something doesn't look right:

axon --doctor                     # Health checks: Python, Ollama, model pulled, store writable.

Local inference uses Ollama or vLLM (self-hosted). Cloud providers (OpenAI, Gemini, Grok, GitHub Copilot, Ollama Cloud) work via API keys.

→ Setup guide for VS Code, MCP, and cloud providers →

---

🔐 Sealed Sharing Quick Start

Share an encrypted knowledge base through OneDrive, Dropbox, or Google Drive. Cloud providers see only ciphertext.

pip install "axon-rag[sealed]"   # install sealed extra on both machines

Owner (5 steps)

axon --store-init "/path/to/OneDrive/AxonStore"  # 1. point store at sync folder
axon --store-bootstrap "your-passphrase"          # 2. bootstrap master key (once per machine)
axon --project-new research                       # 3. create project + ingest
axon --project research --ingest /docs
axon --project-seal research                      # 4. encrypt in place (≈1 s per 100 MB)
axon --share-generate research alice              # 5. print SEALED1:... string — send to grantee

Grantee (3 steps)

axon --store-init "/path/to/OneDrive/AxonStore"   # 1. same shared folder
axon --share-redeem "SEALED1:..."                  # 2. redeem — DEK stored in OS keyring
axon --project mounts/owner_research "question"   # 3. query; Axon decrypts to temp, wipes on exit

[→ Full Sharing Guide](docs/SHARING.md) — OneDrive setup, revocation, headless/Docker grantees, filesystem compatibility matrix.

---

🚀 Entry Points

| Command | Starts | Default Port | Best For | |---------|--------|-------------|---------| | axon | Interactive REPL | — | Day-to-day exploration, power users | | axon-api | FastAPI REST server | 8000 | Agents, scripts, CI pipelines | | axon-mcp | MCP stdio server | — | Any MCP-compatible agent (Claude Code, Codex, Gemini CLI, Cursor, Copilot…) | | axon-ui | Streamlit UI | 8501 | Browser-based exploration |

---

🔌 VS Code + GitHub Copilot

Install the bundled VSIX to unlock the @axon chat participant, Knowledge Graph panel, Code Graph panel, and Governance dashboard — directly inside VS Code alongside Copilot.

Extensions panel  →  "..."  →  Install from VSIX...
→  run `axon-ext`  (or install from VSIX manually)

Or connect via MCP for Copilot agent mode — point .vscode/mcp.json at axon-mcp and all 51 tools appear in the agent hammer menu automatically.

> The VS Code extension surfaces 39 LM tools to Copilot Chat, covering core RAG operations, sealed-store security, sharing, and governance.

Full setup guide →

---

🐍 Use Axon from Your Python Agent

Drop-in retrievers for LangChain and LlamaIndex agents — no REST round-trips, no extra process. Both wrap the same AxonBrain.search_raw() codepath the REST and REPL surfaces use, so hybrid search, reranking, HyDE, multi-query, and the GraphRAG budget apply automatically.

# pip install "axon-rag[langchain]"
from axon import AxonBrain, AxonConfig
from axon.integrations.langchain import AxonRetriever

brain = AxonBrain(AxonConfig.from_yaml("config.yaml"))
retriever = AxonRetriever(brain=brain, top_k=5)

docs = retriever.invoke("what does the project do?")  # list[Document]

# pip install "axon-rag[llama-index]"
from axon.integrations.llama_index import AxonLlamaRetriever

retriever = AxonLlamaRetriever(brain=brain, top_k=5)
nodes = retriever.retrieve("what does the project do?")  # list[NodeWithScore]

Per-call overrides (e.g. force HyDE for one question): retriever.with_overrides({"hyde": True}).invoke(query). From async code, await retriever.aretrieve(query, hyde=True, top_k=8) accepts the same flags as kwargs without rebuilding the retriever (v0.4.1).

---

📚 Documentation

Getting started

| | Guide | What it covers | |-|-------|---------------| | 🚀 | Getting Started | First-time walkthrough — ingest, query, settings | | ⚙️ | Setup Guide | Install, models, VS Code extension, MCP connection | | 🔧 | Troubleshooting | Common errors and platform-specific fixes |

Reference

| | Guide | What it covers | |-|-------|---------------| | 🔑 | Admin Reference | Every endpoint, REPL command, CLI flag, and config option | | ⚡ | Quick Reference | Commands and flags at a glance | | 📡 | API Reference | Full REST endpoint reference with request/response schemas | | 🔌 | MCP Tools | All 51 MCP tool signatures with parameter defaults |

Deep dives

| | Guide | What it covers | |-|-------|---------------| | 🤖 | Model Guide | Choosing LLM and embeddings; per-provider config examples | | 🔬 | Advanced RAG | HyDE, RAPTOR, GraphRAG, CRAG-Lite — how each technique works | | 🌐 | Web Search | Brave Search integration, CRAG-Lite fallback setup | | 🏝️ | Offline / Air-gap Guide | Full air-gap setup, model pre-download, local-assets-only mode | | 💻 | Code RAG Guide | Code graph retrieval and structural search | | 🤝 | AxonStore | Multi-user sharing, revocation, and the lease lifecycle | | 🔐 | Sharing Guide | Plaintext and sealed sharing — which filesystems are safe, OneDrive/Dropbox/Google Drive setup, revocation | | 📊 | Governance Console | Audit trail, maintenance runbook, session management | | 📈 | Evaluation Guide | RAGAS metrics, running evals, building testsets | | 🛠️ | Development Guide | Tests, contributing, pre-commit hooks, packaging & release |

---

🔒 Security

Ingestion is sandboxed to a configurable base directory (RAG_INGEST_BASE). Requests outside it are rejected with 403. See SECURITY.md.

📄 License

MIT — see LICENSE.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jyunming
• Source: jyunming/Axon
• License: MIT
• Homepage: https://jyunming.github.io/Axon/

Install and usage instructions live in the source repository linked above.