improve tool doc for project info

Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/mcp/project_context.py

@@ -20,7 +20,7 @@ async def resolve_project_parameter(project: Optional[str] = None) -> Optional[s
     """Resolve project parameter using three-tier hierarchy.
 
     Resolution order:
-    1. CLI constraint (BASIC_MEMORY_MCP_PROJECT env var) - highest priority
+    1. Single Project Mode  (--project cli arg, or BASIC_MEMORY_MCP_PROJECT env var) - highest priority
     2. Explicit project parameter - medium priority
     3. Default project if default_project_mode=true - lowest priority
 

src/basic_memory/mcp/tools/build_context.py

@@ -50,11 +50,15 @@ async def build_context(
 
     This tool enables natural continuation of discussions by loading relevant context
     from memory:// URIs. It uses pattern matching to find relevant content and builds
-    a rich context graph of related information. Uses stateless architecture - each
-    call requires explicit project parameter.
+    a rich context graph of related information.
+
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
 
     Args:
-        project: Required project name to build context from. Must be an existing project.
+        project: Project name to build context from. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
         url: memory:// URI pointing to discussion content (e.g. memory://specs/search)
         depth: How many relation hops to traverse (1-3 recommended for performance)
         timeframe: How far back to look. Supports natural language like "2 days ago", "last week"

src/basic_memory/mcp/tools/canvas.py

@@ -30,12 +30,16 @@ async def canvas(
 
     This tool creates a .canvas file compatible with Obsidian's Canvas feature,
     allowing visualization of relationships between concepts or documents.
-    Uses stateless architecture - each call requires explicit project parameter.
+
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
 
     For the full JSON Canvas 1.0 specification, see the 'spec://canvas' resource.
 
     Args:
-        project: Required project name to create canvas in. Must be an existing project.
+        project: Project name to create canvas in. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
         nodes: List of node objects following JSON Canvas 1.0 spec
         edges: List of edge objects following JSON Canvas 1.0 spec
         title: The title of the canvas (will be saved as title.canvas)

src/basic_memory/mcp/tools/delete_note.py

@@ -154,15 +154,17 @@ async def delete_note(
 ) -> bool | str:
     """Delete a note from the knowledge base.
 
-    Permanently removes a note from the specified project. Uses stateless
-    architecture - each call requires explicit project parameter.
+    Permanently removes a note from the specified project. The note is identified
+    by title or permalink. If the note doesn't exist, the operation returns False
+    without error. If deletion fails due to other issues, helpful error messages are provided.
 
-    The note is identified by title or permalink. If the note doesn't exist,
-    the operation returns False without error. If deletion fails due to other
-    issues, helpful error messages are provided.
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
 
     Args:
-        project: Required project name to delete from. Must be an existing project.
+        project: Project name to delete from. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
         identifier: Note title or permalink to delete
                    Can be a title like "Meeting Notes" or permalink like "notes/meeting-notes"
         context: Optional FastMCP context for performance caching.

src/basic_memory/mcp/tools/edit_note.py

@@ -142,10 +142,10 @@ async def edit_note(
     """Edit an existing markdown note in the knowledge base.
 
     Makes targeted changes to existing notes without rewriting the entire content.
-    Supports three project resolution modes:
-    1. Explicit project parameter (highest priority)
-    2. Default project mode (if enabled in config)
-    3. CLI constraint mode (--project flag)
+
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
 
     Args:
         identifier: The exact title, permalink, or memory:// URL of the note to edit.
@@ -157,8 +157,8 @@ async def edit_note(
                   - "find_replace": Replace occurrences of find_text with content
                   - "replace_section": Replace content under a specific markdown header
         content: The content to add or use for replacement
-        project: Optional project name. If not provided, uses default_project (if default_project_mode=true)
-               . If unknown, use list_memory_projects() to discover available projects.
+        project: Project name to edit in. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
         section: For replace_section operation - the markdown header to replace content under (e.g., "## Notes", "### Implementation")
         find_text: For find_replace operation - the text to find and replace
         expected_replacements: For find_replace operation - the expected number of replacements (validation will fail if actual doesn't match)

src/basic_memory/mcp/tools/list_directory.py

@@ -25,8 +25,7 @@ async def list_directory(
 
     This tool provides 'ls' functionality for browsing the knowledge base directory structure.
     It can list immediate children or recursively explore subdirectories with depth control,
-    and supports glob pattern filtering for finding specific files. Uses stateless architecture -
-    each call requires explicit project parameter.
+    and supports glob pattern filtering for finding specific files.
 
     Args:
         dir_name: Directory path to list (default: root "/")
@@ -35,9 +34,8 @@ async def list_directory(
                Higher values show subdirectory contents recursively
         file_name_glob: Optional glob pattern for filtering file names
                        Examples: "*.md", "*meeting*", "project_*"
-        project: Optional project name to list directory from. If not provided, uses default_project
-                (if default_project_mode=true). If unknown, use list_memory_projects()
-                to discover available projects.
+        project: Project name to list directory from. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
         context: Optional FastMCP context for performance caching.
 
     Returns:

src/basic_memory/mcp/tools/move_note.py

@@ -349,16 +349,15 @@ async def move_note(
 
     Moves a note from one location to another within the project, updating all
     database references and maintaining semantic content. Uses stateless architecture -
-    each call requires explicit project parameter.
+    project parameter optional with server resolution.
 
     Args:
         identifier: Exact entity identifier (title, permalink, or memory:// URL).
                    Must be an exact match - fuzzy matching is not supported for move operations.
                    Use search_notes() or read_note() first to find the correct identifier if uncertain.
         destination_path: New path relative to project root (e.g., "work/meetings/2025-05-26.md")
-        project: Optional project name to move within. If not provided, uses default_project
-                (if default_project_mode=true). If unknown, use list_memory_projects()
-                to discover available projects.
+        project: Project name to move within. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
         context: Optional FastMCP context for performance caching.
 
     Returns:

src/basic_memory/mcp/tools/read_content.py

@@ -156,7 +156,7 @@ async def read_content(
 
     This tool provides direct access to file content in the knowledge base,
     handling different file types appropriately. Uses stateless architecture -
-    each call requires explicit project parameter.
+    project parameter optional with server resolution.
 
     Supported file types:
     - Text files (markdown, code, etc.) are returned as plain text
@@ -168,9 +168,8 @@ async def read_content(
             - A regular file path (docs/example.md)
             - A memory URL (memory://docs/example)
             - A permalink (docs/example)
-        project: Optional project name to read from. If not provided, uses default_project
-                (if default_project_mode=true). If unknown, use list_memory_projects()
-                to discover available projects.
+        project: Project name to read from. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
         context: Optional FastMCP context for performance caching.
 
     Returns:

src/basic_memory/mcp/tools/read_note.py

@@ -29,24 +29,20 @@ async def read_note(
 
     Finds and retrieves a note by its title, permalink, or content search,
     returning the raw markdown content including observations, relations, and metadata.
-    Uses stateless architecture - each call requires explicit project parameter.
 
-    Project Selection:
-    If you don't know which project to use:
-    1. Call list_memory_projects() to discover available projects
-    2. Or call recent_activity() to see project activity and get recommendations
-    3. Ask the user which project to read from
-    4. Remember their choice for the entire conversation session
-    5. Only ask again if the user explicitly mentions switching projects
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
 
     This tool will try multiple lookup strategies to find the most relevant note:
     1. Direct permalink lookup
     2. Title search fallback
     3. Text search as last resort
 
     Args:
-        project: Required project name to read from. Must be an existing project.
-                If unknown, use list_memory_projects() to discover available projects.
+        project: Project name to read from. Optional - server will resolve using the
+                hierarchy above. If unknown, use list_memory_projects() to discover
+                available projects.
         identifier: The title or permalink of the note to read
                    Can be a full memory:// URL, a permalink, a title, or search text
         page: Page number for paginated results (default: 1)

src/basic_memory/mcp/tools/recent_activity.py

@@ -40,13 +40,21 @@ async def recent_activity(
 ) -> str:
     """Get recent activity for a specific project or across all projects.
 
-    This tool works in two modes based on the project parameter:
-
-    **Discovery Mode (project=None)**: Returns activity summary across all projects,
-    enabling project discovery and cross-project activity overview.
-
-    **Project-Specific Mode (project provided)**: Returns detailed activity for a
-    specific project with filtering and graph traversal capabilities.
+    Project Resolution:
+    The server resolves projects in this order:
+    1. Single Project Mode - server constrained to one project, parameter ignored
+    2. Explicit project parameter - specify which project to query
+    3. Default project - server configured default if no project specified
+
+    Discovery Mode:
+    When no specific project can be resolved, returns activity across all projects
+    to help discover available projects and their recent activity.
+
+    Project Discovery (when project is unknown):
+    1. Call list_memory_projects() to see available projects
+    2. Or use this tool without project parameter to see cross-project activity
+    3. Ask the user which project to focus on
+    4. Remember their choice for the conversation
 
     Args:
         type: Filter by content type(s). Can be a string or list of strings.
@@ -62,34 +70,30 @@ async def recent_activity(
             - Relative: "2 days ago", "last week", "yesterday"
             - Points in time: "2024-01-01", "January 1st"
             - Standard format: "7d", "24h"
-        project: Optional project name. If not provided, uses default_project (if default_project_mode=true)
-                or returns activity across all projects for discovery.
-                If unknown, use list_memory_projects() to discover available projects.
+        project: Project name to query. Optional - server will resolve using the
+                hierarchy above. If unknown, use list_memory_projects() to discover
+                available projects.
         context: Optional FastMCP context for performance caching.
 
     Returns:
-        - ProjectActivitySummary: When project=None (discovery mode)
-        - GraphContext: When project is specified (project-specific mode)
+        Human-readable summary of recent activity. When no specific project is
+        resolved, returns cross-project discovery information. When a specific
+        project is resolved, returns detailed activity for that project.
 
     Examples:
-        # Default project mode or discovery mode
+        # Cross-project discovery mode
         recent_activity()
         recent_activity(timeframe="yesterday")
 
-        # Project-specific mode - detailed activity for one project
-        recent_activity(type="entity", timeframe="yesterday")
-        recent_activity(type=["entity"], timeframe="yesterday")
-        recent_activity(type=["relation", "observation"], timeframe="today")
-        recent_activity(type="entity", depth=2, timeframe="2 weeks ago")
-
-        # Explicit project specification
+        # Project-specific activity
         recent_activity(project="work-docs", type="entity", timeframe="yesterday")
+        recent_activity(project="research", type=["entity", "relation"], timeframe="today")
+        recent_activity(project="notes", type="entity", depth=2, timeframe="2 weeks ago")
 
     Raises:
         ToolError: If project doesn't exist or type parameter contains invalid values
 
     Notes:
-        - Discovery mode enables project selection without session state
         - Higher depth values (>3) may impact performance with large result sets
         - For focused queries, consider using build_context with a specific URI
         - Max timeframe is 1 year in the past