basicmachines-co-basic-memory/v15-docs/default-project-mode.md

Default Project Mode

Status: New Feature PR: #298 (SPEC-6) Related: explicit-project-parameter.md

What's New

v0.15.0 introduces default_project_mode - a configuration option that simplifies single-project workflows by automatically using your default project when no explicit project parameter is provided.

Quick Start

Enable Default Project Mode

Edit ~/.basic-memory/config.json:

{
  "default_project": "main",
  "default_project_mode": true,
  "projects": {
    "main": "/Users/you/basic-memory"
  }
}

Now Tools Work Without Project Parameter

# Before (explicit project required)
await write_note("Note", "Content", "folder", project="main")

# After (with default_project_mode: true)
await write_note("Note", "Content", "folder")  # Uses "main" automatically

Configuration Options

Option	Type	Default	Description
default_project_mode	boolean	false	Enable auto-fallback to default project
default_project	string	"main"	Which project to use as default

How It Works

Three-Tier Project Resolution

When a tool is called, Basic Memory resolves the project in this order:

1. CLI Constraint (Highest): bm --project work-notes forces all tools to use "work-notes"
2. Explicit Parameter (Medium): project="specific" in tool call
3. Default Mode (Lowest): Uses default_project if default_project_mode: true

Examples

With default_project_mode: false (default):

# Must specify project explicitly
await search_notes("query", project="main")  # ✓ Works
await search_notes("query")                  # ✗ Error: project required

With default_project_mode: true:

# Project parameter is optional
await search_notes("query")                  # ✓ Uses default_project
await search_notes("query", project="work")  # ✓ Explicit override works

Use Cases

Single-Project Users

Best for:

• Users who maintain one primary knowledge base
• Personal knowledge management
• Single-purpose documentation

Configuration:

{
  "default_project": "main",
  "default_project_mode": true,
  "projects": {
    "main": "/Users/you/basic-memory"
  }
}

Benefits:

• Simpler tool calls
• Less verbose for AI assistants
• Familiar workflow (like v0.14.x)

Multi-Project Users

Best for:

• Multiple distinct knowledge bases (work, personal, research)
• Switching contexts frequently
• Team collaboration with separate projects

Configuration:

{
  "default_project": "main",
  "default_project_mode": false,
  "projects": {
    "work": "/Users/you/work-kb",
    "personal": "/Users/you/personal-kb",
    "research": "/Users/you/research-kb"
  }
}

Benefits:

• Explicit project selection prevents mistakes
• Clear which knowledge base is being accessed
• Better for context switching

Workflow Examples

Single-Project Workflow

# config.json: default_project_mode: true, default_project: "main"

# Write without specifying project
await write_note(
    title="Meeting Notes",
    content="# Team Sync\n...",
    folder="meetings"
)  # → Saved to "main" project

# Search across default project
results = await search_notes("quarterly goals")
# → Searches "main" project

# Build context from default project
context = await build_context("memory://goals/q4-2024")
# → Uses "main" project

Multi-Project with Explicit Selection

# config.json: default_project_mode: false

# Work project
await write_note(
    title="Architecture Decision",
    content="# ADR-001\n...",
    folder="decisions",
    project="work"
)

# Personal project
await write_note(
    title="Book Notes",
    content="# Design Patterns\n...",
    folder="reading",
    project="personal"
)

# Research project
await search_notes(
    query="machine learning",
    project="research"
)

Hybrid: Default with Occasional Override

# config.json: default_project_mode: true, default_project: "personal"

# Most operations use personal (default)
await write_note("Daily Journal", "...", "journal")
# → Saved to "personal"

# Explicitly use work project when needed
await write_note(
    title="Sprint Planning",
    content="...",
    folder="planning",
    project="work"  # Override default
)
# → Saved to "work"

# Back to default
await search_notes("goals")
# → Searches "personal"

Migration Guide

From v0.14.x (Implicit Project)

v0.14.x had implicit project context via middleware. To get similar behavior:

Enable default_project_mode:

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

Now tools work without explicit project parameter (like v0.14.x).

From v0.15.0 Explicit-Only

If you started with v0.15.0 using explicit projects:

Keep current behavior:

{
  "default_project_mode": false  # or omit (false is default)
}

Or simplify for single project:

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

LLM Integration

Claude Desktop

Claude can detect and use default_project_mode:

Auto-detection:

# Claude reads config
config = read_config()

if config.get("default_project_mode"):
    # Use simple calls
    await write_note("Note", "Content", "folder")
else:
    # Discover and use explicit project
    projects = await list_memory_projects()
    await write_note("Note", "Content", "folder", project=projects[0].name)

Custom MCP Clients

from basic_memory.config import ConfigManager

config = ConfigManager().config

if config.default_project_mode:
    # Project parameter optional
    result = await mcp_tool(arg1, arg2)
else:
    # Project parameter required
    result = await mcp_tool(arg1, arg2, project="name")

Error Handling

Missing Project (default_project_mode: false)

try:
    results = await search_notes("query")
except ValueError as e:
    print("Error: project parameter required")
    # Show available projects
    projects = await list_memory_projects()
    print(f"Available: {[p.name for p in projects]}")

Invalid Default Project

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

Result: Falls back to "main" project if default doesn't exist.

Configuration Management

Update Config

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

# Or use CLI (if available)
bm config set default_project_mode true
bm config set default_project main

Verify Config

from basic_memory.config import ConfigManager

config = ConfigManager().config
print(f"Default mode: {config.default_project_mode}")
print(f"Default project: {config.default_project}")
print(f"Projects: {list(config.projects.keys())}")

Environment Override

# Override via environment
export BASIC_MEMORY_DEFAULT_PROJECT_MODE=true
export BASIC_MEMORY_DEFAULT_PROJECT=work

# Now default_project_mode enabled for this session

Best Practices

1. Choose based on workflow:

   • Single project → enable default_project_mode
   • Multiple projects → keep explicit (false)

2. Document your choice:

   • Add comment to config.json explaining why

3. Consistent with team:

   • Agree on project mode for shared setups

4. Test both modes:

   • Try each to see what feels natural

5. Use CLI constraints when needed:

   • bm --project work-notes overrides everything

Troubleshooting

Tools Not Using Default Project

Problem: default_project_mode: true but tools still require project

Check:

# Verify config
cat ~/.basic-memory/config.json | grep default_project_mode

# Should show: "default_project_mode": true

Solution: Restart MCP server to reload config

Wrong Project Being Used

Problem: Tools using unexpected project

Check resolution order:

1. CLI constraint (--project flag)
2. Explicit parameter in tool call
3. Default project (if mode enabled)

Solution: Check for CLI constraints or explicit parameters

Config Not Loading

Problem: Changes to config.json not taking effect

Solution:

# Restart MCP server
# Or reload config programmatically
from basic_memory import config as config_module
config_module._config = None  # Clear cache

Technical Details

Implementation

class BasicMemoryConfig(BaseSettings):
    default_project: str = Field(
        default="main",
        description="Name of the default project to use"
    )

    default_project_mode: bool = Field(
        default=False,
        description="When True, MCP tools automatically use default_project when no project parameter is specified"
    )

Project Resolution Logic

def resolve_project(
    explicit_project: Optional[str] = None,
    cli_project: Optional[str] = None,
    config: BasicMemoryConfig = None
) -> str:
    # 1. CLI constraint (highest priority)
    if cli_project:
        return cli_project

    # 2. Explicit parameter
    if explicit_project:
        return explicit_project

    # 3. Default mode (lowest priority)
    if config.default_project_mode:
        return config.default_project

    # 4. No project found
    raise ValueError("Project parameter required")

See Also

• explicit-project-parameter.md - Why explicit project is required
• SPEC-6: Explicit Project Parameter Architecture
• MCP tools documentation