# SuperMemory

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

- **Type:** MCP server
- **Install:** `agentstack add mcp-yashvanthange-supermemory`
- **Verified:** Pending review
- **Seller:** [YashvantHange](https://agentstack.voostack.com/s/yashvanthange)
- **Installs:** 0
- **Latest version:** 0.2.2
- **License:** MIT
- **Upstream author:** [YashvantHange](https://github.com/YashvantHange)
- **Source:** https://github.com/YashvantHange/SuperMemory

## Install

```sh
agentstack add mcp-yashvanthange-supermemory
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

[](https://pypi.org/project/supermemory-agent/)
[](https://github.com/YashvantHange/SuperMemory/releases)
[](LICENSE)
[](https://registry.modelcontextprotocol.io)

---

## Quick start

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

Or with [uv](https://docs.astral.sh/uv/):

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

**Latest release:** [v0.2.4](https://github.com/YashvantHange/SuperMemory/releases/tag/v0.2.4) — wheel + sdist attached on every [GitHub Release](https://github.com/YashvantHange/SuperMemory/releases).

---

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

```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](https://github.com/YashvantHange/SuperMemory/releases)

### From source (developers)

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

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

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

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

| 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

```bash
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](docs/GIT_SETUP.md) | Fix commit author name/email on GitHub |
| [docs/RELEASES.md](docs/RELEASES.md) | Release checklist — every tag ships wheel + sdist |
| [docs/PUBLISHING.md](docs/PUBLISHING.md) | PyPI, MCP Registry, Cursor & Claude directories |
| [PRIVACY.md](PRIVACY.md) | Privacy policy |
| [skills/README.md](skills/README.md) | Agent skill install paths |

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

---

## License

MIT — see [LICENSE](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [YashvantHange](https://github.com/YashvantHange)
- **Source:** [YashvantHange/SuperMemory](https://github.com/YashvantHange/SuperMemory)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Versions

- **0.2.2** — security scan: pending review — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-yashvanthange-supermemory
- Seller: https://agentstack.voostack.com/s/yashvanthange
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.