feat: Multi-project support, OAuth authentication, and major improvements

[bm-claudeai]

Overview

This PR introduces several major features and improvements to Basic Memory, preparing for the v0.13.0 release.

Major Features

🎯 Multi-Project Support

• Unified database architecture with proper project isolation
• Project management API for creating, updating, and managing projects
• Projects defined in config.json and synced with database
• Backward compatibility with automatic default project creation
• CLI commands and API endpoints support project context

🔐 OAuth 2.1 Authentication

• Multiple provider support (Basic, Supabase, GitHub, Google framework)
• JWT-based access tokens with configurable expiration
• PKCE support for enhanced security
• MCP Inspector integration for authenticated testing
• New CLI commands: basic-memory auth register-client and basic-memory auth test-auth

📝 Server-Side Template Engine

• Handlebars templates for prompt and response rendering
• Custom helpers for rich formatting
• XML-formatted output for better LLM consumption
• Template compilation caching for performance

📥 Enhanced Import System

• Unified importer framework with consistent interface
• New /import API endpoints
• Real-time progress tracking
• Support for ChatGPT, Claude conversations/projects, and Memory JSON

📁 Directory Navigation

• Browse and navigate project file structure
• /directory/tree and /directory/list endpoints
• Hierarchical tree view of knowledge base

API Changes

New Endpoints

• Project management: /projects, /projects/{id}
• Import API: /{project}/import/*
• Directory API: /{project}/directory/*
• Prompt templates: /{project}/prompts/*
• Management API: /management/sync/*

Breaking Changes

• All knowledge endpoints now require project context: /{project}/entities
• Database location unified at ~/.basic-memory/memory.db

Technical Improvements

• Simplified MCP server startup using FastMCP's built-in capabilities
• Unified background sync approach for all transports
• Fixed JWT audience validation and OAuth flow
• Comprehensive test coverage for new features
• Type error fixes and improved error handling

Testing

Run the full test suite:

make test

OAuth can be tested with:

export FASTMCP_AUTH_SECRET_KEY="test-secret-key"
FASTMCP_AUTH_ENABLED=true basic-memory mcp --transport streamable-http
basic-memory auth test-auth

Release Notes

See RELEASE_NOTES_v0.13.0.md for complete details.

🤖 This PR was created with the assistance of Claude