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 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()