Kash 2.0 — Hybrid 4-Route RRF + Verifiable GraphRAG

Compile Knowledge.
Channel the Akashic.

Turn raw PDF, Markdown, and TXT documents into self-contained, embedded GraphRAG brains — packaged into ultra-lightweight ~50MB Docker containers with zero runtime dependencies.

Pure Go 1.25 ~50MB Docker image 4-route RRF fusion 96.7% verifiable provenance Zero Python · zero external DBs

Quickstart Explore the hybrid engine

# 1. Install the pure-Go binary $ go install github.com/akashicode/kash/cmd/kash@latest # 2. Scaffold an agent project with data/ and agent.yaml $ kash init my-expert && cd my-expert # 3. Add raw documents (PDF · Markdown · TXT) $ cp ~/research/*.pdf data/ # 4. Compile into embedded vector (chromem), graph (cayley) & BM25 $ kash build ✓ Corpus profile measured: fold=latin, 8 ref patterns detected ✓ Chunked 42 documents (1,892 passages with citation breadcrumbs) ✓ Built pure-Go BM25 index (data/lexical.idx) ✓ Extracted 3,451 graph triples with evidential weighting # 5. Serve REST, MCP, A2A & the offline dashboard on one port $ kash serve 🚀 Live at http://localhost:8000 (OpenAI API, MCP, and Web UI)

Retrieval architecture

Retrieval That Actually Finds Things

Most RAG systems rely on cosine similarity and hope. Kash runs four independent retrieval routes simultaneously, fused by Reciprocal Rank Fusion (RRF k=60) with cascading reranking.

Simulate query

"ways to keep the write path from stalling under load"

Decompose: entities=[], concepts=["write path", "stall", "backpressure"]

Vector chromem-go

Semantic dense embeddings

Finds deep contextual meaning even when source documents use entirely different vocabulary.

Match: "the queue sheds load before the commit buffer saturates…"

BM25 pure-go

Exact keyword matching

Catches rare technical nouns, identifiers, and terms that vector models smooth away.

Match: "write path", "stall" (freq: 12)

Exact ref ref_patterns

Numbered verses & sections

Detects structural numbering patterns mined from your documents ("Section 4.2", "Clause 3(b)").

No explicit verse/clause identified in query

Graph cayley

Entity & triple traversal

Traverses relations 1–2 hops away and resolves directly to the source passage chunks.

Entity hit: "commit buffer" ↳ resolved to 3 chunks

Reciprocal Rank Fusion (RRF k=60) + bounded reranking

Candidates from all four routes are merged by ranked position. The top 100 enter the Cohere-compatible reranker cascade.

Recall@5: 1.00

vs 0.40 on vector-only RAG

Structure & provenance

A Graph You Can Mathematically Prove

No hallucinated citations, no blind character counts. Documents chunk along their heading hierarchies with structural breadcrumbs, and every graph fact points back to the exact passage it was extracted from.

Structure-Aware Chunking

Chunks split on Markdown and PDF headings, not arbitrary character boundaries. Each chunk receives a contextual breadcrumb header baked into its text at build time.

[Platform Handbook > Section 4.2 Data Retention > Clause 3]

"Records classified as operational telemetry are retained for 90 days, after which they are irreversibly purged from both primary and replica storage."

Numbered verses and legal clauses remain individually addressable
Table headers duplicate automatically across long table chunk splits
Text-quality gate rejects corrupt PDFs with font substitution ciphers

Audit with `kash verify`

Every triple stores its originating chunk ID. kash verify walks the graph, fetches chunks from vector storage, and confirms both endpoints are mentioned.

Facts audited2,202

Both endpoints verified in passage1,854 · 84.2%

One endpoint verified276 · 12.5%

Missing or fabricated citations0 · 0.0%

Overall passage grounding✓ 96.7% verifiable

Iterative gleaning extracts missed facts on dense texts
Evidential weights: log1p(weight) boost for multi-passage facts
Citations strictly cite [passage N] or the document alone — never faked

Domain profiling

Zero Domain Configuration

Stop hand-writing regular expressions. Kash measures your documents at build time and writes data/domain.profile.json. You only write configuration when you explicitly want an override.

            data/domain.profile.json
            ✓ Auto-generated by kash build
          
{
  "diacritics": {
    "mode": "latin",
    "evidence": "12,904 accented marks in 41/60 docs"
  },
  "title_stopwords": {
    "derived": ["appendix", "revision", "draft"],
    "count": 18
  },
  "structural_references": [
    { "prefix": "section",  "hits": 3209, "sequence": 0.94 },
    { "prefix": "clause",   "hits": 840,  "sequence": 0.97 },
    { "prefix": "figure",   "hits": 412,  "sequence": 0.88 }
  ],
  "extraction_vocabulary": {
    "predicates": ["owns", "depends_on", "supersedes", "defined_in"],
    "honorifics": ["dr. ", "prof. ", "eng. "]
  }
}

Why Kash 2.0

Collapse the RAG Infrastructure Tax

Typical RAG pipelines combine Python microservices, external vector servers, database clusters, and cloud orchestration. Kash collapses the entire stack into a single binary.

Capability	Traditional RAG stack	Kash 2.0
Runtime engine	Python 3.11 + FastAPI + LangChain + Celery	✓Single pure-Go binary (~25MB)
Vector database	Pinecone / Weaviate / Qdrant (recurring cost)	✓Embedded pure-Go `chromem-go`
Knowledge graph	Neo4j cluster with Cypher queries & JVM	✓Embedded pure-Go `cayley`
Keyword search	Elasticsearch / OpenSearch cluster	✓Embedded pure-Go BM25 (`data/lexical.idx`)
Retrieval fusion	Vector only, or ad-hoc custom Python scripts	✓4-route Reciprocal Rank Fusion (k=60)
Domain adaptation	Weeks of prompt tuning and hand-crafted regex	✓Auto-profiling (`data/domain.profile.json`)
Auditing & provenance	None — hallucinated citations accepted blindly	✓End-to-end audit with `kash verify`
Deployment artifact	Kubernetes Helm charts, 4 Docker images (>3GB)	✓One ~50MB Docker container

Three protocols & a UI

One Port. All Interfaces.

Serve queries to web apps, AI coding assistants, and multi-agent systems simultaneously on :8000 — plus an offline dashboard for live inspection.

OpenAI Drop-In Compatible

Exposes POST /v1/chat/completions. Any tool, library, or web UI that speaks OpenAI — Open WebUI, LibreChat, Vercel AI SDK, LangChain — works out of the box with your compiled brain.

GraphRAG passages automatically injected into system context
Supports stream: true SSE streaming
Secured by an optional AGENT_API_KEY bearer token

curl /v1/chat/completionsREST
$ curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -d '{
    "model": "kash-agent",
    "messages": [
      {
        "role": "user",
        "content": "What does Section 4.2 require for data retention?"
      }
    ],
    "stream": false
  }'

Model Context Protocol

Direct IDE and agent tool integration via GET /mcp. Connect Cursor, Claude Desktop, Windsurf, or custom agent swarms to your agent as a first-class knowledge tool.

Exposes query_knowledge with automatic prompt descriptions
SSE transport over HTTP on the same unified port
Tool schemas update automatically from the compiled corpus

claude_desktop_config.jsonMCP tool
{
  "mcpServers": {
    "kash-agent": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Agent-to-Agent RPC

Pure JSON-RPC 2.0 at POST /rpc/agent. Wire multiple specialized Kash containers together in AutoGen, CrewAI, or Swarm networks with structured queries and parameters.

Structured parameters with top_k and graph-depth overrides
Machine-readable fact provenance and citations
Standard JSON-RPC error codes and batching

curl /rpc/agentJSON-RPC 2.0
$ curl http://localhost:8000/rpc/agent \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "agent.query",
    "params": {
      "query": "Compare perspectives between chapter 3 and 7",
      "top_k": 8
    }
  }'

Built-in Zero-CDN Dashboard

Open http://localhost:8000/ in a browser. The single-page dashboard is baked into the Go binary via embed.FS, so it works completely offline inside isolated VPCs.

Books view — inspect indexed documents, chunks, and hashes
Graph explorer — force-directed visualizer for entity chains
Retrieval tester — view raw fused rankings before generation

GET / (browser UI)Embedded HTML5
<!-- Zero external CDN calls: 100% self-contained -->
Dashboard tabs:
  • 📚 Books            (manifest, chunk totals, status)
  • 🕸️ Knowledge graph  (interactive canvas)
  • 🔍 Retrieval tester (query breakdown)

Open in browser: http://localhost:8000

Command line interface

The Complete Kash CLI Suite

Seven focused commands to initialize, build, profile, audit, resolve, and deploy your agent containers.

kash init <name>Scaffold

Scaffolds a new agent project with a minimal agent.yaml override file, a data/ folder, and an optimized multi-arch Dockerfile.

Usage: kash init my-agent

kash buildCompiler

Measures the corpus, extracts triples, builds the vector store and BM25 index. Fully incremental and resumable via build.manifest.json.

--rebuild · discard DBs, rebuild from scratch

--prune · remove deleted documents

--refresh-profile · re-derive corpus profile

kash profileInspection

Inspects the derived domain profile, the evidence behind each measurement, and the active overrides in agent.yaml.

--dry-run · print without writing to disk

--refresh · re-derive over existing profile

--no-llm · lexical & regex measurements only

kash verifyAudit

Audits the provenance chain from graph facts back to text passages, reporting the share of facts verified against reader-visible sources.

--show <N> · examples to print per finding

--sample <N> · audit sample limit (0 = all)

kash resolve-entitiesGraph linker

Clusters spelling variants — diacritics, honorifics, stem vowels — to connect graph paths across transliterations.

--llm · LLM adjudication for edge cases

--min-degree <N> · minimum connection threshold

--show-all · list every clustered alias

kash serveRuntime

Starts unified HTTP serving: OpenAI REST API, MCP tool protocol, A2A JSON-RPC, and the embedded web dashboard.

--dir <path> · agent directory (default: .)

--agent <path> · agent.yaml location

kash versionInfo

Displays the current semantic version, the git commit hash, and the compiler build timestamp.

Usage: kash version

Ready to Ship Pure-Go AI Brains?

Build your first knowledge agent in minutes. No cloud vector database bills, no multi-container headache.

go install github.com/akashicode/kash/cmd/kash@latest

Explore on GitHub Read the v2.0 changelog

Compile Knowledge.Channel the Akashic.