⚡ Kash

Cache your knowledge. Channel the Akashic.

A compiler for knowledge. Turn a folder of documents into a self-contained GraphRAG agent you can docker run.

📄 Documents  →  ⚡ kash build  →  🐳 One Container  →  🚀 Ship Anywhere

RAG usually means a Python service, a hosted vector database, a graph server, and glue to hold them together. Kash is a compiler instead. All the expensive work happens once, at build time. What ships is a single binary with the databases baked in.

Works with any OpenAI-compatible API — OpenAI, Voyage, Ollama, LiteLLM, OneAPI. Bring your own model. 🔑

# 1. Install
go install github.com/akashicode/kash/cmd/kash@latest

# 2. Scaffold an agent
kash init my-expert

# 3. Drop in your knowledge (PDF · Markdown · TXT)
cp ~/docs/*.pdf my-expert/data/

# 4. Compile
cd my-expert && kash build

# 5. Serve
kash serve

🎉 Live at http://localhost:8000 — REST API, MCP server, and a dashboard.

Most RAG is cosine similarity and hope. Kash runs four independent retrieval routes and fuses them with Reciprocal Rank Fusion — so a question phrased any way still lands.

flowchart LR
    Q["❓ Query"] --> D["✂️ Decompose<br/><i>entities · concepts</i>"]
    D --> V["🧮 Vector<br/><i>semantic</i>"]
    D --> L["🔤 BM25<br/><i>keyword</i>"]
    D --> X["🎯 Exact ref<br/><i>“clause 7.2”</i>"]
    D --> G["🕸️ Graph<br/><i>facts → passages</i>"]
    V --> F["⚖️ RRF Fusion"]
    L --> F
    X --> F
    G --> F
    F --> RR["📊 Rerank"]
    RR --> A["💬 Answer<br/><i>with citations</i>"]

Why fusion beats any single route: each returns a ranked list, and RRF (k=60) rewards documents that several routes agree on. A chunk ranked 3rd by vectors and 2nd by BM25 outranks one ranked 1st by vectors alone.

Measured on the test corpus: recall@5 of 1.00 fused vs 0.40 vector-only.

Kash splits on document structure, not every N characters. Each chunk carries a breadcrumb baked into its text at build time — so it's part of the embedding, part of the BM25 index, and part of what the model reads:

[Vigyāna Bhairava Tantra > Dhāraṇā 49]

Focus on the space between two breaths…

That single line is why "what is dharana 49" works: the exact-reference route can route to it, BM25 can match it, and the answer can cite it.

• 🔢 Numbered items stay individually addressable — a new verse or clause number starts a new chunk
• 📊 Table headers carry into every chunk of a long table
• 🧾 Corrupt PDF text is rejected, not embedded — some PDFs decode to valid UTF-8 that is actually a substitution cipher, and a quality gate catches it before it reaches the index

Every fact records the chunk it came from, not just the document. That makes the whole chain walkable: entity → chunk id → the actual passage.

Knowledge Graph Facts:
- Abhinavagupta commented on Tantrāloka (source: tantraloka.md [passage 1])
  ↳ Tantrāloka is part of Trika (source: malini.md) [connected via Tantrāloka]

A fact whose passage was retrieved cites [passage N] — pointing at text the reader can see. One whose passage wasn't cites its document and nothing more. Provenance is never invented.

And you can audit it:

kash verify

Facts: 2202          Fold mode: iast

Traceable to a passage:
  both endpoints found      1854   84.2%
  one endpoint found         276   12.5%

Not traceable:
  passage found neither       72    3.3%
  chunk no longer exists       0    0.0%
  no chunk recorded            0    0.0%

✓ 96.7% of facts can be shown to a reader in the passage they came from

The settings that depend on your subject matter are measured from your documents, not asked for. kash build profiles the corpus and writes data/domain.profile.json.

kash profile          # what was measured, and the evidence for it

• resolution.fold_diacritics = iast
    IAST marks: 3597866 in 56/60 docs; Latin marks: 1439 in 37/60 docs
• resolution.strip_final_vowel = true
    1566 stem-vowel variant pairs, e.g. lakṣya/lakṣyam, tāmasa/tāmasam
• chunker.ref_patterns = 6 detected + 2 generic
    "dhāraṇā" (105 hits, sequence 0.97); "śloka" (3209 hits, sequence 0.67)

Point Kash at legal contracts and it finds Clause 4.2. At a research library and it finds Figure 3. Nobody writes a regex.

Configuration is layered, and agent.yaml always wins:

built-in defaults  <  data/domain.profile.json  <  agent.yaml

So you only add a block when you disagree with the measurement. Setting a list there replaces the derived one rather than merging.

kash build tracks every document in data/build.manifest.json — content hash, chunk and triple counts, and how far each phase got.

kash build              # v1 — compiles everything
cp new-books/*.pdf data/
kash build              # v2 — only the new documents are processed

• ⏭️ Unchanged documents are skipped — no embedding calls, no LLM calls
• ♻️ Changed documents are replaced — old vectors and triples removed first
• 🔌 Interrupted builds resume at the exact batch they stopped on — including a build stopped after its last document, whose lexical index, entity descriptions and MCP description are completed by the next run
• 🏷️ Each change bumps the corpus version, exposed at GET /health

kash serve hosts a dashboard at / — one self-contained page embedded in the binary, so it works offline in a container with no CDN.

The retrieval tester is the fastest way to diagnose a bad answer — it shows you what the model actually received.

🔒 Secure every endpoint with the AGENT_API_KEY environment variable.

# Fill in .env with your runtime API keys, then:
kash build
docker compose up --build

docker build -t my-agent:latest .
docker run -p 8000:8000 --env-file .env my-agent:latest

kash build && kash serve
# Falls back to ~/.kash/config.yaml when env vars aren't set

Auto-generated by kash init. Used by kash build for embedding and extraction:

build_providers:
  llm:
    base_url: "https://api.openai.com/v1"
    api_key: "sk-..."
    model: "gpt-4o"
    # reasoning_effort: medium   # low | medium | high — reasoning models only
  embedder:
    base_url: "https://api.voyageai.com/v1"
    api_key: "pa-..."
    model: "voyage-3"

Generated per project. Persona, dimensions, chunk sizes — and that's genuinely all you need to write:

agent:
  name: "my-agent"
  system_prompt: |
    You are a knowledgeable expert assistant...

runtime:
  embedder:
    dimensions: 1024     # must match at build AND serve time
  llm:
    reasoning_effort: medium   # optional

build:
  chunk_size: 1000       # characters per chunk (800–2000 works best)
  chunk_overlap: 200

retrieval:
  top_k: 5               # chunks injected as context
  graph_facts: 10        # graph facts injected

git clone https://github.com/akashicode/kash.git
cd kash
make build          # or: make build-all for every platform
                    # Windows without make: powershell -File scripts\build.ps1
go test ./...       # full suite

Release history and upgrade notes live in CHANGELOG.md — including which changes need a kash build --rebuild.