SuperMemory MCP

SuperMemory is an MCP-first learning memory layer for agents. It helps Claude, Cursor, and other MCP clients reuse validated lessons from prior failures, corrections, and outcomes without saving full transcripts.

The MVP is local-first and file-backed. Data is stored in .supermemory/ by default.

Install

python -m pip install -e .

Related MCP server: MemLayer

Run

python -m supermemory_mcp.server --storage .supermemory --transport stdio

If the Python user scripts directory is on your PATH, this also works:

supermemory-mcp --storage .supermemory --transport stdio

Without installing the package, run from this repository with:

$env:PYTHONPATH = "src"
python -m supermemory_mcp.server --storage .supermemory --transport stdio

For Streamable HTTP:

python -m supermemory_mcp.server --storage .supermemory --transport streamable-http

MCP Tools

• retrieve: policy-first, stage-aware memory retrieval.

• record_event: record a bounded significant event.

• record_failure: record a bounded failure signal.

• record_correction: record a bounded correction signal.

• reflect: create a candidate lesson from evidence events.

• validate: validate a candidate and enqueue approved lessons.

• process_promotions: promote pending validated lessons.

• report_outcome: report retrieved/used/accepted/improved telemetry.

• get_policies: return active policies.

• add_policy: add a local policy.

• add_skill: add a reusable workflow/skill block.

• search_skills: search reusable skills visible to the current namespace.

• get_skill: read a reusable skill by ID.

MCP Resources

• supermemory://policies/active

• supermemory://lessons/{lesson_id}

• supermemory://memory/{lesson_id}/provenance

• supermemory://skills/{skill_id}

Claude Desktop

Install the package, then add the server from examples/claude_desktop_config.json to:

%APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop after editing the config.

Cursor

Use examples/cursor.mcp.json as either:

.cursor/mcp.json

for this project, or:

%USERPROFILE%\.cursor\mcp.json

for a global Cursor MCP config.

Useful Agent Flow

retrieve
record_failure or record_correction
reflect
validate
process_promotions
retrieve again
report_outcome

This is the core closed loop: learn from meaningful evidence, validate before storing, promote only approved lessons, then update confidence from real outcomes.