amnesia-gov 0.2.2__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.
- amnesia/__init__.py +66 -0
- amnesia/audit.py +335 -0
- amnesia/backend.py +158 -0
- amnesia/chain.py +166 -0
- amnesia/cli.py +594 -0
- amnesia/diagnostics.py +185 -0
- amnesia/errors.py +75 -0
- amnesia/expiry.py +275 -0
- amnesia/governor.py +688 -0
- amnesia/models.py +134 -0
- amnesia/pii.py +78 -0
- amnesia/poison.py +274 -0
- amnesia/policies/default.yaml +101 -0
- amnesia/policy.py +522 -0
- amnesia/py.typed +0 -0
- amnesia/report.py +509 -0
- amnesia/server.py +310 -0
- amnesia/store.py +901 -0
- amnesia/validation.py +117 -0
- amnesia_gov-0.2.2.dist-info/METADATA +820 -0
- amnesia_gov-0.2.2.dist-info/RECORD +25 -0
- amnesia_gov-0.2.2.dist-info/WHEEL +5 -0
- amnesia_gov-0.2.2.dist-info/entry_points.txt +3 -0
- amnesia_gov-0.2.2.dist-info/licenses/LICENSE +21 -0
- amnesia_gov-0.2.2.dist-info/top_level.txt +1 -0
amnesia/__init__.py
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
"""Amnesia -- a governance layer for agent memory.
|
|
2
|
+
|
|
3
|
+
Most memory projects answer "how do we remember more?". Amnesia answers the other
|
|
4
|
+
half: what should never be stored, who is allowed to see it, and when it should be
|
|
5
|
+
forgotten.
|
|
6
|
+
|
|
7
|
+
Quick orientation:
|
|
8
|
+
|
|
9
|
+
MemoryGovernor the only entry point you normally need
|
|
10
|
+
PolicyEngine "who can see what", as reviewable configuration
|
|
11
|
+
PoisonDetector pattern attacks a per-memory gate cannot see
|
|
12
|
+
MemoryStore reference backend (SQLite + BM25)
|
|
13
|
+
MemoryBackend protocol other stores implement to sit behind this layer
|
|
14
|
+
AuditLog append-only evidence, including refusals
|
|
15
|
+
Maintenance supersession, decay and physical deletion
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from .audit import AuditLog, PolicyStampedAudit
|
|
19
|
+
from .backend import InMemoryLedger, MemoryBackend, WriteAttemptLedger, resolve_ledger
|
|
20
|
+
from .errors import AmnesiaError, BackendError, IntegrityError, PolicyError, ValidationError
|
|
21
|
+
from .expiry import Maintenance, SweepReport
|
|
22
|
+
from .governor import CANDIDATE_LIMIT, MemoryGovernor
|
|
23
|
+
from .models import MemoryItem, Principal, parse_iso, utcnow
|
|
24
|
+
from .poison import Finding, PoisonDetector, PoisonReport
|
|
25
|
+
from .policy import PolicyDecision, PolicyEngine, diff_configs
|
|
26
|
+
from .report import build_report, render_markdown
|
|
27
|
+
from .store import MemoryStore, tokens
|
|
28
|
+
from .validation import validate_principal, validate_recall, validate_write
|
|
29
|
+
|
|
30
|
+
__version__ = "0.2.2"
|
|
31
|
+
|
|
32
|
+
__all__ = [
|
|
33
|
+
"CANDIDATE_LIMIT",
|
|
34
|
+
"AmnesiaError",
|
|
35
|
+
"AuditLog",
|
|
36
|
+
"BackendError",
|
|
37
|
+
"Finding",
|
|
38
|
+
"InMemoryLedger",
|
|
39
|
+
"IntegrityError",
|
|
40
|
+
"Maintenance",
|
|
41
|
+
"MemoryBackend",
|
|
42
|
+
"MemoryGovernor",
|
|
43
|
+
"MemoryItem",
|
|
44
|
+
"MemoryStore",
|
|
45
|
+
"PoisonDetector",
|
|
46
|
+
"PoisonReport",
|
|
47
|
+
"PolicyDecision",
|
|
48
|
+
"PolicyEngine",
|
|
49
|
+
"PolicyError",
|
|
50
|
+
"PolicyStampedAudit",
|
|
51
|
+
"Principal",
|
|
52
|
+
"SweepReport",
|
|
53
|
+
"ValidationError",
|
|
54
|
+
"WriteAttemptLedger",
|
|
55
|
+
"__version__",
|
|
56
|
+
"build_report",
|
|
57
|
+
"diff_configs",
|
|
58
|
+
"parse_iso",
|
|
59
|
+
"render_markdown",
|
|
60
|
+
"resolve_ledger",
|
|
61
|
+
"tokens",
|
|
62
|
+
"utcnow",
|
|
63
|
+
"validate_principal",
|
|
64
|
+
"validate_recall",
|
|
65
|
+
"validate_write",
|
|
66
|
+
]
|
amnesia/audit.py
ADDED
|
@@ -0,0 +1,335 @@
|
|
|
1
|
+
"""Audit log.
|
|
2
|
+
|
|
3
|
+
The least glamorous layer in the project, and the one that decides enterprise
|
|
4
|
+
deals. Every write, allow, denial and deletion must leave a tamper-evident trail.
|
|
5
|
+
|
|
6
|
+
Denied recalls are recorded too. "What the agent wanted to say but was not
|
|
7
|
+
allowed to" is more interesting evidence than what it did say.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import json
|
|
13
|
+
import os
|
|
14
|
+
import time
|
|
15
|
+
from collections.abc import Iterator
|
|
16
|
+
from contextlib import contextmanager
|
|
17
|
+
from pathlib import Path
|
|
18
|
+
from typing import Any, BinaryIO
|
|
19
|
+
|
|
20
|
+
from .chain import GENESIS, ChainStatus, digest, verify
|
|
21
|
+
from .errors import BackendError, is_transient
|
|
22
|
+
from .models import utcnow
|
|
23
|
+
|
|
24
|
+
_TAIL_BLOCK = 4096
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def _lock(handle: BinaryIO) -> None:
|
|
28
|
+
"""Take an exclusive lock on the open log.
|
|
29
|
+
|
|
30
|
+
Both branches carry a `type: ignore[attr-defined]` and **both are needed**, one per platform:
|
|
31
|
+
a checker resolves only the platform it is running on, so `fcntl` is unresolvable on Windows
|
|
32
|
+
and `msvcrt` on Linux and macOS. Whichever branch the local platform does not take leaves an
|
|
33
|
+
unused ignore behind — which is exactly why `warn_unused_ignores` is off in `pyproject.toml`.
|
|
34
|
+
Getting this half-right is a real failure mode: the ignores were originally only on the
|
|
35
|
+
`fcntl` side, so the gate passed on Windows and failed on Linux and macOS.
|
|
36
|
+
"""
|
|
37
|
+
if os.name == "nt":
|
|
38
|
+
import msvcrt
|
|
39
|
+
|
|
40
|
+
msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK, 1) # type: ignore[attr-defined]
|
|
41
|
+
else:
|
|
42
|
+
import fcntl
|
|
43
|
+
|
|
44
|
+
fcntl.flock(handle.fileno(), fcntl.LOCK_EX) # type: ignore[attr-defined]
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def _unlock(handle: BinaryIO) -> None:
|
|
48
|
+
"""Release the lock taken by `_lock`. See that function for the two-sided ignore."""
|
|
49
|
+
if os.name == "nt":
|
|
50
|
+
import msvcrt
|
|
51
|
+
|
|
52
|
+
msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1) # type: ignore[attr-defined]
|
|
53
|
+
else:
|
|
54
|
+
import fcntl
|
|
55
|
+
|
|
56
|
+
fcntl.flock(handle.fileno(), fcntl.LOCK_UN) # type: ignore[attr-defined]
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def _tail_link(handle: BinaryIO) -> tuple[int, str]:
|
|
60
|
+
"""Read the last entry and return the `(seq, prev)` the next one should link to.
|
|
61
|
+
|
|
62
|
+
Read backwards in blocks rather than reading the file: the log is append-only and grows
|
|
63
|
+
without bound, and this runs on every governed operation.
|
|
64
|
+
|
|
65
|
+
Returns `(1, GENESIS)` when there is nothing to link to — an empty log, or a tail that
|
|
66
|
+
cannot be parsed because a previous writer died mid-line. Starting a fresh segment is the
|
|
67
|
+
honest response to an unreadable tail: the alternative is refusing to audit, and an
|
|
68
|
+
unaudited write is the worse outcome. The boundary it writes is visible to `chain.verify`,
|
|
69
|
+
which is what stops it being a way to hide an edit.
|
|
70
|
+
"""
|
|
71
|
+
handle.seek(0, os.SEEK_END)
|
|
72
|
+
remaining = handle.tell()
|
|
73
|
+
if remaining == 0:
|
|
74
|
+
return 1, GENESIS
|
|
75
|
+
|
|
76
|
+
buffer = b""
|
|
77
|
+
while remaining > 0 and buffer.count(b"\n") < 2:
|
|
78
|
+
step = min(_TAIL_BLOCK, remaining)
|
|
79
|
+
remaining -= step
|
|
80
|
+
handle.seek(remaining)
|
|
81
|
+
buffer = handle.read(step) + buffer
|
|
82
|
+
|
|
83
|
+
lines = [line for line in buffer.split(b"\n") if line.strip()]
|
|
84
|
+
if not lines:
|
|
85
|
+
return 1, GENESIS
|
|
86
|
+
try:
|
|
87
|
+
last = json.loads(lines[-1].decode("utf-8"))
|
|
88
|
+
except (UnicodeDecodeError, json.JSONDecodeError):
|
|
89
|
+
return 1, GENESIS
|
|
90
|
+
|
|
91
|
+
seq = last.get("seq")
|
|
92
|
+
link = last.get("hash")
|
|
93
|
+
if not isinstance(seq, int) or not isinstance(link, str):
|
|
94
|
+
# The last entry predates chaining. Start a segment; `chain.verify` reports the
|
|
95
|
+
# unchained prefix rather than pretending it was verified.
|
|
96
|
+
return 1, GENESIS
|
|
97
|
+
return seq + 1, link
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
class AuditLog:
|
|
101
|
+
"""Append-only JSONL stream.
|
|
102
|
+
|
|
103
|
+
Deliberately not a database: it should stay greppable, diffable and
|
|
104
|
+
archivable by whatever the customer already uses.
|
|
105
|
+
"""
|
|
106
|
+
|
|
107
|
+
def __init__(self, path: str | Path):
|
|
108
|
+
self.path = Path(path)
|
|
109
|
+
# Set by `entries()`; also here so it is readable before the first read.
|
|
110
|
+
self.unreadable_lines = 0
|
|
111
|
+
try:
|
|
112
|
+
self.path.parent.mkdir(parents=True, exist_ok=True)
|
|
113
|
+
except OSError as exc:
|
|
114
|
+
raise BackendError(
|
|
115
|
+
f"Cannot create the audit log directory {self.path.parent}: {exc}"
|
|
116
|
+
) from exc
|
|
117
|
+
|
|
118
|
+
# Checked here rather than discovered on the first append. Without this, pointing
|
|
119
|
+
# --audit at a directory raised a bare `PermissionError` from inside pathlib on the
|
|
120
|
+
# first write, several layers below anything that could explain it, and the CLI does not
|
|
121
|
+
# catch that type -- so the operator got a traceback for a configuration mistake.
|
|
122
|
+
if self.path.exists() and not self.path.is_file():
|
|
123
|
+
raise BackendError(
|
|
124
|
+
f"Cannot open audit log at {str(self.path)!r}: it exists but is not a file. "
|
|
125
|
+
"Point --audit at a file, or at a path that does not exist yet."
|
|
126
|
+
)
|
|
127
|
+
|
|
128
|
+
def record(self, event: str, **fields: Any) -> dict[str, Any]:
|
|
129
|
+
"""Append one entry, chained to the one before it.
|
|
130
|
+
|
|
131
|
+
Retried on a transient access error, because this is on the critical path of every
|
|
132
|
+
governed operation: a host briefly refusing to open the file used to take the whole
|
|
133
|
+
`remember` down with it. Not swallowed: if the retries are exhausted the error is
|
|
134
|
+
raised, because an audit entry that silently goes missing is a worse outcome than a
|
|
135
|
+
failed write.
|
|
136
|
+
|
|
137
|
+
The whole read-tail-then-append happens under an exclusive lock, and that is not
|
|
138
|
+
optional. Chaining needs the previous entry's hash, which makes appending a
|
|
139
|
+
read-modify-write: without the lock, two processes read the same predecessor and build
|
|
140
|
+
two entries on top of it, and the resulting log is *indistinguishable from tampering*
|
|
141
|
+
when verified. A tamper-evident log that cries wolf under ordinary concurrent use is
|
|
142
|
+
worse than no chain at all, and ten concurrent CLI processes is an ordinary load.
|
|
143
|
+
"""
|
|
144
|
+
entry = {"ts": utcnow().isoformat(), "event": event, **fields}
|
|
145
|
+
delay = 0.02
|
|
146
|
+
for attempt in range(8):
|
|
147
|
+
try:
|
|
148
|
+
with self._locked_append() as handle:
|
|
149
|
+
seq, prev = _tail_link(handle)
|
|
150
|
+
entry["seq"] = seq
|
|
151
|
+
entry["prev"] = prev
|
|
152
|
+
entry["hash"] = digest(seq, prev, entry)
|
|
153
|
+
handle.seek(0, os.SEEK_END)
|
|
154
|
+
handle.write((json.dumps(entry, ensure_ascii=False) + "\n").encode("utf-8"))
|
|
155
|
+
return entry
|
|
156
|
+
except OSError as exc:
|
|
157
|
+
if attempt == 7 or not is_transient(exc):
|
|
158
|
+
raise
|
|
159
|
+
time.sleep(delay)
|
|
160
|
+
delay = min(delay * 2, 0.5)
|
|
161
|
+
raise AssertionError("unreachable") # pragma: no cover
|
|
162
|
+
|
|
163
|
+
@contextmanager
|
|
164
|
+
def _locked_append(self) -> Iterator[BinaryIO]:
|
|
165
|
+
"""Open the log for appending and hold an exclusive lock on it.
|
|
166
|
+
|
|
167
|
+
`msvcrt` on Windows, `fcntl` elsewhere — both are stdlib, and this is the only place the
|
|
168
|
+
project needs a cross-process lock. The lock is advisory, which is enough here: every
|
|
169
|
+
writer goes through this method.
|
|
170
|
+
"""
|
|
171
|
+
handle = self.path.open("a+b")
|
|
172
|
+
try:
|
|
173
|
+
handle.seek(0)
|
|
174
|
+
_lock(handle)
|
|
175
|
+
try:
|
|
176
|
+
yield handle
|
|
177
|
+
finally:
|
|
178
|
+
handle.seek(0)
|
|
179
|
+
_unlock(handle)
|
|
180
|
+
finally:
|
|
181
|
+
handle.close()
|
|
182
|
+
|
|
183
|
+
def chain_status(self) -> ChainStatus:
|
|
184
|
+
"""Verify the log's hash chain. See `amnesia.chain` for what is and is not proven."""
|
|
185
|
+
status = verify(self.entries())
|
|
186
|
+
if self.unreadable_lines:
|
|
187
|
+
status = ChainStatus(
|
|
188
|
+
chained=status.chained,
|
|
189
|
+
unchained=status.unchained,
|
|
190
|
+
breaks=status.breaks,
|
|
191
|
+
first_break_index=status.first_break_index,
|
|
192
|
+
unreadable=self.unreadable_lines,
|
|
193
|
+
)
|
|
194
|
+
return status
|
|
195
|
+
|
|
196
|
+
# ---- semantic wrappers, so event names stay consistent ----
|
|
197
|
+
|
|
198
|
+
def write_decision(self, **f: Any) -> dict[str, Any]:
|
|
199
|
+
return self.record("memory.write", **f)
|
|
200
|
+
|
|
201
|
+
def read_decision(self, **f: Any) -> dict[str, Any]:
|
|
202
|
+
return self.record("memory.read", **f)
|
|
203
|
+
|
|
204
|
+
def recall_denied(self, **f: Any) -> dict[str, Any]:
|
|
205
|
+
return self.record("memory.recall_denied", **f)
|
|
206
|
+
|
|
207
|
+
def forget(self, **f: Any) -> dict[str, Any]:
|
|
208
|
+
return self.record("memory.forget", **f)
|
|
209
|
+
|
|
210
|
+
def sweep(self, **f: Any) -> dict[str, Any]:
|
|
211
|
+
return self.record("memory.sweep", **f)
|
|
212
|
+
|
|
213
|
+
# ---- queries ----
|
|
214
|
+
|
|
215
|
+
def entries(self) -> Iterator[dict[str, Any]]:
|
|
216
|
+
"""Yield every entry that can be parsed, and count the ones that cannot.
|
|
217
|
+
|
|
218
|
+
Skipping rather than raising, because the log is a plain file that customers grep and
|
|
219
|
+
archive, and a writer killed mid-append leaves a half-written line behind. Raising on it
|
|
220
|
+
took down `report`, `verify`, `explain` and `flagged` at once — one damaged line anywhere
|
|
221
|
+
in the file made the whole trail unreadable, which is the opposite of what an evidence
|
|
222
|
+
store should do.
|
|
223
|
+
|
|
224
|
+
The count lands on `unreadable_lines` so a caller can report on a subset *knowingly*
|
|
225
|
+
rather than quietly. A damaged line normally shows up as a gap or a broken link in the
|
|
226
|
+
hash chain too, and that is the stronger signal.
|
|
227
|
+
"""
|
|
228
|
+
self.unreadable_lines = 0
|
|
229
|
+
if not self.path.exists():
|
|
230
|
+
return
|
|
231
|
+
with self.path.open("r", encoding="utf-8") as fh:
|
|
232
|
+
for line in fh:
|
|
233
|
+
line = line.strip()
|
|
234
|
+
if not line:
|
|
235
|
+
continue
|
|
236
|
+
try:
|
|
237
|
+
yield json.loads(line)
|
|
238
|
+
except json.JSONDecodeError:
|
|
239
|
+
self.unreadable_lines += 1
|
|
240
|
+
|
|
241
|
+
def for_memory(self, memory_id: str) -> list[dict[str, Any]]:
|
|
242
|
+
"""The full lifecycle of one memory: who wrote it, who asked, how often it was refused."""
|
|
243
|
+
return [e for e in self.entries() if e.get("memory_id") == memory_id]
|
|
244
|
+
|
|
245
|
+
def tail(self, n: int = 20) -> list[dict[str, Any]]:
|
|
246
|
+
"""The last n entries, read backwards from the end of the file.
|
|
247
|
+
|
|
248
|
+
Reading the whole log to return twenty lines is fine until it is not. A
|
|
249
|
+
long-running deployment accumulates entries without bound, and `tail` is exactly
|
|
250
|
+
what an operator reaches for when the file has grown large. Splitting on the byte
|
|
251
|
+
value of the newline is safe for UTF-8: a newline byte cannot occur inside a
|
|
252
|
+
multi-byte character.
|
|
253
|
+
"""
|
|
254
|
+
if n <= 0 or not self.path.exists():
|
|
255
|
+
return []
|
|
256
|
+
block = 64 * 1024
|
|
257
|
+
with self.path.open("rb") as handle:
|
|
258
|
+
handle.seek(0, os.SEEK_END)
|
|
259
|
+
remaining = handle.tell()
|
|
260
|
+
buffer = b""
|
|
261
|
+
# Keep growing the window until it holds more than n newlines, so the first
|
|
262
|
+
# line is guaranteed to be complete.
|
|
263
|
+
while remaining > 0 and buffer.count(b"\n") <= n:
|
|
264
|
+
step = min(block, remaining)
|
|
265
|
+
remaining -= step
|
|
266
|
+
handle.seek(remaining)
|
|
267
|
+
buffer = handle.read(step) + buffer
|
|
268
|
+
lines = [line for line in buffer.split(b"\n") if line.strip()]
|
|
269
|
+
# Same tolerance as `entries()`: a damaged line is skipped, not raised on. `audit --tail`
|
|
270
|
+
# is what an operator reaches for *while* something is wrong, so it is the last thing
|
|
271
|
+
# that should refuse to run.
|
|
272
|
+
out: list[dict[str, Any]] = []
|
|
273
|
+
for raw in lines[-n:]:
|
|
274
|
+
try:
|
|
275
|
+
out.append(json.loads(raw.decode("utf-8")))
|
|
276
|
+
except (UnicodeDecodeError, json.JSONDecodeError):
|
|
277
|
+
continue
|
|
278
|
+
return out
|
|
279
|
+
|
|
280
|
+
|
|
281
|
+
class PolicyStampedAudit:
|
|
282
|
+
"""Wraps an `AuditLog` and stamps every entry with the policy revision in force.
|
|
283
|
+
|
|
284
|
+
Centralised rather than passed at each call site for a specific reason: there are
|
|
285
|
+
more than a dozen places that write audit events, and each one remembering to
|
|
286
|
+
include the revision is a chance to forget. An audit record that cannot say which
|
|
287
|
+
policy governed the decision is much weaker evidence -- "we were authorised to do
|
|
288
|
+
that" is unanswerable if permissions changed since.
|
|
289
|
+
|
|
290
|
+
Delegates everything else, so it is a drop-in for `AuditLog`.
|
|
291
|
+
"""
|
|
292
|
+
|
|
293
|
+
def __init__(self, inner: AuditLog, revision_provider: Any):
|
|
294
|
+
self._inner = inner
|
|
295
|
+
self._revision_provider = revision_provider
|
|
296
|
+
|
|
297
|
+
@property
|
|
298
|
+
def inner(self) -> AuditLog:
|
|
299
|
+
return self._inner
|
|
300
|
+
|
|
301
|
+
@property
|
|
302
|
+
def path(self) -> Path:
|
|
303
|
+
return self._inner.path
|
|
304
|
+
|
|
305
|
+
def record(self, event: str, **fields: Any) -> dict[str, Any]:
|
|
306
|
+
fields.setdefault("policy_revision", self._revision_provider())
|
|
307
|
+
return self._inner.record(event, **fields)
|
|
308
|
+
|
|
309
|
+
# Semantic wrappers must go through this class's `record`, not the inner one.
|
|
310
|
+
def write_decision(self, **f: Any) -> dict[str, Any]:
|
|
311
|
+
return self.record("memory.write", **f)
|
|
312
|
+
|
|
313
|
+
def read_decision(self, **f: Any) -> dict[str, Any]:
|
|
314
|
+
return self.record("memory.read", **f)
|
|
315
|
+
|
|
316
|
+
def recall_denied(self, **f: Any) -> dict[str, Any]:
|
|
317
|
+
return self.record("memory.recall_denied", **f)
|
|
318
|
+
|
|
319
|
+
def forget(self, **f: Any) -> dict[str, Any]:
|
|
320
|
+
return self.record("memory.forget", **f)
|
|
321
|
+
|
|
322
|
+
def sweep(self, **f: Any) -> dict[str, Any]:
|
|
323
|
+
return self.record("memory.sweep", **f)
|
|
324
|
+
|
|
325
|
+
def entries(self) -> Iterator[dict[str, Any]]:
|
|
326
|
+
return self._inner.entries()
|
|
327
|
+
|
|
328
|
+
def for_memory(self, memory_id: str) -> list[dict[str, Any]]:
|
|
329
|
+
return self._inner.for_memory(memory_id)
|
|
330
|
+
|
|
331
|
+
def tail(self, n: int = 20) -> list[dict[str, Any]]:
|
|
332
|
+
return self._inner.tail(n)
|
|
333
|
+
|
|
334
|
+
def chain_status(self) -> ChainStatus:
|
|
335
|
+
return self._inner.chain_status()
|
amnesia/backend.py
ADDED
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
"""The seam that makes "sits in front of the memory store you already run" real.
|
|
2
|
+
|
|
3
|
+
Amnesia does not want to become your memory store. It wants to be the thing your
|
|
4
|
+
memory store sits behind. That only works if the store is swappable, so this module
|
|
5
|
+
defines the contract.
|
|
6
|
+
|
|
7
|
+
**Honest scope note.** What ships here is the extension point, the reference
|
|
8
|
+
implementation (`store.MemoryStore`) and a test proving a foreign backend can be
|
|
9
|
+
dropped in. Shipping adapters for specific third-party stores -- `hindsight`,
|
|
10
|
+
`ai-memory`, `company-brain` -- is deliberately *not* included: each one needs that
|
|
11
|
+
project's real API surface, and guessing at it would produce adapter code that
|
|
12
|
+
looks finished and has never once executed. A defined seam plus a test is worth
|
|
13
|
+
more than a fabricated integration.
|
|
14
|
+
|
|
15
|
+
Two protocols, because they have different bars:
|
|
16
|
+
|
|
17
|
+
- `MemoryBackend` is what a memory store must provide. Any store that can be
|
|
18
|
+
wrapped by an adapter can satisfy it.
|
|
19
|
+
- `WriteAttemptLedger` is optional. It is governance telemetry, not storage, and
|
|
20
|
+
requiring it of every backend would make adapters harder to write for no good
|
|
21
|
+
reason. Without it, burst detection falls back to an in-process ledger.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
from __future__ import annotations
|
|
25
|
+
|
|
26
|
+
from collections.abc import Sequence
|
|
27
|
+
from datetime import datetime
|
|
28
|
+
from typing import Any, Protocol, runtime_checkable
|
|
29
|
+
|
|
30
|
+
from .models import MemoryItem
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
@runtime_checkable
|
|
34
|
+
class MemoryBackend(Protocol):
|
|
35
|
+
"""What the governor needs from a memory store.
|
|
36
|
+
|
|
37
|
+
Deliberately narrow. In particular there is no `search(query)` that returns
|
|
38
|
+
ranked results with authorization already applied, because the two retrieval
|
|
39
|
+
paths are the whole point: `search_candidates` exists to report what was
|
|
40
|
+
*withheld*, and a backend that cannot answer that cannot support the
|
|
41
|
+
explainability guarantee.
|
|
42
|
+
"""
|
|
43
|
+
|
|
44
|
+
def add(self, item: MemoryItem) -> MemoryItem: ...
|
|
45
|
+
|
|
46
|
+
def get(self, memory_id: str) -> MemoryItem | None: ...
|
|
47
|
+
|
|
48
|
+
def update(self, memory_id: str, **fields: Any) -> None: ...
|
|
49
|
+
|
|
50
|
+
def delete(self, ids: Sequence[str]) -> list[str]: ...
|
|
51
|
+
|
|
52
|
+
def all_items(self, tenant: str | None = None) -> list[MemoryItem]: ...
|
|
53
|
+
|
|
54
|
+
def count(self, tenant: str | None = None) -> int: ...
|
|
55
|
+
|
|
56
|
+
def search_candidates(
|
|
57
|
+
self,
|
|
58
|
+
query: str,
|
|
59
|
+
*,
|
|
60
|
+
tenant: str,
|
|
61
|
+
min_confidence: float,
|
|
62
|
+
now: datetime,
|
|
63
|
+
limit: int = 20,
|
|
64
|
+
min_score: float = 0.0,
|
|
65
|
+
offset: int = 0,
|
|
66
|
+
) -> list[tuple[MemoryItem, float]]: ...
|
|
67
|
+
|
|
68
|
+
def search_allowed(
|
|
69
|
+
self,
|
|
70
|
+
query: str,
|
|
71
|
+
*,
|
|
72
|
+
tenant: str,
|
|
73
|
+
allowed_scopes: Sequence[str],
|
|
74
|
+
min_confidence: float,
|
|
75
|
+
now: datetime,
|
|
76
|
+
limit: int = 20,
|
|
77
|
+
min_score: float = 0.0,
|
|
78
|
+
offset: int = 0,
|
|
79
|
+
) -> list[tuple[MemoryItem, float]]: ...
|
|
80
|
+
|
|
81
|
+
def active_by_subject(self, tenant: str, subject: str) -> list[MemoryItem]: ...
|
|
82
|
+
|
|
83
|
+
def touch(self, ids: Sequence[str], now: datetime) -> None: ...
|
|
84
|
+
|
|
85
|
+
def close(self) -> None: ...
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
@runtime_checkable
|
|
89
|
+
class WriteAttemptLedger(Protocol):
|
|
90
|
+
"""Every write attempt, including the rejected ones.
|
|
91
|
+
|
|
92
|
+
A store that only records successes cannot show a burst of *refused* writes,
|
|
93
|
+
which is the signature of someone probing the gate -- so this cannot be
|
|
94
|
+
reconstructed from the memory table after the fact.
|
|
95
|
+
"""
|
|
96
|
+
|
|
97
|
+
def record_attempt(
|
|
98
|
+
self,
|
|
99
|
+
*,
|
|
100
|
+
tenant: str,
|
|
101
|
+
subject: str,
|
|
102
|
+
source: str,
|
|
103
|
+
scope: str,
|
|
104
|
+
outcome: str,
|
|
105
|
+
now: datetime,
|
|
106
|
+
) -> None: ...
|
|
107
|
+
|
|
108
|
+
def count_attempts_since(self, *, tenant: str, subject: str, since: datetime) -> int: ...
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
class InMemoryLedger:
|
|
112
|
+
"""Fallback for backends that do not implement `WriteAttemptLedger`.
|
|
113
|
+
|
|
114
|
+
Degraded but not silent: burst detection still works for the lifetime of the
|
|
115
|
+
process, and `MemoryGovernor` records the degradation in the audit stream so an
|
|
116
|
+
operator can tell the difference between "no burst" and "we cannot see bursts".
|
|
117
|
+
"""
|
|
118
|
+
|
|
119
|
+
def __init__(self) -> None:
|
|
120
|
+
self._rows: list[dict[str, Any]] = []
|
|
121
|
+
|
|
122
|
+
def record_attempt(
|
|
123
|
+
self,
|
|
124
|
+
*,
|
|
125
|
+
tenant: str,
|
|
126
|
+
subject: str,
|
|
127
|
+
source: str,
|
|
128
|
+
scope: str,
|
|
129
|
+
outcome: str,
|
|
130
|
+
now: datetime,
|
|
131
|
+
) -> None:
|
|
132
|
+
self._rows.append(
|
|
133
|
+
{
|
|
134
|
+
"tenant": tenant,
|
|
135
|
+
"subject": subject or "",
|
|
136
|
+
"source": source,
|
|
137
|
+
"scope": scope,
|
|
138
|
+
"outcome": outcome,
|
|
139
|
+
"ts": now,
|
|
140
|
+
}
|
|
141
|
+
)
|
|
142
|
+
|
|
143
|
+
def count_attempts_since(self, *, tenant: str, subject: str, since: datetime) -> int:
|
|
144
|
+
return sum(
|
|
145
|
+
1
|
|
146
|
+
for row in self._rows
|
|
147
|
+
if row["tenant"] == tenant and row["subject"] == subject and row["ts"] >= since
|
|
148
|
+
)
|
|
149
|
+
|
|
150
|
+
def attempts(self) -> list[dict[str, Any]]:
|
|
151
|
+
return list(self._rows)
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def resolve_ledger(backend: MemoryBackend) -> WriteAttemptLedger:
|
|
155
|
+
"""Use the backend's own ledger when it has one, otherwise fall back."""
|
|
156
|
+
if isinstance(backend, WriteAttemptLedger):
|
|
157
|
+
return backend
|
|
158
|
+
return InMemoryLedger()
|