User Guide

Learn how to effectively use Basic Memory in your daily workflow to build rich semantic knowledge

Once you have Basic Memory installed, here’s how to make the most of it. This covers everything from creating your first notes to building a comprehensive knowledge graph.

Basic Memory Workflow

Using Basic Memory follows a natural cycle:

1. Have conversations with AI assistants like Claude
2. Capture knowledge in Markdown files
3. Build connections between pieces of knowledge
4. Reference your knowledge in future conversations
5. Edit files directly when needed
6. Sync changes automatically

Creating Knowledge

Through Conversations

To create knowledge during conversations with Claude:

You: We've covered several authentication approaches. Could you create a note summarizing what we've discussed?

Claude: I'll create a note summarizing our authentication discussion.

This creates a Markdown file in your ~/basic-memory directory with semantic markup.

Direct File Creation

You can create files directly:

1. Create a new Markdown file in your ~/basic-memory directory
2. Add frontmatter with title, type, and optional tags
3. Structure content with observations and relations
4. Save the file

Using Special Prompts

Basic Memory includes several special prompts that help you leverage your knowledge base more effectively. In apps like Claude Desktop, these prompts trigger specific tools to search and analyze your knowledge base.

Continue Conversation

Use this prompt to resume previous topics with full context:

"Let's continue our conversation about [topic]"

What happens:

• Searches your knowledge base for relevant content
• Builds context from related documents
• Resumes with awareness of previous discussions

Recent Activity

See what you’ve been working on recently:

"What have we been discussing recently?"

What happens:

• Retrieves recently modified documents
• Summarizes main topics and points
• Offers to continue any discussions

Search

Find specific information in your knowledge base:

"Find information about [topic]"

What happens:

• Searches across all your documents
• Summarizes key findings
• Offers to explore specific documents

Working with Memory URLs

Basic Memory uses special memory:// URLs to reference knowledge:

URL Formats

memory://title                   # Reference by title
memory://folder/title            # Reference by folder and title
memory://permalink               # Reference by permalink
memory://path/relation_type/*    # Follow all relations of type
memory://path/*/target           # Find entities with relations to target

Using Memory URLs

Reference existing knowledge in conversations:

You: "Take a look at memory://coffee-brewing-methods and let's discuss improvements"

Claude will load that specific document and any related context.

Building Knowledge Connections

Creating Relations

Use WikiLink syntax to connect knowledge:

- implements [[Authentication System]]
- requires [[Database Schema]]
- relates_to [[Security Guidelines]]

Common Relation Types

• implements - One thing implements another
• requires - Dependencies
• relates_to - General connections
• part_of - Hierarchy relationships
• extends - Extensions or enhancements
• pairs_with - Things that work together

Adding Observations

Structure facts with semantic categories:

- [decision] We chose JWT tokens for stateless auth
- [requirement] Must support 2FA for sensitive operations
- [technique] Use bcrypt for password hashing
- [issue] Rate limiting needed for login attempts

File Organization

Directory Structure

~/basic-memory/
├── projects/          # Project-specific notes
├── decisions/         # Decision records
├── learning/          # Learning notes and research
├── meetings/          # Meeting notes
└── archive/           # Archived content

Best Practices

• Use descriptive filenames
• Group related content in folders
• Include dates in time-sensitive notes
• Archive old content regularly

Controlling What Gets Indexed

New in v0.15.0: Basic Memory respects .gitignore patterns to automatically skip sensitive files and skip indexing files if needed.

How it works:

Basic Memory combines ignore patterns from two sources:

1. Global patterns: ~/.basic-memory/.bmignore (applied to all projects)
2. Project patterns: {project}/.gitignore (applied to specific project)

Example .gitignore:

# Sensitive files
.env
.env.*
*.key
credentials.json

# Build artifacts
node_modules/
__pycache__/
dist/
build/

# OS files
.DS_Store
Thumbs.db

Benefits:

• Security: Prevents indexing sensitive files like .env or API keys
• Performance: Skips unnecessary files like node_modules/ or build outputs
• Cleaner knowledge base: Ignores OS and editor files

Files matching these patterns are automatically skipped during index sync and never indexed in your knowledge base.

Multi-Project Features

Project Management

# Create new project
basic-memory project add work ~/work-notes

# List all projects
basic-memory project list

Project Selection Workflow

New in v0.15.0: At the start of each conversation, the AI will:

1. Check your available projects
2. Suggest the most active project based on recent activity
3. Ask which project to use for this conversation
4. Remember your choice throughout the session

Example conversation:

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"

For single-project users:

If you only use one project, you can skip the selection prompt. Add this to ~/.basic-memory/config.json:

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

With this enabled, the AI uses your default project automatically without asking. You can still override this by explicitly specifying a different project in tool calls.

Single Project Mode

For focused work sessions or automation, you can lock the MCP server to a specific project:

# Start MCP server constrained to specific project
basic-memory mcp --project work-notes

This locks the entire MCP session to one project - the project parameter in tool calls will be ignored.

When to use:

• Automation workflows that should only access one project
• Focused work sessions where you want to prevent accidental cross-project operations
• Team environments with project-specific access

Key difference from Default Project Mode:

• Single Project Mode: Locks session to one project, cannot switch
• Default Project Mode: Uses default automatically, but can still switch projects

Enhanced Editing

Incremental editing instead of rewriting:

You: "Add a troubleshooting section to my setup guide"
Claude: [Uses edit_note to append new section]

Smart file organization:

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

Enhanced Search

Search now includes frontmatter tags:

---
title: Coffee Notes
tags: [brewing, equipment, techniques]
---

Tags are searchable: "Find my brewing notes" will find this document.

Syncing and Updates

Real-time Sync (Default)

Basic Memory automatically syncs file changes in real-time. No manual sync needed.

Checking Status

# View sync status
basic-memory status

# View project information
basic-memory project info

Integration Tips

With Obsidian

1. Open your ~/basic-memory directory in Obsidian
2. Use graph view to see connections
3. Edit files directly in Obsidian
4. Changes are synced in real time. Ask the AI to read a note to see changes.

With Git

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

Basic Memory files are git-friendly and work well with version control.

With Other Editors

Basic Memory uses standard Markdown files that work with:

• VS Code with Markdown extensions
• Typora for rich text editing
• Any text editor for quick edits
• Web editors for remote access

Configuration

Basic Memory can be configured through ~/.basic-memory/config.json or environment variables. Environment variables take precedence over config file settings.

Configuration File Location

Config file: ~/.basic-memory/config.json

Example configuration:

{
  "default_project": "main",
  "default_project_mode": true,
  "log_level": "INFO",
  "sync_delay": 1000,
  "kebab_filenames": false,
  "disable_permalinks": false,
  "sync_changes": true
}

Project Settings

projects - Mapping of project names to filesystem paths

• Type: Dictionary
• Default: {"main": "~/basic-memory"}
• Example: {"work": "~/work-notes", "personal": "~/personal-notes"}

default_project - Name of the default project

• Type: String
• Default: "main"
• Used when no project is specified

default_project_mode - Automatic project selection for single-project users

• Type: Boolean
• Default: false
• When true, AI assistants automatically use default project without asking
• Environment variable: BASIC_MEMORY_DEFAULT_PROJECT_MODE

project_root - Constrain all projects under a root directory

• Type: String (optional)
• Default: null (projects can be created anywhere)
• When set, all project paths must be within this directory
• Environment variable: BASIC_MEMORY_PROJECT_ROOT

Sync Settings

sync_changes - Enable/disable real-time synchronization

• Type: Boolean
• Default: true
• When false, changes are not automatically synced
• Environment variable: BASIC_MEMORY_SYNC_CHANGES

sync_delay - Milliseconds to wait after changes before syncing

• Type: Integer
• Default: 1000 (1 second)
• Prevents excessive sync operations during rapid edits
• Environment variable: BASIC_MEMORY_SYNC_DELAY

sync_thread_pool_size - Thread pool size for file I/O operations

• Type: Integer
• Default: 4
• Higher values may improve performance with many files
• Environment variable: BASIC_MEMORY_SYNC_THREAD_POOL_SIZE

skip_initialization_sync - Skip expensive initialization sync

• Type: Boolean
• Default: false
• Useful for cloud/stateless deployments
• Environment variable: BASIC_MEMORY_SKIP_INITIALIZATION_SYNC

watch_project_reload_interval - Seconds between reloading project list

• Type: Integer
• Default: 30
• Used in watch service to detect new projects
• Environment variable: BASIC_MEMORY_WATCH_PROJECT_RELOAD_INTERVAL

File Management

kebab_filenames - Filename format for generated files

• Type: Boolean
• Default: false
• false: Preserves spaces and special characters
• true: Converts to kebab-case (consistent with permalinks)
• Environment variable: BASIC_MEMORY_KEBAB_FILENAMES

update_permalinks_on_move - Update permalinks when files are moved

• Type: Boolean
• Default: false
• When true, permalinks are updated to reflect new file location
• Environment variable: BASIC_MEMORY_UPDATE_PERMALINKS_ON_MOVE

disable_permalinks - Disable automatic permalink generation

• Type: Boolean
• Default: false
• When true, new notes won’t have permalinks added
• Existing permalinks still work for reading
• Environment variable: BASIC_MEMORY_DISABLE_PERMALINKS

Logging

log_level - Logging verbosity

• Type: String
• Default: "INFO"
• Options: "DEBUG", "INFO", "WARNING", "ERROR"
• Environment variable: BASIC_MEMORY_LOG_LEVEL

Console logging - Enable logging to console

• Environment variable only: BASIC_MEMORY_CONSOLE_LOGGING
• Values: true, false, 1, 0, yes, no
• Default: false (logs to file only)

Log file location: ~/.basic-memory/basic-memory-{process}.log

Environment Variables

All configuration can be overridden with environment variables using the BASIC_MEMORY_ prefix:

# Set default project mode
export BASIC_MEMORY_DEFAULT_PROJECT_MODE=true

# Change log level
export BASIC_MEMORY_LOG_LEVEL=DEBUG

# Enable console logging
export BASIC_MEMORY_CONSOLE_LOGGING=true

# Set custom sync delay
export BASIC_MEMORY_SYNC_DELAY=2000

Special environment variables:

BASIC_MEMORY_HOME - Override default project location

• Default: ~/basic-memory
• Used when creating the main project

BASIC_MEMORY_PROJECT_ROOT - Constrain project paths

• Optional
• All projects must be created within this directory

BASIC_MEMORY_CLOUD_MODE - Enable cloud mode

• Values: true, false
• See Cloud Guide for details

Configuration Priority

Settings are applied in this order (highest to lowest priority):

1. Environment variables (e.g., BASIC_MEMORY_LOG_LEVEL)
2. Config file (~/.basic-memory/config.json)
3. Default values (hardcoded in application)

Example:

# Config file has: "log_level": "INFO"
# Environment has: BASIC_MEMORY_LOG_LEVEL=DEBUG
# Result: DEBUG is used (environment wins)

Editing Configuration

Via config file:

# Edit configuration
vim ~/.basic-memory/config.json

# Restart MCP server for changes to take effect
# (Claude Desktop, VS Code, etc.)

Via CLI:

# Set default project
basic-memory project default work

# View all projects
basic-memory project list

# Check current configuration
cat ~/.basic-memory/config.json

Via environment:

# Temporary (current session)
export BASIC_MEMORY_LOG_LEVEL=DEBUG
basic-memory status

# Permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export BASIC_MEMORY_DEFAULT_PROJECT_MODE=true' >> ~/.bashrc

Troubleshooting

Common Issues

Changes not syncing:

• Check basic-memory status for sync status
• Verify file permissions
• Reset the database with basic-memory reset

Claude can’t find knowledge:

• Confirm files are in the correct project directory
• Check frontmatter formatting
• Try memory:// URLs for direct references

Performance issues:

• Large knowledge bases may need optimization
• Use basic-memory project info to check database size
• Consider archiving old content

Getting Help

Live help is available on our Discord server in the #help channel. You can also find past conversations of people who may have encountered a problem similar to yours.

# View all available commands
basic-memory --help

# Get help for specific commands
basic-memory sync --help
basic-memory project --help

Best Practices

Knowledge Creation

1. Create Relations - Link related concepts
2. Make Observations - Structure facts with semantic categories
3. Create an AI Assistant Guide - AI assistants can be guided through a reference note
4. Be descriptive - Use clear titles and rich content
5. Add context - Include background and reasoning
6. Use categories - Structure observations semantically
7. Review and refine - Edit AI-generated content for accuracy

Workflow

1. Use Special Prompts - Start conversations contextually
2. Build incrementally - Add to existing notes rather than creating duplicates
3. Organize regularly - Move old content to appropriate folders
4. Cross-reference - Link new content to existing knowledge
5. Switch projects - Use different projects for different contexts and to create boundaries

Long-term Maintenance

1. Archive old content - Keep active knowledge base focused
2. Refactor connections - Update relations as knowledge evolves
3. Regular reviews - Periodically review and update key documents
4. Backup regularly - Use git or other backup solutions

Next Steps