Installation

This guide covers everything you need to know about installing and configuring Basic Memory on different platforms.

System Requirements

Python

Version 3.12 or higher required

Operating System

macOS, Linux, or Windows

MCP Client

Claude Desktop, VS Code with MCP, or other MCP-compatible client

Disk Space

Minimal (~50MB for installation)

Basic Memory requires Python 3.12+ due to modern type system features (type statement and type parameters). It will not work with earlier Python versions.

Checking Your Python Version

Before installing, verify your Python version:

python --version
# or
python3 --version

If you see a version lower than 3.12, you’ll need to upgrade Python first:

macOS
Windows
Linux

# Using Homebrew
brew install [email protected]

# Ubuntu/Debian
sudo apt update
sudo apt install python3.12

# Fedora
sudo dnf install python3.12

Installation Methods

Method 1: Using uv (Recommended)

uv is a fast Python package installer. It’s the recommended method for installing Basic Memory.

Install uv (if not already installed)

macOS/Linux
Windows

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Install Basic Memory

uv tool install basic-memory

This installs Basic Memory as a standalone tool with its own isolated environment.

Verify installation

basic-memory --version

You should see output like: basic-memory, version 0.15.0

With uv, you can also run Basic Memory without installing it using uvx basic-memory [command].

Method 2: Using pip

If you prefer pip or don’t want to install uv:

Install Basic Memory

pip install basic-memory

Or for a user-local installation (recommended):

pip install --user basic-memory

Verify installation

basic-memory --version

Method 3: From Source (For Development)

If you want to contribute or modify Basic Memory:

Clone the repository

git clone https://github.com/basicmachines-co/basic-memory.git
cd basic-memory

Install with development dependencies

# Using uv (recommended)
uv sync

# Or using pip
pip install -e ".[dev]"

Verify installation

basic-memory --version

Configuring MCP Clients

Basic Memory works with any MCP-compatible client. Here’s how to configure the most popular ones:

Claude Desktop

Claude Desktop is the most popular MCP client for Basic Memory.

Locate the configuration file

macOS
Windows
Linux

~/Library/Application Support/Claude/claude_desktop_config.json

%APPDATA%\Claude\claude_desktop_config.json

~/.config/Claude/claude_desktop_config.json

If the file doesn’t exist, create it.

Add Basic Memory configuration

Using uv (recommended)
Using pip
With custom project

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

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

{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp",
        "--project",
        "my-project-name"
      ]
    }
  }
}

Restart Claude Desktop

Close and reopen Claude Desktop completely for the changes to take effect.

Verify MCP is working

Look for a small hammer icon (🔨) in Claude Desktop. When you start typing prompts like “Create a note about…”, Claude should be able to use Basic Memory tools.

VS Code

For VS Code with MCP support:

Open VS Code User Settings (JSON)

Press Ctrl + Shift + P (or Cmd + Shift + P on macOS) and type:

Preferences: Open User Settings (JSON)

Add Basic Memory configuration

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

Alternative: Workspace configuration

Create .vscode/mcp.json in your workspace:

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

This allows sharing the configuration with your team.

Other MCP Clients

For other MCP-compatible clients, the general pattern is:

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

Refer to your client’s documentation for specific configuration details.

Initial Setup

After installation, initialize your Basic Memory project:

Check default project location

By default, Basic Memory stores notes in ~/basic-memory/:

basic-memory status

This creates the directory and database if they don’t exist.

(Optional) Create a custom project

If you want to use a different location:

basic-memory project add my-project ~/Documents/my-knowledge-base
basic-memory project default my-project

Start sync service

For real-time synchronization:

basic-memory sync --watch

Or run a one-time sync:

basic-memory sync

Configuration Options

Custom Project Directory

To use a custom directory for your knowledge base:

# Add a new project
basic-memory project add work ~/work-knowledge

# Set it as default
basic-memory project default work

# Verify
basic-memory project list

Multiple Projects

You can manage multiple knowledge bases:

basic-memory project list

Cloud Sync (Optional)

Basic Memory Cloud provides cross-device synchronization:

Visit basicmemory.com and sign up for an account.

Use code BMFOSS for 20% off for 3 months (OSS discount).

Authenticate

basic-memory cloud login

This opens your browser for OAuth authentication.

Set up cloud sync

basic-memory cloud setup

This configures rclone for bidirectional sync.

Enable cloud for a project

basic-memory project set-cloud my-project

Sync to cloud

# One-way sync (local → cloud)
basic-memory project sync

# Bidirectional sync
basic-memory project bisync

Cloud sync is completely optional. Basic Memory works perfectly as a local-only tool.

Importing Existing Data

If you have existing notes or conversations, you can import them:

From Claude.ai

Export conversations from Claude.ai

In Claude.ai, go to Settings → Export Data to download your conversations.

Import to Basic Memory

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

For projects:

basic-memory import claude projects ~/Downloads/projects.json

From ChatGPT

Export conversations from ChatGPT

In ChatGPT Settings, use Data Export to download your conversations.

Import to Basic Memory

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

From Memory JSON

If you have data from another MCP memory server:

basic-memory import memory-json ~/path/to/memory.json

Verification

Verify your installation is working correctly:

Check version

basic-memory --version

Check status

basic-memory status

Should show your project directory and sync status.

Test MCP in Claude

Open Claude Desktop and try:

Create a note about testing Basic Memory installation

If it works, you should see a new file in ~/basic-memory/.

Troubleshooting

Command not found: basic-memory

Problem: The basic-memory command is not in your PATH.Solutions:

If using uv tool install, ensure uv’s bin directory is in your PATH:
```
export PATH="$HOME/.local/bin:$PATH"
```
Add this to your ~/.bashrc or ~/.zshrc to make it permanent.
If using pip install --user, add the user bin directory:
```
export PATH="$HOME/.local/bin:$PATH"
```
Use the full path:
```
~/.local/bin/basic-memory --version
```

Python version too old

Problem: Error message about Python version.Solution: Upgrade to Python 3.12 or higher:

macOS
Linux
Windows

brew install [email protected]

# Ubuntu/Debian
sudo apt install python3.12

# Use update-alternatives to set default
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 1

Claude Desktop doesn't show MCP tools

Problem: No hammer icon or MCP tools in Claude Desktop.Solutions:

Verify config file location is correct for your OS
Check JSON syntax is valid (use a JSON validator)
Ensure you fully restarted Claude Desktop (not just closed the window)
Check Claude Desktop logs:
- macOS: ~/Library/Logs/Claude/
- Windows: %APPDATA%\Claude\logs\
Test Basic Memory works directly:
```
basic-memory --version
```

Permission denied errors

Problem: Cannot write to the default directory.Solution: Check directory permissions:

ls -la ~/basic-memory/

If needed, fix permissions:

chmod 755 ~/basic-memory/

Or use a custom directory:

basic-memory project add custom ~/Documents/knowledge
basic-memory project default custom

Sync issues

Problem: Files aren’t syncing or showing errors.Solutions:

Check sync status:
```
basic-memory status
```
Run sync manually with verbose output:
```
basic-memory sync --verbose
```
Check logs:
```
cat ~/.basic-memory/basic-memory.log
```
Verify database integrity:
```
basic-memory doctor
```

Cannot connect to cloud

Problem: Cloud authentication fails.Solutions:

Check your internet connection
Verify your subscription is active at basicmemory.com

Try logging out and back in:

basic-memory cloud logout
basic-memory cloud login

Check cloud status:
```
basic-memory cloud status
```

Uninstallation

If you need to uninstall Basic Memory:

Using uv
Using pip

uv tool uninstall basic-memory

pip uninstall basic-memory

To remove your data:

# Remove default project
rm -rf ~/basic-memory/

# Remove configuration
rm -rf ~/.basic-memory/

This permanently deletes your knowledge base. Back up any important notes before uninstalling.

Next Steps

Quick Start

Create your first note and start building your knowledge base

User Guide

Learn about Basic Memory’s features in depth

CLI Reference

Complete command-line interface documentation

Knowledge Format

Understand the Markdown format for notes

Getting Help

If you run into issues:

Discord Community

Ask questions and get help

GitHub Issues

Report bugs or request features

Documentation

Browse the full docs

Get Started

Core Concepts

User Guide

Cloud Features

Advanced

​Installation

​System Requirements

Python

Operating System

MCP Client

Disk Space

​Checking Your Python Version

​Installation Methods

​Method 1: Using uv (Recommended)

​Method 2: Using pip

​Method 3: From Source (For Development)

​Configuring MCP Clients

​Claude Desktop

​VS Code

​Other MCP Clients

​Initial Setup

​Configuration Options

​Custom Project Directory

​Multiple Projects

​Cloud Sync (Optional)

​Importing Existing Data

​From Claude.ai

​From ChatGPT

​From Memory JSON

​Verification

​Troubleshooting

​Uninstallation

​Next Steps

Quick Start

User Guide

CLI Reference

Knowledge Format

​Getting Help

Discord Community

GitHub Issues

Documentation

Build docs developers (and LLMs) love

Installation

System Requirements

Checking Your Python Version

Installation Methods

Method 1: Using uv (Recommended)

Method 2: Using pip

Method 3: From Source (For Development)

Configuring MCP Clients

Claude Desktop

VS Code

Other MCP Clients

Initial Setup

Configuration Options

Custom Project Directory

Multiple Projects

Cloud Sync (Optional)

Importing Existing Data

From Claude.ai

From ChatGPT

From Memory JSON

Verification

Troubleshooting

Uninstallation

Next Steps

Getting Help