basicmachines-co-basic-memory/v15-docs/explicit-project-parameter.md

Explicit Project Parameter (SPEC-6)

Status: Breaking Change PR: #298 Affects: All MCP tool users

What Changed

Starting in v0.15.0, all MCP tools require an explicit project parameter. The previous implicit project context (via middleware) has been removed in favor of a stateless architecture.

Before v0.15.0

# Tools used implicit current_project from middleware
await write_note("My Note", "Content", "folder")
await search_notes("query")

v0.15.0 and Later

# Explicit project required
await write_note("My Note", "Content", "folder", project="main")
await search_notes("query", project="main")

Why This Matters

Benefits:

• Stateless Architecture: Tools are now truly stateless - no hidden state
• Multi-project Clarity: Explicit about which project you're working with
• Better for Cloud: Enables proper multi-tenant isolation
• Simpler Debugging: No confusion about "current" project

Impact:

• Existing MCP integrations may break if they don't specify project
• LLMs need to be aware of project parameter requirement
• Configuration option available for easier migration (see below)

How to Use

Option 1: Specify Project Every Time (Recommended for Multi-project Users)

# Always include project parameter
results = await search_notes(
    query="authentication",
    project="work-docs"
)

content = await read_note(
    identifier="Search Design",
    project="work-docs"
)

await write_note(
    title="New Feature",
    content="...",
    folder="specs",
    project="work-docs"
)

Option 2: Enable default_project_mode (Recommended for Single-project Users)

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

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

With default_project_mode: true:

# Project parameter is optional - uses default_project when omitted
await write_note("My Note", "Content", "folder")  # Uses "main" project
await search_notes("query")  # Uses "main" project

# Can still override with explicit project
await search_notes("query", project="other-project")

Option 3: Project Discovery for New Users

If you don't know which project to use:

# List available projects
projects = await list_memory_projects()
for project in projects:
    print(f"- {project.name}: {project.path}")

# Check recent activity to find active project
activity = await recent_activity()  # Shows cross-project activity
# Returns recommendations for which project to use

Migration Guide

For Claude Desktop Users

1. Check your config: cat ~/.basic-memory/config.json

2. Single project setup (easiest):

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

3. Multi-project setup (explicit):

   • Keep default_project_mode: false (or omit it)
   • LLM will need to specify project in each call

For MCP Server Developers

Update tool calls to include project parameter:

# Old (v0.14.x)
async def my_integration():
    # Relied on middleware to set current_project
    results = await search_notes(query="test")

# New (v0.15.0+)
async def my_integration(project: str = "main"):
    # Explicitly pass project
    results = await search_notes(query="test", project=project)

For API Users

If using the Basic Memory API directly:

# All endpoints now require project parameter
import httpx

async with httpx.AsyncClient() as client:
    response = await client.post(
        "http://localhost:8000/notes/search",
        json={
            "query": "test",
            "project": "main"  # Required
        }
    )

Technical Details

Architecture Change

Removed:

• ProjectMiddleware - no longer maintains project context
• get_current_project() - removed from MCP tools
• Implicit project state in MCP server

Added:

• default_project_mode config option
• Explicit project parameter on all MCP tools
• Stateless tool architecture (SPEC-6)

Configuration Options

Config Key	Type	Default	Description
default_project_mode	bool	false	Auto-use default_project when project param omitted
default_project	string	"main"	Project to use in default_project_mode

Three-Tier Project Resolution

1. CLI Constraint (Highest Priority): --project flag constrains all operations
2. Explicit Parameter (Medium): project="name" in tool calls
3. Default Mode (Lowest): Falls back to default_project if default_project_mode: true

Common Questions

Q: Will my existing setup break? A: If you use a single project and enable default_project_mode: true, no. Otherwise, you'll need to add project parameters.

Q: Can I still use multiple projects? A: Yes! Just specify the project parameter explicitly in each call.

Q: What if I forget the project parameter? A: You'll get an error unless default_project_mode: true is set in config.

Q: How does this work with Claude Desktop? A: Claude can read your config and use default_project_mode, or it can discover projects using list_memory_projects().

Related Changes

• See default-project-mode.md for detailed config options
• See cloud-mode-usage.md for cloud API usage
• See SPEC-6 for full architectural specification