basic-memory 0.14.4__py3-none-any.whl → 0.15.0__py3-none-any.whl

basic_memory/mcp/resources/ai_assistant_guide.md

@@ -14,6 +14,44 @@ natural conversations. The system automatically creates a semantic knowledge gra
 - **Semantic**: Simple patterns create a structured knowledge graph
 - **Persistent**: Knowledge persists across sessions and conversations
 
+## Project Management and Configuration
+
+Basic Memory uses a **stateless architecture** where each tool call can specify which project to work with. This provides three ways to determine the active project:
+
+### Three-Tier Project Resolution
+
+1. **CLI Constraint (Highest Priority)**: When Basic Memory is started with `--project project-name`, all operations are constrained to that project
+2. **Explicit Project Parameter (Medium Priority)**: When you specify `project="project-name"` in tool calls
+3. **Default Project Mode (Lowest Priority)**: When `default_project_mode=true` in configuration, tools automatically use the configured `default_project`
+
+### Default Project Mode
+
+When `default_project_mode` is enabled in the user's configuration:
+- All tools become more convenient - no need to specify project repeatedly
+- Perfect for users who primarily work with a single project
+- Still allows explicit project specification when needed
+- Falls back gracefully to multi-project mode if no default is configured
+
+```python
+# With default_project_mode enabled, these are equivalent:
+await write_note("My Note", "Content", "folder")
+await write_note("My Note", "Content", "folder", project="default-project")
+
+# You can still override with explicit project:
+await write_note("My Note", "Content", "folder", project="other-project")
+```
+
+### Project Discovery
+
+If you're unsure which project to use:
+```python
+# Discover available projects
+projects = await list_memory_projects()
+
+# See recent activity across projects for recommendations
+activity = await recent_activity()  # Shows cross-project activity and suggestions
+```
+
 ## The Importance of the Knowledge Graph
 
 **Basic Memory's value comes from connections between notes, not just the notes themselves.**
@@ -33,49 +71,120 @@ build these connections!
 
 ## Core Tools Reference
 
+### Knowledge Creation and Editing
+
 ```python
 # Writing knowledge - THE MOST IMPORTANT TOOL!
 response = await write_note(
     title="Search Design",  # Required: Note title
     content="# Search Design\n...",  # Required: Note content
-    folder="specs",  # Optional: Folder to save in
+    folder="specs",  # Required: Folder to save in
     tags=["search", "design"],  # Optional: Tags for categorization
-    verbose=True  # Optional: Get parsing details
+    project="my-project"  # Optional: Explicit project (uses default if not specified)
+)
+
+# Editing existing notes
+await edit_note(
+    identifier="Search Design",  # Required: Note to edit
+    operation="append",  # Required: append, prepend, find_replace, replace_section
+    content="\n## New Section\nAdditional content",  # Required: Content to add/replace
+    project="my-project"  # Optional: Explicit project
+)
+
+# Moving notes
+await move_note(
+    identifier="Search Design",  # Required: Note to move
+    destination_path="archive/old-search-design.md",  # Required: New location
+    project="my-project"  # Optional: Explicit project
+)
+
+# Deleting notes
+success = await delete_note(
+    identifier="Old Draft",  # Required: Note to delete
+    project="my-project"  # Optional: Explicit project
 )
+```
+
+### Knowledge Reading and Discovery
 
+```python
 # Reading knowledge
-content = await read_note("Search Design")  # By title
+content = await read_note("Search Design")  # By title (uses default project)
 content = await read_note("specs/search-design")  # By path
 content = await read_note("memory://specs/search")  # By memory URL
+content = await read_note("Search Design", project="work-docs")  # Explicit project
 
+# Reading raw file content (text, images, binaries)
+file_data = await read_content(
+    path="assets/diagram.png",  # Required: File path
+    project="my-project"  # Optional: Explicit project
+)
+
+# Viewing notes as formatted artifacts
+await view_note(
+    identifier="Search Design",  # Required: Note to view
+    project="my-project",  # Optional: Explicit project
+    page=1,  # Optional: Pagination
+    page_size=10  # Optional: Items per page
+)
+
+# Browsing directory contents
+listing = await list_directory(
+    dir_name="/specs",  # Optional: Directory path (default: "/")
+    depth=2,  # Optional: Recursion depth
+    file_name_glob="*.md",  # Optional: File pattern filter
+    project="my-project"  # Optional: Explicit project
+)
+```
+
+### Search and Context
+
+```python
 # Searching for knowledge
 results = await search_notes(
-    query="authentication system",  # Text to search for
+    query="authentication system",  # Required: Text to search for
+    project="my-project",  # Optional: Explicit project
     page=1,  # Optional: Pagination
-    page_size=10  # Optional: Results per page
+    page_size=10,  # Optional: Results per page
+    search_type="text",  # Optional: "text", "title", or "permalink"
+    types=["entity"],  # Optional: Filter by content types
+    entity_types=["observation"],  # Optional: Filter by entity types
+    after_date="1 week"  # Optional: Recent content only
 )
 
 # Building context from the knowledge graph
 context = await build_context(
-    url="memory://specs/search",  # Starting point
+    url="memory://specs/search",  # Required: Starting point
+    project="my-project",  # Optional: Explicit project
     depth=2,  # Optional: How many hops to follow
-    timeframe="1 month"  # Optional: Recent timeframe
+    timeframe="1 month",  # Optional: Recent timeframe
+    max_related=10  # Optional: Max related items
 )
 
 # Checking recent changes
 activity = await recent_activity(
-    type="all",  # Optional: Entity types to include
+    type=["entity", "relation"],  # Optional: Entity types to include
     depth=1,  # Optional: Related items to include
-    timeframe="1 week"  # Optional: Time window
+    timeframe="1 week",  # Optional: Time window
+    project="my-project"  # Optional: Explicit project (None for cross-project discovery)
 )
+```
+
+### Visualization and Project Management
 
+```python
 # Creating a knowledge visualization
 canvas_result = await canvas(
-    nodes=[{"id": "note1", "label": "Search Design"}],  # Nodes to display
-    edges=[{"from": "note1", "to": "note2"}],  # Connections
-    title="Project Overview",  # Canvas title
-    folder="diagrams"  # Storage location
+    nodes=[{"id": "note1", "type": "file", "file": "Search Design.md"}],  # Required: Nodes
+    edges=[{"id": "edge1", "fromNode": "note1", "toNode": "note2"}],  # Required: Edges
+    title="Project Overview",  # Required: Canvas title
+    folder="diagrams",  # Required: Storage location
+    project="my-project"  # Optional: Explicit project
 )
+
+# Project management
+projects = await list_memory_projects()  # List all available projects
+project_info = await project_info(project="my-project")  # Get project statistics
 ```
 
 ## memory:// URLs Explained
@@ -135,27 +244,31 @@ Users will interact with Basic Memory in patterns like:
 1. **Creating knowledge**:
    ```
    Human: "Let's write up what we discussed about search."
-   
+
    You: I'll create a note capturing our discussion about the search functionality.
-   [Use write_note() to record the conversation details]
+   await write_note(
+       title="Search Functionality Discussion",
+       content="# Search Functionality Discussion\n...",
+       folder="discussions"
+   )
    ```
 
 2. **Referencing existing knowledge**:
    ```
    Human: "Take a look at memory://specs/search"
-   
+
    You: I'll examine that information.
-   [Use build_context() to gather related information]
-   [Then read_note() to access specific content]
+   context = await build_context(url="memory://specs/search")
+   content = await read_note("specs/search")
    ```
 
 3. **Finding information**:
    ```
    Human: "What were our decisions about auth?"
-   
+
    You: Let me find that information for you.
-   [Use search_notes() to find relevant notes]
-   [Then build_context() to understand connections]
+   results = await search_notes(query="auth decisions")
+   context = await build_context(url=f"memory://{results[0].permalink}")
    ```
 
 ## Key Things to Remember
@@ -263,7 +376,7 @@ When creating relations, you can:
 # Example workflow for creating notes with effective relations
 async def create_note_with_effective_relations():
     # Search for existing entities to reference
-    search_results = await search_notes("travel")
+    search_results = await search_notes(query="travel")
     existing_entities = [result.title for result in search_results.primary_results]
 
     # Check if specific entities exist
@@ -297,7 +410,7 @@ async def create_note_with_effective_relations():
 
     # Now create the note with both verified and forward relations
     content = f"""# Tokyo Neighborhood Guide
-    
+
 ## Overview
 Details about different Tokyo neighborhoods and their unique characteristics.
 
@@ -313,7 +426,7 @@ Details about different Tokyo neighborhoods and their unique characteristics.
     result = await write_note(
         title="Tokyo Neighborhood Guide",
         content=content,
-        verbose=True
+        folder="travel"
     )
 
     # You can check which relations were resolved and which are forward references
@@ -335,7 +448,7 @@ Common issues to watch for:
        content = await read_note("Document")
    except:
        # Try search instead
-       results = await search_notes("Document")
+       results = await search_notes(query="Document")
        if results and results.primary_results:
            # Found something similar
            content = await read_note(results.primary_results[0].permalink)
@@ -343,23 +456,40 @@ Common issues to watch for:
 
 2. **Forward References (Unresolved Relations)**
    ```python
-   response = await write_note(..., verbose=True)
+   response = await write_note(
+       title="My Note",
+       content="Content with [[Forward Reference]]",
+       folder="notes"
+   )
    # Check for forward references (unresolved relations)
    forward_refs = []
    for relation in response.get('relations', []):
        if not relation.get('target_id'):
            forward_refs.append(relation.get('to_name'))
-   
+
    if forward_refs:
        # This is a feature, not an error! Inform the user about forward references
        print(f"Note created with forward references to: {forward_refs}")
        print("These will be automatically linked when those notes are created.")
-       
+
        # Optionally suggest creating those entities now
        print("Would you like me to create any of these notes now to complete the connections?")
    ```
 
-3. **Sync Issues**
+3. **Project Discovery Issues**
+   ```python
+   # If user asks about content but no default project is configured
+   try:
+       results = await search_notes(query="user query")
+   except Exception as e:
+       if "project" in str(e).lower():
+           # Show available projects and ask user to choose
+           projects = await list_memory_projects()
+           print(f"Available projects: {[p.name for p in projects]}")
+           print("Which project should I search in?")
+   ```
+
+4. **Sync Issues**
    ```python
    # If information seems outdated
    activity = await recent_activity(timeframe="1 hour")
@@ -369,14 +499,21 @@ Common issues to watch for:
 
 ## Best Practices
 
-1. **Proactively Record Context**
+1. **Smart Project Management**
+    - **For new users**: Call `recent_activity()` without project parameter to discover active projects and get recommendations
+    - **For known projects**: Use explicit project parameters when switching between multiple projects
+    - **For single-project users**: Rely on default_project_mode for convenience
+    - **When uncertain**: Use `list_memory_projects()` to show available options and ask the user
+    - **Remember choices**: Once a user indicates their preferred project, use it consistently throughout the conversation
+
+2. **Proactively Record Context**
     - Offer to capture important discussions
     - Record decisions, rationales, and conclusions
     - Link to related topics
     - Ask for permission first: "Would you like me to save our discussion about [topic]?"
     - Confirm when complete: "I've saved our discussion to Basic Memory"
 
-2. **Create a Rich Semantic Graph**
+3. **Create a Rich Semantic Graph**
     - **Add meaningful observations**: Include at least 3-5 categorized observations in each note
     - **Create deliberate relations**: Connect each note to at least 2-3 related entities
     - **Use existing entities**: Before creating a new relation, search for existing entities
@@ -386,7 +523,7 @@ Common issues to watch for:
       of "relates_to")
     - **Consider bidirectional relations**: When appropriate, create inverse relations in both entities
 
-3. **Structure Content Thoughtfully**
+4. **Structure Content Thoughtfully**
     - Use clear, descriptive titles
     - Organize with logical sections (Context, Decision, Implementation, etc.)
     - Include relevant context and background
@@ -394,20 +531,21 @@ Common issues to watch for:
     - Use a consistent format for similar types of notes
     - Balance detail with conciseness
 
-4. **Navigate Knowledge Effectively**
-    - Start with specific searches
-    - Follow relation paths
+5. **Navigate Knowledge Effectively**
+    - Start with specific searches using `search_notes()`
+    - Follow relation paths with `build_context()`
     - Combine information from multiple sources
-    - Verify information is current
+    - Verify information is current with `recent_activity()`
     - Build a complete picture before responding
+    - Use appropriate project context for searches
 
-5. **Help Users Maintain Their Knowledge**
-    - Suggest organizing related topics
-    - Identify potential duplicates
+6. **Help Users Maintain Their Knowledge**
+    - Suggest organizing related topics across projects when appropriate
+    - Identify potential duplicates using search
     - Recommend adding relations between topics
     - Offer to create summaries of scattered information
-    - Suggest potential missing relations: "I notice this might relate to [topic], would you like me to add that
-      connection?"
+    - Suggest potential missing relations: "I notice this might relate to [topic], would you like me to add that connection?"
+    - Help users decide when to use explicit vs default project parameters
 
 Built with ♥️ b
 y Basic Machines

basic_memory/mcp/resources/project_info.py

@@ -1,19 +1,24 @@
 """Project info tool for Basic Memory MCP server."""
 
+from typing import Optional
+
 from loguru import logger
+from fastmcp import Context
 
-from basic_memory.mcp.project_session import get_active_project
 from basic_memory.mcp.async_client import client
+from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_get
 from basic_memory.schemas import ProjectInfoResponse
 
 
 @mcp.resource(
-    uri="memory://project_info",
+    uri="memory://{project}/info",
     description="Get information and statistics about the current Basic Memory project.",
 )
-async def project_info() -> ProjectInfoResponse:
+async def project_info(
+    project: Optional[str] = None, context: Context | None = None
+) -> ProjectInfoResponse:
     """Get comprehensive information about the current Basic Memory project.
 
     This tool provides detailed statistics and status information about your
@@ -31,13 +36,22 @@ async def project_info() -> ProjectInfoResponse:
     - Monitor growth and activity over time
     - Identify potential issues like unresolved relations
 
+    Args:
+        project: Optional project name. If not provided, uses default_project
+                (if default_project_mode=true) or CLI constraint. If unknown,
+                use list_memory_projects() to discover available projects.
+        context: Optional FastMCP context for performance caching.
+
     Returns:
         Detailed project information and statistics
 
     Examples:
-        # Get information about the current project
+        # Get information about the current/default project
         info = await project_info()
 
+        # Get information about a specific project
+        info = await project_info(project="my-project")
+
         # Check entity counts
         print(f"Total entities: {info.statistics.total_entities}")
 
@@ -45,8 +59,8 @@ async def project_info() -> ProjectInfoResponse:
         print(f"Basic Memory version: {info.system.version}")
     """
     logger.info("Getting project info")
-    project_config = get_active_project()
-    project_url = project_config.project_url
+    project_config = await get_active_project(client, project, context)
+    project_url = project_config.permalink
 
     # Call the API endpoint
     response = await call_get(client, f"{project_url}/project/info")

basic_memory/mcp/server.py

@@ -2,45 +2,8 @@
 Basic Memory FastMCP server.
 """
 
-import asyncio
-from contextlib import asynccontextmanager
-from dataclasses import dataclass
-from typing import AsyncIterator, Optional, Any
-
 from fastmcp import FastMCP
 
-from basic_memory.config import ConfigManager
-from basic_memory.services.initialization import initialize_app
-
-
-@dataclass
-class AppContext:
-    watch_task: Optional[asyncio.Task]
-    migration_manager: Optional[Any] = None
-
-
-@asynccontextmanager
-async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:  # pragma: no cover
-    """ """
-    # defer import so tests can monkeypatch
-    from basic_memory.mcp.project_session import session
-
-    app_config = ConfigManager().config
-    # Initialize on startup (now returns migration_manager)
-    migration_manager = await initialize_app(app_config)
-
-    # Initialize project session with default project
-    session.initialize(app_config.default_project)
-
-    try:
-        yield AppContext(watch_task=None, migration_manager=migration_manager)
-    finally:
-        # Cleanup on shutdown - migration tasks will be cancelled automatically
-        pass
-
-
-# Create the shared server instance with custom Stytch auth
 mcp = FastMCP(
     name="Basic Memory",
-    lifespan=app_lifespan,
 )

basic_memory/mcp/tools/__init__.py

@@ -21,13 +21,13 @@ from basic_memory.mcp.tools.move_note import move_note
 from basic_memory.mcp.tools.sync_status import sync_status
 from basic_memory.mcp.tools.project_management import (
     list_memory_projects,
-    switch_project,
-    get_current_project,
-    set_default_project,
     create_memory_project,
     delete_project,
 )
 
+# ChatGPT-compatible tools
+from basic_memory.mcp.tools.chatgpt_tools import search, fetch
+
 __all__ = [
     "build_context",
     "canvas",
@@ -35,16 +35,15 @@ __all__ = [
     "delete_note",
     "delete_project",
     "edit_note",
-    "get_current_project",
+    "fetch",
     "list_directory",
     "list_memory_projects",
     "move_note",
     "read_content",
     "read_note",
     "recent_activity",
+    "search",
     "search_notes",
-    "set_default_project",
-    "switch_project",
     "sync_status",
     "view_note",
     "write_note",

basic_memory/mcp/tools/build_context.py

@@ -3,11 +3,12 @@
 from typing import Optional
 
 from loguru import logger
+from fastmcp import Context
 
 from basic_memory.mcp.async_client import client
+from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_get
-from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas.base import TimeFrame
 from basic_memory.schemas.memory import (
     GraphContext,
@@ -17,18 +18,19 @@ from basic_memory.schemas.memory import (
 
 type StringOrInt = str | int
 
+
 @mcp.tool(
     description="""Build context from a memory:// URI to continue conversations naturally.
-    
+
     Use this to follow up on previous discussions or explore related topics.
-    
+
     Memory URL Format:
-    - Use paths like "folder/note" or "memory://folder/note" 
+    - Use paths like "folder/note" or "memory://folder/note"
     - Pattern matching: "folder/*" matches all notes in folder
     - Valid characters: letters, numbers, hyphens, underscores, forward slashes
     - Avoid: double slashes (//), angle brackets (<>), quotes, pipes (|)
     - Examples: "specs/search", "projects/basic-memory", "notes/*"
-    
+
     Timeframes support natural language like:
     - "2 days ago", "last week", "today", "3 months ago"
     - Or standard formats like "7d", "24h"
@@ -36,27 +38,34 @@ type StringOrInt = str | int
 )
 async def build_context(
     url: MemoryUrl,
+    project: Optional[str] = None,
     depth: Optional[StringOrInt] = 1,
     timeframe: Optional[TimeFrame] = "7d",
     page: int = 1,
     page_size: int = 10,
     max_related: int = 10,
-    project: Optional[str] = None,
+    context: Context | None = None,
 ) -> GraphContext:
-    """Get context needed to continue a discussion.
+    """Get context needed to continue a discussion within a specific project.
 
     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.
 
+    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: 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"
         page: Page number of results to return (default: 1)
         page_size: Number of results to return per page (default: 10)
         max_related: Maximum number of related results to return (default: 10)
-        project: Optional project name to build context from. If not provided, uses current active project.
+        context: Optional FastMCP context for performance caching.
 
     Returns:
         GraphContext containing:
@@ -66,34 +75,35 @@ async def build_context(
 
     Examples:
         # Continue a specific discussion
-        build_context("memory://specs/search")
+        build_context("my-project", "memory://specs/search")
 
         # Get deeper context about a component
-        build_context("memory://components/memory-service", depth=2)
+        build_context("work-docs", "memory://components/memory-service", depth=2)
 
         # Look at recent changes to a specification
-        build_context("memory://specs/document-format", timeframe="today")
+        build_context("research", "memory://specs/document-format", timeframe="today")
 
         # Research the history of a feature
-        build_context("memory://features/knowledge-graph", timeframe="3 months ago")
+        build_context("dev-notes", "memory://features/knowledge-graph", timeframe="3 months ago")
 
-        # Build context from specific project
-        build_context("memory://specs/search", project="work-project")
+    Raises:
+        ToolError: If project doesn't exist or depth parameter is invalid
     """
-    logger.info(f"Building context from {url}")
-    
+    logger.info(f"Building context from {url} in project {project}")
+
     # Convert string depth to integer if needed
     if isinstance(depth, str):
         try:
             depth = int(depth)
         except ValueError:
             from mcp.server.fastmcp.exceptions import ToolError
+
             raise ToolError(f"Invalid depth parameter: '{depth}' is not a valid integer")
-    
+
     # URL is already validated and normalized by MemoryUrl type annotation
 
-    # Get the active project first to check project-specific sync status
-    active_project = get_active_project(project)
+    # Get the active project using the new stateless approach
+    active_project = await get_active_project(client, project, context)
 
     # Check migration status and wait briefly if needed
     from basic_memory.mcp.tools.utils import wait_for_migration_or_return_status