basic-memory 0.12.2__py3-none-any.whl → 0.13.0__py3-none-any.whl

basic_memory/mcp/tools/write_note.py

@@ -1,12 +1,13 @@
 """Write note tool for Basic Memory MCP server."""
 
-from typing import List, Union
+from typing import List, Union, Optional
 
 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_put
+from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas import EntityResponse
 from basic_memory.schemas.base import Entity
 from basic_memory.utils import parse_tags
@@ -26,6 +27,7 @@ async def write_note(
     content: str,
     folder: str,
     tags=None,  # Remove type hint completely to avoid schema issues
+    project: Optional[str] = None,
 ) -> str:
     """Write a markdown note to the knowledge base.
 
@@ -52,9 +54,11 @@ async def write_note(
     Args:
         title: The title of the note
         content: Markdown content for the note, can include observations and relations
-        folder: the folder where the file should be saved
+        folder: Folder path relative to project root where the file should be saved.
+                Use forward slashes (/) as separators. Examples: "notes", "projects/2025", "research/ml"
         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")
+        project: Optional project name to write to. If not provided, uses current active project.
 
     Returns:
         A markdown formatted summary of the semantic content, including:
@@ -64,12 +68,19 @@ async def write_note(
         - Relation counts (resolved/unresolved)
         - Tags if present
     """
-    logger.info("MCP tool call", tool="write_note", folder=folder, title=title, tags=tags)
+    logger.info(f"MCP tool call tool=write_note folder={folder}, title={title}, tags={tags}")
+
+    # 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 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": [f"#{tag}" for tag in tag_list]} if tag_list else None
+    metadata = {"tags": tag_list} if tag_list else None
     entity = Entity(
         title=title,
         folder=folder,
@@ -78,10 +89,12 @@ async def write_note(
         content=content,
         entity_metadata=metadata,
     )
+    active_project = get_active_project(project)
+    project_url = active_project.project_url
 
     # Create or update via knowledge API
-    logger.debug("Creating entity via API", permalink=entity.permalink)
-    url = f"/knowledge/entities/{entity.permalink}"
+    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())
 
@@ -115,22 +128,16 @@ async def write_note(
         summary.append(f"- Resolved: {resolved}")
         if unresolved:
             summary.append(f"- Unresolved: {unresolved}")
-            summary.append("\nUnresolved relations will be retried on next sync.")
+            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(
-        "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,
+        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)

basic_memory/models/__init__.py

@@ -3,12 +3,13 @@
 import basic_memory
 from basic_memory.models.base import Base
 from basic_memory.models.knowledge import Entity, Observation, Relation
-
-SCHEMA_VERSION = basic_memory.__version__ + "-" + "003"
+from basic_memory.models.project import Project
 
 __all__ = [
     "Base",
     "Entity",
     "Observation",
     "Relation",
+    "Project",
+    "basic_memory",
 ]

basic_memory/models/knowledge.py

@@ -17,7 +17,6 @@ from sqlalchemy import (
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from basic_memory.models.base import Base
-
 from basic_memory.utils import generate_permalink
 
 
@@ -29,6 +28,7 @@ class Entity(Base):
     - Maps to a file on disk
     - Maintains a checksum for change detection
     - Tracks both source file and semantic properties
+    - Belongs to a specific project
     """
 
     __tablename__ = "entity"
@@ -38,13 +38,21 @@ class Entity(Base):
         Index("ix_entity_title", "title"),
         Index("ix_entity_created_at", "created_at"),  # For timeline queries
         Index("ix_entity_updated_at", "updated_at"),  # For timeline queries
-        # Unique index only for markdown files with non-null permalinks
+        Index("ix_entity_project_id", "project_id"),  # For project filtering
+        # Project-specific uniqueness constraints
         Index(
-            "uix_entity_permalink",
+            "uix_entity_permalink_project",
             "permalink",
+            "project_id",
             unique=True,
             sqlite_where=text("content_type = 'text/markdown' AND permalink IS NOT NULL"),
         ),
+        Index(
+            "uix_entity_file_path_project",
+            "file_path",
+            "project_id",
+            unique=True,
+        ),
     )
 
     # Core identity
@@ -54,10 +62,13 @@ class Entity(Base):
     entity_metadata: Mapped[Optional[dict]] = mapped_column(JSON, nullable=True)
     content_type: Mapped[str] = mapped_column(String)
 
+    # Project reference
+    project_id: Mapped[int] = mapped_column(Integer, ForeignKey("project.id"), nullable=False)
+
     # Normalized path for URIs - required for markdown files only
     permalink: Mapped[Optional[str]] = mapped_column(String, nullable=True, index=True)
     # Actual filesystem relative path
-    file_path: Mapped[str] = mapped_column(String, unique=True, index=True)
+    file_path: Mapped[str] = mapped_column(String, index=True)
     # checksum of file
     checksum: Mapped[Optional[str]] = mapped_column(String, nullable=True)
 
@@ -66,6 +77,7 @@ class Entity(Base):
     updated_at: Mapped[datetime] = mapped_column(DateTime)
 
     # Relationships
+    project = relationship("Project", back_populates="entities")
     observations = relationship(
         "Observation", back_populates="entity", cascade="all, delete-orphan"
     )

basic_memory/models/project.py

@@ -0,0 +1,78 @@
+"""Project model for Basic Memory."""
+
+from datetime import datetime
+from typing import Optional
+
+from sqlalchemy import (
+    Integer,
+    String,
+    Text,
+    Boolean,
+    DateTime,
+    Index,
+    event,
+)
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from basic_memory.models.base import Base
+from basic_memory.utils import generate_permalink
+
+
+class Project(Base):
+    """Project model for Basic Memory.
+
+    A project represents a collection of knowledge entities that are grouped together.
+    Projects are stored in the app-level database and provide context for all knowledge
+    operations.
+    """
+
+    __tablename__ = "project"
+    __table_args__ = (
+        # Regular indexes
+        Index("ix_project_name", "name", unique=True),
+        Index("ix_project_permalink", "permalink", unique=True),
+        Index("ix_project_path", "path"),
+        Index("ix_project_created_at", "created_at"),
+        Index("ix_project_updated_at", "updated_at"),
+    )
+
+    # Core identity
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    name: Mapped[str] = mapped_column(String, unique=True)
+    description: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
+
+    # URL-friendly identifier generated from name
+    permalink: Mapped[str] = mapped_column(String, unique=True)
+
+    # Filesystem path to project directory
+    path: Mapped[str] = mapped_column(String)
+
+    # Status flags
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
+    is_default: Mapped[Optional[bool]] = mapped_column(Boolean, default=None, nullable=True)
+
+    # Timestamps
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime, default=datetime.utcnow, onupdate=datetime.utcnow
+    )
+
+    # Define relationships to entities, observations, and relations
+    # These relationships will be established once we add project_id to those models
+    entities = relationship("Entity", back_populates="project", cascade="all, delete-orphan")
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"Project(id={self.id}, name='{self.name}', permalink='{self.permalink}', path='{self.path}')"
+
+
+@event.listens_for(Project, "before_insert")
+@event.listens_for(Project, "before_update")
+def set_project_permalink(mapper, connection, project):
+    """Generate URL-friendly permalink for the project if needed.
+
+    This event listener ensures the permalink is always derived from the name,
+    even if the name changes.
+    """
+    # If the name changed or permalink is empty, regenerate permalink
+    if not project.permalink or project.permalink != generate_permalink(project.name):
+        project.permalink = generate_permalink(project.name)

basic_memory/models/search.py

@@ -13,21 +13,24 @@ CREATE VIRTUAL TABLE IF NOT EXISTS search_index USING fts5(
     permalink,             -- Stable identifier (now indexed for path search)
     file_path UNINDEXED,   -- Physical location
     type UNINDEXED,        -- entity/relation/observation
-    
-    -- Relation fields 
+
+    -- Project context
+    project_id UNINDEXED,  -- Project identifier
+
+    -- Relation fields
     from_id UNINDEXED,     -- Source entity
     to_id UNINDEXED,       -- Target entity
     relation_type UNINDEXED, -- Type of relation
-    
+
     -- Observation fields
     entity_id UNINDEXED,   -- Parent entity
     category UNINDEXED,    -- Observation category
-    
+
     -- Common fields
     metadata UNINDEXED,    -- JSON metadata
     created_at UNINDEXED,  -- Creation timestamp
     updated_at UNINDEXED,  -- Last update
-    
+
     -- Configuration
     tokenize='unicode61 tokenchars 0x2F',  -- Hex code for /
     prefix='1,2,3,4'                    -- Support longer prefixes for paths

basic_memory/repository/__init__.py

@@ -1,9 +1,11 @@
 from .entity_repository import EntityRepository
 from .observation_repository import ObservationRepository
+from .project_repository import ProjectRepository
 from .relation_repository import RelationRepository
 
 __all__ = [
     "EntityRepository",
     "ObservationRepository",
+    "ProjectRepository",
     "RelationRepository",
 ]

basic_memory/repository/entity_repository.py

@@ -18,9 +18,14 @@ class EntityRepository(Repository[Entity]):
     to strings before passing to repository methods.
     """
 
-    def __init__(self, session_maker: async_sessionmaker[AsyncSession]):
-        """Initialize with session maker."""
-        super().__init__(session_maker, Entity)
+    def __init__(self, session_maker: async_sessionmaker[AsyncSession], project_id: int):
+        """Initialize with session maker and project_id filter.
+
+        Args:
+            session_maker: SQLAlchemy session maker
+            project_id: Project ID to filter all operations by
+        """
+        super().__init__(session_maker, Entity, project_id=project_id)
 
     async def get_by_permalink(self, permalink: str) -> Optional[Entity]:
         """Get entity by permalink.

basic_memory/repository/observation_repository.py

@@ -1,6 +1,6 @@
 """Repository for managing Observation objects."""
 
-from typing import Sequence
+from typing import Dict, List, Sequence
 
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import async_sessionmaker
@@ -12,8 +12,14 @@ from basic_memory.repository.repository import Repository
 class ObservationRepository(Repository[Observation]):
     """Repository for Observation model with memory-specific operations."""
 
-    def __init__(self, session_maker: async_sessionmaker):
-        super().__init__(session_maker, Observation)
+    def __init__(self, session_maker: async_sessionmaker, project_id: int):
+        """Initialize with session maker and project_id filter.
+
+        Args:
+            session_maker: SQLAlchemy session maker
+            project_id: Project ID to filter all operations by
+        """
+        super().__init__(session_maker, Observation, project_id=project_id)
 
     async def find_by_entity(self, entity_id: int) -> Sequence[Observation]:
         """Find all observations for a specific entity."""
@@ -38,3 +44,29 @@ class ObservationRepository(Repository[Observation]):
         query = select(Observation.category).distinct()
         result = await self.execute_query(query, use_query_options=False)
         return result.scalars().all()
+
+    async def find_by_entities(self, entity_ids: List[int]) -> Dict[int, List[Observation]]:
+        """Find all observations for multiple entities in a single query.
+
+        Args:
+            entity_ids: List of entity IDs to fetch observations for
+
+        Returns:
+            Dictionary mapping entity_id to list of observations
+        """
+        if not entity_ids:  # pragma: no cover
+            return {}
+
+        # Query observations for all entities in the list
+        query = select(Observation).filter(Observation.entity_id.in_(entity_ids))
+        result = await self.execute_query(query)
+        observations = result.scalars().all()
+
+        # Group observations by entity_id
+        observations_by_entity = {}
+        for obs in observations:
+            if obs.entity_id not in observations_by_entity:
+                observations_by_entity[obs.entity_id] = []
+            observations_by_entity[obs.entity_id].append(obs)
+
+        return observations_by_entity

basic_memory/repository/project_info_repository.py

@@ -1,9 +1,10 @@
 from basic_memory.repository.repository import Repository
+from basic_memory.models.project import Project
 
 
 class ProjectInfoRepository(Repository):
     """Repository for statistics queries."""
 
     def __init__(self, session_maker):
-        # Initialize with a dummy model since we're just using the execute_query method
-        super().__init__(session_maker, None)  # type: ignore
+        # Initialize with Project model as a reference
+        super().__init__(session_maker, Project)

basic_memory/repository/project_repository.py

@@ -0,0 +1,85 @@
+"""Repository for managing projects in Basic Memory."""
+
+from pathlib import Path
+from typing import Optional, Sequence, Union
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from basic_memory import db
+from basic_memory.models.project import Project
+from basic_memory.repository.repository import Repository
+
+
+class ProjectRepository(Repository[Project]):
+    """Repository for Project model.
+
+    Projects represent collections of knowledge entities grouped together.
+    Each entity, observation, and relation belongs to a specific project.
+    """
+
+    def __init__(self, session_maker: async_sessionmaker[AsyncSession]):
+        """Initialize with session maker."""
+        super().__init__(session_maker, Project)
+
+    async def get_by_name(self, name: str) -> Optional[Project]:
+        """Get project by name.
+
+        Args:
+            name: Unique name of the project
+        """
+        query = self.select().where(Project.name == name)
+        return await self.find_one(query)
+
+    async def get_by_permalink(self, permalink: str) -> Optional[Project]:
+        """Get project by permalink.
+
+        Args:
+            permalink: URL-friendly identifier for the project
+        """
+        query = self.select().where(Project.permalink == permalink)
+        return await self.find_one(query)
+
+    async def get_by_path(self, path: Union[Path, str]) -> Optional[Project]:
+        """Get project by filesystem path.
+
+        Args:
+            path: Path to the project directory (will be converted to string internally)
+        """
+        query = self.select().where(Project.path == str(path))
+        return await self.find_one(query)
+
+    async def get_default_project(self) -> Optional[Project]:
+        """Get the default project (the one marked as is_default=True)."""
+        query = self.select().where(Project.is_default.is_not(None))
+        return await self.find_one(query)
+
+    async def get_active_projects(self) -> Sequence[Project]:
+        """Get all active projects."""
+        query = self.select().where(Project.is_active == True)  # noqa: E712
+        result = await self.execute_query(query)
+        return list(result.scalars().all())
+
+    async def set_as_default(self, project_id: int) -> Optional[Project]:
+        """Set a project as the default and unset previous default.
+
+        Args:
+            project_id: ID of the project to set as default
+
+        Returns:
+            The updated project if found, None otherwise
+        """
+        async with db.scoped_session(self.session_maker) as session:
+            # First, clear the default flag for all projects using direct SQL
+            await session.execute(
+                text("UPDATE project SET is_default = NULL WHERE is_default IS NOT NULL")
+            )
+            await session.flush()
+
+            # Set the new default project
+            target_project = await self.select_by_id(session, project_id)
+            if target_project:
+                target_project.is_default = True
+                await session.flush()
+                return target_project
+            return None  # pragma: no cover

basic_memory/repository/relation_repository.py

@@ -16,8 +16,14 @@ from basic_memory.repository.repository import Repository
 class RelationRepository(Repository[Relation]):
     """Repository for Relation model with memory-specific operations."""
 
-    def __init__(self, session_maker: async_sessionmaker):
-        super().__init__(session_maker, Relation)
+    def __init__(self, session_maker: async_sessionmaker, project_id: int):
+        """Initialize with session maker and project_id filter.
+
+        Args:
+            session_maker: SQLAlchemy session maker
+            project_id: Project ID to filter all operations by
+        """
+        super().__init__(session_maker, Relation, project_id=project_id)
 
     async def find_relation(
         self, from_permalink: str, to_permalink: str, relation_type: str