mnemolite 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.
mnemolite/__init__.py ADDED
@@ -0,0 +1,5 @@
1
+ """Mnemolite — local-first, zero-LLM memory engine for AI agents."""
2
+
3
+ from .core import PRESETS, Mnemolite, RecallWeights
4
+
5
+ __all__ = ["Mnemolite", "RecallWeights", "PRESETS"]
@@ -0,0 +1,23 @@
1
+ """Constants shared by the extraction and storage layers."""
2
+
3
+ # Nouns too vague to connect anything: keeping them turns the graph into a hub
4
+ # where unrelated episodes are linked through "thing" or "user". Lives here so
5
+ # consolidator.py (which builds nodes) and db.py (which reports concepts) agree.
6
+ GENERIC_NOUNS = {
7
+ "thing",
8
+ "way",
9
+ "today",
10
+ "tomorrow",
11
+ "yesterday",
12
+ "project",
13
+ "user",
14
+ "someone",
15
+ "anyone",
16
+ "everything",
17
+ "something",
18
+ "nothing",
19
+ }
20
+
21
+ # The memory is almost always about the user, so triples keep this one generic
22
+ # noun as the canonical self node even though concepts and the brief exclude it.
23
+ SELF_NOUNS = {"user"}
mnemolite/brief.py ADDED
@@ -0,0 +1,72 @@
1
+ """Render the memory graph as a Markdown brief for agent session start.
2
+
3
+ The brief is a projection of SQLite, not a second source of truth: it shows the
4
+ typed facts worth reading, never the implicit ``co_occurs`` mesh. Output is
5
+ byte-stable for an unchanged database (the ``_Generated`` stamp is the newest
6
+ data timestamp, not wall-clock time), so it can be diffed in git.
7
+ """
8
+
9
+ from .db import Database, parse_utc
10
+
11
+ NO_MEMORY = "_No memory yet._"
12
+ MAX_BRIEF_CONCEPTS = 20
13
+
14
+
15
+ def _edge_line(edge: dict) -> str:
16
+ return (
17
+ f"- {edge['source']} --[{edge['relation']}]--> {edge['target']} "
18
+ f"(weight: {float(edge['weight']):.1f})"
19
+ )
20
+
21
+
22
+ def _concept_blocks(nodes: list) -> list[str]:
23
+ """Group concept lines by node_type, sorted for stable output."""
24
+ groups: dict[str, list] = {}
25
+ for node in nodes:
26
+ groups.setdefault(node.get("node_type") or "entity", []).append(node)
27
+
28
+ lines: list[str] = []
29
+ for node_type in sorted(groups):
30
+ lines.append(f"### {node_type}")
31
+ for node in groups[node_type]:
32
+ name = node["name"]
33
+ display = node.get("display_name") or name
34
+ lines.append(f"- {display}" if display == name else f"- {display} ({name})")
35
+ lines.append("")
36
+ return lines
37
+
38
+
39
+ def render_brief(db: Database, top_n: int = 30) -> str:
40
+ """Return a Markdown brief summarizing the current graph state.
41
+
42
+ Sections: recent typed activity, strongest typed connections, and the most
43
+ recently active concepts. ``co_occurs`` edges are excluded everywhere and
44
+ generic nouns are excluded from concepts, because the brief exists to show
45
+ facts, not the implicit mesh. An empty graph yields ``_No memory yet._``.
46
+ """
47
+ recent = db.get_recent_edges(top_n)
48
+ strongest = db.get_strongest_edges(top_n)
49
+ concepts = db.get_active_nodes(MAX_BRIEF_CONCEPTS)
50
+
51
+ if not recent and not strongest and not concepts:
52
+ return f"{NO_MEMORY}\n"
53
+
54
+ stamps = [
55
+ parse_utc(node["last_seen"])
56
+ for node in concepts
57
+ if node.get("last_seen")
58
+ ]
59
+ blocks = ["# Mnemolite Brief"]
60
+ if stamps:
61
+ blocks.append(f"_Generated: {max(stamps).isoformat()}_")
62
+ if recent:
63
+ blocks.extend(["", "## Recent Activity"])
64
+ blocks.extend(_edge_line(edge) for edge in recent)
65
+ if strongest:
66
+ blocks.extend(["", "## Strongest Connections"])
67
+ blocks.extend(_edge_line(edge) for edge in strongest)
68
+ if concepts:
69
+ blocks.extend(["", "## Active Concepts", ""])
70
+ blocks.extend(_concept_blocks(concepts))
71
+
72
+ return "\n".join(blocks).rstrip("\n") + "\n"
@@ -0,0 +1,335 @@
1
+ """Entity and triple extraction plus graph consolidation.
2
+
3
+ No sentence encoder lives here: ``Embedder`` owns the only
4
+ ``SentenceTransformer`` instance (see AGENTS.md). This module only parses text
5
+ with spaCy and writes the resulting nodes/edges through ``Database``.
6
+ """
7
+
8
+ import logging
9
+ import re
10
+ from itertools import combinations, islice
11
+
12
+ import spacy
13
+ from spacy.cli import download as spacy_download
14
+ from spacy.tokens import Token
15
+
16
+ from ._constants import GENERIC_NOUNS, SELF_NOUNS
17
+
18
+ log = logging.getLogger(__name__)
19
+
20
+ # spaCy labels that describe a concept worth a node. Date/time/quantity labels
21
+ # would flood the graph with one-off nodes.
22
+ ENTITY_LABELS = {"PERSON", "ORG", "GPE", "PRODUCT", "EVENT"}
23
+
24
+ # A sentence with many entities is usually a list, not a claim about how they
25
+ # relate, so cap the quadratic pair explosion.
26
+ MAX_COOCCURRENCE_PAIRS = 10
27
+
28
+ # "User's" -> "User", "users’" -> "users". spaCy splits the clitic off most
29
+ # tokens, but named-entity spans can still carry it.
30
+ _POSSESSIVE = re.compile(r"(?:['’]s|['’])$")
31
+
32
+
33
+ def _strip_possessive(text: str) -> str:
34
+ return _POSSESSIVE.sub("", text.strip()).strip()
35
+
36
+
37
+ def _normalize_key(text: str) -> str:
38
+ """Canonical graph key: no possessive, lowercase, no trailing period."""
39
+ return _strip_possessive(text).lower().strip().rstrip(".").strip()
40
+
41
+
42
+ class Consolidator:
43
+ def __init__(self):
44
+ spacy_model = "en_core_web_sm"
45
+ try:
46
+ self.nlp = spacy.load(spacy_model)
47
+ except OSError:
48
+ log.info("Downloading spaCy model '%s'...", spacy_model)
49
+ try:
50
+ spacy_download(spacy_model)
51
+ self.nlp = spacy.load(spacy_model)
52
+ except Exception as e:
53
+ log.error(
54
+ "Failed to auto-install. Please run: python -m spacy download %s",
55
+ spacy_model,
56
+ )
57
+ raise e
58
+
59
+ # ------------------------------------------------------------------
60
+ # Extraction
61
+ # ------------------------------------------------------------------
62
+
63
+ def extract_entities(self, text: str) -> list[str]:
64
+ """Normalized entity names (lowercase, lemmatized) mentioned in text."""
65
+ return [mention["name"] for mention in self._entity_mentions(self.nlp(text))]
66
+
67
+ def extract_entity_mentions(self, text: str) -> list[dict]:
68
+ """Entities with graph metadata: ``name``, ``display_name``, ``node_type``.
69
+
70
+ ``name`` is the normalized graph key (lemma, lowercase) so "Dog",
71
+ "dogs" and "Dog's" collapse into one node; ``display_name`` keeps the
72
+ original casing for humans.
73
+ """
74
+ return self._entity_mentions(self.nlp(text))
75
+
76
+ def extract_query_entities(self, text: str) -> list[str]:
77
+ """Entity names used as graph seeds for recall.
78
+
79
+ Unlike :meth:`extract_entities`, generic nouns are kept when they are
80
+ mentioned in a query: memories are usually written about "the user",
81
+ and the graph stores that node even though the word is too vague to
82
+ show as a concept in the brief. Pronouns and stop words are still
83
+ filtered.
84
+ """
85
+ return [
86
+ mention["name"]
87
+ for mention in self._entity_mentions(
88
+ self.nlp(text), include_generic=True
89
+ )
90
+ ]
91
+
92
+ def _entity_mentions(self, doc, include_generic: bool = False) -> list[dict]:
93
+ """Entity mentions for a parsed ``Doc`` or ``Span``."""
94
+ mentions: dict[str, dict] = {}
95
+
96
+ def remember(raw: str, node_type: str, name: str | None = None) -> None:
97
+ display = _strip_possessive(raw)
98
+ # NER often swallows the sentence-final period ("Acme Corp.").
99
+ # The display keeps it, but the graph key must match the version
100
+ # without it ("Acme Corp is hiring").
101
+ key = _normalize_key(name or display)
102
+ if not key or (not include_generic and key in GENERIC_NOUNS):
103
+ return
104
+ if key not in mentions:
105
+ mentions[key] = {
106
+ "name": key,
107
+ "display_name": display or key,
108
+ "node_type": node_type,
109
+ }
110
+ elif mentions[key]["node_type"] == "entity" and node_type != "entity":
111
+ # A typed NER hit outranks a bare noun chunk for the same word.
112
+ mentions[key]["node_type"] = node_type
113
+
114
+ # Named entities first: their label is the most specific node type.
115
+ named = [ent for ent in doc.ents if ent.label_ in ENTITY_LABELS]
116
+ for ent in named:
117
+ remember(ent.text, ent.label_)
118
+
119
+ # Nouns (core concepts), keyed by lemma so "dog"/"dogs" become "dog".
120
+ # Chunks whose head is inside a named entity are skipped: "York" in
121
+ # "New York" and "Corp" in "Acme Corp." are not separate concepts.
122
+ for chunk in doc.noun_chunks:
123
+ root = chunk.root
124
+ if root.pos_ not in ("NOUN", "PROPN"):
125
+ continue # pronouns ("It") are not concepts
126
+ if any(ent.start <= root.i < ent.end for ent in named):
127
+ continue
128
+ lemma = root.lemma_.lower()
129
+ if len(lemma) <= 2 or self.nlp.vocab[lemma].is_stop:
130
+ continue
131
+ # Keep the original casing for humans, key the node by lemma.
132
+ remember(root.text, "entity", name=lemma)
133
+
134
+ return list(mentions.values())
135
+
136
+ def extract_triples(self, text: str) -> list[tuple[str, str, str]]:
137
+ """Extract (subject, predicate, object) triples with dependency parsing.
138
+
139
+ Examples:
140
+ "Jack is a dog." -> ("jack", "is_a", "dog")
141
+ "user won a lottery" -> ("user", "win", "lottery")
142
+ "Alice doesn't like tea." -> ("alice", "not_like", "tea")
143
+ """
144
+ return self._triples(self.nlp(text))
145
+
146
+ @staticmethod
147
+ def _lemma(token: Token) -> str:
148
+ return (token.lemma_ or token.text).lower().strip()
149
+
150
+ @staticmethod
151
+ def _is_negated(token: Token) -> bool:
152
+ return any(child.dep_ == "neg" for child in token.children)
153
+
154
+ @staticmethod
155
+ def _subject(token: Token) -> Token | None:
156
+ for child in token.children:
157
+ if child.dep_ in ("nsubj", "nsubjpass"):
158
+ return child
159
+ # Coordinated verbs share the subject of their head verb:
160
+ # "Alice sings and dances" -> both verbs are about Alice.
161
+ if token.dep_ == "conj" and token.head.pos_ in ("VERB", "AUX"):
162
+ for child in token.head.children:
163
+ if child.dep_ in ("nsubj", "nsubjpass"):
164
+ return child
165
+ return None
166
+
167
+ @staticmethod
168
+ def _object(token: Token) -> Token | None:
169
+ for child in token.children:
170
+ if child.dep_ in ("dobj", "pobj"):
171
+ return child
172
+ if child.dep_ == "prep":
173
+ for p_child in child.children:
174
+ if p_child.dep_ == "pobj":
175
+ return p_child
176
+ return None
177
+
178
+ @staticmethod
179
+ def _endpoint_key(token: Token, span_keys: dict[int, str]) -> str | None:
180
+ """Graph key for a triple endpoint, or None if it is not a concept.
181
+
182
+ A named-entity span wins over the token so "Acme Corp." maps to
183
+ "acme corp" and "New York" to "new york". Pronouns and generic nouns
184
+ are dropped, except the canonical self node "user".
185
+ """
186
+ if token.pos_ == "PRON":
187
+ return None
188
+ key = span_keys.get(token.i)
189
+ if key is None:
190
+ key = _normalize_key(token.lemma_ or token.text)
191
+ if not key or (key in GENERIC_NOUNS and key not in SELF_NOUNS):
192
+ return None
193
+ return key
194
+
195
+ def _triples(self, doc) -> list[tuple[str, str, str]]:
196
+ triples: list[tuple[str, str, str]] = []
197
+
198
+ # Map every token inside a named entity to the span's graph key. This
199
+ # keeps a token-level endpoint ("Corp." in "Acme Corp.") aligned with
200
+ # the entity node instead of creating a second, truncated node.
201
+ span_keys: dict[int, str] = {}
202
+ for ent in doc.ents:
203
+ if ent.label_ not in ENTITY_LABELS:
204
+ continue
205
+ key = _normalize_key(ent.text)
206
+ if not key:
207
+ continue
208
+ for ent_token in ent:
209
+ span_keys[ent_token.i] = key
210
+
211
+ for token in doc:
212
+ # 1. Subject-Copula-Complement (Jack is a dog). "is" is AUX in
213
+ # spaCy, so this branch must run before the VERB filter.
214
+ if token.lemma_ == "be" and token.pos_ in ("AUX", "VERB"):
215
+ subj = self._subject(token)
216
+ comp = next(
217
+ (child for child in token.children if child.dep_ in ("attr", "acomp")),
218
+ None,
219
+ )
220
+ if subj is not None and comp is not None:
221
+ subj_key = self._endpoint_key(subj, span_keys)
222
+ comp_key = self._endpoint_key(comp, span_keys)
223
+ if subj_key is not None and comp_key is not None:
224
+ relation = (
225
+ "is_not_a" if self._is_negated(token) else "is_a"
226
+ )
227
+ triples.append((subj_key, relation, comp_key))
228
+ continue
229
+
230
+ if token.pos_ != "VERB":
231
+ continue
232
+
233
+ subj = self._subject(token)
234
+ if subj is None:
235
+ continue
236
+
237
+ obj = self._object(token)
238
+ negated = self._is_negated(token)
239
+
240
+ if obj is not None:
241
+ # 2. Subject-Verb-Object (user won lottery).
242
+ subj_key = self._endpoint_key(subj, span_keys)
243
+ obj_key = self._endpoint_key(obj, span_keys)
244
+ if subj_key is not None and obj_key is not None:
245
+ predicate = ("not_" if negated else "") + self._lemma(token)
246
+ triples.append((subj_key, predicate, obj_key))
247
+ continue
248
+
249
+ # A clausal complement carries the actual fact: "I think Bob likes
250
+ # tea" should yield Bob/like/tea, not I/did/think.
251
+ if any(child.dep_ in ("ccomp", "xcomp") for child in token.children):
252
+ continue
253
+
254
+ subj_key = self._endpoint_key(subj, span_keys)
255
+ if subj_key is None:
256
+ continue
257
+
258
+ # 3. Intransitive verb: Subject + Verb (no object). Keep particles
259
+ # in the verb phrase ("pass away", "wake up").
260
+ verb_phrase = self._lemma(token)
261
+ for child in token.children:
262
+ if child.dep_ == "prt":
263
+ verb_phrase = f"{verb_phrase}_{self._lemma(child)}"
264
+ if negated:
265
+ verb_phrase = f"not_{verb_phrase}"
266
+ triples.append((subj_key, "did", verb_phrase))
267
+
268
+ # 4. Possessions (User's dog).
269
+ for token in doc:
270
+ if token.dep_ == "poss":
271
+ owner_key = self._endpoint_key(token, span_keys)
272
+ thing_key = self._endpoint_key(token.head, span_keys)
273
+ if owner_key is not None and thing_key is not None:
274
+ triples.append((owner_key, "has_a", thing_key))
275
+
276
+ return list(set(triples)) # Remove duplicates
277
+
278
+ # ------------------------------------------------------------------
279
+ # Consolidation
280
+ # ------------------------------------------------------------------
281
+
282
+ def consolidate(self, episodes: list, db) -> int:
283
+ """Turn episodes into graph nodes and edges; returns episodes processed."""
284
+ if not episodes:
285
+ return 0
286
+
287
+ processed = 0
288
+ for episode in episodes:
289
+ doc = self.nlp(episode["content"])
290
+
291
+ # One transaction per episode: a merge-heavy episode writes dozens
292
+ # of nodes/edges and per-row connections would serialize badly.
293
+ with db.batch() as conn:
294
+ # A+B. Entities become nodes; co-occurrence edges link only
295
+ # entities that share a sentence, and at most
296
+ # MAX_COOCCURRENCE_PAIRS per sentence. Linking everything in
297
+ # the episode turned a 30-entity mention list into 435
298
+ # meaningless edges.
299
+ for sent in doc.sents:
300
+ node_ids = [
301
+ db.get_or_create_node(
302
+ mention["name"],
303
+ mention["node_type"],
304
+ display_name=mention["display_name"],
305
+ conn=conn,
306
+ )
307
+ for mention in self._entity_mentions(sent)
308
+ ]
309
+ # Sort ids so co_occurs is undirected: "Zoe and Yuri" and
310
+ # "Yuri and Zoe" must reinforce one edge, not create two.
311
+ for left, right in islice(
312
+ combinations(sorted(node_ids), 2), MAX_COOCCURRENCE_PAIRS
313
+ ):
314
+ db.reinforce_edge(
315
+ left, right, relation="co_occurs", conn=conn,
316
+ episode_id=episode["id"],
317
+ )
318
+
319
+ # C. Typed triples (explicit, high-confidence connections).
320
+ for subj, pred, obj in self._triples(doc):
321
+ subj_id = db.get_or_create_node(subj, conn=conn)
322
+ obj_id = db.get_or_create_node(obj, conn=conn)
323
+ db.reinforce_edge(
324
+ subj_id, obj_id, relation=pred, conn=conn,
325
+ episode_id=episode["id"],
326
+ )
327
+
328
+ # Mark inside the write transaction: a crash must not leave
329
+ # committed edges on an episode that still looks unconsolidated,
330
+ # or the next run would double its weights.
331
+ db.mark_consolidated([episode["id"]], conn=conn)
332
+
333
+ processed += 1
334
+
335
+ return processed