When developing with Claude Code, many developers encounter a recurring pain point: the necessity to re-explain project context in every new session. This includes details like legacy modules supporting critical flows, queries that previously caused performance issues, specific test failures, the rationale behind architectural decisions, or project-specific conventions in release notes. Such contextual information often needs to be articulated repeatedly across sessions, proving inefficient and frustrating.
While some of this context belongs in a CLAUDE.md file, not all of it does. CLAUDE.md excels for stable project instructions, such as how to run the project, execute tests, coding conventions, architectural guidelines, commands the agent should know, and repo-specific workflows. This type of context is stable and broadly useful.
However, problems arise when CLAUDE.md becomes a dumping ground for every pitfall, debugging note, warning, workaround, decision, and preference. At that point, it ceases to be an effective onboarding guide and transforms into a sprawling context dump. This creates two primary issues: First, every new session incurs token costs for the entire CLAUDE.md, even if the current task only requires a small detail. Second, the more context provided, the easier it is for crucial information to be overlooked. More context is not always better context; sometimes, it merely creates a larger haystack with the same needle inside.
To address this, one developer conceptualized project context as two distinct entities: CLAUDE.md for stable onboarding instructions, and "working memory" for retrieved, project-specific notes. CLAUDE.md should explain how the project works, while working memory should recall what happened during project development, encompassing decisions, facts, patterns, pitfalls, architectural notes, project preferences, and session summaries. The crucial distinction is that working memory should not be indiscriminately dumped into every prompt; instead, it should be searched, ranked, and injected only when relevant to the current task.
Based on this approach, the developer built Memento MCP (Memory Context Provider). Memento MCP is a local-first MCP server designed to provide persistent project memory to Claude Code and other stdio-MCP clients. The fundamental idea is straightforward: store useful project knowledge as typed memories; search and rank these memories based on the current task; and then inject only the relevant memory into the AI agent. This mechanism efficiently prevents the common problem of repeatedly pasting large amounts of context into every new session.
Memento MCP's default setup utilizes local SQLite and FTS5 search, requiring no mandatory cloud account or hosted vector database. Furthermore, it supports optional embeddings, team memory synchronization via Git, indexing of Obsidian vaults, privacy controls, and a local web inspector, offering a comprehensive solution for intelligent context management.