NervaPack

NervaPack is a privacy-first, offline knowledge graph for your codebase. It solves two fundamental problems with standard Vector RAG:

• Token waste — chunk-based RAG retrieves blobs of text that may only tangentially relate to your query, bloating your context window.
• Privacy risk — sending code to cloud embedding APIs leaks your proprietary logic.

NervaPack runs 100% on your machine. It uses tree-sitter to parse your codebase into a deterministic Abstract Syntax Tree graph, then uses a local Ollama model to draw hard semantic edges between your documentation and your code. Queries traverse this graph with a K-Hop BFS, returning a hyper-targeted, token-efficient context window — no cloud required.

Verified Performance

91.2% Average Token Reduction — independently verified on real-world codebases.

Cost Savings: $181–$724 per developer per year (GPT-4o to Claude Sonnet)

📊 View Full Benchmarks · 🧪 Messy Code Performance

Code quality impact: 90–99% reduction on clean code, 50–75% on legacy/messy code. Even poorly structured codebases benefit significantly.

Why NervaPack vs. standard Vector RAG

Prerequisites

• Python 3.10+
• Git — your project must be a git repository (git init if not)

(Optional for semantic code-doc binding) — an LLM provider. Structural graph indexing and basic queries work out-of-the-box with zero configuration and no cloud connection.

Installation

# Recommended
pip install nervapack

# With optional features
pip install "nervapack[mcp]"          # MCP server for Claude Code / Cursor
pip install "nervapack[memory]"       # agent memory MCP server
pip install "nervapack[metrics]"      # exact token counts (tiktoken)
pip install "nervapack[dashboard]"    # web dashboard (streamlit + plotly)
pip install "nervapack[claude]"       # Claude API support
pip install "nervapack[openai]"       # OpenAI API support
pip install "nervapack[all]"          # everything

On first run, ChromaDB downloads an ONNX embedding model (~30 MB) to ~/.cache/chroma/. This is a one-time download.

Quick Start

cd your-project/

# 1. Build the knowledge graph (runs locally, no LLM required for basic use)
nervapack ingest .

# 2. Query for context — get focused results + token savings dashboard
nervapack query "How does authentication work?"

# 3. Add semantic doc-to-code edges (requires an LLM)
nervapack enrich .

# 4. Visualize the full graph
nervapack visualize --enhanced --communities

# 5. After changing files, sync incrementally (fast — only changed files)
nervapack sync .

# 6. If you ingested wrong data or need a fresh start
nervapack clean --all
nervapack ingest .

# 7. Check system health
nervapack doctor

Command Reference

nervapack ingest [PATH] — Build the graph

Scans PATH (default: .) and builds the full knowledge graph.

What happens:

1. Walks the directory tree with tree-sitter, skipping dist/, build/, node_modules/, venv/, site/, .tox/, and dozens of other build directories automatically.
2. Parses source files into exact AST nodes: classes, functions, imports.
3. Chunks all .md files by header hierarchy.
4. Embeds every entity into a local ChromaDB vector store (ONNX by default, Ollama optional).
5. Optionally binds doc chunks to code nodes via an LLM, adding EXPLAINS edges.
6. Saves the graph once to .nervapack/graph.graphml.

Re-ingesting is safe — upsert is used throughout, so running ingest twice does not duplicate data.

nervapack ingest .                           # auto-detect LLM
nervapack ingest . --llm ollama              # force Ollama
nervapack ingest . --llm claude              # use Claude API
nervapack ingest . --llm openai --model gpt-4o-mini
nervapack ingest . --embeddings ollama       # use Ollama for embeddings too

Supported languages (bundled): Python, JavaScript, JSX, TypeScript, TSX

Additional languages:

pip install "nervapack[go]"            # Go
pip install "nervapack[rust]"          # Rust
pip install "nervapack[java]"          # Java
pip install "nervapack[c]"             # C / C headers
pip install "nervapack[cpp]"           # C++
pip install "nervapack[ruby]"          # Ruby
pip install "nervapack[csharp]"        # C#
pip install "nervapack[all-languages]" # all of the above

Exclude directories — create .nervapackignore in your project root (gitignore syntax):

dist/
build/
site/
generated/
*.egg-info/

nervapack query PROMPT — Query the graph

Retrieves focused context for a natural-language prompt and prints a token savings dashboard.

What happens:

1. Intent detection — "what breaks if I change X" routes to impact analysis (reverse BFS); exact symbol names bypass vector search.
2. ChromaDB returns the top-3 most semantically similar nodes.
3. Those nodes seed a K-Hop BFS through the NetworkX graph (default: 1 hop, both directions).
4. Adjacent nodes — including any markdown docs via EXPLAINS edges and memory notes via TOUCHES edges — are collected.
5. A focused Markdown context block is printed, ready to paste into an LLM prompt.
6. Token efficiency panel shows savings vs. naive "dump the whole file" RAG.

nervapack query "How does authentication work?"
nervapack query "What calls VectorStore?"
nervapack query "what breaks if I change GraphBuilder"  # impact analysis

Example output:

Query: "How does authentication work?"

Query Router: Intent: semantic, Direction: both
Vector Search: Found 3 seed nodes

Retrieved Context:
──────────────────────────────────────────────────────────
# NervaPack Context Retrieval
## File: `src/auth/middleware.py`
### CLASS: AuthMiddleware (L15-L42)
...
──────────────────────────────────────────────────────────

╭──────────────  NervaPack Token Efficiency  ──────────────╮
│  Strategy              Tokens   Reduction                 │
│  Naive RAG (3 files)   12,840   100% (base)              │
│  NervaPack              1,180     9.2%                    │
│ ─────────────────────────────────────────────────────────│
│  Tokens saved: 11,660   Reduction: 90.8%                 │
│  Cost saved (GPT-4o $2.50/1M): $0.0292 per query         │
╰───────────────────────────────────────────────────────────╯

nervapack sync [PATH] — Incremental update

Updates only the files that changed since the last ingest. Uses GitPython to diff the working tree.

nervapack sync .

A full ingest on a large project can take minutes. sync turns that into a 2–5 second surgical update per file. Re-parses changed files, batch-upserts new vectors, and saves the graph once at the end.

nervapack clean [OPTIONS] — Remove ingested data

Wipe graph data and start fresh. Use this when you have duplicate vectors, ingested the wrong directory, or need to reduce disk usage.

nervapack clean --vectors          # wipe ChromaDB only (chroma_db/)
nervapack clean --graph            # delete graph.graphml only
nervapack clean --history          # clear query + graph history logs
nervapack clean --all              # everything above (keeps memory.db)
nervapack clean --all --yes        # skip confirmation (CI / scripts)

Never deleted by clean: memory.db — your agent memory is always safe.

Typical workflow after a bad ingest:

nervapack clean --all
nervapack ingest .

nervapack enrich [PATH] — Add semantic edges