Skip to main content

​
Quick Start

This guide will get you from zero to your first working knowledge base in under 5 minutes.

​
Prerequisites

  • Python 3.12 or higher
  • Claude Desktop app (or another MCP-compatible client)
  • Basic familiarity with the command line
Basic Memory requires Python 3.12+ due to modern type system features. Check your version with python --version.

​
Installation

1

Install Basic Memory

Install using uv (recommended) or pip:
uv tool install basic-memory
Verify the installation:
basic-memory --version
2

Configure Claude Desktop

Add Basic Memory to your Claude Desktop configuration file:
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp"
      ]
    }
  }
}
If using pip instead of uv, replace "uvx" with "basic-memory" and remove "basic-memory" from the args array.
3

Restart Claude Desktop

Close and reopen Claude Desktop to load the Basic Memory MCP server.You should see a small hammer icon (🔨) in Claude indicating MCP tools are available.
4

Start the sync service (optional but recommended)

In a terminal, start the sync service to keep your knowledge base in sync:
basic-memory sync --watch
This watches for file changes and keeps your SQLite index up to date.
You can run sync as a one-time operation with basic-memory sync or skip this step - Claude can still use Basic Memory without sync, but file changes outside of Claude won’t be immediately available.

​
Your First Note

Let’s create your first note through a conversation with Claude:
1

Open Claude Desktop

Start a new conversation in Claude Desktop.
2

Ask Claude to create a note

Try this prompt:
Create a note about Python programming. Include observations about:
- It's a high-level interpreted language
- Created by Guido van Rossum
- Known for readability and simplicity
- Widely used in data science and web development

Add relations to related topics like Data Science and Web Development.
3

Claude creates the note

Claude will use the write_note tool to create a structured Markdown file at ~/basic-memory/python-programming.md:
---
title: Python Programming
permalink: python-programming
tags:
- programming
- python
---

# Python Programming

## Observations

- [language_type] High-level interpreted language
- [creator] Created by Guido van Rossum
- [characteristic] Known for readability and simplicity
- [use_case] Widely used in data science and web development

## Relations

- used_in [[Data Science]]
- used_in [[Web Development]]
- created_by [[Guido van Rossum]]
4

View the file

Open the file in your favorite text editor or Obsidian:
# View with cat
cat ~/basic-memory/python-programming.md

# Or open in your default editor
open ~/basic-memory/python-programming.md

​
Reading Notes

Now let’s read the note back:
1

Ask Claude to read the note

In the same or a new conversation:
What do I know about Python programming?
2

Claude retrieves the information

Claude will use the read_note tool to load your note and respond with the information you saved.

​
Building Context

The real power comes from building connected knowledge:
1

Create related notes

Create notes for Data Science and Web Development, with observations about each field.
Link them back to Python Programming.
2

Ask Claude to build context

Tell me about Python and how it relates to the other topics in my knowledge base.
Claude will use the build_context tool to traverse the knowledge graph, following relations to gather comprehensive information.

​
Essential Commands

Here are the most common Basic Memory commands you’ll use: 
basic-memory status

​
Common Prompts to Try

Here are some prompts to explore Basic Memory’s capabilities: 
Create a note about [topic] with observations about [aspects] and relations to [related topics]

Search my notes for information about [query]

What do I know about [topic] and its related concepts?

What have I been working on in the past week?

Continue our conversation about [topic] from last time

Create a canvas visualization of my [topic] notes and their connections

​
What’s in Your Knowledge Base?

By default, Basic Memory stores everything in ~/basic-memory/: 
~/basic-memory/
├── python-programming.md
├── data-science.md
├── web-development.md
└── .basic-memory/
    └── basic-memory.db  # SQLite index
The .basic-memory/ directory contains the SQLite database used for indexing and search. The Markdown files are the source of truth.

​
Next Steps

Installation Details

Learn about different installation methods and configuration options

User Guide

Deep dive into Basic Memory’s features and workflows

CLI Reference

Complete command-line interface documentation

Knowledge Format

Learn about the Markdown format for notes

​
Troubleshooting

  1. Verify Basic Memory is installed: basic-memory --version
  2. Check your claude_desktop_config.json syntax is valid
  3. Ensure you restarted Claude Desktop after editing the config
  4. Look for error messages in Claude’s logs
  1. Make sure you’re running basic-memory sync --watch
  2. Check for errors in the sync output
  3. Verify file permissions in ~/basic-memory/
  4. Run basic-memory status to check sync status
Notes are stored in ~/basic-memory/ by default. Check:
ls -la ~/basic-memory/
You can also check which project is active:
basic-memory project list
Basic Memory requires Python 3.12+. Check your version:
python --version
If you need to upgrade, see python.org/downloads
Join our Discord community for help and to share your experience!

Build docs developers (and LLMs) love

Get started for freeTalk to us