Home / Articles

Giving Claude Code a Memory: A Local MCP Plugin Called Memento

AI coding agents forget everything between sessions. Memento, a local MCP plugin for Claude Code, captures, scrubs, deduplicates and recalls project context.

Publisher: REACTAPP.TOP7 min read1502 words

This article is published in English.

Sources: My AI Coding Agent Keeps Forgetting Me — So I Gave It a Brain

Picture a Tuesday night around 11pm. Three hours into rewriting an authentication middleware with Claude Code, you and the agent have gone back and forth on a strategy pattern versus a plain factory. Both got tried, the factory won and session tokens finally thread through the new validation layer in a way that makes sense. It's one of those sessions where everything clicks and AI pair programming feels legitimate.

The next morning you open a fresh session and ask to pick up where you left off on the auth middleware. The reply is a cheerful offer to help, followed by a request to describe the project structure and goals from scratch.

Three hours of shared context, gone.

Everyone hits this

Use any AI coding tool for more than a week, whether it's Claude Code, Cursor, Copilot or Windsurf, and you'll run into it. Every session starts blank, and the routine gets old fast. The first 15 to 20 minutes go to re-explaining the project: here's the folder layout, here's how auth works, here's why Supabase beat building it in-house, and no, Redis was ruled out. Of course the tool doesn't remember. It can't.

You catch yourself starting sentences with "remember when we" and trailing off, because there's no "we" on the other side. For the AI there's no yesterday, only right now. It's like having your smartest coworker show up with total amnesia every morning.

The obvious fixes don't last

The first attempts are predictable. One is a huge CLAUDE.md file packed with pages of project context, ASCII architecture diagrams, coding conventions and file structure. That helps with basics, so the agent knows your framework and where routes live. What it can't hold is decisions. It won't know that approach A was tried last Wednesday and collapsed because of a race condition in the queue worker, which is exactly why approach B won. Knowledge like that piles up over days of working together, and a static markdown file can't keep pace, because the project moves and the file goes stale within a couple of days.

The second attempt is a running side document of things to tell the AI at the start of each session: key decisions, failed approaches, gotchas. It works after a fashion, but stop and think about what's happening. You're manually maintaining memory for a machine that writes code ten times faster than you do, and it needs you to act as its notebook.

Neither approach survives more than a week or two, and you end up spending more time managing AI context than writing code.

The real problem

These tools have no memory. That's the entire issue.

A human teammate is valuable for more than coding ability. They build up context. They know why Postgres got picked over Mongo, they remember the billing bug in January that came from timezone math and they recall the architectural decision three sprints back that explains why one module looks odd. The AI holds none of that shared history. By design, it's stateless.

When these tools were glorified autocomplete, that hardly mattered. Now they refactor whole modules, debug race conditions across services and help with real architectural calls. When something that capable can't recall yesterday's work, the frustration is hard to overstate.

So what if it could simply remember? Not through the brute-force route of pasting everything into the prompt, but with the AI pulling relevant context from past sessions by itself, based on what you're working on right now, without being asked.

Memento

That idea became Memento, named after the film. It's a Claude Code plugin, technically an MCP server, that gives the agent persistent memory across sessions. While you work, it captures architectural decisions, bug fixes and config changes in the background and stores them locally on your machine. At the start of a new session it surfaces whatever fits the task at hand.

The first time it worked looked like this. On Monday, you debug a race condition in a queue worker. The root cause is a missing lock, Claude helps fix it, and Memento saves the context without any effort from you. On Wednesday you're back in the queue worker for something unrelated and don't mention Monday at all. Claude brings up on its own that a race condition in this spot was fixed on Monday with a lockfile, and offers to check whether the two are related.

That's the moment it lands. The agent remembered something nobody told it, not because old context was pasted in and not because of an instructions file, but because it genuinely held memory of the previous session.

Under the hood

Capture. Two hooks run as you work. One fires after meaningful tool use, such as file edits and commands but not plain file reads. The other fires when the session ends and grabs a summary. It all happens in the background.

Scrub and tag. Before anything is stored, a redactor strips out API keys, tokens, passwords and AWS credentials. Then a tagger sorts the memory into a type, such as decision, error, architecture or config, using pattern matching. No LLM calls are involved in this step.

Deduplicate. Fifty variants of the same memory would just be clutter. Memento checks for exact duplicates with a hash, then runs a cosine similarity check for memories that mean the same thing in different words. If the newer version carries more detail, it replaces the older one.

Store. By default everything lands in local JSON files, with zero dependencies and nothing to configure. ChromaDB can be plugged in for proper vector search, and Neo4j for graph-based retrieval.

Recall. When a new session starts, Memento queries the stored memories semantically. It matches on meaning and not keywords, so a question about the login flow can pull up memories about session token validation even though the phrases share nothing.

Everything runs locally. The embedding model, all-MiniLM-L6-v2, executes on your own machine through Transformers.js, so no API calls are made and nothing leaves your laptop.

What gets remembered

Memory is tagged as it's captured. The categories include decisions (why X was chosen over Y), errors (what broke and how it was fixed), architecture (how components relate) and config (environment variables and deploy details), with eight in total listed in the README. The point is that Memento doesn't just hoard raw chat logs. It classifies context, so recall can be smarter about what matters right now.

Memories are scoped to a project by its git root, so notes from an API repository don't leak into work on the frontend. Cross-project search exists for when you want it.

Keeping data safe

The reliability engineering is somewhat generous. A circuit breaker stops a database hiccup from cascading, a write-ahead log means a crash mid-save won't lose the memory and an LRU cache serves as a fallback when the main storage is briefly unavailable. That may be overkill, but tools that silently drop data are a real irritation, and the aim is that anything Memento captured is still there.

Trying it

It's open source and published on npm. One command does the job:

npx memento-memory

That installs the MCP server, sets up the auto-capture hooks and patches your Claude configuration, so the next Claude Code session just works. A global install with npm install -g memento-memory is also an option, and the README lists the full setup choices.

Some manual commands are available too:

  • /recall searches your memories
  • /remember saves something explicitly
  • memory_health reports system status
  • memory_list browses what's stored

Why it matters

AI coding tools are in an odd spot. They can refactor whole modules, untangle complex bugs and reason about system architecture, yet they wake up each morning knowing nothing about you or your project. The more capable they become, the more that gap hurts, because you can sense how much better things would be with any continuity at all.

Memento is an attempt to close that gap. It has rough edges, and there are surely cases where it classifies something wrongly or misses context that should've been obvious. Still, starting a session where Claude already knows what happened last week is how this should have worked from the beginning. The missing memory was the bug.