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 +217 -0
- mnemo/chain.py +295 -0
- mnemo/cli.py +158 -0
- mnemo/config.py +159 -0
- mnemo/core.py +1088 -0
- mnemo/db.py +156 -0
- mnemo/direct.py +834 -0
- mnemo/embedder.py +305 -0
- mnemo/errors.py +29 -0
- mnemo/install.py +779 -0
- mnemo/mcp_direct.py +420 -0
- mnemo/memory_policy.md +30 -0
- mnemo/migrations/.gitkeep +1 -0
- mnemo/migrations/0001_sqlite_init.sql +217 -0
- mnemo/migrations/0002_event_chain.sql +47 -0
- mnemo/migrations/0003_fact_identity.sql +83 -0
- mnemo/migrations/0004_fact_identity_unique.sql +21 -0
- mnemo/models.py +288 -0
- mnemo/project.py +91 -0
- mnemo/seed.py +119 -0
- mnemo/services.py +182 -0
- mnemo/sqlite.py +400 -0
- mnemo/telemetry.py +27 -0
- mnemo/transfer.py +362 -0
- mnemo/web/__init__.py +0 -0
- mnemo/web/app.py +502 -0
- mnemo/web/static/app.css +2 -0
- mnemo/web/static/htmx.LICENSE +13 -0
- mnemo/web/static/htmx.js +3925 -0
- mnemo/web/tailwind.config.js +6 -0
- mnemo/web/tailwind.css +4 -0
- mnemo/web/templates/_macros.html +8 -0
- mnemo/web/templates/_rows.html +22 -0
- mnemo/web/templates/base.html +40 -0
- mnemo/web/templates/diff.html +66 -0
- mnemo/web/templates/error.html +8 -0
- mnemo/web/templates/fact.html +69 -0
- mnemo/web/templates/list.html +31 -0
- mnemo/web/templates/retracted.html +45 -0
- mnemohive-0.1.4.dist-info/METADATA +416 -0
- mnemohive-0.1.4.dist-info/RECORD +43 -0
- mnemohive-0.1.4.dist-info/WHEEL +4 -0
- mnemohive-0.1.4.dist-info/entry_points.txt +6 -0
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())
|