basic-memory 0.0.0__py3-none-any.whl

basic_memory/mcp/tools/knowledge.py

@@ -0,0 +1,56 @@
+"""Knowledge graph management tools for Basic Memory MCP server."""
+
+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.request import (
+    GetEntitiesRequest,
+)
+from basic_memory.schemas.delete import (
+    DeleteEntitiesRequest,
+)
+from basic_memory.schemas.response import EntityListResponse, EntityResponse, DeleteEntitiesResponse
+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:
+    """Get a specific entity info by its permalink.
+
+    Args:
+        permalink: Path identifier for the entity
+    """
+    url = f"/knowledge/entities/{permalink}"
+    response = await call_get(client, url)
+    return EntityResponse.model_validate(response.json())
+
+
+@mcp.tool(
+    description="Load multiple entities by their permalinks in a single request",
+)
+async def get_entities(request: GetEntitiesRequest) -> EntityListResponse:
+    """Load multiple entities by their permalinks.
+
+    Args:
+        request: OpenNodesRequest containing list of permalinks to load
+
+    Returns:
+        EntityListResponse containing complete details for each requested entity
+    """
+    url = "/knowledge/entities"
+    response = await call_get(
+        client, url, params=[("permalink", permalink) for permalink in request.permalinks]
+    )
+    return EntityListResponse.model_validate(response.json())
+
+
+@mcp.tool(
+    description="Permanently delete entities and all related content (observations and relations)",
+)
+async def delete_entities(request: DeleteEntitiesRequest) -> DeleteEntitiesResponse:
+    """Delete entities from the knowledge graph."""
+    url = "/knowledge/entities/delete"
+    response = await call_post(client, url, json=request.model_dump())
+    return DeleteEntitiesResponse.model_validate(response.json())

basic_memory/mcp/tools/memory.py

@@ -0,0 +1,142 @@
+"""Discussion context tools for Basic Memory MCP server."""
+
+from typing import Optional, Literal
+
+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.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",
+    max_results: 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"
+        max_results: Maximum number of 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")
+    """
+    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, "max_results": max_results},
+    )
+    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: Literal["entity", "observation", "relation"] = None,
+    depth: Optional[int] = 1,
+    timeframe: Optional[TimeFrame] = "7d",
+    max_results: 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"
+        max_results: Maximum number of 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 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
+    """
+    logger.info(
+        f"Getting recent activity from {type}, depth={depth}, timeframe={timeframe}, max_results={max_results}"
+    )
+    params = {
+        "depth": depth,
+        "timeframe": timeframe,
+        "max_results": max_results,
+        "type": type if type else None,
+    }
+
+    response = await call_get(
+        client,
+        "/memory/recent",
+        params=params,
+    )
+    return GraphContext.model_validate(response.json())

basic_memory/mcp/tools/notes.py

@@ -0,0 +1,122 @@
+"""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
+
+
+@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.
+
+    Args:
+        title: The title of the note
+        content: Markdown content for the note
+        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:
+        # Create a simple note
+        write_note(
+            tile="Meeting Notes: Project Planning.md",
+            content="# Key Points\\n\\n- Discussed timeline\\n- Set priorities"
+            folder="notes"
+        )
+
+        # Create note with tags
+        write_note(
+            title="Security Review",
+            content="# Findings\\n\\n1. Updated auth flow\\n2. Added rate limiting",
+            folder="security",
+            tags=["security", "development"]
+        )
+    """
+    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 a note's content by its title or permalink")
+async def read_note(identifier: str) -> str:
+    """Get the markdown content of a note.
+    Uses the resource router to return the actual file content.
+
+    Args:
+        identifier: Note title or permalink
+
+    Returns:
+        The note's markdown content
+
+    Examples:
+        # Read by title
+        read_note("Meeting Notes: Project Planning")
+
+        # Read by permalink
+        read_note("notes/project-planning")
+
+    Raises:
+        ValueError: If the note cannot be found
+    """
+    response = await call_get(client, f"/resource/{identifier}")
+    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/mcp/tools/search.py

@@ -0,0 +1,28 @@
+"""Search tools for Basic Memory MCP server."""
+from loguru import logger
+
+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
+
+
+@mcp.tool(
+    description="Search across all content in basic-memory, including documents and entities",
+)
+async def search(query: SearchQuery) -> SearchResponse:
+    """Search across all content in basic-memory.
+
+    Args:
+        query: SearchQuery object with search parameters including:
+            - text: Search text (required)
+            - types: Optional list of content types to search ("document" or "entity")
+            - entity_types: Optional list of entity types to filter by
+            - after_date: Optional date filter for recent content
+
+    Returns:
+        SearchResponse with search results and metadata
+    """
+    logger.info(f"Searching for {query.text}")
+    response = await call_post(client,"/search/", json=query.model_dump())
+    return SearchResponse.model_validate(response.json())

basic_memory/mcp/tools/utils.py

@@ -0,0 +1,154 @@
+import typing
+
+from httpx import Response, URL, AsyncClient, HTTPStatusError
+from httpx._client import UseClientDefault, USE_CLIENT_DEFAULT
+from httpx._types import (
+    RequestContent,
+    RequestData,
+    RequestFiles,
+    QueryParamTypes,
+    HeaderTypes,
+    CookieTypes,
+    AuthTypes,
+    TimeoutTypes,
+    RequestExtensions,
+)
+from loguru import logger
+from mcp.server.fastmcp.exceptions import ToolError
+
+
+async def call_get(
+    client: AsyncClient,
+    url: URL | str,
+    *,
+    params: QueryParamTypes | None = None,
+    headers: HeaderTypes | None = None,
+    cookies: CookieTypes | None = None,
+    auth: AuthTypes | UseClientDefault | None = USE_CLIENT_DEFAULT,
+    follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,
+    timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,
+    extensions: RequestExtensions | None = None,
+) -> Response:
+    logger.debug(f"Calling GET '{url}' params: '{params}'")
+    try:
+        response = await client.get(
+            url,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            auth=auth,
+            follow_redirects=follow_redirects,
+            timeout=timeout,
+            extensions=extensions,
+        )
+        response.raise_for_status()
+        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
+
+
+async def call_put(
+    client: AsyncClient,
+    url: URL | str,
+    *,
+    content: RequestContent | None = None,
+    data: RequestData | None = None,
+    files: RequestFiles | None = None,
+    json: typing.Any | None = None,
+    params: QueryParamTypes | None = None,
+    headers: HeaderTypes | None = None,
+    cookies: CookieTypes | None = None,
+    auth: AuthTypes | UseClientDefault = USE_CLIENT_DEFAULT,
+    follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,
+    timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,
+    extensions: RequestExtensions | None = None,
+) -> Response:
+    try:
+        response = await client.put(
+            url,
+            content=content,
+            data=data,
+            files=files,
+            json=json,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            auth=auth,
+            follow_redirects=follow_redirects,
+            timeout=timeout,
+            extensions=extensions,
+        )
+        response.raise_for_status()
+        return response
+    except HTTPStatusError as e:
+        logger.error(f"Error calling PUT {url}: {e}")
+        raise ToolError(f"Error calling tool: {e}") from e
+
+
+async def call_post(
+    client: AsyncClient,
+    url: URL | str,
+    *,
+    content: RequestContent | None = None,
+    data: RequestData | None = None,
+    files: RequestFiles | None = None,
+    json: typing.Any | None = None,
+    params: QueryParamTypes | None = None,
+    headers: HeaderTypes | None = None,
+    cookies: CookieTypes | None = None,
+    auth: AuthTypes | UseClientDefault = USE_CLIENT_DEFAULT,
+    follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,
+    timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,
+    extensions: RequestExtensions | None = None,
+) -> Response:
+    try:
+        response = await client.post(
+            url=url,
+            content=content,
+            data=data,
+            files=files,
+            json=json,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            auth=auth,
+            follow_redirects=follow_redirects,
+            timeout=timeout,
+            extensions=extensions,
+        )
+        response.raise_for_status()
+        return response
+    except HTTPStatusError as e:
+        logger.error(f"Error calling POST {url}: {e}")
+        raise ToolError(f"Error calling tool: {e}") from e
+
+
+async def call_delete(
+    client: AsyncClient,
+    url: URL | str,
+    *,
+    params: QueryParamTypes | None = None,
+    headers: HeaderTypes | None = None,
+    cookies: CookieTypes | None = None,
+    auth: AuthTypes | UseClientDefault = USE_CLIENT_DEFAULT,
+    follow_redirects: bool | UseClientDefault = USE_CLIENT_DEFAULT,
+    timeout: TimeoutTypes | UseClientDefault = USE_CLIENT_DEFAULT,
+    extensions: RequestExtensions | None = None,
+) -> Response:
+    try:
+        response = await client.delete(
+            url=url,
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            auth=auth,
+            follow_redirects=follow_redirects,
+            timeout=timeout,
+            extensions=extensions,
+        )
+        response.raise_for_status()
+        return response
+    except HTTPStatusError as e:
+        logger.error(f"Error calling DELETE {url}: {e}")
+        raise ToolError(f"Error calling tool: {e}") from e

basic_memory/models/__init__.py

@@ -0,0 +1,12 @@
+"""Models package for basic-memory."""
+
+from basic_memory.models.base import Base
+from basic_memory.models.knowledge import Entity, Observation, Relation, ObservationCategory
+
+__all__ = [
+    'Base',
+    'Entity',
+    'Observation', 
+    'ObservationCategory', 
+    'Relation'
+]

basic_memory/models/base.py

@@ -0,0 +1,9 @@
+"""Base model class for SQLAlchemy models."""
+
+from sqlalchemy.ext.asyncio import AsyncAttrs
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(AsyncAttrs, DeclarativeBase):
+    """Base class for all models"""
+    pass