User Guide

This guide 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

The most natural way to create knowledge is during conversations:

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.

[Uses write_note tool]

Done! I've created "Authentication Approaches.md" with:
- Overview of options we discussed
- Observations about JWT vs sessions
- Relations to your security notes

This creates a Markdown file with semantic markup in your knowledge base.

Direct File Creation

You can also create files directly:

1. Create a new Markdown file in your project directory
2. Add frontmatter with title, type, and optional tags
3. Structure content with observations and relations
4. Save the file - it syncs automatically

Example file structure:

---
title: API Design Decisions
tags: [api, architecture, decisions]
---

# API Design Decisions

## Context
We needed to choose an approach for the new API.

## Observations
- [decision] Use REST over GraphQL for simplicity #api
- [requirement] Must support versioning from day one
- [risk] Rate limiting needed for public endpoints

## Relations
- implements [[API Specification]]
- depends_on [[Authentication System]]

Using Special Prompts

Basic Memory includes special prompts that help you leverage your knowledge base effectively.

Continue Conversation

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:

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

"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

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:

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

Common Relation Types

Adding Observations

Structure facts with semantic categories:

## Observations
- [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
- [fact] Average response time is 50ms
- [question] Should we support OAuth?

Multi-Project Workflows

How Projects Work

Basic Memory supports multiple projects for organizing different knowledge bases. When you start a 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"

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

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

This sets your fallback project when no explicit project is passed. You can still override by specifying a different project.

Single Project Mode (Locked)

For focused sessions or automation, lock the MCP server to one project:

basic-memory mcp --project work-notes

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

When to use:

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

Moving Notes Between Projects

File Organization

Directory Structure

Organize files in any structure that suits you:

~/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

Best Practices

• Use descriptive filenames
• Group related content in folders
• Include dates in time-sensitive notes (e.g., 2024-01-15 Team Standup.md)
• Archive old content regularly

Controlling What Gets Indexed

Basic Memory respects .gitignore patterns to skip sensitive files.

Pattern sources:

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

Example .gitignore:

# Sensitive files
.env
*.key
credentials.json

# Build artifacts
node_modules/
__pycache__/
dist/

# OS files
.DS_Store
Thumbs.db

Files matching these patterns are automatically skipped during indexing.

Enhanced Editing

Incremental Editing

Edit notes without rewriting entire documents:

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

Available operations:

• append - Add content to end
• prepend - Add content to beginning
• find_replace - Replace specific text
• replace_section - Replace entire section by heading

Smart File Organization

Move and rename notes with database consistency:

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

Directory Operations

Move or delete entire folders:

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

You: "Delete the empty temp folder"
Claude: [Uses delete_note with is_directory=true]
"Deleted temp/ and all 3 contained files"

Enhanced Search

Tags and frontmatter fields are searchable. Use tag: shorthand or metadata filters to narrow results:

You: "Find all my notes tagged with security"
Claude: [Uses search_notes with query="tag:security"]

You: "Show me in-progress specs"
Claude: [Uses search_notes with note_types=["spec"], metadata_filters={"status": "in-progress"}]

You: "Find high priority items from this year"
Claude: [Uses search_notes with metadata_filters={"priority": {"$in": ["high", "critical"]}},
         after_date="2026-01-01"]

You can also search purely by metadata — no text query needed:

You: "What notes have status draft?"
Claude: [Uses search_notes with status="draft"]

Schema Workflows

As your knowledge base grows, you may want consistent structure for certain note types. Schemas let you define what a "good" note of a particular type should contain, then validate notes against that definition.

Conversational example:

You: "I've been writing a lot of person notes. Can you help me standardize them?"

Claude: Let me analyze your existing person notes to find common patterns.

[Uses schema_infer with note_type="person"]

Based on your notes, here's what most of them include:
- name (in 95% of notes)
- role (in 80%)
- works_at relation (in 60%)

I can create a schema note that formalizes this pattern.
Would you like me to save it?

You: "Yes, and validate my existing notes against it"

Claude: [Creates schema note, then validates]
3 of your 15 person notes are missing the [name] observation.
Here are the ones that need updating...

See the Schema System guide for full details on picoschema syntax, validation modes, and the infer-validate-diff lifecycle.

Semantic Search

Semantic search lets you find notes by meaning rather than exact keywords. This is helpful when you remember the concept but not the exact words used in the note.

Conversational example:

You: "Find my notes about making the app faster"

Claude: [Uses search_notes with search_type="hybrid"]

I found several relevant notes:
1. "React Performance Optimization" — contains observations about bundle size and lazy loading
2. "Database Query Tuning" — discusses index strategies and query plans
3. "Caching Architecture" — your design decisions for the Redis cache layer

Would you like me to build context from any of these?

Semantic search is included by default. Embeddings are generated automatically on first startup. See the Semantic Search guide for configuration details.

Syncing and Updates

Real-time Sync

Basic Memory automatically syncs file changes in real-time. When you edit a file in your editor:

1. The change is detected within ~1 second
2. The file is re-parsed for observations and relations
3. The database is updated
4. Search index is refreshed

No manual sync needed for normal workflows.

Checking Status

# View sync status
basic-memory status

# View project information
basic-memory project info

Force Re-sync

If something seems out of sync:

# Re-sync all files
basic-memory sync

# Reset and rebuild database (use if issues persist)
basic-memory reset

Integration Tips

With Obsidian

1. Open your ~/basic-memory directory as an Obsidian vault
2. Use Graph View to visualize connections
3. Edit files directly in Obsidian
4. Changes sync automatically - ask the AI to read a note to see updates

With Git

Basic Memory files are git-friendly:

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

Benefits:

• Version history for all changes
• Backup to GitHub/GitLab
• Collaborate with others
• Track what changed over time

With Other Editors

Basic Memory uses standard Markdown that works with:

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

The database syncs regardless of how you edit files.

Best Practices

Knowledge Creation

1. Create relations - Link related concepts with [[WikiLinks]]
2. Make observations - Structure facts with [category] syntax
3. Be descriptive - Use clear titles and rich content
4. Add context - Include background and reasoning
5. Review and refine - Edit AI-generated content for accuracy

Workflow

1. Use special prompts - "Continue conversation", "Recent activity", "Search"
2. Build incrementally - Add to existing notes rather than creating duplicates
3. Organize regularly - Move old content to archive
4. Cross-reference - Link new content to existing knowledge
5. Use projects - Separate work, personal, research

Long-term Maintenance

1. Archive old content - Keep active knowledge base focused
2. Refactor connections - Update relations as knowledge evolves
3. Regular reviews - Periodically update key documents
4. Backup regularly - Use git, cloud sync, or snapshots

Troubleshooting

Changes Not Syncing

1. Check sync status: basic-memory status
2. Verify file permissions
3. Check if file matches ignore patterns
4. Reset database: basic-memory reset

Claude Can't Find Knowledge

1. Confirm files are in correct project directory
2. Check frontmatter formatting (valid YAML)
3. Use memory:// URLs for direct references
4. Trigger re-sync: basic-memory sync

Performance Issues

1. Check database size: basic-memory project info
2. Archive old content
3. Adjust sync delay in config (default: 1000ms)

Getting Help

• Discord: discord.gg/tyvKNccgqN - #help channel
• GitHub: github.com/basicmachines-co/basic-memory/issues

# View all commands
basic-memory --help

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

Next Steps