mcp-super-memory 0.4.4

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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Donggyun Seo
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,290 @@
1
+ # mcp-super-memory
2
+
3
+ [![PyPI version](https://img.shields.io/pypi/v/mcp-super-memory)](https://pypi.org/project/mcp-super-memory/)
4
+ [![Python](https://img.shields.io/pypi/pyversions/mcp-super-memory)](https://pypi.org/project/mcp-super-memory/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
+
7
+ **N:M associative memory graph for LLM agents — delivered as an MCP server.**
8
+
9
+ > Search **"Newton"** → reach **"strawberry"** through shared keys.
10
+ > Embedding similarity alone can't do this.
11
+
12
+ `mcp-super-memory` is an associative memory system for LLM agents built on a **Key/Value graph** — not a vector store. Memories live in a **Value Space**, accessed through a separate **Key Space** — one memory reachable via many keys, one key leading to many memories. This enables human-like associative leaps (multi-hop graph traversal) that pure embedding search fundamentally cannot replicate.
13
+
14
+ **Works with:** Claude Desktop · Claude Code · any MCP-compatible LLM agent
15
+
16
+ ---
17
+
18
+ ## Why Not Just Embeddings?
19
+
20
+ Every existing memory system (Mem0, A-MEM, MemGPT) stores memories as nodes and retrieves them by embedding similarity. This works until it doesn't:
21
+
22
+ ```
23
+ Query: "Newton"
24
+ Embedding search finds: "Newton discovered gravity" ✅
25
+ Embedding search misses: "user likes strawberries" ❌
26
+ ```
27
+
28
+ Super Memory finds both — because "Newton" → apple memory → fruit key → strawberry memory. The **path exists in the key graph**, not in embedding space.
29
+
30
+ ---
31
+
32
+ ## How It Works
33
+
34
+ ```
35
+ Key Space (concepts) Value Space (memories)
36
+ ───────────────────── ──────────────────────────────
37
+ [Newton] ──────────────────→ "Newton discovered gravity"
38
+ [apple] ────────┬─────────→ ↑ same memory
39
+ [gravity] ────────┘
40
+
41
+ [apple] ────────┼─────────→ "apples are red fruit"
42
+ [fruit] ──────┬─┘
43
+ [red] ──────┤
44
+
45
+ [fruit] ──────┼─────────→ "user likes strawberries"
46
+ [strawberry]────┘
47
+ ```
48
+
49
+ Search `"Newton"` → matches `[Newton]`, `[apple]` keys (1-hop) → follows shared `[fruit]` key → reaches strawberry memory (2-hop, score decayed by 0.3×).
50
+
51
+ **Results include `hop` field** — you always know if a result is direct or associative.
52
+
53
+ ---
54
+
55
+ ## Key Features
56
+
57
+ | Feature | Super Memory | A-MEM | Mem0 | MemGPT |
58
+ |---------|-------------|-------|------|--------|
59
+ | Key/Value separation | ✅ N:M | ❌ | ❌ | ❌ |
60
+ | Associative multi-hop | ✅ built-in | ❌ | ❌ | ❌ |
61
+ | Depth system | ✅ | ❌ | ❌ | partial |
62
+ | Memory versioning | ✅ supersede | overwrites | overwrites | ❌ |
63
+ | Time decay | ✅ depth-weighted | ❌ | ❌ | ❌ |
64
+ | Key types | ✅ concept/name/proper_noun | ❌ | ❌ | ❌ |
65
+ | Key merge (IDF) | ✅ | ❌ | ❌ | ❌ |
66
+ | Dual-path recall | ✅ key + content | ❌ | ❌ | ❌ |
67
+
68
+ ### Depth System
69
+
70
+ Every memory has a depth score `0.0 → 1.0`:
71
+
72
+ | Stage | Depth | Behavior |
73
+ |-------|-------|----------|
74
+ | Shallow | `< 0.3` | Recent, unverified. Easy to update or forget. |
75
+ | Medium | `0.3–0.7` | Confirmed multiple times. Stable. |
76
+ | Deep | `> 0.7` | Well-established fact. Resists correction. |
77
+
78
+ Depth increases `+0.05` each recall. Deep memories decay slower over time. If you try to correct a deep memory, it resists — its depth stays higher even after supersede.
79
+
80
+ ### Key Types
81
+
82
+ Not all keys should behave the same. Names shouldn't match semantically — "동건" shouldn't match "뉴턴" just because they're both short Korean words.
83
+
84
+ | Type | Matching | Use Case |
85
+ |------|----------|----------|
86
+ | `concept` (default) | Embedding similarity ≥ 0.35 | Topics, categories, attributes |
87
+ | `name` | Exact match only | Person names |
88
+ | `proper_noun` | Exact match only | Brands, places |
89
+
90
+ Name/proper_noun keys also get IDF penalty (`×0.5`) when they become hub keys connected to many memories, preventing them from polluting unrelated searches.
91
+
92
+ ### Versioning (not overwriting)
93
+
94
+ ```
95
+ "user lives in Seoul" (depth: 0.4 → weakened to 0.12, preserved)
96
+ ↑ superseded by
97
+ "user moved to Busan" (depth: 0.0, new)
98
+ ```
99
+
100
+ Unlike A-MEM which overwrites memory on evolution, Super Memory keeps the full history. Every correction is traceable — when did the belief change, and from what session?
101
+
102
+ ### Key Merging
103
+
104
+ ```
105
+ Add key "파이썬" → finds existing "Python" (similarity 0.87 > threshold 0.85)
106
+ → reuses existing key instead of creating duplicate
107
+ ```
108
+
109
+ Prevents key space fragmentation. Same concept across languages or phrasing stays unified.
110
+
111
+ ### Dual-Path Recall
112
+
113
+ Recall searches two paths simultaneously:
114
+
115
+ - **Path A (key matching):** Query embedding → match keys → follow links → memories
116
+ - **Path B (content matching):** Query embedding → directly compare against memory content embeddings
117
+
118
+ Scores from both paths are summed. This ensures memories are found even when they weren't tagged with the right keys.
119
+
120
+ ---
121
+
122
+ ## Architecture
123
+
124
+ ```
125
+ ┌─────────────────────────────────────────────────────────┐
126
+ │ Key Space │
127
+ │ [name] [동건] [programming] [python] [fruit] [red] │
128
+ │ ↓ ↓ ↓ ↓ ↓ ↓ │
129
+ │ [vec] [exact] [vec] [vec] [vec] [vec] │
130
+ └────────────────────────┬────────────────────────────────┘
131
+ │ N:M links
132
+
133
+ ┌─────────────────────────────────────────────────────────┐
134
+ │ Value Space │
135
+ │ "user's name is Donggeon" depth: 0.85 (deep) │
136
+ │ "user likes Python" depth: 0.30 (medium) │
137
+ │ "user likes strawberries" depth: 0.05 (shallow) │
138
+ └─────────────────────────────────────────────────────────┘
139
+ ```
140
+
141
+ **Recall algorithm (2-hop):**
142
+ 1. Embed query → find matching keys (concept: similarity ≥ 0.35, name/proper_noun: exact match)
143
+ 2. Also compare query embedding directly against memory content embeddings (≥ 0.3)
144
+ 3. Follow links → collect memories, aggregate scores (multiple key matches sum up, IDF-weighted)
145
+ 4. For each 1-hop memory: follow *its* keys → find 2-hop memories (score × `HOP_DECAY = 0.3`)
146
+ 5. Apply depth factor (`0.5 + depth × 0.5`) and time decay (depth-weighted, 30-day half-life)
147
+ 6. Return ranked results with `hop` field
148
+
149
+ ---
150
+
151
+ ## MCP Tools
152
+
153
+ The memory system exposes 8 tools via MCP:
154
+
155
+ | Tool | Description |
156
+ |------|-------------|
157
+ | `recall(query, top_k)` | N:M search with 2-hop associative traversal + content matching |
158
+ | `remember(content, keys, key_types?)` | Save memory with key concepts and optional type annotations |
159
+ | `correct(memory_id, content, keys?)` | Versioned update — old memory preserved but weakened |
160
+ | `related(memory_id)` | Find memories sharing keys (associative exploration) |
161
+ | `forget(memory_id)` | Permanently delete |
162
+ | `get_conversation(session_id, turn?)` | Load original conversation turns |
163
+ | `list_memories()` | List all stored memories with keys, depth, access count |
164
+ | `memory_stats()` | Get current key/memory/link counts |
165
+
166
+ A system prompt template is also available via `memory_system_prompt` MCP prompt — include it to instruct the agent to recall silently, use diverse keys, and never mention the memory system to users.
167
+
168
+ ---
169
+
170
+ ## Quick Start (MCP Server)
171
+
172
+ ### Claude Desktop
173
+
174
+ Add to `claude_desktop_config.json`:
175
+
176
+ **OpenAI embeddings:**
177
+ ```json
178
+ {
179
+ "mcpServers": {
180
+ "mcp-super-memory": {
181
+ "command": "uvx",
182
+ "args": ["mcp-super-memory"],
183
+ "env": {
184
+ "OPENAI_API_KEY": "your-openai-api-key"
185
+ }
186
+ }
187
+ }
188
+ }
189
+ ```
190
+
191
+ **Local embeddings (no API key required):**
192
+ ```json
193
+ {
194
+ "mcpServers": {
195
+ "mcp-super-memory": {
196
+ "command": "uvx",
197
+ "args": ["mcp-super-memory[local]"],
198
+ "env": {
199
+ "EMBEDDING_BACKEND": "local"
200
+ }
201
+ }
202
+ }
203
+ }
204
+ ```
205
+
206
+ ### Claude Code
207
+
208
+ ```bash
209
+ # OpenAI embeddings
210
+ claude mcp add mcp-super-memory -e OPENAI_API_KEY=your-openai-api-key -- uvx mcp-super-memory
211
+
212
+ # Local embeddings (no API key required)
213
+ claude mcp add mcp-super-memory -e EMBEDDING_BACKEND=local -- uvx "mcp-super-memory[local]"
214
+ ```
215
+
216
+ ### Manual / Development
217
+
218
+ ```bash
219
+ git clone https://github.com/donggyun112/mcp-super-memory
220
+ cd super-memory
221
+ ```
222
+
223
+ Create `.env`:
224
+ ```
225
+ OPENAI_API_KEY=your-openai-api-key
226
+ OPENAI_EMBEDDING_MODEL=text-embedding-3-small
227
+ ```
228
+
229
+ Or use local embeddings (no API key required):
230
+ ```
231
+ EMBEDDING_BACKEND=local
232
+ LOCAL_EMBEDDING_MODEL=paraphrase-multilingual-MiniLM-L12-v2 # optional, this is the default
233
+ ```
234
+
235
+ > **Note:** Mixing backends on existing data will break recall. If switching backends, clear `~/.super-memory/graph.json` first.
236
+
237
+ ```bash
238
+ uv sync
239
+ uv run mcp-super-memory
240
+ ```
241
+
242
+ **Requirements:**
243
+ - Python 3.12+
244
+ - OpenAI API key (for embeddings) — or `sentence-transformers` for local embeddings
245
+
246
+ ---
247
+
248
+ ## Data Storage
249
+
250
+ All data is local. No external database required.
251
+
252
+ ```
253
+ data/
254
+ ├── graph.json # keys, memories, links
255
+ └── conversations/
256
+ └── {session_id}.jsonl # original conversation turns
257
+ ```
258
+
259
+ ---
260
+
261
+ ## Limitations
262
+
263
+ - **Linear scan** — suitable for personal use (~10k memories). FAISS/ChromaDB integration planned for larger scale.
264
+ - **2-hop max** — deeper associative chains require `related()` tool calls by the agent.
265
+ - **Agent quality matters** — key selection on `remember` affects retrieval quality. System prompt tuning is important.
266
+
267
+ ---
268
+
269
+ ## Comparison with A-MEM
270
+
271
+ A-MEM (NeurIPS 2025) focuses on *memory evolution* — when new memories arrive, existing memories' descriptions update. Super Memory focuses on *memory access* — how to reach the right memory through associative paths.
272
+
273
+ They solve different problems. A-MEM asks "how do we keep memories well-organized?" Super Memory asks "how do we find memories the way humans actually think?"
274
+
275
+ The versioning approach also differs: A-MEM overwrites on evolution (current state only), Super Memory preserves history (full timeline).
276
+
277
+ ---
278
+
279
+ ## Roadmap
280
+
281
+ - [ ] FAISS/ChromaDB for scale
282
+ - [ ] Coding agent profile (different key strategies for code context)
283
+ - [ ] Memory export/import
284
+ - [ ] Multi-user support
285
+
286
+ ---
287
+
288
+ ## License
289
+
290
+ MIT
@@ -0,0 +1,5 @@
1
+ export declare const OPENAI_API_KEY: string;
2
+ export declare const OPENAI_EMBEDDING_MODEL: string;
3
+ export declare const EMBEDDING_BACKEND: string;
4
+ export declare function embedTextAsync(text: string): Promise<number[]>;
5
+ //# sourceMappingURL=embedding.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../src/embedding.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,cAAc,QAAmC,CAAC;AAC/D,eAAO,MAAM,sBAAsB,QAC6B,CAAC;AAKjE,eAAO,MAAM,iBAAiB,QACqB,CAAC;AAsCpD,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAqBpE"}
@@ -0,0 +1,59 @@
1
+ import { config } from "dotenv";
2
+ config();
3
+ import OpenAI from "openai";
4
+ export const OPENAI_API_KEY = process.env.OPENAI_API_KEY ?? "";
5
+ export const OPENAI_EMBEDDING_MODEL = process.env.OPENAI_EMBEDDING_MODEL ?? "text-embedding-3-small";
6
+ const LOCAL_EMBEDDING_MODEL = process.env.LOCAL_EMBEDDING_MODEL ?? "paraphrase-multilingual-MiniLM-L12-v2";
7
+ const _DEFAULT_BACKEND = OPENAI_API_KEY ? "openai" : "local";
8
+ export const EMBEDDING_BACKEND = process.env.EMBEDDING_BACKEND ?? _DEFAULT_BACKEND;
9
+ const EMBED_RETRIES = 3;
10
+ let _openaiClient = null;
11
+ function getOpenAIClient() {
12
+ if (!_openaiClient) {
13
+ _openaiClient = new OpenAI({ apiKey: OPENAI_API_KEY });
14
+ }
15
+ return _openaiClient;
16
+ }
17
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
18
+ let _localModel = null;
19
+ async function getLocalModel() {
20
+ if (!_localModel) {
21
+ try {
22
+ const { pipeline } = await import("@xenova/transformers");
23
+ _localModel = await pipeline("feature-extraction", LOCAL_EMBEDDING_MODEL);
24
+ }
25
+ catch {
26
+ throw new Error("@xenova/transformers is not installed.\n" +
27
+ "Install it with: npm install @xenova/transformers\n" +
28
+ "Or set OPENAI_API_KEY to use OpenAI embeddings.");
29
+ }
30
+ }
31
+ return _localModel;
32
+ }
33
+ async function embedLocal(text) {
34
+ const model = await getLocalModel();
35
+ const output = await model(text, { pooling: "mean", normalize: true });
36
+ return Array.from(output.data[0]);
37
+ }
38
+ export async function embedTextAsync(text) {
39
+ if (EMBEDDING_BACKEND === "local") {
40
+ return embedLocal(text);
41
+ }
42
+ const client = getOpenAIClient();
43
+ for (let attempt = 0; attempt < EMBED_RETRIES; attempt++) {
44
+ try {
45
+ const resp = await client.embeddings.create({
46
+ model: OPENAI_EMBEDDING_MODEL,
47
+ input: text,
48
+ });
49
+ return resp.data[0].embedding;
50
+ }
51
+ catch (err) {
52
+ if (attempt === EMBED_RETRIES - 1)
53
+ throw err;
54
+ await new Promise((resolve) => setTimeout(resolve, Math.pow(2, attempt) * 1000));
55
+ }
56
+ }
57
+ throw new Error("unreachable");
58
+ }
59
+ //# sourceMappingURL=embedding.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"embedding.js","sourceRoot":"","sources":["../src/embedding.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
package/dist/index.js ADDED
@@ -0,0 +1,13 @@
1
+ #!/usr/bin/env node
2
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
3
+ import { graph, server } from "./server.js";
4
+ async function main() {
5
+ await graph.load();
6
+ const transport = new StdioServerTransport();
7
+ await server.connect(transport);
8
+ }
9
+ main().catch((err) => {
10
+ console.error("[fatal]", err);
11
+ process.exit(1);
12
+ });
13
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE5C,KAAK,UAAU,IAAI;IACjB,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;IACnB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IAC9B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
@@ -0,0 +1,53 @@
1
+ import type { Key, Memory } from "./types.js";
2
+ export declare function sanitizeKeys(keys: unknown): string[];
3
+ export declare class MemoryGraph {
4
+ keys: Record<string, Key>;
5
+ memories: Record<string, Memory>;
6
+ private _keyToMems;
7
+ private _memToKeys;
8
+ private _supersededBy;
9
+ private _storedDim;
10
+ private _lock;
11
+ private _dirty;
12
+ static readonly HOP_DECAY = 0.3;
13
+ static readonly TIME_HALF_LIFE: number;
14
+ get linkCount(): number;
15
+ private _link;
16
+ private _hasLink;
17
+ private _unlinkMemory;
18
+ private _pruneOrphanKeys;
19
+ private _checkDim;
20
+ private _isExpired;
21
+ private _timeFactor;
22
+ private _keyIdf;
23
+ private _findDuplicate;
24
+ private _autoLinkKeys;
25
+ getKeysForMemory(memId: string): string[];
26
+ load(): Promise<void>;
27
+ save(): Promise<void>;
28
+ markDirty(): void;
29
+ flush(): Promise<void>;
30
+ findOrCreateKey(concept: string, keyType?: "concept" | "name" | "proper_noun"): Promise<string>;
31
+ add(content: string, keyConcepts: string[], options?: {
32
+ keyTypes?: Record<string, string> | null;
33
+ source?: Record<string, unknown> | null;
34
+ namespace?: string;
35
+ ttlSeconds?: number | null;
36
+ relatedTo?: string[] | null;
37
+ }): Promise<[string, boolean]>;
38
+ supersede(oldId: string, newContent: string, options?: {
39
+ keyConcepts?: string[] | null;
40
+ keyTypes?: Record<string, string> | null;
41
+ source?: Record<string, unknown> | null;
42
+ namespace?: string | null;
43
+ relatedTo?: string[] | null;
44
+ }): Promise<string>;
45
+ recall(query: string, topK?: number, namespace?: string | null, expand?: boolean): Promise<object[]>;
46
+ getRelated(memoryId: string): object[];
47
+ delete(memoryId: string): Promise<boolean>;
48
+ listAll(namespace?: string | null): object[];
49
+ cleanupExpired(): Promise<number>;
50
+ }
51
+ export declare function saveTurn(sessionId: string, role: string, content: string): Promise<number>;
52
+ export declare function loadConversation(sessionId: string, turn?: number | null): Promise<object[]>;
53
+ //# sourceMappingURL=memoryGraph.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"memoryGraph.d.ts","sourceRoot":"","sources":["../src/memoryGraph.ts"],"names":[],"mappings":"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"}