mnemohive 0.1.4__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.
mnemo/__init__.py ADDED
@@ -0,0 +1,217 @@
1
+ """Mnemo — Git for agent memory.
2
+
3
+ An append-only, inspectable, reversible memory layer for LLM agents:
4
+ ``add`` / ``search`` / ``blame`` / ``revert`` / ``diff`` / ``log`` in one SQLite file.
5
+
6
+ ``Mnemo`` is the sync public surface (thin wrappers over the async ``MnemoStore``
7
+ core, spec §9) — convenient for the CLI/demo. Each call opens a short-lived
8
+ connection; for many calls, use ``MnemoStore`` on a connection you keep open.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import asyncio
14
+ from collections.abc import Awaitable, Callable
15
+ from pathlib import Path
16
+ from typing import Any, TypeVar
17
+ from uuid import UUID
18
+
19
+ from mnemo.core import MnemoStore
20
+ from mnemo.db import connect
21
+ from mnemo.direct import DirectMemory
22
+ from mnemo.errors import ErrorCode, MnemoError
23
+ from mnemo.models import (
24
+ Commit,
25
+ CurrentValue,
26
+ Diff,
27
+ Event,
28
+ Fact,
29
+ HistoricalValue,
30
+ HistoryPage,
31
+ MutationResult,
32
+ SearchHit,
33
+ )
34
+
35
+ __version__ = "0.1.4"
36
+ __all__ = [
37
+ "Mnemo",
38
+ "MnemoStore",
39
+ "Event",
40
+ "Fact",
41
+ "Commit",
42
+ "Diff",
43
+ "MutationResult",
44
+ "MnemoError",
45
+ "ErrorCode",
46
+ ]
47
+
48
+ T = TypeVar("T")
49
+
50
+
51
+ class Mnemo:
52
+ """Synchronous SDK over the async core (one connection per call)."""
53
+
54
+ def __init__(
55
+ self,
56
+ path: str | Path,
57
+ embedder: Any,
58
+ *,
59
+ namespace: str = "default",
60
+ user_id: str = "default",
61
+ agent_id: str = "default",
62
+ ) -> None:
63
+ self._path = path
64
+ self._embedder = embedder
65
+ self._namespace = namespace
66
+ self._user_id = user_id
67
+ self._agent_id = agent_id
68
+
69
+ @property
70
+ def direct(self) -> _DirectSDK:
71
+ """Guarded mutations and scoped reads using this client's connection settings."""
72
+ return _DirectSDK(self)
73
+
74
+ def _run(self, fn: Callable[[MnemoStore], Awaitable[T]]) -> T:
75
+ async def _wrapped() -> T:
76
+ conn = await connect(self._path, create=False)
77
+ try:
78
+ store = MnemoStore(
79
+ conn,
80
+ self._embedder,
81
+ namespace=self._namespace,
82
+ user_id=self._user_id,
83
+ agent_id=self._agent_id,
84
+ )
85
+ return await fn(store)
86
+ finally:
87
+ await conn.close()
88
+
89
+ return asyncio.run(_wrapped())
90
+
91
+ def add(self, subject: str, predicate: str, object: Any, **kwargs: Any) -> Event:
92
+ return self._run(lambda s: s.add(subject, predicate, object, **kwargs))
93
+
94
+ def search(self, query: str, **kwargs: Any) -> list[Fact]:
95
+ return self._run(lambda s: s.search(query, **kwargs))
96
+
97
+ def get(self, fact_id: UUID) -> Fact | None:
98
+ return self._run(lambda s: s.get(fact_id))
99
+
100
+ def blame(self, **kwargs: Any) -> list[Event]:
101
+ return self._run(lambda s: s.blame(**kwargs))
102
+
103
+ def revert(self, fact_id: UUID, to_event_id: UUID, **kwargs: Any) -> Event:
104
+ return self._run(lambda s: s.revert(fact_id, to_event_id, **kwargs))
105
+
106
+ def invalidate(self, fact_id: UUID, **kwargs: Any) -> Event:
107
+ return self._run(lambda s: s.invalidate(fact_id, **kwargs))
108
+
109
+ def diff(self, commit_a: Commit | UUID, commit_b: Commit | UUID) -> Diff:
110
+ return self._run(lambda s: s.diff(commit_a, commit_b))
111
+
112
+ def log(self, **kwargs: Any) -> list[Event]:
113
+ return self._run(lambda s: s.log(**kwargs))
114
+
115
+ def commit(self, label: str | None = None) -> Commit:
116
+ return self._run(lambda s: s.commit(label))
117
+
118
+
119
+ class _DirectSDK:
120
+ """Synchronous adapter for DirectMemory; validation and transactions stay in the core."""
121
+
122
+ def __init__(self, client: Mnemo) -> None:
123
+ self._client = client
124
+
125
+ def _run(self, fn: Callable[[DirectMemory], Awaitable[T]]) -> T:
126
+ return self._client._run(lambda store: fn(DirectMemory(store)))
127
+
128
+ def create(
129
+ self,
130
+ subject: str,
131
+ predicate: str,
132
+ value: str,
133
+ *,
134
+ request_id: UUID,
135
+ actor: str | None = None,
136
+ source_span: Any | None = None,
137
+ source: str = "agent",
138
+ ) -> MutationResult:
139
+ return self._run(
140
+ lambda d: d.create(
141
+ subject,
142
+ predicate,
143
+ value,
144
+ request_id=request_id,
145
+ actor=actor,
146
+ source_span=source_span,
147
+ source=source,
148
+ )
149
+ )
150
+
151
+ def update(
152
+ self,
153
+ fact_id: UUID,
154
+ value: str,
155
+ *,
156
+ expected_event_id: UUID,
157
+ request_id: UUID,
158
+ actor: str | None = None,
159
+ source: str = "agent",
160
+ ) -> MutationResult:
161
+ return self._run(
162
+ lambda d: d.update(
163
+ fact_id,
164
+ value,
165
+ expected_event_id=expected_event_id,
166
+ request_id=request_id,
167
+ actor=actor,
168
+ source=source,
169
+ )
170
+ )
171
+
172
+ def retract(
173
+ self,
174
+ fact_id: UUID,
175
+ *,
176
+ expected_event_id: UUID,
177
+ request_id: UUID,
178
+ actor: str | None = None,
179
+ reason: str | None = None,
180
+ ) -> MutationResult:
181
+ return self._run(
182
+ lambda d: d.retract(
183
+ fact_id,
184
+ expected_event_id=expected_event_id,
185
+ request_id=request_id,
186
+ actor=actor,
187
+ reason=reason,
188
+ )
189
+ )
190
+
191
+ def revert(
192
+ self,
193
+ fact_id: UUID,
194
+ to_event_id: UUID,
195
+ *,
196
+ expected_event_id: UUID,
197
+ request_id: UUID,
198
+ actor: str | None = None,
199
+ ) -> MutationResult:
200
+ return self._run(
201
+ lambda d: d.revert(
202
+ fact_id,
203
+ to_event_id,
204
+ expected_event_id=expected_event_id,
205
+ request_id=request_id,
206
+ actor=actor,
207
+ )
208
+ )
209
+
210
+ def get(self, fact_id: UUID, event_id: UUID | None = None) -> CurrentValue | HistoricalValue:
211
+ return self._run(lambda d: d.get(fact_id, event_id))
212
+
213
+ def history(self, fact_id: UUID, *, cursor: str | None = None, limit: int = 20) -> HistoryPage:
214
+ return self._run(lambda d: d.history(fact_id, cursor=cursor, limit=limit))
215
+
216
+ def search_direct(self, query: str, *, limit: int = 5) -> list[SearchHit]:
217
+ return self._run(lambda d: d.search(query, limit=limit))
mnemo/chain.py ADDED
@@ -0,0 +1,295 @@
1
+ """Tamper evidence: a hash chain over the event log, and the check behind `mnemo verify`.
2
+
3
+ Each event's hash is SHA-256 over the previous hash and a ``json_array`` of its payload
4
+ columns, in ``seq`` order (migration 0002 writes it on every insert). Verifying
5
+ recomputes the chain from the events and also checks that every memory's HEAD is its
6
+ newest event, so an edit made around Mnemo's triggers shows up.
7
+
8
+ Someone who rewrites an event and every later hash leaves a self-consistent chain. To
9
+ catch that, ``mnemo verify`` keeps the head it last verified in a witness file outside
10
+ the store and checks that the chain still passes through it; keep a copy elsewhere
11
+ (``--witness``) for a check that does not rely on the same disk.
12
+
13
+ A memory's identity (its scope, subject, predicate and key) lives in memory_fact, not
14
+ in its events. Migration 0003 seals each fact the same way, in a second chain over
15
+ those columns, and the witness records that chain's head too.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import hashlib
21
+ import os
22
+ import re
23
+ import sqlite3
24
+ from dataclasses import dataclass, field
25
+ from pathlib import Path
26
+
27
+ from mnemo.sqlite import Connection
28
+
29
+ # Every payload column of memory_event (all but the supersession and recall
30
+ # bookkeeping), in the order migration 0002's trigger hashes them.
31
+ CHAIN_COLUMNS = (
32
+ "seq",
33
+ "event_id",
34
+ "fact_id",
35
+ "op",
36
+ "object_text",
37
+ "object_number",
38
+ "object_json",
39
+ "provenance",
40
+ "actor",
41
+ "confidence",
42
+ "trust_level",
43
+ "source_span",
44
+ "valid_from",
45
+ "valid_to",
46
+ "recorded_at",
47
+ "parent_event_id",
48
+ "commit_id",
49
+ "importance",
50
+ "write_score",
51
+ "tier",
52
+ "reason",
53
+ "session_id",
54
+ "expires_at",
55
+ )
56
+
57
+
58
+ # The identity columns of memory_fact, in the order migration 0003's trigger seals them.
59
+ FACT_COLUMNS = (
60
+ "fact_id",
61
+ "namespace",
62
+ "user_id",
63
+ "agent_id",
64
+ "session_id",
65
+ "subject",
66
+ "predicate",
67
+ "fact_key",
68
+ "kind",
69
+ "created_at",
70
+ "identity_mode",
71
+ "identity_ref",
72
+ )
73
+
74
+
75
+ def sha256_hex(text: str | bytes | None) -> str:
76
+ """Registered as sha256_hex() on every connection."""
77
+ data = b"" if text is None else text.encode() if isinstance(text, str) else text
78
+ return hashlib.sha256(data).hexdigest()
79
+
80
+
81
+ def payload_sql(alias: str, columns: tuple[str, ...] = CHAIN_COLUMNS) -> str:
82
+ return "json_array(" + ", ".join(f"{alias}.{c}" for c in columns) + ")"
83
+
84
+
85
+ def backfill(raw: sqlite3.Connection) -> int:
86
+ """Chain the events stored before migration 0002, inside its transaction."""
87
+ rows = raw.execute(f"SELECT seq, {payload_sql('e')} FROM memory_event e ORDER BY seq")
88
+ previous, links = "", []
89
+ for seq, payload in rows:
90
+ previous = sha256_hex(previous + payload)
91
+ links.append((seq, previous))
92
+ raw.executemany("INSERT INTO memory_event_chain (seq, hash) VALUES (?, ?)", links)
93
+ return len(links)
94
+
95
+
96
+ def seal_existing_facts(raw: sqlite3.Connection) -> int:
97
+ """Seal the facts stored before migration 0003, in the order they were stored."""
98
+ rows = raw.execute(
99
+ f"SELECT fact_id, {payload_sql('f', FACT_COLUMNS)} FROM memory_fact f ORDER BY rowid"
100
+ )
101
+ previous, seals = "", []
102
+ for fact_id, payload in rows:
103
+ previous = sha256_hex(previous + payload)
104
+ seals.append((fact_id, previous))
105
+ raw.executemany("INSERT INTO memory_fact_seal (fact_id, hash) VALUES (?, ?)", seals)
106
+ return len(seals)
107
+
108
+
109
+ @dataclass(frozen=True)
110
+ class Witness:
111
+ """A chain position verified earlier: the hash of the event at ``seq``, and the
112
+ seal of the fact at ``fact_seq`` (absent from witnesses written before migration 0003)."""
113
+
114
+ seq: int
115
+ hash: str
116
+ fact_seq: int | None = None
117
+ fact_hash: str | None = None
118
+
119
+ @classmethod
120
+ def read(cls, path: Path) -> Witness | None:
121
+ bad = f"{path} is not a Mnemo witness file (want 'SEQ HASH [FACT_SEQ FACT_HASH]')"
122
+ try:
123
+ lines = [line for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
124
+ except FileNotFoundError:
125
+ return None
126
+ fields = lines[0].split() if len(lines) == 1 else []
127
+ if len(fields) not in (2, 4) or not all(
128
+ re.fullmatch(r"[1-9][0-9]*", seq) and re.fullmatch(r"[0-9a-f]{64}", digest)
129
+ for seq, digest in zip(fields[::2], fields[1::2], strict=True)
130
+ ):
131
+ raise ValueError(bad)
132
+ if len(fields) == 2:
133
+ return cls(int(fields[0]), fields[1])
134
+ return cls(int(fields[0]), fields[1], int(fields[2]), fields[3])
135
+
136
+ def write(self, path: Path) -> None:
137
+ """Replace the file atomically, readable only by its owner."""
138
+ from mnemo.embedder import private_dirs
139
+
140
+ private_dirs(path.parent)
141
+ temporary = path.with_name(path.name + ".tmp")
142
+ descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
143
+ try:
144
+ with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
145
+ sealed = self.fact_seq is not None and self.fact_hash is not None
146
+ facts = f" {self.fact_seq} {self.fact_hash}" if sealed else ""
147
+ handle.write(f"{self.seq} {self.hash}{facts}\n")
148
+ handle.flush()
149
+ os.fsync(handle.fileno())
150
+ os.replace(temporary, path)
151
+ except BaseException:
152
+ temporary.unlink(missing_ok=True)
153
+ raise
154
+
155
+
156
+ def witness_path(db: Path) -> Path:
157
+ """Where `mnemo verify` keeps the head it verified: beside the store, not in it."""
158
+ return db.with_name(db.name + ".verified")
159
+
160
+
161
+ @dataclass
162
+ class Verification:
163
+ events: int = 0
164
+ head: str | None = None
165
+ """The newest event's hash: keep it to detect a rewrite of the whole chain."""
166
+ head_seq: int | None = None
167
+ facts: int = 0
168
+ fact_head: str | None = None
169
+ """The newest fact seal: the witness keeps it to detect a rewrite of the seals."""
170
+ fact_head_seq: int | None = None
171
+ problems: list[str] = field(default_factory=list)
172
+
173
+ @property
174
+ def witness(self) -> Witness | None:
175
+ if not (self.head and self.head_seq):
176
+ return None
177
+ return Witness(self.head_seq, self.head, self.fact_head_seq, self.fact_head)
178
+
179
+ @property
180
+ def ok(self) -> bool:
181
+ return not self.problems
182
+
183
+
184
+ async def verify(conn: Connection, since: Witness | None = None) -> Verification:
185
+ """Recompute the chain and check HEADs, in one read snapshot. With ``since``, also
186
+ check that the chain still passes through that earlier verified head."""
187
+ result = Verification()
188
+ async with conn.transaction(readonly=not conn.is_in_transaction()):
189
+
190
+ def chain() -> None:
191
+ rows = conn.raw.execute(
192
+ f"SELECT e.seq, {payload_sql('e')}, c.hash FROM memory_event e "
193
+ "LEFT JOIN memory_event_chain c ON c.seq = e.seq ORDER BY e.seq"
194
+ )
195
+ previous, seen = "", None
196
+ for seq, payload, stored in rows:
197
+ result.events += 1
198
+ result.head_seq = seq
199
+ expected = sha256_hex(previous + payload)
200
+ if stored is None:
201
+ result.problems.append(f"event seq {seq} has no chain entry")
202
+ elif stored != expected and len(result.problems) < 20:
203
+ result.problems.append(
204
+ f"event seq {seq} does not match its hash: it or an earlier "
205
+ "event was changed, removed or inserted outside Mnemo"
206
+ )
207
+ previous = stored or expected
208
+ if since is not None and seq == since.seq:
209
+ seen = previous
210
+ result.head = previous or None
211
+ if since is not None and seen != since.hash:
212
+ result.problems.append(
213
+ f"history was rewritten since it was last verified: the chain no longer "
214
+ f"passes through seq {since.seq} with hash {since.hash[:16]}…"
215
+ + (" (that event is gone)" if seen is None else "")
216
+ )
217
+ seals(conn.raw, result, since)
218
+ orphans = conn.raw.execute(
219
+ "SELECT c.seq FROM memory_event_chain c "
220
+ "LEFT JOIN memory_event e ON e.seq = c.seq WHERE e.seq IS NULL"
221
+ ).fetchall()
222
+ for (seq,) in orphans[:20]:
223
+ result.problems.append(f"event seq {seq} was deleted (its hash remains)")
224
+ heads = conn.raw.execute("""
225
+ SELECT f.fact_id, f.status, f.current_event_id, last.event_id, last.op
226
+ FROM memory_fact f
227
+ LEFT JOIN memory_event last ON last.seq = (
228
+ SELECT max(seq) FROM memory_event WHERE fact_id = f.fact_id)
229
+ """).fetchall()
230
+ for fact_id, status, current, newest, op in heads:
231
+ expected = {"INVALIDATE": "invalidated", "DELETE": "deleted"}.get(op, "active")
232
+ if current != newest:
233
+ result.problems.append(f"memory {fact_id}: HEAD is not its newest event")
234
+ elif status != expected:
235
+ result.problems.append(
236
+ f"memory {fact_id}: status {status!r} disagrees with its HEAD ({op})"
237
+ )
238
+ stranded = conn.raw.execute(
239
+ "SELECT 'event seq ' || e.seq, e.fact_id FROM memory_event e "
240
+ "LEFT JOIN memory_fact f ON f.fact_id = e.fact_id WHERE f.fact_id IS NULL "
241
+ "UNION ALL "
242
+ "SELECT 'receipt ' || r.receipt_id, r.fact_id FROM memory_mutation_receipt r "
243
+ "LEFT JOIN memory_fact f ON f.fact_id = r.fact_id WHERE f.fact_id IS NULL"
244
+ ).fetchall()
245
+ for row, fact_id in stranded[:20]:
246
+ result.problems.append(
247
+ f"{row} belongs to memory {fact_id}, which was deleted outside Mnemo"
248
+ )
249
+
250
+ await conn._call(chain)
251
+ return result
252
+
253
+
254
+ def seals(raw: sqlite3.Connection, result: Verification, since: Witness | None) -> None:
255
+ """Recompute the fact seals: a memory's identity changed, deleted or inserted
256
+ outside Mnemo breaks its seal, and a rewrite of every seal misses the witness."""
257
+ rows = raw.execute(
258
+ f"SELECT s.seq, s.fact_id, {payload_sql('f', FACT_COLUMNS)}, f.fact_id, s.hash "
259
+ "FROM memory_fact_seal s LEFT JOIN memory_fact f ON f.fact_id = s.fact_id "
260
+ "ORDER BY s.seq"
261
+ )
262
+ previous, seen, reported = "", None, 0
263
+
264
+ def problem(text: str) -> None:
265
+ nonlocal reported
266
+ reported += 1
267
+ if reported <= 20:
268
+ result.problems.append(text)
269
+
270
+ for seq, fact_id, payload, present, stored in rows:
271
+ result.facts += 1
272
+ result.fact_head_seq = seq
273
+ if present is None:
274
+ problem(f"memory {fact_id} was deleted outside Mnemo (its seal remains)")
275
+ elif sha256_hex(previous + payload) != stored:
276
+ problem(
277
+ f"memory {fact_id}: its identity (scope, subject, predicate or key) was "
278
+ "changed outside Mnemo, or an earlier seal was"
279
+ )
280
+ previous = stored
281
+ if since is not None and since.fact_seq == seq:
282
+ seen = previous
283
+ result.fact_head = previous or None
284
+ unsealed = raw.execute(
285
+ "SELECT f.fact_id FROM memory_fact f "
286
+ "LEFT JOIN memory_fact_seal s ON s.fact_id = f.fact_id WHERE s.fact_id IS NULL"
287
+ ).fetchall()
288
+ for (fact_id,) in unsealed[:20]: # counted apart, so seal problems cannot hide them
289
+ result.problems.append(f"memory {fact_id} has no seal: it was inserted outside Mnemo")
290
+ if since is not None and since.fact_hash is not None and seen != since.fact_hash:
291
+ result.problems.append(
292
+ "memory identities were rewritten since they were last verified: the seals no "
293
+ f"longer pass through seq {since.fact_seq} with hash {since.fact_hash[:16]}…"
294
+ + (" (that seal is gone)" if seen is None else "")
295
+ )
mnemo/cli.py ADDED
@@ -0,0 +1,158 @@
1
+ """The `mnemo` command: connect your agents, open the review UI, keep the store.
2
+
3
+ mnemo install # connect Claude Code, Codex and OpenCode; shows every change, asks first
4
+ mnemo uninstall # undo `mnemo install`; memories are kept
5
+ mnemo ui # web review UI on http://127.0.0.1:8000
6
+ mnemo migrate # apply pending schema migrations to the store file
7
+ mnemo reindex # rebuild vectors and the word index (after a model change)
8
+ mnemo verify # check the history was not changed outside Mnemo since last time
9
+ mnemo export # write this scope's memories, with their history, as JSON
10
+ mnemo import FILE # restore an export (or a Postgres-era export) into an empty store
11
+
12
+ Memory lives in one file, ``~/.mnemo/mnemo.db`` by default (MNEMO_DB). Installed as a
13
+ tool (``uv tool install mnemohive``), this is all a
14
+ user needs, and the agents run the tool's own server rather than a checkout.
15
+ `mnemo install --help` lists the installer's options.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import argparse
21
+ import asyncio
22
+ import sys
23
+ from collections.abc import Sequence
24
+ from pathlib import Path
25
+
26
+ from mnemo.install import main as install_main
27
+
28
+ GONE = {
29
+ "up": "Mnemo no longer needs Docker or Postgres: memory is the file in MNEMO_DB "
30
+ "(default ~/.mnemo/mnemo.db). Run `mnemo install` to create it.",
31
+ "down": "Mnemo no longer runs Postgres, so there is nothing to stop. A Postgres "
32
+ "container from an earlier version keeps running until you stop it with Docker.",
33
+ }
34
+
35
+
36
+ def serve_ui(port: int) -> int:
37
+ import uvicorn
38
+
39
+ uvicorn.run("mnemo.web.app:app", host="127.0.0.1", port=port)
40
+ return 0
41
+
42
+
43
+ async def _verify(witness: Path | None) -> int:
44
+ from mnemo.chain import Witness, verify, witness_path
45
+ from mnemo.db import check_schema, connect
46
+ from mnemo.services import dir_permission_warning, where
47
+
48
+ conn = await connect(create=False)
49
+ store = where(conn.path)
50
+ witness = witness or witness_path(conn.path)
51
+ try:
52
+ since = Witness.read(witness)
53
+ except ValueError as exc:
54
+ await conn.close()
55
+ print(f"FAIL {exc}", file=sys.stderr)
56
+ return 1
57
+ try:
58
+ await check_schema(conn)
59
+ result = await verify(conn, since)
60
+ finally:
61
+ await conn.close()
62
+ if not result.ok:
63
+ print(f"FAIL {store}: {len(result.problems)} problem(s)", file=sys.stderr)
64
+ for problem in result.problems:
65
+ print(f" {problem}", file=sys.stderr)
66
+ print(f" {where(witness)} was left unchanged.", file=sys.stderr)
67
+ if any("last verified" in problem for problem in result.problems):
68
+ print(
69
+ " If you restored a backup or recreated the store yourself, delete "
70
+ f"{where(witness)} and run mnemo verify again to record the new head.",
71
+ file=sys.stderr,
72
+ )
73
+ return 1
74
+ print(
75
+ f"ok {store}: {result.events} events, history intact, HEADs consistent, "
76
+ f"{result.facts} memory identities sealed"
77
+ )
78
+ if since is not None:
79
+ print(f" still builds on the head verified at seq {since.seq}")
80
+ print(f" chain head {result.head or '(empty)'}")
81
+ if result.witness is not None:
82
+ result.witness.write(witness)
83
+ print(f" recorded in {where(witness)}; keep a copy elsewhere to catch a rewrite")
84
+ if warning := dir_permission_warning(conn.path):
85
+ print(f"warn {warning}")
86
+ return 0
87
+
88
+
89
+ async def _reindex() -> dict[str, int]:
90
+ from mnemo.config import get_settings
91
+ from mnemo.core import reindex
92
+ from mnemo.db import check_schema, connect
93
+ from mnemo.embedder import build_embedder
94
+
95
+ settings = get_settings()
96
+ embedder = build_embedder(settings)
97
+ conn = await connect(create=False)
98
+ try:
99
+ await check_schema(conn)
100
+ return await reindex(conn, embedder)
101
+ finally:
102
+ await conn.close()
103
+ close = getattr(embedder, "close", None)
104
+ if close:
105
+ close()
106
+
107
+
108
+ def main(argv: Sequence[str] | None = None) -> int:
109
+ parser = argparse.ArgumentParser(
110
+ prog="mnemo", description="Shared, versioned memory for your coding agents."
111
+ )
112
+ commands = parser.add_subparsers(dest="command", required=True, metavar="COMMAND")
113
+ commands.add_parser("install", help="connect Claude Code, Codex and OpenCode", add_help=False)
114
+ commands.add_parser("uninstall", help="undo `mnemo install`", add_help=False)
115
+ ui = commands.add_parser("ui", help="web review UI on 127.0.0.1")
116
+ ui.add_argument("--port", type=int, default=8000)
117
+ commands.add_parser("migrate", help="apply pending schema migrations")
118
+ commands.add_parser("reindex", help="rebuild vectors and the word index")
119
+ verify = commands.add_parser("verify", help="check the history was not changed outside Mnemo")
120
+ verify.add_argument(
121
+ "--witness",
122
+ type=Path,
123
+ metavar="FILE",
124
+ help="the head verified last time (default: beside the store, MNEMO_DB.verified)",
125
+ )
126
+ commands.add_parser("export", help="write memories and history as JSON", add_help=False)
127
+ commands.add_parser("import", help="restore an export into an empty store", add_help=False)
128
+ for name in GONE:
129
+ commands.add_parser(name) # no help: argparse leaves it out of the listing
130
+ args, rest = parser.parse_known_args(argv)
131
+ if args.command in ("install", "uninstall"):
132
+ return install_main((["--uninstall"] if args.command == "uninstall" else []) + rest)
133
+ if args.command in ("export", "import"):
134
+ from mnemo.transfer import main as transfer_main
135
+
136
+ transfer_main([args.command, *rest])
137
+ return 0
138
+ if rest:
139
+ parser.error(f"unrecognized arguments: {' '.join(rest)}")
140
+ if args.command in GONE:
141
+ print(f"mnemo {args.command}: {GONE[args.command]}", file=sys.stderr)
142
+ return 0
143
+ if args.command == "migrate":
144
+ from mnemo.db import main as migrate
145
+
146
+ migrate()
147
+ return 0
148
+ if args.command == "verify":
149
+ return asyncio.run(_verify(args.witness))
150
+ if args.command == "reindex":
151
+ counts = asyncio.run(_reindex())
152
+ print(f"Embedded {counts['embedded']} of {counts['events']} events; word index rebuilt.")
153
+ return 0
154
+ return serve_ui(args.port)
155
+
156
+
157
+ if __name__ == "__main__":
158
+ raise SystemExit(main())