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.
- meminumb-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md +27 -0
- meminumb-0.1.0/.github/workflows/ci.yml +32 -0
- meminumb-0.1.0/.gitignore +10 -0
- meminumb-0.1.0/CONTRIBUTING.md +51 -0
- meminumb-0.1.0/LICENSE +21 -0
- meminumb-0.1.0/PKG-INFO +252 -0
- meminumb-0.1.0/README.md +202 -0
- meminumb-0.1.0/examples/basic_usage.py +40 -0
- meminumb-0.1.0/examples/chat_demo.py +178 -0
- meminumb-0.1.0/examples/persistent_storage.py +69 -0
- meminumb-0.1.0/meminumb/__init__.py +16 -0
- meminumb-0.1.0/meminumb/_id.py +15 -0
- meminumb-0.1.0/meminumb/embedder.py +83 -0
- meminumb-0.1.0/meminumb/memory.py +174 -0
- meminumb-0.1.0/meminumb/result.py +61 -0
- meminumb-0.1.0/meminumb/store.py +194 -0
- meminumb-0.1.0/pyproject.toml +44 -0
- meminumb-0.1.0/tests/test_atomicity.py +111 -0
- meminumb-0.1.0/tests/test_memory.py +102 -0
- meminumb-0.1.0/tests/test_outcomes.py +150 -0
- meminumb-0.1.0/tests/test_update.py +76 -0
|
@@ -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,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.
|
meminumb-0.1.0/PKG-INFO
ADDED
|
@@ -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).
|
meminumb-0.1.0/README.md
ADDED
|
@@ -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'))}")
|