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.
- agent_audit_memory-0.2.0rc1/LICENSE +21 -0
- agent_audit_memory-0.2.0rc1/PKG-INFO +236 -0
- agent_audit_memory-0.2.0rc1/README.md +223 -0
- agent_audit_memory-0.2.0rc1/agent_audit_memory.egg-info/PKG-INFO +236 -0
- agent_audit_memory-0.2.0rc1/agent_audit_memory.egg-info/SOURCES.txt +28 -0
- agent_audit_memory-0.2.0rc1/agent_audit_memory.egg-info/dependency_links.txt +1 -0
- agent_audit_memory-0.2.0rc1/agent_audit_memory.egg-info/top_level.txt +1 -0
- agent_audit_memory-0.2.0rc1/aml/__init__.py +56 -0
- agent_audit_memory-0.2.0rc1/aml/chain.py +99 -0
- agent_audit_memory-0.2.0rc1/aml/hardrules.py +48 -0
- agent_audit_memory-0.2.0rc1/aml/ledger.py +82 -0
- agent_audit_memory-0.2.0rc1/aml/lock.py +48 -0
- agent_audit_memory-0.2.0rc1/aml/recycle.py +121 -0
- agent_audit_memory-0.2.0rc1/aml/search.py +45 -0
- agent_audit_memory-0.2.0rc1/aml/security.py +97 -0
- agent_audit_memory-0.2.0rc1/aml/store.py +166 -0
- agent_audit_memory-0.2.0rc1/aml/util.py +156 -0
- agent_audit_memory-0.2.0rc1/aml/wal.py +94 -0
- agent_audit_memory-0.2.0rc1/pyproject.toml +22 -0
- agent_audit_memory-0.2.0rc1/setup.cfg +4 -0
- agent_audit_memory-0.2.0rc1/tests/test_chain.py +62 -0
- agent_audit_memory-0.2.0rc1/tests/test_hardrules.py +53 -0
- agent_audit_memory-0.2.0rc1/tests/test_ledger.py +65 -0
- agent_audit_memory-0.2.0rc1/tests/test_lock.py +65 -0
- agent_audit_memory-0.2.0rc1/tests/test_recovery.py +255 -0
- agent_audit_memory-0.2.0rc1/tests/test_recycle.py +81 -0
- agent_audit_memory-0.2.0rc1/tests/test_search.py +52 -0
- agent_audit_memory-0.2.0rc1/tests/test_security.py +62 -0
- agent_audit_memory-0.2.0rc1/tests/test_store.py +81 -0
- 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
|
+

|
|
38
|
+

|
|
39
|
+

|
|
40
|
+

|
|
41
|
+

|
|
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
|
+

|
|
25
|
+

|
|
26
|
+

|
|
27
|
+

|
|
28
|
+

|
|
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`.
|