Basic Memory: an MCP service for building persistent knowledge graphs from AI conversations

General Introduction

Basic Memory is a tool for building knowledge graphs by conversing with AI assistants such as Claude. Developed by Basic Machines, its core feature is that it saves conversations as Markdown files, which are stored on the user's local computer, ensuring that the data is completely under the user's control. The tool builds knowledge graphs by Model Context Protocol (MCP) Collaborating with big models, AI can read and write knowledge to form semantically connected graphs. It also supports integration with Obsidian for easy viewing and editing. Currently in Beta, it is suitable for users who need to accumulate structured knowledge, such as researchers, writers or knowledge management enthusiasts.

Function List

• Dialogue generates knowledge: Turn natural conversations with AI into structured Markdown documents.
• local storage: All data is saved on the user's computer and is not uploaded to the cloud.
• semantic mapping: Automatically extracts relationships between knowledge points and generates traversable graphs.
• Large model collaboration: The MCP protocol is used to communicate with the Claude and other model interactions to read and write local knowledge.
• Obsidian Integration: View and edit Markdown files directly in Obsidian.
• Data import: Support for importing existing conversations from Claude's JSON files.
• real time synchronization: Monitor document changes to keep the knowledge base up to date.

Using Help

Installation process

Basic Memory is currently a command line tool and requires some technical skills to install. Below are the detailed steps:

1. Preparing the environment
   • Make sure Python 3.8 or later is installed on your computer.
   • mounting uv tool (recommended), run it in the terminal:

     pip install uv
     

2. Installing Basic Memory
   • Enter the command in the terminal:

     uv tool install basic-memory
     

   • Check if the installation was successful and run it:

     basic-memory --version
     

     If the version number is displayed, the installation is complete.

3. Configuring the MCP Server
   • Basic Memory communicates with the AI via the MCP protocol. Start the local MCP service:

     uvx basic-memory mcp
     

   • If you are using Claude, you will need to add MCP settings to the Claude Desktop configuration file. Edit the file (path on Mac systems is ~/Library/Application Support/Claude/claude_desktop_config.json):

     {
     "mcpServers": {
     "basic-memory": {
     "command": "uvx".
     "args": ["basic-memory", "mcp"]
     }
     }
     }
     

4. Initialization Project
   • Create a folder as a knowledge base, for example ~/basic-memoryThe
   • Go to the folder:

     cd ~/basic-memory
     

   • Initialization:

     basic-memory init
     

5. Initiate synchronization
   • Run the real-time synchronization command:

     basic-memory sync --watch
     

Alternative installation methods (via Smithery)

• Use Smithery to auto-configure:

npx -y @smithery/cli install @basicmachines-co/basic-memory --client claude

• This automatically installs and configures Basic Memory, eliminating the need to manually edit the Claude configuration file.

How to use the main features

1. Knowledge creation through dialogue

• Open Claude Desktop and talk to the AI. For example, "Tell me how to brew coffee."
• After the AI answers, Basic Memory automatically generates a Markdown file and saves it to your project folder (e.g. ~/basic-memory). Example of a document:

---

title: Coffee-brewing-methods
permalink: coffee-brewing-methods
type: note
tags: coffee-brewing-methods
- coffee-brewing-methods
- coffee-brewing-methods
---

# Coffee Brewing Method
## Observation
- [METHOD] Hand-brewed coffee has a more delicate flavor than French press.
- [Technique] Water Temperature: 96°C for Best Extraction
## Relationship
- Relates to [[coffee bean source]]
- Needs [[grinding technique]]

2. Viewing and editing knowledge

• Open Obsidian and import the project folder (e.g. ~/basic-memory).
• View the Knowledge Graph in Obsidian and click on the file to edit it. For example, if you want to add "Hand Punch Needs Filter Paper", you can write it directly in the file:

- [Tools] Hand Brewed Coffee Needs Filters

3. Introducing existing dialogues

• Export conversation logs in JSON format from the Claude website.
• Runs in the terminal:

basic-memory import --folder ~/basic-memory ~/Downloads/conversations.json

• The system converts the dialog to a Markdown file and stores it in the specified folder.

4. Keeping knowledge synchronized

• (of a computer) run basic-memory sync --watch, conversations and edits are updated in real time.
• For example, after Obsidian modifies a file, the AI reads the latest content for the next conversation.

Operation process details

• Starting a conversation: Ask a question in Claude and the answer is automatically saved as Markdown.
• Inspection of documents: Open the project folder to view the generated files.
• Organize knowledge: Adjusting content and adding new links in Obsidian.
• continued use: Each conversation completes the knowledge graph.

This tool is intuitive to operate and all data is local. Once installed, a few commands are enough to get started. It is still under development, but the core functionality is already practical.

application scenario

1. Research note management
   Researchers discuss topics with AI, and Basic Memory automatically generates structured notes for easy follow-up.
2. Writing material accumulation
   Writers chat with AI about inspiration, and the tool records and connects relevant content to support creation.
3. Personal Knowledge Base Building
   Users ask the AI everyday questions, such as cooking tips, gradually building a personal knowledge base.

QA

1. Do I need to network?
   Yes, communication with AI requires networking, but the data is only stored locally.
2. What models are supported?
   Claude is currently supported, other models may be added in the future.
3. Will data be lost?
   No, unless the user manually deletes it, the files are under local control.