basic-memory 0.10.1__py3-none-any.whl → 0.12.0__py3-none-any.whl

basic_memory/mcp/server.py

@@ -4,8 +4,8 @@ from mcp.server.fastmcp import FastMCP
 from mcp.server.fastmcp.utilities.logging import configure_logging
 
 # mcp console logging
-configure_logging(level="INFO")
+configure_logging(level="ERROR")
 
 
 # Create the shared server instance
-mcp = FastMCP("Basic Memory")
+mcp = FastMCP("Basic Memory", log_level="ERROR")

basic_memory/mcp/tools/__init__.py

@@ -12,7 +12,7 @@ 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.write_note import write_note
-from basic_memory.mcp.tools.search import search
+from basic_memory.mcp.tools.search import search_notes
 from basic_memory.mcp.tools.canvas import canvas
 
 __all__ = [
@@ -22,6 +22,6 @@ __all__ = [
     "read_content",
     "read_note",
     "recent_activity",
-    "search",
+    "search_notes",
     "write_note",
 ]

basic_memory/mcp/tools/read_note.py

@@ -6,10 +6,9 @@ from loguru import logger
 
 from basic_memory.mcp.async_client import client
 from basic_memory.mcp.server import mcp
-from basic_memory.mcp.tools.search import search
+from basic_memory.mcp.tools.search import search_notes
 from basic_memory.mcp.tools.utils import call_get
 from basic_memory.schemas.memory import memory_url_path
-from basic_memory.schemas.search import SearchQuery
 
 
 @mcp.tool(
@@ -63,7 +62,7 @@ async def read_note(identifier: str, page: int = 1, page_size: int = 10) -> str:
 
     # Fallback 1: Try title search via API
     logger.info(f"Search title for: {identifier}")
-    title_results = await search(SearchQuery(title=identifier))
+    title_results = await search_notes(query=identifier, search_type="title")
 
     if title_results and title_results.results:
         result = title_results.results[0]  # Get the first/best match
@@ -87,7 +86,7 @@ async def read_note(identifier: str, page: int = 1, page_size: int = 10) -> str:
 
     # Fallback 2: Text search as a last resort
     logger.info(f"Title search failed, trying text search for: {identifier}")
-    text_results = await search(SearchQuery(text=identifier))
+    text_results = await search_notes(query=identifier, search_type="text")
 
     # We didn't find a direct match, construct a helpful error message
     if not text_results or not text_results.results:

basic_memory/mcp/tools/search.py

@@ -1,17 +1,27 @@
 """Search tools for Basic Memory MCP server."""
 
+from typing import List, 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_post
-from basic_memory.schemas.search import SearchQuery, SearchResponse
-from basic_memory.mcp.async_client import client
+from basic_memory.schemas.search import SearchItemType, SearchQuery, SearchResponse
 
 
 @mcp.tool(
     description="Search across all content in the knowledge base.",
 )
-async def search(query: SearchQuery, page: int = 1, page_size: int = 10) -> SearchResponse:
+async def search_notes(
+    query: str,
+    page: int = 1,
+    page_size: int = 10,
+    search_type: str = "text",
+    types: Optional[List[str]] = None,
+    entity_types: Optional[List[str]] = None,
+    after_date: Optional[str] = None,
+) -> SearchResponse:
     """Search across all content in the knowledge base.
 
     This tool searches the knowledge base using full-text search, pattern matching,
@@ -19,59 +29,85 @@ async def search(query: SearchQuery, page: int = 1, page_size: int = 10) -> Sear
     and date.
 
     Args:
-        query: SearchQuery object with search parameters including:
-            - text: Full-text search (e.g., "project planning")
-              Supports boolean operators: AND, OR, NOT and parentheses for grouping
-            - title: Search only in titles (e.g., "Meeting notes")
-            - permalink: Exact permalink match (e.g., "docs/meeting-notes")
-            - permalink_match: Pattern matching for permalinks (e.g., "docs/*-notes")
-            - types: Optional list of content types to search (e.g., ["entity", "observation"])
-            - entity_types: Optional list of entity types to filter by (e.g., ["note", "person"])
-            - after_date: Optional date filter for recent content (e.g., "1 week", "2d")
+        query: The search query string
         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")
 
     Returns:
         SearchResponse with results and pagination info
 
     Examples:
         # Basic text search
-        results = await search(SearchQuery(text="project planning"))
+        results = await search_notes("project planning")
 
         # Boolean AND search (both terms must be present)
-        results = await search(SearchQuery(text="project AND planning"))
+        results = await search_notes("project AND planning")
 
         # Boolean OR search (either term can be present)
-        results = await search(SearchQuery(text="project OR meeting"))
+        results = await search_notes("project OR meeting")
 
         # Boolean NOT search (exclude terms)
-        results = await search(SearchQuery(text="project NOT meeting"))
+        results = await search_notes("project NOT meeting")
 
         # Boolean search with grouping
-        results = await search(SearchQuery(text="(project OR planning) AND notes"))
+        results = await search_notes("(project OR planning) AND notes")
 
         # Search with type filter
-        results = await search(SearchQuery(
-            text="meeting notes",
+        results = await search_notes(
+            query="meeting notes",
+            types=["entity"],
+        )
+
+        # Search with entity type filter, e.g., note vs
+        results = await search_notes(
+            query="meeting notes",
             types=["entity"],
-        ))
+        )
 
         # Search for recent content
-        results = await search(SearchQuery(
-            text="bug report",
+        results = await search_notes(
+            query="bug report",
             after_date="1 week"
-        ))
+        )
 
         # Pattern matching on permalinks
-        results = await search(SearchQuery(
-            permalink_match="docs/meeting-*"
-        ))
+        results = await search_notes(
+            query="docs/meeting-*",
+            search_type="permalink"
+        )
     """
-    logger.info(f"Searching for {query}")
+    # Create a SearchQuery object based on the parameters
+    search_query = SearchQuery()
+
+    # Set the appropriate search field based on search_type
+    if search_type == "text":
+        search_query.text = query
+    elif search_type == "title":
+        search_query.title = query
+    elif search_type == "permalink" and "*" in query:
+        search_query.permalink_match = query
+    elif search_type == "permalink":
+        search_query.permalink = query
+    else:
+        search_query.text = query  # Default to text search
+
+    # Add optional filters if provided
+    if entity_types:
+        search_query.entity_types = [SearchItemType(t) for t in entity_types]
+    if types:
+        search_query.types = types
+    if after_date:
+        search_query.after_date = after_date
+
+    logger.info(f"Searching for {search_query}")
     response = await call_post(
         client,
         "/search/",
-        json=query.model_dump(),
+        json=search_query.model_dump(),
         params={"page": page, "page_size": page_size},
     )
     return SearchResponse.model_validate(response.json())

basic_memory/mcp/tools/write_note.py

@@ -88,8 +88,10 @@ async def write_note(
     # Format semantic summary based on status code
     action = "Created" if response.status_code == 201 else "Updated"
     summary = [
-        f"# {action} {result.file_path} ({result.checksum[:8] if result.checksum else 'unknown'})",
+        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

basic_memory/repository/search_repository.py

@@ -4,10 +4,10 @@ import json
 import time
 from dataclasses import dataclass
 from datetime import datetime
-from typing import List, Optional, Any, Dict
+from typing import Any, Dict, List, Optional
 
 from loguru import logger
-from sqlalchemy import text, Executable, Result
+from sqlalchemy import Executable, Result, text
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 
 from basic_memory import db
@@ -123,9 +123,9 @@ class SearchRepository:
         permalink: Optional[str] = None,
         permalink_match: Optional[str] = None,
         title: Optional[str] = None,
-        types: Optional[List[SearchItemType]] = None,
+        types: Optional[List[str]] = None,
         after_date: Optional[datetime] = None,
-        entity_types: Optional[List[str]] = None,
+        entity_types: Optional[List[SearchItemType]] = None,
         limit: int = 10,
         offset: int = 0,
     ) -> List[SearchIndexRow]:
@@ -174,15 +174,15 @@ class SearchRepository:
             else:
                 conditions.append("permalink MATCH :permalink")
 
-        # Handle type filter
-        if types:
-            type_list = ", ".join(f"'{t.value}'" for t in types)
-            conditions.append(f"type IN ({type_list})")
-
         # Handle entity type filter
         if entity_types:
-            entity_type_list = ", ".join(f"'{t}'" for t in entity_types)
-            conditions.append(f"json_extract(metadata, '$.entity_type') IN ({entity_type_list})")
+            type_list = ", ".join(f"'{t.value}'" for t in entity_types)
+            conditions.append(f"type IN ({type_list})")
+
+        # Handle type filter
+        if types:
+            type_list = ", ".join(f"'{t}'" for t in types)
+            conditions.append(f"json_extract(metadata, '$.entity_type') IN ({type_list})")
 
         # Handle date filter using datetime() for proper comparison
         if after_date:

basic_memory/schemas/search.py

@@ -49,8 +49,8 @@ class SearchQuery(BaseModel):
     title: Optional[str] = None  # title only search
 
     # Optional filters
-    types: Optional[List[SearchItemType]] = None  # Filter by item type
-    entity_types: Optional[List[str]] = None  # Filter by entity type
+    types: Optional[List[str]] = None  # Filter by type
+    entity_types: Optional[List[SearchItemType]] = None  # Filter by entity type
     after_date: Optional[Union[datetime, str]] = None  # Time-based filter
 
     @field_validator("after_date")

basic_memory/services/context_service.py

@@ -81,7 +81,7 @@ class ContextService:
         else:
             logger.debug(f"Build context for '{types}'")
             primary = await self.search_repository.search(
-                types=types, after_date=since, limit=limit, offset=offset
+                entity_types=types, after_date=since, limit=limit, offset=offset
             )
 
         # Get type_id pairs for traversal

basic_memory/services/entity_service.py

@@ -1,24 +1,24 @@
 """Service for managing entities in the database."""
 
 from pathlib import Path
-from typing import Sequence, List, Optional, Tuple, Union
+from typing import List, Optional, Sequence, Tuple, Union
 
 import frontmatter
 from loguru import logger
 from sqlalchemy.exc import IntegrityError
 
 from basic_memory.markdown import EntityMarkdown
+from basic_memory.markdown.entity_parser import EntityParser
 from basic_memory.markdown.utils import entity_model_from_markdown, schema_to_markdown
-from basic_memory.models import Entity as EntityModel, Observation, Relation
+from basic_memory.models import Entity as EntityModel
+from basic_memory.models import Observation, Relation
 from basic_memory.repository import ObservationRepository, RelationRepository
 from basic_memory.repository.entity_repository import EntityRepository
 from basic_memory.schemas import Entity as EntitySchema
 from basic_memory.schemas.base import Permalink
-from basic_memory.services.exceptions import EntityNotFoundError, EntityCreationError
-from basic_memory.services import FileService
-from basic_memory.services import BaseService
+from basic_memory.services import BaseService, FileService
+from basic_memory.services.exceptions import EntityCreationError, EntityNotFoundError
 from basic_memory.services.link_resolver import LinkResolver
-from basic_memory.markdown.entity_parser import EntityParser
 from basic_memory.utils import generate_permalink
 
 
@@ -89,7 +89,7 @@ class EntityService(BaseService[EntityModel]):
         logger.debug(f"Creating or updating entity: {schema}")
 
         # Try to find existing entity using smart resolution
-        existing = await self.link_resolver.resolve_link(schema.permalink)
+        existing = await self.link_resolver.resolve_link(schema.permalink or schema.file_path)
 
         if existing:
             logger.debug(f"Found existing entity: {existing.permalink}")
@@ -100,7 +100,7 @@ class EntityService(BaseService[EntityModel]):
 
     async def create_entity(self, schema: EntitySchema) -> EntityModel:
         """Create a new entity and write to filesystem."""
-        logger.debug(f"Creating entity: {schema.permalink}")
+        logger.debug(f"Creating entity: {schema.title}")
 
         # Get file path and ensure it's a Path object
         file_path = Path(schema.file_path)
@@ -230,7 +230,7 @@ class EntityService(BaseService[EntityModel]):
         Creates the entity with null checksum to indicate sync not complete.
         Relations will be added in second pass.
         """
-        logger.debug(f"Creating entity: {markdown.frontmatter.title}")
+        logger.debug(f"Creating entity: {markdown.frontmatter.title} file_path: {file_path}")
         model = entity_model_from_markdown(file_path, markdown)
 
         # Mark as incomplete because we still need to add relations
@@ -315,7 +315,7 @@ class EntityService(BaseService[EntityModel]):
             except IntegrityError:
                 # Unique constraint violation - relation already exists
                 logger.debug(
-                    f"Skipping duplicate relation {rel.type} from {db_entity.permalink} target: {rel.target}, type: {rel.type}"
+                    f"Skipping duplicate relation {rel.type} from {db_entity.permalink} target: {rel.target}"
                 )
                 continue
 

basic_memory/services/link_resolver.py

@@ -46,10 +46,17 @@ class LinkResolver:
             logger.debug(f"Found title match: {entity.title}")
             return entity
 
+        # 3. Try file path
+        found_path = await self.entity_repository.get_by_file_path(clean_text)
+        if found_path:
+            logger.debug(f"Found entity with path: {found_path.file_path}")
+            return found_path
+
+        # search if indicated
         if use_search and "*" not in clean_text:
             # 3. Fall back to search for fuzzy matching on title
             results = await self.search_service.search(
-                query=SearchQuery(title=clean_text, types=[SearchItemType.ENTITY]),
+                query=SearchQuery(title=clean_text, entity_types=[SearchItemType.ENTITY]),
             )
 
             if results:

basic_memory/services/search_service.py

@@ -181,17 +181,6 @@ class SearchService:
         Each type gets its own row in the search index with appropriate metadata.
         """
 
-        if entity.permalink is None:  # pragma: no cover
-            logger.error(
-                "Missing permalink for markdown entity",
-                entity_id=entity.id,
-                title=entity.title,
-                file_path=entity.file_path,
-            )
-            raise ValueError(
-                f"Entity permalink should not be None for markdown entity: {entity.id} ({entity.title})"
-            )
-
         content_stems = []
         content_snippet = ""
         title_variants = self._generate_variants(entity.title)
@@ -202,22 +191,13 @@ class SearchService:
             content_stems.append(content)
             content_snippet = f"{content[:250]}"
 
-        content_stems.extend(self._generate_variants(entity.permalink))
+        if entity.permalink:
+            content_stems.extend(self._generate_variants(entity.permalink))
+
         content_stems.extend(self._generate_variants(entity.file_path))
 
         entity_content_stems = "\n".join(p for p in content_stems if p and p.strip())
 
-        if entity.permalink is None:  # pragma: no cover
-            logger.error(
-                "Missing permalink for markdown entity",
-                entity_id=entity.id,
-                title=entity.title,
-                file_path=entity.file_path,
-            )
-            raise ValueError(
-                f"Entity permalink should not be None for markdown entity: {entity.id} ({entity.title})"
-            )
-
         # Index entity
         await self.repository.index_item(
             SearchIndexRow(

basic_memory/sync/sync_service.py

@@ -11,6 +11,8 @@ from typing import Dict, Optional, Set, Tuple
 from loguru import logger
 from sqlalchemy.exc import IntegrityError
 
+from basic_memory.config import ProjectConfig
+from basic_memory.file_utils import has_frontmatter
 from basic_memory.markdown import EntityParser
 from basic_memory.models import Entity
 from basic_memory.repository import EntityRepository, RelationRepository
@@ -65,6 +67,7 @@ class SyncService:
 
     def __init__(
         self,
+        config: ProjectConfig,
         entity_service: EntityService,
         entity_parser: EntityParser,
         entity_repository: EntityRepository,
@@ -72,6 +75,7 @@ class SyncService:
         search_service: SearchService,
         file_service: FileService,
     ):
+        self.config = config
         self.entity_service = entity_service
         self.entity_parser = entity_parser
         self.entity_repository = entity_repository
@@ -327,43 +331,52 @@ class SyncService:
         """
         # Parse markdown first to get any existing permalink
         logger.debug("Parsing markdown file", path=path)
-        entity_markdown = await self.entity_parser.parse_file(path)
 
-        # Resolve permalink - this handles all the cases including conflicts
-        permalink = await self.entity_service.resolve_permalink(path, markdown=entity_markdown)
+        file_path = self.entity_parser.base_path / path
+        file_content = file_path.read_text()
+        file_contains_frontmatter = has_frontmatter(file_content)
 
-        # If permalink changed, update the file
-        if permalink != entity_markdown.frontmatter.permalink:
-            logger.info(
-                "Updating permalink",
-                path=path,
-                old_permalink=entity_markdown.frontmatter.permalink,
-                new_permalink=permalink,
-            )
+        # entity markdown will always contain front matter, so it can be used up create/update the entity
+        entity_markdown = await self.entity_parser.parse_file(path)
 
-            entity_markdown.frontmatter.metadata["permalink"] = permalink
-            checksum = await self.file_service.update_frontmatter(path, {"permalink": permalink})
-        else:
-            checksum = await self.file_service.compute_checksum(path)
+        # if the file contains frontmatter, resolve a permalink
+        if file_contains_frontmatter:
+            # Resolve permalink - this handles all the cases including conflicts
+            permalink = await self.entity_service.resolve_permalink(path, markdown=entity_markdown)
+
+            # If permalink changed, update the file
+            if permalink != entity_markdown.frontmatter.permalink:
+                logger.info(
+                    "Updating permalink",
+                    path=path,
+                    old_permalink=entity_markdown.frontmatter.permalink,
+                    new_permalink=permalink,
+                )
+
+                entity_markdown.frontmatter.metadata["permalink"] = permalink
+                await self.file_service.update_frontmatter(path, {"permalink": permalink})
 
         # if the file is new, create an entity
         if new:
             # Create entity with final permalink
-            logger.debug("Creating new entity from markdown", path=path, permalink=permalink)
-
+            logger.debug("Creating new entity from markdown", path=path)
             await self.entity_service.create_entity_from_markdown(Path(path), entity_markdown)
 
         # otherwise we need to update the entity and observations
         else:
-            logger.debug("Updating entity from markdown", path=path, permalink=permalink)
-
+            logger.debug("Updating entity from markdown", path=path)
             await self.entity_service.update_entity_and_observations(Path(path), entity_markdown)
 
         # Update relations and search index
         entity = await self.entity_service.update_entity_relations(path, entity_markdown)
 
+        # After updating relations, we need to compute the checksum again
+        # This is necessary for files with wikilinks to ensure consistent checksums
+        # after relation processing is complete
+        final_checksum = await self.file_service.compute_checksum(path)
+
         # set checksum
-        await self.entity_repository.update(entity.id, {"checksum": checksum})
+        await self.entity_repository.update(entity.id, {"checksum": final_checksum})
 
         logger.debug(
             "Markdown sync completed",
@@ -371,9 +384,11 @@ class SyncService:
             entity_id=entity.id,
             observation_count=len(entity.observations),
             relation_count=len(entity.relations),
+            checksum=final_checksum,
         )
 
-        return entity, checksum
+        # Return the final checksum to ensure everything is consistent
+        return entity, final_checksum
 
     async def sync_regular_file(self, path: str, new: bool = True) -> Tuple[Optional[Entity], str]:
         """Sync a non-markdown file with basic tracking.
@@ -468,8 +483,30 @@ class SyncService:
 
         entity = await self.entity_repository.get_by_file_path(old_path)
         if entity:
-            # Update file_path but keep the same permalink for link stability
-            updated = await self.entity_repository.update(entity.id, {"file_path": new_path})
+            # Update file_path in all cases
+            updates = {"file_path": new_path}
+
+            # If configured, also update permalink to match new path
+            if self.config.update_permalinks_on_move:
+                # generate new permalink value
+                new_permalink = await self.entity_service.resolve_permalink(new_path)
+
+                # write to file and get new checksum
+                new_checksum = await self.file_service.update_frontmatter(
+                    new_path, {"permalink": new_permalink}
+                )
+
+                updates["permalink"] = new_permalink
+                updates["checksum"] = new_checksum
+
+                logger.info(
+                    "Updating permalink on move",
+                    old_permalink=entity.permalink,
+                    new_permalink=new_permalink,
+                    new_checksum=new_checksum,
+                )
+
+            updated = await self.entity_repository.update(entity.id, updates)
 
             if updated is None:  # pragma: no cover
                 logger.error(

basic_memory/utils.py

@@ -138,15 +138,23 @@ def parse_tags(tags: Union[List[str], str, None]) -> List[str]:
 
     Returns:
         A list of tag strings, or an empty list if no tags
+
+    Note:
+        This function strips leading '#' characters from tags to prevent
+        their accumulation when tags are processed multiple times.
     """
     if tags is None:
         return []
 
+    # Process list of tags
     if isinstance(tags, list):
-        return tags
+        # First strip whitespace, then strip leading '#' characters to prevent accumulation
+        return [tag.strip().lstrip("#") for tag in tags if tag and tag.strip()]
 
+    # Process comma-separated string of tags
     if isinstance(tags, str):
-        return [tag.strip() for tag in tags.split(",") if tag.strip()]
+        # Split by comma, strip whitespace, then strip leading '#' characters
+        return [tag.strip().lstrip("#") for tag in tags.split(",") if tag and tag.strip()]
 
     # For any other type, try to convert to string and parse
     try:  # pragma: no cover