Memora

Claude Code で設定すると、サーバーは自動的に実行されます。手動で実行する場合：

# Default (stdio mode for MCP)
memora-server

# With graph visualization server
memora-server --graph-port 8765

# HTTP transport (alternative to stdio)
memora-server --transport streamable-http --host 127.0.0.1 --port 8080

Claude Code

プロジェクトのルートにある .mcp.json に追加します。

ローカル DB：

{
  "mcpServers": {
    "memora": {
      "command": "memora-server",
      "args": [],
      "env": {
        "MEMORA_DB_PATH": "~/.local/share/memora/memories.db",
        "MEMORA_ALLOW_ANY_TAG": "1",
        "MEMORA_GRAPH_PORT": "8765"
      }
    }
  }
}

クラウド DB（Cloudflare D1）— 推奨：

{
  "mcpServers": {
    "memora": {
      "command": "memora-server",
      "args": ["--no-graph"],
      "env": {
        "MEMORA_STORAGE_URI": "d1://<account-id>/<database-id>",
        "CLOUDFLARE_API_TOKEN": "<your-api-token>",
        "MEMORA_ALLOW_ANY_TAG": "1"
      }
    }
  }
}

D1 では、ローカルの可視化サーバーを無効にするため --no-graph を使用します。代わりに、Cloudflare Pages の URL でホストされているグラフを使用してください（クラウドグラフを参照）。

d1:// をプライマリに指定すると、そのデータベースの読み取りレプリケーションが無効になっていない限り、起動に失敗します（読み取りレプリケーションが有効な間は、セッションブックマークによる REST の読み取り後書き込みが機能しません）。MEMORA_D1_ALLOW_READ_REPLICATION=1 を設定すると、警告をログに記録して起動します。

クラウド DB（S3/R2）— 同期モード：

{
  "mcpServers": {
    "memora": {
      "command": "memora-server",
      "args": [],
      "env": {
        "AWS_PROFILE": "memora",
        "AWS_ENDPOINT_URL": "https://<account-id>.r2.cloudflarestorage.com",
        "MEMORA_STORAGE_URI": "s3://memories/memories.db",
        "MEMORA_CLOUD_ENCRYPT": "true",
        "MEMORA_ALLOW_ANY_TAG": "1",
        "MEMORA_GRAPH_PORT": "8765"
      }
    }
  }
}

Codex CLI

~/.codex/config.toml に追加します。

[mcp_servers.memora]
  command = "memora-server"  # or full path: /path/to/bin/memora-server
  args = ["--no-graph"]
  env = {
    AWS_PROFILE = "memora",
    AWS_ENDPOINT_URL = "https://<account-id>.r2.cloudflarestorage.com",
    MEMORA_STORAGE_URI = "s3://memories/memories.db",
    MEMORA_CLOUD_ENCRYPT = "true",
    MEMORA_ALLOW_ANY_TAG = "1",
  }

44 個の MCP ツールはすべて無条件に登録されるため、ほとんどのツールが呼び出されない場合でも、すべてのエージェントセッションに約 12,700 トークンのツールスキーマ全体が注入されます。MEMORA_TOOL_PROFILE はデプロイごとにサブセットを公開するため、制限されたツールは本当に存在しなくなります — tools/list から消え、かつディスパッチも不可能になります (call_tool は隠れた実行ではなく unknown-tool を返します)。プロファイルは起動時に適用され、証明されます。アクティブなプロファイルと公開されているツール数は stderr にログ出力されます。

• 未設定 / 空 = full。 既存のデプロイの動作は変わりません。
• 不明な値は起動を中止します。その際、有効な値を示すメッセージが表示されます。full に暗黙的にフォールバックすることは決してありません — タイプミスによって、すべてのワーカーに破壊的なメンテナンスツール (memory_rebuild_embeddings、memory_delete_batch) が再び公開されてはなりません。フェイルクローズドです。
• memory_list は leader に含まれますが、agent には含まれません。memory_list_compact の 0.22 秒に対して D1 ストアで 163〜174 秒かかっていた間は、両方から除外されていました。 #973 でそれが修正されました (現在は約 1.1 秒)。agent から除外されているのは、速度のためではなく、ワーカーの読み取りサーフェスが意図的に狭くされているためです。
• leader/agent の境界は memora/tool_profile.py 内のデータ (2 つの frozenset) です。これを編集するのは 1 行であり、44 個のデコレーターを一掃する作業ではありません。
• このプルーニングは FastMCP のプライベートな _tool_manager._tools 辞書から削除するため、memora は mcp>=1.27,<1.28 (監査済みのマイナーバージョン) を固定し、低レベルの登録済み MCP リクエストハンドラー (_mcp_server.request_handlers[ListToolsRequest] / [CallToolRequest] — 実際のクライアントリクエストが使用する実際のディスパッチ呼び出し可能オブジェクトであり、FastMCP.list_tools / call_tool という Python ヘルパーではありません) を通じて起動時の証明を実行し、インストールされている SDK がリスト/ディスパッチを別の場所にルーティングしている場合 (プライベート実装のドリフト) には起動を拒否します。固定は静的ガードであり、証明は実行時のバックストップです。上限を引き上げるには tests/test_tool_profile.py を再実行する必要があります。
• コンテナデプロイでは、プロファイルはコンテナごとですが、ロールはエージェントごとです。あるワークスペースの leader とそのワーカーを 1 つのコンテナで提供するには leader スーパーセットが必要です。agent では leader から create_section/store_document/delete/digest/tags が剥ぎ取られてしまいます。
• memora-server (つまり memora.server.main()) が唯一サポートされるプロファイル済みの提供パスです。memora.server.mcp をインポートして自分で mcp.run() を呼び出す直接埋め込み型は、プロファイリングを完全にバイパスします (グローバルの mcp は依然として 44 個すべてのツールを保持しています)。プロファイリングを希望する埋め込み型は、自分で apply_tool_profile を呼び出すか、main() を使用する必要があります。

# Leader deployment — exposes 19 tools
MEMORA_TOOL_PROFILE=leader memora-server

# Agent worker — exposes 12 tools
MEMORA_TOOL_PROFILE=agent memora-server

# Full (default) — all 44 tools, existing behaviour
memora-server

# Typo refuses to start:
# MEMORA_TOOL_PROFILE=agnt memora-server
# Error: unknown MEMORA_TOOL_PROFILE='agnt'; valid values: full, leader, agent

1 つの memora プロセスで、すべてのワークスペースにサービスを提供できます。MEMORA_DATABASES は {name: storage URI} の JSON レジストリであり、クライアントは /mcp/<name> で自身のストアに到達します。セレクターは .mcp.json にすでにある URL であり、ツール引数ではありません — すべてのツールにオプションの db を設けることは、忘れるチャンスが 44 回あるということであり、忘れるたびに誰か他の人のストアに書き込まれてしまいます。

MEMORA_DATABASES を未設定にすると従来の形です: MEMORA_STORAGE_URI / MEMORA_DB_PATH からの単一バックエンド、単一の /mcp。既存の stdio デプロイは変更されません。

ルーティング (streamable-http のみ):

バインドはリクエストごとではなく、MCP セッションごとに固定されます。/mcp/alpha で開いたセッションを /mcp/beta で再利用しても、解決先は引き続き alpha です。クライアントは会話の途中でデータベースを切り替えられません。

設定に不備がある場合は起動を拒否します（従来のデータベースにはフォールバックしません）。対象となる不備は、不正な JSON、オブジェクト以外の値、重複キー、空の URI、URL パスのセグメントが1つでない名前、またはデータベースが複数列挙されている場合に MEMORA_DEFAULT_DB が未設定または不明であることです。

実行例と接続例。 これはストリーマブル HTTP リスナーであり、MCP の command エントリーではありません（command エントリーでは stdio の子プロセスが起動しますが、そのプロセスは stdio で MCP を話しません）。認証情報はサーバープロセスに保存されます。

MEMORA_DATABASES='{"memora":"d1://<account-id>/<memora-db-id>","alpha":"d1://<account-id>/<alpha-db-id>"}' \
MEMORA_DEFAULT_DB=memora \
CLOUDFLARE_API_TOKEN='<token>' \
MEMORA_VECTOR_SCAN_PAGE_SIZE=100 \
memora-server --transport streamable-http --host 127.0.0.1 --port 8000 --no-graph

{
  "mcpServers": {
    "memora": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp/alpha"
    }
  }
}

コンテナー／プロキシ構成（このホストで通常使用するランチャー。上記のコマンドとは異なります）：scripts/memora-instance.sh up myinstance は同じ HTTP サーバーをコンテナー内で起動し、scripts/memora_proxy.py を 127.0.0.1:<PORT>（memora インスタンスでは8910）で起動します。ワークスペース URL は http://127.0.0.1:8910/mcp/alpha になります。コンテナーのデプロイを参照してください。

レジストリには d1://、s3://、ローカルパスを混在させることができます。parse_backend_uri はスキームに応じて振り分けます。

memory_stats はバインドされたデータベースを報告します。 database（このセッションが実際に解決した名前）と database_source（path、 registry_default、または unconfigured）を返します。.mcp.json に有効だが誤った名前を指定しても、ほかの方法では検出できません。すべてのツールが動作し、読み取りは成功し、書き込みは別のプロジェクトのストアに気付かれずに行われます。memory_stats を呼び出し、database が意図したワークスペースと一致することを確認してください。

複数データベースプロセスのヘルスチェック：GET /health は稼働状態の確認です（データベース I/O は行いません。監視プロセスが再起動を判断する際に使用できる唯一のシグナルです）。GET /health/db はアラート用のエンドポイントです（常に HTTP 200 を返します。status は ok、degraded、unknown — まだスナップショットがない場合、更新がタイムアウトした場合、または証跡が最大許容経過時間より古い場合 — のいずれかです。レジストリ自体が使用できない場合は error です）。GET /health/db/{name} はワークスペースごとのプローブです（200 または503）。1つのストアの劣化を理由にプロセス全体を停止すると、正常なストアまで停止してしまいます。

MEMORA_DATABASES が未設定の場合、プロセスは稼働中、1つのデータベースにバインドされます（MEMORA_STORAGE_URI / MEMORA_DB_PATH）。これは従来の「1ストア、1コンテナー、1ポート」の構成です。

MEMORA_DATABASES が設定されている場合、1つのコンテナーがすべてのワークスペースを提供し、クライアントは URL パス（/mcp/<name>）でストアを選択します。複数データベースのルーティングを参照してください。scripts/memora-instance.sh では、インスタンスファイルごとに STORAGE_URI、VOLUME、MEMORA_DATABASES のいずれか1つが必要です（load() は少なくとも1つを必須とします）。複数が設定されている場合、cmd_up は MEMORA_DATABASES、STORAGE_URI、VOLUME の順に使用します。

Dockerfile は認証情報を含まないイメージをビルドします。scripts/memora-instance.sh は instances/myinstance.env（または別の名前のファイル）から1つのインスタンスをデプロイします。このスクリプトの実行時 CLI は $MEMORA_CONTAINER_BIN（デフォルトは container — Apple の CLI）です。スクリプトが実行するすべてのコンテナー操作（build、up、status、 logs、down）で、この設定が適用されます。生成される memora_proxy.py プロセスでは container list がハードコードされています。これもプロキシが存在する理由です。このランタイムでは、起動のたびにコンテナーの IP が再割り当てされます。

./scripts/memora-instance.sh build   myinstance   # build the image
./scripts/memora-instance.sh up      myinstance   # run the container
./scripts/memora-instance.sh proxy   myinstance   # render a LaunchAgent + print install commands
./scripts/memora-instance.sh status                # every instance at a glance

次に、ワークスペースをそのコンテナーに接続します。秘密情報を含まないクライアント設定全体は以下のとおりです。 レジストリインスタンスではストアをパス（/mcp/<name>）に指定する必要があります。/mcp のみの場合はレジストリのデフォルトが使用されます。

{"mcpServers": {"memora": {"type": "http", "url": "http://127.0.0.1:8910/mcp/alpha"}}}

Memora は3種類の埋め込みバックエンドに対応しています：

埋め込みと LLM は個別に設定します。

片方の MEMORA_EMBEDDING_* だけを設定する分割構成は拒否されます。あるプロバイダーのシークレットが別のホストに送信されることはありません。

注意 — OpenRouter には埋め込みエンドポイントがありません。 OpenRouter のカタログはチャット／マルチモーダルのみで、埋め込みモデルはありません。OPENAI_BASE_URL（または MEMORA のベース URL）を使って、埋め込みの接続先を OpenRouter に設定しないでください。この設定では埋め込み呼び出しがすべて 404 になります。MEMORA_EMBEDDING_STRICT=1 が設定されていない場合、Memora は TF-IDF にフォールバックして応答を続けるため、正常に動作しているように見えながら、ストアにはキーワードの集合が蓄積されます。OpenRouter はLLMにのみ使用する場合は問題ありません。

設定例（LLM は OpenRouter、埋め込みは Cloudflare Workers AI を使用）：

@cf/baai/bge-m3 は1024次元です。トークンには Workers AI の権限が必要です。エンドポイントの形式：

https://api.cloudflare.com/client/v4/accounts/<account_id>/ai/v1

{
  "env": {
    "MEMORA_EMBEDDING_MODEL": "openai",
    "OPENAI_API_KEY": "<openrouter-key>",
    "OPENAI_BASE_URL": "https://openrouter.ai/api/v1",
    "MEMORA_LLM_MODEL": "deepseek/deepseek-chat",
    "MEMORA_EMBEDDING_API_KEY": "<cloudflare-api-token-with-workers-ai>",
    "MEMORA_EMBEDDING_BASE_URL": "https://api.cloudflare.com/client/v4/accounts/<account_id>/ai/v1",
    "OPENAI_EMBEDDING_MODEL": "@cf/baai/bge-m3",
    "MEMORA_EMBEDDING_STRICT": "1"
  }
}

この修正でできること（誇張なし）：埋め込みと LLM で異なるプロバイダーを使用できます。部分的な分離は拒否され、厳密モードでは暗黙の劣化が、明示的な名前付きエラーになります。

自動： memory_create、memory_update、または memory_create_batch を実行すると、埋め込みと相互参照が自動的に計算されます。

ストアのフィンガープリントが変わった場合は手動での再構築が必要です — MEMORA_EMBEDDING_MODEL だけでなく、以下も対象です。

• 埋め込みのエンドポイント（MEMORA_EMBEDDING_BASE_URL / ホスト）
• 実際のモデル ID（OPENAI_EMBEDDING_MODEL。例：@cf/baai/bge-m3 への切り替え）
• ベクトルの種類または次元数（単語キー TF-IDF バッグ対高密度 1024 次元、または 384 対 1024）
• 混在ストア（一部の行は高密度、一部はスパース） — コサイン類似度はキーが共有されている場合のみ機能するため、種類が混在すると古い行の再現率は 0.0 になります

フィンガープリントの形式：backend|model|repr（例：openai|@cf/baai/bge-m3|dense:1024）。従来のメタ値 openai のみの場合は、不一致として扱われます。

# After changing embedding model/endpoint, rebuild all embeddings
memory_rebuild_embeddings

# Then rebuild cross-references to update the knowledge graph
memory_rebuild_crossrefs

組み込みの HTTP サーバーが MCP サーバーとともに自動的に起動し、インタラクティブなナレッジグラフの可視化を提供します。

詳細パネル

タイムラインパネル

ローカルでのアクセス：

http://localhost:8765/graph

SSH 経由でのリモートアクセス：

ssh -L 8765:localhost:8765 user@remote
# Then open http://localhost:8765/graph in your browser

設定：

{
  "env": {
    "MEMORA_GRAPH_PORT": "8765"
  }
}

無効にするには、MCP 設定の args に "--no-graph" を追加します。

グラフ UI の機能

• 詳細パネル - メモリーの内容、メタデータ、タグ、関連するメモリーを表示します
• タイムラインパネル - メモリーを時系列で表示し、クリックするとグラフ内でハイライトします
• 履歴パネル - 連続するエントリーをまとめたすべての操作のログです。クリック可能なメモリー参照も表示されます（削除済みのメモリーには取り消し線が表示されます）
• チャットパネル - ストリーミング応答とクリック可能な [Memory #ID] 参照に対応した、RAG を活用する LLM チャットでメモリーについて質問できます
• タイムスライダー - 日付範囲でメモリーを絞り込み、ドラッグして履歴を確認できます
• リアルタイム更新 - メモリーの変更時に、グラフ、タイムライン、履歴が SSE 経由で更新されます
• フィルター - タグ／セクションのドロップダウン、ズームコントロール
• Mermaid のレンダリング - コードブロックを図としてレンダリングします

ノードの色

• 🟣 タグ - タグに応じた紫色の濃淡
• 🔴 課題 - 赤（未解決）、オレンジ（進行中）、緑（解決済み）、グレー（修正しない）
• 🔵 TODO - 青（未着手）、オレンジ（進行中）、緑（完了）、赤（ブロック中）

ノードのサイズは接続数を示します。

データベースとして Cloudflare D1 を使用する場合、グラフの可視化は Cloudflare Pages でホストされるため、ローカルサーバーは必要ありません。

メリット：

• どこからでもアクセス可能（SSH トンネリング不要）
• WebSocket 経由でリアルタイムに更新
• ?db= パラメーターによる複数データベースのサポート
• Cloudflare Zero Trust による安全なアクセス

セットアップ：

1. D1 データベースを作成：

   npx wrangler d1 create memora-graph
   npx wrangler d1 execute memora-graph --file=memora-graph/schema.sql
   

2. Pages にデプロイ：

   cd memora-graph
   npm run deploy
   

   npm run deploy は最初に scripts/d1_write_guard.py --scope all を実行し、検出事項がある場合はデプロイを拒否します。ガードを回避してしまうため、wrangler pages deploy を直接実行しないでください（docs/local-primary-implementation.md §0 P6）。

3. Cloudflare Dashboard でバインディングを設定：

   • Pages → memora-graph → Settings → Bindings
   • D1 を追加：DB_MEMORA → 使用するデータベース
   • R2 を追加：R2_MEMORA → 使用するバケット（画像用）

4. D1 URI を使ってMCP を設定：

   {
     "env": {
       "MEMORA_STORAGE_URI": "d1://<account-id>/<database-id>",
       "CLOUDFLARE_API_TOKEN": "<your-token>"
     }
   }
   

アクセス先： https://memora-graph.pages.dev

Zero Trust で保護する：

1. Cloudflare Dashboard → Zero Trust → Access → Applications
2. memora-graph.pages.dev のアプリケーションを追加
3. 許可するメールアドレスを指定してポリシーを作成
4. Pages → Settings → Access Policy を有効化

詳しいセットアップ方法と複数データベースの設定については、memora-graph/ を参照してください。

グラフ UI からナレッジベースについて直接質問できます。チャットパネルでは RAG（検索拡張生成）を使用して関連する記憶を検索し、ツール呼び出しに対応した LLM の応答をストリーミングします。

• 右下にあるフローティングチャットアイコンで切り替え
• セマンティック検索で、コンテキストとして最も関連性の高い記憶を検索
• クリック可能な [Memory #ID] 参照付きのストリーミング応答。クリックするとグラフ上のノードにフォーカスします
• ツール呼び出し — LLM はチャットから直接、記憶を作成、更新、削除できます（例：「これを記憶として保存して」、「記憶 #42 を削除して」、「記憶 #10 を次の内容で更新して...」）
• ローカルサーバーと Cloudflare Pages のデプロイの両方で動作します

チャットモデルの設定：

OpenAI 互換 API が必要です（ローカルでは OPENAI_API_KEY + OPENAI_BASE_URL、Cloudflare では OPENROUTER_API_KEY シークレット）。チャットモデルはツールの使用（関数呼び出し）に対応している必要があります。

AI によるセマンティック比較を使用して、重複する記憶を見つけて統合します：

# Find potential duplicates (uses cross-refs + optional LLM analysis)
memory_find_duplicates(min_similarity=0.7, max_similarity=0.95, limit=10, use_llm=True)

# Merge duplicates (append, prepend, or replace strategies)
memory_merge(source_id=123, target_id=456, merge_strategy="append")

LLM 比較では、記憶のペアを分析し、次の内容を返します：

• verdict： "duplicate"、"similar"、または "different"
• confidence：0.0～1.0 のスコア
• reasoning：簡潔な説明
• suggested_action："merge"、"keep_both"、または "review"

OPENAI_BASE_URL 経由で、OpenAI 互換のあらゆるチャット API（OpenAI、OpenRouter、Azure など）で動作します。この LLM 用途では OpenRouter を利用できますが、埋め込みには対応していません。埋め込みは別途設定してください（「セマンティック検索と埋め込み」を参照）。

構造化ドキュメント（調査レポート、アーキテクチャの決定事項、事後分析）を、検索可能なフラグメントツリーとして保存します：

# Store a markdown document — auto-parsed into typed fragments
memory_store_document(
    content="# Research Report\n\n## Evidence Table\n| Claim | Confidence |\n...",
    document_key="research/memora-enhancements-2026-04-08",
    tags=["memora/research"]
)
# Returns: {root_id: 230, fragment_count: 100, node_map: {claim: [...], plan_item: [...], ...}}

# Retrieve the full document or specific fragment types
memory_get_document(document_key="research/memora-enhancements-2026-04-08")
memory_get_document(document_key="...", node_kinds=["claim"], content_mode="full")

# Delete a document and all its fragments
memory_delete_document(document_key="research/memora-enhancements-2026-04-08")

仕組み： パーサーは構造に基づいて Markdown を分割します。表は個々の主張に、番号付きリストは計画項目に、URL リストは参照に、リスクのセクションはリスクのフラグメントになります。各フラグメントは memory_semantic_search で個別に検索でき、ドキュメント全体は 1 つの単位として取得できます。

フラグメントの種類： claim、plan_item、reference、section_chunk、risk

整合性ガード： ドキュメントのフラグメントが誤って変更されないように保護します：

• フラグメントを memory_delete で削除するには force=True が必要です
• memory_merge はフラグメントの統合を拒否します
• memory_absorb は類似性の照合からフラグメントを除外します
• memory_find_duplicates と memory_detect_supersessions はフラグメントをスキップします
• グラフ UI ではフラグメントを非表示にし、ドキュメントのルートノードのみを表示します

一般的な記憶の種類に対応する構造化ツール：

# Create a TODO with status and priority
memory_create_todo(content="Implement feature X", status="open", priority="high", category="backend")

# Create an issue with severity
memory_create_issue(content="Bug in login flow", status="open", severity="major", component="auth")

# Create a section placeholder (hidden from graph)
memory_create_section(content="Architecture", section="docs", subsection="api")

保存された記憶を分析し、実行可能な分析情報を提示します：

# Full analysis with LLM-powered pattern detection
memory_insights(period="7d", include_llm_analysis=True)

# Quick summary without LLM (faster, no API key needed)
memory_insights(period="1m", include_llm_analysis=False)

次の情報を返します：

• アクティビティの概要 — 期間内に作成された記憶を、種類とタグごとに分類
• 未完了項目 — 古い項目の検出機能付きの未完了 TODO と課題（MEMORA_STALE_DAYS で設定可能。memory_insights のデフォルトは 14、グラフ UI のデフォルトは 30 — 同じ変数を 2 つの機能で使用）
• 統合候補 — 統合できる類似した記憶のペア
• LLM による分析 — テーマ、重点分野、ナレッジの不足、要約（OPENAI_API_KEY が必要）

記憶間の関係を管理します：

# Create typed edges between memories
memory_link(from_id=1, to_id=2, edge_type="implements", bidirectional=True)

# Edge types: references, implements, supersedes, extends, contradicts, related_to

# Remove links
memory_unlink(from_id=1, to_id=2)

# Boost memory importance for ranking
memory_boost(memory_id=42, boost_amount=0.5)

# Detect clusters of related memories
memory_clusters(min_cluster_size=2, min_score=0.3)

オフラインで閲覧するには、メモリーを静的な HTML ファイルとしてエクスポートします。

memory_export_graph(output_path="~/memories_graph.html", min_score=0.25)

これは任意です。ライブグラフサーバーでは、リアルタイム更新に対応した同じビジュアライゼーションを利用できます。

Telescope を使って、Neovim から直接メモリーを参照できます。プラグインを設定にコピーします。

# For kickstart.nvim / lazy.nvim
cp nvim/memora.lua ~/.config/nvim/lua/kickstart/plugins/

使い方： <leader>sm を押すと、あいまい検索とプレビュー機能を備えたメモリーブラウザーが開きます。

必要なもの：telescope.nvim、plenary.nvim、および Python 環境にインストールされた memora。