Claude-Mem: persistent, local memory for agent sessions

Everything worth knowing about thedotmack/claude-mem: a memory engine that observes an agent’s work, summarizes it, and feeds relevant context back in later sessions.

---

What Claude-Mem is

Claude-Mem is a plugin and persistent memory engine for coding assistants. Its core function is to stop a new session from starting without the context of previous ones: it captures observations of tool usage, generates semantic summaries, and re-injects them when relevant.

The open-source core installs locally and stores data in SQLite; the project adds hybrid search with Chroma, a local Bun-run service, and MCP tools. So it isn’t just an instructions file for Claude Code: it’s a combination of lifecycle hooks, a background process, databases, and a query interface. The README and official documentation also describe compatibility with Cursor, Windsurf, OpenCode, Codex CLI, Gemini CLI, Antigravity CLI, OpenClaw, and MCP clients.

The project’s website distinguishes the free, Apache-2.0-licensed local engine from CMEM Cloud, a paid sync service and private MCP link. The subscription advertised on the site is 20 USD a month; it is not a requirement to use the local engine.

The origin: solving the context reset

The author identified in the README is Alex Newman (thedotmack, official X account: @Claude_Memory). The earliest launch evidence recovered is a Hacker News post by Newman from October 23, 2025, titled “I built a context management plugin and it changed my life,” which linked to an r/ClaudeCode thread. The submission got 11 points and one comment (HN 45676686).

The project’s narrative starts from an everyday limitation of agent sessions: exploration work, decisions, errors, and fixes get lost when a session closes or reconnects. In December 2025, Newman announced on X the availability of Cursor-Mem in Claude-Mem 8.5.0; the link to that announcement was picked up in HN 46429613, with 2 points and one comment. That is a signal that Cursor was an early extension, not confirmation of official Cursor backing.

Since then the scope has widened: cmem.ai’s integrations page includes more agents, MCP clients, and transcript captures. That expansion raises a practical tension: a memory that helps avoid repeating explanations can also store information the user doesn’t want propagated. That’s why the README includes <private> tags to exclude content, and why version 13.13.0 introduced a sensitive observation type.

Philosophy and principles

The documentation lays out five ideas that underpin the design:

• Continuity without manual intervention: hooks capture events and relevant context reappears automatically when sessions start or continue.
• Progressive disclosure: a compact index is fetched first; detail is retrieved only for the chosen identifiers. The README estimates savings of roughly tenfold versus pulling every observation.
• Search by meaning and by text: it combines SQLite’s FTS5 with Chroma to merge keyword matching and semantic retrieval.

• Local control and privacy: the local install keeps data on the machine; <private> lets you exclude fragments. Cloud sync is a separate offering.

• Integration through standards and adapters: MCP lets other clients query the memory, while per-environment adapters install the necessary hooks.

These are the project’s own design claims, not an independent audit of answer quality or token savings.

How it works

The documented flow has four main pieces:

1. Capture: six scripts tied to five lifecycle stages —SessionStart, UserPromptSubmit, PostToolUse, Stop, and SessionEnd— observe the agent’s activity. The installer also runs a dependency pre-check, which is not itself a lifecycle hook.

2. Processing and storage: a local process managed by Bun logs sessions, observations, and summaries into SQLite. Chroma supplies the vector index for semantic search. The worker’s web interface shows the memory flow in real time.
3. Retrieval: the MCP tools follow a three-layer sequence. search returns a cheap index of results; timeline places an observation within its chronology; get_observations fetches the full content for a list of identifiers. The README also mentions mem-search, a skill for natural-language queries.

4. Injection and later use: in the next session, the plugin selects and adds context according to the configuration. The user can query the history instead of relying exclusively on that automatic injection.

The official documentation lists Node.js 20 or higher, a recent version of Claude Code with plugin support, Bun, uv, and SQLite 3; the installer tries to provide Bun and uv if they’re missing. For other environments, the exact requirement depends on the corresponding adapter.

Official and semi-official status

Claude-Mem is a project independent of thedotmack. The sources gathered show no acceptance, certification, or endorsement by Anthropic, OpenAI, Cursor, Google, or Microsoft. Being installable from Claude Code via /plugin marketplace add thedotmack/claude-mem and /plugin install claude-mem demonstrates a distribution mechanism compatible with that marketplace, not a vendor certification.

Its semi-official status is clearer within its own offering: cmem.ai presents Claude-Mem as the open engine behind CMEM Cloud and links to documentation, changelog, Discord, and the repository. Interoperability with MCP is technical compatibility; it does not make Claude-Mem an official part of every MCP client it’s mentioned alongside.

The ecosystem

Project, service, and documentation

• thedotmack/claude-mem: main repository, local engine, plugins, and adapters.
• CMEM Cloud / cmem.ai: an optional commercial sync service; it advertises a replicated observation base and a private MCP link for authorized clients.
• ragtime/ inside the repository: a component licensed Apache-2.0 per the README. No sufficient evidence was found to describe it as an independent repository.
• workers/sync-hub, cursor-hooks, openclaw, plugin, and docs appear as directories of the main repository. They indicate the distribution bundles adapters and the sync service in the same tree, not several separate official repositories.

Ports, extensions, and forks found

The npm registry search turned up extensions that declare themselves compatible with or derived from Claude-Mem. They’re named as community projects; no author sponsorship is implied:

• Ephemushroom/opencode-claude-mem (@ephemushroom/opencode-claude-mem): a plugin for OpenCode; the npm registry showed 84 weekly downloads and version 0.4.4.
• mc303/claude-mem-opencode: OpenCode integration; 30 weekly downloads and version 0.1.4 on npm.
• bloodf/opencode-mem (@bloodf/opencode-claude-mem): an OpenCode adapter; 22 weekly downloads and version 1.2.0.
• ManuelStaggl/keepmind: described as a Node-only fork of Claude-Mem; 621 weekly downloads and version 3.3.2.
• sdsrss/claude-mem-lite: a lightweight alternative based on SQLite, FTS5, and TF-IDF; its description explicitly frames it as a lower-cost alternative, not an official branch; 1,728 weekly downloads and version 3.59.1.
• rumitvn/tre-mem: a branch-aware shared memory side layer on top of Claude-Mem; 67 weekly downloads and version 0.11.3.
• pencil-agent/pencil-mem: a port for nanopencil, per the registry; 10 weekly downloads and version 0.1.2.
• ArtemisAI/pi-mem (pi-agent-memory): an extension for Pi agents that declares itself powered by Claude-Mem; 24 weekly downloads and version 0.3.4.

The README also links translations of the project itself into Simplified and Traditional Chinese, Japanese, Portuguese, Korean, Spanish, German, French, Hebrew, Arabic, Russian, Polish, Czech, Dutch, Turkish, Ukrainian, Vietnamese, Tagalog, Indonesian, Thai, Hindi, Bengali, Urdu, Romanian, Swedish, Italian, Greek, Hungarian, Finnish, Danish, and Norwegian. Those pages are translated documentation, not separate translation repositories.

Repository numbers

Measurement: August 5, 2026, GitHub’s public page and npm.

Metric	Value retrieved
Stars	89.7k
Forks	7.8k
Visible commits	2,378
Visible branches	411
Visible tags	324
Visible open issues	209
Visible open pull requests	149
Latest release	v13.13.1, August 3, 2026
npm package	claude-mem 13.13.1
npm weekly downloads	12,620
npm monthly downloads	64,123
License	Apache-2.0

GitHub returned a rate limit on the API endpoints during this measurement; that’s why the figures for stars, forks, branches, tags, commits, issues, and pull requests are the ones visible on the public page, not an API extraction. Real subscriber counts and a reliable contributor ranking could not be retrieved, so they’re omitted. The issue count shown in the interface is separate from open pull requests on that page; the API’s open_issues_count field, when available, can mix both concepts.

Version 13.13.1 adds the interactive /mode-creator flow, which builds a custom mode from the user’s domain and note-taking needs. 13.13.0 adds the sensitive type and configurable Telegram alerts. These are changes described by the project in its own changelog.

How to contribute

The README lays out a conventional, verifiable flow: fork the repository, create a feature branch, make changes with tests, update the documentation, and open a pull request. It also documents three release branches: main for stable releases published to npm, and core-dev and community-edge for running early fixes and community integrations from source.

There are signs of intense review discipline. The 13.12.2 changelog states that 157 open pull requests were evaluated against a public rubric in docs/merge-rubric.md; 13.12.4 declares 2,539 passing tests and none failing for its bugfix cycle. These are the maintainer’s own results and rules, not an external verification.

Quick usage guide

Installation and first run

1. Install for Claude Code:

   npx claude-mem install

2. Or install from the plugin marketplace inside Claude Code:

   /plugin marketplace add thedotmack/claude-mem
   /plugin install claude-mem

3. Restart Claude Code. According to the README, observations from previous sessions will start appearing automatically in new sessions.

For OpenCode, the documented command is npx claude-mem install --ide opencode; for Antigravity CLI, npx claude-mem install --ide antigravity. Don’t use npm install -g claude-mem for the first run: the README clarifies that it installs the library but doesn’t register the hooks or configure the worker.

Common workflows

• Look up a previous decision or bug: run search(query="authentication bug", type="bugfix", limit=10), review the index, and request detail with get_observations(ids=[123, 456]). The identifiers are examples from the README; they should be replaced with the ones returned by the search.
• Reconstruct the sequence of a change: use timeline around a found observation to retrieve chronological context without loading the entire history.
• Query the memory from an MCP client: connect the compatible client and use the search, timeline, and get_observations tools. The integrations page lists Claude Code, Cursor, Windsurf, OpenCode, OpenClaw, Codex CLI, Gemini CLI, and VS Code.
• Exclude sensitive data: wrap content that shouldn’t be stored with the <private> tags documented in the README.

Essential configuration

The first file a Claude Code install modifies is ~/.claude-mem/settings.json, created with default values. The documentation states it holds, among other things:

• the AI model or provider;
• the local worker’s port;
• the data directory;
• the log level;
• context injection rules;
• CLAUDE_MEM_MODE, which selects the mode and language of observations, e.g. code--zh;
• CLAUDE_MEM_TELEGRAM_TRIGGER_TYPES, which controls which types trigger Telegram alerts.

After changing CLAUDE_MEM_MODE, the README asks you to restart Claude Code. Modes are stored in plugin/modes/; the documented local path to inspect them is ~/.claude/plugins/marketplaces/thedotmack/plugin/modes/.

Common pitfalls and fixes

• The npm command doesn’t exist on Windows: the README attributes the error to Node.js/npm missing from the PATH. Install Node.js, restart the terminal, and repeat the install.
• The global package installed but the plugin doesn’t work: replace npm install -g claude-mem with npx claude-mem install or the marketplace commands, because the global package doesn’t activate the hooks or the worker.
• Worker restart loop after updating: the 13.12.3 changelog documents that earlier versions could recreate a stale process on a version mismatch. The published fix is to update; the first hook of the fixed version terminates the stale process and takes over.
• Data that shouldn’t reappear: use <private> before the content gets captured. For information that isn’t strictly private but shouldn’t leak into future write-ups, review the sensitive type and the notifications added in 13.13.0.
• Maintainer guidelines accidentally included in marketplace installs: the 13.12.4 note explains this was fixed by moving local notes to CLAUDE.local.md. Staying on a current version reduces exposure to that historical bug.

Integrations and migration

The most direct migration path from an existing Claude Code install is to install the new environment’s adapter with --ide where it exists and keep the local configuration. For other clients, interoperability relies on MCP and the search tools. CMEM Cloud adds cross-machine sync and a private MCP link, but it’s optional and paid.

Community extensions for OpenCode, Pi, and nanopencil show alternative paths, though their compatibility and maintenance should be verified per project. No official guide promising automatic migration from Mem0, Zep, Letta, LangMem, Cognee, OpenAI Memory, or Supermemory was found; the website lists them as comparisons, not import procedures.

How the community received it

The recoverable reception on Hacker News is small compared to the GitHub figures:

• HN 47558167, submitted by perelin on March 28, 2026, linked directly to the repository under the title Claude-Mem. It reached 2 points and 1 comment. The listing describes the product as automatic capture of Claude’s activity, compression via the agent SDK, and context injection into future sessions. It’s a descriptive listing, not an independent positive review.
• HN 46229436, submitted by handfuloflight on December 11, 2025, linked the same repository and got 1 point and 0 comments. It’s early discovery, not community consensus.
• HN 45676686, by thedotmack, received 11 points and 1 comment for linking the r/ClaudeCode post about the context management plugin. The Reddit content couldn’t be retrieved automatically because the page returned an issue link; that’s why no Reddit opinions that couldn’t be read are attributed.
• HN 46429613, also by thedotmack, linked the X announcement for Cursor-Mem/Claude-Mem 8.5.0: 2 points and 1 comment. X did not allow the direct content to be retrieved without authentication; only the title, link, and metric served by HN are preserved.

The most concrete technical criticism recovered comes from the changelog itself, not a third party: 13.12.4 acknowledges that internal maintainer guidelines had reached marketplace installs and could be obeyed by user instances. The project moved that material to CLAUDE.local.md. It also documented blocked-port failures, foreign-key migrations, and worker loops. These are maintenance fixes, not proof that the system is insecure in its current version.

Searches were attempted on HN by name, author, and Cursor-Mem; direct Reddit; X via the linked announcement; YouTube; Product Hunt; Dev.to/Hashnode; podcasts; and curated lists. In this run, no verifiable reviews, videos, Product Hunt launch, newsletter mentions, or direct threads were recovered on those channels. The absence of recovered material doesn’t measure quality or rule out its existence.

Claude-Mem versus other proposals

Proposal	Verifiable overlap	Verifiable difference or limit
sdsrss/claude-mem-lite	Both offer persistent memory for Claude Code.	The package presents itself as a lighter alternative, with a single SQLite base and FTS5 + TF-IDF; Claude-Mem additionally documents Chroma and a Bun worker.
ManuelStaggl/keepmind	The npm registry describes it as a fork of Claude-Mem for persisting context.	Keepmind declares itself a Node-only fork; no feature comparison maintained by both projects was found.
rumitvn/tre-mem	It builds on Claude-Mem as a memory layer for coding agents.	Tre-mem positions itself as a shared, branch-aware side layer; that approach isn’t described as a core function of Claude-Mem itself.
Mem0, Zep, Letta, LangMem, Cognee, OpenAI Memory, and Supermemory	CMEM’s website lists comparison pages against all of them.	Those comparisons and equivalent test metrics weren’t retrieved; no functional superiority is claimed.

Use cases and who this repository can help

• Developers who switch between long Claude Code sessions: the hooks, SQLite, summaries, and context injection aim to preserve decisions, diagnostics, and exploratory work when a session restarts.
• Teams or individuals who move between terminal, IDE, and agents: the documented MCP support and adapters for Cursor, OpenCode, Codex CLI, Gemini CLI, Windsurf, and OpenClaw offer a way to query the same memory from more than one tool; CMEM Cloud extends that to cross-machine sync if purchased.
• People researching a large codebase: the search → timeline → get_observations pattern lets you locate a fact and expand only the necessary context, instead of loading the entire memory at once.
• Users with privacy or traceability requirements: the <private> tags, local storage, and the sensitive type provide explicit controls, though they require the user to tag the material and review their configuration.
• Maintainers of agent integrations: the community adapters for OpenCode, Pi, and nanopencil, along with the MCP protocol, show how to extend the engine, but those extensions don’t amount to official support and should be evaluated separately.

Resources

• Repository: https://github.com/thedotmack/claude-mem
• Documentation and installation: https://docs.claude-mem.ai/introduction
• Architecture and search: https://docs.claude-mem.ai/introduction
• Official changelog: https://cmem.ai/changelog
• Integrations: https://cmem.ai/integrations
• npm package and metrics: https://www.npmjs.com/package/claude-mem
• CMEM Cloud service: https://cmem.ai/
• Discord community: https://discord.gg/J4wttp9vDu
• HN discussions: https://news.ycombinator.com/item?id=47558167, https://news.ycombinator.com/item?id=46229436, https://news.ycombinator.com/item?id=45676686, https://news.ycombinator.com/item?id=46429613
• X announcement linked by HN: https://twitter.com/Claude_Memory/status/2005856998919700833

---

Note: this article combines the README, official documentation and website of Claude-Mem/CMEM, GitHub’s public pages, the npm registry, and Hacker News results retrieved on August 5, 2026. Figures change over time; access limitations are noted where they affect the data.