Welcome

memo-mcp gives your AI assistant a memory it can show its work from.

You tell Claude something once: how your team deploys, why a decision was made, which version of a library you use. Claude saves it. Next week, in a new conversation, Claude finds it again and tells you exactly where the answer came from, who wrote it down, and when.

Everything lives in one file on your own computer. Nothing is sent to a cloud service.

Who this is for

• People who work with Claude every day and are tired of explaining the same background in every new conversation.
• Teams and project leads who want decisions, conventions and hard-won answers to stay findable, with a clear record of where each one came from.
• Anyone who cares where an answer came from. Every result carries its source, and you can ask why it was chosen.

What it is not

• It is not a chat app. You keep using Claude as usual; memo-mcp works in the background.
• It is not a cloud service. There is no account, no subscription and no upload.
• It does not browse the web. Claude finds information and hands it over to be saved.
• It does not decide what is true on your behalf. Notes Claude writes are marked as Claude’s until you say otherwise.

How to read this guide

Running it for others, or want the technical details? The operator guide covers installation options, every setting, tuning and monitoring.

Why it matters

The problem: an assistant that forgets

AI assistants are good at reasoning and poor at remembering. Each new conversation starts from zero. So people paste the same background again and again: the project layout, the team’s conventions, the decision made last month and the reason for it. Time goes into re-explaining instead of working. When the assistant guesses instead, it can sound confident and still be wrong.

What changes with memo-mcp

Answers come with receipts. Every answer from the memory carries its source: which document, which passage, who saved it and when. You can open the original in one step. You can also ask why that passage was chosen over the others. The memory explains its own ranking in plain terms.

You stop repeating yourself. Save a document, a decision or a single fact once. Claude looks it up when it is relevant, in this conversation or one months from now.

Corrections keep their history. When a fact changes, such as “we moved from Postgres 15 to 16”, the new fact replaces the old one. The old one is kept as history. You can always ask what was believed on a given date.

You stay in charge of what counts as reliable. Anything Claude saves on its own is labelled as Claude’s work. Only you can mark something as checked. Claude can ask, but it cannot do it itself. See Trust.

It stays on your machine. The memory is one file on your computer. It works offline after a one-time download, and it sends nothing anywhere. See Privacy and safety.

It costs nothing to run. It is free and open source under the MIT licence. It needs no server, no database to install and no paid service.

Where it pays off

More examples are in Use cases.

How it compares to Claude’s built-in memory

Claude Code and the Claude apps have their own memory features. For many people those are the right default, and they need no setup.

memo-mcp is for when you want more than that:

• to see and check what the memory holds, in a browser or as plain files;
• to know why a particular answer came back;
• to keep separate memories for separate projects or clients;
• to keep a full history of what changed and when;
• to make sure nothing leaves your computer.

The two can be used side by side.

Quick start

This takes about ten minutes. At the end, Claude will have a memory, and you will have saved your first note and asked your first question.

What you need

• A Mac, Linux or Windows computer.
• Claude Code, or the Claude Desktop app.
• About 200 MB of free disk space for the program and its one-time download.

Step 1: Download memo-mcp

1. Open the releases page.

2. Download the file for your computer:

   Your computer	File name contains
   Mac with Apple silicon (M1 and newer)	darwin_arm64
   Mac with Intel	darwin_amd64
   Linux	linux_amd64 or linux_arm64
   Windows	windows_amd64

3. Unpack it. Inside is a single program called memo-mcp (or memo-mcp.exe on Windows).

4. Move it somewhere permanent, for example a bin folder in your home folder. Note the full path; you need it in the next step.

To check that it runs, open a terminal and type the path to the program followed by version:

~/bin/memo-mcp version

You should see a version number. On a Mac, if you see a warning that the developer cannot be verified, open System Settings → Privacy & Security and choose Allow Anyway.

Step 2: Connect it to Claude

Choose a name for this memory. One memory per project works well, for example my-project.

Claude Code

Run this once in a terminal, with your own path and name:

claude mcp add memo --env MEMO_KB=my-project -- ~/bin/memo-mcp

Claude Desktop

Open Settings → Developer → Edit Config, add the memo entry below and save. Use the full path to the program; ~ does not work here.

{
  "mcpServers": {
    "memo": {
      "command": "/Users/you/bin/memo-mcp",
      "env": { "MEMO_KB": "my-project" }
    }
  }
}

Then quit Claude Desktop completely and open it again.

Step 3: Check that Claude sees it

Start a new conversation and ask:

What is in my memo knowledge base?

Claude should answer that the memory is empty, or list what it holds. In Claude Code, the /mcp command also lists memo as connected.

The first start downloads a language model. It is about 140 MB, happens once, and takes a minute or two. Until it finishes, searching still works by matching words, and Claude may mention that search is “degraded”. Notes saved during that time are fully searchable once the download completes. This is the only time memo-mcp uses the internet.

Step 4: Save your first note

Tell Claude something worth keeping, and ask it to save it:

Save this to memo: we deploy on Tuesdays only, and the release owner runs the smoke tests before tagging.

Claude confirms it was saved and gives it an address that starts with memo://. That address is how you and Claude point at this exact note later.

You can also hand over a whole document:

Read docs/architecture.md and save it to memo as project documentation.

Step 5: Ask your first question

Start a new conversation, so Claude cannot simply remember the last one, and ask:

When do we release? Check memo.

Claude finds the note, answers, and names the source. To see how it decided, ask:

Why did that result come first?

You are set up

• Learn what to say day to day in Everyday use.
• Open the memory in a browser: Looking inside.
• If something did not work, see Questions and troubleshooting.

Everyday use

You use memo-mcp by talking to Claude. There are no special commands to learn. Say what you want in your own words, and mention “memo” when you want Claude to use the memory rather than its general knowledge.

Tip. Claude works better with the memory once it knows the house rules. The project ships a short guide for Claude called SKILL.md. Put it in your project, or paste it into a conversation, and Claude will search before answering and save what it learns.

Saving documents and notes

What you can save

• Documents: design notes, guides, meeting notes, documentation pages Claude has read for you, or any markdown or text file.
• Notes: a few sentences about something worth keeping.
• Code explanations: how a module works, and why it was written that way.
• Conversations: a summary of a discussion and what was decided.

How to ask

Save this to memo as a note: the staging database is reset every Sunday night.

Read the file docs/runbook.md and save it to memo.

Fetch the gRPC Go documentation page on deadlines and save it to memo, as version 1.64.

Claude replies with an address such as memo://doc/01a1…. You do not need to remember it. Claude and the browser view use it to point at that exact document.

Good habits

• Say where it came from. When Claude saves a web page, it records the web address. When you dictate a note, it records that you said it. Later, every answer shows this.
• Say which version. For documentation about a tool or library, mention the version. Later questions about that version then get answers for that version, and not for an older one.
• Add one line of context to a long document, such as “This is the 2026 security policy for the payments team.” It helps the right passages surface.

Saving the same thing twice

Saving an identical document again does nothing, so there are no duplicates. Saving a changed version keeps both: the new one becomes current, and the old one stays in its history. You can always see what a document said on an earlier date.

Saving from the terminal

If you prefer, you can save files without Claude, for example a whole folder of notes:

memo-mcp ingest ~/notes/project-x

Things you save yourself this way are marked as yours. Things Claude saves are marked as Claude’s. Trust explains why that matters.

Asking questions

How to ask

Ask the way you would ask a colleague, and mention memo so Claude checks the memory first:

What does memo say about how we handle failed payments?

Check memo: which version of the gRPC library do we use, and what changed in it?

Claude searches and reads the most relevant passages. It then answers and names its sources.

What comes back

Each result carries:

• Where it came from: the document title and, for web pages, the original address.
• Who saved it: you, Claude, or a checked source. See Trust.
• When it was saved, and whether a newer version exists.
• How strong the match is: strong, moderate or weak. A weak match is a hint, not an answer, and Claude should treat it that way.

Asking why

Every search can explain itself. Ask:

Why did that come up first?

Claude can show which kinds of matching found each result. Some results match your exact words, some match a name or code identifier exactly, and some match the meaning even when the words differ. Claude can also show how each result scored. The same explanation is visible in the browser view. See Looking inside.

When nothing is found

If the memory holds nothing relevant, memo-mcp says so plainly and does not offer the closest guess. That is deliberate. “We don’t have this” is more useful than a confident wrong answer. Claude then knows to look elsewhere. Once it finds the answer, ask it to save it, so the next person does not have to search again.

Too many results

If a question matches a lot, the answer says that some results were left out and suggests how to narrow it, for example by version or by shelf. You can say:

Only look at version 1.64.

Only search the billing shelf.

Asking about the past

Because old versions are kept, you can ask what the memory said at an earlier date:

What did memo say our database version was on 1 March?

Facts and corrections

A fact is one short statement worth keeping on its own:

• “The API rate limit is 100 requests per minute.”
• “Alice owns the billing service.”
• “We use Postgres 16 in production.”

Facts are separate from documents because they are small, they change, and you often want the current one.

Recording a fact

Remember that the API rate limit is 100 requests per minute.

A good fact points to its proof. When Claude learns a fact from a saved document, it links the fact to the passage that says so. The fact then carries its own source.

You can also say how long a fact holds:

Remember that the office is closed from 23 December to 2 January.

Correcting a fact

When something changes, say so:

The rate limit is now 200 per minute. Update memo.

Claude records the new fact as replacing the old one. The new fact is current from now on. The old one is not deleted; it is kept as history with the date it stopped being true.

Looking back

What was the rate limit in January?

Show me the history of the rate limit fact.

The browser view has a facts timeline that shows the same thing at a glance. See Looking inside.

When facts disagree

Two facts can contradict each other, for example when two people recorded different numbers. memo-mcp notices this and lists it as something to resolve. See Keeping it tidy.

Forgetting things

Sometimes a note is wrong, out of date, or should never have been saved.

Asking Claude to forget

Forget the old onboarding note in memo; it describes the previous tooling.

Claude asks for, or supplies, a short reason. The note then disappears from searches.

Its address keeps working, though. Anyone who follows an old link to it sees that it was forgotten, when, and why, instead of a dead end. That keeps the record honest.

What Claude may and may not forget

Claude can only forget things Claude saved. Things you saved yourself, or marked as checked, can only be removed by you. This prevents a mistaken or misled assistant from deleting your own records.

To remove something yourself, use the terminal with the item’s address:

memo-mcp forget memo://doc/01a1... --reason "replaced by the 2026 policy"

Removing text completely

Forgetting hides an item and keeps its text in history. If text must be erased, for example a password pasted by mistake, add --redact:

memo-mcp forget memo://doc/01a1... --reason "contained a secret" --redact

The record that something was removed stays. The text itself is gone.

Keeping work separate

memo-mcp gives you two ways to keep things apart: shelves inside one memory, and separate memories.

Shelves: topics within one memory

A shelf is a label for a group of documents, such as billing, infrastructure or grpc-docs. Questions search every shelf unless you say otherwise, so shelves organise without hiding anything.

Save this on the billing shelf.

Only look on the infrastructure shelf.

Use shelves for topics within one project or team.

Separate memories: one per project or client

Each memory is its own file. Nothing in one can be found from another. Use separate memories when the contents must not mix, for example for different clients, or for work and personal notes.

The memory’s name is set when you connect memo-mcp to Claude. It is the MEMO_KB value in Quick start, step 2. To add a second memory, add memo-mcp again under another name:

claude mcp add memo-client-b --env MEMO_KB=client-b -- ~/bin/memo-mcp

In Claude Code, you can also set a memory per project folder, so each project automatically gets its own. The operator guide shows how.

Trust: who vouched for what

Every item in memo-mcp carries a trust level. It answers one question: who has vouched for this?

The level appears next to every search result, in the browser view and in what Claude tells you.

Why Claude cannot raise trust by itself

If an assistant could mark its own notes as verified, the label would mean nothing. A web page with misleading instructions could also persuade it to “verify” something false. So memo-mcp has one firm rule: only a person can raise trust.

Claude can ask. When it believes a note deserves more trust, it requests a promotion, and one of two things happens:

• Your app shows a dialog. It contains the passage, where it came from and the level requested. Nothing changes unless you press accept.

• Your app cannot show dialogs. Claude gives you a short command to run yourself, for example:

  memo-mcp trust promote memo://doc/01a1... --to user
  

Every change of trust is recorded: who made it, when and why.

Warning. Some setups can be configured to accept every dialog automatically. If you do that, the trust labels lose their meaning. Treat everything as agent level.

Lowering trust

If something you trusted turns out to be wrong, lower it:

memo-mcp trust demote memo://doc/01a1... --to agent

How trust affects answers

Trust does not change how relevant a result is. A note Claude saved can still be the best match. What trust changes:

• You can see it. Every answer shows whether it rests on something a person checked, or only on Claude’s own notes.

• You can require it. Ask Claude to use only items at or above a level:

  Answer only from items a person has checked.

• It settles ties. When two facts disagree, the one with higher trust is preferred, then the newer one.

Looking inside

memo-mcp includes a browser view of your memory. It shows everything Claude can see, in the same order Claude would see it. It is read-only: nothing on it can change your memory, so it is safe to explore.

Opening it

In a terminal, using the same memory name as in your Claude setup:

MEMO_KB=my-project memo-mcp ui

It prints an address such as http://127.0.0.1:54750. Open it in your browser. The page is only reachable from your own computer. Press Ctrl-C in the terminal to stop it.

What you can do there

When it helps

• Before you rely on an answer, open its source and read it in context.
• When results seem off, run the same search here and look at the “why” table.
• To show someone else what the team’s memory knows, without giving them Claude.
• To check what Claude saved during a long session.

Keeping it tidy

A memory that grows for months collects loose ends:

• facts that contradict each other;
• two names for the same thing, such as “Postgres” and “PostgreSQL”;
• near-duplicate notes;
• topics mentioned in many places but never summarised.

memo-mcp finds these. It does not fix them on its own. Claude does the writing, and you decide anything that matters.

Asking Claude to tidy up

Tidy up the memo knowledge base.

Claude asks memo-mcp for a to-do list. Each item comes with the material needed to handle it:

• Write a summary page for a topic mentioned in many places. Claude writes it from the saved passages. Each sentence points back to its source.
• Refresh an out-of-date page. A summary is marked stale when a document it was based on changes.
• Resolve a contradiction between two facts by keeping the right one.
• Merge two names that mean the same thing.

Checks on every summary

When Claude hands a summary back, memo-mcp checks it before keeping it:

• Did it leave anything out? Important facts about the topic that the page does not mention are reported.
• Did it make anything up? Sentences that the sources do not support are flagged.
• What changed? For a refreshed page, you see the difference from the previous version.

Summary pages are always labelled as written by Claude, with their sources listed, so they never pass for original material.

Decisions that stay with you

Merging two names and settling contradictions affect what the memory treats as true. Claude can propose them, and you can confirm them in the conversation or from the terminal. Nothing is merged silently.

Tip. Once a month, ask “Is there anything in memo that needs my decision?” Claude will list the open items.

Use cases

Project memory for a codebase

The situation. Every Claude session on your project starts by re-reading the same files and re-learning the same conventions.

With memo-mcp. Save the architecture notes, conventions and “why we did it this way” explanations once. Claude looks them up when they are relevant. When the code changes, ask Claude to save the new version. The old one stays as history.

At the end of a working session: “Save to memo what we learned today about the payment retry logic, and why we chose exponential backoff.”

Documentation pinned to the version you use

The situation. Libraries change between versions, and assistants mix them up.

With memo-mcp. Have Claude fetch and save the documentation for the exact version you use, labelled with that version. Questions then get answers for your version.

“Fetch the gRPC Go docs on deadlines for version 1.64 and save them to memo.”

Team decisions and their reasons

The situation. Six months later, nobody remembers why a decision was made, and it gets argued again.

With memo-mcp. Save each decision with its reason and date. Record the outcome as a fact. When it changes, record the new fact as replacing the old one. The history shows when and why.

“Remember that we chose Postgres over MongoDB on 12 May because we need transactions across accounts. Link it to the meeting notes.”

Research notes

The situation. You read many sources, and later cannot find which one said what.

With memo-mcp. Have Claude save each source with its address and a one-line context. Ask questions across all of them. Every answer names its source, and you can open the exact passage.

Onboarding a new teammate

The situation. A new person spends weeks absorbing knowledge nobody wrote down.

With memo-mcp. The team’s memory is already there. The newcomer can browse it in the browser view or ask Claude questions against it. Trust labels show which answers a person has checked.

Support and operations runbooks

The situation. During an incident, you need the procedure that is current now.

With memo-mcp. Save runbooks and record key facts, such as on-call contacts, limits and endpoints. Facts that change are corrected rather than duplicated, so the current answer is always the one that comes back.

Privacy and safety

Where your information lives

Everything is stored in one file on your computer, in a folder called .memo-mcp in your home folder. Only your user account can open that folder. There is no cloud copy, no account and no sync.

What leaves your computer

Almost nothing. The first time memo-mcp starts, it downloads a language model of about 140 MB from Hugging Face, a public model library. That is the only time it contacts the internet. After that it works fully offline.

memo-mcp itself never visits websites. When you ask Claude to save a web page, Claude fetches it and hands over the text.

There is no telemetry, no usage reporting and no analytics.

Two things to be aware of

1. The memory file is not encrypted. Anyone who can open files in your home folder can read it. Do not store passwords or secrets in it. If you saved one by mistake, remove it completely; see Forgetting things.
2. Claude sees what it saves and searches. The words go through Claude, as everything in a conversation does. memo-mcp adds no extra exposure, but it does not hide anything from Claude either.

Safety rules built in

• Claude cannot vouch for itself. Only a person can raise an item’s trust. See Trust.
• Claude cannot delete your records. It can only remove what Claude saved.
• Nothing is silently overwritten. Changes create new versions, and the old ones stay in history.
• The browser view cannot change anything, and it is only reachable from your own computer.
• The optional activity log is off by default. If you turn it on, it records which tools were used and how long they took, but never the text you saved or read.

Backing up and moving

Your memory is a single file, so backing it up is copying it. See Questions and troubleshooting for moving it to another computer.

Questions and troubleshooting

Claude doesn’t seem to see memo

• Claude Code: type /mcp. memo should be listed as connected. If it shows an error, the message usually says what is wrong.
• Claude Desktop: quit it completely, not just the window, and open it again. Check that the path in the settings file is the full path to the program, starting with / on a Mac or C:\ on Windows.
• On a Mac, the program may be blocked the first time. See Quick start, step 1.

It found nothing

• It may really not be there. memo-mcp says “nothing found” instead of guessing. Ask Claude to save the answer once it finds it elsewhere.
• You may be looking in a different memory. Each memory has a name. If Claude was set up with my-project and you saved things under another name, they are in a different file. Ask Claude “What is in my memo knowledge base?” to see which one it uses.
• The question may be limited to one shelf or version. Ask again without the limit.

Results feel off

• Ask “Why did that come first?” The explanation often shows the cause: an old note, a weak match, or the wrong version.
• Open the same search in the browser view and look at the sources.
• Save a better source, or correct the fact. Old, wrong notes can be forgotten; see Forgetting things.

Claude says search is “degraded”

The language model that matches by meaning is not ready. This is normal for a few minutes after the first start, or after switching models, while it downloads or catches up. Search still works by matching words. If it lasts, the computer may have no internet access for the one-time download. Ask whoever set it up, or see the operator guide.

Is my information sent anywhere?

No. See Privacy and safety. The only download is the one-time language model.

Can I move my memory to another computer?

Yes. Your memory is one file:

1. Close Claude on the old computer, so the file is not in use.
2. Copy the file from the .memo-mcp/kb folder in your home folder. Its name is the memory name followed by .db, for example my-project.db.
3. Install memo-mcp on the new computer (Quick start), and put the file in the same folder there.

The language model downloads again on the new computer the first time.

How do I back it up?

Close Claude, then copy the same file somewhere safe. To back it up while Claude is open, see Backup and restore in the operator guide.

Can several people share one memory?

memo-mcp is built for one person on one computer. A team can share by exporting the memory as documents, or by having one person curate a memory others browse. Simultaneous use over a network drive is not supported.

Can I read my memory without Claude?

Yes. Use the browser view. An operator can also export everything as ordinary documents that open in any editor or in Obsidian.

Where do I get help?

Open an issue on GitHub. Describe what you asked and what happened, but do not include anything private.

Words we use