basic-memory 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

basic_memory/markdown/schemas.py

@@ -13,7 +13,7 @@ class Observation(BaseModel):
     content: str
     tags: Optional[List[str]] = None
     context: Optional[str] = None
-    
+
     def __str__(self) -> str:
         obs_string = f"- [{self.category}] {self.content}"
         if self.context:
@@ -27,7 +27,7 @@ class Relation(BaseModel):
     type: str
     target: str
     context: Optional[str] = None
-    
+
     def __str__(self) -> str:
         rel_string = f"- {self.type} [[{self.target}]]"
         if self.context:
@@ -38,24 +38,23 @@ class Relation(BaseModel):
 class EntityFrontmatter(BaseModel):
     """Required frontmatter fields for an entity."""
 
-    metadata: Optional[dict] = None
+    metadata: dict = {}
 
     @property
     def tags(self) -> List[str]:
-        return self.metadata.get("tags") if self.metadata else []
+        return self.metadata.get("tags") if self.metadata else []  # pyright: ignore
 
     @property
     def title(self) -> str:
-        return self.metadata.get("title") if self.metadata else None
+        return self.metadata.get("title") if self.metadata else None  # pyright: ignore
 
     @property
     def type(self) -> str:
-        return self.metadata.get("type", "note") if self.metadata else "note"
+        return self.metadata.get("type", "note") if self.metadata else "note"  # pyright: ignore
 
     @property
     def permalink(self) -> str:
-        return self.metadata.get("permalink") if self.metadata else None
-
+        return self.metadata.get("permalink") if self.metadata else None  # pyright: ignore
 
 
 class EntityMarkdown(BaseModel):

basic_memory/markdown/utils.py

@@ -1,144 +1,93 @@
+"""Utilities for converting between markdown and entity models."""
+
 from pathlib import Path
-from typing import Optional
+from typing import Optional, Any
 
 from frontmatter import Post
 
-from basic_memory.markdown import EntityMarkdown, EntityFrontmatter, Observation, Relation
-from basic_memory.markdown.entity_parser import parse
-from basic_memory.models import Entity, ObservationCategory, Observation as ObservationModel
+from basic_memory.markdown import EntityMarkdown
+from basic_memory.models import Entity, Observation as ObservationModel
 from basic_memory.utils import generate_permalink
 
 
-def entity_model_to_markdown(entity: Entity, content: Optional[str] = None) -> EntityMarkdown:
+def entity_model_from_markdown(
+    file_path: Path, markdown: EntityMarkdown, entity: Optional[Entity] = None
+) -> Entity:
     """
-    Converts an entity model to its Markdown representation, including metadata,
-    observations, relations, and content. Ensures that observations and relations
-    from the provided content are synchronized with the entity model. Removes
-    duplicate or unmatched observations and relations from the content to maintain
-    consistency.
-
-    :param entity: An instance of the Entity class containing metadata, observations,
-        relations, and other properties of the entity.
-    :type entity: Entity
-    :param content: Optional raw Markdown-formatted content to be parsed for semantic
-        information like observations or relations.
-    :type content: Optional[str]
-    :return: An instance of the EntityMarkdown class containing the entity's
-        frontmatter, observations, relations, and sanitized content formatted
-        in Markdown.
-    :rtype: EntityMarkdown
+    Convert markdown entity to model. Does not include relations.
+
+    Args:
+        file_path: Path to the markdown file
+        markdown: Parsed markdown entity
+        entity: Optional existing entity to update
+
+    Returns:
+        Entity model populated from markdown
+
+    Raises:
+        ValueError: If required datetime fields are missing from markdown
     """
-    metadata = entity.entity_metadata or {}
-    metadata["type"] = entity.entity_type or "note"
-    metadata["title"] = entity.title
-    metadata["permalink"] = entity.permalink
-
-    # convert model to markdown
-    entity_observations = [
-        Observation(
-            category=obs.category,
+
+    if not markdown.created or not markdown.modified:  # pragma: no cover
+        raise ValueError("Both created and modified dates are required in markdown")
+
+    # Generate permalink if not provided
+    permalink = markdown.frontmatter.permalink or generate_permalink(file_path)
+
+    # Create or update entity
+    model = entity or Entity()
+
+    # Update basic fields
+    model.title = markdown.frontmatter.title
+    model.entity_type = markdown.frontmatter.type
+    model.permalink = permalink
+    model.file_path = str(file_path)
+    model.content_type = "text/markdown"
+    model.created_at = markdown.created
+    model.updated_at = markdown.modified
+
+    # Handle metadata - ensure all values are strings and filter None
+    metadata = markdown.frontmatter.metadata or {}
+    model.entity_metadata = {k: str(v) for k, v in metadata.items() if v is not None}
+
+    # Convert observations
+    model.observations = [
+        ObservationModel(
             content=obs.content,
-            tags=obs.tags if obs.tags else None,
+            category=obs.category,
             context=obs.context,
+            tags=obs.tags,
         )
-        for obs in entity.observations
+        for obs in markdown.observations
     ]
 
-    entity_relations = [
-        Relation(
-            type=r.relation_type,
-            target=r.to_entity.title if r.to_entity else r.to_name,
-            context=r.context,
-        )
-        for r in entity.outgoing_relations
-    ]
-
-    observations = entity_observations
-    relations = entity_relations
-
-    # parse the content to see if it has semantic info (observations/relations)
-    entity_content = parse(content) if content else None
-
-    if entity_content:
-        # remove if they are already in the content
-        observations = [o for o in entity_observations if o not in entity_content.observations]
-        relations = [r for r in entity_relations if r not in entity_content.relations]
-
-        # remove from the content if not present in the db entity
-        for o in entity_content.observations:
-            if o not in entity_observations:
-                content = content.replace(str(o), "")
-
-        for r in entity_content.relations:
-            if r not in entity_relations:
-                content = content.replace(str(r), "")
-
-    return EntityMarkdown(
-        frontmatter=EntityFrontmatter(metadata=metadata),
-        content=content,
-        observations=observations,
-        relations=relations,
-        created = entity.created_at,
-        modified = entity.updated_at,
-    )
+    return model
 
 
-def entity_model_from_markdown(file_path: Path, markdown: EntityMarkdown, entity: Optional[Entity] = None) -> Entity:
+async def schema_to_markdown(schema: Any) -> Post:
     """
-    Convert markdown entity to model.
-    Does not include relations.
+    Convert schema to markdown Post object.
 
     Args:
-        markdown: Parsed markdown entity
-        include_relations: Whether to include relations. Set False for first sync pass.
-    """
+        schema: Schema to convert (must have title, entity_type, and permalink attributes)
 
-    # Validate/default category
-    def get_valid_category(obs):
-        if not obs.category or obs.category not in [c.value for c in ObservationCategory]:
-            return ObservationCategory.NOTE.value
-        return obs.category
-
-    permalink = markdown.frontmatter.permalink or generate_permalink(file_path)
-    model = entity or Entity()
-    
-    model.title=markdown.frontmatter.title
-    model.entity_type=markdown.frontmatter.type
-    model.permalink=permalink
-    model.file_path=str(file_path)
-    model.content_type="text/markdown"
-    model.created_at=markdown.created
-    model.updated_at=markdown.modified
-    model.entity_metadata={k:str(v) for k,v in markdown.frontmatter.metadata.items()}
-    model.observations=[
-            ObservationModel(
-                content=obs.content,
-                category=get_valid_category(obs),
-                context=obs.context,
-                tags=obs.tags,
-            )
-            for obs in markdown.observations
-        ]
-    
-    return model
-
-async def schema_to_markdown(schema):
-    """
-    Convert schema to markdown.
-    :param schema: the schema to convert 
-    :return: Post 
+    Returns:
+        Post object with frontmatter metadata
     """
-    # Create Post object
+    # Extract content and metadata
     content = schema.content or ""
-    frontmatter_metadata = schema.entity_metadata or {}
-    
-    # remove from map so we can define ordering in frontmatter
-    if "type" in frontmatter_metadata:
-        del frontmatter_metadata["type"]
-    if "title" in frontmatter_metadata:
-        del frontmatter_metadata["title"]
-    if "permalink" in frontmatter_metadata:
-        del frontmatter_metadata["permalink"]
-        
-    post = Post(content, title=schema.title, type=schema.entity_type, permalink=schema.permalink, **frontmatter_metadata)
+    frontmatter_metadata = dict(schema.entity_metadata or {})
+
+    # Remove special fields for ordered frontmatter
+    for field in ["type", "title", "permalink"]:
+        frontmatter_metadata.pop(field, None)
+
+    # Create Post with ordered fields
+    post = Post(
+        content,
+        title=schema.title,
+        type=schema.entity_type,
+        permalink=schema.permalink,
+        **frontmatter_metadata,
+    )
     return post

basic_memory/mcp/__init__.py

@@ -1 +1 @@
-"""MCP server for basic-memory."""
+"""MCP server for basic-memory."""

basic_memory/mcp/async_client.py

@@ -6,5 +6,3 @@ BASE_URL = "http://test"
 
 # Create shared async client
 client = AsyncClient(transport=ASGITransport(app=fastapi_app), base_url=BASE_URL)
-
-

basic_memory/mcp/server.py

@@ -1,39 +1,15 @@
 """Enhanced FastMCP server instance for Basic Memory."""
-import sys
 
-from loguru import logger
 from mcp.server.fastmcp import FastMCP
-from mcp.server.fastmcp.utilities.logging import configure_logging
 
-from basic_memory.config import config
+from basic_memory.utils import setup_logging
 
 # mcp console logging
-configure_logging(level="INFO")
+# configure_logging(level='INFO')
 
 
-def setup_logging(home_dir: str = config.home, log_file: str = ".basic-memory/basic-memory.log"):
-    """Configure file logging to the basic-memory home directory."""
-    log = f"{home_dir}/{log_file}"
-
-    # Add file handler with rotation
-    logger.add(
-        log,
-        rotation="100 MB",
-        retention="10 days",
-        backtrace=True,
-        diagnose=True,
-        enqueue=True,
-        colorize=False,
-    )
-
-    # Add stderr handler
-    logger.add(
-        sys.stderr,
-        colorize=True,
-    )
-
 # start our out file logging
-setup_logging()
+setup_logging(log_file=".basic-memory/basic-memory.log")
 
 # Create the shared server instance
 mcp = FastMCP("Basic Memory")

basic_memory/mcp/tools/__init__.py

@@ -7,8 +7,10 @@ all tools with the MCP server.
 
 # Import tools to register them with MCP
 from basic_memory.mcp.tools.memory import build_context, recent_activity
-#from basic_memory.mcp.tools.ai_edit import ai_edit
+
+# from basic_memory.mcp.tools.ai_edit import ai_edit
 from basic_memory.mcp.tools.notes import read_note, write_note
+from basic_memory.mcp.tools.search import search
 
 from basic_memory.mcp.tools.knowledge import (
     delete_entities,
@@ -26,9 +28,9 @@ __all__ = [
     # memory tools
     "build_context",
     "recent_activity",
-    #notes
+    # notes
     "read_note",
     "write_note",
     # file edit
-    #"ai_edit",
+    # "ai_edit",
 ]

basic_memory/mcp/tools/knowledge.py

@@ -2,7 +2,7 @@
 
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_get, call_post
-from basic_memory.schemas.base import PathId
+from basic_memory.schemas.base import Permalink
 from basic_memory.schemas.request import (
     GetEntitiesRequest,
 )
@@ -16,7 +16,7 @@ from basic_memory.mcp.async_client import client
 @mcp.tool(
     description="Get complete information about a specific entity including observations and relations",
 )
-async def get_entity(permalink: PathId) -> EntityResponse:
+async def get_entity(permalink: Permalink) -> EntityResponse:
     """Get a specific entity info by its permalink.
 
     Args:

basic_memory/mcp/tools/memory.py

@@ -7,9 +7,13 @@ 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_get
-from basic_memory.schemas.memory import GraphContext, MemoryUrl, memory_url, memory_url_path, normalize_memory_url
+from basic_memory.schemas.memory import (
+    GraphContext,
+    MemoryUrl,
+    memory_url_path,
+    normalize_memory_url,
+)
 from basic_memory.schemas.base import TimeFrame
-from basic_memory.schemas.search import SearchItemType
 
 
 @mcp.tool(
@@ -84,7 +88,7 @@ async def build_context(
     """,
 )
 async def recent_activity(
-    type: List[Literal["entity", "observation", "relation"]] = None,
+    type: List[Literal["entity", "observation", "relation"]] = [],
     depth: Optional[int] = 1,
     timeframe: Optional[TimeFrame] = "7d",
     max_results: int = 10,
@@ -136,7 +140,7 @@ async def recent_activity(
         "timeframe": timeframe,
         "max_results": max_results,
     }
-    if type: 
+    if type:
         params["type"] = type
 
     response = await call_get(

basic_memory/mcp/tools/search.py

@@ -1,4 +1,5 @@
 """Search tools for Basic Memory MCP server."""
+
 from loguru import logger
 
 from basic_memory.mcp.server import mcp
@@ -24,5 +25,5 @@ async def search(query: SearchQuery) -> SearchResponse:
         SearchResponse with search results and metadata
     """
     logger.info(f"Searching for {query.text}")
-    response = await call_post(client,"/search/", json=query.model_dump())
+    response = await call_post(client, "/search/", json=query.model_dump())
     return SearchResponse.model_validate(response.json())

basic_memory/mcp/tools/utils.py

@@ -45,7 +45,7 @@ async def call_get(
         return response
     except HTTPStatusError as e:
         logger.error(f"Error calling GET {url}: {e}")
-        raise ToolError(f"Error calling tool: {e}. Response: {response.text}") from e
+        raise ToolError(f"Error calling tool: {e}.") from e
 
 
 async def call_put(

basic_memory/models/__init__.py

@@ -2,7 +2,7 @@
 
 import basic_memory
 from basic_memory.models.base import Base
-from basic_memory.models.knowledge import Entity, Observation, Relation, ObservationCategory
+from basic_memory.models.knowledge import Entity, Observation, Relation
 
 SCHEMA_VERSION = basic_memory.__version__ + "-" + "003"
 
@@ -10,6 +10,5 @@ __all__ = [
     "Base",
     "Entity",
     "Observation",
-    "ObservationCategory",
     "Relation",
 ]

basic_memory/models/base.py

@@ -1,10 +1,10 @@
 """Base model class for SQLAlchemy models."""
-from sqlalchemy import String, Integer
+
 from sqlalchemy.ext.asyncio import AsyncAttrs
-from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from sqlalchemy.orm import DeclarativeBase
 
 
 class Base(AsyncAttrs, DeclarativeBase):
     """Base class for all models"""
-    pass
 
+    pass

basic_memory/models/knowledge.py

@@ -1,6 +1,5 @@
 """Knowledge graph models."""
 
-import re
 from datetime import datetime
 from typing import Optional
 
@@ -14,17 +13,15 @@ from sqlalchemy import (
     Index,
     JSON,
 )
-from sqlalchemy.orm import Mapped, mapped_column, relationship, validates
+from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from basic_memory.models.base import Base
-from enum import Enum
 
 from basic_memory.utils import generate_permalink
 
 
 class Entity(Base):
-    """
-    Core entity in the knowledge graph.
+    """Core entity in the knowledge graph.
 
     Entities represent semantic nodes maintained by the AI layer. Each entity:
     - Has a unique numeric ID (database-generated)
@@ -79,44 +76,15 @@ class Entity(Base):
 
     @property
     def relations(self):
+        """Get all relations (incoming and outgoing) for this entity."""
         return self.incoming_relations + self.outgoing_relations
 
-    @validates("permalink")
-    def validate_permalink(self, key, value):
-        """Validate permalink format.
-
-        Requirements:
-        1. Must be valid URI path component
-        2. Only lowercase letters, numbers, and hyphens (no underscores)
-        3. Path segments separated by forward slashes
-        4. No leading/trailing hyphens in segments
-        """
-        if not value:
-            raise ValueError("Permalink must not be None")
-
-        if not re.match(r"^[a-z0-9][a-z0-9\-/]*[a-z0-9]$", value):
-            raise ValueError(
-                f"Invalid permalink format: {value}. "
-                "Use only lowercase letters, numbers, and hyphens."
-            )
-        return value
-
     def __repr__(self) -> str:
         return f"Entity(id={self.id}, name='{self.title}', type='{self.entity_type}'"
 
 
-class ObservationCategory(str, Enum):
-    TECH = "tech"
-    DESIGN = "design"
-    FEATURE = "feature"
-    NOTE = "note"
-    ISSUE = "issue"
-    TODO = "todo"
-
-
 class Observation(Base):
-    """
-    An observation about an entity.
+    """An observation about an entity.
 
     Observations are atomic facts or notes about an entity.
     """
@@ -130,13 +98,8 @@ class Observation(Base):
     id: Mapped[int] = mapped_column(Integer, primary_key=True)
     entity_id: Mapped[int] = mapped_column(Integer, ForeignKey("entity.id", ondelete="CASCADE"))
     content: Mapped[str] = mapped_column(Text)
-    category: Mapped[str] = mapped_column(
-        String,
-        nullable=False,
-        default=ObservationCategory.NOTE.value,
-        server_default=ObservationCategory.NOTE.value,
-    )
-    context: Mapped[str] = mapped_column(Text, nullable=True)
+    category: Mapped[str] = mapped_column(String, nullable=False, default="note")
+    context: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
     tags: Mapped[Optional[list[str]]] = mapped_column(
         JSON, nullable=True, default=list, server_default="[]"
     )
@@ -146,23 +109,21 @@ class Observation(Base):
 
     @property
     def permalink(self) -> str:
-        """
-        Create synthetic permalink for the observation
-            We can construct these because observations are always
-            defined in and owned by a single entity
+        """Create synthetic permalink for the observation.
+
+        We can construct these because observations are always defined in
+        and owned by a single entity.
         """
         return generate_permalink(
             f"{self.entity.permalink}/observations/{self.category}/{self.content}"
         )
 
-    def __repr__(self) -> str:
+    def __repr__(self) -> str:  # pragma: no cover
         return f"Observation(id={self.id}, entity_id={self.entity_id}, content='{self.content}')"
 
 
 class Relation(Base):
-    """
-    A directed relation between two entities.
-    """
+    """A directed relation between two entities."""
 
     __tablename__ = "relation"
     __table_args__ = (
@@ -174,12 +135,12 @@ class Relation(Base):
 
     id: Mapped[int] = mapped_column(Integer, primary_key=True)
     from_id: Mapped[int] = mapped_column(Integer, ForeignKey("entity.id", ondelete="CASCADE"))
-    to_id: Mapped[int] = mapped_column(
+    to_id: Mapped[Optional[int]] = mapped_column(
         Integer, ForeignKey("entity.id", ondelete="CASCADE"), nullable=True
     )
     to_name: Mapped[str] = mapped_column(String)
     relation_type: Mapped[str] = mapped_column(String)
-    context: Mapped[str] = mapped_column(Text, nullable=True)
+    context: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
 
     # Relationships
     from_entity = relationship(
@@ -189,15 +150,17 @@ class Relation(Base):
 
     @property
     def permalink(self) -> str:
-        """Create relation permalink showing the semantic connection:
-        source/relation_type/target
-        e.g., "specs/search/implements/features/search-ui"
-        """
+        """Create relation permalink showing the semantic connection.
 
+        Format: source/relation_type/target
+        Example: "specs/search/implements/features/search-ui"
+        """
+        if self.to_entity:
+            return generate_permalink(
+                f"{self.from_entity.permalink}/{self.relation_type}/{self.to_entity.permalink}"
+            )
         return generate_permalink(
-            f"{self.from_entity.permalink}/{self.relation_type}/{self.to_entity.permalink}"
-            if self.to_entity
-            else f"{self.from_entity.permalink}/{self.relation_type}/{self.to_name}"
+            f"{self.from_entity.permalink}/{self.relation_type}/{self.to_name}"
         )
 
     def __repr__(self) -> str:

basic_memory/models/search.py

@@ -31,4 +31,4 @@ CREATE VIRTUAL TABLE IF NOT EXISTS search_index USING fts5(
     tokenize='unicode61 tokenchars 0x2F',  -- Hex code for /
     prefix='1,2,3,4'                    -- Support longer prefixes for paths
 );
-""")
+""")

basic_memory/repository/__init__.py

@@ -2,6 +2,8 @@ from .entity_repository import EntityRepository
 from .observation_repository import ObservationRepository
 from .relation_repository import RelationRepository
 
-__all__ = ["EntityRepository", "ObservationRepository", "RelationRepository", ]
-
-
+__all__ = [
+    "EntityRepository",
+    "ObservationRepository",
+    "RelationRepository",
+]