Agentmemory

AgentMemory.fyi

AI エージェント向けのビジュアルメモリーマネージャー。Claude Code、Cursor、Cline、Continue で共有する唯一の信頼できる情報源です。

_{* Vercel でのホスト版プレビューです。メールアドレスまたは GitHub でサインインしてお試しください。データはSupabase RLSによりアカウント内で非公開に保たれます。セルフホストまたはローカル専用モードについては、以下のクイックスタートをご覧ください。}

スクリーンショット

ダッシュボード — 概要統計、最近のメモリー、カテゴリ別の内訳、クイックアクション

メモリーグラフ — インラインのメモリー詳細パネルと、ベクトル距離順に表示される類似メモリー（一致率 98%／97%）を備えた D3 力指向ビュー

エクスポート — ワンクリックで CLAUDE.md、.cursorrules、MemGPT JSON、または共有可能な読み取り専用 URL を出力。ライブプレビューとカテゴリフィルターも利用できます

いつまでも完全無料

AgentMemory は MIT ライセンスのオープンソースです。ペイウォールも、プレミアムプランも、制限もありません。

• 誰でも無料 — メモリー数、プロジェクト数は無制限
• セルフホスト可能 — テレメトリーやロックインなしで、永久にローカルで実行できます
• MCP ネイティブ — Claude Desktop、Cursor、Cline、Continue、Windsurf、Roo Code、Kilo Code、Zed、Aider、Goose、Warp、Codex CLI、Gemini CLI、GitHub Copilot CLI、Qwen Code CLI、Google Antigravity、AWS Kiro、Droid、OpenCode、OpenClaw、pi-mono で Model Context Protocol サーバーとして動作します。以下のAI ツールへの接続をご覧ください。
• ビジュアル — すべてのメモリーとその意味的な関係をグラフで表示
• ポータブル — .cursorrules、CLAUDE.md、MemGPT JSON、Claude Code の .jsonl セッションとのインポート／エクスポート
• 任意のクラウド同期 — サインインすると、Supabase 経由でデバイス間のメモリーを同期できます

プロジェクトを支援する

AgentMemory は空き時間に開発・保守されています。時間の節約に役立った場合は、開発へのご支援をご検討ください。

• DonationAlerts で寄付 — カード、SBP、YooMoney、暗号資産など、100 種類以上の方法
• リポジトリにスターを付ける — 最高の 0 ドル寄付です
• バグの報告や機能のリクエスト
• PR での貢献
• Twitter／Reddit／HackerNews で広める

クイックスタート

Web UI（ローカル専用モード）

npm install
npm run dev
# → http://localhost:5173

バックエンドなしで動作します。メモリーは localStorage（ブラウザー）または ~/.agentmemory/（stdio MCP）に保存されます。

MCP サーバー（stdio、ローカル）

npm run mcp

claude_desktop_config.json で設定します（スクリプトは tsx 経由で mcp/index.ts を実行するため、ビルド手順は不要です）。

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

9 個のツール：add_memory、search_memories、list_memories、find_similar、delete_memory、list_projects、switch_project、get_project_context、import_jsonl、backfill_embeddings。3 個のリソース：agentmemory://rules、agentmemory://graph、agentmemory://projects。完全無料で、ライセンスキーは不要です。

AI ツールに接続する

AgentMemory は、同じ MCP サーバーを 2 つのモードで公開します。

• ローカル stdio — tsx を使って mcp/index.ts を実行します。エージェントプロセスが子プロセスとして呼び出します。マシンのファイルシステムにアクセスできるデスクトップツールに最適です。
• クラウド HTTP — https://<your-host>/mcp にあるストリーミング HTTP エンドポイントです（Vercel のデフォルト）。ホスト型ツール、ウェブクライアント、複数のマシン間で同じメモリを共有する場合に最適です。ユーザーの Supabase JWT は Authorization: Bearer <jwt> に指定します。

以下のスニペットでは、クローン先が /absolute/path/to/agentmemory であることを前提としています。ローカル stdio コマンドは tsx で MCP サーバーを直接実行するため、ビルド手順は不要です。

繰り返し使用する 2 つの参考スニペット

// LOCAL — stdio
{
  "command": "npx",
  "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
  "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
}

// CLOUD — HTTP
{
  "url": "https://your-app.vercel.app/mcp",
  "headers": { "Authorization": "Bearer <supabase-jwt>" }
}

Supabase JWT を取得するには、ホスト型 AgentMemory ウェブ UI にサインインし、DevTools で JSON.parse(localStorage.getItem('sb-<project>-auth-token') || 'null') を実行して、access_token をコピーします。JWT の有効期限は約 1 時間です。セッションごとにコマンドを再実行して更新してください。

目次

#	ツール	設定ファイル	モード
1	Claude Desktop	claude_desktop_config.json	stdio / http
2	Cursor	.cursor/mcp.json	stdio / http
3	Cline	Cline サイドバー → MCP Servers	stdio / http
4	Continue	~/.continue/config.yaml	stdio / http
5	Roo Code	.roo/mcp.json	stdio / http
6	Kilo Code	Kilo サイドバー → MCP Servers	stdio / http
7	Windsurf	~/.codeium/windsurf/mcp_config.json	stdio / http
8	Zed	~/.config/zed/settings.json	stdio / http
9	Aider	--mcp-server フラグ	stdio
10	Goose	~/.config/goose/config.yaml	stdio / http
11	Warp	Warp Drive → MCP Servers	stdio / http
12	OpenAI Codex CLI	~/.codex/config.toml	stdio / http
13	Google Gemini CLI	~/.gemini/settings.json	stdio / http
14	GitHub Copilot CLI	~/.config/github-copilot/mcp.json	stdio / http
15	Qwen Code CLI	~/.qwen/settings.json	stdio / http
16	Google Antigravity	.antigravity/mcp.json	stdio / http
17	AWS Kiro	.kiro/settings/mcp.json	stdio / http
18	Droid (Factory)	~/.droid/mcp.json	stdio / http
19	OpenCode	opencode.json / ~/.config/opencode/config.json	stdio / http
20	OpenClaw & pi-mono	~/.openclaw/openclaw.json / ~/.pi/config.json	stdio / http

---

1. Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（mac） · %APPDATA%\Claude\claude_desktop_config.json（win） · ~/.config/Claude/claude_desktop_config.json（linux）。

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

Claude Desktop を再起動します。コネクターパネルに 9 個の 🔧 ツールと 3 個の 📄 リソースが表示されます。

---

2. Cursor

ワークスペース内の .cursor/mcp.json（プロジェクトごと）、または ~/.cursor/mcp.json（グローバル）。

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

Cursor Settings → Features → MCP を開きます。サーバーが表示されない場合は Refresh をクリックします。

---

3. Cline

VSCode 拡張機能です。Cline サイドバー → ⚙️ Settings → MCP Servers → Configure MCP Servers を開き、cline_mcp_settings.json を編集します。

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" },
      "disabled": false
    }
  }
}

Cline は保存時にファイルを自動で再読み込みします。チャット内の 🔧 アイコンの下にメモリツールが表示されます。

---

4. Continue

~/.continue/config.yaml（YAML；Continue 1.0 以降）：

mcpServers:
  - name: agentmemory
    command: npx
    args:
      - tsx
      - /absolute/path/to/agentmemory/mcp/index.ts
    env:
      AGENTMEMORY_HOME: /absolute/path/to/storage

クラウドモードの場合は、transport: http と url、headers に置き換えてください（Continue MCP docs を参照）。

---

5. Roo Code

ワークスペース内の .roo/mcp.json、または Roo サイドバー → MCP → Edit Global MCP から設定します。

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

---

6. Kilo Code

Kilo は OpenCode のフォークなので、同じスキーマを使用できます。Kilo のサイドバー → MCP Servers → Edit Global MCP を開くか、ワークスペース内の .kilocode/mcp.json を開きます。

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

クラウドモードでは、エントリーを { "url": "https://...", "headers": { "Authorization": "Bearer ..." } } に置き換えます。

---

7. Windsurf

~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

再起動後、Windsurf Settings → Cascade → MCP Servers に表示されます。

---

8. Zed

~/.config/zed/settings.json（注：Zed では mcpServers ではなく context_servers を使用します）：

{
  "context_servers": {
    "agentmemory": {
      "command": {
        "path": "npx",
        "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
        "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
      }
    }
  }
}

クラウドモードでは、command の代わりに "settings": { "url": "https://...", "headers": { "Authorization": "Bearer ..." } } を使用します。Zed のコンテキストサーバーのドキュメントを参照してください。

---

9. Aider

Aider 0.73+ で MCP が追加されました。コマンドラインでサーバーを指定します（サーバーごとに --mcp-server を 1 つ指定します）：

aider --mcp-server "npx tsx /absolute/path/to/agentmemory/mcp/index.ts AGENTMEMORY_HOME=/path/to/storage"

または、~/.aider.conf.yml に記述します：

mcp-servers: |
  agentmemory: npx tsx /absolute/path/to/agentmemory/mcp/index.ts AGENTMEMORY_HOME=/path/to/storage

Aider は起動時に利用可能なツールを一覧表示します。チャットでは /tool agentmemory__add_memory ... を使って参照します。

---

10. Goose

~/.config/goose/config.yaml — extensions は Goose での MCP サーバーの呼び名です：

extensions:
  agentmemory:
    type: stdio
    cmd: npx
    args: ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"]
    envs:
      AGENTMEMORY_HOME: /absolute/path/to/storage
    enabled: true

クラウドモード：type: streamable_http、uri: https://your-app.vercel.app/mcp、headers.Authorization: "Bearer <jwt>"、envs: {} を設定します。

---

11. Warp

Warp Drive → Settings → AI → Manage MCP Servers → + Add：

フィールド	値
名前	agentmemory
コマンド	npx tsx /absolute/path/to/agentmemory/mcp/index.ts
環境変数	AGENTMEMORY_HOME=/absolute/path/to/storage

Warp は、マシン間の同期用に ~/.warp/mcp_config.json にも対応しています。Claude Desktop と同じ mcpServers スキーマを使用します。

---

12. OpenAI Codex CLI

~/.codex/config.toml：

[mcp_servers.agentmemory]
command = "npx"
args = ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"]
env = { AGENTMEMORY_HOME = "/absolute/path/to/storage" }

クラウドでは、テーブルを次の内容に置き換えます：

[mcp_servers.agentmemory]
url = "https://your-app.vercel.app/mcp"
http_headers = { Authorization = "Bearer <supabase-jwt>" }

codex mcp list で確認します。

---

13. Google Gemini CLI

~/.gemini/settings.json：

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

サーバーごとに trust: true が設定されている場合、デフォルトで信頼されます。Gemini CLI の MCP ドキュメントを参照してください。

---

14. GitHub Copilot CLI

新しい copilot CLI（旧 gh copilot を置き換えるもの）です。~/.config/github-copilot/mcp.json：

{
  "mcpServers": {
    "agentmemory": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

または、実行時にインラインで指定します：copilot --additional-mcp-config @/absolute/path/to/config.json。チャットでは、ツール名に agentmemory__ が自動的に付加されます。

---

15. Qwen Code CLI

Alibaba の qwen CLI（Qwen3-Coder）です。~/.qwen/settings.json（ビルドによっては ~/.qwen-cli/settings.json）：

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

---

16. Google Antigravity

ワークスペース内の .antigravity/mcp.json（プロジェクトごと）、または ~/.antigravity/mcp.json（グローバル）：

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

クラウドモード：{ "url": "https://your-app.vercel.app/mcp", "headers": { "Authorization": "Bearer <supabase-jwt>" } } に置き換えます。Antigravity はワークスペースを開くとファイルを読み込みます。

---

17. AWS Kiro

ワークスペース内の .kiro/settings/mcp.json（プロジェクトごと）、または ~/.kiro/settings/mcp.json（グローバル）：

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

サーバーに接続できない場合、Kiro Settings → MCP Servers に更新ボタンが表示されます。

---

18. Droid (Factory)

~/.droid/mcp.json（グローバル）、または .factory/mcp.json（プロジェクトごと）：

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

droid mcp list を実行して、読み込まれたことを確認します。TUI では、@agentmemory を使ってツールを呼び出します。

---

19. OpenCode

プロジェクトのルートにある opencode.json、またはグローバル設定用の ~/.config/opencode/config.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agentmemory": {
      "type": "local",
      "command": ["npx", "tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "environment": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" },
      "enabled": true
    }
  }
}

クラウドモードでは、"type": "remote"、"url": "https://your-app.vercel.app/mcp"、"headers": { "Authorization": "Bearer <supabase-jwt>" } に置き換えます。プロンプト内で use the agentmemory tool と記述して参照します。

20. OpenClaw と pi-mono

これらはコーディング IDE ではなく、個人向けの AI アシスタントです。MCP サーバーをスキルとして受け入れるため、AgentMemory がアシスタントの長期記憶になります。

OpenClaw — ~/.openclaw/openclaw.json：

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

openclaw gateway restart でゲートウェイを再起動します。Telegram／WhatsApp／Discord では、アシスタントがセッションをまたいで永続的な記憶を利用できるようになります。「ダークモードが好みだと覚えておいて」と伝えると、その情報が記憶されます。

pi-mono（Mario Zechner による pi CLI）— ~/.pi/config.json：

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/agentmemory/mcp/index.ts"],
      "env": { "AGENTMEMORY_HOME": "/absolute/path/to/storage" }
    }
  }
}

pi を実行し、エージェントに search_memories を使って以前のコンテキストを検索するよう依頼します。

---

トラブルシューティング

症状	対処方法
mcp/index.ts で ENOENT が発生する	絶対パスを使用してください。JSON 内では ~ は展開されません
command not found: tsx	npm i -g tsx を実行するか、npx tsx を node --import tsx に置き換えてください
ツールが表示されない	クライアントを再起動してください。Cline、Kilo、Roo などでは「有効にする」切り替えを明示的に操作する必要があります
クラウドで 401 Unauthorized が発生する	JWT の有効期限が切れています。ウェブ UI の DevTools の localStorage からコピーし直してください
クラウドで 429 Too Many Requests が発生する	RATE_LIMIT_PER_HOUR に達しています。backfill_embeddings を使って待つか、間隔を空けて再試行してください
Cannot find module '@modelcontextprotocol/...' が発生する	agentmemory リポジトリのルートで npm install を実行してください

機能

記憶の減衰とアクセス追跡

記憶は指数減衰曲線（strength = 0.5^(days/30) × importance/5）に従い、読み取られるたびに強度が増します。各記憶は次の4つのティアのいずれかに分類され、カード上に色付きのバッジで表示されます。

ティア	強度	色	意味
hot	≥ 0.70	赤	最近作成された、または頻繁にアクセスされている
warm	≥ 0.40	琥珀色	依然として関連性がある
cold	≥ 0.15	青	薄れつつありますが、コンテキストのために保持されています
dead	< 0.15	グレー	自動削除候補

• runAutoForget() はアプリの起動時に実行され、次のいずれかに該当する記憶を削除します。TTL の期限切れ、または (strength < 0.05 AND access_count < 3)、または (importance ≤ 2 AND age > 180 days)。
• MemoryCard はマウント時に touchMemory(id) を呼び出し、access_count を増やして last_accessed_at を更新します。
• すべてのバックエンドで保持されます。ローカル（zustand）および Supabase（Postgres の strength 列と useAuth からの runAutoForget）で利用できます。

ハイブリッド検索（BM25 + ベクトル + RRF によるグラフ検索）

3 つのソースは、src/utils/rrf.ts で Reciprocal Rank Fusion（k=60）を使って統合されます。

ソース	重み	実行場所	実装
ベクトル（コサイン）	0.6	サーバー（クラウド）／ローカル	pgvector + HuggingFace Inference API、384 次元の MiniLM-L6-v2（無料、クレジットカード不要）
BM25	0.4	両方	pg_trgm のトライグラム類似度（サーバー）または Porter ステミング済み転置インデックス（ローカル）
グラフ	0.3	両方	relations テーブル（サーバー）またはメモリー内エッジ（ローカル）を通じた 1 ホップの展開

各ソースの上位結果を RRF(d) = Σᵢ wᵢ / (k + rankᵢ(d)) で結合し、上位 N 件を返します。ローカルの BM25 インデックスは (count, max(updated_at)) をキーにキャッシュし、追加／更新／削除／自動削除のたびに無効化されます。

クラウド MCP でセマンティック検索を有効にする — huggingface.co に登録し（無料）、https://huggingface.co/settings/tokens で読み取りトークンを取得して、Vercel に HUGGINGFACE_API_KEY を設定します。api/mcp.ts のサーバーレスハンドラーは createHuggingFaceEmbedder(token) をインスタンス化し、SupabaseBackend に注入します。add_memory ではコンテンツがベクトル化され、vector(384) として保存されます。search_memories ではクエリがベクトル化され、semantic_search_memories RPC が HNSW インデックスを使ってコサイン検索を行います。

キーがなくてもサーバーは動作します。ただし、ベクトルソースをスキップするため、RRF は 2 つのソース（BM25 + グラフ）になります。

既存のメモリーの一括更新 — ベクトライザーを有効にした後も、既存の行の embedding = NULL はそのままです。remaining = 0 になるまで、backfill_embeddings MCP ツールを繰り返し実行します。

backfill_embeddings({ limit: 64 })
backfill_embeddings({ limit: 64 })
…

各呼び出しでは ⌈N/32⌉ 回の埋め込み API 呼び出しが発生し、ユーザーごとのレート制限が適用されます。60 秒のサーバーレスタイムアウトでは、1 回の実行につき HF バッチを約 3 回、つまり約 96 件のメモリーを処理できます。

レート制限 — Supabase スキーマでは api_rate_limits テーブルと consume_rate_limit(p_user_id, p_cost, p_max) RPC が追加されます。埋め込み API 呼び出し（検索クエリ、メモリーの挿入、一括更新のバッチ）ごとに、スライディング 1 時間ウィンドウから ceil(texts/32) 単位がアトミックに消費されます。デフォルトの上限は RATE_LIMIT_PER_HOUR=100 です。これにより、HF の月間 30,000 回の無料枠内で、約 30 人のアクティブユーザーに十分な余裕が生まれます。無効にするには環境変数を 0 に設定します。上限に達すると、MCP 呼び出しは正確なリセット時刻を含む isError: true を返します。

Claude Code セッションからの JSONL インポート

Claude Code のセッションファイル（~/.claude/projects/-my-project/<uuid>.jsonl）をインポートページにドロップするか、MCP の import_jsonl ツールを呼び出します。パーサーは次の処理を行います。

1. 1 行につき 1 つの JSON オブジェクトを読み込みます
2. tool_use／tool_result ブロックを除外します（user／assistant メッセージのみ保持）
3. ユーザーメッセージをフィルタリングします。20～600 文字に限定し、システムリマインダーとシェルコマンド（ok、./run-build.sh など）を除外します
4. 正規表現のヒントを使って自動分類します。優先順位は decision > constraint > preference > architecture > context（デフォルト）です
5. #hashtags とファイル拡張子のヒント（*.ts → typescript）からタグを抽出します
6. 1 ファイルあたりのメモリー数を 200 件に制限します

MCP の使用方法（stdio モードと HTTP モードの両方で動作します）。

{
  "name": "import_jsonl",
  "arguments": {
    "path": "/Users/you/.claude/projects/-my-project/abc123.jsonl"
  }
}

{ imported: N, total: M, user_messages: K, accepted: K } を返します。

クラウド同期（Supabase + Vercel）

約 5 分で独自のプライベート同期バックエンドを実行できます。

1. Supabase プロジェクトを作成する

1. supabase.com にアクセスし、New project を選択します
2. プロビジョニング後、SQL Editor を開き、supabase/schema.sql の内容を貼り付けて Run を選択します
   • スキーマは初回実行時に pgvector 拡張機能を有効にし、embedding vector(384) 列と HNSW インデックスを作成します
3. Authentication → Providers で Email（マジックリンク）と GitHub（任意。手順については下記の §1a を参照）を有効にします
4. Settings → API で Project URL と anon キーをコピーします
5. （セマンティック検索を使う場合は任意）huggingface.co に登録し、https://huggingface.co/settings/tokens で読み取りトークンを作成します

1a. GitHub ログインを有効にする（任意）

GitHub ログインは認証ページでワンクリックで利用でき、メールのマジックリンクを経由する手間を省けます。設定は約5分で完了します。

手順 1 — GitHub OAuth App を作成する

1. https://github.com/settings/developers に移動 → New OAuth App
2. 次の項目を入力します。
   • Application name：AgentMemory（または任意の名前）
   • Homepage URL：デプロイ先の URL（例：https://agentmemory-dusky.vercel.app）、またはローカル開発の場合は http://localhost:5173
   • Authorization callback URL：次の手順で Supabase からコピーします。あとで編集するため、ここに戻ってきます
3. Register application をクリックします
4. 次のページで Generate a new client secret をクリックします。Client ID と Client secret をコピーします（シークレットは再表示できません）

手順 2 — Supabase に接続する

1. Supabase Dashboard に戻り、Authentication → Providers → GitHub を開きます
2. Enable Sign in with GitHub をオンにします
3. 手順 1 の Client ID と Client Secret を貼り付けます
4. Save をクリックします
5. Authentication → URL Configuration で、サイトの URL を Site URL と Additional Redirect URLs に追加します。
   • http://localhost:5173（開発）
   • https://your-app.vercel.app（本番環境）
6. Supabase にプロジェクトの正式な Callback URL が表示されます。https://<project-ref>.supabase.co/auth/v1/callback のような形式です。GitHub OAuth App に戻り、これを Authorization callback URL に貼り付けます

手順 3 — テストする

アプリで /auth を開き → Continue with GitHub をクリックします → GitHub に移動するので、承認すると、ログインした状態でアプリに戻ります。サイドバーのアバターが GitHub のプロフィール画像に切り替わり、左下に Sign out ボタンが表示されます。

セルフホスト時の注意点：配信する各カスタムドメインを Supabase の Additional Redirect URLs に追加する必要があります。追加しないと、OAuth によって redirectTo パラメーターが拒否されます。これを省略すると、Supabase は redirect_uri not in allowlist エラーを返します。

2. 環境を設定する

public/.env.example を .env にコピーします（または Vercel で変数を設定します）。

VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGc...
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=eyJhbGc...
# Optional: enables pgvector semantic search via HuggingFace Inference API (free tier)
HUGGINGFACE_API_KEY=hf_xxxxxxxxxxxxxxxxxxxxxxxx
# Optional: per-user embedding rate limit (default 100/hr, protects HF free tier)
RATE_LIMIT_PER_HOUR=100
# Service role key NOT used — RLS scopes everything to auth.uid()

3. Vercel にデプロイする

npm i -g vercel
vercel
# accept defaults; add the SUPABASE_* env vars when prompted

Web アプリは、ルートにある静的な単一ファイルビルド（dist/index.html）です。 MCP サーバーは、/mcp および /api/mcp でサーバーレス関数として公開されます。

4. リモート MCP を使用する

クライアント（Claude Desktop、Cursor、カスタムクライアント）は、HTTP 経由でホストされた MCP サーバーに接続できます。ユーザーの Supabase JWT を Authorization: Bearer <jwt> ヘッダーに含めて送信します。

{
  "mcpServers": {
    "agentmemory-cloud": {
      "url": "https://your-app.vercel.app/mcp",
      "headers": {
        "Authorization": "Bearer <supabase-access-token>"
      }
    }
  }
}

この関数は Supabase 経由で JWT を検証し、RLS を使用して Postgres にクエリを実行するため、各ユーザーには自分のデータのみが表示されます。ユーザーのリクエストにサービスロールキーは必要ありません。RLS が処理します。

アーキテクチャ

src/
  store/memoryStore.ts        # Zustand store + pure logic helpers (hybridSearch, decay)
  utils/
    bm25.ts                   # BM25 inverted index
    rrf.ts                    # Reciprocal Rank Fusion
    stemmer.ts                # Compact Porter stemmer
    memoryDecay.ts            # calculateStrength, tierOf, touchMemory, runAutoForget
    jsonlImport.ts            # Claude Code session parser
  lib/supabase.ts             # Supabase browser client
  lib/cloudSync.ts            # Pull/push helpers used by memoryStore
  hooks/useAuth.ts            # Wires Supabase auth state to the store
  components/
    MemoryCard.tsx            # Tier badge + touch-on-mount
    Layout.tsx                # Sidebar with sign-in / cloud status
  pages/
    AuthPage.tsx              # Magic-link + GitHub OAuth sign-in
    ImportPage.tsx            # .jsonl + .md/.txt/.cursorrules dropzone
    SupportPage.tsx           # Donate CTA

mcp/
  server.ts                   # Transport-agnostic MCP server (9 tools + 3 resources)
  embeddings.ts               # HuggingFace Inference API wrapper (MiniLM-L6-v2, 384-dim)
  backends/
    local.ts                  # Reads/writes the zustand store on disk
    supabase.ts               # RRF search (BM25+vector+graph), embeds on add, RLS-scoped via caller's JWT
  index.ts                    # Stdio entrypoint (uses LocalBackend)

api/
  mcp.ts                      # Vercel serverless handler (Streamable HTTP)

supabase/
  schema.sql                  # Tables, RLS policies, search_memories / find_similar_memories RPCs

ローカルモードとクラウドモードは、同じ Memory 型と同じ memoryStore アクションを共有します。違いは、変更が Supabase にも反映されるかどうかだけです。

開発

npm run dev                 # Vite dev server
npm run build               # Production web build
npm run mcp                 # Run stdio MCP server (tsx, no build step)
npm run typecheck:mcp       # tsc --noEmit on the MCP workspace
npx tsc --noEmit            # tsc --noEmit on the web workspace

ライセンス

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