Atmem

AtMem

AtMem 2.3.10 adds opt-in, bounded source-evidence discovery. Read the integration guide and stable promotion qualification. Ordinary memory and Code defaults remain unchanged; discovery is explicitly enabled by the host.

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

AtMem 2.3.9 adds optional AtMem Code: share project memory across coding agents, explore source-backed structure, and inspect recorded coding experience. Start with the simple Code guide, release note, or public comparison results. Ordinary AtMem memory remains available without enabling Code. Earlier benchmarks retain their original tested-version provenance.

Created and maintained by Javad Taghia (@JavadTaghia).

Install AtMem once and give OpenClaw, Pydantic AI, LangChain/LangGraph, or a custom agent governed long-term memory. AtBot is installed automatically as AtMem's private intelligence companion: AtBot proposes and ranks; AtMem alone authorizes, stores, scopes, injects, corrects, and deletes memory.

Start here

1. Install AtMem and choose memory intelligence

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

That one Python installation includes the pinned atmem-atbot package and an always-present local vector index. Do not install AtBot separately. During atmem atbot setup, choose local Ollama, a local OpenAI-compatible model, a hosted provider, or the safe deterministic fallback. API keys stay in environment variables; AtMem does not save them.

For encrypted local households, install the SQLCipher extra and verify the runtime before migration:

# Ubuntu/Debian first: sudo apt-get install libsqlcipher-dev build-essential
# Then install with the system SQLCipher headers and library:
CFLAGS="-I/usr/include/sqlcipher" LDFLAGS="-lsqlcipher" \
  python -m pip install --upgrade 'atmem[encrypted]'

# macOS and Windows can install the extra directly:
python -m pip install --upgrade 'atmem[encrypted]'
atmem household status ~/.atmem/memories.db
atmem household migrate ~/.atmem/memories.db

Stop every writer before migration. AtMem validates SQLite integrity, SQLCipher page integrity and per-table row counts before the atomic cutover; see SaaS integration and recovery.

In 2.3.10, pip install atmem installs the Python packages only; pip does not run a post-install downloader. On the first atmem init, if compatible Bun is not already installed, AtMem clearly announces and downloads its pinned official Bun runtime for AtFlows, verifies the archive against a release-pinned SHA-256, and stores it under ~/.atmem/runtime/bun. It does not require administrator rights or change the global PATH. A compatible system Bun is reused instead. AtFlows may then use network access once to prepare its separately packaged web runtime. Ordinary AtMem memory operations do not require Bun or AtFlows.

2. Connect your agent

OpenClaw — fully managed

atmem openclaw install
atmem control verify

AtMem installs the matching npm bridge, discovers OpenClaw agents and workspaces, starts in safe shadow mode, restarts the gateway, and verifies the connection. It also offers to download the default local embedding model and build, verify, and activate its vector epoch. For unattended setup, make that approval explicit with atmem openclaw install --allow-model-download; choose another Ollama model with --embedding-model MODEL. Do not install the npm package yourself.

Already using AtMem 2.1 with OpenClaw? Upgrade in place:

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

The upgrade command is idempotent. It replaces a running dashboard with the new Python runtime before refreshing and testing the OpenClaw bridge, so the UI cannot continue serving the pre-upgrade package version.

For Pydantic AI, LangGraph, or another non-OpenClaw integration, finish an upgrade by restarting a background dashboard directly:

python -m pip install --upgrade atmem
atmem dashboard daemon restart

Using python -m pip is important: it upgrades the same Python environment selected by python, rather than an unrelated pip executable on PATH.

Pydantic AI — native capability

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

from pydantic_ai import Agent
from atmem.adapters import AtMemAdapterIdentity
from atmem.adapters.pydantic_ai import PydanticAIAtMemAdapter
from atmem.control import ControlPlaneManager

manager = ControlPlaneManager()
scope = manager.agent_topology()["agents"][0]
identity = AtMemAdapterIdentity(
    agent_id=scope["agent_id"],
    workspace_id=scope["workspace_id"],
    subject_id=scope["subject_id"],
    user_id="authenticated-application-user",  # required only for delegation
)
memory = PydanticAIAtMemAdapter(manager, identity).capability()
agent = Agent("openai:gpt-5-mini", capabilities=[memory])

LangChain/LangGraph — native middleware

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

from langchain.agents import create_agent
from atmem.adapters import AtMemAdapterIdentity
from atmem.adapters.langgraph import create_langgraph_middleware
from atmem.control import ControlPlaneManager

manager = ControlPlaneManager()
scope = manager.agent_topology()["agents"][0]
identity = AtMemAdapterIdentity(
    agent_id=scope["agent_id"],
    workspace_id=scope["workspace_id"],
    subject_id=scope["subject_id"],
    user_id="authenticated-application-user",  # required only for delegation
)
memory = create_langgraph_middleware(manager, identity)
agent = create_agent(model="openai:gpt-5-mini", tools=[], middleware=[memory])

The framework hooks automate authenticated capture, governed retrieval, context injection, exposure proof, and turn/tool evidence. When an enabled delegated-provider registration matches the complete scope, they instead carry the exact HMAC-authenticated provider workflow through the Pydantic AI or LangChain/LangGraph model boundary, without also using native AtMem context. This delegated host path is packaged in 2.2.6. The adapters do not replace your agent's model, tools, conversation history, or LangGraph checkpoints. See the complete framework adapter guide for async, multi-agent, and low-level StateGraph integration.

Spec 007 milestone: govern work in progress

AtMem 2.2.6 includes Governed Task State: a separate, revisioned authority plane for what an agent is doing now, what remains, what is blocked, and whether completion is allowed. It is disabled by default and never turns temporary task progress into long-term personal memory.

Start one exact scope and inspect it from either the CLI or the dashboard:

atmem task enable ~/.atmem/memories.db \
  --subject user-1 --agent agent-1 --workspace workspace-1
atmem task start ~/.atmem/memories.db --task-id release-007 \
  --goal "Ship the governed task-state milestone" --actor [email protected] \
  --required-item verify="Run release verification" \
  --subject user-1 --agent agent-1 --workspace workspace-1
atmem task show ~/.atmem/memories.db release-007 \
  --subject user-1 --agent agent-1 --workspace workspace-1
atmem dashboard

The dashboard's Governed tasks card shows progress, blockers, recent task decisions, context delivery, the current revision, and guarded lifecycle actions. Model delivery requires an exact task identity. Pydantic AI may supply atmem_task_id in run dependencies; LangGraph may supply it through configurable; construction-time identity.for_task("release-007") remains a backward-compatible fallback. OpenClaw resolves the owner-authorized current conversation binding. AtMem never guesses from prompt text or chooses among open tasks. AtBot may propose a change, but AtMem revalidates and commits it.

See the Governed Task State guide for lifecycle, correction, provenance, expiry, benchmark, and automation examples, and read the 2.3.6 release notes before upgrading.

Prove memory quality locally

atmem benchmark run --output benchmark.json

This offline release gate runs 24 isolated extraction, contradiction, recall, withholding, injection, privacy, poisoning and fallback cases. Safety must be perfect; other quality metrics cannot fall below checked-in baselines. Optional local/hosted profiles, LongMemEval import and fair Mem0 OSS comparison are also available without adding Mem0 or model SDKs to the base install. See the memory benchmark guide for commands and honest limits. The retrieval and archive improvements from 2.3.3 remain in 2.3.6, which also strengthens canonical memory-integrity boundaries while preserving streamlined local startup and shared-login navigation. Developer opt-in fusion, scoped graph nomination and matrix reuse are available for evaluation; broader performance targets remain research, not release claims.

3. Review, then activate

Every integration starts in shadow mode: AtMem learns and shows what it would retrieve, but cannot change model context. Review it in the dashboard, then explicitly enable governed injection:

atmem dashboard
atmem control status
atmem control activate
atmem control verify

If AtBot or its selected model is unavailable, AtMem continues with safe local capture and hybrid ranking. Memory authority and agent operation do not depend on a hosted model.

Companion boundary: AtBot is a separately packaged, headless component installed and managed by AtMem. It is not an independent agent or a second memory authority.

Optional: delegate context authority

Delegated HTTP transport requires per-instance HMAC request credentials for context and health. See the shared profile and beta migration before enabling an older delegated registration.

AtMem uses its own governed retrieval by default. Introduced in 2.2.6, its explicit, provider-neutral delegated mode supports deployments where another compatible provider must make the context decision while AtMem owns host integration and flight evidence.

atmem delegated register --help
atmem delegated status
atmem delegated enable context-provider:local
atmem delegated doctor

Registration is disabled by default and is bound to exact user, agent, and workspace scopes. On matching turns, AtMem verifies the signed result, injects the provider's exact bytes once, and separately proves delivery. It does not run native retrieval after an accepted delegated decision. Provider failure withholds context unless the operator explicitly registered native fallback. See the delegated context-provider guide.

AtMem also ships provider-side adapters, each as an independent optional extra:

# Mem0 chooses context; AtMem verifies and records delivery
python -m pip install 'atmem[mem0]'
atmem provider init mem0-local --kind mem0 --mode oss --port 8788

# Or use an application-owned LangGraph / Pydantic AI factory
python -m pip install 'atmem[langgraph-provider]'
atmem provider init graph-context --kind langgraph \
  --factory myapp.memory_graph:build_graph --port 8789

python -m pip install 'atmem[pydantic-provider]'
atmem provider init ai-context --kind pydantic-ai \
  --factory myapp.memory_agent:build_agent --port 8790

atmem provider init creates private signing material and prints the exact registration command; it does not enable delegated authority. See the context-provider adapter quick starts.

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.

Installation details

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

AtMem requires Python 3.10 or newer. It always creates a dependency-free local vector sidecar. atmem openclaw install can automatically prepare an Ollama embedding model, while the semantic extra adds local sentence-transformer choices:

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

For repository development, install both workspace packages:

python -m pip install -e './packages/atbot[dev]' -e '.[dev]'
atmem atbot setup

The authority modules remain model-agnostic and do not import AtBot. The AtMem distribution requires the separately packaged, exactly pinned AtBot companion, whose built-in Ollama and OpenAI-compatible client uses only the Python standard library. Framework SDKs enter the environment only through explicit extras.

Integration boundaries

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

# Initialize local sign-in and manage encrypted evidence privileges.
atmem init
atmem users create audit.viewer viewer
atmem users create incident.team investigator
atmem users create evidence.team evidence_collector
atmem evidence status

# 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:8768/ on a new install; existing daemon ports are preserved
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.

The governed-memory chat remains the primary dashboard surface. AtBot provider, model, endpoint, lifecycle, and fallback controls are kept in a collapsed Memory intelligence settings row. The browser renews an expired local CSRF session once and retries the mutation; persistent failure asks the user to refresh rather than exposing a raw security error.

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 and requires a local AtMem account. It uses HttpOnly sessions, 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

Existing 2.1 installations upgrade without starting a new migration:

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

The upgrade retains the current shadow or active mode, refreshes the pinned bridge, restarts the gateway, records a self-test flight, and restores the previous bridge if verification fails.

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.

Encrypted Agent Black Box evidence

When the recorder is configured, new capture defaults to encrypted full fidelity: exact text, context, model exchange, tool arguments/results and ordered file, image, audio and video parts are sealed in the protected evidence vault. The legacy evidence table retains compatible digests and bounded operational projections; it never receives the exact reserved payload. New and migrated control stores are application-encrypted as a whole, so those projections and their metadata are not readable by opening the file as SQLite. Other historical or external plaintext sources must still pass the inventory and verified-cleanup gate before an installation claims complete metadata-at-rest protection.

The Settings page presents this as one compact Evidence protection row. Turning Data off retains encrypted metadata and labels new runs not reconstructable. Turning the Recorder off stores no new evidence. Neither control creates plaintext storage.

Evidence privileges are deliberately separate from agent/API admin headers:

• Viewer sees content-free metadata, hashes, integrity and coverage only.
• Investigator can decrypt, view, play and reconstruct exact evidence inside AtMem.
• Evidence Collector can additionally export plaintext after exact confirmation and manage evidence settings. Viewer and Investigator plaintext export always fails.
• Administrator has ultimate local evidence access and manages local users, roles and password resets.

atmem init prints the first Administrator's temporary password once. The dashboard uses username/password sign-in and forces that password to change. create-test-accounts remains a compatibility command for automated tests; its bearer tokens are not the normal dashboard experience.

Portable AtMem Home

All new durable state resolves from one AtMem Home (ATMEM_HOME, otherwise ~/.atmem). New installations use config/, identity/, memory/, evidence/, artifacts/, migrations/ and disposable runtime//indexes/ directories under that root. Exact media is retained twice inside AtMem's encrypted boundary: in the protected evidence document as the disaster-recovery authority and in the content-addressed artifact vault for verification and deduplication.

atmem home status
atmem home verify
atmem restore /path/to/copied-atmem-home

On another computer, atmem restore opens the copied home against a disposable runtime binding. Sign in with an Administrator account contained in that copy; the source agent, OpenClaw media directory and host logs are not required. Restore/open does not silently migrate evidence. Existing 2.3 prerelease layouts use an explicit, copy-first conversion:

atmem home migrate --home ~/.atmem /path/to/new-portable-home
atmem home verify --home /path/to/new-portable-home
atmem home migrate --home ~/.atmem /path/to/new-portable-home --commit
atmem home adopt --home /path/to/new-portable-home

Stop AtMem and connected agent writers before copying or migrating. Migration streams an inventory, copies and verifies each known durable store, journals its phase and never deletes the source. Adoption requires the copied Administrator, rotates sessions and changes only machine-local bindings; historical evidence IDs, hashes and artifact bytes are not rewritten.

Legacy evidence projection

The table below describes the compatible content-minimizing projection. By itself it is not sufficient to replay or reconstruct a run after the originating agent/logs are lost; authorized reconstruction reads the encrypted vault.

The runtime can record these content-minimizing event types:

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 this legacy projection. SHA-256 digests are fingerprints, not encryption or anonymization. Exact values are available only through authorized AtMem evidence operations when the protected full-fidelity boundary captured them. 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_recall_decision, memory_form_episode, 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.
• Every persistent 2.2 memory database has a rebuildable local vector sidecar. Its active epoch participates in governed candidate nomination, but every vector match is checked against canonical scope, status, digest, exclusions, sensitivity, and generation before use. Higher-quality embedding libraries and model downloads remain optional.
• In full capture mode, available external media bytes are copied into encrypted AtMem evidence and its content-addressed artifact vault before capture is claimed; the host reference is provenance, not a recovery dependency. Metadata/off modes are visibly non-reconstructable.
• 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

Official website documentation is maintained through the public documentation inventory. See how to contribute and update release docs. Website publication follows a separate owner-reviewed, main-only deployment.

• Current implementation status
• AtMem Code: shared project memory — optional structure and experience for coding agents
• Generic runtime adapter
• Delegated context-provider contract
• 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
• Spec-driven development

Development verification

Material features use the repository's GitHub Spec Kit Lean workflow. See Spec-driven development for feature directories, Codex skills, and the constitution-backed delivery sequence.

AtMem and its separately packaged AtBot companion share this repository. They remain separate processes and communicate only through the loopback companion protocol; neither package imports the other's runtime code.

In 2.2, AtMem declares the exactly pinned AtBot companion as a required distribution dependency. A clean package installation will install it automatically after both 2.2 distributions are published; repository development uses the editable command above. Model setup remains an explicit user decision:

atmem atbot setup       # interactive local, hosted API, custom, or skip choice
atmem atbot providers   # list profiles, defaults, and API-key environment names
atmem atbot doctor      # verify runtime, provider, protocol, and safe fallback

The dashboard exposes the same provider, model, endpoint, start, stop, and safe fallback controls in a collapsed settings row below governed-memory chat. It also shows the equivalent CLI command, so a user can switch between the UI and terminal without reading a separate setup guide. Local choices include Ollama and any loopback OpenAI-compatible server. Hosted profiles include OpenRouter, OpenAI, DeepSeek, xAI Grok, Anthropic Claude, Hugging Face, and a custom HTTPS OpenAI-compatible endpoint. Configuration stores only the environment-variable name containing a key; it never stores the key itself. Choosing Use safe fallback is remembered and leaves AtMem's deterministic local ranking active.

python -m pip install -e '.[dev]' -e './packages/atbot[dev]'
python -m pytest -q
python -m pytest -q packages/atbot/tests

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

This stable source line is 2.3.10, with OpenClaw bridge 2.3.10, AtBot 0.1.1, and AtFlows 0.1.4. All four versions are stable. Use the release note for install/upgrade commands and the qualification report for promotion provenance. The 600-task DolphinBench result is recorded against the tested 2.3.10b1 artifact: 390/600 (65.0%). Stable promotion does not rename that evidence or imply independent verification.

License

AtMem is licensed under the Apache License 2.0. It permits commercial and internal enterprise use, modification, and distribution, subject to the license terms. Apache-2.0 also provides an explicit contributor patent grant and does not require an organization to publish private changes merely because it runs the software as a service.