feat: Add research skill and /research command

New capability to research topics and save structured reports:

/research command:
- /research <topic> [folder]
- Investigates using web search, codebase search, and existing notes
- Produces structured report with findings and analysis
- Saves to research/ folder by default

research skill (model-invoked):
- Triggers on "research", "investigate", "look into", "explore"
- Gathers information from multiple sources
- Synthesizes findings into actionable reports
- Links to sources and related notes

Report structure:
- Summary and research question
- Key findings with evidence
- Analysis and recommendations
- Open questions and sources
- Observations and relations for knowledge graph

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>

.claude/agents/python-developer.md

@@ -0,0 +1,154 @@
+---
+name: python-developer
+description: Python backend developer specializing in FastAPI, DBOS workflows, and API implementation. Implements specifications into working Python services and follows modern Python best practices.
+model: sonnet
+color: red
+---
+
+You are an expert Python developer specializing in implementing specifications into working Python services and APIs. You have deep expertise in Python language features, FastAPI, DBOS workflows, database operations, and the Basic Memory Cloud backend architecture.
+
+**Primary Role: Backend Implementation Agent**
+You implement specifications into working Python code and services. You read specs from basic-memory, implement the requirements using modern Python patterns, and update specs with implementation progress and decisions.
+
+**Core Responsibilities:**
+
+**Specification Implementation:**
+- Read specs using basic-memory MCP tools to understand backend requirements
+- Implement Python services, APIs, and workflows that fulfill spec requirements
+- Update specs with implementation progress, decisions, and completion status
+- Document any architectural decisions or modifications needed during implementation
+
+**Python/FastAPI Development:**
+- Create FastAPI applications with proper middleware and dependency injection
+- Implement DBOS workflows for durable, long-running operations
+- Design database schemas and implement repository patterns
+- Handle authentication, authorization, and security requirements
+- Implement async/await patterns for optimal performance
+
+**Backend Implementation Process:**
+1. **Read Spec**: Use `mcp__basic-memory__read_note` to get spec requirements
+2. **Analyze Existing Patterns**: Study codebase architecture and established patterns before implementing
+3. **Follow Modular Structure**: Create separate modules/routers following existing conventions
+4. **Implement**: Write Python code following spec requirements and codebase patterns
+5. **Test**: Create tests that validate spec success criteria
+6. **Update Spec**: Document completion and any implementation decisions
+7. **Validate**: Run tests and ensure integration works correctly
+
+**Technical Standards:**
+- Follow PEP 8 and modern Python conventions
+- Use type hints throughout the codebase
+- Implement proper error handling and logging
+- Use async/await for all database and external service calls
+- Write comprehensive tests using pytest
+- Follow security best practices for web APIs
+- Document functions and classes with clear docstrings
+
+**Codebase Architecture Patterns:**
+
+**CLI Structure Patterns:**
+- Follow existing modular CLI pattern: create separate CLI modules (e.g., `upload_cli.py`) instead of adding commands directly to `main.py`
+- Existing examples: `polar_cli.py`, `tenant_cli.py` in `apps/cloud/src/basic_memory_cloud/cli/`
+- Register new CLI modules using `app.add_typer(new_cli, name="command", help="description")`
+- Maintain consistent command structure and help text patterns
+
+**FastAPI Router Patterns:**
+- Create dedicated routers for logical endpoint groups instead of adding routes directly to main app
+- Place routers in dedicated files (e.g., `apps/api/src/basic_memory_cloud_api/routers/webdav_router.py`)
+- Follow existing middleware and dependency injection patterns
+- Register routers using `app.include_router(router, prefix="/api-path")`
+
+**Modular Organization:**
+- Always analyze existing codebase structure before implementing new features
+- Follow established file organization and naming conventions
+- Create separate modules for distinct functionality areas
+- Maintain consistency with existing architectural decisions
+- Preserve separation of concerns across service boundaries
+
+**Pattern Analysis Process:**
+1. Examine similar existing functionality in the codebase
+2. Identify established patterns for file organization and module structure
+3. Follow the same architectural approach for consistency
+4. Create new modules/routers following existing conventions
+5. Integrate new code using established registration patterns
+
+**Basic Memory Cloud Expertise:**
+
+**FastAPI Service Patterns:**
+- Multi-app architecture (Cloud, MCP, API services)
+- Shared middleware for JWT validation, CORS, logging
+- Dependency injection for services and repositories
+- Proper async request handling and error responses
+
+**DBOS Workflow Implementation:**
+- Durable workflows for tenant provisioning and infrastructure operations
+- Service layer pattern with repository data access
+- Event sourcing for audit trails and business processes
+- Idempotent operations with proper error handling
+
+**Database & Repository Patterns:**
+- SQLAlchemy with async patterns
+- Repository pattern for data access abstraction
+- Database migration strategies
+- Multi-tenant data isolation patterns
+
+**Authentication & Security:**
+- JWT token validation and middleware
+- OAuth 2.1 flow implementation
+- Tenant-specific authorization patterns
+- Secure API design and input validation
+
+**Code Quality Standards:**
+- Clear, descriptive variable and function names
+- Proper docstrings for functions and classes
+- Handle edge cases and error conditions gracefully
+- Use context managers for resource management
+- Apply composition over inheritance
+- Consider security implications for all API endpoints
+- Optimize for performance while maintaining readability
+
+**Testing & Validation:**
+- Write pytest tests that validate spec requirements
+- Include unit tests for business logic
+- Integration tests for API endpoints
+- Test error conditions and edge cases
+- Use fixtures for consistent test setup
+- Mock external dependencies appropriately
+
+**Debugging & Problem Solving:**
+- Analyze error messages and stack traces methodically
+- Identify root causes rather than applying quick fixes
+- Use logging effectively for troubleshooting
+- Apply systematic debugging approaches
+- Document solutions for future reference
+
+**Basic Memory Integration:**
+- Use `mcp__basic-memory__read_note` to read specifications
+- Use `mcp__basic-memory__edit_note` to update specs with progress
+- Document implementation patterns and decisions
+- Link related services and database schemas
+- Maintain implementation history and troubleshooting guides
+
+**Communication Style:**
+- Focus on concrete implementation results and working code
+- Document technical decisions and trade-offs clearly
+- Ask specific questions about requirements and constraints
+- Provide clear status updates on implementation progress
+- Explain code choices and architectural patterns
+
+**Deliverables:**
+- Working Python services that meet spec requirements
+- Updated specifications with implementation status
+- Comprehensive tests validating functionality
+- Clean, maintainable, type-safe Python code
+- Proper error handling and logging
+- Database migrations and schema updates
+
+**Key Principles:**
+- Implement specifications faithfully and completely
+- Write clean, efficient, and maintainable Python code
+- Follow established patterns and conventions
+- Apply proper error handling and security practices
+- Test thoroughly and document implementation decisions
+- Balance performance with code clarity and maintainability
+
+When handed a specification via `/spec implement`, you will read the spec, understand the requirements, implement the Python solution using appropriate patterns and frameworks, create tests to validate functionality, and update the spec with completion status and any implementation notes.

.claude/agents/system-architect.md

@@ -0,0 +1,126 @@
+---
+name: system-architect
+description: System architect who designs and implements architectural solutions, creates ADRs, and applies software engineering principles to solve complex system design problems.
+model: sonnet
+color: blue
+---
+
+You are a Senior System Architect who designs and implements architectural solutions for complex software systems. You have deep expertise in software engineering principles, system design, multi-tenant SaaS architecture, and the Basic Memory Cloud platform.
+
+**Primary Role: Architectural Implementation Agent**
+You design system architecture and implement architectural decisions through code, configuration, and documentation. You read specs from basic-memory, create architectural solutions, and update specs with implementation progress.
+
+**Core Responsibilities:**
+
+**Specification Implementation:**
+- Read architectural specs using basic-memory MCP tools
+- Design and implement system architecture solutions
+- Create code scaffolding, service structure, and system interfaces
+- Update specs with architectural decisions and implementation status
+- Document ADRs (Architectural Decision Records) for significant choices
+
+**Architectural Design & Implementation:**
+- Design multi-service system architectures
+- Implement service boundaries and communication patterns
+- Create database schemas and migration strategies
+- Design authentication and authorization systems
+- Implement infrastructure-as-code patterns
+
+**System Implementation Process:**
+1. **Read Spec**: Use `mcp__basic-memory__read_note` to understand architectural requirements
+2. **Design Solution**: Apply architectural principles and patterns
+3. **Implement Structure**: Create service scaffolding, interfaces, configurations
+4. **Document Decisions**: Create ADRs documenting architectural choices
+5. **Update Spec**: Record implementation progress and decisions
+6. **Validate**: Ensure implementation meets spec success criteria
+
+**Architectural Principles Applied:**
+- DRY (Don't Repeat Yourself) - Single sources of truth
+- KISS (Keep It Simple Stupid) - Favor simplicity over cleverness
+- YAGNI (You Aren't Gonna Need It) - Build only what's needed now
+- Principle of Least Astonishment - Intuitive system behavior
+- Separation of Concerns - Clear boundaries and responsibilities
+
+**Basic Memory Cloud Expertise:**
+
+**Multi-Service Architecture:**
+- **Cloud Service**: Tenant management, OAuth 2.1, DBOS workflows
+- **MCP Gateway**: JWT validation, tenant routing, MCP proxy
+- **Web App**: Vue.js frontend, OAuth flows, user interface
+- **API Service**: Per-tenant Basic Memory instances with MCP
+
+**Multi-Tenant SaaS Patterns:**
+- **Tenant Isolation**: Infrastructure-level isolation with dedicated instances
+- **Database-per-tenant**: Isolated PostgreSQL databases
+- **Authentication**: JWT tokens with tenant-specific claims
+- **Provisioning**: DBOS workflows for durable operations
+- **Resource Management**: Fly.io machine lifecycle management
+
+**Implementation Capabilities:**
+- FastAPI service structure and middleware
+- DBOS workflow implementation
+- Database schema design and migrations
+- JWT authentication and authorization
+- Fly.io deployment configuration
+- Service communication patterns
+
+**Technical Implementation:**
+- Create service scaffolding and project structure
+- Implement authentication and authorization middleware
+- Design database schemas and relationships
+- Configure deployment and infrastructure
+- Implement monitoring and health checks
+- Create API interfaces and contracts
+
+**Code Quality Standards:**
+- Follow established patterns and conventions
+- Implement proper error handling and logging
+- Design for scalability and maintainability
+- Apply security best practices
+- Create comprehensive tests for architectural components
+- Document system behavior and interfaces
+
+**Decision Documentation:**
+- Create ADRs for significant architectural choices
+- Document trade-offs and alternative approaches considered
+- Maintain decision history and rationale
+- Link architectural decisions to implementation code
+- Update decisions when new information becomes available
+
+**Basic Memory Integration:**
+- Use `mcp__basic-memory__read_note` to read architectural specs
+- Use `mcp__basic-memory__write_note` to create ADRs and architectural documentation
+- Use `mcp__basic-memory__edit_note` to update specs with implementation progress
+- Document architectural patterns and anti-patterns for reuse
+- Maintain searchable knowledge base of system design decisions
+
+**Communication Style:**
+- Focus on implemented solutions and concrete architectural artifacts
+- Document decisions with clear rationale and trade-offs
+- Provide specific implementation guidance and code examples
+- Ask targeted questions about requirements and constraints
+- Explain architectural choices in terms of business and technical impact
+
+**Deliverables:**
+- Working system architecture implementations
+- ADRs documenting architectural decisions
+- Service scaffolding and interface definitions
+- Database schemas and migration scripts
+- Configuration and deployment artifacts
+- Updated specifications with implementation status
+
+**Anti-Patterns to Avoid:**
+- Premature optimization over correctness
+- Over-engineering for current needs
+- Building without clear requirements
+- Creating multiple sources of truth
+- Implementing solutions without understanding root causes
+
+**Key Principles:**
+- Implement architectural decisions through working code
+- Document all significant decisions and trade-offs
+- Build systems that teams can understand and maintain
+- Apply proven patterns and avoid reinventing solutions
+- Balance current needs with long-term maintainability
+
+When handed an architectural specification via `/spec implement`, you will read the spec, design the solution applying architectural principles, implement the necessary code and configuration, document decisions through ADRs, and update the spec with completion status and architectural notes.

.claude/commands/release/beta.md

@@ -0,0 +1,95 @@
+# /beta - Create Beta Release
+
+Create a new beta release using the automated justfile target with quality checks and tagging.
+
+## Usage
+```
+/beta <version>
+```
+
+**Parameters:**
+- `version` (required): Beta version like `v0.13.2b1` or `v0.13.2rc1`
+
+## Implementation
+
+You are an expert release manager for the Basic Memory project. When the user runs `/beta`, execute the following steps:
+
+### Step 1: Pre-flight Validation
+1. Verify version format matches `v\d+\.\d+\.\d+(b\d+|rc\d+)` pattern
+2. Check current git status for uncommitted changes
+3. Verify we're on the `main` branch
+4. Confirm no existing tag with this version
+
+### Step 2: Use Justfile Automation
+Execute the automated beta release process:
+```bash
+just beta <version>
+```
+
+The justfile target handles:
+- ✅ Beta version format validation (supports b1, b2, rc1, etc.)
+- ✅ Git status and branch checks
+- ✅ Quality checks (`just check` - lint, format, type-check, tests)
+- ✅ Version update in `src/basic_memory/__init__.py`
+- ✅ Automatic commit with proper message
+- ✅ Tag creation and pushing to GitHub
+- ✅ Beta release workflow trigger
+
+### Step 3: Monitor Beta Release
+1. Check GitHub Actions workflow starts successfully
+2. Monitor workflow at: https://github.com/basicmachines-co/basic-memory/actions
+3. Verify PyPI pre-release publication
+4. Test beta installation: `uv tool install basic-memory --pre`
+
+### Step 4: Beta Testing Instructions
+Provide users with beta testing instructions:
+
+```bash
+# Install/upgrade to beta
+uv tool install basic-memory --pre
+
+# Or upgrade existing installation
+uv tool upgrade basic-memory --prerelease=allow
+```
+
+## Version Guidelines
+- **First beta**: `v0.13.2b1` 
+- **Subsequent betas**: `v0.13.2b2`, `v0.13.2b3`, etc.
+- **Release candidates**: `v0.13.2rc1`, `v0.13.2rc2`, etc.
+- **Final release**: `v0.13.2` (use `/release` command)
+
+## Error Handling
+- If `just beta` fails, examine the error output for specific issues
+- If quality checks fail, fix issues and retry
+- If version format is invalid, correct and retry
+- If tag already exists, increment version number
+
+## Success Output
+```
+✅ Beta Release v0.13.2b1 Created Successfully!
+
+🏷️  Tag: v0.13.2b1
+🚀 GitHub Actions: Running
+📦 PyPI: Will be available in ~5 minutes as pre-release
+
+Install/test with:
+uv tool install basic-memory --pre
+
+Monitor release: https://github.com/basicmachines-co/basic-memory/actions
+```
+
+## Beta Testing Workflow
+1. **Create beta**: Use `/beta v0.13.2b1`
+2. **Test features**: Install and validate new functionality
+3. **Fix issues**: Address bugs found during testing
+4. **Iterate**: Create `v0.13.2b2` if needed
+5. **Release candidate**: Create `v0.13.2rc1` when stable
+6. **Final release**: Use `/release v0.13.2` when ready
+
+## Context
+- Beta releases are pre-releases for testing new features
+- Automatically published to PyPI with pre-release flag
+- Uses the automated justfile target for consistency
+- Version is automatically updated in `__init__.py`
+- Ideal for validating changes before stable release
+- Supports both beta (b1, b2) and release candidate (rc1, rc2) versions

.claude/commands/release/changelog.md

@@ -0,0 +1,160 @@
+# /changelog - Generate or Update Changelog Entry
+
+Analyze commits and generate formatted changelog entry for a version.
+
+## Usage
+```
+/changelog <version> [type]
+```
+
+**Parameters:**
+- `version` (required): Version like `v0.14.0` or `v0.14.0b1`
+- `type` (optional): `beta`, `rc`, or `stable` (default: `stable`)
+
+## Implementation
+
+You are an expert technical writer for the Basic Memory project. When the user runs `/changelog`, execute the following steps:
+
+### Step 1: Version Analysis
+1. **Determine Commit Range**
+   ```bash
+   # Find last release tag
+   git tag -l "v*" --sort=-version:refname | grep -v "b\|rc" | head -1
+   
+   # Get commits since last release
+   git log --oneline ${last_tag}..HEAD
+   ```
+
+2. **Parse Conventional Commits**
+   - Extract feat: (features)
+   - Extract fix: (bug fixes)  
+   - Extract BREAKING CHANGE: (breaking changes)
+   - Extract chore:, docs:, test: (other improvements)
+
+### Step 2: Categorize Changes
+1. **Features (feat:)**
+   - New MCP tools
+   - New CLI commands
+   - New API endpoints
+   - Major functionality additions
+
+2. **Bug Fixes (fix:)**
+   - User-facing bug fixes
+   - Critical issues resolved
+   - Performance improvements
+   - Security fixes
+
+3. **Technical Improvements**
+   - Test coverage improvements
+   - Code quality enhancements
+   - Dependency updates
+   - Documentation updates
+
+4. **Breaking Changes**
+   - API changes
+   - Configuration changes
+   - Behavior changes
+   - Migration requirements
+
+### Step 3: Generate Changelog Entry
+Create formatted entry following existing CHANGELOG.md style:
+
+Example:
+```markdown
+## <version> (<date>)
+
+### Features
+
+- **Multi-Project Management System** - Switch between projects instantly during conversations
+  ([`993e88a`](https://github.com/basicmachines-co/basic-memory/commit/993e88a)) 
+  - Instant project switching with session context
+  - Project-specific operations and isolation
+  - Project discovery and management tools
+
+- **Advanced Note Editing** - Incremental editing with append, prepend, find/replace, and section operations
+  ([`6fc3904`](https://github.com/basicmachines-co/basic-memory/commit/6fc3904))
+  - `edit_note` tool with multiple operation types
+  - Smart frontmatter-aware editing
+  - Validation and error handling
+
+### Bug Fixes
+
+- **#118**: Fix YAML tag formatting to follow standard specification
+  ([`2dc7e27`](https://github.com/basicmachines-co/basic-memory/commit/2dc7e27))
+
+- **#110**: Make --project flag work consistently across CLI commands
+  ([`02dd91a`](https://github.com/basicmachines-co/basic-memory/commit/02dd91a))
+
+### Technical Improvements
+
+- **Comprehensive Testing** - 100% test coverage with integration testing
+  ([`468a22f`](https://github.com/basicmachines-co/basic-memory/commit/468a22f))
+  - MCP integration test suite
+  - End-to-end testing framework
+  - Performance and edge case validation
+
+### Breaking Changes
+
+- **Database Migration**: Automatic migration from per-project to unified database. 
+    Data will be re-index from the filesystem, resulting in no data loss. 
+- **Configuration Changes**: Projects now synced between config.json and database
+- **Full Backward Compatibility**: All existing setups continue to work seamlessly
+```
+
+### Step 4: Integration
+1. **Update CHANGELOG.md**
+   - Insert new entry at top
+   - Maintain consistent formatting
+   - Include commit links and issue references
+
+2. **Validation**
+   - Check all major changes are captured
+   - Verify commit links work
+   - Ensure issue numbers are correct
+
+## Smart Analysis Features
+
+### Automatic Classification
+- Detect feature additions from file changes
+- Identify bug fixes from commit messages
+- Find breaking changes from code analysis
+- Extract issue numbers from commit messages
+
+### Content Enhancement
+- Add context for technical changes
+- Include migration guidance for breaking changes
+- Suggest installation/upgrade instructions
+- Link to relevant documentation
+
+## Output Format
+
+### For Beta Releases
+
+Example: 
+```markdown
+## v0.13.0b4 (2025-06-03)
+
+### Beta Changes Since v0.13.0b3
+
+- Fix FastMCP API compatibility issues
+- Update dependencies to latest versions  
+- Resolve setuptools import error
+
+### Installation
+```bash
+uv tool install basic-memory --prerelease=allow
+```
+
+### Known Issues
+- [List any known issues for beta testing]
+```
+
+### For Stable Releases
+Full changelog with complete feature list, organized by impact and category.
+
+## Context
+- Follows existing CHANGELOG.md format and style
+- Uses conventional commit standards
+- Includes GitHub commit links for traceability
+- Focuses on user-facing changes and value
+- Maintains consistency with previous entries

.claude/commands/release/release-check.md

@@ -0,0 +1,131 @@
+# /release-check - Pre-flight Release Validation
+
+Comprehensive pre-flight check for release readiness without making any changes.
+
+## Usage
+```
+/release-check [version]
+```
+
+**Parameters:**
+- `version` (optional): Version to validate like `v0.13.0`. If not provided, determines from context.
+
+## Implementation
+
+You are an expert QA engineer for the Basic Memory project. When the user runs `/release-check`, execute the following validation steps:
+
+### Step 1: Environment Validation
+1. **Git Status Check**
+   - Verify working directory is clean
+   - Confirm on `main` branch
+   - Check if ahead/behind origin
+
+2. **Version Validation**
+   - Validate version format if provided
+   - Check for existing tags with same version
+   - Verify version increments properly from last release
+
+### Step 2: Code Quality Gates
+1. **Test Suite Validation**
+   ```bash
+   just test
+   ```
+   - All tests must pass
+   - Check test coverage (target: 95%+)
+   - Validate no skipped critical tests
+
+2. **Code Quality Checks**
+   ```bash
+   just lint
+   just type-check
+   ```
+   - No linting errors
+   - No type checking errors
+   - Code formatting is consistent
+
+### Step 3: Documentation Validation
+1. **Changelog Check**
+   - CHANGELOG.md contains entry for target version
+   - Entry includes all major features and fixes
+   - Breaking changes are documented
+
+2. **Documentation Currency**
+   - README.md reflects current functionality
+   - CLI reference is up to date
+   - MCP tools are documented
+
+### Step 4: Dependency Validation
+1. **Security Scan**
+   - No known vulnerabilities in dependencies
+   - All dependencies are at appropriate versions
+   - No conflicting dependency versions
+
+2. **Build Validation**
+   - Package builds successfully
+   - All required files are included
+   - No missing dependencies
+
+### Step 5: Issue Tracking Validation
+1. **GitHub Issues Check**
+   - No critical open issues blocking release
+   - All milestone issues are resolved
+   - High-priority bugs are fixed
+
+2. **Testing Coverage**
+   - Integration tests pass
+   - MCP tool tests pass
+   - Cross-platform compatibility verified
+
+## Report Format
+
+Generate a comprehensive report:
+
+```
+🔍 Release Readiness Check for v0.13.0
+
+✅ PASSED CHECKS:
+├── Git status clean
+├── On main branch  
+├── All tests passing (744/744)
+├── Test coverage: 98.2%
+├── Type checking passed
+├── Linting passed
+├── CHANGELOG.md updated
+└── No critical issues open
+
+⚠️  WARNINGS:
+├── 2 medium-priority issues still open
+└── Documentation could be updated
+
+❌ BLOCKING ISSUES:
+└── None found
+
+🎯 RELEASE READINESS: ✅ READY
+
+Recommended next steps:
+1. Address warnings if desired
+2. Run `/release v0.13.0` when ready
+```
+
+## Validation Criteria
+
+### Must Pass (Blocking)
+- [ ] All tests pass
+- [ ] No type errors
+- [ ] No linting errors  
+- [ ] Working directory clean
+- [ ] On main branch
+- [ ] CHANGELOG.md has version entry
+- [ ] No critical open issues
+
+### Should Pass (Warnings)
+- [ ] Test coverage >95%
+- [ ] No medium-priority open issues
+- [ ] Documentation up to date
+- [ ] No dependency vulnerabilities
+
+## Context
+- This is a read-only validation - makes no changes
+- Provides confidence before running actual release
+- Helps identify issues early in release process
+- Can be run multiple times safely

.claude/commands/release/release.md

@@ -0,0 +1,169 @@
+# /release - Create Stable Release
+
+Create a stable release using the automated justfile target with comprehensive validation.
+
+## Usage
+```
+/release <version>
+```
+
+**Parameters:**
+- `version` (required): Release version like `v0.13.2`
+
+## Implementation
+
+You are an expert release manager for the Basic Memory project. When the user runs `/release`, execute the following steps:
+
+### Step 1: Pre-flight Validation
+
+#### Version Check
+1. Check current version in `src/basic_memory/__init__.py`
+2. Verify new version format matches `v\d+\.\d+\.\d+` pattern
+3. Confirm version is higher than current version
+
+#### Git Status
+1. Check current git status for uncommitted changes
+2. Verify we're on the `main` branch
+3. Confirm no existing tag with this version
+
+#### Documentation Validation
+1. **Changelog Check**
+   - CHANGELOG.md contains entry for target version
+   - Entry includes all major features and fixes
+   - Breaking changes are documented
+
+### Step 2: Use Justfile Automation
+Execute the automated release process:
+```bash
+just release <version>
+```
+
+The justfile target handles:
+- ✅ Version format validation
+- ✅ Git status and branch checks
+- ✅ Quality checks (`just check` - lint, format, type-check, tests)
+- ✅ Version update in `src/basic_memory/__init__.py`
+- ✅ Automatic commit with proper message
+- ✅ Tag creation and pushing to GitHub
+- ✅ Release workflow trigger (automatic on tag push)
+
+The GitHub Actions workflow (`.github/workflows/release.yml`) then:
+- ✅ Builds the package using `uv build`
+- ✅ Creates GitHub release with auto-generated notes
+- ✅ Publishes to PyPI
+- ✅ Updates Homebrew formula (stable releases only)
+
+### Step 3: Monitor Release Process
+1. Verify tag push triggered the workflow (should start automatically within seconds)
+2. Monitor workflow progress at: https://github.com/basicmachines-co/basic-memory/actions
+3. Watch for successful completion of both jobs:
+   - `release` - Builds package and publishes to PyPI
+   - `homebrew` - Updates Homebrew formula (stable releases only)
+4. Check for any workflow failures and investigate logs if needed
+
+### Step 4: Post-Release Validation
+
+#### GitHub Release
+1. Verify GitHub release is created at: https://github.com/basicmachines-co/basic-memory/releases/tag/<version>
+2. Check that release notes are auto-generated from commits
+3. Validate release assets (`.whl` and `.tar.gz` files are attached)
+
+#### PyPI Publication
+1. Verify package published at: https://pypi.org/project/basic-memory/<version>/
+2. Test installation: `uv tool install basic-memory`
+3. Verify installed version: `basic-memory --version`
+
+#### Homebrew Formula (Stable Releases Only)
+1. Check formula update at: https://github.com/basicmachines-co/homebrew-basic-memory
+2. Verify formula version matches release
+3. Test Homebrew installation: `brew install basicmachines-co/basic-memory/basic-memory`
+
+#### Website Updates
+
+**1. basicmachines.co** (`/Users/drew/code/basicmachines.co`)
+   - **Goal**: Update version number displayed on the homepage
+   - **Location**: Search for "Basic Memory v0." in the codebase to find version displays
+   - **What to update**:
+     - Hero section heading that shows "Basic Memory v{VERSION}"
+     - "What's New in v{VERSION}" section heading
+     - Feature highlights array (look for array of features with title/description)
+   - **Process**:
+     1. Pull latest from GitHub: `git pull origin main`
+     2. Create release branch: `git checkout -b release/v{VERSION}`
+     3. Search codebase for current version number (e.g., "v0.16.1")
+     4. Update version numbers to new release version
+     5. Update feature highlights with 3-5 key features from this release (extract from CHANGELOG.md)
+     6. Commit changes: `git commit -m "chore: update to v{VERSION}"`
+     7. Push branch: `git push origin release/v{VERSION}`
+   - **Deploy**: Follow deployment process for basicmachines.co
+
+**2. docs.basicmemory.com** (`/Users/drew/code/docs.basicmemory.com`)
+   - **Goal**: Add new release notes section to the latest-releases page
+   - **File**: `src/pages/latest-releases.mdx`
+   - **What to do**:
+     1. Pull latest from GitHub: `git pull origin main`
+     2. Create release branch: `git checkout -b release/v{VERSION}`
+     3. Read the existing file to understand the format and structure
+     4. Read `/Users/drew/code/basic-memory/CHANGELOG.md` to get release content
+     5. Add new release section **at the top** (after MDX imports, before other releases)
+     6. Follow the existing pattern:
+        - Heading: `## [v{VERSION}](github-link) — YYYY-MM-DD`
+        - Focus statement if applicable
+        - `<Info>` block with highlights (3-5 key items)
+        - Sections for Features, Bug Fixes, Breaking Changes, etc.
+        - Link to full changelog at the end
+        - Separator `---` between releases
+     7. Commit changes: `git commit -m "docs: add v{VERSION} release notes"`
+     8. Push branch: `git push origin release/v{VERSION}`
+   - **Source content**: Extract and format sections from CHANGELOG.md for this version
+   - **Deploy**: Follow deployment process for docs.basicmemory.com
+
+**4. Announce Release**
+   - Post to Discord community if significant changes
+   - Update social media if major release
+   - Notify users via appropriate channels
+
+## Pre-conditions Check
+Before starting, verify:
+- [ ] All beta testing is complete
+- [ ] Critical bugs are fixed
+- [ ] Breaking changes are documented
+- [ ] CHANGELOG.md is updated (if needed)
+- [ ] Version number follows semantic versioning
+
+## Error Handling
+- If `just release` fails, examine the error output for specific issues
+- If quality checks fail, fix issues and retry
+- If changelog entry missing, update CHANGELOG.md and commit before retrying
+- If GitHub Actions fail, check workflow logs for debugging
+
+## Success Output
+```
+🎉 Stable Release v0.13.2 Created Successfully!
+
+🏷️  Tag: v0.13.2
+📋 GitHub Release: https://github.com/basicmachines-co/basic-memory/releases/tag/v0.13.2
+📦 PyPI: https://pypi.org/project/basic-memory/0.13.2/
+🍺 Homebrew: https://github.com/basicmachines-co/homebrew-basic-memory
+🚀 GitHub Actions: Completed
+
+Install with pip/uv:
+  uv tool install basic-memory
+
+Install with Homebrew:
+  brew install basicmachines-co/basic-memory/basic-memory
+
+Users can now upgrade:
+  uv tool upgrade basic-memory
+  brew upgrade basic-memory
+```
+
+## Context
+- This creates production releases used by end users
+- Must pass all quality gates before proceeding
+- Uses the automated justfile target for consistency
+- Version is automatically updated in `__init__.py`
+- Triggers automated GitHub release with changelog
+- Package is published to PyPI for `pip` and `uv` users
+- Homebrew formula is automatically updated for stable releases
+- Supports multiple installation methods (uv, pip, Homebrew)

.claude/commands/spec.md

@@ -0,0 +1,51 @@
+---
+allowed-tools: mcp__basic-memory__write_note, mcp__basic-memory__read_note, mcp__basic-memory__search_notes, mcp__basic-memory__edit_note
+argument-hint: [create|status|show|review] [spec-name]
+description: Manage specifications in our development process
+---
+
+## Context
+
+Specifications are managed in the Basic Memory "specs" project. All specs live in a centralized location accessible across all repositories via MCP tools.
+
+See SPEC-1 and SPEC-2 in the "specs" project for the full specification-driven development process.
+
+Available commands:
+- `create [name]` - Create new specification
+- `status` - Show all spec statuses
+- `show [spec-name]` - Read a specific spec
+- `review [spec-name]` - Review implementation against spec
+
+## Your task
+
+Execute the spec command: `/spec $ARGUMENTS`
+
+### If command is "create":
+1. Get next SPEC number by searching existing specs in "specs" project
+2. Create new spec using template from SPEC-2
+3. Use mcp__basic-memory__write_note with project="specs"
+4. Include standard sections: Why, What, How, How to Evaluate
+
+### If command is "status":
+1. Use mcp__basic-memory__search_notes with project="specs"
+2. Display table with spec number, title, and progress
+3. Show completion status from checkboxes in content
+
+### If command is "show":
+1. Use mcp__basic-memory__read_note with project="specs"
+2. Display the full spec content
+
+### If command is "review":
+1. Read the specified spec and its "How to Evaluate" section
+2. Review current implementation against success criteria with careful evaluation of:
+   - **Functional completeness** - All specified features working
+   - **Test coverage analysis** - Actual test files and coverage percentage
+     - Count existing test files vs required components/APIs/composables
+     - Verify unit tests, integration tests, and end-to-end tests
+     - Check for missing test categories (component, API, workflow)
+   - **Code quality metrics** - TypeScript compilation, linting, performance
+   - **Architecture compliance** - Component isolation, state management patterns
+   - **Documentation completeness** - Implementation matches specification
+3. Provide honest, accurate assessment - do not overstate completeness
+4. Document findings and update spec with review results using mcp__basic-memory__edit_note
+5. If gaps found, clearly identify what still needs to be implemented/tested

.claude/commands/test-live.md

@@ -0,0 +1,622 @@
+# /project:test-live - Live Basic Memory Testing Suite
+
+Execute comprehensive real-world testing of Basic Memory using the installed version. 
+All test results are recorded as notes in a dedicated test project.
+
+## Usage
+```
+/project:test-live [phase]
+```
+
+**Parameters:**
+- `phase` (optional): Specific test phase to run (`recent`, `core`, `features`, `edge`, `workflows`, `stress`, or `all`)
+- `recent` - Focus on recent changes and new features (recommended for regular testing)
+- `core` - Essential tools only (Tier 1: write_note, read_note, search_notes, edit_note, list_memory_projects, recent_activity)
+- `features` - Core + important workflows (Tier 1 + Tier 2)
+- `all` - Comprehensive testing of all tools and scenarios
+
+## Implementation
+
+You are an expert QA engineer conducting live testing of Basic Memory. 
+When the user runs `/project:test-live`, execute comprehensive test plan:
+
+## Tool Testing Priority
+
+### **Tier 1: Critical Core (Always Test)**
+1. **write_note** - Foundation of all knowledge creation
+2. **read_note** - Primary knowledge retrieval mechanism
+3. **search_notes** - Essential for finding information
+4. **edit_note** - Core content modification capability
+5. **list_memory_projects** - Project discovery and session guidance
+6. **recent_activity** - Project discovery mode and activity analysis
+
+### **Tier 2: Important Workflows (Usually Test)**
+7. **build_context** - Conversation continuity via memory:// URLs
+8. **create_memory_project** - Essential for project setup
+9. **move_note** - Knowledge organization
+10. **sync_status** - Understanding system state
+11. **delete_project** - Project lifecycle management
+
+### **Tier 3: Enhanced Functionality (Sometimes Test)**
+12. **view_note** - Claude Desktop artifact display
+13. **read_content** - Raw content access
+14. **delete_note** - Content removal
+15. **list_directory** - File system exploration
+16. **edit_note** (advanced modes) - Complex find/replace operations
+
+### **Tier 4: Specialized (Rarely Test)**
+17. **canvas** - Obsidian visualization (specialized use case)
+18. **MCP Prompts** - Enhanced UX tools (ai_assistant_guide, continue_conversation)
+
+## Stateless Architecture Testing
+
+### **Project Discovery Workflow (CRITICAL)**
+Test the new stateless project selection flow:
+
+1. **Initial Discovery**
+   - Call `list_memory_projects()` without knowing which project to use
+   - Verify clear session guidance appears: "Next: Ask which project to use"
+   - Confirm removal of CLI-specific references
+
+2. **Activity-Based Discovery**
+   - Call `recent_activity()` without project parameter (discovery mode)
+   - Verify intelligent project suggestions based on activity
+   - Test guidance: "Should I use [most-active-project] for this task?"
+
+3. **Session Tracking Validation**
+   - Verify all tool responses include `[Session: Using project 'name']`
+   - Confirm guidance reminds about session-wide project tracking
+
+4. **Single Project Constraint Mode**
+   - Test MCP server with `--project` parameter
+   - Verify all operations constrained to specified project
+   - Test project override behavior in constrained mode
+
+### **Explicit Project Parameters (CRITICAL)**
+All tools must require explicit project parameters:
+
+1. **Parameter Validation**
+   - Test all Tier 1 tools require `project` parameter
+   - Verify clear error messages for missing project
+   - Test invalid project name handling
+
+2. **No Session State Dependencies**
+   - Confirm no tool relies on "current project" concept
+   - Test rapid project switching within conversation
+   - Verify each call is truly independent
+
+### Pre-Test Setup
+
+1. **Environment Verification**
+   - Verify basic-memory is installed and accessible via MCP
+   - Check version and confirm it's the expected release
+   - Test MCP connection and tool availability
+
+2. **Recent Changes Analysis** (if phase includes 'recent' or 'all')
+   - Run `git log --oneline -20` to examine recent commits
+   - Identify new features, bug fixes, and enhancements
+   - Generate targeted test scenarios for recent changes
+   - Prioritize regression testing for recently fixed issues
+
+3. **Test Project Creation**
+
+Run the bash `date` command to get the current date/time. 
+
+   ```
+   Create project: "basic-memory-testing-[timestamp]"
+   Location: ~/basic-memory-testing-[timestamp]
+   Purpose: Record all test observations and results
+   ```
+
+Make sure to use the newly created project for all subsequent test operations by specifying it in the `project` parameter of each tool call.
+
+4. **Baseline Documentation**
+   Create initial test session note with:
+   - Test environment details
+   - Version being tested
+   - Recent changes identified (if applicable)
+   - Test objectives and scope
+   - Start timestamp
+
+### Phase 0: Recent Changes Validation (if 'recent' or 'all' phase)
+
+Based on recent commit analysis, create targeted test scenarios:
+
+**Recent Changes Test Protocol:**
+1. **Feature Addition Tests** - For each new feature identified:
+   - Test basic functionality
+   - Test integration with existing tools
+   - Verify documentation accuracy
+   - Test edge cases and error handling
+
+2. **Bug Fix Regression Tests** - For each recent fix:
+   - Recreate the original problem scenario
+   - Verify the fix works as expected
+   - Test related functionality isn't broken
+   - Document the verification in test notes
+
+3. **Performance/Enhancement Validation** - For optimizations:
+   - Establish baseline timing
+   - Compare with expected improvements
+   - Test under various load conditions
+   - Document performance observations
+
+**Example Recent Changes (Update based on actual git log):**
+- Watch Service Restart (#156): Test project creation → file modification → automatic restart
+- Cross-Project Moves (#161): Test move_note with cross-project detection
+- Docker Environment Support (#174): Test BASIC_MEMORY_HOME behavior
+- MCP Server Logging (#164): Verify log level configurations
+
+### Phase 1: Core Functionality Validation (Tier 1 Tools)
+
+Test essential MCP tools that form the foundation of Basic Memory:
+
+**1. write_note Tests (Critical):**
+- ✅ Basic note creation with frontmatter
+- ✅ Special characters and Unicode in titles
+- ✅ Various content types (lists, headings, code blocks)
+- ✅ Empty notes and minimal content edge cases
+- ⚠️ Error handling for invalid parameters
+
+**2. read_note Tests (Critical):**
+- ✅ Read by title, permalink, memory:// URLs
+- ✅ Non-existent notes (error handling)
+- ✅ Notes with complex markdown formatting
+- ⚠️ Performance with large notes (>10MB)
+
+**3. search_notes Tests (Critical):**
+- ✅ Simple text queries across content
+- ✅ Tag-based searches with multiple tags
+- ✅ Boolean operators (AND, OR, NOT)
+- ✅ Empty/no results scenarios
+- ⚠️ Performance with 100+ notes
+
+**4. edit_note Tests (Critical):**
+- ✅ Append operations preserving frontmatter
+- ✅ Prepend operations
+- ✅ Find/replace with validation
+- ✅ Section replacement under headers
+- ⚠️ Error scenarios (invalid operations)
+
+**5. list_memory_projects Tests (Critical):**
+- ✅ Display all projects with clear session guidance
+- ✅ Project discovery workflow prompts
+- ✅ Removal of CLI-specific references
+- ✅ Empty project list handling
+- ✅ Single project constraint mode display
+
+**6. recent_activity Tests (Critical - Discovery Mode):**
+- ✅ Discovery mode without project parameter
+- ✅ Intelligent project suggestions based on activity
+- ✅ Guidance prompts for project selection
+- ✅ Session tracking reminders in responses
+- ⚠️ Performance with multiple projects
+
+### Phase 2: Important Workflows (Tier 2 Tools)
+
+**7. build_context Tests (Important):**
+- ✅ Different depth levels (1, 2, 3+)
+- ✅ Various timeframes for context
+- ✅ memory:// URL navigation
+- ⚠️ Performance with complex relation graphs
+
+**8. create_memory_project Tests (Important):**
+- ✅ Create projects dynamically
+- ✅ Set default during creation
+- ✅ Path validation and creation
+- ⚠️ Invalid paths and names
+- ✅ Integration with existing projects
+
+**9. move_note Tests (Important):**
+- ✅ Move within same project
+- ✅ Cross-project moves with detection (#161)
+- ✅ Automatic folder creation
+- ✅ Database consistency validation
+- ⚠️ Special characters in paths
+
+**10. sync_status Tests (Important):**
+- ✅ Background operation monitoring
+- ✅ File synchronization status
+- ✅ Project sync state reporting
+- ⚠️ Error state handling
+
+### Phase 3: Enhanced Functionality (Tier 3 Tools)
+
+**11. view_note Tests (Enhanced):**
+- ✅ Claude Desktop artifact display
+- ✅ Title extraction from frontmatter
+- ✅ Unicode and emoji content rendering
+- ⚠️ Error handling for non-existent notes
+
+**12. read_content Tests (Enhanced):**
+- ✅ Raw file content access
+- ✅ Binary file handling
+- ✅ Image file reading
+- ⚠️ Large file performance
+
+**13. delete_note Tests (Enhanced):**
+- ✅ Single note deletion
+- ✅ Database consistency after deletion
+- ⚠️ Non-existent note handling
+- ✅ Confirmation of successful deletion
+
+**14. list_directory Tests (Enhanced):**
+- ✅ Directory content listing
+- ✅ Depth control and filtering
+- ✅ File name globbing
+- ⚠️ Empty directory handling
+
+**15. delete_project Tests (Enhanced):**
+- ✅ Project removal from config
+- ✅ Database cleanup
+- ⚠️ Default project protection
+- ⚠️ Non-existent project handling
+
+### Phase 4: Edge Case Exploration
+
+**Boundary Testing:**
+- Very long titles and content (stress limits)
+- Empty projects and notes
+- Unicode, emojis, special symbols
+- Deeply nested folder structures
+- Circular relations and self-references
+- Maximum relation depths
+
+**Error Scenarios:**
+- Invalid memory:// URLs
+- Missing files referenced in database
+- Invalid project names and paths
+- Malformed note structures
+- Concurrent operation conflicts
+
+**Performance Testing:**
+- Create 100+ notes rapidly
+- Complex search queries
+- Deep relation chains (5+ levels)
+- Rapid successive operations
+- Memory usage monitoring
+
+### Phase 5: Real-World Workflow Scenarios
+
+**Meeting Notes Pipeline:**
+1. Create meeting notes with action items
+2. Extract action items using edit_note
+3. Build relations to project documents
+4. Update progress incrementally
+5. Search and track completion
+
+**Research Knowledge Building:**
+1. Create research topic hierarchy
+2. Build complex relation networks
+3. Add incremental findings over time
+4. Search for connections and patterns
+5. Reorganize as knowledge evolves
+
+**Multi-Project Workflow:**
+1. Technical documentation project
+2. Personal recipe collection project
+3. Learning/course notes project
+4. Specify different projects for different operations
+5. Cross-reference related concepts
+
+**Content Evolution:**
+1. Start with basic notes
+2. Enhance with relations and observations
+3. Reorganize file structure using moves
+4. Update content with edit operations
+5. Validate knowledge graph integrity
+
+### Phase 6: Specialized Tools Testing (Tier 4)
+
+**16. canvas Tests (Specialized):**
+- ✅ JSON Canvas generation
+- ✅ Node and edge creation
+- ✅ Obsidian compatibility
+- ⚠️ Complex graph handling
+
+**17. MCP Prompts Tests (Specialized):**
+- ✅ ai_assistant_guide output
+- ✅ continue_conversation functionality
+- ✅ Formatted search results
+- ✅ Enhanced activity reports
+
+### Phase 7: Integration & File Watching Tests
+
+**File System Integration:**
+- ✅ Watch service behavior with file changes
+- ✅ Project creation → watch restart (#156)
+- ✅ Multi-project synchronization
+- ⚠️ MCP→API→DB→File stack validation
+
+**Real Integration Testing:**
+- ✅ End-to-end file watching vs manual operations
+- ✅ Cross-session persistence
+- ✅ Database consistency across operations
+- ⚠️ Performance under real file system changes
+
+### Phase 8: Creative Stress Testing
+
+**Creative Exploration:**
+- Rapid project creation/switching patterns
+- Unusual but valid markdown structures
+- Creative observation categories
+- Novel relation types and patterns
+- Unexpected tool combinations
+
+**Stress Scenarios:**
+- Bulk operations (many notes quickly)
+- Complex nested moves and edits
+- Deep context building
+- Complex boolean search expressions
+- Resource constraint testing
+
+## Test Execution Guidelines
+
+### Quick Testing (core/features phases)
+- Focus on Tier 1 tools (core) or Tier 1+2 (features)
+- Test essential functionality and common edge cases
+- Record critical issues immediately
+- Complete in 15-20 minutes
+
+### Comprehensive Testing (all phase)
+- Cover all tiers systematically
+- Include specialized tools and stress testing
+- Document performance baselines
+- Complete in 45-60 minutes
+
+### Recent Changes Focus (recent phase)
+- Analyze git log for recent commits
+- Generate targeted test scenarios
+- Focus on regression testing for fixes
+- Validate new features thoroughly
+
+## Test Observation Format
+
+Record ALL observations immediately as Basic Memory notes:
+
+```markdown
+---
+title: Test Session [Phase] YYYY-MM-DD HH:MM
+tags: [testing, v0.13.0, live-testing, [phase]]
+permalink: test-session-[phase]-[timestamp]
+---
+
+# Test Session [Phase] - [Date/Time]
+
+## Environment
+- Basic Memory version: [version]
+- MCP connection: [status]
+- Test project: [name]
+- Phase focus: [description]
+
+## Test Results
+
+### ✅ Successful Operations
+- [timestamp] ✅ write_note: Created note with emoji title 📝 #tier1 #functionality
+- [timestamp] ✅ search_notes: Boolean query returned 23 results in 0.4s #tier1 #performance  
+- [timestamp] ✅ edit_note: Append operation preserved frontmatter #tier1 #reliability
+
+### ⚠️ Issues Discovered
+- [timestamp] ⚠️ move_note: Slow with deep folder paths (2.1s) #tier2 #performance
+- [timestamp] 🚨 search_notes: Unicode query returned unexpected results #tier1 #bug #critical
+- [timestamp] ⚠️ build_context: Context lost for memory:// URLs #tier2 #issue
+
+### 🚀 Enhancements Identified
+- edit_note could benefit from preview mode #ux-improvement
+- search_notes needs fuzzy matching for typos #feature-idea
+- move_note could auto-suggest folder creation #usability
+
+### 📊 Performance Metrics
+- Average write_note time: 0.3s
+- Search with 100+ notes: 0.6s
+- Project parameter overhead: <0.1s
+- Memory usage: [observed levels]
+
+## Relations
+- tests [[Basic Memory v0.13.0]]
+- part_of [[Live Testing Suite]]
+- found_issues [[Bug Report: Unicode Search]]
+- discovered [[Performance Optimization Opportunities]]
+```
+
+## Quality Assessment Areas
+
+**User Experience & Usability:**
+- Tool instruction clarity and examples
+- Error message actionability
+- Response time acceptability
+- Tool consistency and discoverability
+- Learning curve and intuitiveness
+
+**System Behavior:**
+- Stateless operation independence
+- memory:// URL navigation reliability
+- Multi-step workflow cohesion
+- Edge case graceful handling
+- Recovery from user errors
+
+**Documentation Alignment:**
+- Tool output clarity and helpfulness
+- Behavior vs. documentation accuracy
+- Example validity and usefulness
+- Real-world vs. documented workflows
+
+**Mental Model Validation:**
+- Natural user expectation alignment
+- Surprising behavior identification
+- Mistake recovery ease
+- Knowledge graph concept naturalness
+
+**Performance & Reliability:**
+- Operation completion times
+- Consistency across sessions
+- Scaling behavior with growth
+- Unexpected slowness identification
+
+## Error Documentation Protocol
+
+For each error discovered:
+
+1. **Immediate Recording**
+   - Create dedicated error note
+   - Include exact reproduction steps
+   - Capture error messages verbatim
+   - Note system state when error occurred
+
+2. **Error Note Format**
+   ```markdown
+   ---
+   title: Bug Report - [Short Description]
+   tags: [bug, testing, v0.13.0, [severity]]
+   ---
+   
+   # Bug Report: [Description]
+   
+   ## Reproduction Steps
+   1. [Exact steps to reproduce]
+   2. [Include all parameters used]
+   3. [Note any special conditions]
+   
+   ## Expected Behavior
+   [What should have happened]
+   
+   ## Actual Behavior  
+   [What actually happened]
+   
+   ## Error Messages
+   ```
+   [Exact error text]
+   ```
+   
+   ## Environment
+   - Version: [version]
+   - Project: [name]
+   - Timestamp: [when]
+   
+   ## Severity
+   - [ ] Critical (blocks major functionality)
+   - [ ] High (impacts user experience)
+   - [ ] Medium (workaround available)
+   - [ ] Low (minor inconvenience)
+   
+   ## Relations
+   - discovered_during [[Test Session [Phase]]]
+   - affects [[Feature Name]]
+   ```
+
+## Success Metrics Tracking
+
+**Quantitative Measures:**
+- Test scenario completion rate
+- Bug discovery count with severity
+- Performance benchmark establishment
+- Tool coverage completeness
+
+**Qualitative Measures:**
+- Conversation flow naturalness
+- Knowledge graph quality
+- User experience insights
+- System reliability assessment
+
+## Test Execution Flow
+
+1. **Setup Phase** (5 minutes)
+   - Verify environment and create test project
+   - Record baseline system state
+   - Establish performance benchmarks
+
+2. **Core Testing** (15-20 minutes per phase)
+   - Execute test scenarios systematically
+   - Record observations immediately
+   - Note timestamps for performance tracking
+   - Explore variations when interesting behaviors occur
+
+3. **Documentation** (5 minutes per phase)
+   - Create phase summary note
+   - Link related test observations
+   - Update running issues list
+   - Record enhancement ideas
+
+4. **Analysis Phase** (10 minutes)
+   - Review all observations across phases
+   - Identify patterns and trends
+   - Create comprehensive summary report
+   - Generate development recommendations
+
+## Testing Success Criteria
+
+### Core Testing (Tier 1) - Must Pass
+- All 6 critical tools function correctly
+- No critical bugs in essential workflows
+- Acceptable performance for basic operations
+- Error handling works as expected
+
+### Feature Testing (Tier 1+2) - Should Pass
+- All 11 core + important tools function
+- Workflow scenarios complete successfully
+- Performance meets baseline expectations
+- Integration points work correctly
+
+### Comprehensive Testing (All Tiers) - Complete Coverage
+- All tools tested across all scenarios
+- Edge cases and stress testing completed
+- Performance baselines established
+- Full documentation of issues and enhancements
+
+## Expected Outcomes
+
+**System Validation:**
+- Feature verification prioritized by tier importance
+- Recent changes validated for regression
+- Performance baseline establishment
+- Bug identification with severity assessment
+
+**Knowledge Base Creation:**
+- Prioritized testing documentation
+- Real usage examples for user guides
+- Recent changes validation records
+- Performance insights for optimization
+
+**Development Insights:**
+- Tier-based bug priority list
+- Recent changes impact assessment
+- Enhancement ideas from real usage
+- User experience improvement areas
+
+## Post-Test Deliverables
+
+1. **Test Summary Note**
+   - Overall results and findings
+   - Critical issues requiring immediate attention
+   - Enhancement opportunities discovered
+   - System readiness assessment
+
+2. **Bug Report Collection**
+   - All discovered issues with reproduction steps
+   - Severity and impact assessments
+   - Suggested fixes where applicable
+
+3. **Performance Baseline**
+   - Timing data for all operations
+   - Scaling behavior observations
+   - Resource usage patterns
+
+4. **UX Improvement Recommendations**
+   - Usability enhancement suggestions
+   - Documentation improvement areas
+   - Tool design optimization ideas
+
+5. **Updated TESTING.md**
+   - Incorporate new test scenarios discovered
+   - Update based on real execution experience
+   - Add performance benchmarks and targets
+
+## Context
+- Uses real installed basic-memory version 
+- Tests complete MCP→API→DB→File stack
+- Creates living documentation in Basic Memory itself
+- Follows integration over isolation philosophy
+- Prioritizes testing by tool importance and usage frequency
+- Adapts to recent development changes dynamically
+- Focuses on real usage patterns over checklist validation
+- Generates actionable insights prioritized by impact

.dockerignore

@@ -0,0 +1,60 @@
+# Git files
+.git/
+.gitignore
+.gitattributes
+
+# Development files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing files
+tests/
+test-int/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+
+# Virtual environments (uv creates these during build)
+.venv/
+venv/
+.env
+
+# CI/CD files
+.github/
+
+# Documentation (keep README.md and pyproject.toml)
+docs/
+CHANGELOG.md
+CLAUDE.md
+CONTRIBUTING.md
+
+# Example files not needed for runtime
+examples/
+
+# Local development files
+.basic-memory/
+*.db
+*.sqlite3
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+*.log

.env.example

@@ -0,0 +1,28 @@
+# Basic Memory Environment Variables Example
+# Copy this file to .env and customize as needed
+# Note: .env files are gitignored and should never be committed
+
+# ============================================================================
+# PostgreSQL Test Database Configuration
+# ============================================================================
+# These variables allow you to override the default test database credentials
+# Default values match docker-compose-postgres.yml for local development
+#
+# Only needed if you want to use different credentials or a remote test database
+# By default, tests use: postgresql://basic_memory_user:dev_password@localhost:5433/basic_memory_test
+
+# Full PostgreSQL test database URL (used by tests and migrations)
+# POSTGRES_TEST_URL=postgresql+asyncpg://basic_memory_user:dev_password@localhost:5433/basic_memory_test
+
+# Individual components (used by justfile postgres-reset command)
+# POSTGRES_USER=basic_memory_user
+# POSTGRES_TEST_DB=basic_memory_test
+
+# ============================================================================
+# Production Database Configuration
+# ============================================================================
+# For production use, set these in your deployment environment
+# DO NOT use the test credentials above in production!
+
+# BASIC_MEMORY_DATABASE_BACKEND=postgres  # or "sqlite"
+# BASIC_MEMORY_DATABASE_URL=postgresql+asyncpg://user:password@host:port/database

.github/dependabot.yml

@@ -0,0 +1,12 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+      

.github/workflows/claude-code-review.yml

@@ -0,0 +1,82 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Only run for organization members and collaborators
+    if: |
+      github.event.pull_request.author_association == 'OWNER' ||
+      github.event.pull_request.author_association == 'MEMBER' ||
+      github.event.pull_request.author_association == 'COLLABORATOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          track_progress: true  # Enable visual progress tracking
+          allowed_bots: '*'
+          prompt: |
+            Review this Basic Memory PR against our team checklist:
+
+            ## Code Quality & Standards
+            - [ ] Follows Basic Memory's coding conventions in CLAUDE.md
+            - [ ] Python 3.12+ type annotations and async patterns
+            - [ ] SQLAlchemy 2.0 best practices
+            - [ ] FastAPI and Typer conventions followed
+            - [ ] 100-character line length limit maintained
+            - [ ] No commented-out code blocks
+
+            ## Testing & Documentation
+            - [ ] Unit tests for new functions/methods
+            - [ ] Integration tests for new MCP tools
+            - [ ] Test coverage for edge cases
+            - [ ] Documentation updated (README, docstrings)
+            - [ ] CLAUDE.md updated if conventions change
+
+            ## Basic Memory Architecture
+            - [ ] MCP tools follow atomic, composable design
+            - [ ] Database changes include Alembic migrations
+            - [ ] Preserves local-first architecture principles
+            - [ ] Knowledge graph operations maintain consistency
+            - [ ] Markdown file handling preserves integrity
+            - [ ] AI-human collaboration patterns followed
+
+            ## Security & Performance
+            - [ ] No hardcoded secrets or credentials
+            - [ ] Input validation for MCP tools
+            - [ ] Proper error handling and logging
+            - [ ] Performance considerations addressed
+            - [ ] No sensitive data in logs or commits
+            
+            ## Compatability
+            - [ ] File path comparisons must be windows compatible
+            - [ ] Avoid using emojis and unicode characters in console and log output
+
+            Read the CLAUDE.md file for detailed project context. For each checklist item, verify if it's satisfied and comment on any that need attention. Use inline comments for specific code issues and post a summary with checklist results.
+
+          # Allow broader tool access for thorough code review
+          claude_args: '--allowed-tools "Bash(gh pr:*),Bash(gh issue:*),Bash(gh api:*),Bash(git log:*),Bash(git show:*),Read,Grep,Glob"'

.github/workflows/claude-issue-triage.yml

@@ -0,0 +1,71 @@
+name: Claude Issue Triage
+
+on:
+  issues:
+    types: [opened]
+
+jobs:
+  triage:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      id-token: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Issue Triage
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          track_progress: true  # Show triage progress
+          prompt: |
+            Analyze this new Basic Memory issue and perform triage:
+
+            **Issue Analysis:**
+            1. **Type Classification:**
+               - Bug report (code defect)
+               - Feature request (new functionality)
+               - Enhancement (improvement to existing feature)
+               - Documentation (docs improvement)
+               - Question/Support (user help)
+               - MCP tool issue (specific to MCP functionality)
+
+            2. **Priority Assessment:**
+               - Critical: Security issues, data loss, complete breakage
+               - High: Major functionality broken, affects many users
+               - Medium: Minor bugs, usability issues
+               - Low: Nice-to-have improvements, cosmetic issues
+
+            3. **Component Classification:**
+               - CLI commands
+               - MCP tools
+               - Database/sync
+               - Cloud functionality
+               - Documentation
+               - Testing
+
+            4. **Complexity Estimate:**
+               - Simple: Quick fix, documentation update
+               - Medium: Requires some investigation/testing
+               - Complex: Major feature work, architectural changes
+
+            **Actions to Take:**
+            1. Add appropriate labels using: `gh issue edit ${{ github.event.issue.number }} --add-label "label1,label2"`
+            2. Check for duplicates using: `gh search issues`
+            3. If duplicate found, comment mentioning the original issue
+            4. For feature requests, ask clarifying questions if needed
+            5. For bugs, request reproduction steps if missing
+
+            **Available Labels:**
+            - Type: bug, enhancement, feature, documentation, question, mcp-tool
+            - Priority: critical, high, medium, low
+            - Component: cli, mcp, database, cloud, docs, testing
+            - Complexity: simple, medium, complex
+            - Status: needs-reproduction, needs-clarification, duplicate
+
+            Read the issue carefully and provide helpful triage with appropriate labels.
+
+          claude_args: '--allowed-tools "Bash(gh issue:*),Bash(gh search:*),Read"'

.github/workflows/claude.yml

@@ -0,0 +1,68 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+  pull_request_target:
+    types: [opened, synchronize]
+
+jobs:
+  claude:
+    if: |
+      (
+        (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+        (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+        (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+        (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude'))) ||
+        (github.event_name == 'pull_request_target' && contains(github.event.pull_request.body, '@claude'))
+      ) && (
+        github.event.comment.author_association == 'OWNER' ||
+        github.event.comment.author_association == 'MEMBER' ||
+        github.event.comment.author_association == 'COLLABORATOR' ||
+        github.event.sender.author_association == 'OWNER' ||
+        github.event.sender.author_association == 'MEMBER' ||
+        github.event.sender.author_association == 'COLLABORATOR' ||
+        github.event.pull_request.author_association == 'OWNER' ||
+        github.event.pull_request.author_association == 'MEMBER' ||
+        github.event.pull_request.author_association == 'COLLABORATOR'
+      )
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          # For pull_request_target, checkout the PR head to review the actual changes
+          ref: ${{ github.event_name == 'pull_request_target' && github.event.pull_request.head.sha || github.sha }}
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          track_progress: true  # Enable visual progress tracking
+          
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.claude.com/en/docs/claude-code/sdk#command-line for available options
+          # claude_args: '--model claude-opus-4-1-20250805 --allowed-tools Bash(gh pr:*)'
+

.github/workflows/dev-release.yml

@@ -0,0 +1,53 @@
+name: Dev Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:  # Allow manual triggering
+
+jobs:
+  dev-release:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: |
+          pip install uv
+
+      - name: Install dependencies and build
+        run: |
+          uv venv
+          uv sync
+          uv build
+
+      - name: Check if this is a dev version
+        id: check_version
+        run: |
+          VERSION=$(uv run python -c "import basic_memory; print(basic_memory.__version__)")
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          if [[ "$VERSION" == *"dev"* ]]; then
+            echo "is_dev=true" >> $GITHUB_OUTPUT
+            echo "Dev version detected: $VERSION"
+          else
+            echo "is_dev=false" >> $GITHUB_OUTPUT
+            echo "Release version detected: $VERSION, skipping dev release"
+          fi
+
+      - name: Publish dev version to PyPI
+        if: steps.check_version.outputs.is_dev == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}
+          skip-existing: true  # Don't fail if version already exists

.github/workflows/docker.yml

@@ -0,0 +1,61 @@
+name: Docker Image CI
+
+on:
+  push:
+    tags:
+      - 'v*'  # Trigger on version tags like v1.0.0, v0.13.0, etc.
+  workflow_dispatch:  # Allow manual triggering for testing
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: basicmachines-co/basic-memory
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          platforms: linux/amd64,linux/arm64
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+

.github/workflows/release.yml

@@ -1,96 +1,85 @@
 name: Release
 
 on:
-  workflow_dispatch:
-    inputs:
-      version_type:
-        description: 'Type of version bump (major, minor, patch)'
-        required: true
-        default: 'patch'
-        type: choice
-        options:
-          - patch
-          - minor
-          - major
+  push:
+    tags:
+      - 'v*'  # Trigger on version tags like v1.0.0, v0.13.0, etc.
 
 jobs:
   release:
     runs-on: ubuntu-latest
-    concurrency: release
     permissions:
       id-token: write
       contents: write
-    outputs:
-      released: ${{ steps.release.outputs.released }}
-      tag: ${{ steps.release.outputs.tag }}
 
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
-      - name: Python Semantic Release
-        id: release
-        uses: python-semantic-release/python-semantic-release@master
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
-        if: steps.release.outputs.released == 'true'
-        with:
-          password: ${{ secrets.PYPI_TOKEN }}
-
-      - name: Publish to GitHub Release Assets
-        uses: python-semantic-release/publish-action@v9.8.9
-        if: steps.release.outputs.released == 'true'
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          tag: ${{ steps.release.outputs.tag }}
-
-  build-macos:
-    needs: release
-    if: needs.release.outputs.released == 'true'
-    runs-on: macos-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          ref: ${{ needs.release.outputs.tag }}
-
-      - name: Set up Python "3.12"
-        uses: actions/setup-python@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
         with:
           python-version: "3.12"
-          cache: 'pip'
-
-      - name: Install librsvg
-        run: brew install librsvg
 
       - name: Install uv
         run: |
           pip install uv
 
-      - name: Create virtual env
+      - name: Install dependencies and build
         run: |
           uv venv
-
-      - name: Install dependencies
-        run: |
           uv sync
+          uv build
 
-      - name: Build macOS installer
+      - name: Verify build succeeded
         run: |
-          make installer-mac
-          xattr -dr com.apple.quarantine "installer/build/Basic Memory Installer.app"
+          # Verify that build artifacts exist
+          ls -la dist/
+          echo "Build completed successfully"
 
-      - name: Zip macOS installer
-        run: |
-          cd installer/build
-          zip -ry "Basic-Memory-Installer-${{ needs.release.outputs.tag }}.zip" "Basic Memory Installer.app"
-
-      - name: Upload macOS installer
-        uses: softprops/action-gh-release@v1
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
         with:
-          files: installer/build/Basic-Memory-Installer-${{ needs.release.outputs.tag }}.zip
-          tag_name: ${{ needs.release.outputs.tag }}
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+          generate_release_notes: true
+          tag_name: ${{ github.ref_name }}
           token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_TOKEN }}
+
+  homebrew:
+    name: Update Homebrew Formula
+    needs: release
+    runs-on: ubuntu-latest
+    # Only run for stable releases (not dev, beta, or rc versions)
+    if: ${{ !contains(github.ref_name, 'dev') && !contains(github.ref_name, 'b') && !contains(github.ref_name, 'rc') }}
+    permissions:
+      contents: write
+      actions: read
+    steps:
+      - name: Update Homebrew formula
+        uses: mislav/bump-homebrew-formula-action@v3
+        with:
+          # Formula name in homebrew-basic-memory repo
+          formula-name: basic-memory
+          # The tap repository
+          homebrew-tap: basicmachines-co/homebrew-basic-memory
+          # Base branch of the tap repository
+          base-branch: main
+          # Download URL will be automatically constructed from the tag
+          download-url: https://github.com/basicmachines-co/basic-memory/archive/refs/tags/${{ github.ref_name }}.tar.gz
+          # Commit message for the formula update
+          commit-message: |
+            {{formulaName}} {{version}}
+
+            Created by https://github.com/basicmachines-co/basic-memory/actions/runs/${{ github.run_id }}
+        env:
+          # Personal Access Token with repo scope for homebrew-basic-memory repo
+          COMMITTER_TOKEN: ${{ secrets.HOMEBREW_TOKEN }}
+

.github/workflows/test.yml

@@ -5,14 +5,22 @@ on:
     branches: [ "main" ]
   pull_request:
     branches: [ "main" ]
+  # pull_request_target runs on the BASE of the PR, not the merge result.
+  # It has write permissions and access to secrets.
+  # It's useful for PRs from forks or automated PRs but requires careful use for security reasons.
+  # See: https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target
+  pull_request_target:
+    branches: [ "main" ]
 
 jobs:
-  test:
-    runs-on: ubuntu-latest
+  test-sqlite:
+    name: Test SQLite (${{ matrix.os }}, Python ${{ matrix.python-version }})
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ "3.12" ]
+        os: [ubuntu-latest, windows-latest]
+        python-version: [ "3.12", "3.13" ]
+    runs-on: ${{ matrix.os }}
 
     steps:
       - uses: actions/checkout@v4
@@ -29,6 +37,18 @@ jobs:
         run: |
           pip install uv
 
+      - name: Install just (Linux/macOS)
+        if: runner.os != 'Windows'
+        run: |
+          curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
+
+      - name: Install just (Windows)
+        if: runner.os == 'Windows'
+        run: |
+          # Install just using Chocolatey (pre-installed on GitHub Actions Windows runners)
+          choco install just --yes
+        shell: pwsh
+
       - name: Create virtual env
         run: |
           uv venv
@@ -39,9 +59,69 @@ jobs:
 
       - name: Run type checks
         run: |
-          uv run make type-check
+          just typecheck
 
-      - name: Run tests
+      - name: Run linting
+        run: |
+          just lint
+
+      - name: Run tests (SQLite)
         run: |
           uv pip install pytest pytest-cov
-          uv run make test
+          just test-sqlite
+
+  test-postgres:
+    name: Test Postgres (Python ${{ matrix.python-version }})
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ "3.12", "3.13" ]
+    runs-on: ubuntu-latest
+
+    # Postgres service (only available on Linux runners)
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_DB: basic_memory_test
+          POSTGRES_USER: basic_memory_user
+          POSTGRES_PASSWORD: dev_password
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5433:5432
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+
+      - name: Install uv
+        run: |
+          pip install uv
+
+      - name: Install just
+        run: |
+          curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
+
+      - name: Create virtual env
+        run: |
+          uv venv
+
+      - name: Install dependencies
+        run: |
+          uv pip install -e .[dev]
+
+      - name: Run tests (Postgres)
+        run: |
+          uv pip install pytest pytest-cov
+          just test-postgres

.gitignore

@@ -42,4 +42,15 @@ ENV/
 
 # macOS
 .DS_Store
-/.coverage.*
+.coverage.*
+
+# obsidian docs:
+/docs/.obsidian/
+/examples/.obsidian/
+/examples/.basic-memory/
+
+
+# claude action
+claude-output
+**/.claude/settings.local.json
+.mcp.json

CLA.md

@@ -1,34 +1,71 @@
-Developer Certificate of Origin
-Version 1.1
-https://developercertificate.org/
+# Contributor License Agreement
 
-Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+## Copyright Assignment and License Grant
 
-Everyone is permitted to copy and distribute verbatim copies of this
-license document, but changing it is not allowed.
+By signing this Contributor License Agreement ("Agreement"), you accept and agree to the following terms and conditions
+for your present and future Contributions submitted
+to Basic Machines LLC. Except for the license granted herein to Basic Machines LLC and recipients of software
+distributed by Basic Machines LLC, you reserve all right,
+title, and interest in and to your Contributions.
 
-Developer's Certificate of Origin 1.1
+### 1. Definitions
 
-By making a contribution to this project, I certify that:
+"You" (or "Your") shall mean the copyright owner or legal entity authorized by the copyright owner that is making this
+Agreement with Basic Machines LLC.
 
-(a) The contribution was created in whole or in part by me and I
-have the right to submit it under the open source license
-indicated in the file; or
+"Contribution" shall mean any original work of authorship, including any modifications or additions to an existing work,
+that is intentionally submitted by You to Basic
+Machines LLC for inclusion in, or documentation of, any of the products owned or managed by Basic Machines LLC (the "
+Work").
 
-(b) The contribution is based upon previous work that, to the best
-of my knowledge, is covered under an appropriate open source
-license and I have the right under that license to submit that
-work with modifications, whether created in whole or in part
-by me, under the same open source license (unless I am
-permitted to submit under a different license), as indicated
-in the file; or
+### 2. Grant of Copyright License
 
-(c) The contribution was provided directly to me by some other
-person who certified (a), (b) or (c) and I have not modified
-it.
+Subject to the terms and conditions of this Agreement, You hereby grant to Basic Machines LLC and to recipients of
+software distributed by Basic Machines LLC a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the
+Work, and to permit persons to whom the Work is furnished to do so.
 
-(d) I understand and agree that this project and the contribution
-are public and that a record of the contribution (including all
-personal information I submit with it, including my sign-off) is
-maintained indefinitely and may be redistributed consistent with
-this project or the open source license(s) involved.
+### 3. Assignment of Copyright
+
+You hereby assign to Basic Machines LLC all right, title, and interest worldwide in all Copyright covering your
+Contributions. Basic Machines LLC may license the
+Contributions under any license terms, including copyleft, permissive, commercial, or proprietary licenses.
+
+### 4. Grant of Patent License
+
+Subject to the terms and conditions of this Agreement, You hereby grant to Basic Machines LLC and to recipients of
+software distributed by Basic Machines LLC a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to
+make, have made, use, offer to sell, sell, import, and
+otherwise transfer the Work.
+
+### 5. Developer Certificate of Origin
+
+By making a Contribution to this project, You certify that:
+
+(a) The Contribution was created in whole or in part by You and You have the right to submit it under this Agreement; or
+
+(b) The Contribution is based upon previous work that, to the best of Your knowledge, is covered under an appropriate
+open source license and You have the right under that
+license to submit that work with modifications, whether created in whole or in part by You, under this Agreement; or
+
+(c) The Contribution was provided directly to You by some other person who certified (a), (b) or (c) and You have not
+modified it.
+
+(d) You understand and agree that this project and the Contribution are public and that a record of the Contribution (
+including all personal information You submit with
+it, including Your sign-off) is maintained indefinitely and may be redistributed consistent with this project or the
+open source license(s) involved.
+
+### 6. Representations
+
+You represent that you are legally entitled to grant the above license and assignment. If your employer(s) has rights to
+intellectual property that you create that
+includes your Contributions, you represent that you have received permission to make Contributions on behalf of that
+employer, or that your employer has waived such rights
+for your Contributions to Basic Machines LLC.
+
+---
+
+This Agreement is effective as of the date you first submit a Contribution to Basic Machines LLC.

CLAUDE.md

@@ -14,20 +14,34 @@ See the [README.md](README.md) file for a project overview.
 
 ### Build and Test Commands
 
-- Install: `make install` or `pip install -e ".[dev]"`
-- Run tests: `uv run pytest -p pytest_mock -v` or `make test`
+- Install: `just install` or `pip install -e ".[dev]"`
+- Run all tests (with coverage): `just test` - Runs both unit and integration tests with unified coverage
+- Run unit tests only: `just test-unit` - Fast, no coverage
+- Run integration tests only: `just test-int` - Fast, no coverage
+- Generate HTML coverage: `just coverage` - Opens in browser
 - Single test: `pytest tests/path/to/test_file.py::test_function_name`
-- Lint: `make lint` or `ruff check . --fix`
-- Type check: `make type-check` or `uv run pyright`
-- Format: `make format` or `uv run ruff format .`
-- Run all code checks: `make check` (runs lint, format, type-check, test)
-- Create db migration: `make migration m="Your migration message"`
-- Run development MCP Inspector: `make run-inspector`
+- Run benchmarks: `pytest test-int/test_sync_performance_benchmark.py -v -m "benchmark and not slow"`
+- Lint: `just lint` or `ruff check . --fix`
+- Type check: `just typecheck` or `uv run pyright`
+- Format: `just format` or `uv run ruff format .`
+- Run all code checks: `just check` (runs lint, format, typecheck, test)
+- Create db migration: `just migration "Your migration message"`
+- Run development MCP Inspector: `just run-inspector`
+
+**Note:** Project requires Python 3.12+ (uses type parameter syntax and `type` aliases introduced in 3.12)
+
+### Test Structure
+
+- `tests/` - Unit tests for individual components (mocked, fast)
+- `test-int/` - Integration tests for real-world scenarios (no mocks, realistic)
+- Both directories are covered by unified coverage reporting
+- Benchmark tests in `test-int/` are marked with `@pytest.mark.benchmark`
+- Slow tests are marked with `@pytest.mark.slow`
 
 ### Code Style Guidelines
 
 - Line length: 100 characters max
-- Python 3.12+ with full type annotations
+- Python 3.12+ with full type annotations (uses type parameters and type aliases)
 - Format with ruff (consistent styling)
 - Import order: standard lib, third-party, local imports
 - Naming: snake_case for functions/variables, PascalCase for classes
@@ -61,9 +75,46 @@ See the [README.md](README.md) file for a project overview.
 - Schema changes require Alembic migrations
 - SQLite is used for indexing and full text search, files are source of truth
 - Testing uses pytest with asyncio support (strict mode)
+- Unit tests (`tests/`) use mocks when necessary; integration tests (`test-int/`) use real implementations
 - Test database uses in-memory SQLite
-- Avoid creating mocks in tests in most circumstances.
-- Each test runs in a standalone enviroment with in memory SQLite and tmp_file directory
+- Each test runs in a standalone environment with in-memory SQLite and tmp_file directory
+- Performance benchmarks are in `test-int/test_sync_performance_benchmark.py`
+- Use pytest markers: `@pytest.mark.benchmark` for benchmarks, `@pytest.mark.slow` for slow tests
+
+### Async Client Pattern (Important!)
+
+**All MCP tools and CLI commands use the context manager pattern for HTTP clients:**
+
+```python
+from basic_memory.mcp.async_client import get_client
+
+async def my_mcp_tool():
+    async with get_client() as client:
+        # Use client for API calls
+        response = await call_get(client, "/path")
+        return response
+```
+
+**Do NOT use:**
+- ❌ `from basic_memory.mcp.async_client import client` (deprecated module-level client)
+- ❌ Manual auth header management
+- ❌ `inject_auth_header()` (deleted)
+
+**Key principles:**
+- Auth happens at client creation, not per-request
+- Proper resource management via context managers
+- Supports three modes: Local (ASGI), CLI cloud (HTTP + auth), Cloud app (factory injection)
+- Factory pattern enables dependency injection for cloud consolidation
+
+**For cloud app integration:**
+```python
+from basic_memory.mcp import async_client
+
+# Set custom factory before importing tools
+async_client.set_client_factory(your_custom_factory)
+```
+
+See SPEC-16 for full context manager refactor details.
 
 ## BASIC MEMORY PRODUCT USAGE
 
@@ -80,6 +131,7 @@ See the [README.md](README.md) file for a project overview.
 
 ### Basic Memory Commands
 
+**Local Commands:**
 - Sync knowledge: `basic-memory sync` or `basic-memory sync --watch`
 - Import from Claude: `basic-memory import claude conversations`
 - Import from ChatGPT: `basic-memory import chatgpt`
@@ -89,24 +141,41 @@ See the [README.md](README.md) file for a project overview.
     - Guide: `basic-memory tools basic-memory-guide`
     - Continue: `basic-memory tools continue-conversation --topic="search"`
 
+**Cloud Commands (requires subscription):**
+- Authenticate: `basic-memory cloud login`
+- Logout: `basic-memory cloud logout`
+- Bidirectional sync: `basic-memory cloud sync`
+- Integrity check: `basic-memory cloud check`
+- Mount cloud storage: `basic-memory cloud mount`
+- Unmount cloud storage: `basic-memory cloud unmount`
+
 ### MCP Capabilities
 
 - Basic Memory exposes these MCP tools to LLMs:
 
   **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
+    - `read_content(path)` - Read raw file content (text, images, binaries) without knowledge graph processing
+    - `view_note(identifier, page, page_size)` - View notes as formatted artifacts for better readability
+    - `edit_note(identifier, operation, content)` - Edit notes incrementally (append, prepend, find/replace, replace_section)
+    - `move_note(identifier, destination_path)` - Move notes to new locations, updating database and maintaining links
+    - `delete_note(identifier)` - Delete notes from the knowledge base
 
   **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)` - Browse directory contents with filtering and depth control
 
   **Search & Discovery:**
-    - `search(query, page, page_size)` - Full-text search across all content with filtering options
+    - `search_notes(query, page, page_size, search_type, types, entity_types, after_date)` - Full-text search across all content with advanced filtering options
+
+  **Project Management:**
+    - `list_memory_projects()` - List all available projects with their status
+    - `create_memory_project(project_name, project_path, set_default)` - Create new Basic Memory projects
+    - `delete_project(project_name)` - Delete a project from configuration
+    - `get_current_project()` - Get current project information and stats
+    - `sync_status()` - Check file synchronization and background operation status
 
   **Visualization:**
     - `canvas(nodes, edges, title, folder)` - Generate Obsidian canvas files for knowledge graph visualization
@@ -118,6 +187,34 @@ See the [README.md](README.md) file for a project overview.
     - `recent_activity(timeframe)` - View recently changed items with formatted output
     - `json_canvas_spec()` - Full JSON Canvas specification for Obsidian visualization
 
+### Cloud Features (v0.15.0+)
+
+Basic Memory now supports cloud synchronization and storage (requires active subscription):
+
+**Authentication:**
+- JWT-based authentication with subscription validation
+- Secure session management with token refresh
+- Support for multiple cloud projects
+
+**Bidirectional Sync:**
+- rclone bisync integration for two-way synchronization
+- Conflict resolution and integrity verification
+- Real-time sync with change detection
+- Mount/unmount cloud storage for direct file access
+
+**Cloud Project Management:**
+- Create and manage projects in the cloud
+- Toggle between local and cloud modes
+- Per-project sync configuration
+- Subscription-based access control
+
+**Security & Performance:**
+- Removed .env file loading for improved security
+- .gitignore integration (respects gitignored files)
+- WAL mode for SQLite performance
+- Background relation resolution (non-blocking startup)
+- API performance optimizations (SPEC-11)
+
 ## AI-Human Collaborative Development
 
 Basic Memory emerged from and enables a new kind of development process that combines human and AI capabilities. Instead
@@ -130,4 +227,43 @@ of using AI just for code generation, we've developed a true collaborative workf
 5. Results improve through iterative collaboration and shared understanding
 
 This approach has allowed us to tackle more complex challenges and build a more robust system than either humans or AI
-could achieve independently.
+could achieve independently.
+
+## GitHub Integration
+
+Basic Memory has taken AI-Human collaboration to the next level by integrating Claude directly into the development workflow through GitHub:
+
+### GitHub MCP Tools
+
+Using the GitHub Model Context Protocol server, Claude can now:
+
+- **Repository Management**:
+  - View repository files and structure
+  - Read file contents
+  - Create new branches
+  - Create and update files
+
+- **Issue Management**:
+  - Create new issues
+  - Comment on existing issues
+  - Close and update issues
+  - Search across issues
+
+- **Pull Request Workflow**:
+  - Create pull requests
+  - Review code changes
+  - Add comments to PRs
+
+This integration enables Claude to participate as a full team member in the development process, not just as a code generation tool. Claude's GitHub account ([bm-claudeai](https://github.com/bm-claudeai)) is a member of the Basic Machines organization with direct contributor access to the codebase.
+
+### Collaborative Development Process
+
+With GitHub integration, the development workflow includes:
+
+1. **Direct code review** - Claude can analyze PRs and provide detailed feedback
+2. **Contribution tracking** - All of Claude's contributions are properly attributed in the Git history
+3. **Branch management** - Claude can create feature branches for implementations
+4. **Documentation maintenance** - Claude can keep documentation updated as the code evolves
+5. **Code Commits**: ALWAYS sign off commits with `git commit -s`
+
+This level of integration represents a new paradigm in AI-human collaboration, where the AI assistant becomes a full-fledged team member rather than just a tool for generating code snippets.

CONTRIBUTING.md

@@ -1,6 +1,7 @@
 # Contributing to Basic Memory
 
-Thank you for considering contributing to Basic Memory! This document outlines the process for contributing to the project and how to get started as a developer.
+Thank you for considering contributing to Basic Memory! This document outlines the process for contributing to the
+project and how to get started as a developer.
 
 ## Getting Started
 
@@ -14,8 +15,8 @@ Thank you for considering contributing to Basic Memory! This document outlines t
 
 2. **Install Dependencies**:
    ```bash
-   # Using make (recommended)
-   make install
+   # Using just (recommended)
+   just install
    
    # Or using uv
    uv install -e ".[dev]"
@@ -24,13 +25,27 @@ Thank you for considering contributing to Basic Memory! This document outlines t
    pip install -e ".[dev]"
    ```
 
-3. **Run the Tests**:
+   > **Note**: Basic Memory uses [just](https://just.systems) as a modern command runner. Install with `brew install just` or `cargo install just`.
+
+3. **Activate the Virtual Environment**
    ```bash
-   # Run all tests
-   make test
-   # or
-   uv run pytest -p pytest_mock -v
-   
+   source .venv/bin/activate
+   ```
+
+4. **Run the Tests**:
+   ```bash
+   # Run all tests with unified coverage (unit + integration)
+   just test
+
+   # Run unit tests only (fast, no coverage)
+   just test-unit
+
+   # Run integration tests only (fast, no coverage)
+   just test-int
+
+   # Generate HTML coverage report
+   just coverage
+
    # Run a specific test
    pytest tests/path/to/test_file.py::test_function_name
    ```
@@ -48,16 +63,16 @@ Thank you for considering contributing to Basic Memory! This document outlines t
 4. **Check Code Quality**:
    ```bash
    # Run all checks at once
-   make check
+   just check
    
    # Or run individual checks
-   make lint      # Run linting
-   make format    # Format code
-   make type-check  # Type checking
+   just lint      # Run linting
+   just format    # Format code
+   just type-check  # Type checking
    ```
 5. **Test Your Changes**: Ensure all tests pass locally and maintain 100% test coverage.
    ```bash
-   make test
+   just test
    ```
 6. **Submit a PR**: Submit a pull request with a detailed description of your changes.
 
@@ -65,65 +80,68 @@ Thank you for considering contributing to Basic Memory! This document outlines t
 
 This project is designed for collaborative development between humans and LLMs (Large Language Models):
 
-1. **CLAUDE.md**: The repository includes a `CLAUDE.md` file that serves as a project guide for both humans and LLMs. This file contains:
-   - Key project information and architectural overview
-   - Development commands and workflows
-   - Code style guidelines
-   - Documentation standards
+1. **CLAUDE.md**: The repository includes a `CLAUDE.md` file that serves as a project guide for both humans and LLMs.
+   This file contains:
+    - Key project information and architectural overview
+    - Development commands and workflows
+    - Code style guidelines
+    - Documentation standards
 
 2. **AI-Human Collaborative Workflow**:
-   - We encourage using LLMs like Claude for code generation, reviews, and documentation
-   - When possible, save context in markdown files that can be referenced later
-   - This enables seamless knowledge transfer between different development sessions
-   - Claude can help with implementation details while you focus on architecture and design
+    - We encourage using LLMs like Claude for code generation, reviews, and documentation
+    - When possible, save context in markdown files that can be referenced later
+    - This enables seamless knowledge transfer between different development sessions
+    - Claude can help with implementation details while you focus on architecture and design
 
 3. **Adding to CLAUDE.md**:
-   - If you discover useful project information or common commands, consider adding them to CLAUDE.md
-   - This helps all contributors (human and AI) maintain consistent knowledge of the project
+    - If you discover useful project information or common commands, consider adding them to CLAUDE.md
+    - This helps all contributors (human and AI) maintain consistent knowledge of the project
 
 ## Pull Request Process
 
 1. **Create a Pull Request**: Open a PR against the `main` branch with a clear title and description.
-2. **Sign the Developer Certificate of Origin (DCO)**: All contributions require signing our DCO, which certifies that you have the right to submit your contributions. This will be automatically checked by our CLA assistant when you create a PR.
+2. **Sign the Developer Certificate of Origin (DCO)**: All contributions require signing our DCO, which certifies that
+   you have the right to submit your contributions. This will be automatically checked by our CLA assistant when you
+   create a PR.
 3. **PR Description**: Include:
-   - What the PR changes
-   - Why the change is needed
-   - How you tested the changes
-   - Any related issues (use "Fixes #123" to automatically close issues)
+    - What the PR changes
+    - Why the change is needed
+    - How you tested the changes
+    - Any related issues (use "Fixes #123" to automatically close issues)
 4. **Code Review**: Wait for code review and address any feedback.
 5. **CI Checks**: Ensure all CI checks pass.
 6. **Merge**: Once approved, a maintainer will merge your PR.
 
 ## Developer Certificate of Origin
 
-By contributing to this project, you agree to the [Developer Certificate of Origin (DCO)](CLA.md). This means you certify that:
+By contributing to this project, you agree to the [Developer Certificate of Origin (DCO)](CLA.md). This means you
+certify that:
+
 - You have the right to submit your contributions
 - You're not knowingly submitting code with patent or copyright issues
 - Your contributions are provided under the project's license (AGPL-3.0)
 
-This is a lightweight alternative to a Contributor License Agreement and helps ensure that all contributions can be properly incorporated into the project and potentially used in commercial applications.
+This is a lightweight alternative to a Contributor License Agreement and helps ensure that all contributions can be
+properly incorporated into the project and potentially used in commercial applications.
 
 ### Signing Your Commits
 
-You can sign your commits in one of two ways:
+Sign your commit:
 
-1. **Using the `-s` or `--signoff` flag**:
-   ```bash
-   git commit -s -m "Your commit message"
-   ```
-   This adds a `Signed-off-by` line to your commit message, certifying that you adhere to the DCO.
+**Using the `-s` or `--signoff` flag**:
 
-2. **Configuring Git to automatically sign off**:
-   ```bash
-   git config --global alias.cs 'commit -s'
-   ```
-   Then use `git cs -m "Your commit message"` to commit with sign-off.
+```bash
+git commit -s -m "Your commit message"
+```
 
-The sign-off certifies that you have the right to submit your contribution under the project's license and verifies your agreement to the DCO.
+This adds a `Signed-off-by` line to your commit message, certifying that you adhere to the DCO.
+
+The sign-off certifies that you have the right to submit your contribution under the project's license and verifies your
+agreement to the DCO.
 
 ## Code Style Guidelines
 
-- **Python Version**: Python 3.12+ with full type annotations
+- **Python Version**: Python 3.12+ with full type annotations (3.12+ required for type parameter syntax)
 - **Line Length**: 100 characters maximum
 - **Formatting**: Use ruff for consistent styling
 - **Import Order**: Standard lib, third-party, local imports
@@ -133,12 +151,112 @@ The sign-off certifies that you have the right to submit your contribution under
 
 ## Testing Guidelines
 
-- **Coverage Target**: We aim for 100% test coverage for all code
+### Test Structure
+
+Basic Memory uses two test directories with unified coverage reporting:
+
+- **`tests/`**: Unit tests that test individual components in isolation
+  - Fast execution with extensive mocking
+  - Test individual functions, classes, and modules
+  - Run with: `just test-unit` (no coverage, fast)
+
+- **`test-int/`**: Integration tests that test real-world scenarios
+  - Test full workflows with real database and file operations
+  - Include performance benchmarks
+  - More realistic but slower than unit tests
+  - Run with: `just test-int` (no coverage, fast)
+
+### Running Tests
+
+```bash
+# Run all tests with unified coverage report
+just test
+
+# Run only unit tests (fast iteration)
+just test-unit
+
+# Run only integration tests
+just test-int
+
+# Generate HTML coverage report
+just coverage
+
+# Run specific test
+pytest tests/path/to/test_file.py::test_function_name
+
+# Run tests excluding benchmarks
+pytest -m "not benchmark"
+
+# Run only benchmark tests
+pytest -m benchmark test-int/test_sync_performance_benchmark.py
+```
+
+### Performance Benchmarks
+
+The `test-int/test_sync_performance_benchmark.py` file contains performance benchmarks that measure sync and indexing speed:
+
+- `test_benchmark_sync_100_files` - Small repository performance
+- `test_benchmark_sync_500_files` - Medium repository performance
+- `test_benchmark_sync_1000_files` - Large repository performance (marked slow)
+- `test_benchmark_resync_no_changes` - Re-sync performance baseline
+
+Run benchmarks with:
+```bash
+# Run all benchmarks (excluding slow ones)
+pytest test-int/test_sync_performance_benchmark.py -v -m "benchmark and not slow"
+
+# Run all benchmarks including slow ones
+pytest test-int/test_sync_performance_benchmark.py -v -m benchmark
+
+# Run specific benchmark
+pytest test-int/test_sync_performance_benchmark.py::test_benchmark_sync_100_files -v
+```
+
+See `test-int/BENCHMARKS.md` for detailed benchmark documentation.
+
+### Testing Best Practices
+
+- **Coverage Target**: We aim for high test coverage for all code
 - **Test Framework**: Use pytest for unit and integration tests
-- **Mocking**: Use pytest-mock for mocking dependencies
+- **Mocking**: Avoid mocking in integration tests; use sparingly in unit tests
 - **Edge Cases**: Test both normal operation and edge cases
 - **Database Testing**: Use in-memory SQLite for testing database operations
-- **Fixtures**: Use pytest fixtures for setup and teardown
+- **Fixtures**: Use async pytest fixtures for setup and teardown
+- **Markers**: Use `@pytest.mark.benchmark` for benchmarks, `@pytest.mark.slow` for slow tests
+
+## Release Process
+
+Basic Memory uses automatic versioning based on git tags with `uv-dynamic-versioning`. Here's how releases work:
+
+### Version Management
+- **Development versions**: Automatically generated from git commits (e.g., `0.12.4.dev26+468a22f`)
+- **Beta releases**: Created by tagging with beta suffixes (e.g., `git tag v0.13.0b1`)
+- **Stable releases**: Created by tagging with version numbers (e.g., `git tag v0.13.0`)
+
+### Release Workflows
+
+#### Development Builds
+- Automatically published to PyPI on every commit to `main`
+- Version format: `0.12.4.dev26+468a22f` (base version + dev + commit count + hash)
+- Users install with: `pip install basic-memory --pre --force-reinstall`
+
+#### Beta Releases
+1. Create and push a beta tag: `git tag v0.13.0b1 && git push origin v0.13.0b1`
+2. GitHub Actions automatically builds and publishes to PyPI
+3. Users install with: `pip install basic-memory --pre`
+
+#### Stable Releases
+1. Create and push a version tag: `git tag v0.13.0 && git push origin v0.13.0`
+2. GitHub Actions automatically:
+   - Builds the package with version `0.13.0`
+   - Creates GitHub release with auto-generated notes
+   - Publishes to PyPI
+3. Users install with: `pip install basic-memory`
+
+### For Contributors
+- No manual version bumping required
+- Versions are automatically derived from git tags
+- Focus on code changes, not version management
 
 ## Creating Issues
 
@@ -156,4 +274,4 @@ All contributors must follow the [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## Thank You!
 
-Your contributions help make Basic Memory better for everyone. We appreciate your time and effort!
+Your contributions help make Basic Memory better. We appreciate your time and effort!

Dockerfile

@@ -0,0 +1,46 @@
+FROM python:3.12-slim-bookworm
+
+# Build arguments for user ID and group ID (defaults to 1000)
+ARG UID=1000
+ARG GID=1000
+
+# Copy uv from official image
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+# Create a group and user with the provided UID/GID
+# Check if the GID already exists, if not create appgroup
+RUN (getent group ${GID} || groupadd --gid ${GID} appgroup) && \
+    useradd --uid ${UID} --gid ${GID} --create-home --shell /bin/bash appuser
+
+# Copy the project into the image
+ADD . /app
+
+# Sync the project into a new environment, asserting the lockfile is up to date
+WORKDIR /app
+RUN uv sync --locked
+
+# Create necessary directories and set ownership
+RUN mkdir -p /app/data/basic-memory /app/.basic-memory && \
+    chown -R appuser:${GID} /app
+
+# Set default data directory and add venv to PATH
+ENV BASIC_MEMORY_HOME=/app/data/basic-memory \
+    BASIC_MEMORY_PROJECT_ROOT=/app/data \
+    PATH="/app/.venv/bin:$PATH"
+
+# Switch to the non-root user
+USER appuser
+
+# Expose port
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD basic-memory --version || exit 1
+
+# Use the basic-memory entrypoint to run the MCP server with default SSE transport
+CMD ["basic-memory", "mcp", "--transport", "sse", "--host", "0.0.0.0", "--port", "8000"]

Makefile

@@ -1,67 +0,0 @@
-.PHONY: install test test-module lint clean format type-check installer-mac installer-win check
-
-install:
-	pip install -e ".[dev]"
-
-test:
-	uv run pytest -p pytest_mock -v
-
-# Run tests for a specific module
-# Usage: make test-module m=path/to/module.py [cov=module_path]
-test-module:
-	@if [ -z "$(m)" ]; then \
-		echo "Usage: make test-module m=path/to/module.py [cov=module_path]"; \
-		exit 1; \
-	fi; \
-	if [ -z "$(cov)" ]; then \
-		uv run pytest $(m) -v; \
-	else \
-		uv run pytest $(m) -v --cov=$(cov); \
-	fi
-
-lint:
-	ruff check . --fix
-
-type-check:
-	uv run pyright
-
-clean:
-	find . -type f -name '*.pyc' -delete
-	find . -type d -name '__pycache__' -exec rm -r {} +
-	rm -rf installer/build/
-	rm -rf installer/dist/
-	rm -f rw.*.dmg
-	rm -rf dist
-	rm -rf installer/build
-	rm -rf installer/dist
-	rm -f .coverage.*
-
-format:
-	uv run ruff format .
-
-# run inspector tool
-run-inspector:
-	uv run mcp dev src/basic_memory/mcp/main.py
-
-# Build app installer
-installer-mac:
-	cd installer && chmod +x make_icons.sh && ./make_icons.sh
-	cd installer && uv run python setup.py bdist_mac
-
-installer-win:
-	cd installer && uv run python setup.py bdist_win32
-
-
-update-deps:
-	uv lock --upgrade
-
-check: lint  format type-check test
-
-
-# Target for generating Alembic migrations with a message from command line
-migration:
-	@if [ -z "$(m)" ]; then \
-		echo "Usage: make migration m=\"Your migration message\""; \
-		exit 1; \
-	fi; \
-	cd src/basic_memory/alembic && alembic revision --autogenerate -m "$(m)"

README.md

@@ -1,38 +1,44 @@
-# Basic Memory
-
 [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 [![PyPI version](https://badge.fury.io/py/basic-memory.svg)](https://badge.fury.io/py/basic-memory)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
 [![Tests](https://github.com/basicmachines-co/basic-memory/workflows/Tests/badge.svg)](https://github.com/basicmachines-co/basic-memory/actions)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+![](https://badge.mcpx.dev?type=server 'MCP Server')
+![](https://badge.mcpx.dev?type=dev 'MCP Dev')
+[![smithery badge](https://smithery.ai/badge/@basicmachines-co/basic-memory)](https://smithery.ai/server/@basicmachines-co/basic-memory)
 
-```
-██████╗  █████╗ ███████╗██╗ ██████╗    ███╗   ███╗███████╗███╗   ███╗ ██████╗ ██████╗ ██╗   ██╗
-██╔══██╗██╔══██╗██╔════╝██║██╔════╝    ████╗ ████║██╔════╝████╗ ████║██╔═══██╗██╔══██╗╚██╗ ██╔╝
-██████╔╝███████║███████╗██║██║         ██╔████╔██║█████╗  ██╔████╔██║██║   ██║██████╔╝ ╚████╔╝ 
-██╔══██╗██╔══██║╚════██║██║██║         ██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║██║   ██║██╔══██╗  ╚██╔╝  
-██████╔╝██║  ██║███████║██║╚██████╗    ██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║╚██████╔╝██║  ██║   ██║   
-╚═════╝ ╚═╝  ╚═╝╚══════╝╚═╝ ╚═════╝    ╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝ ╚═════╝ ╚═╝  ╚═╝   ╚═╝   
+## 🚀 Basic Memory Cloud is Live!
 
-```
+- **Cross-device and multi-platform support is here.** Your knowledge graph now works on desktop, web, and mobile - seamlessly synced across all your AI tools (Claude, ChatGPT, Gemini, Claude Code, and Codex) 
+- **Early Supporter Pricing:** Early users get 25% off forever. 
+The open source project continues as always. Cloud just makes it work everywhere.
+
+[Sign up now →](https://basicmemory.com/beta)
+
+with a 7 day free trial
+
+# Basic Memory
 
 Basic Memory lets you build persistent knowledge through natural conversations with Large Language Models (LLMs) like
 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.
 
-LLMs can build context from local knowledge bases.
+- Website: https://basicmachines.co
+- Documentation: https://memory.basicmachines.co
 
-![Example Gif](docs/attachments/Obsidian-CoffeeKnowledgeBase-examples-overlays.gif)
+## Pick up your conversation right where you left off
 
-Basic Memory provides persistent contextual awareness across sessions through a structured knowledge graph.
-The system enables LLMs to access and reference prior conversations, track semantic relationships between concepts, and
-incorporate human edits made directly to knowledge files.
+- AI assistants can load context from local files in a new conversation
+- Notes are saved locally as Markdown files in real time
+- No project knowledge or special prompting required
+
+https://github.com/user-attachments/assets/a55d8238-8dd0-454a-be4c-8860dbbd0ddc
 
 ## Quick Start
 
 ```bash
 # Install with uv (recommended)
-uv install basic-memory
+uv tool install basic-memory
 
 # Configure Claude Desktop (edit ~/Library/Application Support/Claude/claude_desktop_config.json)
 # Add this to your config:
@@ -56,33 +62,23 @@ uv install basic-memory
 
 You can view shared context via files in `~/basic-memory` (default directory location).
 
-You can also install the cli tools to sync files or manage projects.
+### Alternative Installation via Smithery
 
-```bash 
-uv tool install basic-memory
+You can use [Smithery](https://smithery.ai/server/@basicmachines-co/basic-memory) to automatically configure Basic
+Memory for Claude Desktop:
 
-# create a new project in a different directory
-basic-memory project add coffee ./examples/coffee
-
-# you can set the project to the default 
-basic-memory project default coffee
+```bash
+npx -y @smithery/cli install @basicmachines-co/basic-memory --client claude
 ```
 
-View available projects
+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.
 
-```bash 
-basic-memory project list
-                             Basic Memory Projects
-┏━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┓
-┃ Name   ┃ Path                                             ┃ Default ┃ Active ┃
-┡━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━┩
-│ main   │ ~/basic-memory                                   │ ✓       │ ✓      │
-│ coffee │ ~/dev/basicmachines/basic-memory/examples/coffee │         │        │
-└────────┴──────────────────────────────────────────────────┴─────────┴────────┘
-```
+### Glama.ai
 
-Basic Memory will write notes in Markdown format. Open you project directory in your text editor to view project files
-while you have conversations with an LLM.
+<a href="https://glama.ai/mcp/servers/o90kttu9ym">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/o90kttu9ym/badge" alt="basic-memory MCP server" />
+</a>
 
 ## Why Basic Memory?
 
@@ -114,6 +110,9 @@ With Basic Memory, you can:
 - Keep everything local and under your control
 - Use familiar tools like Obsidian to view and edit notes
 - Build a personal knowledge base that grows over time
+- Sync your knowledge to the cloud with bidirectional synchronization
+- Authenticate and manage cloud projects with subscription validation
+- Mount cloud storage for direct file access
 
 ## How It Works in Practice
 
@@ -163,36 +162,13 @@ tags:
 - affects [[Flavor Extraction]]
 ```
 
-The note embeds semantic content and links to other topics via simple Markdown
-formatting.
+The note embeds semantic content and links to other topics via simple Markdown formatting.
 
-3. You see this file on your computer in real time in the `~/$HOME/basic-memory` directory:
+3. You see this file on your computer in real time in the current project directory (default `~/$HOME/basic-memory`).
 
-```markdown
----
-title: Coffee Brewing Methods
-permalink: coffee-brewing-methods
-type: note
----
+- Realtime sync can be enabled via running `basic-memory sync --watch`
 
-# Coffee Brewing Methods
-
-## Observations
-
-- [method] Pour over provides more clarity and highlights subtle flavors
-- [technique] Water temperature at 205°F (96°C) extracts optimal compounds
-- [principle] Freshly ground beans preserve aromatics and flavor
-- [preference] Medium-light roasts work best for pour over # Added by you
-
-## Relations
-
-- relates_to [[Coffee Bean Origins]]
-- requires [[Proper Grinding Technique]]
-- affects [[Flavor Extraction]]
-- pairs_with [[Breakfast Pastries]]  # Added by you
-```
-
-4. In a new chat with the LLM, you can reference this knowledge:
+4. In a chat with the LLM, you can reference a topic:
 
 ```
 Look at `coffee-brewing-methods` for context about pour over coffee
@@ -212,15 +188,14 @@ Following relation 'requires [[Proper Grinding Technique]]':
 - Impact of consistent particle size on extraction
 ```
 
-Each related document can lead to more context, building a rich semantic understanding of your knowledge base. All of
-this context comes from standard Markdown files that both humans and LLMs can read and write.
+Each related document can lead to more context, building a rich semantic understanding of your knowledge base.
 
-Every time the LLM writes notes,they are saved in local Markdown files that you can:
+This creates a two-way flow where:
 
-- Edit in any text editor
-- Version via git
-- Back up normally
-- Share when you want to
+- Humans write and edit Markdown files
+- LLMs read and write through the MCP protocol
+- Sync keeps everything consistent
+- All knowledge stays in local files.
 
 ## Technical Implementation
 
@@ -256,7 +231,7 @@ permalink: <a uri slug>
 
 Observations are facts about a topic.
 They can be added by creating a Markdown list with a special format that can reference a `category`, `tags` using a
-"#" charactor, and an optional `context`.
+"#" character, and an optional `context`.
 
 Observation Markdown format:
 
@@ -300,72 +275,37 @@ Examples of relations:
 - documented_in [[Coffee Journal]]
 ```
 
-### Complete Example
+## Using with VS Code
 
-Here's a complete example of a note with frontmatter, observations, and relations:
+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)`.
 
-```markdown
----
-title: Pour Over Coffee Method
-type: note
-permalink: pour-over-coffee-method
-tags:
-- brewing
-- coffee
-- techniques
----
-
-# Pour Over Coffee Method
-
-This note documents the pour over brewing method and my experiences with it.
-
-## Overview
-
-The pour over method involves pouring hot water through coffee grounds in a filter. The water drains through the coffee
-and filter into a carafe or cup.
-
-## Observations
-
-- [equipment] Hario V60 dripper produces clean, bright cup #gear
-- [technique] Pour in concentric circles to ensure even extraction
-- [ratio] 1:16 coffee-to-water ratio works best for balanced flavor
-- [timing] Total brew time should be 2:30-3:00 minutes for medium roast
-- [temperature] Water at 205°F (96°C) extracts optimal flavor compounds
-- [grind] Medium-fine grind similar to table salt texture
-- [tip] 30-45 second bloom with double the coffee weight in water
-- [result] Produces a cleaner cup with more distinct flavor notes than immersion methods
-
-## Relations
-
-- complements [[Light Roast Beans]]
-- requires [[Gooseneck Kettle]]
-- contrasts_with [[French Press Method]]
-- pairs_with [[Breakfast Pastries]]
-- documented_in [[Brewing Journal]]
-- inspired_by [[Japanese Brewing Techniques]]
-- affects [[Flavor Extraction]]
-- part_of [[Morning Ritual]]
+```json
+{
+  "mcp": {
+    "servers": {
+      "basic-memory": {
+        "command": "uvx",
+        "args": ["basic-memory", "mcp"]
+      }
+    }
+  }
+}
 ```
 
-Basic Memory will parse the Markdown and derive the semantic relationships in the content. When you run
-`basic-memory sync`:
+Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
 
-1. New and changed files are detected
-2. Markdown patterns become semantic knowledge:
+```json
+{
+  "servers": {
+    "basic-memory": {
+      "command": "uvx",
+      "args": ["basic-memory", "mcp"]
+    }
+  }
+}
+```
 
-- `[tech]` becomes a categorized observation
-- `[[WikiLink]]` creates a relation in the knowledge graph
-- Tags and metadata are indexed for search
-
-3. A SQLite database maintains these relationships for fast querying
-4. MCP-compatible LLMs can access this knowledge via memory:// URLs
-
-This creates a two-way flow where:
-
-- Humans write and edit Markdown files
-- LLMs read and write through the MCP protocol
-- Sync keeps everything consistent
-- All knowledge stays in local files.
+You can use Basic Memory with VS Code to easily retrieve and store information while coding.
 
 ## Using with Claude Desktop
 
@@ -419,14 +359,57 @@ basic-memory sync
 basic-memory sync --watch
 ```
 
-3. In Claude Desktop, the LLM can now use these tools:
+3. Cloud features (optional, requires subscription):
 
+```bash
+# Authenticate with cloud
+basic-memory cloud login
+
+# Bidirectional sync with cloud
+basic-memory cloud sync
+
+# Verify cloud integrity
+basic-memory cloud check
+
+# Mount cloud storage
+basic-memory cloud mount
+```
+
+4. In Claude Desktop, the LLM can now use these tools:
+
+**Content Management:**
 ```
 write_note(title, content, folder, tags) - Create or update notes
 read_note(identifier, page, page_size) - Read notes by title or permalink
+read_content(path) - Read raw file content (text, images, binaries)
+view_note(identifier) - View notes as formatted artifacts
+edit_note(identifier, operation, content) - Edit notes incrementally
+move_note(identifier, destination_path) - Move notes with database consistency
+delete_note(identifier) - Delete notes from knowledge base
+```
+
+**Knowledge Graph Navigation:**
+```
 build_context(url, depth, timeframe) - Navigate knowledge graph via memory:// URLs
-search(query, page, page_size) - Search across your knowledge base
 recent_activity(type, depth, timeframe) - Find recently updated information
+list_directory(dir_name, depth) - Browse directory contents with filtering
+```
+
+**Search & Discovery:**
+```
+search(query, page, page_size) - Search across your knowledge base
+```
+
+**Project Management:**
+```
+list_memory_projects() - List all available projects
+create_memory_project(project_name, project_path) - Create new projects
+get_current_project() - Show current project stats
+sync_status() - Check synchronization status
+```
+
+**Visualization:**
+```
 canvas(nodes, edges, title, folder) - Generate knowledge visualizations
 ```
 
@@ -440,263 +423,82 @@ canvas(nodes, edges, title, folder) - Generate knowledge visualizations
 "What have I been working on in the past week?"
 ```
 
-## Multiple Projects
+## Futher info
 
-Basic Memory supports managing multiple separate knowledge bases through projects. This feature allows you to maintain
-separate knowledge graphs for different purposes (e.g., personal notes, work projects, research topics).
+See the [Documentation](https://memory.basicmachines.co/) for more info, including:
 
-### Managing Projects
+- [Complete User Guide](https://docs.basicmemory.com/user-guide/)
+- [CLI tools](https://docs.basicmemory.com/guides/cli-reference/)
+- [Cloud CLI and Sync](https://docs.basicmemory.com/guides/cloud-cli/)
+- [Managing multiple Projects](https://docs.basicmemory.com/guides/cli-reference/#project)
+- [Importing data from OpenAI/Claude Projects](https://docs.basicmemory.com/guides/cli-reference/#import)
 
+## Development
+
+### Running Tests
+
+Basic Memory supports dual database backends (SQLite and Postgres). Tests are parametrized to run against both backends automatically.
+
+**Quick Start:**
 ```bash
-# List all configured projects
-basic-memory project list
+# Run SQLite tests (default, no Docker needed)
+just test-sqlite
 
-# Add a new project
-basic-memory project add work ~/work-basic-memory
-
-# Set the default project
-basic-memory project default work
-
-# Remove a project (doesn't delete files)
-basic-memory project remove personal
-
-# Show current project
-basic-memory project current
+# Run Postgres tests (requires Docker)
+just test-postgres
 ```
 
-### Using Projects in Commands
+**Available Test Commands:**
 
-All commands support the `--project` flag to specify which project to use:
+- `just test-sqlite` - Run tests against SQLite only (fastest, no Docker needed)
+- `just test-postgres` - Run tests against Postgres only (requires Docker)
+- `just test-windows` - Run Windows-specific tests (auto-skips on other platforms)
+- `just test-benchmark` - Run performance benchmark tests
+- `just test-all` - Run all tests including Windows, Postgres, and benchmarks
 
+**Postgres Testing Requirements:**
+
+To run Postgres tests, you need to start the test database:
 ```bash
-# Sync a specific project
-basic-memory --project=work sync
-
-# Run MCP server for a specific project
-basic-memory --project=personal mcp
+docker-compose -f docker-compose-postgres.yml up -d
 ```
 
-You can also set the `BASIC_MEMORY_PROJECT` environment variable:
+Tests will connect to `localhost:5433/basic_memory_test`.
 
+**Test Markers:**
+
+Tests use pytest markers for selective execution:
+- `postgres` - Tests that run against Postgres backend
+- `windows` - Windows-specific database optimizations
+- `benchmark` - Performance tests (excluded from default runs)
+
+**Other Development Commands:**
 ```bash
-BASIC_MEMORY_PROJECT=work basic-memory sync
+just install          # Install with dev dependencies
+just lint             # Run linting checks
+just typecheck        # Run type checking
+just format           # Format code with ruff
+just check            # Run all quality checks
+just migration "msg"  # Create database migration
 ```
 
-### Project Isolation
-
-Each project maintains:
-
-- Its own collection of markdown files in the specified directory
-- A separate SQLite database for that project
-- Complete knowledge graph isolation from other projects
-
-## Design Philosophy
-
-Basic Memory is built on some key ideas:
-
-- Your knowledge should stay in files you control
-- Both humans and AI should use natural formats
-- Simple text patterns can capture rich meaning
-- Local-first doesn't mean feature-poor
-- Knowledge should persist across conversations
-- AI assistants should build on past context
-- File formats should be human-readable and editable
-- Semantic structure should emerge from natural patterns
-- Knowledge graphs should be both AI and human navigable
-- Systems should augment human memory, not replace it
-
-## Importing Existing Data
-
-Basic Memory provides CLI commands to import data from various sources, converting them into the structured Markdown
-format:
-
-### Claude.ai
-
-First, request an export of your data from your Claude account. The data will be emailed to you in several files,
-including
-`conversations.json` and `projects.json`.
-
-Import Claude.ai conversation data
-
-```bash
- basic-memory import claude conversations 
-```
-
-The conversations will be turned into Markdown files and placed in the "conversations" folder by default (this can be
-changed with the --folder arg).
-
-Example:
-
-```bash
-Importing chats from conversations.json...writing to .../basic-memory
-  Reading chat data... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
-╭────────────────────────────╮
-│ Import complete!           │
-│                            │
-│ Imported 307 conversations │
-│ Containing 7769 messages   │
-╰────────────────────────────╯
-```
-
-Next, you can run the `sync` command to import the data into basic-memory
-
-```bash
-basic-memory sync
-```
-
-You can also import project data from Claude.ai
-
-```bash 
-➜  basic-memory import claude projects
-Importing projects from projects.json...writing to .../basic-memory/projects
-  Reading project data... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
-╭────────────────────────────────╮
-│ Import complete!               │
-│                                │
-│ Imported 101 project documents │
-│ Imported 32 prompt templates   │
-╰────────────────────────────────╯
-
-Run 'basic-memory sync' to index the new files.
-```
-
-### OpenAI ChatGPT
-
-```bash
- ➜  basic-memory import chatgpt
-Importing chats from conversations.json...writing to .../basic-memory/conversations
-
-  Reading chat data... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
-╭────────────────────────────╮
-│ Import complete!           │
-│                            │
-│ Imported 198 conversations │
-│ Containing 11777 messages  │
-╰────────────────────────────╯
-
-
-```
-
-### Knowledge Graph Memory Server
-
-From the MCP Server: https://github.com/modelcontextprotocol/servers/tree/main/src/memory
-
-```bash
-➜  basic-memory import memory-json
-Importing from memory.json...writing to .../basic-memory
-  Reading memory.json... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
-  Creating entities...   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
-╭──────────────────────╮
-│ Import complete!     │
-│                      │
-│ Created 126 entities │
-│ Added 252 relations  │
-╰──────────────────────╯
-```
-
-## Working with Your Knowledge Base
-
-Once you've built up a knowledge base, you can interact with it in several ways:
-
-### Command Line Interface
-
-Basic Memory provides a powerful CLI for managing your knowledge:
-
-```bash
-# See all available commands
-basic-memory --help
-
-# Check the status of your knowledge sync
-basic-memory status
-
-# Access specific tool functionality directly
-basic-memory tools
-
-# Start a continuous sync process
-basic-memory sync --watch
-```
-
-### Obsidian Integration
-
-Basic Memory works seamlessly with [Obsidian](https://obsidian.md/), a popular knowledge management app:
-
-1. Point Obsidian to your Basic Memory directory
-2. Use standard Obsidian features like backlinks and graph view
-3. See your knowledge graph visually
-4. Use the canvas visualization generated by Basic Memory
-
-### File Organization
-
-Basic Memory is flexible about how you organize your files:
-
-- Group by topic in folders
-- Use a flat structure with descriptive filenames
-- Add custom metadata in frontmatter
-- Tag files for better searchability
-
-The system will build the semantic knowledge graph regardless of your file organization preference.
-
-## Using stdin with Basic Memory's `write_note` Tool
-
-The `write-note` tool supports reading content from standard input (stdin), allowing for more flexible workflows when
-creating or updating notes in your Basic Memory knowledge base.
-
-### Use Cases
-
-This feature is particularly useful for:
-
-1. **Piping output from other commands** directly into Basic Memory notes
-2. **Creating notes with multi-line content** without having to escape quotes or special characters
-3. **Integrating with AI assistants** like Claude Code that can generate content and pipe it to Basic Memory
-4. **Processing text data** from files or other sources
-
-## Basic Usage
-
-### Method 1: Using a Pipe
-
-You can pipe content from another command into `write_note`:
-
-```bash
-# Pipe output of a command into a new note
-echo "# My Note\n\nThis is a test note" | basic-memory tools write-note --title "Test Note" --folder "notes"
-
-# Pipe output of a file into a new note
-cat README.md | basic-memory tools write-note --title "Project README" --folder "documentation"
-
-# Process text through other tools before saving as a note
-cat data.txt | grep "important" | basic-memory tools write-note --title "Important Data" --folder "data"
-```
-
-### Method 2: Using Heredoc Syntax
-
-For multi-line content, you can use heredoc syntax:
-
-```bash
-# Create a note with heredoc
-cat << EOF | basic-memory tools write_note --title "Project Ideas" --folder "projects"
-# Project Ideas for Q2
-
-## AI Integration
-- Improve recommendation engine
-- Add semantic search to product catalog
-
-## Infrastructure
-- Migrate to Kubernetes
-- Implement CI/CD pipeline
-EOF
-```
-
-### Method 3: Input Redirection
-
-You can redirect input from a file:
-
-```bash
-# Create a note from file content
-basic-memory tools write-note --title "Meeting Notes" --folder "meetings" < meeting_notes.md
-```
+See the [justfile](justfile) for the complete list of development commands.
 
 ## License
 
 AGPL-3.0
 
-Built with ♥️ by Basic Machines
+Contributions are welcome. See the [Contributing](CONTRIBUTING.md) guide for info about setting up the project locally
+and submitting PRs.
+
+## Star History
+
+<a href="https://www.star-history.com/#basicmachines-co/basic-memory&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=basicmachines-co/basic-memory&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=basicmachines-co/basic-memory&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=basicmachines-co/basic-memory&type=Date" />
+ </picture>
+</a>
+
+Built with ♥️ by Basic Machines

SECURITY.md

@@ -0,0 +1,13 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.x.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+Use this section to tell people how to report a vulnerability.
+
+If you find a vulnerability, please contact hello@basicmachines.co

claude-code-plugin/.claude-plugin/marketplace.json

@@ -0,0 +1,23 @@
+{
+  "name": "basicmachines",
+  "owner": {
+    "name": "Basic Machines",
+    "email": "hello@basicmachines.co"
+  },
+  "metadata": {
+    "description": "Official plugins from Basic Machines for knowledge management and AI-assisted development",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "basic-memory",
+      "source": ".",
+      "description": "Skills, commands, and hooks for Basic Memory MCP - capture knowledge, continue conversations, and follow spec-driven development",
+      "version": "0.1.0",
+      "author": {
+        "name": "Basic Machines"
+      },
+      "keywords": ["memory", "knowledge", "mcp", "specs", "context"]
+    }
+  ]
+}

claude-code-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "basic-memory",
+  "description": "Claude Code skills for Basic Memory - capture knowledge, continue conversations, and follow spec-driven development using the Basic Memory MCP server",
+  "version": "0.1.0",
+  "author": {
+    "name": "Basic Machines"
+  },
+  "repository": "https://github.com/basicmachines-co/basic-memory"
+}

claude-code-plugin/PLUGIN.md

@@ -0,0 +1,313 @@
+# Basic Memory Plugin for Claude Code
+
+This plugin provides skills, commands, and hooks for working with [Basic Memory](https://basicmemory.io) - a local-first knowledge management system built on the Model Context Protocol (MCP).
+
+## Prerequisites
+
+You need the Basic Memory MCP server running. Install it via:
+
+```bash
+# Install basic-memory
+pip install basic-memory
+
+# Or with pipx
+pipx install basic-memory
+```
+
+Then add it to your Claude Code MCP configuration.
+
+## Installation
+
+### Add the Marketplace
+
+```
+/plugin marketplace add basicmachines-co/basic-memory/claude-code-plugin
+```
+
+### Install the Plugin
+
+```
+/plugin install basic-memory@basicmachines
+```
+
+### Or via Repository Settings
+
+Add to your `.claude/settings.json`:
+
+```json
+{
+  "plugins": {
+    "extraKnownMarketplaces": {
+      "basicmachines": {
+        "source": {
+          "source": "github",
+          "repo": "basicmachines-co/basic-memory",
+          "path": "claude-code-plugin"
+        }
+      }
+    },
+    "installed": ["basic-memory@basicmachines"]
+  }
+}
+```
+
+---
+
+## Slash Commands
+
+User-invoked commands for explicit interaction with Basic Memory.
+
+### `/remember [title] [folder]`
+
+Capture insights, decisions, or learnings from the current conversation.
+
+```
+/remember "FastAPI Async Pattern"
+/remember "Auth Decision" decisions
+```
+
+Creates a structured note with:
+- Context from the conversation
+- Observations with `[decision]`, `[insight]`, `[pattern]` categories
+- Relations linking to related concepts
+
+### `/continue [topic]`
+
+Resume previous work by building context from Basic Memory.
+
+```
+/continue postgres migration
+/continue SPEC-24
+/continue
+```
+
+If no topic is provided, shows recent activity and asks what to dive into.
+
+### `/context <memory://url> [depth] [timeframe]`
+
+Build context from a specific memory:// URL.
+
+```
+/context memory://SPEC-24
+/context memory://architecture/* 3 2weeks
+```
+
+### `/recent [timeframe] [project]`
+
+Show recent activity in Basic Memory.
+
+```
+/recent
+/recent 1week
+/recent today specs
+```
+
+### `/organize [action] [project]`
+
+Organize and maintain your knowledge graph.
+
+```
+/organize                    # Quick health check
+/organize orphans            # Find unlinked notes
+/organize duplicates         # Find similar notes
+/organize relations "Note"   # Suggest links for a note
+/organize tags               # Review tag consistency
+```
+
+Actions:
+- `health` - Overview of knowledge base status (default)
+- `orphans` - Find notes with no relations
+- `duplicates` - Find overlapping notes
+- `relations` - Suggest connections
+- `tags` - Review tag consistency
+
+### `/research <topic> [folder]`
+
+Research a topic and save a structured report to Basic Memory.
+
+```
+/research MCP protocol
+/research "database migrations"
+/research "auth options" decisions
+```
+
+Produces a report with:
+- Summary and key findings
+- Analysis and recommendations
+- Sources and related notes
+- Saved to `research/` folder by default
+
+---
+
+## Skills
+
+Model-invoked capabilities that Claude uses automatically based on context.
+
+### knowledge-capture
+
+Automatically captures insights, decisions, and learnings into structured notes.
+
+**Triggers when:**
+- Important decisions are made
+- Technical insights are discovered
+- Problems are solved
+- Design trade-offs are discussed
+
+### continue-conversation
+
+Resumes previous work by building context from the knowledge graph.
+
+**Triggers when:**
+- Starting a new session
+- User mentions previous work ("continue with...", "back to...")
+- Need context about ongoing projects
+
+### spec-driven-development
+
+Guides implementation based on specifications stored in Basic Memory.
+
+**Triggers when:**
+- Implementing a feature defined by a spec
+- Creating new specifications
+- Reviewing implementation against criteria
+
+### edit-note
+
+Interactively edit notes using MCP tools in a conversational workflow.
+
+**Triggers when:**
+- User wants to edit, update, or modify a note
+- User asks to change specific content in a note
+- User wants to add observations or relations
+
+**How it works:**
+1. Fetches the note via MCP
+2. Shows current content
+3. Applies edits using `edit_note` operations (append, prepend, find_replace, replace_section)
+4. Shows the updated result
+
+**Best for:** Cloud users or when you want conversational editing.
+
+### edit-note-local
+
+Edit notes directly as local markdown files with automatic sync.
+
+**Triggers when:**
+- User has local Basic Memory installation
+- User wants to make substantial file edits
+- User prefers working with full file content
+
+**How it works:**
+1. Finds the note's file path via MCP
+2. Uses Claude Code's Read/Edit/Write tools on the actual file
+3. Basic Memory's `sync --watch` picks up changes automatically
+
+**Best for:** Local users who want full file access and git integration.
+
+### knowledge-organize
+
+Help organize, link, and maintain the knowledge graph.
+
+**Triggers when:**
+- User wants to organize their notes
+- User asks about orphan or unlinked notes
+- User wants to find connections between notes
+- User mentions duplicates or similar notes
+- User asks for help with folder organization
+
+**Capabilities:**
+- **Find orphan notes** - Identify notes with no relations
+- **Suggest relations** - Propose meaningful links between notes
+- **Identify duplicates** - Find notes covering similar topics
+- **Folder organization** - Review and suggest folder structure
+- **Tag consistency** - Normalize and improve tagging
+- **Create index notes** - Generate hub notes linking related topics
+- **Enrich sparse notes** - Suggest observations and structure
+
+**Best for:** Periodic knowledge base maintenance and improving discoverability.
+
+### research
+
+Research topics thoroughly and produce structured reports saved to Basic Memory.
+
+**Triggers when:**
+- User asks to research or investigate something
+- User wants to understand a concept or technology
+- User needs context before making a decision
+- Phrases like "research", "look into", "explore", "investigate"
+
+**What it produces:**
+- Structured report with summary, findings, and analysis
+- Recommendations when applicable
+- Links to sources and related notes
+- Saved to `research/` folder
+
+**Best for:** Building knowledge base through investigation and documentation.
+
+---
+
+## Hooks
+
+Automated behaviors that enhance the Basic Memory workflow.
+
+### PostToolUse: write_note
+
+Confirms when notes are saved to Basic Memory.
+
+### Stop
+
+After significant conversations, suggests using `/remember` to capture valuable insights (only when genuinely useful).
+
+---
+
+## MCP Tools Used
+
+This plugin leverages Basic Memory's MCP tools:
+
+| Tool | Purpose |
+|------|---------|
+| `write_note` | Create/update markdown notes |
+| `read_note` | Read notes by title or permalink |
+| `search_notes` | Full-text search across content |
+| `build_context` | Navigate knowledge graph via memory:// URLs |
+| `recent_activity` | Get recently updated information |
+| `edit_note` | Incrementally update notes |
+
+---
+
+## Plugin Structure
+
+```
+claude-code-plugin/
+├── .claude-plugin/
+│   ├── plugin.json          # Plugin manifest
+│   └── marketplace.json     # Self-hosted marketplace
+├── commands/
+│   ├── remember.md          # /remember command
+│   ├── continue.md          # /continue command
+│   ├── context.md           # /context command
+│   ├── recent.md            # /recent command
+│   ├── organize.md          # /organize command
+│   └── research.md          # /research command
+├── skills/
+│   ├── knowledge-capture/
+│   ├── continue-conversation/
+│   ├── spec-driven-development/
+│   ├── edit-note/
+│   ├── edit-note-local/
+│   ├── knowledge-organize/
+│   └── research/
+├── hooks/
+│   └── hooks.json           # Hook definitions
+├── README.md                # Quick start guide
+└── PLUGIN.md                # Full documentation
+```
+
+---
+
+## Related
+
+- [Basic Memory Documentation](https://docs.basicmemory.io)
+- [Basic Memory GitHub](https://github.com/basicmachines-co/basic-memory)
+- [Model Context Protocol](https://modelcontextprotocol.io)
+- [Claude Code Plugins](https://code.claude.com/docs/en/plugins)

claude-code-plugin/README.md

@@ -0,0 +1,100 @@
+# Basic Memory Plugin for Claude Code
+
+A Claude Code plugin that integrates [Basic Memory](https://basicmemory.io) - a local-first knowledge management system built on the Model Context Protocol (MCP).
+
+## What This Plugin Does
+
+This plugin helps Claude Code work seamlessly with your Basic Memory knowledge base:
+
+- **Capture knowledge** from conversations automatically
+- **Resume previous work** by building context from your knowledge graph
+- **Edit notes** interactively through conversation
+- **Organize your knowledge** by finding orphans, suggesting links, and maintaining structure
+
+## Installation
+
+### 1. Install Basic Memory
+
+```bash
+pip install basic-memory
+# or
+pipx install basic-memory
+```
+
+### 2. Add the Marketplace
+
+```
+/plugin marketplace add basicmachines-co/basic-memory/claude-code-plugin
+```
+
+### 3. Install the Plugin
+
+```
+/plugin install basic-memory@basicmachines
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/remember [title]` | Capture insights from the current conversation |
+| `/continue [topic]` | Resume previous work with context |
+| `/context <memory://url>` | Build context from a specific note |
+| `/recent [timeframe]` | Show recent activity |
+| `/organize [action]` | Maintain your knowledge graph |
+| `/research <topic>` | Research a topic and save a report |
+
+### Examples
+
+```bash
+# Capture what we just discussed
+/remember "Database Design Decision"
+
+# Pick up where we left off
+/continue postgres migration
+
+# Check recent changes
+/recent 1week
+
+# Find orphan notes and suggest links
+/organize orphans
+
+# Research a topic and save findings
+/research "MCP protocol"
+```
+
+## Skills
+
+Skills are model-invoked - Claude uses them automatically when the context fits.
+
+| Skill | What It Does |
+|-------|--------------|
+| `knowledge-capture` | Auto-captures decisions and insights into structured notes |
+| `continue-conversation` | Builds context when resuming previous work |
+| `spec-driven-development` | Guides implementation based on specs in Basic Memory |
+| `edit-note` | Edits notes via MCP tools (cloud-compatible) |
+| `edit-note-local` | Edits notes as files (local installations) |
+| `knowledge-organize` | Helps organize and link notes |
+| `research` | Researches topics and produces saved reports |
+
+## Hooks
+
+| Event | Behavior |
+|-------|----------|
+| `PostToolUse: write_note` | Confirms when notes are saved |
+| `Stop` | Suggests capturing valuable insights after conversations |
+
+## Requirements
+
+- [Claude Code](https://claude.com/claude-code)
+- [Basic Memory](https://basicmemory.io) with MCP server configured
+
+## Documentation
+
+- [Full Plugin Documentation](./PLUGIN.md)
+- [Basic Memory Docs](https://docs.basicmemory.io)
+- [Claude Code Plugins](https://code.claude.com/docs/en/plugins)
+
+## License
+
+MIT - See the [Basic Memory repository](https://github.com/basicmachines-co/basic-memory) for details.

claude-code-plugin/commands/context.md

@@ -0,0 +1,39 @@
+---
+description: Build context from a Basic Memory URL
+argument-hint: <memory://url> [depth] [timeframe]
+allowed-tools: mcp__basic-memory__build_context, mcp__basic-memory__read_note
+---
+
+# Context
+
+Build context from a Basic Memory memory:// URL.
+
+## Arguments
+
+- `$1` - Memory URL (e.g., `memory://topic`, `memory://folder/*`, `memory://SPEC-24`)
+- `$2` - Depth of relation traversal (optional, default: 2)
+- `$3` - Timeframe for recent changes (optional, default: "7d")
+
+## Your Task
+
+Navigate the knowledge graph and build comprehensive context.
+
+1. **Build context** using `mcp__basic-memory__build_context`:
+   - url: "$1"
+   - depth: $2 or 2
+   - timeframe: "$3" or "7d"
+
+2. **Present the context**:
+   - Main note content
+   - Related notes found via relations
+   - Recent changes within timeframe
+   - Key observations and decisions
+
+3. **Read additional notes** if needed for more detail.
+
+## Memory URL Formats
+
+- `memory://note-title` - Single note by title
+- `memory://folder/*` - All notes in a folder
+- `memory://SPEC-*` - Pattern matching
+- `memory://specs/SPEC-24` - Note in specific project folder

claude-code-plugin/commands/continue.md

@@ -0,0 +1,46 @@
+---
+description: Resume previous work from Basic Memory context
+argument-hint: [topic]
+allowed-tools: mcp__basic-memory__build_context, mcp__basic-memory__recent_activity, mcp__basic-memory__search_notes, mcp__basic-memory__read_note
+---
+
+# Continue
+
+Resume previous work by building context from Basic Memory.
+
+## Arguments
+
+- `$ARGUMENTS` - Topic, note title, or search terms to find previous context
+
+## Your Task
+
+Build context to continue previous work seamlessly.
+
+1. **Find relevant context**:
+
+   If a specific topic is provided ("$ARGUMENTS"):
+   - Search for matching notes: `mcp__basic-memory__search_notes`
+   - Build context from matches: `mcp__basic-memory__build_context`
+   - Read key notes for details: `mcp__basic-memory__read_note`
+
+   If no topic provided:
+   - Get recent activity: `mcp__basic-memory__recent_activity` with timeframe "3d"
+   - Present what's been happening
+   - Ask which topic to dive into
+
+2. **Present context**:
+   - Summarize current state of the work
+   - Highlight recent changes or progress
+   - List open items or next steps
+   - Show related context from the knowledge graph
+
+3. **Be ready to continue**:
+   - Understand what was done before
+   - Know what needs to happen next
+   - Have relevant context loaded
+
+## Tips
+
+- Use `memory://topic` URL format with `build_context`
+- Check multiple projects if needed (main, specs)
+- Follow relations to find connected knowledge

claude-code-plugin/commands/organize.md

@@ -0,0 +1,87 @@
+---
+description: Organize and maintain your Basic Memory knowledge graph
+argument-hint: [health|orphans|duplicates|relations|tags] [project]
+allowed-tools: mcp__basic-memory__search_notes, mcp__basic-memory__read_note, mcp__basic-memory__list_directory, mcp__basic-memory__edit_note, mcp__basic-memory__write_note
+---
+
+# Organize
+
+Help organize, link, and maintain your Basic Memory knowledge graph.
+
+## Arguments
+
+- `$1` - Action (optional): `health`, `orphans`, `duplicates`, `relations`, `tags` (default: `health`)
+- `$2` - Project (optional): defaults to "main"
+
+## Actions
+
+### `/organize` or `/organize health`
+
+Run a quick health check:
+1. Count total notes
+2. Identify orphan notes (no relations)
+3. Check for potential duplicates
+4. Show folder distribution
+5. Report any issues found
+
+### `/organize orphans`
+
+Find and address orphan notes:
+1. Search for notes with empty Relations sections
+2. List orphans found
+3. For each orphan, suggest potential relations based on content
+4. Offer to add relations or create index notes
+
+### `/organize duplicates`
+
+Find potentially duplicate notes:
+1. Search for notes with similar titles
+2. Compare content for overlap
+3. Suggest: merge, differentiate, or link with `supersedes`
+
+### `/organize relations [note-title]`
+
+Suggest relations for a specific note (or recent notes if not specified):
+1. Read the target note
+2. Search for related content
+3. Suggest relation types:
+   - `relates-to` - General connection
+   - `extends` - Builds upon
+   - `implements` - Realizes concept
+   - `depends-on` - Requires understanding of
+4. Offer to add selected relations
+
+### `/organize tags`
+
+Review tag consistency:
+1. Gather all tags across notes
+2. Find similar/duplicate tags (e.g., `arch` vs `architecture`)
+3. Identify over-used or under-used tags
+4. Suggest normalization
+
+## Your Task
+
+Execute: `/organize $ARGUMENTS`
+
+Based on the action requested:
+
+1. **Gather data** using search and list tools
+2. **Analyze** for the specific issue (orphans, duplicates, etc.)
+3. **Present findings** clearly with counts and examples
+4. **Offer solutions** - ask before making changes
+5. **Apply fixes** using edit_note or write_note when user approves
+
+Always confirm before modifying notes. Show what will change and get approval.
+
+## Examples
+
+```
+/organize                    # Quick health check
+/organize health             # Same as above
+/organize orphans            # Find unlinked notes
+/organize duplicates         # Find similar notes
+/organize relations          # Suggest links for recent notes
+/organize relations "My Note" # Suggest links for specific note
+/organize tags               # Review tag consistency
+/organize health specs       # Health check on specs project
+```

claude-code-plugin/commands/recent.md

@@ -0,0 +1,40 @@
+---
+description: Show recent activity in Basic Memory
+argument-hint: [timeframe] [project]
+allowed-tools: mcp__basic-memory__recent_activity, mcp__basic-memory__read_note
+---
+
+# Recent
+
+Show recent activity in Basic Memory.
+
+## Arguments
+
+- `$1` - Timeframe (optional): "today", "1d", "3d", "1 week", "2 weeks" (default: "3d")
+- `$2` - Project (optional): "main", "specs", etc.
+
+## Your Task
+
+Show what's been happening in Basic Memory recently.
+
+1. **Get recent activity** using `mcp__basic-memory__recent_activity`:
+   - timeframe: "$1" or "3d"
+   - project: "$2" or check all projects
+
+2. **Present activity**:
+   - List recently modified notes
+   - Group by type or folder if helpful
+   - Highlight key changes
+   - Show dates of modifications
+
+3. **Offer to dive deeper**:
+   - Ask if user wants to read any specific notes
+   - Suggest continuing work on active items
+
+## Timeframe Examples
+
+- `today` - Just today
+- `1d` or `yesterday` - Last 24 hours
+- `3d` - Last 3 days
+- `1 week` - Last week
+- `2 weeks` - Last 2 weeks

claude-code-plugin/commands/remember.md

@@ -0,0 +1,43 @@
+---
+description: Capture insights, decisions, or learnings to Basic Memory
+argument-hint: [title] [optional: folder]
+allowed-tools: mcp__basic-memory__write_note, mcp__basic-memory__search_notes
+---
+
+# Remember
+
+Capture what we just discussed into a Basic Memory note.
+
+## Arguments
+
+- `$1` - Title for the note (required)
+- `$2` - Folder to save in (optional, defaults to "notes")
+
+## Your Task
+
+Create a structured note capturing the key insights from our conversation.
+
+1. **Analyze the conversation** for:
+   - Decisions made
+   - Insights discovered
+   - Problems solved
+   - Patterns identified
+   - Trade-offs discussed
+
+2. **Structure the note** with:
+   - Clear title: "$1" (or generate one if not provided)
+   - Context section explaining the situation
+   - Main content with key points
+   - Observations using `[category]` format:
+     - `[decision]` - Choices made
+     - `[insight]` - Understanding gained
+     - `[pattern]` - Reusable approaches
+     - `[learning]` - Lessons learned
+   - Relations to link related concepts with `[[WikiLinks]]`
+
+3. **Save using** `mcp__basic-memory__write_note`:
+   - folder: "$2" or "notes"
+   - Include relevant tags
+   - Project: use "main" unless user specifies otherwise
+
+4. **Confirm** what was captured and where it was saved.

claude-code-plugin/commands/research.md

@@ -0,0 +1,140 @@
+---
+description: Research a topic and save a structured report to Basic Memory
+argument-hint: <topic> [folder]
+allowed-tools: mcp__basic-memory__write_note, mcp__basic-memory__search_notes, mcp__basic-memory__read_note, mcp__basic-memory__build_context, WebSearch, WebFetch, Grep, Glob, Read
+---
+
+# Research
+
+Research a topic thoroughly and produce a structured report saved to Basic Memory.
+
+## Arguments
+
+- `$1` - Topic to research (required)
+- `$2` - Folder to save report (optional, default: "research")
+
+## Your Task
+
+Conduct thorough research on: **$ARGUMENTS**
+
+### 1. Check Existing Knowledge
+
+First, see what we already know:
+```python
+mcp__basic-memory__search_notes(query="$1", project="main")
+```
+
+Read any relevant existing notes to avoid duplicating research.
+
+### 2. Gather Information
+
+Depending on the topic, use appropriate tools:
+
+**For codebase topics:**
+- Search code with Grep/Glob
+- Read relevant files
+- Check tests for examples
+
+**For external topics:**
+- Use WebSearch for current information
+- Fetch documentation with WebFetch
+- Look for official sources
+
+**For Basic Memory context:**
+- Build context from related notes
+- Check for prior decisions or research
+
+### 3. Analyze Findings
+
+Synthesize what you learned:
+- Identify key concepts
+- Note patterns and trade-offs
+- Form recommendations if applicable
+- Flag uncertainties
+
+### 4. Produce Report
+
+Create a structured report with this format:
+
+```markdown
+---
+title: "Research: [Topic]"
+type: research
+tags:
+- research
+- [relevant-tags]
+---
+
+# Research: [Topic]
+
+## Summary
+
+[2-3 sentence executive summary]
+
+## Research Question
+
+[What we investigated and why]
+
+## Key Findings
+
+### [Finding 1]
+[Details and evidence]
+
+### [Finding 2]
+[Details and evidence]
+
+### [Finding 3]
+[Details and evidence]
+
+## Analysis
+
+[Synthesis, patterns, trade-offs, recommendations]
+
+## Open Questions
+
+- [Areas needing more investigation]
+
+## Sources
+
+- [Links to sources]
+- [[Related Notes]] from Basic Memory
+
+## Observations
+
+- [finding] Key insight #research
+- [recommendation] Suggested approach based on research
+
+## Relations
+
+- researches [[Topic]]
+- relates-to [[Related Concepts]]
+```
+
+### 5. Save Report
+
+```python
+mcp__basic-memory__write_note(
+    title="Research: $1",
+    content="[report content]",
+    folder="$2" or "research",
+    tags=["research", ...],
+    project="main"
+)
+```
+
+### 6. Present Summary
+
+After saving, present:
+- Key findings summary
+- Main recommendation (if applicable)
+- Where the report was saved
+- Offer to dive deeper into any aspect
+
+## Examples
+
+```
+/research MCP protocol
+/research "database migration patterns"
+/research "authentication options" decisions
+/research "React vs Vue" architecture
+```

claude-code-plugin/hooks/hooks.json

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "mcp__basic-memory__write_note",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '✓ Note saved to Basic Memory'"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "If this conversation contained valuable insights, decisions, or learnings that should be preserved, suggest using `/remember [title]` to capture them in Basic Memory. Only suggest this if there's genuinely valuable content worth preserving - don't suggest for trivial interactions."
+          }
+        ]
+      }
+    ]
+  }
+}

claude-code-plugin/skills/continue-conversation/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: continue-conversation
+description: Resume previous work by building context from Basic Memory knowledge graph using memory URLs and recent activity
+---
+
+# Continue Conversation
+
+This skill helps you resume previous work by building context from the Basic Memory knowledge graph, enabling seamless continuation across sessions.
+
+## When to Use
+
+Use this skill when:
+- Starting a new session and need to pick up where you left off
+- User mentions previous work ("continue with...", "back to...", "where were we with...")
+- Need context about ongoing projects or specs
+- User asks about something discussed in a previous conversation
+- Working on a multi-session task
+
+## Building Context
+
+### 1. Identify What to Continue
+
+Ask if unclear:
+- What topic or project to resume?
+- What timeframe to look at?
+- Any specific aspect to focus on?
+
+### 2. Gather Context with MCP Tools
+
+**Option A: Known Topic - Use build_context**
+
+```python
+# Navigate knowledge graph from a known starting point
+mcp__basic-memory__build_context(
+    url="memory://topic-or-note-name",
+    depth=2,           # How many relation hops to follow
+    timeframe="7d",    # Recent changes
+    project="main"     # or "specs" for specifications
+)
+```
+
+Memory URL formats:
+- `memory://note-title` - Single note
+- `memory://folder/*` - All notes in folder
+- `memory://specs/SPEC-24*` - Pattern matching
+
+**Option B: Recent Activity - What's been happening?**
+
+```python
+# See what's changed recently
+mcp__basic-memory__recent_activity(
+    timeframe="3d",    # "1d", "1 week", "2 weeks"
+    depth=1,
+    project="main"
+)
+```
+
+**Option C: Search for Context**
+
+```python
+# Find relevant notes
+mcp__basic-memory__search_notes(
+    query="search terms",
+    page_size=10,
+    project="main"
+)
+```
+
+### 3. Read Key Notes
+
+Once you identify relevant notes:
+
+```python
+mcp__basic-memory__read_note(
+    identifier="note-title-or-permalink",
+    project="main"
+)
+```
+
+### 4. Present Context to User
+
+Summarize what you found:
+- Current state of the work
+- Recent changes or progress
+- Open items or next steps
+- Related context that might be helpful
+
+## Context Strategies by Scenario
+
+### Resuming a Spec Implementation
+
+```python
+# 1. Read the spec
+mcp__basic-memory__read_note(
+    identifier="SPEC-24: Postgres Database Migration",
+    project="specs"
+)
+
+# 2. Check recent activity on related topics
+mcp__basic-memory__build_context(
+    url="memory://SPEC-24*",
+    timeframe="7d",
+    project="specs"
+)
+
+# 3. Look at what's been done in the codebase
+# (Use regular file tools for this)
+```
+
+### Continuing General Work
+
+```python
+# 1. Check recent activity across projects
+mcp__basic-memory__recent_activity(
+    timeframe="3d",
+    project="main"
+)
+
+# 2. Read any notes from recent sessions
+mcp__basic-memory__read_note(
+    identifier="relevant-note",
+    project="main"
+)
+```
+
+### Following Up on a Topic
+
+```python
+# 1. Search for the topic
+mcp__basic-memory__search_notes(
+    query="topic keywords",
+    project="main"
+)
+
+# 2. Build context from best match
+mcp__basic-memory__build_context(
+    url="memory://found-note-permalink",
+    depth=2,
+    project="main"
+)
+```
+
+## Timeframe Reference
+
+Natural language timeframes:
+- `"today"` - Current day
+- `"yesterday"` - Previous day
+- `"3d"` or `"3 days"` - Last 3 days
+- `"1 week"` or `"7d"` - Last week
+- `"2 weeks"` - Last 2 weeks
+- `"1 month"` - Last month
+
+## Project Reference
+
+Common projects:
+- `main` - Primary knowledge base
+- `specs` - Specifications and design docs
+- `basic-memory-llc` - Business/company notes
+- `getting-started` - Tutorial content
+
+List available projects:
+```python
+mcp__basic-memory__list_memory_projects()
+```
+
+## Example Conversations
+
+### User: "Let's continue with the Postgres migration"
+
+```
+1. Read SPEC-24 from specs project
+2. Check for related notes about implementation progress
+3. Summarize:
+   - Spec overview and goals
+   - What's been completed (checkmarks)
+   - What's pending (checkboxes)
+   - Any blockers or decisions needed
+```
+
+### User: "What was I working on yesterday?"
+
+```
+1. Get recent activity for last 2 days
+2. List modified notes with brief descriptions
+3. Ask which topic to dive into
+```
+
+### User: "Back to the async client pattern"
+
+```
+1. Search for "async client pattern"
+2. Build context from matching note
+3. Include related notes via relations
+4. Present the full picture
+```
+
+## Best Practices
+
+1. **Start broad, then narrow** - Get overview first, then specific details
+2. **Follow relations** - Knowledge graph connections are valuable
+3. **Check multiple projects** - Specs might be separate from implementation notes
+4. **Present incrementally** - Share what you find as you go
+5. **Confirm understanding** - Verify the context is what user needs
+6. **Update as you go** - Capture new progress in notes during the session
+
+## Combining with Other Skills
+
+After building context, you might:
+- Use **knowledge-capture** to document new progress
+- Use **spec-driven-development** if continuing a spec implementation
+- Create new notes linking to the context you gathered

claude-code-plugin/skills/edit-note-local/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: edit-note-local
+description: Edit Basic Memory notes directly as local files - enables full file editing with automatic sync (local installations only)
+---
+
+# Edit Note Local
+
+This skill enables direct file-based editing of Basic Memory notes. It works by editing the actual markdown files in the knowledge base, which Basic Memory's sync service automatically picks up. This provides a more seamless editing experience for local installations.
+
+## When to Use
+
+Use this skill when:
+- User has a local Basic Memory installation (not cloud-only)
+- User wants to make substantial edits to a note
+- User prefers working with the full file content
+- User wants changes to sync automatically via `basic-memory sync --watch`
+
+**Note:** This skill requires local file access. For cloud-only users, use the `edit-note` skill instead.
+
+## Editing Workflow
+
+### 1. Find the Note's File Path
+
+First, get the note metadata to find its file location:
+
+```python
+# Search for the note
+mcp__basic-memory__search_notes(
+    query="note title or keywords",
+    project="main"
+)
+
+# Read the note to get file_path from metadata
+mcp__basic-memory__read_note(
+    identifier="note-title",
+    project="main"
+)
+```
+
+The response includes `file_path` which gives the relative path within the knowledge base.
+
+### 2. Determine Full File Path
+
+Basic Memory projects have a root directory. Common locations:
+- Default: `~/basic-memory/`
+- Custom: Check project configuration
+
+Construct the full path:
+```
+{project_root}/{file_path}
+```
+
+For example:
+- Project root: `/Users/username/basic-memory`
+- File path from note: `notes/My Note.md`
+- Full path: `/Users/username/basic-memory/notes/My Note.md`
+
+### 3. Read the File
+
+Use Claude Code's Read tool to get the full file content:
+
+```python
+Read(file_path="/Users/username/basic-memory/notes/My Note.md")
+```
+
+Display the content to the user, explaining the structure:
+- Frontmatter (YAML between `---` markers)
+- Main content
+- Observations section
+- Relations section
+
+### 4. Edit the File
+
+Use Claude Code's Edit tool for precise changes:
+
+```python
+Edit(
+    file_path="/Users/username/basic-memory/notes/My Note.md",
+    old_string="text to replace",
+    new_string="new text"
+)
+```
+
+Or use Write for complete rewrites:
+
+```python
+Write(
+    file_path="/Users/username/basic-memory/notes/My Note.md",
+    content="Complete new file content..."
+)
+```
+
+### 5. Sync Happens Automatically
+
+If the user has `basic-memory sync --watch` running, changes are picked up automatically. Otherwise, they can run:
+```bash
+basic-memory sync
+```
+
+## File Structure Reference
+
+Basic Memory notes follow this markdown structure:
+
+```markdown
+---
+title: Note Title
+type: note
+permalink: note-title
+tags:
+- tag1
+- tag2
+---
+
+# Note Title
+
+## Context
+
+Background and situation explanation.
+
+## Main Content
+
+The primary content of the note...
+
+## Observations
+
+- [category] Observation text #optional-tag
+- [decision] A decision that was made #tag
+- [insight] An insight discovered
+
+## Relations
+
+- relates-to [[Other Note]]
+- implements [[Parent Concept]]
+- learned-from [[Source Note]]
+```
+
+## Editing Patterns
+
+### Edit Frontmatter Tags
+
+```python
+Edit(
+    file_path="/path/to/note.md",
+    old_string="tags:\n- old-tag",
+    new_string="tags:\n- old-tag\n- new-tag"
+)
+```
+
+### Add New Section
+
+```python
+Edit(
+    file_path="/path/to/note.md",
+    old_string="## Observations",
+    new_string="## New Section\n\nNew content here.\n\n## Observations"
+)
+```
+
+### Modify Observation
+
+```python
+Edit(
+    file_path="/path/to/note.md",
+    old_string="- [decision] Old decision",
+    new_string="- [decision] Updated decision with new info #updated"
+)
+```
+
+### Add Relation
+
+```python
+Edit(
+    file_path="/path/to/note.md",
+    old_string="## Relations\n",
+    new_string="## Relations\n\n- relates-to [[New Related Note]]\n"
+)
+```
+
+### Complete Rewrite
+
+For major changes, read the file, construct new content preserving the frontmatter structure, and write:
+
+```python
+Write(
+    file_path="/path/to/note.md",
+    content="""---
+title: Note Title
+type: note
+permalink: note-title
+tags:
+- updated
+---
+
+# Note Title
+
+Completely rewritten content...
+
+## Observations
+
+- [rewrite] Complete rewrite of this note #major-update
+
+## Relations
+
+- updates [[Previous Version]]
+"""
+)
+```
+
+## Finding the Project Root
+
+To find where Basic Memory stores files, you can:
+
+1. **Check common locations:**
+   - `~/basic-memory/`
+   - `~/Documents/basic-memory/`
+   - Current working directory
+
+2. **Use the list_directory tool:**
+   ```python
+   mcp__basic-memory__list_directory(
+       dir_name="/",
+       project="main"
+   )
+   ```
+
+3. **Ask the user:** "Where is your Basic Memory knowledge base located?"
+
+## Advantages of Local Editing
+
+1. **Full file access** - Edit any part of the file including frontmatter
+2. **Multi-line edits** - Make complex structural changes easily
+3. **Batch operations** - Edit multiple files in sequence
+4. **Version control** - Changes tracked by git if the folder is a repo
+5. **Instant preview** - Use any markdown editor alongside
+6. **Auto-sync** - `sync --watch` picks up changes automatically
+
+## Best Practices
+
+1. **Preserve frontmatter** - Don't break the YAML structure
+2. **Keep valid markdown** - Maintain proper formatting
+3. **Preserve permalinks** - Changing them can break links
+4. **Show diffs** - Tell the user what changed
+5. **Suggest sync** - Remind about `basic-memory sync` if not watching
+6. **Handle missing files** - Check if file exists before editing
+
+## Example Conversation
+
+**User:** "I want to completely rewrite my architecture decision note"
+
+**Claude:**
+1. Searches for the note via MCP
+2. Gets the file path
+3. Reads the current file content
+4. Asks: "Here's the current note. What would you like the new version to say?"
+
+**User:** Provides new content
+
+**Claude:**
+1. Preserves the frontmatter (title, permalink, type)
+2. Writes the new content using Write tool
+3. Confirms: "Updated the file at `/path/to/note.md`. If you have sync --watch running, it's already indexed. Otherwise run `basic-memory sync`."

claude-code-plugin/skills/edit-note/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: edit-note
+description: Interactively edit Basic Memory notes using MCP tools - view, modify, and update notes in a conversational workflow (works with cloud and local)
+---
+
+# Edit Note
+
+This skill enables interactive editing of Basic Memory notes using MCP tools. It works with both Basic Memory Cloud and local installations since it operates through the MCP interface rather than direct file access.
+
+## When to Use
+
+Use this skill when:
+- User wants to edit an existing note
+- User asks to update, change, or modify note content
+- User wants to refine observations or relations in a note
+- User says things like "edit my note about...", "update the...", "change X to Y in..."
+
+## Editing Workflow
+
+### 1. Fetch the Current Note
+
+First, retrieve the note to show the user what exists:
+
+```python
+mcp__basic-memory__read_note(
+    identifier="Note Title or permalink",
+    project="main"  # or specified project
+)
+```
+
+Present the note content clearly, highlighting:
+- Current title and metadata
+- Main content sections
+- Observations (with categories)
+- Relations (with link targets)
+
+### 2. Understand the Edit Request
+
+Ask clarifying questions if needed:
+- Which section to modify?
+- What specifically to change?
+- Add new content or replace existing?
+
+### 3. Apply the Edit
+
+Use the appropriate `edit_note` operation:
+
+**Append** - Add content to the end:
+```python
+mcp__basic-memory__edit_note(
+    identifier="note-title",
+    operation="append",
+    content="\n\n## New Section\n\nNew content here...",
+    project="main"
+)
+```
+
+**Prepend** - Add content to the beginning:
+```python
+mcp__basic-memory__edit_note(
+    identifier="note-title",
+    operation="prepend",
+    content="# Updated Header\n\n",
+    project="main"
+)
+```
+
+**Find and Replace** - Replace specific text:
+```python
+mcp__basic-memory__edit_note(
+    identifier="note-title",
+    operation="find_replace",
+    find_text="old text to find",
+    content="new replacement text",
+    project="main"
+)
+```
+
+**Replace Section** - Replace an entire section by heading:
+```python
+mcp__basic-memory__edit_note(
+    identifier="note-title",
+    operation="replace_section",
+    section="## Section Heading",
+    content="## Section Heading\n\nCompletely new section content...",
+    project="main"
+)
+```
+
+### 4. Show the Result
+
+After editing, fetch and display the updated note:
+
+```python
+mcp__basic-memory__read_note(
+    identifier="note-title",
+    project="main"
+)
+```
+
+Highlight what changed so the user can verify.
+
+## Edit Operations Reference
+
+| Operation | Use Case | Required Parameters |
+|-----------|----------|---------------------|
+| `append` | Add to end | `content` |
+| `prepend` | Add to beginning | `content` |
+| `find_replace` | Change specific text | `find_text`, `content` |
+| `replace_section` | Rewrite a section | `section`, `content` |
+
+## Common Edit Patterns
+
+### Adding a New Observation
+
+```python
+mcp__basic-memory__edit_note(
+    identifier="note-title",
+    operation="find_replace",
+    find_text="## Observations",
+    content="## Observations\n\n- [new-category] New observation here #tag",
+    project="main"
+)
+```
+
+Or append to observations section:
+```python
+mcp__basic-memory__edit_note(
+    identifier="note-title",
+    operation="append",
+    content="\n- [insight] Additional insight discovered #tag",
+    project="main"
+)
+```
+
+### Adding a New Relation
+
+```python
+mcp__basic-memory__edit_note(
+    identifier="note-title",
+    operation="find_replace",
+    find_text="## Relations",
+    content="## Relations\n\n- relates-to [[New Related Note]]",
+    project="main"
+)
+```
+
+### Updating a Specific Observation
+
+```python
+mcp__basic-memory__edit_note(
+    identifier="note-title",
+    operation="find_replace",
+    find_text="- [decision] Old decision text",
+    content="- [decision] Updated decision with new context #updated",
+    project="main"
+)
+```
+
+### Rewriting the Context Section
+
+```python
+mcp__basic-memory__edit_note(
+    identifier="note-title",
+    operation="replace_section",
+    section="## Context",
+    content="## Context\n\nCompletely rewritten context explaining the new situation...",
+    project="main"
+)
+```
+
+## Multi-Step Editing Session
+
+For complex edits, work iteratively:
+
+1. **Show current state** → Read and display the note
+2. **First edit** → Apply one change
+3. **Show result** → Display updated note
+4. **Next edit** → Apply another change if needed
+5. **Confirm complete** → Final display and confirmation
+
+This keeps the user informed and allows course correction.
+
+## Best Practices
+
+1. **Always show before and after** - User should see what changed
+2. **One edit at a time** - For complex changes, do multiple operations
+3. **Preserve structure** - Maintain the note's markdown format
+4. **Be careful with find_replace** - Ensure the find_text is unique
+5. **Confirm destructive changes** - Ask before replacing large sections
+6. **Keep observations formatted** - Maintain `[category]` prefix format
+7. **Keep relations formatted** - Maintain `- relation-type [[Target]]` format
+
+## Example Conversation
+
+**User:** "Edit my note about the async client pattern - add an observation about testing"
+
+**Claude:**
+1. Fetches "Async Client Pattern" note
+2. Displays current content
+3. Asks: "What observation about testing would you like to add?"
+
+**User:** "That the context manager pattern makes mocking easier in tests"
+
+**Claude:**
+1. Uses `edit_note` with `append` to add:
+   `- [testing] Context manager pattern simplifies mocking in unit tests #testability`
+2. Fetches and displays updated note
+3. Confirms: "Added the testing observation. Here's the updated note..."

claude-code-plugin/skills/knowledge-capture/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: knowledge-capture
+description: Capture insights, decisions, and learnings from conversations into structured Basic Memory notes with observations and relations
+---
+
+# Knowledge Capture
+
+This skill helps you capture valuable information from conversations into Basic Memory's knowledge graph using structured notes with observations and relations.
+
+## When to Use
+
+Use this skill when:
+- Important decisions are made during a conversation
+- Technical insights or patterns are discovered
+- Problems are solved and the solution should be preserved
+- Design trade-offs are discussed
+- Architecture or implementation approaches are chosen
+- Learnings from debugging or investigation emerge
+
+## Capture Process
+
+### 1. Identify Valuable Information
+
+Look for:
+- **Decisions**: Choices made and their rationale
+- **Insights**: New understanding or "aha" moments
+- **Patterns**: Reusable approaches or solutions
+- **Trade-offs**: Options considered and why one was chosen
+- **Learnings**: What worked, what didn't, and why
+- **Context**: Background that would help future understanding
+
+### 2. Structure the Note
+
+Use Basic Memory's knowledge format:
+
+```markdown
+---
+title: Descriptive Title
+type: note
+tags:
+- relevant
+- tags
+---
+
+# Title
+
+## Context
+Brief background explaining the situation.
+
+## Content
+Main content organized logically.
+
+## Observations
+
+- [decision] What was decided and why #tag
+- [insight] Key understanding gained #tag
+- [pattern] Reusable approach identified #tag
+- [learning] What we learned from this #tag
+- [tradeoff] Option A chosen over B because... #tag
+
+## Relations
+
+- relates-to [[Related Concept]]
+- implements [[Parent Spec or Design]]
+- learned-from [[Source of Learning]]
+```
+
+### 3. Choose Appropriate Categories
+
+Common observation categories:
+- `[decision]` - Choices made
+- `[insight]` - Understanding gained
+- `[pattern]` - Reusable approaches
+- `[learning]` - Lessons learned
+- `[tradeoff]` - Options weighed
+- `[problem]` - Issues identified
+- `[solution]` - Fixes applied
+- `[architecture]` - Structural decisions
+- `[implementation]` - Code-level choices
+- `[constraint]` - Limitations discovered
+- `[requirement]` - Needs identified
+
+### 4. Create Meaningful Relations
+
+Link to related knowledge:
+- `relates-to` - General association
+- `implements` - Realizes a spec or design
+- `extends` - Builds upon existing concept
+- `learned-from` - Source of insight
+- `enables` - Makes something possible
+- `depends-on` - Requires another concept
+- `solves` - Addresses a problem
+
+## MCP Tools to Use
+
+```python
+# Write a new note
+mcp__basic-memory__write_note(
+    title="Your Note Title",
+    content="Full markdown content...",
+    folder="appropriate/folder",
+    tags=["tag1", "tag2"],
+    project="main"  # or appropriate project
+)
+
+# Search for related notes to link
+mcp__basic-memory__search_notes(
+    query="relevant terms",
+    project="main"
+)
+
+# Read existing notes for context
+mcp__basic-memory__read_note(
+    identifier="note-title-or-permalink",
+    project="main"
+)
+```
+
+## Folder Organization
+
+Choose appropriate folders:
+- `decisions/` - Architecture and design decisions
+- `learnings/` - Insights and lessons learned
+- `patterns/` - Reusable approaches
+- `debug-logs/` - Problem investigations
+- `conversations/` - Imported conversation summaries
+
+## Examples
+
+### Capturing a Technical Decision
+
+```markdown
+---
+title: FastAPI Async Client Pattern
+type: note
+tags:
+- architecture
+- fastapi
+- async
+---
+
+# FastAPI Async Client Pattern
+
+## Context
+During implementation of MCP tools, we needed to decide how to handle HTTP client lifecycle.
+
+## Decision
+Use context manager pattern for HTTP clients instead of module-level singletons.
+
+## Rationale
+- Proper resource management
+- Supports three deployment modes (local ASGI, CLI cloud, cloud app)
+- Auth happens at client creation, not per-request
+- Enables dependency injection for testing
+
+## Observations
+
+- [decision] Context manager pattern for HTTP clients enables proper resource cleanup #architecture
+- [pattern] Factory pattern allows different client configurations per deployment mode #flexibility
+- [tradeoff] Slightly more verbose than singleton but much more flexible #engineering
+
+## Relations
+
+- implements [[SPEC-16 MCP Cloud Service Consolidation]]
+- enables [[Cloud App Integration]]
+```
+
+### Capturing a Debugging Insight
+
+```markdown
+---
+title: SQLite WAL Mode Performance Fix
+type: note
+tags:
+- debugging
+- sqlite
+- performance
+---
+
+# SQLite WAL Mode Performance Fix
+
+## Problem
+Sync operations were slow with multiple concurrent writes.
+
+## Investigation
+Found that default SQLite journaling was causing lock contention.
+
+## Solution
+Enabled WAL (Write-Ahead Logging) mode for the database connection.
+
+## Observations
+
+- [problem] Default SQLite journaling causes lock contention under concurrent writes #performance
+- [solution] WAL mode significantly improves concurrent write performance #sqlite
+- [learning] Always consider WAL mode for SQLite in applications with concurrent access #database
+
+## Relations
+
+- solves [[Sync Performance Issues]]
+- relates-to [[SPEC-19 Sync Performance]]
+```
+
+## Best Practices
+
+1. **Capture immediately** - Write notes while context is fresh
+2. **Be specific** - Include concrete details, not vague summaries
+3. **Link liberally** - More relations = better knowledge graph
+4. **Use tags** - Enable discovery via search
+5. **Include context** - Future you won't remember the situation
+6. **Prefer facts over opinions** - Observations should be verifiable
+7. **Keep notes atomic** - One concept per note when possible

claude-code-plugin/skills/knowledge-organize/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: knowledge-organize
+description: Help organize, link, and maintain the Basic Memory knowledge graph - find orphan notes, suggest relations, identify duplicates, and improve overall knowledge structure
+---
+
+# Knowledge Organize
+
+This skill helps users maintain a healthy, well-connected knowledge graph. As notes accumulate, it becomes valuable to periodically organize, link, and curate the knowledge base.
+
+## When to Use
+
+Use this skill when:
+- User asks to organize their notes
+- User wants to find connections between notes
+- User mentions orphan or unlinked notes
+- User wants to clean up or improve their knowledge base
+- User asks about duplicate or similar notes
+- User wants help with folder organization
+- User asks to review or audit their notes
+- Phrases like "help me organize", "find related notes", "what's not linked", "clean up my notes"
+
+## Organization Capabilities
+
+### 1. Find Orphan Notes
+
+Identify notes that have no relations to other notes - they're isolated in the knowledge graph.
+
+```python
+# Get all notes
+mcp__basic-memory__search_notes(
+    query="*",
+    page_size=50,
+    project="main"
+)
+
+# For each note, check if it has relations
+# Orphans have empty Relations sections
+```
+
+**What to do with orphans:**
+- Suggest potential relations based on content similarity
+- Ask if they should be linked to existing topics
+- Propose creating hub notes to connect related orphans
+
+### 2. Suggest Relations
+
+Analyze note content and suggest meaningful connections.
+
+```python
+# Read a note
+mcp__basic-memory__read_note(
+    identifier="note-to-analyze",
+    project="main"
+)
+
+# Search for potentially related notes
+mcp__basic-memory__search_notes(
+    query="key terms from the note",
+    project="main"
+)
+
+# Suggest relations based on:
+# - Shared topics or concepts
+# - Complementary content (problem/solution, question/answer)
+# - Sequential relationship (part 1, part 2)
+# - Hierarchical (parent concept, child detail)
+```
+
+**Relation types to suggest:**
+- `relates-to` - General topical connection
+- `extends` - Builds upon or expands
+- `implements` - Realizes a concept
+- `depends-on` - Requires understanding of
+- `contradicts` - Presents alternative view
+- `learned-from` - Source of insight
+- `enables` - Makes something possible
+
+### 3. Identify Similar/Duplicate Notes
+
+Find notes that may cover the same topic.
+
+```python
+# Search for notes with similar titles or content
+mcp__basic-memory__search_notes(
+    query="topic keywords",
+    project="main"
+)
+
+# Compare results for overlap
+# Look for:
+# - Similar titles
+# - Overlapping observations
+# - Same tags
+# - Related timestamps (created around same time)
+```
+
+**Actions for duplicates:**
+- Merge into a single comprehensive note
+- Link them with `supersedes` or `updates` relations
+- Differentiate by adding context about their distinct focus
+
+### 4. Folder Organization Review
+
+Analyze folder structure and suggest improvements.
+
+```python
+# List directory structure
+mcp__basic-memory__list_directory(
+    dir_name="/",
+    depth=3,
+    project="main"
+)
+
+# Identify:
+# - Overcrowded folders
+# - Single-note folders
+# - Inconsistent naming
+# - Notes that might belong elsewhere
+```
+
+**Organization suggestions:**
+- Group related notes into topic folders
+- Create subfolders for large categories
+- Suggest consistent naming conventions
+- Move misplaced notes
+
+### 5. Tag Consistency
+
+Review and normalize tags across notes.
+
+```python
+# Search notes to analyze tag patterns
+mcp__basic-memory__search_notes(
+    query="*",
+    page_size=100,
+    project="main"
+)
+
+# Look for:
+# - Similar tags (architecture vs arch)
+# - Unused tags
+# - Over-used generic tags
+# - Missing tags on relevant notes
+```
+
+**Tag improvements:**
+- Suggest tag standardization (pick one variant)
+- Propose new tags for common themes
+- Identify notes missing obvious tags
+
+### 6. Create Index/Hub Notes
+
+Generate notes that serve as navigation hubs for related topics.
+
+```python
+# After identifying a cluster of related notes
+mcp__basic-memory__write_note(
+    title="Architecture Decisions Index",
+    content="""---
+title: Architecture Decisions Index
+type: index
+tags:
+- architecture
+- index
+---
+
+# Architecture Decisions Index
+
+A hub linking all architecture-related decisions and patterns.
+
+## Decisions
+
+- [[Database Selection Decision]]
+- [[API Design Patterns]]
+- [[Authentication Architecture]]
+
+## Patterns
+
+- [[Repository Pattern]]
+- [[Async Client Pattern]]
+
+## Observations
+
+- [index] Central hub for architecture knowledge #navigation
+
+## Relations
+
+- indexes [[Architecture]]
+""",
+    folder="indexes",
+    project="main"
+)
+```
+
+### 7. Enrich Sparse Notes
+
+Find notes lacking observations or structure and suggest improvements.
+
+```python
+# Read a sparse note
+mcp__basic-memory__read_note(
+    identifier="sparse-note",
+    project="main"
+)
+
+# If missing:
+# - Observations section → suggest categories
+# - Relations section → suggest links
+# - Tags → suggest relevant tags
+# - Context → suggest adding background
+```
+
+## Organization Workflows
+
+### Quick Health Check
+
+A fast overview of knowledge base status:
+
+1. Count total notes
+2. Identify orphan count
+3. List recently modified
+4. Check for obvious duplicates
+5. Report folder distribution
+
+### Deep Organization Session
+
+Thorough review and improvement:
+
+1. **Audit phase** - Catalog all notes, identify issues
+2. **Orphan phase** - Address unlinked notes
+3. **Relation phase** - Suggest new connections
+4. **Duplicate phase** - Merge or differentiate similar notes
+5. **Structure phase** - Reorganize folders if needed
+6. **Index phase** - Create hub notes for major topics
+
+### Topic-Focused Organization
+
+Organize around a specific subject:
+
+1. Find all notes related to topic
+2. Map existing relations
+3. Identify gaps in the topic graph
+4. Suggest new notes to fill gaps
+5. Create topic index note
+
+## Best Practices
+
+1. **Work incrementally** - Don't reorganize everything at once
+2. **Confirm before changing** - Always ask before moving/editing notes
+3. **Preserve permalinks** - Moving is okay, changing permalinks breaks links
+4. **Show the graph** - Help user visualize connections
+5. **Explain suggestions** - Say why a relation makes sense
+6. **Respect user's system** - Enhance their organization, don't impose a new one
+
+## Example Conversations
+
+**User:** "Help me organize my notes"
+
+**Claude:**
+1. Runs health check on the knowledge base
+2. Reports: "You have 47 notes. I found 12 orphan notes and 3 potential duplicates."
+3. Asks: "Would you like to start by connecting the orphan notes, or review the duplicates first?"
+
+**User:** "Find notes that should be linked to my API design note"
+
+**Claude:**
+1. Reads the API design note
+2. Searches for related content
+3. Suggests: "I found 5 notes that could relate:
+   - 'REST Best Practices' → relates-to
+   - 'Authentication Flow' → implements
+   - 'Rate Limiting Decision' → extends
+   Would you like me to add any of these relations?"
+
+**User:** "Are there any notes about similar topics?"
+
+**Claude:**
+1. Analyzes note titles and content
+2. Identifies clusters of similar notes
+3. Reports: "I found these potential overlaps:
+   - 'Auth Flow' and 'Authentication Design' cover similar ground
+   - 'DB Schema v1' and 'DB Schema v2' might need a 'supersedes' relation
+   Would you like to review any of these?"

claude-code-plugin/skills/research/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: research
+description: Research a topic thoroughly and produce a structured report saved to Basic Memory - investigate concepts, gather context, and document findings
+---
+
+# Research
+
+This skill helps conduct thorough research on a topic and produces a structured report that gets saved to Basic Memory for future reference.
+
+## When to Use
+
+Use this skill when:
+- User asks to research or investigate something
+- User wants to understand a concept, technology, or approach
+- User needs context gathered before making a decision
+- User asks "what is...", "how does... work", "explore...", "investigate..."
+- User wants findings documented for later
+- Phrases like "research this", "look into", "find out about", "explore options for"
+
+## Research Process
+
+### 1. Understand the Research Question
+
+Clarify what specifically to investigate:
+- What is the core question or topic?
+- What scope - broad overview or deep dive?
+- Any specific aspects to focus on?
+- What will the research inform (a decision, implementation, understanding)?
+
+### 2. Gather Information
+
+Use available tools to collect information:
+
+**For codebase research:**
+- Search the codebase for relevant code
+- Read documentation and comments
+- Trace how things connect
+- Look at tests for usage examples
+
+**For concept research:**
+- Use web search for current information
+- Fetch documentation from official sources
+- Look for examples and best practices
+- Compare alternatives if relevant
+
+**For Basic Memory context:**
+```python
+# Check what we already know
+mcp__basic-memory__search_notes(
+    query="topic keywords",
+    project="main"
+)
+
+# Build context from related notes
+mcp__basic-memory__build_context(
+    url="memory://related-topic",
+    depth=2,
+    project="main"
+)
+```
+
+### 3. Analyze and Synthesize
+
+Organize findings into coherent insights:
+- Identify key concepts and how they relate
+- Note patterns, trade-offs, and considerations
+- Highlight what's most relevant to the user's needs
+- Flag uncertainties or areas needing more investigation
+
+### 4. Produce the Report
+
+Create a structured research report:
+
+```markdown
+---
+title: "Research: [Topic]"
+type: research
+tags:
+- research
+- [topic-tags]
+---
+
+# Research: [Topic]
+
+## Summary
+
+[2-3 sentence executive summary of findings]
+
+## Research Question
+
+[What we set out to understand]
+
+## Key Findings
+
+### [Finding 1]
+[Details, evidence, implications]
+
+### [Finding 2]
+[Details, evidence, implications]
+
+### [Finding 3]
+[Details, evidence, implications]
+
+## Analysis
+
+[Synthesis of findings - patterns, trade-offs, recommendations]
+
+## Open Questions
+
+- [Things that need more investigation]
+- [Uncertainties or assumptions]
+
+## Sources
+
+- [Where information came from]
+- [[Related Note]] - relevant prior knowledge
+
+## Observations
+
+- [finding] Key insight discovered #research
+- [pattern] Pattern identified during research
+- [recommendation] Suggested approach based on findings
+
+## Relations
+
+- researches [[Topic]]
+- informs [[Decision or Implementation]]
+- relates-to [[Related Concepts]]
+```
+
+### 5. Save to Basic Memory
+
+```python
+mcp__basic-memory__write_note(
+    title="Research: [Topic]",
+    content="[Full report content]",
+    folder="research",
+    tags=["research", "topic-tags"],
+    project="main"
+)
+```
+
+## Report Styles
+
+Adjust based on the research type:
+
+### Quick Investigation
+- Focused summary
+- 2-3 key findings
+- Direct recommendation
+- Saved to `research/` folder
+
+### Deep Dive
+- Comprehensive analysis
+- Multiple sections
+- Detailed evidence
+- Comparison of options
+- Saved to `research/` folder
+
+### Decision Support
+- Options evaluated
+- Pros/cons for each
+- Clear recommendation with rationale
+- Saved to `decisions/` or `research/` folder
+
+### Technical Exploration
+- How it works
+- Architecture/design
+- Code examples
+- Integration considerations
+- Saved to `research/` folder
+
+## Best Practices
+
+1. **Start with what we know** - Check Basic Memory for existing context
+2. **Be thorough but focused** - Cover the topic well without tangents
+3. **Cite sources** - Link to where information came from
+4. **Be honest about uncertainty** - Flag what's unclear or needs verification
+5. **Make it actionable** - Include recommendations when appropriate
+6. **Link to related knowledge** - Connect to existing notes
+7. **Save for future reference** - Always save the report to Basic Memory
+
+## Example Conversations
+
+**User:** "Research how other projects handle database migrations"
+
+**Claude:**
+1. Searches codebase for migration patterns
+2. Checks Basic Memory for related decisions
+3. Looks up best practices online
+4. Produces report comparing approaches
+5. Saves to `research/Database Migration Approaches.md`
+6. Presents summary with recommendation
+
+**User:** "Investigate the MCP protocol"
+
+**Claude:**
+1. Fetches MCP documentation
+2. Searches for examples in codebase
+3. Checks Basic Memory for prior context
+4. Produces comprehensive report on MCP
+5. Saves to `research/MCP Protocol Overview.md`
+6. Presents key concepts and how to use them
+
+**User:** "Look into authentication options for the API"
+
+**Claude:**
+1. Researches common auth patterns (JWT, OAuth, API keys)
+2. Checks existing codebase auth implementation
+3. Evaluates trade-offs for the use case
+4. Produces decision-support report
+5. Saves to `research/API Authentication Options.md`
+6. Recommends approach with rationale

claude-code-plugin/skills/spec-driven-development/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: spec-driven-development
+description: Guide implementation based on specs stored in Basic Memory, following the SPEC-1 specification-driven development process
+---
+
+# Spec-Driven Development
+
+This skill guides implementation work based on specifications stored in the Basic Memory "specs" project, following the process defined in SPEC-1.
+
+## When to Use
+
+Use this skill when:
+- Implementing a feature defined by a spec
+- Creating a new specification before implementation
+- Reviewing implementation against spec criteria
+- Need to understand what a spec requires
+- Updating spec progress as work completes
+
+## The Spec-Driven Process
+
+From SPEC-1, the workflow is:
+
+1. **Create** - Write spec as complete thought in Basic Memory "specs" project
+2. **Discuss** - Iterate and refine the specification
+3. **Implement** - Execute implementation directly
+4. **Validate** - Review implementation against spec criteria
+5. **Document** - Update spec with learnings and decisions
+
+## Spec Structure
+
+Every spec contains:
+- **Why** - The reasoning and problem being solved
+- **What** - What is affected or changed
+- **How** - High-level approach to implementation
+- **How to Evaluate** - Testing/validation procedure
+
+### Progress Tracking Format
+
+Specs use living documentation with checklists:
+
+```markdown
+### Feature Area
+- ✅ Basic functionality implemented
+- ✅ Props and events defined
+- [ ] Add sorting controls
+- [ ] Improve accessibility
+- [x] Currently implementing responsive design
+```
+
+- `✅` - Completed items
+- `[ ]` - Pending items
+- `[x]` - In-progress items
+
+## Working with Specs
+
+### Reading a Spec
+
+```python
+# Get the full spec
+mcp__basic-memory__read_note(
+    identifier="SPEC-24: Postgres Database Migration",
+    project="specs"
+)
+
+# Or search for it
+mcp__basic-memory__search_notes(
+    query="postgres migration",
+    project="specs"
+)
+```
+
+### Creating a New Spec
+
+```python
+# 1. First, find the next spec number
+mcp__basic-memory__search_notes(
+    query="SPEC-",
+    project="specs"
+)
+
+# 2. Create the spec with proper structure
+mcp__basic-memory__write_note(
+    title="SPEC-30: Your Feature Name",
+    content="""---
+title: 'SPEC-30: Your Feature Name'
+type: spec
+tags:
+- feature-area
+- component
+---
+
+# SPEC-30: Your Feature Name
+
+## Why
+
+[Problem statement and motivation]
+
+## What
+
+[What is affected or changed]
+- Affected areas
+- Components involved
+- Scope boundaries
+
+## How (High Level)
+
+[Implementation approach]
+
+### Phase 1: Foundation
+- [ ] Task 1
+- [ ] Task 2
+
+### Phase 2: Core Features
+- [ ] Task 3
+- [ ] Task 4
+
+## How to Evaluate
+
+### Success Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+### Testing Procedure
+1. Step 1
+2. Step 2
+
+## Observations
+
+- [goal] Primary objective #tag
+- [constraint] Known limitation #tag
+
+## Relations
+
+- relates-to [[Related Spec]]
+- depends-on [[Dependency]]
+""",
+    folder="",  # Root of specs project
+    project="specs"
+)
+```
+
+### Updating Spec Progress
+
+```python
+# Mark items complete as you implement
+mcp__basic-memory__edit_note(
+    identifier="SPEC-24: Postgres Database Migration",
+    operation="find_replace",
+    find_text="- [ ] Create migration scripts",
+    content="- ✅ Create migration scripts",
+    project="specs"
+)
+
+# Or add new observations
+mcp__basic-memory__edit_note(
+    identifier="SPEC-24: Postgres Database Migration",
+    operation="append",
+    content="\n- [learning] Alembic autogenerate works well for model changes #migration",
+    project="specs"
+)
+```
+
+### Reviewing Implementation
+
+When reviewing against a spec:
+
+1. **Read the spec's "How to Evaluate" section**
+2. **Check each success criterion:**
+   - Functional completeness
+   - Test coverage (count test files, check categories)
+   - Code quality (TypeScript, linting, performance)
+   - Architecture compliance
+   - Documentation completeness
+3. **Be honest** - Don't overstate completeness
+4. **Document findings** - Update spec with review results
+5. **Identify gaps** - Clearly note what still needs work
+
+## Implementation Workflow
+
+### Starting Implementation
+
+1. **Read the spec thoroughly**
+   ```python
+   mcp__basic-memory__read_note(
+       identifier="SPEC-XX: Feature Name",
+       project="specs"
+   )
+   ```
+
+2. **Understand dependencies**
+   - Check Relations section for dependencies
+   - Read related specs if needed
+
+3. **Plan your approach**
+   - Break "How" section into concrete tasks
+   - Identify what to implement first
+
+4. **Mark first item in-progress**
+   ```python
+   mcp__basic-memory__edit_note(
+       identifier="SPEC-XX",
+       operation="find_replace",
+       find_text="- [ ] First task",
+       content="- [x] First task",
+       project="specs"
+   )
+   ```
+
+### During Implementation
+
+1. **Update progress as you complete items**
+2. **Add observations for decisions made**
+3. **Note any deviations from the spec**
+4. **Capture learnings that might help future specs**
+
+### After Implementation
+
+1. **Run full evaluation against criteria**
+2. **Mark all completed items with ✅**
+3. **Add final observations**
+4. **Document any follow-up work needed**
+
+## Spec Naming Convention
+
+Format: `SPEC-X: Descriptive Title`
+
+Examples:
+- `SPEC-24: Postgres Database Migration`
+- `SPEC-25: Cloud Index Service`
+- `SPEC-26: Multi-User Security and Permissions`
+
+## Common Spec Patterns
+
+### Feature Spec
+```markdown
+## Why
+User need or problem
+
+## What
+- New UI components
+- API endpoints
+- Database changes
+
+## How
+Implementation phases with checkboxes
+```
+
+### Architecture Spec
+```markdown
+## Why
+Technical debt or scalability need
+
+## What
+- System components affected
+- Data flow changes
+- Integration points
+
+## How
+Migration strategy with rollback plan
+```
+
+### Process Spec
+```markdown
+## Why
+Workflow improvement need
+
+## What
+- Process steps changed
+- Tools involved
+- Team impact
+
+## How
+Rollout plan and adoption strategy
+```
+
+## Best Practices
+
+1. **Spec first, code second** - Write spec before implementation
+2. **Keep specs living** - Update as understanding evolves
+3. **Be specific in criteria** - Vague criteria = vague completion
+4. **Link related specs** - Build the knowledge graph
+5. **Capture decisions** - Future you will thank you
+6. **Review honestly** - Incomplete is okay, dishonest isn't
+7. **Close the loop** - Mark items done as you complete them
+
+## Using with Slash Commands
+
+The `/spec` command provides quick access:
+- `/spec create [name]` - Create new specification
+- `/spec status` - Show all spec statuses
+- `/spec show [name]` - Read a specific spec
+- `/spec review [name]` - Validate implementation

docker-compose-postgres.yml

@@ -0,0 +1,42 @@
+# Docker Compose configuration for Basic Memory with PostgreSQL
+# Use this for local development and testing with Postgres backend
+#
+# Usage:
+#   docker-compose -f docker-compose-postgres.yml up -d
+#   docker-compose -f docker-compose-postgres.yml down
+
+services:
+  postgres:
+    image: postgres:17
+    container_name: basic-memory-postgres
+    environment:
+      # Local development/test credentials - NOT for production
+      # These values are referenced by tests and justfile commands
+      POSTGRES_DB: basic_memory
+      POSTGRES_USER: basic_memory_user
+      POSTGRES_PASSWORD: dev_password  # Simple password for local testing only
+    ports:
+      - "5433:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U basic_memory_user -d basic_memory"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    restart: unless-stopped
+
+volumes:
+  # Named volume for Postgres data
+  postgres_data:
+    driver: local
+
+  # Named volume for persistent configuration
+  # Database will be stored in Postgres, not in this volume
+  basic-memory-config:
+    driver: local
+
+# Network configuration (optional)
+# networks:
+#   basic-memory-net:
+#     driver: bridge

docker-compose.yml

@@ -0,0 +1,83 @@
+# Docker Compose configuration for Basic Memory
+# See docs/Docker.md for detailed setup instructions
+
+version: '3.8'
+
+services:
+  basic-memory:
+    # Use pre-built image (recommended for most users)
+    image: ghcr.io/basicmachines-co/basic-memory:latest
+    
+    # Uncomment to build locally instead:
+    # build: .
+    
+    container_name: basic-memory-server
+    
+    # Volume mounts for knowledge directories and persistent data
+    volumes:
+
+      # Persistent storage for configuration and database
+      - basic-memory-config:/root/.basic-memory:rw
+
+      # Mount your knowledge directory (required)
+      # Change './knowledge' to your actual Obsidian vault or knowledge directory
+      - ./knowledge:/app/data:rw
+
+      # OPTIONAL: Mount additional knowledge directories for multiple projects
+      # - ./work-notes:/app/data/work:rw
+      # - ./personal-notes:/app/data/personal:rw
+
+      # You can edit the project config manually in the mounted config volume
+      # The default project will be configured to use /app/data
+    environment:
+      # Project configuration
+      - BASIC_MEMORY_DEFAULT_PROJECT=main
+      
+      # Enable real-time file synchronization (recommended for Docker)
+      - BASIC_MEMORY_SYNC_CHANGES=true
+      
+      # Logging configuration
+      - BASIC_MEMORY_LOG_LEVEL=INFO
+      
+      # Sync delay in milliseconds (adjust for performance vs responsiveness)
+      - BASIC_MEMORY_SYNC_DELAY=1000
+    
+    # Port exposure for HTTP transport (only needed if not using STDIO)
+    ports:
+      - "8000:8000"
+    
+    # Command with SSE transport (configurable via environment variables above)
+    # IMPORTANT: The SSE and streamable-http endpoints are not secured
+    command: ["basic-memory", "mcp", "--transport", "sse", "--host", "0.0.0.0", "--port", "8000"]
+    
+    # Container management
+    restart: unless-stopped
+    
+    # Health monitoring
+    healthcheck:
+      test: ["CMD", "basic-memory", "--version"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+    
+    # Optional: Resource limits
+    # deploy:
+    #   resources:
+    #     limits:
+    #       memory: 512M
+    #       cpus: '0.5'
+    #     reservations:
+    #       memory: 256M
+    #       cpus: '0.25'
+
+volumes:
+  # Named volume for persistent configuration and database
+  # This ensures your configuration and knowledge graph persist across container restarts
+  basic-memory-config:
+    driver: local
+
+# Network configuration (optional)
+# networks:
+#   basic-memory-net:
+#     driver: bridge

docs/.obsidian/app.json

@@ -1 +0,0 @@
-{}

docs/.obsidian/appearance.json

@@ -1 +0,0 @@
-{}

docs/.obsidian/core-plugins.json

@@ -1,31 +0,0 @@
-{
-  "file-explorer": true,
-  "global-search": true,
-  "switcher": true,
-  "graph": true,
-  "backlink": true,
-  "canvas": true,
-  "outgoing-link": true,
-  "tag-pane": true,
-  "properties": false,
-  "page-preview": true,
-  "daily-notes": true,
-  "templates": true,
-  "note-composer": true,
-  "command-palette": true,
-  "slash-command": false,
-  "editor-status": true,
-  "bookmarks": true,
-  "markdown-importer": false,
-  "zk-prefixer": false,
-  "random-note": false,
-  "outline": true,
-  "word-count": true,
-  "slides": false,
-  "audio-recorder": false,
-  "workspaces": false,
-  "file-recovery": true,
-  "publish": true,
-  "sync": true,
-  "webviewer": false
-}

docs/.obsidian/publish.json

@@ -1,6 +0,0 @@
-{
-  "siteId": "947ee055a8c6f1a57efa4afa09791e62",
-  "host": "publish-01.obsidian.md",
-  "included": [],
-  "excluded": []
-}

docs/.obsidian/workspace.json

@@ -1,167 +0,0 @@
-{
-  "main": {
-    "id": "9361625269255fc5",
-    "type": "split",
-    "children": [
-      {
-        "id": "9220768da355d9a9",
-        "type": "tabs",
-        "children": [
-          {
-            "id": "cd58e5dfc86465e3",
-            "type": "leaf",
-            "state": {
-              "type": "empty",
-              "state": {},
-              "icon": "lucide-file",
-              "title": "New tab"
-            }
-          }
-        ]
-      }
-    ],
-    "direction": "vertical"
-  },
-  "left": {
-    "id": "932aa23fccfbb069",
-    "type": "split",
-    "children": [
-      {
-        "id": "c60acde475f2bc34",
-        "type": "tabs",
-        "children": [
-          {
-            "id": "a06f3217ff27ae41",
-            "type": "leaf",
-            "state": {
-              "type": "file-explorer",
-              "state": {
-                "sortOrder": "alphabetical",
-                "autoReveal": false
-              },
-              "icon": "lucide-folder-closed",
-              "title": "Files"
-            }
-          },
-          {
-            "id": "c338fa22e7339c9a",
-            "type": "leaf",
-            "state": {
-              "type": "search",
-              "state": {
-                "query": "",
-                "matchingCase": false,
-                "explainSearch": false,
-                "collapseAll": false,
-                "extraContext": false,
-                "sortOrder": "alphabetical"
-              },
-              "icon": "lucide-search",
-              "title": "Search"
-            }
-          },
-          {
-            "id": "56de0827023b2535",
-            "type": "leaf",
-            "state": {
-              "type": "bookmarks",
-              "state": {},
-              "icon": "lucide-bookmark",
-              "title": "Bookmarks"
-            }
-          }
-        ]
-      }
-    ],
-    "direction": "horizontal",
-    "width": 300
-  },
-  "right": {
-    "id": "c3389d21c08cd71c",
-    "type": "split",
-    "children": [
-      {
-        "id": "11a1174f51a1cf86",
-        "type": "tabs",
-        "children": [
-          {
-            "id": "bf2a1fb608e63866",
-            "type": "leaf",
-            "state": {
-              "type": "backlink",
-              "state": {
-                "collapseAll": false,
-                "extraContext": false,
-                "sortOrder": "alphabetical",
-                "showSearch": false,
-                "searchQuery": "",
-                "backlinkCollapsed": false,
-                "unlinkedCollapsed": true
-              },
-              "icon": "links-coming-in",
-              "title": "Backlinks"
-            }
-          },
-          {
-            "id": "6f08673b57226dc1",
-            "type": "leaf",
-            "state": {
-              "type": "outgoing-link",
-              "state": {
-                "linksCollapsed": false,
-                "unlinkedCollapsed": true
-              },
-              "icon": "links-going-out",
-              "title": "Outgoing links"
-            }
-          },
-          {
-            "id": "e987a9643ca3ec81",
-            "type": "leaf",
-            "state": {
-              "type": "tag",
-              "state": {
-                "sortOrder": "frequency",
-                "useHierarchy": true,
-                "showSearch": false,
-                "searchQuery": ""
-              },
-              "icon": "lucide-tags",
-              "title": "Tags"
-            }
-          },
-          {
-            "id": "108a72a022d7e501",
-            "type": "leaf",
-            "state": {
-              "type": "outline",
-              "state": {
-                "followCursor": false,
-                "showSearch": false,
-                "searchQuery": ""
-              },
-              "icon": "lucide-list",
-              "title": "Outline"
-            }
-          }
-        ]
-      }
-    ],
-    "direction": "horizontal",
-    "width": 300,
-    "collapsed": true
-  },
-  "left-ribbon": {
-    "hiddenItems": {
-      "publish:Publish changes...": false,
-      "switcher:Open quick switcher": false,
-      "graph:Open graph view": false,
-      "canvas:Create new canvas": false,
-      "daily-notes:Open today's daily note": false,
-      "templates:Insert template": false,
-      "command-palette:Open command palette": false
-    }
-  },
-  "active": "a06f3217ff27ae41",
-  "lastOpenFiles": []
-}

docs/AI Assistant Guide.md

@@ -1,396 +0,0 @@
----
-title: AI Assistant Guide
-type: note
-permalink: docs/ai-assistant-guide
----
-
-# AI Assistant Guide for Basic Memory
-
-This guide helps you, the AI assistant, use Basic Memory tools effectively when working with users. It covers reading, writing, and navigating knowledge through the Model Context Protocol (MCP).
-
-## Overview
-
-Basic Memory allows you and users to record context in local Markdown files, building a rich knowledge base through natural conversations. The system automatically creates a semantic knowledge graph from simple text patterns.
-
-- **Local-First**: All data is stored in plain text files on the user's computer
-- **Real-Time**: Users see content updates immediately
-- **Bi-Directional**: Both you and users can read and edit notes
-- **Semantic**: Simple patterns create a structured knowledge graph
-- **Persistent**: Knowledge persists across sessions and conversations
-
-## The Importance of the Knowledge Graph
-
-Basic Memory's value comes from connections between notes, not just the notes themselves. When writing notes, your primary goal should be creating a rich, interconnected knowledge graph.
-
-When creating content, focus on:
-
-1. **Increasing Semantic Density**: Add multiple observations and relations to each note
-2. **Using Accurate References**: Aim to reference existing entities by their exact titles
-3. **Creating Forward References**: Feel free to reference entities that don't exist yet - Basic Memory will resolve these when they're created later
-4. **Creating Bidirectional Links**: When appropriate, connect entities from both directions
-5. **Using Meaningful Categories**: Add semantic context with appropriate observation categories
-6. **Choosing Precise Relations**: Use specific relation types that convey meaning
-
-Remember that a knowledge graph with 10 heavily connected notes is more valuable than 20 isolated notes. Your job is to help build these connections.
-
-## Core Tools Reference
-
-```python
-# Writing knowledge - THE MOST IMPORTANT TOOL!
-response = await write_note(
-    title="Search Design",              # Required: Note title
-    content="# Search Design\n...",     # Required: Note content
-    folder="specs",                     # Optional: Folder to save in
-    tags=["search", "design"],          # Optional: Tags for categorization
-    verbose=True                        # Optional: Get parsing details
-)
-
-# Reading knowledge
-content = await read_note("Search Design")             # By title
-content = await read_note("specs/search-design")       # By path
-content = await read_note("memory://specs/search")     # By memory URL
-
-# Searching for knowledge
-results = await search(
-    query="authentication system",      # Text to search for
-    page=1,                             # Optional: Pagination
-    page_size=10                        # Optional: Results per page
-)
-
-# Building context from the knowledge graph
-context = await build_context(
-    url="memory://specs/search",        # Starting point
-    depth=2,                            # Optional: How many hops to follow
-    timeframe="1 month"                 # Optional: Recent timeframe
-)
-
-# Checking recent changes
-activity = await recent_activity(
-    type="all",                         # Optional: Entity types to include
-    depth=1,                            # Optional: Related items to include
-    timeframe="1 week"                  # Optional: Time window
-)
-
-# Creating a knowledge visualization
-canvas_result = await canvas(
-    nodes=[{"id": "note1", "label": "Search Design"}],  # Nodes to display
-    edges=[{"from": "note1", "to": "note2"}],           # Connections
-    title="Project Overview",                           # Canvas title
-    folder="diagrams"                                   # Storage location
-)
-```
-
-## memory:// URLs Explained
-
-Basic Memory uses a special URL format to reference entities in the knowledge graph:
-
-- `memory://title` - Reference by title
-- `memory://folder/title` - Reference by folder and title 
-- `memory://permalink` - Reference by permalink
-- `memory://path/relation_type/*` - Follow all relations of a specific type
-- `memory://path/*/target` - Find all entities with relations to target
-
-## Semantic Markdown Format
-
-Knowledge is encoded in standard markdown using simple patterns:
-
-**Observations** - Facts about an entity:
-```markdown
-- [category] This is an observation #tag1 #tag2 (optional context)
-```
-
-**Relations** - Links between entities:
-```markdown
-- relation_type [[Target Entity]] (optional context)
-```
-
-**Common Categories & Relation Types:**
-- Categories: `[idea]`, `[decision]`, `[question]`, `[fact]`, `[requirement]`, `[technique]`, `[recipe]`, `[preference]`
-- Relations: `relates_to`, `implements`, `requires`, `extends`, `part_of`, `pairs_with`, `inspired_by`, `originated_from`
-
-## When to Record Context
-
-**Always consider recording context when**:
-
-1. Users make decisions or reach conclusions
-2. Important information emerges during conversation
-3. Multiple related topics are discussed
-4. The conversation contains information that might be useful later
-5. Plans, tasks, or action items are mentioned
-
-**Protocol for recording context**:
-
-1. Identify valuable information in the conversation
-2. Ask the user: "Would you like me to record our discussion about [topic] in Basic Memory?"
-3. If they agree, use `write_note` to capture the information
-4. If they decline, continue without recording
-5. Let the user know when information has been recorded: "I've saved our discussion about [topic] to Basic Memory."
-
-## Understanding User Interactions
-
-Users will interact with Basic Memory in patterns like:
-
-1. **Creating knowledge**:
-   ```
-   Human: "Let's write up what we discussed about search."
-   
-   You: I'll create a note capturing our discussion about the search functionality.
-   [Use write_note() to record the conversation details]
-   ```
-
-2. **Referencing existing knowledge**:
-   ```
-   Human: "Take a look at memory://specs/search"
-   
-   You: I'll examine that information.
-   [Use build_context() to gather related information]
-   [Then read_note() to access specific content]
-   ```
-
-3. **Finding information**:
-   ```
-   Human: "What were our decisions about auth?"
-   
-   You: Let me find that information for you.
-   [Use search() to find relevant notes]
-   [Then build_context() to understand connections]
-   ```
-
-## Key Things to Remember
-
-1. **Files are Truth**
-   - All knowledge lives in local files on the user's computer
-   - Users can edit files outside your interaction
-   - Changes need to be synced by the user (usually automatic)
-   - Always verify information is current with `recent_activity()`
-
-2. **Building Context Effectively**
-   - Start with specific entities
-   - Follow meaningful relations
-   - Check recent changes
-   - Build context incrementally
-   - Combine related information
-
-3. **Writing Knowledge Wisely**
-   - Using the same title+folder will overwrite existing notes
-   - Structure content with clear headings and sections
-   - Use semantic markup for observations and relations
-   - Keep files organized in logical folders
-
-## Common Knowledge Patterns
-
-### Capturing Decisions
-
-```markdown
-# Coffee Brewing Methods
-
-## Context
-I've experimented with various brewing methods including French press, pour over, and espresso.
-
-## Decision
-Pour over is my preferred method for light to medium roasts because it highlights subtle flavors and offers more control over the extraction.
-
-## Observations
-- [technique] Blooming the coffee grounds for 30 seconds improves extraction #brewing
-- [preference] Water temperature between 195-205°F works best #temperature
-- [equipment] Gooseneck kettle provides better control of water flow #tools
-
-## Relations
-- pairs_with [[Light Roast Beans]]
-- contrasts_with [[French Press Method]]
-- requires [[Proper Grinding Technique]]
-```
-
-### Recording Project Structure
-
-```markdown
-# Garden Planning
-
-## Overview
-This document outlines the garden layout and planting strategy for this season.
-
-## Observations
-- [structure] Raised beds in south corner for sun exposure #layout
-- [structure] Drip irrigation system installed for efficiency #watering
-- [pattern] Companion planting used to deter pests naturally #technique
-
-## Relations
-- contains [[Vegetable Section]]
-- contains [[Herb Garden]]
-- implements [[Organic Gardening Principles]]
-```
-
-### Technical Discussions
-
-```markdown
-# Recipe Improvement Discussion
-
-## Key Points
-Discussed strategies for improving the chocolate chip cookie recipe.
-
-## Observations
-- [issue] Cookies spread too thin when baked at 350°F #texture
-- [solution] Chilling dough for 24 hours improves flavor and reduces spreading #technique
-- [decision] Will use brown butter instead of regular butter #flavor
-
-## Relations
-- improves [[Basic Cookie Recipe]]
-- inspired_by [[Bakery-Style Cookies]]
-- pairs_with [[Homemade Ice Cream]]
-```
-
-### Creating Effective Relations
-
-When creating relations, you can:
-1. Reference existing entities by their exact title
-2. Create forward references to entities that don't exist yet
-
-```python
-# Example workflow for creating notes with effective relations
-async def create_note_with_effective_relations():
-    # Search for existing entities to reference
-    search_results = await search("travel")
-    existing_entities = [result.title for result in search_results.primary_results]
-    
-    # Check if specific entities exist
-    packing_tips_exists = "Packing Tips" in existing_entities
-    japan_travel_exists = "Japan Travel Guide" in existing_entities
-    
-    # Prepare relations section - include both existing and forward references
-    relations_section = "## Relations\n"
-    
-    # Existing reference - exact match to known entity
-    if packing_tips_exists:
-        relations_section += "- references [[Packing Tips]]\n"
-    else:
-        # Forward reference - will be linked when that entity is created later
-        relations_section += "- references [[Packing Tips]]\n"
-    
-    # Another possible reference
-    if japan_travel_exists:
-        relations_section += "- part_of [[Japan Travel Guide]]\n"
-    
-    # You can also check recently modified notes to reference them
-    recent = await recent_activity(timeframe="1 week")
-    recent_titles = [item.title for item in recent.primary_results]
-    
-    if "Transportation Options" in recent_titles:
-        relations_section += "- relates_to [[Transportation Options]]\n"
-    
-    # Always include meaningful forward references, even if they don't exist yet
-    relations_section += "- located_in [[Tokyo]]\n"
-    relations_section += "- visited_during [[Spring 2023 Trip]]\n"
-    
-    # Now create the note with both verified and forward relations
-    content = f"""# Tokyo Neighborhood Guide
-    
-## Overview
-Details about different Tokyo neighborhoods and their unique characteristics.
-
-## Observations
-- [area] Shibuya is a busy shopping district #shopping
-- [transportation] Yamanote Line connects major neighborhoods #transit
-- [recommendation] Visit Shimokitazawa for vintage shopping #unique
-- [tip] Get a Suica card for easy train travel #convenience
-
-{relations_section}
-    """
-    
-    result = await write_note(
-        title="Tokyo Neighborhood Guide",
-        content=content,
-        verbose=True
-    )
-    
-    # You can check which relations were resolved and which are forward references
-    if result and 'relations' in result:
-        resolved = [r['to_name'] for r in result['relations'] if r.get('target_id')]
-        forward_refs = [r['to_name'] for r in result['relations'] if not r.get('target_id')]
-        
-        print(f"Resolved relations: {resolved}")
-        print(f"Forward references that will be resolved later: {forward_refs}")
-```
-
-## Error Handling
-
-Common issues to watch for:
-
-1. **Missing Content**
-   ```python
-   try:
-       content = await read_note("Document")
-   except:
-       # Try search instead
-       results = await search("Document")
-       if results and results.primary_results:
-           # Found something similar
-           content = await read_note(results.primary_results[0].permalink)
-   ```
-
-2. **Forward References (Unresolved Relations)**
-   ```python
-   response = await write_note(..., verbose=True)
-   # Check for forward references (unresolved relations)
-   forward_refs = []
-   for relation in response.get('relations', []):
-       if not relation.get('target_id'):
-           forward_refs.append(relation.get('to_name'))
-   
-   if forward_refs:
-       # This is a feature, not an error! Inform the user about forward references
-       print(f"Note created with forward references to: {forward_refs}")
-       print("These will be automatically linked when those notes are created.")
-       
-       # Optionally suggest creating those entities now
-       print("Would you like me to create any of these notes now to complete the connections?")
-   ```
-
-3. **Sync Issues**
-   ```python
-   # If information seems outdated
-   activity = await recent_activity(timeframe="1 hour")
-   if not activity or not activity.primary_results:
-       print("It seems there haven't been recent updates. You might need to run 'basic-memory sync'.")
-   ```
-
-## Best Practices
-
-1. **Proactively Record Context**
-   - Offer to capture important discussions
-   - Record decisions, rationales, and conclusions
-   - Link to related topics
-   - Ask for permission first: "Would you like me to save our discussion about [topic]?"
-   - Confirm when complete: "I've saved our discussion to Basic Memory"
-
-2. **Create a Rich Semantic Graph**
-   - **Add meaningful observations**: Include at least 3-5 categorized observations in each note
-   - **Create deliberate relations**: Connect each note to at least 2-3 related entities
-   - **Use existing entities**: Before creating a new relation, search for existing entities
-   - **Verify wikilinks**: When referencing `[[Entity]]`, use exact titles of existing notes
-   - **Check accuracy**: Use `search()` or `recent_activity()` to confirm entity titles
-   - **Use precise relation types**: Choose specific relation types that convey meaning (e.g., "implements" instead of "relates_to")
-   - **Consider bidirectional relations**: When appropriate, create inverse relations in both entities
-
-3. **Structure Content Thoughtfully**
-   - Use clear, descriptive titles
-   - Organize with logical sections (Context, Decision, Implementation, etc.)
-   - Include relevant context and background
-   - Add semantic observations with appropriate categories
-   - Use a consistent format for similar types of notes
-   - Balance detail with conciseness
-
-4. **Navigate Knowledge Effectively**
-   - Start with specific searches
-   - Follow relation paths
-   - Combine information from multiple sources
-   - Verify information is current
-   - Build a complete picture before responding
-
-5. **Help Users Maintain Their Knowledge**
-   - Suggest organizing related topics
-   - Identify potential duplicates
-   - Recommend adding relations between topics
-   - Offer to create summaries of scattered information
-   - Suggest potential missing relations: "I notice this might relate to [topic], would you like me to add that connection?"
-
-Built with ♥️ by Basic Machines

docs/CLI Reference.md

@@ -1,289 +0,0 @@
----
-title: CLI Reference
-type: note
-permalink: docs/cli-reference
----
-
-# CLI Reference
-
-Basic Memory provides command line tools for managing your knowledge base. This reference covers the available commands and their options.
-
-## Core Commands
-
-### sync
-
-Keeps files and the knowledge graph in sync:
-
-```bash
-# Basic sync
-basic-memory sync
-
-# Watch for changes
-basic-memory sync --watch
-
-# Sync specific folder
-basic-memory sync path/to/folder
-```
-
-Options:
-- `--watch`: Continuously monitor for changes
-- `--verbose`: Show detailed output
-- `PATH`: Optional path to sync (defaults to ~/basic-memory)
-
-### import
-
-Imports external knowledge sources:
-
-```bash
-# Claude conversations
-basic-memory import claude conversations
-
-# Claude projects
-basic-memory import claude projects
-
-# ChatGPT history
-basic-memory import chatgpt
-```
-
-Options:
-- `--folder PATH`: Target folder for imported content
-- `--overwrite`: Replace existing files
-- `--skip-existing`: Keep existing files
-
-### status
-
-Shows system status information:
-
-```bash
-# Basic status check
-basic-memory status
-
-# Detailed status
-basic-memory status --verbose
-
-# JSON output
-basic-memory status --json
-```
-
-
-### project
-
-Create multiple projects to manage your knowledge. 
-  
-```bash  
-# List all configured projects  
-basic-memory project list  
-  
-# Add a new project  
-basic-memory project add work ~/work-basic-memory  
-  
-# Set the default project  
-basic-memory project default work  
-  
-# Remove a project (doesn't delete files)  
-basic-memory project remove personal  
-  
-# Show current project  
-basic-memory project current  
-```  
-
-> Be sure to restart Claude Desktop after changing projects. 
-
-#### Using Projects in Commands  
-  
-All commands support the `--project` flag to specify which project to use:  
-  
-```bash  
-# Sync a specific project  
-basic-memory --project=work sync  
-  
-# Run MCP server for a specific project  
-basic-memory --project=personal mcp  
-```  
-  
-You can also set the `BASIC_MEMORY_PROJECT` environment variable:  
-  
-```bash  
-BASIC_MEMORY_PROJECT=work basic-memory sync  
-```  
-
-### help
-
-The full list of commands and help for each can be viewed with the `--help` argument.
-
-```
- ✗ basic-memory --help
-
- Usage: basic-memory [OPTIONS] COMMAND [ARGS]...
-
- Basic Memory - Local-first personal knowledge management system.
-
-╭─ Options ─────────────────────────────────────────────────────────────────────────────────╮
-│ --project             -p      TEXT  Specify which project to use                          │
-│                                     [env var: BASIC_MEMORY_PROJECT]                       │
-│                                     [default: None]                                       │
-│ --version             -V            Show version information and exit.                    │
-│ --install-completion                Install completion for the current shell.             │
-│ --show-completion                   Show completion for the current shell, to copy it or  │
-│                                     customize the installation.                           │
-│ --help                              Show this message and exit.                           │
-╰───────────────────────────────────────────────────────────────────────────────────────────╯
-╭─ Commands ────────────────────────────────────────────────────────────────────────────────╮
-│ sync      Sync knowledge files with the database.                                         │
-│ status    Show sync status between files and database.                                    │
-│ reset     Reset database (drop all tables and recreate).                                  │
-│ mcp       Run the MCP server for Claude Desktop integration.                              │
-│ import    Import data from various sources                                                │
-│ tool      Direct access to MCP tools via CLI                                              │
-│ project   Manage multiple Basic Memory projects                                           │
-╰───────────────────────────────────────────────────────────────────────────────────────────╯
-```
-
-## Initial Setup
-
-```bash
-# Install Basic Memory
-uv install basic-memory
-
-# First sync
-basic-memory sync
-
-# Start watching mode
-basic-memory sync --watch
-```
-
-> **Important**: You need to install Basic Memory via `uv` or `pip` to use the command line tools, see [[Getting Started with Basic Memory#Installation]].
-
-## Regular Usage
-
-```bash
-# Check status
-basic-memory status
-
-# Import new content
-basic-memory import claude conversations
-
-# Sync changes
-basic-memory sync
-
-# Sync changes continuously
-basic-memory sync --watch
-```
-
-## Maintenance Tasks
-
-```bash
-# Check system status in detail
-basic-memory status --verbose
-
-# Full resync of all files
-basic-memory sync
-
-# Import updates to specific folder
-basic-memory import claude conversations --folder new
-```
-
-
-## Using stdin with Basic Memory's `write_note` Tool
-
-The `write-note` tool supports reading content from standard input (stdin), allowing for more flexible workflows when creating or updating notes in your Basic Memory knowledge base.
-
-### Use Cases
-
-This feature is particularly useful for:
-
-1. **Piping output from other commands** directly into Basic Memory notes
-2. **Creating notes with multi-line content** without having to escape quotes or special characters
-3. **Integrating with AI assistants** like Claude Code that can generate content and pipe it to Basic Memory
-4. **Processing text data** from files or other sources
-
-### Basic Usage
-
-#### Method 1: Using a Pipe
-
-You can pipe content from another command into `write_note`:
-
-```bash
-# Pipe output of a command into a new note
-echo "# My Note\n\nThis is a test note" | basic-memory tool write-note --title "Test Note" --folder "notes"
-
-# Pipe output of a file into a new note
-cat README.md | basic-memory tool write-note --title "Project README" --folder "documentation"
-
-# Process text through other tools before saving as a note
-cat data.txt | grep "important" | basic-memory tool write-note --title "Important Data" --folder "data"
-```
-
-#### Method 2: Using Heredoc Syntax
-
-For multi-line content, you can use heredoc syntax:
-
-```bash
-# Create a note with heredoc
-cat << EOF | basic-memory tool write_note --title "Project Ideas" --folder "projects"
-# Project Ideas for Q2
-
-## AI Integration
-- Improve recommendation engine
-- Add semantic search to product catalog
-
-## Infrastructure
-- Migrate to Kubernetes
-- Implement CI/CD pipeline
-EOF
-```
-
-#### Method 3: Input Redirection
-
-You can redirect input from a file:
-
-```bash
-# Create a note from file content
-basic-memory tool write-note --title "Meeting Notes" --folder "meetings" < meeting_notes.md
-```
-
-#### Integration with Claude Code
-
-This feature works well with Claude Code in the terminal:
-
-In a Claude Code session, let Claude know he can use the basic-memory tools, then he can execute them via the cli:
-
-```
-⏺ Bash(echo "# Test Note from Claude\n\nThis is a test note created by Claude to test the stdin functionality." | basic-memory tool write-note --title "Claude Test Note" --folder "test" --tags "test" --tags "claude")…
-  ⎿  # Created test/Claude Test Note.md (23e00eec)
-     permalink: test/claude-test-note
-
-     ## Tags
-     - test, claude
-
-```
-
-
-## Troubleshooting Common Issues
-
-### Sync Conflicts
-
-If you encounter a file changed during sync error:
-1. Check the file referenced in the error message
-2. Resolve any conflicts manually
-3. Run sync again
-
-### Import Errors
-
-If import fails:
-1. Check that the source file is in the correct format
-2. Verify permissions on the target directory
-3. Use --verbose flag for detailed error information
-
-### Status Issues
-
-If status shows problems:
-1. Note any unresolved relations or warnings
-2. Run a full sync to attempt automatic resolution
-3. Check file permissions if database access errors occur
-
-
-## Relations
-- used_by [[Getting Started with Basic Memory]] (Installation instructions)
-- complements [[User Guide]] (How to use Basic Memory)
-- relates_to [[Introduction to Basic Memory]] (System overview)

docs/Canvas.md

@@ -1,107 +0,0 @@
----
-title: Canvas Visualizations
-type: note
-permalink: docs/canvas
-tags:
-- visualization
-- mapping
-- obsidian
----
-
-# Canvas Visualizations
-
-Basic Memory can create visual knowledge maps using Obsidian's Canvas feature. These visualizations help you understand relationships between concepts, map out processes, and visualize your knowledge structure.
-
-## Creating Canvas Visualizations
-
-Ask Claude to create a visualization by describing what you want to map:
-
-```
-You: "Create a canvas visualization of my project components and their relationships."
-
-You: "Make a concept map showing the main themes from our discussion about climate change."
-
-You: "Can you make a canvas diagram of the perfect pour over method?"
-```
-
-![[Canvas.png]]
-
-## Types of Visualizations
-
-Basic Memory can create several types of visual maps:
-
-### Document Maps
-Visualize connections between your notes and documents
-
-### Concept Maps
-Create visual representations of ideas and their relationships
-
-### Process Diagrams
-Map workflows, sequences, and procedures
-
-### Thematic Analysis
-Organize ideas around central themes
-
-### Relationship Networks
-Show how different entities relate to each other
-
-## Visualization Sources
-
-Claude can create visualizations based on:
-
-### Documents in Your Knowledge Base
-```
-You: "Create a canvas showing the connections between my project planning documents"
-```
-
-### Conversation Content
-```
-You: "Make a canvas visualization of the main points we just discussed"
-```
-
-### Search Results
-```
-You: "Find all my notes about psychology and create a visual map of the concepts"
-```
-
-### Themes and Relationships
-```
-You: "Create a visual map showing how different philosophical schools relate to each other"
-```
-
-## Visualization Workflow
-
-1. **Request a visualization** by describing what you want to see
-2. **Claude creates the canvas file** in your Basic Memory directory
-3. **Open the file in Obsidian** to view the visualization
-4. **Refine the visualization** by asking Claude for adjustments:
-   ```
-   You: "Could you reorganize the canvas to group related components together?"
-   
-   You: "Please add more detail about the connection between these two concepts."
-   ```
-
-## Technical Details
-
-Behind the scenes, Claude:
-
-1. Creates a `.canvas` file in JSON format
-2. Adds nodes for each concept or document
-3. Creates edges to represent relationships
-4. Sets positions for visual clarity
-5. Includes any relevant metadata
-
-The resulting file is fully compatible with Obsidian's Canvas feature and can be edited directly in Obsidian.
-
-## Tips for Effective Visualizations
-
-- **Be specific** about what you want to visualize
-- **Specify the level of detail** you need
-- **Mention the visualization type** you want (concept map, process flow, etc.)
-- **Start simple** and ask for refinements
-- **Provide context** about what documents or concepts to include
-
-## Relations
-- enhances [[Obsidian Integration]] (Using Basic Memory with Obsidian)
-- visualizes [[Knowledge Format]] (The structure of your knowledge)
-- complements [[User Guide]] (Ways to use Basic Memory)

docs/Docker.md

@@ -0,0 +1,365 @@
+# Docker Setup Guide
+
+Basic Memory can be run in Docker containers to provide a consistent, isolated environment for your knowledge management
+system. This is particularly useful for integrating with existing Dockerized MCP servers or for deployment scenarios.
+
+## Quick Start
+
+### Option 1: Using Pre-built Images (Recommended)
+
+Basic Memory provides pre-built Docker images on GitHub Container Registry that are automatically updated with each release.
+
+1. **Use the official image directly:**
+   ```bash
+   docker run -d \
+     --name basic-memory-server \
+     -p 8000:8000 \
+     -v /path/to/your/obsidian-vault:/app/data:rw \
+     -v basic-memory-config:/app/.basic-memory:rw \
+     ghcr.io/basicmachines-co/basic-memory:latest
+   ```
+
+2. **Or use Docker Compose with the pre-built image:**
+   ```yaml
+   version: '3.8'
+   services:
+     basic-memory:
+       image: ghcr.io/basicmachines-co/basic-memory:latest
+       container_name: basic-memory-server
+       ports:
+         - "8000:8000"
+       volumes:
+         - /path/to/your/obsidian-vault:/app/data:rw
+         - basic-memory-config:/app/.basic-memory:rw
+       environment:
+         - BASIC_MEMORY_DEFAULT_PROJECT=main
+       restart: unless-stopped
+   ```
+
+### Option 2: Using Docker Compose (Building Locally)
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/basicmachines-co/basic-memory.git
+   cd basic-memory
+   ```
+
+2. **Update the docker-compose.yml:**
+   Edit the volume mount to point to your Obsidian vault:
+   ```yaml
+   volumes:
+     # Change './obsidian-vault' to your actual directory path
+     - /path/to/your/obsidian-vault:/app/data:rw
+   ```
+
+3. **Start the container:**
+   ```bash
+   docker-compose up -d
+   ```
+
+### Option 3: Using Docker CLI
+
+```bash
+# Build the image
+docker build -t basic-memory .
+
+# Run with volume mounting
+docker run -d \
+  --name basic-memory-server \
+  -v /path/to/your/obsidian-vault:/app/data:rw \
+  -v basic-memory-config:/app/.basic-memory:rw \
+  -e BASIC_MEMORY_DEFAULT_PROJECT=main \
+  basic-memory
+```
+
+## Configuration
+
+### Volume Mounts
+
+Basic Memory requires several volume mounts for proper operation:
+
+1. **Knowledge Directory** (Required):
+   ```yaml
+   - /path/to/your/obsidian-vault:/app/data:rw
+   ```
+   Mount your Obsidian vault or knowledge base directory.
+
+2. **Configuration and Database** (Recommended):
+   ```yaml
+   - basic-memory-config:/app/.basic-memory:rw
+   ```
+   Persistent storage for configuration and SQLite database.
+
+You can edit the basic-memory config.json file located in the /app/.basic-memory/config.json after Basic Memory starts.
+
+3. **Multiple Projects** (Optional):
+   ```yaml
+   - /path/to/project1:/app/data/project1:rw
+   - /path/to/project2:/app/data/project2:rw
+   ```
+
+You can edit the basic-memory config.json file located in the /app/.basic-memory/config.json
+
+## CLI Commands via Docker
+
+You can run Basic Memory CLI commands inside the container using `docker exec`:
+
+### Basic Commands
+
+```bash
+# Check status
+docker exec basic-memory-server basic-memory status
+
+# Sync files
+docker exec basic-memory-server basic-memory sync
+
+# Show help
+docker exec basic-memory-server basic-memory --help
+```
+
+### Managing Projects with Volume Mounts
+
+When using Docker volumes, you'll need to configure projects to point to your mounted directories:
+
+1. **Check current configuration:**
+   ```bash
+   docker exec basic-memory-server cat /app/.basic-memory/config.json
+   ```
+
+2. **Add a project for your mounted volume:**
+   ```bash
+   # If you mounted /path/to/your/vault to /app/data
+   docker exec basic-memory-server basic-memory project create my-vault /app/data
+   
+   # Set it as default
+   docker exec basic-memory-server basic-memory project set-default my-vault
+   ```
+
+3. **Sync the new project:**
+   ```bash
+   docker exec basic-memory-server basic-memory sync
+   ```
+
+### Example: Setting up an Obsidian Vault
+
+If you mounted your Obsidian vault like this in docker-compose.yml:
+```yaml
+volumes:
+  - /Users/yourname/Documents/ObsidianVault:/app/data:rw
+```
+
+Then configure it:
+```bash
+# Create project pointing to mounted vault
+docker exec basic-memory-server basic-memory project create obsidian /app/data
+
+# Set as default
+docker exec basic-memory-server basic-memory project set-default obsidian
+
+# Sync to index all files
+docker exec basic-memory-server basic-memory sync
+```
+
+### Environment Variables
+
+Configure Basic Memory using environment variables:
+
+```yaml
+environment:
+
+  # Default project
+  - BASIC_MEMORY_DEFAULT_PROJECT=main
+
+  # Enable real-time sync
+  - BASIC_MEMORY_SYNC_CHANGES=true
+
+  # Logging level
+  - BASIC_MEMORY_LOG_LEVEL=INFO
+
+  # Sync delay in milliseconds
+  - BASIC_MEMORY_SYNC_DELAY=1000
+```
+
+## File Permissions
+
+### Linux/macOS
+
+The Docker container now runs as a non-root user to avoid file ownership issues. By default, the container uses UID/GID 1000, but you can customize this to match your user:
+
+```bash
+# Build with custom UID/GID to match your user
+docker build --build-arg UID=$(id -u) --build-arg GID=$(id -g) -t basic-memory .
+
+# Or use docker-compose with build args
+```
+
+**Example docker-compose.yml with custom user:**
+```yaml
+version: '3.8'
+services:
+  basic-memory:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        UID: 1000  # Replace with your UID
+        GID: 1000  # Replace with your GID
+    container_name: basic-memory-server
+    ports:
+      - "8000:8000"
+    volumes:
+      - /path/to/your/obsidian-vault:/app/data:rw
+      - basic-memory-config:/app/.basic-memory:rw
+    environment:
+      - BASIC_MEMORY_DEFAULT_PROJECT=main
+    restart: unless-stopped
+```
+
+**Using pre-built images:**
+If using the pre-built image from GitHub Container Registry, files will be created with UID/GID 1000. You can either:
+
+1. Change your local directory ownership to match:
+   ```bash
+   sudo chown -R 1000:1000 /path/to/your/obsidian-vault
+   ```
+
+2. Or build your own image with custom UID/GID as shown above.
+
+### Windows
+
+When using Docker Desktop on Windows, ensure the directories are shared:
+
+1. Open Docker Desktop
+2. Go to Settings → Resources → File Sharing
+3. Add your knowledge directory path
+4. Apply & Restart
+
+## Troubleshooting
+
+### Common Issues
+
+1. **File Watching Not Working:**
+    - Ensure volume mounts are read-write (`:rw`)
+    - Check directory permissions
+    - On Linux, may need to increase inotify limits:
+      ```bash
+      echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
+      sudo sysctl -p
+      ```
+
+2. **Configuration Not Persisting:**
+    - Use named volumes for `/app/.basic-memory`
+    - Check volume mount permissions
+
+3. **Network Connectivity:**
+    - For HTTP transport, ensure port 8000 is exposed
+    - Check firewall settings
+
+### Debug Mode
+
+Run with debug logging:
+
+```yaml
+environment:
+  - BASIC_MEMORY_LOG_LEVEL=DEBUG
+```
+
+View logs:
+
+```bash
+docker-compose logs -f basic-memory
+```
+
+
+## Security Considerations
+
+1. **Docker Security:**
+   The container runs as a non-root user (UID/GID 1000 by default) for improved security. You can customize the user ID using build arguments to match your local user.
+
+2. **Volume Permissions:**
+   Ensure mounted directories have appropriate permissions and don't expose sensitive data. With the non-root container, files will be created with the specified user ownership.
+
+3. **Network Security:**
+   If using HTTP transport, consider using reverse proxy with SSL/TLS and authentication if the endpoint is available on
+   a network.
+
+4. **IMPORTANT:** The HTTP endpoints have no authorization. They should not be exposed on a public network.  
+
+## Integration Examples
+
+### Claude Desktop with Docker
+
+The recommended way to connect Claude Desktop to the containerized Basic Memory is using `mcp-proxy`, which converts the HTTP transport to STDIO that Claude Desktop expects:
+
+1. **Start the Docker container:**
+   ```bash
+   docker-compose up -d
+   ```
+
+2. **Configure Claude Desktop** to use mcp-proxy:
+   ```json
+   {
+     "mcpServers": {
+       "basic-memory": {
+         "command": "uvx",
+         "args": [
+           "mcp-proxy",
+           "http://localhost:8000/mcp"
+         ]
+       }
+     }
+   }
+   ```
+
+
+## Support
+
+For Docker-specific issues:
+
+1. Check the [troubleshooting section](#troubleshooting) above
+2. Review container logs: `docker-compose logs basic-memory`
+3. Verify volume mounts: `docker inspect basic-memory-server`
+4. Test file permissions: `docker exec basic-memory-server ls -la /app`
+
+For general Basic Memory support, see the main [README](../README.md)
+and [documentation](https://memory.basicmachines.co/).
+
+## GitHub Container Registry Images
+
+### Available Images
+
+Pre-built Docker images are available on GitHub Container Registry at [`ghcr.io/basicmachines-co/basic-memory`](https://github.com/basicmachines-co/basic-memory/pkgs/container/basic-memory).
+
+**Supported architectures:**
+- `linux/amd64` (Intel/AMD x64)
+- `linux/arm64` (ARM64, including Apple Silicon)
+
+**Available tags:**
+- `latest` - Latest stable release
+- `v0.13.8`, `v0.13.7`, etc. - Specific version tags
+- `v0.13`, `v0.12`, etc. - Major.minor tags
+
+### Automated Builds
+
+Docker images are automatically built and published when new releases are tagged:
+
+1. **Release Process:** When a git tag matching `v*` (e.g., `v0.13.8`) is pushed, the CI workflow automatically:
+   - Builds multi-platform Docker images
+   - Pushes to GitHub Container Registry with appropriate tags
+   - Uses native GitHub integration for seamless publishing
+
+2. **CI/CD Pipeline:** The Docker workflow includes:
+   - Multi-platform builds (AMD64 and ARM64)
+   - Layer caching for faster builds
+   - Automatic tagging with semantic versioning
+   - Security scanning and optimization
+
+### Setup Requirements (For Maintainers)
+
+GitHub Container Registry integration is automatic for this repository:
+
+1. **No external setup required** - GHCR is natively integrated with GitHub
+2. **Automatic permissions** - Uses `GITHUB_TOKEN` with `packages: write` permission
+3. **Public by default** - Images are automatically public for public repositories
+
+The Docker CI workflow (`.github/workflows/docker.yml`) handles everything automatically when version tags are pushed.

docs/Getting Started with Basic Memory.md

@@ -1,176 +0,0 @@
----
-title: Getting Started with Basic Memory
-type: note
-permalink: docs/getting-started
----
-
-# Getting Started with Basic Memory
-
-This guide will help you install Basic Memory, configure it with Claude Desktop, and create your first knowledge notes through conversations.
-
-## Installation
-
-### 1. Install Basic Memory
-
-```bash
-# Install with uv (recommended)
-uv install basic-memory
-
-# Or with pip
-pip install basic-memory
-```
-
-> **Important**: You need to install Basic Memory using one of the commands above to use the command line tools. The `uvx` command mentioned in the Claude Desktop configuration is only for enabling Claude to access Basic Memory.
-
-### 2. Configure Claude Desktop
-
-To enable Claude to read and write to your knowledge base, edit the Claude Desktop configuration file (usually at `~/Library/Application Support/Claude/claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "basic-memory": {
-      "command": "uvx",
-      "args": [
-        "basic-memory",
-        "mcp"
-      ]
-    }
-  }
-}
-```
-
-This configuration uses `uvx` to execute Basic Memory without requiring a full installation in Claude's environment.
-
-### 3. Start the Sync Service
-
-Start the sync service to monitor your files for changes:
-
-```bash
-# One-time sync
-basic-memory sync
-
-# For continuous monitoring (recommended)
-basic-memory sync --watch
-```
-
-The `--watch` flag enables automatic detection of file changes, keeping your knowledge base current.
-
-## Creating Your First Knowledge Note
-
-1. **Start a conversation in Claude Desktop** about any topic:
-   ```
-   You: "Let's talk about coffee brewing methods I've been experimenting with."
-   ```
-
-2. **Have a natural conversation** about the topic
-
-3. **Ask Claude to create a note**:
-   ```
-   You: "Could you create a note summarizing what we've discussed about coffee brewing?"
-   ```
-
-4. **Claude creates a Markdown file** in your `~/basic-memory` directory
-
-5. **View and edit the file** with any text editor or Obsidian
-
-## Using Special Prompts
-
-Basic Memory includes special prompts that help you start conversations with context from your knowledge base:
-
-### Continue Conversation
-
-To resume a previous topic:
-
-```
-You: "Let's continue our conversation about coffee brewing."
-```
-
-This prompt triggers Claude to:
-1. Search your knowledge base for relevant content about coffee brewing
-2. Build context from these documents
-3. Resume the conversation with full awareness of previous discussions
-
-### Recent Activity
-
-To see what you've been working on:
-
-```
-You: "What have we been discussing recently?"
-```
-
-This prompt causes Claude to:
-1. Retrieve documents modified in the recent past
-2. Summarize the topics and main points
-3. Offer to continue any of those discussions
-
-### Search
-
-To find specific information:
-
-```
-You: "Find information about pour over coffee methods."
-```
-
-Claude will:
-1. Search your knowledge base for relevant documents
-2. Summarize the key findings
-3. Offer to explore specific documents in more detail
-
-## Using Your Knowledge Base
-
-### Referencing Knowledge
-
-In future conversations, reference your existing knowledge:
-
-```
-You: "What water temperature did we decide was optimal for coffee brewing?"
-```
-
-Or directly reference notes using memory:// URLs:
-
-```
-You: "Take a look at memory://coffee-brewing-methods and let's discuss how to improve my technique."
-```
-
-### Building On Previous Knowledge
-
-Basic Memory enables continuous knowledge building:
-
-1. **Reference previous discussions** in new conversations
-2. **Add to existing notes** through conversations
-3. **Create connections** between related topics
-4. **Follow relationships** to build comprehensive context
-
-## Importing Existing Conversations
-
-Import your existing AI conversations:
-
-```bash
-# From Claude
-basic-memory import claude conversations
-
-# From ChatGPT
-basic-memory import chatgpt
-```
-
-After importing, run `basic-memory sync` to index everything.
-
-## Quick Tips
-
-- Keep `basic-memory sync --watch` running in a terminal window
-- Use special prompts (Continue Conversation, Recent Activity, Search) to start contextual discussions
-- Build connections between notes for a richer knowledge graph
-- Use direct memory:// URLs when you need precise context
-- Use git to version control your knowledge base
-- Review and edit AI-generated notes for accuracy
-
-## Next Steps
-
-After getting started, explore these areas:
-
-1. **Read the [[User Guide]]** for comprehensive usage instructions
-2. **Understand the [[Knowledge Format]]** to learn how knowledge is structured
-3. **Set up [[Obsidian Integration]]** for visual knowledge navigation
-4. **Learn about [[Canvas]]** visualizations for mapping concepts
-5. **Review the [[CLI Reference]]** for command line tools

docs/Knowledge Format.md

@@ -1,195 +0,0 @@
----
-title: Knowledge Format
-type: note
-permalink: docs/knowledge-format
-tags:
-- architecture
-- patterns
-- knowledge
-- design
----
-
-# Knowledge Format
-
-Basic Memory uses standard Markdown with simple semantic patterns to create a knowledge graph. This document details the file structure and patterns used to organize knowledge.
-
-## File-First Architecture
-
-All knowledge in Basic Memory is stored in plain text Markdown files:
-
-- Files are the source of truth for all knowledge
-- Changes to files automatically update the knowledge graph
-- You maintain complete ownership and control
-- Files work with git and other version control systems
-- Knowledge persists independently of any AI conversation
-
-## Core Document Structure
-
-Every document uses this basic structure:
-
-```markdown
----
-title: Document Title
-type: note
-tags: [tag1, tag2]
-permalink: custom-path
----
-
-# Document Title
-
-Regular markdown content...
-
-## Observations
-- [category] Content with #tags (optional context)
-
-## Relations
-- relation_type [[Other Document]] (optional context)
-```
-
-### Frontmatter
-
-The YAML frontmatter at the top of each file defines essential metadata:
-
-```yaml
----
-title: Document Title    # Used for linking and references
-type: note               # Document type
-tags: [tag1, tag2]       # For organization and searching
-permalink: custom-link   # Optional custom URL path
----
-```
-
-The title is particularly important as it's used to create links between documents.
-
-### Observations
-
-Observations are facts or statements about a topic:
-
-```markdown
-## Observations
-- [tech] Uses SQLite for storage #database
-- [design] Follows local-first architecture #architecture
-- [decision] Selected bcrypt for passwords #security (Based on audit)
-```
-
-Each observation contains:
-- **Category** in [brackets] - classifies the information type
-- **Content text** - the main information
-- Optional **#tags** - additional categorization
-- Optional **(context)** - supporting details
-
-Common categories include:
-- `[tech]`: Technical details
-- `[design]`: Architecture decisions
-- `[feature]`: User capabilities
-- `[decision]`: Choices that were made
-- `[principle]`: Fundamental concepts
-- `[method]`: Approaches or techniques
-- `[preference]`: Personal opinions
-
-### Relations
-
-Relations connect documents to form the knowledge graph:
-
-```markdown
-## Relations
-- implements [[Search Design]]
-- depends_on [[Database Schema]]
-- relates_to [[User Interface]]
-```
-
-You can also create inline references:
-```markdown
-This builds on [[Core Design]] and uses [[Utility Functions]].
-```
-
-Common relation types include:
-- `implements`: Implementation of a specification
-- `depends_on`: Required dependency
-- `relates_to`: General connection
-- `inspired_by`: Source of ideas
-- `extends`: Enhancement
-- `part_of`: Component relationship
-- `contains`: Hierarchical relationship
-- `pairs_with`: Complementary relationship
-
-## Knowledge Graph
-
-Basic Memory automatically builds a knowledge graph from your document connections:
-
-- Each document becomes a node in the graph
-- Relations create edges between nodes
-- Relation types add semantic meaning to connections
-- Forward references can link to documents that don't exist yet
-
-This graph enables rich context building and navigation across your knowledge base.
-
-## Permalinks and memory:// URLs
-
-Every document in Basic Memory has a unique permalink that serves as its stable identifier:
-
-### How Permalinks Work
-
-- **Automatically assigned**: The system generates a permalink for each document
-- **Based on title**: By default, derived from the document title
-- **Always unique**: If conflicts exist, the system adds a suffix to ensure uniqueness
-- **Stable reference**: Remains the same even if the file moves in the directory structure
-- **Used in memory:// URLs**: Forms the basis of the memory:// addressing scheme
-
-You can specify a custom permalink in the frontmatter:
-```yaml
----
-title: Authentication Approaches
-permalink: auth-approaches-2024
----
-```
-
-If not specified, one will be generated automatically from the title.
-
-### Using memory:// URLs
-
-The memory:// URL scheme provides a reliable way to reference knowledge:
-
-```
-memory://auth-approaches-2024        # Direct access by permalink
-memory://Authentication Approaches   # Access by title (automatically resolves)
-memory://project/auth-approaches     # Access by path
-```
-
-Memory URLs support pattern matching for more powerful queries:
-
-```
-memory://auth*                      # All documents with permalinks starting with "auth"
-memory://*/approaches               # All documents with permalinks ending with "approaches"
-memory://project/*/requirements     # All requirements documents in the project folder
-memory://docs/search/implements/*   # Follow all implements relations from search docs
-```
-
-This addressing scheme ensures content remains accessible even as your knowledge base evolves and files are reorganized.
-
-## File Organization
-
-Organize files in any structure that suits your needs:
-
-```
-docs/
-  architecture/
-    design.md
-    patterns.md
-  features/
-    search.md
-    auth.md
-```
-
-You can:
-- Group by topic in folders
-- Use a flat structure with descriptive filenames
-- Tag files for easier discovery
-- Add custom metadata in frontmatter
-
-The system will build the semantic knowledge graph regardless of how you organize your files.
-
-## Relations
-- implemented_by [[User Guide]] (How to work with this format)
-- relates_to [[Getting Started with Basic Memory]] (Setup instructions)
-- explained_in [[Introduction to Basic Memory]] (Overview of the system)

docs/Obsidian Integration.md

@@ -1,146 +0,0 @@
----
-title: Obsidian Integration
-type: note
-permalink: docs/obsidian-integration
----
-
-# Obsidian Integration
-
-Basic Memory integrates seamlessly with [Obsidian](https://obsidian.md), providing powerful visualization and navigation capabilities for your knowledge graph.
-
-## Setup
-
-### Creating an Obsidian Vault
-
-1. Download and install [Obsidian](https://obsidian.md)
-2. Create a new vault
-3. Point it to your Basic Memory directory (~/basic-memory by default)
-4. Enable core plugins like Graph View, Backlinks, and Tags
-
-## Visualization Features
-
-### Graph View
-
-Obsidian's Graph View provides a visual representation of your knowledge network:
-
-- Each document appears as a node
-- Relations appear as connections between nodes
-- Colors can be customized to distinguish types
-- Filters let you focus on specific aspects
-- Local graphs show connections for individual documents
-
-### Backlinks
-
-Obsidian automatically tracks references between documents:
-
-- View all documents that reference the current one
-- See the exact context of each reference
-- Navigate easily through connections
-- Track how concepts relate to each other
-
-### Tag Explorer
-
-Use tags to organize and filter content:
-
-- View all tags in your knowledge base
-- See how many documents use each tag
-- Filter documents by tag combinations
-- Create hierarchical tag structures
-
-## Knowledge Elements
-
-Basic Memory's knowledge format works natively with Obsidian:
-
-### Wiki Links
-
-```markdown
-## Relations
-- implements [[Search Design]]
-- depends_on [[Database Schema]]
-```
-
-These display as clickable links in Obsidian and appear in the graph view.
-
-### Observations with Tags
-
-```markdown
-## Observations
-- [tech] Using SQLite #database
-- [design] Local-first #architecture
-```
-
-Tags become searchable and filterable in Obsidian's tag pane.
-
-### Frontmatter
-
-```yaml
----
-title: Document Title
-type: note
-tags: [search, design]
----
-```
-
-Frontmatter provides metadata for Obsidian to use in search and filtering.
-
-## Canvas Integration
-
-Basic Memory can create [Obsidian Canvas](https://obsidian.md/canvas) files:
-
-1. Ask Claude to create a visualization:
-   ```
-   You: "Create a canvas showing the structure of our project components."
-   ```
-
-2. Claude generates a .canvas file in your knowledge base
-
-3. Open the file in Obsidian to view and edit the visual representation
-
-4. Canvas files maintain references to your documents
-
-## Recommended Plugins
-
-These Obsidian plugins work especially well with Basic Memory:
-
-- **Dataview**: Query your knowledge base programmatically
-- **Kanban**: Organize tasks from knowledge files
-- **Calendar**: View and navigate temporal knowledge
-- **Templates**: Create consistent knowledge structures
-
-## Workflow Suggestions
-
-### Daily Notes
-
-```markdown
-# 2024-01-21
-
-## Progress
-- Updated [[Search Design]]
-- Fixed [[Bug Report 123]]
-
-## Notes
-- [idea] Better indexing #enhancement
-- [todo] Update docs #documentation
-
-## Links
-- relates_to [[Current Sprint]]
-- updates [[Project Status]]
-```
-
-### Project Tracking
-
-```markdown
-# Current Sprint
-
-## Tasks
-- [ ] Update [[Search]]
-- [ ] Fix [[Auth Bug]]
-
-## Tags
-#sprint #planning #current
-```
-
-## Relations
-- enhances [[Introduction to Basic Memory]] (Overview of system)
-- relates_to [[Canvas]] (Visual knowledge mapping)
-- complements [[User Guide]] (Using Basic Memory)

docs/Technical Information.md

@@ -1,99 +0,0 @@
----
-title: Technical Information
-type: note
-permalink: docs/technical-information
----
-
-# Technical Information
-
-This document provides technical details about Basic Memory's implementation, licensing, and integration with the Model Context Protocol (MCP).
-
-## Architecture
-
-Basic Memory consists of:
-
-1. **Core Knowledge Engine**: Parses and indexes Markdown files
-2. **SQLite Database**: Provides fast querying and search
-3. **MCP Server**: Implements the Model Context Protocol
-4. **CLI Tools**: Command-line utilities for management
-5. **Sync Service**: Monitors file changes and updates the database
-
-The system follows a file-first architecture where all knowledge is represented in standard Markdown files and the database serves as a secondary index.
-
-## Model Context Protocol (MCP)
-
-Basic Memory implements the [Model Context Protocol](https://github.com/modelcontextprotocol/spec), an open standard for enabling AI models to access external tools:
-
-- **Standardized Interface**: Common protocol for tool integration
-- **Tool Registration**: Basic Memory registers as a tool provider
-- **Asynchronous Communication**: Enables efficient interaction with AI models
-- **Standardized Schema**: Structured data exchange format
-
-Integration with Claude Desktop uses the MCP to grant Claude access to your knowledge base through a set of specialized tools that search, read, and write knowledge.
-
-## Licensing
-
-Basic Memory is licensed under the [GNU Affero General Public License v3.0 (AGPL-3.0)](https://www.gnu.org/licenses/agpl-3.0.en.html):
-
-- **Free Software**: You can use, study, share, and modify the software
-- **Copyleft**: Derivative works must be distributed under the same license
-- **Network Use**: Network users must be able to receive the source code
-- **Commercial Use**: Allowed, subject to license requirements
-
-The AGPL license ensures Basic Memory remains open source while protecting against proprietary forks.
-
-## Source Code
-
-Basic Memory is developed as an open-source project:
-
-- **GitHub Repository**: [https://github.com/basicmachines-co/basic-memory](https://github.com/basicmachines-co/basic-memory)
-- **Issue Tracker**: Report bugs and request features on GitHub
-- **Contributions**: Pull requests are welcome following the contributing guidelines
-- **Documentation**: Source for this documentation is also available in the repository
-
-## Data Storage and Privacy
-
-Basic Memory is designed with privacy as a core principle:
-
-- **Local-First**: All data remains on your local machine
-- **No Cloud Dependency**: No remote servers or accounts required
-- **Telemetry**: Optional and disabled by default
-- **Standard Formats**: All data is stored in standard file formats you control
-
-## Implementation Details
-
-### Entity Model
-
-Basic Memory's core data model consists of:
-
-- **Entities**: Documents in your knowledge base
-- **Observations**: Facts or statements about entities
-- **Relations**: Connections between entities
-- **Tags**: Additional categorization for entities and observations
-
-The system parses Markdown files to extract this structured information while preserving the human-readable format.
-
-### Sync Process
-
-The sync process:
-
-1. Detects changes to files in the knowledge directory
-2. Parses modified files to extract structured data
-3. Updates the SQLite database with changes
-4. Resolves forward references when new entities are created
-5. Updates the search index for fast querying
-
-### Search Engine
-
-The search functionality:
-
-1. Uses a combination of full-text search and semantic matching
-2. Indexes observations, relations, and content
-3. Supports wildcards and pattern matching in memory:// URLs
-4. Traverses the knowledge graph to follow relationships
-5. Ranks results by relevance to the query
-
-## Relations
-- relates_to [[Introduction to Basic Memory]] (System overview)
-- relates_to [[CLI Reference]] (Command line tools)
-- implements [[Knowledge Format]] (File structure and format)

docs/User Guide.md

@@ -1,518 +0,0 @@
----
-title: User Guide
-type: note
-permalink: docs/user-guide
----
-
-# User Guide
-
-This guide explains how to effectively use Basic Memory in your daily workflow, from creating knowledge through conversations to building a rich semantic network.
-
-## Basic Memory Workflow
-
-Using Basic Memory follows a natural cycle:
-
-1. **Have conversations** with AI assistants like Claude
-2. **Capture knowledge** in Markdown files
-3. **Build connections** between pieces of knowledge
-4. **Reference your knowledge** in future conversations
-5. **Edit files directly** when needed
-6. **Sync changes** automatically
-
-## Creating Knowledge
-
-### Through Conversations
-
-To create knowledge during conversations with Claude:
-
-```
-You: We've covered several authentication approaches. Could you create a note summarizing what we've discussed?
-
-Claude: I'll create a note summarizing our authentication discussion.
-```
-
-This creates a Markdown file in your `~/basic-memory` directory with semantic markup.
-
-### Direct File Creation
-
-You can create files directly:
-
-1. Create a new Markdown file in your `~/basic-memory` directory
-2. Add frontmatter with title, type, and optional tags
-3. Structure content with observations and relations
-4. Save the file
-5. Run `basic-memory sync` if not in watch mode
-
-## Using Special Prompts
-
-Basic Memory includes several special prompts that help you leverage your knowledge base more effectively. In apps like Claude Desktop, these prompts trigger specific tools to search and analyze your knowledge base.
-
-### Continue Conversation
-
-When you want to pick up where you left off on a topic:
-
-```
-You: Let's continue our conversation about authentication systems.
-```
-
-Behind the scenes:
-- Claude searches your knowledge base for content about "authentication systems"
-- It retrieves relevant documents and their relations
-- It analyzes the context to understand where you left off
-- It builds a comprehensive picture of what you've previously discussed
-- It can then resume the conversation with all that context
-
-This is particularly useful when:
-- Starting a new session days or weeks after your last discussion
-- Switching between multiple ongoing projects
-- Building on previous work without repeating yourself
-
-### Recent Activity
-
-To get an overview of what you've been working on:
-
-```
-You: What have we been discussing recently?
-```
-
-Behind the scenes:
-- Claude retrieves documents modified recently
-- It analyzes patterns and themes
-- It summarizes the key topics and changes
-- It offers to continue working on any of those topics
-
-This is useful for:
-- Coming back after a break
-- Getting a quick reminder of ongoing projects
-- Deciding what to work on next
-
-### Search
-
-To find specific information in your knowledge base:
-
-```
-You: Find information about JWT authentication in my notes.
-```
-
-Behind the scenes:
-- Claude performs a semantic search for "JWT authentication"
-- It retrieves and ranks the most relevant documents
-- It summarizes the key findings
-- It offers to explore specific areas in more detail
-
-This is useful for:
-- Finding specific information quickly
-- Exploring what you know about a topic
-- Starting work on an existing topic
-
-### Example
-
-Choose "Continue Conversation"
-![[prompt 1.png|500]]
-
-Enter a topic
-![[prompt2.png|500]]
-
-Give instructions
-![[prompt3.png|500]]
-
-Claude can build context from the supplied topic.
-![[prompt4.png|500]]
-
-
-## Searching Your Knowledge Base
-
-Basic Memory provides multiple ways to search and explore your knowledge base:
-
-### Natural Language Search
-
-The simplest way to search is to ask Claude directly:
-
-```
-You: What do I know about authentication methods?
-```
-
-Claude will search your knowledge base semantically and return relevant information.
-
-### Search Prompt
-
-Use the dedicated search prompt for more focused searches:
-
-```
-You: Search for "JWT authentication"
-```
-
-This triggers a specialized search that returns precise results with document titles, relevant excerpts, and offers to explore specific documents.
-
-### Boolean Search
-
-For more precise searches, use boolean operators to refine your queries:
-
-```
-You: Search for "authentication AND OAuth NOT basic"
-```
-
-Basic Memory supports standard boolean operators:
-
-- **AND**: Find documents containing both terms
-  ```
-  You: Search for "python AND flask"
-  ```
-  This finds documents containing both "python" and "flask"
-
-- **OR**: Find documents containing either term
-  ```
-  You: Search for "python OR javascript"
-  ```
-  This finds documents containing either "python" or "javascript"
-
-- **NOT**: Exclude documents containing specific terms
-  ```
-  You: Search for "python NOT django"
-  ```
-  This finds documents containing "python" but excludes those containing "django"
-
-- **Grouping with parentheses**: Control operator precedence
-  ```
-  You: Search for "(python OR javascript) AND web"
-  ```
-  This finds documents about web development that mention either Python or JavaScript
-
-Boolean search is particularly useful for:
-- Narrowing down results in large knowledge bases
-- Finding specific combinations of concepts
-- Excluding irrelevant content from search results
-- Creating complex queries for precise information retrieval
-
-### Memory URL Pattern Matching
-
-For advanced searches, use memory:// URL patterns with wildcards:
-
-```
-You: Look at memory://auth* and summarize all authentication approaches.
-```
-
-Pattern matching supports:
-- **Wildcards**: `memory://auth*` matches all permalinks starting with "auth"
-- **Path patterns**: `memory://project/*/auth` matches auth documents in any project subfolder
-- **Relation traversal**: `memory://auth-system/implements/*` finds all documents that implement the auth system
-
-### Combining Search with Context Building
-
-The most powerful searches build comprehensive context by following relationships:
-
-```
-You: Search for JWT authentication and then follow all implementation relations.
-```
-
-This builds a complete picture by:
-1. Finding documents about JWT authentication
-2. Following implementation relationships from those documents
-3. Building a complete picture of how JWT is implemented across your system
-
-### Search Best Practices
-
-For effective searching:
-1. **Be specific** with search terms and phrases
-2. **Use boolean operators** to refine searches and find precise information
-3. **Use technical terms** when searching for technical content
-4. **Follow up** on search results by asking for more details about specific documents
-5. **Combine approaches** by starting with search and then using memory:// URLs for precision
-6. **Use relation traversal** to explore connected concepts after finding initial documents
-
-## Referencing Knowledge
-
-### Using memory:// URLs
-
-Reference specific knowledge directly:
-
-```
-You: Please look at memory://authentication-approaches and suggest which approach would be best for our mobile app.
-```
-
-### Natural Language References
-
-Reference knowledge conversationally:
-
-```
-You: What did we decide about authentication for the project?
-```
-
-### Advanced References
-
-Follow connections across your knowledge graph:
-
-```
-You: Look at memory://project-architecture and check related documents to give me a complete picture.
-```
-
-## Working with Files
-
-### File Location and Organization
-
-By default, Basic Memory stores files in `~/basic-memory`:
-
-- Browse this directory in your file explorer
-- Organize files into subfolders
-- Use git for version control
-
-### File Format
-
-Each knowledge file follows this structure:
-
-```markdown
----
-title: Authentication Approaches
-type: note
-tags: [security, architecture]
-permalink: authentication-approaches
----
-
-# Authentication Approaches
-
-A comparison of authentication methods.
-
-## Observations
-- [approach] JWT provides stateless authentication #security
-- [limitation] Session tokens require server-side storage #infrastructure
-
-## Relations
-- implements [[Security Requirements]]
-- affects [[User Login Flow]]
-```
-
-### Editing Files
-
-Modify files in any text editor:
-
-1. Open the file in your preferred editor
-2. Make changes to content, observations, or relations
-3. Save the file
-4. Basic Memory detects changes automatically when running in watch mode
-
-## Building a Knowledge Graph
-
-The value of Basic Memory comes from connections between pieces of knowledge.
-
-### Creating Relations
-
-When creating or editing notes, build connections:
-
-```markdown
-## Relations
-- implements [[Security Requirements]]
-- depends_on [[User Authentication]]
-```
-
-Relations can be:
-- Hierarchical (part_of, contains)
-- Directional (implements, depends_on)
-- Associative (relates_to, similar_to)
-- Temporal (precedes, follows)
-
-Relations are also created via regular wiki-link style links within the body text.
-
-### Forward References
-
-Reference documents that don't exist yet:
-
-```markdown
-- will_impact [[Future Feature]]
-```
-
-These references resolve automatically when you create the referenced document.
-
-## Conversation Continuity
-
-Basic Memory maintains context across different conversations.
-
-### Starting New Sessions with Context
-
-When starting a new conversation with Claude, you can:
-
-1. **Use special prompts** like "Continue conversation about..." or "What were we working on?"
-2. **Reference specific documents** with memory:// URLs
-3. **Ask about recent work** with "What have we been discussing recently?"
-4. **Search for specific topics** with "Find information about..."
-
-### Long-Term Projects
-
-Maintain context for complex projects over time:
-
-1. **Document key decisions** as you make them
-2. **Create relationships** between project components
-3. **Reference past decisions** when implementing features
-4. **Update documentation** as the project evolves
-
-### Tips for Effective Continuity
-
-1. **Be specific about topics** when continuing a conversation
-2. **Reference documents directly** with memory:// URLs for precision
-3. **Create summary notes** after important discussions
-4. **Update existing notes** rather than creating duplicates
-5. **Build robust connections** between related topics
-
-## Advanced Features
-
-### Importing External Knowledge
-
-Import existing conversations:
-
-```bash
-# From Claude
-basic-memory import claude conversations
-
-# From ChatGPT
-basic-memory import chatgpt
-```
-
-After importing, run `basic-memory sync` to index everything.
-
-### Obsidian Integration
-
-Use with [Obsidian](https://obsidian.md):
-
-1. Point Obsidian to your `~/basic-memory` directory
-2. Use Obsidian's graph view to visualize your knowledge network
-3. All changes sync back to Basic Memory
-
-### Canvas Visualizations
-
-Create visual knowledge maps:
-
-```
-You: Could you create a canvas visualization of our project components?
-```
-
-This generates an Obsidian canvas file showing the relationships between concepts.
-
-### Advanced Memory URI Patterns
-
-Use wildcards and patterns:
-
-```
-You: Review memory://project/*/requirements to summarize all project requirements.
-```
-
-## Command Line Interface
-
-### Sync Commands
-
-```bash
-# One-time sync
-basic-memory sync
-
-# Watch for changes
-basic-memory sync --watch
-```
-
-### Status and Information
-
-```bash
-# Check system status
-basic-memory status
-
-# View CLI help
-basic-memory --help
-```
-
-### Import Commands
-
-```bash
-# Import from Claude
-basic-memory import claude conversations
-
-# Import from ChatGPT
-basic-memory import chatgpt
-```
-
-
-## Multiple Projects  
-  
-Basic Memory supports managing multiple separate knowledge bases through projects. This feature allows you to maintain  
-separate knowledge graphs for different purposes (e.g., personal notes, work projects, research topics).  
-
-Basic Memory keeps a list of projects in a config file: ` ~/.basic-memory/config.json`
-  
-### Managing Projects  
-  
-```bash  
-# List all configured projects  
-basic-memory project list  
-  
-# Add a new project  
-basic-memory project add work ~/work-basic-memory  
-  
-# Set the default project  
-basic-memory project default work  
-  
-# Remove a project (doesn't delete files)  
-basic-memory project remove personal  
-  
-# Show current project  
-basic-memory project current  
-```  
-  
-### Using Projects in Commands  
-  
-All commands support the `--project` flag to specify which project to use:  
-  
-```bash  
-# Sync a specific project  
-basic-memory --project=work sync  
-  
-# Run MCP server for a specific project  
-basic-memory --project=personal mcp  
-```  
-  
-You can also set the `BASIC_MEMORY_PROJECT` environment variable:  
-  
-```bash  
-BASIC_MEMORY_PROJECT=work basic-memory sync  
-```  
-  
-### Project Isolation  
-  
-Each project maintains:  
-  
-- Its own collection of markdown files in the specified directory  
-- A separate SQLite database for that project  
-- Complete knowledge graph isolation from other projects
-## Workflow Tips
-
-1. Run sync in watch mode for automatic updates
-2. Use git for version control of your knowledge base
-3. Review and edit AI-created content for accuracy
-4. Periodically organize and refine your knowledge structure
-5. Build rich connections between related ideas
-6. Use forward references to plan future documentation
-7. Start conversations with special prompts to leverage existing knowledge
-
-## Troubleshooting
-
-### Sync Issues
-
-If changes aren't showing up:
-1. Verify `basic-memory sync --watch` is running
-2. Run `basic-memory status` to check system state
-3. Try a manual sync with `basic-memory sync`
-
-### Missing Content
-
-If content isn't found:
-1. Check the exact path and permalink
-2. Try searching with more general terms
-3. Verify the file exists in your knowledge base
-
-### Relation Problems
-
-If relations aren't working:
-1. Ensure exact title matching in [[WikiLinks]]
-2. Check for typos in relation types
-3. Verify both documents exist
-
-## Relations
-- implements [[Knowledge Format]] (How knowledge is structured)
-- relates_to [[Getting Started with Basic Memory]] (Setup and first steps)
-- relates_to [[Canvas]] (Creating visual knowledge maps)
-- relates_to [[CLI Reference]] (Command line tools)

docs/Welcome to Basic memory.md

@@ -1,181 +0,0 @@
----
-title: Introduction to Basic Memory
-type: docs
-permalink: docs/introduction
-tags:
-  - documentation
-  - index
-  - overview
----
-
-# BASIC MEMORY
-
-Basic Memory is a knowledge management system that allows you to build a persistent semantic graph from conversations
-with AI assistants. All knowledge is stored in standard Markdown files on your computer, giving you full control and
-ownership of your data.
-
-## Core Functions
-
-Basic Memory connects you and AI assistants through shared knowledge:
-
-1. **Captures knowledge** from natural conversations with AI assistants
-2. **Structures information** using simple semantic patterns in Markdown
-3. **Enables knowledge reuse** across different conversations and sessions
-4. **Maintains persistence** through local files you control completely
-
-Both you and AI assistants like Claude can read from and write to the same knowledge base, creating a continuous
-learning environment where each conversation builds upon previous ones.
-
-![[Obsidian-CoffeeKnowledgeBase-examples-overlays.gif]]
-
-## Technical Architecture
-
-Basic Memory uses:
-
-- **Files as the source of truth** - Everything is stored in plain Markdown files
-- **Git-compatible storage** - All knowledge can be versioned, branched, and merged
-- **Local SQLite database** - For fast indexing and searching only (not primary storage)
-- **Memory:// URI scheme** - For precise knowledge referencing and navigation
-- **Model Context Protocol (MCP)** - For seamless AI assistant integration
-
-## Knowledge Structure
-
-Knowledge in Basic Memory is organized as a semantic graph:
-
-1. **Entities** - Distinct concepts represented by Markdown documents
-2. **Observations** - Categorized facts and information about entities
-3. **Relations** - Connections between entities that form the knowledge graph
-
-This structure emerges from simple text patterns in standard Markdown:
-
-```markdown
----
-title: Coffee Brewing Methods
-type: note
-permalink: coffee/coffee-brewing-methods
-tags:
-- '#coffee'
-- '#brewing'
-- '#methods'
-- '#demo'
----
-
-# Coffee Brewing Methods
-
-An exploration of different coffee brewing techniques, their characteristics, and how they affect flavor extraction.
-
-## Overview
-
-Coffee brewing is both an art and a science. Different brewing methods extract different compounds from coffee beans,
-resulting in unique flavor profiles, body, and mouthfeel. The key variables in any brewing method are:
-
-- Grind size
-- Water temperature
-- Brew time
-- Coffee-to-water ratio
-- Agitation/turbulence
-
-## Observations
-
-- [principle] Coffee extraction follows a predictable pattern: acids extract first, then sugars, then bitter compounds
-  #extraction
-- [method] Pour over methods generally produce cleaner, brighter cups with more distinct flavor notes #clarity
-
-## Relations
-
-- requires [[Proper Grinding Technique]]
-- affects [[Flavor Extraction]]
-```
-
-Becomes
-
-```json
-{
-  "entities": [
-    {
-      "permalink": "coffee/coffee-brewing-methods",
-      "title": "Coffee Brewing Methods",
-      "file_path": "Coffee Notes/Coffee Brewing Methods.md",
-      "entity_type": "note",
-      "entity_metadata": {
-        "title": "Coffee Brewing Methods",
-        "type": "note",
-        "permalink": "coffee/coffee-brewing-methods",
-        "tags": "['#coffee', '#brewing', '#methods', '#demo']"
-      },
-      "checksum": "bfa32a0f23fa124b53f0694c344d2788b0ce50bd090b55b6d738401d2a349e4c",
-      "content_type": "text/markdown",
-      "observations": [
-        {
-          "category": "principle",
-          "content": "Coffee extraction follows a predictable pattern: acids extract first, then sugars, then bitter compounds #extraction",
-          "tags": [
-            "extraction"
-          ],
-          "permalink": "coffee/coffee-brewing-methods/observations/principle/coffee-extraction-follows-a-predictable-pattern-acids-extract-first-then-sugars-then-bitter-compounds-extraction"
-        },
-        {
-          "category": "method",
-          "content": "Pour over methods generally produce cleaner, brighter cups with more distinct flavor notes #clarity",
-          "tags": [
-            "clarity"
-          ],
-          "permalink": "coffee/coffee-brewing-methods/observations/method/pour-over-methods-generally-produce-cleaner-brighter-cups-with-more-distinct-flavor-notes-clarity"
-        }
-      ],
-      "relations": [
-        {
-          "from_id": "coffee/coffee-bean-origins",
-          "to_id": "coffee/coffee-brewing-methods",
-          "relation_type": "pairs_with",
-          "context": null,
-          "permalink": "coffee/coffee-bean-origins/pairs-with/coffee/coffee-brewing-methods",
-          "to_name": "Coffee Brewing Methods"
-        },
-        {
-          "from_id": "coffee/flavor-extraction",
-          "to_id": "coffee/coffee-brewing-methods",
-          "relation_type": "affected_by",
-          "context": null,
-          "permalink": "coffee/flavor-extraction/affected-by/coffee/coffee-brewing-methods",
-          "to_name": "Coffee Brewing Methods"
-        }
-      ],
-      "created_at": "2025-03-06T14:01:23.445071",
-      "updated_at": "2025-03-06T13:34:48.563606"
-    }
-  ]
-}
-```
-
-Basic Memory understands how to build context via its semantic graph.
-
-## User Control and File Management
-
-Basic Memory gives you complete control over your knowledge:
-
-- **Local-first storage** - All knowledge lives on your computer
-- **Standard file formats** - Plain Markdown compatible with any editor
-- **Directory organization** - Knowledge stored in `~/basic-memory` by default
-- **Version control ready** - Use git for history, branching, and collaboration
-- **Edit anywhere** - Modify files with any text editor or Obsidian
-
-Changes to files automatically update the knowledge graph, and AI assistants can see your edits in future conversations.
-
-## Documentation Map
-
-Continue exploring Basic Memory with these guides:
-
-- Installation and setup [[Getting Started with Basic Memory]]
-- Comprehensive usage instructions [[User Guide]]
-- Detailed explanation of knowledge structure [[Knowledge Format]]
-- Reference for AI assistants using Basic Memory [[AI Assistant Guide]]
-- Technical implementation details [[Technical Information]]
-- Command line tool reference [[CLI Reference]]
-- Obsidian integration guide [[Obsidian Integration]]
-- Canvas visualization guide [[Canvas]]
-
-## Next Steps
-
-Start with the [[Getting Started with Basic Memory]] guide to install Basic Memory and configure it with your AI
-assistant.

docs/character-handling.md

@@ -0,0 +1,241 @@
+# Character Handling and Conflict Resolution
+
+Basic Memory handles various character encoding scenarios and file naming conventions to provide consistent permalink generation and conflict resolution. This document explains how the system works and how to resolve common character-related issues.
+
+## Overview
+
+Basic Memory uses a sophisticated system to generate permalinks from file paths while maintaining consistency across different operating systems and character encodings. The system normalizes file paths and generates unique permalinks to prevent conflicts.
+
+## Character Normalization Rules
+
+### 1. Permalink Generation
+
+When Basic Memory processes a file path, it applies these normalization rules:
+
+```
+Original: "Finance/My Investment Strategy.md"
+Permalink: "finance/my-investment-strategy"
+```
+
+**Transformation process:**
+1. Remove file extension (`.md`)
+2. Convert to lowercase (case-insensitive)
+3. Replace spaces with hyphens
+4. Replace underscores with hyphens
+5. Handle international characters (transliteration for Latin, preservation for non-Latin)
+6. Convert camelCase to kebab-case
+
+### 2. International Character Support
+
+**Latin characters with diacritics** are transliterated:
+- `ø` → `o` (Søren → soren)
+- `ü` → `u` (Müller → muller)
+- `é` → `e` (Café → cafe)
+- `ñ` → `n` (Niño → nino)
+
+**Non-Latin characters** are preserved:
+- Chinese: `中文/测试文档.md` → `中文/测试文档`
+- Japanese: `日本語/文書.md` → `日本語/文書`
+
+## Common Conflict Scenarios
+
+### 1. Hyphen vs Space Conflicts
+
+**Problem:** Files with existing hyphens conflict with generated permalinks from spaces.
+
+**Example:**
+```
+File 1: "basic memory bug.md"     → permalink: "basic-memory-bug"
+File 2: "basic-memory-bug.md"    → permalink: "basic-memory-bug" (CONFLICT!)
+```
+
+**Resolution:** The system automatically resolves this by adding suffixes:
+```
+File 1: "basic memory bug.md"     → permalink: "basic-memory-bug"
+File 2: "basic-memory-bug.md"    → permalink: "basic-memory-bug-1"
+```
+
+**Best Practice:** Choose consistent naming conventions within your project.
+
+### 2. Case Sensitivity Conflicts
+
+**Problem:** Different case variations that normalize to the same permalink.
+
+**Example on macOS:**
+```
+Directory: Finance/investment.md
+Directory: finance/investment.md  (different on filesystem, same permalink)
+```
+
+**Resolution:** Basic Memory detects case conflicts and prevents them during sync operations with helpful error messages.
+
+**Best Practice:** Use consistent casing for directory and file names.
+
+### 3. Character Encoding Conflicts
+
+**Problem:** Different Unicode normalizations of the same logical character.
+
+**Example:**
+```
+File 1: "café.md" (é as single character)
+File 2: "café.md" (e + combining accent)
+```
+
+**Resolution:** Basic Memory normalizes Unicode characters using NFD normalization to detect these conflicts.
+
+### 4. Forward Slash Conflicts
+
+**Problem:** Forward slashes in frontmatter or file names interpreted as path separators.
+
+**Example:**
+```yaml
+---
+permalink: finance/investment/strategy
+---
+```
+
+**Resolution:** Basic Memory validates frontmatter permalinks and warns about path separator conflicts.
+
+## Error Messages and Troubleshooting
+
+### "UNIQUE constraint failed: entity.file_path, entity.project_id"
+
+**Cause:** Two entities trying to use the same file path within a project.
+
+**Common scenarios:**
+1. File move operation where destination is already occupied
+2. Case sensitivity differences on macOS
+3. Character encoding conflicts
+4. Concurrent file operations
+
+**Resolution steps:**
+1. Check for duplicate file names with different cases
+2. Look for files with similar names but different character encodings
+3. Rename conflicting files to have unique names
+4. Run sync again after resolving conflicts
+
+### "File path conflict detected during move"
+
+**Cause:** Enhanced conflict detection preventing potential database integrity violations.
+
+**What this means:** The system detected that moving a file would create a conflict before attempting the database operation.
+
+**Resolution:** Follow the specific guidance in the error message, which will indicate the type of conflict detected.
+
+## Best Practices
+
+### 1. File Naming Conventions
+
+**Recommended patterns:**
+- Use consistent casing (prefer lowercase)
+- Use hyphens instead of spaces for multi-word files
+- Avoid special characters that could conflict with path separators
+- Be consistent with directory structure casing
+
+**Examples:**
+```
+✅ Good:
+- finance/investment-strategy.md
+- projects/basic-memory-features.md
+- docs/api-reference.md
+
+❌ Problematic:
+- Finance/Investment Strategy.md  (mixed case, spaces)
+- finance/Investment Strategy.md  (inconsistent case)
+- docs/API/Reference.md          (mixed case directories)
+```
+
+### 2. Permalink Management
+
+**Custom permalinks in frontmatter:**
+```yaml
+---
+type: knowledge
+permalink: custom-permalink-name
+---
+```
+
+**Guidelines:**
+- Use lowercase permalinks
+- Use hyphens for word separation
+- Avoid path separators unless creating sub-paths
+- Ensure uniqueness within your project
+
+### 3. Directory Structure
+
+**Consistent casing:**
+```
+✅ Good:
+finance/
+  investment-strategies.md
+  portfolio-management.md
+
+❌ Problematic:  
+Finance/           (capital F)
+  investment-strategies.md
+finance/           (lowercase f) 
+  portfolio-management.md
+```
+
+## Migration and Cleanup
+
+### Identifying Conflicts
+
+Use Basic Memory's built-in conflict detection:
+
+```bash
+# Sync will report conflicts
+basic-memory sync
+
+# Check sync status for warnings
+basic-memory status
+```
+
+### Resolving Existing Conflicts
+
+1. **Identify conflicting files** from sync error messages
+2. **Choose consistent naming convention** for your project
+3. **Rename files** to follow the convention
+4. **Re-run sync** to verify resolution
+
+### Bulk Renaming Strategy
+
+For projects with many conflicts:
+
+1. **Backup your project** before making changes
+2. **Standardize on lowercase** file and directory names
+3. **Replace spaces with hyphens** in file names
+4. **Use consistent character encoding** (UTF-8)
+5. **Test sync after each batch** of changes
+
+## System Enhancements
+
+### Recent Improvements (v0.13+)
+
+1. **Enhanced conflict detection** before database operations
+2. **Improved error messages** with specific resolution guidance
+3. **Character normalization utilities** for consistent handling
+4. **File swap detection** for complex move scenarios
+5. **Proactive conflict warnings** during permalink resolution
+
+### Monitoring and Logging
+
+The system now provides detailed logging for conflict resolution:
+
+```
+DEBUG: Detected potential file path conflicts for 'Finance/Investment.md': ['finance/investment.md']
+WARNING: File path conflict detected during move: entity_id=123 trying to move from 'old.md' to 'new.md'
+```
+
+These logs help identify and resolve conflicts before they cause sync failures.
+
+## Support and Resources
+
+If you encounter character-related conflicts not covered in this guide:
+
+1. **Check the logs** for specific conflict details
+2. **Review error messages** for resolution guidance  
+3. **Report issues** with examples of the conflicting files
+4. **Consider the file naming best practices** outlined above
+
+The Basic Memory system is designed to handle most character conflicts automatically while providing clear guidance for manual resolution when needed.

docs/cloud-cli.md

@@ -0,0 +1,726 @@
+# Basic Memory Cloud CLI Guide
+
+The Basic Memory Cloud CLI provides seamless integration between local and cloud knowledge bases using **project-scoped synchronization**. Each project can optionally sync with the cloud, giving you fine-grained control over what syncs and where.
+
+## Overview
+
+The cloud CLI enables you to:
+- **Toggle cloud mode** - All regular `bm` commands work with cloud when enabled
+- **Project-scoped sync** - Each project independently manages its sync configuration
+- **Explicit operations** - Sync only what you want, when you want
+- **Bidirectional sync** - Keep local and cloud in sync with rclone bisync
+- **Offline access** - Work locally, sync when ready
+
+## Prerequisites
+
+Before using Basic Memory Cloud, you need:
+
+- **Active Subscription**: An active Basic Memory Cloud subscription is required to access cloud features
+- **Subscribe**: Visit [https://basicmemory.com/subscribe](https://basicmemory.com/subscribe) to sign up
+
+If you attempt to log in without an active subscription, you'll receive a "Subscription Required" error with a link to subscribe.
+
+## Architecture: Project-Scoped Sync
+
+### The Problem
+
+**Old approach (SPEC-8):** All projects lived in a single `~/basic-memory-cloud-sync/` directory. This caused:
+- ❌ Directory conflicts between mount and bisync
+- ❌ Auto-discovery creating phantom projects
+- ❌ Confusion about what syncs and when
+- ❌ All-or-nothing sync (couldn't sync just one project)
+
+**New approach (SPEC-20):** Each project independently configures sync.
+
+### How It Works
+
+**Projects can exist in three states:**
+
+1. **Cloud-only** - Project exists on cloud, no local copy
+2. **Cloud + Local (synced)** - Project has a local working directory that syncs
+3. **Local-only** - Project exists locally (when cloud mode is disabled)
+
+**Example:**
+
+```bash
+# You have 3 projects on cloud:
+# - research: wants local sync at ~/Documents/research
+# - work: wants local sync at ~/work-notes
+# - temp: cloud-only, no local sync needed
+
+bm project add research --local-path ~/Documents/research
+bm project add work --local-path ~/work-notes
+bm project add temp  # No local sync
+
+# Now you can sync individually (after initial --resync):
+bm project bisync --name research
+bm project bisync --name work
+# temp stays cloud-only
+```
+
+**What happens under the covers:**
+- Config stores `cloud_projects` dict mapping project names to local paths
+- Each project gets its own bisync state in `~/.basic-memory/bisync-state/{project}/`
+- Rclone syncs using single remote: `basic-memory-cloud`
+- Projects can live anywhere on your filesystem, not forced into sync directory
+
+## Quick Start
+
+### 1. Enable Cloud Mode
+
+Authenticate and enable cloud mode:
+
+```bash
+bm cloud login
+```
+
+**What this does:**
+1. Opens browser to Basic Memory Cloud authentication page
+2. Stores authentication token in `~/.basic-memory/auth/token`
+3. **Enables cloud mode** - all CLI commands now work against cloud
+4. Validates your subscription status
+
+**Result:** All `bm project`, `bm tools` commands now work with cloud.
+
+### 2. Set Up Sync
+
+Install rclone and configure credentials:
+
+```bash
+bm cloud setup
+```
+
+**What this does:**
+1. Installs rclone automatically (if needed)
+2. Fetches your tenant information from cloud
+3. Generates scoped S3 credentials for sync
+4. Configures single rclone remote: `basic-memory-cloud`
+
+**Result:** You're ready to sync projects. No sync directories created yet - those come with project setup.
+
+### 3. Add Projects with Sync
+
+Create projects with optional local sync paths:
+
+```bash
+# Create cloud project without local sync
+bm project add research
+
+# Create cloud project WITH local sync
+bm project add research --local-path ~/Documents/research
+
+# Or configure sync for existing project
+bm project sync-setup research ~/Documents/research
+```
+
+**What happens under the covers:**
+
+When you add a project with `--local-path`:
+1. Project created on cloud at `/app/data/research`
+2. Local path stored in config: `cloud_projects.research.local_path = "~/Documents/research"`
+3. Local directory created if it doesn't exist
+4. Bisync state directory created at `~/.basic-memory/bisync-state/research/`
+
+**Result:** Project is ready to sync, but no files synced yet.
+
+### 4. Sync Your Project
+
+Establish the initial sync baseline. **Best practice:** Always preview with `--dry-run` first:
+
+```bash
+# Step 1: Preview the initial sync (recommended)
+bm project bisync --name research --resync --dry-run
+
+# Step 2: If all looks good, run the actual sync
+bm project bisync --name research --resync
+```
+
+**What happens under the covers:**
+1. Rclone reads from `~/Documents/research` (local)
+2. Connects to `basic-memory-cloud:bucket-name/app/data/research` (remote)
+3. Creates bisync state files in `~/.basic-memory/bisync-state/research/`
+4. Syncs files bidirectionally with settings:
+   - `conflict_resolve=newer` (most recent wins)
+   - `max_delete=25` (safety limit)
+   - Respects `.bmignore` patterns
+
+**Result:** Local and cloud are in sync. Baseline established.
+
+**Why `--resync`?** This is an rclone requirement for the first bisync run. It establishes the initial state that future syncs will compare against. After the first sync, never use `--resync` unless you need to force a new baseline.
+
+See: https://rclone.org/bisync/#resync
+```
+--resync
+This will effectively make both Path1 and Path2 filesystems contain a matching superset of all files. By default, Path2 files that do not exist in Path1 will be copied to Path1, and the process will then copy the Path1 tree to Path2.
+```
+
+### 5. Subsequent Syncs
+
+After the first sync, just run bisync without `--resync`:
+
+```bash
+bm project bisync --name research
+```
+
+**What happens:**
+1. Rclone compares local and cloud states
+2. Syncs changes in both directions
+3. Auto-resolves conflicts (newer file wins)
+4. Updates `last_sync` timestamp in config
+
+**Result:** Changes flow both ways - edit locally or in cloud, both stay in sync.
+
+### 6. Verify Setup
+
+Check status:
+
+```bash
+bm cloud status
+```
+
+You should see:
+- `Mode: Cloud (enabled)`
+- `Cloud instance is healthy`
+- Instructions for project sync commands
+
+## Working with Projects
+
+### Understanding Project Commands
+
+**Key concept:** When cloud mode is enabled, use regular `bm project` commands (not `bm cloud project`).
+
+```bash
+# In cloud mode:
+bm project list              # Lists cloud projects
+bm project add research      # Creates cloud project
+
+# In local mode:
+bm project list              # Lists local projects
+bm project add research ~/Documents/research  # Creates local project
+```
+
+### Creating Projects
+
+**Use case 1: Cloud-only project (no local sync)**
+
+```bash
+bm project add temp-notes
+```
+
+**What this does:**
+- Creates project on cloud at `/app/data/temp-notes`
+- No local directory created
+- No sync configuration
+
+**Result:** Project exists on cloud, accessible via MCP tools, but no local copy.
+
+**Use case 2: Cloud project with local sync**
+
+```bash
+bm project add research --local-path ~/Documents/research
+```
+
+**What this does:**
+- Creates project on cloud at `/app/data/research`
+- Creates local directory `~/Documents/research`
+- Stores sync config in `~/.basic-memory/config.json`
+- Prepares for bisync (but doesn't sync yet)
+
+**Result:** Project ready to sync. Run `bm project bisync --name research --resync` to establish baseline.
+
+**Use case 3: Add sync to existing cloud project**
+
+```bash
+# Project already exists on cloud
+bm project sync-setup research ~/Documents/research
+```
+
+**What this does:**
+- Updates existing project's sync configuration
+- Creates local directory
+- Prepares for bisync
+
+**Result:** Existing cloud project now has local sync path. Run bisync to pull files down.
+
+### Listing Projects
+
+View all projects:
+
+```bash
+bm project list
+```
+
+**What you see:**
+- All projects in cloud (when cloud mode enabled)
+- Default project marked
+- Project paths shown
+
+**Future:** Will show sync status (synced/not synced, last sync time).
+
+## File Synchronization
+
+### Understanding the Sync Commands
+
+**There are three sync-related commands:**
+
+1. `bm project sync` - One-way: local → cloud (make cloud match local)
+2. `bm project bisync` - Two-way: local ↔ cloud (recommended)
+3. `bm project check` - Verify files match (no changes)
+
+### One-Way Sync: Local → Cloud
+
+**Use case:** You made changes locally and want to push to cloud (overwrite cloud).
+
+```bash
+bm project sync --name research
+```
+
+**What happens:**
+1. Reads files from `~/Documents/research` (local)
+2. Uses rclone sync to make cloud identical to local
+3. Respects `.bmignore` patterns
+4. Shows progress bar
+
+**Result:** Cloud now matches local exactly. Any cloud-only changes are overwritten.
+
+**When to use:**
+- You know local is the source of truth
+- You want to force cloud to match local
+- You don't care about cloud changes
+
+### Two-Way Sync: Local ↔ Cloud (Recommended)
+
+**Use case:** You edit files both locally and in cloud UI, want both to stay in sync.
+
+```bash
+# First time - establish baseline
+bm project bisync --name research --resync
+
+# Subsequent syncs
+bm project bisync --name research
+```
+
+**What happens:**
+1. Compares local and cloud states using bisync metadata
+2. Syncs changes in both directions
+3. Auto-resolves conflicts (newer file wins)
+4. Detects excessive deletes and fails safely (max 25 files)
+
+**Conflict resolution example:**
+
+```bash
+# Edit locally
+echo "Local change" > ~/Documents/research/notes.md
+
+# Edit same file in cloud UI
+# Cloud now has: "Cloud change"
+
+# Run bisync
+bm project bisync --name research
+
+# Result: Newer file wins (based on modification time)
+# If cloud was more recent, cloud version kept
+# If local was more recent, local version kept
+```
+
+**When to use:**
+- Default workflow for most users
+- You edit in multiple places
+- You want automatic conflict resolution
+
+### Verify Sync Integrity
+
+**Use case:** Check if local and cloud match without making changes.
+
+```bash
+bm project check --name research
+```
+
+**What happens:**
+1. Compares file checksums between local and cloud
+2. Reports differences
+3. No files transferred
+
+**Result:** Shows which files differ. Run bisync to sync them.
+
+```bash
+# One-way check (faster)
+bm project check --name research --one-way
+```
+
+### Preview Changes (Dry Run)
+
+**Use case:** See what would change without actually syncing.
+
+```bash
+bm project bisync --name research --dry-run
+```
+
+**What happens:**
+1. Runs bisync logic
+2. Shows what would be transferred/deleted
+3. No actual changes made
+
+**Result:** Safe preview of sync operations.
+
+### Advanced: List Remote Files
+
+**Use case:** See what files exist on cloud without syncing.
+
+```bash
+# List all files in project
+bm project ls --name research
+
+# List files in subdirectory
+bm project ls --name research --path subfolder
+```
+
+**What happens:**
+1. Connects to cloud via rclone
+2. Lists files in remote project path
+3. No files transferred
+
+**Result:** See cloud file listing.
+
+## Multiple Projects
+
+### Syncing Multiple Projects
+
+**Use case:** You have several projects with local sync, want to sync all at once.
+
+```bash
+# Setup multiple projects
+bm project add research --local-path ~/Documents/research
+bm project add work --local-path ~/work-notes
+bm project add personal --local-path ~/personal
+
+# Establish baselines
+bm project bisync --name research --resync
+bm project bisync --name work --resync
+bm project bisync --name personal --resync
+
+# Daily workflow: sync everything
+bm project bisync --name research
+bm project bisync --name work
+bm project bisync --name personal
+```
+
+**Future:** `--all` flag will sync all configured projects:
+
+```bash
+bm project bisync --all  # Coming soon
+```
+
+### Mixed Usage
+
+**Use case:** Some projects sync, some stay cloud-only.
+
+```bash
+# Projects with sync
+bm project add research --local-path ~/Documents/research
+bm project add work --local-path ~/work
+
+# Cloud-only projects
+bm project add archive
+bm project add temp-notes
+
+# Sync only the configured ones
+bm project bisync --name research
+bm project bisync --name work
+
+# Archive and temp-notes stay cloud-only
+```
+
+**Result:** Fine-grained control over what syncs.
+
+## Disable Cloud Mode
+
+Return to local mode:
+
+```bash
+bm cloud logout
+```
+
+**What this does:**
+1. Disables cloud mode in config
+2. All commands now work locally
+3. Auth token remains (can re-enable with login)
+
+**Result:** All `bm` commands work with local projects again.
+
+## Filter Configuration
+
+### Understanding .bmignore
+
+**The problem:** You don't want to sync everything (e.g., `.git`, `node_modules`, database files).
+
+**The solution:** `.bmignore` file with gitignore-style patterns.
+
+**Location:** `~/.basic-memory/.bmignore`
+
+**Default patterns:**
+
+```gitignore
+# Version control
+.git/**
+
+# Python
+__pycache__/**
+*.pyc
+.venv/**
+venv/**
+
+# Node.js
+node_modules/**
+
+# Basic Memory internals
+memory.db/**
+memory.db-shm/**
+memory.db-wal/**
+config.json/**
+watch-status.json/**
+.bmignore.rclone/**
+
+# OS files
+.DS_Store/**
+Thumbs.db/**
+
+# Environment files
+.env/**
+.env.local/**
+```
+
+**How it works:**
+1. On first sync, `.bmignore` created with defaults
+2. Patterns converted to rclone filter format (`.bmignore.rclone`)
+3. Rclone uses filters during sync
+4. Same patterns used by all projects
+
+**Customizing:**
+
+```bash
+# Edit patterns
+code ~/.basic-memory/.bmignore
+
+# Add custom patterns
+echo "*.tmp/**" >> ~/.basic-memory/.bmignore
+
+# Next sync uses updated patterns
+bm project bisync --name research
+```
+
+## Troubleshooting
+
+### Authentication Issues
+
+**Problem:** "Authentication failed" or "Invalid token"
+
+**Solution:** Re-authenticate:
+
+```bash
+bm cloud logout
+bm cloud login
+```
+
+### Subscription Issues
+
+**Problem:** "Subscription Required" error
+
+**Solution:**
+1. Visit subscribe URL shown in error
+2. Sign up for subscription
+3. Run `bm cloud login` again
+
+**Note:** Access is immediate when subscription becomes active.
+
+### Bisync Initialization
+
+**Problem:** "First bisync requires --resync"
+
+**Explanation:** Bisync needs a baseline state before it can sync changes.
+
+**Solution:**
+
+```bash
+bm project bisync --name research --resync
+```
+
+**What this does:**
+- Establishes initial sync state
+- Creates baseline in `~/.basic-memory/bisync-state/research/`
+- Syncs all files bidirectionally
+
+**Result:** Future syncs work without `--resync`.
+
+### Empty Directory Issues
+
+**Problem:** "Empty prior Path1 listing. Cannot sync to an empty directory"
+
+**Explanation:** Rclone bisync doesn't work well with completely empty directories. It needs at least one file to establish a baseline.
+
+**Solution:** Add at least one file before running `--resync`:
+
+```bash
+# Create a placeholder file
+echo "# Research Notes" > ~/Documents/research/README.md
+
+# Now run bisync
+bm project bisync --name research --resync
+```
+
+**Why this happens:** Bisync creates listing files that track the state of each side. When both directories are completely empty, these listing files are considered invalid by rclone.
+
+**Best practice:** Always have at least one file (like a README.md) in your project directory before setting up sync.
+
+### Bisync State Corruption
+
+**Problem:** Bisync fails with errors about corrupted state or listing files
+
+**Explanation:** Sometimes bisync state can become inconsistent (e.g., after mixing dry-run and actual runs, or after manual file operations).
+
+**Solution:** Clear bisync state and re-establish baseline:
+
+```bash
+# Clear bisync state
+bm project bisync-reset research
+
+# Re-establish baseline
+bm project bisync --name research --resync
+```
+
+**What this does:**
+- Removes all bisync metadata from `~/.basic-memory/bisync-state/research/`
+- Forces fresh baseline on next `--resync`
+- Safe operation (doesn't touch your files)
+
+**Note:** This command also runs automatically when you remove a project to clean up state directories.
+
+### Too Many Deletes
+
+**Problem:** "Error: max delete limit (25) exceeded"
+
+**Explanation:** Bisync detected you're about to delete more than 25 files. This is a safety check to prevent accidents.
+
+**Solution 1:** Review what you're deleting, then force resync:
+
+```bash
+# Check what would be deleted
+bm project bisync --name research --dry-run
+
+# If correct, establish new baseline
+bm project bisync --name research --resync
+```
+
+**Solution 2:** Use one-way sync if you know local is correct:
+
+```bash
+bm project sync --name research
+```
+
+### Project Not Configured for Sync
+
+**Problem:** "Project research has no local_sync_path configured"
+
+**Explanation:** Project exists on cloud but has no local sync path.
+
+**Solution:**
+
+```bash
+bm project sync-setup research ~/Documents/research
+bm project bisync --name research --resync
+```
+
+### Connection Issues
+
+**Problem:** "Cannot connect to cloud instance"
+
+**Solution:** Check status:
+
+```bash
+bm cloud status
+```
+
+If instance is down, wait a few minutes and retry.
+
+## Security
+
+- **Authentication**: OAuth 2.1 with PKCE flow
+- **Tokens**: Stored securely in `~/.basic-memory/basic-memory-cloud.json`
+- **Transport**: All data encrypted in transit (HTTPS)
+- **Credentials**: Scoped S3 credentials (read-write to your tenant only)
+- **Isolation**: Your data isolated from other tenants
+- **Ignore patterns**: Sensitive files automatically excluded via `.bmignore`
+
+## Command Reference
+
+### Cloud Mode Management
+
+```bash
+bm cloud login              # Authenticate and enable cloud mode
+bm cloud logout             # Disable cloud mode
+bm cloud status             # Check cloud mode and instance health
+```
+
+### Setup
+
+```bash
+bm cloud setup              # Install rclone and configure credentials
+```
+
+### Project Management
+
+When cloud mode is enabled:
+
+```bash
+bm project list                           # List cloud projects
+bm project add <name>                     # Create cloud project (no sync)
+bm project add <name> --local-path <path> # Create with local sync
+bm project sync-setup <name> <path>       # Add sync to existing project
+bm project rm <name>                      # Delete project
+```
+
+### File Synchronization
+
+```bash
+# One-way sync (local → cloud)
+bm project sync --name <project>
+bm project sync --name <project> --dry-run
+bm project sync --name <project> --verbose
+
+# Two-way sync (local ↔ cloud) - Recommended
+bm project bisync --name <project>          # After first --resync
+bm project bisync --name <project> --resync # First time / force baseline
+bm project bisync --name <project> --dry-run
+bm project bisync --name <project> --verbose
+
+# Integrity check
+bm project check --name <project>
+bm project check --name <project> --one-way
+
+# List remote files
+bm project ls --name <project>
+bm project ls --name <project> --path <subpath>
+```
+
+## Summary
+
+**Basic Memory Cloud uses project-scoped sync:**
+
+1. **Enable cloud mode** - `bm cloud login`
+2. **Install rclone** - `bm cloud setup`
+3. **Add projects with sync** - `bm project add research --local-path ~/Documents/research`
+4. **Preview first sync** - `bm project bisync --name research --resync --dry-run`
+5. **Establish baseline** - `bm project bisync --name research --resync`
+6. **Daily workflow** - `bm project bisync --name research`
+
+**Key benefits:**
+- ✅ Each project independently syncs (or doesn't)
+- ✅ Projects can live anywhere on disk
+- ✅ Explicit sync operations (no magic)
+- ✅ Safe by design (max delete limits, conflict resolution)
+- ✅ Full offline access (work locally, sync when ready)
+
+**Future enhancements:**
+- `--all` flag to sync all configured projects
+- Project list showing sync status
+- Watch mode for automatic sync

examples/.obsidian/app.json

@@ -1,3 +0,0 @@
-{
-  "promptDelete": false
-}

examples/.obsidian/appearance.json

@@ -1 +0,0 @@
-{}

examples/.obsidian/community-plugins.json

@@ -1,3 +0,0 @@
-[
-  "optimize-canvas-connections"
-]

examples/.obsidian/core-plugins.json

@@ -1,31 +0,0 @@
-{
-  "file-explorer": true,
-  "global-search": true,
-  "switcher": true,
-  "graph": true,
-  "backlink": true,
-  "canvas": true,
-  "outgoing-link": true,
-  "tag-pane": true,
-  "properties": false,
-  "page-preview": true,
-  "daily-notes": true,
-  "templates": true,
-  "note-composer": true,
-  "command-palette": true,
-  "slash-command": false,
-  "editor-status": true,
-  "bookmarks": true,
-  "markdown-importer": false,
-  "zk-prefixer": false,
-  "random-note": false,
-  "outline": true,
-  "word-count": true,
-  "slides": false,
-  "audio-recorder": false,
-  "workspaces": false,
-  "file-recovery": true,
-  "publish": true,
-  "sync": true,
-  "webviewer": false
-}

examples/.obsidian/graph.json

@@ -1,22 +0,0 @@
-{
-  "collapse-filter": true,
-  "search": "",
-  "showTags": false,
-  "showAttachments": false,
-  "hideUnresolved": false,
-  "showOrphans": true,
-  "collapse-color-groups": true,
-  "colorGroups": [],
-  "collapse-display": true,
-  "showArrow": false,
-  "textFadeMultiplier": 0,
-  "nodeSizeMultiplier": 1,
-  "lineSizeMultiplier": 1,
-  "collapse-forces": true,
-  "centerStrength": 0.518713248970312,
-  "repelStrength": 10,
-  "linkStrength": 1,
-  "linkDistance": 250,
-  "scale": 1,
-  "close": false
-}

examples/.obsidian/plugins/optimize-canvas-connections/main.js

@@ -1,158 +0,0 @@
-/*
-THIS IS A GENERATED/BUNDLED FILE BY ESBUILD
-if you want to view the source, please visit the github repository of this plugin
-*/
-
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// main.ts
-var main_exports = {};
-__export(main_exports, {
-  default: () => OptimizeCanvasConnectionsPlugin
-});
-module.exports = __toCommonJS(main_exports);
-var import_obsidian = require("obsidian");
-var OptimizeCanvasConnectionsPlugin = class extends import_obsidian.Plugin {
-  async onload() {
-    this.addCommand({
-      id: "optimize-preserve-axes-selection",
-      name: "Optimize selection (preserve axes)",
-      checkCallback: (checking) => {
-        const canvasView = app.workspace.getActiveViewOfType(import_obsidian.ItemView);
-        if ((canvasView == null ? void 0 : canvasView.getViewType()) == "canvas") {
-          if (!checking) {
-            this.optimize("preserve-axes");
-          }
-          return true;
-        }
-        return false;
-      }
-    });
-    this.addCommand({
-      id: "optimize-shortest-path-selection",
-      name: "Optimize selection (shortest path)",
-      checkCallback: (checking) => {
-        const canvasView = app.workspace.getActiveViewOfType(import_obsidian.ItemView);
-        if ((canvasView == null ? void 0 : canvasView.getViewType()) == "canvas") {
-          if (!checking) {
-            this.optimize("shortest-path");
-          }
-          return true;
-        }
-        return false;
-      }
-    });
-  }
-  onunload() {
-  }
-  async optimize(option) {
-    const canvasView = app.workspace.getActiveViewOfType(import_obsidian.ItemView);
-    const canvas = canvasView == null ? void 0 : canvasView.canvas;
-    const currentSelection = canvas == null ? void 0 : canvas.selection;
-    let selectedIDs = new Array();
-    currentSelection.forEach(function(selection) {
-      selectedIDs.push(selection.id);
-    });
-    let applyToAll = false;
-    if (selectedIDs.length == 0) {
-      applyToAll = true;
-    }
-    for (let [edgeKey, edge] of canvas["edges"]) {
-      let fromNode = edge["from"]["node"];
-      let toNode = edge["to"]["node"];
-      let fromPossibilities = [edge["from"]["side"]];
-      if (applyToAll || selectedIDs.includes(fromNode["id"])) {
-        switch (option) {
-          case "shortest-path":
-            fromPossibilities = ["top", "bottom", "left", "right"];
-            break;
-          case "preserve-axes":
-            switch (edge["from"]["side"]) {
-              case "top":
-              case "bottom":
-                fromPossibilities = ["top", "bottom"];
-                break;
-              case "left":
-              case "right":
-                fromPossibilities = ["left", "right"];
-                break;
-            }
-        }
-      }
-      let toPossibilities = [edge["to"]["side"]];
-      if (applyToAll || selectedIDs.includes(toNode["id"])) {
-        switch (option) {
-          case "shortest-path":
-            toPossibilities = ["top", "bottom", "left", "right"];
-            break;
-          case "preserve-axes":
-            switch (edge["to"]["side"]) {
-              case "top":
-              case "bottom":
-                toPossibilities = ["top", "bottom"];
-                break;
-              case "left":
-              case "right":
-                toPossibilities = ["left", "right"];
-                break;
-            }
-        }
-      }
-      let distances = [];
-      for (const fromSide of fromPossibilities) {
-        let fromPoint = { "x": 0, "y": 0 };
-        if (fromSide == "top") {
-          fromPoint = { "x": fromNode["x"] + fromNode["width"] / 2, "y": fromNode["y"] };
-        } else if (fromSide == "bottom") {
-          fromPoint = { "x": fromNode["x"] + fromNode["width"] / 2, "y": fromNode["y"] + fromNode["height"] };
-        } else if (fromSide == "left") {
-          fromPoint = { "x": fromNode["x"], "y": fromNode["y"] + fromNode["height"] / 2 };
-        } else if (fromSide == "right") {
-          fromPoint = { "x": fromNode["x"] + fromNode["width"], "y": fromNode["y"] + fromNode["height"] / 2 };
-        }
-        for (const toSide of toPossibilities) {
-          let toPoint = { "x": 0, "y": 0 };
-          if (toSide == "top") {
-            toPoint = { "x": toNode["x"] + toNode["width"] / 2, "y": toNode["y"] };
-          } else if (toSide == "bottom") {
-            toPoint = { "x": toNode["x"] + toNode["width"] / 2, "y": toNode["y"] + toNode["height"] };
-          } else if (toSide == "left") {
-            toPoint = { "x": toNode["x"], "y": toNode["y"] + toNode["height"] / 2 };
-          } else if (toSide == "right") {
-            toPoint = { "x": toNode["x"] + toNode["width"], "y": toNode["y"] + toNode["height"] / 2 };
-          }
-          distances.push({
-            "fromSide": fromSide,
-            "toSide": toSide,
-            "distance": (toPoint.x - fromPoint.x) ** 2 + (toPoint.y - fromPoint.y) ** 2
-          });
-        }
-      }
-      distances = distances.sort(function(a, b) {
-        return a.distance - b.distance;
-      });
-      edge["from"]["side"] = distances[0]["fromSide"];
-      edge["to"]["side"] = distances[0]["toSide"];
-      edge.render();
-    }
-    canvas.requestSave();
-  }
-};
-
-/* nosourcemap */

examples/.obsidian/plugins/optimize-canvas-connections/manifest.json

@@ -1,10 +0,0 @@
-{
-	"id": "optimize-canvas-connections",
-	"name": "Optimize Canvas Connections",
-	"version": "1.0.0",
-	"minAppVersion": "1.1.9",
-	"description": "An Obsidian plugin that declutters a canvas by reconnecting notes using their nearest edges.",
-	"author": "Félix Chénier",
-	"authorUrl": "https://felixchenier.uqam.ca",
-	"isDesktopOnly": false
-}

examples/.obsidian/publish.json

@@ -1,6 +0,0 @@
-{
-  "siteId": null,
-  "host": null,
-  "included": [],
-  "excluded": []
-}

examples/.obsidian/workspace.json

@@ -1,186 +0,0 @@
-{
-  "main": {
-    "id": "7ae5f8d0583c3a18",
-    "type": "split",
-    "children": [
-      {
-        "id": "22434516a5f1a19f",
-        "type": "tabs",
-        "children": [
-          {
-            "id": "6fae14c14e044a89",
-            "type": "leaf",
-            "state": {
-              "type": "markdown",
-              "state": {
-                "file": "Coffee Notes/Coffee Brewing Methods.md",
-                "mode": "source",
-                "source": true
-              },
-              "icon": "lucide-file",
-              "title": "Coffee Brewing Methods"
-            }
-          }
-        ]
-      }
-    ],
-    "direction": "vertical"
-  },
-  "left": {
-    "id": "402ef826b6e8c27a",
-    "type": "split",
-    "children": [
-      {
-        "id": "7df070b9023ec8de",
-        "type": "tabs",
-        "children": [
-          {
-            "id": "6fc235d3a84e414f",
-            "type": "leaf",
-            "state": {
-              "type": "file-explorer",
-              "state": {
-                "sortOrder": "alphabetical",
-                "autoReveal": false
-              },
-              "icon": "lucide-folder-closed",
-              "title": "Files"
-            }
-          },
-          {
-            "id": "8679c962d1bfd321",
-            "type": "leaf",
-            "state": {
-              "type": "search",
-              "state": {
-                "query": "",
-                "matchingCase": false,
-                "explainSearch": false,
-                "collapseAll": false,
-                "extraContext": false,
-                "sortOrder": "alphabetical"
-              },
-              "icon": "lucide-search",
-              "title": "Search"
-            }
-          },
-          {
-            "id": "8848cf5cc01540b2",
-            "type": "leaf",
-            "state": {
-              "type": "bookmarks",
-              "state": {},
-              "icon": "lucide-bookmark",
-              "title": "Bookmarks"
-            }
-          }
-        ]
-      }
-    ],
-    "direction": "horizontal",
-    "width": 264.5
-  },
-  "right": {
-    "id": "5bfd609e7511200a",
-    "type": "split",
-    "children": [
-      {
-        "id": "5b83fb5c13b27ce5",
-        "type": "tabs",
-        "children": [
-          {
-            "id": "396b2dfa99a4a44e",
-            "type": "leaf",
-            "state": {
-              "type": "backlink",
-              "state": {
-                "file": "Untitled.md",
-                "collapseAll": false,
-                "extraContext": false,
-                "sortOrder": "alphabetical",
-                "showSearch": false,
-                "searchQuery": "",
-                "backlinkCollapsed": false,
-                "unlinkedCollapsed": true
-              },
-              "icon": "links-coming-in",
-              "title": "Backlinks for Untitled"
-            }
-          },
-          {
-            "id": "b606de8f7f078b60",
-            "type": "leaf",
-            "state": {
-              "type": "outgoing-link",
-              "state": {
-                "file": "Untitled.md",
-                "linksCollapsed": false,
-                "unlinkedCollapsed": true
-              },
-              "icon": "links-going-out",
-              "title": "Outgoing links from Untitled"
-            }
-          },
-          {
-            "id": "2788e9059ef83663",
-            "type": "leaf",
-            "state": {
-              "type": "tag",
-              "state": {
-                "sortOrder": "frequency",
-                "useHierarchy": true,
-                "showSearch": false,
-                "searchQuery": ""
-              },
-              "icon": "lucide-tags",
-              "title": "Tags"
-            }
-          },
-          {
-            "id": "cdf344bf83b2f251",
-            "type": "leaf",
-            "state": {
-              "type": "outline",
-              "state": {
-                "file": "Untitled.md",
-                "followCursor": false,
-                "showSearch": false,
-                "searchQuery": ""
-              },
-              "icon": "lucide-list",
-              "title": "Outline of Untitled"
-            }
-          }
-        ]
-      }
-    ],
-    "direction": "horizontal",
-    "width": 682.5,
-    "collapsed": true
-  },
-  "left-ribbon": {
-    "hiddenItems": {
-      "switcher:Open quick switcher": false,
-      "graph:Open graph view": false,
-      "canvas:Create new canvas": false,
-      "daily-notes:Open today's daily note": false,
-      "templates:Insert template": false,
-      "command-palette:Open command palette": false,
-      "publish:Publish changes...": false
-    }
-  },
-  "active": "6fae14c14e044a89",
-  "lastOpenFiles": [
-    "Untitled.md",
-    "Coffee Notes/Coffee Brewing Methods.md",
-    "Coffee Notes/Coffee Knowledge Base.md",
-    "Coffee Notes/Flavor Extraction.md",
-    "Coffee Notes/Coffee Flavor Map.md",
-    "Coffee Notes/Coffee Bean Origins.md",
-    "Coffee Notes/Perfect Pour Over Coffee Method.canvas",
-    "Coffee Notes/Coffee Brewing Methods Venn Diagram.canvas",
-    "Coffee Notes/Pour Over Techniques.md",
-    "Coffee Notes/Tasting Notes.md",
-    "Coffee Notes/Hybrid Pour Over Technique.md"
-  ]
-}

examples/Coffee Notes/Brewing Equipment.md

@@ -1,83 +0,0 @@
----
-title: Brewing Equipment
-type: note
-permalink: coffee/brewing-equipment
-tags:
-- '#coffee'
-- '#equipment'
-- '#gear'
-- '#brewing'
-- '#demo'
----
-
-# Brewing Equipment
-
-Essential tools and equipment for brewing coffee, their characteristics, and how they affect the brewing process.
-
-## Overview
-
-The equipment used to brew coffee plays a crucial role in determining the final cup quality. From grinders to brewers to kettles, each piece of equipment contributes to different aspects of the brewing process.
-
-## Observations
-
-- [principle] Equipment quality often has a bigger impact on consistency than on absolute quality potential #quality
-- [principle] Good grind consistency is the most important technical factor in extraction quality #grind
-- [investment] A good burr grinder is often the most important investment for improving home coffee #gear
-- [technique] Equipment maintenance and cleaning significantly impact flavor consistency over time #maintenance
-
-## Grinders
-
-- [equipment] Burr grinders crush beans between two abrasive surfaces for more consistent particle size #grinders
-- [equipment] Blade grinders chop beans unevenly, leading to inconsistent extraction #grinders
-- [equipment] Flat burr grinders produce very consistent particle size but generate more heat #burrs
-- [equipment] Conical burr grinders create slightly less uniform grounds but with less heat and noise #burrs
-- [feature] Grind adjustment mechanisms range from stepped to stepless for different precision levels #adjustment
-- [feature] Retention (grounds trapped in grinder) affects dose consistency and freshness #retention
-- [price] Hand grinders offer excellent value, with models like Timemore C2 and 1Zpresso JX providing excellent results around $100-150 #budget
-- [price] Entry-level electric burr grinders like Baratza Encore start around $170 but provide significant improvement over blade grinders #value
-
-## Brewers
-
-### Pour Over Brewers
-- [equipment] Hario V60 uses a conical design with spiral ridges to control flow rate #pourover
-- [equipment] Kalita Wave has a flat bottom with three small holes for more consistent extraction #pourover
-- [equipment] Chemex combines brewer and server with thick proprietary filters for ultra-clean cup #pourover
-- [material] Ceramic brewers retain heat better than plastic but are more fragile #materials
-- [material] Glass brewers provide neutral flavor but less heat retention #materials
-- [material] Plastic brewers are inexpensive, durable, and surprisingly good for heat retention #materials
-
-### Immersion Brewers
-- [equipment] French Press uses a metal mesh to separate grounds, allowing oils and fine particles to pass #immersion
-- [equipment] AeroPress uses pressure and paper filter for clean, versatile brewing #immersion
-- [equipment] Clever Dripper combines immersion and drip methods with a valve mechanism #hybrid
-- [material] Glass French presses look elegant but break easily and have poor heat retention #materials
-- [material] Stainless steel or ceramic French presses offer better durability and heat retention #materials
-
-### Pressure Brewers
-- [equipment] Espresso machines use 9 bars of pressure, requiring significant investment for good results #espresso
-- [equipment] Moka pot uses steam pressure for strong, concentrated coffee at affordable price #moka
-- [equipment] Manual lever machines like Flair or Robot provide espresso-style coffee with manual control #manual_espresso
-
-## Kettles
-
-- [equipment] Gooseneck kettles provide precision pouring control essential for pour over methods #kettles
-- [feature] Variable temperature kettles allow precise temperature control for different roast levels #temp_control
-- [feature] Flow restrictors can help beginners maintain consistent pour rates #pour_control
-- [material] Electric kettles offer convenience and temperature stability #convenience
-- [material] Stovetop kettles may be more durable but offer less temperature control #durability
-
-## Accessories
-
-- [equipment] Coffee scale with 0.1g precision helps maintain consistent ratios #measurement
-- [equipment] Timer ensures consistent extraction times #consistency
-- [equipment] Quality filters significantly impact flavor clarity and body #filters
-- [equipment] Storage containers with one-way valves help preserve bean freshness #storage
-- [equipment] Blind shaker or dosing cup reduces grinder mess and improves workflow #workflow
-
-## Relations
-
-- improves [[Coffee Brewing Methods]]
-- affects [[Flavor Extraction]]
-- requires [[Proper Maintenance]]
-- enhances [[Home Coffee Setup]]
-- part_of [[Coffee Knowledge Base]]

examples/Coffee Notes/Coffee Bean Origins.md

@@ -1,78 +0,0 @@
----
-title: Coffee Bean Origins
-type: note
-permalink: coffee/coffee-bean-origins
-tags:
-- '#coffee'
-- '#origins'
-- '#beans'
-- '#regions'
-- '#demo'
----
-
-# Coffee Bean Origins
-
-An exploration of coffee-growing regions around the world and how geography, climate, and processing methods affect flavor profiles.
-
-## Overview
-
-Coffee beans are grown in various regions around the world, primarily in what's known as the "Coffee Belt" - the area between the Tropics of Cancer and Capricorn. The flavor characteristics of coffee beans are influenced by:
-
-- Geographic region and climate
-- Altitude
-- Soil composition
-- Variety of coffee plant
-- Processing method
-- Harvest and sorting practices
-
-## Observations
-
-- [principle] Higher altitude generally produces harder, denser beans with more complex acidity #altitude
-- [region] Ethiopian beans often feature bright, fruity notes with floral aromatics #ethiopia
-- [region] Colombian coffee typically offers balanced acidity with caramel sweetness and nutty undertones #colombia
-- [region] Guatemalan coffee presents complex acidity with chocolate notes and sometimes spice characteristics #guatemala
-- [region] Brazilian coffee tends toward nutty, chocolate notes with lower acidity and fuller body #brazil
-- [region] Kenyan coffee is known for bright, wine-like acidity and berry or citrus notes #kenya
-- [processing] Natural (dry) processing tends to create fruitier, more fermented flavors #processing
-- [processing] Washed (wet) processing generally results in cleaner, brighter cups with more clarity #processing
-- [processing] Honey processing creates a middle ground with some fruity notes while maintaining clarity #processing
-- [factor] Shade-grown coffee typically develops more slowly, resulting in more complex flavors #cultivation
-- [factor] Soil volcanic soil often imparts distinctive mineral characteristics to coffee #terroir
-- [variety] Gesha/Geisha variety is known for exceptional floral and tea-like qualities #varieties
-- [variety] Bourbon varieties often feature sweet, complex cup profiles #varieties
-- [variety] Robusta beans have higher caffeine content but generally less complex flavor than Arabica #varieties
-
-## Major Growing Regions
-
-- [africa] Ethiopian coffees: Yirgacheffe, Sidamo, Harrar regions each with distinctive profiles #ethiopia
-- [africa] Kenyan coffees: Often categorized by grade (AA, AB, etc.) based on bean size #kenya
-- [americas] Colombian regions: Huila, Nariño, Antioquia each with unique characteristics #colombia
-- [americas] Central American producers: Guatemala, Costa Rica, Panama known for balanced profiles #central_america
-- [americas] Brazilian regions: Cerrado, Sul de Minas, Mogiana with varying profiles #brazil
-- [asia] Indonesian islands: Sumatra, Java, Sulawesi producing earthy, full-bodied coffees #indonesia
-- [asia] Vietnamese coffee: World's largest Robusta producer, often used in blends and commercial coffee #vietnam
-
-## Processing Methods
-
-- [natural] Beans dried inside the fruit, creating fruity, fermented notes and heavier body #processing
-- [washed] Fruit removed before drying, resulting in cleaner cup with more pronounced acidity #processing
-- [honey] Some fruit mucilage left on during drying, creates balanced sweetness and body #processing
-- [wet-hulled] Unique to Indonesia, creates earthy, herbal, low-acid profiles #processing
-- [experimental] Anaerobic fermentation, wine-yeast inoculation, and other newer methods #innovation
-
-## Tasting Notes by Region
-
-- [ethiopia] Blueberry, jasmine, bergamot, stone fruit, citrus #flavor_notes
-- [kenya] Blackcurrant, tomato, tropical fruit, wine-like acidity #flavor_notes
-- [colombia] Caramel, nuts, red apple, chocolate, balanced acidity #flavor_notes
-- [guatemala] Chocolate, spice, green apple, balanced #flavor_notes
-- [brazil] Nuts, chocolate, low acidity, full body #flavor_notes
-- [indonesia] Earthy, herbal, spice, cedar, full body, low acidity #flavor_notes
-
-## Relations
-
-- influences [[Flavor Extraction]]
-- pairs_with [[Coffee Brewing Methods]]
-- affects [[Tasting Notes]]
-- relates_to [[Specialty Coffee]]
-- part_of [[Coffee Knowledge Base]]

examples/Coffee Notes/Coffee Brewing Methods.md

@@ -1,70 +0,0 @@
----
-title: Coffee Brewing Methods
-type: note
-permalink: coffee/coffee-brewing-methods
-tags:
-- '#coffee'
-- '#brewing'
-- '#methods'
-- '#demo'
----
-
-# Coffee Brewing Methods
-
-An exploration of different coffee brewing techniques, their characteristics, and how they affect flavor extraction.
-
-## Overview
-
-Coffee brewing is both an art and a science. Different brewing methods extract different compounds from coffee beans, resulting in unique flavor profiles, body, and mouthfeel. The key variables in any brewing method are:
-
-- Grind size
-- Water temperature
-- Brew time
-- Coffee-to-water ratio
-- Agitation/turbulence
-
-## Observations
-
-- [principle] Coffee extraction follows a predictable pattern: acids extract first, then sugars, then bitter compounds #extraction
-- [method] Pour over methods generally produce cleaner, brighter cups with more distinct flavor notes #clarity
-- [method] Immersion methods like French press create fuller body and more rounded flavors #body
-- [technique] Water at 195-205°F (90-96°C) extracts optimal flavor compounds for most brewing methods #temperature
-- [technique] Grind size directly correlates with ideal extraction time (finer = shorter, coarser = longer) #grind
-- [preference] Medium-light roasts often showcase more origin characteristics in pour over methods #roast
-- [equipment] Burr grinders produce more consistent particle size than blade grinders, resulting in more even extraction #gear
-- [ratio] 1:15 to 1:17 coffee-to-water ratio (by weight) works well for most brew methods #brewing
-- [science] Different brewing temperatures extract different chemical compounds from the beans #chemistry
-- [technique] Bloom phase (pre-infusion with small amount of water) allows CO2 to escape and improves extraction #bloom
-
-## Pour Over Methods
-
-- [method] V60 produces very clean cup with excellent clarity of flavor #pourover
-- [method] Chemex uses thicker filter paper, resulting in even cleaner cup with fewer oils #pourover
-- [method] Kalita Wave provides more consistent extraction due to flat bottom design #pourover
-- [technique] Concentric circular pouring pattern ensures even saturation of grounds #technique
-- [timing] Most pour over methods complete in 2:30-3:30 total brew time #brewing
-
-## Immersion Methods
-
-- [method] French Press creates full-bodied cup with rich mouthfeel due to metal filter allowing oils to pass #immersion
-- [method] AeroPress is versatile, capable of producing both espresso-like and filter-style coffee #immersion
-- [method] Cold brew uses time instead of heat to extract, resulting in lower acidity #immersion
-- [technique] French press ideal steep time is 4-5 minutes before plunging #timing
-- [technique] AeroPress inverted method prevents dripping during extraction phase #technique
-
-## Pressure Methods
-
-- [method] Espresso uses 9 bars of pressure to force water through finely ground coffee #pressure
-- [method] Moka pot uses steam pressure to push water through grounds, creating strong, concentrated coffee #pressure
-- [technique] Espresso requires very fine grind, almost powder-like consistency #grind
-- [timing] Espresso shots typically extract in 25-30 seconds #timing
-- [principle] Pressure methods can extract compounds that aren't soluble in regular brewing methods #extraction
-
-## Relations
-
-- requires [[Proper Grinding Technique]]
-- affects [[Flavor Extraction]]
-- pairs_with [[Coffee Bean Origins]]
-- uses [[Brewing Equipment]]
-- influences [[Tasting Notes]]
-- part_of [[Coffee Knowledge Base]]

examples/Coffee Notes/Coffee Flavor Map.md

@@ -1,89 +0,0 @@
----
-title: Coffee Flavor Map
-type: note
-permalink: coffee/coffee-flavor-map
-tags:
-- '#coffee'
-- '#visualization'
-- '#canvas'
-- '#demo'
----
-
-# Coffee Flavor Map
-
-A visual mapping of coffee flavor attributes, brewing methods, and their relationships. This note describes a canvas visualization that could be generated to demonstrate Basic Memory's visualization capabilities.
-
-## Overview
-
-The Coffee Flavor Map provides a visual representation of how different brewing methods, coffee origins, and equipment choices affect flavor outcomes. This canvas visualization helps users understand the complex relationships in coffee brewing and tasting.
-
-## Canvas Visualization Elements
-
-### Core Nodes
-- **Flavor Attributes**: Acidity, Sweetness, Body, Clarity, Bitterness, Complexity
-- **Brewing Methods**: Pour Over, French Press, AeroPress, Espresso, Moka Pot, Cold Brew
-- **Origin Regions**: Ethiopia, Kenya, Colombia, Brazil, Guatemala, Indonesia
-- **Equipment Elements**: Grinder Quality, Water Temperature, Brewing Device, Filter Type
-
-### Node Connections
-- Lines connecting brewing methods to their typical flavor outcomes
-- Arrows showing how equipment choices affect extraction variables
-- Connections between origins and their characteristic flavor profiles
-- Highlighting of optimal brewing methods for different origins
-
-### Visual Organization
-- Flavor outcomes in the center
-- Brewing methods on the left side
-- Origins on the right side
-- Equipment variables at the bottom
-- Color coding by category (methods, origins, equipment, flavors)
-
-## Using This Visualization
-
-### For Coffee Exploration
-- Identify which brewing methods might highlight the characteristics you prefer
-- See which origins naturally pair well with your preferred brewing method
-- Understand how equipment changes can modify flavor outcomes
-- Visualize the complex interplay between all coffee variables
-
-### As a Basic Memory Demo
-- Demonstrates Canvas visualization capabilities
-- Shows how relations can be visually mapped
-- Illustrates complex knowledge organization
-- Provides an intuitive way to navigate coffee knowledge
-
-## How To Generate This Canvas
-
-In a conversation with Claude, you could request:
-
-```
-Please create a canvas visualization mapping the relationships between coffee brewing methods, origins, and flavor outcomes. Show how different equipment and techniques influence extraction and resulting flavor profiles.
-```
-
-This would generate a `.canvas` file in your Basic Memory directory that could be opened with Obsidian for an interactive visualization of these coffee relationships.
-
-## Example Visualization Snippets
-
-### Pour Over Method Node
-- Connected to: High Clarity, Bright Acidity, Medium Body
-- Best pairs with: Ethiopian and Kenyan beans
-- Equipment dependencies: Gooseneck Kettle, Paper Filter, Burr Grinder
-
-### Ethiopian Coffee Node
-- Characteristic flavors: Floral, Fruity, Bright
-- Best brewing methods: Pour Over, AeroPress
-- Challenging with: French Press (loses clarity of delicate notes)
-
-### Grind Size Node
-- Affects: Extraction Rate, Flavor Balance
-- Fine grind increases: Extraction Speed, Surface Area
-- Coarse grind increases: Flow Rate, Reduces Bitter Compounds
-
-## Relations
-
-- visualizes [[Coffee Knowledge Base]]
-- relates_to [[Coffee Brewing Methods]]
-- relates_to [[Coffee Bean Origins]]
-- relates_to [[Flavor Extraction]]
-- relates_to [[Tasting Notes]]
-- demonstrates [[Canvas]]

examples/Coffee Notes/Coffee Knowledge Base.md

@@ -1,73 +0,0 @@
----
-title: Coffee Knowledge Base
-type: note
-permalink: coffee/coffee-knowledge-base
-tags:
-- '#coffee'
-- '#index'
-- '#demo'
-- '#knowledge'
----
-
-# Coffee Knowledge Base
-
-A comprehensive collection of coffee knowledge, from bean origins to brewing methods to tasting notes. This knowledge base demonstrates Basic Memory's ability to organize and connect information in a meaningful way.
-
-## Overview
-
-This Coffee Knowledge Base captures key information about coffee, structured with semantic observations and relations that connect different aspects of coffee knowledge. It serves as both a useful reference for coffee enthusiasts and a demonstration of how Basic Memory organizes information.
-
-## Key Topics
-
-### Core Coffee Knowledge
-
-- [[Coffee Brewing Methods]] - Different techniques for preparing coffee
-- [[Coffee Bean Origins]] - Where coffee comes from and how region affects flavor
-- [[Brewing Equipment]] - Tools and devices used to prepare coffee
-- [[Flavor Extraction]] - The science of dissolving flavor compounds from coffee
-- [[Tasting Notes]] - How to taste and describe coffee flavors
-
-### Brewing Techniques
-
-- Proper grinding is fundamental to good extraction
-- Water quality significantly impacts flavor
-- Different brewing methods highlight different characteristics
-- Time, temperature, and grind size are the key variables to control
-- Freshness of beans dramatically affects quality
-
-### Coffee Preferences
-
-- Light roasts preserve more origin characteristics and acidity
-- Dark roasts emphasize body and chocolatey/roasted flavors
-- Pour over methods highlight clarity and distinct flavor notes
-- Immersion methods create fuller body and rounded flavor
-- Personal preference matters more than "correctness"
-
-## Using This Knowledge Base
-
-### For Learning
-
-Use this knowledge base to:
-- Understand coffee fundamentals
-- Explore connections between brewing methods and flavor outcomes
-- Learn how different origins produce distinct flavor profiles
-- Discover how equipment affects the brewing process
-- Develop a vocabulary for describing coffee experiences
-
-### As a Demo
-
-This knowledge base demonstrates:
-- Semantic knowledge organization with categories and relations
-- Building connections between related concepts
-- Creating a navigable knowledge graph
-- Structuring information in a way both humans and AI assistants can understand
-- How Basic Memory enables persistent knowledge across conversations
-
-## Relations
-
-- contains [[Coffee Brewing Methods]]
-- contains [[Coffee Bean Origins]]
-- contains [[Brewing Equipment]]
-- contains [[Flavor Extraction]]
-- contains [[Tasting Notes]]
-- demonstrates [[Basic Memory Capabilities]]

examples/Coffee Notes/Flavor Extraction.md

@@ -1,79 +0,0 @@
----
-title: Flavor Extraction
-type: note
-permalink: coffee/flavor-extraction
-tags:
-- '#coffee'
-- '#extraction'
-- '#brewing'
-- '#science'
-- '#demo'
----
-
-# Flavor Extraction
-
-Understanding the science of coffee extraction, how different compounds dissolve at different rates, and how to control extraction to achieve desired flavor profiles.
-
-## Overview
-
-Coffee extraction is the process of dissolving flavor compounds from ground coffee into water. The science of extraction is key to producing a balanced, flavorful cup. Extraction is affected by numerous variables including grind size, water temperature, contact time, agitation, and pressure.
-
-## Observations
-
-- [science] Coffee contains over 1,000 aroma compounds and hundreds of flavor compounds #chemistry
-- [principle] Extraction occurs in a predictable sequence: acids → sugars → bitter compounds #extraction_order
-- [principle] Under-extraction results in sour, bright, thin coffee lacking sweetness and body #under_extraction
-- [principle] Over-extraction results in bitter, hollow, astringent flavors #over_extraction
-- [principle] The goal is typically balanced extraction (18-22% of coffee solubles dissolved) #balanced_extraction
-- [technique] Finer grind size increases extraction rate due to greater surface area #grind_size
-- [technique] Higher water temperature increases extraction rate and solubility of compounds #temperature
-- [technique] Longer contact time allows more complete extraction #brew_time
-- [technique] Agitation (stirring, turbulence) increases extraction rate by preventing saturation zones #agitation
-- [technique] Pressure (as in espresso) can extract compounds that aren't water-soluble at atmospheric pressure #pressure
-
-## Factors Affecting Extraction
-
-- [factor] Grind size: Finer = faster extraction, coarser = slower extraction #grind
-- [factor] Water temperature: Higher = faster extraction, lower = slower extraction #temperature
-- [factor] Contact time: Longer = more extraction, shorter = less extraction #time
-- [factor] Agitation: More = faster extraction, less = slower extraction #agitation
-- [factor] Coffee-to-water ratio: More coffee = lower extraction percentage #ratio
-- [factor] Water quality: Mineral content affects extraction of different compounds #water
-- [factor] Roast level: Darker roasts extract more easily than lighter roasts #roast
-- [factor] Bean density: Denser beans (typically high-altitude) require more effort to extract #density
-- [factor] Freshness: Freshly roasted coffee extracts differently than aged coffee #freshness
-- [factor] Brewing method: Different methods extract different compounds at different rates #method
-
-## Signs of Extraction Levels
-
-- [under] Sour, bright, lack of sweetness, thin body, quick finish #flavor
-- [under] Typically from: too coarse grind, too cool water, too short brew time #causes
-- [balanced] Sweet, bright but not sour, rich but not bitter, pleasing finish #flavor
-- [balanced] Achieved through proper ratio of variables for given coffee #technique
-- [over] Bitter, hollow, astringent, dry finish, sometimes papery #flavor
-- [over] Typically from: too fine grind, too hot water, too long brew time #causes
-
-## Measuring Extraction
-
-- [method] Total Dissolved Solids (TDS) meters measure concentration of coffee solution #measurement
-- [method] Extraction yield = percentage of coffee grounds dissolved in the final brew #calculation
-- [preference] Specialty coffee typically targets 18-22% extraction yield #standards
-- [preference] Some specialty light roasts may taste best at higher extraction percentages #speciality
-
-## Controlling Extraction
-
-- [technique] Adjust grind size as primary extraction control #basics
-- [technique] Use water temperature to fine-tune extraction #fine_tuning
-- [technique] Modify pour technique to control agitation level #technique
-- [technique] Adjust coffee-to-water ratio to balance strength and extraction #ratio
-- [technique] Pre-infusion (blooming) helps achieve even extraction #blooming
-- [technique] Pulse pouring creates different extraction dynamics than continuous pour #pour_technique
-
-## Relations
-
-- affected_by [[Coffee Brewing Methods]]
-- influenced_by [[Coffee Bean Origins]]
-- enhanced_by [[Brewing Equipment]]
-- determines [[Tasting Notes]]
-- requires [[Water Quality]]
-- part_of [[Coffee Knowledge Base]]

examples/Coffee Notes/Perfect Pour Over Coffee Method.canvas

@@ -1,161 +0,0 @@
-{
-	"nodes":[
-		{
-			"id":"node-5",
-			"type":"text",
-			"text":"## Main Pour Phase\n- Use concentric circles from center outward\n- Maintain steady, controlled flow rate\n- Avoid pouring directly on filter walls\n- Keep water level consistent\n- Pulse pour in 2-3 stages (or continuous pour)\n- Total brew time target: 2:30-3:30",
-			"position":{"x":450,"y":200},
-			"x":530,
-			"y":-100,
-			"width":300,
-			"height":200,
-			"color":"1"
-		},
-		{
-			"id":"node-8",
-			"type":"text",
-			"text":"## Drawdown\n- Allow water to fully drain\n- Flat bed indicates even extraction\n- Total brew time should be ~2:30-3:30\n- Remove filter promptly after brewing",
-			"position":{"x":450,"y":700},
-			"x":540,
-			"y":375,
-			"width":300,
-			"height":150,
-			"color":"1"
-		},
-		{
-			"id":"node-6",
-			"type":"text",
-			"text":"## Pour Pattern\n\nConcentric circles ensure even saturation of coffee grounds. Begin at the center and work outward, avoiding filter edges. Pour height of 1-2 inches above coffee bed.",
-			"position":{"x":250,"y":450},
-			"x":960,
-			"y":25,
-			"width":300,
-			"height":150,
-			"color":"5"
-		},
-		{
-			"id":"node-12",
-			"type":"text",
-			"text":"## Tasting Notes\n\n- Balanced extraction: sweet, bright, complex\n- Under-extraction: sour, lacking sweetness\n- Over-extraction: bitter, astringent, hollow\n\nTake notes on each brew to track improvements and preferences.",
-			"position":{"x":-250,"y":700},
-			"x":1020,
-			"y":420,
-			"width":300,
-			"height":150,
-			"color":"6"
-		},
-		{
-			"id":"node-9",
-			"type":"text",
-			"text":"## Troubleshooting\n\n- Too sour/weak: Grind finer, water hotter, increase brew time\n- Too bitter/strong: Grind coarser, water cooler, decrease brew time\n- Uneven extraction: Improve pour technique, better grinder\n- Channeling: More careful pouring, better bloom\n- Slow drawdown: Coarser grind, less agitation\n- Fast drawdown: Finer grind, more careful pouring",
-			"position":{"x":100,"y":700},
-			"x":30,
-			"y":570,
-			"width":300,
-			"height":200,
-			"color":"6"
-		},
-		{
-			"id":"node-3",
-			"type":"text",
-			"text":"## Preparation\n- Heat water to 195-205°F (90-96°C)\n- Measure coffee (1:15 to 1:17 ratio)\n- Medium-fine grind (sea salt consistency)\n- Rinse filter with hot water\n- Discard rinse water\n- Add ground coffee to filter\n- Level coffee bed",
-			"position":{"x":-250,"y":200},
-			"x":30,
-			"y":-500,
-			"width":300,
-			"height":200,
-			"color":"3"
-		},
-		{
-			"id":"node-1",
-			"type":"text",
-			"text":"# Perfect Pour Over Method\n\nA systematic approach to brewing exceptional pour over coffee by controlling key variables and following proper technique.",
-			"position":{"x":0,"y":0},
-			"x":-580,
-			"y":-760,
-			"width":400,
-			"height":120,
-			"color":"4"
-		},
-		{
-			"id":"node-10",
-			"type":"text",
-			"text":"## Grinding Parameters\n\n- V60: Medium-fine (sea salt)\n- Chemex: Medium (slightly coarser than V60)\n- Kalita Wave: Medium (between V60 and Chemex)\n\nConsistent particle size is critical; use quality burr grinder.",
-			"position":{"x":-250,"y":450},
-			"x":30,
-			"y":-910,
-			"width":300,
-			"height":150,
-			"color":"5"
-		},
-		{
-			"id":"node-2",
-			"type":"text",
-			"text":"## Equipment Setup\n- Clean V60/Chemex/Kalita Wave\n- Paper filter (rinsed)\n- Server/mug\n- Scale with timer\n- Gooseneck kettle\n- Burr grinder\n- Fresh coffee beans",
-			"position":{"x":-600,"y":200},
-			"x":-530,
-			"y":-500,
-			"width":300,
-			"height":200,
-			"color":"3"
-		},
-		{
-			"id":"node-4",
-			"type":"text",
-			"text":"## The Bloom\n- Start timer\n- Pour 2-3x coffee weight water\n- Ensure all grounds are saturated\n- Gentle stir or swirl if needed\n- Allow 30-45 seconds for degassing\n- Look for bubbling and dome formation",
-			"position":{"x":100,"y":200},
-			"x":530,
-			"y":-500,
-			"width":300,
-			"height":200,
-			"color":"1"
-		},
-		{
-			"id":"node-13",
-			"type":"text",
-			"text":"## Coffee-to-Water Ratio\n\n- Standard: 1:15 to 1:17 (coffee:water)\n- Stronger cup: 1:15 (67g/L)\n- Medium cup: 1:16 (62.5g/L)\n- Lighter cup: 1:17 (58.8g/L)\n\nExample: For 300ml water, use ~18-20g coffee",
-			"position":{"x":-600,"y":700},
-			"x":30,
-			"y":-100,
-			"width":300,
-			"height":150,
-			"color":"6"
-		},
-		{
-			"id":"node-7",
-			"type":"text",
-			"text":"## Brew Time Guideline\n\n- Bloom: 30-45 seconds\n- First pour: 1:00-1:15\n- Second pour: 1:45-2:00\n- Final pour: 2:15-2:30\n- Drawdown complete: 2:45-3:30\n\nAdjust for taste: shorter for lighter, longer for stronger",
-			"position":{"x":600,"y":450},
-			"x":-80,
-			"y":220,
-			"width":300,
-			"height":200,
-			"color":"5"
-		},
-		{
-			"id":"node-11",
-			"type":"text",
-			"text":"## Water Quality\n\n- Clean, filtered water\n- No strong odors or flavors\n- Ideal TDS: 75-150 ppm\n- Ideal pH: 7.0-7.5\n- Avoid distilled water (lacks minerals)\n- Avoid hard water (scaling issues)",
-			"position":{"x":-600,"y":450},
-			"x":-780,
-			"y":-125,
-			"width":300,
-			"height":150,
-			"color":"5"
-		}
-	],
-	"edges":[
-		{"id":"edge-1","fromNode":"node-1","fromSide":"bottom","toNode":"node-2","toSide":"top","label":"Step 1"},
-		{"id":"edge-2","fromNode":"node-2","fromSide":"right","toNode":"node-3","toSide":"left","label":"Step 2"},
-		{"id":"edge-3","fromNode":"node-3","fromSide":"right","toNode":"node-4","toSide":"left","label":"Step 3"},
-		{"id":"edge-4","fromNode":"node-4","fromSide":"bottom","toNode":"node-5","toSide":"top","label":"Step 4"},
-		{"id":"edge-5","fromNode":"node-5","fromSide":"bottom","toNode":"node-8","toSide":"top","label":"Step 5"},
-		{"id":"edge-6","fromNode":"node-5","fromSide":"left","toNode":"node-7","toSide":"right","label":"Timing"},
-		{"id":"edge-7","fromNode":"node-5","fromSide":"right","toNode":"node-6","toSide":"left","label":"Technique"},
-		{"id":"edge-8","fromNode":"node-8","fromSide":"left","toNode":"node-9","toSide":"right","label":"if problems"},
-		{"id":"edge-9","fromNode":"node-3","fromSide":"top","toNode":"node-10","toSide":"bottom","label":"Grinding details"},
-		{"id":"edge-10","fromNode":"node-2","fromSide":"bottom","toNode":"node-11","toSide":"right","label":"Water details"},
-		{"id":"edge-11","fromNode":"node-8","fromSide":"right","toNode":"node-12","toSide":"left","label":"Evaluate"},
-		{"id":"edge-12","fromNode":"node-3","fromSide":"bottom","toNode":"node-13","toSide":"top","label":"Ratio details"}
-	]
-}

examples/Coffee Notes/Tasting Notes.md

@@ -1,84 +0,0 @@
----
-title: Tasting Notes
-type: note
-permalink: coffee/tasting-notes
-tags:
-- '#coffee'
-- '#tasting'
-- '#flavor'
-- '#cupping'
-- '#demo'
----
-
-# Tasting Notes
-
-How to taste and evaluate coffee, identify flavor characteristics, and develop a personal coffee palate.
-
-## Overview
-
-Coffee tasting, or "cupping" in professional contexts, is the practice of observing the tastes and aromas of brewed coffee. Developing a coffee palate helps identify preferences, communicate about coffee experiences, and better understand how brewing variables affect the cup.
-
-## Observations
-
-- [principle] Flavor perception includes taste, aroma, mouthfeel, and retronasal perception #sensory
-- [principle] Our taste buds can only perceive sweet, sour, salty, bitter, and umami #taste
-- [principle] Most of what we call "flavor" is actually aroma detected retronasally #aroma
-- [technique] Professional coffee tasting (cupping) uses a standardized protocol for consistency #cupping
-- [technique] Slurping coffee aerates it and spreads it across all taste receptors #technique
-- [technique] Allowing coffee to cool reveals different flavor notes at different temperatures #temperature
-
-## Coffee Flavor Wheel
-
-- [tool] The SCA Coffee Flavor Wheel provides a standardized vocabulary for describing coffee #flavor_wheel
-- [category] Primary categories include: Fruity, Floral, Sweet, Nutty/Cocoa, Spice, Roasted, Other #categories
-- [subcategory] Fruity breaks down into: Berry, Dried Fruit, Citrus Fruit, Stone Fruit, Tropical Fruit, etc. #fruit_notes
-- [subcategory] Floral includes: Floral, Black Tea, Chamomile, Rose, Jasmine, etc. #floral_notes
-- [subcategory] Sweet includes: Brown Sugar, Molasses, Honey, Maple Syrup, Vanilla, etc. #sweet_notes
-- [subcategory] Nutty/Cocoa includes: Nut, Cocoa, Dark Chocolate, Chocolate, etc. #nutty_notes
-- [subcategory] Spice includes: Brown Spice, Pepper, Anise, Nutmeg, Cinnamon, etc. #spice_notes
-
-## Basic Tasting Components
-
-- [component] Acidity: The bright, tangy quality (not sourness from under-extraction) #acidity
-- [component] Sweetness: The pleasant, sugary quality balancing other elements #sweetness
-- [component] Body: The physical mouthfeel and weight of the coffee #body
-- [component] Finish/Aftertaste: The flavor that lingers after swallowing #finish
-- [component] Balance: How well all elements work together #balance
-- [component] Complexity: The range and layers of distinct flavors #complexity
-- [component] Cleanliness: Absence of defects or off-flavors #cleanliness
-
-## Common Flavor Notes by Origin
-
-- [ethiopia] Blueberry, jasmine, bergamot, lemon, tea-like #flavor_notes
-- [kenya] Blackcurrant, grapefruit, tomato-like acidity, winey #flavor_notes
-- [colombia] Caramel, red apple, nuts, chocolate, balanced acidity #flavor_notes
-- [guatemala] Chocolate, spice, apple, medium acidity #flavor_notes
-- [brazil] Nuts, chocolate, low-to-medium acidity, full body #flavor_notes
-- [indonesia] Earthy, herbal, spice, cedar, full body, low acidity #flavor_notes
-- [costa_rica] Clean, bright, citrus, balanced, light chocolate #flavor_notes
-
-## Developing Your Palate
-
-- [technique] Taste coffees side-by-side to identify differences #comparison
-- [technique] Try describing flavors before looking at roaster's notes #blind_tasting
-- [technique] Keep a coffee journal with detailed notes about each coffee #journaling
-- [technique] Explore different processing methods of the same origin #processing
-- [technique] Try the same coffee brewed with different methods #brewing_comparison
-- [technique] Use reference flavors (actual fruits, chocolates, etc.) to calibrate your palate #calibration
-
-## Personal Coffee Experiences
-
-- [experience] Ethiopian Yirgacheffe prepared as pour over: intense blueberry, jasmine aromatics, tea-like body
-- [experience] Sumatra Mandheling in French press: earthy, cedar, herbal, tobacco, full body
-- [experience] Panama Gesha as pour over: intense floral notes, jasmine, bergamot, delicate body
-- [experience] Brazil Cerrado as espresso: nutty, chocolate, caramel, low acidity, great crema
-- [experience] Kenya AA as pour over: bright blackcurrant, tomato-like acidity, winey finish
-
-## Relations
-
-- determined_by [[Flavor Extraction]]
-- influenced_by [[Coffee Bean Origins]]
-- varies_with [[Coffee Brewing Methods]]
-- enhanced_by [[Proper Grinding Technique]]
-- documented_in [[Coffee Journal]]
-- part_of [[Coffee Knowledge Base]]

installer/README.md

@@ -1,26 +0,0 @@
-# Basic Memory Installer
-
-This installer configures Basic Memory to work with Claude Desktop.
-
-## Installation
-
-1. Download the latest installer from the [releases page](https://github.com/basicmachines-co/basic-memory/releases)
-2. Unzip the downloaded file
-3. Since the app is currently unsigned, you'll need to:
-
-   On your Mac, choose Apple menu  > System Settings, then click Privacy & Security in the sidebar. (You may need to
-   scroll down.)
-
-   Go to Security, then click Open.
-
-   Click Open Anyway.
-
-   This button is available for about an hour after you try to open the app.
-
-   Enter your login password, then click OK.
-
-   https://support.apple.com/guide/mac-help/apple-cant-check-app-for-malicious-software-mchleab3a043/mac
-
-5. Restart Claude Desktop
-
-The warning only appears the first time you open the app. Future updates will include proper code signing.

installer/icon.svg

@@ -1,64 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<svg viewBox="0 0 512 512" xmlns="http://www.w3.org/2000/svg">
-  <!-- Background -->
-  <rect x="0" y="0" width="512" height="512" rx="64" fill="#111111"/>
-
-  <!-- Define arrowhead marker -->
-  <defs>
-    <marker id="arrowhead" 
-            markerWidth="10" 
-            markerHeight="10" 
-            refX="8" 
-            refY="5"
-            orient="auto">
-      <path d="M 0 0 L 10 5 L 0 10 Z" 
-            fill="#00cc00"/>
-    </marker>
-  </defs>
-  
-  <!-- State 1 (initial) -->
-  <circle cx="156" cy="256" r="30" fill="none" stroke="#00cc00" stroke-width="3"/>
-  
-  <!-- State 2 (accept) -->
-  <circle cx="356" cy="176" r="34" fill="none" stroke="#00cc00" stroke-width="3"/>
-  <circle cx="356" cy="176" r="28" fill="none" stroke="#00cc00" stroke-width="3"/>
-  
-  <!-- State 3 (accept) -->
-  <circle cx="356" cy="336" r="34" fill="none" stroke="#00cc00" stroke-width="3"/>
-  <circle cx="356" cy="336" r="28" fill="none" stroke="#00cc00" stroke-width="3"/>
-
-  <!-- Initial arrow -->
-  <path d="M 96 256 L 126 256" 
-        stroke="#00cc00" stroke-width="3" fill="none"
-        marker-end="url(#arrowhead)"/>
-
-  <!-- State transitions -->
-  <!-- 1 -> 2 -->
-  <path d="M 180 240
-           Q 260 200, 320 176" 
-        stroke="#00cc00" stroke-width="3" fill="none"
-        marker-end="url(#arrowhead)"/>
-        
-  <!-- 1 -> 3 -->
-  <path d="M 180 272
-           Q 260 312, 320 336" 
-        stroke="#00cc00" stroke-width="3" fill="none"
-        marker-end="url(#arrowhead)"/>
-
-  <!-- Self loops -->
-  <path d="M 356 142
-           Q 396 142, 396 176
-           Q 396 210, 356 210
-           Q 316 210, 316 176
-           Q 316 142, 356 142" 
-        stroke="#00cc00" stroke-width="2" fill="none"
-        marker-end="url(#arrowhead)"/>
-        
-  <path d="M 356 302
-           Q 396 302, 396 336
-           Q 396 370, 356 370
-           Q 316 370, 316 336
-           Q 316 302, 356 302" 
-        stroke="#00cc00" stroke-width="2" fill="none"
-        marker-end="url(#arrowhead)"/>
-</svg>

installer/installer.py

@@ -1,93 +0,0 @@
-import json
-import subprocess
-import sys
-from pathlib import Path
-
-# Use tkinter for GUI alerts on macOS
-if sys.platform == "darwin":
-    import tkinter as tk
-    from tkinter import messagebox
-
-
-def ensure_uv_installed():
-    """Check if uv is installed, install if not."""
-    try:
-        subprocess.run(["uv", "--version"], capture_output=True, check=True)
-    except (subprocess.CalledProcessError, FileNotFoundError):
-        print("Installing uv package manager...")
-        subprocess.run(
-            [
-                "curl",
-                "-LsSf",
-                "https://astral.sh/uv/install.sh",
-                "|",
-                "sh",
-            ],
-            shell=True,
-        )
-
-
-def get_config_path():
-    """Get Claude Desktop config path for current platform."""
-    if sys.platform == "darwin":
-        return Path.home() / "Library/Application Support/Claude/claude_desktop_config.json"
-    elif sys.platform == "win32":
-        return Path.home() / "AppData/Roaming/Claude/claude_desktop_config.json"
-    else:
-        raise RuntimeError(f"Unsupported platform: {sys.platform}")
-
-
-def update_claude_config():
-    """Update Claude Desktop config to include basic-memory."""
-    config_path = get_config_path()
-    config_path.parent.mkdir(parents=True, exist_ok=True)
-
-    # Load existing config or create new
-    if config_path.exists():
-        config = json.loads(config_path.read_text())
-    else:
-        config = {"mcpServers": {}}
-
-    # Add/update basic-memory config
-    config["mcpServers"]["basic-memory"] = {
-        "command": "uvx",
-        "args": ["basic-memory@latest", "mcp"],
-    }
-
-    # Write back config
-    config_path.write_text(json.dumps(config, indent=2))
-
-
-def print_completion_message():
-    """Show completion message with helpful tips."""
-    message = """Installation complete! Basic Memory is now available in Claude Desktop.
-
-Please restart Claude Desktop for changes to take effect.
-
-Quick Start:
-1. You can run sync directly using: uvx basic-memory sync
-2. Optionally, install globally with: uv pip install basic-memory
-
-Built with ♥️ by Basic Machines."""
-
-    if sys.platform == "darwin":
-        # Show GUI message on macOS
-        root = tk.Tk()
-        root.withdraw()  # Hide the main window
-        messagebox.showinfo("Basic Memory", message)
-        root.destroy()
-    else:
-        # Fallback to console output
-        print(message)
-
-
-def main():
-    print("Welcome to Basic Memory installer")
-    ensure_uv_installed()
-    print("Configuring Claude Desktop...")
-    update_claude_config()
-    print_completion_message()
-
-
-if __name__ == "__main__":
-    main()

installer/make_icons.sh

@@ -1,27 +0,0 @@
-#!/bin/bash
-
-# Convert SVG to PNG at various required sizes
-rsvg-convert -h 16 -w 16 icon.svg > icon_16x16.png
-rsvg-convert -h 32 -w 32 icon.svg > icon_32x32.png
-rsvg-convert -h 128 -w 128 icon.svg > icon_128x128.png
-rsvg-convert -h 256 -w 256 icon.svg > icon_256x256.png
-rsvg-convert -h 512 -w 512 icon.svg > icon_512x512.png
-
-# Create iconset directory
-mkdir -p Basic.iconset
-
-# Move files into iconset with Mac-specific names
-cp icon_16x16.png Basic.iconset/icon_16x16.png
-cp icon_32x32.png Basic.iconset/icon_16x16@2x.png
-cp icon_32x32.png Basic.iconset/icon_32x32.png
-cp icon_128x128.png Basic.iconset/icon_32x32@2x.png
-cp icon_256x256.png Basic.iconset/icon_128x128.png
-cp icon_512x512.png Basic.iconset/icon_256x256.png
-cp icon_512x512.png Basic.iconset/icon_512x512.png
-
-# Convert iconset to icns
-iconutil -c icns Basic.iconset
-
-# Clean up
-rm -rf Basic.iconset
-rm icon_*.png

installer/setup.py

@@ -1,40 +0,0 @@
-from cx_Freeze import setup, Executable
-import sys
-
-# Build options for all platforms
-build_exe_options = {
-    "packages": ["json", "pathlib"],
-    "excludes": ["unittest", "pydoc", "test"],
-}
-
-# Platform-specific options
-if sys.platform == "win32":
-    base = "Win32GUI"  # Use GUI base for Windows
-    build_exe_options.update(
-        {
-            "include_msvcr": True,
-        }
-    )
-    target_name = "Basic Memory Installer.exe"
-else:  # darwin
-    base = None  # Don't use GUI base for macOS
-    target_name = "Basic Memory Installer"
-
-executables = [
-    Executable(script="installer.py", target_name=target_name, base=base, icon="Basic.icns")
-]
-
-setup(
-    name="basic-memory",
-    version=open("../pyproject.toml").read().split('version = "', 1)[1].split('"', 1)[0],
-    description="Basic Memory - Local-first knowledge management",
-    options={
-        "build_exe": build_exe_options,
-        "bdist_mac": {
-            "bundle_name": "Basic Memory Installer",
-            "iconfile": "Basic.icns",
-            "codesign_identity": "-",  # Force ad-hoc signing
-        },
-    },
-    executables=executables,
-)

justfile

@@ -0,0 +1,255 @@
+# Basic Memory - Modern Command Runner
+
+# Install dependencies
+install:
+    uv pip install -e ".[dev]"
+    uv sync
+    @echo ""
+    @echo "💡 Remember to activate the virtual environment by running: source .venv/bin/activate"
+
+# Run all tests with unified coverage report
+test: test-unit test-int
+
+# Run unit tests only (fast, no coverage)
+test-unit:
+    uv run pytest -p pytest_mock -v --no-cov tests
+
+# Run integration tests only (fast, no coverage)
+test-int:
+    uv run pytest -p pytest_mock -v --no-cov test-int
+
+# ==============================================================================
+# DATABASE BACKEND TESTING
+# ==============================================================================
+# Basic Memory supports dual database backends (SQLite and Postgres).
+# Tests are parametrized to run against both backends automatically.
+#
+# Quick Start:
+#   just test-sqlite    # Run SQLite tests (default, no Docker needed)
+#   just test-postgres  # Run Postgres tests (requires Docker)
+#
+# For Postgres tests, first start the database:
+#   docker-compose -f docker-compose-postgres.yml up -d
+# ==============================================================================
+
+# Run tests against SQLite only (default backend, skip Postgres/Benchmark tests)
+# This is the fastest option and doesn't require any Docker setup.
+# Use this for local development and quick feedback.
+# Includes Windows-specific tests which will auto-skip on non-Windows platforms.
+test-sqlite:
+    uv run pytest -p pytest_mock -v --no-cov -m "not postgres and not benchmark" tests test-int
+
+# Run tests against Postgres only (requires docker-compose-postgres.yml up)
+# First start Postgres: docker-compose -f docker-compose-postgres.yml up -d
+# Tests will connect to localhost:5433/basic_memory_test
+# To reset the database: just postgres-reset
+test-postgres:
+    uv run pytest -p pytest_mock -v --no-cov -m "postgres and not benchmark" tests test-int
+
+# Reset Postgres test database (drops and recreates schema)
+# Useful when Alembic migration state gets out of sync during development
+# Uses credentials from docker-compose-postgres.yml
+postgres-reset:
+    docker exec basic-memory-postgres psql -U ${POSTGRES_USER:-basic_memory_user} -d ${POSTGRES_TEST_DB:-basic_memory_test} -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"
+    @echo "✅ Postgres test database reset"
+
+# Run Alembic migrations manually against Postgres test database
+# Useful for debugging migration issues
+# Uses credentials from docker-compose-postgres.yml (can override with env vars)
+postgres-migrate:
+    @cd src/basic_memory/alembic && \
+    BASIC_MEMORY_DATABASE_BACKEND=postgres \
+    BASIC_MEMORY_DATABASE_URL=${POSTGRES_TEST_URL:-postgresql://basic_memory_user:dev_password@localhost:5433/basic_memory_test} \
+    uv run alembic upgrade head
+    @echo "✅ Migrations applied to Postgres test database"
+
+# Run Windows-specific tests only (only works on Windows platform)
+# These tests verify Windows-specific database optimizations (locking mode, NullPool)
+# Will be skipped automatically on non-Windows platforms
+test-windows:
+    uv run pytest -p pytest_mock -v --no-cov -m windows tests test-int
+
+# Run benchmark tests only (performance testing)
+# These are slow tests that measure sync performance with various file counts
+# Excluded from default test runs to keep CI fast
+test-benchmark:
+    uv run pytest -p pytest_mock -v --no-cov -m benchmark tests test-int
+
+# Run all tests including Windows, Postgres, and Benchmarks (for CI/comprehensive testing)
+# Use this before releasing to ensure everything works across all backends and platforms
+test-all:
+    uv run pytest -p pytest_mock -v --no-cov tests test-int
+
+# Generate HTML coverage report
+coverage:
+    uv run pytest -p pytest_mock -v -n auto tests test-int --cov-report=html
+    @echo "Coverage report generated in htmlcov/index.html"
+
+# Lint and fix code (calls fix)
+lint: fix
+
+# Lint and fix code
+fix:
+    uv run ruff check --fix --unsafe-fixes src tests test-int
+
+# Type check code
+typecheck:
+    uv run pyright
+
+# Clean build artifacts and cache files
+clean:
+    find . -type f -name '*.pyc' -delete
+    find . -type d -name '__pycache__' -exec rm -r {} +
+    rm -rf installer/build/ installer/dist/ dist/
+    rm -f rw.*.dmg .coverage.*
+
+# Format code with ruff
+format:
+    uv run ruff format .
+
+# Run MCP inspector tool
+run-inspector:
+    npx @modelcontextprotocol/inspector
+
+# Build macOS installer
+installer-mac:
+    cd installer && chmod +x make_icons.sh && ./make_icons.sh
+    cd installer && uv run python setup.py bdist_mac
+
+# Build Windows installer
+installer-win:
+    cd installer && uv run python setup.py bdist_win32
+
+# Update all dependencies to latest versions
+update-deps:
+    uv sync --upgrade
+
+# Run all code quality checks and tests
+check: lint format typecheck test
+
+# Generate Alembic migration with descriptive message
+migration message:
+    cd src/basic_memory/alembic && alembic revision --autogenerate -m "{{message}}"
+
+# Create a stable release (e.g., just release v0.13.2)
+release version:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    
+    # Validate version format
+    if [[ ! "{{version}}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+        echo "❌ Invalid version format. Use: v0.13.2"
+        exit 1
+    fi
+    
+    # Extract version number without 'v' prefix
+    VERSION_NUM=$(echo "{{version}}" | sed 's/^v//')
+    
+    echo "🚀 Creating stable release {{version}}"
+    
+    # Pre-flight checks
+    echo "📋 Running pre-flight checks..."
+    if [[ -n $(git status --porcelain) ]]; then
+        echo "❌ Uncommitted changes found. Please commit or stash them first."
+        exit 1
+    fi
+    
+    if [[ $(git branch --show-current) != "main" ]]; then
+        echo "❌ Not on main branch. Switch to main first."
+        exit 1
+    fi
+    
+    # Check if tag already exists
+    if git tag -l "{{version}}" | grep -q "{{version}}"; then
+        echo "❌ Tag {{version}} already exists"
+        exit 1
+    fi
+    
+    # Run quality checks
+    echo "🔍 Running quality checks..."
+    just check
+    
+    # Update version in __init__.py
+    echo "📝 Updating version in __init__.py..."
+    sed -i.bak "s/__version__ = \".*\"/__version__ = \"$VERSION_NUM\"/" src/basic_memory/__init__.py
+    rm -f src/basic_memory/__init__.py.bak
+    
+    # Commit version update
+    git add src/basic_memory/__init__.py
+    git commit -m "chore: update version to $VERSION_NUM for {{version}} release"
+    
+    # Create and push tag
+    echo "🏷️  Creating tag {{version}}..."
+    git tag "{{version}}"
+    
+    echo "📤 Pushing to GitHub..."
+    git push origin main
+    git push origin "{{version}}"
+    
+    echo "✅ Release {{version}} created successfully!"
+    echo "📦 GitHub Actions will build and publish to PyPI"
+    echo "🔗 Monitor at: https://github.com/basicmachines-co/basic-memory/actions"
+
+# Create a beta release (e.g., just beta v0.13.2b1)
+beta version:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    
+    # Validate version format (allow beta/rc suffixes)
+    if [[ ! "{{version}}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(b[0-9]+|rc[0-9]+)$ ]]; then
+        echo "❌ Invalid beta version format. Use: v0.13.2b1 or v0.13.2rc1"
+        exit 1
+    fi
+    
+    # Extract version number without 'v' prefix
+    VERSION_NUM=$(echo "{{version}}" | sed 's/^v//')
+    
+    echo "🧪 Creating beta release {{version}}"
+    
+    # Pre-flight checks
+    echo "📋 Running pre-flight checks..."
+    if [[ -n $(git status --porcelain) ]]; then
+        echo "❌ Uncommitted changes found. Please commit or stash them first."
+        exit 1
+    fi
+    
+    if [[ $(git branch --show-current) != "main" ]]; then
+        echo "❌ Not on main branch. Switch to main first."
+        exit 1
+    fi
+    
+    # Check if tag already exists
+    if git tag -l "{{version}}" | grep -q "{{version}}"; then
+        echo "❌ Tag {{version}} already exists"
+        exit 1
+    fi
+    
+    # Run quality checks
+    echo "🔍 Running quality checks..."
+    just check
+    
+    # Update version in __init__.py
+    echo "📝 Updating version in __init__.py..."
+    sed -i.bak "s/__version__ = \".*\"/__version__ = \"$VERSION_NUM\"/" src/basic_memory/__init__.py
+    rm -f src/basic_memory/__init__.py.bak
+    
+    # Commit version update
+    git add src/basic_memory/__init__.py
+    git commit -m "chore: update version to $VERSION_NUM for {{version}} beta release"
+    
+    # Create and push tag
+    echo "🏷️  Creating tag {{version}}..."
+    git tag "{{version}}"
+    
+    echo "📤 Pushing to GitHub..."
+    git push origin main
+    git push origin "{{version}}"
+    
+    echo "✅ Beta release {{version}} created successfully!"
+    echo "📦 GitHub Actions will build and publish to PyPI as pre-release"
+    echo "🔗 Monitor at: https://github.com/basicmachines-co/basic-memory/actions"
+    echo "📥 Install with: uv tool install basic-memory --pre"
+
+# List all available recipes
+default:
+    @just --list