# Atmem

> Local-first, auditable memory for AI agents, with governed retrieval, delegated context delivery, and verifiable execution evidence. Works with OpenClaw, MCP, Pydantic AI, and LangChain/LangGraph. No external API required for local memory. Install with pip: pip install atmem

- **Type:** MCP server
- **Install:** `agentstack add mcp-aetna000-atmem`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [aetna000](https://agentstack.voostack.com/s/aetna000)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [aetna000](https://github.com/aetna000)
- **Source:** https://github.com/aetna000/atmem
- **Website:** https://atmem.ai

## Install

```sh
agentstack add mcp-aetna000-atmem
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/javadtaghia)
([@JavadTaghia](https://x.com/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

```bash
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

```bash
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:

```bash
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:

```bash
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

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

```python
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

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

```python
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:

```bash
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

```bash
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:

```bash
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.

```bash
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:

```bash
# 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

```bash
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:

```bash
python -m pip install 'atmem[semantic]==2.3.6'
```

For repository development, install both workspace packages:

```bash
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:

```bash
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:

```bash
# 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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-aetna000-atmem
- Seller: https://agentstack.voostack.com/s/aetna000
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.