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 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/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