Skip to main content
Glama

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.

PyPI GitHub Release License: MIT MCP Registry


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.


Related MCP server: memmd-mcp

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

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

Available Tools

29 tools
add_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_policiesB
Read-only

Return active policies visible to a namespace.

Inputs: namespace. Returns: object

get_skillA
Read-only

Read a reusable skill by ID.

Inputs: skill_id (required). Returns: object

learn.analyticsD
Read-only

Inputs: no named parameters. Returns: object

learn.evaluateD
Read-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.improvementsD
Read-only

Inputs: agent_id, workflow_id. Returns: object

learn.policiesD
Read-only

Inputs: no named parameters. Returns: object

learn.reflectD

Inputs: fix, step, failure, workflow, +4 more. Returns: object

learn.retrieveD
Read-only

Inputs: query (required), step, workflow, namespace, +1 more. Returns: object

learn.rollbackD
Destructive

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.skillsD
Read-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

retrieveC
Read-only

Retrieve policy-first, stage-aware lessons.

Inputs: query (required), step, tool, agent, +7 more. Returns: object

search_skillsC
Read-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

    D1.7/5.0

    Scored across 29 tools

    Disambiguation2/5

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

    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.

    Tool Count2/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers