Open Source AI · Developer Tooling
NervaPack
91.2% average token reduction and 96% recall on SWE-bench Lite — a 100% local, AST-aware knowledge graph and bi-temporal memory engine for AI coding agents.
Customer
Developers, AI/ML Engineers, Tech Leads, Engineering Managers, and Security-Conscious Enterprises
Timeline
2026 · Active Open Source
Status
Published on PyPI & Read the Docs
Capability
Stack
Outcome
Customer Context
Who they are and what world they live in
As codebases grow, pasting full repository dumps or relying on naive text-chunk RAG floods LLM context windows with 50,000+ tokens of noise, causing high API costs ($700+/dev/year) and lost accuracy. Developers and security-conscious teams need a local-first system that retains structural understanding of code entities and persists architectural decisions across sessions without sending code to cloud services.
The Problem
The fuzzy ask, translated
Naive RAG splits files into arbitrary text windows, losing critical software structure (which class calls what, which function imports what module, which docs explain which feature). Furthermore, AI agents lack persistent project memory — forgetting past design decisions and architectural trade-offs between prompt sessions. NervaPack solves both by pairing AST-driven structural graphs with bi-temporal project memory.
The Constraints
Time · Budget · Regulatory · Technical · Organizational
100% local, offline operation: 0 KB cloud data transmission — all AST parsing, vector search (ChromaDB ONNX), and SQLite FTS5 memory stay on dev machines
Deterministic structural precision: Tree-sitter AST parsing creates explicit CALLS, IMPORTS, EXPLAINS, and TOUCHES graph edges across Python, TS/JS, Go, Rust, C++, and Java
Bi-temporal memory integrity: facts, decisions, and procedures track valid_from, valid_until, and recorded_at timestamps so superseded decisions are preserved for auditability
Sub-200 token memory recall: loads 30 days of project decision history in ~170 tokens
Dual MCP server protocol compliance: 20 MCP tools exposed via nervapack-mcp (code graph) and nervapack-memory-mcp (bi-temporal memory) for Claude Code, Cursor, and Windsurf
Architecture Decisions
What I chose. What I rejected. Why.
Code retrieval model
Chosen
K-hop BFS graph traversal over Tree-sitter AST entities
Rejected
Naive semantic chunk RAG / full-pack text dumps (Repomix/Aider)
Why
Code questions depend on relationships (callers, callees, imports, explanations). K-hop traversal pulls only 5–15 structurally relevant nodes (2,459 tokens avg vs 52,037 tokens naive RAG), delivering 91.2% token savings with 96% recall on SWE-bench Lite.
Persistent agent memory
Chosen
Bi-temporal memory model backed by SQLite FTS5 and ONNX vector embeddings
Rejected
Single flat key-value store / ephemeral conversation buffer
Why
Software decisions evolve. Bi-temporal attributes (valid_from, valid_until, recorded_at) allow agents to update current policy while keeping historical context intact, enabling line-level TOUCHES links between code changes and original design rationale.
Agent integration interface
Chosen
Dual MCP Server Suite (nervapack-mcp & nervapack-memory-mcp) with 20 total tools
Rejected
Custom IDE extension per editor
Why
Model Context Protocol (MCP) provides zero-friction native compatibility with Claude Code, Cursor, Windsurf, and VS Code through a single .mcp.json configuration file.
Operational developer loop
Chosen
Fast CLI with 2–5s incremental git-diff sync and HTML graph visualization
Rejected
Full re-indexing on every code edit
Why
Developers demand fast feedback. Git-diff sync inspects modified files and updates affected graph slices in 2–5 seconds without locking the codebase.
The Hard Problem
The one thing that almost broke the deployment
Balancing context precision against retrieval latency without cloud GPU dependencies. Naive graph databases require complex setup, while pure vector embeddings hallucinate code connections. Connecting line-level code entities directly to project decision facts (TOUCHES edges) required a lightweight, deterministic bridge between tree-sitter AST offsets and SQLite FTS5 records.
The Fix
Created an integrated 4-module engine: (1) Tree-sitter parser generates AST nodes and hard edges; (2) SQLite FTS5 + local ONNX embedding index stores bi-temporal memory; (3) Line-level TOUCHES edges bridge memory directly to code entities; (4) K-hop BFS retriever isolates exact 5–15 node subgraphs for prompt injection. Verified on SWE-bench Lite with 96% recall and 4.5x fewer tokens than Aider.
Production Reality
What I had to fix in week 2
Large repositories contain thousands of doc-to-code links and decision records. Full re-indexing choked dev workflows. The incremental git-diff sync engine solved this by computing diff patches and updating only modified node neighborhoods in 2–5 seconds, keeping the graph live during active coding.
Lessons Carried Forward
What this taught me that I apply to every deployment
Code RAG must be AST-aware — text chunks destroy call hierarchies and import graphs
Bi-temporal tracking prevents agent context pollution when architectural decisions change over time
Sub-200 token recall makes persistent memory practical for every prompt session
Dual MCP server partitioning (Code Graph vs Memory) keeps tool definitions clean for AI clients
Published documentation on Read the Docs provides developers instant onboarding and API transparency
Related Deployments