MCP Tools Reference

Basic Memory provides a comprehensive suite of MCP (Model Context Protocol) tools and prompts that enable AI assistants to work directly with your knowledge base.

Knowledge Management Tools

write_note

Create or update notes with semantic structure.

Example:

You: "Create a note about our API design decisions"
AI: [Uses write_note to create note with observations and relations]

read_note

Read existing notes with context.

Example:

You: "Show me my notes on authentication"
AI: [Uses read_note to load content and related knowledge]

edit_note

Edit notes incrementally without rewriting.

Operations:

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

Example:

You: "Add a section about rate limiting to my API notes"
AI: [Uses edit_note with append operation]

view_note

Display notes as formatted artifacts.

Shows notes with proper formatting in Claude Desktop for enhanced readability.

delete_note

Remove notes or directories from knowledge base.

Example:

You: "Delete the old temp folder"
AI: [Uses delete_note with is_directory=true]

move_note

Move and rename notes or directories.

Maintains database consistency and updates search index.

Example:

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

Search and Discovery Tools

search_notes

Full-text search across knowledge.

Searches content, titles, and frontmatter tags.

Example:

You: "Find all my notes about database optimization"
AI: [Uses search_notes to locate relevant content]

recent_activity

Show recently modified content.

Discovery mode: Omit project to see activity across all projects.

Example:

You: "What have I been working on this week?"
AI: [Uses recent_activity with timeframe="1 week"]

build_context

Load context from memory:// URLs.

Navigate knowledge graph relationships and build conversation context from previous work.

Example:

You: "Load context from my architecture decisions"
AI: [Uses build_context with memory://architecture/*]

list_directory

Browse knowledge base structure.

Example:

You: "Show me what's in my projects folder"
AI: [Uses list_directory to explore structure]

Project Management Tools

list_memory_projects

Show all available projects.

No parameters required. Displays project status and statistics.

Example:

You: "What projects do I have?"
AI: [Uses list_memory_projects to show all projects]

create_memory_project

Create new knowledge projects.

delete_project

Remove projects from configuration.

Removes from Basic Memory configuration. Does not delete actual files.

sync_status

Check file synchronization status.

No parameters required. Shows sync progress across all projects and identifies any issues.

Utility Tools

read_content

Read raw file content.

Access files without knowledge graph processing. Supports text, images, and binary files.

canvas

Create Obsidian canvas visualizations.

Generate knowledge graph visualizations for Obsidian.

Project Modes

Basic Memory supports three different project modes to accommodate different workflows.

Multi-Project Mode (Default)

The standard mode for users with multiple knowledge bases:

• AI assistants discover projects using list_memory_projects() and recent_activity()
• Users specify which project to work with during conversations
• Full flexibility to work across multiple projects in one session

Example workflow:

AI: I'll check what projects you have available.
[Calls list_memory_projects()]

AI: I see you have 'work', 'personal', and 'research' projects. Which would you like to use?

You: Let's work with the research project

AI: I'll use the 'research' project for our work.
[Uses project="research" in all subsequent tool calls]

Default Project Mode

For single-project users who want automatic project selection.

Enable in ~/.basic-memory/config.json:

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

Behavior:

• Tools automatically use your default project when no project parameter is specified
• You can still override by explicitly passing a different project
• Best for users who primarily work in one project

Single Project Mode

For locked, single-project sessions.

Start MCP server with --project flag:

basic-memory mcp --project work

Behavior:

• Locks the entire MCP session to one project
• The project parameter in tool calls is ignored
• Best for automation, focused sessions, or restricted access

Project Resolution Hierarchy

When multiple project specifications exist, Basic Memory uses this priority:

1. Single Project Mode (highest) - --project CLI parameter
2. Explicit Parameter (medium) - project parameter in tool call
3. Default Project Mode (lowest) - Automatic default

MCP Prompts

Basic Memory includes specialized prompts for enhanced AI interactions.

ai_assistant_guide

Comprehensive usage guide for AI assistants with best practices and workflow recommendations.

continue_conversation

Load context for conversation continuity.

search_notes (prompt)

Enhanced search with formatted results - better than raw search tool for conversations.

recent_activity (prompt)

Formatted recent activity display with contextual information.

sync_status (prompt)

Detailed sync status information with troubleshooting guidance.

Tool Usage Patterns

Knowledge Creation Flow

Start with basic note, enhance incrementally, organize, then review.

Example conversation:

You: "I want to document my thoughts on the new API design"
AI: I'll create a note for your API design thoughts.
[Uses write_note to create initial note]

You: "Add a section about authentication concerns"
AI: I'll append an authentication section.
[Uses edit_note with append operation]

You: "This should go in my architecture folder"
AI: I'll move the note to your architecture folder.
[Uses move_note to relocate the file]

You: "Show me the final note"
Claude: Here's your complete API design note.
[Uses view_note to display formatted artifact]

Research and Discovery Flow

Find existing knowledge, explore context, create new insights.

Example:

You: "I'm working on database optimization, what have I learned before?"
Claude: [Uses search_notes to find relevant notes]

You: "Tell me more about that PostgreSQL indexing note"
Claude: [Uses read_note to load complete content]

You: "Load the context from my database performance work"
Claude: [Uses build_context with memory:// URLs]

You: "Create a new note combining these insights"
Claude: [Uses write_note to capture synthesized knowledge]

Project Discovery Flow

list_memory_projects → recent_activity (discovery mode) → project selection

Discover projects, view cross-project activity, choose working project.

Content Organization Flow

list_directory → search_notes → move_note → list_directory

Explore structure, find content, reorganize, verify changes.

Directory Operations Flow

list_directory → move_note (is_directory=True) → delete_note (is_directory=True)

Bulk organize folders, move entire directories, clean up.

Example:

You: "Move the entire 'old-projects' folder to 'archive'"
Claude: [Uses move_note with is_directory=True]
✓ Moved old-projects/ → archive/old-projects/
✓ All 15 files moved with database consistency

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

Common Parameters

Identifiers

Most tools accept flexible identifiers:

• Note titles: "My Important Note"
• Permalinks: "my-important-note"
• Memory URLs: "memory://folder/note"
• File paths: "folder/note.md"

Timeframes

Natural language supported:

• "2 days ago", "last week", "today"
• "3 months ago", "yesterday"
• Standard formats: "7d", "24h"

Project Parameters

Most content tools require project specification:

• Specify which project: project="work-docs"
• Optional if default_project_mode: true
• Automatically resolved with --project flag
• recent_activity() supports discovery mode (no project = cross-project view)

Memory URLs

Use memory:// URLs with build_context for intelligent navigation:

memory://project-planning          # Load specific note
memory://architecture/*            # Load all architecture notes
memory://decisions/database-choice # Load specific decision document

Quick Reference

Most Common Tools:

• write_note - Create knowledge
• search_notes - Find information
• edit_note - Update incrementally
• list_memory_projects - Discover projects
• recent_activity - Check progress

Most Useful Prompts:

• continue_conversation - Resume discussions
• ai_assistant_guide - Get usage help
• search_notes - Formatted search results

Next Steps