cognitive-ai-memory

---

問題点

毎朝、あなたのAI エージェントは初対面のようにあなたに接します。同じ背景情報を何度も説明し、同じ好みを何度も忘れます。セッションが始まるたびに、すべてがゼロからのスタートです。

多くの「メモリー」ツールは、エージェントにベクトルデータベースを追加して、それで完成としています。しかし、それは単なる保存にすぎません。ほぼ重複した情報を溜め込み、検索がノイズに埋もれてしまいます。金魚鉢を大きくしただけです。

YourMemoryは違います。データベースではなく、脳のように機能するメモリーです。

flowchart LR
    A["🧠 You tell your<br/>AI something"] --> B["Extract durable<br/>facts"]
    B --> C["Dedup + embed<br/>+ graph-link"]
    C --> D[("Memory<br/>store")]
    D -->|"related facts pile up"| E["✨ Consolidate<br/>N → 1 summary"]
    D -->|"stale + unused"| F["📉 Decay<br/>+ prune"]
    D -->|"new session"| G["♻️ Recall<br/>hybrid + graph"]
    E --> D
    G --> H["🤖 Your agent<br/>picks up where<br/>it left off"]
    style D fill:#0a2540,stroke:#19cdff,color:#fff
    style E fill:#0c2b3a,stroke:#5eead4,color:#fff
    style H fill:#0c2b3a,stroke:#19cdff,color:#fff

---

✨ 他とは違う特長

	機能	内容
🧠	統合	関連する事実が十分に蓄積されると、それらを簡潔な要約にまとめ、元の情報はアーカイブします。メモリーは膨れ上がるのではなく、時間とともに研ぎ澄まされます。
📉	生物学的な減衰	すべてのメモリーはエビングハウスの忘却曲線に沿って古くなります。古くて使われない事実は薄れ、重要で頻繁に思い出される事実は保持されます。
🔗	エンティティグラフ	メモリーは共通する人物、場所、概念を介してつながるため、尋ねるのを忘れていたことも想起できます。
♻️	コンテキストリセット後も保持	コンテキストウィンドウが圧縮されると、YourMemoryは作業中のコンテキストを引き継ぎます。現在の作業状況を把握するためにファイルを読み直す必要はありません。
🔒	改ざんを検知できる監査証跡	読み取り、書き込み、削除のすべてがハッシュチェーン台帳に記録されます。1件でも記録を変更すると、チェーンが壊れます。
👥	チーム共有メモリープール	ロールベースの共有メモリーにより、チーム全体のエージェントが同じ組織知識を利用できます。プライベートなメモリーは非公開に保たれます。
🛡️	データに関する権利を組み込み済み	1つのコマンドでエクスポート（アクセス権）と忘れられる権利（消去）を実行でき、SOC 2に準拠した管理機能も備えています。
🔌	MCPネイティブかつローカル優先	Claude、Cursor、Cline、Windsurf、その他あらゆるMCPクライアントで動作します。すべてマシン上で実行され、APIキーは不要で、システム外にデータが送信されることもありません。

1つのコマンドでインストールできます。デフォルトはDuckDB（セットアップ不要）、チーム向けにはPostgres + pgvectorを利用できます。

---

目次

• 🏆 ベンチマーク
• 🚀 クイックスタート
• 🧠 メモリの仕組み
  • 統合
  • 減衰
  • ハイブリッド検索
• 🔒 信頼と監査証跡
• 👥 チームメモリプール
• 🛡️ データの権利とコンプライアンス
• 🎛️ ダッシュボード
• 🔧 MCP ツール
• ⚡ LLM 呼び出しなしで質問する
• 🔀 API プロキシ — メモリを確実に利用
• 🏗️ アーキテクチャとスタック
• 🩺 トラブルシューティング
• 🤝 コントリビューション

---

🏆 ベンチマーク

3 つの外部データセットを使用しています。すべての数値は独立して再現可能です — ベンチマークのコードはリポジトリ内にあります。詳しい方法論については、BENCHMARKS.mdをご覧ください。

LoCoMo-10 — 複数セッションの会話メモリ

xychart-beta
    title "Recall@5 · LoCoMo-10 (higher is better)"
    x-axis ["Mem0", "Zep Cloud", "Supermemory", "YourMemory"]
    y-axis "Recall@5 percent" 0 --> 70
    bar [18, 28, 31, 59]

すべての 10 サンプルで、Zep Cloud よりも想起率が 2 倍優れています。*Supermemory と Mem0 はベンチマークの途中で無料枠の上限に達したため、スコアは全 1,534 ペアを対象に算出しています。

LongMemEval-S — 500 問、各問につき約 53 の妨害セッション

長期メモリに関する最も難しい標準ベンチマークです。各質問は約 53 のセッションに埋もれています。

指標	スコア
Recall@5（正解セッションが上位 5 件に含まれる割合）	89.4%
Recall-all@5（すべての正解セッションが上位 5 件に含まれる割合）	84.8%
nDCG@5（ランキング品質）	87.4%

HotpotQA — 200 件のマルチホップ質問

システム	BOTH_FOUND@5
YourMemory（ベクトル + BM25 + エンティティグラフ）	71.5%
YourMemory（エンティティエッジなし）	59.5%

エンティティグラフのエッジによって +12 ポイント向上します — Fact 2 のクエリに対する埋め込み類似度が低い場合でも、Fact 1 から Fact 2 へたどることができます。

解説記事：エビングハウスの忘却曲線を使って、AI エージェント向けのメモリ減衰を構築しました

---

🚀 クイックスタート

Python 3.11–3.14。Docker もデータベースのセットアップも不要です。すべてのメモリはローカルの ~/.yourmemory/ に保存されます。

pip install yourmemory
yourmemory-register <your-token>
yourmemory-setup

トークンの取得： yourmemoryai.xyz にアクセス → メールアドレスを入力 → 6 桁のコードで認証 → トークンをコピーします。

yourmemory-setup は Claude Code、Claude Desktop、Cursor、Windsurf、Cline を自動検出して設定し、使用するバックエンドを尋ねます。

• DuckDB — セットアップ不要の単一ローカルファイル (デフォルト)
• Postgres — 共有環境／本番環境向け。DATABASE_URL を指定します（pgvector 拡張機能が必要です）

オプション — より高精度なローカル抽出： YourMemory は組み込みのヒューリスティックですぐに利用できます。より高品質な完全ローカルの事実抽出を行うには、Ollama をインストールしてください。yourmemory-setup がモデル（qwen2.5:7b、約 4.7 GB）を自動的に取得します。クラウドを利用する場合は、YOURMEMORY_EXTRACT_BACKEND=anthropic を設定してください。

またはバイナリからインストール — Python は不要です

pip を使いたくない場合は、最新リリースからお使いのプラットフォーム向けのスタンドアロンバイナリを入手してください。

プラットフォーム	アセット
macOS (Apple Silicon)	yourmemory-macos-arm64.tar.gz
macOS (Intel)	yourmemory-macos-x86_64.tar.gz
Linux (x86-64)	yourmemory-linux-x86_64.tar.gz
Windows (x86-64)	yourmemory-windows-x86_64.exe.zip

# macOS / Linux — download, extract, run
tar -xzf yourmemory-macos-arm64.tar.gz
./yourmemory-macos-arm64 register <your-token>
./yourmemory-macos-arm64 setup
./yourmemory-macos-arm64            # start the server

1 つの実行ファイルですべてのコマンドに対応します。register、setup、ask "<question>"、path を実行でき、引数を指定しない場合はサーバーが起動します。

完全に自己完結しており、オフラインで動作します — バイナリには Python、すべての依存関係、さらに両方の ML モデル（埋め込みモデルと spaCy）が含まれています。初回起動時にダウンロードされるものはありません。トレードオフはファイルサイズ（約 2 GB）です。./build-binary.sh を実行するだけで独自のバイナリをビルドでき、ビルドワークフローによってマルチプラットフォーム対応のリリースバイナリが自動生成されます。

---

🧠 メモリの仕組み

YourMemory はメモリを生きたシステムとして扱います。脳と同じように、成長し、統合され、忘れ、つながります。

統合 — N → 1

ほとんどのメモリツールは増え続けるだけです。YourMemory は関連する事実の集まりを検出し、十分に蓄積されると、それらをすっきりとした単一の要約に圧縮します。元の内容はアーカイブされるため、削除されることはなく、何も失われません。

flowchart LR
    subgraph before [Related facts pile up]
        A1["Railway uses Nixpacks"]
        A2["Railway on Pro plan"]
        A3["Railway env vars hold<br/>the Postgres URL"]
        A4["Deploys on Railway<br/>with Postgres"]
    end
    before --> C{"cluster +<br/>LLM summarize"}
    C --> S["✨ Summary<br/>Deploys on Railway (Pro,<br/>Nixpacks) with Postgres<br/>via env vars"]
    C -.->|"archived, recoverable"| ARC[("archive")]
    style S fill:#0a2540,stroke:#5eead4,color:#fff
    style C fill:#0c2b3a,stroke:#19cdff,color:#fff

本番環境のストアでの実例：444 件のメモリ → 16 件の要約。同じ知識を、ノイズを大幅に減らして保持できます。統合はイベント駆動型（関連するメモリが蓄積したときに実行）であり、毎晩無条件に実行されるジョブではありません。

減衰 — 忘却曲線

メモリの強度は指数関数的に減衰します。重要度と想起頻度によって、減衰が遅くなります。

effective_λ  = base_λ × (1 − importance × 0.8)
strength     = clamp(importance × e^(−effective_λ × active_days) × (1 + recall_count × 0.2), 0, 1)

active_days は、あなたが活動した日のみを数えます。休暇を取ってもメモリは失われません。強度が 0.05 を下回ったメモリは自動的に整理されます。各カテゴリはそれぞれ異なる速度で古くなります。

カテゴリ	半減期	適した内容
strategy	約 38 日	うまくいったパターン、アーキテクチャ上の決定
fact	約 24 日	好み、アイデンティティ、安定した知識
assumption	約 19 日	推定された文脈、不確かな信念
failure	約 11 日	エラー、誤ったアプローチ、環境固有の問題

**つながりを考慮した整理：**減衰したメモリでも、グラフ上の隣接ノードのいずれかがまだ強い場合は保持されます。直接問い合わせる頻度が低くても、土台となる文脈は残ります。

ハイブリッド検索 — ベクトル + BM25 + グラフ

想起は 2 回のラウンドで実行され、尋ねた内容と、尋ね忘れた内容の両方を提示します。

flowchart LR
    Q["query"] --> R1["Vector + BM25<br/>hybrid search"]
    R1 --> R2["Graph expansion<br/>(what you forgot to ask)"]
    R2 --> S["rank by<br/>similarity × strength"]
    S --> OUT["🎯 Ranked memories"]
    style OUT fill:#0a2540,stroke:#19cdff,color:#fff

主体を考慮した重複排除は、保存のたびに実行されます。各文の主体を埋め込み表現にすることで、"Sachit uses DuckDB" と "YourMemory uses DuckDB" は（対象エンティティが異なるため）別々に保持され、"YourMemory uses DuckDB" と "YourMemory stores data in DuckDB" は（同じエンティティを指すため）統合されます。単語リストのハードコードはなく、あらゆる言語に一般化できます。

---

🔒 信頼性と監査証跡

企業は、仕組みの見えないブラックボックスにデータを保存させることはできません。そのため、読み取り、書き込み、更新、削除、統合のすべての操作が、ハッシュチェーンで保護された改ざん検知可能な監査ログに追記されます。

flowchart LR
    E0["GENESIS"] --> E1
    subgraph E1 [Event 1]
        H1["row_hash =<br/>sha256(prev + data)"]
    end
    E1 --> E2
    subgraph E2 [Event 2]
        H2["row_hash =<br/>sha256(#1.hash + data)"]
    end
    E2 --> E3
    subgraph E3 [Event 3]
        H3["row_hash =<br/>sha256(#2.hash + data)"]
    end
    E3 --> V{"GET /audit/verify"}
    V -->|chain intact| OK["✅ verified"]
    V -->|any row altered| BAD["❌ chain breaks<br/>at that row"]
    style OK fill:#0a2540,stroke:#5eead4,color:#fff
    style BAD fill:#3a0c14,stroke:#fb7185,color:#fff

各行には、タイムスタンプ、実行者のユーザーとエージェント、アクション、操作、対象のメモリ、ソース（http と mcp のいずれか）、および直前の行のハッシュが記録されます。過去の記録が変更されると、verify_chain() がチェーンの破損箇所を正確に特定します。

GET  /audit            # browse the trail (filter by user / action / operation)
GET  /audit/verify     # cryptographically verify the chain is untampered
POST /audit/prune      # retention-based cleanup (90-day minimum, never lower)

監査ログはフェイルオープンで、メモリ操作を妨げることはありません。また、ダッシュボード自身の描画ループによる読み取り／一覧表示イベントは除外されるため、監査証跡にはノイズではなく有用な情報が残ります。

---

👥 チーム共有メモリプール

個人のプライベートな文脈を漏らすことなく、チーム全体のエージェントが共有の頭脳を使えるようにします。メモリは共有（プール内で閲覧可能）またはプライベート（所有者のみ閲覧可能）のいずれかです。

flowchart TB
    P(("🧠 Team Pool<br/>shared memory"))
    A["Alice's agent"] <-->|shared| P
    B["Bob's agent"] <-->|shared| P
    C["Carol's agent"] <-->|shared| P
    A -. private .-> AP["🔒 Alice-only"]
    B -. private .-> BP["🔒 Bob-only"]
    style P fill:#0a2540,stroke:#19cdff,color:#fff
    style AP fill:#0c1424,stroke:#5a6b80,color:#8294a8
    style BP fill:#0c1424,stroke:#5a6b80,color:#8294a8

エージェントごとにロールベースのアクセス制御が適用されます。あるエンジニアのエージェントが学んだことは、チーム全体がすぐに活用でき、機密性の高い文脈は所有者の範囲内に保たれます。

POST   /pools                          # create a pool
POST   /pools/{id}/members             # add a member (with role)
POST   /pools/{id}/memories            # contribute a shared memory
POST   /pools/{id}/retrieve            # recall across the pool

---

🛡️ データの権利とコンプライアンス

実データを保存するメモリを安心して使うには、それを支える管理機能が必要です。

権利	エンドポイント	機能
アクセス（DSAR エクスポート）	GET /users/{id}/export	ユーザーについて保存されたすべてのデータをエクスポート
消去（忘れられる権利）	DELETE /users/{id}/memories	1 つのコマンドでユーザーのメモリを一括消去
データポータビリティ	POST /users/{id}/import	以前のエクスポートを再インポート
復元可能性	GET /users/{id}/archive	統合時に置き換えられた元のデータを取得

ハッシュチェーンで保護された監査証跡と 90 日間の最低保持期間を組み合わせることで、これらは SECURITY.md（SOC 2 に準拠）に記載された管理策に直接対応します。

---

🎛️ ダッシュボード

ブラウザーで使える組み込み UI が 2 つあります。追加の設定は不要で、サーバーとともに自動的に起動します。

メモリダッシュボード — http://localhost:3033/ui

Memories・Audit・Pools タブを備えた、読み取りと書き込みの両方に対応するビューです。統計バー（Strong／Fading／Near-prune）、エージェント別タブ、強度をリアルタイムで表示するメモリカード、カテゴリーフィルター、監査ログ、プール管理を利用できます。

グラフビジュアライザー — http://localhost:3033/graph

メモリ同士のつながりを示す、インタラクティブな力指向マップです。ルートメモリは明るいノードで表示され、近隣のノードはカテゴリーごとに色分けされます。エッジの太さは接続の強さを表します。ドラッグやズームをしたり、任意のノードをクリックして全コンテンツを表示したりできます。

http://localhost:3033/graph?memoryId=42&userId=alex&depth=2

---

🔧 MCP ツール

AI が自動的に呼び出す 3 つのツールです。

ツール	AI が呼び出すタイミング	機能
recall_memory(query, current_path?)	すべてのタスクの開始時	類似度 × 減衰後の強度に基づいてランキングしたメモリを提示します。パスが一致するメモリには空間的なブーストを適用します
store_memory(content, importance, category?, context_paths?)	新しいことを学んだ後	埋め込みを生成して重複を排除し、減衰処理とともに保存します。ファイル／ディレクトリのパスは任意でタグ付けできます
update_memory(id, new_content, importance)	保存済みの情報が古くなったとき	埋め込みを再生成して置き換え、変更を監査ログに記録します

# Store with spatial context
store_memory(
    "Alex prefers tabs over spaces in Python",
    importance=0.9, category="fact",
    context_paths=["/projects/backend"],
)

# Next session — spatial boost fires when working in that directory
recall_memory("Python formatting", current_path="/projects/backend")
# → {"content": "Alex prefers tabs over spaces in Python", "strength": 0.87}

---

⚡ LLM を呼び出さずに質問する

LLM API を一切呼び出さずに質問に答えられる、唯一のメモリシステムです。

yourmemory ask "what database does this project use"
# → YourMemory uses DuckDB locally and Postgres in production.

yourmemory ask "how do I fix a kubernetes deployment"
# → Not enough memory context to answer without an LLM.

メモリの強度が十分であれば、即座に回答します。トークン消費はゼロ、クラウド費用もゼロ、レイテンシもゼロです。十分でない場合は、幻覚を起こす代わりに適切に回答を控えます。クエリがマシンの外に出ることはありません。

---

🔀 API プロキシ — メモリを確実に利用

MCP ツールを呼び出すかどうかは AI の判断に委ねられます。API プロキシを使えばその不確実性をなくせます。すべての LLM 呼び出しをインターセプトし、関連するメモリを自動的に挿入して、モデルの設定なしで store_memory／update_memory を処理します。

サーバー（yourmemory）を起動し、クライアントの接続先を localhost:3033 に設定します。

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-ant-...",
    base_url="http://localhost:3033/proxy/anthropic",
    default_headers={"X-YourMemory-User": "alex"},  # per-user memory
)

# Memory is injected automatically — no other changes needed
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What database do I use?"}],
)

OpenAI も base_url="http://localhost:3033/proxy/openai" を使えば同様に動作します。

---

🏗️ アーキテクチャとスタック

flowchart LR
    C["Your AI client<br/>Claude · Cursor · any MCP"] <--> Y["🧠 YourMemory"]
    Y --> M[("Memory<br/>store")]
    Y --> A[("Audit<br/>ledger")]
    style Y fill:#0a2540,stroke:#19cdff,color:#fff
    style M fill:#0c1a2c,stroke:#5eead4,color:#fff
    style A fill:#0c1a2c,stroke:#5eead4,color:#fff

コンポーネント	役割
DuckDB	デフォルトのベクトルストア。セットアップ不要で、ネイティブなコサイン類似度に対応します
PostgreSQL + pgvector	オプション。チームや大規模なデータセット向けです
NetworkX	デフォルトのグラフバックエンド（~/.yourmemory/graph.pkl）
Neo4j	オプションのグラフバックエンド
sentence-transformers	ローカルでの埋め込み生成（multi-qa-mpnet-base-dot-v1、768 次元）
spaCy	重複排除とエンティティ抽出のためのローカル NLP
APScheduler	減衰とプルーニングを自動化

---

🩺 トラブルシューティング

書き込みが停止する／タイムアウトする（DuckDB のシングルライターロック）。 MCP サーバーと HTTP サーバーを同時に実行すると、DuckDB の書き込みロックを奪い合います。次の方法で解決できます。

pkill -f yourmemory 2>/dev/null || true
rm -f ~/.yourmemory/memories.duckdb.wal ~/.yourmemory/memories.duckdb.lock 2>/dev/null || true
# restart your client

Claude Desktop（MCP）と Claude Code（フック）を同時に実行していますか？その場合は SQLite を使用してください。読み取り／書き込みが同時に行われても問題なく処理できます。 DATABASE_URL=sqlite:///~/.yourmemory/memories.db

---

🤝 コントリビュート

PR を歓迎します。CONTRIBUTORS.md をご覧ください。

📚 データセットの参照先

• LoCoMo — Maharana ほか（2024）
• LongMemEval — Wu ほか（2024）
• HotpotQA — Yang ほか（2018）

📄 ライセンス

Copyright 2026 Sachit Misra — CC-BY-NC-4.0 の下でライセンスされています。

無料で利用できる用途： 個人利用、教育、学術研究、オープンソースプロジェクト。 商用利用： 別途、書面による契約が必要です → [email protected]