NervaPack

NervaPack

NervaPack は、コードベース向けのプライバシー優先型オフライン知識グラフです。標準的なベクトル RAG が抱える2つの根本的な問題を解決します。

• トークンの無駄 — チャンクベースの RAG は、クエリとわずかにしか関連しないテキストの塊を取得することがあり、コンテキストウィンドウを圧迫します。
• プライバシーのリスク — コードをクラウドの埋め込み API に送信すると、独自のロジックが漏えいします。

NervaPack はすべての処理をお使いのマシン上で実行します。tree-sitter を使ってコードベースを決定論的な抽象構文木（AST）グラフに解析し、ローカルの Ollama モデルを使って、ドキュメントとコードの間に明確な意味的エッジを作成します。クエリは K-Hop BFS でこのグラフをたどり、非常に的を絞ったトークン効率の高いコンテキストウィンドウを返します。クラウドは不要です。

---

検証済みのパフォーマンス

平均トークン削減率 91.2% — 実際のコードベースで独立した検証を実施済みです。

テスト種別	トークン数（単純方式）	トークン数（NervaPack）	削減率
簡単なクエリ	10,926	101	99.1%
中程度のクエリ	13,092	164	98.7%
複雑なクエリ	3,290	1,102	66.5%
平均	52,037	2,459	91.2%

コスト削減額： 開発者1人あたり年間$181～$724（GPT-4oからClaude Sonnetまで）

📊 ベンチマークの全結果を見る · 🧪 乱雑なコードでのパフォーマンス

コード品質への影響： 整ったコードでは90～99%、レガシーコードや乱雑なコードでは50～75%削減します。構造が整っていないコードベースでも大きな効果があります。

---

標準的なベクトル RAGとNervaPackの比較

	標準的なベクトル RAG	NervaPack
解析	任意のテキストチャンク	決定論的な AST ノード（クラス、関数、インポート）
検索	最近傍のテキスト塊	構造グラフ上の K-Hop BFS
ドキュメント ↔ コードのリンク	なし	ローカル LLM が作成する明確な EXPLAINS エッジ
プライバシー	クラウド埋め込み	すべてローカル（ChromaDB + ONNX + Ollama は任意）
増分同期	すべて再インデックス	GitPython の差分によるファイル単位のピンポイント更新
トークン削減	測定なし	クエリごとの正確な削減率を示す組み込みダッシュボード
グラフの可視性	ブラックボックス	すべてのノードとエッジを表示するインタラクティブな HTML 可視化
重複防止	繰り返し取り込むとデータが重複	upsert — 再取り込みは冪等
エージェントのメモリ	なし	セッションをまたぐメモリに対応した17ツールの MCP サーバー

---

前提条件

• Python 3.10+
• Git — プロジェクトは Git リポジトリである必要があります（そうでない場合は git init を実行してください）

（意味的なコードとドキュメントの紐付けに必要な場合のみ） — LLM プロバイダー。構造グラフのインデックス作成と基本的なクエリは、設定不要かつクラウド接続なしでそのまま動作します。

プロバイダー	セットアップ	コスト	プライバシー
Ollama（デフォルト）	brew install ollama && ollama pull llama3	無料	すべてローカル
Claude API	pip install "nervapack[claude]" + ANTHROPIC_API_KEY	呼び出し1,000回あたり約$0.25	クラウド
OpenAI API	pip install "nervapack[openai]" + OPENAI_API_KEY	呼び出し1,000回あたり約$0.15	クラウド
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. オプションで LLM を使ってドキュメントのチャンクをコードノードに結び付け、EXPLAINS エッジを追加します。
6. グラフを .nervapack/graph.graphml に一度だけ保存します。

再取り込みは安全です — 全体で upsert を使用しているため、ingest を 2 回実行してもデータは重複しません。

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 — グラフにクエリ

自然言語のプロンプトに対して関連性の高いコンテキストを取得し、トークン削減のダッシュボードを表示します。

実行内容：

1. 意図を検出します — 「X を変更したら何が壊れるか」は影響分析（逆方向 BFS）に振り分けられ、正確なシンボル名の場合はベクトル検索をスキップします。
2. ChromaDB が意味的に最も類似する上位 3 件のノードを返します。
3. それらのノードを起点として、NetworkX グラフ内を K-hop BFS で探索します（デフォルト：1 ホップ、両方向）。
4. EXPLAINS エッジで関連付けられた Markdown ドキュメントや、TOUCHES エッジで関連付けられたメモリーノートを含む、隣接ノードを収集します。
5. LLM のプロンプトに貼り付けられる、対象を絞った Markdown コンテキストブロックを表示します。
6. トークン効率パネルに、単純に「ファイル全体を出力する」RAG と比べた削減量を表示します。

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 秒で実行できます。変更されたファイルを再解析し、新しいベクトルを一括で upsert して、最後にグラフを一度だけ保存します。

---

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 — エージェントのメモリーは常に安全です。

取り込みに失敗した後の一般的なワークフロー：

nervapack clean --all
nervapack ingest .

---

nervapack enrich [PATH] — セマンティックエッジを追加

取り込み済みのグラフに対して、LLM によるドキュメントとコードの結び付けを実行します。次の場合に使用します。

• LLM なしで 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 — エージェントの使用に伴って増加しますが、数 MB を超えることはほとんどありません。

---

MCP 連携（Claude Code、Cursor、Windsurf）

NervaPack には、同じパッケージ内に 2 つの 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 コンテキストとトークン節約
graph_status	ノード／エッジ数、言語の内訳、同期されていないファイルの警告
explore	インデックス化されたすべてのクラス、関数、インポート、Markdown ドキュメントを閲覧
impact	依存関係を逆方向に分析し、指定したエンティティに依存するものを特定

エージェントメモリ 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	ノード数、DB サイズ、上位エンティティ、すべての名前空間
memory_list_sessions	ノード数とともにすべてのセッションを一覧表示
memory_clear_session	セッションとそのすべてのノードを削除
memory_for_code	ソースファイルまたは特定の行に関連するメモリ
memory_to_code	メモリノードに関連するコードの場所
memory_import	JSON 配列からメモリを一括登録
memory_switch_namespace	アクティブな名前空間を切り替え
memory_verify_staleness	保存後にソースファイルが変更されたメモリにフラグを付与

CLAUDE.md テンプレート

すべての Claude Code セッションで NervaPack を利用できるようにするには、CLAUDE.md に追加してください。

## 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 シングルトン、トークン節約パネル
nervapack.graph.query_history	JSONL の末尾読み込み — O(total) ではなく O(limit)
nervapack.graph.analytics	graph.degree() の一括処理 — ノードごとのループではなく単一呼び出し
nervapack.llm.base	キーワードによる事前フィルタリング（上位 12 件の候補）を備えた bind_docs_to_ast
nervapack.llm.providers.ollama	ollama.list() を 60 秒間キャッシュ
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 — エージェントメモリ

新しいチャットを始めるたびに、プロジェクトのコンテキストを貼り直す必要はありません。

# 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

トークン効率：

方法	セッションあたりのトークン数	20 セッション後
手動で貼り付け（アーキテクチャドキュメント）	~2,400	~48,000
memory_recall	~171	~3,420
節約量		トークン数を 93% 削減

CLI：

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. リポジトリをフォークし、ブランチを作成します。
2. テストを実行します：python3 -m pytest tests/memory/ -q
3. ドキュメントのチェックを実行します：python3 -m mkdocs build --strict
4. master に対してプルリクエストを作成します。

バグ報告と機能リクエスト：issue tracker。

---

ライセンス

MIT — LICENSE を参照してください。