> ## Documentation Index
> Fetch the complete documentation index at: https://memory.basicmachines.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> Install Basic Memory, configure it with your AI assistant, and create your first knowledge notes.

Basic Memory works through the Model Context Protocol (MCP) to connect with AI assistants like Claude Desktop, Claude Code, and Gemini CLI. Here's how to set it up.

## Installation

### Universal Installation (All Platforms)

You can install Basic Memory using `uv`, an extremely fast Python package and project manager, written in Rust.

You can install `uv` from [astral's website ↗️](https://docs.astral.sh/uv/getting-started/installation/)

```bash theme={null}
uv tool install basic-memory
```

> [!WARNING]
>
> * **`uv` must be installed and available in your system PATH**. Claude Desktop runs in its own isolated environment and needs `uv` to manage dependencies.

### Homebrew Installation (macOS)

The easiest way to install Basic Memory on macOS is with Homebrew:

```bash theme={null}
brew tap basicmachines-co/basic-memory
brew install basic-memory
```

> [!NOTE]
>
> If you use Homebrew, you do **not** need to install with `uv` or `pip` separately.

### 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`

```json theme={null}
{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp"
      ]
    }
  }
}
```

**Restart Claude Desktop**. You should see Basic Memory tools available in the "tools" menu in Claude Desktop (the little hammer icon in the bottom-right corner of the chat interface). Click it to view available tools.

![tools-menu](https://mintcdn.com/basicmachines/o-7gfHyHm-1OBf90/attachments/claude-tools-menu.png?fit=max\&auto=format\&n=o-7gfHyHm-1OBf90\&q=85\&s=9ffdf1f5ac5b9fa226250134d5d00570)

### Install Basic Memory Pre-releases (For Daring Adventurers)

```bash theme={null}
# Beta releases (new features, testing)
pip install basic-memory --pre

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

### Choosing Where Your Notes Are Saved

By default, Basic Memory saves notes in a project called `main` in `~/basic-memory`. If you want notes saved somewhere else—like an existing note-taking folder—you can change this easily.

#### Use Your Existing Notes Folder

The easiest way is to ask Claude directly in your conversation:

```
Create a new project called "my project" in the "/Users/yourname/Documents/Notes" directory
```

Then:

```
Set the default project to "my project"
```

Alternatively, you can use command line tools:

```bash theme={null}
# Point Basic Memory to your existing notes folder
basic-memory project add "my project" <path to your project>

# Make it your default location
basic-memory project default "my project"
```

> [!WARNING]
>
> If you change default projects from the command line new notes will be saved in your chosen folder after restarting your MCP Client (e.g. Claude Desktop).

**Want to use Obsidian?** Just open your folder location as a vault. See the [Obsidian Integration guide](https://memory.basicmachines.co/integrations/obsidian.md) for detailed setup with existing vaults.

**Need multiple note collections?** You can create different projects for work, personal, etc. See [Multi-Project Setup](#multi-project-setup) below.

> [!NOTE]
>
> **Advanced configuration**: Basic Memory stores its settings in `~/.basic-memory/config.json`. While you can use CLI commands for most configuration (recommended), you can also edit this file directly to manage projects and settings. Changes to the config file require restarting Claude Desktop.

### Multi-Project Setup

You can also work with multiple projects and switch between them using tools via the LLM.

```
What is the default project?
```

![projects](https://mintcdn.com/basicmachines/o-7gfHyHm-1OBf90/attachments/projects.png?fit=max\&auto=format\&n=o-7gfHyHm-1OBf90\&q=85\&s=5fc8f8ac57c02d3b91a6072ea73989e9)

```
create a new project "work notes"
```

Will create a note in the "work notes" project, while leaving the current project active.

```
switch to the "recipies" project
```

Switch to a project and make it active.

```
set the default project to "work notes"
```

Set the default project used at startup.

## Creating Your First Knowledge Note

1. **Open Claude Desktop** and start a new conversation.

2. **Have a natural conversation** about any topic:
   ```
   You: "Let's talk about coffee brewing methods I've been experimenting with."
   Claude: "I'd be happy to discuss coffee brewing methods..."
   You: "I've found that pour over gives more flavor clarity than French press..."
   ```

3. **Ask Claude to create a note**:
   ```
   You: "Could you create a note summarizing what we've discussed about coffee brewing?"
   ```

4. **Confirm note creation**:
   Claude will confirm when the note has been created and where it's stored.

5. **View the created file** in your `~/basic-memory` directory using any text editor or Obsidian.
   The file structure will look similar to:
   ```markdown theme={null}
   ---
   title: Coffee Brewing Methods
   permalink: coffee-brewing-methods
   tags: [coffee, brewing, equipment]  # v0.14.0: Now searchable!
   ---

   # Coffee Brewing Methods

   ## Observations
   - [method] Pour over provides more clarity...
   - [technique] Water temperature at 205°F...

   ## Relations
   - relates_to [[Other Coffee Topics]]
   ```

## Using Special Prompts

Basic Memory includes special prompts that help you start conversations with context from your knowledge base:

### Continue Conversation

To resume a previous topic:

```
You: "Let's continue our conversation about coffee brewing."
```

This prompt triggers Claude to:

1. Search your knowledge base for relevant content about coffee brewing
2. Build context from these documents
3. Resume the conversation with full awareness of previous discussions

### Recent Activity

To see what you've been working on:

```
You: "What have we been discussing recently?"
```

This prompt causes Claude to:

1. Retrieve documents modified in the recent past
2. Summarize the topics and main points
3. Offer to continue any of those discussions

### Search

To find specific information:

```
You: "Find information about pour over coffee methods."
```

Claude will:

1. Search your knowledge base for relevant documents
2. Summarize the key findings
3. Offer to explore specific documents in more detail

See [User Guide - Using Special Prompts](https://memory.basicmachines.co/user-guide.md#using-special-prompts) for further information.

## Using Your Knowledge Base

### Referencing Knowledge

In future conversations, reference your existing knowledge:

```
You: "What water temperature did we decide was optimal for coffee brewing?"
```

Or directly reference notes using memory:// URLs:

```
You: "Take a look at memory://coffee-brewing-methods and let's discuss how to improve my technique."
```

### Building On Previous Knowledge

Basic Memory enables continuous knowledge building:

1. **Reference previous discussions** in new conversations
2. **Edit notes incrementally** without rewriting entire documents
3. **Move and organize notes** as your knowledge base grows
4. **Switch between projects** instantly during conversations
5. **Search by tags** to find related content quickly
6. **Create connections** between related topics
7. **Follow relationships** to build comprehensive context

### Workflow Examples

**Incremental Editing:**

```
You: "Add a section about espresso to my coffee brewing notes"
Claude: [Uses edit_note to append new section]
```

**File Organization:**

```
You: "Move my old meeting notes to an archive folder"
Claude: [Uses move_note with database consistency]
```

**Project Switching:**

```
You: "Switch to my work project and show recent activity"
Claude: [Switches projects and shows work-specific content]
```

## Importing Existing Conversations

Import your existing AI conversations using the cli commands:

```bash theme={null}
# From Claude
basic-memory import claude conversations

# From ChatGPT
basic-memory import chatgpt
```

After importing, changes sync automatically in real-time. You can see project statistics by running `basic-memory project info`.

## Quick Tips

### General Usage

* Basic Memory syncs changes in real-time (no manual sync needed)
* Use special prompts (Continue Conversation, Recent Activity, Search) to start contextual discussions
* Build connections between notes for a richer knowledge graph
* Use direct `memory://` URLs with permalinks for precise context
* Review and edit AI-generated notes for accuracy

## Next Steps

After getting started, explore these areas:

> [card] [User Guide](https://memory.basicmachines.co/user-guide.md)
>
> Comprehensive usage instructions

> [card] [Knowledge Format](https://memory.basicmachines.co/guides/knowledge-format.md)
>
> Learn how knowledge is structured

> [card] [Obsidian Integration](https://memory.basicmachines.co/integrations/obsidian.md)
>
> Visual knowledge navigation

> [card] [Canvas Visualizations](https://memory.basicmachines.co/guides/canvas.md)
>
> Map concepts visually

> [card] [CLI Reference](https://memory.basicmachines.co/guides/cli-reference.md)
>
> Command line tools

> [card] [OAuth Authentication](https://memory.basicmachines.co/integrations/oauth-setup)
>
> Secure remote access (v0.13.5+)

### Staying Updated

To update Basic Memory when new versions are released:

```bash theme={null}
# Update stable release
uv tool upgrade basic-memory

# Homebrew
brew upgrade basic-memory
```

> [!NOTE]
>
> After updating, restart Claude Desktop for changes to take effect.

> [card] Fluid project switching
>
> Switch between projects during conversations

> [card] Advanced note editing
>
> Edit notes incrementally without rewriting

> [card] Smart file management
>
> Move and organize notes with database consistency

> [card] Enhanced search
>
> Search with frontmatter tag support

## Troubleshooting Installation

### Fix Path to uv

If you get an error that says `ENOENT` , this most likely means Claude Desktop could not find your `uv` installation. Make sure that you have `uv` installed per the instructions above, then:

**Step 1: Find the absolute path to uvx**

Open Terminal and run:

```bash theme={null}
which uvx
```

This will show you the full path (e.g., `/Users/yourusername/.cargo/bin/uvx`).

**Step 2: Edit Claude Desktop Configuration**

Edit the Claude Desktop config:

```json theme={null}
{
  "mcpServers": {
    "basic-memory": {
      "command": "/absolute/path/to/uvx",
      "args": [
        "basic-memory",
        "mcp"
      ]
    }
  }
}
```

Replace `/absolute/path/to/uvx` with the actual path you found in Step 1.

**Step 3: Restart Claude Desktop**

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

### Claude Says "No Basic Memory Tools Available"

If Claude cannot find Basic Memory tools:

1. **Check absolute paths**: Ensure you're using complete absolute paths to uvx in the Claude Desktop configuration
2. **Verify installation**: Run `basic-memory --version` in Terminal to confirm Basic Memory is installed
3. **Restart applications**: Restart both Terminal and Claude Desktop after making configuration changes
4. **Check sync status**: You can view the sync status by running `basic-memory status`

### Permission Issues

If you encounter permission errors:

1. Check that Basic Memory has access to create files in your home directory
2. Ensure Claude Desktop has permission to execute the uvx command


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.