Atmem

AtMem

[](./docs/releases/v2.3.7b2.md) [](https://github.com/aetna000/atmem/actions/workflows/ci.yml)

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

> Release status: AtMem 2.3.6 remains the stable release. AtMem 2.3.7b2 is a Windows concurrency and durability prerelease; see its [release note](./docs/releases/v2.3.7b2.md). The stable [memory-integrity benchmark](./docs/benchmarks/memory-integrity.md) remains unchanged. AtFlows telemetry and read-only review leads remain separate and explicit. > It records exact host-observed text and supported multimodal boundaries by default, > while keeping every claim limited to what the connected agent actually supplied.

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.6
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.

In 2.3.7b2, 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.6
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.6'
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.6'
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](docs/framework-adapters.md) 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 you@example.com \
  --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](docs/governed-task-state.md) for lifecycle, correction, provenance, expiry, benchmark, and automation examples, and read the [2.3.6 release notes](docs/releases/v2.3.6.md) 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](docs/benchmarks.md) for commands and honest limits. The retrieval and archive improvements from [2.3.3](docs/releases/v2.3.3.md) remain in [2.3.6](docs/releases/v2.3.6.md), 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](docs/contracts/delegated-request-auth-v1.md) 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](docs/delegated-context-provider.md).

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](docs/context-provider-adapters.md).

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.6
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.6'

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

| 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](docs/generic-adapter.md) 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 ev

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [aetna000](https://github.com/aetna000)
- **Source:** [aetna000/atmem](https://github.com/aetna000/atmem)
- **License:** Apache-2.0
- **Homepage:** https://atmem.ai

Install and usage instructions live in the source repository linked above.