basic-memory 0.13.7.dev1__py3-none-any.whl → 0.14.0__py3-none-any.whl

basic_memory/__init__.py

@@ -1,7 +1,7 @@
 """basic-memory - Local-first knowledge management combining Zettelkasten with knowledge graphs"""
 
 # Package version - updated by release automation
-__version__ = "0.13.6"
+__version__ = "0.14.0"
 
 # API version for FastAPI - independent of package version
 __api_version__ = "v0"

basic_memory/api/routers/utils.py

@@ -52,7 +52,7 @@ async def to_graph_context(
                     file_path=item.file_path,
                     permalink=item.permalink,  # pyright: ignore
                     relation_type=item.relation_type,  # pyright: ignore
-                    from_entity=from_entity.title,  # pyright: ignore
+                    from_entity=from_entity.title if from_entity else None,
                     to_entity=to_entity.title if to_entity else None,
                     created_at=item.created_at,
                 )

basic_memory/cli/commands/db.py

@@ -1,13 +1,14 @@
 """Database management commands."""
 
 import asyncio
+from pathlib import Path
 
 import typer
 from loguru import logger
 
 from basic_memory import db
 from basic_memory.cli.app import app
-from basic_memory.config import app_config
+from basic_memory.config import app_config, config_manager
 
 
 @app.command()
@@ -25,6 +26,12 @@ def reset(
             db_path.unlink()
             logger.info(f"Database file deleted: {db_path}")
 
+        # Reset project configuration
+        config_manager.config.projects = {"main": str(Path.home() / "basic-memory")}
+        config_manager.config.default_project = "main"
+        config_manager.save_config(config_manager.config)
+        logger.info("Project configuration reset to default")
+
         # Create a new empty database
         asyncio.run(db.run_migrations(app_config))
         logger.info("Database reset complete")

basic_memory/cli/commands/mcp.py

@@ -85,4 +85,5 @@ def mcp(
             host=host,
             port=port,
             path=path,
+            log_level="INFO",
         )

basic_memory/cli/commands/project.py

@@ -120,7 +120,7 @@ def set_default_project(
     try:
         project_name = generate_permalink(name)
 
-        response = asyncio.run(call_put(client, f"projects/{project_name}/default"))
+        response = asyncio.run(call_put(client, f"/projects/{project_name}/default"))
         result = ProjectStatusResponse.model_validate(response.json())
 
         console.print(f"[green]{result.message}[/green]")
@@ -128,12 +128,8 @@ def set_default_project(
         console.print(f"[red]Error setting default project: {str(e)}[/red]")
         raise typer.Exit(1)
 
-    # Reload configuration to apply the change
-    from importlib import reload
-    from basic_memory import config as config_module
-
-    reload(config_module)
-
+    # The API call above should have updated both config and MCP session
+    # No need for manual reload - the project service handles this automatically
     console.print("[green]Project activated for current session[/green]")
 
 

basic_memory/config.py

@@ -45,7 +45,9 @@ class BasicMemoryConfig(BaseSettings):
     env: Environment = Field(default="dev", description="Environment name")
 
     projects: Dict[str, str] = Field(
-        default_factory=lambda: {"main": str(Path.home() / "basic-memory")},
+        default_factory=lambda: {
+            "main": str(Path(os.getenv("BASIC_MEMORY_HOME", Path.home() / "basic-memory")))
+        },
         description="Mapping of project names to their filesystem paths",
     )
     default_project: str = Field(
@@ -92,7 +94,9 @@ class BasicMemoryConfig(BaseSettings):
         """Ensure configuration is valid after initialization."""
         # Ensure main project exists
         if "main" not in self.projects:  # pragma: no cover
-            self.projects["main"] = str(Path.home() / "basic-memory")
+            self.projects["main"] = str(
+                Path(os.getenv("BASIC_MEMORY_HOME", Path.home() / "basic-memory"))
+            )
 
         # Ensure default project is valid
         if self.default_project not in self.projects:  # pragma: no cover

basic_memory/db.py

@@ -95,11 +95,12 @@ async def get_or_create_db(
 
     if _engine is None:
         _engine, _session_maker = _create_engine_and_session(db_path, db_type)
-        
+
         # Run migrations automatically unless explicitly disabled
         if ensure_migrations:
             if app_config is None:
                 from basic_memory.config import app_config as global_app_config
+
                 app_config = global_app_config
             await run_migrations(app_config, db_type)
 
@@ -170,12 +171,12 @@ async def run_migrations(
 ):  # pragma: no cover
     """Run any pending alembic migrations."""
     global _migrations_completed
-    
+
     # Skip if migrations already completed unless forced
     if _migrations_completed and not force:
         logger.debug("Migrations already completed in this session, skipping")
         return
-        
+
     logger.info("Running database migrations...")
     try:
         # Get the absolute path to the alembic directory relative to this file
@@ -206,7 +207,7 @@ async def run_migrations(
         # initialize the search Index schema
         # the project_id is not used for init_search_index, so we pass a dummy value
         await SearchRepository(session_maker, 1).init_search_index()
-        
+
         # Mark migrations as completed
         _migrations_completed = True
     except Exception as e:  # pragma: no cover

basic_memory/markdown/utils.py

@@ -38,7 +38,9 @@ def entity_model_from_markdown(
     # Update basic fields
     model.title = markdown.frontmatter.title
     model.entity_type = markdown.frontmatter.type
-    model.permalink = markdown.frontmatter.permalink
+    # Only update permalink if it exists in frontmatter, otherwise preserve existing
+    if markdown.frontmatter.permalink is not None:
+        model.permalink = markdown.frontmatter.permalink
     model.file_path = str(file_path)
     model.content_type = "text/markdown"
     model.created_at = markdown.created

basic_memory/mcp/project_session.py

@@ -8,7 +8,7 @@ from dataclasses import dataclass
 from typing import Optional
 from loguru import logger
 
-from basic_memory.config import ProjectConfig, get_project_config
+from basic_memory.config import ProjectConfig, get_project_config, config_manager
 
 
 @dataclass
@@ -64,6 +64,21 @@ class ProjectSession:
         self.current_project = self.default_project  # pragma: no cover
         logger.info(f"Reset project context to default: {self.default_project}")  # pragma: no cover
 
+    def refresh_from_config(self) -> None:
+        """Refresh session state from current configuration.
+
+        This method reloads the default project from config and reinitializes
+        the session. This should be called when the default project is changed
+        via CLI or API to ensure MCP session stays in sync.
+        """
+        # Reload config to get latest default project
+        current_config = config_manager.load_config()
+        new_default = current_config.default_project
+
+        # Reinitialize with new default
+        self.initialize(new_default)
+        logger.info(f"Refreshed project session from config, new default: {new_default}")
+
 
 # Global session instance
 session = ProjectSession()

basic_memory/mcp/prompts/sync_status.py

@@ -12,10 +12,6 @@ from basic_memory.mcp.server import mcp
 )
 async def sync_status_prompt() -> str:
     """Get sync status with AI assistant guidance.
-
-    This prompt provides detailed sync status information along with
-    recommendations for how AI assistants should handle different sync states.
-
     Returns:
         Formatted sync status with AI assistant guidance
     """

basic_memory/mcp/server.py

@@ -105,6 +105,5 @@ auth_settings, auth_provider = create_auth_config()
 # Create the shared server instance
 mcp = FastMCP(
     name="Basic Memory",
-    log_level="DEBUG",
     auth=auth_provider,
 )

basic_memory/mcp/tools/build_context.py

@@ -82,10 +82,15 @@ async def build_context(
     logger.info(f"Building context from {url}")
     # 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)
+
     # Check migration status and wait briefly if needed
     from basic_memory.mcp.tools.utils import wait_for_migration_or_return_status
 
-    migration_status = await wait_for_migration_or_return_status(timeout=5.0)
+    migration_status = await wait_for_migration_or_return_status(
+        timeout=5.0, project_name=active_project.name
+    )
     if migration_status:  # pragma: no cover
         # Return a proper GraphContext with status message
         from basic_memory.schemas.memory import MemoryMetadata
@@ -102,8 +107,6 @@ async def build_context(
                 uri=migration_status,  # Include status in metadata
             ),
         )
-
-    active_project = get_active_project(project)
     project_url = active_project.project_url
 
     response = await call_get(

basic_memory/mcp/tools/move_note.py

@@ -7,9 +7,155 @@ from loguru import logger
 
 from basic_memory.mcp.async_client import client
 from basic_memory.mcp.server import mcp
-from basic_memory.mcp.tools.utils import call_post
+from basic_memory.mcp.tools.utils import call_post, call_get
 from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas import EntityResponse
+from basic_memory.schemas.project_info import ProjectList
+
+
+async def _detect_cross_project_move_attempt(
+    identifier: str, destination_path: str, current_project: str
+) -> Optional[str]:
+    """Detect potential cross-project move attempts and return guidance.
+
+    Args:
+        identifier: The note identifier being moved
+        destination_path: The destination path
+        current_project: The current active project
+
+    Returns:
+        Error message with guidance if cross-project move is detected, None otherwise
+    """
+    try:
+        # Get list of all available projects to check against
+        response = await call_get(client, "/projects/projects")
+        project_list = ProjectList.model_validate(response.json())
+        project_names = [p.name.lower() for p in project_list.projects]
+
+        # Check if destination path contains any project names
+        dest_lower = destination_path.lower()
+        path_parts = dest_lower.split("/")
+
+        # Look for project names in the destination path
+        for part in path_parts:
+            if part in project_names and part != current_project.lower():
+                # Found a different project name in the path
+                matching_project = next(
+                    p.name for p in project_list.projects if p.name.lower() == part
+                )
+                return _format_cross_project_error_response(
+                    identifier, destination_path, current_project, matching_project
+                )
+
+        # Check if the destination path looks like it might be trying to reference another project
+        # (e.g., contains common project-like patterns)
+        if any(keyword in dest_lower for keyword in ["project", "workspace", "repo"]):
+            # This might be a cross-project attempt, but we can't be sure
+            # Return a general guidance message
+            available_projects = [
+                p.name for p in project_list.projects if p.name != current_project
+            ]
+            if available_projects:
+                return _format_potential_cross_project_guidance(
+                    identifier, destination_path, current_project, available_projects
+                )
+
+    except Exception as e:
+        # If we can't detect, don't interfere with normal error handling
+        logger.debug(f"Could not check for cross-project move: {e}")
+        return None
+
+    return None
+
+
+def _format_cross_project_error_response(
+    identifier: str, destination_path: str, current_project: str, target_project: str
+) -> str:
+    """Format error response for detected cross-project move attempts."""
+    return dedent(f"""
+        # Move Failed - Cross-Project Move Not Supported
+        
+        Cannot move '{identifier}' to '{destination_path}' because it appears to reference a different project ('{target_project}').
+        
+        **Current project:** {current_project}
+        **Target project:** {target_project}
+        
+        ## Cross-project moves are not supported directly
+        
+        Notes can only be moved within the same project. To move content between projects, use this workflow:
+        
+        ### Recommended approach:
+        ```
+        # 1. Read the note content from current project
+        read_note("{identifier}")
+        
+        # 2. Switch to the target project
+        switch_project("{target_project}")
+        
+        # 3. Create the note in the target project
+        write_note("Note Title", "content from step 1", "target-folder")
+        
+        # 4. Switch back to original project (optional)
+        switch_project("{current_project}")
+        
+        # 5. Delete the original note if desired
+        delete_note("{identifier}")
+        ```
+        
+        ### Alternative: Stay in current project
+        If you want to move the note within the **{current_project}** project only:
+        ```
+        move_note("{identifier}", "new-folder/new-name.md")
+        ```
+        
+        ## Available projects:
+        Use `list_projects()` to see all available projects and `switch_project("project-name")` to change projects.
+        """).strip()
+
+
+def _format_potential_cross_project_guidance(
+    identifier: str, destination_path: str, current_project: str, available_projects: list[str]
+) -> str:
+    """Format guidance for potentially cross-project moves."""
+    other_projects = ", ".join(available_projects[:3])  # Show first 3 projects
+    if len(available_projects) > 3:
+        other_projects += f" (and {len(available_projects) - 3} others)"
+
+    return dedent(f"""
+        # Move Failed - Check Project Context
+        
+        Cannot move '{identifier}' to '{destination_path}' within the current project '{current_project}'.
+        
+        ## If you intended to move within the current project:
+        The destination path should be relative to the project root:
+        ```
+        move_note("{identifier}", "folder/filename.md")
+        ```
+        
+        ## If you intended to move to a different project:
+        Cross-project moves require switching projects first. Available projects: {other_projects}
+        
+        ### To move to another project:
+        ```
+        # 1. Read the content
+        read_note("{identifier}")
+        
+        # 2. Switch to target project
+        switch_project("target-project-name")
+        
+        # 3. Create note in target project
+        write_note("Title", "content", "folder")
+        
+        # 4. Switch back and delete original if desired
+        switch_project("{current_project}")
+        delete_note("{identifier}")
+        ```
+        
+        ### To see all projects:
+        ```
+        list_projects()
+        ```
+        """).strip()
 
 
 def _format_move_error_response(error_message: str, identifier: str, destination_path: str) -> str:
@@ -258,6 +404,14 @@ async def move_note(
     active_project = get_active_project(project)
     project_url = active_project.project_url
 
+    # Check for potential cross-project move attempts
+    cross_project_error = await _detect_cross_project_move_attempt(
+        identifier, destination_path, active_project.name
+    )
+    if cross_project_error:
+        logger.info(f"Detected cross-project move attempt: {identifier} -> {destination_path}")
+        return cross_project_error
+
     try:
         # Prepare move request
         move_data = {

basic_memory/mcp/tools/read_note.py

@@ -52,14 +52,17 @@ async def read_note(
         read_note("Meeting Notes", project="work-project")
     """
 
+    # Get the active project first to check project-specific sync status
+    active_project = get_active_project(project)
+
     # Check migration status and wait briefly if needed
     from basic_memory.mcp.tools.utils import wait_for_migration_or_return_status
 
-    migration_status = await wait_for_migration_or_return_status(timeout=5.0)
+    migration_status = await wait_for_migration_or_return_status(
+        timeout=5.0, project_name=active_project.name
+    )
     if migration_status:  # pragma: no cover
         return f"# System Status\n\n{migration_status}\n\nPlease wait for migration to complete before reading notes."
-
-    active_project = get_active_project(project)
     project_url = active_project.project_url
 
     # Get the file via REST API - first try direct permalink lookup

basic_memory/mcp/tools/search.py

@@ -45,13 +45,18 @@ def _format_search_error_response(error_message: str, query: str, search_type: s
             - Boolean OR: `meeting OR discussion`
             - Boolean NOT: `project NOT archived`
             - Grouped: `(project OR planning) AND notes`
+            - Exact phrases: `"weekly standup meeting"`
+            - Content-specific: `tag:example` or `category:observation`
 
             ## Try again with:
             ```
-            search_notes("INSERT_CLEAN_QUERY_HERE")
+            search_notes("{clean_query}")
             ```
 
-            Replace INSERT_CLEAN_QUERY_HERE with your simplified search terms.
+            ## Alternative search strategies:
+            - Break into simpler terms: `search_notes("{' '.join(clean_query.split()[:2])}")`
+            - Try different search types: `search_notes("{clean_query}", search_type="title")`
+            - Use filtering: `search_notes("{clean_query}", types=["entity"])`
             """).strip()
 
     # Project not found errors (check before general "not found")
@@ -85,24 +90,39 @@ def _format_search_error_response(error_message: str, query: str, search_type: s
 
             No content found matching '{query}' in the current project.
 
-            ## Suggestions to try:
+            ## Search strategy suggestions:
             1. **Broaden your search**: Try fewer or more general terms
                - Instead of: `{query}`
                - Try: `{simplified_query}`
 
-            2. **Check spelling**: Verify terms are spelled correctly
-            3. **Try different search types**:
-               - Text search: `search_notes("{query}", search_type="text")`
-               - Title search: `search_notes("{query}", search_type="title")`
-               - Permalink search: `search_notes("{query}", search_type="permalink")`
-
-            4. **Use boolean operators**:
-               - Try OR search for broader results
-
-            ## Check what content exists:
-            - Recent activity: `recent_activity(timeframe="7d")`
-            - List files: `list_directory("/")`
-            - Browse by folder: `list_directory("/notes")` or `list_directory("/docs")`
+            2. **Check spelling and try variations**:
+               - Verify terms are spelled correctly
+               - Try synonyms or related terms
+
+            3. **Use different search approaches**:
+               - **Text search**: `search_notes("{query}", search_type="text")` (searches full content)
+               - **Title search**: `search_notes("{query}", search_type="title")` (searches only titles)
+               - **Permalink search**: `search_notes("{query}", search_type="permalink")` (searches file paths)
+
+            4. **Try boolean operators for broader results**:
+               - OR search: `search_notes("{' OR '.join(query.split()[:3])}")`
+               - Remove restrictive terms: Focus on the most important keywords
+
+            5. **Use filtering to narrow scope**:
+               - By content type: `search_notes("{query}", types=["entity"])`
+               - By recent content: `search_notes("{query}", after_date="1 week")`
+               - By entity type: `search_notes("{query}", entity_types=["observation"])`
+
+            6. **Try advanced search patterns**:
+               - Tag search: `search_notes("tag:your-tag")`
+               - Category search: `search_notes("category:observation")`
+               - Pattern matching: `search_notes("*{query}*", search_type="permalink")`
+
+            ## Explore what content exists:
+            - **Recent activity**: `recent_activity(timeframe="7d")` - See what's been updated recently
+            - **List directories**: `list_directory("/")` - Browse all content
+            - **Browse by folder**: `list_directory("/notes")` or `list_directory("/docs")`
+            - **Check project**: `get_current_project()` - Verify you're in the right project
             """).strip()
 
     # Server/API errors
@@ -151,25 +171,36 @@ You don't have permission to search in the current project: {error_message}
 
 Error searching for '{query}': {error_message}
 
-## General troubleshooting:
-1. **Check your query**: Ensure it uses valid search syntax
-2. **Try simpler terms**: Use basic words without special characters
+## Troubleshooting steps:
+1. **Simplify your query**: Try basic words without special characters
+2. **Check search syntax**: Ensure boolean operators are correctly formatted
 3. **Verify project access**: Make sure you can access the current project
-4. **Check recent activity**: `recent_activity(timeframe="7d")` to see if content exists
-
-## Alternative approaches:
-- Browse files: `list_directory("/")`
-- Try different search type: `search_notes("{query}", search_type="title")`
-- Search with filters: `search_notes("{query}", types=["entity"])`
-
-## Need help?
-- View recent changes: `recent_activity()`
-- List projects: `list_projects()` 
-- Check current project: `get_current_project()`"""
+4. **Test with simple search**: Try `search_notes("test")` to verify search is working
+
+## Alternative search approaches:
+- **Different search types**: 
+  - Title only: `search_notes("{query}", search_type="title")`
+  - Permalink patterns: `search_notes("{query}*", search_type="permalink")`
+- **With filters**: `search_notes("{query}", types=["entity"])`
+- **Recent content**: `search_notes("{query}", after_date="1 week")`
+- **Boolean variations**: `search_notes("{' OR '.join(query.split()[:2])}")`
+
+## Explore your content:
+- **Browse files**: `list_directory("/")` - See all available content
+- **Recent activity**: `recent_activity(timeframe="7d")` - Check what's been updated
+- **Project info**: `get_current_project()` - Verify current project
+- **All projects**: `list_projects()` - Switch to different project if needed
+
+## Search syntax reference:
+- **Basic**: `keyword` or `multiple words`
+- **Boolean**: `term1 AND term2`, `term1 OR term2`, `term1 NOT term2`
+- **Phrases**: `"exact phrase"`
+- **Grouping**: `(term1 OR term2) AND term3`
+- **Patterns**: `tag:example`, `category:observation`"""
 
 
 @mcp.tool(
-    description="Search across all content in the knowledge base.",
+    description="Search across all content in the knowledge base with advanced syntax support.",
 )
 async def search_notes(
     query: str,
@@ -181,24 +212,60 @@ async def search_notes(
     after_date: Optional[str] = None,
     project: Optional[str] = None,
 ) -> SearchResponse | str:
-    """Search across all content in the knowledge base.
+    """Search across all content in the knowledge base with comprehensive syntax support.
 
     This tool searches the knowledge base using full-text search, pattern matching,
     or exact permalink lookup. It supports filtering by content type, entity type,
-    and date.
+    and date, with advanced boolean and phrase search capabilities.
+
+    ## Search Syntax Examples
+
+    ### Basic Searches
+    - `search_notes("keyword")` - Find any content containing "keyword"
+    - `search_notes("exact phrase")` - Search for exact phrase match
+
+    ### Advanced Boolean Searches  
+    - `search_notes("term1 term2")` - Find content with both terms (implicit AND)
+    - `search_notes("term1 AND term2")` - Explicit AND search (both terms required)
+    - `search_notes("term1 OR term2")` - Either term can be present
+    - `search_notes("term1 NOT term2")` - Include term1 but exclude term2
+    - `search_notes("(project OR planning) AND notes")` - Grouped boolean logic
+
+    ### Content-Specific Searches
+    - `search_notes("tag:example")` - Search within specific tags (if supported by content)
+    - `search_notes("category:observation")` - Filter by observation categories
+    - `search_notes("author:username")` - Find content by author (if metadata available)
+
+    ### Search Type Examples
+    - `search_notes("Meeting", search_type="title")` - Search only in titles
+    - `search_notes("docs/meeting-*", search_type="permalink")` - Pattern match permalinks
+    - `search_notes("keyword", search_type="text")` - Full-text search (default)
+
+    ### Filtering Options
+    - `search_notes("query", types=["entity"])` - Search only entities
+    - `search_notes("query", types=["note", "person"])` - Multiple content types
+    - `search_notes("query", entity_types=["observation"])` - Filter by entity type
+    - `search_notes("query", after_date="2024-01-01")` - Recent content only
+    - `search_notes("query", after_date="1 week")` - Relative date filtering
+
+    ### Advanced Pattern Examples
+    - `search_notes("project AND (meeting OR discussion)")` - Complex boolean logic
+    - `search_notes("\"exact phrase\" AND keyword")` - Combine phrase and keyword search
+    - `search_notes("bug NOT fixed")` - Exclude resolved issues
+    - `search_notes("docs/2024-*", search_type="permalink")` - Year-based permalink search
 
     Args:
-        query: The search query string
+        query: The search query string (supports boolean operators, phrases, patterns)
         page: The page number of results to return (default 1)
         page_size: The number of results to return per page (default 10)
         search_type: Type of search to perform, one of: "text", "title", "permalink" (default: "text")
         types: Optional list of note types to search (e.g., ["note", "person"])
         entity_types: Optional list of entity types to filter by (e.g., ["entity", "observation"])
-        after_date: Optional date filter for recent content (e.g., "1 week", "2d")
+        after_date: Optional date filter for recent content (e.g., "1 week", "2d", "2024-01-01")
         project: Optional project name to search in. If not provided, uses current active project.
 
     Returns:
-        SearchResponse with results and pagination info
+        SearchResponse with results and pagination info, or helpful error guidance if search fails
 
     Examples:
         # Basic text search
@@ -216,16 +283,19 @@ async def search_notes(
         # Boolean search with grouping
         results = await search_notes("(project OR planning) AND notes")
 
+        # Exact phrase search
+        results = await search_notes("\"weekly standup meeting\"")
+
         # Search with type filter
         results = await search_notes(
             query="meeting notes",
             types=["entity"],
         )
 
-        # Search with entity type filter, e.g., note vs
+        # Search with entity type filter
         results = await search_notes(
             query="meeting notes",
-            types=["entity"],
+            entity_types=["observation"],
         )
 
         # Search for recent content
@@ -242,6 +312,13 @@ async def search_notes(
 
         # Search in specific project
         results = await search_notes("meeting notes", project="work-project")
+
+        # Complex search with multiple filters
+        results = await search_notes(
+            query="(bug OR issue) AND NOT resolved",
+            types=["entity"],
+            after_date="2024-01-01"
+        )
     """
     # Create a SearchQuery object based on the parameters
     search_query = SearchQuery()