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

basic_memory/mcp/tools/write_note.py

@@ -4,11 +4,12 @@ from typing import List, Union, Optional
 
 from loguru import logger
 
-from basic_memory.mcp.async_client import client
+from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.project_context import get_active_project, add_project_metadata
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_put
-from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas import EntityResponse
+from fastmcp import Context
 from basic_memory.schemas.base import Entity
 from basic_memory.utils import parse_tags, validate_project_path
 
@@ -26,14 +27,20 @@ async def write_note(
     title: str,
     content: str,
     folder: str,
-    tags=None,  # Remove type hint completely to avoid schema issues
-    entity_type: str = "note",
     project: Optional[str] = None,
+    tags=None,
+    entity_type: str = "note",
+    context: Context | None = None,
 ) -> str:
     """Write a markdown note to the knowledge base.
 
-    The content can include semantic observations and relations using markdown syntax.
-    Relations can be specified either explicitly or through inline wiki-style links:
+    Creates or updates a markdown note with semantic observations and relations.
+
+    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.
+
+    The content can include semantic observations and relations using markdown syntax:
 
     Observations format:
         `- [category] Observation text #tag1 #tag2 (optional context)`
@@ -50,108 +57,162 @@ async def write_note(
         Examples:
         `- depends_on [[Content Parser]] (Need for semantic extraction)`
         `- implements [[Search Spec]] (Initial implementation)`
-        `- This feature extends [[Base Design]] andst uses [[Core Utils]]`
+        `- This feature extends [[Base Design]] and uses [[Core Utils]]`
 
     Args:
         title: The title of the note
         content: Markdown content for the note, can include observations and relations
         folder: Folder path relative to project root where the file should be saved.
-                Use forward slashes (/) as separators. Examples: "notes", "projects/2025", "research/ml"
+                Use forward slashes (/) as separators. Use "/" or "" to write to project root.
+                Examples: "notes", "projects/2025", "research/ml", "/" (root)
+        project: Project name to write to. Optional - server will resolve using the
+                hierarchy above. If unknown, use list_memory_projects() to discover
+                available projects.
         tags: Tags to categorize the note. Can be a list of strings, a comma-separated string, or None.
               Note: If passing from external MCP clients, use a string format (e.g. "tag1,tag2,tag3")
         entity_type: Type of entity to create. Defaults to "note". Can be "guide", "report", "config", etc.
-        project: Optional project name to write to. If not provided, uses current active project.
+        context: Optional FastMCP context for performance caching.
 
     Returns:
         A markdown formatted summary of the semantic content, including:
-        - Creation/update status
+        - Creation/update status with project name
         - File path and checksum
         - Observation counts by category
         - Relation counts (resolved/unresolved)
         - Tags if present
-    """
-    logger.info(f"MCP tool call tool=write_note folder={folder}, title={title}, tags={tags}")
+        - Session tracking metadata for project awareness
+
+    Examples:
+        # Assistant flow when project is unknown
+        # 1. list_memory_projects() -> Ask user which project
+        # 2. User: "Use my-research"
+        # 3. write_note(...) and remember "my-research" for session
+
+        # Create a simple note
+        write_note(
+            project="my-research",
+            title="Meeting Notes",
+            folder="meetings",
+            content="# Weekly Standup\\n\\n- [decision] Use SQLite for storage #tech"
+        )
+
+        # Create a note with tags and entity type
+        write_note(
+            project="work-project",
+            title="API Design",
+            folder="specs",
+            content="# REST API Specification\\n\\n- implements [[Authentication]]",
+            tags=["api", "design"],
+            entity_type="guide"
+        )
 
-    # Get the active project first to check project-specific sync status
-    active_project = get_active_project(project)
+        # Update existing note (same title/folder)
+        write_note(
+            project="my-research",
+            title="Meeting Notes",
+            folder="meetings",
+            content="# Weekly Standup\\n\\n- [decision] Use PostgreSQL instead #tech"
+        )
 
-    # Validate folder path to prevent path traversal attacks
-    project_path = active_project.home
-    if folder and not validate_project_path(folder, project_path):
-        logger.warning(
-            "Attempted path traversal attack blocked", folder=folder, project=active_project.name
+    Raises:
+        HTTPError: If project doesn't exist or is inaccessible
+        SecurityError: If folder path attempts path traversal
+    """
+    async with get_client() as client:
+        logger.info(
+            f"MCP tool call tool=write_note project={project} folder={folder}, title={title}, tags={tags}"
         )
-        return f"# Error\n\nFolder path '{folder}' is not allowed - paths must stay within project boundaries"
-
-    # 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, 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 creating notes."
-
-    # Process tags using the helper function
-    tag_list = parse_tags(tags)
-    # Create the entity request
-    metadata = {"tags": tag_list} if tag_list else None
-    entity = Entity(
-        title=title,
-        folder=folder,
-        entity_type=entity_type,
-        content_type="text/markdown",
-        content=content,
-        entity_metadata=metadata,
-    )
-    project_url = active_project.project_url
-
-    # Create or update via knowledge API
-    logger.debug(f"Creating entity via API permalink={entity.permalink}")
-    url = f"{project_url}/knowledge/entities/{entity.permalink}"
-    response = await call_put(client, url, json=entity.model_dump())
-    result = EntityResponse.model_validate(response.json())
-
-    # Format semantic summary based on status code
-    action = "Created" if response.status_code == 201 else "Updated"
-    summary = [
-        f"# {action} note",
-        f"file_path: {result.file_path}",
-        f"permalink: {result.permalink}",
-        f"checksum: {result.checksum[:8] if result.checksum else 'unknown'}",
-    ]
-
-    # Count observations by category
-    categories = {}
-    if result.observations:
-        for obs in result.observations:
-            categories[obs.category] = categories.get(obs.category, 0) + 1
-
-        summary.append("\n## Observations")
-        for category, count in sorted(categories.items()):
-            summary.append(f"- {category}: {count}")
-
-    # Count resolved/unresolved relations
-    unresolved = 0
-    resolved = 0
-    if result.relations:
-        unresolved = sum(1 for r in result.relations if not r.to_id)
-        resolved = len(result.relations) - unresolved
-
-        summary.append("\n## Relations")
-        summary.append(f"- Resolved: {resolved}")
-        if unresolved:
-            summary.append(f"- Unresolved: {unresolved}")
-            summary.append("\nNote: Unresolved relations point to entities that don't exist yet.")
-            summary.append(
-                "They will be automatically resolved when target entities are created or during sync operations."
+
+        # Get and validate the project (supports optional project parameter)
+        active_project = await get_active_project(client, project, context)
+
+        # Normalize "/" to empty string for root folder (must happen before validation)
+        if folder == "/":
+            folder = ""
+
+        # Validate folder path to prevent path traversal attacks
+        project_path = active_project.home
+        if folder and not validate_project_path(folder, project_path):
+            logger.warning(
+                "Attempted path traversal attack blocked",
+                folder=folder,
+                project=active_project.name,
             )
+            return f"# Error\n\nFolder path '{folder}' is not allowed - paths must stay within project boundaries"
 
-    if tag_list:
-        summary.append(f"\n## Tags\n- {', '.join(tag_list)}")
+        # Check migration status and wait briefly if needed
+        from basic_memory.mcp.tools.utils import wait_for_migration_or_return_status
 
-    # Log the response with structured data
-    logger.info(
-        f"MCP tool response: tool=write_note action={action} permalink={result.permalink} observations_count={len(result.observations)} relations_count={len(result.relations)} resolved_relations={resolved} unresolved_relations={unresolved} status_code={response.status_code}"
-    )
-    return "\n".join(summary)
+        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 creating notes."
+
+        # Process tags using the helper function
+        tag_list = parse_tags(tags)
+        # Create the entity request
+        metadata = {"tags": tag_list} if tag_list else None
+        entity = Entity(
+            title=title,
+            folder=folder,
+            entity_type=entity_type,
+            content_type="text/markdown",
+            content=content,
+            entity_metadata=metadata,
+        )
+        project_url = active_project.permalink
+
+        # Create or update via knowledge API
+        logger.debug(f"Creating entity via API permalink={entity.permalink}")
+        url = f"{project_url}/knowledge/entities/{entity.permalink}"
+        response = await call_put(client, url, json=entity.model_dump())
+        result = EntityResponse.model_validate(response.json())
+
+        # Format semantic summary based on status code
+        action = "Created" if response.status_code == 201 else "Updated"
+        summary = [
+            f"# {action} note",
+            f"project: {active_project.name}",
+            f"file_path: {result.file_path}",
+            f"permalink: {result.permalink}",
+            f"checksum: {result.checksum[:8] if result.checksum else 'unknown'}",
+        ]
+
+        # Count observations by category
+        categories = {}
+        if result.observations:
+            for obs in result.observations:
+                categories[obs.category] = categories.get(obs.category, 0) + 1
+
+            summary.append("\n## Observations")
+            for category, count in sorted(categories.items()):
+                summary.append(f"- {category}: {count}")
+
+        # Count resolved/unresolved relations
+        unresolved = 0
+        resolved = 0
+        if result.relations:
+            unresolved = sum(1 for r in result.relations if not r.to_id)
+            resolved = len(result.relations) - unresolved
+
+            summary.append("\n## Relations")
+            summary.append(f"- Resolved: {resolved}")
+            if unresolved:
+                summary.append(f"- Unresolved: {unresolved}")
+                summary.append(
+                    "\nNote: Unresolved relations point to entities that don't exist yet."
+                )
+                summary.append(
+                    "They will be automatically resolved when target entities are created or during sync operations."
+                )
+
+        if tag_list:
+            summary.append(f"\n## Tags\n- {', '.join(tag_list)}")
+
+        # Log the response with structured data
+        logger.info(
+            f"MCP tool response: tool=write_note project={active_project.name} action={action} permalink={result.permalink} observations_count={len(result.observations)} relations_count={len(result.relations)} resolved_relations={resolved} unresolved_relations={unresolved} status_code={response.status_code}"
+        )
+        result = "\n".join(summary)
+        return add_project_metadata(result, active_project.name)

basic_memory/models/knowledge.py

@@ -74,8 +74,14 @@ class Entity(Base):
     checksum: Mapped[Optional[str]] = mapped_column(String, nullable=True)
 
     # Metadata and tracking
-    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now().astimezone())
-    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now().astimezone(), onupdate=lambda: datetime.now().astimezone())
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now().astimezone()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now().astimezone(),
+        onupdate=lambda: datetime.now().astimezone(),
+    )
 
     # Relationships
     project = relationship("Project", back_populates="entities")
@@ -104,15 +110,15 @@ class Entity(Base):
     def is_markdown(self):
         """Check if the entity is a markdown file."""
         return self.content_type == "text/markdown"
-    
+
     def __getattribute__(self, name):
         """Override attribute access to ensure datetime fields are timezone-aware."""
         value = super().__getattribute__(name)
-        
+
         # Ensure datetime fields are timezone-aware
-        if name in ('created_at', 'updated_at') and isinstance(value, datetime):
+        if name in ("created_at", "updated_at") and isinstance(value, datetime):
             return ensure_timezone_aware(value)
-        
+
         return value
 
     def __repr__(self) -> str:

basic_memory/models/project.py

@@ -52,9 +52,13 @@ class Project(Base):
     is_default: Mapped[Optional[bool]] = mapped_column(Boolean, default=None, nullable=True)
 
     # Timestamps
-    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(UTC))
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(UTC)
+    )
     updated_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(UTC), onupdate=lambda: datetime.now(UTC)
+        DateTime(timezone=True),
+        default=lambda: datetime.now(UTC),
+        onupdate=lambda: datetime.now(UTC),
     )
 
     # Define relationships to entities, observations, and relations

basic_memory/repository/entity_repository.py

@@ -101,11 +101,10 @@ class EntityRepository(Repository[Entity]):
         return list(result.scalars().all())
 
     async def upsert_entity(self, entity: Entity) -> Entity:
-        """Insert or update entity using a hybrid approach.
+        """Insert or update entity using simple try/catch with database-level conflict resolution.
 
-        This method provides a cleaner alternative to the try/catch approach
-        for handling permalink and file_path conflicts. It first tries direct
-        insertion, then handles conflicts intelligently.
+        Handles file_path race conditions by checking for existing entity on IntegrityError.
+        For permalink conflicts, generates a unique permalink with numeric suffix.
 
         Args:
             entity: The entity to insert or update
@@ -113,50 +112,12 @@ class EntityRepository(Repository[Entity]):
         Returns:
             The inserted or updated entity
         """
-
         async with db.scoped_session(self.session_maker) as session:
             # Set project_id if applicable and not already set
             self._set_project_id_if_needed(entity)
 
-            # Check for existing entity with same file_path first
-            existing_by_path = await session.execute(
-                select(Entity).where(
-                    Entity.file_path == entity.file_path, Entity.project_id == entity.project_id
-                )
-            )
-            existing_path_entity = existing_by_path.scalar_one_or_none()
-
-            if existing_path_entity:
-                # Update existing entity with same file path
-                for key, value in {
-                    "title": entity.title,
-                    "entity_type": entity.entity_type,
-                    "entity_metadata": entity.entity_metadata,
-                    "content_type": entity.content_type,
-                    "permalink": entity.permalink,
-                    "checksum": entity.checksum,
-                    "updated_at": entity.updated_at,
-                }.items():
-                    setattr(existing_path_entity, key, value)
-
-                await session.flush()
-                # Return with relationships loaded
-                query = (
-                    self.select()
-                    .where(Entity.file_path == entity.file_path)
-                    .options(*self.get_load_options())
-                )
-                result = await session.execute(query)
-                found = result.scalar_one_or_none()
-                if not found:  # pragma: no cover
-                    raise RuntimeError(
-                        f"Failed to retrieve entity after update: {entity.file_path}"
-                    )
-                return found
-
-            # No existing entity with same file_path, try insert
+            # Try simple insert first
             try:
-                # Simple insert for new entity
                 session.add(entity)
                 await session.flush()
 
@@ -175,20 +136,20 @@ class EntityRepository(Repository[Entity]):
                 return found
 
             except IntegrityError:
-                # Could be either file_path or permalink conflict
                 await session.rollback()
 
-                # Check if it's a file_path conflict (race condition)
-                existing_by_path_check = await session.execute(
-                    select(Entity).where(
+                # Re-query after rollback to get a fresh, attached entity
+                existing_result = await session.execute(
+                    select(Entity)
+                    .where(
                         Entity.file_path == entity.file_path, Entity.project_id == entity.project_id
                     )
+                    .options(*self.get_load_options())
                 )
-                race_condition_entity = existing_by_path_check.scalar_one_or_none()
+                existing_entity = existing_result.scalar_one_or_none()
 
-                if race_condition_entity:
-                    # Race condition: file_path conflict detected after our initial check
-                    # Update the existing entity instead
+                if existing_entity:
+                    # File path conflict - update the existing entity
                     for key, value in {
                         "title": entity.title,
                         "entity_type": entity.entity_type,
@@ -198,25 +159,82 @@ class EntityRepository(Repository[Entity]):
                         "checksum": entity.checksum,
                         "updated_at": entity.updated_at,
                     }.items():
-                        setattr(race_condition_entity, key, value)
-
-                    await session.flush()
-                    # Return the updated entity with relationships loaded
-                    query = (
-                        self.select()
-                        .where(Entity.file_path == entity.file_path)
-                        .options(*self.get_load_options())
-                    )
-                    result = await session.execute(query)
-                    found = result.scalar_one_or_none()
-                    if not found:  # pragma: no cover
-                        raise RuntimeError(
-                            f"Failed to retrieve entity after race condition update: {entity.file_path}"
-                        )
-                    return found
+                        setattr(existing_entity, key, value)
+
+                    # Clear and re-add observations
+                    existing_entity.observations.clear()
+                    for obs in entity.observations:
+                        obs.entity_id = existing_entity.id
+                        existing_entity.observations.append(obs)
+
+                    await session.commit()
+                    return existing_entity
+
                 else:
-                    # Must be permalink conflict - generate unique permalink
-                    return await self._handle_permalink_conflict(entity, session)
+                    # No file_path conflict - must be permalink conflict
+                    # Generate unique permalink and retry
+                    entity = await self._handle_permalink_conflict(entity, session)
+                    return entity
+
+    async def get_distinct_directories(self) -> List[str]:
+        """Extract unique directory paths from file_path column.
+
+        Optimized method for getting directory structure without loading full entities
+        or relationships. Returns a sorted list of unique directory paths.
+
+        Returns:
+            List of unique directory paths (e.g., ["notes", "notes/meetings", "specs"])
+        """
+        # Query only file_path column, no entity objects or relationships
+        query = select(Entity.file_path).distinct()
+        query = self._add_project_filter(query)
+
+        # Execute with use_query_options=False to skip eager loading
+        result = await self.execute_query(query, use_query_options=False)
+        file_paths = [row for row in result.scalars().all()]
+
+        # Parse file paths to extract unique directories
+        directories = set()
+        for file_path in file_paths:
+            parts = [p for p in file_path.split("/") if p]
+            # Add all parent directories (exclude filename which is the last part)
+            for i in range(len(parts) - 1):
+                dir_path = "/".join(parts[: i + 1])
+                directories.add(dir_path)
+
+        return sorted(directories)
+
+    async def find_by_directory_prefix(self, directory_prefix: str) -> Sequence[Entity]:
+        """Find entities whose file_path starts with the given directory prefix.
+
+        Optimized method for listing directory contents without loading all entities.
+        Uses SQL LIKE pattern matching to filter entities by directory path.
+
+        Args:
+            directory_prefix: Directory path prefix (e.g., "docs", "docs/guides")
+                             Empty string returns all entities (root directory)
+
+        Returns:
+            Sequence of entities in the specified directory and subdirectories
+        """
+        # Build SQL LIKE pattern
+        if directory_prefix == "" or directory_prefix == "/":
+            # Root directory - return all entities
+            return await self.find_all()
+
+        # Remove leading/trailing slashes for consistency
+        directory_prefix = directory_prefix.strip("/")
+
+        # Query entities with file_path starting with prefix
+        # Pattern matches "prefix/" to ensure we get files IN the directory,
+        # not just files whose names start with the prefix
+        pattern = f"{directory_prefix}/%"
+
+        query = self.select().where(Entity.file_path.like(pattern))
+
+        # Skip eager loading - we only need basic entity fields for directory trees
+        result = await self.execute_query(query, use_query_options=False)
+        return list(result.scalars().all())
 
     async def _handle_permalink_conflict(self, entity: Entity, session: AsyncSession) -> Entity:
         """Handle permalink conflicts by generating a unique permalink."""
@@ -237,18 +255,7 @@ class EntityRepository(Repository[Entity]):
                 break
             suffix += 1
 
-        # Insert with unique permalink (no conflict possible now)
+        # Insert with unique permalink
         session.add(entity)
         await session.flush()
-
-        # Return the inserted entity with relationships loaded
-        query = (
-            self.select()
-            .where(Entity.file_path == entity.file_path)
-            .options(*self.get_load_options())
-        )
-        result = await session.execute(query)
-        found = result.scalar_one_or_none()
-        if not found:  # pragma: no cover
-            raise RuntimeError(f"Failed to retrieve entity after insert: {entity.file_path}")
-        return found
+        return entity

basic_memory/repository/relation_repository.py

@@ -73,5 +73,18 @@ class RelationRepository(Repository[Relation]):
         result = await self.execute_query(query)
         return result.scalars().all()
 
+    async def find_unresolved_relations_for_entity(self, entity_id: int) -> Sequence[Relation]:
+        """Find unresolved relations for a specific entity.
+
+        Args:
+            entity_id: The entity whose unresolved outgoing relations to find.
+
+        Returns:
+            List of unresolved relations where this entity is the source.
+        """
+        query = select(Relation).filter(Relation.from_id == entity_id, Relation.to_id.is_(None))
+        result = await self.execute_query(query)
+        return result.scalars().all()
+
     def get_load_options(self) -> List[LoaderOption]:
         return [selectinload(Relation.from_entity), selectinload(Relation.to_entity)]

basic_memory/repository/repository.py

@@ -10,13 +10,13 @@ from sqlalchemy import (
     Executable,
     inspect,
     Result,
-    Column,
     and_,
     delete,
 )
 from sqlalchemy.exc import NoResultFound
 from sqlalchemy.ext.asyncio import async_sessionmaker, AsyncSession
 from sqlalchemy.orm.interfaces import LoaderOption
+from sqlalchemy.sql.elements import ColumnElement
 
 from basic_memory import db
 from basic_memory.models import Base
@@ -38,7 +38,7 @@ class Repository[T: Base]:
         if Model:
             self.Model = Model
             self.mapper = inspect(self.Model).mapper
-            self.primary_key: Column[Any] = self.mapper.primary_key[0]
+            self.primary_key: ColumnElement[Any] = self.mapper.primary_key[0]
             self.valid_columns = [column.key for column in self.mapper.columns]
             # Check if this model has a project_id column
             self.has_project_id = "project_id" in self.valid_columns
@@ -152,12 +152,25 @@ class Repository[T: Base]:
         # Add project filter if applicable
         return self._add_project_filter(query)
 
-    async def find_all(self, skip: int = 0, limit: Optional[int] = None) -> Sequence[T]:
-        """Fetch records from the database with pagination."""
+    async def find_all(
+        self, skip: int = 0, limit: Optional[int] = None, use_load_options: bool = True
+    ) -> Sequence[T]:
+        """Fetch records from the database with pagination.
+
+        Args:
+            skip: Number of records to skip
+            limit: Maximum number of records to return
+            use_load_options: Whether to apply eager loading options (default: True)
+        """
         logger.debug(f"Finding all {self.Model.__name__} (skip={skip}, limit={limit})")
 
         async with db.scoped_session(self.session_maker) as session:
-            query = select(self.Model).offset(skip).options(*self.get_load_options())
+            query = select(self.Model).offset(skip)
+
+            # Only apply load options if requested
+            if use_load_options:
+                query = query.options(*self.get_load_options())
+
             # Add project filter if applicable
             query = self._add_project_filter(query)