AtMem

AtMem is a host-neutral Agent Black Box and reversible memory control plane.

It gives agent runtimes one governed memory source and one tamper-evident record of what the host observed: memory considered and injected, model boundaries, tool requests and completions, turn termination, and linked external outcome receipts. OpenClaw is the first fully automated adapter. Other runtimes connect through the generic control MCP contract.

AtMem starts in shadow mode. It records memory candidates and flight evidence but never authorizes memory injection. An operator can review the evidence, activate AtMem explicitly, and return to shadow at any time. The OpenClaw adapter additionally copies native memory, freezes it during takeover, and restores it exactly.

Install

python -m pip install atmem==2.1.0
atmem --version

AtMem requires Python 3.10 or newer. The canonical engine has no mandatory third-party Python dependencies. Semantic vector search is optional:

python -m pip install 'atmem[semantic]==2.1.0'

Choose an integration

Runtime	Start command	What AtMem supplies	What the runtime supplies
Any custom agent, CLI, or SaaS worker	atmem control shadow --host generic	memory governance, shadow/active policy, flight store, verification, audit, CLI, MCP, dashboard	authenticated identity and truthful model/tool/context hooks
OpenClaw	atmem openclaw install	all generic capabilities plus automated native-memory copy, hook installation, gateway checks, activation, and restore	the OpenClaw runtime
Memory engine only	atmem mcp or Python Memory	canonical memory, recall, provenance, lifecycle, deletion, and audit	all agent-flight and prompt-boundary integration

The dashboard is a view over the same local state used by CLI and MCP. It is not a separate source of truth.

Connect any agent runtime

Start a generic control plane against the same canonical database used by the memory MCP server:

atmem control shadow --host generic --memory-db ~/.atmem/memories.db
atmem control mcp

The host MCP is deliberately non-administrative. It exposes capture, prepare, context-exposure confirmation, flight-event recording, adapter sync/status, and cannot approve memory, acknowledge findings, or activate AtMem. Approving a generic shadow candidate writes the reviewed fact into the bound canonical database, so atmem mcp, CLI, operator MCP, and dashboard see the same active record and record ID.

For every turn, the runtime must:

1. assign stable agent, workspace, session, run, and turn identifiers;
2. capture authenticated user memory candidates;
3. call control_prepare before the model request;
4. inject the returned context only when inject is exactly true;
5. confirm the exact exposure after constructing the model request;
6. record model input/output, each tool request/completion, and turn end;
7. bind an outcome receipt when an independent system proves a real-world result.

See the generic adapter contract for tool names, multi-agent scopes, event requirements, and trust boundaries.

Operate AtMem

The operator CLI, operator MCP, and loopback dashboard call the same manager operations:

# Read state and verify integrity.
atmem control status
atmem control verify
atmem control memory-sync
atmem control memory-status

# Inspect and decide memory.
atmem control memory-reviews
atmem control memory-search "preferred editor"
atmem control memory-record RECORD_ID
atmem control memory-review RECORD_ID approve
atmem control memory-audit --since 2026-08-15T00:00:00Z
atmem control memory-audit --format ndjson --output audit.ndjson

# Inspect, export, and acknowledge agent flights.
atmem blackbox runs --limit 50
atmem blackbox story RUN_ID
atmem blackbox verify RUN_ID
atmem blackbox export RUN_ID --format json --output flight.json
atmem blackbox ack RUN_ID ATTENTION_CODE

# Explicit influence control.
atmem control activate
atmem control restore

To expose those same administrative operations to a trusted local operator client, run:

atmem control operator-mcp

Do not expose the operator MCP to an agent or untrusted network. It can approve or reject memory, acknowledge findings, configure generic agent scopes, export evidence, activate AtMem, and return it to shadow.

Dashboard

atmem dashboard daemon start   # http://127.0.0.1:8766/
atmem dashboard daemon open
atmem dashboard daemon status
atmem dashboard daemon restart
atmem dashboard daemon stop
atmem dashboard daemon remove  # service metadata only; memory remains

The dashboard shows a concise action timeline first. A flight node is green when no active finding remains, amber when it needs review, and red when the observed run failed or its evidence is incomplete. Selecting a node reveals the request/reply when a protected local adapter reader can supply them, memory used, tools and websites, model/provider, tokens, latency, risks, blocking reason, outcome evidence, hashes, and the full timeline. Findings can be acknowledged without deleting or rewriting evidence.

Memory search, review, record history, audit filters, downloads, agent topology, verification, activation, and return-to-shadow use the same operations as the CLI. The canonical dashboard API is /api/memory/*; legacy /api/mirror/* paths remain aliases for older local clients.

The dashboard binds only to loopback, has no login, checks origin and CSRF on mutations, and should not be placed behind a public reverse proxy.

Multiple agents and workspaces

Generic runtimes register persistent agents explicitly:

[
  {"agent_id":"main","name":"Main","workspace":"shared","is_default":true},
  {"agent_id":"research","name":"Research","workspace":"shared"},
  {"agent_id":"private","workspace":"private","parent_workspace":"shared"}
]

atmem control configure-agents agents.json
atmem control agents

Agents in the same workspace share one memory subject. Different workspaces are isolated. A parent relationship records nesting but does not merge memory. Every capture, prepare, and flight event can carry agent, workspace, and subject identity. OpenClaw topology is discovered from OpenClaw configuration and bound to the verified memory mirror; generic topology is explicit and local. Temporary child runs may reuse a registered workspace and subject. They do not create a new durable scope implicitly; register them when they need persistent identity or isolated memory.

Install and migrate OpenClaw

Do not install the npm bridge separately. The Python installer owns the version pair and validates the result:

atmem openclaw install
atmem control status
atmem control verify
atmem dashboard daemon start

# Activate only after review.
atmem control activate

# Test restoration without changing live state, then restore when required.
atmem control restore --drill
atmem control restore

atmem openclaw install installs the pinned npm bridge, binds the exact Python executable, copies MEMORY.md and memory/*.md across detected persistent agent workspaces, starts shadow synchronization, restarts the gateway, and verifies the loaded integration. Rerunning it refreshes an existing shadow migration without replacing the original restore snapshot.

See OpenClaw setup, the OpenClaw control-plane guarantees, and the OpenClaw bridge package.

Agent Black Box evidence

The runtime can record these content-minimizing event types:

Boundary	Retained evidence
turn input	digest, size, counts, correlation IDs
context disposition	injected, empty, withheld, failed, or not applicable; receipt and record IDs
model input/output	provider, model, digests, latency, tokens, bounded usage metadata
tool request/completion	tool name, argument/result digests, safe key names, duration, error category
turn end	success, failure, cancellation, or incomplete state
external outcome	opaque receipt ID, digest, status, and safe metadata supplied by a verifier

A verified flight proves retained chain integrity and closure of the boundaries the runtime reported. It does not prove that a hook was truthful, semantically validate an answer, or prove email delivery, payment settlement, or a database change without independent system-of-record evidence.

Raw prompts, replies, tool parameters, and tool results are not stored in the Black Box. SHA-256 digests are fingerprints, not encryption or anonymization. See the Agent Black Box guide.

Use the memory engine directly

from atmem import Memory

memory = Memory("memories.db")
memory.remember("user-1", "My preferred editor is Vim.", session_id="s1")
records = memory.recall("user-1", "preferred editor", limit=5)
verification = memory.verify("user-1")
memory.close()

Or run the model-agnostic memory MCP server:

atmem mcp --db ~/.atmem/memories.db --subject user-1

MCP tools: memory_remember, memory_observe, memory_recall, memory_get_record, memory_get_source, memory_recall_block, memory_persona, memory_context_pack, memory_capture, memory_list, memory_forget, memory_forget_artifact, memory_promote, memory_audit, memory_verify, memory_graph_status, memory_graph_merges, memory_graph_history, and memory_log_action.

See the integration guide, audit search, semantic search, and multimodal observations.

Data, privacy, and recovery

• Canonical memory, provenance, lifecycle state, and audit evidence use SQLite.
• Semantic vectors are optional derived indexes and are checked against canonical records.
• External media bytes remain host-controlled; AtMem stores a typed text observation, byte digest, model identity, and host reference.
• External observations remain quarantined until an operator approves them.
• Rejected, superseded, or tombstoned memory is excluded from ordinary search and recall.
• Forget cascades through canonical, graph, media, and vector-derived state and returns a receipt.
• Generic return-to-shadow stops future context injection but does not undo past model outputs or tool actions.
• OpenClaw restore verifies and reinstates the preserved native configuration and files; it also cannot undo past outputs or external actions.

For backups, permissions, and disaster recovery, read data storage and backup and the auditing guide. For a custom product deployment, read Using AtMem in a SaaS product. AtMem does not ship a hosted multi-tenant control service; your SaaS remains responsible for tenant authentication, authorization, storage isolation, encryption, retention, and system-of-record verification.

Documentation map

• Current implementation status
• Generic runtime adapter
• Agent Black Box
• Integration guide
• OpenClaw setup
• OpenClaw control-plane guarantees
• SaaS integration and go-live checklist
• Audit log specification
• Audit investigation
• Storage, backup, and recovery

Development verification

python -m pip install -e '.[dev]'
pytest -q

cd integrations/openclaw
npm ci
npm run typecheck
npm test
npm run smoke

Current repository metadata is version 2.1.0. Python and npm release versions are intentionally kept equal because the OpenClaw installer pins the matching bridge.

Licensed under AGPL-3.0-only.