basic-memory 0.14.2__tar.gz → 0.14.3__tar.gz

{basic_memory-0.14.2 → basic_memory-0.14.3}/CONTRIBUTING.md

@@ -27,7 +27,12 @@ project and how to get started as a developer.
 
    > **Note**: Basic Memory uses [just](https://just.systems) as a modern command runner. Install with `brew install just` or `cargo install just`.
 
-3. **Run the Tests**:
+3. **Activate the Virtual Environment**
+   ```bash
+   source .venv/bin/activate
+   ```
+
+4. **Run the Tests**:
    ```bash
    # Run all tests
    just test

{basic_memory-0.14.2 → basic_memory-0.14.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: basic-memory
-Version: 0.14.2
+Version: 0.14.3
 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
@@ -13,7 +13,7 @@ Requires-Dist: aiosqlite>=0.20.0
 Requires-Dist: alembic>=1.14.1
 Requires-Dist: dateparser>=1.2.0
 Requires-Dist: fastapi[standard]>=0.115.8
-Requires-Dist: fastmcp<2.10.0,>=2.3.4
+Requires-Dist: fastmcp==2.10.2
 Requires-Dist: greenlet>=3.1.1
 Requires-Dist: icecream>=2.1.3
 Requires-Dist: loguru>=0.7.3

basic_memory-0.14.3/docs/character-handling.md

@@ -0,0 +1,241 @@
+# Character Handling and Conflict Resolution
+
+Basic Memory handles various character encoding scenarios and file naming conventions to provide consistent permalink generation and conflict resolution. This document explains how the system works and how to resolve common character-related issues.
+
+## Overview
+
+Basic Memory uses a sophisticated system to generate permalinks from file paths while maintaining consistency across different operating systems and character encodings. The system normalizes file paths and generates unique permalinks to prevent conflicts.
+
+## Character Normalization Rules
+
+### 1. Permalink Generation
+
+When Basic Memory processes a file path, it applies these normalization rules:
+
+```
+Original: "Finance/My Investment Strategy.md"
+Permalink: "finance/my-investment-strategy"
+```
+
+**Transformation process:**
+1. Remove file extension (`.md`)
+2. Convert to lowercase (case-insensitive)
+3. Replace spaces with hyphens
+4. Replace underscores with hyphens
+5. Handle international characters (transliteration for Latin, preservation for non-Latin)
+6. Convert camelCase to kebab-case
+
+### 2. International Character Support
+
+**Latin characters with diacritics** are transliterated:
+- `ø` → `o` (Søren → soren)
+- `ü` → `u` (Müller → muller)
+- `é` → `e` (Café → cafe)
+- `ñ` → `n` (Niño → nino)
+
+**Non-Latin characters** are preserved:
+- Chinese: `中文/测试文档.md` → `中文/测试文档`
+- Japanese: `日本語/文書.md` → `日本語/文書`
+
+## Common Conflict Scenarios
+
+### 1. Hyphen vs Space Conflicts
+
+**Problem:** Files with existing hyphens conflict with generated permalinks from spaces.
+
+**Example:**
+```
+File 1: "basic memory bug.md"     → permalink: "basic-memory-bug"
+File 2: "basic-memory-bug.md"    → permalink: "basic-memory-bug" (CONFLICT!)
+```
+
+**Resolution:** The system automatically resolves this by adding suffixes:
+```
+File 1: "basic memory bug.md"     → permalink: "basic-memory-bug"
+File 2: "basic-memory-bug.md"    → permalink: "basic-memory-bug-1"
+```
+
+**Best Practice:** Choose consistent naming conventions within your project.
+
+### 2. Case Sensitivity Conflicts
+
+**Problem:** Different case variations that normalize to the same permalink.
+
+**Example on macOS:**
+```
+Directory: Finance/investment.md
+Directory: finance/investment.md  (different on filesystem, same permalink)
+```
+
+**Resolution:** Basic Memory detects case conflicts and prevents them during sync operations with helpful error messages.
+
+**Best Practice:** Use consistent casing for directory and file names.
+
+### 3. Character Encoding Conflicts
+
+**Problem:** Different Unicode normalizations of the same logical character.
+
+**Example:**
+```
+File 1: "café.md" (é as single character)
+File 2: "café.md" (e + combining accent)
+```
+
+**Resolution:** Basic Memory normalizes Unicode characters using NFD normalization to detect these conflicts.
+
+### 4. Forward Slash Conflicts
+
+**Problem:** Forward slashes in frontmatter or file names interpreted as path separators.
+
+**Example:**
+```yaml
+---
+permalink: finance/investment/strategy
+---
+```
+
+**Resolution:** Basic Memory validates frontmatter permalinks and warns about path separator conflicts.
+
+## Error Messages and Troubleshooting
+
+### "UNIQUE constraint failed: entity.file_path, entity.project_id"
+
+**Cause:** Two entities trying to use the same file path within a project.
+
+**Common scenarios:**
+1. File move operation where destination is already occupied
+2. Case sensitivity differences on macOS
+3. Character encoding conflicts
+4. Concurrent file operations
+
+**Resolution steps:**
+1. Check for duplicate file names with different cases
+2. Look for files with similar names but different character encodings
+3. Rename conflicting files to have unique names
+4. Run sync again after resolving conflicts
+
+### "File path conflict detected during move"
+
+**Cause:** Enhanced conflict detection preventing potential database integrity violations.
+
+**What this means:** The system detected that moving a file would create a conflict before attempting the database operation.
+
+**Resolution:** Follow the specific guidance in the error message, which will indicate the type of conflict detected.
+
+## Best Practices
+
+### 1. File Naming Conventions
+
+**Recommended patterns:**
+- Use consistent casing (prefer lowercase)
+- Use hyphens instead of spaces for multi-word files
+- Avoid special characters that could conflict with path separators
+- Be consistent with directory structure casing
+
+**Examples:**
+```
+✅ Good:
+- finance/investment-strategy.md
+- projects/basic-memory-features.md
+- docs/api-reference.md
+
+❌ Problematic:
+- Finance/Investment Strategy.md  (mixed case, spaces)
+- finance/Investment Strategy.md  (inconsistent case)
+- docs/API/Reference.md          (mixed case directories)
+```
+
+### 2. Permalink Management
+
+**Custom permalinks in frontmatter:**
+```yaml
+---
+type: knowledge
+permalink: custom-permalink-name
+---
+```
+
+**Guidelines:**
+- Use lowercase permalinks
+- Use hyphens for word separation
+- Avoid path separators unless creating sub-paths
+- Ensure uniqueness within your project
+
+### 3. Directory Structure
+
+**Consistent casing:**
+```
+✅ Good:
+finance/
+  investment-strategies.md
+  portfolio-management.md
+
+❌ Problematic:  
+Finance/           (capital F)
+  investment-strategies.md
+finance/           (lowercase f) 
+  portfolio-management.md
+```
+
+## Migration and Cleanup
+
+### Identifying Conflicts
+
+Use Basic Memory's built-in conflict detection:
+
+```bash
+# Sync will report conflicts
+basic-memory sync
+
+# Check sync status for warnings
+basic-memory status
+```
+
+### Resolving Existing Conflicts
+
+1. **Identify conflicting files** from sync error messages
+2. **Choose consistent naming convention** for your project
+3. **Rename files** to follow the convention
+4. **Re-run sync** to verify resolution
+
+### Bulk Renaming Strategy
+
+For projects with many conflicts:
+
+1. **Backup your project** before making changes
+2. **Standardize on lowercase** file and directory names
+3. **Replace spaces with hyphens** in file names
+4. **Use consistent character encoding** (UTF-8)
+5. **Test sync after each batch** of changes
+
+## System Enhancements
+
+### Recent Improvements (v0.13+)
+
+1. **Enhanced conflict detection** before database operations
+2. **Improved error messages** with specific resolution guidance
+3. **Character normalization utilities** for consistent handling
+4. **File swap detection** for complex move scenarios
+5. **Proactive conflict warnings** during permalink resolution
+
+### Monitoring and Logging
+
+The system now provides detailed logging for conflict resolution:
+
+```
+DEBUG: Detected potential file path conflicts for 'Finance/Investment.md': ['finance/investment.md']
+WARNING: File path conflict detected during move: entity_id=123 trying to move from 'old.md' to 'new.md'
+```
+
+These logs help identify and resolve conflicts before they cause sync failures.
+
+## Support and Resources
+
+If you encounter character-related conflicts not covered in this guide:
+
+1. **Check the logs** for specific conflict details
+2. **Review error messages** for resolution guidance  
+3. **Report issues** with examples of the conflicting files
+4. **Consider the file naming best practices** outlined above
+
+The Basic Memory system is designed to handle most character conflicts automatically while providing clear guidance for manual resolution when needed.

{basic_memory-0.14.2 → basic_memory-0.14.3}/justfile

@@ -3,6 +3,9 @@
 # Install dependencies
 install:
     pip install -e ".[dev]"
+    uv sync
+    @echo ""
+    @echo "💡 Remember to activate the virtual environment by running: source .venv/bin/activate"
 
 # Run unit tests in parallel
 test-unit:
@@ -179,4 +182,4 @@ beta version:
 
 # List all available recipes
 default:
-    @just --list
+    @just --list

{basic_memory-0.14.2 → basic_memory-0.14.3}/pyproject.toml

@@ -30,7 +30,7 @@ dependencies = [
     "alembic>=1.14.1",
     "pillow>=11.1.0",
     "pybars3>=0.9.7",
-    "fastmcp>=2.3.4,<2.10.0",
+    "fastmcp==2.10.2",
     "pyjwt>=2.10.1",
     "python-dotenv>=1.1.0",
     "pytest-aio>=1.9.0",
@@ -52,7 +52,7 @@ build-backend = "hatchling.build"
 
 [tool.pytest.ini_options]
 pythonpath = ["src", "tests"]
-addopts = "--cov=basic_memory --cov-report term-missing -ra -q"
+addopts = "--cov=basic_memory --cov-report term-missing"
 testpaths = ["tests"]
 asyncio_mode = "strict"
 asyncio_default_fixture_loop_scope = "function"

{basic_memory-0.14.2 → basic_memory-0.14.3}/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.2"
+__version__ = "0.14.3"
 
 # API version for FastAPI - independent of package version
 __api_version__ = "v0"

{basic_memory-0.14.2 → basic_memory-0.14.3}/src/basic_memory/alembic/env.py

@@ -8,17 +8,19 @@ from sqlalchemy import pool
 
 from alembic import context
 
+from basic_memory.config import ConfigManager
+
 # set config.env to "test" for pytest to prevent logging to file in utils.setup_logging()
 os.environ["BASIC_MEMORY_ENV"] = "test"
 
 # Import after setting environment variable  # noqa: E402
-from basic_memory.config import app_config  # noqa: E402
 from basic_memory.models import Base  # noqa: E402
 
 # this is the Alembic Config object, which provides
 # access to the values within the .ini file in use.
 config = context.config
 
+app_config = ConfigManager().config
 # Set the SQLAlchemy URL from our app config
 sqlalchemy_url = f"sqlite:///{app_config.database_path}"
 config.set_main_option("sqlalchemy.url", sqlalchemy_url)

{basic_memory-0.14.2 → basic_memory-0.14.3}/src/basic_memory/api/app.py

@@ -20,15 +20,18 @@ from basic_memory.api.routers import (
     search,
     prompt_router,
 )
-from basic_memory.config import app_config
+from basic_memory.config import ConfigManager
 from basic_memory.services.initialization import initialize_app, initialize_file_sync
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):  # pragma: no cover
     """Lifecycle manager for the FastAPI app."""
+
+    app_config = ConfigManager().config
     # Initialize app and database
     logger.info("Starting Basic Memory API")
+    print(f"fastapi {app_config.projects}")
     await initialize_app(app_config)
 
     logger.info(f"Sync changes enabled: {app_config.sync_changes}")

{basic_memory-0.14.2 → basic_memory-0.14.3}/src/basic_memory/api/routers/management_router.py

@@ -6,7 +6,7 @@ from fastapi import APIRouter, Request
 from loguru import logger
 from pydantic import BaseModel
 
-from basic_memory.config import app_config
+from basic_memory.config import ConfigManager
 from basic_memory.deps import SyncServiceDep, ProjectRepositoryDep
 
 router = APIRouter(prefix="/management", tags=["management"])
@@ -41,6 +41,8 @@ async def start_watch_service(
         # Watch service is already running
         return WatchStatusResponse(running=True)
 
+    app_config = ConfigManager().config
+
     # Create and start a new watch service
     logger.info("Starting watch service via management API")
 

{basic_memory-0.14.2 → basic_memory-0.14.3}/src/basic_memory/api/routers/project_router.py

@@ -1,5 +1,6 @@
 """Router for project management."""
 
+import os
 from fastapi import APIRouter, HTTPException, Path, Body
 from typing import Optional
 
@@ -32,40 +33,47 @@ async def get_project_info(
 @project_router.patch("/{name}", response_model=ProjectStatusResponse)
 async def update_project(
     project_service: ProjectServiceDep,
-    project_name: str = Path(..., description="Name of the project to update"),
-    path: Optional[str] = Body(None, description="New path for the project"),
+    name: str = Path(..., description="Name of the project to update"),
+    path: Optional[str] = Body(None, description="New absolute path for the project"),
     is_active: Optional[bool] = Body(None, description="Status of the project (active/inactive)"),
 ) -> ProjectStatusResponse:
     """Update a project's information in configuration and database.
 
     Args:
-        project_name: The name of the project to update
-        path: Optional new path for the project
+        name: The name of the project to update
+        path: Optional new absolute path for the project
         is_active: Optional status update for the project
 
     Returns:
         Response confirming the project was updated
     """
-    try:  # pragma: no cover
+    try:
+        # Validate that path is absolute if provided
+        if path and not os.path.isabs(path):
+            raise HTTPException(status_code=400, detail="Path must be absolute")
+
         # Get original project info for the response
         old_project_info = ProjectItem(
-            name=project_name,
-            path=project_service.projects.get(project_name, ""),
+            name=name,
+            path=project_service.projects.get(name, ""),
         )
 
-        await project_service.update_project(project_name, updated_path=path, is_active=is_active)
+        if path:
+            await project_service.move_project(name, path)
+        elif is_active is not None:
+            await project_service.update_project(name, is_active=is_active)
 
         # Get updated project info
-        updated_path = path if path else project_service.projects.get(project_name, "")
+        updated_path = path if path else project_service.projects.get(name, "")
 
         return ProjectStatusResponse(
-            message=f"Project '{project_name}' updated successfully",
+            message=f"Project '{name}' updated successfully",
             status="success",
-            default=(project_name == project_service.default_project),
+            default=(name == project_service.default_project),
             old_project=old_project_info,
-            new_project=ProjectItem(name=project_name, path=updated_path),
+            new_project=ProjectItem(name=name, path=updated_path),
         )
-    except ValueError as e:  # pragma: no cover
+    except ValueError as e:
         raise HTTPException(status_code=400, detail=str(e))
 
 

{basic_memory-0.14.2 → basic_memory-0.14.3}/src/basic_memory/cli/app.py

@@ -2,7 +2,7 @@ from typing import Optional
 
 import typer
 
-from basic_memory.config import get_project_config
+from basic_memory.config import get_project_config, ConfigManager
 from basic_memory.mcp.project_session import session
 
 
@@ -10,8 +10,8 @@ def version_callback(value: bool) -> None:
     """Show version and exit."""
     if value:  # pragma: no cover
         import basic_memory
-        from basic_memory.config import config
 
+        config = get_project_config()
         typer.echo(f"Basic Memory version: {basic_memory.__version__}")
         typer.echo(f"Current project: {config.project}")
         typer.echo(f"Project path: {config.home}")
@@ -44,9 +44,9 @@ def app_callback(
 
     # Run initialization for every command unless --version was specified
     if not version and ctx.invoked_subcommand is not None:
-        from basic_memory.config import app_config
         from basic_memory.services.initialization import ensure_initialization
 
+        app_config = ConfigManager().config
         ensure_initialization(app_config)
 
         # Initialize MCP session with the specified project or default

{basic_memory-0.14.2 → basic_memory-0.14.3}/src/basic_memory/cli/commands/__init__.py

@@ -1,10 +1,9 @@
 """CLI commands for basic-memory."""
 
-from . import auth, status, sync, db, import_memory_json, mcp, import_claude_conversations
+from . import status, sync, db, import_memory_json, mcp, import_claude_conversations
 from . import import_claude_projects, import_chatgpt, tool, project
 
 __all__ = [
-    "auth",
     "status",
     "sync",
     "db",

{basic_memory-0.14.2 → basic_memory-0.14.3}/src/basic_memory/cli/commands/db.py

@@ -1,14 +1,13 @@
 """Database management commands."""
 
 import asyncio
-from pathlib import Path
 
 import typer
 from loguru import logger
 
 from basic_memory import db
 from basic_memory.cli.app import app
-from basic_memory.config import app_config, config_manager
+from basic_memory.config import ConfigManager, BasicMemoryConfig, save_basic_memory_config
 
 
 @app.command()
@@ -18,6 +17,8 @@ def reset(
     """Reset database (drop all tables and recreate)."""
     if typer.confirm("This will delete all data in your db. Are you sure?"):
         logger.info("Resetting database...")
+        config_manager = ConfigManager()
+        app_config = config_manager.config
         # Get database path
         db_path = app_config.app_database_path
 
@@ -27,9 +28,8 @@ def reset(
             logger.info(f"Database file deleted: {db_path}")
 
         # Reset project configuration
-        config_manager.config.projects = {"main": str(Path.home() / "basic-memory")}
-        config_manager.config.default_project = "main"
-        config_manager.save_config(config_manager.config)
+        config = BasicMemoryConfig()
+        save_basic_memory_config(config_manager.config_file, config)
         logger.info("Project configuration reset to default")
 
         # Create a new empty database

{basic_memory-0.14.2 → basic_memory-0.14.3}/src/basic_memory/cli/commands/import_chatgpt.py

@@ -7,7 +7,7 @@ from typing import Annotated
 
 import typer
 from basic_memory.cli.app import import_app
-from basic_memory.config import config
+from basic_memory.config import get_project_config
 from basic_memory.importers import ChatGPTImporter
 from basic_memory.markdown import EntityParser, MarkdownProcessor
 from loguru import logger
@@ -19,6 +19,7 @@ console = Console()
 
 async def get_markdown_processor() -> MarkdownProcessor:
     """Get MarkdownProcessor instance."""
+    config = get_project_config()
     entity_parser = EntityParser(config.home)
     return MarkdownProcessor(entity_parser)
 
@@ -49,7 +50,7 @@ def import_chatgpt(
 
         # Get markdown processor
         markdown_processor = asyncio.run(get_markdown_processor())
-
+        config = get_project_config()
         # Process the file
         base_path = config.home / folder
         console.print(f"\nImporting chats from {conversations_json}...writing to {base_path}")

{basic_memory-0.14.2 → basic_memory-0.14.3}/src/basic_memory/cli/commands/import_claude_conversations.py

@@ -7,7 +7,7 @@ from typing import Annotated
 
 import typer
 from basic_memory.cli.app import claude_app
-from basic_memory.config import config
+from basic_memory.config import get_project_config
 from basic_memory.importers.claude_conversations_importer import ClaudeConversationsImporter
 from basic_memory.markdown import EntityParser, MarkdownProcessor
 from loguru import logger
@@ -19,6 +19,7 @@ console = Console()
 
 async def get_markdown_processor() -> MarkdownProcessor:
     """Get MarkdownProcessor instance."""
+    config = get_project_config()
     entity_parser = EntityParser(config.home)
     return MarkdownProcessor(entity_parser)
 
@@ -42,6 +43,7 @@ def import_claude(
     After importing, run 'basic-memory sync' to index the new files.
     """
 
+    config = get_project_config()
     try:
         if not conversations_json.exists():
             typer.echo(f"Error: File not found: {conversations_json}", err=True)

{basic_memory-0.14.2 → basic_memory-0.14.3}/src/basic_memory/cli/commands/import_claude_projects.py

@@ -7,7 +7,7 @@ from typing import Annotated
 
 import typer
 from basic_memory.cli.app import claude_app
-from basic_memory.config import config
+from basic_memory.config import get_project_config
 from basic_memory.importers.claude_projects_importer import ClaudeProjectsImporter
 from basic_memory.markdown import EntityParser, MarkdownProcessor
 from loguru import logger
@@ -19,6 +19,7 @@ console = Console()
 
 async def get_markdown_processor() -> MarkdownProcessor:
     """Get MarkdownProcessor instance."""
+    config = get_project_config()
     entity_parser = EntityParser(config.home)
     return MarkdownProcessor(entity_parser)
 
@@ -41,6 +42,7 @@ def import_projects(
 
     After importing, run 'basic-memory sync' to index the new files.
     """
+    config = get_project_config()
     try:
         if not projects_json.exists():
             typer.echo(f"Error: File not found: {projects_json}", err=True)

{basic_memory-0.14.2 → basic_memory-0.14.3}/src/basic_memory/cli/commands/import_memory_json.py

@@ -7,7 +7,7 @@ from typing import Annotated
 
 import typer
 from basic_memory.cli.app import import_app
-from basic_memory.config import config
+from basic_memory.config import get_project_config
 from basic_memory.importers.memory_json_importer import MemoryJsonImporter
 from basic_memory.markdown import EntityParser, MarkdownProcessor
 from loguru import logger
@@ -19,6 +19,7 @@ console = Console()
 
 async def get_markdown_processor() -> MarkdownProcessor:
     """Get MarkdownProcessor instance."""
+    config = get_project_config()
     entity_parser = EntityParser(config.home)
     return MarkdownProcessor(entity_parser)
 
@@ -46,6 +47,7 @@ def memory_json(
         typer.echo(f"Error: File not found: {json_path}", err=True)
         raise typer.Exit(1)
 
+    config = get_project_config()
     try:
         # Get markdown processor
         markdown_processor = asyncio.run(get_markdown_processor())
@@ -74,7 +76,8 @@ def memory_json(
             Panel(
                 f"[green]Import complete![/green]\n\n"
                 f"Created {result.entities} entities\n"
-                f"Added {result.relations} relations",
+                f"Added {result.relations} relations\n"
+                f"Skipped {result.skipped_entities} entities\n",
                 expand=False,
             )
         )

{basic_memory-0.14.2 → basic_memory-0.14.3}/src/basic_memory/cli/commands/mcp.py

@@ -4,6 +4,7 @@ import asyncio
 import typer
 
 from basic_memory.cli.app import app
+from basic_memory.config import ConfigManager
 
 # Import mcp instance
 from basic_memory.mcp.server import mcp as mcp_server  # pragma: no cover
@@ -34,26 +35,13 @@ def mcp(
     - sse: Server-Sent Events (for compatibility with existing clients)
     """
 
-    # Check if OAuth is enabled
-    import os
-
-    auth_enabled = os.getenv("FASTMCP_AUTH_ENABLED", "false").lower() == "true"
-    if auth_enabled:
-        logger.info("OAuth authentication is ENABLED")
-        logger.info(f"Issuer URL: {os.getenv('FASTMCP_AUTH_ISSUER_URL', 'http://localhost:8000')}")
-        if os.getenv("FASTMCP_AUTH_REQUIRED_SCOPES"):
-            logger.info(f"Required scopes: {os.getenv('FASTMCP_AUTH_REQUIRED_SCOPES')}")
-    else:
-        logger.info("OAuth authentication is DISABLED")
-
-    from basic_memory.config import app_config
     from basic_memory.services.initialization import initialize_file_sync
 
-    # Start the MCP server with the specified transport
-
     # Use unified thread-based sync approach for both transports
     import threading
 
+    app_config = ConfigManager().config
+
     def run_file_sync():
         """Run file sync in a separate thread with its own event loop."""
         loop = asyncio.new_event_loop()