basic-memory 0.10.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

basic_memory/mcp/resources/ai_assistant_guide.md

@@ -0,0 +1,413 @@
+# AI Assistant Guide for Basic Memory
+
+This guide helps AIs use Basic Memory tools effectively when working with users. It covers reading, writing, and
+navigating knowledge through the Model Context Protocol (MCP).
+
+## Overview
+
+Basic Memory allows you and users to record context in local Markdown files, building a rich knowledge base through
+natural conversations. The system automatically creates a semantic knowledge graph from simple text patterns.
+
+- **Local-First**: All data is stored in plain text files on the user's computer
+- **Real-Time**: Users see content updates immediately
+- **Bi-Directional**: Both you and users can read and edit notes
+- **Semantic**: Simple patterns create a structured knowledge graph
+- **Persistent**: Knowledge persists across sessions and conversations
+
+## The Importance of the Knowledge Graph
+
+**Basic Memory's value comes from connections between notes, not just the notes themselves.**
+
+When writing notes, your primary goal should be creating a rich, interconnected knowledge graph:
+
+1. **Increase Semantic Density**: Add multiple observations and relations to each note
+2. **Use Accurate References**: Aim to reference existing entities by their exact titles
+3. **Create Forward References**: Feel free to reference entities that don't exist yet - Basic Memory will resolve these
+   when they're created later
+4. **Create Bidirectional Links**: When appropriate, connect entities from both directions
+5. **Use Meaningful Categories**: Add semantic context with appropriate observation categories
+6. **Choose Precise Relations**: Use specific relation types that convey meaning
+
+Remember: A knowledge graph with 10 heavily connected notes is more valuable than 20 isolated notes. Your job is to help
+build these connections!
+
+## Core Tools Reference
+
+```python
+# Writing knowledge - THE MOST IMPORTANT TOOL!
+response = await write_note(
+    title="Search Design",  # Required: Note title
+    content="# Search Design\n...",  # Required: Note content
+    folder="specs",  # Optional: Folder to save in
+    tags=["search", "design"],  # Optional: Tags for categorization
+    verbose=True  # Optional: Get parsing details
+)
+
+# Reading knowledge
+content = await read_note("Search Design")  # By title
+content = await read_note("specs/search-design")  # By path
+content = await read_note("memory://specs/search")  # By memory URL
+
+# Searching for knowledge
+results = await search_notes(
+    query="authentication system",  # Text to search for
+    page=1,  # Optional: Pagination
+    page_size=10  # Optional: Results per page
+)
+
+# Building context from the knowledge graph
+context = await build_context(
+    url="memory://specs/search",  # Starting point
+    depth=2,  # Optional: How many hops to follow
+    timeframe="1 month"  # Optional: Recent timeframe
+)
+
+# Checking recent changes
+activity = await recent_activity(
+    type="all",  # Optional: Entity types to include
+    depth=1,  # Optional: Related items to include
+    timeframe="1 week"  # Optional: Time window
+)
+
+# Creating a knowledge visualization
+canvas_result = await canvas(
+    nodes=[{"id": "note1", "label": "Search Design"}],  # Nodes to display
+    edges=[{"from": "note1", "to": "note2"}],  # Connections
+    title="Project Overview",  # Canvas title
+    folder="diagrams"  # Storage location
+)
+```
+
+## memory:// URLs Explained
+
+Basic Memory uses a special URL format to reference entities in the knowledge graph:
+
+- `memory://title` - Reference by title
+- `memory://folder/title` - Reference by folder and title
+- `memory://permalink` - Reference by permalink
+- `memory://path/relation_type/*` - Follow all relations of a specific type
+- `memory://path/*/target` - Find all entities with relations to target
+
+## Semantic Markdown Format
+
+Knowledge is encoded in standard markdown using simple patterns:
+
+**Observations** - Facts about an entity:
+
+```markdown
+- [category] This is an observation #tag1 #tag2 (optional context)
+```
+
+**Relations** - Links between entities:
+
+```markdown
+- relation_type [[Target Entity]] (optional context)
+```
+
+**Common Categories & Relation Types:**
+
+- Categories: `[idea]`, `[decision]`, `[question]`, `[fact]`, `[requirement]`, `[technique]`, `[recipe]`, `[preference]`
+- Relations: `relates_to`, `implements`, `requires`, `extends`, `part_of`, `pairs_with`, `inspired_by`,
+  `originated_from`
+
+## When to Record Context
+
+**Always consider recording context when**:
+
+1. Users make decisions or reach conclusions
+2. Important information emerges during conversation
+3. Multiple related topics are discussed
+4. The conversation contains information that might be useful later
+5. Plans, tasks, or action items are mentioned
+
+**Protocol for recording context**:
+
+1. Identify valuable information in the conversation
+2. Ask the user: "Would you like me to record our discussion about [topic] in Basic Memory?"
+3. If they agree, use `write_note` to capture the information
+4. If they decline, continue without recording
+5. Let the user know when information has been recorded: "I've saved our discussion about [topic] to Basic Memory."
+
+## Understanding User Interactions
+
+Users will interact with Basic Memory in patterns like:
+
+1. **Creating knowledge**:
+   ```
+   Human: "Let's write up what we discussed about search."
+   
+   You: I'll create a note capturing our discussion about the search functionality.
+   [Use write_note() to record the conversation details]
+   ```
+
+2. **Referencing existing knowledge**:
+   ```
+   Human: "Take a look at memory://specs/search"
+   
+   You: I'll examine that information.
+   [Use build_context() to gather related information]
+   [Then read_note() to access specific content]
+   ```
+
+3. **Finding information**:
+   ```
+   Human: "What were our decisions about auth?"
+   
+   You: Let me find that information for you.
+   [Use search_notes() to find relevant notes]
+   [Then build_context() to understand connections]
+   ```
+
+## Key Things to Remember
+
+1. **Files are Truth**
+    - All knowledge lives in local files on the user's computer
+    - Users can edit files outside your interaction
+    - Changes need to be synced by the user (usually automatic)
+    - Always verify information is current with `recent_activity()`
+
+2. **Building Context Effectively**
+    - Start with specific entities
+    - Follow meaningful relations
+    - Check recent changes
+    - Build context incrementally
+    - Combine related information
+
+3. **Writing Knowledge Wisely**
+    - Using the same title+folder will overwrite existing notes
+    - Structure content with clear headings and sections
+    - Use semantic markup for observations and relations
+    - Keep files organized in logical folders
+
+## Common Knowledge Patterns
+
+### Capturing Decisions
+
+```markdown
+# Coffee Brewing Methods
+
+## Context
+
+I've experimented with various brewing methods including French press, pour over, and espresso.
+
+## Decision
+
+Pour over is my preferred method for light to medium roasts because it highlights subtle flavors and offers more control
+over the extraction.
+
+## Observations
+
+- [technique] Blooming the coffee grounds for 30 seconds improves extraction #brewing
+- [preference] Water temperature between 195-205°F works best #temperature
+- [equipment] Gooseneck kettle provides better control of water flow #tools
+
+## Relations
+
+- pairs_with [[Light Roast Beans]]
+- contrasts_with [[French Press Method]]
+- requires [[Proper Grinding Technique]]
+```
+
+### Recording Project Structure
+
+```markdown
+# Garden Planning
+
+## Overview
+
+This document outlines the garden layout and planting strategy for this season.
+
+## Observations
+
+- [structure] Raised beds in south corner for sun exposure #layout
+- [structure] Drip irrigation system installed for efficiency #watering
+- [pattern] Companion planting used to deter pests naturally #technique
+
+## Relations
+
+- contains [[Vegetable Section]]
+- contains [[Herb Garden]]
+- implements [[Organic Gardening Principles]]
+```
+
+### Technical Discussions
+
+```markdown
+# Recipe Improvement Discussion
+
+## Key Points
+
+Discussed strategies for improving the chocolate chip cookie recipe.
+
+## Observations
+
+- [issue] Cookies spread too thin when baked at 350°F #texture
+- [solution] Chilling dough for 24 hours improves flavor and reduces spreading #technique
+- [decision] Will use brown butter instead of regular butter #flavor
+
+## Relations
+
+- improves [[Basic Cookie Recipe]]
+- inspired_by [[Bakery-Style Cookies]]
+- pairs_with [[Homemade Ice Cream]]
+```
+
+### Creating Effective Relations
+
+When creating relations, you can:
+
+1. Reference existing entities by their exact title
+2. Create forward references to entities that don't exist yet
+
+```python
+# Example workflow for creating notes with effective relations
+async def create_note_with_effective_relations():
+    # Search for existing entities to reference
+    search_results = await search_notes("travel")
+    existing_entities = [result.title for result in search_results.primary_results]
+
+    # Check if specific entities exist
+    packing_tips_exists = "Packing Tips" in existing_entities
+    japan_travel_exists = "Japan Travel Guide" in existing_entities
+
+    # Prepare relations section - include both existing and forward references
+    relations_section = "## Relations\n"
+
+    # Existing reference - exact match to known entity
+    if packing_tips_exists:
+        relations_section += "- references [[Packing Tips]]\n"
+    else:
+        # Forward reference - will be linked when that entity is created later
+        relations_section += "- references [[Packing Tips]]\n"
+
+    # Another possible reference
+    if japan_travel_exists:
+        relations_section += "- part_of [[Japan Travel Guide]]\n"
+
+    # You can also check recently modified notes to reference them
+    recent = await recent_activity(timeframe="1 week")
+    recent_titles = [item.title for item in recent.primary_results]
+
+    if "Transportation Options" in recent_titles:
+        relations_section += "- relates_to [[Transportation Options]]\n"
+
+    # Always include meaningful forward references, even if they don't exist yet
+    relations_section += "- located_in [[Tokyo]]\n"
+    relations_section += "- visited_during [[Spring 2023 Trip]]\n"
+
+    # Now create the note with both verified and forward relations
+    content = f"""# Tokyo Neighborhood Guide
+    
+## Overview
+Details about different Tokyo neighborhoods and their unique characteristics.
+
+## Observations
+- [area] Shibuya is a busy shopping district #shopping
+- [transportation] Yamanote Line connects major neighborhoods #transit
+- [recommendation] Visit Shimokitazawa for vintage shopping #unique
+- [tip] Get a Suica card for easy train travel #convenience
+
+{relations_section}
+    """
+
+    result = await write_note(
+        title="Tokyo Neighborhood Guide",
+        content=content,
+        verbose=True
+    )
+
+    # You can check which relations were resolved and which are forward references
+    if result and 'relations' in result:
+        resolved = [r['to_name'] for r in result['relations'] if r.get('target_id')]
+        forward_refs = [r['to_name'] for r in result['relations'] if not r.get('target_id')]
+
+        print(f"Resolved relations: {resolved}")
+        print(f"Forward references that will be resolved later: {forward_refs}")
+```
+
+## Error Handling
+
+Common issues to watch for:
+
+1. **Missing Content**
+   ```python
+   try:
+       content = await read_note("Document")
+   except:
+       # Try search instead
+       results = await search_notes("Document")
+       if results and results.primary_results:
+           # Found something similar
+           content = await read_note(results.primary_results[0].permalink)
+   ```
+
+2. **Forward References (Unresolved Relations)**
+   ```python
+   response = await write_note(..., verbose=True)
+   # Check for forward references (unresolved relations)
+   forward_refs = []
+   for relation in response.get('relations', []):
+       if not relation.get('target_id'):
+           forward_refs.append(relation.get('to_name'))
+   
+   if forward_refs:
+       # This is a feature, not an error! Inform the user about forward references
+       print(f"Note created with forward references to: {forward_refs}")
+       print("These will be automatically linked when those notes are created.")
+       
+       # Optionally suggest creating those entities now
+       print("Would you like me to create any of these notes now to complete the connections?")
+   ```
+
+3. **Sync Issues**
+   ```python
+   # If information seems outdated
+   activity = await recent_activity(timeframe="1 hour")
+   if not activity or not activity.primary_results:
+       print("It seems there haven't been recent updates. You might need to run 'basic-memory sync'.")
+   ```
+
+## Best Practices
+
+1. **Proactively Record Context**
+    - Offer to capture important discussions
+    - Record decisions, rationales, and conclusions
+    - Link to related topics
+    - Ask for permission first: "Would you like me to save our discussion about [topic]?"
+    - Confirm when complete: "I've saved our discussion to Basic Memory"
+
+2. **Create a Rich Semantic Graph**
+    - **Add meaningful observations**: Include at least 3-5 categorized observations in each note
+    - **Create deliberate relations**: Connect each note to at least 2-3 related entities
+    - **Use existing entities**: Before creating a new relation, search for existing entities
+    - **Verify wikilinks**: When referencing `[[Entity]]`, use exact titles of existing notes
+    - **Check accuracy**: Use `search_notes()` or `recent_activity()` to confirm entity titles
+    - **Use precise relation types**: Choose specific relation types that convey meaning (e.g., "implements" instead
+      of "relates_to")
+    - **Consider bidirectional relations**: When appropriate, create inverse relations in both entities
+
+3. **Structure Content Thoughtfully**
+    - Use clear, descriptive titles
+    - Organize with logical sections (Context, Decision, Implementation, etc.)
+    - Include relevant context and background
+    - Add semantic observations with appropriate categories
+    - Use a consistent format for similar types of notes
+    - Balance detail with conciseness
+
+4. **Navigate Knowledge Effectively**
+    - Start with specific searches
+    - Follow relation paths
+    - Combine information from multiple sources
+    - Verify information is current
+    - Build a complete picture before responding
+
+5. **Help Users Maintain Their Knowledge**
+    - Suggest organizing related topics
+    - Identify potential duplicates
+    - Recommend adding relations between topics
+    - Offer to create summaries of scattered information
+    - Suggest potential missing relations: "I notice this might relate to [topic], would you like me to add that
+      connection?"
+
+Built with ♥️ b
+y Basic Machines

basic_memory/mcp/tools/__init__.py

@@ -12,7 +12,7 @@ from basic_memory.mcp.tools.build_context import build_context
 from basic_memory.mcp.tools.recent_activity import recent_activity
 from basic_memory.mcp.tools.read_note import read_note
 from basic_memory.mcp.tools.write_note import write_note
-from basic_memory.mcp.tools.search import search
+from basic_memory.mcp.tools.search import search_notes
 from basic_memory.mcp.tools.canvas import canvas
 
 __all__ = [
@@ -22,6 +22,6 @@ __all__ = [
     "read_content",
     "read_note",
     "recent_activity",
-    "search",
+    "search_notes",
     "write_note",
 ]

basic_memory/mcp/tools/read_note.py

@@ -6,7 +6,7 @@ from loguru import logger
 
 from basic_memory.mcp.async_client import client
 from basic_memory.mcp.server import mcp
-from basic_memory.mcp.tools.search import search
+from basic_memory.mcp.tools.search import search_notes
 from basic_memory.mcp.tools.utils import call_get
 from basic_memory.schemas.memory import memory_url_path
 from basic_memory.schemas.search import SearchQuery
@@ -63,7 +63,7 @@ async def read_note(identifier: str, page: int = 1, page_size: int = 10) -> str:
 
     # Fallback 1: Try title search via API
     logger.info(f"Search title for: {identifier}")
-    title_results = await search(SearchQuery(title=identifier))
+    title_results = await search_notes(SearchQuery(title=identifier))
 
     if title_results and title_results.results:
         result = title_results.results[0]  # Get the first/best match
@@ -87,7 +87,7 @@ async def read_note(identifier: str, page: int = 1, page_size: int = 10) -> str:
 
     # Fallback 2: Text search as a last resort
     logger.info(f"Title search failed, trying text search for: {identifier}")
-    text_results = await search(SearchQuery(text=identifier))
+    text_results = await search_notes(SearchQuery(text=identifier))
 
     # We didn't find a direct match, construct a helpful error message
     if not text_results or not text_results.results:

basic_memory/mcp/tools/search.py

@@ -9,10 +9,10 @@ from basic_memory.mcp.async_client import client
 
 
 @mcp.tool(
-    description="Search across all content in basic-memory, including documents and entities",
+    description="Search across all content in the knowledge base.",
 )
-async def search(query: SearchQuery, page: int = 1, page_size: int = 10) -> SearchResponse:
-    """Search across all content in basic-memory.
+async def search_notes(query: SearchQuery, page: int = 1, page_size: int = 10) -> SearchResponse:
+    """Search across all content in the knowledge base.
 
     This tool searches the knowledge base using full-text search, pattern matching,
     or exact permalink lookup. It supports filtering by content type, entity type,
@@ -36,34 +36,34 @@ async def search(query: SearchQuery, page: int = 1, page_size: int = 10) -> Sear
 
     Examples:
         # Basic text search
-        results = await search(SearchQuery(text="project planning"))
+        results = await search_notes(SearchQuery(text="project planning"))
 
         # Boolean AND search (both terms must be present)
-        results = await search(SearchQuery(text="project AND planning"))
+        results = await search_notes(SearchQuery(text="project AND planning"))
 
         # Boolean OR search (either term can be present)
-        results = await search(SearchQuery(text="project OR meeting"))
+        results = await search_notes(SearchQuery(text="project OR meeting"))
 
         # Boolean NOT search (exclude terms)
-        results = await search(SearchQuery(text="project NOT meeting"))
+        results = await search_notes(SearchQuery(text="project NOT meeting"))
 
         # Boolean search with grouping
-        results = await search(SearchQuery(text="(project OR planning) AND notes"))
+        results = await search_notes(SearchQuery(text="(project OR planning) AND notes"))
 
         # Search with type filter
-        results = await search(SearchQuery(
+        results = await search_notes(SearchQuery(
             text="meeting notes",
             types=["entity"],
         ))
 
         # Search for recent content
-        results = await search(SearchQuery(
+        results = await search_notes(SearchQuery(
             text="bug report",
             after_date="1 week"
         ))
 
         # Pattern matching on permalinks
-        results = await search(SearchQuery(
+        results = await search_notes(SearchQuery(
             permalink_match="docs/meeting-*"
         ))
     """

basic_memory/mcp/tools/write_note.py

@@ -1,6 +1,6 @@
 """Write note tool for Basic Memory MCP server."""
 
-from typing import Optional, List
+from typing import List, Union
 
 from loguru import logger
 
@@ -9,6 +9,13 @@ from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_put
 from basic_memory.schemas import EntityResponse
 from basic_memory.schemas.base import Entity
+from basic_memory.utils import parse_tags
+
+# Define TagType as a Union that can accept either a string or a list of strings or None
+TagType = Union[List[str], str, None]
+
+# Define TagType as a Union that can accept either a string or a list of strings or None
+TagType = Union[List[str], str, None]
 
 
 @mcp.tool(
@@ -18,7 +25,7 @@ async def write_note(
     title: str,
     content: str,
     folder: str,
-    tags: Optional[List[str]] = None,
+    tags=None,  # Remove type hint completely to avoid schema issues
 ) -> str:
     """Write a markdown note to the knowledge base.
 
@@ -40,13 +47,14 @@ async def write_note(
         Examples:
         `- depends_on [[Content Parser]] (Need for semantic extraction)`
         `- implements [[Search Spec]] (Initial implementation)`
-        `- This feature extends [[Base Design]] and uses [[Core Utils]]`
+        `- This feature extends [[Base Design]] andst 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
+        tags: Tags to categorize the note. Can be a list of strings, a comma-separated string, or None.
+              Note: If passing from external MCP clients, use a string format (e.g. "tag1,tag2,tag3")
 
     Returns:
         A markdown formatted summary of the semantic content, including:
@@ -58,8 +66,10 @@ async def write_note(
     """
     logger.info("MCP tool call", tool="write_note", folder=folder, title=title, tags=tags)
 
+    # Process tags using the helper function
+    tag_list = parse_tags(tags)
     # Create the entity request
-    metadata = {"tags": [f"#{tag}" for tag in tags]} if tags else None
+    metadata = {"tags": [f"#{tag}" for tag in tag_list]} if tag_list else None
     entity = Entity(
         title=title,
         folder=folder,
@@ -105,8 +115,8 @@ async def write_note(
             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)}")
+    if tag_list:
+        summary.append(f"\n## Tags\n- {', '.join(tag_list)}")
 
     # Log the response with structured data
     logger.info(

basic_memory/services/entity_service.py

@@ -141,10 +141,20 @@ class EntityService(BaseService[EntityModel]):
         # Convert file path string to Path
         file_path = Path(entity.file_path)
 
+        # Read existing frontmatter from the file if it exists
+        existing_markdown = await self.entity_parser.parse_file(file_path)
+
+        # Create post with new content from schema
         post = await schema_to_markdown(schema)
 
+        # Merge new metadata with existing metadata
+        existing_markdown.frontmatter.metadata.update(post.metadata)
+
+        # Create a new post with merged metadata
+        merged_post = frontmatter.Post(post.content, **existing_markdown.frontmatter.metadata)
+
         # write file
-        final_content = frontmatter.dumps(post, sort_keys=False)
+        final_content = frontmatter.dumps(merged_post, sort_keys=False)
         checksum = await self.file_service.write_file(file_path, final_content)
 
         # parse entity from file

basic_memory/sync/watch_service.py

@@ -351,4 +351,4 @@ class WatchService:
             duration_ms=duration_ms,
         )
 
-        await self.write_status()
+        await self.write_status()

basic_memory/utils.py

@@ -6,7 +6,7 @@ import logging
 import re
 import sys
 from pathlib import Path
-from typing import Optional, Protocol, Union, runtime_checkable
+from typing import Optional, Protocol, Union, runtime_checkable, List
 
 from loguru import logger
 from unidecode import unidecode
@@ -128,3 +128,29 @@ def setup_logging(
     # Set log levels for noisy loggers
     for logger_name, level in noisy_loggers.items():
         logging.getLogger(logger_name).setLevel(level)
+
+
+def parse_tags(tags: Union[List[str], str, None]) -> List[str]:
+    """Parse tags from various input formats into a consistent list.
+
+    Args:
+        tags: Can be a list of strings, a comma-separated string, or None
+
+    Returns:
+        A list of tag strings, or an empty list if no tags
+    """
+    if tags is None:
+        return []
+
+    if isinstance(tags, list):
+        return tags
+
+    if isinstance(tags, str):
+        return [tag.strip() for tag in tags.split(",") if tag.strip()]
+
+    # For any other type, try to convert to string and parse
+    try:  # pragma: no cover
+        return parse_tags(str(tags))
+    except (ValueError, TypeError):  # pragma: no cover
+        logger.warning(f"Couldn't parse tags from input of type {type(tags)}: {tags}")
+        return []