# Quickstart: Local

> Install Basic Memory locally and connect it to your AI assistant.

Local mode keeps notes on your machine and runs the MCP server locally. It's open-source and free to use.

<mermaid code="flowchart LR
    A[Install] --> B[Configure]
    B --> C[Connect]
    C --> D[Create Notes]
">



</mermaid>

---

<tip>

**Prefer not to install anything?** Basic Memory Cloud connects your AI in about 2 minutes — [sign up at basicmemory.com](https://basicmemory.com/?utm_source=docs&utm_medium=docs&utm_campaign=quickstart-local) and follow the [cloud quickstart](/start-here/quickstart-cloud).

</tip>

## 1. Install Basic Memory

Choose your installation method. All installs include semantic search for hybrid (keyword + meaning-based) search.

### macOS (Homebrew) - Recommended

```bash
brew tap basicmachines-co/basic-memory
brew trust basicmachines-co/basic-memory
brew install basic-memory
```

<note>

`brew trust` accepts code from this third-party tap. On older Homebrew versions the command doesn't exist yet — just skip it. Details in [Local Installation](/local/local-install).

</note>

### All platforms (uv)

First install `uv` from [astral.sh](https://docs.astral.sh/uv/getting-started/installation/), then:

```bash
uv tool install basic-memory
```

<note>

**Requirements:** Python 3.12 or higher. Check with `python --version`.

</note>

### Verify installation

```bash
basic-memory --version
```

You should see the installed version printed. If it's older than the [latest release](https://github.com/basicmachines-co/basic-memory/releases), run `bm update` (`bm` is a short alias for `basic-memory`).

---

## 2. Configure Claude Desktop

Add Basic Memory to your `claude_desktop_config.json`:

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

Installed with Homebrew? Use `"command": "basic-memory", "args": ["mcp"]` instead. **Restart Claude Desktop** after editing.

Config file locations per platform and ENOENT fixes: [Claude Desktop → Local Setup](/integrations/claude-desktop#local-setup).

---

## 3. Verify the connection

In Claude Desktop, open the **search and tools** menu in the chat input area. You should see Basic Memory tools listed.

Ask Claude:

```bash
List my projects
```

**Expected response:**

```bash
You have 1 project:
- main (default) - ~/basic-memory - 0 notes
```

---

## 4. Create your first note

Try this prompt:

```bash
Create a note called "My First Note" with a summary of what Basic Memory does.
```

Claude will create a Markdown file at `~/basic-memory/My First Note.md`.

**Example conversation:**

```bash
You: Create a note called "My First Note" with a summary of what Basic Memory does.

Claude: I'll create a note for you.

[Uses write_note tool]

Done! I've created "My First Note.md" in your basic-memory folder.
It includes an overview of Basic Memory's key features:
- Knowledge storage in Markdown
- Semantic observations and relations
- Search across your knowledge base
```

---

## 5. View your notes

Your notes are stored at `~/basic-memory` by default. You can:

### Open in any text editor

```bash
# View in terminal
cat ~/basic-memory/My\ First\ Note.md

# Open folder
open ~/basic-memory  # macOS
explorer ~/basic-memory  # Windows
```

### Use Obsidian for visual navigation

1. Open Obsidian
2. **Create new vault** → select `~/basic-memory`
3. Use the **graph view** to see connections between notes

### Example note structure

After creating a few notes, your folder might look like:

```bash
~/basic-memory/
├── My First Note.md
├── projects/
│   └── API Design.md
├── research/
│   └── Database Optimization.md
└── meetings/
    └── Team Standup 2026-06-15.md
```

---

## What you can do now

Try these prompts with Claude:

<table>
<thead>
  <tr>
    <th>
      Prompt
    </th>
    
    <th>
      What it does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        Create a note about [topic]
      </code>
    </td>
    
    <td>
      Creates a new Markdown file
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        What have we discussed recently?
      </code>
    </td>
    
    <td>
      Shows recently modified notes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Find notes about [topic]
      </code>
    </td>
    
    <td>
      Searches your knowledge base
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Continue our conversation about [topic]
      </code>
    </td>
    
    <td>
      Loads context from previous notes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Add to my [topic] notes
      </code>
    </td>
    
    <td>
      Edits an existing note
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Move my [note] to the archive folder
      </code>
    </td>
    
    <td>
      Reorganizes files
    </td>
  </tr>
</tbody>
</table>

### Example workflow

```bash
You: "Let's document our API design decisions"

Claude: I'll create a note for the API design decisions.
[Creates ~/basic-memory/API Design Decisions.md]

--- Later ---

You: "What did we decide about authentication?"

Claude: [Searches knowledge base]
"Based on your 'API Design Decisions' note, you decided to use JWT tokens..."

You: "Add a section about rate limiting"

Claude: [Uses edit_note to append]
"I've added a rate limiting section to your API design notes."
```

---

## Customize your setup

### Change where notes are saved

```bash
# Create a new project in a different location
basic-memory project add "my-notes" ~/Documents/notes

# Make it the default
basic-memory project default "my-notes"
```

Restart Claude Desktop for changes to take effect. For more on projects and default-project configuration, see [Set Up Local Projects](/local/getting-started).

---

## Useful CLI commands

```bash
# Check project index status
basic-memory status

# List all projects
basic-memory project list

# View project statistics
basic-memory project info main

# Import Claude conversations
basic-memory import claude conversations

# Import ChatGPT conversations
basic-memory import chatgpt

# Rebuild the search index
basic-memory reindex
```

---

## Troubleshooting

### ENOENT error

Claude Desktop can't find `uvx`. Use the full path:

```bash
# Find the path
which uvx
# Output: /Users/yourname/.local/bin/uvx

# Update config to use full path
{
  "mcpServers": {
    "basic-memory": {
      "command": "/Users/yourname/.local/bin/uvx",
      "args": ["basic-memory", "mcp"]
    }
  }
}
```

### No tools showing

1. Verify installation: `basic-memory --version`
2. Check the config file syntax (valid JSON)
3. Restart Claude Desktop completely

### Permission errors

```bash
# Fix permissions on the notes folder
chmod -R u+rw ~/basic-memory
```

See the full [Troubleshooting](/reference/troubleshooting) guide for more solutions.

---

## Next steps

<card-group>
<card icon="i-lucide-terminal" title="CLI Basics" to="/local/cli-basics">

Learn the command line tools for managing your knowledge.

</card>

<card icon="i-lucide-settings" title="Configuration" to="/reference/configuration">

All configuration options and environment variables.

</card>

<card icon="i-lucide-file-text" title="Knowledge Format" to="/concepts/knowledge-format">

Learn the note structure with observations and relations.

</card>

<card icon="i-lucide-hexagon" title="Obsidian Integration" to="/integrations/obsidian">

Visual knowledge navigation with graph view.

</card>
</card-group>