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

basic_memory/utils.py

@@ -5,11 +5,12 @@ import os
 import logging
 import re
 import sys
-import unicodedata
+from datetime import datetime
 from pathlib import Path
-from typing import Optional, Protocol, Union, runtime_checkable, List, Any
+from typing import Optional, Protocol, Union, runtime_checkable, List
 
 from loguru import logger
+from unidecode import unidecode
 
 
 @runtime_checkable
@@ -27,9 +28,11 @@ FilePath = Union[Path, str]
 logging.getLogger("opentelemetry.sdk.metrics._internal.instrument").setLevel(logging.ERROR)
 
 
-def generate_permalink(file_path: Union[Path, str, Any]) -> str:
-    """
-    Generate a permalink from a file path.
+def generate_permalink(file_path: Union[Path, str, PathLike], split_extension: bool = True) -> str:
+    """Generate a stable permalink from a file path.
+
+    Args:
+        file_path: Original file path (str, Path, or PathLike)
 
     Returns:
         Normalized permalink that matches validation rules. Converts spaces and underscores
@@ -38,7 +41,7 @@ def generate_permalink(file_path: Union[Path, str, Any]) -> str:
     Examples:
         >>> generate_permalink("docs/My Feature.md")
         'docs/my-feature'
-        >>> generate_permalink("specs/API_v2.md")
+        >>> generate_permalink("specs/API (v2).md")
         'specs/api-v2'
         >>> generate_permalink("design/unified_model_refactor.md")
         'design/unified-model-refactor'
@@ -46,84 +49,99 @@ def generate_permalink(file_path: Union[Path, str, Any]) -> str:
         '中文/测试文档'
     """
     # Convert Path to string if needed
-    path_str = str(file_path)
-
-    # Remove extension
-    base = os.path.splitext(path_str)[0]
-
-    # Create a transliteration mapping for specific characters
-    transliteration_map = {
-        "ø": "o",  # Handle Søren -> soren
-        "å": "a",  # Handle Kierkegård -> kierkegard
-        "ü": "u",  # Handle Müller -> muller
-        "é": "e",  # Handle Café -> cafe
-        "è": "e",  # Handle Mère -> mere
-        "ê": "e",  # Handle Fête -> fete
-        "à": "a",  # Handle À la mode -> a la mode
-        "ç": "c",  # Handle Façade -> facade
-        "ñ": "n",  # Handle Niño -> nino
-        "ö": "o",  # Handle Björk -> bjork
-        "ä": "a",  # Handle Häagen -> haagen
-        # Add more mappings as needed
-    }
+    path_str = Path(str(file_path)).as_posix()
+
+    # Remove extension (for now, possibly)
+    (base, extension) = os.path.splitext(path_str)
+
+    # Check if we have CJK characters that should be preserved
+    # CJK ranges: \u4e00-\u9fff (CJK Unified Ideographs), \u3000-\u303f (CJK symbols),
+    # \u3400-\u4dbf (CJK Extension A), \uff00-\uffef (Fullwidth forms)
+    has_cjk_chars = any(
+        "\u4e00" <= char <= "\u9fff"
+        or "\u3000" <= char <= "\u303f"
+        or "\u3400" <= char <= "\u4dbf"
+        or "\uff00" <= char <= "\uffef"
+        for char in base
+    )
 
-    # Process character by character, transliterating Latin characters with diacritics
-    result = ""
-    for char in base:
-        # Direct mapping for known characters
-        if char.lower() in transliteration_map:
-            result += transliteration_map[char.lower()]
-        # General case using Unicode normalization
-        elif unicodedata.category(char).startswith("L") and ord(char) > 127:
-            # Decompose the character (e.g., ü -> u + combining diaeresis)
-            decomposed = unicodedata.normalize("NFD", char)
-            # If decomposition produced multiple characters and first one is ASCII
-            if len(decomposed) > 1 and ord(decomposed[0]) < 128:
-                # Keep only the base character
-                result += decomposed[0].lower()
-            else:
-                # For non-Latin scripts like Chinese, preserve the character
+    if has_cjk_chars:
+        # For text with CJK characters, selectively transliterate only Latin accented chars
+        result = ""
+        for char in base:
+            if (
+                "\u4e00" <= char <= "\u9fff"
+                or "\u3000" <= char <= "\u303f"
+                or "\u3400" <= char <= "\u4dbf"
+            ):
+                # Preserve CJK ideographs and symbols
                 result += char
-        else:
-            # Add the character as is
-            result += char
+            elif "\uff00" <= char <= "\uffef":
+                # Remove Chinese fullwidth punctuation entirely (like ，！？)
+                continue
+            else:
+                # Transliterate Latin accented characters to ASCII
+                result += unidecode(char)
 
-    # Handle special punctuation cases for apostrophes
-    result = result.replace("'", "")
+        # Insert hyphens between CJK and Latin character transitions
+        # Match: CJK followed by Latin letter/digit, or Latin letter/digit followed by CJK
+        result = re.sub(
+            r"([\u4e00-\u9fff\u3000-\u303f\u3400-\u4dbf])([a-zA-Z0-9])", r"\1-\2", result
+        )
+        result = re.sub(
+            r"([a-zA-Z0-9])([\u4e00-\u9fff\u3000-\u303f\u3400-\u4dbf])", r"\1-\2", result
+        )
 
-    # Insert dash between camelCase
-    # This regex finds boundaries between lowercase and uppercase letters
-    result = re.sub(r"([a-z0-9])([A-Z])", r"\1-\2", result)
+        # Insert dash between camelCase
+        result = re.sub(r"([a-z0-9])([A-Z])", r"\1-\2", result)
 
-    # Insert dash between Chinese and Latin character boundaries
-    # This is needed for cases like "中文English" -> "中文-english"
-    result = re.sub(r"([\u4e00-\u9fff])([a-zA-Z])", r"\1-\2", result)
-    result = re.sub(r"([a-zA-Z])([\u4e00-\u9fff])", r"\1-\2", result)
+        # Convert ASCII letters to lowercase, preserve CJK
+        lower_text = "".join(c.lower() if c.isascii() and c.isalpha() else c for c in result)
 
-    # Convert ASCII letters to lowercase, preserve non-ASCII characters
-    lower_text = "".join(c.lower() if c.isascii() and c.isalpha() else c for c in result)
+        # Replace underscores with hyphens
+        text_with_hyphens = lower_text.replace("_", "-")
 
-    # Replace underscores with hyphens
-    text_with_hyphens = lower_text.replace("_", "-")
+        # Remove apostrophes entirely (don't replace with hyphens)
+        text_no_apostrophes = text_with_hyphens.replace("'", "")
 
-    # Replace spaces and unsafe ASCII characters with hyphens, but preserve non-ASCII characters
-    # Include common Chinese character ranges and other non-ASCII characters
-    clean_text = re.sub(
-        r"[^a-z0-9\u4e00-\u9fff\u3000-\u303f\u3400-\u4dbf/\-]", "-", text_with_hyphens
-    )
+        # Replace unsafe chars with hyphens, but preserve CJK characters
+        clean_text = re.sub(
+            r"[^a-z0-9\u4e00-\u9fff\u3000-\u303f\u3400-\u4dbf/\-]", "-", text_no_apostrophes
+        )
+    else:
+        # Original ASCII-only processing for backward compatibility
+        # Transliterate unicode to ascii
+        ascii_text = unidecode(base)
+
+        # Insert dash between camelCase
+        ascii_text = re.sub(r"([a-z0-9])([A-Z])", r"\1-\2", ascii_text)
+
+        # Convert to lowercase
+        lower_text = ascii_text.lower()
+
+        # replace underscores with hyphens
+        text_with_hyphens = lower_text.replace("_", "-")
+
+        # Remove apostrophes entirely (don't replace with hyphens)
+        text_no_apostrophes = text_with_hyphens.replace("'", "")
+
+        # Replace remaining invalid chars with hyphens
+        clean_text = re.sub(r"[^a-z0-9/\-]", "-", text_no_apostrophes)
 
     # Collapse multiple hyphens
     clean_text = re.sub(r"-+", "-", clean_text)
 
-    # Remove hyphens between adjacent Chinese characters only
-    # This handles cases like "你好-世界" -> "你好世界"
-    clean_text = re.sub(r"([\u4e00-\u9fff])-([\u4e00-\u9fff])", r"\1\2", clean_text)
-
     # Clean each path segment
     segments = clean_text.split("/")
     clean_segments = [s.strip("-") for s in segments]
 
-    return "/".join(clean_segments)
+    return_val = "/".join(clean_segments)
+
+    # Append file extension back, if necessary
+    if not split_extension and extension:
+        return_val += extension
+
+    return return_val
 
 
 def setup_logging(
@@ -173,8 +191,6 @@ def setup_logging(
         "httpx": logging.WARNING,
         # File watching logs
         "watchfiles.main": logging.WARNING,
-        # SQLAlchemy deprecation warnings
-        "sqlalchemy": logging.WARNING,
     }
 
     # Set log levels for noisy loggers
@@ -203,8 +219,21 @@ def parse_tags(tags: Union[List[str], str, None]) -> List[str]:
         # First strip whitespace, then strip leading '#' characters to prevent accumulation
         return [tag.strip().lstrip("#") for tag in tags if tag and tag.strip()]
 
-    # Process comma-separated string of tags
+    # Process string input
     if isinstance(tags, str):
+        # Check if it's a JSON array string (common issue from AI assistants)
+        import json
+        if tags.strip().startswith('[') and tags.strip().endswith(']'):
+            try:
+                # Try to parse as JSON array
+                parsed_json = json.loads(tags)
+                if isinstance(parsed_json, list):
+                    # Recursively parse the JSON array as a list
+                    return parse_tags(parsed_json)
+            except json.JSONDecodeError:
+                # Not valid JSON, fall through to comma-separated parsing
+                pass
+        
         # Split by comma, strip whitespace, then strip leading '#' characters
         return [tag.strip().lstrip("#") for tag in tags.split(",") if tag and tag.strip()]
 
@@ -214,3 +243,137 @@ def parse_tags(tags: Union[List[str], str, None]) -> List[str]:
     except (ValueError, TypeError):  # pragma: no cover
         logger.warning(f"Couldn't parse tags from input of type {type(tags)}: {tags}")
         return []
+
+
+def normalize_newlines(multiline: str) -> str:
+    """Replace any \r\n, \r, or \n with the native newline.
+
+    Args:
+        multiline: String containing any mixture of newlines.
+
+    Returns:
+        A string with normalized newlines native to the platform.
+    """
+    return re.sub(r"\r\n?|\n", os.linesep, multiline)
+
+
+def normalize_file_path_for_comparison(file_path: str) -> str:
+    """Normalize a file path for conflict detection.
+
+    This function normalizes file paths to help detect potential conflicts:
+    - Converts to lowercase for case-insensitive comparison
+    - Normalizes Unicode characters
+    - Handles path separators consistently
+
+    Args:
+        file_path: The file path to normalize
+
+    Returns:
+        Normalized file path for comparison purposes
+    """
+    import unicodedata
+
+    # Convert to lowercase for case-insensitive comparison
+    normalized = file_path.lower()
+
+    # Normalize Unicode characters (NFD normalization)
+    normalized = unicodedata.normalize("NFD", normalized)
+
+    # Replace path separators with forward slashes
+    normalized = normalized.replace("\\", "/")
+
+    # Remove multiple slashes
+    normalized = re.sub(r"/+", "/", normalized)
+
+    return normalized
+
+
+def detect_potential_file_conflicts(file_path: str, existing_paths: List[str]) -> List[str]:
+    """Detect potential conflicts between a file path and existing paths.
+
+    This function checks for various types of conflicts:
+    - Case sensitivity differences
+    - Unicode normalization differences
+    - Path separator differences
+    - Permalink generation conflicts
+
+    Args:
+        file_path: The file path to check
+        existing_paths: List of existing file paths to check against
+
+    Returns:
+        List of existing paths that might conflict with the given file path
+    """
+    conflicts = []
+
+    # Normalize the input file path
+    normalized_input = normalize_file_path_for_comparison(file_path)
+    input_permalink = generate_permalink(file_path)
+
+    for existing_path in existing_paths:
+        # Skip identical paths
+        if existing_path == file_path:
+            continue
+
+        # Check for case-insensitive path conflicts
+        normalized_existing = normalize_file_path_for_comparison(existing_path)
+        if normalized_input == normalized_existing:
+            conflicts.append(existing_path)
+            continue
+
+        # Check for permalink conflicts
+        existing_permalink = generate_permalink(existing_path)
+        if input_permalink == existing_permalink:
+            conflicts.append(existing_path)
+            continue
+
+    return conflicts
+
+
+def validate_project_path(path: str, project_path: Path) -> bool:
+    """Ensure path stays within project boundaries."""
+    # Allow empty strings as they resolve to the project root
+    if not path:
+        return True
+
+    # Check for obvious path traversal patterns first
+    if ".." in path or "~" in path:
+        return False
+
+    # Check for Windows-style path traversal (even on Unix systems)
+    if "\\.." in path or path.startswith("\\"):
+        return False
+
+    # Block absolute paths (Unix-style starting with / or Windows-style with drive letters)
+    if path.startswith("/") or (len(path) >= 2 and path[1] == ":"):
+        return False
+
+    # Block paths with control characters (but allow whitespace that will be stripped)
+    if path.strip() and any(ord(c) < 32 and c not in [" ", "\t"] for c in path):
+        return False
+
+    try:
+        resolved = (project_path / path).resolve()
+        return resolved.is_relative_to(project_path.resolve())
+    except (ValueError, OSError):
+        return False
+
+
+def ensure_timezone_aware(dt: datetime) -> datetime:
+    """Ensure a datetime is timezone-aware using system timezone.
+
+    If the datetime is naive, convert it to timezone-aware using the system's local timezone.
+    If it's already timezone-aware, return it unchanged.
+
+    Args:
+        dt: The datetime to ensure is timezone-aware
+
+    Returns:
+        A timezone-aware datetime
+    """
+    if dt.tzinfo is None:
+        # Naive datetime - assume it's in local time and add timezone
+        return dt.astimezone()
+    else:
+        # Already timezone-aware
+        return dt

{basic_memory-0.14.2.dist-info → basic_memory-0.14.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: basic-memory
-Version: 0.14.2
+Version: 0.14.4
 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
@@ -51,11 +51,8 @@ Basic Memory lets you build persistent knowledge through natural conversations w
 Claude, while keeping everything in simple Markdown files on your computer. It uses the Model Context Protocol (MCP) to
 enable any compatible LLM to read and write to your local knowledge base.
 
-- Website: https://basicmemory.com
-- Company: https://basicmachines.co
+- Website: https://basicmachines.co
 - Documentation: https://memory.basicmachines.co
-- Discord: https://discord.gg/tyvKNccgqN
-- YouTube: https://www.youtube.com/@basicmachines-co
 
 ## Pick up your conversation right where you left off
 
@@ -71,10 +68,6 @@ 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:
 {
@@ -106,14 +99,8 @@ Memory for Claude Desktop:
 npx -y @smithery/cli install @basicmachines-co/basic-memory --client claude
 ```
 
-This installs and configures Basic Memory without requiring manual edits to the Claude Desktop configuration file. Note: The Smithery installation uses their hosted MCP server, while your data remains stored locally as Markdown files.
-
-### Add to Cursor
-
-Once you have installed Basic Memory revisit this page for the 1-click installer for Cursor:
-
-[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=basic-memory&config=eyJjb21tYW5kIjoiL1VzZXJzL2RyZXcvLmxvY2FsL2Jpbi91dnggYmFzaWMtbWVtb3J5IG1jcCJ9)
-
+This installs and configures Basic Memory without requiring manual edits to the Claude Desktop configuration file. The
+Smithery server hosts the MCP server component, while your data remains stored locally as Markdown files.
 
 ### Glama.ai
 
@@ -204,8 +191,7 @@ The note embeds semantic content and links to other topics via simple Markdown f
 
 3. You see this file on your computer in real time in the current project directory (default `~/$HOME/basic-memory`).
 
-- Realtime sync is enabled by default starting with v0.12.0
-- Project switching during conversations is supported starting with v0.13.0
+- Realtime sync can be enabled via running `basic-memory sync --watch`
 
 4. In a chat with the LLM, you can reference a topic:
 
@@ -263,7 +249,7 @@ title: <Entity title>
 type: <The type of Entity> (e.g. note)
 permalink: <a uri slug>
 
-- <optional metadata> (such as tags)
+- <optional metadata> (such as tags) 
 ```
 
 ### Observations
@@ -315,13 +301,6 @@ Examples of relations:
 ```
 
 ## Using with VS Code
-For one-click installation, click one of the install buttons below...
-
-[![Install with UV in VS Code](https://img.shields.io/badge/VS_Code-UV-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=basic-memory&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22basic-memory%22%2C%22mcp%22%5D%7D) [![Install with UV in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-UV-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=basic-memory&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22basic-memory%22%2C%22mcp%22%5D%7D&quality=insiders)
-
-You can use Basic Memory with VS Code to easily retrieve and store information while coding. Click the installation buttons above for one-click setup, or follow the manual installation instructions below.
-
-### Manual Installation
 
 Add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.
 
@@ -351,6 +330,8 @@ Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace
 }
 ```
 
+You can use Basic Memory with VS Code to easily retrieve and store information while coding.
+
 ## Using with Claude Desktop
 
 Basic Memory is built using the MCP (Model Context Protocol) and works with the Claude desktop app (https://claude.ai/):
@@ -374,8 +355,7 @@ for OS X):
 }
 ```
 
-If you want to use a specific project (see [Multiple Projects](docs/User%20Guide.md#multiple-projects)), update your
-Claude Desktop
+If you want to use a specific project (see [Multiple Projects](#multiple-projects) below), update your Claude Desktop
 config:
 
 ```json
@@ -385,9 +365,9 @@ config:
       "command": "uvx",
       "args": [
         "basic-memory",
+        "mcp",
         "--project",
-        "your-project-name",
-        "mcp"
+        "your-project-name"
       ]
     }
   }
@@ -396,27 +376,23 @@ config:
 
 2. Sync your knowledge:
 
-Basic Memory will sync the files in your project in real time if you make manual edits.
+```bash
+# One-time sync of local knowledge updates
+basic-memory sync
+
+# Run realtime sync process (recommended)
+basic-memory sync --watch
+```
 
 3. In Claude Desktop, the LLM can now use these tools:
 
 ```
 write_note(title, content, folder, tags) - Create or update notes
 read_note(identifier, page, page_size) - Read notes by title or permalink
-edit_note(identifier, operation, content) - Edit notes incrementally (append, prepend, find/replace)
-move_note(identifier, destination_path) - Move notes with database consistency
-view_note(identifier) - Display notes as formatted artifacts for better readability
 build_context(url, depth, timeframe) - Navigate knowledge graph via memory:// URLs
-search_notes(query, page, page_size) - Search across your knowledge base
+search(query, page, page_size) - Search across your knowledge base
 recent_activity(type, depth, timeframe) - Find recently updated information
 canvas(nodes, edges, title, folder) - Generate knowledge visualizations
-list_memory_projects() - List all available projects with status
-switch_project(project_name) - Switch to different project context
-get_current_project() - Show current project and statistics
-create_memory_project(name, path, set_default) - Create new projects
-delete_project(name) - Delete projects from configuration
-set_default_project(name) - Set default project
-sync_status() - Check file synchronization status
 ```
 
 5. Example prompts to try:
@@ -427,10 +403,6 @@ sync_status() - Check file synchronization status
 "Create a canvas visualization of my project components"
 "Read my notes on the authentication system"
 "What have I been working on in the past week?"
-"Switch to my work-notes project"
-"List all my available projects"
-"Edit my coffee brewing note to add a new technique"
-"Move my old meeting notes to the archive folder"
 ```
 
 ## Futher info
@@ -442,49 +414,6 @@ See the [Documentation](https://memory.basicmachines.co/) for more info, includi
 - [Managing multiple Projects](https://memory.basicmachines.co/docs/cli-reference#project)
 - [Importing data from OpenAI/Claude Projects](https://memory.basicmachines.co/docs/cli-reference#import)
 
-## Installation Options
-
-### Stable Release
-```bash
-pip install basic-memory
-```
-
-### Beta/Pre-releases
-```bash
-pip install basic-memory --pre
-```
-
-### Development Builds
-Development versions are automatically published on every commit to main with versions like `0.12.4.dev26+468a22f`:
-```bash
-pip install basic-memory --pre --force-reinstall
-```
-
-### Docker
-
-Run Basic Memory in a container with volume mounting for your Obsidian vault:
-
-```bash
-# Clone and start with Docker Compose
-git clone https://github.com/basicmachines-co/basic-memory.git
-cd basic-memory
-
-# Edit docker-compose.yml to point to your Obsidian vault
-# Then start the container
-docker-compose up -d
-```
-
-Or use Docker directly:
-```bash
-docker run -d \
-  --name basic-memory-server \
-  -v /path/to/your/obsidian-vault:/data/knowledge:rw \
-  -v basic-memory-config:/root/.basic-memory:rw \
-  ghcr.io/basicmachines-co/basic-memory:latest
-```
-
-See [Docker Setup Guide](docs/Docker.md) for detailed configuration options, multiple project setup, and integration examples.
-
 ## License
 
 AGPL-3.0
@@ -502,4 +431,4 @@ and submitting PRs.
  </picture>
 </a>
 
-Built with ♥️ by Basic Machines
+Built with ♥️ by Basic Machines