{
  "markdown": "# SuperMemory\n\n<!-- mcp-name: io.github.YashvantHange/supermemory -->\n\n**MCP-first agent learning layer** for Claude, Cursor, and custom agent workflows.\n\nSuperMemory 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.\n\n[![PyPI](https://img.shields.io/pypi/v/supermemory-agent)](https://pypi.org/project/supermemory-agent/)\n[![GitHub Release](https://img.shields.io/github/v/release/YashvantHange/SuperMemory)](https://github.com/YashvantHange/SuperMemory/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![MCP Registry](https://img.shields.io/badge/MCP-io.github.YashvantHange%2Fsupermemory-green)](https://registry.modelcontextprotocol.io)\n\n---\n\n## Quick start\n\n```bash\npip install supermemory-agent\nsupermemory-agent --storage .supermemory --transport stdio\n```\n\nOr with [uv](https://docs.astral.sh/uv/):\n\n```bash\nuvx supermemory-agent --storage .supermemory --transport stdio\n```\n\n**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).\n\n---\n\n## What you get\n\n| Component | Description |\n|-----------|-------------|\n| **MCP server** | 29 tools + 4 resources over stdio (or streamable HTTP) |\n| **Agent skill** | `skills/supermemory-agent-learning/SKILL.md` — bundled in the PyPI package |\n| **Python SDK** | In-process integration via `uall_python` |\n| **REST API** | FastAPI server for remote / polyglot clients |\n| **Storage** | Local `.supermemory/` files by default; SQLite and PostgreSQL optional |\n\nEverything lives in one repo: MCP server, skills, SDK, REST API, tests, and release packages.\n\n---\n\n## Install\n\n### PyPI (recommended)\n\n```bash\npip install supermemory-agent\n```\n\nAfter install, bundled skills are at `site-packages/skills/supermemory-agent-learning/`. Copy to your editor skills folder if needed.\n\n### GitHub Release (offline / pinned version)\n\nEach release ships installable assets:\n\n```bash\npip install https://github.com/YashvantHange/SuperMemory/releases/download/v0.2.4/supermemory_agent-0.2.4-py3-none-any.whl\n```\n\nBrowse all versions: [github.com/YashvantHange/SuperMemory/releases](https://github.com/YashvantHange/SuperMemory/releases)\n\n### From source (developers)\n\n```bash\ngit clone https://github.com/YashvantHange/SuperMemory.git\ncd SuperMemory\npip install -e \".[dev]\"\npython -m pytest tests/ -v\n```\n\n---\n\n## Configure MCP\n\n### Cursor\n\nCopy `examples/cursor.mcp.json` to `.cursor/mcp.json` in your project:\n\n```json\n{\n  \"mcpServers\": {\n    \"supermemory\": {\n      \"command\": \"supermemory-agent\",\n      \"args\": [\"--storage\", \".supermemory\", \"--transport\", \"stdio\"]\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nMerge `examples/claude_desktop_config.json` into:\n\n```\n%APPDATA%\\Claude\\claude_desktop_config.json\n```\n\nRestart Claude Desktop after saving.\n\n### Run manually\n\nDo **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.\n\n```bash\n# For local HTTP testing only:\nsupermemory-agent --transport streamable-http\n```\n\nWhen configured in Cursor or Claude Desktop, the client launches the server automatically over stdio.\n\n---\n\n## Agent skills (Cursor + Claude Code)\n\n| Source | Path |\n|--------|------|\n| **Canonical** (edit here) | `skills/supermemory-agent-learning/` |\n| **Cursor project** | `.cursor/skills/supermemory-agent-learning/` |\n| **Claude Code project** | `.claude/skills/supermemory-agent-learning/` |\n| **PyPI install** | `site-packages/skills/supermemory-agent-learning/` |\n\nAfter editing `skills/`, sync copies:\n\n```bash\npython scripts/sync_skills.py\n```\n\nMention **SuperMemory**, **agent learning**, or **MCP memory** in chat to load the skill.\n\n---\n\n## Learning loop\n\n```\nretrieve → record_failure → reflect(event_ids) → validate → process_promotions\n         → retrieve again → report_outcome\n```\n\n**Core rule:** capture workflow outcomes and distilled lessons only — never full transcripts. Default retrieval budget: `max_tokens=800`.\n\n---\n\n## MCP tools (29)\n\n**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`\n\n**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`\n\nAll tools include MCP safety annotations (`readOnlyHint` / `destructiveHint`).\n\n## MCP resources (4)\n\n- `supermemory://policies/active`\n- `supermemory://lessons/{lesson_id}`\n- `supermemory://memory/{lesson_id}/provenance`\n- `supermemory://skills/{skill_id}`\n\n---\n\n## Python SDK\n\n```python\nfrom uall_python import UALLClient\n\nclient = UALLClient(storage=\"file\")\n\nwith client.run(workflow_id=\"pdf-pipeline\", step=\"planner\", namespace=\"team:eng\") as run:\n    lessons = run.retrieve(step=\"planner\", max_tokens=800)\n    run.record_failure(snippet=\"chose OCR for searchable PDF\", tags=[\"routing\"])\n    run.report_lesson_outcome(lesson_id=\"lesson_001\", used=True, accepted=True, improved=True)\n```\n\n## REST API\n\n```bash\npython -m uall_server\n```\n\nServer: `http://localhost:8000` — see `api/openapi.yaml`.\n\n---\n\n## Storage\n\n| Tier | Backend | Config |\n|------|---------|--------|\n| Default | `.supermemory/` JSON files | `SUPERMEMORY_STORAGE_PATH` or `UALL_DATA_DIR` |\n| Optional | SQLite | `UALL_STORAGE_BACKEND=sqlite` |\n| Enterprise | PostgreSQL | `UALL_STORAGE_BACKEND=postgres` |\n\n---\n\n## Project layout\n\n```\nSuperMemory/\n├── src/supermemory_mcp/          # MCP server (29 tools, 4 resources)\n├── skills/supermemory-agent-learning/   # Agent skill (SKILL.md)\n├── packages/uall/                # Core learning engine\n├── packages/uall_python/         # Python SDK\n├── packages/uall_server/         # REST API\n├── examples/                     # Cursor + Claude Desktop MCP configs\n├── tests/                        # 74 tests incl. stdio MCP transport\n└── docs/                         # Publishing, releases, privacy\n```\n\n---\n\n## Tests\n\n```bash\npython -m pytest tests/ -v\npython -m pytest tests/test_mcp_server.py -v   # real stdio MCP transport\npython -m pytest tests/test_core.py -v         # closed-loop integration\n```\n\n---\n\n## Docs\n\n| Doc | Purpose |\n|-----|---------|\n| [docs/GIT_SETUP.md](docs/GIT_SETUP.md) | Fix commit author name/email on GitHub |\n| [docs/RELEASES.md](docs/RELEASES.md) | Release checklist — every tag ships wheel + sdist |\n| [docs/PUBLISHING.md](docs/PUBLISHING.md) | PyPI, MCP Registry, Cursor & Claude directories |\n| [PRIVACY.md](PRIVACY.md) | Privacy policy |\n| [skills/README.md](skills/README.md) | Agent skill install paths |\n\n**MCP Registry name:** `io.github.YashvantHange/supermemory`  \n**PyPI package:** `supermemory-agent`\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n",
  "bytes": 7175,
  "sha": "6855832091ffed58618435c55e52c01af1a9754a9674fef258963b19403517f9",
  "repo_slug": "yashvanthange/supermemory",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_yashvanthange_supermemory_a2085308/readme"
}