basic-memory 0.7.0__py3-none-any.whl → 0.17.4__py3-none-any.whl

basic_memory/mcp/tools/memory.py

@@ -1,170 +0,0 @@
-"""Discussion context tools for Basic Memory MCP server."""
-
-from typing import Optional, Literal, List
-
-from loguru import logger
-import logfire
-
-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_path,
-    normalize_memory_url,
-)
-from basic_memory.schemas.base import TimeFrame
-
-
-@mcp.tool(
-    description="""Build context from a memory:// URI to continue conversations naturally.
-    
-    Use this to follow up on previous discussions or explore related topics.
-    Timeframes support natural language like:
-    - "2 days ago"
-    - "last week" 
-    - "today"
-    - "3 months ago"
-    Or standard formats like "7d", "24h"
-    """,
-)
-async def build_context(
-    url: MemoryUrl,
-    depth: Optional[int] = 1,
-    timeframe: Optional[TimeFrame] = "7d",
-    page: int = 1,
-    page_size: int = 10,
-    max_related: int = 10,
-) -> GraphContext:
-    """Get context needed to continue a discussion.
-
-    This tool enables natural continuation of discussions by loading relevant context
-    from memory:// URIs. It uses pattern matching to find relevant content and builds
-    a rich context graph of related information.
-
-    Args:
-        url: memory:// URI pointing to discussion content (e.g. memory://specs/search)
-        depth: How many relation hops to traverse (1-3 recommended for performance)
-        timeframe: How far back to look. Supports natural language like "2 days ago", "last week"
-        page: Page number of results to return (default: 1)
-        page_size: Number of results to return per page (default: 10)
-        max_related: Maximum number of related results to return (default: 10)
-
-    Returns:
-        GraphContext containing:
-            - primary_results: Content matching the memory:// URI
-            - related_results: Connected content via relations
-            - metadata: Context building details
-
-    Examples:
-        # Continue a specific discussion
-        build_context("memory://specs/search")
-
-        # Get deeper context about a component
-        build_context("memory://components/memory-service", depth=2)
-
-        # Look at recent changes to a specification
-        build_context("memory://specs/document-format", timeframe="today")
-
-        # Research the history of a feature
-        build_context("memory://features/knowledge-graph", timeframe="3 months ago")
-    """
-    with logfire.span("Building context", url=url, depth=depth, timeframe=timeframe):  # pyright: ignore [reportGeneralTypeIssues]
-        logger.info(f"Building context from {url}")
-        url = normalize_memory_url(url)
-        response = await call_get(
-            client,
-            f"/memory/{memory_url_path(url)}",
-            params={
-                "depth": depth,
-                "timeframe": timeframe,
-                "page": page,
-                "page_size": page_size,
-                "max_related": max_related,
-            },
-        )
-        return GraphContext.model_validate(response.json())
-
-
-@mcp.tool(
-    description="""Get recent activity from across the knowledge base.
-    
-    Timeframe supports natural language formats like:
-    - "2 days ago"  
-    - "last week"
-    - "yesterday" 
-    - "today"
-    - "3 weeks ago"
-    Or standard formats like "7d"
-    """,
-)
-async def recent_activity(
-    type: List[Literal["entity", "observation", "relation"]] = [],
-    depth: Optional[int] = 1,
-    timeframe: Optional[TimeFrame] = "7d",
-    page: int = 1,
-    page_size: int = 10,
-    max_related: int = 10,
-) -> GraphContext:
-    """Get recent activity across the knowledge base.
-
-    Args:
-        type: Filter by content type(s). Valid options:
-            - ["entity"] for knowledge entities
-            - ["relation"] for connections between entities
-            - ["observation"] for notes and observations
-            Multiple types can be combined: ["entity", "relation"]
-        depth: How many relation hops to traverse (1-3 recommended)
-        timeframe: Time window to search. Supports natural language:
-            - Relative: "2 days ago", "last week", "yesterday"
-            - Points in time: "2024-01-01", "January 1st"
-            - Standard format: "7d", "24h"
-        page: Page number of results to return (default: 1)
-        page_size: Number of results to return per page (default: 10)
-        max_related: Maximum number of related results to return (default: 10)
-
-    Returns:
-        GraphContext containing:
-            - primary_results: Latest activities matching the filters
-            - related_results: Connected content via relations
-            - metadata: Query details and statistics
-
-    Examples:
-        # Get all entities for the last 10 days (default)
-        recent_activity()
-
-        # Get all entities from yesterday
-        recent_activity(type=["entity"], timeframe="yesterday")
-
-        # Get recent relations and observations
-        recent_activity(type=["relation", "observation"], timeframe="today")
-
-        # Look back further with more context
-        recent_activity(type=["entity"], depth=2, timeframe="2 weeks ago")
-
-    Notes:
-        - Higher depth values (>3) may impact performance with large result sets
-        - For focused queries, consider using build_context with a specific URI
-        - Max timeframe is 1 year in the past
-    """
-    with logfire.span("Getting recent activity", type=type, depth=depth, timeframe=timeframe):  # pyright: ignore [reportGeneralTypeIssues]
-        logger.info(
-            f"Getting recent activity from {type}, depth={depth}, timeframe={timeframe}, page={page}, page_size={page_size}, max_related={max_related}"
-        )
-        params = {
-            "depth": depth,
-            "timeframe": timeframe,
-            "page": page,
-            "page_size": page_size,
-            "max_related": max_related,
-        }
-        if type:
-            params["type"] = type
-
-        response = await call_get(
-            client,
-            "/memory/recent",
-            params=params,
-        )
-        return GraphContext.model_validate(response.json())

basic_memory/mcp/tools/notes.py

@@ -1,202 +0,0 @@
-"""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
-import logfire
-
-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 a markdown formatted summary of the semantic content.",
-)
-async def write_note(
-    title: str,
-    content: str,
-    folder: str,
-    tags: Optional[List[str]] = None,
-) -> 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
-
-    Returns:
-        A markdown formatted summary of the semantic content, including:
-        - Creation/update status
-        - File path and checksum
-        - Observation counts by category
-        - Relation counts (resolved/unresolved)
-        - Tags if present
-    """
-    with logfire.span("Writing note", title=title, folder=folder):  # pyright: ignore [reportGeneralTypeIssues]
-        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,
-        )
-
-        # Create or update via knowledge API
-        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())
-
-        # Format semantic summary based on status code
-        action = "Created" if response.status_code == 201 else "Updated"
-        assert result.checksum is not None
-        summary = [
-            f"# {action} {result.file_path} ({result.checksum[:8]})",
-            f"permalink: {result.permalink}",
-        ]
-
-        if result.observations:
-            categories = {}
-            for obs in result.observations:
-                categories[obs.category] = categories.get(obs.category, 0) + 1
-
-            summary.append("\n## Observations")
-            for category, count in sorted(categories.items()):
-                summary.append(f"- {category}: {count}")
-
-        if result.relations:
-            unresolved = sum(1 for r in result.relations if not r.to_id)
-            resolved = len(result.relations) - unresolved
-
-            summary.append("\n## Relations")
-            summary.append(f"- Resolved: {resolved}")
-            if unresolved:
-                summary.append(f"- Unresolved: {unresolved}")
-                summary.append("\nUnresolved relations will be retried on next sync.")
-
-        if tags:
-            summary.append(f"\n## Tags\n- {', '.join(tags)}")
-
-        return "\n".join(summary)
-
-
-@mcp.tool(description="Read note content by title, permalink, relation, or pattern")
-async def read_note(identifier: str, page: int = 1, page_size: int = 10) -> 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")
-        page: the page number of results to return (default 1)
-        page_size: the number of results to return per page (default 10)
-
-    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
-    """
-    with logfire.span("Reading note", identifier=identifier):  # pyright: ignore [reportGeneralTypeIssues]
-        logger.info(f"Reading note {identifier}")
-        url = memory_url_path(identifier)
-        response = await call_get(
-            client, f"/resource/{url}", params={"page": page, "page_size": page_size}
-        )
-        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")
-    """
-    with logfire.span("Deleting note", identifier=identifier):  # pyright: ignore [reportGeneralTypeIssues]
-        response = await call_delete(client, f"/knowledge/entities/{identifier}")
-        result = DeleteEntitiesResponse.model_validate(response.json())
-        return result.deleted

basic_memory/schemas/discovery.py

@@ -1,28 +0,0 @@
-"""Schemas for knowledge discovery and analytics endpoints."""
-
-from typing import List, Optional
-from pydantic import BaseModel, Field
-
-from basic_memory.schemas.response import EntityResponse
-
-
-class EntityTypeList(BaseModel):
-    """List of unique entity types in the system."""
-
-    types: List[str]
-
-
-class ObservationCategoryList(BaseModel):
-    """List of unique observation categories in the system."""
-
-    categories: List[str]
-
-
-class TypedEntityList(BaseModel):
-    """List of entities of a specific type."""
-
-    entity_type: str = Field(..., description="Type of entities in the list")
-    entities: List[EntityResponse]
-    total: int = Field(..., description="Total number of entities")
-    sort_by: Optional[str] = Field(None, description="Field used for sorting")
-    include_related: bool = Field(False, description="Whether related entities are included")

basic_memory/sync/file_change_scanner.py

@@ -1,158 +0,0 @@
-"""Service for detecting changes between filesystem and database."""
-
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Dict, Sequence
-
-from loguru import logger
-
-from basic_memory.file_utils import compute_checksum
-from basic_memory.models import Entity
-from basic_memory.repository.entity_repository import EntityRepository
-from basic_memory.sync.utils import SyncReport
-
-
-@dataclass
-class FileState:
-    """State of a file including file path, permalink and checksum info."""
-
-    file_path: str
-    permalink: str
-    checksum: str
-
-
-@dataclass
-class ScanResult:
-    """Result of scanning a directory."""
-
-    # file_path -> checksum
-    files: Dict[str, str] = field(default_factory=dict)
-    # file_path -> error message
-    errors: Dict[str, str] = field(default_factory=dict)
-
-
-class FileChangeScanner:
-    """
-    Service for detecting changes between filesystem and database.
-    The filesystem is treated as the source of truth.
-    """
-
-    def __init__(self, entity_repository: EntityRepository):
-        self.entity_repository = entity_repository
-
-    async def scan_directory(self, directory: Path) -> ScanResult:
-        """
-        Scan directory for markdown files and their checksums.
-        Only processes .md files, logs and skips others.
-
-        Args:
-            directory: Directory to scan
-
-        Returns:
-            ScanResult containing found files and any errors
-        """
-        logger.debug(f"Scanning directory: {directory}")
-        result = ScanResult()
-
-        if not directory.exists():
-            logger.debug(f"Directory does not exist: {directory}")
-            return result
-
-        for path in directory.rglob("*"):
-            if not path.is_file() or not path.name.endswith(".md"):
-                if path.is_file():
-                    logger.debug(f"Skipping non-markdown file: {path}")
-                continue
-
-            try:
-                # Get relative path first - used in error reporting if needed
-                rel_path = str(path.relative_to(directory))
-                content = path.read_text()
-                checksum = await compute_checksum(content)
-                result.files[rel_path] = checksum
-
-            except Exception as e:
-                rel_path = str(path.relative_to(directory))
-                result.errors[rel_path] = str(e)
-                logger.error(f"Failed to read {rel_path}: {e}")
-
-        logger.debug(f"Found {len(result.files)} markdown files")
-        if result.errors:
-            logger.warning(f"Encountered {len(result.errors)} errors while scanning")
-
-        return result
-
-    async def find_changes(
-        self, directory: Path, db_file_state: Dict[str, FileState]
-    ) -> SyncReport:
-        """Find changes between filesystem and database."""
-        # Get current files and checksums
-        scan_result = await self.scan_directory(directory)
-        current_files = scan_result.files
-
-        # Build report
-        report = SyncReport(total=len(current_files))
-
-        # Track potentially moved files by checksum
-        files_by_checksum = {}  # checksum -> file_path
-
-        # First find potential new files and record checksums
-        for file_path, checksum in current_files.items():
-            logger.debug(f"{file_path} ({checksum[:8]})")
-
-            if file_path not in db_file_state:
-                # Could be new or could be the destination of a move
-                report.new.add(file_path)
-                files_by_checksum[checksum] = file_path
-            elif checksum != db_file_state[file_path].checksum:
-                report.modified.add(file_path)
-
-            report.checksums[file_path] = checksum
-
-        # Now detect moves and deletions
-        for db_file_path, db_state in db_file_state.items():
-            if db_file_path not in current_files:
-                if db_state.checksum in files_by_checksum:
-                    # Found a move - file exists at new path with same checksum
-                    new_path = files_by_checksum[db_state.checksum]
-                    report.moves[db_file_path] = new_path
-                    # Remove from new files since it's a move
-                    report.new.remove(new_path)
-                else:
-                    # Actually deleted
-                    report.deleted.add(db_file_path)
-
-        # Log summary
-        logger.debug(f"Total files: {report.total}")
-        logger.debug(f"Changes found: {report.total_changes}")
-        logger.debug(f"  New: {len(report.new)}")
-        logger.debug(f"  Modified: {len(report.modified)}")
-        logger.debug(f"  Moved: {len(report.moves)}")
-        logger.debug(f"  Deleted: {len(report.deleted)}")
-
-        if scan_result.errors:  # pragma: no cover
-            logger.warning("Files skipped due to errors:")
-            for file_path, error in scan_result.errors.items():
-                logger.warning(f"  {file_path}: {error}")
-
-        return report
-
-    async def get_db_file_state(self, db_records: Sequence[Entity]) -> Dict[str, FileState]:
-        """Get file_path and checksums from database.
-        Args:
-            db_records: database records
-        Returns:
-            Dict mapping file paths to FileState
-            :param db_records: the data from the db
-        """
-        return {
-            r.file_path: FileState(
-                file_path=r.file_path, permalink=r.permalink, checksum=r.checksum or ""
-            )
-            for r in db_records
-        }
-
-    async def find_knowledge_changes(self, directory: Path) -> SyncReport:
-        """Find changes in knowledge directory."""
-        db_file_state = await self.get_db_file_state(await self.entity_repository.find_all())
-        return await self.find_changes(directory=directory, db_file_state=db_file_state)

basic_memory/sync/utils.py

@@ -1,31 +0,0 @@
-"""Types and utilities for file sync."""
-
-from dataclasses import dataclass, field
-from typing import Set, Dict
-
-
-@dataclass
-class SyncReport:
-    """Report of file changes found compared to database state.
-
-    Attributes:
-        total: Total number of files in directory being synced
-        new: Files that exist on disk but not in database
-        modified: Files that exist in both but have different checksums
-        deleted: Files that exist in database but not on disk
-        moves: Files that have been moved from one location to another
-        checksums: Current checksums for files on disk
-    """
-
-    total: int = 0
-    # We keep paths as strings in sets/dicts for easier serialization
-    new: Set[str] = field(default_factory=set)
-    modified: Set[str] = field(default_factory=set)
-    deleted: Set[str] = field(default_factory=set)
-    moves: Dict[str, str] = field(default_factory=dict)  # old_path -> new_path
-    checksums: Dict[str, str] = field(default_factory=dict)  # path -> checksum
-
-    @property
-    def total_changes(self) -> int:
-        """Total number of changes."""
-        return len(self.new) + len(self.modified) + len(self.deleted) + len(self.moves)