Basic Memory

Latest Releases

Basic Memory is updated frequently, below are notable recent changes.

View the latest changes to Basic Memory on GitHub

v0.15.2 — 2025-10-14

Cloud Features

  • WebDAV upload command for cloud projects (#356)
    • New basic-memory cloud upload command for uploading files to cloud projects via WebDAV
    • Supports uploading individual files or entire directories
    • Automatic project syncing after upload completes
    • Simplifies workflow for adding local files to cloud projects

Full Changelog: https://github.com/basicmachines-co/basic-memory/compare/v0.15.1…v0.15.2

v0.15.1 — 2025-10-13

Focus: Cloud mode stability, performance optimizations, and bug fixes

Highlights:

  • 10-100x performance improvement for directory operations
  • 43% faster sync and indexing operations
  • Enhanced cloud mode security with path validation
  • Critical bug fixes for project deletion and Claude Desktop compatibility

Performance Improvements

  • Optimize directory operations for 10-100x performance improvement (#350)

    • Dramatically faster directory listing and traversal operations
    • Improved responsiveness for large knowledge bases
    • Optimized file system operations

  • Optimize sync/indexing for 43% faster performance (#352)

    • Significantly faster file synchronization
    • Reduced indexing time for large projects
    • Enhanced overall system responsiveness

Cloud Mode Enhancements

  • Cloud mode path validation and sanitization (#332)

    • Enhanced security with strict path validation in cloud mode
    • Prevents path traversal attacks and unauthorized file access
    • Improved data isolation for multi-tenant environments

  • BASIC_MEMORY_PROJECT_ROOT for path constraints (#334)

    • New environment variable for defining project root boundaries
    • Additional security layer for cloud deployments
    • Prevents access to files outside designated project directories

  • Normalize paths to lowercase in cloud mode (#336)

    • Prevents case-sensitivity collisions in cloud storage
    • Ensures consistent file handling across platforms
    • Improves cross-platform compatibility

  • Configuration persistence via Tigris (SPEC-15) (#343)

    • Cloud configuration storage implementation
    • Persistent settings across sessions
    • Foundation for enhanced cloud features

  • Async client context manager pattern (#344)

    • Improved cloud client architecture
    • Better resource management and connection handling
    • Enhanced reliability for cloud operations

Bug Fixes

  • Prevent nested project paths (#338)

    • Prevents data conflicts from nested project configurations
    • Improved project isolation and data integrity
    • Clear error messages for invalid project structures

  • Project deletion with permalink normalization (#345)

    • Fixed project deletion failures caused by permalink handling
    • Consistent permalink normalization across operations
    • Improved project management reliability

  • Add permalink normalization to project lookups (#348)

    • Ensures consistent project lookups across all operations
    • Fixes edge cases with project switching
    • Enhanced project management stability

  • Correct ProjectItem.home property (#341)

    • Fixed property to return path instead of name
    • Corrects API contract for project information
    • Improved integration reliability

  • Update view_note and ChatGPT tools for Claude Desktop compatibility (#355)

    • Fixed Claude Desktop integration issues
    • Enhanced MCP tool compatibility
    • Improved cross-platform tool support

Documentation

  • v0.15.0 assistant guide (#335)

    • Comprehensive guide for AI assistants working with Basic Memory
    • Enhanced integration documentation
    • Improved developer experience

  • Tool documentation for write_note (#339)

    • Clarified usage of empty string or ”/” for root folder
    • Improved API documentation
    • Better tool usage examples

Full Changelog: https://github.com/basicmachines-co/basic-memory/compare/v0.15.0…v0.15.1

v0.15.0 — 2024-10-04

Major Release: Cloud features, performance improvements, and enhanced project workflow

Highlights:

  • Basic Memory Cloud (invite-only beta) - Cloud sync, authentication, and file mounting
  • API performance improvements with background relation resolution
  • Improved project selection - Choose your project at conversation start
  • Python 3.13 support and .gitignore integration
  • ChatGPT integration with specialized tools

Cloud Features

  • Sync to cloud projects
  • CLI commands support cloud projects
  • ChatGPT tools integration

Basic Memory Cloud is currently in invite-only beta. Sign up for Early Access on basicmemory.com.

Performance Improvements

  • API performance optimizations (#315)

    • Implements SPEC-11 performance improvements
    • Optimized database queries and response times

  • Lifecycle management optimization (#320)

    • Enhanced application lifecycle management

  • Background relation resolution (#319)

    • Non-blocking startup with background processing
    • Prevents cold start delays

  • Non-blocking sync operations (#309)

    • Thread pool for sync operations
    • Improved responsiveness

Security Enhancements

  • Remove .env file loading (#330)

    • Eliminates unintended environment variable loading
    • Improved configuration security

  • .gitignore integration (#314)

    • Respects .gitignore patterns during sync
    • Prevents syncing build artifacts and temporary files

Platform Support

  • Python 3.13 support

    • Full compatibility with Python 3.13
    • Updated dependencies and CI testing

  • ChatGPT tools integration (#305)

    • ChatGPT-specific search and fetch tools

Bug Fixes

  • Permalink collision prevention (2a050ed)

    • Prevents data loss from fuzzy search matching similar file paths
    • Strict link resolution during entity creation

  • Normalize underscores in memory:// URLs (#329)

    • Consistent URL handling for knowledge graph navigation

  • Simplify entity upsert (#328)

    • Database-level conflict resolution
    • Reduced application complexity

  • Minimum timeframe enforcement (#318)

    • Enforced minimum timeframe for operations

  • DateTime JSON schema format (#312)

    • Proper datetime format annotations for MCP validation

  • Remove obsolete project management code (#310)

    • Cleanup of deprecated functionality

  • Fix move_note without file extension (#281)

    • Allow moving notes by title alone

Architecture

  • Disable permalinks config flag (#313)

    • Optional permalink generation

  • Enhanced project workflow (#298)

    • Improved project selection at conversation start

Breaking Changes & Migration

Project workflow changes:

  • AI assistants will ask which project to use at conversation start
  • You can still switch projects mid-conversation by saying “switch to project ‘foo’”
  • The assistant remembers your current project throughout the conversation

Migration: No action required - conversations will work naturally with the new workflow. Single-project users can enable default_project_mode in config to skip the selection prompt.

What’s changed for users:

  1. Project selection - AI asks which project to use when starting conversations
  2. Flexible switching - Tell the AI to switch projects anytime during the conversation
  3. Single-project mode - Enable default_project_mode in ~/.basic-memory/config.json to automatically use your default project

See What’s New for complete details and Getting Started for setup guidance.

v0.14.4 — 2025-09-04

Critical Bug Fixes

  • Critical search index bug - prevent note disappearing on edit (#257)
    • Fixed critical issue where notes would disappear during editing operations
    • Improved search index stability and consistency

Database & Project Management

  • Add missing foreign key constraints for project removal (#258)

    • Enhanced database integrity with proper foreign key constraints
    • Improved project deletion handling and data consistency

  • Add project isolation to ContextService.find_related() method (#262)

    • Fixed cross-project data leakage in context search operations
    • Strengthened project boundary enforcement

  • Complete project management special character support (#279)

    • Enhanced support for special characters in project names and paths
    • Improved cross-platform compatibility for project management

Platform Compatibility

  • Windows platform compatibility improvements (#252)

    • Addressed multiple Windows-specific issues and compatibility problems
    • Enhanced cross-platform file handling and path resolution

  • Fix Windows test failures and add Windows CI support (#273)

    • Added Windows continuous integration support
    • Fixed platform-specific test failures

File Handling & Synchronization

  • Handle vim atomic write DELETE events without ADD (#249)

    • Improved handling of vim’s atomic write operations
    • Better file synchronization with external editors

  • Sanitize filenames and allow optional kebab case (#260)

    • Enhanced filename sanitization for cross-platform compatibility
    • Added support for kebab-case filename formatting

MCP & API Improvements

  • Enable string-to-integer conversion for build_context depth parameter (#259)

    • Improved parameter handling in MCP build_context operations
    • Enhanced API flexibility and error handling

  • Use discriminated unions for MCP schema validation in build_context (#266)

    • Strengthened MCP schema validation with discriminated unions
    • Improved type safety and error detection

  • Add ISO datetime serialization to MCP schema models (#270)

    • Enhanced datetime handling in MCP operations
    • Improved API consistency and standard compliance

Logging & Configuration

  • Respect BASIC_MEMORY_LOG_LEVEL and BASIC_MEMORY_CONSOLE_LOGGING environment variables (#264)
    • Proper handling of logging configuration environment variables
    • Enhanced debugging and troubleshooting capabilities

Content Processing

  • Ensure all datetime operations return timezone-aware objects (#268)

    • Fixed timezone handling inconsistencies
    • Improved datetime processing reliability

  • Fix observation parsing to exclude markdown and wiki links (#269)

    • Enhanced content parsing to properly handle markdown and wiki link formats
    • Improved observation extraction accuracy

  • Update YAML frontmatter tag formatting for Obsidian compatibility (#280)

    • Enhanced Obsidian plugin compatibility with improved YAML frontmatter handling
    • Better integration with Obsidian’s tagging system

Infrastructure

  • Implement non-root Docker container to fix file ownership issues (#277)
    • Enhanced Docker container security by running as non-root user
    • Fixed file ownership and permission issues in containerized environments

New Contributors

v0.14.3 — 2025-08-02

Bug Fixes & Stability Improvements

  • Enhanced character conflict detection and error handling for sync operations (fb1350b)

    • Improved file path conflict detection for case-insensitive file systems
    • Better handling of character encoding differences and Unicode normalization
    • Enhanced error messages for sync conflicts

  • Replace recursive _traverse_messages with iterative approach (7585a29)

    • Fixed stack overflow issues when handling deep conversation threads
    • Improved performance for ChatGPT import with large conversation histories
    • Better memory usage for processing complex conversation structures

  • Handle missing ‘name’ key in memory JSON import (a4a3b1b)

    • Fixed crashes when importing memory JSON files with incomplete data
    • Improved error handling and validation for legacy import formats
    • Better backward compatibility with older memory export formats

  • Fix: basic memory home env var not respected when project path is changed (6361574)

    • Fixed environment variable handling for custom project locations
    • Improved cross-platform path resolution
    • Better support for relative and absolute path configurations

  • Fix: path traversal security vulnerability in mcp tools (a0cf623)

    • Secured MCP tool file operations against path traversal attacks
    • Enhanced input validation for file paths and operations
    • Improved security posture for file system interactions

Testing & Quality

  • Make case sensitivity test platform-aware (7460a93)
    • Fixed test failures on case-insensitive file systems (macOS, Windows)
    • Added platform detection for appropriate test behavior
    • Improved test reliability across different operating systems

v0.14.2 — 2025-07-03

  • #211: Fix deprecation warnings in output (e738037)

    • Replace deprecated datetime.utcnow() with timezone-aware alternatives and suppress SQLAlchemy warnings

  • #212: MCP Error with MCP-Hub: (518d57c)

    • The MCP Tools spec calls for accepting empty parameter objects, which these two tools did not
    • Verified by testing the container locally

v0.14.1 — 2025-07-02

Bug Fixes

  • #203: Pin FastMCP to prevent v2.10.0 breaking change (3a2e8c3)

    • FastMCP v2.10.0 introduced decorative ASCII box drawing characters in stdout output
    • This breaks JSON-based MCP protocol communication, preventing MCP servers from functioning
    • Constrained dependency to fastmcp<2.10.0 until upstream issue is resolved
    • Critical fix: without this, Basic Memory MCP server fails to start with Claude Desktop and other MCP clients

  • #190: Fix MCP integration issues (bd4f551)

    • Fixed problems with Model Context Protocol integration that affected tool functionality
    • Ensures stable communication between Basic Memory and AI tools like MCP Hub

  • #200: Add Cursor IDE support (5360005)

    • Added an “Add to Cursor” button for easier integration with Cursor IDE
    • Provides developers with seamless setup for their preferred AI-powered development environment

Documentation

  • Updated README.md with clearer installation instructions and troubleshooting guides (39f811f)

v0.14.0 — 2025-06-26

Features

  • Docker Container Registry Migration - Switch from Docker Hub to GitHub Container Registry for better security and integration (616c1f0)

    • Automated Docker image publishing via GitHub Actions CI/CD pipeline
    • Enhanced container security with GitHub’s integrated vulnerability scanning
    • Streamlined container deployment workflow for production environments

  • Enhanced Search Documentation - Comprehensive search syntax examples for improved user experience (a589f8b)

    • Detailed examples for Boolean search operators (AND, OR, NOT)
    • Advanced search patterns including phrase matching and field-specific queries
    • User-friendly documentation for complex search scenarios

  • Cross-Project File Management - Intelligent move operations with project boundary detection (db5ef7d)

    • Automatic detection of cross-project move attempts with helpful guidance
    • Clear error messages when attempting unsupported cross-project operations

Bug Fixes

  • #184: Preserve permalinks when editing notes without frontmatter permalinks (c2f4b63)

    • Fix permalink preservation during note editing operations
    • Ensure consistent permalink handling across different note formats
    • Maintain note identity and searchability during incremental edits

  • #183: Implement project-specific sync status checks for MCP tools (12b5152)

    • Fix sync status reporting to correctly reflect current project state
    • Resolve inconsistencies where sync status showed global instead of project-specific information
    • Improve project isolation for sync operations and status reporting

  • #180: Handle Boolean search syntax with hyphenated terms (546e3cd)

    • Fix search parsing issues with hyphenated terms in Boolean queries
    • Improve search query tokenization for complex term structures
    • Enhanced search reliability for technical documentation and multi-word concepts

  • #174: Respect BASIC_MEMORY_HOME environment variable in Docker containers (9f1db23)

    • Fix Docker container configuration to properly honor custom home directory settings
    • Improve containerized deployment flexibility with environment variable support
    • Ensure consistent behavior between local and containerized installations

  • #168: Scope entity queries by project_id in upsert_entity method (2a3adc1)

    • Fix entity isolation issues in multi-project setups
    • Prevent cross-project entity conflicts during database operations
    • Strengthen project boundary enforcement at the database level

  • #166: Handle None from_entity in Context API RelationSummary (8a065c3)

    • Fix null pointer exceptions in relation processing
    • Improve error handling for incomplete relation data
    • Enhanced stability for knowledge graph traversal operations

  • #164: Remove log level configuration from mcp_server.run() (224e4bf)

    • Simplify MCP server startup by removing redundant log level settings
    • Fix potential logging configuration conflicts
    • Streamline server initialization process

  • #162: Ensure permalinks are generated for entities with null permalinks during move operations (f506507)

    • Fix move operations for entities without existing permalinks
    • Automatic permalink generation during file move operations
    • Maintain database consistency during file reorganization

Technical Improvements

  • Comprehensive Test Coverage - Extensive test suites for new features and edge cases

    • Enhanced test coverage for project-specific sync status functionality
    • Additional test scenarios for search syntax validation and edge cases
    • Integration tests for Docker CI workflow and container publishing
    • Comprehensive move operations testing with project boundary validation

  • Docker CI/CD Pipeline - Production-ready automated container publishing (74847cc)

    • Automated Docker image building and publishing on release
    • Multi-architecture container support for AMD64 and ARM64 platforms
    • Integrated security scanning and vulnerability assessments
    • Streamlined deployment pipeline for production environments

  • Release Process Improvements - Enhanced automation and quality gates (a52ce1c)

    • Homebrew formula updates limited to stable releases only
    • Improved release automation with better quality control
    • Enhanced CI/CD pipeline reliability and error handling

  • Code Quality Enhancements - Improved error handling and validation

    • Better null safety in entity and relation processing
    • Enhanced project isolation validation throughout the codebase
    • Improved error messages and user guidance for edge cases
    • Strengthened database consistency guarantees across operations

Infrastructure

  • GitHub Container Registry Integration - Modern container infrastructure

    • Migration from Docker Hub to GitHub Container Registry (ghcr.io)
    • Improved security with integrated vulnerability scanning
    • Better integration with GitHub-based development workflow
    • Enhanced container versioning and artifact management

  • Enhanced CI/CD Workflows - Robust automated testing and deployment

    • Automated Docker image publishing on releases
    • Comprehensive test coverage validation before deployment
    • Multi-platform container building and publishing
    • Integration with GitHub’s security and monitoring tools

Migration Guide

This release includes several behind-the-scenes improvements and fixes. All changes are backward compatible:

  • Docker Users: Container images now served from ghcr.io/basicmachines-co/basic-memory instead of Docker Hub
  • Search Users: Enhanced search syntax handling - existing queries continue to work unchanged
  • Multi-Project Users: Improved project isolation - all existing projects remain fully functional
  • All Users: Enhanced stability and error handling - no breaking changes to existing workflows

Installation

# Latest stable release
uv tool install basic-memory

# Update existing installation
uv tool upgrade basic-memory

# Docker (new registry)
docker pull ghcr.io/basicmachines-co/basic-memory:latest

Full Changelog: https://github.com/basicmachines-co/basic-memory/compare/v0.13.7…v0.14.0

v0.13.7 — 2025-06-18

What’s Changed

NOTE: This version is the same package as v0.13.6. The version bump is to test the CI and make sure the Homebrew auto-update process is completely working. Installation by Homebrew is now fully supported.

Full Changelog: https://github.com/basicmachines-co/basic-memory/compare/v0.13.6…v0.13.7

v0.13.6 — 2025-06-18

Bug Fixes

New Contributors

Full Changelog

v0.13.5 — 2025-06-12

Bug Fixes

  • MCP Tools: Renamed create_project tool to create_memory_project for namespace isolation
  • Namespace: Continued namespace isolation effort to prevent conflicts with other MCP servers

Changes

  • Tool functionality remains identical – only the name changed from create_project to create_memory_project
  • All integration tests updated to use the new tool name
  • Completes namespace isolation for project management tools alongside list_memory_projects

Full Changelog

v0.13.4 — 2025-06-12

Bug Fixes

  • MCP Tools: Renamed list_projects tool to list_memory_projects to avoid naming conflicts with other MCP servers
  • Namespace: Improved tool naming specificity for better MCP server integration and isolation

Changes

  • Tool functionality remains identical – only the name changed from list_projects to list_memory_projects
  • All integration tests updated to use the new tool name
  • Better namespace isolation for Basic Memory MCP tools

Full Changelog

v0.13.3 — 2025-06-12

Bug Fixes

  • Projects: Fixed case-insensitive project switching where switching succeeded but subsequent operations failed due to session state inconsistency
  • Config: Enhanced config manager with case-insensitive project lookup using permalink-based matching
  • MCP Tools: Updated project management tools to store canonical project names from database instead of user input
  • API: Improved project service to handle both name and permalink lookups consistently

Full Changelog

v0.13.2 — 2025-06-11

What’s Changed

  • fix: project cli commands and case sensitivity when switching projects by @phernandez

Full Changelog

v0.13.1 — 2025-06-11

Bug Fixes

  • CLI: Fixed basic-memory project project management commands that were not working in v0.13.0
  • Projects: Resolved case sensitivity issues when switching between projects that caused “Project not found” errors
  • API: Standardized CLI project command endpoints and improved error handling
  • Core: Implemented consistent project name handling using permalinks to avoid case-related conflicts

Changes

  • 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

Full Changelog

Built with ❤️ by Basic Memory