aetnamem

Try governed memory beside your agent. Switch only after you inspect it.
Reversible memory trials for OpenClaw and Hermes, backed by auditable evidence.

Start safely · Watch the OpenClaw demo · Agent skills · Safe Switch guide · Current status · Python / MCP · Research

AetnaMem is a local-first memory and evidence layer for agents. Version 0.6.1 adds Safe Switch (beta): install it beside an existing OpenClaw or Hermes setup, collect candidate memories without changing the model's context, inspect exactly what AetnaMem would recall, try a limited canary, and turn it off through one local state file.

The generic Python Memory API, aetnamem mcp, existing SQLite databases, and normal OpenClaw integration remain compatible. The matching OpenClaw plugin is 0.4.0.

Adopt AetnaMem without a blind switch

Your current OpenClaw or Hermes memory stays in place while you evaluate AetnaMem:

Install beside the agent. Nothing is cut over.
Capture authenticated user turns. Candidate facts go to a separate local trial database; model context is unchanged.
Review the candidates. Approve useful facts and reject noisy ones.
Preview the exact context. AetnaMem shows the bytes, size, selected candidates, and manifest digest before the model sees anything.
Run a bounded canary. Only the number of turns you authorize receive approved memory.
Inspect your evidence. Compare answers and costs for your task; AetnaMem also reports candidate decisions, context size, exposures, configuration digests, and transition-chain validity.
Activate or restore. Switch on when your evidence is good enough, or roll back the saved host configuration without deleting the trial record.

Start the side-by-side trial:

python3 -m pip install --upgrade aetnamem
openclaw plugins install npm:openclaw-memory-aetnamem@0.4.0 --pin
aetnamem trial start --host openclaw
aetnamem trial status
aetnamem trial candidates

Then approve a candidate, inspect the preview, and allow one canary turn:

aetnamem trial approve tc_...
aetnamem trial preview
aetnamem trial canary --turns 1

# After evaluating your own result:
aetnamem trial activate  # use approved AetnaMem context normally
aetnamem trial rollback  # or restore the saved OpenClaw configuration

The 77-second real OpenClaw demonstration uses DeepSeek on an isolated agent. Its baseline answered “I do not know yet”; the one-turn AetnaMem canary answered “Kyoto” and used 12.9% fewer model tokens in that run. This is reproducible evidence for one demonstration task—not a promise that every workload improves by 12.9%.

The product promise is the safe evaluation path: see what AetnaMem captures, inspect what it would show, try a limited canary, and switch only when your own evidence supports the decision.

Give your agent governed-memory skills

Install the AetnaMem engine, then install the repository's focused skills:

python3 -m pip install --upgrade aetnamem
npx skills add aetna000/aetnamem

The skill library gives Codex, Claude, and other compatible agents three plain-language workflows:

Skill	Ask the agent
`use-governed-memory`	“Remember that reports must be Markdown, with provenance.”
`audit-agent-memory`	“Why do you remember that? Export the verified trace.”
`trial-agent-memory`	“Try AetnaMem beside OpenClaw without changing its context yet.”

The skills do not replace the evidence engine. They call public AetnaMem CLI operations; the engine remains responsible for admission policy, SQLite storage, provenance, audit-chain verification, correction, and deletion receipts. OpenClaw or Hermes hooks are still required for automatic capture of authenticated turns.

Skills tell the agent how to use memory. AetnaMem proves what actually happened.

The repository includes Codex and Claude plugin manifests as well as the provider-neutral skills. See the Agent skills guide for trust boundaries, example conversations, wrapper commands, and validation.

What happens during a Safe Switch trial

For OpenClaw:

python3 -m pip install --upgrade aetnamem
openclaw plugins install npm:openclaw-memory-aetnamem@0.4.0 --pin
aetnamem trial start --host auto
aetnamem trial dashboard

--host auto means “detect exactly one supported agent executable on this machine.” It fails and asks you to choose if both OpenClaw and Hermes are installed; it never guesses. The beginner flow has no --subject: candidate memory is scoped internally as local-user. Applications with real tenant identity should continue using the explicit Python/MCP subject boundary.

The trial moves through visible modes:

Mode	What AetnaMem does	Does it change the agent's context?
`capture`	Extracts candidate facts from authenticated user turns into a separate trial database	No
`preview`	Shows what it would recall; only user-approved candidates are eligible	No
`canary`	Supplies approved context for a fixed number of turns	Yes, limited
`active`	Supplies approved context on eligible turns	Yes
`off`	Stops capture and injection through the local control file	No

Important: capture stores normalized candidate facts and a source digest, not the raw user message. It does not expose memory tools to the agent. A missing, corrupt, or tampered trial state fails closed to off.

aetnamem trial status
aetnamem trial candidates
aetnamem trial approve tc_...
aetnamem trial preview
aetnamem trial canary --turns 10  # asks you to type the detected host name
aetnamem trial off       # immediate stop; host keeps running
aetnamem trial rollback  # stop, then restore the saved host plugin config

off affects future AetnaMem capture and context injection. rollback also restores the host configuration snapshot. Neither command deletes trial evidence, reverses past agent outputs, or deletes provider logs.

The dashboard labels what is measured. Candidate counts, preview contents, context size, exposure counts, config digests, and chain verification are local evidence. They do not prove that answers improved. The checked-in OpenClaw benchmark is reference evidence, not a measurement of your installation. A paid paired-replay comparison remains a separate explicit operation; AetnaMem never spends provider money merely because it was installed.

Read the Safe Switch guide for host-specific details and exact rollback boundaries.

What is product, beta, and research?

Maturity	Capabilities	How to treat them
Released core	Python/CLI/MCP memory, provenance and quarantine, correction, deletion receipts, audit search/trace	Supported public interfaces; still follow the documented host and identity boundaries
Beta, opt-in	Safe Switch, four-memory orchestration, semantic investigator sidecar, multimodal text observations, graph recall, Guarded Actions	Useful and tested, but adopt deliberately and verify in your environment
Research	Causal Memory Ledger / Memory Impact, 16-arm studies, learned memory-selection policy, EtD workflows	Reproducible machinery and exploratory evidence; not a general performance, clinical, or regulatory claim

This distinction is deliberate: “implemented” is not the same as “proven to improve every agent.”

Give OpenClaw four kinds of memory

You do not need to understand memory databases. Install AetnaMem and its OpenClaw plugin, run the wizard, and enable the configuration it creates:

python3 -m pip install --upgrade aetnamem
openclaw plugins install npm:openclaw-memory-aetnamem@latest --pin
aetnamem setup
openclaw aetnamem setup --single-user --subject you \
  --orchestrated --runtime-config ~/.aetnamem/runtime.json

The wizard walks through exactly ten short steps:

Explain what AetnaMem will add.
Choose a ready-made setup.
Name the person whose memories these are.
Name the agent.
Choose the private SQLite location.
Optionally point to OpenClaw SKILL.md files.
Choose where the configuration is saved.
Confirm the safety model.
Write and validate the configuration.
Print the exact OpenClaw and generic MCP commands.

For a scripted install with safe single-user defaults:

aetnamem setup --yes --preset starter --subject you \
  --agent openclaw-primary

Check the result before connecting an agent:

aetnamem runtime status --config ~/.aetnamem/runtime.json

Existing aetnamem mcp, Python Memory, and non-orchestrated OpenClaw setups continue to use the original semantic recall path. Four-memory orchestration is opt-in and falls back to legacy recall if the connected Python package does not offer the runtime tools.

The four memories in plain language

Imagine an agent completing a task:

What am I doing now?      → Working memory
What facts do I know?     → Semantic memory
What happened last time?  → Episodic memory
How should I do this?      → Procedural memory
                                  │
                                  ▼
                         One bounded context pack
                                  │
                                  ▼
                         OpenClaw or another agent

Memory	What it gives the agent	A simple example
Working	The current goal, constraints, progress, and unresolved items	“The report is drafted; upload is still pending.”
Semantic	Governed facts and preferences with provenance, correction, and deletion	“Production reports must be PDF.”
Episodic	Relevant prior attempts, successes, failures, and reviewed lessons	“The previous upload timed out after using the old endpoint.”
Procedural	The best versioned skill or procedure for the task	“Use the report-upload skill and verify its receipt.”

After the agent acts, AetnaMem can record the outcome reported by the caller. The generic CLI and MCP paths label this evidence caller_asserted; a trusted host integration must separately authenticate evidence before labeling it host_attested. Failed outcomes may create a quarantined lesson proposal for review. A skill can inform an action, but it never authorizes an action; optional Guarded Actions remain the approval boundary.

Ready-made configurations

The wizard creates normal JSON, but most users should start from a preset:

Preset	Best for	Behavior
`starter`	One person and one OpenClaw agent	Balanced local defaults
`private`	Minimal local context and conservative retrieval	Smaller budgets and stricter matching
`team`	Several cooperating agents behind a trusted host	Larger budgets and team-ready policy fields
`benchmark`	Reproducible comparisons	Generous deterministic budgets

List or generate presets without the wizard:

aetnamem runtime presets
aetnamem runtime init --preset private --subject you \
  --agent openclaw-primary --output ~/.aetnamem/runtime.json

The same runtime works with Grok, Claude, DeepSeek, OpenAI, Ollama, or another model because coordination happens through generic MCP:

aetnamem runtime mcp --config ~/.aetnamem/runtime.json

See the four-memory runtime guide for the configuration, lifecycle, lesson review, and generic MCP tools. The four-memory ablation benchmark shows the complete runtime beside semantic-only and each leave-one-plane-out variant without making a model-quality claim.

What can you do with this repository?

Think of AetnaMem as a governed continuity layer for AI systems. It helps an agent remember useful context, helps people understand where that context came from, and can carry evidence forward into reviewed decisions and approved changes. You can adopt one part without adopting the rest.

AI and agent use cases

What you want	What AetnaMem provides	Read more
Give an assistant durable memory	Remember, recall, correct, supersede, inspect, and forget user facts across sessions	Integration guide
Reduce repeated prompt context	A cache-aware context pack separates a stable persona from selective turn recall, applies hard budgets, and avoids repeating the same record in both blocks	0.4.1 release and measured result
Add memory to different agent frameworks	One Python, CLI, and MCP contract works independently of the model provider; build thin host adapters only when automatic lifecycle hooks are useful	Agent/MCP integration
Govern observations from multimodal agents	Store typed text observations with exact-byte artifact provenance, quarantine them, search/trace their influence, and delete every indexed derivative without storing media bytes	Multimodal observations
Add automatic memory to OpenClaw	The npm plugin injects bounded recall before a prompt and captures trusted user facts after a turn	OpenClaw setup
Add memory tools to Hermes	Hermes can discover AetnaMem over MCP; a context-engine wrapper can consume the same cache-aware context pack	Hermes guide
Use Claude, Grok, DeepSeek, OpenAI, Ollama, or another model	Memory policy and storage remain outside the model; swap the inference provider without replacing the memory engine	Grok/xAI guide and integration guide
See how AetnaMem helps Grok in a game	The Grok Memory Challenge demonstrates selective recall, correction, poisoned-context quarantine, deletion receipts, and audit verification in a short playable vault adventure	Play or watch the Grok memory game
Run a private local assistant	A desktop-style dashboard combines local chat, searchable memory, approvals, files, and live audit verification	Desktop guide
Stop webpages or tool output from silently becoming trusted memory	Classified untrusted content is quarantined and needs an explicit promotion step	Audit and trust model
Recall relationships, not only matching text	An optional governed graph adds bounded multi-hop retrieval with visible path evidence and direct-record fallback	Graph memory design
Investigate what an agent knew and did	Search by ordinary words, dates, sessions, event types, or outcomes; expand a match into a hash-chained memory-to-action timeline and export it as text or JSON	Audit search and trace guide
Search memory by meaning without changing agent recall	An optional exact-vector sidecar nominates candidates; canonical subject, status, and digest checks gate every result, and hybrid mode uses explainable rank fusion	Semantic investigation search
Audit who investigated memory	`--audit-access` writes query, filter, and result digests to a separate hash chain without changing the agent evidence under investigation	Audit search guide
Honor correction and deletion requests	New values supersede recognized old facts; forgetting purges live content and produces a deletion receipt	Auditing guide
Compare memory systems reproducibly	The repository includes unit gates, MemoryStackBench integration, and raw OpenClaw/DeepSeek token, cost, accuracy, and latency trials	Benchmark evidence

Agent governance and operational use cases

What you want	What AetnaMem provides	Read more
Require human approval before an agent changes something	Stage the exact operation, bind approval to its hash, recheck the target, execute, verify, and issue a receipt	Guarded actions
Prevent “approved one thing, executed another” failures	Plan mutation, expired approval, changed world state, or adapter drift stops execution	Flagship demo
Handle crashes around external effects honestly	Interrupted calls are fenced as uncertain or recovery-required instead of being blindly retried	Guarded actions
Join another agent runtime to the audit timeline	Import compatible operational journals as digest-only, explicitly unverified evidence without copying sensitive payloads	Integration guide
Build a governed tool gateway	Use the fail-closed MCP filter gate as a foundation for separating reads from direct writes	Guarantees and roadmap

Evidence-to-Decision and organizational use cases

What you want	What AetnaMem provides	Read more
Run a structured evidence-to-decision process	Versioned clinical and generic EtD templates turn evidence and contextual judgments into a recommendation	EtD profile
Let a panel collaborate and vote	Namespace-scoped cases, roles, conflicts of interest, recusal, frozen voter eligibility, hidden-until-close ballots, and deterministic outcomes	Decision workflow
Keep recommendation, approval, and authorization distinct	Panel adoption, institutional approval, resource sign-off, and change authorization are separate auditable transitions	Decision workflow
Connect an approved decision to implementation	A scoped authorization can be revalidated when an exact guarded action is staged and again before execution	Decision host integration
Host the workflow for many users	Embed the SDK behind your own authenticated application using SQLite for local/single-server work or PostgreSQL for multi-process deployment	Host integration and deployment
Produce verifiable governance evidence	Ed25519 or host-supplied KMS attestations sign identities and decision receipts; an offline verifier checks exported bundles	Decision host integration
Apply retention to sensitive decisions and conflicts	Decision and conflict-of-interest payloads can be logically purged under separate policies with signed purge receipts	Decision workflow
Prepare a hospital, policy team, or business unit pilot	A complete playground, acceptance protocol, evidence checklist, and independent methodology-review package are included	Pilot and review runbook

Why this is more than another memory cache

Most agent-memory integrations are discussed primarily as chat history, retrieval, or prompt caching. AetnaMem includes those practical concerns, but its distinctive value is the chain around them: source provenance, trust and quarantine, correction, deletion receipts, bounded context, independent audit verification, human approval, and an optional evidence-to-approved-change workflow. The same record can help an agent answer a question without being mistaken for authority to take an action.

That combination is useful when “the model remembered something” is not a sufficient operational explanation. It gives engineering teams a small local starting point, while giving managers, reviewers, and regulated organizations a path to inspect what informed a result and what was actually authorized. The measured OpenClaw/DeepSeek experiment also shows the practical side: cache-aware AetnaMem used 13.32% fewer prompt tokens and had 2.97% lower provider-reported cost than native MEMORY.md, with 20/20 answers in both arms. This is one controlled benchmark, not a universal saving; the raw trials and limitations are published for review.

The memory engine is usable today. The collaborative decision and EtD SDKs are experimental and need a real organizational pilot and external methodology review before clinical or regulatory claims. Multi-user products must also supply authentication, authorization, UI, networking, and deployment controls. See guarantee boundaries for the exact division of responsibility.

Try the local assistant today

A local assistant desktop app: governed chat backed by a lightweight local Ollama model, visible/searchable memory, approval-gated file writes in a safe workspace, an in-browser file viewer/editor, and a live-verified audit chain. One launcher does everything — installs Ollama if missing, pulls the qwen3:1.7b model on first run, starts the service, and opens the dashboard in your browser already signed in (tokens ride in the URL fragment and never leave the browser).

macOS

git clone https://github.com/aetna000/aetnamem.git && cd aetnamem
chmod +x scripts/macos/aetnamem-desktop.command
open scripts/macos/aetnamem-desktop.command

macOS additionally seals the memory database encrypted at rest on quit, keyed through the Keychain. Details: aetnamem Desktop for macOS.

Linux (Ubuntu/Debian and RHEL/Fedora/CentOS)

git clone https://github.com/aetna000/aetnamem.git && cd aetnamem
chmod +x scripts/linux/aetnamem-desktop.sh
./scripts/linux/aetnamem-desktop.sh

Needs python3 ≥ 3.10 (sudo apt-get install python3 / sudo dnf install python3) and curl. Ollama is installed via its official installer if missing. The database lives at ~/.local/share/aetnamem/memories.db (no at-rest sealing on Linux yet).

Windows 10/11

Double-click scripts\windows\aetnamem-desktop.bat, or run:

powershell -ExecutionPolicy Bypass -File scripts\windows\aetnamem-desktop.ps1

Needs Python 3.10+ (winget install Python.Python.3.12). Ollama is installed via winget if missing. The database lives at %LOCALAPPDATA%\aetnamem (no at-rest sealing on Windows yet).

Using the app

Chat — the assistant runs fully on your machine with the local model. Tell it things worth remembering; ask it to draft files.
Approvals tab — when the assistant wants to write a file, the action is staged, never executed. Review the plan and click Approve & run or Deny.
Files tab — everything in your workspace (~/Aetnamem Workspace on macOS/Windows, ~/aetnamem-workspace on Linux). Markdown renders in the browser; any text file can be edited and saved in place.
Memory tab — every remembered fact with status, provenance, and trust tier; search and filter, including quarantined and forgotten records.
Settings — switch provider (local Ollama, OpenAI, DeepSeek, or any OpenAI-compatible endpoint), run the system check, and review the Data & security panel showing exactly where your data lives.

Data location and backup

The desktop launchers use platform-native data locations: macOS stores a Keychain-protected sealed database under ~/Library/Application Support, Linux uses $XDG_DATA_HOME when set and otherwise ~/.local/share, and Windows uses %LOCALAPPDATA%. Workspace files are stored separately. Quit the service before copying SQLite data, and on macOS back up the encrypted database, its HMAC sidecar, and a recoverable copy of the Keychain key. See Data storage, backup, and restore for exact paths and restore instructions.

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.
Semantic search is optional and search-only. Its derived vector sidecar is plaintext SQLite, can be rebuilt, and never replaces canonical evidence. Every candidate is revalidated by subject, live status, and content digest. Local Ollama avoids content egress; a remote embedding endpoint receives indexed memory during build and each semantic query.
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. The standard-library independent verifier 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

pip install aetnamem
# or, from a checkout:
pip install -e .

The package installs two console commands:

aetnamem provides the memory CLI, the MCP server through aetnamem mcp, and guarded actions through aetnamem actions ….
aetnamem-service starts the local assistant dashboard. Run aetnamem-service --help for workspace, database, network, and browser options. The cross-platform desktop launchers above additionally bootstrap Ollama and the recommended lightweight model.

aetna000 is the organization namespace only; it is not installed as a product command.

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', ...}]

# Optional graph recall adds bounded multi-hop retrieval while preserving
# direct record fallback and the same governance rules.
m.recall("user-1", "What airport does my boss prefer?", use_graph=True)

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:

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 memories   ./memories.db --subject user-1 --all
aetnamem search     ./memories.db "preferred airport" --subject user-1
aetnamem trace      ./memories.db "preferred airport" --subject user-1 --output trace.json
aetnamem index build ./memories.db --subject user-1 --embedder ollama --model nomic-embed-text
aetnamem search     ./memories.db "departure location" --subject user-1 --mode hybrid
aetnamem index verify ./memories.db --subject user-1
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.

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:

aetnamem actions import-journal ./memories.db user-1 ./source-journal.db \
  --source-id production-agent

Imports are idempotent per source/transaction and are explicitly labeled unverified_operational_journal: importing external evidence does not upgrade its mutable status rows or claimed identities into aetnamem proof.

The HMAC approval key belongs in the human/reviewer process, not the agent-facing process. The --approver-label value is attribution; the shared key authenticates key possession, not that label. Likewise, CLI --authority-id/--authority-digest flags are only host-attested when a trusted host controls the staging command. The filesystem CLI is a reference vertical slice; the filter-only MCP gate is implemented, while automatic staging of arbitrary upstream MCP writes, Telegram review, additional execution providers, Firestore, and X adapters are tracked explicitly in the roadmap. Protocol and security details are in guarded-actions guide.

Collaborative decisions and EtD

The optional aetnamem.decisions Python SDK adds namespace-scoped, multi-principal decision cases, immutable evidence links, conflict/recusal handling, ballots, deterministic outcomes, recommendation adoption, institutional approvals, and scoped change authorization. aetnamem.etd provides versioned clinical and generic Evidence-to-Decision templates plus deterministic reporting.

from aetnamem.decisions import ActorContext, DecisionEngine
from aetnamem.etd import clinical_etd_template

engine = DecisionEngine("organization.db")
chair = ActorContext("hospital-7", "principal-42")  # host-authenticated values
case = engine.create_case(
    chair,
    title="Medication reconciliation",
    template=clinical_etd_template(),
    content={"question": "Should we introduce pharmacist reconciliation?"},
    idempotency_key="request-001",
)

The host supplies authentication, users, UI, HTTP/TLS, notifications, and organization-level authorization. The SDK enforces case membership, recusal, idempotency, concurrency, exact revision binding, and audit transitions. The standard installation includes both the SQLite and PostgreSQL backends plus Ed25519 identity/receipt verification; the provider-neutral KMS adapter accepts a host-supplied AWS KMS client. Decision and COI payloads have independently configurable logical retention and signed purge receipts. These features do not claim GRADE, clinical, or regulatory compliance. Run aetnamem-etd-playground against SQLite or PostgreSQL and verify its export with aetnamem-etd-verify.

See the decision workflow specification, EtD profile, and host integration guide. Organizations preparing real users should also use the pilot and methodology-review runbook.

Use from agents (MCP)

aetnamem mcp currently serves 17 memory verbs as MCP tools over stdio: newline-delimited JSON-RPC implemented with the standard library only and does not require an additional MCP framework. Defaults: database at ~/.aetnamem/memories.db (override with --db or $AETNAMEM_DB) and subject default (--subject), so single-user personal agents need no per-call subject wiring. It is not yet an action interception gateway and does not prevent an agent from calling other write tools directly.

Claude Code:

claude mcp add aetnamem -- aetnamem mcp

Claude Desktop / any host with JSON MCP config (OpenClaw's MCP bridge takes the same command + args shape):

{
  "mcpServers": {
    "aetnamem": {
      "command": "aetnamem",
      "args": ["mcp", "--db", "/home/you/.aetnamem/memories.db"]
    }
  }
}

The agent gets memory_remember, memory_observe, memory_recall, memory_recall_block (bounded prompt-injection block), memory_persona, memory_context_pack (host-neutral stable/dynamic context), memory_capture (auto-capture with digest-only assistant/tool logging), memory_list, memory_forget, memory_forget_artifact, memory_promote, memory_audit, memory_verify, and memory_graph_status, memory_graph_merges, memory_graph_history, and memory_log_action. Graph merge decisions are deliberately absent from MCP; they require the reviewer-authenticated dashboard/HTTP surface or explicit CLI use.

memory_observe accepts a typed text observation from an image, audio, video, or document extractor and always quarantines it. memory_forget_artifact purges all indexed AetnaMem derivatives of one exact-byte SHA-256 while explicitly leaving the host's original file alone. See the multimodal observation guide. These two tools ship in Python v0.5.2; the 15 earlier MCP contracts are unchanged.

subject_id is a storage scope chosen by the caller, not an authenticated tenant identity. Likewise, exposing memory_promote lets the agent request a promotion; use a trusted approval layer or omit that tool when promotion must be human-only.

Grok/xAI users: the Grok/xAI guide shows how to expose aetnamem as xAI function-calling tools today, with a local playground that lets Grok search, capture, forget, and audit memory while the engine keeps provenance and deletion receipts. xAI Remote MCP is the deployment path once the local stdio MCP server is exposed behind an HTTP/SSE gateway.

OpenClaw users: the native integration is a native plugin that adds automatic memory — auto-recall injection before every prompt and auto-capture after every turn — on top of the same engine and audit chain. The policy gates run server-side, so a hostile webpage summarized by the agent still cannot plant durable memory, deletion still returns receipts, and you can independently audit the same SQLite file with aetnamem verify or tools/verify_audit.py while the agent uses it. Full tool catalog, host configs, and troubleshooting: integration guide.

Install the native four-memory integration:

python3 -m pip install --upgrade aetnamem
openclaw plugins install npm:openclaw-memory-aetnamem@latest --pin
aetnamem setup
openclaw aetnamem setup --single-user --subject you \
  --orchestrated --runtime-config ~/.aetnamem/runtime.json

The setup applies conservative context budgets and enables the required conversation hooks. It does not rewrite MEMORY.md; verify recall before removing duplicated native memory. One plugin instance currently has one fixed subject and must not be shared between authenticated users.

By default, each prompt receives no more than three matching memories within a 1,200-character recall block plus a 600-character persona block, and unrelated queries receive no recall block.

In the checked-in three-arm OpenClaw 2026.7.1-2 + DeepSeek V4 Flash follow-up, 20 fresh-session tasks per arm used 596,581 prompt tokens with a 19,489-character native MEMORY.md, 521,858 with the current AetnaMem layout, and 517,118 with cache-aware AetnaMem. The optimized arm therefore used 79,463 fewer prompt tokens (13.320%) and cost 2.968% less than native, with 20/20 correct answers in every arm and 20/20 target retrieval in both AetnaMem arms. It did not increase absolute cache reads over current AetnaMem; its additional 0.908% token and 1.190% cost improvement came from the optimized bundle's smaller model-visible surface. An earlier run produced a 0.674% cost increase under a different cache mix, so neither bill is a universal claim. The raw trials, protocol, limitations, and reproduction command are checked in; the plugin README also includes the two-minute recall demo.

Integrating with other agent frameworks

The rule is: MCP first, native adapter only when it adds lifecycle hooks. Do not fork the memory semantics per host. aetnamem should stay the auditable engine; framework integrations should be thin wrappers that call the same MCP/Python verbs and preserve the same audit trail.

For any MCP-capable host, start with:

aetnamem mcp --db ~/.aetnamem/memories.db --subject you

Then configure the host to expose the memory_* tools. This is the right first path for Hermes, Claude Desktop, Claude Code, and any framework that can launch a stdio MCP server. The dedicated Hermes guide includes the exact commands and explains the boundary between tool-based memory and automatic prompt injection.

For an automatic adapter, call one provider-neutral operation before the model invocation:

pack = memory.build_context_pack("user-42", current_query)
system_prefix += "\n" + pack["stable_context"]
current_turn += "\n" + pack["dynamic_context"]

The same contract is available as CLI aetnamem context-pack and MCP tool memory_context_pack. The stable block is deterministic and suitable for a stable system-prefix position; the dynamic block is selective and belongs near the current turn. Records already present in the stable block are not repeated in the dynamic block. This layout can preserve provider prefix-cache reuse while keeping the total prompt bounded, but it cannot guarantee cache hits: cache boundaries, minimum cacheable lengths, TTLs, and billing remain provider and host behavior.

Build a native adapter only when the framework gives useful hooks:

hook point	aetnamem call	purpose
before prompt/context build	`memory_prepare_turn` or legacy `memory_context_pack`	inject bounded, audited stable + dynamic context
after user/agent turn	`memory_record_outcome` plus `memory_capture`	close the learning loop and capture user facts
before history write	strip injected memory blocks	prevent recall feedback loops
explicit agent tools	`memory_recall`, `memory_forget`, `memory_audit`, `memory_verify`	search, request logical purge, and verify recorded behavior

Native adapters should pass the host's session_id and turn_id whenever available, so memory reads, writes, tool calls, forgets, and user-visible responses line up in one audit timeline.

Priority targets:

framework / host	first integration	native adapter shape
OpenClaw	implemented native plugin	hook-based auto-recall/capture
Hermes	implemented MCP setup guide	context-engine/plugin wrapper consuming `memory_context_pack`
LangGraph	Python helper node/store	recall node before model call, capture node after turn
OpenAI Agents SDK	tools + runner/session wrapper	pre-run context builder and post-run capture
CrewAI	external memory tools	memory adapter if its memory API can preserve receipts/audit IDs
Microsoft Agent Framework / Semantic Kernel	plugin/tools	context provider plus action logging
LlamaIndex / Haystack	tool/component wrapper	long-term memory component, not replacement for short-term chat state

The adapter directory should stay organized by host:

integrations/
  openclaw/
  hermes/
  langgraph/
  openai-agents/
  crewai/
  microsoft-agent-framework/
  llamaindex/
  haystack/

Each adapter should document the same guarantees: untrusted content stays quarantined, deletion returns receipts, recall injection is bounded and audited, and the SQLite database can still be verified externally with aetnamem verify or tools/verify_audit.py.

Compliance posture

The architecture separates mutable content tables from an engine-append-only, hash-chained audit table. This can support accountability, access, rectification, and deletion workflows, but it is not compliance certification or legal advice. forget() performs a logical purge in the live database; it does not by itself sanitize SQLite free pages, WAL files, backups, exports, or external replicas. Checkpoint placement, retention, secure erasure, access control, identity, lawful basis, and jurisdiction-specific requirements remain deployment responsibilities. See the audit-log specification for the precise integrity threat model.

Current semantic-memory storage pipeline

These L0–L3 labels describe the internal pipeline used by the semantic provider. They are not alternatives to the four runtime memory types above.

L0 — episodes: raw turns, append-only, purged by deletion.
L1 — records: extracted facts with provenance.
L2 — scenes: deterministic per-session view (aetnamem scenes).
L3 — persona: live-derived snapshot of active facts (aetnamem persona, MCP memory_persona) — no cached persona is stored; each generated snapshot carries its source record IDs.
Derived proposals: external LLM/batch jobs submit candidates via aetnamem propose / Memory.propose_facts(); they land quarantined with mandatory evidence links and only activate through promote().

How recall works

Recall has top-k semantics. SQLite FTS5 selects a bounded candidate set (200 by default), trust and recency priors rank it, and the best limit records are returned. Quarantined, superseded, and tombstoned records are never candidates. Retrieval events record the algorithm, cap, candidate count, score inputs, and a bounded ledger (the first 50 plus every returned result). A versioned digest binds the selected retrieval fields to the audit chain. Pass min_score= to drop weak matches.

Graph recall is opt-in with use_graph=True, CLI --graph, or service AETNAMEM_GRAPH_RECALL=1. It extracts a conservative entity/edge index from governed records, seeds it with FTS5, spreads through at most two bounded hops, and blends the result with direct record recall. Returned graph hits include their path evidence. The index inherits quarantine, promotion, supersession, and forgetting; it can be recreated at any time:

aetnamem graph-backfill ./memories.db user-1
aetnamem recall ./memories.db user-1 "What airport does my boss prefer?" --graph
aetnamem graph-consolidate ./memories.db user-1
aetnamem graph-merges ./memories.db user-1 --status pending
aetnamem graph-inspect ./memories.db user-1

What the released core is and is not

Semantic extraction is deterministic (generic sentence patterns: "my X is Y", "use Y as my X", "remember that …", "I avoid …") so that policy failures are debuggable, not probabilistic. The embedded four-memory runtime, setup presets, local Python API, CLI, MCP server, deterministic consolidation, persona snapshots, scenes, checkpoints, and independent memory verifier are implemented. An optional, deterministic graph index provides bounded multi-hop recall with path evidence and direct-record fallback. Guarded Actions additionally ships an action ledger, exact-plan shared-key approvals, filesystem reference adapter, recovery fencing, external journal import, and independent action verifier. A fail-closed, filter-only MCP gate is implemented; automatic conversion of arbitrary upstream writes into staged actions, authenticated host identity, encrypted payloads, LLM-backed graph extraction, public HTTP deployments, remote memory-plane transport, and additional storage backends remain roadmap work — see the roadmap. The policy gates in aetnamem/core/policy.py are the product; nothing in the engine may reference the vocabulary of a benchmark scenario.

Documentation

Adoption path

Safe Switch guide — Beta: exact trial commands, host behavior, evidence meaning, activation, stop, and rollback boundaries.
Agent skills guide — Beta: conversational governed-memory, audit, and Safe Switch workflows.
OpenClaw setup and Hermes guide: host-specific installation and identity boundaries.
Integration guide: complete CLI and MCP reference.
0.6.1 release notes: package versions, compatibility, validation, and known limits.

Released memory and audit surfaces

Current capability status: the canonical released, beta, research, and planned boundary.
Auditing guide and audit search/trace: investigate memory without knowing an internal ID and export text or JSON evidence.
Multimodal observations: governed text observations with exact-artifact provenance; AetnaMem does not store or understand media bytes.
Semantic investigator search — opt-in: local or configured embeddings for human investigation; default agent recall remains lexical.
Data storage and backup and audit-log specification: persistence, recovery, replay, and verification boundaries.

Beta and advanced surfaces

Four-memory runtime — opt-in: working, semantic, episodic, and procedural context orchestration.
Graph memory — opt-in: derived, rebuildable relationship index with path evidence.
Guarded Actions — Beta: approval and action evidence; not a universal MCP write interceptor.
macOS desktop — Beta: local desktop workflow with platform-specific Keychain-backed sealing.

Research and experimental work

These components are checked in so their methods and evidence can be inspected. They are not part of the Safe Switch adoption claim:

Memory Impact Lab — Research: balanced interventions, signed host verification, estimators, and a held-out policy gate. The 100-run Grok pilot is exploratory and incomplete; no general causal performance claim ships.
Collaborative decisions / EtD — Research: a generic evidence-to-decision workflow, not a clinical or regulatory product claim.
Governed outbound channels and inference engineering memory — Proposal: specifications, not implemented product surfaces.
Architecture plan and roadmap: future work, not release documentation.

Benchmark

Development is gated on MemoryStackBench's seven_sins_v0_1 suite (webpage poisoning, retention after deletion, missing provenance, stale temporal updates, overgeneralization). Current score: 33/33, with unit tests covering the same gates on non-benchmark vocabulary to keep the score honest.

git clone https://github.com/aetna000/MemoryStackBench.git
cd MemoryStackBench
cp /path/to/aetnamem/bench/adapters/aetnamem.py memorybench/adapters/aetnamem.py
cp /path/to/aetnamem/bench/targets/aetnamem.yaml targets/aetnamem.yaml
PYTHONPATH=/path/to/aetnamem:$PWD \
python -m memorybench.cli run \
  --target targets/aetnamem.yaml \
  --suite suites/seven_sins_v0_1 \
  --out runs/aetnamem-local

License

AGPL-3.0 (see the license). Anyone may use aetnamem, including commercially, but derivative works — including software that serves aetnamem over a network — must be released under the same terms.

Name		Name	Last commit message	Last commit date
Latest commit History 57 Commits
.claude-plugin		.claude-plugin
.claude		.claude
.codex-plugin		.codex-plugin
.github/workflows		.github/workflows
aetnamem		aetnamem
bench		bench
docs		docs
examples		examples
integrations		integrations
paper		paper
scripts		scripts
skills		skills
tests		tests
tools		tools
.gitignore		.gitignore
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
TODO.md		TODO.md
plan.md		plan.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation