NervaPack

NervaPack

NervaPack 是一款以隐私为先、离线运行的代码库知识图谱工具。它解决了标准向量 RAG 的两个根本问题：

• Token 浪费——基于分块的 RAG 会检索可能仅与查询略有关联的大段文本，导致上下文窗口膨胀。
• 隐私风险——将代码发送到云端嵌入 API 会泄露专有逻辑。

NervaPack 100% 在你的机器上运行。它使用 tree-sitter 将代码库解析为确定性抽象语法树图，然后使用本地 Ollama 模型在文档与代码之间建立明确的语义边。查询通过 K 跳 BFS 遍历此图，返回高度精准且节省 Token 的上下文窗口，无需连接云端。

---

经验证的性能

平均减少 91.2% 的 Token 用量——已在真实代码库上通过独立验证。

测试类型	Token（朴素方案）	Token（NervaPack）	减少比例
简单查询	10,926	101	99.1%
中等查询	13,092	164	98.7%
复杂查询	3,290	1,102	66.5%
平均值	52,037	2,459	91.2%

**成本节省：**每位开发者每年 $181–$724（GPT-4o 至 Claude Sonnet）

📊 查看完整基准测试 · 🧪 杂乱代码性能

**代码质量的影响：**整洁代码可减少 90–99%，遗留／杂乱代码可减少 50–75%。即使代码结构较差，也能显著受益。

---

NervaPack 与标准向量 RAG 的对比

	标准向量 RAG	NervaPack
解析	任意文本块	确定性 AST 节点（类、函数、导入）
检索	最近邻文本块	在结构图上执行 K 跳 BFS
文档 ↔ 代码链接	无	由本地 LLM 建立明确的 EXPLAINS 边
隐私	云端嵌入	100% 本地（ChromaDB + ONNX + 可选 Ollama）
增量同步	重新索引所有内容	通过 GitPython diff 按文件精准更新
Token 节省	无测量	内置仪表板显示每次查询的精确减少量
图可视化	黑盒	以交互式 HTML 可视化每个节点和边
防重复	重复导入 = 重复数据	upsert — 重新导入具有幂等性
Agent 记忆	无	用于跨会话记忆的 17 工具 MCP 服务

---

前置条件

• Python 3.10+
• Git——你的项目必须是 Git 仓库（如不是，请运行 git init）

（语义代码与文档关联为可选功能）——需要 LLM 提供方。结构图索引和基本查询开箱即用，无需任何配置，也无需连接云端。

提供方	设置	费用	隐私
Ollama（默认）	brew install ollama && ollama pull llama3	免费	100% 本地
Claude API	pip install "nervapack[claude]" + ANTHROPIC_API_KEY	约 $0.25/1k 次调用	云端
OpenAI API	pip install "nervapack[openai]" + OPENAI_API_KEY	约 $0.15/1k 次调用	云端
MCP (Claude Code)	无需配置	包含在订阅中	云端

---

安装

# 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

首次运行时，ChromaDB 会将 ONNX 嵌入模型（约 30 MB）下载到 ~/.cache/chroma/。这只需下载一次。

---

快速开始

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

---

命令参考

nervapack ingest [PATH] — 构建图

扫描 PATH（默认值：.）并构建完整的知识图谱。

执行内容：

1. 使用 tree-sitter 遍历目录树，并自动跳过 dist/、build/、node_modules/、venv/、site/、.tox/ 及其他数十种构建目录。
2. 将源文件解析为精确的 AST 节点：类、函数、导入项。
3. 按标题层级对所有 .md 文件分块。
4. 将每个实体嵌入本地 ChromaDB 向量存储（默认使用 ONNX，也可选用 Ollama）。
5. 可选地使用大模型将文档块绑定到代码节点，并添加 EXPLAINS 边。
6. 将图一次性保存到 .nervapack/graph.graphml。

重新摄取是安全的——全程使用 upsert，因此运行两次 ingest 不会产生重复数据。

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

支持的语言（内置）： Python、JavaScript、JSX、TypeScript、TSX

其他语言：

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

排除目录——在项目根目录中创建 .nervapackignore（采用 gitignore 语法）：

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

---

nervapack query PROMPT — 查询图

针对自然语言提示词检索相关上下文，并输出 Token 节省情况面板。

执行内容：

1. 意图检测——“更改 X 会导致什么问题”会转到影响分析（反向 BFS）；精确的符号名称则会跳过向量搜索。
2. ChromaDB 返回语义相似度最高的 3 个节点。
3. 这些节点作为种子，在 NetworkX 图中执行 K-Hop BFS（默认：1 跳，双向）。
4. 收集相邻节点，包括通过 EXPLAINS 边连接的 Markdown 文档和通过 TOUCHES 边连接的记忆笔记。
5. 输出一段简明的 Markdown 上下文，可直接粘贴到大模型提示词中。
6. Token 效率面板显示相较于朴素的“转储整个文件”式 RAG 节省的 Token。

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

输出示例：

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] — 增量更新

仅更新自上次摄取以来发生更改的文件。使用 GitPython 比较工作树的差异。

nervapack sync .

大型项目的完整摄取可能需要几分钟。sync 可将其变为针对每个文件 2–5 秒的精准更新。它会重新解析更改的文件，批量更新新向量，并在最后一次性保存图。

---

nervapack clean [OPTIONS] — 移除已摄取的数据

清除图数据并重新开始。如果存在重复向量、摄取了错误的目录，或需要减少磁盘占用，请使用此命令。

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)

clean 永远不会删除： memory.db——你的 Agent 记忆始终安全。

摄取错误后的典型工作流：

nervapack clean --all
nervapack ingest .

---

nervapack enrich [PATH] — 添加语义边

对已摄取的图运行大模型文档到代码的绑定。如果你：

• 运行 ingest 时未使用大模型，现在想添加 EXPLAINS 边。
• 添加了新文档，想要绑定它们而无需重新完整摄取。

nervapack enrich .                           # auto-detect LLM
nervapack enrich . --llm ollama --model llama3
nervapack enrich . --llm claude              # shows cost estimate before proceeding

---

nervapack status [--detailed] — 图的健康状况

nervapack status            # node/edge counts + unsynced files
nervapack status --detailed # full analytics: health score, language distribution, coverage

健康评分（0–100）综合考虑文档覆盖率、节点连通性、图密度和边的多样性。仅包含结构信息的图通常得分为 30–40；运行 enrich 后，分数会升至 70–90。

---

nervapack visualize [OPTIONS] — 交互式 HTML 图

nervapack visualize                           # basic visualization
nervapack visualize --enhanced                # + real-time search + path finder
nervapack visualize --enhanced --communities  # + community detection (Louvain)
nervapack visualize --output ~/my-graph.html  # custom output path
nervapack visualize --no-browser              # generate without opening

生成独立的 HTML 文件，无需外部依赖——可拖动、缩放、搜索，也可查找节点间的最短路径。

---

nervapack explore TARGET [--hops N] — 定向子图

提取并可视化特定文件、类或函数的 N 跳邻域。

nervapack explore GraphBuilder --hops 2
nervapack explore src/auth/middleware.py --hops 1
nervapack explore "function:parse"

---

nervapack dependencies [FILE] — 导入依赖分析

分析文件级导入链，检测循环依赖，并可视化依赖图。

nervapack dependencies                        # full project analysis
nervapack dependencies src/graph/builder.py   # single file
nervapack dependencies --no-cycles            # skip cycle detection

---

nervapack hotspots [OPTIONS] — 更改频率分析

显示 Git 历史中更改最频繁的文件——这些文件是文档编写和审查的首选目标。

nervapack hotspots                            # top 20 by commit count
nervapack hotspots --since "6 months ago"    # recent history only
nervapack hotspots --ext .py --churn         # Python files, sort by lines changed

---

nervapack history [OPTIONS] — 查询历史记录

nervapack history              # last 10 queries with token savings
nervapack history --limit 50   # last 50
nervapack history --stats      # aggregate: total savings, cost avoided, top topics
nervapack history --clear      # delete history

---

nervapack serve [--port N] — Web 仪表板

nervapack serve                # http://localhost:8501
nervapack serve --port 8080    # custom port

需要 nervapack[dashboard]。显示图谱概览、语言分布、分析数据、查询历史趋势和交互式图谱浏览器。

---

nervapack doctor — 环境检查

nervapack doctor

验证 Python 版本、tree-sitter 语法、嵌入后端、Ollama 连通性和 MCP 配置。安装后或排查问题时运行此命令。

---

存储布局

所有内容都存放在项目根目录下的 .nervapack/ 中：

.nervapack/
├── graph.graphml          # NetworkX DiGraph (AST + EXPLAINS edges)
├── chroma_db/             # ChromaDB vector store (ONNX embeddings)
├── memory.db              # Agent memory (SQLite + FTS5, bi-temporal)
├── query_history.jsonl    # Per-query token savings log
└── graph_history.jsonl    # Ingest/sync event log

将 .nervapack/ 添加到 .gitignore，使其不纳入版本控制。

磁盘使用指南：

• chroma_db/ — 通常为 10–100 MB，具体取决于项目大小。如果占用意外增长，请运行 nervapack clean --vectors && nervapack ingest .。
• graph.graphml — 通常为 0.5–5 MB。
• memory.db — 随 Agent 使用而增长；很少超过几 MB。

---

MCP 集成（Claude Code、Cursor、Windsurf）

NervaPack 在同一个包中提供两个 MCP 服务。将此 .mcp.json 放在项目根目录中：

{
  "mcpServers": {
    "nervapack": {
      "command": "nervapack-mcp",
      "description": "NervaPack knowledge graph (v0.6.1) — query, graph_status, explore, impact"
    },
    "nervapack-memory": {
      "command": "nervapack-memory-mcp",
      "description": "NervaPack agent memory (v0.6.1) — store, recall, and reason over facts across sessions"
    }
  }
}

知识图谱 MCP 工具（nervapack-mcp）

工具	功能
query	向量搜索 → K-Hop BFS → 精简的 Markdown 上下文 + Token 节省量
graph_status	节点/边数量、语言分布、未同步文件警告
explore	浏览所有已索引的类、函数、导入和 Markdown 文档
impact	反向依赖分析——查找依赖指定实体的内容

Agent Memory MCP 工具（nervapack-memory-mcp）——17 个工具

工具	用途
memory_start_session	开启一个命名会话
memory_store	保存事实、决策、结果、流程、偏好或操作
memory_recall	FTS5 搜索 → 图谱扩展 → 评分后、受预算限制的回忆
memory_about	实体档案：与一个实体关联的所有事实/决策
memory_why	解释某项决策：理由、被否决的替代方案和结果
memory_timeline	按时间顺序追踪，包含已被取代的版本
memory_end_session	以结果摘要结束会话
memory_forget	软删除或彻底清除节点
memory_verify	确认（置信度 +0.1）或驳回（关闭 + 置信度 ×0.5）
memory_stats	节点数量、数据库大小、热门实体和所有命名空间
memory_list_sessions	列出所有会话及节点数量
memory_clear_session	删除一个会话及其所有节点
memory_for_code	与源文件或指定行关联的记忆
memory_to_code	记忆节点关联的代码位置
memory_import	从 JSON 数组批量导入初始记忆
memory_switch_namespace	切换当前命名空间
memory_verify_staleness	标记自保存后源文件已更改的记忆

CLAUDE.md 模板

将以下内容添加到 CLAUDE.md，使 NervaPack 接入每次 Claude Code 会话：

## Always use NervaPack MCP tools

At the start of every session:
1. Call `memory_start_session("<task name>")` to open a named session.
2. Call `memory_recall("project context", budget_tokens=400)` to load prior decisions.
3. Call `query("<topic>")` before answering any question about how the code works.

During the session — call `memory_store` for:
- Any decision made (kind="decision" with rationale and alternatives_rejected)
- Any fact discovered about system behaviour (kind="fact")
- Any procedure or convention established (kind="procedure")

At session end — call `memory_end_session("<one-paragraph summary>")`.

---

架构

nervapack ingest .
       │
       ├─ ASTParser (tree-sitter)               16 extensions, 10 languages
       │    └─ ParsedEntity[]: class, function, import
       │
       ├─ GraphBuilder (NetworkX DiGraph)
       │    ├─ Nodes: file, class, function, import, markdown
       │    ├─ Edges: DEFINES (AST, confidence=1.0)
       │    ├─ Edges: REFERENCES (heuristic name overlap, confidence=0.7)
       │    └─ Edges: EXPLAINS (LLM or keyword binding, confidence=0.5–0.9)
       │
       ├─ VectorStore (ChromaDB)
       │    ├─ Embedding: ONNX (default) or Ollama
       │    └─ upsert — re-ingest is idempotent
       │
       └─ GraphHistory  — snapshot recorded after each ingest/sync

nervapack query "..."
       │
       ├─ Intent detection (impact / exact / semantic)
       ├─ VectorStore.search() → seed node IDs
       ├─ GraphRetriever.retrieve_context()
       │    └─ deque BFS, direction: forward / reverse / both
       ├─ MemoryStore.get_touches_for_file() → memory context injection
       └─ TokenMeter → savings vs. naive RAG

nervapack clean --all
       └─ Deletes chroma_db/, graph.graphml, history logs
          Never touches memory.db

主要源代码模块：

模块	职责
nervapack.parser.ast_parser	tree-sitter 解析 → ParsedEntity；共享的单例解析器实例
nervapack.parser.md_chunker	Markdown → 按标题分隔的分块；从 os.walk 中排除构建目录
nervapack.graph.builder	NetworkX DiGraph；用于同步的 O(1) 文件索引；为 REFERENCES 编译正则表达式
nervapack.graph.vector_store	ChromaDB upsert（幂等）；可插拔的嵌入函数
nervapack.graph.retrieval	使用 deque 的 K-Hop BFS（O(n)，而非 O(n²)）
nervapack.graph.token_meter	tiktoken 单例；Token 节省量面板
nervapack.graph.query_history	尾部读取 JSONL — O(limit)，而非 O(total)
nervapack.graph.analytics	批量调用 graph.degree() — 单次调用，而非逐节点循环
nervapack.llm.base	使用关键字预筛选的 bind_docs_to_ast（前 12 个候选项）
nervapack.llm.providers.ollama	ollama.list() 缓存 60 s
nervapack.memory.store	SQLite + FTS5；双时态；用于 O(1) 跳扩展的 batch_neighbors
nervapack.memory.recall	批量跳扩展；召回时记录审计跟踪
nervapack.mcp_server	FastMCP — query、graph_status、explore、impact
nervapack.memory.mcp_server	FastMCP — 17 个记忆工具

---

nervapack.memory — Agent 记忆

不必再在每次新聊天中重复粘贴项目上下文。

# Store a decision
memory_store(
    "Chose JWT over session cookies for auth_service — stateless horizontal scaling",
    kind="decision",
    entities=["auth_service"],
    confidence=0.9,
    rationale="Stateless tokens enable horizontal scaling without shared session store.",
    alternatives_rejected=["server-side sessions", "PASETO"],
)

# Recall in any future session
memory_recall("project context", budget_tokens=400)

## Memory recall: "project context" (6 items · 171/400 tokens)

### Decisions
- [d_0019f2] 2026-06-05 · conf 0.90 — Chose JWT for auth_service

### Facts
- [f_0019f3] 2026-06-05 · conf 1.00 — auth_service issues 15-min access tokens

### Procedures
- [p_0019f5] 2026-06-12 · conf 1.00 — Deploy: GitHub Actions → staging → prod manual

Token 效率：

方式	每个会话的 Token 数	20 个会话后
手动粘贴（架构文档）	~2,400	~48,000
memory_recall	~171	~3,420
节省		减少 93% 的 Token

命令行：

nervapack-memory init                          # create schema
nervapack-memory stats                         # counts + top entities
nervapack-memory search "JWT auth"             # FTS search
nervapack-memory timeline "auth service"       # chronological trace
nervapack-memory audit d_0019f2abc             # access audit trail
nervapack-memory rebind old/path.py new/path.py  # update file links after rename
nervapack-memory export --out dump.json        # JSON dump

**数据模型：**8 种节点类型、7 种边类型、双时态（valid_from/valid_until），默认情况下从不硬删除。

---

隐私

NervaPack 默认完全离线运行：

• 嵌入使用 ChromaDB 内置的 ONNX 模型（在 CPU 上运行，无需云服务）。
• LLM 调用（使用 Ollama 时）仅发送到 localhost:11434。
• 所有图数据和向量数据都存储在项目内的 .nervapack/ 中。
• 运行时不会收集遥测数据、进行分析或发起网络调用。

只有在你明确传入 --llm claude 或 --llm openai 时，代码才会离开你的计算机。

---

贡献

1. Fork 仓库并创建分支。
2. 运行测试：python3 -m pytest tests/memory/ -q
3. 检查文档：python3 -m mkdocs build --strict
4. 向 master 提交拉取请求。

错误报告和功能请求：问题跟踪器。

---

许可证

MIT — 详见 LICENSE。