basicmachines-co-basic-memory/llms-install.md

Basic Memory Installation Guide for LLMs

This guide is specifically designed to help AI assistants like Cline install and configure Basic Memory. Follow these steps in order.

Installation Steps

1. Install Basic Memory Package

Use one of the following package managers to install:

# Install with uv (recommended)
uv tool install basic-memory

# Or with pip
pip install basic-memory

2. Configure MCP Server

Add the following to your config:

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

For Claude Desktop, this file is located at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

3. Start Synchronization (optional)

To synchronize files in real-time, run:

basic-memory sync --watch

Or for a one-time sync:

basic-memory sync

4. Updating Basic Memory

Basic Memory supports automatic updates by default for uv tool and Homebrew installs.

For manual checks and upgrades:

# Check now and install if supported
bm update

# Check only, do not install
bm update --check

To disable automatic updates, set "auto_update": false in ~/.basic-memory/config.json.

Configuration Options

Custom Directory

To use a directory other than the default ~/basic-memory:

basic-memory project add custom-project /path/to/your/directory
basic-memory project default custom-project

Multiple Projects

To manage multiple knowledge bases:

# List all projects
basic-memory project list

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

# Set default project
basic-memory project default work

Importing Existing Data

From Claude.ai

basic-memory import claude conversations path/to/conversations.json
basic-memory import claude projects path/to/projects.json

From ChatGPT

basic-memory import chatgpt path/to/conversations.json

From MCP Memory Server

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

Troubleshooting

If you encounter issues:

1. Check that Basic Memory is properly installed:

   basic-memory --version
   

2. Verify the sync process is running:

   ps aux | grep basic-memory
   

3. Check sync output for errors:

   basic-memory sync --verbose
   

4. Check log output:

   cat ~/.basic-memory/basic-memory.log
   

For more detailed information, refer to the full documentation.