SuperMemory

SuperMemory

面向 Claude、Cursor 和自定义 Agent 工作流的 MCP 优先 Agent 学习层。

SuperMemory 从失败和纠正中提取精炼的经验教训（而非完整的对话记录），在存储前进行验证，并通过闭环持续改进 Agent。

---

快速开始

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

也可以使用 uv：

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

最新版本： v0.2.4 — 每个 GitHub Release 均附带 wheel 和 sdist。

---

包含的内容

组件	说明
MCP 服务	通过 stdio（或可流式传输的 HTTP）提供 29 个工具和 4 个资源
Agent 技能	skills/supermemory-agent-learning/SKILL.md — 随 PyPI 包一并提供
Python SDK	通过 uall_python 进行进程内集成
REST API	面向远程／多语言客户端的 FastAPI 服务
存储	默认使用本地 .supermemory/ 文件；可选 SQLite 和 PostgreSQL

所有内容都位于同一个仓库中：MCP 服务、技能、SDK、REST API、测试和发布包。

---

安装

PyPI（推荐）

pip install supermemory-agent

安装后，随包提供的技能位于 site-packages/skills/supermemory-agent-learning/。如有需要，可将其复制到编辑器的技能文件夹中。

GitHub Release（离线／固定版本）

每个版本都附带可安装的文件：

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。在 shell 中按 Enter 会导致 JSON 解析错误。

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

在 Cursor 或 Claude Desktop 中完成配置后，客户端会通过 stdio 自动启动服务。

---

Agent 技能（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、Agent 学习或 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