# AtomicMemory: inspectable, correction-aware memory for AI agents

> AtomicMemory is an open-source memory layer for agents, shipped as a Rust CLI, a TypeScript SDK, framework adapters and an MCP server. The design bet is that memory should be editable and auditable rather than append-only, and the Local path trades a Docker and an OpenAI key for that control.

**atomicstrata/atomicmemory** — Portable semantic memory for AI agents: core engine, TypeScript SDK, framework adapters, MCP server, CLI, and host plugins.

- Repository: https://github.com/atomicstrata/atomicmemory
- Website: https://docs.atomicstrata.ai
- Stars: 435 · Forks: 38
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/atomicstrata-atomicmemory

## The problem AtomicMemory targets: memory that cannot be corrected

Most agent memory stacks are append-only. You write a fact, it gets embedded, and later a retrieval call returns it. If the fact changes, the old version does not go away; it competes with the new one at query time. AtomicMemory's README frames this as the black-box problem and names its answer directly: memory that is correction-aware, meaning you can supersede, clarify, delete or retain a stored fact as circumstances change. The audience is teams building agents that run across sessions and need durable context without binding the application to one model, framework or deployment. That last clause matters more than it reads. The project ships a CLI, an MCP server, a TypeScript SDK, framework adapters and host plugins, and the README describes them as one memory protocol reached through several surfaces, so swapping a host or a framework does not mean re-embedding everything.

## How the pieces fit: Core, the am CLI, and the MCP surface

The repository is a monorepo. The top level holds packages/, adapters/, plugins/, crates/ and scripts/ alongside a pnpm workspace and a Cargo workspace. Cargo.toml lists four Rust members: crates/cli, crates/cloud-client, crates/cloud-types and crates/core-types, with workspace version 0.2.1, edition 2024 and rust-version 1.88. The CLI you install as am is that Rust binary, not a Node wrapper, which is why the installer can drop a single executable onto PATH. The TypeScript side lives in packages/ and is published as @atomicmemory/core and @atomicmemory/sdk. On the Local path, Core runs on your machine and the CLI talks to it at http://127.0.0.1:17350 by default under the profile named local. The MCP server is the bridge to agent hosts: am integrate writes the host's user-level MCP configuration, and the README states plainly that it does not install a marketplace plugin. The README also describes provider boundaries around extraction, embeddings, mutation, reranking and retrieval packaging, which is the mechanism behind the model-flexible claim: those stages are swappable rather than fused into one pipeline.

## Installing the am CLI and storing your first memory

The README's quickstart is a single curl that installs the CLI and runs initialization in one guided command. The --init flag is what triggers the interactive setup; plain installation without it would leave you to run am init yourself.

```bash
curl --proto '=https' --tlsv1.2 -fsSL https://get.atomicstrata.ai/install.sh | sh -s -- --init
```

Interactive am init offers Hosted Cloud as option 1 and Connected Local as option 2. Hosted Cloud needs no Docker and no OpenAI key. If the installer updates PATH, the README says to open a new terminal before the next commands, or use the shell-specific activation command it prints. Once a profile is active, ingest and retrieval are two commands:

```bash
am memory ingest "I prefer aisle seats when flying."
am memory search "seat preference"
```

The first command writes the preference; the second returns the stored memory for a semantic query. To wire the active profile into an agent host, the README gives this form, with cursor, claude-code or codex as valid hosts:

```bash
am integrate --yes --host cursor
```

For the self-hosted path, Connected Local requires Docker Desktop or Docker Engine running, an OpenAI API key, and macOS or glibc Linux on x86_64 or arm64. Initialization and verification are two separate commands, and the second is the one that tells you whether the stack actually works:

```bash
am init --local
am doctor --smoke
```

For headless automation, the README shows seeding dashboard auth and the OpenAI key before selecting Local explicitly:

```bash
am auth login --token "$AM_DASHBOARD_JWT"
export OPENAI_API_KEY=sk-...
am init --local --yes
```

Non-interactive Cloud runs use am init --yes --project <cloud-id>, while Local automation must opt in with am init --local --yes.

## Credential handling on the Cloud path, and where it gets awkward

The credential design is unusual enough to be worth understanding before you script it. Managed server keys use a per-installation name of the form am-cli-a1b2c3d4e5f6, so a second machine does not rotate the first machine's credential. The README states that a working stored project credential is reused; otherwise the CLI rotates only this installation's exact am-cli-<12-hex> key and creates it when absent, leaving legacy unsuffixed keys and other installations' keys untouched. Credentials are bound to the Cloud origin and project, stored with owner-only permissions and never printed. The awkward parts are the interactive edges. With no project, initialization opens onboarding and waits for project creation in an interactive terminal; a non-interactive run instead prints the URL and a recovery command rather than waiting, which means a CI job can stall on a step no human is watching unless you have already created the project. Ambiguous slugs fail with a request for the unique project ID, so --project accepts a unique ID or a case-insensitive slug and infers Cloud versus Local from the resolved project type. Explicit selectors assert the type instead: am init --cloud --project <cloud-id> requires a Cloud project, am init --local --project <local-id> requires a Local one. At the API-key limit, initialization preserves the previous default profile and prints the dashboard URL plus commands to list or revoke a key and retry. It does not rotate or revoke unrelated keys as quota recovery, which is the right call but does mean a full key quota stops initialization until someone acts.

## Where AtomicMemory is the wrong tool

The Local path is not cross-platform in the way a Node package usually is. The README lists macOS or glibc Linux on x86_64 or arm64 as the requirement, so a Windows host running Connected Local is outside what the documentation covers. That is a real constraint for teams whose agent development happens on Windows machines. The Local path also pulls in two dependencies that Hosted Cloud does not: Docker Desktop or Docker Engine must be running, and you must supply an OpenAI API key. An air-gapped deployment therefore has neither of the two documented paths available as written. There is a second, softer limitation in the positioning. The headline benchmark table reports v66 results on BEAM-100K, BEAM-1M, BEAM-10M and LoCoMo10 with matched methodology, and the README says reproducibility artifacts and harness details will be published with the benchmark materials. Until those artifacts exist in the repository, the numbers are the project's own claim rather than something a reader can re-run, and the README itself flags BEAM-10M temporal retrieval as the known open frontier, where it describes parity with Mem0-new rather than a lead.

## AtomicMemory against a plain vector store

The obvious alternative is a vector database such as pgvector on Postgres, which the repository's own topics list. pgvector gives you embeddings, an index and a similarity query, and it is a fine substrate. The difference is what sits above the index. With pgvector alone, correction is your problem: you decide how a superseded fact is marked, how a deletion propagates, and how retrieval avoids returning both the old and the new version of the same preference. AtomicMemory puts supersede, clarify, delete and retain into the memory protocol itself, and exposes that protocol through the CLI, the MCP server and the SDK so the same semantics apply whichever surface calls it. The trade is control for surface area. A raw pgvector table has no opinion about mutation semantics and no CLI to learn; AtomicMemory has both, plus a Rust workspace, a pnpm workspace and a set of CI scripts that the repository root shows under scripts/ci. If you want the smallest possible dependency and you are willing to write your own reconciliation logic, pgvector is the shorter path. If your agents already lose track of which fact is current, the correction layer is the part you are buying.

## Maintenance, licensing and what an upgrade costs

The repository is not archived, and the last push was on 2026-09-08, so the project is being worked on rather than parked. The most recent release listed is cli-v0.2.1 (am 0.2.1) from 2026-08-27, following cli-v0.2.0 on 2026-08-07, and the Cargo workspace version is 0.2.1, so the CLI and the Rust crates move together. The npm packages @atomicmemory/core and @atomicmemory/sdk are versioned separately, which means an upgrade can move one surface without the other; check both before you bump. The monorepo pins pnpm@9.15.4 and requires Node >=20.10.0 and pnpm >=9.15.4 for the JavaScript side, and rust-version 1.88 for the Rust side. Those are the floors to verify in CI before an upgrade, not after. On licensing, the README badge and package.json both say Apache-2.0, but the repository metadata reports NOASSERTION, meaning GitHub could not classify the LICENSE file automatically. Read the LICENSE file itself rather than trusting either label; this is a factual discrepancy in the repository, not a legal opinion.

## Conclusion

Adopt AtomicMemory if you need agent memory you can inspect and correct, and you accept the Connected Local prerequisites: Docker running, an OpenAI API key, and macOS or glibc Linux on x86_64 or arm64. Do not pick it if you want a fully managed black box, or if you need Windows as a Local host, since the README lists only macOS and glibc Linux. Before committing, run am doctor --smoke against your Local profile, confirm the Core URL resolves to http://127.0.0.1:17350 on your machine, and read the LICENSE file directly, because the repository metadata reports NOASSERTION while the README and package.json both say Apache-2.0.

## FAQ

### What is AtomicMemory and who is it for?

It is a portable semantic memory layer for AI agents and applications, shipped as a core engine, a TypeScript SDK, framework adapters, an MCP server, a CLI and host plugins. It targets teams that need durable context across sessions without coupling the application to one model, framework or deployment.

### How do I install the am CLI and connect it to an agent host?

The README's quickstart is a curl install script run with the --init flag, which installs the CLI and runs guided initialization. After that, am integrate --yes --host cursor writes the host's user-level MCP configuration; claude-code and codex are the other hosts named in the README.

### Does AtomicMemory require Docker or an OpenAI API key?

Hosted Cloud requires neither, according to the README. Connected Local requires Docker Desktop or Docker Engine running plus an OpenAI API key, and supports macOS or glibc Linux on x86_64 or arm64.

### What is the default Core URL for a Local profile?

The README states the Local defaults remain profile local and Core URL http://127.0.0.1:17350. You can verify the setup with am doctor --smoke.

## Sources

- [atomicstrata/atomicmemory on GitHub](https://github.com/atomicstrata/atomicmemory)
- [Issues](https://github.com/atomicstrata/atomicmemory/issues)
- [Project website](https://docs.atomicstrata.ai)
- [README](https://github.com/atomicstrata/atomicmemory/blob/main/README.md)
- [Releases](https://github.com/atomicstrata/atomicmemory/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/atomicstrata-atomicmemory