SuperMemory

SuperMemory

MCP を最優先とするエージェント学習レイヤー。Claude、Cursor、カスタムのエージェントワークフローに対応しています。

SuperMemory は、会話の全記録ではなく、失敗や修正から抽出した教訓を取得し、保存前に検証します。さらに、クローズドループのサイクルを通じて、時間とともにエージェントを改善します。

---

クイックスタート

pip install supermemory-agent
supermemory-agent --storage .supermemory --transport stdio

または、uv を使用します。

uvx supermemory-agent --storage .supermemory --transport stdio

最新リリース： v0.2.4 — すべての GitHub リリースに、wheel と sdist が添付されています。

---

提供内容

コンポーネント	説明
MCP サーバー	stdio（またはストリーム可能な HTTP）経由で 29 個のツールと 4 個のリソースを提供
エージェントスキル	skills/supermemory-agent-learning/SKILL.md — PyPI パッケージに同梱
Python SDK	uall_python によるプロセス内連携
REST API	リモート／複数言語対応クライアント向けの FastAPI サーバー
ストレージ	デフォルトではローカルの .supermemory/ ファイルを使用。SQLite と PostgreSQL はオプション

MCP サーバー、スキル、SDK、REST API、テスト、リリースパッケージのすべてが、1 つのリポジトリに含まれています。

---

インストール

PyPI（推奨）

pip install supermemory-agent

インストール後、同梱のスキルは site-packages/skills/supermemory-agent-learning/ にあります。必要に応じて、エディターのスキルフォルダーにコピーしてください。

GitHub リリース（オフライン／バージョン固定）

各リリースにはインストール可能なアセットが含まれています。

pip install https://github.com/YashvantHange/SuperMemory/releases/download/v0.2.4/supermemory_agent-0.2.4-py3-none-any.whl

すべてのバージョンを見る：github.com/YashvantHange/SuperMemory/releases

ソースから（開発者向け）

git clone https://github.com/YashvantHange/SuperMemory.git
cd SuperMemory
pip install -e ".[dev]"
python -m pytest tests/ -v

---

MCP の設定

Cursor

examples/cursor.mcp.json を、プロジェクト内の .cursor/mcp.json にコピーします。

{
  "mcpServers": {
    "supermemory": {
      "command": "supermemory-agent",
      "args": ["--storage", ".supermemory", "--transport", "stdio"]
    }
  }
}

Claude Desktop

examples/claude_desktop_config.json の内容を、次のファイルにマージします。

%APPDATA%\Claude\claude_desktop_config.json

保存後、Claude Desktop を再起動してください。

手動で実行

ターミナルで supermemory-agent だけを実行しないでください。stdio モードでは、MCP クライアントからの JSON-RPC を想定しています。シェルで Enter キーを押すと、JSON の解析エラーが発生します。

# For local HTTP testing only:
supermemory-agent --transport streamable-http

Cursor または Claude Desktop で設定すると、クライアントが stdio 経由でサーバーを自動的に起動します。

---

エージェントスキル（Cursor + Claude Code）

ソース	パス
正式版（ここで編集）	skills/supermemory-agent-learning/
Cursor プロジェクト	.cursor/skills/supermemory-agent-learning/
Claude Code プロジェクト	.claude/skills/supermemory-agent-learning/
PyPI インストール	site-packages/skills/supermemory-agent-learning/

skills/ を編集した後、コピーを同期します。

python scripts/sync_skills.py

チャットで SuperMemory、エージェント学習、または MCP メモリに言及すると、スキルが読み込まれます。

---

学習ループ

retrieve → record_failure → reflect(event_ids) → validate → process_promotions
         → retrieve again → report_outcome

基本ルール： ワークフローの結果と抽出した教訓のみを取得し、会話の全記録は決して保存しません。デフォルトの検索予算は max_tokens=800 です。

---

MCP ツール（29 個）

コア（13 個）： retrieve、record_event、record_failure、record_correction、reflect、validate、process_promotions、report_outcome、get_policies、add_policy、add_skill、search_skills、get_skill

UALL 拡張（16 個）： learn.run.start、learn.run.event、learn.run.end、learn.store、learn.retrieve、learn.reflect、learn.validate、learn.evaluate、learn.feedback、learn.improvements、learn.analytics、learn.policies、learn.experiment、learn.rollback、learn.skills、learn.telemetry

すべてのツールに MCP の安全性アノテーション（readOnlyHint／destructiveHint）が含まれています。

MCP resources (4)

• supermemory://policies/active
• supermemory://lessons/{lesson_id}
• supermemory://memory/{lesson_id}/provenance
• supermemory://skills/{skill_id}

---

Python SDK

from uall_python import UALLClient

client = UALLClient(storage="file")

with client.run(workflow_id="pdf-pipeline", step="planner", namespace="team:eng") as run:
    lessons = run.retrieve(step="planner", max_tokens=800)
    run.record_failure(snippet="chose OCR for searchable PDF", tags=["routing"])
    run.report_lesson_outcome(lesson_id="lesson_001", used=True, accepted=True, improved=True)

REST API

python -m uall_server

Server: http://localhost:8000 — see api/openapi.yaml.

---

Storage

Tier	Backend	Config
Default	.supermemory/ JSON files	SUPERMEMORY_STORAGE_PATH or UALL_DATA_DIR
Optional	SQLite	UALL_STORAGE_BACKEND=sqlite
Enterprise	PostgreSQL	UALL_STORAGE_BACKEND=postgres

---

Project layout

SuperMemory/
├── src/supermemory_mcp/          # MCP server (29 tools, 4 resources)
├── skills/supermemory-agent-learning/   # Agent skill (SKILL.md)
├── packages/uall/                # Core learning engine
├── packages/uall_python/         # Python SDK
├── packages/uall_server/         # REST API
├── examples/                     # Cursor + Claude Desktop MCP configs
├── tests/                        # 74 tests incl. stdio MCP transport
└── docs/                         # Publishing, releases, privacy

---

Tests

python -m pytest tests/ -v
python -m pytest tests/test_mcp_server.py -v   # real stdio MCP transport
python -m pytest tests/test_core.py -v         # closed-loop integration

---

Docs

Doc	Purpose
docs/GIT_SETUP.md	Fix commit author name/email on GitHub
docs/RELEASES.md	Release checklist — every tag ships wheel + sdist
docs/PUBLISHING.md	PyPI, MCP Registry, Cursor & Claude directories
PRIVACY.md	Privacy policy
skills/README.md	Agent skill install paths

MCP Registry name: io.github.YashvantHange/supermemory
PyPI package: supermemory-agent

---

License

MIT — see LICENSE