What's New - v0.15.0

Cloud sync, performance improvements, and Python 3.13 support

v0.15.0

Basic Memory v0.15.0 introduces Cloud projects, multi-project conversation improvements, performance optimizations, and Python 3.13 support.

Basic Memory Cloud

Work with your knowledge base across multiple devices using cloud sync and storage.

Learn More

See the Basic Memory Cloud guide for complete documentation including:

• Using cloud mode via the command line
• Managing projects
• Uploading notes
• Viewing notes via the notes web ui

Multi-Project Conversations

AI assistants now ask which project to use at the start of conversations.

What You’ll Experience

When starting a new conversation, the AI will:

1. Check for available projects
2. Suggest the most active project based on recent activity
3. Ask which project to use
4. Remember your choice throughout the conversation

Example conversation:

You: "Let's work on documentation"

Claude: I see you have 3 projects: main, work-docs, creative-writing
Your most active project is work-docs (15 recent updates)
Should I use work-docs for this task?

You: "Yes"

Claude: I'll use work-docs for this session.
[All subsequent operations use work-docs project]

Default Project Setup

If you only use one project, enable automatic project selection:

Configuration (~/.basic-memory/config.json):

{
  "default_project": "main",
  "default_project_mode": true
}

With this enabled:

• AI uses your default project automatically when no project is specified
• You can still override by explicitly passing a different project to tools
• Suitable for users who primarily work in one project

Single Project Mode

Lock an MCP session to a specific project using the --project flag:

basic-memory mcp --project work-notes

Key behavior: All operations in this session use the specified project - the project parameter in tool calls is ignored. Useful for automation, security, and focused work sessions where you want to prevent accidental cross-project operations.

What Changed from v0.14.x

Removed tools:

• switch_project() - no longer available
• get_current_project() - no longer available

New behavior:

• AI asks which project to use at conversation start
• Project selection remembered throughout session
• list_memory_projects() shows available projects with activity suggestions
• recent_activity() provides cross-project discovery

All MCP tools now accept an explicit project parameter. See Technical Information for architecture details.

Performance Improvements

v0.15.0 includes significant performance optimizations across API operations, database queries, and startup processes.

API Optimizations

API response times improved 3-4x through query optimization and batch loading. The read_note endpoint now completes in 75ms instead of 250ms, while build_context operations with depth=2 run in 320ms instead of 1200ms.

What changed:

• Single optimized queries replace multiple separate database calls
• Batch loading eliminates N+1 query problems
• Eager loading strategies reduce round trips

Database queries for typical MCP tool calls dropped from 15-20 queries to 3-5 queries (75% reduction).

Startup Performance

The MCP server now starts instantly (<1 second) regardless of knowledge base size. Previously, large knowledge bases with 1000+ entities could have slow startup times.

Background relation resolution:

• Entity relations resolve in background threads
• Server accepts requests immediately on startup
• Relations complete asynchronously without blocking operations

Database Performance

SQLite now uses Write-Ahead Logging (WAL) mode by default, enabling concurrent reads and writes. This feature is particularly relevant to Windows users.

Performance gains:

• 2-3x faster write operations
• Readers don’t block writers (and vice versa)
• Bulk operations complete in seconds instead of minutes

Platform Support

Python 3.13

Basic Memory now supports Python 3.13. All dependencies have been verified compatible, and Python 3.13 is included in the CI test matrix.

Supported versions: Python 3.10, 3.11, 3.12, 3.13

.gitignore Support

The sync process now respects .gitignore patterns, automatically skipping files during synchronization.

What you’ll notice:

• Sensitive files (.env, credentials) excluded from sync
• Build artifacts (node_modules/, __pycache__/) not indexed
• OS and editor files (.DS_Store, .vscode/) ignored

Create a .gitignore in your project root to control which files are synced. See Controlling What gets synced in the user guide.

Bug Fixes

v0.15.0 resolves numerous bugs related to entity conflicts, URL handling, file operations, and platform compatibility.

Key fixes:

• Entity upsert conflicts resolved through database-level conflict handling
• memory:// URLs with underscores now properly normalized to hyphens
• move_note automatically handles file extensions (works with or without .md)
• .env file auto-loading removed for compatibility with code repos using env files
• Minimum timeframe enforcement prevents timezone edge cases
• DateTime fields include proper JSON schema format for MCP validation

See the complete changelog or the full v0.15.0 release notes.

v0.14.0

Advanced Note Editing

Edit notes incrementally without rewriting entire documents:

Append Operations

Adding to existing meeting notes:

You: "Add today's action items to our project meeting notes"

Claude: [Uses edit_note with append operation]
✓ Added to "Weekly Project Meeting Notes":

## Action Items - January 15, 2025
- [ ] Sarah: Update API documentation by Friday
- [ ] Mike: Review security implementation
- [ ] Team: Prepare demo for client meeting next week
- [ ] Jenny: Coordinate user testing sessions

[Content appended to existing note without affecting previous sections]

Building research over time:

You: "Add the new study findings to my climate research note"

Claude: [Appends new research section]
✓ Added to "Climate Change Solutions Research":

## Recent Studies - January 2025
- [study] MIT carbon capture efficiency improved 40% #breakthrough
- [finding] Solar panel costs dropped 15% year-over-year #economics
- [policy] EU carbon tax showing measurable emissions reduction #policy-impact

Relations automatically updated to connect with existing energy and policy notes.

Prepend Operations

Adding timestamps to journals:

You: "Add today's entry to my learning journal"

Claude: [Uses prepend to add newest entry at top]
✓ Added to beginning of "Daily Learning Journal":

## January 15, 2025 - React Performance Insights
- [discovery] useMemo doesn't help with props.children changes #react-gotcha
- [technique] React.Children.count for shallow comparison #workaround
- [pattern] Custom hooks for complex state logic #architecture

[New entry added above previous entries, maintaining chronological order]

Section Replacement

Updating specific documentation sections:

You: "Update the deployment section in our API docs with the new Docker setup"

Claude: [Replaces specific section under ## Deployment header]
✓ Updated "API Documentation" → ## Deployment section:


## 🐳 Docker Support

**Run Basic Memory in Docker Desktop or your own container runtime:**

Update the docker-compose.yml to set the path to your knowledge folder and then:

$ docker-compose up

Basic Memory now supports SSE and can be used with [n8n ↗️](https://n8n.io) workflows.


### Docker Setup (Updated)
# Build the application
docker build -t my-api:latest .

# Run with environment variables
docker run -d \
  -p 8000:8000 \
  -e DATABASE_URL=postgresql://... \
  -e REDIS_URL=redis://... \
  my-api:latest

### Environment Variables
- `DATABASE_URL`: PostgreSQL connection string
- `REDIS_URL`: Redis cache connection
- `JWT_SECRET`: Secret key for token signing

[Only the deployment section was updated, rest of documentation unchanged]

Find and Replace

Version updates across documentation:

You: "Update all references to v0.12.0 to v0.13.0 in the configuration guide"

Claude: [Uses find_replace with validation]
✓ Updated "Configuration Guide":
Found and replaced 3 occurrences of "v0.12.0" with "v0.13.0"

Changes made:
- Line 23: Version requirement updated
- Line 45: Docker image tag updated
- Line 67: Example configuration updated

Smart File Management

Move and organize notes with full database consistency:

Organizing Project Documentation

Moving notes to appropriate folders:

You: "Move all my old meeting notes to an archive folder"

Claude: [Moves files and updates database]
✓ Moved 8 meeting notes to archive/:
- meeting-2024-12-01.md → archive/meetings/meeting-2024-12-01.md
- meeting-2024-12-08.md → archive/meetings/meeting-2024-12-08.md
- weekly-standup-notes.md → archive/meetings/weekly-standup-notes.md

Database updated: permalinks, search index, and relations preserved.
All links to these notes remain functional.

Reorganizing research by topic:

You: "Move my AI research notes into a dedicated ai-research folder"

Claude: [Creates folder structure and moves files]
✓ Created folder: ai-research/
✓ Moved 12 AI-related notes:
- neural-networks.md → ai-research/neural-networks.md
- transformer-architecture.md → ai-research/transformer-architecture.md
- ai-ethics-considerations.md → ai-research/ethics/ai-ethics-considerations.md

Search functionality maintained, all relations preserved.

Renaming and Restructuring

Renaming notes for clarity:

You: "Rename 'temp-notes.md' to 'database-design-decisions.md'"

Claude: [Renames file and updates all references]
✓ Renamed: temp-notes.md → database-design-decisions.md
✓ Updated permalink: /temp-notes → /database-design-decisions
✓ Search index updated
✓ All internal links automatically updated

View Notes as Formatted Artifacts

Display notes as html formatted artifacts in Claude Desktop:

Technical Documentation

You: "Show me the API documentation as a formatted artifact"

Claude: [Uses view_note tool to display formatted artifact]

Claude displays a html formatted artifact with:

• Proper heading hierarchy
• Syntax-highlighted code blocks
• Organized sections and subsections
• Typography and spacing
• Clickable links and references

Creative Writing Projects

You: "Display my character development notes as an artifact"

Claude: [Creates formatted view of character notes]

Result: Readable format showing:

• Character profiles with clear sections
• Relationship maps and connections
• Story arc progression
• Research and background details

Research Summaries

You: "View my climate research compilation as an artifact"

Claude: [Formats research note]

Displays: Research document with:

• Executive summary
• Organized findings by category
• Source citations and links
• Visual hierarchy of information

Enhanced Search & Discovery

Find content more easily with frontmatter tag search:

Searchable Frontmatter Tags

Before v0.13.0 - Only content was searchable:

---
title: Coffee Brewing Methods
tags: [coffee, brewing, equipment, chemex]
---

# Coffee Brewing Methods
Pour-over techniques for better coffee...

Search for “chemex” would find nothing

v0.13.0 - Tags are now indexed and searchable:

You: "Search for all my chemex notes"

Claude: [Finds notes with 'chemex' in tags or content]
Found 4 notes mentioning 'chemex':
• Coffee Brewing Methods (tag match)
• Morning Routine - Coffee Setup (content match)
• Kitchen Equipment Reviews (tag match)
• Weekend Coffee Experiments (content match)

Better Content Discovery

Topic-based discovery:

You: "Find all my notes about productivity"

Claude: [Searches across titles, content, tags, and metadata]
Found 12 productivity-related notes:

By Tags:
• Daily Habits Tracking [productivity, habits]
• Time Management Systems [productivity, time-management]
• Focus Techniques [productivity, deep-work]

By Content:
• Weekly Reviews (mentions productivity goals)
• Book Notes: Deep Work (productivity principles)
• Morning Routine (productivity habits)

Project-scoped search:

You: "Search for 'authentication' in my work project only"

Claude: [Searches within current work project]
Found 6 authentication-related notes in work-notes project:
• API Authentication Strategy
• OAuth Implementation Guide
• Security Review - Auth System
• User Session Management
• Password Reset Flow
• Two-Factor Authentication Setup

Unified Database Architecture

Single app-level database for better performance and project management:

Automatic Migration

Seamless upgrade from v0.12.x:

After upgrading, Basic Memory will re-index all your project notes into a single project. Basic Memory uses your files as the source of truth, so there is no risk of data loss. You can see the status any time.

You: what is the sync status?

Claude:

**Current Status**: 🔄 Syncing 1 projects (231/331 files, 70%)
**System Ready**: 🔄 Processing

🔄 **File synchronization in progress**

Basic Memory is automatically processing all configured projects and building knowledge graphs.
This typically takes 1-3 minutes depending on the amount of content.

**Currently Processing:**
- **main**: Processing new files (231/331, 70%)

**What's happening:**
- Scanning and indexing markdown files
- Building entity and relationship graphs
- Setting up full-text search indexes
- Processing file changes and updates

**What you can do:**
- Wait for automatic processing to complete - no action needed
- Use this tool again to check progress
- Simple operations may work already
- All projects will be available once sync finishes

**Note**: All configured projects will be automatically synced during startup.
You don't need to manually switch projects - Basic Memory handles this for you.

Better Project Isolation

Secure project boundaries:

You: "Switch to work-notes project"
Claude: ✓ Switched to work-notes

You: "Search for client information"
Claude: [Searches only within work-notes project]
Found 3 client-related notes in work-notes:
• Client Requirements Document
• Meeting Notes - Client Kickoff
• Client Feedback Analysis

[Personal project notes remain completely isolated]

Complete MCP Tool Suite

New Project Management Tools

Discover and manage projects:

# List all available projects
list_projects()
→ Shows: main (default, current), work-notes, personal-journal

# Project discovery and management
list_memory_projects()
→ Shows all projects with guidance for session management

# Project-specific operations (stateless architecture)
write_note("My Note", "Content", "folder", project="work-notes")
→ Creates note in specified project

search_notes("query", project="work-notes")
→ Searches within specified project only

# Check sync status
sync_status()
→ Shows: file sync status, background operations, any issues

Enhanced Note Operations

Incremental editing tools:

# Append new content
edit_note("meeting-notes", "append", "\n## New Action Items\n- Task 1\n- Task 2")

# Prepend timestamp
edit_note("journal", "prepend", "# January 15, 2025\nToday's insights...")

# Replace specific section
edit_note("api-docs", "replace_section", "New deployment steps...", section="## Deployment")

# Find and replace with validation
edit_note("config", "find_replace", "v0.13.0", find_text="v0.12.0", expected_replacements=3)

File management tools:

# Move notes with database consistency
move_note("old-location.md", "new-folder/better-name.md")

# View formatted artifacts
view_note("important-document")
→ Displays note as formatted artifact in Claude Desktop

Real-World Workflows

Software Development Team

Morning standup routine:

You: "Switch to our team project and show yesterday's progress"

Claude: [Switches to team project]
✓ Switched to team-project

Recent activity (last 24 hours):
• Updated API documentation with new authentication endpoints
• Added deployment guide for Docker setup
• Meeting notes from client feedback session
• Bug tracking for payment processing issues

You: "Add today's standup notes"

Claude: [Creates structured standup note]
✓ Created "Daily Standup - January 15, 2025"

## Team Updates
- Sarah: Completed user authentication module, starting on password reset
- Mike: Fixed payment processing bug, investigating performance issues
- Jenny: Client demo went well, gathering requirements for Phase 2

## Blockers
- Need DevOps review for production deployment
- Waiting on client approval for UI changes

[Automatically linked to previous standup notes and relevant project documentation]

Academic Researcher

Research session workflow:

You: "Switch to my research project and add today's paper notes"

Claude: [Switches to research context]
✓ Switched to phd-research project

You: "Create detailed notes on the transformer architecture paper"

Claude: [Creates research note]
✓ Created "Attention Is All You Need - Paper Analysis"

## Key Contributions
- [innovation] Self-attention mechanism replaces RNN/CNN architectures #breakthrough
- [performance] Parallelizable training reduces computation time significantly #efficiency
- [impact] Enables larger models and better sequence understanding #scaling

## Technical Details
- [architecture] Multi-head attention with scaled dot-product attention #technical
- [training] Position encoding for sequence order without recurrence #implementation
- [results] BLEU score improvements on translation tasks #evaluation

## Relations
- revolutionizes [[Natural Language Processing]]
- enables [[Large Language Models]]
- influences [[Computer Vision - Vision Transformers]]

[Automatically connects to existing AI research and methodology notes]

You: "Move this to my 'foundational-papers' folder"

Claude: [Organizes research]
✓ Moved to foundational-papers/attention-is-all-you-need.md
✓ Updated research index and cross-references

Creative Writer

Novel planning session:

You: "Switch to my novel project and update character development"

Claude: [Switches to creative writing project]
✓ Switched to sci-fi-novel project

You: "Add new backstory details to Sarah Chen's character profile"

Claude: [Uses append to add to existing character note]
✓ Updated "Sarah Chen - Protagonist Character Profile"

## New Backstory Details
- [background] Lost younger brother in early neural implant experiment #trauma
- [motivation] Brother's death drives her investigation into NeuroLink Corp #personal-stakes
- [skill] Developed hacking abilities after brother's accident #character-development
- [relationship] Estranged from father who worked for competing tech company #family-conflict

## Character Arc Implications
- [growth] Must overcome trust issues to work with allies #emotional-journey
- [conflict] Personal vendetta vs. broader social justice #internal-struggle

Relations updated:
- drives [[Main Plot - Corporate Conspiracy]]
- connects_to [[NeuroLink Corporation - Antagonist]]
- influences [[Theme - Technology vs Humanity]]

You: "View the character profile as a formatted artifact"

Claude: [Displays character sheet]
[Shows organized character profile with clear sections, relationship maps, and story connections]

Personal Knowledge Management

Weekly life review:

You: "Switch to my personal project and create this week's reflection"

Claude: [Switches to personal knowledge context]
✓ Switched to personal-life project

You: "Review this week's notes and create a summary of patterns and insights"

Claude: [Analyzes recent personal notes]
✓ Created "Weekly Reflection - January 15, 2025"

## This Week's Patterns
- [energy] Most productive mornings when I exercise first #health-performance-link
- [social] Deep conversations with friends boost mood for 2+ days #relationship-impact
- [work] Finished projects faster when I break tasks into 25-minute chunks #productivity-technique

## Growth Areas Identified
- [challenge] Procrastination increases when overwhelmed - need better task management #self-awareness
- [opportunity] Reading before bed improves sleep quality #habit-optimization

## Goal Progress
- [fitness] Ran 3 times this week (goal: 3x) ✓ #achievement
- [learning] Completed 2 Spanish lessons (goal: 3x) #partial-progress
- [creativity] No creative writing this week #missed-goal

## Relations
- builds_on [[Monthly Goals - January 2025]]
- informs [[Habit Tracking and Optimization]]
- connects_to [[Work-Life Balance Strategies]]

You: "Move my old reflections to an archive folder"

Claude: [Organizes personal history]
✓ Moved 12 reflection notes to archive/reflections/
✓ Maintained chronological order and cross-references
✓ Updated personal development timeline

Get started with Basic Memory →