How to Install and Use Claude-mem
This guide is based on the open-source project Claude-mem by thedotmack, licensed under Apache-2.0. StackGuide AI is not affiliated with Claude-mem.
Claude-mem gives a coding agent a memory that survives from one session to the next. It captures what the agent did during a session, compresses it with AI, and injects the relevant context back into future sessions, so a new session does not start from zero on a project it has already worked on. As of October 31, 2026, its GitHub repository has 107,330 stars.
What claude-mem is, and who it is for
Under the hood it has four parts: lifecycle hooks that observe a session, a local worker service with a web viewer, a SQLite database for sessions and summaries, and a vector database for search. On top of that sits a mem-search skill and MCP search tools that follow a three-layer pattern: search for a compact index, look at the timeline around an interesting result, and only then fetch the full details for the IDs you filtered to. The README presents that filtering as roughly a tenfold token saving compared with fetching everything up front; treat that as the project's claim about its own design, not as a measurement StackGuide AI made.
It suits developers who work on the same codebase across many agent sessions and keep losing context between them. It is not a chat history viewer on its own, and it is not a replacement for version control, tests, or written documentation: memory helps the agent recall decisions, but the code and the docs remain the source of truth.
One decision matters before you install: where the memory lives. The installer asks you to sign in, which provisions a memory key and unlocks the hosted claude-mem observer with a 30-day free trial, after which the README says memory falls back to your Anthropic plan unless you subscribe. A local observer is opt-in instead. If you want memory to stay on your own machine, choose the local path in Step 1 and read the privacy implications before accepting any hosted default.
Prerequisites
- A supported agent: Claude Code is the primary case in the README, with install flags for OpenCode, T3 Code, Antigravity, Oh My Pi, Pi and DeepSeek Harness, plus an OpenClaw gateway installer.
- Node.js for the installer: installation runs through
npx, so Node.js must be available on your machine. - A memory provider choice: decide before installing whether you will sign in to the hosted observer, use your own OpenRouter or Gemini key, use your Anthropic plan, or run the local observer. The installer asks, but answering in advance avoids accepting a default you did not want.
- Privacy boundaries: decide what must never be stored. The README notes
<private>tags to exclude sensitive content from storage; use them for secrets, credentials and anything else that should not enter a memory database.
Step 1: Install claude-mem
The single command for the default install is:
npx claude-mem installThe installer sets everything up first, then asks you to sign in in your browser with an email magic link, which the README says requires no card. If you prefer to skip the sign-in, pass an explicit --provider flag, set CLAUDE_MEM_ONLINE_OPTIN=false, or run in a CI or non-interactive shell, and the installer completes without any account interaction.
For a specific agent, use its flag. Examples from the README:
npx claude-mem install --ide opencode
npx claude-mem install --ide antigravity
npx claude-mem install --ide piOr, inside Claude Code, install from the plugin marketplace:
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-memRestart the agent after installing. Context from previous sessions should then appear automatically in new sessions.
Do not substitute npm install -g claude-mem for the installer. The README warns explicitly that the global npm package installs the SDK and library only: it does not register the plugin hooks or set up the worker service.
Step 2: Try a memory search in a new session
Start a fresh session on a project you have already worked in, and ask the agent about something it did in an earlier session, for example a bugfix or a decision it recorded. The agent should search memory, show you the compact index first, and fetch details only for the results it needs.
Then open the worker's web viewer at the URL printed on startup, where memory, sessions and settings remain at /viewer. Check that what was stored matches what you expected to be stored, and that anything you marked private is absent. If the stored record is wrong or too broad, fix the privacy tags and the project's configuration before relying on memory for real work.
Common problems and fixes
| Problem | Fix |
|---|---|
| Nothing from a previous session appears | Restart the agent after installing, start a new session rather than continuing an old one, and check the worker is running. Hooks only capture sessions that run after installation. |
| You installed with npm globally and nothing works | That installs the SDK only. Run npx claude-mem install or the plugin commands above instead, as the README instructs. |
| You did not want a hosted account | Re-run the installer with an explicit --provider flag, or set CLAUDE_MEM_ONLINE_OPTIN=false, and check the official docs for the local observer setup. Do not assume a sign-in you already completed has been undone; check the provider setting in the viewer. |
| Sensitive content was stored | Mark it with <private> tags going forward, check the official docs for how stored observations are removed, and rotate any credential that was captured. |
| OpenCode does not pick it up | The README requires OpenCode 1.3.4 or later for its flag, and a restart after installing. Check both before troubleshooting further. |
FAQ
Does claude-mem replace my notes or docs? No. It recalls session observations and summaries; project decisions that matter should still live in the repository, in docs and in commit messages, where a human can read them without an agent.
Is the memory really local? It depends on the provider you chose. The local worker and SQLite database are local, but the default installer path signs you in to a hosted observer with a trial. If local-only matters to you, choose the local observer explicitly and verify the provider setting.
What happens when the trial ends? According to the README, memory automatically falls back to your Anthropic plan unless you subscribe. Check the official docs for the current trial and pricing terms before depending on the hosted path.
Can I use it with more than one agent? Yes, with a separate install flag per agent, as listed in Step 1. Each agent's hooks and provider setup are its own configuration.
Licence and attribution
Claude-mem is licensed under Apache-2.0. In plain terms, and not as legal advice: you may use, modify and distribute it, including commercially, provided you keep the licence and attribution notices, state significant changes, and respect the patent grant and its limits in the licence text. The README also notes a separate licence file for its ragtime/ directory and points to its own licence and IP-boundary docs for the open versus commercial boundary, so read those before embedding claude-mem in a product you sell.
What to try next
Once a new session recalls an old decision correctly, test the boundary that matters most: ask about a decision, check the timeline around it, and confirm the full observation matches what actually happened. Memory that is approximately right is worse than no memory if you act on it without checking.
This guide was checked against the official README and repository as of October 31, 2026. StackGuide AI did not run this tool for this guide, so this guide makes no claim based on running the tool; the commands below are the ones the official README publishes.