supermemory-agent 0.2.3__tar.gz → 0.2.5__tar.gz

supermemory_agent-0.2.5/.cursor/rules/no-cursor-attribution.mdc

@@ -0,0 +1,14 @@
+---
+description: Git commits must not include Cursor co-author attribution
+alwaysApply: true
+---
+
+# No Cursor commit attribution
+
+When creating git commits in this repo:
+
+- Never add `Co-authored-by: Cursor <cursoragent@cursor.com>` to commit messages.
+- Never add `Made-with: Cursor` or any other Cursor attribution trailer.
+- Do not use `git commit --trailer` for Cursor attribution.
+- Use only the user's identity as author.
+- If a co-author line is required, use the label from `.git-coauthor` (default: **SuperMemory Agent**).

supermemory_agent-0.2.5/.git-coauthor

@@ -0,0 +1,9 @@
+# Custom co-author label when Cursor adds its default attribution.
+# The git hook replaces "Co-authored-by: Cursor <cursoragent@cursor.com>"
+# with the name below before the commit is finalized.
+#
+# Use your verified GitHub email so GitHub still links commits to your profile.
+# Set COAUTHOR_NAME empty to remove co-author lines entirely instead.
+
+COAUTHOR_NAME="SuperMemory Agent"
+COAUTHOR_EMAIL="yashvanthange420@gmail.com"

{supermemory_agent-0.2.3 → supermemory_agent-0.2.5}/.github/workflows/publish.yml

@@ -1,4 +1,4 @@
-name: Publish PyPI and MCP Registry
+name: Publish Release
 
 on:
   release:
@@ -6,11 +6,11 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: read
+  contents: write
   id-token: write
 
 jobs:
-  publish-pypi:
+  build-and-publish:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -19,12 +19,27 @@ jobs:
         with:
           python-version: "3.11"
 
+      - name: Sync version from release tag
+        if: github.event_name == 'release'
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          sed -i "s/^version = \".*\"/version = \"$VERSION\"/" pyproject.toml
+          jq --arg v "$VERSION" '.version = $v | .packages[0].version = $v' server.json > server.tmp.json
+          mv server.tmp.json server.json
+          echo "Building supermemory-agent $VERSION"
+
       - name: Install build tools
-        run: pip install build twine
+        run: pip install build
 
       - name: Build package
         run: python -m build
 
+      - name: Upload release assets
+        if: github.event_name == 'release'
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
@@ -32,7 +47,7 @@ jobs:
           skip-existing: true
 
   publish-mcp-registry:
-    needs: publish-pypi
+    needs: build-and-publish
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

supermemory_agent-0.2.5/.mailmap

@@ -0,0 +1 @@
+Yashvant Hange <yashvanthange420@gmail.com> yashvanthange <yashvanthange420@gmail.com.com>

supermemory_agent-0.2.5/PKG-INFO

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: supermemory-agent
+Version: 0.2.5
+Summary: SuperMemory: MCP-first learning memory layer for Claude, Cursor, and agent workflows
+Project-URL: Homepage, https://github.com/YashvantHange/SuperMemory
+Project-URL: Repository, https://github.com/YashvantHange/SuperMemory
+Project-URL: Issues, https://github.com/YashvantHange/SuperMemory/issues
+Author-email: Yashvant Hange <yashvanthange420@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-memory,claude,cursor,mcp,model-context-protocol,supermemory
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.109
+Requires-Dist: httpx>=0.26
+Requires-Dist: mcp<2,>=1.27
+Requires-Dist: pydantic>=2.5
+Requires-Dist: python-dateutil>=2.8
+Requires-Dist: uvicorn[standard]>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: postgres
+Requires-Dist: asyncpg>=0.29; extra == 'postgres'
+Requires-Dist: psycopg2-binary>=2.9; extra == 'postgres'
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.19; extra == 'sqlite'
+Description-Content-Type: text/markdown
+
+# SuperMemory
+
+<!-- mcp-name: io.github.YashvantHange/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](https://img.shields.io/pypi/v/supermemory-agent)](https://pypi.org/project/supermemory-agent/)
+[![GitHub Release](https://img.shields.io/github/v/release/YashvantHange/SuperMemory)](https://github.com/YashvantHange/SuperMemory/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![MCP Registry](https://img.shields.io/badge/MCP-io.github.YashvantHange%2Fsupermemory-green)](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)

supermemory_agent-0.2.5/PRIVACY.md

@@ -0,0 +1,38 @@
+# SuperMemory Privacy Policy
+
+**Last updated:** June 13, 2026  
+**Contact:** yashvanthange420@gmail.com
+
+## Overview
+
+SuperMemory is a local-first MCP server. All learning data is stored on the user's machine in a `.supermemory/` directory. We do not operate a cloud backend for this product.
+
+## Data Collection
+
+- SuperMemory stores only data explicitly sent by the user or their AI agent through MCP tools (lessons, policies, skills, event summaries).
+- We do not collect telemetry, analytics, or personal information by default.
+- No data is transmitted to SuperMemory developers unless you voluntarily contact us for support.
+
+## Data Storage
+
+- Data is stored locally in the directory configured via `--storage` or `SUPERMEMORY_STORAGE_PATH` (default: `.supermemory/`).
+- Users control retention by deleting their local storage directory.
+
+## Third-Party Sharing
+
+- SuperMemory does not share user data with third parties.
+- No third-party AI models are called by the server.
+
+## Security
+
+- Local file storage only; no remote authentication required.
+- Optional streamable-http transport runs on localhost by default.
+
+## Your Rights
+
+- You may delete all stored data at any time by removing your `.supermemory/` folder.
+- For questions: yashvanthange420@gmail.com or GitHub Issues at https://github.com/YashvantHange/SuperMemory/issues
+
+## Changes
+
+We may update this policy on GitHub. Continued use after changes constitutes acceptance.

supermemory_agent-0.2.5/README.md

@@ -0,0 +1,241 @@
+# SuperMemory
+
+<!-- mcp-name: io.github.YashvantHange/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](https://img.shields.io/pypi/v/supermemory-agent)](https://pypi.org/project/supermemory-agent/)
+[![GitHub Release](https://img.shields.io/github/v/release/YashvantHange/SuperMemory)](https://github.com/YashvantHange/SuperMemory/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![MCP Registry](https://img.shields.io/badge/MCP-io.github.YashvantHange%2Fsupermemory-green)](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)