basicmachines-co-basic-memory/scripts/generate_tool_reference_project.py

#!/usr/bin/env python3
"""
Generate a Basic Memory project with comprehensive MCP tool reference documentation.

This script creates a structured knowledge base that users can download and import
into their Basic Memory projects, providing complete tool usage examples in a
navigable knowledge graph format.
"""

import os
from pathlib import Path
from datetime import datetime

# Tool categories and their tools
TOOLS = {
    "Content Management": {
        "write_note": {
            "description": "Create or update markdown notes with semantic observations and relations",
            "params": "title, content, folder, project, tags, entity_type",
            "returns": "Markdown formatted summary of semantic content",
        },
        "read_note": {
            "description": "Read markdown notes by title, permalink, or memory:// URL",
            "params": "identifier, project, page, page_size",
            "returns": "Full markdown content with frontmatter and formatting",
        },
        "read_content": {
            "description": "Read raw file content (text, images, binaries) without knowledge graph processing",
            "params": "path, project",
            "returns": "Raw file content or base64 encoded binary data",
        },
        "view_note": {
            "description": "View notes as formatted artifacts for better readability",
            "params": "identifier, project, page, page_size",
            "returns": "Formatted artifact presentation of note content",
        },
        "edit_note": {
            "description": "Edit notes incrementally with append, prepend, find/replace, replace_section",
            "params": "identifier, operation, content, project",
            "returns": "Confirmation with updated entity information",
        },
        "move_note": {
            "description": "Move notes to new locations, updating database and maintaining links",
            "params": "identifier, destination_path, project",
            "returns": "Confirmation with old and new paths",
        },
        "delete_note": {
            "description": "Delete notes from the knowledge base",
            "params": "identifier, project",
            "returns": "Confirmation of deletion",
        },
    },
    "Knowledge Graph Navigation": {
        "build_context": {
            "description": "Navigate knowledge graph via memory:// URLs for conversation continuity",
            "params": "url, depth, timeframe, project",
            "returns": "Contextual information from knowledge graph traversal",
        },
        "recent_activity": {
            "description": "Get recently updated information with specified timeframe",
            "params": "type, depth, timeframe, project",
            "returns": "List of recently modified entities",
        },
        "list_directory": {
            "description": "Browse directory contents with filtering and depth control",
            "params": "dir_name, depth, file_name_glob, project",
            "returns": "Hierarchical directory structure",
        },
    },
    "Search & Discovery": {
        "search_notes": {
            "description": "Full-text search with advanced filtering and boolean operators",
            "params": "query, project, page, page_size, search_type, types, entity_types, after_date",
            "returns": "SearchResponse with paginated results",
        },
    },
    "Project Management": {
        "list_memory_projects": {
            "description": "List all available projects with their status",
            "params": "None",
            "returns": "List of projects with metadata",
        },
        "create_memory_project": {
            "description": "Create new Basic Memory projects",
            "params": "project_name, project_path, set_default",
            "returns": "Confirmation with project details",
        },
        "delete_project": {
            "description": "Delete a project from configuration",
            "params": "project_name",
            "returns": "Confirmation of deletion",
        },
        "get_current_project": {
            "description": "Get current project information and stats",
            "params": "None",
            "returns": "Current project metadata",
        },
        "sync_status": {
            "description": "Check file synchronization and background operation status",
            "params": "project",
            "returns": "Sync status and operation details",
        },
    },
    "Visualization": {
        "canvas": {
            "description": "Generate Obsidian canvas files for knowledge graph visualization",
            "params": "nodes, edges, title, folder, project",
            "returns": "Path to created canvas file",
        },
    },
}

# Detailed examples for key tools
TOOL_EXAMPLES = {
    "write_note": '''
## Basic Usage

```python
# Create a simple note
write_note(
    project="my-research",
    title="Meeting Notes",
    folder="meetings",
    content="# Weekly Standup\\n\\n- [decision] Use SQLite for storage #tech"
)
```

## With Semantic Content

```python
write_note(
    project="work-project",
    title="API Design",
    folder="specs",
    content="""
# REST API Specification

## Overview
Core API endpoints for user management.

## Observations
- [design] RESTful architecture #api #architecture
- [tech] FastAPI framework #implementation #python
- [decision] JWT for authentication #security

## Relations
- implements [[Authentication System]]
- uses [[PostgreSQL Database]]
- specified_by [[OpenAPI Spec]]
    """,
    tags=["api", "design"],
    entity_type="guide"
)
```

## Creating Knowledge Graph Entries

```python
# Entity with relations to other concepts
write_note(
    project="knowledge-base",
    title="Machine Learning Basics",
    folder="concepts",
    content="""
# Machine Learning Basics

Core concepts in machine learning and AI.

## Observations
- [definition] ML is subset of AI focused on learning from data #ai #ml
- [technique] Supervised learning requires labeled data #training
- [application] Image recognition, NLP, recommendation systems #use-cases

## Relations
- part_of [[Artificial Intelligence]]
- requires [[Training Data]]
- enables [[Predictive Analytics]]
- contrasts_with [[Rule-Based Systems]]
    """
)
```
''',
    "read_note": '''
## Read by Permalink

```python
# Direct permalink lookup (fastest)
read_note("my-research", "specs/search-spec")
```

## Read by Title

```python
# Title search with fallback
read_note("work-project", "Search Specification")
```

## Read with Memory URL

```python
# Using memory:// protocol
read_note("my-research", "memory://specs/search-spec")
```

## With Pagination

```python
# Large notes with pagination
read_note("work-project", "Project Updates", page=2, page_size=5)
```
''',
    "search_notes": '''
## Basic Search

```python
# Simple keyword search
search_notes("project planning")
```

## Boolean Operators

```python
# AND search (both terms required)
search_notes("project AND planning")

# OR search (either term)
search_notes("project OR meeting")

# NOT search (exclude term)
search_notes("project NOT archived")

# Complex boolean with grouping
search_notes("(project OR planning) AND notes")
```

## Phrase Search

```python
# Exact phrase match
search_notes('"weekly standup meeting"')
```

## Search with Filters

```python
# Filter by content type
search_notes(
    "meeting notes",
    types=["entity"]
)

# Filter by entity type
search_notes(
    "meeting notes",
    entity_types=["observation"]
)

# Recent content only
search_notes(
    "bug report",
    after_date="1 week"
)
```

## Search Types

```python
# Title-only search
search_notes("Machine Learning", search_type="title")

# Permalink pattern matching
search_notes("docs/meeting-*", search_type="permalink")

# Full-text search (default)
search_notes("keyword", search_type="text")
```

## Advanced Patterns

```python
# Content-specific search
search_notes("tag:example")  # Search within tags
search_notes("category:observation")  # Filter by category

# Complex multi-filter search
search_notes(
    "(bug OR issue) AND NOT resolved",
    types=["entity"],
    after_date="2024-01-01"
)
```
''',
    "build_context": '''
## Basic Context Building

```python
# Build context from a starting point
build_context("memory://projects/current-project")
```

## With Depth Control

```python
# Follow relations to depth of 2
build_context("memory://concepts/machine-learning", depth=2)
```

## With Timeframe Filter

```python
# Recent context from last week
build_context("memory://meetings/weekly", timeframe="1w")
```

## For Conversation Continuity

```python
# Load previous conversation context
build_context("memory://conversations/project-discussion", depth=3)
```
''',
    "edit_note": '''
## Append Content

```python
edit_note(
    "my-research",
    "meeting-notes",
    operation="append",
    content="\\n## New Section\\n\\nAdditional meeting notes..."
)
```

## Prepend Content

```python
edit_note(
    "work-project",
    "todo-list",
    operation="prepend",
    content="## Urgent Tasks\\n\\n- Fix critical bug\\n\\n"
)
```

## Find and Replace

```python
edit_note(
    "my-research",
    "api-spec",
    operation="find_replace",
    content="SQLite|PostgreSQL"  # Find|Replace pattern
)
```

## Replace Section

```python
edit_note(
    "work-project",
    "design-doc",
    operation="replace_section",
    content="## Old Section|## New Section\\n\\nUpdated content..."
)
```
''',
}


def create_frontmatter(title: str, entity_type: str, tags: list[str], permalink: str = None) -> str:
    """Generate YAML frontmatter for a markdown file."""
    created = datetime.now().isoformat()
    fm = [
        "---",
        f"title: {title}",
        f"type: {entity_type}",
    ]
    if permalink:
        fm.append(f"permalink: {permalink}")
    if tags:
        fm.append("tags:")
        for tag in tags:
            fm.append(f"- {tag}")
    fm.extend([
        f"created: {created}",
        f"modified: {created}",
        "---",
    ])
    return "\n".join(fm)


def generate_category_file(category: str, tools: dict, output_dir: Path) -> None:
    """Generate a category index file."""
    filename = category.lower().replace(" ", "-").replace("&", "and")
    filepath = output_dir / "categories" / f"{filename}.md"

    tags = ["mcp-tools", "reference", "category"]
    frontmatter = create_frontmatter(category, "guide", tags)

    content = [frontmatter, "", f"# {category}", ""]
    content.append(f"Tools in the {category} category for Basic Memory MCP server.")
    content.append("")

    content.append("## Observations")
    content.append(f"- [category] Contains {len(tools)} MCP tools #mcp #tools")
    content.append(f"- [purpose] {category} functionality for Basic Memory #functionality")
    content.append("")

    content.append("## Tools in This Category")
    content.append("")
    for tool_name, tool_info in tools.items():
        content.append(f"### {tool_name}")
        content.append(f"{tool_info['description']}")
        content.append("")

    content.append("## Relations")
    for tool_name in tools.keys():
        tool_title = " ".join(word.capitalize() for word in tool_name.split("_"))
        content.append(f"- contains [[{tool_title}]]")
    content.append("- part_of [[MCP Tool Reference]]")

    filepath.parent.mkdir(parents=True, exist_ok=True)
    filepath.write_text("\n".join(content))
    print(f"Created: {filepath}")


def generate_tool_file(tool_name: str, tool_info: dict, category: str, output_dir: Path) -> None:
    """Generate a detailed tool reference file."""
    tool_title = " ".join(word.capitalize() for word in tool_name.split("_"))
    filepath = output_dir / "tools" / f"{tool_name}.md"

    tags = ["mcp-tools", "reference", tool_name]
    frontmatter = create_frontmatter(tool_title, "guide", tags, f"tools/{tool_name}")

    content = [frontmatter, "", f"# {tool_title}", ""]
    content.append(tool_info["description"])
    content.append("")

    content.append("## Function Signature")
    content.append("")
    content.append("```python")
    content.append(f"{tool_name}({tool_info['params']})")
    content.append("```")
    content.append("")

    content.append("## Observations")
    content.append(f"- [tool] MCP tool for {tool_info['description'].lower()} #mcp #basic-memory")
    content.append(f"- [returns] {tool_info['returns']} #output")
    content.append(f"- [category] {category} tool #classification")
    content.append("")

    # Add examples if available
    if tool_name in TOOL_EXAMPLES:
        content.append("## Usage Examples")
        content.append(TOOL_EXAMPLES[tool_name])
        content.append("")

    content.append("## Relations")
    category_link = category.replace(" ", "-").replace("&", "and")
    category_title = category
    content.append(f"- part_of [[{category_title}]]")
    content.append("- documented_in [[MCP Tool Reference]]")

    # Add cross-references to related tools
    if category == "Content Management":
        if tool_name == "write_note":
            content.append("- complements [[Read Note]]")
            content.append("- complements [[Edit Note]]")
        elif tool_name == "read_note":
            content.append("- complements [[Write Note]]")
            content.append("- alternative [[View Note]]")
        elif tool_name == "edit_note":
            content.append("- requires [[Read Note]]")
            content.append("- alternative [[Write Note]]")
    elif category == "Search & Discovery":
        content.append("- complements [[Recent Activity]]")
        content.append("- complements [[Build Context]]")

    filepath.parent.mkdir(parents=True, exist_ok=True)
    filepath.write_text("\n".join(content))
    print(f"Created: {filepath}")


def generate_index_file(output_dir: Path) -> None:
    """Generate the main index file."""
    filepath = output_dir / "index.md"

    tags = ["mcp-tools", "reference", "index"]
    frontmatter = create_frontmatter("MCP Tool Reference", "guide", tags, "index")

    content = [frontmatter, "", "# MCP Tool Reference", ""]
    content.append("Comprehensive reference for all Basic Memory MCP tools with examples and usage patterns.")
    content.append("")

    content.append("## Overview")
    content.append("")
    content.append("This project contains detailed documentation for all 16 core MCP tools in Basic Memory.")
    content.append("Each tool is documented as a separate entity with examples, parameters, and relationships.")
    content.append("")

    content.append("## Observations")
    total_tools = sum(len(tools) for tools in TOOLS.values())
    content.append(f"- [structure] Contains {total_tools} tool reference documents #documentation")
    content.append(f"- [structure] Organized into {len(TOOLS)} categories #organization")
    content.append("- [purpose] Provides copy-paste examples for LLM instructions #usage")
    content.append("- [format] Follows Basic Memory knowledge graph format #compliance")
    content.append("")

    content.append("## Tool Categories")
    content.append("")
    for category in TOOLS.keys():
        category_link = category.replace(" ", "-").replace("&", "and")
        content.append(f"### {category}")
        content.append(f"See [[{category}]] for all tools in this category.")
        content.append("")

    content.append("## Relations")
    for category in TOOLS.keys():
        content.append(f"- contains [[{category}]]")
    content.append("- documented_in [[Basic Memory Documentation]]")

    filepath.write_text("\n".join(content))
    print(f"Created: {filepath}")


def generate_readme(output_dir: Path) -> None:
    """Generate README for the project."""
    filepath = output_dir / "README.md"

    content = [
        "# Basic Memory MCP Tool Reference Project",
        "",
        "A downloadable Basic Memory project containing comprehensive documentation for all MCP tools.",
        "",
        "## What This Is",
        "",
        "This is a complete Basic Memory project that you can import into your own Basic Memory installation.",
        "It provides detailed reference documentation for all 16 core MCP tools, organized as a knowledge graph",
        "that you can navigate and search using Basic Memory's tools.",
        "",
        "## How to Use",
        "",
        "### Option 1: Import into Existing Project",
        "",
        "1. Copy the contents of this directory into your Basic Memory project",
        "2. Run `basic-memory sync` to index the new content",
        "3. Use `search_notes` or `build_context` to explore the documentation",
        "",
        "### Option 2: Create New Project",
        "",
        "1. Create a new Basic Memory project:",
        "   ```bash",
        "   basic-memory tools create-memory-project \\",
        '     --project-name "tool-reference" \\',
        '     --project-path "~/basic-memory-tool-reference"',
        "   ```",
        "",
        "2. Copy these files into the new project directory",
        "",
        "3. Sync the project:",
        "   ```bash",
        "   basic-memory sync",
        "   ```",
        "",
        "### Option 3: Browse in Your Editor",
        "",
        "The files are standard markdown with Basic Memory frontmatter.",
        "You can browse them in any markdown editor or Obsidian.",
        "",
        "## Project Structure",
        "",
        "```",
        "tool-reference/",
        "├── README.md (this file)",
        "├── index.md (main reference guide)",
        "├── tools/",
        "│   ├── write_note.md",
        "│   ├── read_note.md",
        "│   ├── search_notes.md",
        "│   └── ... (all 16 tools)",
        "└── categories/",
        "    ├── content-management.md",
        "    ├── knowledge-graph-navigation.md",
        "    ├── search-and-discovery.md",
        "    ├── project-management.md",
        "    └── visualization.md",
        "```",
        "",
        "## Using the Documentation",
        "",
        "### Search for Tools",
        "",
        "```python",
        '# Find all content management tools',
        'search_notes("content management", search_type="text")',
        "",
        "# Find write_note examples",
        'search_notes("write_note")',
        "```",
        "",
        "### Navigate by Category",
        "",
        "```python",
        '# Read a category overview',
        'read_note("content-management")',
        "",
        "# Build context around search tools",
        'build_context("memory://categories/search-and-discovery")',
        "```",
        "",
        "### View Tool Details",
        "",
        "```python",
        '# Read specific tool documentation',
        'read_note("tools/write_note")',
        'read_note("tools/search_notes")',
        "",
        "# View as artifact for better formatting",
        'view_note("tools/build_context")',
        "```",
        "",
        "## What's Included",
        "",
        "- **16 tool reference documents** with detailed examples",
        "- **5 category guides** organizing tools by function",
        "- **Knowledge graph relations** connecting related tools",
        "- **Copy-paste examples** ready for LLM instructions",
        "- **Search syntax guide** for advanced queries",
        "- **Real-world workflows** showing tool combinations",
        "",
        "## Tool Categories",
        "",
    ]

    for category, tools in TOOLS.items():
        content.append(f"### {category}")
        content.append("")
        for tool_name, tool_info in tools.items():
            content.append(f"- `{tool_name}`: {tool_info['description']}")
        content.append("")

    content.extend([
        "## Generated Documentation",
        "",
        "This project was automatically generated from the Basic Memory MCP tool source code.",
        "You can regenerate it by running:",
        "",
        "```bash",
        "python scripts/generate_tool_reference_project.py",
        "```",
        "",
        "## License",
        "",
        "Same as Basic Memory - AGPL v3",
        "",
    ])

    filepath.write_text("\n".join(content))
    print(f"Created: {filepath}")


def main():
    """Generate the complete tool reference project."""
    output_dir = Path("examples/tool-reference")

    print(f"Generating Basic Memory Tool Reference Project in {output_dir}")
    print()

    # Generate category files
    for category, tools in TOOLS.items():
        generate_category_file(category, tools, output_dir)

    # Generate tool files
    for category, tools in TOOLS.items():
        for tool_name, tool_info in tools.items():
            generate_tool_file(tool_name, tool_info, category, output_dir)

    # Generate index
    generate_index_file(output_dir)

    # Generate README
    generate_readme(output_dir)

    print()
    print("✓ Tool reference project generated successfully!")
    print(f"✓ Location: {output_dir}")
    print(f"✓ Total files: {len(list(output_dir.rglob('*.md')))}")


if __name__ == "__main__":
    main()