Claude Desktop

Set up Basic Memory with Claude Desktop for persistent conversations and knowledge management

Claude Desktop is the recommended way to use Basic Memory. It provides seamless integration through the Model Context Protocol (MCP), giving Claude direct access to your knowledge base.

Installation

Prerequisites

Configure Claude Desktop

Edit your Claude Desktop config, located at:

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

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

Install Basic Memory (Optional)

# Stable release (recommended)
uv tool install basic-memory
# or: pip install basic-memory

# Beta releases (new features, testing)
pip install basic-memory --pre

# Development builds (latest changes)
pip install basic-memory --pre --force-reinstall

Restart Claude Desktop

After saving the config, restart Claude Desktop. You should see Basic Memory tools available in the tools menu (hammer icon in bottom-right).

Features

Core Capabilities

Real-time Sync

Changes you make to files are immediately available in conversations:

1. Edit a file in any text editor
2. Save the changes
3. Ask Claude to read the note - it will see your updates

Memory URLs

Reference specific knowledge with memory:// URLs:

You: "Take a look at memory://project-planning and let's continue our discussion"

Claude will load that specific note and any related context.

Common Workflows

Creating Knowledge

During a conversation:

You: "Could you create a note summarizing our discussion about API design?"
Claude: I'll create a note capturing our API design discussion...
[Creates structured note with observations and relations]

Building on existing knowledge:

You: "Add a section about authentication to my API documentation"
Claude: [Uses edit_note to append new content without rewriting]

Searching and Discovery

Find information:

You: "What did we decide about the database schema?"
Claude: [Searches knowledge base and provides relevant information]

View formatted notes:

You: "Show me the project documentation as a formatted artifact"
Claude: [Uses view_note to display the note as a readable artifact]

Recent activity:

You: "What have we been working on lately?"
Claude: [Shows recently modified notes and offers to continue discussions]

Project Management

New in v0.15.0: Projects are selected at the start of each conversation. Claude will suggest your most active project and ask which one to use.

Starting a conversation:

You: "Let's organize my personal notes"

Claude: I see you have 3 projects: main, work-notes, personal
Your most active project is personal
Should I use personal for this task?

You: "Yes"

For single-project users, add this to ~/.basic-memory/config.json:

{
  "default_project": "main",
  "default_project_mode": true
}

This skips project selection and uses your default project automatically.

Advanced Usage

Special Prompts

Basic Memory includes prompts that trigger specific behaviors:

• “Continue our conversation about [topic]” - Loads relevant context
• “What have we been discussing recently?” - Shows recent activity
• “Find information about [topic]” - Searches knowledge base

Incremental Editing

Instead of rewriting entire notes, Claude can edit incrementally:

• Append: Add new sections to existing notes
• Prepend: Add content to the beginning
• Replace sections: Update specific parts
• Find and replace: Make targeted text changes

File Organization

Claude can help organize your knowledge base:

• Move notes to appropriate folders
• Archive old content
• Create directory structures
• Maintain database consistency during moves

Troubleshooting

Common Issues

Getting Help

# Check installation
basic-memory --version

# View sync status
basic-memory status

# Get help with commands
basic-memory --help

Best Practices

Knowledge Creation

1. Use descriptive titles - They become link targets
2. Add semantic observations - Categorize information
3. Create relations - Connect related concepts
4. Use tags - Enable better search
5. Review AI-generated content - Edit for accuracy

Conversation Management

1. Reference existing knowledge - Use memory:// URLs
2. Build incrementally - Add to existing notes
3. Use multiple projects - Organize knowledge by context (work, personal, etc.)
4. Use special prompts - Leverage built-in behaviors
5. Organize regularly - Keep knowledge base clean

Performance

1. Archive old content - Keep active knowledge focused
2. Use meaningful filenames - Improve discoverability
3. Regular backups - Use git for version control
4. Monitor project size - Check with basic-memory project info

Next Steps