Quickstart: Local

brew tap basicmachines-co/basic-memory
brew install basic-memory

uv tool install basic-memory

basic-memory --version

basic-memory, version 0.18.x

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

List my projects

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

Create a note called "Getting Started" with a summary of what Basic Memory does.

You: Create a note called "Getting Started" with a summary of what Basic Memory does.

Claude: I'll create a note for you.

[Uses write_note tool]

Done! I've created "Getting Started.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

# View in terminal
cat ~/basic-memory/Getting\ Started.md

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

~/basic-memory/
├── Getting Started.md
├── projects/
│   └── API Design.md
├── research/
│   └── Database Optimization.md
└── meetings/
    └── Team Standup 2024-01-15.md

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."

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

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

# Check sync status
basic-memory status

# List all projects
basic-memory project list

# View project statistics
basic-memory project info

# Import Claude conversations
basic-memory import claude conversations

# Import ChatGPT conversations
basic-memory import chatgpt

# Force re-sync all files
basic-memory sync

# 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"]
    }
  }
}

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