agent-audit-memory 0.2.0rc1__tar.gz

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.
Files changed (30) hide show
  1. agent_audit_memory-0.2.0rc1/LICENSE +21 -0
  2. agent_audit_memory-0.2.0rc1/PKG-INFO +236 -0
  3. agent_audit_memory-0.2.0rc1/README.md +223 -0
  4. agent_audit_memory-0.2.0rc1/agent_audit_memory.egg-info/PKG-INFO +236 -0
  5. agent_audit_memory-0.2.0rc1/agent_audit_memory.egg-info/SOURCES.txt +28 -0
  6. agent_audit_memory-0.2.0rc1/agent_audit_memory.egg-info/dependency_links.txt +1 -0
  7. agent_audit_memory-0.2.0rc1/agent_audit_memory.egg-info/top_level.txt +1 -0
  8. agent_audit_memory-0.2.0rc1/aml/__init__.py +56 -0
  9. agent_audit_memory-0.2.0rc1/aml/chain.py +99 -0
  10. agent_audit_memory-0.2.0rc1/aml/hardrules.py +48 -0
  11. agent_audit_memory-0.2.0rc1/aml/ledger.py +82 -0
  12. agent_audit_memory-0.2.0rc1/aml/lock.py +48 -0
  13. agent_audit_memory-0.2.0rc1/aml/recycle.py +121 -0
  14. agent_audit_memory-0.2.0rc1/aml/search.py +45 -0
  15. agent_audit_memory-0.2.0rc1/aml/security.py +97 -0
  16. agent_audit_memory-0.2.0rc1/aml/store.py +166 -0
  17. agent_audit_memory-0.2.0rc1/aml/util.py +156 -0
  18. agent_audit_memory-0.2.0rc1/aml/wal.py +94 -0
  19. agent_audit_memory-0.2.0rc1/pyproject.toml +22 -0
  20. agent_audit_memory-0.2.0rc1/setup.cfg +4 -0
  21. agent_audit_memory-0.2.0rc1/tests/test_chain.py +62 -0
  22. agent_audit_memory-0.2.0rc1/tests/test_hardrules.py +53 -0
  23. agent_audit_memory-0.2.0rc1/tests/test_ledger.py +65 -0
  24. agent_audit_memory-0.2.0rc1/tests/test_lock.py +65 -0
  25. agent_audit_memory-0.2.0rc1/tests/test_recovery.py +255 -0
  26. agent_audit_memory-0.2.0rc1/tests/test_recycle.py +81 -0
  27. agent_audit_memory-0.2.0rc1/tests/test_search.py +52 -0
  28. agent_audit_memory-0.2.0rc1/tests/test_security.py +62 -0
  29. agent_audit_memory-0.2.0rc1/tests/test_store.py +81 -0
  30. agent_audit_memory-0.2.0rc1/tests/test_wal.py +59 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 agent-memory-ledger maintainers
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,236 @@
1
+ Metadata-Version: 2.4
2
+ Name: agent-audit-memory
3
+ Version: 0.2.0rc1
4
+ Summary: A verifiable memory layer for AI agents: WAL with fsync durability, hash-chained trail, recycle bin + provable erasure, conflict ledger, write lock, hard rules, single-writer process lock (research prototype / AI-assisted development).
5
+ Author-email: agent-memory-ledger maintainers <2307788504@qq.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://gitcode.com/gcw_MKhSyoGN/agent-memory-ledger
8
+ Keywords: agent,memory,mcp,audit,verifiable,llm,wal
9
+ Requires-Python: >=3.9
10
+ Description-Content-Type: text/markdown
11
+ License-File: LICENSE
12
+ Dynamic: license-file
13
+
14
+ # agent-memory-ledger
15
+
16
+ > **A verifiable memory layer for AI agents** — WAL-first writes, hash-chained
17
+ > trail, soft-delete recycle bin, conflict ledger, write locks and permanent
18
+ > rigid rules, with a **fail-closed** posture.
19
+
20
+ ```bash
21
+ pip install agent-audit-memory # zero deps, Python 3.9+
22
+ ```
23
+
24
+ > **PyPI name note**: on PyPI this package is published as
25
+ > `agent-audit-memory` — the earlier `agent-memory-ledger` name was already
26
+ > taken on PyPI by an unrelated project, and the rename also follows the
27
+ > naming review recommendation: `audit` communicates the actual value
28
+ > (auditable memory) and avoids the "ledger/blockchain" association. The repo,
29
+ > import path (`import aml`), CLI and everything else are unchanged.
30
+
31
+ > **Release policy**: until a first external-user validation window closes, PyPI
32
+ > releases are published as **pre-release** (`==0.2.0rc1` etc.), not `latest`.
33
+ > Pre-release builds are suitable for prototype validation, **not** for
34
+ > processing sensitive data. See `docs/performance.md` and
35
+ > `docs/compliance.md` before choosing durability/backends.
36
+
37
+ ![License](https://img.shields.io/badge/license-MIT-blue)
38
+ ![Python](https://img.shields.io/badge/python-3.9%2B-blue)
39
+ ![Tests](https://img.shields.io/badge/tests-79%20passed-green)
40
+ ![Deps](https://img.shields.io/badge/runtime%20deps-0-green)
41
+ ![Status](https://img.shields.io/badge/status-research%20prototype-orange)
42
+
43
+ <a href="https://gitcode.com/gcw_MKhSyoGN/agent-memory-ledger"><img src="https://img.shields.io/badge/GitCode-gcw_MKhSyoGN%2Fagent-memory-ledger-blue" alt="GitCode"></a>
44
+ <a href="https://github.com/langarden/agent-memory-ledger"><img src="https://img.shields.io/badge/GitHub-langarden%2Fagent-memory-ledger-black" alt="GitHub"></a>
45
+
46
+ [中文版](docs/README.zh-CN.md) · *Research prototype / AI-assisted development.*
47
+
48
+ ---
49
+
50
+ Most agent memory stores help you **remember**. This one also helps you
51
+ **prove** that nothing was recorded wrong, deleted silently, or tampered with —
52
+ an **audit-grade memory** for agents that need to be accountable.
53
+
54
+ ## Known limitations (read first)
55
+
56
+ > ⚠️ v0.2 is a research prototype. Read this before filing an issue.
57
+
58
+ | # | Limitation | Effect / guidance |
59
+ |:--|:--|:--|
60
+ | 1 | **Single-process writer** per storage directory | enforced by an exclusive lock; second writer raises `ProcessContentionError` with guidance. Recommended: one process, one directory (or per-process `namespace=`). |
61
+ | 2 | **No NFS / network shares** as storage backend | atomic rename is unreliable there; local disk only. |
62
+ | 3 | **File-store capacity** | tuned for ≤ ~10k records per JSON file; SQLite backend on roadmap. |
63
+ | 4 | **No read-side access control** | `namespace=` is data isolation, NOT a security boundary; add OS/object-store ACLs for multi-tenant production. |
64
+ | 5 | **Not a legal forensics tool** | erasure certificates / hash chains are internal integrity proofs, not court-grade evidence (see `docs/compliance.md`). |
65
+ | 6 | **`durability="strict"` is slow** | fsync per write; use it for audit scenarios, not high-QPS chat agents. See `docs/performance.md`. |
66
+ | 7 | **Chain `verify()` is O(n)** | fine ≤ ~100k entries; segmented/snapshot verifier on roadmap. |
67
+
68
+ ## Why another memory library?
69
+
70
+ | Agent memory stores do… | agent-memory-ledger also does… |
71
+ |:--|:--|
72
+ | store and retrieve memories | **write-ahead log** — crash replayable, nothing lost |
73
+ | remember long conversations | **hash-chained trail** — offline `verify()` catches tampering |
74
+ | delete old entries | **soft delete + recycle bin** — 30-day retention, restorable |
75
+ | update conflicting values | **conflict ledger** — surfaces conflicts for human resolution, never merges silently |
76
+ | let agents write freely | **write locks** — subagents write `draft`, master promotes to `core` |
77
+ | decay old knowledge | **hard rules** — permanent rigid rules never decay, archive, or filter |
78
+
79
+ ### The gap this fills
80
+
81
+ Reliability failures are not edge cases. Common failure modes across popular
82
+ agent-memory stores include:
83
+
84
+ - **A failed write loses the memory body permanently** and leaves no way to
85
+ retry — exactly what a write-ahead log + crash replay prevents.
86
+ - **Concurrent writers tear files / corrupt state** during shutdown or shared
87
+ use — a single append-only WAL with an exclusive writer lock removes this
88
+ class of failure.
89
+ - **A single corrupted character silently invalidates a whole batch** —
90
+ silent-corruption failures that a hash-chained, offline-verifiable trail
91
+ surfaces immediately instead of propagating.
92
+
93
+ These are **reliability and verifiability** problems, not "remember harder"
94
+ problems. `agent-memory-ledger` is built so that **every write is logged before
95
+ it lands, every record is hash-chained and offline-checkable, nothing is
96
+ deleted silently, and no conflict is merged without a human** — the ten
97
+ invariants below.
98
+
99
+ ## Product family
100
+
101
+ Part of the **Verifiable-agent family** — the same fail-closed, audit-trail
102
+ design language across four repositories (READMEs link each other):
103
+
104
+ | Repo | Role |
105
+ |:--|:--|
106
+ | [agent-call-audit](https://gitcode.com/gcw_MKhSyoGN/agent-call-audit) | audit **engine** for agent tool calls |
107
+ | **agent-memory-ledger** | verifiable **memory** layer |
108
+ | [agent-audit-gateway](https://gitcode.com/gcw_MKhSyoGN/agent-audit-gateway) | HTTP **gateway** around the engine |
109
+ | [agent-route-grid](https://gitcode.com/gcw_MKhSyoGN/agent-route-grid) | audited multi-agent **routing** |
110
+
111
+ ## Install
112
+
113
+ ```bash
114
+ pip install agent-audit-memory # once published
115
+ # dev / from source:
116
+ pip install -e .
117
+ ```
118
+
119
+ Zero runtime dependencies. Python 3.9+.
120
+
121
+ ## 5-line example
122
+
123
+ ```python
124
+ from aml import MemoryStore, RecycleBin
125
+
126
+ store = MemoryStore("./mem") # WAL + hash chain on disk
127
+ store.put({"layer": "core", "key": "redline", "payload": "no leverage"})
128
+ print(store.chain.verify()) # (True, None, 1) offline proof
129
+ bin = RecycleBin(store); bin.recycle("core", "redline"); bin.restore("redline")
130
+ ```
131
+
132
+ ## Proof of life
133
+
134
+ Real output from `python examples/demo.py` (seven scenarios):
135
+
136
+ ```
137
+ 01 write + verify trail -> trail verify: (True, None, 2)
138
+ 02 WAL replay after crash -> replayed: 2 bad: 0 applied_keys: ['risk_redline', ...]
139
+ 03 hard rule exemption -> risk_redline score=1.0 (kept) | note/alpha score=0.5
140
+ 04 conflict resolution -> conflict CFL-... pending -> after resolve pending: []
141
+ 05 recycle + restore -> original layer has key: False -> restored: True
142
+ 06 write lock fail-closed -> subagent write core: False -> denied (fail-closed)
143
+ 07 sanitize + audit -> {'password': '[REDACTED]', 'token': '[REDACTED]'}
144
+ ```
145
+
146
+ ## Invariants
147
+
148
+ | # | Invariant | Guarantee |
149
+ |:--|:--|:--|
150
+ | 1 | WAL before commit | every mutation is logged first; crash replayable |
151
+ | 2 | Triple pre-check | conflict / sensitive / redundant checks gate every write |
152
+ | 3 | Soft delete | records go to a recycle bin (30 days), restorable |
153
+ | 4 | Hash-chained trail | `verify()` recomputes the chain; tamper is detected |
154
+ | 5 | Hard rules | permanent rigid rules never decay, archive, or filter |
155
+ | 6 | Write lock | subagents write `draft` only; master promotes to `core` |
156
+ | 7 | Zero sensitive persistence | secrets are sanitized / stored as hashes only |
157
+ | 8 | Conflicts surfaced | pending conflicts require human resolution; never merged silently |
158
+ | 9 | Single-writer enforcement | exclusive cross-process lock per storage dir (fail-closed) |
159
+ | 10 | Provable erasure | purge writes an erasure certificate (digest only), plaintext removed |
160
+
161
+ **Durability** (`durability=` on `MemoryStore` / `WalLog`): `strict` fsyncs
162
+ every append (power-loss safe, audit-grade), `normal` flushes per append
163
+ (default), `fast` skips fsync (testing only).
164
+
165
+ ## Concurrency & capacity limits (current file backend)
166
+
167
+ - **Single-process writer** per storage directory (enforced by an exclusive
168
+ lock — a second writer raises `ProcessContentionError` instead of corrupting
169
+ files). This is the **recommended** v0.2 posture: one agent process, one
170
+ directory. A shared SQLite backend for multi-process write is on the roadmap.
171
+ - JSON file store is tuned for **≤ ~10k records per file**; above that, switch
172
+ to the planned SQLite backend (WAL mode, transactional, indexed).
173
+ - Chain `verify()` is an O(n) linear pass — fine for ≤ ~100k entries; a
174
+ segmented/snapshot verifier is on the roadmap for larger sets.
175
+
176
+ ## Compliance note (read before citing regulations)
177
+
178
+ This library provides the **technical substrate** for audit-grade memory —
179
+ WAL, hash-chained trail, soft delete + provable erasure, write locks. It does
180
+ **not** by itself make a system "GDPR / EU AI Act compliant": full compliance
181
+ also requires retention policies, access control on read, operator
182
+ procedures, and organisational processes. See `docs/compliance.md` and
183
+ `RETAIN_ERASE_POLICY.md` for the current capability envelope. (Managed by
184
+ expert review 2026-11.)
185
+
186
+ ## Architecture
187
+
188
+ ```
189
+ aml/
190
+ ├── wal.py append-only write-ahead log + crash recovery
191
+ ├── chain.py hash-chained audit trail (LSN-ordered), offline-verifiable
192
+ ├── store.py layered store (draft / hot / core / archive; namespace-isolated)
193
+ ├── recycle.py soft delete + 30-day retention + provable erasure certificates
194
+ ├── ledger.py conflict ledger (pending -> human resolution)
195
+ ├── lock.py role-based write permission (fail-closed)
196
+ ├── hardrules.py permanent rigid rules (exempt from decay/archive)
197
+ ├── search.py layered retrieval (hard first + source receipt)
198
+ ├── security.py digest / sanitize / backup / audit events
199
+ └── util.py atomic writes + exclusive cross-process file lock
200
+ ```
201
+
202
+ ## Roadmap ideas
203
+
204
+ - **v0.3 — audit-grade completeness** (per external expert review 2026-11):
205
+ content-level read access control; provenance chain (which prompt / tool
206
+ call produced a memory); configurable retention tiers + auto-archive; export
207
+ of an independent audit-event stream.
208
+ - **Scalability — SQLite backend (architecture constraint)**: when adding the
209
+ SQLite store, **do not re-implement the JSON-file hash-chain at file level**.
210
+ SQLite already provides WAL + transactions + row locks; the hash-chain
211
+ semantic should be pushed down to **row level** rather than stacking a second
212
+ WAL on top. Two nested WAL layers add avoidable complexity and consistency
213
+ risk.
214
+ - **Ecosystem — LangGraph/LangChain `Checkpointer` binding (contract
215
+ boundary)**: the compatibility layer stores LangGraph checkpoints **as aml
216
+ payloads** and aml owns the integrity/audit of those writes. It does **not**
217
+ change LangGraph checkpoint semantics; LangGraph-internal bugs / checkpoint
218
+ overwrites are outside aml's guarantees. A **separate demo repository**
219
+ (not the main repo) will host the LangGraph integration demo + compliance
220
+ export scripts, keeping the main repo clean so users can clone-and-run.
221
+ - **MCP server** (`memory.read` / `memory.write`); **remote sync** with a
222
+ verifiable append-only chain.
223
+
224
+ ## Contributing / Security / License / AI disclosure
225
+
226
+ - [CONTRIBUTING.md](CONTRIBUTING.md) — fail-closed first, no new deps,
227
+ sanitized commits, green tests.
228
+ - [SECURITY.md](SECURITY.md) — report privately; reference implementation,
229
+ not a hardened product; no third-party security audit yet.
230
+ - [docs/compliance.md](docs/compliance.md) — capability envelope vs EU AI Act
231
+ / GDPR; [RETAIN_ERASE_POLICY.md](RETAIN_ERASE_POLICY.md) — retention &
232
+ provable-erasure policy; [docs/AUDIT_LOG_FORMAT.md](docs/AUDIT_LOG_FORMAT.md)
233
+ — log schema for third-party audit tooling.
234
+ - [docs/AIGC_DISCLOSURE.md](docs/AIGC_DISCLOSURE.md) — AI-assisted development
235
+ disclosure.
236
+ - [LICENSE](LICENSE) — MIT, `agent-memory-ledger maintainers`.
@@ -0,0 +1,223 @@
1
+ # agent-memory-ledger
2
+
3
+ > **A verifiable memory layer for AI agents** — WAL-first writes, hash-chained
4
+ > trail, soft-delete recycle bin, conflict ledger, write locks and permanent
5
+ > rigid rules, with a **fail-closed** posture.
6
+
7
+ ```bash
8
+ pip install agent-audit-memory # zero deps, Python 3.9+
9
+ ```
10
+
11
+ > **PyPI name note**: on PyPI this package is published as
12
+ > `agent-audit-memory` — the earlier `agent-memory-ledger` name was already
13
+ > taken on PyPI by an unrelated project, and the rename also follows the
14
+ > naming review recommendation: `audit` communicates the actual value
15
+ > (auditable memory) and avoids the "ledger/blockchain" association. The repo,
16
+ > import path (`import aml`), CLI and everything else are unchanged.
17
+
18
+ > **Release policy**: until a first external-user validation window closes, PyPI
19
+ > releases are published as **pre-release** (`==0.2.0rc1` etc.), not `latest`.
20
+ > Pre-release builds are suitable for prototype validation, **not** for
21
+ > processing sensitive data. See `docs/performance.md` and
22
+ > `docs/compliance.md` before choosing durability/backends.
23
+
24
+ ![License](https://img.shields.io/badge/license-MIT-blue)
25
+ ![Python](https://img.shields.io/badge/python-3.9%2B-blue)
26
+ ![Tests](https://img.shields.io/badge/tests-79%20passed-green)
27
+ ![Deps](https://img.shields.io/badge/runtime%20deps-0-green)
28
+ ![Status](https://img.shields.io/badge/status-research%20prototype-orange)
29
+
30
+ <a href="https://gitcode.com/gcw_MKhSyoGN/agent-memory-ledger"><img src="https://img.shields.io/badge/GitCode-gcw_MKhSyoGN%2Fagent-memory-ledger-blue" alt="GitCode"></a>
31
+ <a href="https://github.com/langarden/agent-memory-ledger"><img src="https://img.shields.io/badge/GitHub-langarden%2Fagent-memory-ledger-black" alt="GitHub"></a>
32
+
33
+ [中文版](docs/README.zh-CN.md) · *Research prototype / AI-assisted development.*
34
+
35
+ ---
36
+
37
+ Most agent memory stores help you **remember**. This one also helps you
38
+ **prove** that nothing was recorded wrong, deleted silently, or tampered with —
39
+ an **audit-grade memory** for agents that need to be accountable.
40
+
41
+ ## Known limitations (read first)
42
+
43
+ > ⚠️ v0.2 is a research prototype. Read this before filing an issue.
44
+
45
+ | # | Limitation | Effect / guidance |
46
+ |:--|:--|:--|
47
+ | 1 | **Single-process writer** per storage directory | enforced by an exclusive lock; second writer raises `ProcessContentionError` with guidance. Recommended: one process, one directory (or per-process `namespace=`). |
48
+ | 2 | **No NFS / network shares** as storage backend | atomic rename is unreliable there; local disk only. |
49
+ | 3 | **File-store capacity** | tuned for ≤ ~10k records per JSON file; SQLite backend on roadmap. |
50
+ | 4 | **No read-side access control** | `namespace=` is data isolation, NOT a security boundary; add OS/object-store ACLs for multi-tenant production. |
51
+ | 5 | **Not a legal forensics tool** | erasure certificates / hash chains are internal integrity proofs, not court-grade evidence (see `docs/compliance.md`). |
52
+ | 6 | **`durability="strict"` is slow** | fsync per write; use it for audit scenarios, not high-QPS chat agents. See `docs/performance.md`. |
53
+ | 7 | **Chain `verify()` is O(n)** | fine ≤ ~100k entries; segmented/snapshot verifier on roadmap. |
54
+
55
+ ## Why another memory library?
56
+
57
+ | Agent memory stores do… | agent-memory-ledger also does… |
58
+ |:--|:--|
59
+ | store and retrieve memories | **write-ahead log** — crash replayable, nothing lost |
60
+ | remember long conversations | **hash-chained trail** — offline `verify()` catches tampering |
61
+ | delete old entries | **soft delete + recycle bin** — 30-day retention, restorable |
62
+ | update conflicting values | **conflict ledger** — surfaces conflicts for human resolution, never merges silently |
63
+ | let agents write freely | **write locks** — subagents write `draft`, master promotes to `core` |
64
+ | decay old knowledge | **hard rules** — permanent rigid rules never decay, archive, or filter |
65
+
66
+ ### The gap this fills
67
+
68
+ Reliability failures are not edge cases. Common failure modes across popular
69
+ agent-memory stores include:
70
+
71
+ - **A failed write loses the memory body permanently** and leaves no way to
72
+ retry — exactly what a write-ahead log + crash replay prevents.
73
+ - **Concurrent writers tear files / corrupt state** during shutdown or shared
74
+ use — a single append-only WAL with an exclusive writer lock removes this
75
+ class of failure.
76
+ - **A single corrupted character silently invalidates a whole batch** —
77
+ silent-corruption failures that a hash-chained, offline-verifiable trail
78
+ surfaces immediately instead of propagating.
79
+
80
+ These are **reliability and verifiability** problems, not "remember harder"
81
+ problems. `agent-memory-ledger` is built so that **every write is logged before
82
+ it lands, every record is hash-chained and offline-checkable, nothing is
83
+ deleted silently, and no conflict is merged without a human** — the ten
84
+ invariants below.
85
+
86
+ ## Product family
87
+
88
+ Part of the **Verifiable-agent family** — the same fail-closed, audit-trail
89
+ design language across four repositories (READMEs link each other):
90
+
91
+ | Repo | Role |
92
+ |:--|:--|
93
+ | [agent-call-audit](https://gitcode.com/gcw_MKhSyoGN/agent-call-audit) | audit **engine** for agent tool calls |
94
+ | **agent-memory-ledger** | verifiable **memory** layer |
95
+ | [agent-audit-gateway](https://gitcode.com/gcw_MKhSyoGN/agent-audit-gateway) | HTTP **gateway** around the engine |
96
+ | [agent-route-grid](https://gitcode.com/gcw_MKhSyoGN/agent-route-grid) | audited multi-agent **routing** |
97
+
98
+ ## Install
99
+
100
+ ```bash
101
+ pip install agent-audit-memory # once published
102
+ # dev / from source:
103
+ pip install -e .
104
+ ```
105
+
106
+ Zero runtime dependencies. Python 3.9+.
107
+
108
+ ## 5-line example
109
+
110
+ ```python
111
+ from aml import MemoryStore, RecycleBin
112
+
113
+ store = MemoryStore("./mem") # WAL + hash chain on disk
114
+ store.put({"layer": "core", "key": "redline", "payload": "no leverage"})
115
+ print(store.chain.verify()) # (True, None, 1) offline proof
116
+ bin = RecycleBin(store); bin.recycle("core", "redline"); bin.restore("redline")
117
+ ```
118
+
119
+ ## Proof of life
120
+
121
+ Real output from `python examples/demo.py` (seven scenarios):
122
+
123
+ ```
124
+ 01 write + verify trail -> trail verify: (True, None, 2)
125
+ 02 WAL replay after crash -> replayed: 2 bad: 0 applied_keys: ['risk_redline', ...]
126
+ 03 hard rule exemption -> risk_redline score=1.0 (kept) | note/alpha score=0.5
127
+ 04 conflict resolution -> conflict CFL-... pending -> after resolve pending: []
128
+ 05 recycle + restore -> original layer has key: False -> restored: True
129
+ 06 write lock fail-closed -> subagent write core: False -> denied (fail-closed)
130
+ 07 sanitize + audit -> {'password': '[REDACTED]', 'token': '[REDACTED]'}
131
+ ```
132
+
133
+ ## Invariants
134
+
135
+ | # | Invariant | Guarantee |
136
+ |:--|:--|:--|
137
+ | 1 | WAL before commit | every mutation is logged first; crash replayable |
138
+ | 2 | Triple pre-check | conflict / sensitive / redundant checks gate every write |
139
+ | 3 | Soft delete | records go to a recycle bin (30 days), restorable |
140
+ | 4 | Hash-chained trail | `verify()` recomputes the chain; tamper is detected |
141
+ | 5 | Hard rules | permanent rigid rules never decay, archive, or filter |
142
+ | 6 | Write lock | subagents write `draft` only; master promotes to `core` |
143
+ | 7 | Zero sensitive persistence | secrets are sanitized / stored as hashes only |
144
+ | 8 | Conflicts surfaced | pending conflicts require human resolution; never merged silently |
145
+ | 9 | Single-writer enforcement | exclusive cross-process lock per storage dir (fail-closed) |
146
+ | 10 | Provable erasure | purge writes an erasure certificate (digest only), plaintext removed |
147
+
148
+ **Durability** (`durability=` on `MemoryStore` / `WalLog`): `strict` fsyncs
149
+ every append (power-loss safe, audit-grade), `normal` flushes per append
150
+ (default), `fast` skips fsync (testing only).
151
+
152
+ ## Concurrency & capacity limits (current file backend)
153
+
154
+ - **Single-process writer** per storage directory (enforced by an exclusive
155
+ lock — a second writer raises `ProcessContentionError` instead of corrupting
156
+ files). This is the **recommended** v0.2 posture: one agent process, one
157
+ directory. A shared SQLite backend for multi-process write is on the roadmap.
158
+ - JSON file store is tuned for **≤ ~10k records per file**; above that, switch
159
+ to the planned SQLite backend (WAL mode, transactional, indexed).
160
+ - Chain `verify()` is an O(n) linear pass — fine for ≤ ~100k entries; a
161
+ segmented/snapshot verifier is on the roadmap for larger sets.
162
+
163
+ ## Compliance note (read before citing regulations)
164
+
165
+ This library provides the **technical substrate** for audit-grade memory —
166
+ WAL, hash-chained trail, soft delete + provable erasure, write locks. It does
167
+ **not** by itself make a system "GDPR / EU AI Act compliant": full compliance
168
+ also requires retention policies, access control on read, operator
169
+ procedures, and organisational processes. See `docs/compliance.md` and
170
+ `RETAIN_ERASE_POLICY.md` for the current capability envelope. (Managed by
171
+ expert review 2026-11.)
172
+
173
+ ## Architecture
174
+
175
+ ```
176
+ aml/
177
+ ├── wal.py append-only write-ahead log + crash recovery
178
+ ├── chain.py hash-chained audit trail (LSN-ordered), offline-verifiable
179
+ ├── store.py layered store (draft / hot / core / archive; namespace-isolated)
180
+ ├── recycle.py soft delete + 30-day retention + provable erasure certificates
181
+ ├── ledger.py conflict ledger (pending -> human resolution)
182
+ ├── lock.py role-based write permission (fail-closed)
183
+ ├── hardrules.py permanent rigid rules (exempt from decay/archive)
184
+ ├── search.py layered retrieval (hard first + source receipt)
185
+ ├── security.py digest / sanitize / backup / audit events
186
+ └── util.py atomic writes + exclusive cross-process file lock
187
+ ```
188
+
189
+ ## Roadmap ideas
190
+
191
+ - **v0.3 — audit-grade completeness** (per external expert review 2026-11):
192
+ content-level read access control; provenance chain (which prompt / tool
193
+ call produced a memory); configurable retention tiers + auto-archive; export
194
+ of an independent audit-event stream.
195
+ - **Scalability — SQLite backend (architecture constraint)**: when adding the
196
+ SQLite store, **do not re-implement the JSON-file hash-chain at file level**.
197
+ SQLite already provides WAL + transactions + row locks; the hash-chain
198
+ semantic should be pushed down to **row level** rather than stacking a second
199
+ WAL on top. Two nested WAL layers add avoidable complexity and consistency
200
+ risk.
201
+ - **Ecosystem — LangGraph/LangChain `Checkpointer` binding (contract
202
+ boundary)**: the compatibility layer stores LangGraph checkpoints **as aml
203
+ payloads** and aml owns the integrity/audit of those writes. It does **not**
204
+ change LangGraph checkpoint semantics; LangGraph-internal bugs / checkpoint
205
+ overwrites are outside aml's guarantees. A **separate demo repository**
206
+ (not the main repo) will host the LangGraph integration demo + compliance
207
+ export scripts, keeping the main repo clean so users can clone-and-run.
208
+ - **MCP server** (`memory.read` / `memory.write`); **remote sync** with a
209
+ verifiable append-only chain.
210
+
211
+ ## Contributing / Security / License / AI disclosure
212
+
213
+ - [CONTRIBUTING.md](CONTRIBUTING.md) — fail-closed first, no new deps,
214
+ sanitized commits, green tests.
215
+ - [SECURITY.md](SECURITY.md) — report privately; reference implementation,
216
+ not a hardened product; no third-party security audit yet.
217
+ - [docs/compliance.md](docs/compliance.md) — capability envelope vs EU AI Act
218
+ / GDPR; [RETAIN_ERASE_POLICY.md](RETAIN_ERASE_POLICY.md) — retention &
219
+ provable-erasure policy; [docs/AUDIT_LOG_FORMAT.md](docs/AUDIT_LOG_FORMAT.md)
220
+ — log schema for third-party audit tooling.
221
+ - [docs/AIGC_DISCLOSURE.md](docs/AIGC_DISCLOSURE.md) — AI-assisted development
222
+ disclosure.
223
+ - [LICENSE](LICENSE) — MIT, `agent-memory-ledger maintainers`.