AI Agent Memory: What It Is, What It Costs, and What Leaves Your Machine

Agent memory tools remember what happened last session so you stop re-explaining. How the mechanism works, the token economics, and the privacy surface.

Flat illustration of three stacked dark squares beside a larger orange square on a cream background
9 min read
1,839 words

AI agent memory is the second packaging format in two months to break out of the coding-agent world, and it answers a complaint that anyone using one of these tools daily has made out loud: it forgets everything. Close the session, open a new one, and you are explaining your own project back to a tool that helped you build it yesterday.

The one on GitHub Trending this week, claude-mem, gained 7,995 stars in the week to 4 November and sits at 112,200 overall. That second number matters — this is a large project accelerating, not a new one having a moment.

The problem AI agent memory actually solves

The cost of a forgetful assistant is not measured in tokens, it is measured in the first ten minutes of every session. Which database are we using. Why that table has two ID columns. What we decided about the deploy script and why we rejected the obvious alternative. The agent cannot see any of it, so somebody types it again, slightly differently, and gets slightly different advice.

For an individual that is irritating. For a team it is worse, because the context that gets retyped is whatever the person at the keyboard happens to remember, and the decisions nobody remembers quietly stop existing.

What it does mechanically

The README describes claude-mem as a “persistent memory compression system built for Claude Code”, working by “automatically capturing tool usage observations, generating semantic summaries, and making them available to future sessions”.

Underneath, the pieces are conventional and worth knowing because they tell you where your data sits:

  • Six lifecycle hooks — SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop and SessionEnd — each invoking claude-mem hook claude-code <event>. The agent is not doing the remembering; the hooks are watching it work.
  • A local worker service, managed by Bun, exposing an HTTP API and a web viewer.
  • SQLite holding sessions, observations and summaries, with FTS5 full-text search.
  • A Chroma vector database for hybrid semantic and keyword search.
  • Settings in ~/.claude-mem/settings.json.

Install is npx claude-mem install, or through the plugin marketplace inside Claude Code. The README carries a warning worth repeating: npm install -g claude-mem installs the library only and registers neither the hooks nor the worker, which is the kind of near-miss that leaves someone convinced a tool is broken when it was simply never wired in. It needs Node.js 20 or later, and installs Bun and uv if they are missing.

It is not Claude-only. The README lists Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot and OpenCode among supported agents.

Why the retrieval design is the interesting part

Here is the thing that separates a memory tool that helps from one that quietly doubles your bill: reinjected context is paid for on every turn it stays in the window.

A naive implementation stuffs everything it remembers into each new session and charges you for all of it, forever, whether or not today’s task touches last month’s decisions. The interesting engineering is in not doing that.

claude-mem’s answer is a three-layer search exposed over MCP. The search tool returns a compact index. timeline gives chronological context. get_observations fetches full detail only for the IDs you actually want. The project’s own claim for this design is “~10x token savings by filtering before fetching details” — a vendor figure on a vendor benchmark, and directionally the right shape regardless of the multiple.

This is the same economics that makes agent skills cheap: keep a cheap index permanently in view and load the expensive content only when something asks for it. Any memory tool you evaluate should be able to explain how it avoids carrying everything all the time. If it cannot, that is your answer.

The privacy surface

A tool whose entire job is recording what you and your agent did deserves a careful read of what it keeps and where.

Feature list from the claude-mem README showing privacy control through private tags, screenshots opt-in and off by default, context configuration, automatic operation and citations
claude-mem's README, captured 4 Nov 2026: the privacy controls are listed as features, which is the right place to read them before installing.

Three things are stated plainly, and all three are the answers you would want:

Content wrapped in <private> tags is excluded from storage. An explicit opt-out at the point of writing, which is more useful than a setting buried two menus deep.

Cloud Sync is optional. The default is that this is a local system — SQLite and Chroma on your own disk, behind a worker on your own machine.

Screenshots are opt-in and off by default. When they are on, converted copies are uploaded to cmem.ai only if Cloud Sync is enabled, and sent to the observer model only if image inference is separately enabled. Two independent switches before an image of your screen leaves the building.

That is a defensible design. It is also a reminder that the default-local posture is a choice the maintainer made and could revisit, so for anything under a client confidentiality clause the question is the same one that decides whether a local model is the right answer for business data: what is contractually allowed to leave, and can you prove it did not.

What it costs, as far as anyone has said

Not much is published, and the gaps are worth naming rather than guessing at.

Signing in unlocks a 30-day free trial of the project’s observer, which the README says runs “off-plan”. After the trial, memory “automatically falls back to your Anthropic plan unless you subscribe”. You can instead supply your own OpenRouter or Gemini key, or use your Anthropic plan from the start.

What the page does not state is the subscription price, or the ongoing per-session token cost of the compression step. Both are real numbers that will show up on a bill, and neither is published where a buyer can see it before installing. That is not an accusation — it is a reason to watch your usage for the first fortnight rather than assume the compression is free.

Check the URL before you install

A practical hazard specific to a tool this popular. Searching for it does not reliably land you on the project.

What ranks is content-marketing pages from an unrelated vendor, whose star counts for this project contradict each other across their own articles, alongside wiki entries and directory listings. More seriously, at least one fork appears carrying the upstream README with a cryptocurrency token section bolted on — exchange links and a Solana contract address sitting beneath the real project’s documentation.

A fork looks almost identical to the original on GitHub. The README is the same, the screenshots are the same, and the only reliable difference is the account name in the URL. Before you run an installer that registers six lifecycle hooks and a background worker, read the owner in the address bar and confirm it is the one the project’s own documentation points at.

Memory is not the same as instructions

These two formats are arriving together and get conflated constantly, so the distinction is worth stating once.

A skill is instructions: a directory with a SKILL.md telling the agent how to do something, where the description stays in context and the body loads when relevant. It is a procedure you wrote.

Memory is a record: what actually happened, captured automatically, retrieved when it looks relevant. Nobody wrote it deliberately.

A team wants both, and they fail in opposite directions. A stale skill gives you a procedure nobody follows any more. Stale memory gives you a decision that was reversed in March, presented with the same confidence as one made yesterday.

The part to work out before you commit

Every memory tool answers “how do I remember” in its README. The question that decides whether you keep it is the opposite one, and you generally have to find the answer yourself: how do I make it forget?

Three versions of that, in rising order of how much they will annoy you. Excluding something as you write it is the easy case, and claude-mem handles it with <private> tags. Removing something already recorded is harder — you need to know where it lives, which here is a SQLite database and a Chroma index on your own disk, and whether deleting from one leaves it in the other. Correcting something that is wrong rather than secret is hardest of all, because an automatic capture system has no concept of a decision being superseded; it only has observations with timestamps.

That third case is the one that will bite a team. Somebody records an approach in week one, the team abandons it in week four, and in week nine the assistant confidently reconstructs the abandoned approach because that is what the record says. The fix is not technical — it is remembering to tell the agent explicitly when a decision is reversed, in the same session it is reversed, so the reversal gets captured too.

Related and worth checking on any tool in this category: whether you can read back what it kept. claude-mem exposes a web viewer through its local worker, which means you can audit the record rather than trusting it. A memory system you cannot inspect is a system you are asked to take on faith, and the whole premise is that it knows things you have forgotten.

Where it goes wrong

Memory outlives the reason for it. The architectural constraint you recorded in January was true when the database was MySQL. Nothing in an automatic capture system knows you migrated.

A bad decision becomes durable. Automatic capture does not distinguish a good call from a mistake you later regretted; both are observations, and both come back. This is the memory version of the problem that makes a bounded brief matter more than a clever agent — the system will faithfully reproduce whatever you fed it.

112,000 stars is a popularity number, not a maturity one. It tells you a lot of people found it interesting and nothing about whether it will be maintained next year or what it does to your context window on a long session.

The install footprint is larger than one plugin. Node 20, Bun, uv, a background worker on a local port and two databases. Each is reasonable; collectively they are a service running on your machine, and it is worth knowing that is what you agreed to.

The honest way in is to install it on one project rather than everywhere, use it for a fortnight, and then read the web viewer to see what it actually recorded about you. If the answer is “the things I would have retyped anyway”, it has earned its place. If the answer is a transcript of every dead end you walked down, you have bought a liability with a search index.

Sources

Every figure in this article traces to one of these. Dates are when the page was read.

  1. thedotmack/claude-mem
    GitHubAccessed Nov 4, 2026Official docs
  2. Skills
    AnthropicAccessed Oct 30, 2026Official docs
  3. Trending repositories, weekly
    GitHubAccessed Nov 4, 2026Official docs

Written by

Kai Devlin AI Automation Engineer

Full-stack developer who builds and runs AI automation systems in production. Runs local LLMs on personal hardware, builds N8N pipelines that actually ship, and deploys on Cloudflare Pages. Every guide on Pipeline Monk is tested on real consumer hardware — a Ryzen 7 5800HS with 16GB RAM and a GTX 1650. If it works on that, it works.