SuperMemory

io.github.YashvantHangePublished by GitHub account YashvantHangev0.2.5Updated Oct 24, 2026

MCP-first agent learning: capture failures, validate lessons, retrieve context, improve.

The publisher's own server: Memory.fit

VerifiedSTDIODesktop onlyKnowledge & MemoryAI & ML

Overview

AI-generated overview

A local MCP server that records an agent's failures and corrections as distilled lessons, validates them, and retrieves relevant context later.

What you can do
SuperMemory is an MCP-first agent learning layer that captures distilled lessons from failures and corrections rather than full conversation transcripts. It exposes 29 tools and 4 resources over stdio, including retrieve, record_event, record_failure, record_correction, reflect, validate, process_promotions, report_outcome, and policy and skill tools. It also ships a Python SDK, a REST API, and an agent skill, and stores data in local .supermemory files by default, with SQLite and PostgreSQL optional.
When to use it
Use it when you want an assistant to learn from its own mistakes across sessions, for example to record why a workflow step failed and retrieve that lesson the next time a similar task runs. It suits Claude, Cursor, and custom agent workflows that need a closed-loop retrieve, record, reflect, validate, and promote cycle.
Requirements
Runs as a local process on the user's machine over stdio, installed from PyPI as supermemory-agent (pip or uvx) or from a GitHub release wheel. It needs Python and a storage location, set with SUPERMEMORY_STORAGE_PATH or the legacy UALL_DATA_DIR. No authentication is declared. Optional SQLite or PostgreSQL backends are configured by environment variable.
Before you install
It writes learning data to a local storage directory, so point SUPERMEMORY_STORAGE_PATH at a location you are comfortable persisting. Do not run the stdio command directly in a terminal, since it expects JSON-RPC from an MCP client. The README states that only distilled lessons and workflow outcomes should be captured, never full transcripts, so review what your agent records.

Installation

In SourceWeft

  1. Open SuperMemory in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

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

Or with uv:

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

Latest release: v0.2.4 — wheel + sdist attached on every GitHub Release.

What you get

ComponentDescription
MCP server29 tools + 4 resources over stdio (or streamable HTTP)
Agent skillskills/supermemory-agent-learning/SKILL.md — bundled in the PyPI package
Python SDKIn-process integration via uall_python
REST APIFastAPI server for remote / polyglot clients
StorageLocal .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)

bash
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:

bash
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)

bash
git clone https://github.com/YashvantHange/SuperMemory.gitcd SuperMemorypip install -e ".[dev]"python -m pytest tests/ -v

Configure MCP

Cursor

Copy examples/cursor.mcp.json to .cursor/mcp.json in your project:

json
{  "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.

bash
# 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)

SourcePath
Canonical (edit here)skills/supermemory-agent-learning/
Cursor project.cursor/skills/supermemory-agent-learning/
Claude Code project.claude/skills/supermemory-agent-learning/
PyPI installsite-packages/skills/supermemory-agent-learning/

After editing skills/, sync copies:

bash
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

python
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

bash
python -m uall_server

Server: http://localhost:8000 — see api/openapi.yaml.

Storage

TierBackendConfig
Default.supermemory/ JSON filesSUPERMEMORY_STORAGE_PATH or UALL_DATA_DIR
OptionalSQLiteUALL_STORAGE_BACKEND=sqlite
EnterprisePostgreSQLUALL_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

bash
python -m pytest tests/ -vpython -m pytest tests/test_mcp_server.py -v   # real stdio MCP transportpython -m pytest tests/test_core.py -v         # closed-loop integration

Docs

DocPurpose
docs/GIT_SETUP.mdFix commit author name/email on GitHub
docs/RELEASES.mdRelease checklist — every tag ships wheel + sdist
docs/PUBLISHING.mdPyPI, MCP Registry, Cursor & Claude directories
PRIVACY.mdPrivacy policy
skills/README.mdAgent skill install paths

MCP Registry name: io.github.YashvantHange/supermemory
PyPI package: supermemory-agent

License

MIT — see LICENSE

Source: README.md at commit 9849ccb

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.5LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Memory integrations

Memory.fit

fit.memoryOfficial publisher

Hosted Memory.fit server that lets an AI read your training, sleep, recovery and nutrition data and write back weekly plans, targets and meal plans.

Streamable HTTPWeb executableAuth
Location & LifestyleCredential requiredOct 29, 2026

pg.ddx.io: the PostgreSQL community's memory

io.ddx.pgOfficial publisher

pg.ddx.io: the PostgreSQL community's memory's hosted MCP server, published by pg.ddx.io; no sign-in required; Streamable HTTP; 29 tools.

Streamable HTTPWeb executable
Databases29 toolsOct 24, 2026

var.gg Naming Memory

gg.varOfficial publisher

Remote MCP server that suggests and searches code identifier names from domain concepts in Korean, Japanese, Chinese, Vietnamese and English, and exposes ERD…

Streamable HTTPWeb executable
Databases7 toolsOct 27, 2026

Counterparts

ai.counterparts

Local-first long-term memory for Claude Code and Claude Desktop: the assistant writes notes about you and your projects and recalls them in later sessions.

STDIODesktop only
Knowledge & MemoryNot validated yetNov 7, 2026

LAHZE - Persian AI Memory Platform

Published by GitHub account pedramgholizadeh

LAHZE - Persian AI Memory Platform's hosted MCP server; no sign-in required; Streamable HTTP; 13 tools.

Streamable HTTPWeb executable
Location & Lifestyle13 toolsNov 3, 2026