basic-memory 0.13.0b5__tar.gz → 0.13.1__tar.gz

{basic_memory-0.13.0b5 → basic_memory-0.13.1}/.github/workflows/release.yml

@@ -32,17 +32,11 @@ jobs:
           uv sync
           uv build
 
-      - name: Verify version matches tag
+      - name: Verify build succeeded
         run: |
-          # Get version from built package
-          PACKAGE_VERSION=$(uv run python -c "import basic_memory; print(basic_memory.__version__)")
-          TAG_VERSION=${GITHUB_REF_NAME#v}  # Remove 'v' prefix from tag
-          echo "Package version: $PACKAGE_VERSION"
-          echo "Tag version: $TAG_VERSION"
-          if [ "$PACKAGE_VERSION" != "$TAG_VERSION" ]; then
-            echo "Version mismatch! Package: $PACKAGE_VERSION, Tag: $TAG_VERSION"
-            exit 1
-          fi
+          # Verify that build artifacts exist
+          ls -la dist/
+          echo "Build completed successfully"
 
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2

{basic_memory-0.13.0b5 → basic_memory-0.13.1}/CHANGELOG.md

@@ -1,80 +1,246 @@
 # CHANGELOG
 
+## v0.13.1 (2025-06-11)
 
-## v0.13.0 (2025-06-03)
+### Bug Fixes
 
-### Features
+- **CLI**: Fixed  `basic-memory project` project management commands that were  not working in v0.13.0 (#129)
+- **Projects**: Resolved case sensitivity issues when switching between projects that caused "Project not found" errors (#127)
+- **API**: Standardized CLI project command endpoints and improved error handling
+- **Core**: Implemented consistent project name handling using permalinks to avoid case-related conflicts
 
-- **Multi-Project Management System** - Switch between projects instantly during conversations
-  ([`993e88a`](https://github.com/basicmachines-co/basic-memory/commit/993e88a)) 
-  - Instant project switching with session context
-  - Project-specific operations and isolation
-  - Project discovery and management tools
+### Changes
 
-- **Advanced Note Editing** - Incremental editing with append, prepend, find/replace, and section operations
-  ([`6fc3904`](https://github.com/basicmachines-co/basic-memory/commit/6fc3904))
-  - `edit_note` tool with multiple operation types
-  - Smart frontmatter-aware editing
-  - Validation and error handling
+- Renamed `basic-memory project sync` command to `basic-memory project sync-config` for clarity
+- Improved project switching reliability across different case variations
+- Removed redundant server status messages from CLI error outputs
 
-- **Smart File Management** - Move notes with database consistency and search reindexing
-  ([`9fb931c`](https://github.com/basicmachines-co/basic-memory/commit/9fb931c))
-  - `move_note` tool with rollback protection
-  - Automatic folder creation and permalink updates
-  - Full database consistency maintenance
+## v0.13.0 (2025-06-11)
 
-- **Enhanced Search Capabilities** - Frontmatter tags now searchable, improved content discovery
-  ([`3f5368e`](https://github.com/basicmachines-co/basic-memory/commit/3f5368e))
-  - YAML frontmatter tag indexing
-  - Improved FTS5 search functionality
-  - Project-scoped search operations
+### Overview
 
-- **Production Features** - OAuth authentication, development builds, comprehensive testing
-  ([`5f8d945`](https://github.com/basicmachines-co/basic-memory/commit/5f8d945))
-  - Development build automation
-  - MCP integration testing framework
-  - Enhanced CI/CD pipeline
+Basic Memory v0.13.0 is a **major release** that transforms Basic Memory into a true multi-project knowledge management system. This release introduces fluid project switching, advanced note editing capabilities, robust file management, and production-ready OAuth authentication - all while maintaining full backward compatibility.
 
-### Bug Fixes
+**What's New for Users:**
+- 🎯 **Switch between projects instantly** during conversations with Claude
+- ✏️ **Edit notes incrementally** without rewriting entire documents
+- 📁 **Move and organize notes** with full database consistency
+- 📖 **View notes as formatted artifacts** for better readability in Claude Desktop
+- 🔍 **Search frontmatter tags** to discover content more easily
+- 🔐 **OAuth authentication** for secure remote access
+- ⚡ **Development builds** automatically published for beta testing
 
-- **#118**: Fix YAML tag formatting to follow standard specification
-  ([`2dc7e27`](https://github.com/basicmachines-co/basic-memory/commit/2dc7e27))
+**Key v0.13.0 Accomplishments:**
+- ✅ **Complete Project Management System** - Project switching and project-specific operations
+- ✅ **Advanced Note Editing** - Incremental editing with append, prepend, find/replace, and section operations  
+- ✅ **View Notes as Artifacts in Claude Desktop/Web** - Use the view_note tool to view a note as an artifact
+- ✅ **File Management System** - Full move operations with database consistency and rollback protection
+- ✅ **Enhanced Search Capabilities** - Frontmatter tags now searchable, improved content discoverability
+- ✅ **Unified Database Architecture** - Single app-level database for better performance and project management
 
-- **#110**: Make --project flag work consistently across CLI commands
-  ([`02dd91a`](https://github.com/basicmachines-co/basic-memory/commit/02dd91a))
+### Major Features
 
-- **#93**: Respect custom permalinks in frontmatter for write_note
-  ([`6b6fd76`](https://github.com/basicmachines-co/basic-memory/commit/6b6fd76))
+#### 1. Multiple Project Management 
 
-- Fix list_directory path display to not include leading slash
-  ([`6057126`](https://github.com/basicmachines-co/basic-memory/commit/6057126))
+**Switch between projects instantly during conversations:**
 
-### Technical Improvements
+```
+💬 "What projects do I have?"
+🤖 Available projects:
+   • main (current, default)
+   • work-notes
+   • personal-journal
+   • code-snippets
 
-- **Unified Database Architecture** - Single app-level database for better performance
-  - Migration from per-project databases to unified structure
-  - Project isolation with foreign key relationships
-  - Optimized queries and reduced file I/O
+💬 "Switch to work-notes"
+🤖 ✓ Switched to work-notes project
+   
+   Project Summary:
+   • 47 entities
+   • 125 observations  
+   • 23 relations
 
-- **Comprehensive Testing** - 100% test coverage with integration testing
-  ([`468a22f`](https://github.com/basicmachines-co/basic-memory/commit/468a22f))
-  - MCP integration test suite
-  - End-to-end testing framework
-  - Performance and edge case validation
+💬 "What did I work on yesterday?"
+🤖 [Shows recent activity from work-notes project]
+```
+
+**Key Capabilities:**
+- **Instant Project Switching**: Change project context mid-conversation without restart
+- **Project-Specific Operations**: Operations work within the currently active project context
+- **Project Discovery**: List all available projects with status indicators
+- **Session Context**: Maintains active project throughout conversation
+- **Backward Compatibility**: Existing single-project setups continue to work seamlessly
 
-### Documentation
+#### 2. Advanced Note Editing 
+
+**Edit notes incrementally without rewriting entire documents:**
+
+```python
+# Append new sections to existing notes
+edit_note("project-planning", "append", "\n## New Requirements\n- Feature X\n- Feature Y")
+
+# Prepend timestamps to meeting notes
+edit_note("meeting-notes", "prepend", "## 2025-05-27 Update\n- Progress update...")
+
+# Replace specific sections under headers
+edit_note("api-spec", "replace_section", "New implementation details", section="## Implementation")
+
+# Find and replace with validation
+edit_note("config", "find_replace", "v0.13.0", find_text="v0.12.0", expected_replacements=2)
+```
+
+**Key Capabilities:**
+- **Append Operations**: Add content to end of notes (most common use case)
+- **Prepend Operations**: Add content to beginning of notes
+- **Section Replacement**: Replace content under specific markdown headers
+- **Find & Replace**: Simple text replacements with occurrence counting
+- **Smart Error Handling**: Helpful guidance when operations fail
+- **Project Context**: Works within the active project with session awareness
+
+#### 3. Smart File Management
+
+**Move and organize notes:**
+
+```python
+# Simple moves with automatic folder creation
+move_note("my-note", "work/projects/my-note.md")
+
+# Organize within the active project
+move_note("shared-doc", "archive/old-docs/shared-doc.md")
+
+# Rename operations
+move_note("old-name", "same-folder/new-name.md")
+```
+
+**Key Capabilities:**
+- **Database Consistency**: Updates file paths, permalinks, and checksums automatically
+- **Search Reindexing**: Maintains search functionality after moves
+- **Folder Creation**: Automatically creates destination directories
+- **Project Isolation**: Operates within the currently active project
+- **Link Preservation**: Maintains internal links and references
+
+#### 4. Enhanced Search & Discovery 
+
+**Find content more easily with improved search capabilities:**
+
+- **Frontmatter Tag Search**: Tags from YAML frontmatter are now indexed and searchable
+- **Improved Content Discovery**: Search across titles, content, tags, and metadata
+- **Project-Scoped Search**: Search within the currently active project
+- **Better Search Quality**: Enhanced FTS5 indexing with tag content inclusion
+
+**Example:**
+```yaml
+---
+title: Coffee Brewing Methods
+tags: [coffee, brewing, equipment]
+---
+```
+Now searchable by: "coffee", "brewing", "equipment", or "Coffee Brewing Methods"
+
+#### 5. Unified Database Architecture 
+
+**Single app-level database for better performance and project management:**
+
+- **Migration from Per-Project DBs**: Moved from multiple SQLite files to single app database
+- **Project Isolation**: Proper data separation with project_id foreign keys
+- **Better Performance**: Optimized queries and reduced file I/O
+
+### Complete MCP Tool Suite
+
+#### New Project Management Tools
+- **`list_projects()`** - Discover and list all available projects with status
+- **`switch_project(project_name)`** - Change active project context during conversations
+- **`get_current_project()`** - Show currently active project with statistics
+- **`set_default_project(project_name)`** - Update default project configuration
+- **`sync_status()`** - Check file synchronization status and background operations
+
+#### New Note Operations Tools
+- **`edit_note()`** - Incremental note editing (append, prepend, find/replace, section replace)
+- **`move_note()`** - Move notes with database consistency and search reindexing
+- **`view_note()`** - Display notes as formatted artifacts for better readability in Claude Desktop
+
+#### Enhanced Existing Tools
+All existing tools now support:
+- **Session context awareness** (operates within the currently active project)
+- **Enhanced error messages** with project context metadata
+- **Improved response formatting** with project information footers
+- **Project isolation** ensures operations stay within the correct project boundaries
+
+
+### User Experience Improvements
+
+#### Installation Options
+
+**Multiple ways to install and test Basic Memory:**
+
+```bash
+# Stable release
+uv tool install basic-memory
+
+# Beta/pre-releases
+uv tool install basic-memory --pre
+```
+
+
+#### Bug Fixes & Quality Improvements
+
+**Major issues resolved in v0.13.0:**
+
+- **#118**: Fixed YAML tag formatting to follow standard specification
+- **#110**: Fixed `--project` flag consistency across all CLI commands
+- **#107**: Fixed write_note update failures with existing notes
+- **#93**: Fixed custom permalink handling in frontmatter
+- **#52**: Enhanced search capabilities with frontmatter tag indexing
+- **FTS5 Search**: Fixed special character handling in search queries
+- **Error Handling**: Improved error messages and validation across all tools
+
+### Breaking Changes & Migration
+
+#### For Existing Users
+
+**Automatic Migration**: First run will automatically migrate existing data to the new unified database structure. No manual action required.
+
+**What Changes:**
+- Database location: Moved to `~/.basic-memory/memory.db` (unified across projects)
+- Configuration: Projects defined in `~/.basic-memory/config.json` are synced with database
+
+**What Stays the Same:**
+- All existing notes and data remain unchanged
+- Default project behavior maintained for single-project users
+- All existing MCP tools continue to work without modification
+
+### Documentation & Resources
+
+#### New Documentation
+- [Project Management Guide](docs/Project%20Management.md) - Multi-project workflows
+- [Note Editing Guide](docs/Note%20Editing.md) - Advanced editing techniques
+
+#### Updated Documentation
+- [README.md](README.md) - Installation options and beta build instructions
+- [CONTRIBUTING.md](CONTRIBUTING.md) - Release process and version management
+- [CLAUDE.md](CLAUDE.md) - Development workflow and CI/CD documentation
+- [Claude.ai Integration](docs/Claude.ai%20Integration.md) - Updated MCP tool examples
+
+#### Quick Start Examples
+
+**Project Switching:**
+```
+💬 "Switch to my work project and show recent activity"
+🤖 [Calls switch_project("work") then recent_activity()]
+```
 
-- Add comprehensive testing documentation (TESTING.md)
-- Update project management guides (PROJECT_MANAGEMENT.md)
-- Enhanced note editing documentation (EDIT_NOTE.md)
-- Updated release workflow documentation
+**Note Editing:**
+```
+💬 "Add a section about deployment to my API docs"
+🤖 [Calls edit_note("api-docs", "append", "## Deployment\n...")]
+```
 
-### Breaking Changes
+**File Organization:**
+```
+💬 "Move my old meeting notes to the archive folder"
+🤖 [Calls move_note("meeting-notes", "archive/old-meetings.md")]
+```
 
-- **Database Migration**: Automatic migration from per-project to unified database. 
-    Data will be re-index from the filesystem, resulting in no data loss. 
-- **Configuration Changes**: Projects now synced between config.json and database
-- **Full Backward Compatibility**: All existing setups continue to work seamlessly
 
 
 ## v0.12.3 (2025-04-17)
@@ -861,4 +1027,4 @@ Co-authored-by: phernandez <phernandez@basicmachines.co>
 ### Chores
 
 - Remove basic-foundation src ref in pyproject.toml
-  ([`29fce8b`](https://github.com/basicmachines-co/basic-memory/commit/29fce8b0b922d54d7799bf2534107ee6cfb961b8))
+  ([`29fce8b`](https://github.com/basicmachines-co/basic-memory/commit/29fce8b0b922d54d7799bf2534107ee6cfb961b8))

{basic_memory-0.13.0b5 → basic_memory-0.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: basic-memory
-Version: 0.13.0b5
+Version: 0.13.1
 Summary: Local-first knowledge management combining Zettelkasten with knowledge graphs
 Project-URL: Homepage, https://github.com/basicmachines-co/basic-memory
 Project-URL: Repository, https://github.com/basicmachines-co/basic-memory

{basic_memory-0.13.0b5 → basic_memory-0.13.1}/docs/AI Assistant Guide.md

@@ -77,6 +77,13 @@ read_note("specs/search-design")        # By path
 read_note("memory://specs/search")      # By memory URL
 ```
 
+**Viewing notes as formatted artifacts (Claude Desktop):**
+```
+view_note("Search Design")              # Creates readable artifact
+view_note("specs/search-design")        # By permalink
+view_note("memory://specs/search")      # By memory URL
+```
+
 **Incremental editing** (v0.13.0):
 ```
 edit_note(

{basic_memory-0.13.0b5 → basic_memory-0.13.1}/src/basic_memory/__init__.py

@@ -1,3 +1,4 @@
 """basic-memory - Local-first knowledge management combining Zettelkasten with knowledge graphs"""
 
-__version__ = "0.13.0b5"
+# API version for FastAPI - independent of package version
+__version__ = "v0"

{basic_memory-0.13.0b5 → basic_memory-0.13.1}/src/basic_memory/cli/commands/project.py

@@ -174,7 +174,7 @@ def display_project_info(
     """Display detailed information and statistics about the current project."""
     try:
         # Get project info
-        info = asyncio.run(project_info())
+        info = asyncio.run(project_info.fn())  # type: ignore  # pyright: ignore [reportAttributeAccessIssue]
 
         if json_output:
             # Convert to JSON and print

{basic_memory-0.13.0b5 → basic_memory-0.13.1}/src/basic_memory/cli/commands/tool.py

@@ -90,7 +90,7 @@ def write_note(
             typer.echo("Empty content provided. Please provide non-empty content.", err=True)
             raise typer.Exit(1)
 
-        note = asyncio.run(mcp_write_note(title, content, folder, tags))
+        note = asyncio.run(mcp_write_note.fn(title, content, folder, tags))
         rprint(note)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
@@ -103,7 +103,7 @@ def write_note(
 def read_note(identifier: str, page: int = 1, page_size: int = 10):
     """Read a markdown note from the knowledge base."""
     try:
-        note = asyncio.run(mcp_read_note(identifier, page, page_size))
+        note = asyncio.run(mcp_read_note.fn(identifier, page, page_size))
         rprint(note)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
@@ -124,7 +124,7 @@ def build_context(
     """Get context needed to continue a discussion."""
     try:
         context = asyncio.run(
-            mcp_build_context(
+            mcp_build_context.fn(
                 url=url,
                 depth=depth,
                 timeframe=timeframe,
@@ -157,7 +157,7 @@ def recent_activity(
     """Get recent activity across the knowledge base."""
     try:
         context = asyncio.run(
-            mcp_recent_activity(
+            mcp_recent_activity.fn(
                 type=type,  # pyright: ignore [reportArgumentType]
                 depth=depth,
                 timeframe=timeframe,
@@ -210,7 +210,7 @@ def search_notes(
         search_type = "text" if search_type is None else search_type
 
         results = asyncio.run(
-            mcp_search(
+            mcp_search.fn(
                 query,
                 search_type=search_type,
                 page=page,
@@ -241,7 +241,7 @@ def continue_conversation(
     """Prompt to continue a previous conversation or work session."""
     try:
         # Prompt functions return formatted strings directly
-        session = asyncio.run(mcp_continue_conversation(topic=topic, timeframe=timeframe))
+        session = asyncio.run(mcp_continue_conversation.fn(topic=topic, timeframe=timeframe))  # type: ignore
         rprint(session)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):

{basic_memory-0.13.0b5 → basic_memory-0.13.1}/src/basic_memory/mcp/prompts/recent_activity.py

@@ -38,7 +38,7 @@ async def recent_activity_prompt(
     """
     logger.info(f"Getting recent activity, timeframe: {timeframe}")
 
-    recent = await recent_activity(timeframe=timeframe, type=[SearchItemType.ENTITY])
+    recent = await recent_activity.fn(timeframe=timeframe, type=[SearchItemType.ENTITY])
 
     # Extract primary results from the hierarchical structure
     primary_results = []

{basic_memory-0.13.0b5 → basic_memory-0.13.1}/src/basic_memory/mcp/tools/read_note.py

@@ -81,7 +81,7 @@ async def read_note(
 
     # Fallback 1: Try title search via API
     logger.info(f"Search title for: {identifier}")
-    title_results = await search_notes(query=identifier, search_type="title", project=project)
+    title_results = await search_notes.fn(query=identifier, search_type="title", project=project)
 
     if title_results and title_results.results:
         result = title_results.results[0]  # Get the first/best match
@@ -105,7 +105,7 @@ async def read_note(
 
     # Fallback 2: Text search as a last resort
     logger.info(f"Title search failed, trying text search for: {identifier}")
-    text_results = await search_notes(query=identifier, search_type="text", project=project)
+    text_results = await search_notes.fn(query=identifier, search_type="text", project=project)
 
     # We didn't find a direct match, construct a helpful error message
     if not text_results or not text_results.results:

{basic_memory-0.13.0b5 → basic_memory-0.13.1}/src/basic_memory/mcp/tools/view_note.py

@@ -37,7 +37,7 @@ async def view_note(
     logger.info(f"Viewing note: {identifier}")
 
     # Call the existing read_note logic
-    content = await read_note(identifier, page, page_size, project)
+    content = await read_note.fn(identifier, page, page_size, project)
 
     # Check if this is an error message (note not found)
     if "# Note Not Found:" in content:

{basic_memory-0.13.0b5 → basic_memory-0.13.1}/src/basic_memory/repository/search_repository.py

@@ -237,19 +237,24 @@ class SearchRepository:
 
         # Handle text search for title and content
         if search_text:
-            # Check for explicit boolean operators - only detect them in proper boolean contexts
-            has_boolean = any(op in f" {search_text} " for op in [" AND ", " OR ", " NOT "])
-
-            if has_boolean:
-                # If boolean operators are present, use the raw query
-                # No need to prepare it, FTS5 will understand the operators
-                params["text"] = search_text
-                conditions.append("(title MATCH :text OR content_stems MATCH :text)")
+            # Skip FTS for wildcard-only queries that would cause "unknown special query" errors
+            if search_text.strip() == "*" or search_text.strip() == "":
+                # For wildcard searches, don't add any text conditions - return all results
+                pass
             else:
-                # Standard search with term preparation
-                processed_text = self._prepare_search_term(search_text.strip())
-                params["text"] = processed_text
-                conditions.append("(title MATCH :text OR content_stems MATCH :text)")
+                # Check for explicit boolean operators - only detect them in proper boolean contexts
+                has_boolean = any(op in f" {search_text} " for op in [" AND ", " OR ", " NOT "])
+
+                if has_boolean:
+                    # If boolean operators are present, use the raw query
+                    # No need to prepare it, FTS5 will understand the operators
+                    params["text"] = search_text
+                    conditions.append("(title MATCH :text OR content_stems MATCH :text)")
+                else:
+                    # Standard search with term preparation
+                    processed_text = self._prepare_search_term(search_text.strip())
+                    params["text"] = processed_text
+                    conditions.append("(title MATCH :text OR content_stems MATCH :text)")
 
         # Handle title match search
         if title:

{basic_memory-0.13.0b5 → basic_memory-0.13.1}/src/basic_memory/services/entity_service.py

@@ -299,7 +299,20 @@ class EntityService(BaseService[EntityModel]):
         # Mark as incomplete because we still need to add relations
         model.checksum = None
         # Repository will set project_id automatically
-        return await self.repository.add(model)
+        try:
+            return await self.repository.add(model)
+        except IntegrityError as e:
+            # Handle race condition where entity was created by another process
+            if "UNIQUE constraint failed: entity.file_path" in str(
+                e
+            ) or "UNIQUE constraint failed: entity.permalink" in str(e):
+                logger.info(
+                    f"Entity already exists for file_path={file_path} (file_path or permalink conflict), updating instead of creating"
+                )
+                return await self.update_entity_and_observations(file_path, markdown)
+            else:
+                # Re-raise if it's a different integrity error
+                raise
 
     async def update_entity_and_observations(
         self, file_path: Path, markdown: EntityMarkdown

{basic_memory-0.13.0b5 → basic_memory-0.13.1}/src/basic_memory/services/project_service.py

@@ -209,8 +209,29 @@ class ProjectService:
         db_projects = await self.repository.get_active_projects()
         db_projects_by_name = {p.name: p for p in db_projects}
 
-        # Get all projects from configuration
-        config_projects = config_manager.projects
+        # Get all projects from configuration and normalize names if needed
+        config_projects = config_manager.projects.copy()
+        updated_config = {}
+        config_updated = False
+
+        for name, path in config_projects.items():
+            # Generate normalized name (what the database expects)
+            normalized_name = generate_permalink(name)
+
+            if normalized_name != name:
+                logger.info(f"Normalizing project name in config: '{name}' -> '{normalized_name}'")
+                config_updated = True
+
+            updated_config[normalized_name] = path
+
+        # Update the configuration if any changes were made
+        if config_updated:
+            config_manager.config.projects = updated_config
+            config_manager.save_config(config_manager.config)
+            logger.info("Config updated with normalized project names")
+
+        # Use the normalized config for further processing
+        config_projects = updated_config
 
         # Add projects that exist in config but not in DB
         for name, path in config_projects.items():
@@ -219,7 +240,7 @@ class ProjectService:
                 project_data = {
                     "name": name,
                     "path": path,
-                    "permalink": name.lower().replace(" ", "-"),
+                    "permalink": generate_permalink(name),
                     "is_active": True,
                     # Don't set is_default here - let the enforcement logic handle it
                 }

{basic_memory-0.13.0b5 → basic_memory-0.13.1}/src/basic_memory/sync/sync_service.py

@@ -364,18 +364,43 @@ class SyncService:
             content_type = self.file_service.content_type(path)
 
             file_path = Path(path)
-            entity = await self.entity_repository.add(
-                Entity(
-                    entity_type="file",
-                    file_path=path,
-                    checksum=checksum,
-                    title=file_path.name,
-                    created_at=created,
-                    updated_at=modified,
-                    content_type=content_type,
+            try:
+                entity = await self.entity_repository.add(
+                    Entity(
+                        entity_type="file",
+                        file_path=path,
+                        checksum=checksum,
+                        title=file_path.name,
+                        created_at=created,
+                        updated_at=modified,
+                        content_type=content_type,
+                    )
                 )
-            )
-            return entity, checksum
+                return entity, checksum
+            except IntegrityError as e:
+                # Handle race condition where entity was created by another process
+                if "UNIQUE constraint failed: entity.file_path" in str(e):
+                    logger.info(
+                        f"Entity already exists for file_path={path}, updating instead of creating"
+                    )
+                    # Treat as update instead of create
+                    entity = await self.entity_repository.get_by_file_path(path)
+                    if entity is None:  # pragma: no cover
+                        logger.error(f"Entity not found after constraint violation, path={path}")
+                        raise ValueError(f"Entity not found after constraint violation: {path}")
+
+                    updated = await self.entity_repository.update(
+                        entity.id, {"file_path": path, "checksum": checksum}
+                    )
+
+                    if updated is None:  # pragma: no cover
+                        logger.error(f"Failed to update entity, entity_id={entity.id}, path={path}")
+                        raise ValueError(f"Failed to update entity with ID {entity.id}")
+
+                    return updated, checksum
+                else:
+                    # Re-raise if it's a different integrity error
+                    raise
         else:
             entity = await self.entity_repository.get_by_file_path(path)
             if entity is None:  # pragma: no cover

{basic_memory-0.13.0b5 → basic_memory-0.13.1}/static/ai_assistant_guide.md

@@ -50,6 +50,13 @@ read_note("specs/search-design")         # By permalink
 read_note("memory://specs/search")       # By memory URL
 ```
 
+**Viewing notes as formatted artifacts (Claude Desktop):**
+```
+view_note("Search Design")               # Creates readable artifact
+view_note("specs/search-design")         # By permalink
+view_note("memory://specs/search")       # By memory URL
+```
+
 **Incremental editing (v0.13.0) - REQUIRES EXACT IDENTIFIERS:**
 ```
 edit_note(