fix: #190 MCP Hub tool validation

Signed-off-by: Drew Cain <groksrc@gmail.com>

.github/workflows/daily-traction.yml

@@ -0,0 +1,28 @@
+name: Daily Traction Report
+on:
+  schedule:
+    - cron: '0 14 * * 1-5'
+  workflow_dispatch:
+
+jobs:
+  generate-report:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.9'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r scripts/requirements.txt
+      - name: Generate Daily Traction Report
+        run: python scripts/daily_report.py
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+          REDDIT_CLIENT_ID: ${{ secrets.REDDIT_CLIENT_ID }}
+          REDDIT_SECRET: ${{ secrets.REDDIT_SECRET }}
+          YOUTUBE_API_KEY: ${{ secrets.YOUTUBE_API_KEY }}

CHANGELOG.md

@@ -1,56 +1,138 @@
 # CHANGELOG
 
-## v0.13.8 (2025-06-20)
+## v0.14.0 (2025-06-26)
 
 ### Features
 
-- **Docker Container Support** - Complete Docker integration with volume mounting for Obsidian directories
-  ([`3269a2f`](https://github.com/basicmachines-co/basic-memory/commit/3269a2f33a7595f6d9e5207924062e2542f46759))
-  - Docker Compose configuration for easy deployment
-  - Volume mounting for persistent data and Obsidian integration
-  - Comprehensive Docker documentation and setup guides
-  - Streamlined container-based workflow
+- **Docker Container Registry Migration** - Switch from Docker Hub to GitHub Container Registry for better security and integration  
+  ([`616c1f0`](https://github.com/basicmachines-co/basic-memory/commit/616c1f0710da59c7098a5f4843d4f017877ff7b2))
+  - Automated Docker image publishing via GitHub Actions CI/CD pipeline
+  - Enhanced container security with GitHub's integrated vulnerability scanning
+  - Streamlined container deployment workflow for production environments
+
+- **Enhanced Search Documentation** - Comprehensive search syntax examples for improved user experience
+  ([`a589f8b`](https://github.com/basicmachines-co/basic-memory/commit/a589f8b894e78cce01eb25656856cfea8785fbbf))
+  - Detailed examples for Boolean search operators (AND, OR, NOT)
+  - Advanced search patterns including phrase matching and field-specific queries
+  - User-friendly documentation for complex search scenarios
+
+- **Cross-Project File Management** - Intelligent move operations with project boundary detection
+  ([`db5ef7d`](https://github.com/basicmachines-co/basic-memory/commit/db5ef7d35cc0894309c7a57b5741c9dd978526d4))
+  - Automatic detection of cross-project move attempts with helpful guidance
+  - Clear error messages when attempting unsupported cross-project operations
 
 ### Bug Fixes
 
-- **#151**: Fix reset command project configuration persistence issue
-  ([`af44941`](https://github.com/basicmachines-co/basic-memory/commit/af44941d5aa57b5ad7fcc6af4ed700f49bdb6d4d))
-  - Reset command now properly clears project configuration from `~/.basic-memory/config.json`
-  - Eliminates issue where projects would be recreated after database reset
-  - Ensures clean slate when resetting Basic Memory installation
+- **#184**: Preserve permalinks when editing notes without frontmatter permalinks
+  ([`c2f4b63`](https://github.com/basicmachines-co/basic-memory/commit/c2f4b632cf04921b1a3c2f0d43831b80c519cb31))
+  - Fix permalink preservation during note editing operations
+  - Ensure consistent permalink handling across different note formats
+  - Maintain note identity and searchability during incremental edits
 
-- **#148**: Resolve project state inconsistency between MCP and CLI
-  ([`35e4f73`](https://github.com/basicmachines-co/basic-memory/commit/35e4f73ae8a65501da4d48258ed702f957184c92))
-  - Fix "Project not found" errors when switching default projects
-  - MCP session now automatically refreshes when project configuration changes
-  - Eliminates need to restart MCP server after project operations
-  - Ensures consistent project state across CLI and MCP interfaces
+- **#183**: Implement project-specific sync status checks for MCP tools
+  ([`12b5152`](https://github.com/basicmachines-co/basic-memory/commit/12b51522bc953fca117fc5bc01fcb29c6ca7e13c))
+  - Fix sync status reporting to correctly reflect current project state
+  - Resolve inconsistencies where sync status showed global instead of project-specific information
+  - Improve project isolation for sync operations and status reporting
 
-- **FastMCP Compatibility** - Resolve deprecation warnings for FastMCP integration
-  ([`7be001c`](https://github.com/basicmachines-co/basic-memory/commit/7be001ca6834b3344bb6160cbe537b36bcbaa579))
-  - Update FastMCP usage patterns to eliminate deprecation warnings
-  - Improve future compatibility with FastMCP library updates
-  - Clean up entity repository and service layer code
+- **#180**: Handle Boolean search syntax with hyphenated terms
+  ([`546e3cd`](https://github.com/basicmachines-co/basic-memory/commit/546e3cd8db98b74f746749d41887f8a213cd0b11))
+  - Fix search parsing issues with hyphenated terms in Boolean queries
+  - Improve search query tokenization for complex term structures
+  - Enhanced search reliability for technical documentation and multi-word concepts
+
+- **#174**: Respect BASIC_MEMORY_HOME environment variable in Docker containers
+  ([`9f1db23`](https://github.com/basicmachines-co/basic-memory/commit/9f1db23c78d4648e2c242ad1ee27eed85e3f3b5d))
+  - Fix Docker container configuration to properly honor custom home directory settings
+  - Improve containerized deployment flexibility with environment variable support
+  - Ensure consistent behavior between local and containerized installations
+
+- **#168**: Scope entity queries by project_id in upsert_entity method
+  ([`2a3adc1`](https://github.com/basicmachines-co/basic-memory/commit/2a3adc109a3e4d7ccd65cae4abf63d9bb2338326))
+  - Fix entity isolation issues in multi-project setups
+  - Prevent cross-project entity conflicts during database operations
+  - Strengthen project boundary enforcement at the database level
+
+- **#166**: Handle None from_entity in Context API RelationSummary
+  ([`8a065c3`](https://github.com/basicmachines-co/basic-memory/commit/8a065c32f4e41613207d29aafc952a56e3a52241))
+  - Fix null pointer exceptions in relation processing
+  - Improve error handling for incomplete relation data
+  - Enhanced stability for knowledge graph traversal operations
+
+- **#164**: Remove log level configuration from mcp_server.run()
+  ([`224e4bf`](https://github.com/basicmachines-co/basic-memory/commit/224e4bf9e4438c44a82ffc21bd1a282fe9087690))
+  - Simplify MCP server startup by removing redundant log level settings
+  - Fix potential logging configuration conflicts
+  - Streamline server initialization process
+
+- **#162**: Ensure permalinks are generated for entities with null permalinks during move operations
+  ([`f506507`](https://github.com/basicmachines-co/basic-memory/commit/f50650763dbd4322c132e4bdc959ce4bf074374b))
+  - Fix move operations for entities without existing permalinks
+  - Automatic permalink generation during file move operations
+  - Maintain database consistency during file reorganization
 
 ### Technical Improvements
 
-- **Comprehensive Integration Testing** - New test suites for critical user workflows
-  - Full integration tests for database reset functionality
-  - End-to-end project state synchronization testing
-  - Real MCP client-server communication validation
-  - Direct config file validation without complex mocking
+- **Comprehensive Test Coverage** - Extensive test suites for new features and edge cases
+  - Enhanced test coverage for project-specific sync status functionality
+  - Additional test scenarios for search syntax validation and edge cases
+  - Integration tests for Docker CI workflow and container publishing
+  - Comprehensive move operations testing with project boundary validation
 
-- **Code Quality** - Enhanced error handling and validation
-  - Improved project state management across system components
-  - Better session refresh patterns for configuration changes
-  - Streamlined Docker setup with reduced image size
+- **Docker CI/CD Pipeline** - Production-ready automated container publishing
+  ([`74847cc`](https://github.com/basicmachines-co/basic-memory/commit/74847cc3807b0c6ed511e0d83e0d560e9f07ec44))
+  - Automated Docker image building and publishing on release
+  - Multi-architecture container support for AMD64 and ARM64 platforms
+  - Integrated security scanning and vulnerability assessments
+  - Streamlined deployment pipeline for production environments
 
-### Documentation
+- **Release Process Improvements** - Enhanced automation and quality gates
+  ([`a52ce1c`](https://github.com/basicmachines-co/basic-memory/commit/a52ce1c8605ec2cd450d1f909154172cbc30faa2))
+  - Homebrew formula updates limited to stable releases only
+  - Improved release automation with better quality control
+  - Enhanced CI/CD pipeline reliability and error handling
 
-- **Docker Integration Guide** - Complete documentation for container deployment
-  - Step-by-step Docker Compose setup instructions
-  - Volume mounting configuration for Obsidian workflows
-  - Container-based development environment setup
+- **Code Quality Enhancements** - Improved error handling and validation
+  - Better null safety in entity and relation processing
+  - Enhanced project isolation validation throughout the codebase
+  - Improved error messages and user guidance for edge cases
+  - Strengthened database consistency guarantees across operations
+
+### Infrastructure
+
+- **GitHub Container Registry Integration** - Modern container infrastructure
+  - Migration from Docker Hub to GitHub Container Registry (ghcr.io)
+  - Improved security with integrated vulnerability scanning
+  - Better integration with GitHub-based development workflow
+  - Enhanced container versioning and artifact management
+
+- **Enhanced CI/CD Workflows** - Robust automated testing and deployment
+  - Automated Docker image publishing on releases
+  - Comprehensive test coverage validation before deployment
+  - Multi-platform container building and publishing
+  - Integration with GitHub's security and monitoring tools
+
+### Migration Guide
+
+This release includes several behind-the-scenes improvements and fixes. All changes are backward compatible:
+
+- **Docker Users**: Container images now served from `ghcr.io/basicmachines-co/basic-memory` instead of Docker Hub
+- **Search Users**: Enhanced search syntax handling - existing queries continue to work unchanged
+- **Multi-Project Users**: Improved project isolation - all existing projects remain fully functional
+- **All Users**: Enhanced stability and error handling - no breaking changes to existing workflows
+
+### Installation
+
+```bash
+# Latest stable release
+uv tool install basic-memory
+
+# Update existing installation  
+uv tool upgrade basic-memory
+
+# Docker (new registry)
+docker pull ghcr.io/basicmachines-co/basic-memory:latest
+```
 
 ## v0.13.7 (2025-06-19)
 

README.md

@@ -33,6 +33,10 @@ https://github.com/user-attachments/assets/a55d8238-8dd0-454a-be4c-8860dbbd0ddc
 # Install with uv (recommended)
 uv tool install basic-memory
 
+# or with Homebrew
+brew tap basicmachines-co/basic-memory
+brew install basic-memory
+
 # Configure Claude Desktop (edit ~/Library/Application Support/Claude/claude_desktop_config.json)
 # Add this to your config:
 {

data/daily_metrics.json

@@ -0,0 +1,44 @@
+{
+  "date": "2025-07-01T01:24:37.731009",
+  "metrics": {
+    "github": {
+      "stars": 1009,
+      "forks": 73,
+      "watchers": 1009,
+      "open_issues": 31,
+      "traffic_views": 0,
+      "traffic_unique": 0,
+      "recent_issues": 0
+    },
+    "reddit": {
+      "total_mentions": 25,
+      "subreddit_members": 43,
+      "top_posts": [
+        {
+          "title": "Today's banning is the largest since Affinity, and...",
+          "score": 892,
+          "subreddit": "magicTCG",
+          "num_comments": 127
+        },
+        {
+          "title": "Basic Memory - Backed by Research*",
+          "score": 1,
+          "subreddit": "basicmemory",
+          "num_comments": 0
+        },
+        {
+          "title": "n8n Full Course \u2699\ufe0f Create Our Second Flow \ud83d\udc49 Trigge...",
+          "score": 1,
+          "subreddit": "Tech_UpSkill",
+          "num_comments": 0
+        }
+      ],
+      "hot_discussions": []
+    },
+    "youtube": {
+      "subscribers": 45,
+      "total_views": 1093,
+      "video_count": 6
+    }
+  }
+}

docs/Docker.md

@@ -129,10 +129,10 @@ When using Docker volumes, you'll need to configure projects to point to your mo
 2. **Add a project for your mounted volume:**
    ```bash
    # If you mounted /path/to/your/vault to /app/data
-   docker exec basic-memory-server basic-memory project create my-vault /app/data
+   docker exec basic-memory-server basic-memory project add my-vault /app/data
    
    # Set it as default
-   docker exec basic-memory-server basic-memory project set-default my-vault
+   docker exec basic-memory-server basic-memory project default my-vault
    ```
 
 3. **Sync the new project:**
@@ -151,10 +151,10 @@ volumes:
 Then configure it:
 ```bash
 # Create project pointing to mounted vault
-docker exec basic-memory-server basic-memory project create obsidian /app/data
+docker exec basic-memory-server basic-memory project add obsidian /app/data
 
 # Set as default
-docker exec basic-memory-server basic-memory project set-default obsidian
+docker exec basic-memory-server basic-memory project default obsidian
 
 # Sync to index all files
 docker exec basic-memory-server basic-memory sync

github/workflows/daily-traction.yml

@@ -0,0 +1,31 @@
+name: Daily Traction Report
+on:
+  schedule:
+    - cron: '0 14 * * 1-5'  # 9 AM EST weekdays
+  workflow_dispatch:  # Manual trigger for testing
+
+jobs:
+  generate-report:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.9'
+          
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r scripts/requirements.txt
+          
+      - name: Generate Daily Traction Report
+        run: python scripts/daily_report.py
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK }}
+          REDDIT_CLIENT_ID: ${{ secrets.REDDIT_CLIENT_ID }}
+          REDDIT_SECRET: ${{ secrets.REDDIT_SECRET }}
+          YOUTUBE_API_KEY: ${{ secrets.YOUTUBE_API_KEY }}

github/workflows/scripts/daily_report.py

@@ -0,0 +1,373 @@
+#!/usr/bin/env python3
+"""
+Basic Memory Daily Traction Report - Enhanced with Growth Tracking
+Automated tracking across GitHub, Reddit, YouTube with daily change indicators
+"""
+
+import os
+import requests
+import json
+from datetime import datetime, timedelta
+import praw
+from googleapiclient.discovery import build
+from dateutil import parser
+import base64
+
+class BasicMemoryTracker:
+    def __init__(self):
+        self.github_token = os.getenv('GITHUB_TOKEN')
+        self.discord_webhook = os.getenv('DISCORD_WEBHOOK')
+        self.youtube_api_key = os.getenv('YOUTUBE_API_KEY')
+        
+        # Reddit setup
+        self.reddit = praw.Reddit(
+            client_id=os.getenv('REDDIT_CLIENT_ID'),
+            client_secret=os.getenv('REDDIT_SECRET'),
+            user_agent='BasicMemoryTracker:v1.0'
+        )
+        
+        # YouTube setup
+        self.youtube = build('youtube', 'v3', developerKey=self.youtube_api_key)
+        
+        self.repo_owner = 'basicmachines-co'
+        self.repo_name = 'basic-memory'
+        self.youtube_channel = 'basicmachines-co'
+        self.metrics_file = 'data/daily_metrics.json'
+
+    def get_previous_metrics(self):
+        """Get yesterday's metrics from GitHub repo storage"""
+        try:
+            headers = {'Authorization': f'token {self.github_token}'}
+            url = f'https://api.github.com/repos/{self.repo_owner}/{self.repo_name}/contents/{self.metrics_file}'
+            response = requests.get(url, headers=headers)
+            
+            if response.status_code == 200:
+                file_data = response.json()
+                content = base64.b64decode(file_data['content']).decode('utf-8')
+                return json.loads(content)
+            else:
+                print("📝 No previous metrics found - this is the first run!")
+                return {}
+        except Exception as e:
+            print(f"⚠️ Could not load previous metrics: {e}")
+            return {}
+
+    def save_current_metrics(self, metrics):
+        """Save today's metrics to GitHub repo for tomorrow's comparison"""
+        try:
+            headers = {'Authorization': f'token {self.github_token}'}
+            
+            # Prepare data
+            metrics_data = {
+                'date': datetime.now().isoformat(),
+                'metrics': metrics
+            }
+            content = json.dumps(metrics_data, indent=2)
+            encoded_content = base64.b64encode(content.encode()).decode()
+            
+            # Check if file exists
+            file_url = f'https://api.github.com/repos/{self.repo_owner}/{self.repo_name}/contents/{self.metrics_file}'
+            existing_response = requests.get(file_url, headers=headers)
+            
+            payload = {
+                'message': f'📊 Daily metrics update - {datetime.now().strftime("%Y-%m-%d")}',
+                'content': encoded_content
+            }
+            
+            if existing_response.status_code == 200:
+                # File exists, update it
+                payload['sha'] = existing_response.json()['sha']
+                response = requests.put(file_url, headers=headers, json=payload)
+            else:
+                # File doesn't exist, create it
+                response = requests.put(file_url, headers=headers, json=payload)
+            
+            if response.status_code in [200, 201]:
+                print("✅ Metrics saved for tomorrow's comparison!")
+            else:
+                print(f"⚠️ Failed to save metrics: {response.status_code}")
+                
+        except Exception as e:
+            print(f"⚠️ Error saving metrics: {e}")
+
+    def calculate_change(self, current, previous, key):
+        """Calculate the change between current and previous values"""
+        if not previous or key not in previous:
+            return 0, "🆕"
+        
+        change = current - previous[key]
+        if change > 0:
+            return change, "📈"
+        elif change < 0:
+            return abs(change), "📉"
+        else:
+            return 0, "➡️"
+
+    def format_change(self, change, direction):
+        """Format the change indicator for display"""
+        if direction == "🆕":
+            return "🆕"
+        elif direction == "📈":
+            return f"(+{change})"
+        elif direction == "📉":
+            return f"(-{change})"
+        else:
+            return "(±0)"
+
+    def get_github_metrics(self):
+        """Get GitHub repository metrics"""
+        try:
+            headers = {'Authorization': f'token {self.github_token}'}
+            
+            # Repository stats
+            repo_url = f'https://api.github.com/repos/{self.repo_owner}/{self.repo_name}'
+            repo_response = requests.get(repo_url, headers=headers)
+            repo_data = repo_response.json()
+            
+            # Traffic stats (requires push access)
+            traffic_url = f'https://api.github.com/repos/{self.repo_owner}/{self.repo_name}/traffic/views'
+            traffic_response = requests.get(traffic_url, headers=headers)
+            traffic_data = traffic_response.json() if traffic_response.status_code == 200 else {}
+            
+            # Recent issues
+            issues_url = f'https://api.github.com/repos/{self.repo_owner}/{self.repo_name}/issues'
+            issues_response = requests.get(issues_url, headers=headers)
+            issues_data = issues_response.json() if issues_response.status_code == 200 else []
+            
+            return {
+                'stars': repo_data.get('stargazers_count', 0),
+                'forks': repo_data.get('forks_count', 0),
+                'watchers': repo_data.get('watchers_count', 0),
+                'open_issues': repo_data.get('open_issues_count', 0),
+                'traffic_views': traffic_data.get('count', 0),
+                'traffic_unique': traffic_data.get('uniques', 0),
+                'recent_issues': len([i for i in issues_data if 
+                    parser.parse(i['created_at']).date() >= (datetime.now() - timedelta(days=1)).date()])
+            }
+        except Exception as e:
+            print(f"GitHub API error: {e}")
+            return {'error': str(e)}
+
+    def get_reddit_metrics(self):
+        """Get Reddit metrics for Basic Memory mentions"""
+        try:
+            metrics = {
+                'total_mentions': 0,
+                'subreddit_members': 0,
+                'top_posts': [],
+                'hot_discussions': []
+            }
+            
+            # Search for Basic Memory mentions
+            search_results = list(self.reddit.subreddit('all').search(
+                'Basic Memory', time_filter='day', limit=25
+            ))
+            metrics['total_mentions'] = len(search_results)
+            
+            # Get top posts
+            for post in search_results[:3]:
+                metrics['top_posts'].append({
+                    'title': post.title[:50] + '...' if len(post.title) > 50 else post.title,
+                    'score': post.score,
+                    'subreddit': post.subreddit.display_name,
+                    'num_comments': post.num_comments
+                })
+            
+            # Check r/BasicMemory if it exists
+            try:
+                basic_memory_sub = self.reddit.subreddit('BasicMemory')
+                metrics['subreddit_members'] = basic_memory_sub.subscribers
+            except:
+                metrics['subreddit_members'] = 0
+                
+            return metrics
+        except Exception as e:
+            print(f"Reddit API error: {e}")
+            return {'error': str(e)}
+
+    def get_youtube_metrics(self):
+        """Get YouTube channel metrics"""
+        try:
+            # Get channel statistics
+            channel_response = self.youtube.channels().list(
+                part='statistics,snippet',
+                forUsername=self.youtube_channel
+            ).execute()
+            
+            if not channel_response['items']:
+                # Try by channel handle
+                search_response = self.youtube.search().list(
+                    part='snippet',
+                    q=f'@{self.youtube_channel}',
+                    type='channel',
+                    maxResults=1
+                ).execute()
+                
+                if search_response['items']:
+                    channel_id = search_response['items'][0]['snippet']['channelId']
+                    channel_response = self.youtube.channels().list(
+                        part='statistics,snippet',
+                        id=channel_id
+                    ).execute()
+            
+            if channel_response['items']:
+                stats = channel_response['items'][0]['statistics']
+                return {
+                    'subscribers': int(stats.get('subscriberCount', 0)),
+                    'total_views': int(stats.get('viewCount', 0)),
+                    'video_count': int(stats.get('videoCount', 0))
+                }
+            else:
+                return {'error': 'Channel not found'}
+                
+        except Exception as e:
+            print(f"YouTube API error: {e}")
+            return {'error': str(e)}
+
+    def create_discord_embed(self, current_metrics, previous_metrics):
+        """Create beautiful Discord embed with all metrics and growth indicators"""
+        
+        github_data = current_metrics.get('github', {})
+        reddit_data = current_metrics.get('reddit', {})
+        youtube_data = current_metrics.get('youtube', {})
+        
+        prev_github = previous_metrics.get('github', {})
+        prev_reddit = previous_metrics.get('reddit', {})
+        prev_youtube = previous_metrics.get('youtube', {})
+        
+        # Calculate changes
+        star_change, star_dir = self.calculate_change(github_data.get('stars', 0), prev_github, 'stars')
+        sub_change, sub_dir = self.calculate_change(youtube_data.get('subscribers', 0), prev_youtube, 'subscribers')
+        view_change, view_dir = self.calculate_change(youtube_data.get('total_views', 0), prev_youtube, 'total_views')
+        reddit_change, reddit_dir = self.calculate_change(reddit_data.get('total_mentions', 0), prev_reddit, 'total_mentions')
+        member_change, member_dir = self.calculate_change(reddit_data.get('subreddit_members', 0), prev_reddit, 'subreddit_members')
+        
+        # Calculate total reach
+        total_reach = (
+            github_data.get('traffic_unique', 0) + 
+            reddit_data.get('total_mentions', 0) * 100 +
+            youtube_data.get('total_views', 0)
+        )
+        
+        embed = {
+            "title": "🚀 Basic Memory Daily Traction Report",
+            "description": f"📅 {datetime.now().strftime('%A, %B %d, %Y')}",
+            "color": 0x00ff88,
+            "fields": [
+                {
+                    "name": "⭐ GitHub Metrics",
+                    "value": f"""
+**Stars:** {github_data.get('stars', 'N/A')} {star_dir} {self.format_change(star_change, star_dir)}
+**Forks:** {github_data.get('forks', 'N/A')} 🍴
+**Traffic:** {github_data.get('traffic_unique', 'N/A')} unique visitors 👀
+**Issues:** {github_data.get('recent_issues', 0)} new today 🐛
+                    """.strip(),
+                    "inline": True
+                },
+                {
+                    "name": "🗨️ Reddit Activity", 
+                    "value": f"""
+**Mentions:** {reddit_data.get('total_mentions', 'N/A')} {reddit_dir} {self.format_change(reddit_change, reddit_dir)}
+**r/BasicMemory:** {reddit_data.get('subreddit_members', 'N/A')} {member_dir} {self.format_change(member_change, member_dir)}
+**Hot Posts:** {len(reddit_data.get('top_posts', []))} trending 🔥
+                    """.strip(),
+                    "inline": True
+                },
+                {
+                    "name": "📺 YouTube Stats",
+                    "value": f"""
+**Subscribers:** {youtube_data.get('subscribers', 'N/A')} {sub_dir} {self.format_change(sub_change, sub_dir)}
+**Total Views:** {youtube_data.get('total_views', 'N/A'):,} {view_dir} {self.format_change(view_change, view_dir)}
+**Videos:** {youtube_data.get('video_count', 'N/A')} 🎬
+                    """.strip(),
+                    "inline": True
+                }
+            ],
+            "footer": {
+                "text": f"🤖 Automated by Basic Memory • Daily Reach: {total_reach:,}"
+            },
+            "timestamp": datetime.now().isoformat()
+        }
+        
+        # Add top Reddit posts if available
+        if reddit_data.get('top_posts'):
+            top_post = reddit_data['top_posts'][0]
+            embed["fields"].append({
+                "name": "🔥 Top Reddit Post",
+                "value": f"**{top_post['title']}**\n📊 {top_post['score']} upvotes • 💬 {top_post['num_comments']} comments\n📍 r/{top_post['subreddit']}",
+                "inline": False
+            })
+        
+        return embed
+
+    def send_discord_report(self, embed):
+        """Send the report to Discord"""
+        try:
+            payload = {"embeds": [embed]}
+            response = requests.post(self.discord_webhook, json=payload)
+            
+            if response.status_code == 204:
+                print("✅ Discord report sent successfully!")
+                return True
+            else:
+                print(f"❌ Discord webhook failed: {response.status_code}")
+                print(response.text)
+                return False
+                
+        except Exception as e:
+            print(f"Discord send error: {e}")
+            return False
+
+    def run_daily_report(self):
+        """Main function to generate and send daily report"""
+        print("🚀 Starting Basic Memory Daily Traction Report...")
+        
+        # Load previous metrics
+        print("📊 Loading previous metrics...")
+        previous_metrics = self.get_previous_metrics()
+        
+        # Collect current metrics
+        print("📊 Collecting GitHub metrics...")
+        github_data = self.get_github_metrics()
+        
+        print("🗨️ Collecting Reddit metrics...")
+        reddit_data = self.get_reddit_metrics()
+        
+        print("📺 Collecting YouTube metrics...")
+        youtube_data = self.get_youtube_metrics()
+        
+        # Combine current metrics
+        current_metrics = {
+            'github': github_data,
+            'reddit': reddit_data,
+            'youtube': youtube_data
+        }
+        
+        # Create and send report
+        print("🎨 Creating Discord embed with growth tracking...")
+        embed = self.create_discord_embed(current_metrics, previous_metrics.get('metrics', {}))
+        
+        print("📤 Sending to Discord...")
+        success = self.send_discord_report(embed)
+        
+        # Save current metrics for tomorrow
+        print("💾 Saving metrics for tomorrow's comparison...")
+        self.save_current_metrics(current_metrics)
+        
+        if success:
+            print("🎉 Daily traction report completed successfully!")
+        else:
+            print("😞 Report failed to send")
+            
+        # Print summary for GitHub Actions logs
+        print(f"""
+📊 DAILY SUMMARY:
+⭐ GitHub Stars: {github_data.get('stars', 'Error')}
+👥 Reddit Mentions: {reddit_data.get('total_mentions', 'Error')} 
+📺 YouTube Subscribers: {youtube_data.get('subscribers', 'Error')}
+📺 YouTube Views: {youtube_data.get('total_views', 'Error')}
+        """)
+
+if __name__ == "__main__":
+    tracker = BasicMemoryTracker()
+    tracker.run_daily_report()

github/workflows/scripts/requirements.txt

@@ -0,0 +1,4 @@
+requests==2.31.0
+praw==7.7.1
+google-api-python-client==2.108.0
+python-dateutil==2.8.2

scripts/daily_report.py

@@ -0,0 +1,389 @@
+#!/usr/bin/env python3
+"""
+Basic Memory Daily Traction Report - Enhanced with Growth Tracking
+Automated tracking across GitHub, Reddit, YouTube with daily change indicators
+"""
+
+import os
+import requests
+import json
+from datetime import datetime, timedelta
+import praw
+from googleapiclient.discovery import build
+from dateutil import parser
+import base64
+
+class BasicMemoryTracker:
+    def __init__(self):
+        self.github_token = os.getenv('GITHUB_TOKEN')
+        self.discord_webhook = os.getenv('DISCORD_WEBHOOK')
+        self.youtube_api_key = os.getenv('YOUTUBE_API_KEY')
+        
+        # Reddit setup
+        self.reddit = praw.Reddit(
+            client_id=os.getenv('REDDIT_CLIENT_ID'),
+            client_secret=os.getenv('REDDIT_SECRET'),
+            user_agent='BasicMemoryTracker:v1.0'
+        )
+        
+        # YouTube setup
+        self.youtube = build('youtube', 'v3', developerKey=self.youtube_api_key)
+        
+        self.repo_owner = 'basicmachines-co'
+        self.repo_name = 'basic-memory'
+        self.youtube_channel = 'basicmachines-co'
+        self.metrics_file = 'data/daily_metrics.json'
+
+    def get_previous_metrics(self):
+        """Get yesterday's metrics from GitHub repo storage"""
+        try:
+            headers = {'Authorization': f'token {self.github_token}'}
+            url = f'https://api.github.com/repos/{self.repo_owner}/{self.repo_name}/contents/{self.metrics_file}'
+            response = requests.get(url, headers=headers)
+            
+            if response.status_code == 200:
+                file_data = response.json()
+                content = base64.b64decode(file_data['content']).decode('utf-8')
+                return json.loads(content)
+            else:
+                print("📝 No previous metrics found - this is the first run!")
+                return {}
+        except Exception as e:
+            print(f"⚠️ Could not load previous metrics: {e}")
+            return {}
+
+    def save_current_metrics(self, metrics):
+        """Save today's metrics to GitHub repo for tomorrow's comparison"""
+        try:
+            headers = {'Authorization': f'token {self.github_token}'}
+            
+            # Prepare data
+            metrics_data = {
+                'date': datetime.now().isoformat(),
+                'metrics': metrics
+            }
+            content = json.dumps(metrics_data, indent=2)
+            encoded_content = base64.b64encode(content.encode()).decode()
+            
+            # Check if file exists
+            file_url = f'https://api.github.com/repos/{self.repo_owner}/{self.repo_name}/contents/{self.metrics_file}'
+            existing_response = requests.get(file_url, headers=headers)
+            
+            payload = {
+                'message': f'📊 Daily metrics update - {datetime.now().strftime("%Y-%m-%d")}',
+                'content': encoded_content
+            }
+            
+            if existing_response.status_code == 200:
+                # File exists, update it
+                payload['sha'] = existing_response.json()['sha']
+                response = requests.put(file_url, headers=headers, json=payload)
+            else:
+                # File doesn't exist, create it
+                response = requests.put(file_url, headers=headers, json=payload)
+            
+            if response.status_code in [200, 201]:
+                print("✅ Metrics saved for tomorrow's comparison!")
+            else:
+                print(f"⚠️ Failed to save metrics: {response.status_code}")
+                
+        except Exception as e:
+            print(f"⚠️ Error saving metrics: {e}")
+
+    def calculate_change(self, current, previous, key):
+        """Calculate the change between current and previous values"""
+        if not previous or key not in previous:
+            return 0, "🆕"
+        
+        change = current - previous[key]
+        if change > 0:
+            return change, "📈"
+        elif change < 0:
+            return abs(change), "📉"
+        else:
+            return 0, "➡️"
+
+    def format_change(self, change, direction):
+        """Format the change indicator for display"""
+        if direction == "🆕":
+            return "🆕"
+        elif direction == "📈":
+            return f"(+{change})"
+        elif direction == "📉":
+            return f"(-{change})"
+        else:
+            return "(±0)"
+
+    def get_github_metrics(self):
+        """Get GitHub repository metrics"""
+        try:
+            headers = {'Authorization': f'token {self.github_token}'}
+            
+            # Repository stats
+            repo_url = f'https://api.github.com/repos/{self.repo_owner}/{self.repo_name}'
+            repo_response = requests.get(repo_url, headers=headers)
+            repo_data = repo_response.json()
+            
+            # Traffic stats (requires push access)
+            traffic_url = f'https://api.github.com/repos/{self.repo_owner}/{self.repo_name}/traffic/views'
+            traffic_response = requests.get(traffic_url, headers=headers)
+            traffic_data = traffic_response.json() if traffic_response.status_code == 200 else {}
+            
+            # Recent issues
+            issues_url = f'https://api.github.com/repos/{self.repo_owner}/{self.repo_name}/issues'
+            issues_response = requests.get(issues_url, headers=headers)
+            issues_data = issues_response.json() if issues_response.status_code == 200 else []
+            
+            return {
+                'stars': repo_data.get('stargazers_count', 0),
+                'forks': repo_data.get('forks_count', 0),
+                'watchers': repo_data.get('watchers_count', 0),
+                'open_issues': repo_data.get('open_issues_count', 0),
+                'traffic_views': traffic_data.get('count', 0),
+                'traffic_unique': traffic_data.get('uniques', 0),
+                'recent_issues': len([i for i in issues_data if 
+                    parser.parse(i['created_at']).date() >= (datetime.now() - timedelta(days=1)).date()])
+            }
+        except Exception as e:
+            print(f"GitHub API error: {e}")
+            return {'error': str(e)}
+
+    def get_reddit_metrics(self):
+        """Get Reddit metrics for Basic Memory mentions"""
+        try:
+            metrics = {
+                'total_mentions': 0,
+                'subreddit_members': 0,
+                'top_posts': [],
+                'hot_discussions': []
+            }
+            
+            # Search for Basic Memory mentions
+            search_results = list(self.reddit.subreddit('all').search(
+                'Basic Memory', time_filter='day', limit=25
+            ))
+            metrics['total_mentions'] = len(search_results)
+            
+            # Get top posts
+            for post in search_results[:3]:
+                metrics['top_posts'].append({
+                    'title': post.title[:50] + '...' if len(post.title) > 50 else post.title,
+                    'score': post.score,
+                    'subreddit': post.subreddit.display_name,
+                    'num_comments': post.num_comments
+                })
+            
+            # Check r/BasicMemory if it exists
+            try:
+                basic_memory_sub = self.reddit.subreddit('BasicMemory')
+                metrics['subreddit_members'] = basic_memory_sub.subscribers
+            except:
+                metrics['subreddit_members'] = 0
+                
+            return metrics
+        except Exception as e:
+            print(f"Reddit API error: {e}")
+            return {'error': str(e)}
+
+    def get_youtube_metrics(self):
+        """Get YouTube channel metrics"""
+        try:
+            # Try to find channel by handle first
+            search_response = self.youtube.search().list(
+                part='snippet',
+                q='basicmachines-co',
+                type='channel',
+                maxResults=5
+            ).execute()
+            
+            channel_id = None
+            if search_response.get('items'):
+                # Look for exact match or best match
+                for item in search_response['items']:
+                    channel_title = item['snippet']['title'].lower()
+                    if 'basic' in channel_title and 'machine' in channel_title:
+                        channel_id = item['snippet']['channelId']
+                        break
+                
+                # If no exact match, use first result
+                if not channel_id and search_response['items']:
+                    channel_id = search_response['items'][0]['snippet']['channelId']
+            
+            if channel_id:
+                # Get channel statistics
+                channel_response = self.youtube.channels().list(
+                    part='statistics,snippet',
+                    id=channel_id
+                ).execute()
+                
+                if channel_response.get('items'):
+                    stats = channel_response['items'][0]['statistics']
+                    return {
+                        'subscribers': int(stats.get('subscriberCount', 0)),
+                        'total_views': int(stats.get('viewCount', 0)),
+                        'video_count': int(stats.get('videoCount', 0))
+                    }
+            
+            # Fallback: return placeholder data
+            print("⚠️ YouTube channel not found, using placeholder data")
+            return {
+                'subscribers': 0,
+                'total_views': 0,
+                'video_count': 0
+            }
+                
+        except Exception as e:
+            print(f"YouTube API error: {e}")
+            return {
+                'subscribers': 0,
+                'total_views': 0,
+                'video_count': 0
+            }
+
+    def create_discord_embed(self, current_metrics, previous_metrics):
+        """Create beautiful Discord embed with all metrics and growth indicators"""
+        
+        github_data = current_metrics.get('github', {})
+        reddit_data = current_metrics.get('reddit', {})
+        youtube_data = current_metrics.get('youtube', {})
+        
+        prev_github = previous_metrics.get('github', {})
+        prev_reddit = previous_metrics.get('reddit', {})
+        prev_youtube = previous_metrics.get('youtube', {})
+        
+        # Calculate changes
+        star_change, star_dir = self.calculate_change(github_data.get('stars', 0), prev_github, 'stars')
+        sub_change, sub_dir = self.calculate_change(youtube_data.get('subscribers', 0), prev_youtube, 'subscribers')
+        view_change, view_dir = self.calculate_change(youtube_data.get('total_views', 0), prev_youtube, 'total_views')
+        reddit_change, reddit_dir = self.calculate_change(reddit_data.get('total_mentions', 0), prev_reddit, 'total_mentions')
+        member_change, member_dir = self.calculate_change(reddit_data.get('subreddit_members', 0), prev_reddit, 'subreddit_members')
+        
+        # Calculate total reach
+        total_reach = (
+            github_data.get('traffic_unique', 0) + 
+            reddit_data.get('total_mentions', 0) * 100 +
+            youtube_data.get('total_views', 0)
+        )
+        
+        embed = {
+            "title": "🚀 Basic Memory Daily Traction Report",
+            "description": f"📅 {datetime.now().strftime('%A, %B %d, %Y')}",
+            "color": 0x00ff88,
+            "fields": [
+                {
+                    "name": "⭐ GitHub Metrics",
+                    "value": f"""
+**Stars:** {github_data.get('stars', 'N/A')} {star_dir} {self.format_change(star_change, star_dir)}
+**Forks:** {github_data.get('forks', 'N/A')} 🍴
+**Traffic:** {github_data.get('traffic_unique', 'N/A')} unique visitors 👀
+**Issues:** {github_data.get('recent_issues', 0)} new today 🐛
+                    """.strip(),
+                    "inline": True
+                },
+                {
+                    "name": "🗨️ Reddit Activity", 
+                    "value": f"""
+**Mentions:** {reddit_data.get('total_mentions', 'N/A')} {reddit_dir} {self.format_change(reddit_change, reddit_dir)}
+**r/BasicMemory:** {reddit_data.get('subreddit_members', 'N/A')} {member_dir} {self.format_change(member_change, member_dir)}
+**Hot Posts:** {len(reddit_data.get('top_posts', []))} trending 🔥
+                    """.strip(),
+                    "inline": True
+                },
+                {
+                    "name": "📺 YouTube Stats",
+                    "value": f"""
+**Subscribers:** {youtube_data.get('subscribers', 'N/A')} {sub_dir} {self.format_change(sub_change, sub_dir)}
+**Total Views:** {youtube_data.get('total_views', 'N/A')} {view_dir} {self.format_change(view_change, view_dir)}
+**Videos:** {youtube_data.get('video_count', 'N/A')} 🎬
+                    """.strip(),
+                    "inline": True
+                }
+            ],
+            "footer": {
+                "text": f"🤖 Automated by Basic Memory • Daily Reach: {total_reach}"
+            },
+            "timestamp": datetime.now().isoformat()
+        }
+        
+        # Add top Reddit posts if available
+        if reddit_data.get('top_posts'):
+            top_post = reddit_data['top_posts'][0]
+            embed["fields"].append({
+                "name": "🔥 Top Reddit Post",
+                "value": f"**{top_post['title']}**\n📊 {top_post['score']} upvotes • 💬 {top_post['num_comments']} comments\n📍 r/{top_post['subreddit']}",
+                "inline": False
+            })
+        
+        return embed
+
+    def send_discord_report(self, embed):
+        """Send the report to Discord"""
+        try:
+            payload = {"embeds": [embed]}
+            response = requests.post(self.discord_webhook, json=payload)
+            
+            if response.status_code == 204:
+                print("✅ Discord report sent successfully!")
+                return True
+            else:
+                print(f"❌ Discord webhook failed: {response.status_code}")
+                print(response.text)
+                return False
+                
+        except Exception as e:
+            print(f"Discord send error: {e}")
+            return False
+
+    def run_daily_report(self):
+        """Main function to generate and send daily report"""
+        print("🚀 Starting Basic Memory Daily Traction Report...")
+        
+        # Load previous metrics
+        print("📊 Loading previous metrics...")
+        previous_metrics = self.get_previous_metrics()
+        
+        # Collect current metrics
+        print("📊 Collecting GitHub metrics...")
+        github_data = self.get_github_metrics()
+        
+        print("🗨️ Collecting Reddit metrics...")
+        reddit_data = self.get_reddit_metrics()
+        
+        print("📺 Collecting YouTube metrics...")
+        youtube_data = self.get_youtube_metrics()
+        
+        # Combine current metrics
+        current_metrics = {
+            'github': github_data,
+            'reddit': reddit_data,
+            'youtube': youtube_data
+        }
+        
+        # Create and send report
+        print("🎨 Creating Discord embed with growth tracking...")
+        embed = self.create_discord_embed(current_metrics, previous_metrics.get('metrics', {}))
+        
+        print("📤 Sending to Discord...")
+        success = self.send_discord_report(embed)
+        
+        # Save current metrics for tomorrow
+        print("💾 Saving metrics for tomorrow's comparison...")
+        self.save_current_metrics(current_metrics)
+        
+        if success:
+            print("🎉 Daily traction report completed successfully!")
+        else:
+            print("😞 Report failed to send")
+            
+        # Print summary for GitHub Actions logs
+        print(f"""
+📊 DAILY SUMMARY:
+⭐ GitHub Stars: {github_data.get('stars', 'Error')}
+👥 Reddit Mentions: {reddit_data.get('total_mentions', 'Error')} 
+📺 YouTube Subscribers: {youtube_data.get('subscribers', 'Error')}
+📺 YouTube Views: {youtube_data.get('total_views', 'Error')}
+        """)
+
+if __name__ == "__main__":
+    tracker = BasicMemoryTracker()
+    tracker.run_daily_report()

scripts/requirements.txt

@@ -0,0 +1,4 @@
+requests==2.31.0
+praw==7.7.1
+google-api-python-client==2.108.0
+python-dateutil==2.8.2

src/basic_memory/__init__.py

@@ -1,7 +1,7 @@
 """basic-memory - Local-first knowledge management combining Zettelkasten with knowledge graphs"""
 
 # Package version - updated by release automation
-__version__ = "0.14.0b1"
+__version__ = "0.14.0"
 
 # API version for FastAPI - independent of package version
 __api_version__ = "v0"

src/basic_memory/markdown/utils.py

@@ -38,7 +38,9 @@ def entity_model_from_markdown(
     # Update basic fields
     model.title = markdown.frontmatter.title
     model.entity_type = markdown.frontmatter.type
-    model.permalink = markdown.frontmatter.permalink
+    # Only update permalink if it exists in frontmatter, otherwise preserve existing
+    if markdown.frontmatter.permalink is not None:
+        model.permalink = markdown.frontmatter.permalink
     model.file_path = str(file_path)
     model.content_type = "text/markdown"
     model.created_at = markdown.created

src/basic_memory/mcp/tools/__init__.py

@@ -20,24 +20,24 @@ from basic_memory.mcp.tools.edit_note import edit_note
 from basic_memory.mcp.tools.move_note import move_note
 from basic_memory.mcp.tools.sync_status import sync_status
 from basic_memory.mcp.tools.project_management import (
-    list_projects,
+    list_memory_projects,
     switch_project,
     get_current_project,
     set_default_project,
-    create_project,
+    create_memory_project,
     delete_project,
 )
 
 __all__ = [
     "build_context",
     "canvas",
-    "create_project",
+    "create_memory_project",
     "delete_note",
     "delete_project",
     "edit_note",
     "get_current_project",
     "list_directory",
-    "list_projects",
+    "list_memory_projects",
     "move_note",
     "read_content",
     "read_note",

src/basic_memory/mcp/tools/move_note.py

@@ -109,7 +109,7 @@ def _format_cross_project_error_response(
         ```
         
         ## Available projects:
-        Use `list_projects()` to see all available projects and `switch_project("project-name")` to change projects.
+        Use `list_memory_projects()` to see all available projects and `switch_project("project-name")` to change projects.
         """).strip()
 
 
@@ -153,7 +153,7 @@ def _format_potential_cross_project_guidance(
         
         ### To see all projects:
         ```
-        list_projects()
+        list_memory_projects()
         ```
         """).strip()
 

src/basic_memory/mcp/tools/project_management.py

@@ -19,7 +19,7 @@ from basic_memory.utils import generate_permalink
 
 
 @mcp.tool("list_memory_projects")
-async def list_projects(ctx: Context | None = None) -> str:
+async def list_memory_projects(ctx: Context | None = None) -> str:
     """List all available projects with their status.
 
     Shows all Basic Memory projects that are available, indicating which one
@@ -29,7 +29,7 @@ async def list_projects(ctx: Context | None = None) -> str:
         Formatted list of projects with status indicators
 
     Example:
-        list_projects()
+        list_memory_projects()
     """
     if ctx:  # pragma: no cover
         await ctx.info("Listing all available projects")
@@ -150,7 +150,7 @@ async def switch_project(project_name: str, ctx: Context | None = None) -> str:
             4. **Try again**: The error might be temporary
 
             ## Available options:
-            - See all projects: `list_projects()`
+            - See all projects: `list_memory_projects()`
             - Stay on current project: `get_current_project()`
             - Try different project: `switch_project("correct-project-name")`
 
@@ -231,7 +231,7 @@ async def set_default_project(project_name: str, ctx: Context | None = None) ->
 
 
 @mcp.tool("create_memory_project")
-async def create_project(
+async def create_memory_project(
     project_name: str, project_path: str, set_default: bool = False, ctx: Context | None = None
 ) -> str:
     """Create a new Basic Memory project.
@@ -248,8 +248,8 @@ async def create_project(
         Confirmation message with project details
 
     Example:
-        create_project("my-research", "~/Documents/research")
-        create_project("work-notes", "/home/user/work", set_default=True)
+        create_memory_project("my-research", "~/Documents/research")
+        create_memory_project("work-notes", "/home/user/work", set_default=True)
     """
     if ctx:  # pragma: no cover
         await ctx.info(f"Creating project: {project_name} at {project_path}")

src/basic_memory/mcp/tools/search.py

@@ -45,13 +45,18 @@ def _format_search_error_response(error_message: str, query: str, search_type: s
             - Boolean OR: `meeting OR discussion`
             - Boolean NOT: `project NOT archived`
             - Grouped: `(project OR planning) AND notes`
+            - Exact phrases: `"weekly standup meeting"`
+            - Content-specific: `tag:example` or `category:observation`
 
             ## Try again with:
             ```
-            search_notes("INSERT_CLEAN_QUERY_HERE")
+            search_notes("{clean_query}")
             ```
 
-            Replace INSERT_CLEAN_QUERY_HERE with your simplified search terms.
+            ## Alternative search strategies:
+            - Break into simpler terms: `search_notes("{' '.join(clean_query.split()[:2])}")`
+            - Try different search types: `search_notes("{clean_query}", search_type="title")`
+            - Use filtering: `search_notes("{clean_query}", types=["entity"])`
             """).strip()
 
     # Project not found errors (check before general "not found")
@@ -62,13 +67,13 @@ def _format_search_error_response(error_message: str, query: str, search_type: s
             The current project is not accessible or doesn't exist: {error_message}
 
             ## How to resolve:
-            1. **Check available projects**: `list_projects()`
+            1. **Check available projects**: `list_memory_projects()`
             2. **Switch to valid project**: `switch_project("valid-project-name")`
             3. **Verify project setup**: Ensure your project is properly configured
 
             ## Current session info:
             - Check current project: `get_current_project()`
-            - See available projects: `list_projects()`
+            - See available projects: `list_memory_projects()`
             """).strip()
 
     # No results found
@@ -85,24 +90,39 @@ def _format_search_error_response(error_message: str, query: str, search_type: s
 
             No content found matching '{query}' in the current project.
 
-            ## Suggestions to try:
+            ## Search strategy suggestions:
             1. **Broaden your search**: Try fewer or more general terms
                - Instead of: `{query}`
                - Try: `{simplified_query}`
 
-            2. **Check spelling**: Verify terms are spelled correctly
-            3. **Try different search types**:
-               - Text search: `search_notes("{query}", search_type="text")`
-               - Title search: `search_notes("{query}", search_type="title")`
-               - Permalink search: `search_notes("{query}", search_type="permalink")`
+            2. **Check spelling and try variations**:
+               - Verify terms are spelled correctly
+               - Try synonyms or related terms
 
-            4. **Use boolean operators**:
-               - Try OR search for broader results
+            3. **Use different search approaches**:
+               - **Text search**: `search_notes("{query}", search_type="text")` (searches full content)
+               - **Title search**: `search_notes("{query}", search_type="title")` (searches only titles)
+               - **Permalink search**: `search_notes("{query}", search_type="permalink")` (searches file paths)
 
-            ## Check what content exists:
-            - Recent activity: `recent_activity(timeframe="7d")`
-            - List files: `list_directory("/")`
-            - Browse by folder: `list_directory("/notes")` or `list_directory("/docs")`
+            4. **Try boolean operators for broader results**:
+               - OR search: `search_notes("{' OR '.join(query.split()[:3])}")`
+               - Remove restrictive terms: Focus on the most important keywords
+
+            5. **Use filtering to narrow scope**:
+               - By content type: `search_notes("{query}", types=["entity"])`
+               - By recent content: `search_notes("{query}", after_date="1 week")`
+               - By entity type: `search_notes("{query}", entity_types=["observation"])`
+
+            6. **Try advanced search patterns**:
+               - Tag search: `search_notes("tag:your-tag")`
+               - Category search: `search_notes("category:observation")`
+               - Pattern matching: `search_notes("*{query}*", search_type="permalink")`
+
+            ## Explore what content exists:
+            - **Recent activity**: `recent_activity(timeframe="7d")` - See what's been updated recently
+            - **List directories**: `list_directory("/")` - Browse all content
+            - **Browse by folder**: `list_directory("/notes")` or `list_directory("/docs")`
+            - **Check project**: `get_current_project()` - Verify you're in the right project
             """).strip()
 
     # Server/API errors
@@ -142,7 +162,7 @@ You don't have permission to search in the current project: {error_message}
 3. **Check authentication**: You might need to re-authenticate
 
 ## Alternative actions:
-- List available projects: `list_projects()`
+- List available projects: `list_memory_projects()`
 - Switch to accessible project: `switch_project("project-name")`
 - Check current project: `get_current_project()`"""
 
@@ -151,25 +171,36 @@ You don't have permission to search in the current project: {error_message}
 
 Error searching for '{query}': {error_message}
 
-## General troubleshooting:
-1. **Check your query**: Ensure it uses valid search syntax
-2. **Try simpler terms**: Use basic words without special characters
+## Troubleshooting steps:
+1. **Simplify your query**: Try basic words without special characters
+2. **Check search syntax**: Ensure boolean operators are correctly formatted
 3. **Verify project access**: Make sure you can access the current project
-4. **Check recent activity**: `recent_activity(timeframe="7d")` to see if content exists
+4. **Test with simple search**: Try `search_notes("test")` to verify search is working
 
-## Alternative approaches:
-- Browse files: `list_directory("/")`
-- Try different search type: `search_notes("{query}", search_type="title")`
-- Search with filters: `search_notes("{query}", types=["entity"])`
+## Alternative search approaches:
+- **Different search types**: 
+  - Title only: `search_notes("{query}", search_type="title")`
+  - Permalink patterns: `search_notes("{query}*", search_type="permalink")`
+- **With filters**: `search_notes("{query}", types=["entity"])`
+- **Recent content**: `search_notes("{query}", after_date="1 week")`
+- **Boolean variations**: `search_notes("{' OR '.join(query.split()[:2])}")`
 
-## Need help?
-- View recent changes: `recent_activity()`
-- List projects: `list_projects()` 
-- Check current project: `get_current_project()`"""
+## Explore your content:
+- **Browse files**: `list_directory("/")` - See all available content
+- **Recent activity**: `recent_activity(timeframe="7d")` - Check what's been updated
+- **Project info**: `get_current_project()` - Verify current project
+- **All projects**: `list_memory_projects()` - Switch to different project if needed
+
+## Search syntax reference:
+- **Basic**: `keyword` or `multiple words`
+- **Boolean**: `term1 AND term2`, `term1 OR term2`, `term1 NOT term2`
+- **Phrases**: `"exact phrase"`
+- **Grouping**: `(term1 OR term2) AND term3`
+- **Patterns**: `tag:example`, `category:observation`"""
 
 
 @mcp.tool(
-    description="Search across all content in the knowledge base.",
+    description="Search across all content in the knowledge base with advanced syntax support.",
 )
 async def search_notes(
     query: str,
@@ -181,24 +212,60 @@ async def search_notes(
     after_date: Optional[str] = None,
     project: Optional[str] = None,
 ) -> SearchResponse | str:
-    """Search across all content in the knowledge base.
+    """Search across all content in the knowledge base with comprehensive syntax support.
 
     This tool searches the knowledge base using full-text search, pattern matching,
     or exact permalink lookup. It supports filtering by content type, entity type,
-    and date.
+    and date, with advanced boolean and phrase search capabilities.
+
+    ## Search Syntax Examples
+
+    ### Basic Searches
+    - `search_notes("keyword")` - Find any content containing "keyword"
+    - `search_notes("exact phrase")` - Search for exact phrase match
+
+    ### Advanced Boolean Searches  
+    - `search_notes("term1 term2")` - Find content with both terms (implicit AND)
+    - `search_notes("term1 AND term2")` - Explicit AND search (both terms required)
+    - `search_notes("term1 OR term2")` - Either term can be present
+    - `search_notes("term1 NOT term2")` - Include term1 but exclude term2
+    - `search_notes("(project OR planning) AND notes")` - Grouped boolean logic
+
+    ### Content-Specific Searches
+    - `search_notes("tag:example")` - Search within specific tags (if supported by content)
+    - `search_notes("category:observation")` - Filter by observation categories
+    - `search_notes("author:username")` - Find content by author (if metadata available)
+
+    ### Search Type Examples
+    - `search_notes("Meeting", search_type="title")` - Search only in titles
+    - `search_notes("docs/meeting-*", search_type="permalink")` - Pattern match permalinks
+    - `search_notes("keyword", search_type="text")` - Full-text search (default)
+
+    ### Filtering Options
+    - `search_notes("query", types=["entity"])` - Search only entities
+    - `search_notes("query", types=["note", "person"])` - Multiple content types
+    - `search_notes("query", entity_types=["observation"])` - Filter by entity type
+    - `search_notes("query", after_date="2024-01-01")` - Recent content only
+    - `search_notes("query", after_date="1 week")` - Relative date filtering
+
+    ### Advanced Pattern Examples
+    - `search_notes("project AND (meeting OR discussion)")` - Complex boolean logic
+    - `search_notes("\"exact phrase\" AND keyword")` - Combine phrase and keyword search
+    - `search_notes("bug NOT fixed")` - Exclude resolved issues
+    - `search_notes("docs/2024-*", search_type="permalink")` - Year-based permalink search
 
     Args:
-        query: The search query string
+        query: The search query string (supports boolean operators, phrases, patterns)
         page: The page number of results to return (default 1)
         page_size: The number of results to return per page (default 10)
         search_type: Type of search to perform, one of: "text", "title", "permalink" (default: "text")
         types: Optional list of note types to search (e.g., ["note", "person"])
         entity_types: Optional list of entity types to filter by (e.g., ["entity", "observation"])
-        after_date: Optional date filter for recent content (e.g., "1 week", "2d")
+        after_date: Optional date filter for recent content (e.g., "1 week", "2d", "2024-01-01")
         project: Optional project name to search in. If not provided, uses current active project.
 
     Returns:
-        SearchResponse with results and pagination info
+        SearchResponse with results and pagination info, or helpful error guidance if search fails
 
     Examples:
         # Basic text search
@@ -216,16 +283,19 @@ async def search_notes(
         # Boolean search with grouping
         results = await search_notes("(project OR planning) AND notes")
 
+        # Exact phrase search
+        results = await search_notes("\"weekly standup meeting\"")
+
         # Search with type filter
         results = await search_notes(
             query="meeting notes",
             types=["entity"],
         )
 
-        # Search with entity type filter, e.g., note vs
+        # Search with entity type filter
         results = await search_notes(
             query="meeting notes",
-            types=["entity"],
+            entity_types=["observation"],
         )
 
         # Search for recent content
@@ -242,6 +312,13 @@ async def search_notes(
 
         # Search in specific project
         results = await search_notes("meeting notes", project="work-project")
+
+        # Complex search with multiple filters
+        results = await search_notes(
+            query="(bug OR issue) AND NOT resolved",
+            types=["entity"],
+            after_date="2024-01-01"
+        )
     """
     # Create a SearchQuery object based on the parameters
     search_query = SearchQuery()

src/basic_memory/schemas/response.py

@@ -131,7 +131,7 @@ class EntityResponse(SQLAlchemyModel):
     }
     """
 
-    permalink: Permalink
+    permalink: Optional[Permalink]
     title: str
     file_path: str
     entity_type: EntityType

test-int/mcp/test_move_note_integration.py

@@ -594,7 +594,7 @@ async def test_move_note_potential_cross_project_guidance(mcp_server, app):
         error_message = move_result[0].text
         assert "Check Project Context" in error_message
         assert "workspace-docs" in error_message  # Should mention other available projects
-        assert "list_projects" in error_message
+        assert "list_memory_projects" in error_message
         assert "switch_project" in error_message
 
 

tests/mcp/test_server.py

@@ -93,7 +93,7 @@ class TestMCPServer:
             # Missing SUPABASE_ANON_KEY
         }
 
-        with patch.dict(os.environ, env_vars):
+        with patch.dict(os.environ, env_vars, clear=True):
             with pytest.raises(ValueError, match="SUPABASE_URL and SUPABASE_ANON_KEY must be set"):
                 create_auth_config()
 

tests/mcp/test_tool_edit_note.py

@@ -359,3 +359,42 @@ async def test_edit_note_find_replace_empty_find_text(client):
     assert isinstance(result, str)
     assert "# Edit Failed" in result
     # Should contain helpful guidance about the error
+
+
+@pytest.mark.asyncio
+async def test_edit_note_preserves_permalink_when_frontmatter_missing(client):
+    """Test that editing a note preserves the permalink when frontmatter doesn't contain one.
+    
+    This is a regression test for issue #170 where edit_note would fail with a validation error
+    because the permalink was being set to None when the markdown file didn't have a permalink
+    in its frontmatter.
+    """
+    # Create initial note
+    await write_note.fn(
+        title="Test Note",
+        folder="test",
+        content="# Test Note\nOriginal content here.",
+    )
+
+    # Verify the note was created with a permalink
+    first_result = await edit_note.fn(
+        identifier="test/test-note",
+        operation="append",
+        content="\nFirst edit.",
+    )
+    
+    assert isinstance(first_result, str)
+    assert "permalink: test/test-note" in first_result
+    
+    # Perform another edit - this should preserve the permalink even if the 
+    # file doesn't have a permalink in its frontmatter
+    second_result = await edit_note.fn(
+        identifier="test/test-note",
+        operation="append", 
+        content="\nSecond edit.",
+    )
+
+    assert isinstance(second_result, str)
+    assert "Edited note (append)" in second_result
+    assert "permalink: test/test-note" in second_result
+    # The edit should succeed without validation errors

tests/mcp/test_tool_search.py

@@ -6,6 +6,7 @@ from unittest.mock import patch
 
 from basic_memory.mcp.tools import write_note
 from basic_memory.mcp.tools.search import search_notes, _format_search_error_response
+from basic_memory.schemas.search import SearchResponse
 
 
 @pytest.mark.asyncio
@@ -23,9 +24,14 @@ async def test_search_text(client):
     # Search for it
     response = await search_notes.fn(query="searchable")
 
-    # Verify results
-    assert len(response.results) > 0
-    assert any(r.permalink == "test/test-search-note" for r in response.results)
+    # Verify results - handle both success and error cases
+    if isinstance(response, SearchResponse):
+        # Success case - verify SearchResponse
+        assert len(response.results) > 0
+        assert any(r.permalink == "test/test-search-note" for r in response.results)
+    else:
+        # If search failed and returned error message, test should fail with informative message
+        pytest.fail(f"Search failed with error: {response}")
 
 
 @pytest.mark.asyncio
@@ -43,9 +49,14 @@ async def test_search_title(client):
     # Search for it
     response = await search_notes.fn(query="Search Note", search_type="title")
 
-    # Verify results
-    assert len(response.results) > 0
-    assert any(r.permalink == "test/test-search-note" for r in response.results)
+    # Verify results - handle both success and error cases
+    if isinstance(response, str):
+        # If search failed and returned error message, test should fail with informative message  
+        pytest.fail(f"Search failed with error: {response}")
+    else:
+        # Success case - verify SearchResponse
+        assert len(response.results) > 0
+        assert any(r.permalink == "test/test-search-note" for r in response.results)
 
 
 @pytest.mark.asyncio
@@ -63,9 +74,14 @@ async def test_search_permalink(client):
     # Search for it
     response = await search_notes.fn(query="test/test-search-note", search_type="permalink")
 
-    # Verify results
-    assert len(response.results) > 0
-    assert any(r.permalink == "test/test-search-note" for r in response.results)
+    # Verify results - handle both success and error cases
+    if isinstance(response, SearchResponse):
+        # Success case - verify SearchResponse
+        assert len(response.results) > 0
+        assert any(r.permalink == "test/test-search-note" for r in response.results)
+    else:
+        # If search failed and returned error message, test should fail with informative message
+        pytest.fail(f"Search failed with error: {response}")
 
 
 @pytest.mark.asyncio
@@ -83,9 +99,14 @@ async def test_search_permalink_match(client):
     # Search for it
     response = await search_notes.fn(query="test/test-search-*", search_type="permalink")
 
-    # Verify results
-    assert len(response.results) > 0
-    assert any(r.permalink == "test/test-search-note" for r in response.results)
+    # Verify results - handle both success and error cases
+    if isinstance(response, SearchResponse):
+        # Success case - verify SearchResponse
+        assert len(response.results) > 0
+        assert any(r.permalink == "test/test-search-note" for r in response.results)
+    else:
+        # If search failed and returned error message, test should fail with informative message
+        pytest.fail(f"Search failed with error: {response}")
 
 
 @pytest.mark.asyncio
@@ -103,9 +124,14 @@ async def test_search_pagination(client):
     # Search for it
     response = await search_notes.fn(query="searchable", page=1, page_size=1)
 
-    # Verify results
-    assert len(response.results) == 1
-    assert any(r.permalink == "test/test-search-note" for r in response.results)
+    # Verify results - handle both success and error cases
+    if isinstance(response, SearchResponse):
+        # Success case - verify SearchResponse
+        assert len(response.results) == 1
+        assert any(r.permalink == "test/test-search-note" for r in response.results)
+    else:
+        # If search failed and returned error message, test should fail with informative message
+        pytest.fail(f"Search failed with error: {response}")
 
 
 @pytest.mark.asyncio
@@ -121,8 +147,13 @@ async def test_search_with_type_filter(client):
     # Search with type filter
     response = await search_notes.fn(query="type", types=["note"])
 
-    # Verify all results are entities
-    assert all(r.type == "entity" for r in response.results)
+    # Verify results - handle both success and error cases
+    if isinstance(response, SearchResponse):
+        # Success case - verify all results are entities
+        assert all(r.type == "entity" for r in response.results)
+    else:
+        # If search failed and returned error message, test should fail with informative message
+        pytest.fail(f"Search failed with error: {response}")
 
 
 @pytest.mark.asyncio
@@ -138,8 +169,13 @@ async def test_search_with_entity_type_filter(client):
     # Search with entity type filter
     response = await search_notes.fn(query="type", entity_types=["entity"])
 
-    # Verify all results are entities
-    assert all(r.type == "entity" for r in response.results)
+    # Verify results - handle both success and error cases
+    if isinstance(response, SearchResponse):
+        # Success case - verify all results are entities
+        assert all(r.type == "entity" for r in response.results)
+    else:
+        # If search failed and returned error message, test should fail with informative message
+        pytest.fail(f"Search failed with error: {response}")
 
 
 @pytest.mark.asyncio
@@ -156,8 +192,13 @@ async def test_search_with_date_filter(client):
     one_hour_ago = datetime.now() - timedelta(hours=1)
     response = await search_notes.fn(query="recent", after_date=one_hour_ago.isoformat())
 
-    # Verify we get results within timeframe
-    assert len(response.results) > 0
+    # Verify results - handle both success and error cases
+    if isinstance(response, SearchResponse):
+        # Success case - verify we get results within timeframe
+        assert len(response.results) > 0
+    else:
+        # If search failed and returned error message, test should fail with informative message
+        pytest.fail(f"Search failed with error: {response}")
 
 
 class TestSearchErrorFormatting:
@@ -212,7 +253,7 @@ class TestSearchErrorFormatting:
 
         assert "# Search Failed" in result
         assert "Error searching for 'test query': unknown error" in result
-        assert "General troubleshooting" in result
+        assert "## Troubleshooting steps:" in result
 
 
 class TestSearchToolErrorHandling:

tests/repository/test_search_repository.py

@@ -551,12 +551,14 @@ class TestSearchTermPreparation:
     def test_boolean_query_empty_parts_coverage(self, search_repository):
         """Test Boolean query parsing with empty parts (line 143 coverage)."""
         # Create queries that will result in empty parts after splitting
-        result1 = search_repository._prepare_boolean_query("hello AND  AND world")  # Double operator
+        result1 = search_repository._prepare_boolean_query(
+            "hello AND  AND world"
+        )  # Double operator
         assert "hello" in result1 and "world" in result1
-        
+
         result2 = search_repository._prepare_boolean_query("  OR test")  # Leading operator
         assert "test" in result2
-        
+
         result3 = search_repository._prepare_boolean_query("test OR  ")  # Trailing operator
         assert "test" in result3
 
@@ -566,19 +568,19 @@ class TestSearchTermPreparation:
         result = search_repository._prepare_parenthetical_term('(say "hello" world)')
         # Should escape quotes by doubling them
         assert '""hello""' in result
-        
+
         # Test term with single quotes
-        result2 = search_repository._prepare_parenthetical_term('(it\'s working)')
+        result2 = search_repository._prepare_parenthetical_term("(it's working)")
         assert "it's working" in result2
 
     def test_needs_quoting_empty_input(self, search_repository):
         """Test _needs_quoting with empty inputs (line 207 coverage)."""
         # Test empty string
         assert not search_repository._needs_quoting("")
-        
+
         # Test whitespace-only string
         assert not search_repository._needs_quoting("   ")
-        
+
         # Test None-like cases
         assert not search_repository._needs_quoting("\t")
 
@@ -587,11 +589,11 @@ class TestSearchTermPreparation:
         # Test empty string
         result1 = search_repository._prepare_single_term("")
         assert result1 == ""
-        
+
         # Test whitespace-only string
         result2 = search_repository._prepare_single_term("   ")
         assert result2 == "   "  # Should return as-is
-        
+
         # Test string that becomes empty after strip
         result3 = search_repository._prepare_single_term("\t\n")
         assert result3 == "\t\n"  # Should return original

tests/schemas/test_schemas.py

@@ -127,6 +127,36 @@ def test_entity_out_from_attributes():
     assert len(entity.relations) == 1
 
 
+def test_entity_response_with_none_permalink():
+    """Test EntityResponse can handle None permalink (fixes issue #170).
+    
+    This test ensures that EntityResponse properly validates when the permalink
+    field is None, which can occur when markdown files don't have explicit 
+    permalinks in their frontmatter during edit operations.
+    """
+    # Simulate database model attributes with None permalink
+    db_data = {
+        "title": "Test Entity",
+        "permalink": None,  # This should not cause validation errors
+        "file_path": "test/test-entity.md",
+        "entity_type": "note",
+        "content_type": "text/markdown",
+        "observations": [],
+        "relations": [],
+        "created_at": "2023-01-01T00:00:00",
+        "updated_at": "2023-01-01T00:00:00",
+    }
+    
+    # This should not raise a ValidationError
+    entity = EntityResponse.model_validate(db_data)
+    assert entity.permalink is None
+    assert entity.title == "Test Entity"
+    assert entity.file_path == "test/test-entity.md"
+    assert entity.entity_type == "note"
+    assert len(entity.observations) == 0
+    assert len(entity.relations) == 0
+
+
 def test_search_nodes_input():
     """Test SearchNodesInput validation."""
     search = SearchNodesRequest.model_validate({"query": "test query"})