basic-memory 0.0.0__py3-none-any.whl

basic_memory/markdown/plugins.py

@@ -0,0 +1,236 @@
+"""Markdown-it plugins for Basic Memory markdown parsing."""
+
+from typing import List, Any, Dict
+from markdown_it import MarkdownIt
+from markdown_it.token import Token
+
+
+# Observation handling functions
+def is_observation(token: Token) -> bool:
+    """Check if token looks like our observation format."""
+    if token.type != 'inline':
+        return False
+        
+    content = token.content.strip()
+    if not content:
+        return False
+    
+    # if it's a markdown_task, return false
+    if content.startswith('[ ]') or content.startswith('[x]') or content.startswith('[-]'):
+        return False
+    
+    has_category = content.startswith('[') and ']' in content
+    has_tags = '#' in content
+    return has_category or has_tags
+
+
+def parse_observation(token: Token) -> Dict[str, Any]:
+    """Extract observation parts from token."""
+    # Strip bullet point if present
+    content = token.content.strip()
+    if content.startswith('- '):
+        content = content[2:].strip()
+    elif content.startswith('-'):
+        content = content[1:].strip()
+    
+    # Parse [category]
+    category = None
+    if content.startswith('['):
+        end = content.find(']')
+        if end != -1:
+            category = content[1:end].strip() or None  # Convert empty to None
+            content = content[end + 1:].strip()
+    
+    # Parse (context)
+    context = None
+    if content.endswith(')'):
+        start = content.rfind('(')
+        if start != -1:
+            context = content[start + 1:-1].strip()
+            content = content[:start].strip()
+    
+    # Parse #tags and content
+    parts = content.split()
+    content_parts = []
+    tags = set()  # Use set to avoid duplicates
+    
+    for part in parts:
+        if part.startswith('#'):
+            # Handle multiple #tags stuck together
+            if '#' in part[1:]:
+                # Split on # but keep non-empty tags
+                subtags = [t for t in part.split('#') if t]
+                tags.update(subtags)
+            else:
+                tags.add(part[1:])
+        else:
+            content_parts.append(part)
+    
+    return {
+        'category': category,
+        'content': ' '.join(content_parts).strip(),
+        'tags': list(tags) if tags else None,
+        'context': context
+    }
+
+
+# Relation handling functions
+def is_explicit_relation(token: Token) -> bool:
+    """Check if token looks like our relation format."""
+    if token.type != 'inline':
+        return False
+    
+    content = token.content.strip()
+    return '[[' in content and ']]' in content
+
+
+def parse_relation(token: Token) -> Dict[str, Any]:
+    """Extract relation parts from token."""
+    # Remove bullet point if present
+    content = token.content.strip()
+    if content.startswith('- '):
+        content = content[2:].strip()
+    elif content.startswith('-'):
+        content = content[1:].strip()
+    
+    # Extract [[target]]
+    target = None
+    rel_type = 'relates_to'  # default
+    context = None
+    
+    start = content.find('[[')
+    end = content.find(']]')
+    
+    if start != -1 and end != -1:
+        # Get text before link as relation type
+        before = content[:start].strip()
+        if before:
+            rel_type = before
+            
+        # Get target
+        target = content[start + 2:end].strip()
+        
+        # Look for context after
+        after = content[end + 2:].strip()
+        if after.startswith('(') and after.endswith(')'):
+            context = after[1:-1].strip() or None
+    
+    if not target:
+        return None
+        
+    return {
+        'type': rel_type,
+        'target': target,
+        'context': context
+    }
+
+
+def parse_inline_relations(content: str) -> List[Dict[str, Any]]:
+    """Find wiki-style links in regular content."""
+    relations = []
+    
+    import re
+    pattern = r'\[\[([^\]]+)\]\]'
+    
+    for match in re.finditer(pattern, content):
+        target = match.group(1).strip()
+        if target and not target.startswith('[['):  # Avoid nested matches
+            relations.append({
+                'type': 'links to',
+                'target': target,
+                'context': None
+            })
+            
+    return relations
+
+
+def observation_plugin(md: MarkdownIt) -> None:
+    """Plugin for parsing observation format:
+    - [category] Content text #tag1 #tag2 (context)
+    - Content text #tag1 (context)  # No category is also valid
+    """
+    
+    def observation_rule(state: Any) -> None:
+        """Process observations in token stream."""
+        tokens = state.tokens
+        current_section = None
+        in_list_item = False
+        
+        for idx in range(len(tokens)):
+            token = tokens[idx]
+            
+            # Track current section by headings
+            if token.type == 'heading_open':
+                next_token = tokens[idx + 1] if idx + 1 < len(tokens) else None
+                if next_token and next_token.type == 'inline':
+                    current_section = next_token.content.lower()
+            
+            # Track list nesting
+            elif token.type == 'list_item_open':
+                in_list_item = True
+            elif token.type == 'list_item_close':
+                in_list_item = False
+            
+            # Initialize meta for all tokens
+            token.meta = token.meta or {}
+            
+            # Parse observations in list items
+            if token.type == 'inline' and is_observation(token):
+                obs = parse_observation(token)
+                if obs['content']:  # Only store if we have content
+                    token.meta['observation'] = obs
+    
+    # Add the rule after inline processing
+    md.core.ruler.after('inline', 'observations', observation_rule)
+
+
+def relation_plugin(md: MarkdownIt) -> None:
+    """Plugin for parsing relation formats:
+    
+    Explicit relations:
+    - relation_type [[target]] (context)
+    
+    Implicit relations (links in content):
+    Some text with [[target]] reference
+    """
+    
+    def relation_rule(state: Any) -> None:
+        """Process relations in token stream."""
+        tokens = state.tokens
+        current_section = None
+        in_list_item = False
+        
+        for idx in range(len(tokens)):
+            token = tokens[idx]
+            
+            # Track current section by headings
+            if token.type == 'heading_open':
+                next_token = tokens[idx + 1] if idx + 1 < len(tokens) else None
+                if next_token and next_token.type == 'inline':
+                    current_section = next_token.content.lower()
+            
+            # Track list nesting
+            elif token.type == 'list_item_open':
+                in_list_item = True
+            elif token.type == 'list_item_close':
+                in_list_item = False
+            
+            # Initialize meta for all tokens
+            token.meta = token.meta or {}
+            
+            # Only process inline tokens
+            if token.type == 'inline':
+                # Check for explicit relations in list items
+                if in_list_item and is_explicit_relation(token):
+                    rel = parse_relation(token)
+                    if rel:
+                        token.meta['relations'] = [rel]
+                
+                # Always check for inline links in any text
+                elif '[[' in token.content:
+                    rels = parse_inline_relations(token.content)
+                    if rels:
+                        token.meta['relations'] = token.meta.get('relations', []) + rels
+    
+    # Add the rule after inline processing
+    md.core.ruler.after('inline', 'relations', relation_rule)

basic_memory/markdown/schemas.py

@@ -0,0 +1,73 @@
+"""Schema models for entity markdown files."""
+
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import BaseModel
+
+
+class Observation(BaseModel):
+    """An observation about an entity."""
+
+    category: Optional[str] = None
+    content: str
+    tags: Optional[List[str]] = None
+    context: Optional[str] = None
+    
+    def __str__(self) -> str:
+        obs_string = f"- [{self.category}] {self.content}"
+        if self.tags:
+            obs_string += " " + " ".join(f"#{tag}" for tag in sorted(self.tags))
+        if self.context:
+            obs_string += f" ({self.context})"
+        return obs_string
+
+
+class Relation(BaseModel):
+    """A relation between entities."""
+
+    type: str
+    target: str
+    context: Optional[str] = None
+    
+    def __str__(self) -> str:
+        rel_string = f"- {self.type} [[{self.target}]]"
+        if self.context:
+            rel_string += f" ({self.context})"
+        return rel_string
+
+
+class EntityFrontmatter(BaseModel):
+    """Required frontmatter fields for an entity."""
+
+    metadata: Optional[dict] = None
+
+    @property
+    def tags(self) -> List[str]:
+        return self.metadata.get("tags") if self.metadata else []
+
+    @property
+    def title(self) -> str:
+        return self.metadata.get("title") if self.metadata else None
+
+    @property
+    def type(self) -> str:
+        return self.metadata.get("type", "note") if self.metadata else "note"
+
+    @property
+    def permalink(self) -> str:
+        return self.metadata.get("permalink") if self.metadata else None
+
+
+
+class EntityMarkdown(BaseModel):
+    """Complete entity combining frontmatter, content, and metadata."""
+
+    frontmatter: EntityFrontmatter
+    content: Optional[str] = None
+    observations: List[Observation] = []
+    relations: List[Relation] = []
+
+    # created, updated will have values after a read
+    created: Optional[datetime] = None
+    modified: Optional[datetime] = None

basic_memory/markdown/utils.py

@@ -0,0 +1,144 @@
+from pathlib import Path
+from typing import Optional
+
+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.utils import generate_permalink
+
+
+def entity_model_to_markdown(entity: Entity, content: Optional[str] = None) -> EntityMarkdown:
+    """
+    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
+    """
+    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,
+            content=obs.content,
+            tags=obs.tags if obs.tags else None,
+            context=obs.context,
+        )
+        for obs in entity.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,
+    )
+
+
+def entity_model_from_markdown(file_path: Path, markdown: EntityMarkdown, entity: Optional[Entity] = None) -> Entity:
+    """
+    Convert markdown entity to model.
+    Does not include relations.
+
+    Args:
+        markdown: Parsed markdown entity
+        include_relations: Whether to include relations. Set False for first sync pass.
+    """
+
+    # 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 
+    """
+    # Create Post object
+    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)
+    return post

basic_memory/mcp/__init__.py

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

basic_memory/mcp/async_client.py

@@ -0,0 +1,10 @@
+from httpx import ASGITransport, AsyncClient
+
+from basic_memory.api.app import app as fastapi_app
+
+BASE_URL = "http://test"
+
+# Create shared async client
+client = AsyncClient(transport=ASGITransport(app=fastapi_app), base_url=BASE_URL)
+
+

basic_memory/mcp/main.py

@@ -0,0 +1,21 @@
+"""Main MCP entrypoint for Basic Memory.
+
+Creates and configures the shared MCP instance and handles server startup.
+"""
+
+from loguru import logger
+
+from basic_memory.config import config
+
+# Import shared mcp instance
+from basic_memory.mcp.server import mcp
+
+# Import tools to register them
+import basic_memory.mcp.tools # noqa: F401
+
+
+if __name__ == "__main__":
+    home_dir = config.home
+    logger.info("Starting Basic Memory MCP server")
+    logger.info(f"Home directory: {home_dir}")
+    mcp.run()

basic_memory/mcp/server.py

@@ -0,0 +1,39 @@
+"""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
+
+# mcp console logging
+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()
+
+# Create the shared server instance
+mcp = FastMCP("Basic Memory")

basic_memory/mcp/tools/__init__.py

@@ -0,0 +1,34 @@
+"""MCP tools for Basic Memory.
+
+This package provides the complete set of tools for interacting with
+Basic Memory through the MCP protocol. Importing this module registers
+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.notes import read_note, write_note
+
+from basic_memory.mcp.tools.knowledge import (
+    delete_entities,
+    get_entity,
+    get_entities,
+)
+
+__all__ = [
+    # Knowledge graph tools
+    "delete_entities",
+    "get_entity",
+    "get_entities",
+    # Search tools
+    "search",
+    # memory tools
+    "build_context",
+    "recent_activity",
+    #notes
+    "read_note",
+    "write_note",
+    # file edit
+    #"ai_edit",
+]

basic_memory/mcp/tools/ai_edit.py

@@ -0,0 +1,84 @@
+"""Tool for AI-assisted file editing."""
+
+from pathlib import Path
+from typing import List, Dict, Any
+
+from basic_memory.mcp.server import mcp
+
+
+def _detect_indent(text: str, match_pos: int) -> int:
+    """Get indentation level at a position in text."""
+    # Find start of line containing the match
+    line_start = text.rfind("\n", 0, match_pos)
+    if line_start < 0:
+        line_start = 0
+    else:
+        line_start += 1  # Skip newline char
+
+    # Count leading spaces
+    pos = line_start
+    while pos < len(text) and text[pos].isspace():
+        pos += 1
+    return pos - line_start
+
+
+def _apply_indent(text: str, spaces: int) -> str:
+    """Apply indentation to text."""
+    prefix = " " * spaces
+    return "\n".join(prefix + line if line.strip() else line for line in text.split("\n"))
+
+
+@mcp.tool()
+async def ai_edit(path: str, edits: List[Dict[str, Any]]) -> bool:
+    """AI-assisted file editing tool.
+
+    Args:
+        path: Path to file to edit
+        edits: List of edits to apply. Each edit is a dict with:
+            oldText: Text to replace
+            newText: New content
+            options: Optional dict with:
+                indent: Number of spaces to indent
+                preserveIndentation: Keep existing indent (default: true)
+
+    Returns:
+        bool: True if edits were applied successfully
+    """
+    try:
+        # Read file
+        content = Path(path).read_text()
+        original = content
+        success = True
+
+        # Apply each edit
+        for edit in edits:
+            old_text = edit["oldText"]
+            new_text = edit["newText"]
+            options = edit.get("options", {})
+
+            # Find text to replace
+            match_pos = content.find(old_text)
+            if match_pos < 0:
+                success = False
+                continue
+
+            # Handle indentation
+            if not options.get("preserveIndentation", True):
+                # Use existing indentation
+                indent = _detect_indent(content, match_pos)
+                new_text = _apply_indent(new_text, indent)
+            elif "indent" in options:
+                # Use specified indentation
+                new_text = _apply_indent(new_text, options["indent"])
+
+            # Apply the edit
+            content = content.replace(old_text, new_text)
+
+        # Write back if changed
+        if content != original:
+            Path(path).write_text(content)
+        return success
+
+    except Exception as e:
+        print(f"Error applying edits: {e}")
+        return False