Basic Memory is an MCP (Model Context Protocol) server that allows you to build persistent knowledge through natural conversations with LLMs like Claude. It stores information as Markdown files on your computer, creating a personal knowledge base that both humans and AI can read and write to.
uv tool install basic-memory
brew tap basicmachines-co/basic-memory
brew install basic-memory
npx -y @smithery/cli install @basicmachines-co/basic-memory --client claude
# Stable release
pip install basic-memory
# Beta/pre-releases
pip install basic-memory --pre
# Development builds
pip install basic-memory --pre --force-reinstall
docker run -d \
--name basic-memory-server \
-v /path/to/your/obsidian-vault:/data/knowledge:rw \
-v basic-memory-config:/root/.basic-memory:rw \
ghcr.io/basicmachines-co/basic-memory:latest
Edit your Claude Desktop configuration file (located at ~/Library/Application Support/Claude/claude_desktop_config.json
for macOS):
{
"mcpServers": {
"basic-memory": {
"command": "uvx",
"args": [
"basic-memory",
"mcp"
]
}
}
}
To use a specific project:
{
"mcpServers": {
"basic-memory": {
"command": "uvx",
"args": [
"basic-memory",
"--project",
"your-project-name",
"mcp"
]
}
}
}
Add to your VS Code User Settings (JSON):
{
"mcp": {
"servers": {
"basic-memory": {
"command": "uvx",
"args": ["basic-memory", "mcp"]
}
}
}
}
Or create a .vscode/mcp.json
file in your workspace:
{
"servers": {
"basic-memory": {
"command": "uvx",
"args": ["basic-memory", "mcp"]
}
}
}
Once configured, your notes will be stored in ~/basic-memory
by default. You can interact with Basic Memory through compatible LLM interfaces like Claude Desktop or VS Code.
Basic Memory provides these tools to LLMs:
write_note(title, content, folder, tags)
- Create or update notesread_note(identifier, page, page_size)
- Read notes by title or permalinkedit_note(identifier, operation, content)
- Edit notes incrementallymove_note(identifier, destination_path)
- Move notes with database consistencyview_note(identifier)
- Display notes as formatted artifactsbuild_context(url, depth, timeframe)
- Navigate knowledge graphsearch_notes(query, page, page_size)
- Search across your knowledge baserecent_activity(type, depth, timeframe)
- Find recently updated informationcanvas(nodes, edges, title, folder)
- Generate knowledge visualizationslist_memory_projects()
- List all available projectsswitch_project(project_name)
- Switch to different project contextget_current_project()
- Show current project and statisticscreate_memory_project(name, path, set_default)
- Create new projectsdelete_project(name)
- Delete projects from configurationset_default_project(name)
- Set default projectsync_status()
- Check file synchronization statusBasic Memory uses a specific Markdown format:
---
title: Coffee Brewing Methods
permalink: coffee-brewing-methods
tags:
- coffee
- brewing
---
- [method] Pour over provides more clarity and highlights subtle flavors
- [technique] Water temperature at 205°F (96°C) extracts optimal compounds
- [principle] Freshly ground beans preserve aromatics and flavor
- relates_to [[Coffee Bean Origins]]
- requires [[Proper Grinding Technique]]
- affects [[Flavor Extraction]]
You can manage different knowledge bases as separate projects. Use the following command to switch between them:
basic-memory project switch your-project-name
Or create a new project:
basic-memory project create new-project-name /path/to/store/files
To add this MCP server to Claude Code, run this command in your terminal:
claude mcp add-json "basic-memory" '{"command":"uvx","args":["basic-memory","mcp"]}'
See the official Claude Code MCP documentation for more details.
There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json
file so that it is available in all of your projects.
If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json
file.
To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".
When you click that button the ~/.cursor/mcp.json
file will be opened and you can add your server like this:
{
"mcpServers": {
"basic-memory": {
"command": "uvx",
"args": [
"basic-memory",
"mcp"
]
}
}
}
To add an MCP server to a project you can create a new .cursor/mcp.json
file or add it to the existing one. This will look exactly the same as the global MCP server example above.
Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.
The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.
You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.
To add this MCP server to Claude Desktop:
1. Find your configuration file:
~/Library/Application Support/Claude/claude_desktop_config.json
%APPDATA%\Claude\claude_desktop_config.json
~/.config/Claude/claude_desktop_config.json
2. Add this to your configuration file:
{
"mcpServers": {
"basic-memory": {
"command": "uvx",
"args": [
"basic-memory",
"mcp"
]
}
}
}
3. Restart Claude Desktop for the changes to take effect