SuperMemory MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@SuperMemory MCP retrieve lessons for handling database connection timeouts"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
SuperMemory
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 stdioOr with uv:
uvx supermemory-agent --storage .supermemory --transport stdioLatest release: v0.2.4 — wheel + sdist attached on every GitHub Release.
Related MCP server: memmd-mcp
What you get
Component | Description |
MCP server | 29 tools + 4 resources over stdio (or streamable HTTP) |
Agent skill |
|
Python SDK | In-process integration via |
REST API | FastAPI server for remote / polyglot clients |
Storage | Local |
Everything lives in one repo: MCP server, skills, SDK, REST API, tests, and release packages.
Install
PyPI (recommended)
pip install supermemory-agentAfter 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.whlBrowse 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/ -vConfigure 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.jsonRestart 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-httpWhen configured in Cursor or Claude Desktop, the client launches the server automatically over stdio.
Agent skills (Cursor + Claude Code)
Source | Path |
Canonical (edit here) |
|
Cursor project |
|
Claude Code project |
|
PyPI install |
|
After editing skills/, sync copies:
python scripts/sync_skills.pyMention 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_outcomeCore 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_serverServer: http://localhost:8000 — see api/openapi.yaml.
Storage
Tier | Backend | Config |
Default |
|
|
Optional | SQLite |
|
Enterprise | PostgreSQL |
|
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, privacyTests
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 integrationDocs
Doc | Purpose |
Fix commit author name/email on GitHub | |
Release checklist — every tag ships wheel + sdist | |
PyPI, MCP Registry, Cursor & Claude directories | |
Privacy policy | |
Agent skill install paths |
MCP Registry name: io.github.YashvantHange/supermemory
PyPI package: supermemory-agent
License
MIT — see LICENSE
Available Tools
29 toolsadd_policyC
Add a local policy rule.
Inputs: rule (required), priority, namespace. Returns: object
add_skillC
Add a reusable skill/workflow block.
Inputs: name (required), steps (required), description (required), tools, +4 more. Returns: object
get_policiesBRead-only
Return active policies visible to a namespace.
Inputs: namespace. Returns: object
get_skillARead-only
Read a reusable skill by ID.
Inputs: skill_id (required). Returns: object
learn.analyticsDRead-only
Inputs: no named parameters. Returns: object
learn.evaluateDRead-only
Inputs: run_id (required). Returns: object
learn.experimentD
Inputs: variant_b (required), resource_id (required), traffic_split. Returns: object
learn.feedbackD
Inputs: rating (required), run_id, comment. Returns: object
learn.improvementsDRead-only
Inputs: agent_id, workflow_id. Returns: object
learn.policiesDRead-only
Inputs: no named parameters. Returns: object
learn.reflectD
Inputs: fix, step, failure, workflow, +4 more. Returns: object
learn.retrieveDRead-only
Inputs: query (required), step, workflow, namespace, +1 more. Returns: object
learn.rollbackDDestructive
Inputs: resource_id (required), resource_type (required), target_version (required). Returns: object
learn.run.endD
Inputs: run_id (required), success (required), lessons_used. Returns: object
learn.run.eventD
Inputs: run_id (required), event_type (required), step, tags, +6 more. Returns: object
learn.run.startD
Inputs: workflow_id (required), step, agent, agents, +1 more. Returns: object
learn.skillsDRead-only
Inputs: query (required). Returns: object
learn.storeD
Inputs: lesson_json (required). Returns: object
learn.telemetryD
Inputs: lesson_id (required), used, run_id, accepted, +2 more. Returns: object
learn.validateD
Inputs: fix (required), failure (required), event_ids, root_cause. Returns: object
process_promotionsC
Process pending validated lessons and promote passing items.
Inputs: limit. Returns: object
record_correctionD
Record a bounded correction signal.
Inputs: summary (required), step, tool, agent, +6 more. Returns: object
record_eventB
Record a bounded significant event. Full transcripts should not be sent here.
Inputs: summary (required), event_type (required), step, tool, +7 more. Returns: object
record_failureC
Record a bounded failure signal.
Inputs: summary (required), step, tool, agent, +6 more. Returns: object
reflectC
Create a candidate lesson from evidence events.
Inputs: event_ids (required), suggestion, lesson_text. Returns: object
report_outcomeC
Report telemetry for a retrieved lesson.
Inputs: used (required), accepted (required), improved (required), lesson_id (required), +2 more. Returns: object
retrieveCRead-only
Retrieve policy-first, stage-aware lessons.
Inputs: query (required), step, tool, agent, +7 more. Returns: object
search_skillsCRead-only
Search reusable skills visible to a namespace.
Inputs: query (required), top_k, workflow, namespace. Returns: object
validateC
Validate a lesson candidate and enqueue approved lessons for promotion.
Inputs: metadata, event_ids, reflection_id, candidate_lesson. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 29 tools
Many tools have overlapping or ambiguous names, especially the 'learn.*' tools with empty descriptions (e.g., learn.analytics, learn.evaluate) which are indistinguishable from each other. Additionally, 'retrieve' and 'learn.retrieve' appear to serve similar purposes, causing confusion.
Naming conventions are mixed: some use underscore (add_policy), some use dot notation (learn.analytics), and some are single words (reflect). The 'learn.' prefix is applied inconsistently across tools, and verb_noun patterns are not uniformly followed.
29 tools is excessive for a server that appears to manage policies, skills, and lessons. Many tools seem redundant (e.g., multiple learn.* tools) and could be consolidated. The scope does not justify this many distinct operations.
Core functionalities like adding, retrieving, and validating are present, but there are missing operations such as updating or deleting policies/skills. The learn.* tools are undocumented, leaving potential gaps in the learning pipeline unaddressed.
Maintenance
Related MCP Connectors
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
One memory for your AI agents and your team: Claude, ChatGPT, Cursor and your agents share it.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Persistent memory for AI agents to retain, retrieve, and recall conversation context through MCP.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP-native, local-first memory for coding agents that turns real sessions into reusable decisions, gotchas, and domain knowledge.171,019 PyPI7MIT
- AlicenseBqualityDmaintenanceA shared memory layer for AI agents — one memory.md synced across Claude Desktop, Cursor, Claude Code, OpenAI Codex, and any MCP client.42MIT
- AlicenseAqualityAmaintenanceHosted memory for AI agents that learns from outcomes, with shared rooms. One key across Claude, Cursor & ChatGPT.111,188 npm30MIT
- AlicenseBqualityBmaintenancePersistent, local memory for AI coding agents that learns how you work, not just what you said. Supports Claude Code, Codex CLI, Cursor, and any MCP client.79271 PyPI77MIT