genesys-memory

Papez

AI メモリのためのインテリジェンスレイヤー。

Papez は何が起きたかだけでなく、なぜ起きたかまで記憶します。AI エージェントのメモリのためのスコアリングエンジン + 因果グラフ + ライフサイクルマネージャーです。MCP をネイティブに扱います。

LoCoMo ベンチマーク（認定済み）

システム	スコア	プロトコル
Papez	85.55 ± 0.37	固定: gpt-4o-mini 回答者 + 判定者、temp 0、n=1,540、カテゴリ 1〜4、10 回実行（2026 年 7 月）
Zep	75.14	同等の公開設定
Mem0	66.9	同等の公開設定（Mem0 論文）

約 90 を超えるベンダー自己申告の数値は、異なる回答者/判定者を使用しているため比較できません。この固定プロトコルにおけるオラクル検索の上限は 94.9 です。ご自身で再現できます: Astrix-Labs/locomo-harness · 完全な方法論 · 実行ごとの結果。

ホステッド製品: papez.ai — AI のためのあなたのパーソナルメモリ。ChatGPT、Claude、そしてあらゆる MCP アプリをまたいで持ち運べます · 料金 · 開発者ドキュメント · ベンチマーク方法論（LoCoMo で 85.55、10 回の実行で認定、証跡公開）

これは何か

Papez は、AI メモリのためのスコアリングエンジン、因果グラフ、ライフサイクルマネージャーです。メモリは乗算式（関連性 × 接続性 × 再活性化）でスコアリングされ、因果グラフで接続され、不要になったときには能動的に忘却されます。

このパッケージ（papez）はコアライブラリです。オプションの JSON 永続化を備えたインメモリ因果グラフエンジンに加えて、stdio MCP サーバーを提供します。データベース依存も REST API もありません。このライブラリの上に構築されたホステッド製品（Postgres、追加のストレージバックエンド、REST/HTTP MCP API を備える）は api.papez.ai で別途提供されていますが、このパッケージには含まれません。

なぜ

• フラットなメモリはスケールしません。 すべてをベクトルストアに放り込んでも、理解ゼロの想起しか得られません。500 番目のメモリが、重要な 5 つを埋もれさせてしまいます。
• 忘却がなければ知能もありません。 本物のメモリシステムは忘れます。能動的な枝刈りがなければ、あなたの AI は古びたコンテキストに溺れてしまいます。
• 因果推論がありません。 ベクトルの類似性では「なぜ X を選んだのか?」に答えられません — グラフが必要です。

あなたの AI はすべてを記憶しているのに、何も理解していません。Papez がそれを解決します。

クイックスタート

Python 3.11 以降が必要です。

パッケージをインストールします。基本インストールにはデータベース依存がありません — 状態はメモリ内に保持され、オプションで JSON ファイルに永続化されます。

pip install papez

オプションの追加機能:

pip install 'papez[openai]'      # OpenAI embeddings
pip install 'papez[local]'       # Local embeddings (sentence-transformers, no API key)
pip install 'papez[anthropic]'   # LLM-based causal inference (consolidation, contradiction detection)

stdio MCP サーバーを直接実行します:

python3 -m papez

ソースから

git clone https://github.com/Astrix-Labs/papez.git
cd papez
pip install -e '.[dev]'
pytest tests/

あなたの AI に接続する

Claude Code

claude mcp add papez -- python -m papez

Claude Desktop

claude_desktop_config.json に追加します:

{
  "mcpServers": {
    "papez": {
      "command": "python",
      "args": ["-m", "papez"]
    }
  }
}

信頼性とリトライ

stdio サーバーは単一のローカルプロセスです。負荷がかかったとき、あるいはその前段にあるホスト型トランスポートの再起動や再デプロイ中に、ツール呼び出しが一時的に失敗したり、接続が短時間応答しなくなったりすることがあります。メモリの書き込みや読み取りはエージェントのターンをクラッシュさせるほど重要なものではないため、クライアントはメモリ呼び出しを致命的なものとして扱うのではなく、優雅にデグレードすべきです:

• サーバーも優雅にデグレードします: ツールの例外 (または必須引数の欠落) は、プロトコルレベルの MCP 障害ではなく、構造化された {"error": "...", "retryable": bool} ペイロードとして返されるため、メモリの一時的な問題がトランスポートをクラッシュさせることはありません。retryable フラグは以下のガイダンスをエンコードしています — true になるのは読み取りツールのみです。
• 冪等な読み取りをリトライする (memory_recall、memory_search、memory_traverse、memory_explain、memory_stats) — 短く上限付きのバックオフ (例: 2〜3 回の試行) を使用します。これらには、再アクティブ化の記録以外に気にするべき副作用はありません。
• 曖昧なタイムアウト時に memory_store / memory_amend を盲目的にリトライしないでください — サイレントに成功した後にリトライすると、重複ノードが作成されます。ターンを続行して次の memory_recall で整合を取るか、安定した source_session を渡して重複を簡単に発見できるようにすることを推奨します。
• メモリはベストエフォートのコンテキストとして扱い、ハード依存関係とはしないでください。 呼び出しが失敗した場合は、すでに持っているコンテキストで続行し、中断するのではなく次のターンで再試行してください。グラフは永続的です。書き込みの失敗は回復可能ですが、クラッシュしたエージェントのターンは回復できません。

MCP ツール

ツール	説明
memory_store	新しいメモリを保存します。ライターが指定する型付きエッジ ({id, type}) には related を使用します。related_to はレガシーであり、常に caused_by を作成します。任意で category を指定できます。possible_conflicts (ヒューリスティックなヒント) を返す場合があります。
memory_amend	訂正を記録します: 既存のメモリを上書き (supersedes) する新しいメモリを作成します。古いメモリは削除されず、保持されます (リコール時に減衰)。
memory_recall	自然言語クエリによってメモリをリコールします (ベクトル + キーワード + グラフ拡散活性化)。軽量なペイロードのために verbosity: "concise" をサポートします。
memory_search	ステータス、カテゴリ、日付 (since)、最終アクティブ日 (active_since)、またはエンティティによるフィルタ付きベクトル検索。空のクエリを渡すと、代わりに新しさ順で列挙します (エンベッダー不要) — since/active_since と組み合わせることで、何をクエリすべきかわからなくても「最後に見てから何が新しいか」に答えられます。
memory_traverse	ノードから因果グラフをたどります。到達可能なノードと、誘導部分グラフのエッジ (source/target/type/weight/created_by) を返します — BFS ツリーのスーパーセットであるため、パスを再構築できます。edge_types を尊重します。
memory_explain	メモリのスコアを説明します。score_model ブロック (式 + リアルタイムのフォース別内訳 + 陳腐化の注記) と removal_impact を含みます。
memory_stats	メモリシステムの統計を取得します
pin_memory	メモリをピン留めして、決して忘れられないようにします
unpin_memory	以前にピン留めしたメモリのピン留めを解除します
delete_memory	メモリを完全に削除します
list_core_memories	コアメモリを一覧表示します。任意でカテゴリでフィルタできます
set_core_preferences	コアメモリカテゴリのユーザー設定を行います
promote_to_org	プライベートメモリを組織の可視性に昇格させます

書き手が指定するエッジと訂正

memory_store の related 引数を使うと、書き手が推測に頼らずエッジの意味論を設定できます。各エントリは {"id": "<node-id>", "type": "<edge-type>"} で、new_node --type--> target という有向関係になります（つまり supersedes は、新しいノードが対象を置き換えることを意味します）。無効な型はノードが作成される前に拒否されます — 明示的な書き込みが中途半端に成功することはありません。related_to も依然として存在しますが、常に caused_by を作成します。related を推奨します。

事実を訂正するには、memory_amend(node_id, content, reason=...) を使用します。これは新しいバージョンを保存し、それを SUPERSEDES → old でリンクし、監査のために古いメモリを保持します。リコールは置き換えられたヒットを自動的に優先度を下げ、superseded_by でタグ付けします。

自動リンク候補と字句的に矛盾するもの（変更された数値、否定）を memory_store した場合、結果に possible_conflicts が含まれることがあります — これはヒューリスティックなヒントであり、検証済みの矛盾ではなく、エッジとして実体化されることもありません。これらを使って memory_amend すべきかどうかを判断してください。

簡潔なリコール

memory_recall(query, verbosity="concise") は因果チェーンの拡充をスキップし、ヒットごとに id / summary / status / score / activation / is_core（設定されている場合は superseded_by も）のみを返します — 高頻度の検索ではトークンあたりのコストが大幅に低くなります。verbosity="full"（デフォルト）は変更されていません。再有効化の書き込みはどちらのモードでも発生します（これらは verbosity ではなく read_only によって制御されます）。

activation / decay_score が実際に何を意味するかについては docs/scoring.md を参照してください — 要するに、これはメモリがリコールされたときに上昇する保持の重みであり、削除へのカウントダウンではありません。

仕組み

すべてのメモリは、掛け合わされた 3 つの力によってスコアリングされます:

decay_score = relevance × connectivity × reactivation

• 関連性は時間とともに減衰します。古いメモリは強化されない限り薄れていきます。
• 接続性は、多くの因果リンクを持つメモリを優遇します。ハブとなるメモリは生き残ります。
• 再有効化は、繰り返しリコールされ続けるメモリを後押しします。頻度が重要です。

数式は乗算的であるため、メモリが生き残るには3 つの軸すべてでスコアを獲得する必要があります。高度に接続されていても決してアクセスされないメモリは、それでも減衰します。頻繁にリコールされても因果的に孤立したメモリは、それでも薄れていきます。

decay_score（すべてのヒットで activation という別名が付きます）は保持の重みであり、削除のカウントダウンではありません — メモリをリコールするとこれが上昇し、スコアが低いことは単に「休息中」を意味するのであって「消滅確定」ではありません。削除には、スコアが低いかつ孤立しているかつピン留めされていないかつコアでないかつ組織でないかつアイドル状態（30 日間、保存・リコール・再有効化されていない、GENESYS_FORGETTING_MIN_IDLE_DAYS）という、すべての条件が同時に成立する必要があります。stdio サーバーは 10 分ごとに再スコアリング・遷移・プルーニングのパスを実行します（GENESYS_MAINTENANCE_INTERVAL_S；0 で無効化）。完全なモデルと計算例については docs/scoring.md を参照してください。

STORE → ACTIVE → DORMANT → FADING → PRUNED
           ↑                    │
           └── reactivation ────┘
                                  (only if score=0, orphan, not pinned)

メモリは core ステータスに昇格させることもできます — 構造的に重要なメモリであり、自動的にピン留めされ、決してプルーニングされません。

ベンチマーク結果

この README の冒頭にある認定済みの LoCoMo 結果を参照してください: 凍結されたプロトコル（gpt-4o-mini の回答者と判定者、temperature 0、n=1,540、カテゴリ 1〜4）の下で 10 回の実行にわたり 85.55 ± 0.37。カテゴリ 5 — グラウンドトゥルースに異論がある敵対的質問 — は除外されており、比較可能な公開設定と一致しています。

すべての実行は再現可能です: ハーネスは Astrix-Labs/locomo-harness にあり、完全な方法論と実行ごとの結果が公開されています。リポジトリ内のシナリオの再現スクリプトは benchmarks/ にあります。

ストレージバックエンド

このパッケージには 1 つのストレージバックエンドが同梱されています。インメモリの因果グラフ（storage/memory.py）で、GENESYS_PERSIST_PATH によるオプションの JSON 永続化に対応しています。データベースは不要です。

追加のバックエンド — Postgres/pgvector、FalkorDB、MongoDB、および Obsidian ボールトアダプター — ならびに REST API、OAuth、マルチユーザー認証は、api.papez.ai にあるホスト型製品の一部であり、このリポジトリには含まれていません。

オープンソースライブラリ用に別のストレージバックエンドが欲しいですか？ storage/base.py のプロバイダープロトコルを実装して、独自のものを用意してください。

設定

.env.example を .env にコピーして、以下を設定します。

変数	必須	説明
OPENAI_API_KEY	GENESYS_EMBEDDER=local の場合を除く	埋め込み
ANTHROPIC_API_KEY	いいえ	LLM ベースの因果推論（統合、矛盾検出）を有効にします。デフォルトではオフ — これがない場合、因果エッジは呼び出し元が memory_store で明示的に宣言したエッジと、コサイン類似度によるリンクからのみ生成されます。
GENESYS_EMBEDDER	いいえ	openai（デフォルト）または local（sentence-transformers、API キー不要）
GENESYS_PERSIST_PATH	いいえ	再起動をまたいで状態を永続化する JSON ファイルパス（それ以外の場合はインメモリ）
GENESYS_USER_ID	いいえ	シングルテナントモード用のデフォルトユーザー ID

自動リンクのチューニング

自動リンクは、新しく保存されたメモリを意味的に類似した既存のメモリに接続します。これが緩すぎると「ヘアボール」状態になります — すべてがすべてから約 2 ホップ以内に収まり、走査のスコープ設定が破壊されます。3 つのノブでこれを制限します。

変数	デフォルト	説明
GENESYS_AUTOLINK_MIN_SIMILARITY	埋め込み推奨値	自動リンクを作成するためのコサイン下限。明示的な値は埋め込みのデフォルトより優先されます。
GENESYS_AUTOLINK_MAX_EDGES	3	1 回の memory_store が作成できる自動リンクの最大数。ファンアウトを上限設定します。
GENESYS_AUTOLINK_MAX_NODE_DEGREE	10	任意の単一ノードがターゲットとして蓄積できる auto_link エッジの最大数。ファンアウトだけでは、ハブがストアごとに 1 つのエッジを永遠に獲得し続けることを許してしまいます。これはハブ自体を上限設定します。

下限は埋め込みを考慮しています。自動リンクは永続的なグラフ構造であるため、その下限は一時的なリコール下限より上に位置します。GENESYS_AUTOLINK_MIN_SIMILARITY が未設定の場合、有効な下限は埋め込みの推奨値です — OpenAI では 0.6（text-embedding-3-small、その真の一致は約 0.5 以上にクラスタリングされます）、local sentence-transformers では 0.45（その真の一致は約 0.2〜0.4 にクラスタリングされますが、ノイズペアは約 0.44 で観測されているため、ローカルではほぼ重複するコンテンツのみが自動リンクされます）。不明な埋め込みはすべて 0.45 にフォールバックします。自動リンクは重複排除も行います。ペアがすでに何らかのエッジ（たとえば user_explicit の caused_by）で接続されている場合、並行する auto_link related_to は作成されません。

memory_store の possible_conflicts ヒントは、より広いウィンドウ（GENESYS_CONFLICT_SCAN_K、デフォルト 8）にわたって、独自の、より低い下限（GENESYS_CONFLICT_MIN_SIMILARITY、デフォルトはリコール下限）でスキャンします — そのため、自動リンクの下限を厳しくしても矛盾検出が縮小されることはありません。

リコール / 関連性の下限

同じ埋め込みを考慮したパターンがリコールフィルタリングを統制します。

変数	デフォルト	説明
GENESYS_RECALL_MIN_SIMILARITY	埋め込み推奨値（OpenAI 0.5 / その他 0.2）	このコサイン下限を下回ると、純粋なベクトルヒットが memory_recall から除外されます。キーワードヒットはこれを回避します。
GENESYS_CORE_INJECT_MIN_SIMILARITY	埋め込み推奨値（OpenAI 0.45 / その他 0.2）	自動昇格されたコアメモリをリコール結果に注入するための下限。ピン留めされたメモリは常に注入されます。

スコアリングの調整項目

三力スコアリングの計算式とそのライフサイクルしきい値は、すべて環境変数で設定できます（engine/config.py と docs/scoring.md を参照）: GENESYS_ACTR_DECAY、GENESYS_RELEVANCE_VECTOR_WEIGHT、GENESYS_RELEVANCE_KEYWORD_WEIGHT、GENESYS_MIN_CONNECTIVITY、GENESYS_FORGETTING_THRESHOLD、GENESYS_DORMANCY_* の遷移しきい値、および GENESYS_CORE_* の昇格ウェイトです。

すべてのオプションについては .env.example を参照してください。

開発元

Papez は Astrix Labs の Rishi Meka によって開発されています。Claude に毎回プロジェクトのコンテキストを説明し直すことへの苛立ちから生まれました。目標は、あなたの LLM とあなたの記憶の間にあるインテリジェンスレイヤーです — 完全なオープンソースです。

コントリビューション

CONTRIBUTING.md を参照してください。

ライセンス

AGPL-3.0-or-later

Note: v0.3.6 より前の Papez リリースは、誤って Apache 2.0 としてドキュメント化されていました。LICENSE ファイルには常に AGPLv3 のテキストが含まれていました。v0.3.6 以降、すべてのドキュメントは Contributor License Agreement を伴う AGPL-3.0-or-later を正しく参照しています。