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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. supermemory_agent-0.2.5/.cursor/rules/no-cursor-attribution.mdc +14 -0
  2. supermemory_agent-0.2.5/.git-coauthor +9 -0
  3. supermemory_agent-0.2.5/.mailmap +1 -0
  4. supermemory_agent-0.2.5/PKG-INFO +279 -0
  5. supermemory_agent-0.2.5/README.md +241 -0
  6. supermemory_agent-0.2.5/docs/GIT_SETUP.md +114 -0
  7. supermemory_agent-0.2.5/docs/release-notes-v0.2.4.md +21 -0
  8. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/pyproject.toml +1 -1
  9. supermemory_agent-0.2.5/scripts/hooks/prepare-commit-msg +35 -0
  10. supermemory_agent-0.2.5/scripts/install_git_hooks.ps1 +13 -0
  11. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/server.json +2 -2
  12. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/src/supermemory_mcp/server.py +47 -0
  13. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/tests/test_mcp_server.py +14 -0
  14. supermemory_agent-0.2.4/PKG-INFO +0 -197
  15. supermemory_agent-0.2.4/README.md +0 -159
  16. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/.claude/skills/supermemory-agent-learning/SKILL.md +0 -0
  17. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/.claude/skills/supermemory-agent-learning/examples.md +0 -0
  18. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/.claude/skills/supermemory-agent-learning/reference.md +0 -0
  19. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/.cursor/skills/supermemory-agent-learning/SKILL.md +0 -0
  20. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/.cursor/skills/supermemory-agent-learning/examples.md +0 -0
  21. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/.cursor/skills/supermemory-agent-learning/reference.md +0 -0
  22. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/.env.example +0 -0
  23. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/.github/workflows/publish.yml +0 -0
  24. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/.gitignore +0 -0
  25. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/.mcp.json +0 -0
  26. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/LICENSE +0 -0
  27. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/PRIVACY.md +0 -0
  28. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/api/openapi.yaml +0 -0
  29. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/docker-compose.yml +0 -0
  30. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/docs/PUBLISHING.md +0 -0
  31. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/docs/RELEASES.md +0 -0
  32. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/examples/claude_desktop_config.json +0 -0
  33. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/examples/cursor.mcp.json +0 -0
  34. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/examples/cursor_mcp/mcp.json +0 -0
  35. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/examples/mcp_agents/agents/ocr_worker.md +0 -0
  36. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/examples/mcp_agents/agents/orchestrator.md +0 -0
  37. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/examples/mcp_agents/agents/planner.md +0 -0
  38. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/examples/mcp_agents/multi_agent_mcp.py +0 -0
  39. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/examples/mcp_agents/run_md_agents.py +0 -0
  40. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/examples/mcp_agents/single_agent_mcp.py +0 -0
  41. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/examples/mcp_agents/skill_guided_mcp.py +0 -0
  42. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/examples/multi_agent_orchestrator/demo.py +0 -0
  43. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/__init__.py +0 -0
  44. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/analytics/service.py +0 -0
  45. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/collector/__init__.py +0 -0
  46. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/collector/service.py +0 -0
  47. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/distillation/distiller.py +0 -0
  48. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/evaluation/engine.py +0 -0
  49. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/experiments/manager.py +0 -0
  50. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/memory/__init__.py +0 -0
  51. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/memory/confidence.py +0 -0
  52. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/memory/freshness.py +0 -0
  53. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/memory/graph.py +0 -0
  54. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/memory/namespaces.py +0 -0
  55. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/memory/policies.py +0 -0
  56. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/memory/provenance.py +0 -0
  57. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/memory/pruning.py +0 -0
  58. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/memory/retrieval.py +0 -0
  59. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/memory/ttl.py +0 -0
  60. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/memory/validator.py +0 -0
  61. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/optimization/optimizers.py +0 -0
  62. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/promotion/queue.py +0 -0
  63. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/recommendations/engine.py +0 -0
  64. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/reflection/engine.py +0 -0
  65. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/rollback/manager.py +0 -0
  66. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/service.py +0 -0
  67. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/skills/library.py +0 -0
  68. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall/telemetry/retrieval.py +0 -0
  69. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall_core/__init__.py +0 -0
  70. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall_core/ports/storage.py +0 -0
  71. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall_core/providers/heuristic.py +0 -0
  72. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall_core/providers/llm.py +0 -0
  73. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall_core/schemas/__init__.py +0 -0
  74. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall_core/schemas/common.py +0 -0
  75. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall_core/schemas/events.py +0 -0
  76. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall_core/schemas/graph.py +0 -0
  77. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall_core/schemas/lesson.py +0 -0
  78. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall_core/schemas/namespace.py +0 -0
  79. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall_python/__init__.py +0 -0
  80. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall_python/client.py +0 -0
  81. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall_server/__init__.py +0 -0
  82. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/packages/uall_server/main.py +0 -0
  83. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/scripts/release.py +0 -0
  84. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/scripts/sync_skills.py +0 -0
  85. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/skills/README.md +0 -0
  86. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/skills/supermemory-agent-learning/SKILL.md +0 -0
  87. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/skills/supermemory-agent-learning/examples.md +0 -0
  88. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/skills/supermemory-agent-learning/reference.md +0 -0
  89. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/src/supermemory_mcp/__init__.py +0 -0
  90. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/src/supermemory_mcp/bridge.py +0 -0
  91. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/src/supermemory_mcp/handlers.py +0 -0
  92. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/src/supermemory_mcp/text.py +0 -0
  93. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/storage/adapters/__init__.py +0 -0
  94. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/storage/adapters/file.py +0 -0
  95. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/storage/adapters/postgres_qdrant_redis.py +0 -0
  96. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/storage/adapters/sqlite_chroma.py +0 -0
  97. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/tests/conftest.py +0 -0
  98. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/tests/run_all.py +0 -0
  99. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/tests/test_core.py +0 -0
  100. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/tests/test_mcp.py +0 -0
  101. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/tests/test_mcp_comprehensive.py +0 -0
  102. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/tests/test_mcp_rest_parity.py +0 -0
  103. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/tests/test_registry.py +0 -0
  104. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/tests/test_uall.py +0 -0
  105. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/uall_mcp/__init__.py +0 -0
  106. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/uall_mcp/client.py +0 -0
  107. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/uall_mcp/handlers.py +0 -0
  108. {supermemory_agent-0.2.4 → supermemory_agent-0.2.5}/uall_mcp/server.py +0 -0
@@ -0,0 +1,14 @@
1
+ ---
2
+ description: Git commits must not include Cursor co-author attribution
3
+ alwaysApply: true
4
+ ---
5
+
6
+ # No Cursor commit attribution
7
+
8
+ When creating git commits in this repo:
9
+
10
+ - Never add `Co-authored-by: Cursor <cursoragent@cursor.com>` to commit messages.
11
+ - Never add `Made-with: Cursor` or any other Cursor attribution trailer.
12
+ - Do not use `git commit --trailer` for Cursor attribution.
13
+ - Use only the user's identity as author.
14
+ - If a co-author line is required, use the label from `.git-coauthor` (default: **SuperMemory Agent**).
@@ -0,0 +1,9 @@
1
+ # Custom co-author label when Cursor adds its default attribution.
2
+ # The git hook replaces "Co-authored-by: Cursor <cursoragent@cursor.com>"
3
+ # with the name below before the commit is finalized.
4
+ #
5
+ # Use your verified GitHub email so GitHub still links commits to your profile.
6
+ # Set COAUTHOR_NAME empty to remove co-author lines entirely instead.
7
+
8
+ COAUTHOR_NAME="SuperMemory Agent"
9
+ COAUTHOR_EMAIL="yashvanthange420@gmail.com"
@@ -0,0 +1 @@
1
+ Yashvant Hange <yashvanthange420@gmail.com> yashvanthange <yashvanthange420@gmail.com.com>
@@ -0,0 +1,279 @@
1
+ Metadata-Version: 2.4
2
+ Name: supermemory-agent
3
+ Version: 0.2.5
4
+ Summary: SuperMemory: MCP-first learning memory layer for Claude, Cursor, and agent workflows
5
+ Project-URL: Homepage, https://github.com/YashvantHange/SuperMemory
6
+ Project-URL: Repository, https://github.com/YashvantHange/SuperMemory
7
+ Project-URL: Issues, https://github.com/YashvantHange/SuperMemory/issues
8
+ Author-email: Yashvant Hange <yashvanthange420@gmail.com>
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: agent-memory,claude,cursor,mcp,model-context-protocol,supermemory
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
20
+ Classifier: Topic :: Software Development :: Libraries
21
+ Requires-Python: >=3.10
22
+ Requires-Dist: fastapi>=0.109
23
+ Requires-Dist: httpx>=0.26
24
+ Requires-Dist: mcp<2,>=1.27
25
+ Requires-Dist: pydantic>=2.5
26
+ Requires-Dist: python-dateutil>=2.8
27
+ Requires-Dist: uvicorn[standard]>=0.27
28
+ Provides-Extra: dev
29
+ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
30
+ Requires-Dist: pytest>=7.4; extra == 'dev'
31
+ Requires-Dist: ruff>=0.1; extra == 'dev'
32
+ Provides-Extra: postgres
33
+ Requires-Dist: asyncpg>=0.29; extra == 'postgres'
34
+ Requires-Dist: psycopg2-binary>=2.9; extra == 'postgres'
35
+ Provides-Extra: sqlite
36
+ Requires-Dist: aiosqlite>=0.19; extra == 'sqlite'
37
+ Description-Content-Type: text/markdown
38
+
39
+ # SuperMemory
40
+
41
+ <!-- mcp-name: io.github.YashvantHange/supermemory -->
42
+
43
+ **MCP-first agent learning layer** for Claude, Cursor, and custom agent workflows.
44
+
45
+ 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.
46
+
47
+ [![PyPI](https://img.shields.io/pypi/v/supermemory-agent)](https://pypi.org/project/supermemory-agent/)
48
+ [![GitHub Release](https://img.shields.io/github/v/release/YashvantHange/SuperMemory)](https://github.com/YashvantHange/SuperMemory/releases)
49
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
50
+ [![MCP Registry](https://img.shields.io/badge/MCP-io.github.YashvantHange%2Fsupermemory-green)](https://registry.modelcontextprotocol.io)
51
+
52
+ ---
53
+
54
+ ## Quick start
55
+
56
+ ```bash
57
+ pip install supermemory-agent
58
+ supermemory-agent --storage .supermemory --transport stdio
59
+ ```
60
+
61
+ Or with [uv](https://docs.astral.sh/uv/):
62
+
63
+ ```bash
64
+ uvx supermemory-agent --storage .supermemory --transport stdio
65
+ ```
66
+
67
+ **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).
68
+
69
+ ---
70
+
71
+ ## What you get
72
+
73
+ | Component | Description |
74
+ |-----------|-------------|
75
+ | **MCP server** | 29 tools + 4 resources over stdio (or streamable HTTP) |
76
+ | **Agent skill** | `skills/supermemory-agent-learning/SKILL.md` — bundled in the PyPI package |
77
+ | **Python SDK** | In-process integration via `uall_python` |
78
+ | **REST API** | FastAPI server for remote / polyglot clients |
79
+ | **Storage** | Local `.supermemory/` files by default; SQLite and PostgreSQL optional |
80
+
81
+ Everything lives in one repo: MCP server, skills, SDK, REST API, tests, and release packages.
82
+
83
+ ---
84
+
85
+ ## Install
86
+
87
+ ### PyPI (recommended)
88
+
89
+ ```bash
90
+ pip install supermemory-agent
91
+ ```
92
+
93
+ After install, bundled skills are at `site-packages/skills/supermemory-agent-learning/`. Copy to your editor skills folder if needed.
94
+
95
+ ### GitHub Release (offline / pinned version)
96
+
97
+ Each release ships installable assets:
98
+
99
+ ```bash
100
+ pip install https://github.com/YashvantHange/SuperMemory/releases/download/v0.2.4/supermemory_agent-0.2.4-py3-none-any.whl
101
+ ```
102
+
103
+ Browse all versions: [github.com/YashvantHange/SuperMemory/releases](https://github.com/YashvantHange/SuperMemory/releases)
104
+
105
+ ### From source (developers)
106
+
107
+ ```bash
108
+ git clone https://github.com/YashvantHange/SuperMemory.git
109
+ cd SuperMemory
110
+ pip install -e ".[dev]"
111
+ python -m pytest tests/ -v
112
+ ```
113
+
114
+ ---
115
+
116
+ ## Configure MCP
117
+
118
+ ### Cursor
119
+
120
+ Copy `examples/cursor.mcp.json` to `.cursor/mcp.json` in your project:
121
+
122
+ ```json
123
+ {
124
+ "mcpServers": {
125
+ "supermemory": {
126
+ "command": "supermemory-agent",
127
+ "args": ["--storage", ".supermemory", "--transport", "stdio"]
128
+ }
129
+ }
130
+ }
131
+ ```
132
+
133
+ ### Claude Desktop
134
+
135
+ Merge `examples/claude_desktop_config.json` into:
136
+
137
+ ```
138
+ %APPDATA%\Claude\claude_desktop_config.json
139
+ ```
140
+
141
+ Restart Claude Desktop after saving.
142
+
143
+ ### Run manually
144
+
145
+ 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.
146
+
147
+ ```bash
148
+ # For local HTTP testing only:
149
+ supermemory-agent --transport streamable-http
150
+ ```
151
+
152
+ When configured in Cursor or Claude Desktop, the client launches the server automatically over stdio.
153
+
154
+ ---
155
+
156
+ ## Agent skills (Cursor + Claude Code)
157
+
158
+ | Source | Path |
159
+ |--------|------|
160
+ | **Canonical** (edit here) | `skills/supermemory-agent-learning/` |
161
+ | **Cursor project** | `.cursor/skills/supermemory-agent-learning/` |
162
+ | **Claude Code project** | `.claude/skills/supermemory-agent-learning/` |
163
+ | **PyPI install** | `site-packages/skills/supermemory-agent-learning/` |
164
+
165
+ After editing `skills/`, sync copies:
166
+
167
+ ```bash
168
+ python scripts/sync_skills.py
169
+ ```
170
+
171
+ Mention **SuperMemory**, **agent learning**, or **MCP memory** in chat to load the skill.
172
+
173
+ ---
174
+
175
+ ## Learning loop
176
+
177
+ ```
178
+ retrieve → record_failure → reflect(event_ids) → validate → process_promotions
179
+ → retrieve again → report_outcome
180
+ ```
181
+
182
+ **Core rule:** capture workflow outcomes and distilled lessons only — never full transcripts. Default retrieval budget: `max_tokens=800`.
183
+
184
+ ---
185
+
186
+ ## MCP tools (29)
187
+
188
+ **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`
189
+
190
+ **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`
191
+
192
+ All tools include MCP safety annotations (`readOnlyHint` / `destructiveHint`).
193
+
194
+ ## MCP resources (4)
195
+
196
+ - `supermemory://policies/active`
197
+ - `supermemory://lessons/{lesson_id}`
198
+ - `supermemory://memory/{lesson_id}/provenance`
199
+ - `supermemory://skills/{skill_id}`
200
+
201
+ ---
202
+
203
+ ## Python SDK
204
+
205
+ ```python
206
+ from uall_python import UALLClient
207
+
208
+ client = UALLClient(storage="file")
209
+
210
+ with client.run(workflow_id="pdf-pipeline", step="planner", namespace="team:eng") as run:
211
+ lessons = run.retrieve(step="planner", max_tokens=800)
212
+ run.record_failure(snippet="chose OCR for searchable PDF", tags=["routing"])
213
+ run.report_lesson_outcome(lesson_id="lesson_001", used=True, accepted=True, improved=True)
214
+ ```
215
+
216
+ ## REST API
217
+
218
+ ```bash
219
+ python -m uall_server
220
+ ```
221
+
222
+ Server: `http://localhost:8000` — see `api/openapi.yaml`.
223
+
224
+ ---
225
+
226
+ ## Storage
227
+
228
+ | Tier | Backend | Config |
229
+ |------|---------|--------|
230
+ | Default | `.supermemory/` JSON files | `SUPERMEMORY_STORAGE_PATH` or `UALL_DATA_DIR` |
231
+ | Optional | SQLite | `UALL_STORAGE_BACKEND=sqlite` |
232
+ | Enterprise | PostgreSQL | `UALL_STORAGE_BACKEND=postgres` |
233
+
234
+ ---
235
+
236
+ ## Project layout
237
+
238
+ ```
239
+ SuperMemory/
240
+ ├── src/supermemory_mcp/ # MCP server (29 tools, 4 resources)
241
+ ├── skills/supermemory-agent-learning/ # Agent skill (SKILL.md)
242
+ ├── packages/uall/ # Core learning engine
243
+ ├── packages/uall_python/ # Python SDK
244
+ ├── packages/uall_server/ # REST API
245
+ ├── examples/ # Cursor + Claude Desktop MCP configs
246
+ ├── tests/ # 74 tests incl. stdio MCP transport
247
+ └── docs/ # Publishing, releases, privacy
248
+ ```
249
+
250
+ ---
251
+
252
+ ## Tests
253
+
254
+ ```bash
255
+ python -m pytest tests/ -v
256
+ python -m pytest tests/test_mcp_server.py -v # real stdio MCP transport
257
+ python -m pytest tests/test_core.py -v # closed-loop integration
258
+ ```
259
+
260
+ ---
261
+
262
+ ## Docs
263
+
264
+ | Doc | Purpose |
265
+ |-----|---------|
266
+ | [docs/GIT_SETUP.md](docs/GIT_SETUP.md) | Fix commit author name/email on GitHub |
267
+ | [docs/RELEASES.md](docs/RELEASES.md) | Release checklist — every tag ships wheel + sdist |
268
+ | [docs/PUBLISHING.md](docs/PUBLISHING.md) | PyPI, MCP Registry, Cursor & Claude directories |
269
+ | [PRIVACY.md](PRIVACY.md) | Privacy policy |
270
+ | [skills/README.md](skills/README.md) | Agent skill install paths |
271
+
272
+ **MCP Registry name:** `io.github.YashvantHange/supermemory`
273
+ **PyPI package:** `supermemory-agent`
274
+
275
+ ---
276
+
277
+ ## License
278
+
279
+ MIT — see [LICENSE](LICENSE)
@@ -0,0 +1,241 @@
1
+ # SuperMemory
2
+
3
+ <!-- mcp-name: io.github.YashvantHange/supermemory -->
4
+
5
+ **MCP-first agent learning layer** for Claude, Cursor, and custom agent workflows.
6
+
7
+ 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.
8
+
9
+ [![PyPI](https://img.shields.io/pypi/v/supermemory-agent)](https://pypi.org/project/supermemory-agent/)
10
+ [![GitHub Release](https://img.shields.io/github/v/release/YashvantHange/SuperMemory)](https://github.com/YashvantHange/SuperMemory/releases)
11
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
12
+ [![MCP Registry](https://img.shields.io/badge/MCP-io.github.YashvantHange%2Fsupermemory-green)](https://registry.modelcontextprotocol.io)
13
+
14
+ ---
15
+
16
+ ## Quick start
17
+
18
+ ```bash
19
+ pip install supermemory-agent
20
+ supermemory-agent --storage .supermemory --transport stdio
21
+ ```
22
+
23
+ Or with [uv](https://docs.astral.sh/uv/):
24
+
25
+ ```bash
26
+ uvx supermemory-agent --storage .supermemory --transport stdio
27
+ ```
28
+
29
+ **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).
30
+
31
+ ---
32
+
33
+ ## What you get
34
+
35
+ | Component | Description |
36
+ |-----------|-------------|
37
+ | **MCP server** | 29 tools + 4 resources over stdio (or streamable HTTP) |
38
+ | **Agent skill** | `skills/supermemory-agent-learning/SKILL.md` — bundled in the PyPI package |
39
+ | **Python SDK** | In-process integration via `uall_python` |
40
+ | **REST API** | FastAPI server for remote / polyglot clients |
41
+ | **Storage** | Local `.supermemory/` files by default; SQLite and PostgreSQL optional |
42
+
43
+ Everything lives in one repo: MCP server, skills, SDK, REST API, tests, and release packages.
44
+
45
+ ---
46
+
47
+ ## Install
48
+
49
+ ### PyPI (recommended)
50
+
51
+ ```bash
52
+ pip install supermemory-agent
53
+ ```
54
+
55
+ After install, bundled skills are at `site-packages/skills/supermemory-agent-learning/`. Copy to your editor skills folder if needed.
56
+
57
+ ### GitHub Release (offline / pinned version)
58
+
59
+ Each release ships installable assets:
60
+
61
+ ```bash
62
+ pip install https://github.com/YashvantHange/SuperMemory/releases/download/v0.2.4/supermemory_agent-0.2.4-py3-none-any.whl
63
+ ```
64
+
65
+ Browse all versions: [github.com/YashvantHange/SuperMemory/releases](https://github.com/YashvantHange/SuperMemory/releases)
66
+
67
+ ### From source (developers)
68
+
69
+ ```bash
70
+ git clone https://github.com/YashvantHange/SuperMemory.git
71
+ cd SuperMemory
72
+ pip install -e ".[dev]"
73
+ python -m pytest tests/ -v
74
+ ```
75
+
76
+ ---
77
+
78
+ ## Configure MCP
79
+
80
+ ### Cursor
81
+
82
+ Copy `examples/cursor.mcp.json` to `.cursor/mcp.json` in your project:
83
+
84
+ ```json
85
+ {
86
+ "mcpServers": {
87
+ "supermemory": {
88
+ "command": "supermemory-agent",
89
+ "args": ["--storage", ".supermemory", "--transport", "stdio"]
90
+ }
91
+ }
92
+ }
93
+ ```
94
+
95
+ ### Claude Desktop
96
+
97
+ Merge `examples/claude_desktop_config.json` into:
98
+
99
+ ```
100
+ %APPDATA%\Claude\claude_desktop_config.json
101
+ ```
102
+
103
+ Restart Claude Desktop after saving.
104
+
105
+ ### Run manually
106
+
107
+ 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.
108
+
109
+ ```bash
110
+ # For local HTTP testing only:
111
+ supermemory-agent --transport streamable-http
112
+ ```
113
+
114
+ When configured in Cursor or Claude Desktop, the client launches the server automatically over stdio.
115
+
116
+ ---
117
+
118
+ ## Agent skills (Cursor + Claude Code)
119
+
120
+ | Source | Path |
121
+ |--------|------|
122
+ | **Canonical** (edit here) | `skills/supermemory-agent-learning/` |
123
+ | **Cursor project** | `.cursor/skills/supermemory-agent-learning/` |
124
+ | **Claude Code project** | `.claude/skills/supermemory-agent-learning/` |
125
+ | **PyPI install** | `site-packages/skills/supermemory-agent-learning/` |
126
+
127
+ After editing `skills/`, sync copies:
128
+
129
+ ```bash
130
+ python scripts/sync_skills.py
131
+ ```
132
+
133
+ Mention **SuperMemory**, **agent learning**, or **MCP memory** in chat to load the skill.
134
+
135
+ ---
136
+
137
+ ## Learning loop
138
+
139
+ ```
140
+ retrieve → record_failure → reflect(event_ids) → validate → process_promotions
141
+ → retrieve again → report_outcome
142
+ ```
143
+
144
+ **Core rule:** capture workflow outcomes and distilled lessons only — never full transcripts. Default retrieval budget: `max_tokens=800`.
145
+
146
+ ---
147
+
148
+ ## MCP tools (29)
149
+
150
+ **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`
151
+
152
+ **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`
153
+
154
+ All tools include MCP safety annotations (`readOnlyHint` / `destructiveHint`).
155
+
156
+ ## MCP resources (4)
157
+
158
+ - `supermemory://policies/active`
159
+ - `supermemory://lessons/{lesson_id}`
160
+ - `supermemory://memory/{lesson_id}/provenance`
161
+ - `supermemory://skills/{skill_id}`
162
+
163
+ ---
164
+
165
+ ## Python SDK
166
+
167
+ ```python
168
+ from uall_python import UALLClient
169
+
170
+ client = UALLClient(storage="file")
171
+
172
+ with client.run(workflow_id="pdf-pipeline", step="planner", namespace="team:eng") as run:
173
+ lessons = run.retrieve(step="planner", max_tokens=800)
174
+ run.record_failure(snippet="chose OCR for searchable PDF", tags=["routing"])
175
+ run.report_lesson_outcome(lesson_id="lesson_001", used=True, accepted=True, improved=True)
176
+ ```
177
+
178
+ ## REST API
179
+
180
+ ```bash
181
+ python -m uall_server
182
+ ```
183
+
184
+ Server: `http://localhost:8000` — see `api/openapi.yaml`.
185
+
186
+ ---
187
+
188
+ ## Storage
189
+
190
+ | Tier | Backend | Config |
191
+ |------|---------|--------|
192
+ | Default | `.supermemory/` JSON files | `SUPERMEMORY_STORAGE_PATH` or `UALL_DATA_DIR` |
193
+ | Optional | SQLite | `UALL_STORAGE_BACKEND=sqlite` |
194
+ | Enterprise | PostgreSQL | `UALL_STORAGE_BACKEND=postgres` |
195
+
196
+ ---
197
+
198
+ ## Project layout
199
+
200
+ ```
201
+ SuperMemory/
202
+ ├── src/supermemory_mcp/ # MCP server (29 tools, 4 resources)
203
+ ├── skills/supermemory-agent-learning/ # Agent skill (SKILL.md)
204
+ ├── packages/uall/ # Core learning engine
205
+ ├── packages/uall_python/ # Python SDK
206
+ ├── packages/uall_server/ # REST API
207
+ ├── examples/ # Cursor + Claude Desktop MCP configs
208
+ ├── tests/ # 74 tests incl. stdio MCP transport
209
+ └── docs/ # Publishing, releases, privacy
210
+ ```
211
+
212
+ ---
213
+
214
+ ## Tests
215
+
216
+ ```bash
217
+ python -m pytest tests/ -v
218
+ python -m pytest tests/test_mcp_server.py -v # real stdio MCP transport
219
+ python -m pytest tests/test_core.py -v # closed-loop integration
220
+ ```
221
+
222
+ ---
223
+
224
+ ## Docs
225
+
226
+ | Doc | Purpose |
227
+ |-----|---------|
228
+ | [docs/GIT_SETUP.md](docs/GIT_SETUP.md) | Fix commit author name/email on GitHub |
229
+ | [docs/RELEASES.md](docs/RELEASES.md) | Release checklist — every tag ships wheel + sdist |
230
+ | [docs/PUBLISHING.md](docs/PUBLISHING.md) | PyPI, MCP Registry, Cursor & Claude directories |
231
+ | [PRIVACY.md](PRIVACY.md) | Privacy policy |
232
+ | [skills/README.md](skills/README.md) | Agent skill install paths |
233
+
234
+ **MCP Registry name:** `io.github.YashvantHange/supermemory`
235
+ **PyPI package:** `supermemory-agent`
236
+
237
+ ---
238
+
239
+ ## License
240
+
241
+ MIT — see [LICENSE](LICENSE)
@@ -0,0 +1,114 @@
1
+ # Git author identity
2
+
3
+ Commits must use **your** name and a **verified GitHub email** so they appear on your profile with your avatar.
4
+
5
+ ## Fix on your machine (one time)
6
+
7
+ In PowerShell or CMD:
8
+
9
+ ```bash
10
+ git config --global user.name "Yashvant Hange"
11
+ git config --global user.email "yashvanthange420@gmail.com"
12
+ ```
13
+
14
+ Verify:
15
+
16
+ ```bash
17
+ git config --global user.name
18
+ git config --global user.email
19
+ ```
20
+
21
+ **Important:** The email must match an address added under
22
+ GitHub → **Settings → Emails** (and be verified).
23
+
24
+ Alternative — GitHub private noreply address:
25
+
26
+ ```bash
27
+ git config --global user.email "YashvantHange@users.noreply.github.com"
28
+ ```
29
+
30
+ ## Why past commits looked wrong
31
+
32
+ Earlier commits used:
33
+
34
+ - Name: `yashvanthange` (lowercase handle, not display name)
35
+ - Email: `yashvanthange420@gmail.com.com` (typo — extra `.com`)
36
+
37
+ GitHub could not link those commits to [@YashvantHange](https://github.com/YashvantHange), so they showed as an unlinked contributor.
38
+
39
+ The repo includes `.mailmap` so GitHub displays the correct name for those commits. New commits after fixing `git config` will link to your profile automatically.
40
+
41
+ ## Cursor / AI commits
42
+
43
+ When Cursor commits on your machine, it uses **your local `git config`** as author.
44
+ But Cursor also adds this line to the commit message:
45
+
46
+ ```
47
+ Co-authored-by: Cursor <cursoragent@cursor.com>
48
+ ```
49
+
50
+ GitHub then shows **cursoragent** as a second committer (`yashvanthange` + `cursoragent`).
51
+
52
+ **You cannot rename `cursoragent` inside Cursor settings** — that name is fixed by Cursor.
53
+ This repo renames it via `.git-coauthor` + a git hook.
54
+
55
+ ### Custom agent name (this repo)
56
+
57
+ Edit `.git-coauthor` in the repo root:
58
+
59
+ ```bash
60
+ COAUTHOR_NAME="SuperMemory Agent"
61
+ COAUTHOR_EMAIL="yashvanthange420@gmail.com"
62
+ ```
63
+
64
+ Install or refresh the hook:
65
+
66
+ ```powershell
67
+ powershell -ExecutionPolicy Bypass -File scripts/install_git_hooks.ps1
68
+ ```
69
+
70
+ When Cursor adds its default co-author line, the hook replaces it with:
71
+
72
+ ```
73
+ Co-authored-by: SuperMemory Agent <yashvanthange420@gmail.com>
74
+ ```
75
+
76
+ Use your verified GitHub email so commits still link to your profile.
77
+ To show **only your name** (no co-author), set `COAUTHOR_NAME=""` in `.git-coauthor`.
78
+
79
+ ### Stop Cursor attribution (recommended)
80
+
81
+ 1. Open **Cursor Settings → Agents → Attribution**
82
+ 2. Turn **off Commit Attribution** (and PR Attribution if you prefer)
83
+
84
+ For Cursor CLI, add to `%USERPROFILE%\.cursor\cli-config.json`:
85
+
86
+ ```json
87
+ {
88
+ "attribution": {
89
+ "attributeCommitsToAgent": false,
90
+ "attributePRsToAgent": false
91
+ }
92
+ }
93
+ ```
94
+
95
+ ### Repo hook (backup)
96
+
97
+ If attribution still appears, install the local hook:
98
+
99
+ ```powershell
100
+ powershell -ExecutionPolicy Bypass -File scripts/install_git_hooks.ps1
101
+ ```
102
+
103
+ This removes or renames `cursoragent@cursor.com` lines before each commit is finalized (see `.git-coauthor`).
104
+
105
+ ### Fix an already-pushed commit
106
+
107
+ Only if you are OK rewriting history on `main`:
108
+
109
+ ```bash
110
+ git commit --amend -m "Your message without the Co-authored-by line"
111
+ git push --force-with-lease
112
+ ```
113
+
114
+ For many commits, use interactive rebase or ask for help — do not force-push shared branches without coordinating.
@@ -0,0 +1,21 @@
1
+ ## What's new
2
+
3
+ - Bundle `skills/` in PyPI wheel and sdist (MCP server + `SKILL.md` ship together)
4
+ - Add `readOnlyHint` / `destructiveHint` on all 29 MCP tools (Claude Directory requirement)
5
+ - Document monorepo layout in README
6
+ - GitHub Releases now attach wheel + sdist on every tag (CI + `scripts/release.py`)
7
+ - 74 tests passing
8
+
9
+ ## Install
10
+
11
+ ```bash
12
+ pip install supermemory-agent==0.2.4
13
+ # or from this release asset:
14
+ pip install supermemory_agent-0.2.4-py3-none-any.whl
15
+ supermemory-agent --storage .supermemory --transport stdio
16
+ ```
17
+
18
+ ## Assets
19
+
20
+ - `supermemory_agent-0.2.4-py3-none-any.whl` — recommended
21
+ - `supermemory_agent-0.2.4.tar.gz` — source distribution
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "supermemory-agent"
7
- version = "0.2.4"
7
+ version = "0.2.5"
8
8
  description = "SuperMemory: MCP-first learning memory layer for Claude, Cursor, and agent workflows"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"