basic-memory 0.4.2__tar.gz → 0.4.3__tar.gz

{basic_memory-0.4.2 → basic_memory-0.4.3}/CHANGELOG.md

@@ -1,6 +1,16 @@
 # CHANGELOG
 
 
+## v0.4.3 (2025-02-18)
+
+### Bug Fixes
+
+- Re do enhanced read note format ([#10](https://github.com/basicmachines-co/basic-memory/pull/10),
+  [`39bd5ca`](https://github.com/basicmachines-co/basic-memory/commit/39bd5ca08fd057220b95a8b5d82c5e73a1f5722b))
+
+Co-authored-by: phernandez <phernandez@basicmachines.co>
+
+
 ## v0.4.2 (2025-02-17)
 
 

{basic_memory-0.4.2 → basic_memory-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: basic-memory
-Version: 0.4.2
+Version: 0.4.3
 Summary: Local-first knowledge management combining Zettelkasten with knowledge graphs
 Project-URL: Homepage, https://github.com/basicmachines-co/basic-memory
 Project-URL: Repository, https://github.com/basicmachines-co/basic-memory

{basic_memory-0.4.2 → basic_memory-0.4.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "basic-memory"
-version = "0.4.2"
+version = "0.4.3"
 description = "Local-first knowledge management combining Zettelkasten with knowledge graphs"
 readme = "README.md"
 requires-python = ">=3.12.1"

{basic_memory-0.4.2 → basic_memory-0.4.3}/src/basic_memory/__init__.py

@@ -1,3 +1,3 @@
 """basic-memory - Local-first knowledge management combining Zettelkasten with knowledge graphs"""
 
-__version__ = "0.4.2"
+__version__ = "0.4.3"

basic_memory-0.4.3/src/basic_memory/api/routers/resource_router.py

@@ -0,0 +1,118 @@
+"""Routes for getting entity content."""
+
+import tempfile
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException, BackgroundTasks
+from fastapi.responses import FileResponse
+from loguru import logger
+
+from basic_memory.deps import (
+    ProjectConfigDep,
+    LinkResolverDep,
+    SearchServiceDep,
+    EntityServiceDep,
+    FileServiceDep,
+)
+from basic_memory.repository.search_repository import SearchIndexRow
+from basic_memory.schemas.memory import normalize_memory_url
+from basic_memory.schemas.search import SearchQuery, SearchItemType
+
+router = APIRouter(prefix="/resource", tags=["resources"])
+
+
+def get_entity_ids(item: SearchIndexRow) -> list[int]:
+    match item.type:
+        case SearchItemType.ENTITY:
+            return [item.id]
+        case SearchItemType.OBSERVATION:
+            return [item.entity_id]  # pyright: ignore [reportReturnType]
+        case SearchItemType.RELATION:
+            from_entity = item.from_id
+            to_entity = item.to_id  # pyright: ignore [reportReturnType]
+            return [from_entity, to_entity] if to_entity else [from_entity]  # pyright: ignore [reportReturnType]
+        case _:
+            raise ValueError(f"Unexpected type: {item.type}")
+
+
+@router.get("/{identifier:path}")
+async def get_resource_content(
+    config: ProjectConfigDep,
+    link_resolver: LinkResolverDep,
+    search_service: SearchServiceDep,
+    entity_service: EntityServiceDep,
+    file_service: FileServiceDep,
+    background_tasks: BackgroundTasks,
+    identifier: str,
+) -> FileResponse:
+    """Get resource content by identifier: name or permalink."""
+    logger.debug(f"Getting content for: {identifier}")
+
+    # Find single entity by permalink
+    entity = await link_resolver.resolve_link(identifier)
+    results = [entity] if entity else []
+
+    # search using the identifier as a permalink
+    if not results:
+        # if the identifier contains a wildcard, use GLOB search
+        query = (
+            SearchQuery(permalink_match=identifier)
+            if "*" in identifier
+            else SearchQuery(permalink=identifier)
+        )
+        search_results = await search_service.search(query)
+        if not search_results:
+            raise HTTPException(status_code=404, detail=f"Resource not found: {identifier}")
+
+        # get the entities related to the search results
+        entity_ids = [id for result in search_results for id in get_entity_ids(result)]
+        results = await entity_service.get_entities_by_id(entity_ids)
+
+    # return single response
+    if len(results) == 1:
+        entity = results[0]
+        file_path = Path(f"{config.home}/{entity.file_path}")
+        if not file_path.exists():
+            raise HTTPException(
+                status_code=404,
+                detail=f"File not found: {file_path}",
+            )
+        return FileResponse(path=file_path)
+
+    # for multiple files, initialize a temporary file for writing the results
+    with tempfile.NamedTemporaryFile(delete=False, mode="w", suffix=".md") as tmp_file:
+        temp_file_path = tmp_file.name
+
+        for result in results:
+            # Read content for each entity
+            content = await file_service.read_entity_content(result)
+            memory_url = normalize_memory_url(result.permalink)
+            modified_date = result.updated_at.isoformat()
+            assert result.checksum
+            checksum = result.checksum[:8]
+
+            # Prepare the delimited content
+            response_content = f"--- {memory_url} {modified_date} {checksum}\n"
+            response_content += f"\n{content}\n"
+            response_content += "\n"
+
+            # Write content directly to the temporary file in append mode
+            tmp_file.write(response_content)
+
+        # Ensure all content is written to disk
+        tmp_file.flush()
+
+    # Schedule the temporary file to be deleted after the response
+    background_tasks.add_task(cleanup_temp_file, temp_file_path)
+
+    # Return the file response
+    return FileResponse(path=temp_file_path)
+
+
+def cleanup_temp_file(file_path: str):
+    """Delete the temporary file."""
+    try:
+        Path(file_path).unlink()  # Deletes the file
+        logger.debug(f"Temporary file deleted: {file_path}")
+    except Exception as e:  # pragma: no cover
+        logger.error(f"Error deleting temporary file {file_path}: {e}")

{basic_memory-0.4.2 → basic_memory-0.4.3}/src/basic_memory/cli/commands/import_chatgpt.py

@@ -69,7 +69,11 @@ def traverse_messages(
 
 
 def format_chat_markdown(
-    title: str, mapping: Dict[str, Any], root_id: Optional[str], created_at: float, modified_at: float
+    title: str,
+    mapping: Dict[str, Any],
+    root_id: Optional[str],
+    created_at: float,
+    modified_at: float,
 ) -> str:
     """Format chat as clean markdown."""
 

{basic_memory-0.4.2 → basic_memory-0.4.3}/src/basic_memory/db.py

@@ -140,11 +140,15 @@ async def run_migrations(app_config: ProjectConfig, database_type=DatabaseType.F
 
         # Set required Alembic config options programmatically
         config.set_main_option("script_location", str(alembic_dir))
-        config.set_main_option("file_template",
-                               "%%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s")
+        config.set_main_option(
+            "file_template",
+            "%%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s",
+        )
         config.set_main_option("timezone", "UTC")
         config.set_main_option("revision_environment", "false")
-        config.set_main_option("sqlalchemy.url", DatabaseType.get_db_url(app_config.database_path, database_type))
+        config.set_main_option(
+            "sqlalchemy.url", DatabaseType.get_db_url(app_config.database_path, database_type)
+        )
 
         command.upgrade(config, "head")
         logger.info("Migrations completed successfully")
@@ -153,4 +157,4 @@ async def run_migrations(app_config: ProjectConfig, database_type=DatabaseType.F
         await SearchRepository(session_maker).init_search_index()
     except Exception as e:  # pragma: no cover
         logger.error(f"Error running migrations: {e}")
-        raise
+        raise

basic_memory-0.4.3/src/basic_memory/mcp/tools/notes.py

@@ -0,0 +1,190 @@
+"""Note management tools for Basic Memory MCP server.
+
+These tools provide a natural interface for working with markdown notes
+while leveraging the underlying knowledge graph structure.
+"""
+
+from typing import Optional, List
+
+from loguru import logger
+
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.async_client import client
+from basic_memory.schemas import EntityResponse, DeleteEntitiesResponse
+from basic_memory.schemas.base import Entity
+from basic_memory.mcp.tools.utils import call_get, call_put, call_delete
+from basic_memory.schemas.memory import memory_url_path
+
+
+@mcp.tool(
+    description="Create or update a markdown note. Returns the permalink for referencing.",
+)
+async def write_note(
+    title: str,
+    content: str,
+    folder: str,
+    tags: Optional[List[str]] = None,
+    verbose: bool = False,
+) -> EntityResponse | 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:
+
+    Observations format:
+        `- [category] Observation text #tag1 #tag2 (optional context)`
+
+        Examples:
+        `- [design] Files are the source of truth #architecture (All state comes from files)`
+        `- [tech] Using SQLite for storage #implementation`
+        `- [note] Need to add error handling #todo`
+
+    Relations format:
+        - Explicit: `- relation_type [[Entity]] (optional context)`
+        - Inline: Any `[[Entity]]` reference creates a relation
+
+        Examples:
+        `- depends_on [[Content Parser]] (Need for semantic extraction)`
+        `- implements [[Search Spec]] (Initial implementation)`
+        `- 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: the folder where the file should be saved
+        tags: Optional list of tags to categorize the note
+        verbose: If True, returns full EntityResponse with semantic info
+
+    Returns:
+        If verbose=False: Permalink that can be used to reference the note
+        If verbose=True: EntityResponse with full semantic details
+
+    Examples:
+        # Note with both explicit and inline relations
+        write_note(
+            title="Search Implementation",
+            content="# Search Component\\n\\n"
+                   "Implementation of the search feature, building on [[Core Search]].\\n\\n"
+                   "## Observations\\n"
+                   "- [tech] Using FTS5 for full-text search #implementation\\n"
+                   "- [design] Need pagination support #todo\\n\\n"
+                   "## Relations\\n"
+                   "- implements [[Search Spec]]\\n"
+                   "- depends_on [[Database Schema]]",
+            folder="docs/components"
+        )
+
+        # Note with tags
+        write_note(
+            title="Error Handling Design",
+            content="# Error Handling\\n\\n"
+                   "This design builds on [[Reliability Design]].\\n\\n"
+                   "## Approach\\n"
+                   "- [design] Use error codes #architecture\\n"
+                   "- [tech] Implement retry logic #implementation\\n\\n"
+                   "## Relations\\n"
+                   "- extends [[Base Error Handling]]",
+            folder="docs/design",
+            tags=["architecture", "reliability"]
+        )
+    """
+    logger.info(f"Writing note folder:'{folder}' title: '{title}'")
+
+    # Create the entity request
+    metadata = {"tags": [f"#{tag}" for tag in tags]} if tags else None
+    entity = Entity(
+        title=title,
+        folder=folder,
+        entity_type="note",
+        content_type="text/markdown",
+        content=content,
+        entity_metadata=metadata,
+    )
+
+    # Use existing knowledge tool
+    logger.info(f"Creating {entity.permalink}")
+    url = f"/knowledge/entities/{entity.permalink}"
+    response = await call_put(client, url, json=entity.model_dump())
+    result = EntityResponse.model_validate(response.json())
+    return result if verbose else result.permalink
+
+
+@mcp.tool(description="Read note content by title, permalink, relation, or pattern")
+async def read_note(identifier: str) -> str:
+    """Get note content in unified diff format.
+
+    The content is returned in a unified diff inspired format:
+    ```
+    --- memory://docs/example 2025-01-31T19:32:49 7d9f1c8b
+    <document content>
+    ```
+
+    Multiple documents (from relations or pattern matches) are separated by
+    additional headers.
+
+    Args:
+        identifier: Can be one of:
+            - Note title ("Project Planning")
+            - Note permalink ("docs/example")
+            - Relation path ("docs/example/depends-on/other-doc")
+            - Pattern match ("docs/*-architecture")
+
+    Returns:
+        Document content in unified diff format. For single documents, returns
+        just that document's content. For relations or pattern matches, returns
+        multiple documents separated by unified diff headers.
+
+    Examples:
+        # Single document
+        content = await read_note("Project Planning")
+
+        # Read by permalink
+        content = await read_note("docs/architecture/file-first")
+
+        # Follow relation
+        content = await read_note("docs/architecture/depends-on/docs/content-parser")
+
+        # Pattern matching
+        content = await read_note("docs/*-architecture")  # All architecture docs
+        content = await read_note("docs/*/implements/*")  # Find implementations
+
+    Output format:
+        ```
+        --- memory://docs/example 2025-01-31T19:32:49 7d9f1c8b
+        <first document content>
+
+        --- memory://docs/other 2025-01-30T15:45:22 a1b2c3d4
+        <second document content>
+        ```
+
+    The headers include:
+    - Full memory:// URI for the document
+    - Last modified timestamp
+    - Content checksum
+    """
+    logger.info(f"Reading note {identifier}")
+    url = memory_url_path(identifier)
+    response = await call_get(client, f"/resource/{url}")
+    return response.text
+
+
+@mcp.tool(description="Delete a note by title or permalink")
+async def delete_note(identifier: str) -> bool:
+    """Delete a note from the knowledge base.
+
+    Args:
+        identifier: Note title or permalink
+
+    Returns:
+        True if note was deleted, False otherwise
+
+    Examples:
+        # Delete by title
+        delete_note("Meeting Notes: Project Planning")
+
+        # Delete by permalink
+        delete_note("notes/project-planning")
+    """
+    response = await call_delete(client, f"/knowledge/entities/{identifier}")
+    result = DeleteEntitiesResponse.model_validate(response.json())
+    return result.deleted

{basic_memory-0.4.2 → basic_memory-0.4.3}/src/basic_memory/repository/search_repository.py

@@ -68,24 +68,40 @@ class SearchRepository:
 
     async def init_search_index(self):
         """Create or recreate the search index."""
-
         logger.info("Initializing search index")
-        async with db.scoped_session(self.session_maker) as session:
-            await session.execute(CREATE_SEARCH_INDEX)
-            await session.commit()
-
-    def _quote_search_term(self, term: str) -> str:
-        """Add quotes if term contains special characters.
-        For FTS5, special characters and phrases need to be quoted to be treated as a single token.
+        try:
+            async with db.scoped_session(self.session_maker) as session:
+                await session.execute(CREATE_SEARCH_INDEX)
+                await session.commit()
+        except Exception as e:  # pragma: no cover
+            logger.error(f"Error initializing search index: {e}")
+            raise e
+
+    def _prepare_search_term(self, term: str, is_prefix: bool = True) -> str:
+        """Prepare a search term for FTS5 query.
+
+        Args:
+            term: The search term to prepare
+            is_prefix: Whether to add prefix search capability (* suffix)
+
+        For FTS5:
+        - Special characters and phrases need to be quoted
+        - Terms with spaces or special chars need quotes
         """
-        # List of special characters that need quoting
-        special_chars = ["/", "*", "-", ".", " ", "(", ")", "[", "]", '"', "'"]
+        if "*" in term:
+            return term
+
+        # List of special characters that need quoting (excluding *)
+        special_chars = ["/", "-", ".", " ", "(", ")", "[", "]", '"', "'"]
 
         # Check if term contains any special characters
-        if any(c in term for c in special_chars):
-            # If the term already contains quotes, escape them
+        needs_quotes = any(c in term for c in special_chars)
+
+        if needs_quotes:
+            # If the term already contains quotes, escape them and add a wildcard
             term = term.replace('"', '""')
-            return f'"{term}"'
+            term = f'"{term}"*'
+
         return term
 
     async def search(
@@ -106,14 +122,14 @@ class SearchRepository:
 
         # Handle text search for title and content
         if search_text:
-            search_text = self._quote_search_term(search_text.lower().strip())
-            params["text"] = f"{search_text}*"
+            search_text = self._prepare_search_term(search_text.strip())
+            params["text"] = search_text
             conditions.append("(title MATCH :text OR content MATCH :text)")
 
         # Handle title match search
         if title:
-            title_text = self._quote_search_term(title.lower().strip())
-            params["text"] = f"{title_text}*"
+            title_text = self._prepare_search_term(title.strip())
+            params["text"] = title_text
             conditions.append("title MATCH :text")
 
         # Handle permalink exact search
@@ -123,8 +139,15 @@ class SearchRepository:
 
         # Handle permalink match search, supports *
         if permalink_match:
-            params["permalink"] = self._quote_search_term(permalink_match)
-            conditions.append("permalink MATCH :permalink")
+            # Clean and prepare permalink for FTS5 GLOB match
+            permalink_text = self._prepare_search_term(
+                permalink_match.lower().strip(), is_prefix=False
+            )
+            params["permalink"] = permalink_text
+            if "*" in permalink_match:
+                conditions.append("permalink GLOB :permalink")
+            else:
+                conditions.append("permalink MATCH :permalink")
 
         # Handle type filter
         if types:
@@ -173,7 +196,7 @@ class SearchRepository:
             LIMIT :limit
         """
 
-        # logger.debug(f"Search {sql} params: {params}")
+        logger.debug(f"Search {sql} params: {params}")
         async with db.scoped_session(self.session_maker) as session:
             result = await session.execute(text(sql), params)
             rows = result.fetchall()
@@ -199,8 +222,11 @@ class SearchRepository:
             for row in rows
         ]
 
-        # for r in results:
-        #    logger.debug(f"Search result: type:{r.type} title: {r.title} permalink: {r.permalink} score: {r.score}")
+        logger.debug(f"Found {len(results)} search results")
+        for r in results:
+            logger.debug(
+                f"Search result: type:{r.type} title: {r.title} permalink: {r.permalink} score: {r.score}"
+            )
 
         return results
 
@@ -233,7 +259,7 @@ class SearchRepository:
                 """),
                 search_index_row.to_insert(),
             )
-            logger.debug(f"indexed permalink {search_index_row.permalink}")
+            logger.debug(f"indexed row {search_index_row}")
             await session.commit()
 
     async def delete_by_permalink(self, permalink: str):

{basic_memory-0.4.2 → basic_memory-0.4.3}/src/basic_memory/schemas/response.py

@@ -11,6 +11,7 @@ Key Features:
 4. Bulk operations return all affected items
 """
 
+from datetime import datetime
 from typing import List, Optional, Dict
 
 from pydantic import BaseModel, ConfigDict, Field, AliasPath, AliasChoices
@@ -43,6 +44,8 @@ class ObservationResponse(Observation, SQLAlchemyModel):
     }
     """
 
+    permalink: Permalink
+
 
 class RelationResponse(Relation, SQLAlchemyModel):
     """Response schema for relation operations.
@@ -59,6 +62,8 @@ class RelationResponse(Relation, SQLAlchemyModel):
     }
     """
 
+    permalink: Permalink
+
     from_id: Permalink = Field(
         # use the permalink from the associated Entity
         # or the from_id value
@@ -131,9 +136,12 @@ class EntityResponse(SQLAlchemyModel):
     file_path: str
     entity_type: EntityType
     entity_metadata: Optional[Dict] = None
+    checksum: Optional[str] = None
     content_type: ContentType
     observations: List[ObservationResponse] = []
     relations: List[RelationResponse] = []
+    created_at: datetime
+    updated_at: datetime
 
 
 class EntityListResponse(SQLAlchemyModel):

{basic_memory-0.4.2 → basic_memory-0.4.3}/src/basic_memory/services/entity_service.py

@@ -185,6 +185,11 @@ class EntityService(BaseService[EntityModel]):
             raise EntityNotFoundError(f"Entity not found: {permalink}")
         return db_entity
 
+    async def get_entities_by_id(self, ids: List[int]) -> Sequence[EntityModel]:
+        """Get specific entities and their relationships."""
+        logger.debug(f"Getting entities: {ids}")
+        return await self.repository.find_by_ids(ids)
+
     async def get_entities_by_permalinks(self, permalinks: List[str]) -> Sequence[EntityModel]:
         """Get specific nodes and their relationships."""
         logger.debug(f"Getting entities permalinks: {permalinks}")

{basic_memory-0.4.2 → basic_memory-0.4.3}/src/basic_memory/services/link_resolver.py

@@ -16,9 +16,10 @@ class LinkResolver:
 
     Uses a combination of exact matching and search-based resolution:
     1. Try exact permalink match (fastest)
-    2. Try exact title match
-    3. Fall back to search for fuzzy matching
-    4. Generate new permalink if no match found
+    2. Try permalink pattern match (for wildcards)
+    3. Try exact title match
+    4. Fall back to search for fuzzy matching
+    5. Generate new permalink if no match found
     """
 
     def __init__(self, entity_repository: EntityRepository, search_service: SearchService):
@@ -45,8 +46,8 @@ class LinkResolver:
             logger.debug(f"Found title match: {entity.title}")
             return entity
 
-        if use_search:
-            # 3. Fall back to search for fuzzy matching on title if specified
+        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]),
             )
@@ -59,7 +60,7 @@ class LinkResolver:
                 )
                 return await self.entity_repository.get_by_permalink(best_match.permalink)
 
-            # if we couldn't find anything then return None
+        # if we couldn't find anything then return None
         return None
 
     def _normalize_link_text(self, link_text: str) -> Tuple[str, Optional[str]]:
@@ -87,7 +88,7 @@ class LinkResolver:
 
         return text, alias
 
-    def _select_best_match(self, search_text: str, results: List[SearchIndexRow]) -> Entity:
+    def _select_best_match(self, search_text: str, results: List[SearchIndexRow]) -> SearchIndexRow:
         """Select best match from search results.
 
         Uses multiple criteria:

{basic_memory-0.4.2 → basic_memory-0.4.3}/src/basic_memory/services/search_service.py

@@ -75,7 +75,7 @@ class SearchService:
             else None
         )
 
-        # permalink search
+        # search
         results = await self.repository.search(
             search_text=query.text,
             permalink=query.permalink,