memex

memex：エージェント型ソフトウェアエンジニアリングのための信頼できるエンジニアリングコンテキスト

Claude Code と Codex のエンジニアリングコンテキストをコードの変更に合わせて最新に保ち、 根拠が変わった編集を保留する、オープンソースの MCP サーバーとフックサービスです。

memex.stifler.in

コミットやファイル変更を構造化されたエンジニアリング知識に変換し、鮮度と出所を保ったままエージェントに届けるデーモン、フックサービス、MCP サーバーです。memex が個人の記憶や未加工のセッション状態の保存先になることはありません。

memex は、リポジトリの二時点知識グラフ（モジュール、シンボル、決定事項、問題、根拠、コードの変遷）を構築します。v1 では Claude Code と Codex にもフックします。各セッションは適切なコンテキストで始まり、各編集は現在のコードに照らしてチェックされ、何が変わったのかがエージェントに正確に伝えられます。

memex の公開先

評価記録は BENCHMARK.md、リリース履歴は CHANGELOG.md、報告手順は SECURITY.md、 開発への参加方法は CONTRIBUTING.md をご覧ください。

https://github.com/user-attachments/assets/b14e3185-ea36-4ae5-bd18-2d34e6bf7be4

60 秒でわかる memex v1。プレーヤーが読み込まれない場合は、動画をダウンロードしてください。

ライブコンテキスト（v1）

コーディングエージェントは、コードのスナップショットをもとに作業します。チームメイトが変更をプッシュし、別のエージェントがファイルを編集し、ブランチが移動しても、エージェントは以前に読み取った内容をもとに作業を続けます。v1は、Claude CodeとCodex内でそのスナップショットを最新の状態に保ちます。

uv tool install memex-mcp          # installs the `memex` command
cd your-repo
memex v1 doctor                    # what is set up, what is missing, what to do next
memex v1 install claude            # hooks in .claude/settings.json; global settings untouched
memex v1 install codex --neo4j-uri bolt://localhost:7687   # optional, for Codex

memexを使用するには、すでに稼働しているNeo4j 5サーバーが必要です（Dockerは必須ではありません）。フックはチェックアウト内のプロジェクト設定にのみ追加され、memexがクライアントの認証情報を要求したり保存したりすることはありません。完全なガイド、ホスト別の手順、ロールバックについては、docs/v1/25_ONBOARDING.mdをご覧ください。

flowchart LR
    A[Your repository<br/>files + git] --> B[memex watcher<br/>tree-sitter + Gemini]
    B --> C[Neo4j graph<br/>bitemporal facts]
    C --> D[memex core<br/>ContextPacket selection]
    D --> H[Hook service<br/>session start · edit checks · resume notice]
    D --> E[Hermes MemoryProvider<br/>automatic read-only prefetch]
    D --> F[MCP tools<br/>explicit lookup]
    H --> G[Claude Code / Codex]
    E --> G
    F --> G

    style B fill:#cfe8ff,stroke:#0066cc,color:#000
    style C fill:#fff4cf,stroke:#cc9900,color:#000
    style H fill:#d4f5d4,stroke:#2d8f2d,color:#000

インストール

Claude Codeマーケットプレイス経由

/plugin marketplace add STiFLeR7/claude-plugins
/plugin install memex-mcp@stifler-marketplace

Claude Codeのセッションを再起動してください。

インストールまたはアップグレード後の初回起動時に、memexのPython依存関係がダウンロードされます（約40秒）。この処理は一度だけClaude CodeのMCP接続タイムアウト時間を超えることがあります。先にウォームアップしてから、再起動してください。

npx -y stifler-memex-mcp --help     # one-time download; later starts take a few seconds

Claude Codeに接続タイムアウトが引き続き表示される場合は、/mcp を開き、memex に再接続してください。ツールにNeo4jへ接続できないと表示された場合は、Neo4jを起動してください（例：docker start memex-neo4j）。ツールは再起動しなくても復旧します。

手動

docker compose -f docker/docker-compose.yml up -d
cat > .env <<EOF
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=memex-local
GEMINI_API_KEY=your-key-here
EOF
npx stifler-memex-mcp init --repo .
npx stifler-memex-mcp watch --repo .
npx stifler-memex-mcp serve --repo .

Hermesとの統合

Hermesとの統合は読み取り専用です。個人のメモリ、生のセッション状態、実行状態はHermesが保持します。memexは、範囲を限定した ContextPacket を通じてリポジトリのエンジニアリングコンテキストを提供します。Hermesの state.db、トランスクリプト、プロンプト、ツールの結果は取り込みません。

Hermesのプロファイル設定にmemexプロバイダーを追加してください。

memory:
  provider: memex
plugins:
  memex:
    repo_path: /absolute/path/to/repository
    prefetch_timeout_seconds: 7
    max_items: 8
    max_chars: 12000

Hermesがインストールされていない場合は、MCPの get_engineering_context ツールで同じコンテキストセレクターを使用してください。どちらの方法も、プロトコルに依存しないmemexコアを共有し、情報を取得できない場合はフェイルオープンで動作します。

セルフホスト型のチームデプロイ

チームで共有する環境をセットアップする場合（Neo4jを1台、memex-serverを1台使用し、認証はデフォルトで有効、Neo4jのポートはホストに公開されません）：

bash docker/bootstrap-team-env.sh
docker compose -f docker/docker-compose.team.yml up -d

初期管理者キーの取得方法や、避けるべき down -v の注意点を含む全手順については、docker/TEAM-DEPLOY.mdをご覧ください。

概要

ライフサイクル

flowchart TD
    Init[memex init<br/>extract baseline] --> Watch[memex watch<br/>daemon + git hooks]
    Watch -->|commit| Extract[tree-sitter extract<br/>symbols, imports, lockfile]
    Extract --> Synth[Gemini Flash<br/>diff → Decision nodes]
    Synth --> Write[Graphiti add_episode<br/>+ post-hoc bitemporal SET]
    Write --> Decay[Scheduler<br/>nightly confidence decay]
    Decay -->|stale edges| Archive[expired_at = now]

    Serve[memex serve<br/>MCP stdio/HTTP] -.->|reads| Write
    Agent[AI agent] -->|14 MCP tools| Serve
    Serve -->|record_decision / record_problem| Write

    Cluster[memex cluster<br/>Leiden over hybrid edges] -.->|every N commits| Write

    style Init fill:#e8f4ff,color:#000
    style Watch fill:#fff4cf,color:#000
    style Synth fill:#ffe0cc,color:#000
    style Serve fill:#d4f5d4,color:#000

MCP ツール

14個のツール：読み取り8個、書き込み4個、分析2個。

読み取り

書き込み

二時性信頼度

信頼度は、変化する保存済みの数値ではありません。base_confidence、検証ステータス、最後に補強されてからの経過時間、アクセス回数に基づいて、クエリ時に計算されます。

flowchart LR
    Edge[Edge created<br/>base_confidence] --> Q{Validated by<br/>a human?}
    Q -->|yes| Slow[Slow regime<br/>half-life ~139d]
    Q -->|no| Fast[Fast regime<br/>stale at exactly 30d]
    Slow --> Score[Composite score<br/>conf × recency × rehearsal]
    Fast --> Score
    Score -->|below floor| Stale[get_stale_context surfaces it]
    Score -->|access| Bump[last_reinforced_at updated]
    Bump --> Score

    style Slow fill:#d4f5d4,color:#000
    style Fast fill:#ffd4d4,color:#000

階層型クラスタ

memex cluster は、ハイブリッドエッジグラフに対して階層型 Leiden を実行します。

節約効果を測定する

memex は、トークン削減の指標と人間によるレビュー操作を SQLite データベース（~/.config/memex/telemetry.db）にローカル保存します。

CLI を使って、いつでも節約効果を確認できます：

memex stats

または、生の JSON ペイロードを表示できます：

memex stats --json

または、特定のリポジトリの範囲を指定できます：

memex stats --repo /path/to/repo

次の項目を集計して返します：

• 期間ごとの概要：today、last 7 days、last 30 days、lifetime における呼び出し数、返されたトークン数、推定トークン数（要求されたファイルのサイズ）、節約したトークン数、トークン削減率。
• 上位ツール：節約したトークン数の合計順に並べた、最も価値の高いツール。
• エージェントクライアント：アクティブなエージェント（Claude Code、Gemini CLI、Cursor、Codex）と、エージェントごとのトークン節約の内訳。
• 検証状況：検証済み、未検証、相互確認済みのノードの合計数と、前回のレビューから経過した日数。

同じ統計情報は、HTTP MCP トランスポートからも利用できます：

GET /stats?repo=/path/to/repo
Authorization: Bearer <your-key>

エージェントを接続する

{
  "mcpServers": {
    "memex": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
    }
  }
}

{
  "mcpServers": {
    "memex": {
      "command": "npx",
      "args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
    }
  }
}

{
  "mcpServers": {
    "memex": {
      "command": "npx",
      "args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
    }
  }
}

[mcp_servers.memex]
command = "npx"
args = ["-y", "stifler-memex-mcp", "serve", "--repo", "."]

memex memory-tool serve --repo .                     # in-process
memex memory-tool serve --repo . --transport http    # FastAPI on :7464

from memex.memory_tool import MemexAsyncMemoryTool
memory_tool = MemexAsyncMemoryTool(repo_root=".")
client.beta.messages.run_tools(..., tools=[memory_tool])

運用原則

memex を使う場面

プロジェクト構成

memex/
├── memex/
│   ├── extractor/        tree-sitter + lockfile parsers
│   ├── graph/            Neo4j writes, confidence, archive, cluster engine
│   ├── synthesizer/      Gemini Flash → Decision nodes
│   ├── mcp_server/       14 MCP tools (read + write + analytic)
│   ├── memory_tool/      Anthropic memory_20250818 adapter
│   ├── watcher/          daemon + git hooks
│   └── cli.py            init / watch / serve / review / graph / cluster
├── tests/                unit, integration, and objective evaluation suites
├── docker/               Neo4j compose
├── npm/                  npx wrapper (publishes as stifler-memex-mcp)
└── Dockerfile            introspection-only image for MCP directory sandboxes

コマンド

ライセンス

MIT。詳しくは LICENSE をご覧ください。

作者

Hill Patel (@STiFLeR7)

主な貢献者とメンテナー

• Hill Patel (@STiFLeR7)、アーキテクト兼メンテナー
• Nirvaan Lagishetty (@Nirvaan05)、主要な貢献者兼メンテナー

貢献

Issue または PR を作成してください。uv sync --all-extras で開発ツールチェーンをインストールできます。 オフラインテストスイートには uv run pytest -m "not integration" を実行し、PR を作成する前に uv run ruff check . を実行してください。バージョンを更新する場合は、pyproject.toml、 npm/package.json、server.json、およびチームの Docker イメージタグもあわせて更新してください。

リリース履歴は CHANGELOG.md にあります。v1 の設計と 評価記録は docs/v1/ に、v0.9 のアーキテクチャは docs/architecture/v0.9/ にあります。

Vannevar Bush, 1945: 「個人が使う未来の装置を考えてみてください。それは、機械化された個人用ファイル兼図書館のようなものです。名前が必要ですが、思いつきで付けるなら、memex でよいでしょう。」