basic-memory 0.14.4__py3-none-any.whl → 0.15.1__py3-none-any.whl

basic_memory/mcp/resources/ai_assistant_guide.md

@@ -1,413 +1,283 @@
 # 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).
+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 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.
+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
 
-- **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
+**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.
 
-## The Importance of the Knowledge Graph
+## Project Management 
 
-**Basic Memory's value comes from connections between notes, not just the notes themselves.**
+All tools require explicit project specification.
 
-When writing notes, your primary goal should be creating a rich, interconnected knowledge graph:
+**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)
 
-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
+### Quick Setup Check
 
-Remember: A knowledge graph with 10 heavily connected notes is more valuable than 20 isolated notes. Your job is to help
-build these connections!
+```python
+# Discover projects
+projects = await list_memory_projects()
+
+# Check if default_project_mode enabled
+# If yes: project parameter optional
+# If no: project parameter required
+```
 
-## Core Tools Reference
+### Default Project Mode
 
+When `default_project_mode=true`:
 ```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
-)
+# 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
+```
 
-# 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
+## Core Tools
 
-# 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
-)
+### Writing Knowledge
 
-# 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
+```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
 )
+```
 
-# 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
-)
+### Reading Knowledge
 
-# 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
-)
+```python
+# By identifier
+content = await read_note("Topic", project="main")
+
+# By memory:// URL
+content = await read_note("memory://folder/topic", project="main")
 ```
 
-## memory:// URLs Explained
+### Searching
 
-Basic Memory uses a special URL format to reference entities in the knowledge graph:
+```python
+results = await search_notes(
+    query="authentication",
+    project="main",
+    page_size=10
+)
+```
 
-- `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
+### Building Context
 
-## Semantic Markdown Format
+```python
+context = await build_context(
+    url="memory://specs/auth",
+    project="main",
+    depth=2,
+    timeframe="1 week"
+)
+```
 
-Knowledge is encoded in standard markdown using simple patterns:
+## Knowledge Graph Essentials
 
-**Observations** - Facts about an entity:
+### Observations
 
+Categorized facts with optional tags:
 ```markdown
-- [category] This is an observation #tag1 #tag2 (optional context)
+- [decision] Use JWT for authentication #security
+- [technique] Hash passwords with bcrypt #best-practice
+- [requirement] Support OAuth 2.0 providers
 ```
 
-**Relations** - Links between entities:
+### Relations
 
+Directional links between entities:
 ```markdown
-- relation_type [[Target Entity]] (optional context)
+- implements [[Authentication Spec]]
+- requires [[User Database]]
+- extends [[Base Security Model]]
 ```
 
-**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
+**Common relation types:** `relates_to`, `implements`, `requires`, `extends`, `part_of`, `contrasts_with`
 
-```markdown
-# Coffee Brewing Methods
+### Forward References
 
-## Context
+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"
+)
 
-I've experimented with various brewing methods including French press, pour over, and espresso.
+# Later, create referenced entity
+await write_note(
+    title="OAuth Provider",
+    content="# OAuth Provider\n...",
+    folder="auth",
+    project="main"
+)
+# → Relation automatically resolved
+```
 
-## Decision
+## Best Practices
 
-Pour over is my preferred method for light to medium roasts because it highlights subtle flavors and offers more control
-over the extraction.
+### 1. Project Management
 
-## Observations
+**Single-project users:**
+- Enable `default_project_mode=true`
+- Simpler tool calls
 
-- [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
+**Multi-project users:**
+- Keep `default_project_mode=false`
+- Always specify project explicitly
 
-## Relations
+**Discovery:**
+```python
+# Start with discovery
+projects = await list_memory_projects()
 
-- pairs_with [[Light Roast Beans]]
-- contrasts_with [[French Press Method]]
-- requires [[Proper Grinding Technique]]
+# Cross-project activity (no project param = all projects)
+activity = await recent_activity()
+
+# Or specific project
+activity = await recent_activity(project="main")
 ```
 
-### Recording Project Structure
+### 2. Building Rich Graphs
 
-```markdown
-# Garden Planning
+**Always include:**
+- 3-5 observations per note
+- 2-3 relations per note
+- Meaningful categories and relation types
 
-## Overview
+**Search before creating:**
+```python
+# Find existing entities to reference
+results = await search_notes(query="authentication", project="main")
+# Use exact titles in [[WikiLinks]]
+```
 
-This document outlines the garden layout and planting strategy for this season.
+### 3. Writing Effective Notes
 
-## Observations
+**Structure:**
+```markdown
+# Title
 
-- [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
+## Context
+Background information
 
-## Relations
+## Observations
+- [category] Fact with #tags
+- [category] Another fact
 
-- contains [[Vegetable Section]]
-- contains [[Herb Garden]]
-- implements [[Organic Gardening Principles]]
+## Relations
+- relation_type [[Exact Entity Title]]
 ```
 
-### Technical Discussions
+**Categories:** `[idea]`, `[decision]`, `[fact]`, `[technique]`, `[requirement]`
 
-```markdown
-# Recipe Improvement Discussion
+### 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)
+```
 
-## Key Points
+**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
+```
 
-Discussed strategies for improving the chocolate chip cookie recipe.
+### 5. Recording Context
 
-## Observations
+**Ask permission:**
+> "Would you like me to save our discussion about [topic] to Basic Memory?"
 
-- [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
+**Confirm when done:**
+> "I've saved our discussion to Basic Memory."
 
-## Relations
+**What to record:**
+- Decisions and rationales
+- Important discoveries
+- Action items and plans
+- Connected topics
 
-- improves [[Basic Cookie Recipe]]
-- inspired_by [[Bakery-Style Cookies]]
-- pairs_with [[Homemade Ice Cream]]
-```
+## Common Patterns
 
-### Creating Effective Relations
+### Capture Decision
 
-When creating relations, you can:
+```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"
+)
+```
 
-1. Reference existing entities by their exact title
-2. Create forward references to entities that don't exist yet
+### Link Topics & Build Context
 
 ```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.
+# 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")
 
-## 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}")
+# 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)
 ```
 
-## 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'.")
-   ```
+## Tool Quick Reference
 
-## Best Practices
+| 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
 
-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
+Built with ♥️ by Basic Machines