AtMem: Governed Memory and a Black Box for AI Agents

AtMem is a host neutral Agent Black Box and reversible memory control plane. It gives AI agents governed memory across sessions while recording what the host observed during each run.

The current stable release is AtMem 2.2.6. It supports OpenClaw, Pydantic AI, LangChain and LangGraph, MCP, and custom agent runtimes. The default store is local SQLite. No external model API is required for the basic memory engine.

View the repository · Current implementation status · Version 2.2.6 release notes

The problem AtMem addresses

Agent memory is usually treated as retrieval: save text, find similar text, and place it in the next prompt. That leaves several operational questions unanswered.

Where did a remembered claim come from? Was it supplied by the user, inferred by a model, copied from a webpage, or returned by a tool? Was an old fact corrected or silently overwritten? Did retrieved memory actually enter the model request? Can an operator remove it and verify the result? If a 40 minute agent run fails, can someone reconstruct the sequence without storing every prompt, response, and tool payload?

AtMem separates these concerns:

Authority stays in AtMem

AtBot is installed automatically with AtMem. It is a private intelligence companion, not a second memory authority. AtBot may interpret a user statement, propose a memory update, expand a query, or rerank eligible candidates. AtMem alone validates, authorizes, stores, scopes, injects, corrects, and deletes canonical memory.

This makes model output advisory. A model cannot admit its own proposal merely by sounding confident. AtMem checks the source evidence, authority scope, lifecycle state, review policy, and current record generation before anything changes.

If AtBot or its selected model is unavailable, AtMem continues with deterministic local extraction and conservative local ranking. Memory governance does not depend on a hosted model.

How memory enters the system

Every observation produces one typed outcome:

A proposal must cite an exact source span. The evidence includes the source identifier, the digest of the complete source, byte offsets, and a digest of the cited excerpt. AtMem recomputes these values before admission. A claim that cannot be reproduced from its cited source is refused.

Memory classes are explicit. Durable facts, temporary state, episodes, procedures, and non memory content are not treated as interchangeable. Temporary work progress should not silently become a permanent personal fact.

Low confidence, sensitive, ambiguous, destructive, or untrusted proposals wait for review. Web content cannot create an unreviewed memory mutation. Reviewers may approve, edit and approve, or reject. The decision, actor, reason, time, and resulting record identifiers enter the audit history.

Corrections preserve lineage. A new record becomes active, the previous record becomes superseded, and AtMem retains the relation between them. It does not rewrite history to make the newer statement appear as if it had always been known.

Read the extraction and updating contract

Governed retrieval

AtMem separates candidate discovery from permission to inject. Lexical matching, typo recovery, fact keys, graph paths, semantic similarity, trust, recency, and AtBot ranking may help find or order candidates. None can bypass lifecycle, scope, or trust checks.

The shared retrieval decision classifies the original query:

Query expansion can generate candidates, but only the original query can establish support. Trust and recency can reorder relevant records, but they cannot create relevance. AtMem reopens and revalidates selected record identifiers immediately before constructing a byte stable context package.

The base installation creates a local vector sidecar for deterministic diagnostic hashing and index plumbing. Hashing vectors cannot authorize injection. An optional production semantic profile binds the provider, exact model revision or digest, dimensions, normalization, prefixes, preprocessing version, licence metadata, policy digest, and vector epoch. An incompatible or stale epoch fails closed and can be rebuilt without changing canonical memory.

For governed MCP use, memory_recall_decision is the injection authority. The older memory_recall tool remains a diagnostic search interface.

Retrieval quality · Semantic search

Exact context delivery

Retrieval is not proof of influence. An adapter must place authorized context at the actual model boundary and confirm the exact exposure. AtMem records the disposition as injected, empty, withheld, failed, or not applicable, together with its receipt, record identifiers, and placement digest.

This proves which governed bytes the adapter reported as delivered. It does not prove that the model relied on those bytes or that they improved the answer.

AtMem starts integrations in shadow mode. It captures candidates, prepares retrieval decisions, and records evidence, but cannot change model context. An operator reviews the behaviour before enabling active delivery.

atmem dashboard
atmem control status
atmem control activate
atmem control verify

The operator can return to shadow mode. For OpenClaw, AtMem also copies native memory, freezes it during active takeover, and retains exact restore material.

Agent Black Box

The Agent Black Box records a content minimizing, tamper evident timeline from lifecycle hooks supplied by the host. OpenClaw installs these hooks automatically. Custom runtimes can emit the same contract through the control MCP service.

Raw prompts, responses, tool arguments, and tool results are not stored in the Black Box by default. Digests are fingerprints rather than encryption. Guessable values may still be tested against their hashes, so evidence databases and exports should be treated as sensitive records.

atmem blackbox runs --limit 20
atmem blackbox story RUN_ID
atmem blackbox verify RUN_ID
atmem blackbox export RUN_ID --format json --output flight.json

A verified flight means the retained chain is intact and the reported lifecycle boundaries close correctly. Each observed tool request must have a correlated completion, the run must terminate, and the model and context evidence required by the adapter contract must be present.

It does not prove that an email was delivered, a booking completed, or an answer was factually correct. Those claims require evidence from the relevant system of record.

Read the Agent Black Box guide

Governed Task State

Long term memory answers what the system knows across sessions. Governed Task State records what an agent is doing now. It is a separate, revisioned authority plane and is disabled by default.

A task contains a goal, lifecycle, current revision, constraints, sources to inspect, and actionable items. Each item has a status, dependencies, blockers, evidence, and an assurance class. Every state is an immutable revision. Updates are typed proposals against an exact base revision.

Only AtMem can commit a task revision. AtBot and the host agent may propose changes. A stale proposal returns a conflict and changes nothing. Reusing the same idempotency key replays the original decision. Using that key with different content is rejected.

Task completion can be blocked until required items or evidence are present. A host reported tool success remains host reported. It is not promoted to independent verification unless a registered verifier supplies that evidence.

atmem task enable ~/.atmem/memories.db \
  --subject user1 --agent agent1 --workspace workspace1

atmem task start ~/.atmem/memories.db \
  --task-id release007 \
  --goal "Ship the governed task state milestone" \
  --actor operator@example.com \
  --required-item verify="Run release verification" \
  --subject user1 --agent agent1 --workspace workspace1

AtMem never guesses the active task from prompt text. Pydantic AI and LangGraph can supply an exact task identifier per run. OpenClaw uses an operator authorized conversation binding.

Read the Governed Task State guide

Optional delegated context authority

Native AtMem retrieval is the default. Delegated mode is for deployments where another compatible local provider must remain the sole context decision authority for selected users, agents, and workspaces.

The registration must match the complete user, agent, and workspace scope. A matching provider returns one signed inject or withhold decision. AtMem authenticates the request with a per installation HMAC credential, verifies the provider result with Ed25519, checks expiry and replay protection, delivers accepted bytes once, and records authorization separately from delivery.

If the provider fails, AtMem withholds context by default. Native fallback occurs only when the operator explicitly registered that policy. The evidence labels it as an AtMem fallback rather than provider authorized context.

The current provider transport is local and loopback oriented. It is not a hosted tenant authentication boundary. HMAC proves possession of the request credential. It does not isolate hostile processes running as the same operating system user.

atmem delegated status
atmem delegated self-test
atmem delegated enable context-provider:local
atmem delegated doctor

Optional provider adapters are available for Mem0, LangGraph, and Pydantic AI. They do not alter native AtMem authority unless delegation is explicitly registered and enabled.

Delegated context guide · Provider adapters

Framework integrations

OpenClaw is the first fully managed integration. The installer discovers agents and workspaces, installs the matching bridge, starts in shadow mode, restarts the gateway, and verifies the connection.

python -m pip install --upgrade atmem==2.2.6
atmem openclaw install
atmem control verify

Pydantic AI uses a native capability. LangChain and LangGraph use middleware around their model and tool lifecycle. Both preserve the framework's own messages, checkpoints, tools, workflow state, and model selection.

python -m pip install 'atmem[pydantic-ai]==2.2.6'
python -m pip install 'atmem[langgraph]==2.2.6'
atmem control shadow --host generic --memory-db ~/.atmem/memories.db

Additional callback adapters are packaged as optional extras for OpenAI Agents SDK, Microsoft Agent Framework, Google ADK, smolagents, and CrewAI. Custom runtimes can use the generic control MCP contract or the versioned HTTP clients.

Identity is part of the security boundary. Subject, agent, workspace, and authenticated application user must come from the host. Prompt text, model output, session identifiers, and tool arguments do not grant access to a memory scope.

Framework adapters · Generic adapter contract

Multimodal observations

AtMem can govern observations derived from images, audio, video, files, and tool artifacts. Original bytes remain with the host by default. AtMem stores scoped references, exact digests, provenance, consent state, processing receipts, and derived observations.

A processor receives only authorized bounded bytes. Hosted processing requires explicit egress approval. Its receipt records whether processing was local or hosted, what redaction was applied, the model and revision, the configuration digest, and the evidence region.

An observation is a model inference with confidence and provenance. It is not ground truth. Consent and scope are checked again before storage, indexing, retrieval, and delivery. Revocation prevents late processor output from becoming active and tombstones controlled observations and indexes.

Read the multimodal observation contract

Storage, audit, and deletion

Canonical memory is stored in SQLite by default. Each persistent database has a disposable vector sidecar at <memory-db>.vectors.db. The sidecar can be rebuilt and is never the source of truth.

Memory, lifecycle, review, retrieval, delivery, and flight events are connected through hash chained evidence. The built in verifier and the independent verifier check the retained chain and receipts.

atmem verify ~/.atmem/memories.db --incremental
atmem audit ~/.atmem/memories.db user1
python tools/verify_audit.py ~/.atmem/memories.db --subject user1

Hash chaining detects changes relative to retained trusted evidence. It does not authenticate a claimed actor on its own, provide trusted time, or prevent a database owner from replacing the database and every unanchored checkpoint.

Deletion removes governed live content and derived indexes and returns evidence of the operation. It does not erase independent backups, provider logs, host controlled media, SQLite free pages, or external replicas. Deployments must define backup expiry, secure erasure, access control, retention, and external checkpoint handling.

AtMem also defines a neutral line delimited JSON archive for migration. Imports require explicit scope, start with a dry run, preserve supported source metadata, and do not trust imported vectors or vendor graphs as canonical facts.

Auditing guide · Storage guide · Interchange guide

Installation

AtMem requires Python 3.10 through 3.13. The stable package pins the compatible AtBot companion automatically.

python -m pip install --upgrade atmem==2.2.6
atmem atbot setup
atmem atbot doctor
atmem dashboard

For an existing OpenClaw installation:

python -m pip install --upgrade atmem==2.2.6
atmem openclaw upgrade
atmem control verify

The dashboard binds to loopback, has no hosted login layer, and should not be placed behind a public reverse proxy. A public service must add TLS, tenant authentication and isolation, credential rotation, quotas, encrypted canonical storage, retention controls, and verified backup restoration.

Verification and measured limits

The offline release gate contains 16 isolated cases covering extraction, contradiction handling, retrieval, withholding, injection safety, privacy, poisoning resistance, and fallback.

atmem benchmark run --output benchmark.json

Safety failures block the gate. Other quality metrics cannot fall below checked baselines. Optional model profiles report skipped when their required runtime is unavailable. A skipped profile is not counted as a pass.

The checked retrieval gate uses separate calibration and held out fixtures with 20 answerable paraphrases and 20 unrelated questions. Its release threshold is MRR at 5 of 1.000 and no answer accuracy of 1.000. This is deterministic release evidence for the checked data, not a claim of universal retrieval accuracy.

The repository also contains a 12 question LongMemEval S comparison with Mem0 OSS 2.0.19. Both systems reached evidence session recall at 5 of 1.000. Mem0 recorded the better evidence session MRR at 5, 1.000 versus 0.958, and lower measured search latency on that run. AtMem reports these metrics separately rather than combining them into a weighted score.

Read the benchmark guide

Current claim boundary

AtMem can verify canonical state, derived index bindings, retained audit chains, memory decisions, exact context receipts, and the closure of events reported by a runtime adapter.

It cannot prove that a generic host reported every event truthfully. It cannot prove that a model used delivered memory, that an answer was correct, or that an external action succeeded without independent system evidence. The current dashboard and managed provider transport are local tools rather than a hosted multi tenant security boundary.

These limits are part of the design. AtMem makes the available evidence explicit, links it to authority decisions, and refuses to turn missing evidence into a stronger claim.

Licence

AtMem uses the Apache License 2.0. It permits commercial use, internal modification, and distribution under the licence terms. It does not require private service modifications to be published merely because the software is used over a network.