mnemograph

Mnemograph

AI コーディングエージェント向けの、永続的なイベントソーシング型ナレッジグラフです。単純なキーと値のメモリとは異なり、Mnemograph はエンティティ、関係、観察事項を記録し、セマンティック検索、階層型のコンテキスト取得、Git ベースの AI メモリのバージョン管理を可能にします。

対応対象：Claude Code、opencode、codex CLI、Zed、Continue.dev、および MCP 対応のあらゆるエージェント。

Mnemograph を選ぶ理由

AI コーディングセッションは一時的なものです。Mnemograph は AI パートナーに永続的なメモリを提供します。

• セッションをまたいで保持 — 決定事項、パターン、学びが持続します
• セマンティック検索に対応 — キーワードだけでなく、意味に基づいて関連するコンテキストを見つけられます
• 階層型の取得を提供 — 必要に応じて、概要から詳細なサブグラフまで取得できます
• コードのようにバージョン管理 — ナレッジグラフのブランチ作成、コミット、差分確認、取り消しができます
• 共同作業を可能に — ユーザー間やプロジェクト間でメモリリポジトリを共有できます

メモリのスコープ：ローカルとグローバル

mnemograph を使う前に、メモリの保存先を決めてください。

スコープ	パス	用途
プロジェクトローカル	./.claude/memory	このリポジトリに固有の知識（アーキテクチャ、決定事項、パターン）
グローバル	~/.claude/memory	プロジェクト横断で使う知識（個人的な学び、普遍的なパターン、好み）
カスタム	MEMORY_PATH で指定する任意のパス	チームで共有するメモリ、組織全体のナレッジベース

重要： プロジェクトで mnemograph を初めて設定するとき、エージェントはユーザーにどのスコープを使うか尋ねてください。これは、知識の保存先と、プロジェクト間で共有するかどうかに影響します。

# Project-local (default)
MEMORY_PATH=".claude/memory"

# Global (cross-project)
MEMORY_PATH="$HOME/.claude/memory"

# CLI: use --global flag
mnemograph --global status
mnemograph --global graph

クイックスタート

オプション 1：Claude Code にインストールさせる

このリポジトリの URL を Claude Code に渡し、mnemograph をセットアップするよう依頼してください。

https://github.com/tm42/mnemograph

または、セットアップ手順を Claude に直接伝えてください。

Read https://raw.githubusercontent.com/tm42/mnemograph/main/SETUP_CLAUDE_CODE.md and follow them

オプション 2：手動でインストールする

# Install from PyPI
pip install mnemograph

# Add to Claude Code (global, available in all projects)
claude mcp add --scope user mnemograph \
  -e MEMORY_PATH="$HOME/.claude/memory" \
  -- uvx mnemograph

# Initialize memory directory
mkdir -p ~/.claude/memory

オプション 3：その他の MCP クライアント

MCP クライアントごとに設定形式が異なります。各クライアント用のコピー＆ペースト可能な設定については、UNIVERSAL_MCP_COMPATIBILITY.md を参照してください。

• opencode — ~/.config/opencode/opencode.json
• Codex CLI — ~/.codex/config.yaml
• Zed — ~/.config/zed/settings.json
• Continue.dev — ~/.continue/config.json

主要な環境変数は MEMORY_PATH です。ナレッジグラフの保存先に設定してください。

オプション 4：ソースからインストールする

git clone https://github.com/tm42/mnemograph.git
cd mnemograph
uv sync

# Add to Claude Code (or adapt for your MCP client)
claude mcp add --scope user mnemograph \
  -e MEMORY_PATH="$HOME/.claude/memory" \
  -- uv run --directory /path/to/mnemograph mnemograph

使い方

MCP ツール（あらゆるエージェントで使用）

Mnemograph は、以下のツールを MCP 経由で公開します。

コア操作：

ツール	説明
remember	主要な保存機能：知識をアトミックに保存します（1 回の呼び出しでエンティティ＋観察事項＋関係を保存）
recall	主要な取得機能：トークンを自動管理しながら、関連するコンテキストを取得します。詳細をすべて表示するには focus=['Entity'] を使用します。デフォルトの出力は人間が読みやすい文章です。
create_entities	エンティティを作成します（一致率が 80% を超える重複は自動的にブロックされます）
create_relations	型付きエッジ（implements、uses、decided_for など）でエンティティをリンクします
add_observations	既存のエンティティに事実やメモを追加します
read_graph	ナレッジグラフ全体を取得します（大きくなる場合があるため注意してください）
delete_entities	エンティティを削除します（関連するリレーションも連鎖的に削除されます）
delete_relations	特定のリレーションを削除します
delete_observations	特定の観察事項を削除します

セッションのライフサイクル：

ツール	説明
session_start	セッションの開始を通知し、初期コンテキストを取得します。quick_start ガイドを返します。
session_end	セッションの終了を通知し、必要に応じて要約を保存します
get_primer	ナレッジグラフの概要を把握します（セッション開始時に呼び出します）

ブランチ（並行作業ストリーム）：

ツール	説明
create_branch	分離された作業用の名前付きブランチを作成します（例：「feature/auth-refactor」）
switch_branch	別のブランチに切り替えます
list_branches	すべてのブランチを一覧表示します
merge_branch	ブランチを main にマージします
delete_branch	ブランチを削除します
get_current_branch	現在のブランチ名を取得します

グラフのメンテナンス：

ツール	説明
find_similar	名前が類似しているエンティティを検索します（重複検出）
find_orphans	リレーションのないエンティティを検索します
merge_entities	重複するエンティティをマージします（観察事項を統合し、リレーションの参照先を変更します）
get_graph_health	グラフの品質を評価します：孤立したエンティティ、重複、過剰な情報を持つエンティティ
suggest_relations	意味的類似性に基づいて、関連する可能性のあるリレーションを提案します
create_entities_force	重複チェックを回避してエンティティを作成します
clear_graph	すべてのエンティティ／リレーションをクリアします（イベントソーシングのため、巻き戻し可能です）

タイムトラベル：

ツール	説明
get_state_at	履歴内の任意の時点におけるグラフの状態を表示します
diff_timerange	2 つの時点の間に何が変更されたかを表示します
get_entity_history	特定のエンティティの変更履歴全体を取得します
rewind	git を使用してグラフを以前の状態に巻き戻します
restore_state_at	指定したタイムスタンプ時点の状態にグラフを復元します（監査履歴を保持）
reload	ディスクからグラフの状態を再読み込みします（git 操作の後に使用）

エッジの重み：

ツール	説明
get_relation_weight	重みの内訳を取得します（新しさ、共同アクセス、明示的な重み）
set_relation_importance	明示的な重要度の重みを設定します（0.0-1.0）
get_strongest_connections	エンティティの最も重要なつながりを検索します
get_weak_relations	削除候補（重みの低いリレーション）を検索します

Recall：文章形式とグラフ形式

recall ツールは、デフォルトで文章形式のコンテキストを返します。エージェントが JSON を解析せずにそのまま利用できる、人間が読みやすいテキストです。

# Default: prose format (human-readable)
recall(depth="medium", query="authentication")
# Returns:
# **MyApp** (project)
# A Python web service. Uses OAuth2 for user auth.
# Uses: PostgreSQL, Redis
#
# **Decisions:**
# • Decision: Use JWT — Stateless tokens for API authentication
#
# **Gotchas:**
# • Token expiry is 1 hour by default
# • Refresh tokens stored in Redis

# Optional: graph format (structured JSON)
recall(depth="medium", query="authentication", format="graph")

深度レベル：

• shallow — クイックサマリー：エンティティ数、最近のアクティビティ、注意点
• medium — セマンティック検索＋1 ホップの隣接ノード（約 2000 トークン）
• deep — フォーカスエンティティからのマルチホップ探索（約 5000 トークン）

注意点の抽出： Gotcha:、Warning:、Note:、または Important: で始まる観察事項は、自動的に専用セクションへ抽出されます。

CLI ツール

mnemograph — すべてのメモリ操作を統合する CLI：

# Basic operations
mnemograph status                # Show entity/relation counts, recent events
mnemograph log                   # View event history
mnemograph log --session X       # Filter by session
mnemograph sessions              # List all sessions
mnemograph export                # Export graph as JSON

# VCS commands (git-based version control)
mnemograph vcs init              # Initialize memory as git repo
mnemograph vcs commit -m "msg"   # Commit current state
mnemograph vcs log               # View commit history
mnemograph vcs revert --event ID # Undo specific events (compensating events)
mnemograph vcs revert --session X # Undo entire session

# Graph visualization
mnemograph graph                 # Open interactive graph viewer
mnemograph graph --watch         # Live reload mode (refresh button)

# Time travel
mnemograph show --at "2 days ago"  # View state at a point in time
mnemograph diff "1 week ago"       # Show changes since then
mnemograph history "EntityName"    # Full changelog for an entity
mnemograph rewind -n 1             # Git-based rewind by N commits
mnemograph restore --to "yesterday" # Event-based restore (audit-preserving)

# Graph health and maintenance
mnemograph health                # Show graph health report (orphans, duplicates, etc.)
mnemograph health --fix          # Interactive cleanup mode
mnemograph similar "React"       # Find entities similar to "React" (duplicate check)
mnemograph orphans               # List entities with no relations
mnemograph suggest "FastAPI"     # Suggest relations for an entity
mnemograph clear                 # Clear all entities and relations (with confirmation)

# Global options (come *before* the subcommand)
mnemograph --global status       # Use global memory (~/.claude/memory)
mnemograph --memory-path /path graph  # Custom memory location

どこからでも実行（venv を有効化せずに）：

# Using uv (recommended)
uv run --directory /path/to/mnemograph mnemograph graph

# Using uvx (if installed from PyPI)
uvx --from mnemograph mnemograph status

グラフの可視化 — インタラクティブな D3.js ビューアー：

• レイアウトアルゴリズム：力学ベース、放射状（ハブを中心に配置）、クラスタ化（コンポーネントごと）
• カラー表示モード：エンティティタイプ、連結成分、または次数中心性による色分け
• エッジの重みスライダー：強度で接続をフィルタリング
• ライブ更新：--watch モードと更新ボタンでリアルタイムに更新

アーキテクチャ

~/.mnemograph/memory/    # or ~/.claude/memory, ~/.opencode/memory, etc.
├── mnemograph.db        # SQLite database (events + vectors)
├── state.json           # Cached materialized state (derived)
└── .git/                # Version history

イベントソーシングでは、すべての変更が不変のイベントとして SQLite に記録されます。現在の状態はイベントを再生して計算されます。これにより、次のことが可能になります。

• すべての変更の完全な履歴
• 任意の操作の取り消し
• ナレッジグラフのブランチ作成とマージ
• Claude が何をいつ学習したかの監査証跡

2 層のバージョン管理：

• mnemograph vcs revert — 補償イベントを使って特定のイベントを取り消す、きめ細かな操作
• mnemograph rewind / mnemograph restore — Git レベルまたはタイムスタンプベースで復元する、大まかな操作

ブランチ

ブランチを使うと、メイングラフに影響を与えずに、分離されたナレッジを扱えます。次の用途に最適です。

• 探索的な作業 — 共有ナレッジを汚染せずにアプローチを試す
• 機能ごとのコンテキスト — 「feature/auth-refactor」で認証に関する決定を分離
• 複数のプロジェクト — 異なるコードベース間でコンテキストを切り替え

ブランチの作成と使用

# Create a branch for your feature
create_branch(name="feature/auth-refactor")

# Work normally — all operations happen on this branch
remember(name="OAuth2", entity_type="concept",
         observations=["Implementing OAuth2 flow"])

# Switch back to main to see clean state
switch_branch(name="main")

# Merge when ready
merge_branch(source="feature/auth-refactor", target="main")

ブランチの仕組み

• メインブランチは常に存在し、共有ナレッジを含みます
• フィーチャーブランチはメインブランチを引き継ぎますが、追加内容は分離されたままです
• 自動フィルタリング — recall、search などは現在のブランチとメインブランチのみを参照します
• マージすると、ブランチのエンティティ／リレーションが対象ブランチにコピーされます
• 削除すると、マージ後の後処理（または探索作業の破棄）が行われます

ブランチの命名規則

パターン	用途
feature/xyz	機能固有のナレッジ
explore/xyz	探索的／実験的な作業
project/xyz	プロジェクト固有のコンテキスト
user/name	個人用ワークスペース

エンティティタイプ

タイプ	目的	例
concept	アイデア、パターン、アプローチ	「リポジトリパターン」、「イベントソーシング」
decision	根拠を伴う選択	「シンプルさを優先して Postgres ではなく SQLite を選択」
project	コードベース、システム	「auth-service」、「mnemograph」
pattern	繰り返し使われるコードパターン	「Result 型によるエラー処理」
question	未解決の疑問	「リアルタイム同期を追加すべきか？」
learning	発見	「pytest のフィクスチャでテストのセットアップが簡単になる」
entity	一般的なエンティティ（人物、ファイルなど）	「Alice」、「config.yaml」

トピックの規約

関連するナレッジを参照するためのエントリーポイントとして、トピックエンティティを使用します。

# Create topic entry points
create_entities([
    {"name": "topic/projects", "entityType": "entity"},
    {"name": "topic/decisions", "entityType": "entity"},
    {"name": "topic/patterns", "entityType": "entity"},
])

# Link entities to their topics
create_relations([
    {"from": "auth-service", "to": "topic/projects", "relationType": "part_of"},
    {"from": "Decision: Use Redis", "to": "topic/decisions", "relationType": "part_of"},
])

標準トピック：

• topic/projects — プロジェクトエンティティ
• topic/decisions — アーキテクチャ上の決定
• topic/patterns — パターンとプラクティス
• topic/learnings — 重要な発見
• topic/questions — 未解決の質問

これにより、topic/decisions を調べて「どのような決定をしたか」を簡単に問い合わせられます。

開発

git clone https://github.com/tm42/mnemograph.git
cd mnemograph
uv sync                    # Install dependencies
uv run pytest --cov        # Run tests with coverage (enforces 75% minimum)
uv run ruff check .        # Lint
uv run mnemograph          # Run MCP server directly

ベースとするプロジェクト

Mnemograph は MCP server-memory（Anthropic の公式メモリサーバー）をベースにしています。

ライセンス

MIT