Tools
Aetnamem
By AetnaMem is agent Memory delivers fully local long-term auditable, proof-ready memory for AI Agents via a 4-tier progressive pipeline, with zero external API dependencies, it supports OpenClaw, install it via pip.
Install
pip install aetnamemConfiguration Example
{
"mcpServers": {
"aetnamem": {
"command": "aetnamem",
"args": ["mcp", "--db", "/home/you/.aetnamem/memories.db"]
}
}
}README
<p align="center">
<img src="./docs/assets/aetnamem-header.png" width="1536" alt="aetnamem control plane: provenance-aware memory, guarded actions, and independently verifiable evidence">
</p>
<h1 align="center">aetnamem</h1>
<p align="center">
<strong>Evidence before effect.</strong><br>
Auditable memory and exact-plan guarded actions for stateful AI agents.
</p>
<p align="center">
<a href="https://github.com/aetna000/aetnamem/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/aetna000/aetnamem/actions/workflows/ci.yml/badge.svg"></a>
<img alt="Version 0.2.1" src="https://img.shields.io/badge/version-0.2.1-315A7D?style=flat-square">
<img alt="Python 3.10 or newer" src="https://img.shields.io/badge/python-%E2%89%A53.10-2A6F73?style=flat-square&logo=python&logoColor=white">
<img alt="AGPL 3.0" src="https://img.shields.io/badge/license-AGPL--3.0-B23A48?style=flat-square">
<a href="https://aetna000.github.io/MemoryStackBench/"><img alt="MemoryStackBench 33 out of 33" src="https://img.shields.io/badge/MemoryStackBench-33%2F33-D49A2A?style=flat-square"></a>
</p>
<p align="center">
<a href="#install--use">Quick start</a> ·
<a href="./examples/flagship-demo/">Flagship demo</a> ·
<a href="./paper/aetnamem-control-plane.pdf">Scientific report</a> ·
<a href="./docs/guarded-actions.md">Guarded actions</a> ·
<a href="./TODO.md">Roadmap</a>
</p>
A local-first, zero-dependency Python engine for provenance-aware agent memory
and optional guarded actions. The reference store is one SQLite file. Its
security claims are deterministic and testable, but deliberately narrower
than “the database is trusted” or “every external action is reversible.”
- **Provenance is required.** Extracted records link to their source episode;
derived proposals instead cite existing episode or record IDs. Records also
carry source, session, turn, time, confidence, status, and trust metadata.
- **Classified untrusted content is quarantined.** Records classified as
webpage or tool output land `quarantined` until `promote()`. Correct origin
classification is a host responsibility: an untrusted caller that may lie
about `source_type` is outside this local API's trust boundary. `promote()`
records a trust transition but does not authenticate human confirmation;
protect or withhold that capability when the agent itself is untrusted.
- **Recognized corrections supersede.** When extraction assigns the same
`fact_key`, the new trusted record supersedes the previous active record;
the old record remains inspectable. Unrecognized or unkeyed contradictions
are not automatically resolved.
- **Memory content is logically purged.** `forget()` tombstones matching
records, clears their content and fact key, clears matching source episode
text, removes FTS entries, and returns a deletion receipt. SQLite free
pages, WAL files, filesystem snapshots, replicas, and backups require their
own secure-erasure and retention controls.
- **The audit log is independently checkable.** Engine-generated memory and
guarded-action transitions join a per-subject SHA-256 chain specified in
[audit-log specification](https://github.com/aetna000/aetnamem/blob/main/docs/audit-log-spec.md). The standard-library
[independent verifier](https://github.com/aetna000/aetnamem/blob/main/tools/verify_audit.py) imports no aetnamem
code. Hash chaining detects edits relative to a trusted head; externally
anchored checkpoints are required to detect suffix deletion or replacement
of the entire database.
- **Sensitive values are separated on guarded paths.** Core memory and
guarded-action events use content digests and structural metadata. Raw
action arguments and before-images live in an erasable payload table.
`retain_query_text=True` stores raw recall queries, and the low-level
`log_action()` method accepts caller-provided payloads, so callers must not
place secrets or raw content there.
## Guarantee boundaries
| boundary | engine enforces | deployment must provide |
|---|---|---|
| memory origin | quarantine based on the supplied/classified source type | authentic source attribution when callers are not trusted |
| quarantine promotion | only quarantined records can be promoted; transition is audited | authenticated user confirmation and access control to `promote()` |
| audit history | canonical hashes, per-subject chaining, receipt binding | external checkpoint anchoring against database-owner rewriting |
| memory erasure | logical purge from live tables and indexes | backup/WAL/snapshot retention and forensic secure deletion |
| action authority | exact-plan HMAC signed by a reviewer-key holder | protecting that key and the staging boundary from the agent |
| approver identity | records the supplied approver label | identity authentication; the shared HMAC does not prove that label |
| external effects | adapter preconditions, receipts, postcondition checks, explicit uncertainty | provider-specific idempotency and authoritative recovery where needed |
## Install & use
```bash
pip install aetnamem
# or, from a checkout:
pip install -e .
```
The product installs one console command: `aetnamem`. Use `aetnamem mcp` for
the MCP server and `aetnamem actions …` for guarded actions. `aetna000` is the
organization namespace only; it is not installed as a product command.
```python
from aetnamem import Memory
m = Memory("./memories.db") # or ":memory:"
m.remember("user-1", "My preferred airport is SFO.", session_id="s1")
m.remember("user-1", "Actually, use OAK as my preferred airport going forward.",
session_id="s2")
m.recall("user-1", "Which airport should I fly from?")
# -> [{'content': "User's preferred airport is OAK.", 'status': 'active', ...}]
m.forget("user-1", utterance="Forget my preferred airport.")
m.inspect("user-1") # full evidence dump, incl. audit chain check
```
The core verbs — `remember`, `recall`, `list`, `forget`, `inspect`, `audit` —
plus `promote` (quarantine release), `log_action` (agent audit events),
`consolidate`, `persona`, `scenes`, `propose`, `checkpoint`, and `verify`
are available from Python and the CLI, so any process that can run a shell
command is a client:
```bash
aetnamem remember ./memories.db user-1 "My preferred airport is SFO." --session s1
aetnamem recall ./memories.db user-1 "Which airport should I book from?"
aetnamem forget ./memories.db user-1 --utterance "Forget my preferred airport."
aetnamem list ./memories.db user-1 --all
aetnamem promote ./memories.db user-1 rec_...
aetnamem log-action ./memories.db user-1 tool_call --payload '{"tool":"calendar"}'
aetnamem consolidate ./memories.db user-1
aetnamem persona ./memories.db user-1
aetnamem scenes ./memories.db user-1
aetnamem inspect ./memories.db user-1
aetnamem audit ./memories.db user-1
aetnamem checkpoint ./memories.db ./checkpoints.jsonl # anchor this file externally
aetnamem verify ./memories.db --checkpoints ./checkpoints.jsonl
python tools/verify_audit.py ./memories.db --checkpoints ./checkpoints.jsonl # no aetnamem import
```
The standalone `tools/verify_*.py` commands are included in Git checkouts and
source distributions. Wheel-only installs should use `aetnamem verify` and
`aetnamem actions verify`, which cover the same integrity rules.
## Guarded actions
Guarded-actions mode turns a proposed tool mutation into a canonical hash-bound
`WorldPatch`: exact operation digests, resource preconditions, adapter
fingerprints, causal evidence, authority, approval, execution attempts,
verification, compensation, and a receipt all share the subject's audit
chain. Evidence that merely `informed_by` an operation is distinct from the
host-attested `authorized_by` evidence that permits it.
The first reference adapter performs root-confined UTF-8 file writes and
deletes. It is classified as **verified compensatable**, not transactionally
reversible: `aetnamem` rechecks the before-state, executes only an exact approved
plan, observes the after-state, and verifies any compensation against the
captured before-state.
```bash
mkdir -p ./workspace
# Agent/host staging boundary: no reviewer key is needed here.
aetnamem actions stage ./memories.db user-1 filesystem write_text \
--root ./workspace \
--args '{"path":"report.md","content":"reviewed content"}' \
--actor researcher-agent \
--authority-id task-42 \
--authority-digest 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
aetnamem actions show ./memories.db act_...
# Separate trusted reviewer/executor shell. Persist this key securely.
export AETNAMEM_APPROVAL_KEY="$(python -c 'import secrets; print(secrets.token_hex(32))')"
aetnamem actions approve ./memories.db act_... --approver-label user-1
aetnamem actions commit ./memories.db act_... --root ./workspace
aetnamem actions verify ./memories.db act_...
python tools/verify_actions.py ./memories.db act_... # no aetnamem import
```
Changing the persisted plan, adapter manifest, approval binding, expiry, or
guarded file precondition prevents execution. Raw arguments, before-images, and provider
receipts live in the erasable action payload plane; audit events contain only
structural metadata and digests. Erase those payloads after their retention
period with `aetnamem actions purge-payloads ./memories.db act_...`.
If a process dies across an external execution boundary, use
`aetnamem actions recover ./memories.db act_...`; it fences in-flight effects
as uncertain and emits a `recovery_required` receipt instead of retrying.
Compatible external transaction journals can join the same forensic timeline
without copying their raw arguments, snapshots, results, claimed actors, or
client IDs into the audit plane:
```bash
aetnamem actions import-journal ./memories.db user-1 ./source-journal.db \
--source-id production-agent
```
Imports are idempotent per source/transaction and are
... (truncated)
tools
Comments
Sign in to leave a comment