spomory

Spomory

English | 中文

Spomory は、AI クライアントにセッションをまたいで保持され、すべてのクライアント間で共有されるメモリーを提供します。あるクライアントに何か（プロジェクトの詳細、好み、自分についての情報など）を一度伝えると、同じことを繰り返さなくても、どのクライアントからでも後で思い出せます。MCP サーバーとして動作するため、MCP 対応のクライアントならどれでも使えます。Claude Desktop、Cursor、Codex CLI、Doubao (豆包) では、実際のクライアントセッションを使ってエンドツーエンドで動作確認済みです（詳しくは下記の「できること」をご覧ください）。ModelScope、Coze、阿里云百炼 (Alibaba Cloud Bailian) も互換性が確認されており、他のリモート MCP クライアントと同じ方法で接続できます（Streamable HTTP、または Streamable HTTP にまだ対応していない百炼では SSE）。

MCP サーバーとして、自分のマシン上でローカルに（無料で、データがコンピューターの外に出ることはありません）、またはホスト型のクラウドサービスとして（無料登録で、デバイス間でメモリーを利用できます）実行できます。上記のクライアントはすべて、どちらの方法にも対応しています。この README の残りではローカルでの利用方法を説明します（下記の「はじめる」が対象です）。クラウドで利用する最も手軽な方法は、ウェブアプリの spomory.yliuai.com/get-started/remote を使うことです。各クライアントのローカル／クラウド接続の詳しい設定は、docs/mcp_quickstart.en.md にあります（クライアントごとにセクションが分かれており、Claude Desktop／Cursor／Codex CLI／Doubao それぞれについて、両方の接続方法を説明しています）。

インストールする前に、実際に何ができるのか試してみませんか？spomory.yliuai.com では、登録不要のデモを利用できます。テキストを貼り付けると、構造化された情報に変換されます。その情報は Claude、Cursor、Codex CLI、および接続した他のすべてのクライアントで利用でき、毎回リセットされることなく、セッションをまたいで保持されます。

はじめに

Python 3.11 以降が必要です。

1. インストールします。 この手順は丸ごと省略することもできます。手順 3 の設定で uvx を直接指定すれば、必要に応じて取得して実行するため、事前のインストールは不要です。

pip install "spomory[llm,embedding,mcp]"

2. LLM を設定します。 Spomory は、伝えた内容を構造化された事実に変換するために LLM を使用します。OpenAI、DeepSeek、Qwen など、OpenAI 互換 API であればどれでも使用できます。

export LLM_API_KEY=sk-...
export LLM_BASE_URL=https://api.deepseek.com   # optional, defaults to OpenAI
export LLM_MODEL=deepseek-chat                 # optional, defaults to gpt-4o-mini

3. クライアントに接続します。 Claude Desktop、Cursor、Codex CLI では、それぞれ設定ファイルに数行追加して、spomory-mcp コマンドを指定する必要があります。詳しい手順、各クライアントの設定ファイル例、実際に遭遇した注意点（macOS が ~/Documents 配下の venv をブロックする問題）については、docs/mcp_quickstart.en.md をご覧ください。

設定ファイルのないクライアント（Doubao (豆包)、Coze、ModelScope）では、代わりにクリック操作で入力できる「カスタムコネクター」フォーム（URL とヘッダー、またはローカルプロセス用のコマンド、引数、環境変数）から接続します。同じドキュメントの Doubao セクションをご覧ください（Claude Desktop、Cursor、Codex CLI、Doubao の各クライアントにはそれぞれ専用のセクションがあり、その中で STDIO／HTTP／OAuth をまとめています）。

つまずきやすいのは、設定で spomory-mcp の絶対パスを指定する必要がある点です（which spomory-mcp を実行すると確認できます）。クライアントはシェルの PATH が設定された状態でコマンドを起動するとは限りません。command に uvx を指定すれば、この問題も手順 1 も不要になります。正確な JSON についてはクイックスタートガイドをご覧ください。

これで完了です。データはデフォルトでローカルの ~/.memory-core/ に保存されます（MEMORY_CORE_DATA_DIR で変更できます）。コンテナーイメージからデプロイする MCP ディレクトリ／ホスト向けに、Dockerfile も用意されています。

接続後にすぐ行うとよいことが、もう 2 つあります。 skill/spomory/SKILL.md をクライアントのスキルディレクトリにコピーして、使われないままにならないよう、クライアント自身がこれらのツールを呼び出せるようにしてください。また、すでに Claude Code、Codex、Cursor を使用している場合は、spomory-import-sessions --client claude-code（または codex／cursor）を実行すると、何もない状態から始めるのではなく、実際のセッション履歴を使ってグラフを作成できます。どちらについても、クイックスタートガイドで説明しています。

クラウド API ではなく、LLM の呼び出しもローカルで行いたいですか？ LLM_BASE_URL に vLLM、Ollama、llama.cpp、MLX などのローカル OpenAI 互換サーバーを指定し、EMBEDDING_PROVIDER=openai_compatible を設定すると、ローカルの sentence-transformers モデルではなく、同じ方法で埋め込み処理を行えます。これにより torch 依存関係も完全に不要になります。詳細と各エンジンの設定例については、docs/mcp_quickstart.en.md をご覧ください。

できること

接続すると、クライアントで次の 6 つのツールが利用できるようになります。

ツール	機能
add_memory	伝えた内容を記憶します
search_memory	質問に関連する内容を呼び出します
forget_memory	忘れるよう依頼した内容に最も一致する項目を 1 つ削除します
forget_all_memory	1 回の呼び出しでメモリーグラフ全体を消去します
get_graph	確認用に、ある項目を中心としたメモリーグラフを表示します
export_memory	保存したすべてのデータを JSON としてエクスポートします。データを持ち運べます

6 つすべてのツールについて、Claude Desktop、Cursor、Codex CLI、Doubao の実際のセッションを使い、ローカルとリモートの両方で、最初から最後まで動作することを確認済みです。各クライアントでの「確認済み」の意味については、docs/mcp_quickstart.en.md をご覧ください。

興味のある方向けの仕組み

Spomory を使うために、以下の内容を理解する必要はありません。内部で何が起きているのか知りたい方向けの説明です。

• プラグイン可能な LLM／埋め込みプロバイダー：デフォルトでは、OpenAI 互換の任意の API（中国市場向けの LLM プロバイダーを含む）と、ローカルの sentence-transformers（デフォルトは bge-m3。中国語と英語のバイリンガル）を使用します。
• 二層構造の増分ナレッジグラフ：エンティティと関係を独立したレイヤーとしてモデル化します。新しいデータだけを抽出してマージするため、全体を再構築することはありません。「thanks」「好的」「ok」など、完全一致する埋め草の入力は、抽出可能な事実を含まないため、抽出用 LLM の呼び出しに到達する前に除外します。これは、認証のないエンドポイントにおけるコスト保護として有効です。デフォルトではローカルの LocalGraphStore（networkx + SQLite）を使用します。クラウド実装として PostgresGraphStore も用意されており、どちらも同じ振る舞いに関する契約テストスイートを共有しています。
• HippoRAG 2 スタイルの検索：クエリをエンティティノードだけでなく、トリプルにも直接照合します。照合されたシードノードにパーソナライズド PageRank を適用して拡散させ、複数ホップの関連情報をたどった後、自然言語のコンテキストにまとめます（ソースのタイムスタンプも含まれるため、「X についていつ言及しましたか」という質問にも答えられます）。さらに、取得されない期間が長くなるほど関係の関連性を下げ、同じ事実が繰り返し述べられるほど関連性を高めます（対数による減衰を適用するため、PPR のランクを上回ることはありません）。これは、以下の能動的な ADD／UPDATE／DELETE／NOOP の判断と並行して働く受動的なシグナルです。
• メモリ管理：ADD／UPDATE／DELETE／NOOP のアクション空間を備え、デフォルトのルールベースポリシー（RuleBasedPolicy）と、完全な GRPO トレーニングパイプライン（memory_manager/train_grpo.py。実際の GPU で実行・検証済み）を提供します。
• メモリパスポートのエクスポートと完全削除：JSON-LD スタイルのエクスポート形式、物理削除、監査ログを備えています。
• マルチモーダル画像検証：画像のキャプション生成 → テキスト抽出パイプラインの再利用 → CLIP による候補トリプルのクロスチェック、という流れです。正直に「検証」と位置づけており、「ネイティブなクロスモーダル抽出」とはしていません。
• クラウドの基本構成：FastAPI によるユーザー認証／API キー／クォータ、Stripe ウェブフックによる課金の土台（基本構成のみで、本番環境にはデプロイされていません）。

実測結果

LoCoMo-10 の 84 個の QA ペア（conv-26、最初の 150 ターン）に対する DeepSeek での実行結果です。恣意的に選んだものではなく、現時点では大手各社が公開している数値には及びません。

指標	値
Recall@10（適切な根拠となるターンがコンテキストに含まれていたか）	52.4%
精度 — 厳密な部分文字列一致	19.0%
精度 — LLM による判定（より寛容で、表現の違いを許容）	44.0%

以前の実行では、「いつ」の質問に答えられるよう抽出した述語に日付を組み込む修正を行う前は、精度が低い一方で再現率は高い（62.0%）という結果でした。この修正により、検索再現率は多少低下したものの、精度は実際に 14.3 ポイント向上しました。また、精度の数値を報告するだけでなく、その理由を詳しく調べました。日付を組み込む指示は、内容のない雑談（「ありがとう！」→「2023-07-03 に感謝した」）で誤作動することがあり、そのような価値の低いトリプルが、固定された検索上位 10 件の枠から関連するトリプルを押し出してしまいます。詳細な数値、カテゴリ別の内訳、およびこの問題の発見につながった抽出結果の比較は、docs/benchmark_smoke_test.md をご覧ください。

LongMemEval（xiaowu0162/longmemeval-cleaned のオラクル版、500 問中最初の 10 問）：

指標	値
Recall@10	100%（10/10）
精度 — 厳密な部分文字列一致	30%
精度 — LLM による判定	80%

ここでは、数値と同様に制約も重要です。

1. 全 500 問ではなく、10 問のみです — 各質問では平均約 27 ターンを取り込みます（実際の抽出呼び出し約 27 回に加え、生成呼び出し 1 回、判定呼び出し 1 回）。この環境では LLM API の呼び出しに実際のレイテンシーがあるプロキシを経由するため、全データセットの実行には数十時間かかります。これはモックではなく実際の実行ですが、サンプル数が少ないため、データセット全体にも当てはまる結果と解釈すべきではありません。
2. たまたま 10 問すべてが temporal-reasoning タイプです — データセットには multi-session タイプもあります。load_longmemeval(limit=10) は、層化サンプリングを行わず、ファイル順で最初の 10 件を取得するため、このサンプルはデータセット全体を代表していません。
3. Recall@10 = 100% は、強力な検索性能を示すというより、オラクル版の設計によるところが大きい結果です — オラクル版では、各質問の検索対象を関連するセッションだけに事前に絞り込んでおり、無関係なセッションは含まれません。これは、無関係なターンが数百から数千件ある実際のデプロイ環境のメモリストアよりもかなり容易です。これは LongMemEval の全体版（非オラクル版）とは異なるタスクであり、より難しいそのバリアントについて他製品が報告している数値と直接比較すべきではありません。
4. 厳密一致での精度（30%）は、LLM による判定での精度（80%）を大きく下回っています。これは LoCoMo の結果で見られたパターンと一致しており、部分文字列一致では、正解でも表現が異なる回答が体系的に過少評価されます。

生データ： benchmarks/results/longmemeval_oracle_subset.json； 実行スクリプトは benchmarks/run_longmemeval_subset.py です。

貢献者向け：ソースからのビルド

以下は、内部の実装を変更したい方、テストスイートを実行したい方、または MCP サーバーの実行に必要な範囲を超える依存関係グループ（GPU トレーニング、クラウド API のスケルトン、マルチモーダル検証）を利用したい方向けの内容です。Spomory を使うだけであれば、これらは必要ありません。上記の「はじめに」をご覧ください。

プロジェクト構成

src/
├── memory_core/
│   ├── graph/            # entity/relation models, storage adapters (local SQLite / cloud Postgres), incremental writes
│   ├── retrieval/        # query→triple matching, personalized PageRank, context assembly
│   ├── memory_manager/   # action space, reward functions, GRPO training script, policy inference
│   ├── multimodal/       # image captioning + CLIP verification
│   ├── mcp_server/       # MCP Server (the distribution entry point)
│   ├── export/           # memory passport export format + true delete
│   ├── llm/              # pluggable LLM/embedding providers
│   ├── audit.py          # deletion audit log
│   └── usage.py          # retention/usage tracking
└── cloud_api/            # FastAPI cloud service skeleton (auth, quotas, billing)
benchmarks/                # LoCoMo/LongMemEval evaluation harness + multimodal comparison experiments
tests/                     # 94+ tests, from unit tests to real LLM/GPU/Postgres end-to-end verification
docs/                      # per-epic design notes, verification reports, runbooks (see index below)

開発環境をセットアップする

前提条件：Python 3.11+、uv （uv がない場合は、以下の uv コマンドの代わりに python -m venv と pip install -e を使用できます）。

git clone <this repo's URL> memory-core && cd memory-core
uv venv --python 3.11 .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

# Pick dependency groups as needed — they can be combined, no need to install everything:
uv pip install -e ".[dev]"                 # required to run tests/lint
uv pip install -e ".[llm,embedding]"       # required for the "minimal working memory system" (see the demo below)
uv pip install -e ".[mcp]"                 # extra: connecting to Claude Desktop/Cursor
uv pip install -e ".[rl]"                  # extra: GRPO training (requires a GPU + CUDA)
uv pip install -e ".[cloud]"               # extra: cloud API / Postgres backend
uv pip install -e ".[multimodal]"          # extra: image + CLIP verification

embedding グループをインストールすると、初回使用時にデフォルトモデル BAAI/bge-m3 が HuggingFace からダウンロードされます（約 2.2GB）。huggingface.co にアクセスできることを確認してください（グレート・ファイアウォールの背後にいる場合は、export HF_ENDPOINT=https://hf-mirror.com を設定するとミラー経由で接続できます）。また、export EMBEDDING_MODEL=<any sentence-transformers model name> を設定すれば、より小さなモデルに切り替えることもできます。

最小限の例を実行する（MCP を使わず、Python を直接呼び出す）

dev、llm、embedding をインストールし、「Get started」にある 3 つの環境変数を設定した状態で、このスクリプトを実行すると、「メモを書き込む → 検索する」パイプライン全体を直接試せます（mcp_server/server.py の add_memory／search_memory ツールと同じロジックですが、MCP プロトコル層を経由せず、ライブラリを直接呼び出します）。

# demo.py
from memory_core.graph.local_store import LocalGraphStore
from memory_core.graph.incremental import IncrementalIngestor
from memory_core.llm.openai_compatible import OpenAICompatibleProvider
from memory_core.llm.local_sentence_transformer import SentenceTransformerProvider
from memory_core.memory_manager.policy import RuleBasedPolicy
from memory_core.retrieval.ppr import personalized_pagerank, rank_entities
from memory_core.retrieval.query_match import match_query_to_triples
from memory_core.retrieval.ranker import build_context

store = LocalGraphStore("demo.sqlite3")          # a local file; delete it to reset
llm = OpenAICompatibleProvider()                 # reads LLM_API_KEY etc. from the environment
embedder = SentenceTransformerProvider()         # downloads bge-m3 on first run

# 1. Write a memory: the LLM extracts triples, incrementally merged into the graph
ingestor = IncrementalIngestor(store, llm, policy=RuleBasedPolicy())
result = ingestor.ingest("I do AI research at CAS, mostly in Python.", source_id="demo")
print(f"added {result.new_entities} entities, {result.new_relations} relations")

# 2. Retrieve: match the query against triples -> PPR diffusion -> assemble a natural-language context
query = "Where do I work?"
entities, relations = store.all_entities(), store.all_relations()
entities_by_id = {e.id: e for e in entities}
matches = match_query_to_triples(query, relations, entities_by_id, embedder, top_k=10)
seed_ids = {r.relation.subject_id for r in matches} | {r.relation.object_id for r in matches}
scores = personalized_pagerank(entities, relations, seed_entity_ids=list(seed_ids))
ranked_ids = [eid for eid, _ in rank_entities(scores)]
print(build_context(relations, entities_by_id, ranked_ids, top_k=10))

python demo.py

以下は、上記とまったく同じ入力を使って DeepSeek で実行した際の実際の出力です（捏造も手直しもしていません。実際に返ってきたものです）。

added 3 entities, 2 relations
I do AI research at CAS (recorded at 2026-09-05 10:40:00).I do AI research mostly in Python (recorded at 2026-09-05 10:40:00).

正確な表現やエンティティ／関係の数は LLM 自身による抽出結果に左右されるため、実行ごとに異なります。ただし、環境変数が正しく設定されていれば、空でない出力が得られることでパイプラインが最初から最後まで機能していると確認できます。retrieval/ranker.py は関係のテキストが CJK かどうかを判定し、それに応じて表示します（CJK の場合はスペースなしで中国語のタイムスタンプラベルを付け、それ以外の場合は単語間にスペースを入れて英語のタイムスタンプラベルを付けます）。そのため、このデモの以前のバージョンのように、英語の入力がスペースのないひと続きの単語として出力されることはなくなりました。

テスト

pytest                    # everything
pytest -m "not slow"      # skip tests that download models / train — runs in seconds

「低速」テストの大半はモックではありません。実際の呼び出し（実際の LLM API、ローカルの埋め込みモデル、CLIP モデル）を行うため、対応する環境変数（LLM_API_KEY など）を設定するか、モデルのキャッシュをあらかじめダウンロードしておく必要があります。

ドキュメント一覧

ドキュメント	内容
mcp_quickstart.en.md (中文)	MCP サーバーのインストール、設定、Claude Desktop／Cursor／Codex CLI／Doubao への接続、実運用での注意点
graph_store_interface.en.md (中文)	ストレージアダプターのインターフェース設計
export_format.en.md (中文)	「memory passport」のエクスポート形式
dataset_format.en.md (中文)	GRPO トレーニングデータ形式と実際のデータセットの生成方法
methodology.en.md (中文)	技術的な方法論：実際に検証済みの内容と、未解決の内容
benchmark_smoke_test.en.md (中文)	実際の LoCoMo ベンチマーク結果と失敗事例の分析
memory_manager_eval.en.md (中文)	ルールベースと GRPO でトレーニングしたポリシーの比較。デバッグの過程を含む
multimodal_verification.en.md (中文)	画像と CLIP の検証実験結果
gpu_training_runbook.en.md (中文)	GPU トレーニング環境のセットアップ記録（実際に遭遇した注意点を含む）
postgres_setup.en.md (中文)	クラウド Postgres バックエンドのデプロイ記録
leaderboard_submission.en.md (中文)	サードパーティのリーダーボードに関する調査
mvp_scope.en.md (中文)	MVP のスコープ定義
privacy_policy_draft.en.md (中文) / product_copy_memory_passport.en.md (中文)	プライバシーポリシーの草案／外部向けの製品紹介文
eng_note_cjk_rendering_bug.en.md (中文)	エンジニアリングノート：中国語・日本語・韓国語（CJK）のレンダリングバグを発見して修正し、検証した実際の記録

上記の各ドキュメントには、中国語版と英語版の両方が用意されています。

既知の制限事項

• 音声入力のマルチモーダル検証（ASR と音声埋め込み）は、まだ実装されていません。
• GRPO トレーニングデータセット（実サンプル 140 件）とトレーニングステップ数はまだ少なく、memory_manager_eval.md では、そのためにトレーニングの有効性がどのように制限されるかを率直に説明しています。
• クラウド API／課金機能は骨組みの段階にとどまっており、実際の本番環境には接続されていません。

ライセンス

LICENSE を参照してください。