basic-memory 0.17.1__py3-none-any.whl

basic_memory/mcp/prompts/recent_activity.py

@@ -0,0 +1,188 @@
+"""Recent activity prompts for Basic Memory MCP server.
+
+These prompts help users see what has changed in their knowledge base recently.
+"""
+
+from typing import Annotated, Optional
+
+from loguru import logger
+from pydantic import Field
+
+from basic_memory.mcp.prompts.utils import format_prompt_context, PromptContext, PromptContextItem
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.recent_activity import recent_activity
+from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.memory import GraphContext, ProjectActivitySummary
+from basic_memory.schemas.search import SearchItemType
+
+
+@mcp.prompt(
+    name="recent_activity",
+    description="Get recent activity from a specific project or across all projects",
+)
+async def recent_activity_prompt(
+    timeframe: Annotated[
+        TimeFrame,
+        Field(description="How far back to look for activity (e.g. '1d', '1 week')"),
+    ] = "7d",
+    project: Annotated[
+        Optional[str],
+        Field(
+            description="Specific project to get activity from (None for discovery across all projects)"
+        ),
+    ] = None,
+) -> str:
+    """Get recent activity from a specific project or across all projects.
+
+    This prompt helps you see what's changed recently in the knowledge base.
+    In discovery mode (project=None), it shows activity across all projects.
+    In project-specific mode, it shows detailed activity for one project.
+
+    Args:
+        timeframe: How far back to look for activity (e.g. '1d', '1 week')
+        project: Specific project to get activity from (None for discovery across all projects)
+
+    Returns:
+        Formatted summary of recent activity
+    """
+    logger.info(f"Getting recent activity, timeframe: {timeframe}, project: {project}")
+
+    recent = await recent_activity.fn(
+        project=project, timeframe=timeframe, type=[SearchItemType.ENTITY]
+    )
+
+    # Extract primary results from the hierarchical structure
+    primary_results = []
+    related_results = []
+
+    if isinstance(recent, ProjectActivitySummary):
+        # Discovery mode - extract results from all projects
+        for _, project_activity in recent.projects.items():
+            if project_activity.activity.results:
+                # Take up to 2 primary results per project
+                for item in project_activity.activity.results[:2]:
+                    primary_results.append(item.primary_result)
+                    # Add up to 1 related result per primary item
+                    if item.related_results:
+                        related_results.extend(item.related_results[:1])
+
+        # Limit total results for readability
+        primary_results = primary_results[:8]
+        related_results = related_results[:6]
+
+    elif isinstance(recent, GraphContext):
+        # Project-specific mode - use existing logic
+        if recent.results:
+            # Take up to 5 primary results
+            for item in recent.results[:5]:
+                primary_results.append(item.primary_result)
+                # Add up to 2 related results per primary item
+                if item.related_results:
+                    related_results.extend(item.related_results[:2])
+
+    # Set topic based on mode
+    if project:
+        topic = f"Recent Activity in {project} ({timeframe})"
+    else:
+        topic = f"Recent Activity Across All Projects ({timeframe})"
+
+    prompt_context = format_prompt_context(
+        PromptContext(
+            topic=topic,
+            timeframe=timeframe,
+            results=[
+                PromptContextItem(
+                    primary_results=primary_results,
+                    related_results=related_results[:10],  # Limit total related results
+                )
+            ],
+        )
+    )
+
+    # Add mode-specific suggestions
+    first_title = "Recent Topic"
+    if primary_results and len(primary_results) > 0:
+        first_title = primary_results[0].title
+
+    if project:
+        # Project-specific suggestions
+        capture_suggestions = f"""
+    ## Opportunity to Capture Activity Summary
+
+    Consider creating a summary note of recent activity in {project}:
+
+    ```python
+    await write_note(
+        "{project}",
+        title="Activity Summary {timeframe}",
+        content='''
+        # Activity Summary for {project} ({timeframe})
+
+        ## Overview
+        [Summary of key changes and developments in this project over this period]
+
+        ## Key Updates
+        [List main updates and their significance within this project]
+
+        ## Observations
+        - [trend] [Observation about patterns in recent activity]
+        - [insight] [Connection between different activities]
+
+        ## Relations
+        - summarizes [[{first_title}]]
+        - relates_to [[{project} Overview]]
+        ''',
+        folder="summaries"
+    )
+    ```
+
+    Summarizing periodic activity helps create high-level insights and connections within the project.
+    """
+    else:
+        # Discovery mode suggestions
+        project_count = len(recent.projects) if isinstance(recent, ProjectActivitySummary) else 0
+        most_active = (
+            getattr(recent.summary, "most_active_project", "Unknown")
+            if isinstance(recent, ProjectActivitySummary)
+            else "Unknown"
+        )
+
+        capture_suggestions = f"""
+    ## Cross-Project Activity Discovery
+
+    Found activity across {project_count} projects. Most active: **{most_active}**
+
+    Consider creating a cross-project summary:
+
+    ```python
+    await write_note(
+        "{most_active if most_active != "Unknown" else "main"}",
+        title="Cross-Project Activity Summary {timeframe}",
+        content='''
+        # Cross-Project Activity Summary ({timeframe})
+
+        ## Overview
+        Activity found across {project_count} projects, with {most_active} showing the most activity.
+
+        ## Key Developments
+        [Summarize important changes across all projects]
+
+        ## Project Insights
+        [Note patterns or connections between projects]
+
+        ## Observations
+        - [trend] [Cross-project patterns observed]
+        - [insight] [Connections between different project activities]
+
+        ## Relations
+        - summarizes [[{first_title}]]
+        - relates_to [[Project Portfolio Overview]]
+        ''',
+        folder="summaries"
+    )
+    ```
+
+    Cross-project summaries help identify broader trends and project interconnections.
+    """
+
+    return prompt_context + capture_suggestions

basic_memory/mcp/prompts/search.py

@@ -0,0 +1,57 @@
+"""Search prompts for Basic Memory MCP server.
+
+These prompts help users search and explore their knowledge base.
+"""
+
+from typing import Annotated, Optional
+
+from loguru import logger
+from pydantic import Field
+
+from basic_memory.config import get_project_config
+from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.utils import call_post
+from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.prompt import SearchPromptRequest
+
+
+@mcp.prompt(
+    name="search_knowledge_base",
+    description="Search across all content in basic-memory",
+)
+async def search_prompt(
+    query: str,
+    timeframe: Annotated[
+        Optional[TimeFrame],
+        Field(description="How far back to search (e.g. '1d', '1 week')"),
+    ] = None,
+) -> str:
+    """Search across all content in basic-memory.
+
+    This prompt helps search for content in the knowledge base and
+    provides helpful context about the results.
+
+    Args:
+        query: The search text to look for
+        timeframe: Optional timeframe to limit results (e.g. '1d', '1 week')
+
+    Returns:
+        Formatted search results with context
+    """
+    logger.info(f"Searching knowledge base, query: {query}, timeframe: {timeframe}")
+
+    async with get_client() as client:
+        # Create request model
+        request = SearchPromptRequest(query=query, timeframe=timeframe)
+
+        project_url = get_project_config().project_url
+
+        # Call the prompt API endpoint
+        response = await call_post(
+            client, f"{project_url}/prompt/search", json=request.model_dump(exclude_none=True)
+        )
+
+        # Extract the rendered prompt from the response
+        result = response.json()
+        return result["prompt"]

basic_memory/mcp/prompts/utils.py

@@ -0,0 +1,162 @@
+"""Utility functions for formatting prompt responses.
+
+These utilities help format data from various tools into consistent,
+user-friendly markdown summaries.
+"""
+
+from dataclasses import dataclass
+from textwrap import dedent
+from typing import List
+
+from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.memory import (
+    normalize_memory_url,
+    EntitySummary,
+    RelationSummary,
+    ObservationSummary,
+)
+
+
+@dataclass
+class PromptContextItem:
+    primary_results: List[EntitySummary]
+    related_results: List[EntitySummary | RelationSummary | ObservationSummary]
+
+
+@dataclass
+class PromptContext:
+    timeframe: TimeFrame
+    topic: str
+    results: List[PromptContextItem]
+
+
+def format_prompt_context(context: PromptContext) -> str:
+    """Format continuation context into a helpful summary.
+    Returns:
+        Formatted continuation summary
+    """
+    if not context.results:  # pragma: no cover
+        return dedent(f"""
+            # Continuing conversation on: {context.topic}
+
+            This is a memory retrieval session. 
+            The supplied query did not return any information specifically on this topic.
+            
+            ## Opportunity to Capture New Knowledge!
+            
+            This is an excellent chance to start documenting this topic:
+            
+            ```python
+            await write_note(
+                title="{context.topic}",
+                content=f'''
+                # {context.topic}
+                
+                ## Overview
+                [Summary of what we know about {context.topic}]
+                
+                ## Key Points
+                [Main aspects or components of {context.topic}]
+                
+                ## Observations
+                - [category] [First important observation about {context.topic}]
+                - [category] [Second observation about {context.topic}]
+                
+                ## Relations
+                - relates_to [[Related Topic]]
+                - part_of [[Broader Context]]
+                '''
+            )
+            ```
+            
+            ## Other Options
+            
+            Please use the available basic-memory tools to gather relevant context before responding.
+            You can also:
+            - Try a different search term
+            - Check recent activity with `recent_activity(timeframe="1w")`
+            """)
+
+    # Start building our summary with header - add knowledge capture emphasis
+    summary = dedent(f"""
+        # Continuing conversation on: {context.topic}
+
+        This is a memory retrieval session. 
+        
+        Please use the available basic-memory tools to gather relevant context before responding. 
+        Start by executing one of the suggested commands below to retrieve content.
+
+        Here's what I found from previous conversations:
+        
+        > **Knowledge Capture Recommendation:** As you continue this conversation, actively look for opportunities to record new information, decisions, or insights that emerge. Use `write_note()` to document important context.
+        """)
+
+    # Track what we've added to avoid duplicates
+    added_permalinks = set()
+    sections = []
+
+    # Process each context
+    for context in context.results:  # pyright: ignore
+        for primary in context.primary_results:  # pyright: ignore
+            if primary.permalink not in added_permalinks:
+                primary_permalink = primary.permalink
+
+                added_permalinks.add(primary_permalink)
+
+                # Use permalink if available, otherwise use file_path
+                if primary_permalink:
+                    memory_url = normalize_memory_url(primary_permalink)
+                    read_command = f'read_note("{primary_permalink}")'
+                else:
+                    memory_url = f"file://{primary.file_path}"
+                    read_command = f'read_file("{primary.file_path}")'
+
+                section = dedent(f"""
+                    --- {memory_url}
+
+                    ## {primary.title}
+                    - **Type**: {primary.type}
+                    """)
+
+                # Add creation date
+                section += f"- **Created**: {primary.created_at.strftime('%Y-%m-%d %H:%M')}\n"
+
+                # Add content snippet
+                if hasattr(primary, "content") and primary.content:  # pyright: ignore
+                    content = primary.content or ""  # pyright: ignore
+                    if content:
+                        section += f"\n**Excerpt**:\n{content}\n"
+
+                section += dedent(f"""
+
+                    You can read this document with: `{read_command}`
+                    """)
+                sections.append(section)
+
+        if context.related_results:  # pyright: ignore
+            section += dedent(  # pyright: ignore
+                """   
+                ## Related Context
+                """
+            )
+
+            for related in context.related_results:  # pyright: ignore
+                section_content = dedent(f"""
+                    - type: **{related.type}**
+                    - title: {related.title}
+                    """)
+                if related.permalink:  # pragma: no cover
+                    section_content += (
+                        f'You can view this document with: `read_note("{related.permalink}")`'
+                    )
+                else:  # pragma: no cover
+                    section_content += (
+                        f'You can view this file with: `read_file("{related.file_path}")`'
+                    )
+
+                section += section_content
+                sections.append(section)
+
+    # Add all sections
+    summary += "\n".join(sections)
+    return summary

basic_memory/mcp/resources/ai_assistant_guide.md

@@ -0,0 +1,283 @@
+# AI Assistant Guide for Basic Memory
+
+Quick reference for using Basic Memory tools effectively through MCP.
+
+**For comprehensive coverage**: See the [Extended AI Assistant Guide](https://github.com/basicmachines-co/basic-memory/blob/main/docs/ai-assistant-guide-extended.md) with detailed examples, advanced patterns, and self-contained sections.
+
+## Overview
+
+Basic Memory creates a semantic knowledge graph from markdown files. Focus on building rich connections between notes.
+
+- **Local-First**: Plain text files on user's computer
+- **Persistent**: Knowledge survives across sessions
+- **Semantic**: Observations and relations create a knowledge graph
+
+**Your role**: You're helping humans build enduring knowledge they'll own forever. The semantic graph (observations, relations, context) helps you provide better assistance by understanding connections and maintaining continuity. Think: lasting insights worth keeping, not disposable chat logs.
+
+## Project Management 
+
+All tools require explicit project specification.
+
+**Three-tier resolution:**
+1. CLI constraint: `--project name` (highest priority)
+2. Explicit parameter: `project="name"` in tool calls
+3. Default mode: `default_project_mode=true` in config (fallback)
+
+### Quick Setup Check
+
+```python
+# Discover projects
+projects = await list_memory_projects()
+
+# Check if default_project_mode enabled
+# If yes: project parameter optional
+# If no: project parameter required
+```
+
+### Default Project Mode
+
+When `default_project_mode=true`:
+```python
+# These are equivalent:
+await write_note("Note", "Content", "folder")
+await write_note("Note", "Content", "folder", project="main")
+```
+
+When `default_project_mode=false` (default):
+```python
+# Project required:
+await write_note("Note", "Content", "folder", project="main")  # ✓
+await write_note("Note", "Content", "folder")  # ✗ Error
+```
+
+## Core Tools
+
+### Writing Knowledge
+
+```python
+await write_note(
+    title="Topic",
+    content="# Topic\n## Observations\n- [category] fact\n## Relations\n- relates_to [[Other]]",
+    folder="notes",
+    project="main"  # Required unless default_project_mode=true
+)
+```
+
+### Reading Knowledge
+
+```python
+# By identifier
+content = await read_note("Topic", project="main")
+
+# By memory:// URL
+content = await read_note("memory://folder/topic", project="main")
+```
+
+### Searching
+
+```python
+results = await search_notes(
+    query="authentication",
+    project="main",
+    page_size=10
+)
+```
+
+### Building Context
+
+```python
+context = await build_context(
+    url="memory://specs/auth",
+    project="main",
+    depth=2,
+    timeframe="1 week"
+)
+```
+
+## Knowledge Graph Essentials
+
+### Observations
+
+Categorized facts with optional tags:
+```markdown
+- [decision] Use JWT for authentication #security
+- [technique] Hash passwords with bcrypt #best-practice
+- [requirement] Support OAuth 2.0 providers
+```
+
+### Relations
+
+Directional links between entities:
+```markdown
+- implements [[Authentication Spec]]
+- requires [[User Database]]
+- extends [[Base Security Model]]
+```
+
+**Common relation types:** `relates_to`, `implements`, `requires`, `extends`, `part_of`, `contrasts_with`
+
+### Forward References
+
+Reference entities that don't exist yet:
+```python
+# Create note with forward reference
+await write_note(
+    title="Login Flow",
+    content="## Relations\n- requires [[OAuth Provider]]",  # Doesn't exist yet
+    folder="auth",
+    project="main"
+)
+
+# Later, create referenced entity
+await write_note(
+    title="OAuth Provider",
+    content="# OAuth Provider\n...",
+    folder="auth",
+    project="main"
+)
+# → Relation automatically resolved
+```
+
+## Best Practices
+
+### 1. Project Management
+
+**Single-project users:**
+- Enable `default_project_mode=true`
+- Simpler tool calls
+
+**Multi-project users:**
+- Keep `default_project_mode=false`
+- Always specify project explicitly
+
+**Discovery:**
+```python
+# Start with discovery
+projects = await list_memory_projects()
+
+# Cross-project activity (no project param = all projects)
+activity = await recent_activity()
+
+# Or specific project
+activity = await recent_activity(project="main")
+```
+
+### 2. Building Rich Graphs
+
+**Always include:**
+- 3-5 observations per note
+- 2-3 relations per note
+- Meaningful categories and relation types
+
+**Search before creating:**
+```python
+# Find existing entities to reference
+results = await search_notes(query="authentication", project="main")
+# Use exact titles in [[WikiLinks]]
+```
+
+### 3. Writing Effective Notes
+
+**Structure:**
+```markdown
+# Title
+
+## Context
+Background information
+
+## Observations
+- [category] Fact with #tags
+- [category] Another fact
+
+## Relations
+- relation_type [[Exact Entity Title]]
+```
+
+**Categories:** `[idea]`, `[decision]`, `[fact]`, `[technique]`, `[requirement]`
+
+### 4. Error Handling
+
+**Missing project:**
+```python
+try:
+    await search_notes(query="test")  # Missing project parameter - will error
+except:
+    # Show available projects
+    projects = await list_memory_projects()
+    # Then retry with project
+    results = await search_notes(query="test", project=projects[0].name)
+```
+
+**Forward references:**
+```python
+# Check response for unresolved relations
+response = await write_note(
+    title="New Topic",
+    content="## Relations\n- relates_to [[Future Topic]]",
+    folder="notes",
+    project="main"
+)
+# Forward refs will resolve when target created
+```
+
+### 5. Recording Context
+
+**Ask permission:**
+> "Would you like me to save our discussion about [topic] to Basic Memory?"
+
+**Confirm when done:**
+> "I've saved our discussion to Basic Memory."
+
+**What to record:**
+- Decisions and rationales
+- Important discoveries
+- Action items and plans
+- Connected topics
+
+## Common Patterns
+
+### Capture Decision
+
+```python
+await write_note(
+    title="DB Choice",
+    content="""# DB Choice\n## Decision\nUse PostgreSQL\n## Observations\n- [requirement] ACID compliance #reliability\n- [decision] PostgreSQL over MySQL\n## Relations\n- implements [[Data Architecture]]""",
+    folder="decisions",
+    project="main"
+)
+```
+
+### Link Topics & Build Context
+
+```python
+# Link bidirectionally
+await write_note(title="API Auth", content="## Relations\n- part_of [[API Design]]", folder="api", project="main")
+await edit_note(identifier="API Design", operation="append", content="\n- includes [[API Auth]]", project="main")
+
+# Search and build context
+results = await search_notes(query="authentication", project="main")
+context = await build_context(url=f"memory://{results[0].permalink}", project="main", depth=2)
+```
+
+## Tool Quick Reference
+
+| Tool | Purpose | Key Params |
+|------|---------|------------|
+| `write_note` | Create/update | title, content, folder, project |
+| `read_note` | Read content | identifier, project |
+| `edit_note` | Modify existing | identifier, operation, content, project |
+| `search_notes` | Find notes | query, project |
+| `build_context` | Graph traversal | url, depth, project |
+| `recent_activity` | Recent changes | timeframe, project |
+| `list_memory_projects` | Show projects | (none) |
+
+## memory:// URL Format
+
+- `memory://title` - By title
+- `memory://folder/title` - By folder + title
+- `memory://permalink` - By permalink
+- `memory://folder/*` - All in folder
+
+For full documentation: https://docs.basicmemory.com
+
+Built with ♥️ by Basic Machines