MCP Tools Reference

Complete reference of all Basic Memory MCP tools and prompts available to AI assistants

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. This reference catalogs all available tools and where to find detailed examples.

MCP Tools

Knowledge Management Tools

Search and Discovery Tools

Project Management Tools

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:

• How it works: AI assistants discover projects using list_memory_projects() and recent_activity()
• Project selection: Users specify which project to work with during conversations
• Benefits: Full flexibility to work across multiple projects in one session
• Best for: Users managing separate work, personal, and research knowledge bases

Example workflow:

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

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

User: Let's work with the research project

Assistant: Perfect! 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 to tools
• Best for users who primarily work in one project but occasionally need others

Example:

# With default_project_mode enabled and default_project="main"
write_note("My Note", "Content", "folder")  # Uses "main" project
write_note("Work Note", "Content", "folder", project="work")  # Uses "work" 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 - cannot switch projects
• Best for automation, focused sessions, or restricted access scenarios

Example:

# Start locked to "work" project
basic-memory mcp --project work

# All operations use "work" regardless of parameters
write_note("My Note", "Content", "folder")  # Uses "work"
write_note("Note", "Content", "folder", project="personal")  # Still uses "work"!

Project Resolution Hierarchy

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

1. Single Project Mode (highest priority) - --project CLI parameter or BASIC_MEMORY_MCP_PROJECT env var
2. Explicit Parameter (medium priority) - project parameter in tool call
3. Default Project Mode (lowest priority) - Automatic default when default_project_mode=true

Quick Comparison:

Utility Tools

ChatGPT-Specific Tools

MCP Prompts

Basic Memory includes specialized prompts that provide enhanced AI interactions with formatted responses and guided workflows.

Interactive Prompts

Tool Usage Patterns

Common Workflows

Knowledge Creation Flow:

write_note → edit_note (append/prepend) → move_note → view_note

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

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

You: "Add a section about authentication concerns"
Claude: I'll append an authentication section to your API design note.
[Uses edit_note with append operation]

You: "This should go in my architecture folder"
Claude: I'll move the API design 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 formatted for easy reading.
[Uses view_note to display formatted artifact]

Research and Discovery Flow:

search_notes → read_note → build_context → write_note

Find existing knowledge, explore context, create new insights

You: "I'm working on database optimization, what have I learned before?"
Claude: Let me search your knowledge base for database optimization content.
[Uses search_notes to find relevant notes]

You: "Tell me more about that PostgreSQL indexing note"
Claude: I'll read the full PostgreSQL indexing note for you.
[Uses read_note to load complete content and context]

You: "Load the context from my database performance work"
Claude: I'll gather related notes about database performance to build context.
[Uses build_context with memory:// URLs to load related content]

You: "Create a new note combining these insights for my current project"
Claude: I'll create a comprehensive note that synthesizes your database optimization knowledge.
[Uses write_note to capture new insights with full context]

Project Discovery Flow:

list_memory_projects → recent_activity (discovery mode) → project selection

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

You: "What projects do I have available?"
Claude: Here are all your Basic Memory projects with their current status.
[Uses list_memory_projects to show available projects]

You: "Show me recent activity across all projects"
Claude: Here's recent activity across all your projects to help you choose which to work with.
[Uses recent_activity without project parameter for discovery mode]

You: "I want to work with my research project"
Claude: I'll use the 'research' project for our work. All subsequent operations will specify this project.
[Remembers project choice for conversation context]

You: "What have I been working on recently in this project?"
Claude: Here's your recent activity in the research project.
[Uses recent_activity with project="research" parameter]

Content Organization Flow:

list_directory → search_notes → move_note → list_directory

Explore structure, find content, reorganize, verify changes

You: "Show me what's in my projects folder"
Claude: Here's the structure of your projects folder.
[Uses list_directory to explore folder contents]

You: "Find all notes about the mobile app project"
Claude: I found several notes related to your mobile app project.
[Uses search_notes to locate relevant content]

You: "Move the mobile app notes to a dedicated folder"
Claude: I'll move all mobile app notes to a new 'mobile-app' folder.
[Uses move_note to reorganize content]

You: "Show me the updated folder structure"
Claude: Here's your reorganized projects folder with the new mobile-app directory.
[Uses list_directory to verify the changes]

Integration Examples

In Claude Desktop:

You: "What have I been working on lately?"
Claude: [Uses recent_activity prompt for formatted response]

You: "Create a note about today's meeting"
Claude: [Uses write_note tool with semantic structure]

You: "Show me my project documentation as a formatted view"
Claude: [Uses view_note tool to display artifact]

In Development Workflows:

You: "Document today's architecture decisions in my work project"
Claude: [Uses write_note with project="work" parameter and technical context]

You: "Find all my API documentation in the work project and update the authentication section"
Claude: [Uses search_notes with project="work", then edit_note with section replacement]

Error Handling and Best Practices

Common Tool 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 to operate on: project="work-docs"
• Optional if default_project_mode: true in configuration
• Automatically resolved in constrained mode (--project flag)
• recent_activity() supports discovery mode (no project = cross-project view)

Advanced Features

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

Project Management vs Content Tools

Basic Memory tools fall into two categories:

Project Management Tools (work globally, no project parameter):

• list_memory_projects() - Shows all projects
• create_memory_project(project_name, project_path) - Creates new project
• delete_project(project_name) - Removes project configuration
• sync_status() - Shows status across all projects

Content Tools (require project parameter):

• write_note(title, content, folder, project="...") - Creates note in specified project
• search_notes(query, project="...") - Searches specified project only
• edit_note(identifier, operation, content, project="...") - Edits note in specified project
• read_note(identifier, project="...") - Reads note from specified project
• recent_activity(project="...") - Project-specific activity (or omit for discovery mode)

Example:

# Global operations (no project parameter)
list_memory_projects()                              # Shows all projects
create_memory_project("new-project", "~/Documents") # Creates new project

# Project-specific operations (project parameter required)
write_note("My Note", "Content", "folder", project="work")
search_notes("api documentation", project="work")
edit_note("My Note", "append", "More content", project="work")

# Discovery mode (no project = cross-project view)
recent_activity()  # Shows activity across all projects

Resources and Examples

Where to Find More

• Real workflows: How you can use Basic Memory section
• New features: What’s New with detailed examples
• Setup guides: Integrations for platform-specific usage
• User perspective: User Guide for comprehensive workflows
• AI perspective: AI Assistant Guide for best practices

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

This reference provides the complete catalog of Basic Memory’s MCP capabilities. For detailed examples and real-world usage patterns, explore the guides and how-to sections linked throughout this page.