code-memory

code-memory

Model Context Protocol (MCP) サーバーとして提供される、決定論的で高精度なコードインテリジェンスレイヤーです。

• テレメトリーなし — コードがマシンの外部に送信されることはありません
• API キー不要 — sentence-transformers を使用して完全にローカルで動作します
• セットアップは 1 分 — uvx code-memory を実行するだけですぐに使えます
• トークンを 50% 節約 — ファイル全体をダンプする代わりに、コードを正確に取得します

このプロジェクトを気に入ったら、ぜひ code-memory にスターを付けてください！

code-memory を使う理由

大規模なコードベースから適切なコンテキストを見つけるのは、コストがかかり、不正確で、コンテキストウィンドウの制限を受けます。ファイルをプロンプトにダンプするとトークンが無駄になり、コンテキストが埋まるにつれて LLM は実際のタスクを見失います。

grep／find で手作業で探したり、生のファイルテキストをダンプしたりする代わりに、code-memory はローカルにインデックス化されたコードベースを対象にセマンティック検索を実行します。claude-context に着想を得ていますが、大規模なローカル検索向けに一から設計されています。

対応言語

AST を完全サポート（シンボル抽出を伴う構造解析）：Python、JavaScript/TypeScript、Java、Go、Rust、C/C++、Ruby、Kotlin

フォールバックサポート（ファイル全体のインデックス化）：C#、Swift、Scala、Lua、Shell、Config（yaml/toml/json）、Web（html/css）、SQL、Markdown

.gitignore パターンに一致するファイルは自動的にスキップされます。

アーキテクチャ：段階的な情報開示

単一のモノリシックな検索ではなく、code-memory はクエリを目的別に設計された3 つのツールに振り分けます。

質問の種類	ツール	データソース
「どこ／何／どうやって？」 — 定義、参照、構造、セマンティック検索を探す	search_code	BM25 + Dense Vector（SQLite vec）
「アーキテクチャ／パターン」 — アーキテクチャを理解し、ワークフローを説明する	search_docs	セマンティック／ファジー
「誰／なぜ？」 — リグレッションをデバッグし、意図を理解する	search_history	Git + BM25 + Dense Vector（SQLite vec）
「セットアップ／準備」 — インデックス解析と埋め込み生成	index_codebase	AST Parser + sentence-transformers

これにより、データを取得する前に、LLM は適切な検索戦略を選択する必要があります。

インストール

PyPI から（推奨）

# Install with pip
pip install code-memory

# Or with uvx (for MCP hosts)
uvx code-memory

ソースから

# Clone the repo
git clone https://github.com/kapillamba4/code-memory.git
cd code-memory

# Install dependencies
uv sync

# Run the MCP server (stdio transport)
uv run mcp run code_memory/server.py

ビルド済みバイナリ（スタンドアロン）

GitHub Releases からスタンドアロンの実行ファイルをダウンロードできます。Python のインストールは不要です。

プラットフォーム	アーキテクチャ	ファイル
Linux	x86_64	code-memory-linux-x86_64
macOS	x86_64（Intel）	code-memory-macos-x86_64
macOS	ARM64（Apple Silicon）	code-memory-macos-arm64
Windows	x86_64	code-memory-windows-x86_64.exe

# Linux/macOS: Download and make executable
chmod +x code-memory-*
./code-memory-*

# Windows: Run directly
code-memory-windows-x86_64.exe

注： 初回実行時に、埋め込みモデル（約 600MB）が ~/.cache/huggingface/ にダウンロードされます。2 回目以降はキャッシュされたモデルが使用されます。

クイックスタート

前提条件

• Python ≥ 3.13
• パッケージマネージャーの uv（推奨）または pip

uv がインストールされていない場合は、インストールしてください。

curl -LsSf https://astral.sh/uv/install.sh | sh

インストールと実行

# Install from PyPI
pip install code-memory

# Or run directly with uvx
uvx code-memory

開発

# Run with the MCP Inspector for interactive debugging
uv run mcp dev code_memory/server.py

# Run tests
uv run pytest tests/ -v

# Lint and format
uv run ruff check .
uv run ruff format .

# Build package
uv build

# Build standalone binary (requires pyinstaller)
pip install pyinstaller
pyinstaller --clean code-memory.spec
# Binary output: dist/code-memory

MCP ホストの設定

uvx（Python が必要）またはスタンドアロンバイナリ（依存関係不要）のいずれかを使用できます。

uvx を使用（Python が必要）

Gemini CLI／Gemini Code Assist

MCP 設定（例：~/.gemini/settings.json）に追加します。

{
  "mcpServers": {
    "code-memory": {
      "command": "uvx",
      "args": ["code-memory"]
    }
  }
}

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

{
  "mcpServers": {
    "code-memory": {
      "command": "uvx",
      "args": ["code-memory"]
    }
  }
}

Claude Code（CLI）

プロジェクトルートの .mcp.json、またはグローバルにアクセスする場合は ~/.mcp.json に追加します。

{
  "mcpServers": {
    "code-memory": {
      "command": "uvx",
      "args": ["code-memory"]
    }
  }
}

VS Code（Copilot / Continue）

ワークスペースの .vscode/mcp.json に追加します。

{
  "servers": {
    "code-memory": {
      "command": "uvx",
      "args": ["code-memory"]
    }
  }
}

スタンドアロンバイナリを使用する場合（Python 不要）

ダウンロードしたバイナリの場所にパスを置き換えます。

{
  "mcpServers": {
    "code-memory": {
      "command": "/path/to/code-memory-linux-x86_64"
    }
  }
}

Windows の場合：

{
  "mcpServers": {
    "code-memory": {
      "command": "C:\\path\\to\\code-memory-windows-x86_64.exe"
    }
  }
}

共有 SSE サーバー（メモリ使用量を削減）

デフォルトでは、各 MCP ホストプロジェクトがそれぞれ独自の code-memory プロセスを起動し、プロジェクトごとに埋め込みモデル（約 1～2 GB）を読み込みます。これを避けるには、SSE（Server-Sent Events）経由で単一の共有インスタンスを実行し、すべての MCP ホストからそこに接続します。

共有サーバーを起動する

# Using uvx (recommended)
uvx code-memory --transport sse

# Custom port and host
uvx code-memory --transport sse --port 8765 --host 127.0.0.1

# Using standalone binary
./code-memory-linux-x86_64 --transport sse

デフォルトでは、サーバーは http://127.0.0.1:8765/sse で待ち受けます。

共有サーバーを使用するように MCP ホストを設定する

新しいプロセスを起動する代わりに、実行中の SSE エンドポイントを MCP ホストに指定します。

Claude Desktop

{
  "mcpServers": {
    "code-memory": {
      "url": "http://127.0.0.1:8765/sse"
    }
  }
}

VS Code（Copilot / Continue）

{
  "servers": {
    "code-memory": {
      "url": "http://127.0.0.1:8765/sse"
    }
  }
}

Claude Code（CLI）— .mcp.json

{
  "mcpServers": {
    "code-memory": {
      "url": "http://127.0.0.1:8765/sse"
    }
  }
}

ヒント： uvx code-memory --transport sse を、単一インスタンスのサービスマネージャー（systemd のユーザーサービス、launchd エージェント、または一度だけ設定するログイン／起動の仕組みなど）経由で起動するように設定すると、共有サーバーが自動的に起動します。

セキュリティ： SSE エンドポイントには認証がありません。ローカルプロセスだけが接続できるよう、デフォルトの --host 127.0.0.1 を維持してください。認証を前段に設けていない限り、0.0.0.0 やパブリックインターフェースにバインドしないでください。

設定

CLI オプション

オプション	説明	デフォルト
--transport	トランスポートプロトコル：stdio または sse	stdio
--port	SSE トランスポートのポート（--transport sse を使用する場合のみ）	8765
--host	SSE トランスポートのホスト／バインドアドレス（--transport sse を使用する場合のみ）	127.0.0.1

環境変数

変数	説明	デフォルト
CODE_MEMORY_LOG_LEVEL	ログの詳細度（DEBUG、INFO、WARNING、ERROR）	INFO
EMBEDDING_MODEL	埋め込みに使用する HuggingFace モデル ID	jinaai/jina-code-embeddings-0.5b

例：

CODE_MEMORY_LOG_LEVEL=DEBUG uvx code-memory

カスタム埋め込みモデル

EMBEDDING_MODEL 環境変数を設定すると、別の埋め込みモデルを使用できます。

EMBEDDING_MODEL="BAAI/bge-small-en-v1.5" uvx code-memory

MCP ホストでは、設定に環境変数を追加します。

{
  "mcpServers": {
    "code-memory": {
      "command": "uvx",
      "args": ["code-memory"],
      "env": {
        "EMBEDDING_MODEL": "BAAI/bge-small-en-v1.5"
      }
    }
  }
}

注： 埋め込みモデルを変更すると、既存のインデックスは無効になります。モデルを切り替えた後に index_codebase を再実行する必要があります。

ツール

index_codebase

指定したディレクトリ内のソースファイルとドキュメントをインデックス化、または再インデックス化します。データベースを最新の状態に保つため、search_code または search_docs を使用する前に実行してください。言語に依存しない構造抽出には tree-sitter を使用し、sentence-transformers（ローカルでプロセス内実行）で密なベクトル埋め込みを生成して、セマンティック検索を行います。

index_codebase(directory=".")

search_code

セマンティック検索を実行し、構造的なコード定義を見つけたり、関数／クラスの定義箇所を特定したり、依存関係の参照（呼び出しグラフ）をマッピングしたりします。ハイブリッド検索（BM25 + ベクトル埋め込み）を使用して、完全一致と意味的な類似性を見つけます。

search_code(query="parse python files", search_type="definition")
search_code(query="how do we establish the database connection", search_type="references")
search_code(query="src/auth/", search_type="file_structure")

search_docs

コードベースの概念的な理解に役立ちます。たとえば、仕組み、アーキテクチャパターン、SOP を調べます。コードから抽出した Markdown ドキュメント、README、docstring を検索します。

search_docs(query="how does the authentication flow work?")
search_docs(query="installation instructions", top_k=5)

search_history

Git 履歴を通じて、リグレッションをデバッグし、開発者の意図を理解します。

search_history(query="fix login timeout", search_type="commits")
search_history(query="src/auth/login.py", search_type="file_history", target_file="src/auth/login.py")
search_history(query="server.py", search_type="blame", target_file="server.py", line_start=1, line_end=20)

プロジェクト構成

code-memory/
├── code_memory/           # Package source
│   ├── server.py          # MCP server entry point (FastMCP)
│   ├── db.py              # SQLite database layer with sqlite-vec
│   ├── parser.py          # Tree-sitter-based code parser
│   ├── doc_parser.py      # Markdown documentation parser
│   ├── queries.py         # Hybrid retrieval query layer
│   ├── git_search.py      # Git history search module
│   ├── errors.py          # Custom exception hierarchy
│   ├── validation.py      # Input validation functions
│   ├── logging_config.py  # Structured logging configuration
│   └── api_types.py       # MCP response TypedDicts
├── tests/                 # Test suite
├── pyproject.toml         # Project metadata & dependencies
└── prompts/               # Milestone prompt engineering files

トラブルシューティング

「Git repository not found」エラー

Git リポジトリ内から search_history を実行していることを確認してください。このツールは、現在のディレクトリから上位の階層をたどって .git を探します。

検索結果が空の場合

まず index_codebase(directory=".") を実行して、コードとドキュメントをインデックス化してください。インデックスはローカルの code_memory.db に保存されます。

インデックス化が遅い場合

インデックス化では、ローカルの sentence-transformers モデルを使用して埋め込みを生成します。初回実行時にはモデルがダウンロードされます（jina-code-embeddings-0.5b の場合は約 600 MB）。2 回目以降の実行はより速くなります。

埋め込みモデルのエラー

ディスク容量とメモリが十分にあることを確認してください。jina-code-embeddings-0.5b モデルの読み込みには約 1GB の RAM が必要です。

プライバシーとセキュリティ

コードがマシンの外部に送信されることはありません。 クラウドベースのコードインテリジェンスツールとは異なり、code-memory は完全にローカルで動作します。

• テレメトリーなし — 使用データ、分析、トラッキングはありません
• 外部 API 呼び出しなし — すべての処理はプロセス内で行われます
• クラウドへの依存なし — インターネットに接続していなくても動作します（初期設定後）
• データはローカルに保存 — インデックスはローカルの SQLite データベースに保存されます

code-memory は、次のような用途に最適です。

• 独自および機密性の高いコードベース
• セキュリティを重視する組織
• 外部ネットワークから隔離された開発環境
• プライバシーを重視する開発者

クラウドベースの代替ツールとの詳細な比較については、COMPARISON.md をご覧ください。

外部ネットワークから隔離された環境とオフラインでのサポート

code-memory は完全に隔離された環境で動作します。

方法 1：ビルド済みバイナリとキャッシュ済みモデル

1. インターネットに接続されたマシンで code-memory を一度実行し、埋め込みモデルをキャッシュします。

   uvx code-memory
   # Model downloads to ~/.cache/huggingface/
   

2. 隔離されたマシンに転送します。

   • GitHub Releases のスタンドアロンバイナリ
   • モデルのキャッシュディレクトリ（~/.cache/huggingface/hub/models--*）

3. 隔離されたマシンで実行します。ネットワークは不要です。

方法 2：オフラインでの pip インストール

1. インターネットに接続されたマシンで PyPI から wheel をダウンロードします。
2. 転送してインストールします：pip install code-memory-*.whl
3. 上記の手順でモデルを事前にキャッシュします。
4. オフラインで実行します。

ロードマップ

• マイルストーン 1 — プロジェクトのスキャフォールディングと MCP プロトコルの配線
• マイルストーン 2 — AST パース + SQLite + sqlite-vec を使用した search_code の実装
• マイルストーン 3 — Git 統合による search_history の実装
• マイルストーン 4 — セマンティック検索による search_docs の実装
• マイルストーン 5 — 本番環境向けの堅牢化とパッケージ化

コントリビューション

開発環境のセットアップとガイドラインについては、CONTRIBUTING.md をご覧ください。

変更履歴

バージョン履歴については、CHANGELOG.md をご覧ください。

ライセンス

MIT