CLAUDE.md is not enough: why I built a local-first memory MCP for Claude Code

Luís Monteiro — Sun, 26 Apr 2026 21:34:14 +0000

I use Claude Code a lot.

One thing kept annoying me: not the mistakes, not the occasional wrong assumption, not even the weird confidence.

The annoying part was having to re-explain the same project context in new sessions.

Things like:

this module looks legacy but still supports a critical flow
this query already caused performance issues
this test failed before because the hook returned formatted text, not an array
this architecture decision looks strange, but it exists for a reason
this project separates bugs from improvements in release notes
do not touch this config unless you understand the install flow

Some of that belongs in CLAUDE.md.

But not all of it.

The problem with putting everything in CLAUDE.md

CLAUDE.md is great for stable project instructions:

how to run the project
how to run tests
coding conventions
architecture guidelines
commands the agent should know
repo-specific workflows

That kind of context is stable and broadly useful.

The problem starts when CLAUDE.md becomes the place for every pitfall, debugging note, warning, workaround, decision, and preference.

At that point, it stops being onboarding context and becomes a giant context dump.

That creates two problems.

First, every new session pays for it in tokens, even when the current task only needs one small detail.

Second, the more context you throw in, the easier it is for the important bit to get ignored.

More context is not always better context.

Sometimes it is just a bigger haystack with the same needle inside it.

The split that made more sense to me

I started thinking about project context as two different things:

CLAUDE.md = stable onboarding instructions
working memory = retrieved project-specific notes

CLAUDE.md should explain how the project works.

Working memory should remember what happened while working on the project.

That includes things like:

decisions
facts
patterns
pitfalls
architecture notes
project preferences
session summaries

The key difference is that working memory should not be dumped into every prompt.

It should be searched, ranked, and injected only when relevant.

So I built Memento MCP

Memento MCP is a local-first MCP server that gives Claude Code and other stdio-MCP clients persistent project memory.

The basic idea is simple:

Store useful project knowledge as typed memories.
Search and rank memories for the current task.
Inject only the relevant memory into the agent.
Avoid turning every new session into a giant repeated context paste.

Default setup:

local SQLite
FTS5 search
no mandatory cloud account
no hosted vector DB

It also supports:

optional embeddings
team memory sync through git
Obsidian vault indexing
privacy controls
local web inspector

Example

Instead of adding this to CLAUDE.md forever:

The scheduling module looks legacy but still supports a critical production flow.
Do not rewrite it casually.
The pagination query caused performance issues before.
The release notes must separate bugs from improvements.

Those notes can live as typed memories.

Then, when the agent is working on the scheduling module or release notes, the relevant memory is retrieved.

When the agent is working on something unrelated, that context stays out of the prompt.

That is the part I care about most: reducing repeated context without losing important project knowledge.

GitHub:

https://github.com/lfrmonteiro99/memento-mcp

Docs:

https://lfrmonteiro99.github.io/memento-mcp

What I want feedback on

I am mainly trying to validate the workflow.

The questions I care about:

Does the CLAUDE.md vs working memory split make sense?
Would you trust an MCP server to inject memory into Claude Code?
What kind of project memory would you actually want an agent to remember?
What would make this annoying, unsafe, or too noisy?
Should memory be mostly explicit/manual, or should the agent be allowed to suggest memories automatically?

I built this because I got tired of re-explaining the same project context over and over again.

Not because agents need more magic.

They mostly need better memory, fewer repeated instructions, and less context shoved into every prompt like we are packing for the apocalypse.

Decoding Digital Privacy: Your Guide to Staying Safe Online in Portugal

Luís Monteiro — Fri, 28 Mar 2025 17:39:53 +0000

Check here: https://lpmonteiro.pt/blog/-OMID_PfzL4wr8H8zhOD

In today's hyper-connected world, our digital footprint expands with every click, search, and social media post. Ensuring your online privacy is paramount, and understanding your rights and available tools is crucial. This guide offers practical advice and insights into safeguarding your digital privacy in Portugal.

Understanding Portugal's Data Protection Laws

Portugal adheres to the General Data Protection Regulation (GDPR) of the European Union, providing robust protection for your personal data. This regulation grants you significant rights, including:

The Right to Access: You can request access to the personal data held about you by organizations.
The Right to Rectification: You can correct inaccuracies in your personal data.
The Right to Erasure ('Right to be Forgotten'): You can request the deletion of your personal data under certain circumstances.
The Right to Restrict Processing: You can limit how organizations use your personal data.
The Right to Data Portability: You can obtain your personal data in a structured, commonly used, and machine-readable format.
The Right to Object: You can object to the processing of your personal data for specific purposes, such as direct marketing.
The Comissão Nacional de Proteção de Dados (CNPD) is the Portuguese data protection authority responsible for enforcing GDPR. If you believe your rights have been violated, you can file a complaint with the CNPD.

Practical Tips for Enhancing Your Online Privacy

Beyond legal frameworks, proactive measures are essential for protecting your digital footprint:

Use Strong, Unique Passwords: Avoid easily guessable passwords and reuse the same password across multiple accounts. A password manager can help you generate and store complex passwords securely.
Enable Two-Factor Authentication (2FA): 2FA adds an extra layer of security by requiring a second verification method, such as a code sent to your phone, in addition to your password.
Review Privacy Settings: Regularly review and adjust the privacy settings on your social media accounts, search engines, and other online services. Limit the information you share publicly and control who can see your posts.
Be Mindful of What You Share Online: Think before you post! Information shared online can be difficult to remove and may be used against you in the future.
Use a Virtual Private Network (VPN): A VPN encrypts your internet traffic and masks your IP address, protecting your online activity from prying eyes, especially when using public Wi-Fi.
Keep Your Software Up-to-Date: Software updates often include security patches that address vulnerabilities exploited by hackers.
Be Wary of Phishing Scams: Be cautious of suspicious emails, messages, or websites that ask for your personal information. Never click on links or open attachments from unknown sources.
Use Privacy-Focused Browsers and Search Engines: Consider using browsers like Brave or Firefox Focus, and search engines like DuckDuckGo, which prioritize user privacy.
Regularly Clear Your Browsing History and Cookies: This helps prevent websites from tracking your online activity.

Resources for Further Information

For more in-depth information and resources, consider exploring the following:

Comissão Nacional de Proteção de Dados (CNPD): The official website of the Portuguese data protection authority.
European Data Protection Board (EDPB): Provides guidance and information on GDPR.
Privacy International: An organization that promotes and defends privacy worldwide.
Protecting your digital privacy is an ongoing process that requires vigilance and a proactive approach. By understanding your rights, implementing practical security measures, and staying informed about the latest threats, you can effectively safeguard your personal data and maintain control over your digital footprint in Portugal and beyond.