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 +16 -0
- meminumb/_id.py +15 -0
- meminumb/embedder.py +83 -0
- meminumb/memory.py +174 -0
- meminumb/result.py +61 -0
- meminumb/store.py +194 -0
- meminumb-0.1.0.dist-info/METADATA +252 -0
- meminumb-0.1.0.dist-info/RECORD +10 -0
- meminumb-0.1.0.dist-info/WHEEL +4 -0
- meminumb-0.1.0.dist-info/licenses/LICENSE +21 -0
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,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.
|