basic-memory 0.13.5__tar.gz → 0.13.6__tar.gz

{basic_memory-0.13.5 → basic_memory-0.13.6}/CHANGELOG.md

@@ -1,5 +1,79 @@
 # CHANGELOG
 
+## v0.13.6 (2025-06-18)
+
+### Bug Fixes
+
+- **Custom Entity Types** - Support for custom entity types in write_note
+  ([`7789864`](https://github.com/basicmachines-co/basic-memory/commit/77898644933589c2da9bdd60571d54137a5309ed))
+  - Fixed `entity_type` parameter for `write_note` MCP tool to respect value passed in
+  - Frontmatter `type` field automatically respected when no explicit parameter provided
+  - Maintains backward compatibility with default "note" type
+
+- **#139**: Fix "UNIQUE constraint failed: entity.permalink" database error
+  ([`c6215fd`](https://github.com/basicmachines-co/basic-memory/commit/c6215fd819f9564ead91cf3a950f855241446096))
+  - Implement SQLAlchemy UPSERT strategy to handle permalink conflicts gracefully
+  - Eliminates crashes when creating notes with existing titles in same folders
+  - Seamlessly updates existing entities instead of failing with constraint errors
+
+- **Database Migration Performance** - Eliminate redundant migration initialization
+  ([`84d2aaf`](https://github.com/basicmachines-co/basic-memory/commit/84d2aaf6414dd083af4b0df73f6c8139b63468f6))
+  - Fix duplicate migration calls that slowed system startup
+  - Improve performance with multiple projects (tested with 28+ projects)
+  - Add migration deduplication safeguards with comprehensive test coverage
+
+- **User Experience** - Correct spelling error in continue_conversation prompt
+  ([`b4c26a6`](https://github.com/basicmachines-co/basic-memory/commit/b4c26a613379e6f2ba655efe3d7d8d40c27999e5))
+  - Fix "Chose a folder" → "Choose a folder" in MCP prompt instructions
+  - Improve grammar and clarity in user-facing prompt text
+
+### Documentation
+
+- **Website Updates** - Add new website and community links to README
+  ([`3fdce68`](https://github.com/basicmachines-co/basic-memory/commit/3fdce683d7ad8b6f4855d7138d5ff2136d4c07bc))
+
+- **Project Documentation** - Update README.md and CLAUDE.md with latest project information
+  ([`782cb2d`](https://github.com/basicmachines-co/basic-memory/commit/782cb2df28803482d209135a054e67cc32d7363e))
+
+### Technical Improvements
+
+- **Comprehensive Test Coverage** - Add extensive test suites for new features
+  - Custom entity type validation with 8 new test scenarios
+  - UPSERT behavior testing with edge case coverage
+  - Migration deduplication testing with 6 test scenarios
+  - Database constraint handling validation
+
+- **Code Quality** - Enhanced error handling and validation
+  - Improved SQLAlchemy patterns with modern UPSERT operations
+  - Better conflict resolution strategies for entity management
+  - Strengthened database consistency guarantees
+
+### Performance
+
+- **Database Operations** - Faster startup and improved scalability
+  - Reduced migration overhead for multi-project setups
+  - Optimized conflict resolution for entity creation
+  - Enhanced performance with growing knowledge bases
+
+### Migration Guide
+
+This release includes automatic database improvements. No manual migration required:
+
+- Existing notes and entity types continue working unchanged
+- New `entity_type` parameter is optional and backward compatible
+- Database performance improvements apply automatically
+- All existing MCP tool behavior preserved
+
+### Installation
+
+```bash
+# Latest stable release
+uv tool install basic-memory
+
+# Update existing installation
+uv tool upgrade basic-memory
+```
+
 ## v0.13.5 (2025-06-11)
 
 ### Bug Fixes

{basic_memory-0.13.5 → basic_memory-0.13.6}/CLAUDE.md

@@ -97,15 +97,26 @@ See the [README.md](README.md) file for a project overview.
 
   **Content Management:**
     - `write_note(title, content, folder, tags)` - Create/update markdown notes with semantic observations and relations
-    - `read_note(identifier, page, page_size)` - Read notes by title, permalink, or memory:// URL with knowledge graph
-      awareness
-    - `read_file(path)` - Read raw file content (text, images, binaries) without knowledge graph processing
+    - `read_note(identifier, page, page_size)` - Read notes by title, permalink, or memory:// URL with knowledge graph awareness
+    - `edit_note(identifier, operation, content)` - Edit notes incrementally (append, prepend, find/replace, section replace)
+    - `move_note(identifier, destination_path)` - Move notes with database consistency and search reindexing
+    - `view_note(identifier)` - Display notes as formatted artifacts for better readability in Claude Desktop
+    - `read_content(path)` - Read raw file content (text, images, binaries) without knowledge graph processing
+    - `delete_note(identifier)` - Delete notes from knowledge base
+
+  **Project Management:**
+    - `list_memory_projects()` - List all available projects with status indicators
+    - `switch_project(project_name)` - Switch to different project context during conversations
+    - `get_current_project()` - Show currently active project with statistics
+    - `create_memory_project(name, path, set_default)` - Create new Basic Memory projects
+    - `delete_project(name)` - Delete projects from configuration and database
+    - `set_default_project(name)` - Set default project in config
+    - `sync_status()` - Check file synchronization status and background operations
 
   **Knowledge Graph Navigation:**
-    - `build_context(url, depth, timeframe)` - Navigate the knowledge graph via memory:// URLs for conversation
-      continuity
-    - `recent_activity(type, depth, timeframe)` - Get recently updated information with specified timeframe (e.g., "
-      1d", "1 week")
+    - `build_context(url, depth, timeframe)` - Navigate the knowledge graph via memory:// URLs for conversation continuity
+    - `recent_activity(type, depth, timeframe)` - Get recently updated information with specified timeframe (e.g., "1d", "1 week")
+    - `list_directory(dir_name, depth, file_name_glob)` - List directory contents with filtering and depth control
 
   **Search & Discovery:**
     - `search_notes(query, page, page_size)` - Full-text search across all content with filtering options
@@ -212,13 +223,24 @@ Basic Memory uses `uv-dynamic-versioning` for automatic version management based
 - Users install with: `pip install basic-memory --pre`
 - Use for milestone testing before stable release
 
-#### Stable Releases (Manual)
-- Create version tag: `git tag v0.13.0 && git push origin v0.13.0`
-- Automatically builds, creates GitHub release, and publishes to PyPI
+#### Stable Releases (Automated)
+- Use the automated release system: `just release v0.13.0`
+- Includes comprehensive quality checks (lint, format, type-check, tests)
+- Automatically updates version in `__init__.py`
+- Creates git tag and pushes to GitHub
+- Triggers GitHub Actions workflow for PyPI publication
 - Users install with: `pip install basic-memory`
 
+**Manual method (legacy):**
+- Create version tag: `git tag v0.13.0 && git push origin v0.13.0`
+
 ### For Development
-- No manual version bumping required
-- Versions automatically derived from git tags
-- `pyproject.toml` uses `dynamic = ["version"]`
-- `__init__.py` dynamically reads version from package metadata
+- **Automated releases**: Use `just release v0.13.x` for stable releases and `just beta v0.13.0b1` for beta releases
+- **Quality gates**: All releases require passing lint, format, type-check, and test suites
+- **Version management**: Versions automatically derived from git tags via `uv-dynamic-versioning`
+- **Configuration**: `pyproject.toml` uses `dynamic = ["version"]`
+- **Release automation**: `__init__.py` updated automatically during release process
+- **CI/CD**: GitHub Actions handles building and PyPI publication
+
+## Development Notes
+- make sure you sign off on commits

{basic_memory-0.13.5 → basic_memory-0.13.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: basic-memory
-Version: 0.13.5
+Version: 0.13.6
 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
@@ -51,8 +51,11 @@ 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://basicmachines.co
+- Website: https://basicmemory.com
+- Company: 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
 
@@ -99,8 +102,7 @@ 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. The
-Smithery server hosts the MCP server component, while your data remains stored locally as Markdown files.
+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.
 
 ### Glama.ai
 
@@ -191,7 +193,8 @@ 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 with the v0.12.0 version
+- Realtime sync is enabled by default starting with v0.12.0
+- Project switching during conversations is supported starting with v0.13.0
 
 4. In a chat with the LLM, you can reference a topic:
 
@@ -389,10 +392,20 @@ Basic Memory will sync the files in your project in real time if you make manual
 ```
 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
 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:
@@ -403,6 +416,10 @@ canvas(nodes, edges, title, folder) - Generate knowledge visualizations
 "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

{basic_memory-0.13.5 → basic_memory-0.13.6}/README.md

@@ -13,8 +13,11 @@ 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://basicmachines.co
+- Website: https://basicmemory.com
+- Company: 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
 
@@ -61,8 +64,7 @@ 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. The
-Smithery server hosts the MCP server component, while your data remains stored locally as Markdown files.
+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.
 
 ### Glama.ai
 
@@ -153,7 +155,8 @@ 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 with the v0.12.0 version
+- Realtime sync is enabled by default starting with v0.12.0
+- Project switching during conversations is supported starting with v0.13.0
 
 4. In a chat with the LLM, you can reference a topic:
 
@@ -351,10 +354,20 @@ Basic Memory will sync the files in your project in real time if you make manual
 ```
 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
 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:
@@ -365,6 +378,10 @@ canvas(nodes, edges, title, folder) - Generate knowledge visualizations
 "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

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

{basic_memory-0.13.5 → basic_memory-0.13.6}/src/basic_memory/alembic/env.py

@@ -8,12 +8,12 @@ from sqlalchemy import pool
 
 from alembic import context
 
-from basic_memory.models import Base
-
 # set config.env to "test" for pytest to prevent logging to file in utils.setup_logging()
 os.environ["BASIC_MEMORY_ENV"] = "test"
 
-from basic_memory.config import app_config
+# 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.

{basic_memory-0.13.5 → basic_memory-0.13.6}/src/basic_memory/db.py

@@ -23,6 +23,7 @@ from basic_memory.repository.search_repository import SearchRepository
 # Module level state
 _engine: Optional[AsyncEngine] = None
 _session_maker: Optional[async_sessionmaker[AsyncSession]] = None
+_migrations_completed: bool = False
 
 
 class DatabaseType(Enum):
@@ -72,18 +73,35 @@ async def scoped_session(
         await factory.remove()
 
 
+def _create_engine_and_session(
+    db_path: Path, db_type: DatabaseType = DatabaseType.FILESYSTEM
+) -> tuple[AsyncEngine, async_sessionmaker[AsyncSession]]:
+    """Internal helper to create engine and session maker."""
+    db_url = DatabaseType.get_db_url(db_path, db_type)
+    logger.debug(f"Creating engine for db_url: {db_url}")
+    engine = create_async_engine(db_url, connect_args={"check_same_thread": False})
+    session_maker = async_sessionmaker(engine, expire_on_commit=False)
+    return engine, session_maker
+
+
 async def get_or_create_db(
     db_path: Path,
     db_type: DatabaseType = DatabaseType.FILESYSTEM,
+    ensure_migrations: bool = True,
+    app_config: Optional["BasicMemoryConfig"] = None,
 ) -> tuple[AsyncEngine, async_sessionmaker[AsyncSession]]:  # pragma: no cover
     """Get or create database engine and session maker."""
     global _engine, _session_maker
 
     if _engine is None:
-        db_url = DatabaseType.get_db_url(db_path, db_type)
-        logger.debug(f"Creating engine for db_url: {db_url}")
-        _engine = create_async_engine(db_url, connect_args={"check_same_thread": False})
-        _session_maker = async_sessionmaker(_engine, expire_on_commit=False)
+        _engine, _session_maker = _create_engine_and_session(db_path, db_type)
+        
+        # Run migrations automatically unless explicitly disabled
+        if ensure_migrations:
+            if app_config is None:
+                from basic_memory.config import app_config as global_app_config
+                app_config = global_app_config
+            await run_migrations(app_config, db_type)
 
     # These checks should never fail since we just created the engine and session maker
     # if they were None, but we'll check anyway for the type checker
@@ -100,12 +118,13 @@ async def get_or_create_db(
 
 async def shutdown_db() -> None:  # pragma: no cover
     """Clean up database connections."""
-    global _engine, _session_maker
+    global _engine, _session_maker, _migrations_completed
 
     if _engine:
         await _engine.dispose()
         _engine = None
         _session_maker = None
+        _migrations_completed = False
 
 
 @asynccontextmanager
@@ -119,7 +138,7 @@ async def engine_session_factory(
     for each test. For production use, use get_or_create_db() instead.
     """
 
-    global _engine, _session_maker
+    global _engine, _session_maker, _migrations_completed
 
     db_url = DatabaseType.get_db_url(db_path, db_type)
     logger.debug(f"Creating engine for db_url: {db_url}")
@@ -143,12 +162,20 @@ async def engine_session_factory(
             await _engine.dispose()
             _engine = None
             _session_maker = None
+            _migrations_completed = False
 
 
 async def run_migrations(
-    app_config: BasicMemoryConfig, database_type=DatabaseType.FILESYSTEM
+    app_config: BasicMemoryConfig, database_type=DatabaseType.FILESYSTEM, force: bool = False
 ):  # pragma: no cover
     """Run any pending alembic migrations."""
+    global _migrations_completed
+    
+    # Skip if migrations already completed unless forced
+    if _migrations_completed and not force:
+        logger.debug("Migrations already completed in this session, skipping")
+        return
+        
     logger.info("Running database migrations...")
     try:
         # Get the absolute path to the alembic directory relative to this file
@@ -170,11 +197,18 @@ async def run_migrations(
         command.upgrade(config, "head")
         logger.info("Migrations completed successfully")
 
-        _, session_maker = await get_or_create_db(app_config.database_path, database_type)
+        # Get session maker - ensure we don't trigger recursive migration calls
+        if _session_maker is None:
+            _, session_maker = _create_engine_and_session(app_config.database_path, database_type)
+        else:
+            session_maker = _session_maker
 
         # initialize the search Index schema
         # the project_id is not used for init_search_index, so we pass a dummy value
         await SearchRepository(session_maker, 1).init_search_index()
+        
+        # Mark migrations as completed
+        _migrations_completed = True
     except Exception as e:  # pragma: no cover
         logger.error(f"Error running migrations: {e}")
         raise

{basic_memory-0.13.5 → basic_memory-0.13.6}/src/basic_memory/mcp/tools/write_note.py

@@ -27,6 +27,7 @@ async def write_note(
     content: str,
     folder: str,
     tags=None,  # Remove type hint completely to avoid schema issues
+    entity_type: str = "note",
     project: Optional[str] = None,
 ) -> str:
     """Write a markdown note to the knowledge base.
@@ -58,6 +59,7 @@ async def write_note(
                 Use forward slashes (/) as separators. Examples: "notes", "projects/2025", "research/ml"
         tags: Tags to categorize the note. Can be a list of strings, a comma-separated string, or None.
               Note: If passing from external MCP clients, use a string format (e.g. "tag1,tag2,tag3")
+        entity_type: Type of entity to create. Defaults to "note". Can be "guide", "report", "config", etc.
         project: Optional project name to write to. If not provided, uses current active project.
 
     Returns:
@@ -84,7 +86,7 @@ async def write_note(
     entity = Entity(
         title=title,
         folder=folder,
-        entity_type="note",
+        entity_type=entity_type,
         content_type="text/markdown",
         content=content,
         entity_metadata=metadata,