### Install All Basic Memory Skills

Source: https://docs.basicmemory.com/integrations/skills

Installs all available Basic Memory skills at once using npx. This is the recommended method for a comprehensive setup.

```bash
npx skills add basicmachines-co/basic-memory-skills

```

--------------------------------

### Project Folder Structure Example

Source: https://docs.basicmemory.com/cloud/web-app

Organize your projects using a hierarchical folder structure. This example shows a typical setup for managing active projects, research, decisions, meetings, and archived content.

```bash
~/basic-memory/
├── projects/       # Active projects
├── research/       # Learning and exploration
├── decisions/      # Decision records
├── meetings/       # Meeting notes
└── archive/        # Completed/old content


```

--------------------------------

### Local Basic Memory Setup and Project Addition

Source: https://docs.basicmemory.com/integrations/vscode

Install the Basic Memory CLI locally and add a project pointing to your local folder. This enables automatic syncing of markdown file edits to the knowledge graph.

```bash
# Install Basic Memory
uv tool install basic-memory

# Add a project pointing to a folder
bm project add my-project --local-path ~/workspace/my-project/docs

```

--------------------------------

### Setup rclone and Configure Credentials

Source: https://docs.basicmemory.com/cloud/cloud-sync

Installs the rclone utility and configures necessary credentials for cloud operations.

```bash
bm cloud setup              # Install rclone and configure credentials

```

--------------------------------

### Setup rclone for Cloud Sync

Source: https://docs.basicmemory.com/cloud/cloud-sync

Install rclone, a necessary tool for managing cloud storage synchronization with Basic Memory Cloud.

```bash
bm cloud setup
```

--------------------------------

### Setup and Upload Project Data

Source: https://docs.basicmemory.com/reference/cli-reference

Initialize cloud setup for a project and upload local files or directories. The `--create-project` flag can be used to create a new project if it doesn't exist.

```bash
bm cloud setup
bm cloud upload ~/my-notes --project research --create-project
```

--------------------------------

### Example Folder Structure

Source: https://docs.basicmemory.com/cloud/user-guide

Organize your notes into a hierarchical folder structure for better management. This example shows a common setup for projects, decisions, learning, meetings, and archives.

```tree
main/
├── projects/          # Active project notes
│   ├── api-redesign/
│   └── mobile-app/
├── decisions/         # Decision records
├── learning/          # Research and learning notes
├── meetings/          # Meeting notes
└── archive/           # Completed/old content

```

--------------------------------

### Install Hermes Basic Memory Plugin

Source: https://docs.basicmemory.com/whats-new/hermes-plugin

Install the hermes-basic-memory plugin using the hermes CLI.

```bash
hermes plugins install basicmachines-co/hermes-basic-memory

```

--------------------------------

### Install Basic Memory Locally

Source: https://docs.basicmemory.com/integrations/cursor

Install the Basic Memory package locally using either uv or pip.

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

# Or with pip
pip install basic-memory

```

--------------------------------

### Install Basic Memory Plugin

Source: https://docs.basicmemory.com/integrations/hermes

Use this command to install the basic-memory plugin. Ensure you have Hermes installed.

```bash
hermes plugins install basicmachines-co/hermes-basic-memory
```

--------------------------------

### Example Directory Structure

Source: https://docs.basicmemory.com/local/user-guide

Organize your project files into a clear directory structure for better management.

```text
~/basic-memory/
├── projects/          # Active project notes
│   ├── api-redesign/
│   └── mobile-app/
├── decisions/         # Decision records
├── learning/          # Research and learning notes
├── meetings/          # Meeting notes
└── archive/           # Completed/old content


```

--------------------------------

### Example Workflow Conversation

Source: https://docs.basicmemory.com/start-here/quickstart-cloud

This example conversation shows how to use prompts to create, search, and edit notes within Basic Memory Cloud.

```text
You: "I've been researching coffee brewing methods. Create a note about pour-over technique."

AI: [Creates note with observations and tags]

---
Later
---

You: "What do I know about coffee brewing?"

Claude: [Searches knowledge base, finds your pour-over note]
"Based on your notes, you've been exploring pour-over techniques..."

You: "Add a section about water temperature to my coffee notes"

Claude: [Uses edit_note to append new content]

```

--------------------------------

### Install Basic Memory CLI with uv

Source: https://docs.basicmemory.com/local/local-install

Use this command to install the Basic Memory CLI if you are using the `uv` package manager.

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

--------------------------------

### Install and Restart OpenClaw Plugin

Source: https://docs.basicmemory.com/integrations/openclaw

Install the OpenClaw Basic Memory plugin and restart the OpenClaw gateway to enable its features.

```bash
openclaw plugins install @basicmemory/openclaw-basic-memory
openclaw gateway restart

```

--------------------------------

### Example Workflow Prompts

Source: https://docs.basicmemory.com/start-here/quickstart-cloud

These prompts demonstrate a workflow for interacting with your AI assistant to manage notes in Basic Memory Cloud.

```bash
Create a note about [topic]

```

```bash
What have we discussed recently?

```

```bash
Find notes about [topic]

```

```bash
Continue our conversation about [topic]

```

```bash
Add to my notes about [topic]

```

```bash
Show me my notes on [topic]

```

--------------------------------

### Setup Project Sync Path

Source: https://docs.basicmemory.com/cloud/cloud-sync

Configure the local sync path for a project if it's missing, then perform an initial `--resync`.

```bash
bm cloud sync-setup research ~/Documents/research
bm cloud bisync --name research --resync

```

--------------------------------

### Example Notes Folder Structure

Source: https://docs.basicmemory.com/start-here/quickstart-local

Illustrates a typical directory structure for notes managed by Basic Memory.

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

```

--------------------------------

### Hybrid Setup: Route Shared Projects to Cloud

Source: https://docs.basicmemory.com/cloud/routing

Configure a hybrid setup by saving your API key and then routing specific shared projects to the cloud. Personal projects remain local by default.

```bash
# Save your API key for per-project routing
bm cloud api-key save bmc_your_key_here
```

```bash
# Route shared projects to cloud
bm project set-cloud shared-notes
bm project set-cloud team-wiki
```

--------------------------------

### Install Basic Memory via uv

Source: https://docs.basicmemory.com/start-here/quickstart-local

Install Basic Memory using the uv tool on any platform. Requires Python 3.13 or higher.

```bash
uv tool install basic-memory

```

--------------------------------

### Install Sync Tooling

Source: https://docs.basicmemory.com/cloud/edit-locally-and-in-the-app

Installs and configures rclone, the underlying tool used for bidirectional synchronization.

```bash
bm cloud setup

```

--------------------------------

### Complete Annotated Picoschema Example

Source: https://docs.basicmemory.com/concepts/schema-system

An example demonstrating a complete schema definition with various types, modifiers, and descriptions.

```yaml
schema:
  name: string, full legal name
  role?: string, current job title
  email?: string, primary contact email
  works_at?: Organization, primary employer
  expertise?(array, areas of knowledge): string
  status?(enum, current relationship status): [active, inactive, alumni]
  contact_info?(object):
    phone?: string
    location?: string
```

--------------------------------

### AI Note Organization Example

Source: https://docs.basicmemory.com/cloud/user-guide

Use AI commands to organize notes. This example shows how to move notes to an archive folder.

```text
You: "Move my old meeting notes to the archive folder"

Claude: [Uses move_note]
"Done! I've moved 12 meeting notes to the archive folder."

```

--------------------------------

### Basic Memory CLI Quick Start

Source: https://docs.basicmemory.com/cloud/cloud-guide

A quick sequence of commands to authenticate, check status, and list projects using the Basic Memory CLI.

```bash
# 1. Authenticate
bm cloud login

# 2. Check Status
bm cloud status

# 3. List Projects
bm project list

```

--------------------------------

### Example Basic Memory Cloud API Key

Source: https://docs.basicmemory.com/cloud/api-keys

An example of a fully formed Basic Memory Cloud API key.

```text
bmc_K7xR2pQmNvLwYhT9sU3fAeBcDgHiJkMnOpQrStUv
```

--------------------------------

### Install Basic Memory CLI with Homebrew

Source: https://docs.basicmemory.com/local/local-install

Install the Basic Memory CLI using Homebrew. The `brew trust` command is recommended for untrusted taps on newer Homebrew versions.

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

--------------------------------

### Basic Memory CLI Project List Example Output

Source: https://docs.basicmemory.com/cloud/cloud-guide

Example output format for the 'bm project list' command, showing project names, paths, and default status.

```bash
           Basic Memory Projects
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Name ┃ Path                   ┃ Default ┃
┡━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ main │ /app/data/basic-memory │ ✓       │
└──────┴────────────────────────┴─────────┘


```

--------------------------------

### Memory URL Examples

Source: https://docs.basicmemory.com/start-here/what-is-basic-memory

Examples of how to reference knowledge using memory:// URLs. These can point to specific notes, follow relations, or reference notes by path.

```text
memory://api-authentication          # Reference by permalink
memory://api-authentication/relates_to/*  # Follow all 'relates_to' links
memory://folder/note-title           # Reference by path
```

--------------------------------

### Example Basic Memory Configuration

Source: https://docs.basicmemory.com/reference/configuration

This JSON configuration defines default project, project-specific paths and modes, and enables semantic search with a minimum similarity threshold.

```json
{
  "default_project": "main",
  "projects": {
    "main": {
      "path": "/Users/you/basic-memory",
      "mode": "local"
    },
    "research": {
      "path": "/Users/you/research-notes",
      "mode": "cloud",
      "cloud_sync_path": "/Users/you/research-notes",
      "bisync_initialized": true,
      "last_sync": "2026-02-15T18:30:00Z"
    }
  },
  "semantic_search_enabled": true,
  "semantic_min_similarity": 0.55,
  "permalinks_include_project": true,
  "cloud_mode": false
}
```

--------------------------------

### Create a Note Documenting API Authentication

Source: https://docs.basicmemory.com/integrations/cursor

Example prompt to create a note about API authentication and link it to a specific module.

```text
"Create a note documenting our API authentication approach and link it to the user-auth module."
```

--------------------------------

### AI Directory Operation Example

Source: https://docs.basicmemory.com/cloud/user-guide

Perform directory operations using AI. This example shows moving an entire folder to the archive.

```text
You: "Move the old-projects folder to archive"

Claude: [Uses move_note with is_directory=true]
"Moved old-projects/ → archive/old-projects/ (15 files)"

```

--------------------------------

### Install Local Basic Memory MCP Globally

Source: https://docs.basicmemory.com/integrations/gemini

Install the local Basic Memory MCP globally for your user profile. Use the '-s user' flag to make it available across all your projects.

```bash
gemini mcp add -s user basic-memory bash -c "uvx basic-memory mcp"

```

--------------------------------

### Install uv package manager

Source: https://docs.basicmemory.com/reference/troubleshooting

Install the uv package manager using a curl script. This is necessary if the 'uv' command is not found.

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

```

--------------------------------

### Install a Single Basic Memory Skill

Source: https://docs.basicmemory.com/integrations/skills

Installs a specific Basic Memory skill, such as 'memory-tasks', using npx. Useful when only certain functionalities are needed.

```bash
npx skills add basicmachines-co/basic-memory-skills --skill memory-tasks

```

--------------------------------

### Search Notes for Database Migration Strategy

Source: https://docs.basicmemory.com/integrations/cursor

Example prompt to search existing notes for information related to database migration strategy.

```text
"Search my notes for anything related to database migration strategy."
```

--------------------------------

### Install Local Basic Memory MCP

Source: https://docs.basicmemory.com/integrations/gemini

Install the local Basic Memory MCP for Gemini integration. This command sets up the necessary components for local persistent knowledge.

```bash
gemini mcp add basic-memory bash -c "uvx basic-memory mcp"

```

--------------------------------

### Text Search Example (CLI)

Source: https://docs.basicmemory.com/concepts/semantic-search

Use this command for keyword-based searches when you know the exact terms. Boolean operators like AND/OR are supported.

```bash
bm tool search-notes "project AND planning"
```

--------------------------------

### Example Project Folder Structure

Source: https://docs.basicmemory.com/concepts/projects-and-folders

Illustrates a common organizational pattern for work-related notes using nested folders within a project directory.

```directory
~/Documents/work-notes/
  meetings/
  decisions/
  architecture/
  onboarding/

```

--------------------------------

### AI Note Editing Example

Source: https://docs.basicmemory.com/cloud/user-guide

Instruct AI to edit notes. This example demonstrates appending content to a guide.

```text
You: "Add a troubleshooting section to my setup guide"

Claude: [Uses edit_note with append operation]
"I've added a troubleshooting section to the end of your setup guide."

```

--------------------------------

### Multi-Project Conversation Example

Source: https://docs.basicmemory.com/start-here/getting-started

Illustrates how Basic Memory handles project selection during a conversation, prompting the user to choose a project.

```text
You: "Let's work on documentation"

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

You: "Yes, let's use work-notes"
```

--------------------------------

### Perform Initial Project Sync (Preview and Run)

Source: https://docs.basicmemory.com/cloud/cloud-sync

Guides through the initial synchronization of a project. It is crucial to preview the sync with `--dry-run` first before executing the actual sync using `--resync`.

```bash
# Step 1: Preview the initial sync
bm cloud bisync --name research --resync --dry-run

# Step 2: If all looks good, run the actual sync
bm cloud bisync --name research --resync

```

--------------------------------

### Establish Sync Baseline

Source: https://docs.basicmemory.com/integrations/obsidian

Preview and then run the initial bidirectional synchronization for a project. Use `--resync` only for the first sync.

```bash
# Preview first (recommended)
bm cloud bisync --name my-vault --resync --dry-run

# If all looks good, establish baseline
bm cloud bisync --name my-vault --resync

```

--------------------------------

### Two-Way Sync (Recommended)

Source: https://docs.basicmemory.com/cloud/cloud-sync

Performs a two-way synchronization between local and cloud projects. Use `--resync` for the initial setup or to force a baseline.

```bash
# Two-way sync (recommended)
bm cloud bisync --name <project>          # After first --resync
bm cloud bisync --name <project> --resync # First time / force baseline
bm cloud bisync --name <project> --dry-run
bm cloud bisync --name <project> --verbose

```

--------------------------------

### Create Project via Command Line and AI

Source: https://docs.basicmemory.com/start-here/getting-started

Demonstrates creating a new project using both the command line and conversational AI prompts.

```bash
# Command line
basic-memory project add "work-notes" ~/Documents/work
```

```text
# Or ask your AI assistant
You: "Create a new project called 'work-notes' in ~/Documents/work"
```

--------------------------------

### Example Conversation for Creating a Note

Source: https://docs.basicmemory.com/start-here/quickstart-cloud

This illustrates a typical conversation flow when creating a note using the 'write_note' tool.

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

AI: I'll create a note summarizing Basic Memory for you.

[Uses write_note tool]

I've created "Getting Started" in your knowledge base. The note covers:
- What Basic Memory is
- How the knowledge format works
- Key features like semantic search and relations

```

--------------------------------

### Get llms.txt Index with curl

Source: https://docs.basicmemory.com/reference/llms-txt

Fetch the llms.txt file using curl to get an index of all documentation pages with direct links to their raw markdown content. This serves as a starting point for discovering available documentation.

```bash
curl https://docs.basicmemory.com/llms.txt

```

--------------------------------

### Troubleshoot Local MCP Server

Source: https://docs.basicmemory.com/integrations/claude-code

If local MCP tools are not showing up, verify the installation and re-add the server using these commands.

```bash
claude mcp remove basic-memory && claude mcp add basic-memory basic-memory mcp

```

--------------------------------

### Example Note Structure

Source: https://docs.basicmemory.com/concepts/knowledge-format

This is a typical note created by an AI, showcasing frontmatter, content with observations, and relational links.

```markdown
---
title: Authentication Design
type: note
tags: [auth, security, backend]
permalink: authentication-design
---

# Authentication Design

## Observations
- [decision] Using JWT tokens for stateless authentication #security
- [approach] Refresh tokens stored in HTTP-only cookies to prevent XSS
- [constraint] Tokens expire after 15 minutes to limit exposure window
- [status] Implementation complete and deployed to staging

## Relations
- implements [[API Security Requirements]]
- depends_on [[User Database Schema]]
- relates_to [[Session Management]]

```

--------------------------------

### Metadata Search Examples

Source: https://docs.basicmemory.com/how-to/writing-organization

Filter notes by their properties such as type, tags, or status. This helps in getting overviews and managing project elements.

```natural-language
You: "Show me all notes with type character."
```

```natural-language
You: "Find chapter notes tagged as draft."
```

```natural-language
You: "What research notes are tagged neuroscience?"
```

--------------------------------

### Set Up Existing Cloud Project Locally

Source: https://docs.basicmemory.com/cloud/edit-locally-and-in-the-app

Connects an existing cloud project to a new local folder. Use this when you want to clone a cloud project to your local machine.

```bash
bm cloud sync-setup my-notes ~/notes

```

--------------------------------

### Configure MCP for Local Basic Memory Setup

Source: https://docs.basicmemory.com/integrations/cursor

Add this JSON configuration to Cursor's developer settings to connect to a locally installed Basic Memory instance.

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

--------------------------------

### Create a Snapshot using CLI

Source: https://docs.basicmemory.com/cloud/cloud-snapshots

Use this command to create a manual snapshot of your knowledge base. Add a descriptive name to easily identify it later. This is recommended before making significant changes.

```bash
bm cloud snapshot create "Before reorganization"
```

--------------------------------

### Vector Search Example (CLI)

Source: https://docs.basicmemory.com/concepts/semantic-search

Employ this command for conceptual queries where exact wording is less important. It searches based on the meaning of your query.

```bash
bm tool search-notes "ways to make the frontend faster" --vector
```

--------------------------------

### Install MCP Python Package

Source: https://docs.basicmemory.com/integrations/hermes

If the 'mcp' Python package is not automatically installed, manually install it using uv pip within the Hermes venv.

```bash
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python mcp
```

--------------------------------

### Add Projects with Local Sync Paths

Source: https://docs.basicmemory.com/cloud/cloud-sync

Demonstrates creating cloud projects with and without local sync paths, and configuring sync for existing projects.

```bash
# Create cloud project without local sync
bm project add research

# Create cloud project WITH local sync
bm project add research --local-path ~/Documents/research

# Or configure sync for existing project
bm cloud sync-setup research ~/Documents/research

```

--------------------------------

### Hybrid Search Example (CLI)

Source: https://docs.basicmemory.com/concepts/semantic-search

This is the default search mode, combining keyword precision with meaning-based recall. Use it for general-purpose searching.

```bash
bm tool search-notes "authentication security"
```

--------------------------------

### Check for and install updates

Source: https://docs.basicmemory.com/reference/cli-reference

Checks for a newer Basic Memory release and installs it if available and supported. The --check flag performs a check only, without installing.

```bash
# Check for updates and install if available
bm update
```

```bash
# Check only — report without installing
bm update --check
```

--------------------------------

### Manually Run Basic Memory Watcher

Source: https://docs.basicmemory.com/integrations/claude-desktop

If real-time sync is not working, you can manually start the Basic Memory watcher from the command line to monitor file changes.

```bash
basic-memory watch
```

--------------------------------

### Example Conversation for Project Selection

Source: https://docs.basicmemory.com/cloud/user-guide

Illustrates how the AI interacts with the user to select the appropriate project for a conversation based on availability and recent activity.

```text
You: "Let's work on documentation"

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

You: "Yes, let's use work-notes"

Claude: I'll use the 'work-notes' project for our session.

```

--------------------------------

### Set Up Bidirectional Sync

Source: https://docs.basicmemory.com/cloud/cloud-guide

Configure your local project to sync bidirectionally with the cloud. This involves logging in, setting up sync, adding your project, and performing an initial sync. A dry run is recommended before establishing the baseline.

```bash
# Login and setup sync
bm cloud login
bm cloud setup

# Add existing project with sync enabled
bm project add main --local-path ~/basic-memory

# Initial sync (resync creates baseline)
bm cloud bisync --name main --resync --dry-run  # preview first
bm cloud bisync --name main --resync             # establish baseline

# Ongoing sync (run after local or cloud changes)
bm cloud bisync --name main

```

--------------------------------

### Complete Cloud Upload Workflow

Source: https://docs.basicmemory.com/cloud/cloud-guide

This sequence demonstrates a typical workflow: logging in, uploading a project (creating it if necessary), and verifying the upload.

```bash
# 1. Login to cloud
bm cloud login

# 2. Upload local project (creates project if needed)
bm cloud upload ~/specs --project specs --create-project

# 3. Verify upload
bm project list
```

--------------------------------

### Start Docker Compose Services

Source: https://docs.basicmemory.com/reference/docker

Starts all services defined in the docker-compose.yml file in detached mode.

```bash
docker compose up -d

```

--------------------------------

### Validation Example: Valid Note

Source: https://docs.basicmemory.com/concepts/schema-system

Example output of validating a note that conforms to the schema, showing zero warnings.

```bash
$ bm schema validate people/grace-hopper.md
✓ grace-hopper: valid (0 warnings)

```

--------------------------------

### Preview and Establish Cloud Sync Baseline

Source: https://docs.basicmemory.com/integrations/vscode

Preview the initial bidirectional sync with `--dry-run` before establishing the baseline. Use `--resync` only for the very first sync.

```bash
# Preview first (recommended)
bm cloud bisync --name my-project --resync --dry-run

# Establish baseline
bm cloud bisync --name my-project --resync

```

--------------------------------

### Add and Sync Multiple Projects

Source: https://docs.basicmemory.com/cloud/cloud-sync

Set up multiple projects with local paths and establish initial baselines for cloud synchronization. Daily workflow involves syncing all configured projects.

```bash
# Setup multiple projects
bm project add research --local-path ~/Documents/research
bm project add work --local-path ~/work-notes
bm project add personal --local-path ~/personal

# Establish baselines
bm cloud bisync --name research --resync
bm cloud bisync --name work --resync
bm cloud bisync --name personal --resync

# Daily workflow: sync everything
bm cloud bisync --name research
bm cloud bisync --name work
bm cloud bisync --name personal

```

--------------------------------

### Install Python 3.13 on macOS

Source: https://docs.basicmemory.com/reference/troubleshooting

Install Python 3.13 or higher using Homebrew on macOS to resolve Python version errors.

```bash
# macOS with Homebrew
brew install python@3.13

```

--------------------------------

### Example Note Frontmatter

Source: https://docs.basicmemory.com/concepts/metadata-search

This is an example of YAML frontmatter that can be included at the top of a note. These fields are searchable using the metadata search functionality.

```yaml
---
title: Auth Design
type: spec
tags: [security, oauth]
status: in-progress
priority: high
confidence: 0.85
---
```

--------------------------------

### Example Shared Note URL

Source: https://docs.basicmemory.com/cloud/shared-notes

This is an example of the public, read-only link generated for a shared note. The token is unique to each shared note.

```text
https://cloud.basicmemory.com/s/<token>
```

--------------------------------

### List Projects and Check Directory

Source: https://docs.basicmemory.com/reference/troubleshooting

Confirm that your files are in the correct project directory by listing projects and then checking the directory contents.

```bash
basic-memory project list
ls ~/basic-memory

```

--------------------------------

### Example File Organization in Basic Memory

Source: https://docs.basicmemory.com/concepts/knowledge-format

Demonstrates a flexible folder structure for organizing notes within a Basic Memory project. The knowledge graph connects content regardless of its location.

```treeview
knowledge/
  projects/
    auth-design.md
    api-roadmap.md
  meetings/
    2026-03-01-standup.md
  decisions/
    database-choice.md
```

--------------------------------

### Create First Note Prompt

Source: https://docs.basicmemory.com/start-here/quickstart-cloud

Use this prompt to create your first note in Basic Memory Cloud. The assistant will use the 'write_note' tool.

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

```

--------------------------------

### Install Python 3.13 using pyenv

Source: https://docs.basicmemory.com/reference/troubleshooting

Install and set Python 3.13 as the global version using pyenv to resolve Python version errors.

```bash
# Or use pyenv
pyenv install 3.13.0
pyenv global 3.13.0

```

--------------------------------

### Install Basic Memory via Homebrew

Source: https://docs.basicmemory.com/start-here/quickstart-local

Use this command on macOS to install Basic Memory using Homebrew. Ensure you trust the tap first.

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

```

--------------------------------

### Validation Example: Frontmatter Enum Mismatch

Source: https://docs.basicmemory.com/concepts/schema-system

Example output of validating a note with a frontmatter enum mismatch, indicating the invalid value and expected options.

```bash
$ bm schema validate people/iris-west.md
⚠ iris-west: frontmatter field 'status' enum mismatch (got 'archived', expected one of: draft, published)

```

--------------------------------

### Upload and Create Project

Source: https://docs.basicmemory.com/cloud/cloud-guide

This command uploads a local directory and creates a new cloud project if it doesn't already exist.

```bash
# Upload and create project in one step
bm cloud upload ~/local-project --project new-research --create-project
```

--------------------------------

### Validation Example: Missing Required Frontmatter Field

Source: https://docs.basicmemory.com/concepts/schema-system

Example output of validating a note missing a required frontmatter field, showing the missing field name.

```bash
$ bm schema validate people/hank-pym.md
⚠ hank-pym: missing required frontmatter field: status

```

--------------------------------

### Example Basic Memory Workflow

Source: https://docs.basicmemory.com/start-here/quickstart-local

Illustrates a typical interaction flow with Claude for documenting API design decisions, including note creation, querying, and editing.

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

```

--------------------------------

### Log In to Cloud

Source: https://docs.basicmemory.com/cloud/routing

Log in to your Basic Memory cloud instance. After logging in, all projects will route through your cloud instance.

```bash
bm cloud login
```

--------------------------------

### Target Skill Installation for a Specific Agent

Source: https://docs.basicmemory.com/integrations/skills

Installs Basic Memory skills and targets them for a specific agent, like 'claude', using npx. Ensures compatibility and proper integration.

```bash
npx skills add basicmachines-co/basic-memory-skills --agent claude

```

--------------------------------

### Create a Manual Snapshot

Source: https://docs.basicmemory.com/cloud/restore-lost-content

Create a manual snapshot before making significant changes to your project to ensure you have a rollback point. This is a quick and free operation.

```bash
bm cloud snapshot create "Before reorganizing research/"
```

--------------------------------

### Create and Set Default Project via AI

Source: https://docs.basicmemory.com/start-here/getting-started

Use conversational prompts to create a new project and set it as the default. This is an alternative to using the command line.

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

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

--------------------------------

### Authentication Design Decision Example

Source: https://docs.basicmemory.com/concepts/vs-built-in-memory

This snippet shows an example of how to structure a decision document using markdown with frontmatter. It includes title, type, tags, observations, relations, and dependencies.

```markdown
---
title: Authentication Design Decision
type: decision
tags: [auth, security, api]
---

# Authentication Design Decision

## Observations
- [decision] Using JWT with refresh tokens for stateless auth
- [rationale] Chose JWT over sessions for horizontal scaling
- [constraint] Refresh tokens rotate on each use
- [risk] Token revocation requires a blacklist check

## Relations
- implements [[API Security Requirements]]
- depends_on [[User Database Schema]]
- informs [[Rate Limiting Strategy]]

```

--------------------------------

### Add and Set Default Basic Memory Project

Source: https://docs.basicmemory.com/start-here/quickstart-local

Demonstrates how to add a new project for storing notes and then set it as the default project for basic-memory.

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

```

--------------------------------

### Start Local Basic Memory MCP Server

Source: https://docs.basicmemory.com/integrations/codex

Starts a local HTTP MCP server for Basic Memory on a specified port. This is used when connecting the Codex app to a local Basic Memory instance.

```bash
basic-memory mcp --transport streamable-http --port 8000

```

--------------------------------

### Clone Basic Memory Skills Repository

Source: https://docs.basicmemory.com/integrations/skills

Manually installs Basic Memory skills by cloning the GitHub repository and copying the skill folders to the agent's skills directory. This method provides direct access to the skill files.

```bash
git clone https://github.com/basicmachines-co/basic-memory-skills.git
cp -r basic-memory-skills/memory-notes ~/.claude/skills/

```

--------------------------------

### Basic Memory Plugin Status Output

Source: https://docs.basicmemory.com/integrations/hermes

This is the expected output when the basic-memory plugin is successfully installed and available.

```text
  Provider:  basic-memory
  Plugin:    installed ✓
  Status:    available ✓
```

--------------------------------

### Set Up Bidirectional Sync

Source: https://docs.basicmemory.com/cloud/user-guide

Use these commands to log in, set up, and initiate bidirectional sync for your cloud notes to a local folder. Changes in either location sync automatically.

```bash
bm cloud login
bm cloud setup
bm cloud bisync --name main
```

--------------------------------

### build_context

Source: https://docs.basicmemory.com/reference/mcp-tools-reference

Constructs a context graph by traversing a knowledge graph from a starting memory URL to a specified depth.

```APIDOC
## build_context

### Description
Build context graph from a memory URL. Traverses the knowledge graph from a starting entity, following relations to a configurable depth.

### Parameters
#### Path Parameters
- **url** (string) - Required - `memory://` URL or path.

#### Query Parameters
- **depth** (string or integer) - Optional - Traversal depth (default `1`). Use `2` or `3` for broader context.
- **timeframe** (string) - Optional - Time window filter (default `7d`). Accepts formats like `7d`, `1 week`, `30d`, `3 months`.
- **page** (integer) - Optional - Default `1`.
- **page_size** (integer) - Optional - Default `10`.
- **max_related** (integer) - Optional - Maximum related entities per level (default `10`).
- **output_format** (string) - Optional - Default `"json"`. Also accepts `"text"` for human-readable output.

### TimeFrame Examples
- `7d`: Last 7 days
- `30d`: Last 30 days
- `1 week`: Last week
- `3 months`: Last 3 months
- `1 year`: Last year
```

--------------------------------

### Configure Local Sync

Source: https://docs.basicmemory.com/reference/cli-reference

Set up local synchronization for an existing cloud project, linking a local directory to a cloud project.

```bash
# Configure local sync for an existing cloud project
bm cloud sync-setup research ~/Documents/research
```

--------------------------------

### Query Recent Activity

Source: https://docs.basicmemory.com/integrations/cursor

Example prompt to ask the AI about recent project activity based on notes.

```text
"What have I been working on this week? Check recent activity."
```

--------------------------------

### Upgrade Basic Memory with Homebrew

Source: https://docs.basicmemory.com/whats-new/v0.22.0

Use this command to upgrade the Basic Memory tool if you installed it via Homebrew.

```bash
brew upgrade basic-memory
```

--------------------------------

### Verify Basic Memory Plugin Status

Source: https://docs.basicmemory.com/integrations/hermes

Check the status of the installed basic-memory plugin to confirm it is active and available.

```bash
hermes memory status
```

--------------------------------

### List and Add Projects using BM CLI

Source: https://docs.basicmemory.com/local/cli-basics

Use `bm project list` to see existing projects and `bm project add` to create a new one. Ensure the project name is quoted if it contains spaces.

```bash
bm project list
```

```bash
bm project add "research" ~/Documents/research
```

--------------------------------

### Check Basic Memory Version

Source: https://docs.basicmemory.com/integrations/claude-desktop

Verify that Basic Memory is installed correctly by checking its version from the command line.

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

--------------------------------

### Initialize Git Repository for Basic Memory Files

Source: https://docs.basicmemory.com/local/user-guide

Integrate Basic Memory with Git by initializing a repository, adding files, and making an initial commit. This provides version history, backup, and collaboration capabilities.

```bash
cd ~/basic-memory
git init
git add .
git commit -m "Initial knowledge base"
```

--------------------------------

### Create Cloud Project with Local Sync

Source: https://docs.basicmemory.com/cloud/cloud-sync

Creates a new project in the cloud and configures it for synchronization with a specified local path.

```bash
bm project add <name> --local-path <path> # Create with local sync

```

--------------------------------

### Metadata Search Query for Tagged Notes

Source: https://docs.basicmemory.com/how-to/personal-knowledge

Example of a metadata search query to list all notes that have been tagged with 'health'.

```plaintext
"> List all notes tagged with health"
```

--------------------------------

### CLI Convenience Shortcuts

Source: https://docs.basicmemory.com/concepts/metadata-search

Demonstrates using CLI convenience shortcuts for tags, status, and type filters in a single command.

```bash
bm tool search-notes "auth" --tag security --tag oauth --status draft --type spec
```

--------------------------------

### Sign in to Cloud

Source: https://docs.basicmemory.com/cloud/edit-locally-and-in-the-app

Authenticates your CLI with the Basic Memory cloud service. A browser tab will guide you through the OAuth process.

```bash
bm cloud login

```

--------------------------------

### Add uv to PATH

Source: https://docs.basicmemory.com/reference/troubleshooting

After installing uv, add it to your system's PATH. Restart your terminal or run the source command.

```bash
# Then add to PATH (restart terminal or run)
source ~/.bashrc  # or ~/.zshrc

```

--------------------------------

### Create Cloud Snapshot

Source: https://docs.basicmemory.com/cloud/cloud-guide

Create a manual snapshot of your cloud data before making significant changes. This is useful for backup and recovery.

```bash
# Create a snapshot before major changes
bm cloud snapshot create "Before reorganization"
```

--------------------------------

### Create a Note with Type and Metadata

Source: https://docs.basicmemory.com/reference/ai-assistant-guide

This example shows how to create a note specifying its `note_type` for schema association and search filtering, and includes custom `metadata` for additional searchable fields like 'sprint' and 'team'.

```python
await write_note(
    title="Sprint Planning 2026-02-15",
    content="...",
    directory="meetings",
    note_type="meeting",
    metadata={"sprint": 12, "team": "backend"},
    project="main"
)

```

--------------------------------

### AI Conversation Recording Prompt

Source: https://docs.basicmemory.com/reference/ai-assistant-guide

Example dialogue for an AI assistant asking for permission to save a discussion to Basic Memory.

```text
AI: "Would you like me to save our discussion about API authentication
     to Basic Memory? This helps us continue this conversation later."

User: "Yes, please"

AI: [Saves to Basic Memory]
    "I've saved our discussion as 'API Authentication Discussion'."
```