meminumb 0.1.0__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.
@@ -0,0 +1,27 @@
1
+ ---
2
+ name: Bug report
3
+ about: Something is broken or behaving unexpectedly
4
+ labels: bug
5
+ ---
6
+
7
+ **Describe the bug**
8
+ A clear, concise description of what the bug is.
9
+
10
+ **Minimal reproducible example**
11
+ ```python
12
+ from meminumb import Memory
13
+ mem = Memory()
14
+ # ... steps that trigger the bug
15
+ ```
16
+
17
+ **Expected behaviour**
18
+ What you expected to happen.
19
+
20
+ **Actual behaviour**
21
+ What actually happened. Include the full traceback if applicable.
22
+
23
+ **Environment**
24
+ - Meminumb version:
25
+ - Python version:
26
+ - OS:
27
+ - Embedder used (DummyEmbedder / LocalEmbedder / OpenAIEmbedder):
@@ -0,0 +1,32 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ jobs:
10
+ test:
11
+ name: Python ${{ matrix.python-version }}
12
+ runs-on: ubuntu-latest
13
+ strategy:
14
+ matrix:
15
+ python-version: ["3.10", "3.11", "3.12"]
16
+
17
+ steps:
18
+ - uses: actions/checkout@v4
19
+
20
+ - name: Set up Python ${{ matrix.python-version }}
21
+ uses: actions/setup-python@v5
22
+ with:
23
+ python-version: ${{ matrix.python-version }}
24
+
25
+ - name: Install dependencies
26
+ run: pip install -e ".[dev]"
27
+
28
+ - name: Lint
29
+ run: ruff check meminumb/ tests/
30
+
31
+ - name: Test
32
+ run: pytest tests/ -v --tb=short
@@ -0,0 +1,10 @@
1
+ __pycache__/
2
+ *.pyc
3
+ *.pyo
4
+ .venv/
5
+ *.egg-info/
6
+ dist/
7
+ build/
8
+ .pytest_cache/
9
+ .ruff_cache/
10
+ *.db
@@ -0,0 +1,51 @@
1
+ # Contributing to Meminumb
2
+
3
+ Thank you for your interest in contributing! Meminumb is a small, focused library — contributions that keep it simple and reliable are most welcome.
4
+
5
+ ## Getting started
6
+
7
+ ```bash
8
+ # Fork the repo on GitHub, then:
9
+ git clone https://github.com/<your-username>/Meminumb.git
10
+ cd Meminumb
11
+ pip install -e ".[dev]"
12
+ ```
13
+
14
+ ## Workflow
15
+
16
+ 1. **Open an issue first** — describe the bug or feature before writing code. Wait for a maintainer to label it `accepted` before opening a PR.
17
+ 2. **Create a branch** from `main`:
18
+ ```bash
19
+ git checkout -b fix/your-description
20
+ ```
21
+ 3. **Write tests** for your change. The three test files map to the three main concerns:
22
+ - `tests/test_memory.py` — happy paths
23
+ - `tests/test_atomicity.py` — failure + rollback scenarios
24
+ - `tests/test_outcomes.py` — AddResult classification
25
+ 4. **Run the full suite** before opening a PR:
26
+ ```bash
27
+ pytest tests/ -v
28
+ ruff check meminumb/ tests/
29
+ ```
30
+ 5. **Open a PR** that references the issue (`Closes #N`). Describe what you changed and why.
31
+
32
+ ## PR checklist
33
+
34
+ - [ ] Tests added or updated
35
+ - [ ] `pytest tests/ -v` passes locally
36
+ - [ ] `ruff check` passes (no lint errors)
37
+ - [ ] PR description references the linked issue
38
+
39
+ ## Code style
40
+
41
+ - Python 3.10+, type hints everywhere
42
+ - `ruff` for linting (config in `pyproject.toml`)
43
+ - No external dependencies in `meminumb/` core — optional deps go in `embedder.py` behind a try/import
44
+
45
+ ## Reporting bugs
46
+
47
+ Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md). Include a minimal reproducible example.
48
+
49
+ ## Good first issues
50
+
51
+ Look for issues labelled [`good first issue`](https://github.com/H-S-Prajwal/Meminumb/issues?q=label%3A%22good+first+issue%22).
meminumb-0.1.0/LICENSE ADDED
@@ -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.
@@ -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,202 @@
1
+ # Meminumb
2
+
3
+ **Lightweight, reliable memory layer for AI agents.**
4
+
5
+ Meminumb stores facts about users across sessions so your AI agent can remember context — with two guarantees that common libraries miss:
6
+
7
+ 1. **Atomic writes** — a failure never leaves orphaned data behind
8
+ 2. **Explicit outcomes** — `add()` always tells you what happened to every fact, and why
9
+
10
+ ---
11
+
12
+ ## The problem Meminumb solves
13
+
14
+ 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.
15
+
16
+ Meminumb fixes this by design:
17
+
18
+ | Feature | Meminumb | Typical library |
19
+ |---|---|---|
20
+ | Atomic writes (no orphaned data) | ✅ | ❌ |
21
+ | Explicit outcome per fact | ✅ | ❌ |
22
+ | Content-addressed IDs (idempotent) | ✅ | ❌ |
23
+ | Zero mandatory external deps | ✅ | ❌ |
24
+ | Pluggable embedders | ✅ | varies |
25
+
26
+ ---
27
+
28
+ ## Install
29
+
30
+ ```bash
31
+ pip install meminumb # core only (SQLite, no embeddings API)
32
+ pip install "meminumb[local]" # + sentence-transformers (offline)
33
+ pip install "meminumb[openai]" # + OpenAI embeddings API
34
+ pip install "meminumb[dev]" # + pytest, ruff (for contributors)
35
+ ```
36
+
37
+ ---
38
+
39
+ ## Quickstart
40
+
41
+ ```python
42
+ from meminumb import Memory
43
+
44
+ mem = Memory() # uses offline DummyEmbedder by default
45
+
46
+ result = mem.add(
47
+ ["Alice prefers dark mode", "Alice is a backend developer"],
48
+ user_id="alice",
49
+ )
50
+ print(result)
51
+ # AddResult(stored=2, skipped=0, failed=0)
52
+
53
+ # Try adding a duplicate
54
+ result2 = mem.add(["Alice prefers dark mode"], user_id="alice")
55
+ print(result2)
56
+ # AddResult(stored=0, skipped=1, failed=0)
57
+
58
+ skip = result2.skipped[0]
59
+ print(skip.reason, skip.existing_id)
60
+ # SkipReason.DUPLICATE 3f2a1b8e...
61
+
62
+ # Search
63
+ hits = mem.search("what does Alice like in her editor?", user_id="alice")
64
+ print(hits[0].content)
65
+ # Alice prefers dark mode
66
+ ```
67
+
68
+ ### With local embeddings (semantic search, offline)
69
+
70
+ ```python
71
+ from meminumb import Memory
72
+ from meminumb.embedder import LocalEmbedder
73
+
74
+ mem = Memory(embedder=LocalEmbedder()) # downloads ~90 MB model on first run
75
+ mem.add(["Bob enjoys hiking on weekends"], user_id="bob")
76
+ hits = mem.search("outdoor activities", user_id="bob")
77
+ print(hits[0].content)
78
+ # Bob enjoys hiking on weekends
79
+ ```
80
+
81
+ ---
82
+
83
+ ## API reference
84
+
85
+ ### `Memory(store=None, embedder=None, db_path=":memory:")`
86
+
87
+ | Parameter | Default | Description |
88
+ |---|---|---|
89
+ | `store` | `SQLiteStore(":memory:")` | Storage backend |
90
+ | `embedder` | `DummyEmbedder()` | Embedding backend |
91
+ | `db_path` | `":memory:"` | SQLite file path (pass a real path to persist) |
92
+
93
+ ### `Memory.add(facts, user_id="", agent_id="", metadata=None) → AddResult`
94
+
95
+ Returns an `AddResult` with three lists:
96
+
97
+ ```python
98
+ result.stored # List[MemoryItem] — successfully written
99
+ result.skipped # List[SkippedItem] — not written, with reason
100
+ result.failed # List[SkippedItem] — write attempted, raised error
101
+ result.all_succeeded # bool
102
+ ```
103
+
104
+ Each `SkippedItem` has:
105
+ - `.content` — the original fact
106
+ - `.reason` — `SkipReason.DUPLICATE` | `EMBED_FAILED` | `INSERT_FAILED`
107
+ - `.existing_id` — set when reason is DUPLICATE
108
+ - `.error` — error message when reason is EMBED_FAILED or INSERT_FAILED
109
+
110
+ ### Other methods
111
+
112
+ ```python
113
+ mem.search(query, user_id="", top_k=5) # → List[MemoryItem]
114
+ mem.get(memory_id) # → MemoryItem | None
115
+ mem.get_all(user_id="") # → List[MemoryItem]
116
+ mem.delete(memory_id) # → bool
117
+ mem.clear(user_id="") # → int (count deleted)
118
+ ```
119
+
120
+ ---
121
+
122
+ ## Chat demo — a bot that remembers you
123
+
124
+ 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.
125
+
126
+ ```bash
127
+ pip install groq
128
+ export GROQ_API_KEY="your-key-here" # free at console.groq.com
129
+ python examples/chat_demo.py
130
+ ```
131
+
132
+ **First session:**
133
+ ```
134
+ You: Hi, I'm Prajwal. I love jazz and I'm a backend developer.
135
+ [Meminumb] Stored 3 new fact(s)
136
+ Bot: Nice to meet you Prajwal! Jazz is a great taste. What do you work on?
137
+
138
+ You: quit
139
+ ```
140
+
141
+ **Second session (new process, same memories):**
142
+ ```
143
+ [Meminumb] I remember 3 fact(s) about you from last time.
144
+
145
+ You: What do you remember about me?
146
+ Bot: You're Prajwal, a backend developer who loves jazz!
147
+ ```
148
+
149
+ Type `memory` to inspect stored facts, `clear` to wipe them.
150
+
151
+ ---
152
+
153
+ ## Persistent storage
154
+
155
+ ```python
156
+ mem = Memory(db_path="~/.meminumb/myapp.db")
157
+ ```
158
+
159
+ The database file is created automatically. Use the same path across sessions to persist memory.
160
+
161
+ ---
162
+
163
+ ## Architecture and design decisions
164
+
165
+ ### Why SQLite instead of a vector database?
166
+
167
+ 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)).
168
+
169
+ 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.
170
+
171
+ ### Why content-addressed IDs instead of random UUIDs?
172
+
173
+ 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.
174
+
175
+ Meminumb derives the ID from the content:
176
+ ```python
177
+ id = sha256(user_id + agent_id + content.strip().lower())[:16]
178
+ ```
179
+
180
+ 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.
181
+
182
+ ### Why `AddResult` instead of raising exceptions?
183
+
184
+ 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.
185
+
186
+ `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.
187
+
188
+ ### Why `update()` re-embeds on content change?
189
+
190
+ 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.
191
+
192
+ ---
193
+
194
+ ## Contributing
195
+
196
+ See [CONTRIBUTING.md](CONTRIBUTING.md).
197
+
198
+ ---
199
+
200
+ ## License
201
+
202
+ MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,40 @@
1
+ """Basic Meminumb demo — no API key, no external services required."""
2
+
3
+ from meminumb import Memory
4
+
5
+ mem = Memory() # uses DummyEmbedder by default — works offline
6
+
7
+ # ── Add some facts ──────────────────────────────────────────────────────────
8
+ result = mem.add(
9
+ [
10
+ "Alice prefers dark mode",
11
+ "Alice is a backend developer",
12
+ "Alice uses Python and Go",
13
+ ],
14
+ user_id="alice",
15
+ )
16
+ print(result)
17
+ # AddResult(stored=3, skipped=0, failed=0)
18
+
19
+ # ── Duplicate detection ─────────────────────────────────────────────────────
20
+ result2 = mem.add(["Alice prefers dark mode"], user_id="alice")
21
+ print(result2)
22
+ # AddResult(stored=0, skipped=1, failed=0)
23
+
24
+ skip = result2.skipped[0]
25
+ print(f" skipped: '{skip.content}' — reason={skip.reason}, existing_id={skip.existing_id}")
26
+
27
+ # ── Search ──────────────────────────────────────────────────────────────────
28
+ hits = mem.search("what IDE theme does Alice use?", user_id="alice", top_k=2)
29
+ for h in hits:
30
+ print(f" → {h.content}")
31
+
32
+ # ── Get all ───────────────────────────────────────────────���─────────────────
33
+ all_items = mem.get_all(user_id="alice")
34
+ print(f"\nTotal stored for alice: {len(all_items)}")
35
+
36
+ # ── Delete ──────────────────────────────────────────────────────────────────
37
+ fid = result.stored[0].id
38
+ deleted = mem.delete(fid)
39
+ print(f"Deleted memory {fid}: {deleted}")
40
+ print(f"Remaining: {len(mem.get_all(user_id='alice'))}")