meminumb 0.1.0__py3-none-any.whl

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.
meminumb/__init__.py ADDED
@@ -0,0 +1,16 @@
1
+ """
2
+ Meminumb — reliable memory layer for AI agents.
3
+
4
+ Public API:
5
+ Memory — main class
6
+ AddResult — returned by Memory.add()
7
+ SkipReason — why a fact was not stored
8
+ MemoryItem — a stored memory
9
+ SkippedItem — a fact that was not stored, with reason
10
+ """
11
+
12
+ from meminumb.memory import Memory
13
+ from meminumb.result import AddResult, MemoryItem, SkippedItem, SkipReason
14
+
15
+ __all__ = ["Memory", "AddResult", "MemoryItem", "SkipReason", "SkippedItem"]
16
+ __version__ = "0.1.0"
meminumb/_id.py ADDED
@@ -0,0 +1,15 @@
1
+ from __future__ import annotations
2
+
3
+ import hashlib
4
+
5
+
6
+ def content_id(content: str, user_id: str = "", agent_id: str = "") -> str:
7
+ """
8
+ Deterministic 16-char hex ID derived from the content and its scope.
9
+
10
+ The same fact for the same user/agent always produces the same ID, so
11
+ re-adding an identical fact is detected as a duplicate without any DB
12
+ round-trip beyond an existence check.
13
+ """
14
+ key = f"{user_id}:{agent_id}:{content.strip().lower()}"
15
+ return hashlib.sha256(key.encode()).hexdigest()[:16]
meminumb/embedder.py ADDED
@@ -0,0 +1,83 @@
1
+ from __future__ import annotations
2
+
3
+ import hashlib
4
+ from abc import ABC, abstractmethod
5
+
6
+
7
+ class BaseEmbedder(ABC):
8
+ """Interface all embedders must satisfy."""
9
+
10
+ @abstractmethod
11
+ def embed(self, text: str) -> list[float]:
12
+ """Return a fixed-length embedding vector for the given text."""
13
+
14
+
15
+ class DummyEmbedder(BaseEmbedder):
16
+ """
17
+ Deterministic embedder for tests and offline demos.
18
+
19
+ No external dependencies. Produces a reproducible 64-dim vector from
20
+ an MD5 hash of the text — not semantically meaningful, but good enough
21
+ to exercise the full memory pipeline without any API calls.
22
+ """
23
+
24
+ DIM = 64
25
+
26
+ def embed(self, text: str) -> list[float]:
27
+ digest = hashlib.md5(text.encode()).digest()
28
+ # Tile the 16-byte digest to fill DIM floats in [0, 1]
29
+ values = []
30
+ for i in range(self.DIM):
31
+ values.append(digest[i % 16] / 255.0)
32
+ return values
33
+
34
+
35
+ class LocalEmbedder(BaseEmbedder):
36
+ """
37
+ Embedder backed by sentence-transformers (runs fully offline).
38
+
39
+ Install: pip install meminumb[local]
40
+ Default model: all-MiniLM-L6-v2 (384 dims, ~90 MB, fast on CPU)
41
+ """
42
+
43
+ def __init__(self, model: str = "all-MiniLM-L6-v2") -> None:
44
+ try:
45
+ from sentence_transformers import SentenceTransformer # type: ignore
46
+ except ImportError as exc:
47
+ raise ImportError(
48
+ "LocalEmbedder requires sentence-transformers. "
49
+ "Install it with: pip install meminumb[local]"
50
+ ) from exc
51
+ self._model = SentenceTransformer(model)
52
+
53
+ def embed(self, text: str) -> list[float]:
54
+ return self._model.encode(text).tolist()
55
+
56
+
57
+ class OpenAIEmbedder(BaseEmbedder):
58
+ """
59
+ Embedder backed by the OpenAI Embeddings API.
60
+
61
+ Install: pip install meminumb[openai]
62
+ Requires OPENAI_API_KEY environment variable (or pass api_key=).
63
+ Default model: text-embedding-3-small (1536 dims)
64
+ """
65
+
66
+ def __init__(
67
+ self,
68
+ model: str = "text-embedding-3-small",
69
+ api_key: str | None = None,
70
+ ) -> None:
71
+ try:
72
+ from openai import OpenAI # type: ignore
73
+ except ImportError as exc:
74
+ raise ImportError(
75
+ "OpenAIEmbedder requires the openai package. "
76
+ "Install it with: pip install meminumb[openai]"
77
+ ) from exc
78
+ self._client = OpenAI(api_key=api_key)
79
+ self._model = model
80
+
81
+ def embed(self, text: str) -> list[float]:
82
+ response = self._client.embeddings.create(input=text, model=self._model)
83
+ return response.data[0].embedding
meminumb/memory.py ADDED
@@ -0,0 +1,174 @@
1
+ from __future__ import annotations
2
+
3
+ from typing import Optional
4
+
5
+ from meminumb._id import content_id
6
+ from meminumb.embedder import BaseEmbedder, DummyEmbedder
7
+ from meminumb.result import AddResult, MemoryItem, SkippedItem, SkipReason
8
+ from meminumb.store import SQLiteStore
9
+
10
+
11
+ class Memory:
12
+ """
13
+ Reliable memory layer for AI agents.
14
+
15
+ Key guarantees:
16
+ - Every add() call returns an AddResult. Nothing is silently dropped.
17
+ - Writes are atomic: a failure leaves no orphaned data in the store.
18
+ - Facts are content-addressed: adding the same fact twice is a no-op
19
+ (reported as skipped, not silently ignored and not duplicated).
20
+
21
+ Quickstart::
22
+
23
+ from meminumb import Memory
24
+ mem = Memory()
25
+ result = mem.add(["Alice likes jazz", "Alice dislikes spicy food"], user_id="alice")
26
+ print(result) # AddResult(stored=2, skipped=0, failed=0)
27
+
28
+ hits = mem.search("what music does Alice enjoy?", user_id="alice")
29
+ print(hits[0].content) # Alice likes jazz
30
+ """
31
+
32
+ def __init__(
33
+ self,
34
+ store: Optional[SQLiteStore] = None,
35
+ embedder: Optional[BaseEmbedder] = None,
36
+ db_path: str = ":memory:",
37
+ ) -> None:
38
+ self._store = store or SQLiteStore(db_path)
39
+ self._embedder = embedder or DummyEmbedder()
40
+
41
+ # ------------------------------------------------------------------
42
+ # Write
43
+ # ------------------------------------------------------------------
44
+
45
+ def add(
46
+ self,
47
+ facts: list[str],
48
+ user_id: str = "",
49
+ agent_id: str = "",
50
+ metadata: Optional[dict] = None,
51
+ ) -> AddResult:
52
+ """
53
+ Store a list of facts. Returns an AddResult describing the outcome
54
+ of every individual fact — stored, skipped, or failed.
55
+
56
+ Args:
57
+ facts: Plain-text facts to remember.
58
+ user_id: Scope the memory to a specific user.
59
+ agent_id: Scope the memory to a specific agent (optional).
60
+ metadata: Extra key/value pairs stored alongside each fact.
61
+ """
62
+ result = AddResult()
63
+ base_meta = {"user_id": user_id, "agent_id": agent_id, **(metadata or {})}
64
+
65
+ for fact in facts:
66
+ fact = fact.strip()
67
+ if not fact:
68
+ continue
69
+
70
+ fid = content_id(fact, user_id, agent_id)
71
+
72
+ # 1. Duplicate check — no write attempted
73
+ if self._store.exists(fid):
74
+ result.skipped.append(
75
+ SkippedItem(
76
+ content=fact,
77
+ reason=SkipReason.DUPLICATE,
78
+ existing_id=fid,
79
+ )
80
+ )
81
+ continue
82
+
83
+ # 2. Embed — may fail if the embedder is unavailable
84
+ try:
85
+ embedding = self._embedder.embed(fact)
86
+ except Exception as exc:
87
+ result.failed.append(
88
+ SkippedItem(
89
+ content=fact,
90
+ reason=SkipReason.EMBED_FAILED,
91
+ error=str(exc),
92
+ )
93
+ )
94
+ continue
95
+
96
+ # 3. Atomic write — SQLite rolls back automatically on any error
97
+ try:
98
+ item = MemoryItem(id=fid, content=fact, metadata=base_meta)
99
+ self._store.add_atomic(item, embedding)
100
+ result.stored.append(item)
101
+ except Exception as exc:
102
+ result.failed.append(
103
+ SkippedItem(
104
+ content=fact,
105
+ reason=SkipReason.INSERT_FAILED,
106
+ error=str(exc),
107
+ )
108
+ )
109
+
110
+ return result
111
+
112
+ def update(
113
+ self,
114
+ memory_id: str,
115
+ content: Optional[str] = None,
116
+ metadata: Optional[dict] = None,
117
+ ) -> MemoryItem:
118
+ """
119
+ Update an existing memory's content and/or metadata.
120
+
121
+ If content changes, it is re-embedded automatically.
122
+ Returns the updated MemoryItem.
123
+ Raises KeyError if memory_id does not exist.
124
+
125
+ Args:
126
+ memory_id: ID of the memory to update.
127
+ content: New content text. If omitted, content is unchanged.
128
+ metadata: Extra key/value pairs to merge into existing metadata.
129
+ """
130
+ if not self._store.exists(memory_id):
131
+ raise KeyError(f"Memory '{memory_id}' not found.")
132
+
133
+ new_embedding = None
134
+ if content is not None:
135
+ content = content.strip()
136
+ new_embedding = self._embedder.embed(content)
137
+
138
+ self._store.update_atomic(memory_id, content, new_embedding, metadata)
139
+ return self._store.get(memory_id)
140
+
141
+ def delete(self, memory_id: str) -> bool:
142
+ """Remove a memory by its ID. Returns True if it existed."""
143
+ return self._store.delete(memory_id)
144
+
145
+ def clear(self, user_id: str = "") -> int:
146
+ """Delete all memories (optionally scoped to a user). Returns count deleted."""
147
+ return self._store.clear(user_id or None)
148
+
149
+ # ------------------------------------------------------------------
150
+ # Read
151
+ # ------------------------------------------------------------------
152
+
153
+ def get(self, memory_id: str) -> Optional[MemoryItem]:
154
+ """Fetch a single memory by ID, or None if not found."""
155
+ return self._store.get(memory_id)
156
+
157
+ def search(
158
+ self,
159
+ query: str,
160
+ user_id: str = "",
161
+ top_k: int = 5,
162
+ ) -> list[MemoryItem]:
163
+ """
164
+ Return the top_k most relevant memories for the given query.
165
+
166
+ Uses cosine similarity between the query embedding and stored
167
+ embeddings. Scoped to user_id when provided.
168
+ """
169
+ query_embedding = self._embedder.embed(query)
170
+ return self._store.search(query_embedding, top_k=top_k, user_id=user_id or None)
171
+
172
+ def get_all(self, user_id: str = "") -> list[MemoryItem]:
173
+ """Return all stored memories, optionally filtered by user_id."""
174
+ return self._store.all(user_id=user_id or None)
meminumb/result.py ADDED
@@ -0,0 +1,61 @@
1
+ from __future__ import annotations
2
+
3
+ from dataclasses import dataclass, field
4
+ from enum import Enum
5
+ from typing import Optional
6
+
7
+
8
+ class SkipReason(str, Enum):
9
+ """Why a fact was not stored."""
10
+
11
+ DUPLICATE = "duplicate"
12
+ EMBED_FAILED = "embed_failed"
13
+ INSERT_FAILED = "insert_failed"
14
+
15
+
16
+ @dataclass
17
+ class MemoryItem:
18
+ """A successfully stored memory."""
19
+
20
+ id: str
21
+ content: str
22
+ metadata: dict = field(default_factory=dict)
23
+
24
+
25
+ @dataclass
26
+ class SkippedItem:
27
+ """A fact that was not stored, with a machine-readable reason."""
28
+
29
+ content: str
30
+ reason: SkipReason
31
+ existing_id: Optional[str] = None
32
+ error: Optional[str] = None
33
+
34
+
35
+ @dataclass
36
+ class AddResult:
37
+ """
38
+ The full outcome of a Memory.add() call.
39
+
40
+ Every fact ends up in exactly one of the three lists:
41
+ - stored: written to the store successfully
42
+ - skipped: intentionally not written (e.g. duplicate)
43
+ - failed: write attempted but raised an error
44
+
45
+ Nothing is ever silently dropped.
46
+ """
47
+
48
+ stored: list[MemoryItem] = field(default_factory=list)
49
+ skipped: list[SkippedItem] = field(default_factory=list)
50
+ failed: list[SkippedItem] = field(default_factory=list)
51
+
52
+ @property
53
+ def all_succeeded(self) -> bool:
54
+ return len(self.failed) == 0
55
+
56
+ def __repr__(self) -> str:
57
+ return (
58
+ f"AddResult(stored={len(self.stored)}, "
59
+ f"skipped={len(self.skipped)}, "
60
+ f"failed={len(self.failed)})"
61
+ )
meminumb/store.py ADDED
@@ -0,0 +1,194 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import math
5
+ import sqlite3
6
+ import time
7
+ from pathlib import Path
8
+ from typing import Optional
9
+
10
+ from meminumb.result import MemoryItem
11
+
12
+ _SCHEMA = """
13
+ CREATE TABLE IF NOT EXISTS memories (
14
+ id TEXT PRIMARY KEY,
15
+ content TEXT NOT NULL,
16
+ metadata TEXT NOT NULL DEFAULT '{}',
17
+ embedding TEXT NOT NULL DEFAULT '[]',
18
+ created_at REAL NOT NULL
19
+ );
20
+ """
21
+
22
+
23
+ class SQLiteStore:
24
+ """
25
+ SQLite-backed memory store.
26
+
27
+ All writes use a context-manager transaction so a partial failure
28
+ (e.g. a constraint violation mid-write) automatically rolls back,
29
+ leaving no orphaned rows.
30
+ """
31
+
32
+ def __init__(self, path: str = ":memory:") -> None:
33
+ if path != ":memory:":
34
+ Path(path).parent.mkdir(parents=True, exist_ok=True)
35
+ self._conn = sqlite3.connect(path, check_same_thread=False)
36
+ self._conn.execute("PRAGMA journal_mode=WAL")
37
+ self._conn.execute(_SCHEMA)
38
+ self._conn.commit()
39
+
40
+ # ------------------------------------------------------------------
41
+ # Write
42
+ # ------------------------------------------------------------------
43
+
44
+ def add_atomic(self, item: MemoryItem, embedding: list[float]) -> None:
45
+ """
46
+ Write a memory and its embedding in one atomic transaction.
47
+
48
+ If anything fails (constraint error, disk full, …) the connection's
49
+ context manager rolls back automatically — no orphan is left behind.
50
+ """
51
+ with self._conn:
52
+ self._conn.execute(
53
+ "INSERT INTO memories (id, content, metadata, embedding, created_at) "
54
+ "VALUES (?, ?, ?, ?, ?)",
55
+ (
56
+ item.id,
57
+ item.content,
58
+ json.dumps(item.metadata),
59
+ json.dumps(embedding),
60
+ time.time(),
61
+ ),
62
+ )
63
+
64
+ def update_atomic(
65
+ self,
66
+ memory_id: str,
67
+ content: Optional[str],
68
+ embedding: Optional[list[float]],
69
+ metadata: Optional[dict],
70
+ ) -> bool:
71
+ """
72
+ Update content, embedding, and/or metadata for an existing memory.
73
+
74
+ Returns False if the memory_id does not exist, True on success.
75
+ The update is atomic — a failure leaves the original row unchanged.
76
+ """
77
+ existing = self.get(memory_id)
78
+ if existing is None:
79
+ return False
80
+
81
+ new_content = content if content is not None else existing.content
82
+ new_embedding = embedding if embedding is not None else json.loads(
83
+ self._conn.execute(
84
+ "SELECT embedding FROM memories WHERE id = ?", (memory_id,)
85
+ ).fetchone()[0]
86
+ )
87
+ new_metadata = {**existing.metadata, **(metadata or {})}
88
+
89
+ with self._conn:
90
+ self._conn.execute(
91
+ "UPDATE memories SET content = ?, embedding = ?, metadata = ? WHERE id = ?",
92
+ (new_content, json.dumps(new_embedding), json.dumps(new_metadata), memory_id),
93
+ )
94
+ return True
95
+
96
+ def delete(self, memory_id: str) -> bool:
97
+ with self._conn:
98
+ cur = self._conn.execute(
99
+ "DELETE FROM memories WHERE id = ?", (memory_id,)
100
+ )
101
+ return cur.rowcount > 0
102
+
103
+ def clear(self, user_id: Optional[str] = None) -> int:
104
+ with self._conn:
105
+ if user_id:
106
+ cur = self._conn.execute(
107
+ "DELETE FROM memories WHERE json_extract(metadata, '$.user_id') = ?",
108
+ (user_id,),
109
+ )
110
+ else:
111
+ cur = self._conn.execute("DELETE FROM memories")
112
+ return cur.rowcount
113
+
114
+ # ------------------------------------------------------------------
115
+ # Read
116
+ # ------------------------------------------------------------------
117
+
118
+ def exists(self, memory_id: str) -> bool:
119
+ cur = self._conn.execute(
120
+ "SELECT 1 FROM memories WHERE id = ?", (memory_id,)
121
+ )
122
+ return cur.fetchone() is not None
123
+
124
+ def get(self, memory_id: str) -> Optional[MemoryItem]:
125
+ cur = self._conn.execute(
126
+ "SELECT id, content, metadata FROM memories WHERE id = ?", (memory_id,)
127
+ )
128
+ row = cur.fetchone()
129
+ if row is None:
130
+ return None
131
+ return MemoryItem(id=row[0], content=row[1], metadata=json.loads(row[2]))
132
+
133
+ def search(
134
+ self,
135
+ query_embedding: list[float],
136
+ top_k: int = 5,
137
+ user_id: Optional[str] = None,
138
+ ) -> list[MemoryItem]:
139
+ """Return top_k memories ranked by cosine similarity to query_embedding."""
140
+ if user_id:
141
+ cur = self._conn.execute(
142
+ "SELECT id, content, metadata, embedding FROM memories "
143
+ "WHERE json_extract(metadata, '$.user_id') = ?",
144
+ (user_id,),
145
+ )
146
+ else:
147
+ cur = self._conn.execute(
148
+ "SELECT id, content, metadata, embedding FROM memories"
149
+ )
150
+ rows = cur.fetchall()
151
+ if not rows:
152
+ return []
153
+
154
+ scored = []
155
+ for row_id, content, metadata_json, embedding_json in rows:
156
+ emb = json.loads(embedding_json)
157
+ score = _cosine(query_embedding, emb)
158
+ scored.append((score, row_id, content, metadata_json))
159
+
160
+ scored.sort(key=lambda x: x[0], reverse=True)
161
+ return [
162
+ MemoryItem(id=r[1], content=r[2], metadata=json.loads(r[3]))
163
+ for r in scored[:top_k]
164
+ ]
165
+
166
+ def all(self, user_id: Optional[str] = None) -> list[MemoryItem]:
167
+ if user_id:
168
+ cur = self._conn.execute(
169
+ "SELECT id, content, metadata FROM memories "
170
+ "WHERE json_extract(metadata, '$.user_id') = ?",
171
+ (user_id,),
172
+ )
173
+ else:
174
+ cur = self._conn.execute("SELECT id, content, metadata FROM memories")
175
+ return [
176
+ MemoryItem(id=r[0], content=r[1], metadata=json.loads(r[2]))
177
+ for r in cur.fetchall()
178
+ ]
179
+
180
+
181
+ # ------------------------------------------------------------------
182
+ # Helpers
183
+ # ------------------------------------------------------------------
184
+
185
+
186
+ def _cosine(a: list[float], b: list[float]) -> float:
187
+ if len(a) != len(b):
188
+ return 0.0
189
+ dot = sum(x * y for x, y in zip(a, b))
190
+ mag_a = math.sqrt(sum(x * x for x in a))
191
+ mag_b = math.sqrt(sum(x * x for x in b))
192
+ if mag_a == 0 or mag_b == 0:
193
+ return 0.0
194
+ return dot / (mag_a * mag_b)
@@ -0,0 +1,252 @@
1
+ Metadata-Version: 2.5
2
+ Name: meminumb
3
+ Version: 0.1.0
4
+ Summary: Lightweight, reliable memory layer for AI agents — atomic writes, explicit outcomes
5
+ Project-URL: Repository, https://github.com/H-S-Prajwal/Meminumb
6
+ Project-URL: Issues, https://github.com/H-S-Prajwal/Meminumb/issues
7
+ License: MIT License
8
+
9
+ Copyright (c) 2026 2025sl93074
10
+
11
+ Permission is hereby granted, free of charge, to any person obtaining a copy
12
+ of this software and associated documentation files (the "Software"), to deal
13
+ in the Software without restriction, including without limitation the rights
14
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15
+ copies of the Software, and to permit persons to whom the Software is
16
+ furnished to do so, subject to the following conditions:
17
+
18
+ The above copyright notice and this permission notice shall be included in all
19
+ copies or substantial portions of the Software.
20
+
21
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27
+ SOFTWARE.
28
+ License-File: LICENSE
29
+ Keywords: agents,ai,llm,memory
30
+ Classifier: Development Status :: 3 - Alpha
31
+ Classifier: Intended Audience :: Developers
32
+ Classifier: License :: OSI Approved :: MIT License
33
+ Classifier: Programming Language :: Python :: 3
34
+ Classifier: Programming Language :: Python :: 3.10
35
+ Classifier: Programming Language :: Python :: 3.11
36
+ Classifier: Programming Language :: Python :: 3.12
37
+ Classifier: Topic :: Software Development :: Libraries
38
+ Requires-Python: >=3.10
39
+ Provides-Extra: dev
40
+ Requires-Dist: pytest-cov>=5.0; extra == 'dev'
41
+ Requires-Dist: pytest>=8.0; extra == 'dev'
42
+ Requires-Dist: ruff>=0.4; extra == 'dev'
43
+ Provides-Extra: groq
44
+ Requires-Dist: groq>=0.9; extra == 'groq'
45
+ Provides-Extra: local
46
+ Requires-Dist: sentence-transformers>=2.7; extra == 'local'
47
+ Provides-Extra: openai
48
+ Requires-Dist: openai>=1.0; extra == 'openai'
49
+ Description-Content-Type: text/markdown
50
+
51
+ # Meminumb
52
+
53
+ **Lightweight, reliable memory layer for AI agents.**
54
+
55
+ Meminumb stores facts about users across sessions so your AI agent can remember context — with two guarantees that common libraries miss:
56
+
57
+ 1. **Atomic writes** — a failure never leaves orphaned data behind
58
+ 2. **Explicit outcomes** — `add()` always tells you what happened to every fact, and why
59
+
60
+ ---
61
+
62
+ ## The problem Meminumb solves
63
+
64
+ Most AI memory libraries swallow failures silently. If your database write partially succeeds, you get orphaned entries and duplicate facts on retry. And if a fact is skipped (duplicate, embed error), you never find out why.
65
+
66
+ Meminumb fixes this by design:
67
+
68
+ | Feature | Meminumb | Typical library |
69
+ |---|---|---|
70
+ | Atomic writes (no orphaned data) | ✅ | ❌ |
71
+ | Explicit outcome per fact | ✅ | ❌ |
72
+ | Content-addressed IDs (idempotent) | ✅ | ❌ |
73
+ | Zero mandatory external deps | ✅ | ❌ |
74
+ | Pluggable embedders | ✅ | varies |
75
+
76
+ ---
77
+
78
+ ## Install
79
+
80
+ ```bash
81
+ pip install meminumb # core only (SQLite, no embeddings API)
82
+ pip install "meminumb[local]" # + sentence-transformers (offline)
83
+ pip install "meminumb[openai]" # + OpenAI embeddings API
84
+ pip install "meminumb[dev]" # + pytest, ruff (for contributors)
85
+ ```
86
+
87
+ ---
88
+
89
+ ## Quickstart
90
+
91
+ ```python
92
+ from meminumb import Memory
93
+
94
+ mem = Memory() # uses offline DummyEmbedder by default
95
+
96
+ result = mem.add(
97
+ ["Alice prefers dark mode", "Alice is a backend developer"],
98
+ user_id="alice",
99
+ )
100
+ print(result)
101
+ # AddResult(stored=2, skipped=0, failed=0)
102
+
103
+ # Try adding a duplicate
104
+ result2 = mem.add(["Alice prefers dark mode"], user_id="alice")
105
+ print(result2)
106
+ # AddResult(stored=0, skipped=1, failed=0)
107
+
108
+ skip = result2.skipped[0]
109
+ print(skip.reason, skip.existing_id)
110
+ # SkipReason.DUPLICATE 3f2a1b8e...
111
+
112
+ # Search
113
+ hits = mem.search("what does Alice like in her editor?", user_id="alice")
114
+ print(hits[0].content)
115
+ # Alice prefers dark mode
116
+ ```
117
+
118
+ ### With local embeddings (semantic search, offline)
119
+
120
+ ```python
121
+ from meminumb import Memory
122
+ from meminumb.embedder import LocalEmbedder
123
+
124
+ mem = Memory(embedder=LocalEmbedder()) # downloads ~90 MB model on first run
125
+ mem.add(["Bob enjoys hiking on weekends"], user_id="bob")
126
+ hits = mem.search("outdoor activities", user_id="bob")
127
+ print(hits[0].content)
128
+ # Bob enjoys hiking on weekends
129
+ ```
130
+
131
+ ---
132
+
133
+ ## API reference
134
+
135
+ ### `Memory(store=None, embedder=None, db_path=":memory:")`
136
+
137
+ | Parameter | Default | Description |
138
+ |---|---|---|
139
+ | `store` | `SQLiteStore(":memory:")` | Storage backend |
140
+ | `embedder` | `DummyEmbedder()` | Embedding backend |
141
+ | `db_path` | `":memory:"` | SQLite file path (pass a real path to persist) |
142
+
143
+ ### `Memory.add(facts, user_id="", agent_id="", metadata=None) → AddResult`
144
+
145
+ Returns an `AddResult` with three lists:
146
+
147
+ ```python
148
+ result.stored # List[MemoryItem] — successfully written
149
+ result.skipped # List[SkippedItem] — not written, with reason
150
+ result.failed # List[SkippedItem] — write attempted, raised error
151
+ result.all_succeeded # bool
152
+ ```
153
+
154
+ Each `SkippedItem` has:
155
+ - `.content` — the original fact
156
+ - `.reason` — `SkipReason.DUPLICATE` | `EMBED_FAILED` | `INSERT_FAILED`
157
+ - `.existing_id` — set when reason is DUPLICATE
158
+ - `.error` — error message when reason is EMBED_FAILED or INSERT_FAILED
159
+
160
+ ### Other methods
161
+
162
+ ```python
163
+ mem.search(query, user_id="", top_k=5) # → List[MemoryItem]
164
+ mem.get(memory_id) # → MemoryItem | None
165
+ mem.get_all(user_id="") # → List[MemoryItem]
166
+ mem.delete(memory_id) # → bool
167
+ mem.clear(user_id="") # → int (count deleted)
168
+ ```
169
+
170
+ ---
171
+
172
+ ## Chat demo — a bot that remembers you
173
+
174
+ The most direct way to see Meminumb in action is the conversational demo. It uses a Groq-hosted LLM (free, no credit card) and stores everything Meminumb hears about you persistently.
175
+
176
+ ```bash
177
+ pip install groq
178
+ export GROQ_API_KEY="your-key-here" # free at console.groq.com
179
+ python examples/chat_demo.py
180
+ ```
181
+
182
+ **First session:**
183
+ ```
184
+ You: Hi, I'm Prajwal. I love jazz and I'm a backend developer.
185
+ [Meminumb] Stored 3 new fact(s)
186
+ Bot: Nice to meet you Prajwal! Jazz is a great taste. What do you work on?
187
+
188
+ You: quit
189
+ ```
190
+
191
+ **Second session (new process, same memories):**
192
+ ```
193
+ [Meminumb] I remember 3 fact(s) about you from last time.
194
+
195
+ You: What do you remember about me?
196
+ Bot: You're Prajwal, a backend developer who loves jazz!
197
+ ```
198
+
199
+ Type `memory` to inspect stored facts, `clear` to wipe them.
200
+
201
+ ---
202
+
203
+ ## Persistent storage
204
+
205
+ ```python
206
+ mem = Memory(db_path="~/.meminumb/myapp.db")
207
+ ```
208
+
209
+ The database file is created automatically. Use the same path across sessions to persist memory.
210
+
211
+ ---
212
+
213
+ ## Architecture and design decisions
214
+
215
+ ### Why SQLite instead of a vector database?
216
+
217
+ Most AI memory libraries use a dedicated vector database (Qdrant, Pinecone, Chroma) alongside a separate metadata store. This creates two systems that can go out of sync — if the vector write succeeds but the metadata write fails, you have an orphaned vector with no history record. This is exactly the bug that inspired Meminumb (see [mem0ai/mem0#7879](https://github.com/mem0ai/mem0/issues/7879)).
218
+
219
+ Meminumb stores everything — content, embedding, metadata — in a single SQLite table. SQLite's WAL-mode transactions mean a write either fully commits or fully rolls back. One system, one failure mode, no orphans.
220
+
221
+ ### Why content-addressed IDs instead of random UUIDs?
222
+
223
+ A random UUID means every `add()` call needs a full-text scan to detect duplicates. It also means retrying a failed add creates a new ID each time, potentially producing duplicates.
224
+
225
+ Meminumb derives the ID from the content:
226
+ ```python
227
+ id = sha256(user_id + agent_id + content.strip().lower())[:16]
228
+ ```
229
+
230
+ Same fact + same user always produces the same ID. Duplicate detection is a single existence check. Retries are naturally idempotent — re-adding a fact that already exists is a no-op, not a duplicate.
231
+
232
+ ### Why `AddResult` instead of raising exceptions?
233
+
234
+ Raising an exception on the first failure stops processing the entire batch. In an agent loop adding 10 facts, one embed failure would silently discard the other 9.
235
+
236
+ `AddResult` processes every fact independently and classifies each into `stored`, `skipped`, or `failed` with a machine-readable `SkipReason`. The caller decides what to do — retry the failed ones, alert on duplicates, or just log. Nothing is ever silently dropped.
237
+
238
+ ### Why `update()` re-embeds on content change?
239
+
240
+ Embeddings are what power semantic search. If you change the content text but keep the old embedding, search would still find this memory based on the *old* meaning. Re-embedding on every content change keeps search results accurate with no extra work from the caller.
241
+
242
+ ---
243
+
244
+ ## Contributing
245
+
246
+ See [CONTRIBUTING.md](CONTRIBUTING.md).
247
+
248
+ ---
249
+
250
+ ## License
251
+
252
+ MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,10 @@
1
+ meminumb/__init__.py,sha256=ERFe_NqsqA7yW5XIwPSYoPJ8xxQIZixeO0obVIHO0uE,505
2
+ meminumb/_id.py,sha256=5550hILEVeCqINaBAtfg9XBu7CVh5Nzmfsi_5kYKKqk,526
3
+ meminumb/embedder.py,sha256=wr9xZ-DgihZD4eedvHpLS183tzvsZGC4tzrlXnx__uM,2617
4
+ meminumb/memory.py,sha256=5GP-7ydQZBdqOHpubx3w5C7PH9FY_3qKbY81CczvUe8,6092
5
+ meminumb/result.py,sha256=GN1gBgHv08KPPyEv_x4-GHYj97FSVTsTn6OOyB4Cxno,1479
6
+ meminumb/store.py,sha256=Fj-7nNfheAwd8EO10wF1XS_BT0Huc6sawaTtkAz89do,6532
7
+ meminumb-0.1.0.dist-info/METADATA,sha256=UQXg53V5FS69bM3-0X2PQZBgOllO0qZDnINPJJm_oNY,9240
8
+ meminumb-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
9
+ meminumb-0.1.0.dist-info/licenses/LICENSE,sha256=_4vsEzfXcQHeRPfnS3v2g4nF4HnWjEq0QaNYqKzlrZs,1068
10
+ meminumb-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 2025sl93074
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.