basic-memory 0.13.0b4__py3-none-any.whl → 0.13.0b6__py3-none-any.whl

basic_memory/__init__.py

@@ -1,9 +1,4 @@
 """basic-memory - Local-first knowledge management combining Zettelkasten with knowledge graphs"""
 
-try:
-    from importlib.metadata import version
-
-    __version__ = version("basic-memory")
-except Exception:  # pragma: no cover
-    # Fallback if package not installed (e.g., during development)
-    __version__ = "0.0.0"  # pragma: no cover
+# API version for FastAPI - independent of package version
+__version__ = "v0"

basic_memory/api/routers/knowledge_router.py

@@ -14,6 +14,7 @@ from basic_memory.deps import (
     FileServiceDep,
     ProjectConfigDep,
     AppConfigDep,
+    SyncServiceDep,
 )
 from basic_memory.schemas import (
     EntityListResponse,
@@ -63,6 +64,7 @@ async def create_or_update_entity(
     entity_service: EntityServiceDep,
     search_service: SearchServiceDep,
     file_service: FileServiceDep,
+    sync_service: SyncServiceDep,
 ) -> EntityResponse:
     """Create or update an entity. If entity exists, it will be updated, otherwise created."""
     logger.info(
@@ -85,6 +87,17 @@ async def create_or_update_entity(
 
     # reindex
     await search_service.index_entity(entity, background_tasks=background_tasks)
+
+    # Attempt immediate relation resolution when creating new entities
+    # This helps resolve forward references when related entities are created in the same session
+    if created:
+        try:
+            await sync_service.resolve_relations()
+            logger.debug(f"Resolved relations after creating entity: {entity.permalink}")
+        except Exception as e:  # pragma: no cover
+            # Don't fail the entire request if relation resolution fails
+            logger.warning(f"Failed to resolve relations after entity creation: {e}")
+
     result = EntityResponse.model_validate(entity)
 
     logger.info(

basic_memory/api/routers/memory_router.py

@@ -2,12 +2,11 @@
 
 from typing import Annotated, Optional
 
-from dateparser import parse
 from fastapi import APIRouter, Query
 from loguru import logger
 
 from basic_memory.deps import ContextServiceDep, EntityRepositoryDep
-from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.base import TimeFrame, parse_timeframe
 from basic_memory.schemas.memory import (
     GraphContext,
     normalize_memory_url,
@@ -40,7 +39,7 @@ async def recent(
         f"Getting recent context: `{types}` depth: `{depth}` timeframe: `{timeframe}` page: `{page}` page_size: `{page_size}` max_related: `{max_related}`"
     )
     # Parse timeframe
-    since = parse(timeframe)
+    since = parse_timeframe(timeframe)
     limit = page_size
     offset = (page - 1) * page_size
 
@@ -78,7 +77,7 @@ async def get_memory_context(
     memory_url = normalize_memory_url(uri)
 
     # Parse timeframe
-    since = parse(timeframe) if timeframe else None
+    since = parse_timeframe(timeframe) if timeframe else None
     limit = page_size
     offset = (page - 1) * page_size
 

basic_memory/api/routers/project_router.py

@@ -3,7 +3,7 @@
 from fastapi import APIRouter, HTTPException, Path, Body
 from typing import Optional
 
-from basic_memory.deps import ProjectServiceDep
+from basic_memory.deps import ProjectServiceDep, ProjectPathDep
 from basic_memory.schemas import ProjectInfoResponse
 from basic_memory.schemas.project_info import (
     ProjectList,
@@ -22,9 +22,10 @@ project_resource_router = APIRouter(prefix="/projects", tags=["project_managemen
 @project_router.get("/info", response_model=ProjectInfoResponse)
 async def get_project_info(
     project_service: ProjectServiceDep,
+    project: ProjectPathDep,
 ) -> ProjectInfoResponse:
-    """Get comprehensive information about the current Basic Memory project."""
-    return await project_service.get_project_info()
+    """Get comprehensive information about the specified Basic Memory project."""
+    return await project_service.get_project_info(project)
 
 
 # Update a project
@@ -47,7 +48,7 @@ async def update_project(
     """
     try:  # pragma: no cover
         # Get original project info for the response
-        old_project = ProjectItem(
+        old_project_info = ProjectItem(
             name=project_name,
             path=project_service.projects.get(project_name, ""),
         )
@@ -61,7 +62,7 @@ async def update_project(
             message=f"Project '{project_name}' updated successfully",
             status="success",
             default=(project_name == project_service.default_project),
-            old_project=old_project,
+            old_project=old_project_info,
             new_project=ProjectItem(name=project_name, path=updated_path),
         )
     except ValueError as e:  # pragma: no cover

basic_memory/api/routers/prompt_router.py

@@ -5,12 +5,12 @@ It centralizes all prompt formatting logic that was previously in the MCP prompt
 """
 
 from datetime import datetime, timezone
-from dateparser import parse
 from fastapi import APIRouter, HTTPException, status
 from loguru import logger
 
 from basic_memory.api.routers.utils import to_graph_context, to_search_results
 from basic_memory.api.template_loader import template_loader
+from basic_memory.schemas.base import parse_timeframe
 from basic_memory.deps import (
     ContextServiceDep,
     EntityRepositoryDep,
@@ -51,7 +51,7 @@ async def continue_conversation(
         f"Generating continue conversation prompt, topic: {request.topic}, timeframe: {request.timeframe}"
     )
 
-    since = parse(request.timeframe) if request.timeframe else None
+    since = parse_timeframe(request.timeframe) if request.timeframe else None
 
     # Initialize search results
     search_results = []

basic_memory/cli/commands/project.py

@@ -174,7 +174,7 @@ def display_project_info(
     """Display detailed information and statistics about the current project."""
     try:
         # Get project info
-        info = asyncio.run(project_info())
+        info = asyncio.run(project_info.fn())  # type: ignore  # pyright: ignore [reportAttributeAccessIssue]
 
         if json_output:
             # Convert to JSON and print
@@ -221,7 +221,7 @@ def display_project_info(
                 console.print(entity_types_table)
 
             # Most connected entities
-            if info.statistics.most_connected_entities:
+            if info.statistics.most_connected_entities:  # pragma: no cover
                 connected_table = Table(title="🔗 Most Connected Entities")
                 connected_table.add_column("Title", style="blue")
                 connected_table.add_column("Permalink", style="cyan")
@@ -235,7 +235,7 @@ def display_project_info(
                 console.print(connected_table)
 
             # Recent activity
-            if info.activity.recently_updated:
+            if info.activity.recently_updated:  # pragma: no cover
                 recent_table = Table(title="🕒 Recent Activity")
                 recent_table.add_column("Title", style="blue")
                 recent_table.add_column("Type", style="cyan")

basic_memory/cli/commands/status.py

@@ -122,7 +122,7 @@ def display_changes(project_name: str, title: str, changes: SyncReport, verbose:
     console.print(Panel(tree, expand=False))
 
 
-async def run_status(verbose: bool = False):
+async def run_status(verbose: bool = False):  # pragma: no cover
     """Check sync status of files vs database."""
     # Check knowledge/ directory
 

basic_memory/cli/commands/sync.py

@@ -180,7 +180,7 @@ async def run_sync(verbose: bool = False):
     sync_service = await get_sync_service(project)
 
     logger.info("Running one-time sync")
-    knowledge_changes = await sync_service.sync(config.home)
+    knowledge_changes = await sync_service.sync(config.home, project_name=project.name)
 
     # Log results
     duration_ms = int((time.time() - start_time) * 1000)

basic_memory/cli/commands/tool.py

@@ -90,7 +90,7 @@ def write_note(
             typer.echo("Empty content provided. Please provide non-empty content.", err=True)
             raise typer.Exit(1)
 
-        note = asyncio.run(mcp_write_note(title, content, folder, tags))
+        note = asyncio.run(mcp_write_note.fn(title, content, folder, tags))
         rprint(note)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
@@ -103,7 +103,7 @@ def write_note(
 def read_note(identifier: str, page: int = 1, page_size: int = 10):
     """Read a markdown note from the knowledge base."""
     try:
-        note = asyncio.run(mcp_read_note(identifier, page, page_size))
+        note = asyncio.run(mcp_read_note.fn(identifier, page, page_size))
         rprint(note)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
@@ -124,7 +124,7 @@ def build_context(
     """Get context needed to continue a discussion."""
     try:
         context = asyncio.run(
-            mcp_build_context(
+            mcp_build_context.fn(
                 url=url,
                 depth=depth,
                 timeframe=timeframe,
@@ -157,7 +157,7 @@ def recent_activity(
     """Get recent activity across the knowledge base."""
     try:
         context = asyncio.run(
-            mcp_recent_activity(
+            mcp_recent_activity.fn(
                 type=type,  # pyright: ignore [reportArgumentType]
                 depth=depth,
                 timeframe=timeframe,
@@ -210,7 +210,7 @@ def search_notes(
         search_type = "text" if search_type is None else search_type
 
         results = asyncio.run(
-            mcp_search(
+            mcp_search.fn(
                 query,
                 search_type=search_type,
                 page=page,
@@ -241,7 +241,7 @@ def continue_conversation(
     """Prompt to continue a previous conversation or work session."""
     try:
         # Prompt functions return formatted strings directly
-        session = asyncio.run(mcp_continue_conversation(topic=topic, timeframe=timeframe))
+        session = asyncio.run(mcp_continue_conversation.fn(topic=topic, timeframe=timeframe))  # type: ignore
         rprint(session)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):

basic_memory/mcp/prompts/__init__.py

@@ -10,10 +10,12 @@ from basic_memory.mcp.prompts import continue_conversation
 from basic_memory.mcp.prompts import recent_activity
 from basic_memory.mcp.prompts import search
 from basic_memory.mcp.prompts import ai_assistant_guide
+from basic_memory.mcp.prompts import sync_status
 
 __all__ = [
     "ai_assistant_guide",
     "continue_conversation",
     "recent_activity",
     "search",
+    "sync_status",
 ]

basic_memory/mcp/prompts/recent_activity.py

@@ -38,7 +38,7 @@ async def recent_activity_prompt(
     """
     logger.info(f"Getting recent activity, timeframe: {timeframe}")
 
-    recent = await recent_activity(timeframe=timeframe, type=[SearchItemType.ENTITY])
+    recent = await recent_activity.fn(timeframe=timeframe, type=[SearchItemType.ENTITY])
 
     # Extract primary results from the hierarchical structure
     primary_results = []

basic_memory/mcp/prompts/sync_status.py

@@ -0,0 +1,116 @@
+"""Sync status prompt for Basic Memory MCP server."""
+
+from basic_memory.mcp.server import mcp
+
+
+@mcp.prompt(
+    description="""Get sync status with recommendations for AI assistants.
+    
+    This prompt provides both current sync status and guidance on how
+    AI assistants should respond when sync operations are in progress or completed.
+    """,
+)
+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
+    """
+    try:  # pragma: no cover
+        from basic_memory.services.migration_service import migration_manager
+
+        state = migration_manager.state
+
+        # Build status report
+        lines = [
+            "# Basic Memory Sync Status",
+            "",
+            f"**Current Status**: {state.status.value.replace('_', ' ').title()}",
+            f"**System Ready**: {'Yes' if migration_manager.is_ready else 'No'}",
+            "",
+        ]
+
+        if migration_manager.is_ready:
+            lines.extend(
+                [
+                    "✅ **All sync operations completed** - System is fully operational",
+                    "",
+                    "All Basic Memory tools are available and functioning normally.",
+                    "File indexing is complete and knowledge graphs are up to date.",
+                    "You can proceed with any knowledge management tasks.",
+                ]
+            )
+        else:
+            lines.append(f"**Status Message**: {state.message}")
+
+            if state.status.value == "in_progress":
+                if state.projects_total > 0:
+                    progress = f" ({state.projects_migrated}/{state.projects_total})"
+                    lines.append(f"**Progress**: {progress}")
+
+                lines.extend(
+                    [
+                        "",
+                        "🔄 **File synchronization in progress** - Processing files and building knowledge graphs",
+                        "",
+                        "**Impact**: Some tools may show status messages instead of normal responses",
+                        "until sync completes (usually 1-3 minutes).",
+                    ]
+                )
+
+            elif state.status.value == "failed":
+                lines.extend(
+                    [
+                        "",
+                        f"❌ **Sync failed**: {state.error or 'Unknown error'}",
+                        "",
+                        "**Impact**: System may have limited functionality until issue is resolved.",
+                    ]
+                )
+
+        # Add AI assistant recommendations
+        if not migration_manager.is_ready:
+            lines.extend(
+                [
+                    "",
+                    "---",
+                    "",
+                    "## AI Assistant Recommendations",
+                    "",
+                    "**When sync is in progress:**",
+                    "- Inform the user about the background file processing",
+                    "- Suggest using `sync_status()` tool to check progress",
+                    "- Explain that tools will work normally once sync completes",
+                    "- Avoid creating complex workflows until sync is done",
+                    "",
+                    "**What to tell users:**",
+                    "- 'Basic Memory is processing your files and building knowledge graphs'",
+                    "- 'This usually takes 1-3 minutes depending on your content size'",
+                    "- 'You can check progress anytime with the sync_status tool'",
+                    "- 'Full functionality will be available once processing completes'",
+                    "",
+                    "**User-friendly language:**",
+                    "- Say 'processing files' instead of 'migration' or 'sync'",
+                    "- Say 'building knowledge graphs' instead of 'indexing'",
+                    "- Say 'setting up your knowledge base' instead of 'running migrations'",
+                ]
+            )
+
+        return "\n".join(lines)
+
+    except Exception as e:  # pragma: no cover
+        return f"""# Sync Status - Error
+
+❌ **Unable to check sync status**: {str(e)}
+
+## AI Assistant Recommendations
+
+**When status is unavailable:**
+- Assume the system is likely working normally
+- Try proceeding with normal operations
+- If users report issues, suggest checking logs or restarting
+- Use user-friendly language about 'setting up the knowledge base'
+"""

basic_memory/mcp/server.py

@@ -31,23 +31,23 @@ load_dotenv()
 @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
     """Manage application lifecycle with type-safe context"""
-    # Initialize on startup
-    watch_task = await initialize_app(app_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=watch_task)
+        yield AppContext(watch_task=None, migration_manager=migration_manager)
     finally:
-        # Cleanup on shutdown
-        if watch_task:
-            watch_task.cancel()
+        # Cleanup on shutdown - migration tasks will be cancelled automatically
+        pass
 
 
 # OAuth configuration function

basic_memory/mcp/tools/__init__.py

@@ -11,12 +11,14 @@ from basic_memory.mcp.tools.read_content import read_content
 from basic_memory.mcp.tools.build_context import build_context
 from basic_memory.mcp.tools.recent_activity import recent_activity
 from basic_memory.mcp.tools.read_note import read_note
+from basic_memory.mcp.tools.view_note import view_note
 from basic_memory.mcp.tools.write_note import write_note
 from basic_memory.mcp.tools.search import search_notes
 from basic_memory.mcp.tools.canvas import canvas
 from basic_memory.mcp.tools.list_directory import list_directory
 from basic_memory.mcp.tools.edit_note import edit_note
 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_projects,
     switch_project,
@@ -43,5 +45,7 @@ __all__ = [
     "search_notes",
     "set_default_project",
     "switch_project",
+    "sync_status",
+    "view_note",
     "write_note",
 ]

basic_memory/mcp/tools/build_context.py

@@ -13,7 +13,6 @@ from basic_memory.schemas.memory import (
     GraphContext,
     MemoryUrl,
     memory_url_path,
-    normalize_memory_url,
 )
 
 
@@ -21,12 +20,17 @@ from basic_memory.schemas.memory import (
     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" 
+    - 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"
+    - "2 days ago", "last week", "today", "3 months ago"
+    - Or standard formats like "7d", "24h"
     """,
 )
 async def build_context(
@@ -76,7 +80,28 @@ async def build_context(
         build_context("memory://specs/search", project="work-project")
     """
     logger.info(f"Building context from {url}")
-    url = normalize_memory_url(url)
+    # URL is already validated and normalized by MemoryUrl type annotation
+
+    # 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)
+    if migration_status:  # pragma: no cover
+        # Return a proper GraphContext with status message
+        from basic_memory.schemas.memory import MemoryMetadata
+        from datetime import datetime
+
+        return GraphContext(
+            results=[],
+            metadata=MemoryMetadata(
+                depth=depth or 1,
+                timeframe=timeframe,
+                generated_at=datetime.now(),
+                primary_count=0,
+                related_count=0,
+                uri=migration_status,  # Include status in metadata
+            ),
+        )
 
     active_project = get_active_project(project)
     project_url = active_project.project_url

basic_memory/mcp/tools/canvas.py

@@ -35,7 +35,8 @@ async def canvas(
         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)
-        folder: The folder where the file should be saved
+        folder: Folder path relative to project root where the canvas should be saved.
+                Use forward slashes (/) as separators. Examples: "diagrams", "projects/2025", "visual/maps"
         project: Optional project name to create canvas in. If not provided, uses current active project.
 
     Returns: