SuperMemory MCP server
✓ VerifiedEnables AI agents to capture distilled lessons from failures and corrections to improve performance through a closed-loop learning cycle.
Also known as YashvantHange/SuperMemory, supermemory-agent
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- 181
- Latest version
- 0.2.5
- Last commit
- Jun 13, 2026
- License
- MIT
What is SuperMemory MCP?
SuperMemory enables AI agents to capture distilled lessons from failures and corrections to improve performance through a closed-loop learning cycle.
Summary generated from the project's README
About SuperMemory MCP server
SuperMemory provides a learning layer for AI agents to improve their performance through a closed-loop cycle. Instead of storing entire conversation transcripts, it captures distilled lessons from failures and corrections. This allows agents using Claude, Cursor, or custom workflows to learn from past mistakes and validate new knowledge before storage.
Developers can deploy this server locally via stdio or use a REST API for remote clients. It offers 29 tools, including core functions like record_failure, reflect, and validate, alongside extended learning tools. While it defaults to local JSON file storage in a .supermemory directory, users can configure SQLite or PostgreSQL backends for more advanced needs. The system is designed to be integrated directly into agentic workflows to ensure that every error becomes a repeatable lesson for future tasks.
What you can do with it
- 1Capture workflow failuresAn AI agent can record specific mistakes made during a task to prevent them from happening again.
- 2Validate learned lessonsThe system ensures that new information is verified before it is permanently stored in the agent's memory.
- 3Retrieve past insightsAn agent can search for previous lessons to guide its current decision-making process.
Written from the project's README. Every use case is checked against a quote from it.
How to install SuperMemory MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall SuperMemory MCP in Claude Code
$ claude mcp add supermemory -- uvx supermemory-agentInstall SuperMemory MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"supermemory": {
"command": "uvx",
"args": [
"supermemory-agent"
]
}
}
}Install SuperMemory MCP in VS Code
.vscode/mcp.json
{
"servers": {
"supermemory": {
"type": "stdio",
"command": "uvx",
"args": [
"supermemory-agent"
]
}
}
}Install SuperMemory MCP in VS Code CLI
$ code --add-mcp '{"name":"supermemory","type":"stdio","command":"uvx","args":["supermemory-agent"]}'Install SuperMemory MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"supermemory": {
"command": "uvx",
"args": [
"supermemory-agent"
]
}
}
}Install SuperMemory MCP in Codex
$ codex mcp add supermemory -- uvx supermemory-agentInstall SuperMemory MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.supermemory] command = "uvx" args = ["supermemory-agent"]
Install SuperMemory MCP in Gemini CLI
$ gemini mcp add -s user supermemory uvx -- supermemory-agentInstall SuperMemory MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"supermemory": {
"command": "uvx",
"args": [
"supermemory-agent"
]
}
}
}Configuration
SUPERMEMORY_STORAGE_PATHLocal directory for .supermemory file storage
UALL_DATA_DIRLegacy alias for SUPERMEMORY_STORAGE_PATH
| Name | Description | |
|---|---|---|
| SUPERMEMORY_STORAGE_PATH | Local directory for .supermemory file storage | |
| UALL_DATA_DIR | Legacy alias for SUPERMEMORY_STORAGE_PATH |
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableyashvanthange/supermemory is public and reachablegithub.com/yashvanthange/supermemory ↗Pass
- Package names this repository as its sourcesupermemory-agent names yashvanthange/supermemory as sourcepypi.org/project/supermemory-agent/ ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-06-13github.com/yashvanthange/supermemory ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from supermemory-agentPass
- No critical advisory in the package or its dependencies40 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSuperMemory
MCP-first agent learning layer for Claude, Cursor, and custom agent workflows.
SuperMemory captures distilled lessons from failures and corrections — not full conversation transcripts — validates them before storage, and improves agents over time through a closed-loop cycle.
Quick start
pip install supermemory-agent
supermemory-agent --storage .supermemory --transport stdio
Or with uv:
uvx supermemory-agent --storage .supermemory --transport stdio
Latest release: v0.2.4 — wheel + sdist attached on every GitHub Release.
What you get
| Component | Description |
|---|---|
| MCP server | 29 tools + 4 resources over stdio (or streamable HTTP) |
| Agent skill | skills/supermemory-agent-learning/SKILL.md — bundled in the PyPI package |
| Python SDK | In-process integration via uall_python |
| REST API | FastAPI server for remote / polyglot clients |
| Storage | Local .supermemory/ files by default; SQLite and PostgreSQL optional |
Everything lives in one repo: MCP server, skills, SDK, REST API, tests, and release packages.
Install
PyPI (recommended)
pip install supermemory-agent
After install, bundled skills are at site-packages/skills/supermemory-agent-learning/. Copy to your editor skills folder if needed.
GitHub Release (offline / pinned version)
Each release ships installable assets:
pip install https://github.com/YashvantHange/SuperMemory/releases/download/v0.2.4/supermemory_agent-0.2.4-py3-none-any.whl
Browse all versions: github.com/YashvantHange/SuperMemory/releases
From source (developers)
git clone https://github.com/YashvantHange/SuperMemory.git
cd SuperMemory
pip install -e ".[dev]"
python -m pytest tests/ -v
Configure MCP
Cursor
Copy examples/cursor.mcp.json to .cursor/mcp.json in your project:
{
"mcpServers": {
"supermemory": {
"command": "supermemory-agent",
"args": ["--storage", ".supermemory", "--transport", "stdio"]
}
}
}
Claude Desktop
Merge examples/claude_desktop_config.json into:
%APPDATA%\Claude\claude_desktop_config.json
Restart Claude Desktop after saving.
Run manually
Do not run supermemory-agent alone in a terminal — stdio mode expects JSON-RPC from an MCP client. Pressing Enter in the shell causes a JSON parse error.
# For local HTTP testing only:
supermemory-agent --transport streamable-http
When configured in Cursor or Claude Desktop, the client launches the server automatically over stdio.
Agent skills (Cursor + Claude Code)
| Source | Path |
|---|---|
| Canonical (edit here) | skills/supermemory-agent-learning/ |
| Cursor project | .cursor/skills/supermemory-agent-learning/ |
| Claude Code project | .claude/skills/supermemory-agent-learning/ |
| PyPI install | site-packages/skills/supermemory-agent-learning/ |
After editing skills/, sync copies:
python scripts/sync_skills.py
Mention SuperMemory, agent learning, or MCP memory in chat to load the skill.
Learning loop
retrieve → record_failure → reflect(event_ids) → validate → process_promotions
→ retrieve again → report_outcome
Core rule: capture workflow outcomes and distilled lessons only — never full transcripts. Default retrieval budget: max_tokens=800.
MCP tools (29)
Core (13): retrieve, record_event, record_failure, record_correction, reflect, validate, process_promotions, report_outcome, get_policies, add_policy, add_skill, search_skills, get_skill
Extended 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
All tools include MCP safety annotations (readOnlyHint / destructiveHint).
MCP resources (4)
supermemory://policies/activesupermemory://lessons/{lesson_id}supermemory://memory/{lesson_id}/provenancesupermemory://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
SuperMemory MCP questions
How do I add SuperMemory MCP to Claude Code?
Run claude mcp add supermemory -- uvx supermemory-agent in your terminal. Add --scope user to make it available in every project.
How do I add SuperMemory MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What does SuperMemory capture?
It captures distilled lessons from failures and corrections rather than full conversation transcripts.