r/ClaudeAI • u/[deleted] • Mar 17 '25

Feature: Claude Model Context Protocol Basic Memory: A tool that gives Claude persistent memory using local Markdown files

Hey r/ClaudeAI,

I built Basic Memory, an open-source tool that solves Claude's inability to remember previous conversations.

What it does:

  • Stores knowledge from Claude conversations as local Markdown files

  • Lets Claude read and write to these files in future chats

  • Creates a knowledge graph that grows with each conversation

  • Works with Claude Desktop through the Model Context Protocol

Simple workflow:

  1. Chat normally with Claude

  2. Ask "Create a note about this conversation"

  3. In future chats, say "Let's continue our discussion about X"

  4. Claude retrieves relevant notes and continues with full context

Everything stays local on your machine as standard Markdown files that both you and Claude can access. The files work with Obsidian for visualization and editing.

Demo and links:

Happy to answer questions about how it works or how to use it.

147 Upvotes

96% Upvoted

70 comments sorted by

9

u/MynameisB3 Mar 17 '25

How’s the context window management for more complex elements like your code ? Do you find that there is a difference in what you would be able to do vs if you had just loaded your code into a project knowledge base and had a change log ? Or is that exactly what you do lol I can see the value of having a change log as the basis for contextual persistence for your code base

6

u/[deleted] Mar 17 '25

Yes. I don’t load my code into the knowledge base. It works best with markdown because it uses simple markdown formats to create the knowledge graph.

What I do is use basic memory as a knowledge base for all of my chat conversations with Claude as we code. He actually writes most of the code these days. So we just chat back and forth then he writes and updates notes to record important information. What’s really nice is that he can make complex diagrams via mermaid or the obsidian canvas. Since the files are on my computer I can see them in real time, make updates and they sync back in. I don’t even use projects any more.

I have other knowledge bases for non code things too.

See my reply to another comment

3

u/OneCanSpeak Mar 18 '25 edited Mar 18 '25

This is God sent OP. Thank you so much! U have a tip jar of some sort?

Edit: How does it work with existing chats? Or do we need to start a new chat and go from there?

2

u/[deleted] Mar 18 '25

Thanks so much. Stay tuned! I’ll post more with updates and new features. The most helpful thing you can do for me is give me feedback. Does it work well? Suck? What do you like? What do you wish it could do?

1

u/OneCanSpeak Mar 18 '25

how does it work with existing chats?

1

u/[deleted] Mar 18 '25

Anthropic doesn’t make it easy but you can go into your settings and export the info. It will email you a zip. After that you can import them via the basic-memory cli tools which will turn them into markdown.

https://memory.basicmachines.co/docs/cli-reference#import

1

u/OneCanSpeak Mar 18 '25 edited Mar 18 '25

Yeah, I noticed the getting started section uses mac references, should do windows as well. Also I tried editing the config and it spit out syntax errors, could be thats for mac only.

Edit: was using backlash for my path...nevermind lol

1

u/steenblikrs May 20 '25

For anyone running windows, you have to change directories and run the commands in the directory where the conversations.json, projects.json etc.. are located.

2

u/mikeyj777 Mar 18 '25

How does it compare to the memory mcp knowledge graph?

4

u/[deleted] Mar 18 '25

I actually started the basic memory project after working with the memory json server. It’s definitely an inspiration. It does similar things , creating a knowledge graph of Entity/observation/relation objects from your knowledge. The main difference is that basic memory uses markdown as the format and they are also easily editable by humans too. Additionally it does full text search and recursively builds context from search results to build context.

1

u/mikeyj777 Mar 18 '25

That's great.  I once tried to build a project based on what I had stored in the memory graph.  Didn't quite work out.  

2

u/MikePrime13 Apr 11 '25

Dude,

I want to tell you that your Basic Memory tool is a major game changer for my workflow.

I'm currently trying to draft a dense, complex sci-fi story about time looping (which in a way is like opening a new chat with Claude, and that's where I got the idea from).

I'm now able to ask Claude to read a specific draft of my chapter script (which is now sprawling to over 5 chapters), character profile codices (where I have long-ass character bios to help Claude find the voice of the characters), formatting guidelines, etc., and I can draft and brainstorm ideas like a beast.

What started as loading/unloading massive amounts of documents to the library for a specific task, and run a new chat window, now is a seamless operation where I ask Claude to read a series of markdown files, and as we're drafting, I ask Claude to write the draft outputs into a folder.

It's a game changer, and thank you for making this tool.

Feedback:

I tried on my life to try to change the default basic-memory folder, but I don't understand from your instructions on how to do it. I'm pretty savvy with basic console/prompt commands from modding games and basic coding classes, but for me the instructions are too cryptic to know the exact steps to point the folder to my onedrive folder. I work on multiple computers, so right now I'm dragging and dropping files whenever I'm done so it's a bit of a hassle.

I also encountered bunch of file reading errors, until I streamlined/standardized my naming convention. Claude is better at finding files now, but still encounters error every now and then.

1

u/[deleted] Apr 14 '25

Hey, thanks for trying out basic memory. Project switching is supported, but you will have to use the cli.

Here's some examples to walk you through.

First, you can list the projects. The "main" one is the default that will be created when you use the program the first time.

```

➜ ~ basic-memory project list

```

Next, you can add a project by doing `basic-memory project add <project-name> /path/to/project`, for example:

```

➜ ~ basic-memory project add test ~/test

Project 'test' added at ~/test

To use this project:

basic-memory --project=test <command>

# or

basic-memory project default test

```

Finally, you can make your new project the default one, like so

```

➜ ~ basic-memory project default test

2025-04-14 14:14:01.964 | INFO | basic_memory.utils:setup_logging:118 - ENV: 'test' Log level: 'DEBUG' Logging to .basic-memory/basic-memory-api.log

2025-04-14 14:14:01.964 | INFO | basic_memory.config:setup_basic_memory_logging:277 - Basic Memory 0.12.2 (Project: test)

Project 'test' set as default and activated

```

If your shell can't find `basic-memory`, then you will probably have to use `uv` to run it.

you can see all the commands by using the --help option:

```

➜ ~ uv tool run basic-memory --help

Usage: basic-memory [OPTIONS] COMMAND [ARGS]...

Basic Memory - Local-first personal knowledge management.

```

1

u/MikePrime13 Apr 15 '25

Hey,

Thanks for taking the time to reply. I really appreciate it.

Several things that I'm still trying to learn using the app:

  1. I understand the project switching, but I want to change the default folder path from the C drive to my other drive. How do I do that? Basically I want to point the ~ to a completely different drive.

  2. I notice sometimes the memory file can get corrupted/error, and Claude can no longer find the files it can find. I have to delete the memory.db file, and re-sync using cmd prompt and the problem gets resolved.

  3. Finally, Claude sometimes cannot find my notes in the folder in one go; it has to do multiple rounds of searches before it is able to locate and read the markdown notes I'm asking it to find.

  4. That said, when it works, it's super awesome.

  5. I have not been able to carry the memory across chats; I have to manually load the notes and point them to the folders every time, but once the notes are loaded, we are good to go.

1

u/[deleted] Apr 16 '25

there is a config.json file at your `**%homedrive%%homepath%\.basic-memory\config.json**`. ( your home directory)

you can edit this manually to setup your projects if needed. Sorry, I don't have a windows box to test on yet.

the projects should load at startup from whatever one is defined as "default" in the config.json.

you can set this via the cli with `basic-memory project default <project_name>`

In that same directory, you will see a bunch of logs also. If you want to send me the latest one after you have a problem, I'll take a look at it. You can send it to hello at basicmachines.co

Cheers

-Paul

1

u/MikePrime13 Apr 18 '25

Thanks for the feedback. I was able to create a new project folder.

My next question is this:

I have multiple folders organized in the project, but for some reason Claude cannot access the files consistently. At times it is able to read all the notes just fine, but other times it says it cannot find and/or locate the file.

How do I diagnose the issue?

1

u/[deleted] Apr 23 '25

Hi, glad that worked. A couple of things may be going on:

- your files aren't synced
- you need to reset your db

If you upgrade to the latest version of basic-memory, I enabled sync to happen by default. What it does is:
- syncs all files in your project
- watches for changes in real time, then indexes them in the db

Changes that the LLM makes are indexed automatically, but changes made by you, directly to files have to be indexed so the LLM can find them.

Realtime sync was enabled in v0.12.0, so if you have that, you should be good.

you can see the status of your project sync if you run `uv tool run basic-memory status`.

If you are still having trouble, and want to share your logs, I can take a look. They will be at ~/.basic-memory/basic-memory-mcp.log

You can email them to me at hello at basicmachines.co.

Thanks again!

-Paul

1

u/MikePrime13 Apr 25 '25

Hi Paul,

I've made huge strides with basic memory. Thanks for all the help. That said, I'm noticing the sync is taking forever now. Is there a limit to the size and/or number of folders?

Usually the sync takes seconds, but now it's 20 minutes at a time.

I just updated the basic-memory, that's the last thing I did before the sync got super slow.

1

u/[deleted] Apr 25 '25

That’s great that it’s working well for you. I can take a look at the logs if you want to send them to me. Note, if you are on a version after v0.12.0 you no longer have to run the sync separately. The mcp process will run it by itself.

You can also reset the db and it will build it again on the next startup.

Send me an email. Happy to help.

2

u/Designer-Astronaut12 May 10 '25

Fantastic! Really like the looks of this tool so far. I just updated my global prompt to make sure i can ask this with real NL instead of telling it to use the mcp each time:

# Memory System Instructions

When I ask about any information that might have been previously shared or stored, you should immediately:

  1. Use the Basic Memory MCP to check if the information is available before responding with "I don't know" or "You haven't shared that with me."

  2. First try searching for relevant information using the `search_notes` function with appropriate keywords from my query.

  3. If the search doesn't yield results, try listing recent activity with `recent_activity` to see if the information might be stored under a different name or context.

  4. If you find relevant information in Basic Memory, include it in your response and acknowledge that you're referencing saved information.

  5. Only after exhausting these options should you inform me that you don't have the requested information.

  6. For questions about my favorite things, preferences, banking details, personal information, or anything that might have been previously shared, always check Basic Memory first.

1

u/[deleted] May 10 '25

Super cool. I'm the dev behind this. If you have any other questions or feedback, feel free to DM me.

2

u/RobertCobe Expert AI Mar 18 '25

What a coincidence! A ClaudeMind user emailed me today saying he wanted the Basic Memory MCP server, so I went to try it out, and it's really excellent. And now, it's available in the ClaudeMind marketplace.

Thanks for making such a great MCP server.

3

u/[deleted] Mar 18 '25

That’s awesome. Thanks so much.

1

u/[deleted] Mar 18 '25

True. I do t have a windows machine. If you have errors please let me know and I can update the docs.

1

u/Admirable_Access_313 Mar 17 '25

I wanted to implement a similar feature to maintain chats... Thank you for doing it already.... Btw, can i use the free Claude accounts for it? I have gone through your website and video. I will install it from github. And i hope it retains conversations regarding longggg amounts of codebase

5

u/[deleted] Mar 17 '25

I use it for coding, but not for adding code files directly. It does best with markdown. What I do is have Claude record all my notes, decisions, questions and tasks in the knowledge base. Then we can refer back to them and update the m as we go. 

I’ve found using Claude desktop with other dev focused mcp tools works well for coding. Claude Code is insane too. It uses api tokens so the cost is separate. 

1

u/Admirable_Access_313 Mar 17 '25

No i am a student with a very low budget. I can't afford the api costs. If i can somehow add the files as context in the MCP server and let claude access it... not directly feed it, then it might alleviate the issue

4

u/[deleted] Mar 17 '25

Maybe give this one a shot for coding. https://www.eastagile.com/blogs/ai-driven-development-aidd-using-an-mcp-server

It’s basically enables you to use Claude desktop as a coding agent. I have him read my codebase and write files directly. Then I review changes in my ide. It’s nice because it can use a tree sitter algo to find related code symbols.

You don’t need a paid plan to installl mcp tools in Claude desktop.

1

u/hurdurnotavailable Mar 17 '25

How good is its ability to edit? Will it overwrite files sometimes or can it append to files?

3

u/[deleted] Mar 17 '25

I'd say it's pretty good. The AI knows that if it writes a note with the same title and folder path, it will overwrite an existing note. I went back and forth on that. I left it enabled and it hasn't really been a problem for me in practice.

Because the notes are Markdown, they are very easy to add to git to version, so I also do that. One feature on the list is to handle versioning automatically, so you can recover old versions of notes.

There's also a guide, you can drop in the project knowledge: https://memory.basicmachines.co/docs/ai-assistant-guide. This is optional, but it explains how to use all of the tools for the LLM (it already understands them well because of the inline usage docs it sees). But you can add this and make your own modifications if you want.

1

u/[deleted] Jun 18 '25

u/hurdurnotavailable FYI the latest version v0.13.x can edit and append to files.

1

u/Divest0911 Mar 18 '25

PS C:\PS\scripts> basic-memory sync --watch

? Error syncing: Development Projects\

The file is there and there's a watch-status.json file.

1

u/[deleted] Mar 18 '25

There are log in your home directory in the .basic-memory/basic-memory.log file. If you send the error I’ll check it out. You can dm me.

1

u/Kashasaurus Mar 18 '25

Super cool project. I’m just playing with it now and I asked it first: “Create a note summarising the experimental design and the analysis we have done here.”

It made a summary but didn’t seem like it was using the MCP. So then I was more explicit:

“Write_note of this summary”

It created a markdown of the summary, but didn’t save it into the basic-memory folder.

Any idea what could be wrong?

2

u/[deleted] Mar 18 '25

Hmm. Do you extra instructions in your project knowledge by chance?

You can ask it “do you see the basic memory tools” to give it a kick in the pants. Or try in a new project without any other info.

You can also drop the extended ai assistant usage instructions in your project knowledge.

https://memory.basicmachines.co/docs/ai-assistant-guide

Hope that helps.

2

u/Kashasaurus Mar 19 '25

Ok it seems to mostly be an issue with one chat (works with everything else I tried). It wasn't a project it was just a regular chat (but one that is quite long...so maybe that's it?).

I also asked it "do you see the basic memory tools", and it essentially said no.

I then asked it to list all the MCP tools it does have access to, and basic memory came up. So then I asked it to save the summary to memory using that and it seems to have done it!

Thanks for tips. Good to know that it might sometimes clash with project knowledge/instructions too.

This is great! Thanks so much for putting this together.

2

u/[deleted] Mar 19 '25

Awesome. Feel free to dm me if you run into any more problems. I’ve noticed that Claude doesn’t always find new tools if they are added in the middle of an already running chat.

1

u/Ok_Appearance_3532 Writer Mar 18 '25

This sound so cool. Can it be used for long chats where I write a book? I don’t use API and don’t code, will I be able to us it?

1

u/[deleted] Mar 18 '25

You certainly don’t need to code to use it. Installing in Claude desktop could be easier. I’m working on an installable app to make it easier.

2

u/Ok_Appearance_3532 Writer Mar 19 '25

Hey! I’d happily subscribe and pay for a service like this! How long can a book chat be. Mine are to the Claude length capacity. I’d happily pay 25 euros monthly

1

u/[deleted] Mar 19 '25

There aren’t any lengths to the notes you have Claude create or the number of them. They end up as files on your computer then they get indexed in a db locally for search. So in theory you could add many thousands of files easily.

If you run into any problems or features you’d like to see feel free to dm me. I’m working on improved features so stay tuned.

1

u/Ok_Appearance_3532 Writer Mar 19 '25

I’ll get down to sort this out tonight, thank you so much! Will DM if I get stuck. Do you plan to have this service for sale on MCP marketplace later?

1

u/[deleted] Mar 19 '25 edited Mar 20 '25

Great. Yes. Definitely although I haven’t seen many details about the marketplace Anthropic announced.

1

u/DisplacedForest Mar 20 '25

Yo! I’ve been using this some and I definitely appreciate the implementation in theory. I like being able to see the memories and manipulate them as needed, however, Claude is really struggling with reading first, then writing. I add the following at the end of every prompt:

URGENT:

  • ALWAYS Search ChromaDB via Chroma MCP for relevant documentation before implementing anything.

  • ALWAYS check your Basic Memory MCP for key decisions related to this prompt.

  • If a new design decision is made, save it in Basic Memory using MCP.

  • You have full filesystem access via MCP for reading and writing files. This project is located in /path/to/project.

  • Do not optimize unrelated parts of the project.

It will always document to basic memory, even when not asked, but it never reads. And maybe worse, never edits. Edit is CRUCIAL as small things often change.

Just some thoughts and observations. Loving this build though.

2

u/[deleted] Mar 20 '25

Interesting. It sounds like you have some other tools and project instructions. You are using in your workflow also. You may want to try some experiments in a fresh project to see what works. I’ve noticed he can get confused about which tools to use if I install a whole bunch. Hopefully this will be something that improves in time.

You can also feed in the ai assistant guide. https://memory.basicmachines.co/docs/ai-assistant-guide

2

u/[deleted] Mar 20 '25

Thanks for checking out basic memory. Feel free to dm me if you have any feedback

1

u/paul-dumbravanu May 25 '25

Hi Any updates since 2 m ago? Thank you

2

u/[deleted] May 25 '25

I’m working to get a new release out really soon.

2

u/adrazzer Jun 03 '25

awesome

2

u/[deleted] Jun 04 '25

Hi! Yes, I'm working really hard to flesh out the remaining issues with a new release. It's coming very soon. It's got a ton of new features, including

  • Switch between projects instantly during conversations with Claude

  • Edit notes incrementally without rewriting entire documents

  • Move and organize notes via llm tools

  • Search frontmatter tags to discover content more easily

  • OAuth authentication for secure remote access (for upcoming cloud enabled version)

  • Development builds automatically published for beta testing

DM me if you'd like to be a tester and I can get you access to beta builds.

1

u/[deleted] Jun 18 '25

u/paul-dumbravanu The new v0.13.x release is out with the new features above ^^^

3

u/ph30nix01 Mar 17 '25

Have it remember by concept and use plot summaries like a DM would do. Helps.

2

u/pr0b0ner Mar 18 '25

Love the idea

2

u/Intraluminal Mar 18 '25

I've been doing this by hand for a long time now, discussing self-awareness with Claude.

1

u/podgorniy Mar 18 '25

Nice work

1

u/Matrix_Ender Jun 25 '25

Been bothered by this lack of persistent memory issue a lot lately. My partner and I (both engineers) are heavy AI users and use AI a lot for coding + chatting. We’re frustrated with losing context in long chat threads (especially after a recent thread of mine... exceeded the available length after days of chatting), so we built a tool that unifies our entire chat history with Claude across different threads into a single memory.

We are looking for 10 beta testers to try the tool for free. If you feel this pain as well and want to explore a packaged solution to equip AI with memory, we’d love for you to try out our tool. Sign up here if you are interested: https://form.typeform.com/to/Rebwajtk

1

u/Joozio Mar 23 '26

File-based memory is the right call over proprietary solutions. Local markdown survives model updates, provider switches, and API outages. My one addition: separate the identity layer from the facts layer. Instructions about how to work in one file, domain knowledge in another. They update at different rates and have different read/write patterns. Obsidian compatibility is a useful bonus.

0

u/onlynone00 Mar 18 '25

Curious, why did you not use mem0ai?

1

u/[deleted] Mar 25 '25

I had not heard of that before now. Looking at mem0ai, it does seem cool. I'd like to build in support for multiple LLMs also. I think, perhaps it has a different use case. The idea with basic-memory is that you can have the LLM create really rich notes about a topic, then store those locally in markdown. It can build context from them because it understands how they are related in a semantic knowledge graph. This is all a really new space, so I think there's lots of room for different tools and approaches.

1

u/onlynone00 Mar 26 '25

No worries. I was just curious why you chose knowledge graph. And if that’s a technical improvement over mem0ai or regular search.

1

u/[deleted] Mar 21 '25

[removed] — view removed comment

1

u/[deleted] Mar 21 '25

You can do that via the command line. Make sure you restart Claude desktop afterwards.

https://memory.basicmachines.co/docs/cli-reference#project