AtomicMemory: a correction-aware memory layer with a cloud and a self-hosted path
Portable semantic memory for AI agents: core engine, TypeScript SDK, framework adapters, MCP server, CLI, and host plugins.
At a glance
- What is it?
- AtomicMemory is a TypeScript memory stack for AI agents that spans an open-source Core, a CLI, an SDK and an MCP server. Its distinguishing claim is that memory is editable rather than append-only, and the README's benchmark table is the part worth reading skeptically.
- Who is it for?
- Adopt AtomicMemory if you need agent memory you can audit and correct, you are already on Postgres with pgvector, and you can accept that the benchmark artifacts are promised rather than shipped. Do not adopt it if you have no Docker or no OpenAI key and want a Local install, or if you need a permissively licensed drop-in today.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 7 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem AtomicMemory targets: memory that cannot be corrected
Most agent memory implementations are append-only. You store a fact, you retrieve it, and when the fact changes you either write a second contradicting entry or you delete the first one and hope nothing depended on it. AtomicMemory's README frames the alternative as correction-aware memory: supersede, clarify, delete, or retain memories as facts change. That is the whole pitch, and it is a narrower pitch than the word memory usually implies. The project is not trying to be a vector database or a RAG framework. It is trying to be the layer that decides what an agent should still believe.
The intended audience is visible in the packaging. There is a CLI, a TypeScript SDK, framework adapters, an MCP server, and host plugins. That combination points at application engineers wiring agents into Cursor, Claude Code, or Codex, and at teams that want the same memory protocol to survive a change of model provider. The README states the goal as durable context across sessions without coupling the application to one model, framework, or deployment. The topics list adds local-first, self-hosted, and pgvector, which tells you the storage assumption is Postgres rather than a bespoke store.
How the pieces fit: Core, SDK, MCP server, CLI, adapters
The repository is a monorepo. The README references packages/core/Dockerfile, and the npm badges point at @atomicmemory/core and @atomicmemory/sdk as separate published packages. Core is the engine. The SDK is the server-side integration surface for applications talking to Core. The MCP server is what agent hosts connect to. The CLI, published as am, is the operator interface over all of it.
The design principle the README names is provider boundaries: extraction, embeddings, mutation, reranking, and retrieval packaging each sit behind an explicit boundary. That matters for a memory layer specifically, because the mutation step is where most systems hide their decisions. If you can swap the extraction provider without touching the retrieval path, you can reason about which stage produced a bad memory. The README also claims the mutation and retrieval path is auditable when you run Core yourself, which is the practical difference between this and a hosted-only memory API.
What the material does not give is the internal data model. There is no schema, no description of how a supersede is represented, and no explanation of how conflicting memories are resolved at retrieval time. The README asserts correction-aware behavior as a feature bullet. It does not show the mechanism. Treat that as the main documentation gap to close before committing.
Getting to a working install: the two init paths
The guided installer is the shortest route:
curl --proto '=https' --tlsv1.2 -fsSL https://get.atomicstrata.ai/install.sh | sh -s -- --init
Plain am init defaults to managed Cloud. The README states that no Docker or OpenAI key is required on that path, and that with a single project the CLI selects it automatically while multiple projects trigger a prompt. Non-interactive Cloud automation uses am init --yes --project <cloud-id>. Local automation has to opt in explicitly with am init --local --yes, which is a sensible default: you should not accidentally provision containers.
Once installed, the two commands the README demonstrates are:
am memory ingest "I prefer aisle seats when flying." am memory search "seat preference"
Host integration is a separate step. am integrate --yes --host cursor, or claude-code, or codex. The README is explicit that this writes the host's user-level MCP configuration and does not install a marketplace plugin. That distinction matters if you were expecting a one-click extension.
Connected Local is the heavier path and the README lists its requirements plainly: Docker Desktop or Docker Engine running, an OpenAI API key, and macOS or glibc Linux on x86_64 or arm64. Setup reads the key with hidden input and stores it with owner-only permissions. Verification is am doctor --smoke. Local defaults to profile local and Core URL http://127.0.0.1:17350.
Credential handling is more careful than the rest of the docs
The most specific writing in the README concerns API keys, which suggests the authors have been burned here. Managed server keys carry a per-installation name of the form am-cli-a1b2c3d4e5f6, twelve hex characters. Initialization reuses a working stored project credential; otherwise it rotates only this installation's exact key and creates one when absent. Legacy unsuffixed keys and keys belonging to other installations are left alone. 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 revoke unrelated keys as quota recovery.
Project selection is also typed. am init --project <id-or-slug> infers Cloud versus Local from the resolved project type, while am init --cloud --project <cloud-id> and am init --local --project <local-id> assert it. Ambiguous slugs fail and ask for the unique project ID rather than guessing. Credentials are described as bound to the Cloud origin and project, stored with owner-only permissions, and never printed.
This is the section of the README that reads like it was written after real incidents. It is also the section you can verify locally in a few minutes, which makes it a reasonable first thing to check.
The benchmark table is the weakest evidence in the repository
The README leads with a headline results table: BEAM-100K lenient at 0.7375, BEAM-1M at 0.6625, BEAM-10M at 0.4875, and LoCoMo10 GPT-4o-mini binary at 0.8396, with cost-per-query figures between $0.066 and $1.26 and sample sizes of n=80 or n=1540. The accompanying text says these results put AtomicMemory at or near the published ceiling in each reported category, and then adds the sentence that matters: reproducibility artifacts and harness details will be published with the benchmark materials.
That is a promise, not a result. Without the harness you cannot check the retrieval configuration, the prompt, the judge, or what lenient scoring means in this context. The BEAM-10M row is described as parity with a published Mem0-new figure, and the BEAM-100K row as parity with Hindsight at 0.75, so the comparison is against other published numbers rather than a shared run. Matched methodology is asserted in the README, not demonstrated in it.
None of this means the numbers are wrong. It means that as of the material available, the benchmark table is a marketing surface with a footnote, and the footnote has not been cashed. If retrieval quality is your reason for choosing a memory layer, wait for the artifacts or run your own evaluation against your own corpus.
Where AtomicMemory is the wrong tool
The Local path has hard prerequisites that rule it out for a lot of environments. Docker Desktop or Docker Engine must be running. An OpenAI API key is required even for the self-hosted Core, which is a real constraint: the README describes the key as needed for Local setup, so the open-source engine is not fully offline out of the box. The supported platforms are macOS or glibc Linux on x86_64 or arm64. Windows is not listed. Alpine and other musl-based images are not listed either, which matters if your deployment target is a slim container.
There is a second boundary around the licence. The repository metadata reports the licence as NOASSERTION while the README badge and the LICENSE link both say Apache 2.0. Those two signals disagree, and the metadata is the machine-readable one. Until you open the LICENSE file yourself, you do not know which terms apply. That is a blocking check for anyone with licence review in their adoption path, and it is not something a README badge resolves.
Finally, if your problem is retrieval over a large static document set rather than evolving facts about a user or a session, the correction machinery is overhead. You want an index, not a belief revision system.
The alternative, and the actual difference in approach
The obvious comparison is a general-purpose vector store such as pgvector used directly, or a RAG framework layered on top of one. AtomicMemory's topics list includes pgvector and postgres, so it is likely built on that substrate rather than replacing it. The difference is not storage. It is what happens between retrieval and the model.
With pgvector alone, your application owns the write path. You decide when a new embedding supersedes an old one, you decide how to represent a contradiction, and you decide what the retriever returns when two rows disagree. That is full control and full responsibility. AtomicMemory's claim is that it takes that decision layer and makes it a product surface with explicit mutation operations and provider boundaries you can swap. The README's framing of supersede, clarify, delete, or retain is precisely the set of operations a raw vector store does not give you.
The trade is real in both directions. A raw pgvector table has no opinion, no CLI, no MCP server, and no upgrade cadence to track. AtomicMemory gives you those things and asks you to accept its model of what correction means, plus its release cycle. If your memory semantics are unusual, the abstraction will fight you. If they are ordinary (user preferences, project facts, session state), the abstraction is the reason to use the project.
Maintenance cost and the licence question to settle first
The release history in the supplied material shows cli-v0.2.0 in August and cli-v0.2.1 later the same month, with the package versioned as am 0.2.x. A 0.x line means the CLI surface can change between minor releases, and the README already documents one such change in credential naming: legacy unsuffixed keys are handled differently from the am-cli-<12-hex> form. Expect to read release notes before upgrading the CLI on a machine that holds a working credential.
The monorepo shape has its own cost. Core, SDK, MCP server, CLI, adapters, and host plugins are separate artifacts with separate npm packages, and the README publishes them under the @atomicmemory scope. Pinning versions across that set is your problem, not theirs. The Docker image is published to GHCR per the badge, so a Local deployment means tracking image tags as well as CLI versions.
On licensing, the material is contradictory and I will not resolve it: the repository metadata says NOASSERTION, the README badge and LICENSE link say Apache 2.0. Open the LICENSE file at the commit you intend to use and read it. Nothing here is legal advice, and the discrepancy is exactly the kind of thing a licence review exists to catch.
Editorial conclusion
Adopt AtomicMemory if you need agent memory you can audit and correct, you are already on Postgres with pgvector, and you can accept that the benchmark artifacts are promised rather than shipped. Do not adopt it if you have no Docker or no OpenAI key and want a Local install, or if you need a permissively licensed drop-in today. Verify first that the LICENSE file matches the Apache 2.0 badge, that the benchmark harness referenced in the README has actually been published, and that Hosted Cloud credentials are stored under owner-only permissions on your machine.
Community notes