feat: add DXT packaging support (experimental)

- Add comprehensive manifest.json with all 19 Basic Memory MCP tools
- Implement automated DXT build process via justfile (just dxt)
- Add DXT assets (icons and screenshots)
- Create .dxtignore for excluding development files
- Update .gitignore to exclude generated DXT bundle files

Note: DXT implementation blocked by Anthropic DXT v0.1 limitations:
- Binary permissions issues (anthropics/dxt#12)
- Platform-specific dependency problems (anthropics/dxt#17)
- Native module loading errors with pydantic_core

See issue #193 for detailed analysis and future implementation plan.

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

Co-Authored-By: Claude <noreply@anthropic.com>

.claude/commands/check-health.md

@@ -1,190 +0,0 @@
-# /project:check-health - Project Health Assessment
-
-Comprehensive health check of the Basic Memory project including code quality, test coverage, dependencies, and documentation.
-
-## Usage
-```
-/project:check-health
-```
-
-## Implementation
-
-You are an expert DevOps engineer for the Basic Memory project. When the user runs `/project:check-health`, execute the following comprehensive assessment:
-
-### Step 1: Git Repository Health
-1. **Repository Status**
-   ```bash
-   git status
-   git log --oneline -5
-   git branch -vv
-   ```
-   - Check working directory status
-   - Verify branch alignment with remote
-   - Check recent commit activity
-
-2. **Branch Analysis**
-   - Verify on main branch
-   - Check if ahead/behind remote
-   - Identify any untracked files
-
-### Step 2: Code Quality Assessment
-1. **Linting and Formatting**
-   ```bash
-   uv run ruff check .
-   uv run pyright
-   ```
-   - Count linting issues by severity
-   - Check type annotation coverage
-   - Verify code formatting compliance
-
-2. **Test Suite Health**
-   ```bash
-   uv run pytest --collect-only -q
-   uv run pytest --co -q | wc -l
-   ```
-   - Count total tests
-   - Check for test discovery issues
-   - Verify test structure integrity
-
-### Step 3: Dependency Analysis
-1. **Dependency Health**
-   ```bash
-   uv tree
-   uv lock --dry-run
-   ```
-   - Check for dependency conflicts
-   - Identify outdated dependencies
-   - Verify lock file consistency
-
-2. **Security Scan**
-   ```bash
-   uv run pip-audit --desc
-   ```
-   - Scan for known vulnerabilities
-   - Check dependency licenses
-   - Identify security advisories
-
-### Step 4: Performance Metrics
-1. **Test Performance**
-   ```bash
-   uv run pytest --durations=10
-   ```
-   - Identify slowest tests
-   - Check overall test execution time
-   - Monitor test suite growth
-
-2. **Build Performance**
-   ```bash
-   time uv run python -c "import basic_memory"
-   ```
-   - Check import time
-   - Validate package installation
-   - Monitor startup performance
-
-### Step 5: Documentation Health
-1. **Documentation Coverage**
-   - Check README.md currency
-   - Verify CLI documentation
-   - Validate MCP tool documentation
-   - Check changelog completeness
-
-2. **API Documentation**
-   - Verify docstring coverage
-   - Check type annotation completeness
-   - Validate example code
-
-### Step 6: Project Metrics
-1. **Code Statistics**
-   ```bash
-   find src -name "*.py" | xargs wc -l
-   find tests -name "*.py" | xargs wc -l
-   ```
-   - Lines of code trends
-   - Test-to-code ratio
-   - File organization metrics
-
-## Health Report Format
-
-Generate comprehensive health dashboard:
-
-```
-🏥 Basic Memory Project Health Report
-
-📊 OVERALL HEALTH: 🟢 EXCELLENT (92/100)
-
-🗂️  GIT REPOSITORY
-✅ Clean working directory
-✅ Up to date with origin/main
-✅ Recent commit activity (5 commits this week)
-
-🔍 CODE QUALITY  
-✅ Linting: 0 errors, 2 warnings
-✅ Type checking: 100% coverage
-✅ Formatting: Compliant
-⚠️  Complex functions: 3 need refactoring
-
-🧪 TEST SUITE
-✅ Total tests: 744 
-✅ Test discovery: All tests found
-✅ Coverage: 98.2%
-⚡ Performance: 45.2s (good)
-
-📦 DEPENDENCIES
-✅ Dependencies: Up to date
-✅ Security: No vulnerabilities
-✅ Conflicts: None detected
-⚠️  Outdated: 2 minor updates available
-
-📖 DOCUMENTATION
-✅ README: Current
-✅ API docs: 95% coverage
-⚠️  CLI reference: Needs update
-✅ Changelog: Complete
-
-📈 METRICS
-├── Source code: 15,432 lines
-├── Test code: 8,967 lines  
-├── Test ratio: 58% (excellent)
-└── Complexity: Low (maintainable)
-
-🎯 RECOMMENDATIONS:
-1. Update CLI documentation
-2. Refactor 3 complex functions
-3. Update minor dependencies
-4. Consider splitting large test files
-
-🏆 PROJECT STATUS: Ready for v0.13.0 release!
-```
-
-## Health Scoring
-
-### Excellent (90-100)
-- All quality gates pass
-- High test coverage (>95%)
-- No security issues
-- Documentation current
-
-### Good (75-89)
-- Minor issues present
-- Good test coverage (>90%)
-- No critical security issues
-- Most documentation current
-
-### Needs Attention (60-74)
-- Several quality issues
-- Adequate test coverage (>80%)
-- Minor security concerns
-- Documentation gaps
-
-### Critical (<60)
-- Major quality problems
-- Low test coverage (<80%)
-- Security vulnerabilities
-- Significant documentation issues
-
-## Context
-- Provides comprehensive project overview
-- Identifies potential issues before they become problems
-- Tracks project health trends over time
-- Helps prioritize maintenance tasks
-- Supports release readiness decisions

.claude/commands/commands.md

@@ -1,62 +0,0 @@
-# Basic Memory Custom Commands
-
-This directory contains custom Claude Code slash commands for the Basic Memory project.
-
-## Available Commands
-
-### Release Management (`/project:release:*`)
-- `/project:release:beta` - Create beta releases with automated quality checks
-- `/project:release:release` - Create stable releases with comprehensive validation  
-- `/project:release:release-check` - Pre-flight validation without making changes
-- `/project:release:changelog` - Generate changelog entries from commits
-
-### Development (`/project:*`)
-- `/project:test-coverage` - Run tests with detailed coverage analysis
-- `/project:test-live` - Live testing suite using real Basic Memory installation
-- `/project:lint-fix` - Run comprehensive linting with auto-fix
-- `/project:check-health` - Comprehensive project health assessment
-
-## Command Structure
-
-Commands are organized by functionality:
-```
-.claude/commands/
-├── release/          # Release management commands
-│   ├── beta.md       # /project:release:beta
-│   ├── release.md    # /project:release:release
-│   ├── release-check.md # /project:release:release-check
-│   └── changelog.md  # /project:release:changelog
-├── test-coverage.md  # /project:test-coverage
-├── test-live.md      # /project:test-live
-├── lint-fix.md       # /project:lint-fix
-├── check-health.md   # /project:check-health
-└── commands.md       # This overview file
-```
-
-## Usage
-
-Commands are invoked using the `/project:` prefix:
-- `/project:release:beta v0.13.0b4`
-- `/project:test-coverage mcp`
-- `/project:test-live core`
-- `/project:release:release-check`
-- `/project:check-health`
-
-## Implementation
-
-Each command is implemented as a Markdown file containing structured prompts that:
-1. Validate preconditions
-2. Execute steps in the correct order
-3. Handle errors gracefully  
-4. Provide clear status updates
-5. Return actionable results
-
-## Tooling Integration
-
-Commands leverage existing project tooling:
-- `make check` - Quality checks
-- `make test` - Test suite
-- `make update-deps` - Dependency updates  
-- `uv` - Package management
-- `git` - Version control
-- GitHub Actions - CI/CD pipeline

.claude/commands/lint-fix.md

@@ -1,145 +0,0 @@
-# /project:lint-fix - Comprehensive Code Quality Fix
-
-Run comprehensive linting and auto-fix code quality issues across the codebase.
-
-## Usage
-```
-/project:lint-fix
-```
-
-## Implementation
-
-You are an expert code quality engineer for the Basic Memory project. When the user runs `/project:lint-fix`, execute the following steps:
-
-### Step 1: Pre-flight Check
-1. **Verify Clean Working Directory**
-   ```bash
-   git status --porcelain
-   ```
-   - Check for uncommitted changes
-   - Warn if working directory is not clean
-   - Suggest stashing changes if needed
-
-### Step 2: Import Organization
-1. **Fix Import Order and Cleanup**
-   ```bash
-   uv run ruff check --select I --fix .
-   ```
-   - Sort imports by category (standard, third-party, local)
-   - Remove unused imports
-   - Fix import spacing and organization
-
-### Step 3: Code Formatting
-1. **Apply Consistent Formatting**
-   ```bash
-   uv run ruff format .
-   ```
-   - Format code according to project style
-   - Fix line length issues (100 chars max)
-   - Standardize quotes and spacing
-
-### Step 4: Linting with Auto-fix
-1. **Fix Linting Issues**
-   ```bash
-   uv run ruff check --fix .
-   ```
-   - Auto-fix safe linting issues
-   - Report any remaining manual fixes needed
-   - Focus on code quality and best practices
-
-### Step 5: Type Checking
-1. **Validate Type Annotations**
-   ```bash
-   uv run pyright
-   ```
-   - Check for type errors
-   - Report any missing type annotations
-   - Validate type compatibility
-
-### Step 6: Report Generation
-Generate comprehensive quality report:
-
-```
-🔧 Code Quality Fix Report
-
-✅ FIXES APPLIED:
-├── Import organization: 12 files updated
-├── Code formatting: 8 files reformatted  
-├── Auto-fixable lint issues: 23 issues resolved
-└── Total files processed: 156
-
-⚠️  MANUAL ATTENTION NEEDED:
-├── Type annotations missing in entity_service.py:45
-├── Complex function needs refactoring in sync_service.py:123
-└── Unused variable in test_utils.py:67
-
-🎯 QUALITY SCORE: 96.2% (excellent)
-
-📁 Run `git diff` to review all changes
-```
-
-## Error Handling
-
-### Common Issues
-- **Merge Conflicts**: Provide resolution guidance
-- **Syntax Errors**: Point to specific files and lines
-- **Type Errors**: Suggest specific fixes
-- **Import Errors**: Check for missing dependencies
-
-### Recovery Steps
-- If auto-fixes introduce issues, provide rollback instructions
-- If type checking fails, suggest incremental fixes
-- If tests break, provide debugging guidance
-
-## Quality Gates
-
-### Must Pass
-- [ ] All auto-fixable lint issues resolved
-- [ ] Code formatting consistent
-- [ ] No syntax errors
-- [ ] Import organization clean
-
-### Should Pass (Warnings)
-- [ ] No type checking errors
-- [ ] No complex function warnings
-- [ ] No unused variables/imports
-- [ ] Consistent naming conventions
-
-## Output Examples
-
-### Successful Fix
-```
-🎉 CODE QUALITY IMPROVED!
-
-✅ All auto-fixes applied successfully
-📏 Code formatting: 100% compliant
-🔍 Linting: No issues found
-🏷️  Type checking: All passed
-
-Ready for commit! Use:
-git add -A && git commit -m "style: fix code quality issues"
-```
-
-### Issues Requiring Attention
-```
-⚠️  PARTIAL SUCCESS - MANUAL FIXES NEEDED
-
-✅ Auto-fixes applied: 45 issues
-❌ Manual fixes needed: 3 issues
-
-Priority fixes:
-1. Fix type annotation in services/entity_service.py:142
-2. Simplify complex function in sync/sync_service.py:67
-3. Remove unused import in tests/conftest.py:12
-
-Run these commands:
-# Fix specific file
-uv run pyright src/basic_memory/services/entity_service.py
-```
-
-## Context
-- Uses ruff for fast Python linting and formatting
-- Uses pyright for type checking
-- Follows project code style guidelines (100 char line length)
-- Maintains backward compatibility
-- Integrates with existing pre-commit hooks

.claude/commands/release/beta.md

@@ -1,69 +1,95 @@
 # /beta - Create Beta Release
 
-Create a new beta release for the current version with automated quality checks and tagging.
+Create a new beta release using the automated justfile target with quality checks and tagging.
 
 ## Usage
 ```
-/beta [version]
+/beta <version>
 ```
 
 **Parameters:**
-- `version` (optional): Beta version like `v0.13.0b4`. If not provided, auto-increments from latest beta tag.
+- `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 Checks
-1. Check current git status for uncommitted changes
-2. Verify we're on the `main` branch
-3. Get the latest beta tag to determine next version if not provided
+### 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: Quality Assurance
-1. Run `make check` to ensure code quality
-2. If any checks fail, report issues and stop
-3. Run `make update-deps` to ensure latest dependencies
-4. Commit any dependency updates with proper message
+### Step 2: Use Justfile Automation
+Execute the automated beta release process:
+```bash
+just beta <version>
+```
 
-### Step 3: Version Determination
-If version not provided:
-1. Get latest git tags with `git tag -l "v*b*" --sort=-version:refname | head -1`
-2. Auto-increment beta number (e.g., `v0.13.0b2` → `v0.13.0b3`)
-3. Confirm version with user before proceeding
+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 4: Release Creation
-1. Commit any remaining changes
-2. Push to main: `git push origin main`
-3. Create tag: `git tag {version}`
-4. Push tag: `git push origin {version}`
-
-### Step 5: Monitor Release
+### Step 3: Monitor Beta Release
 1. Check GitHub Actions workflow starts successfully
-2. Provide installation instructions for beta
-3. Report status and next steps
+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 quality checks fail, provide specific fix instructions
-- If git operations fail, provide manual recovery steps  
-- If GitHub Actions fail, provide debugging guidance
+- 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.0b4 Created Successfully!
+✅ Beta Release v0.13.2b1 Created Successfully!
 
-🏷️  Tag: v0.13.0b4
+🏷️  Tag: v0.13.2b1
 🚀 GitHub Actions: Running
-📦 PyPI: Will be available in ~5 minutes
+📦 PyPI: Will be available in ~5 minutes as pre-release
 
-Install with:
-uv tool upgrade basic-memory --prerelease=allow
+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
-- Use the existing Makefile targets (`make check`, `make update-deps`)
-- Follow semantic versioning for beta releases
-- Maintain release notes in CHANGELOG.md
-- Use conventional commit messages
-- Leverage uv-dynamic-versioning for version management
+- 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

@@ -8,7 +8,7 @@ Analyze commits and generate formatted changelog entry for a version.
 ```
 
 **Parameters:**
-- `version` (required): Version like `v0.13.0` or `v0.13.0b4`
+- `version` (required): Version like `v0.14.0` or `v0.14.0b1`
 - `type` (optional): `beta`, `rc`, or `stable` (default: `stable`)
 
 ## Implementation
@@ -59,8 +59,9 @@ You are an expert technical writer for the Basic Memory project. When the user r
 ### Step 3: Generate Changelog Entry
 Create formatted entry following existing CHANGELOG.md style:
 
+Example:
 ```markdown
-## v0.13.0 (2025-06-03)
+## <version> (<date>)
 
 ### Features
 
@@ -128,6 +129,8 @@ Create formatted entry following existing CHANGELOG.md style:
 ## Output Format
 
 ### For Beta Releases
+
+Example: 
 ```markdown
 ## v0.13.0b4 (2025-06-03)
 

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

@@ -28,7 +28,7 @@ You are an expert QA engineer for the Basic Memory project. When the user runs `
 ### Step 2: Code Quality Gates
 1. **Test Suite Validation**
    ```bash
-   make test
+   just test
    ```
    - All tests must pass
    - Check test coverage (target: 95%+)
@@ -36,8 +36,8 @@ You are an expert QA engineer for the Basic Memory project. When the user runs `
 
 2. **Code Quality Checks**
    ```bash
-   make lint
-   make type-check
+   just lint
+   just type-check
    ```
    - No linting errors
    - No type checking errors

.claude/commands/release/release.md

@@ -1,6 +1,6 @@
 # /release - Create Stable Release
 
-Create a stable release from the current main branch with comprehensive validation.
+Create a stable release using the automated justfile target with comprehensive validation.
 
 ## Usage
 ```
@@ -8,7 +8,7 @@ Create a stable release from the current main branch with comprehensive validati
 ```
 
 **Parameters:**
-- `version` (required): Release version like `v0.13.0`
+- `version` (required): Release version like `v0.13.2`
 
 ## Implementation
 
@@ -20,53 +20,60 @@ You are an expert release manager for the Basic Memory project. When the user ru
 3. Verify we're on the `main` branch
 4. Confirm no existing tag with this version
 
-### Step 2: Comprehensive Quality Checks
-1. Run `make check` (lint, format, type-check, full test suite)
-2. Verify test coverage meets minimum requirements (95%+)
-3. Check that CHANGELOG.md contains entry for this version
-4. Validate all high-priority issues are closed
+#### Documentation Validation
+1. **Changelog Check**
+   - CHANGELOG.md contains entry for target version
+   - Entry includes all major features and fixes
+   - Breaking changes are documented
 
-### Step 3: Release Preparation
-1. Update any version references if needed
-2. Commit any final changes with message: `chore: prepare for ${version} release`
-3. Push to main: `git push origin main`
+### Step 2: Use Justfile Automation
+Execute the automated release process:
+```bash
+just release <version>
+```
 
-### Step 4: Release Creation
-1. Create annotated tag: `git tag -a ${version} -m "Release ${version}"`
-2. Push tag: `git push origin ${version}`
-3. Monitor GitHub Actions for release automation
+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
 
-### Step 5: Post-Release Validation
+### Step 3: Monitor Release Process
+1. Check that GitHub Actions workflow starts successfully
+2. Monitor workflow completion at: https://github.com/basicmachines-co/basic-memory/actions
+3. Verify PyPI publication
+4. Test installation: `uv tool install basic-memory`
+
+### Step 4: Post-Release Validation
 1. Verify GitHub release is created automatically
 2. Check PyPI publication
 3. Validate release assets
-4. Test installation: `uv tool install basic-memory`
-
-### Step 6: Documentation Update
-1. Update any post-release documentation
-2. Create follow-up tasks if needed
+4. Update any post-release documentation
 
 ## Pre-conditions Check
 Before starting, verify:
 - [ ] All beta testing is complete
 - [ ] Critical bugs are fixed
 - [ ] Breaking changes are documented
-- [ ] CHANGELOG.md is updated
+- [ ] CHANGELOG.md is updated (if needed)
 - [ ] Version number follows semantic versioning
 
 ## Error Handling
-- If any quality check fails, stop and provide fix instructions
-- If changelog entry missing, prompt to create one
-- If tests fail, provide debugging guidance
-- If GitHub Actions fail, provide manual release steps
+- 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.0 Created Successfully!
+🎉 Stable Release v0.13.2 Created Successfully!
 
-🏷️  Tag: v0.13.0
-📋 GitHub Release: https://github.com/basicmachines-co/basic-memory/releases/tag/v0.13.0
-📦 PyPI: https://pypi.org/project/basic-memory/0.13.0/
+🏷️  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/
 🚀 GitHub Actions: Completed
 
 Install with:
@@ -79,6 +86,7 @@ uv tool upgrade basic-memory
 ## Context
 - This creates production releases used by end users
 - Must pass all quality gates before proceeding
-- Follows the release workflow documented in CLAUDE.md
-- Uses uv-dynamic-versioning for automatic version management
-- Triggers automated GitHub release with changelog
+- Uses the automated justfile target for consistency
+- Version is automatically updated in `__init__.py`
+- Triggers automated GitHub release with changelog
+- Leverages uv-dynamic-versioning for package version management

.claude/commands/test-coverage.md

@@ -1,131 +0,0 @@
-# /test-coverage - Run Tests with Coverage Analysis
-
-Execute test suite with comprehensive coverage reporting and analysis.
-
-## Usage
-```
-/test-coverage [pattern]
-```
-
-**Parameters:**
-- `pattern` (optional): Test pattern to run specific tests (e.g., `test_mcp`, `*integration*`)
-
-## Implementation
-
-You are an expert QA engineer for the Basic Memory project. When the user runs `/test-coverage`, execute the following steps:
-
-### Step 1: Test Execution
-1. **Run Tests with Coverage**
-   ```bash
-   # Full test suite
-   uv run pytest --cov=basic_memory --cov-report=html --cov-report=term -v
-   
-   # Or with pattern if provided
-   uv run pytest tests/*{pattern}* --cov=basic_memory --cov-report=html --cov-report=term -v
-   ```
-
-2. **Generate Coverage Reports**
-   - Terminal summary with percentages
-   - HTML report for detailed analysis
-   - Identify files below coverage threshold
-
-### Step 2: Coverage Analysis
-1. **Summary Statistics**
-   - Overall coverage percentage
-   - Number of files with 100% coverage
-   - Files below 95% threshold
-   - Total lines covered/missed
-
-2. **Detailed Breakdown**
-   - Coverage by module/package
-   - Identify untested code paths
-   - Find missing edge case tests
-
-### Step 3: Report Generation
-Generate comprehensive coverage report:
-
-```
-🧪 Test Coverage Report
-
-📊 OVERALL COVERAGE: 98.2% (target: 95%+)
-
-✅ EXCELLENT COVERAGE (>95%):
-├── basic_memory/mcp/: 99.1%
-├── basic_memory/services/: 98.8%
-├── basic_memory/repository/: 97.9%
-└── basic_memory/api/: 96.2%
-
-⚠️  NEEDS ATTENTION (<95%):
-├── basic_memory/sync/: 94.1% (missing 12 lines)
-└── basic_memory/importers/: 91.8% (missing 23 lines)
-
-🎯 SPECIFIC GAPS:
-├── sync_service.py:142-145 (error handling)
-├── importer_base.py:67-70 (edge case)
-└── file_utils.py:89 (exception path)
-
-📁 HTML Report: htmlcov/index.html
-🚀 Run `open htmlcov/index.html` to view detailed report
-```
-
-### Step 4: Actionable Recommendations
-1. **Coverage Improvements**
-   - Suggest specific tests to add
-   - Identify edge cases to cover
-   - Recommend integration tests
-
-2. **Quality Insights**
-   - Highlight well-tested modules
-   - Point out testing patterns to follow
-   - Suggest refactoring for testability
-
-## Advanced Analysis
-
-### Performance Metrics
-- Test execution time by module
-- Slowest tests identification
-- Coverage collection overhead
-
-### Integration Coverage
-- MCP tool integration tests
-- API endpoint coverage
-- Database operation coverage
-- File system operation coverage
-
-## Output Examples
-
-### Full Coverage Success
-```
-🎉 EXCELLENT COVERAGE!
-
-📊 Coverage: 98.7% (744 tests passed)
-✅ All modules above 95% threshold
-🏆 23 files with 100% coverage
-⚡ Tests completed in 45.2s
-
-Ready for release! 🚀
-```
-
-### Coverage Issues Found
-```
-⚠️  COVERAGE GAPS DETECTED
-
-📊 Coverage: 92.1% (below 95% target)
-❌ 3 modules need attention
-🔍 43 uncovered lines found
-
-Priority fixes:
-1. Add tests for error handling in sync_service.py
-2. Cover edge cases in importer_base.py
-3. Test exception paths in file_utils.py
-
-Run specific tests:
-uv run pytest tests/sync/ -v
-```
-
-## Context
-- Uses pytest with coverage plugin
-- Generates both terminal and HTML reports
-- Focuses on actionable improvement suggestions
-- Integrates with existing test infrastructure
-- Helps maintain high code quality standards

.claude/commands/test-live.md

@@ -1,6 +1,7 @@
 # /project:test-live - Live Basic Memory Testing Suite
 
-Execute comprehensive real-world testing of Basic Memory using the installed version, following the methodology in TESTING.md. All test results are recorded as notes in a dedicated test project.
+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
 ```
@@ -8,11 +9,45 @@ Execute comprehensive real-world testing of Basic Memory using the installed ver
 ```
 
 **Parameters:**
-- `phase` (optional): Specific test phase to run (`core`, `features`, `edge`, `workflows`, `stress`, or `all`)
+- `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_projects, switch_project)
+- `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 testing following the TESTING.md methodology:
+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 status
+6. **switch_project** - Context switching for multi-project workflows
+
+### **Tier 2: Important Workflows (Usually Test)**
+7. **recent_activity** - Understanding what's changed
+8. **build_context** - Conversation continuity via memory:// URLs
+9. **create_memory_project** - Essential for project setup
+10. **move_note** - Knowledge organization
+11. **sync_status** - Understanding system state
+
+### **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. **set_default_project** - Configuration
+17. **delete_project** - Administrative cleanup
+
+### **Tier 4: Specialized (Rarely Test)**
+18. **canvas** - Obsidian visualization (specialized use case)
+19. **MCP Prompts** - Enhanced UX tools (ai_assistant_guide, continue_conversation)
 
 ### Pre-Test Setup
 
@@ -21,83 +56,176 @@ You are an expert QA engineer conducting live testing of Basic Memory. When the
    - Check version and confirm it's the expected release
    - Test MCP connection and tool availability
 
-2. **Test Project Creation**
+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
    ```
 
-3. **Baseline Documentation**
+Make sure to switch to the newly created project with the `switch_project()` tool.
+
+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 1: Core Functionality Validation
+### Phase 0: Recent Changes Validation (if 'recent' or 'all' phase)
 
-Test all fundamental MCP tools systematically:
+Based on recent commit analysis, create targeted test scenarios:
 
-**write_note Tests:**
-- Basic note creation with various content types
-- Frontmatter handling (tags, custom fields)
-- Special characters in titles and content
-- Unicode and emoji support
-- Empty notes and minimal content
+**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
 
-**read_note Tests:**
-- Read by title, permalink, memory:// URLs
-- Non-existent notes (error handling)
-- Notes with complex formatting
-- Performance with large notes
+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
 
-**search_notes Tests:**
-- Simple text queries
-- Tag-based searches 
-- Boolean operators and complex queries
-- Empty/no results scenarios
-- Performance with growing knowledge base
+3. **Performance/Enhancement Validation** - For optimizations:
+   - Establish baseline timing
+   - Compare with expected improvements
+   - Test under various load conditions
+   - Document performance observations
 
-**Recent Activity Tests:**
-- Various timeframes ("today", "1 week", "1d")
-- Type filtering (if available)
-- Empty project scenarios
-- Performance with many recent changes
+**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
 
-**Context Building Tests:**
-- Different depth levels (1, 2, 3+)
-- Various timeframes
-- Relation traversal accuracy
-- Performance with complex graphs
+### Phase 1: Core Functionality Validation (Tier 1 Tools)
 
-### Phase 2: v0.13.0 Feature Deep Dive
+Test essential MCP tools that form the foundation of Basic Memory:
 
-**Project Management:**
-- Create multiple projects dynamically
-- Switch between projects mid-conversation  
-- Cross-project operations
-- Project discovery and status
-- Default project behavior
-- Invalid project handling
+**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
 
-**Advanced Note Editing:**
-- `edit_note` with append operations
-- Prepend operations
-- Find/replace with validation
-- Section replacement under headers
-- Error scenarios (invalid operations)
-- Frontmatter preservation
+**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)
 
-**File Management:**
-- `move_note` within same project
-- Move between projects
-- Automatic folder creation
-- Special characters in paths
-- Database consistency validation
-- Search index updates after moves
+**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
 
-### Phase 3: Edge Case Exploration
+**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 status indicators
+- ✅ Current and default project identification
+- ✅ Empty project list handling
+- ✅ Project metadata accuracy
+
+**6. switch_project Tests (Critical):**
+- ✅ Switch between existing projects
+- ✅ Context preservation during switch
+- ⚠️ Invalid project name handling
+- ✅ Confirmation of successful switch
+
+### Phase 2: Important Workflows (Tier 2 Tools)
+
+**7. recent_activity Tests (Important):**
+- ✅ Various timeframes ("today", "1 week", "1d")
+- ✅ Type filtering capabilities
+- ✅ Empty project scenarios
+- ⚠️ Performance with many recent changes
+
+**8. build_context Tests (Important):**
+- ✅ Different depth levels (1, 2, 3+)
+- ✅ Various timeframes for context
+- ✅ memory:// URL navigation
+- ⚠️ Performance with complex relation graphs
+
+**9. create_memory_project Tests (Important):**
+- ✅ Create projects dynamically
+- ✅ Set default during creation
+- ✅ Path validation and creation
+- ⚠️ Invalid paths and names
+- ✅ Integration with existing projects
+
+**10. move_note Tests (Important):**
+- ✅ Move within same project
+- ✅ Cross-project moves with detection (#161)
+- ✅ Automatic folder creation
+- ✅ Database consistency validation
+- ⚠️ Special characters in paths
+
+**11. sync_status Tests (Important):**
+- ✅ Background operation monitoring
+- ✅ File synchronization status
+- ✅ Project sync state reporting
+- ⚠️ Error state handling
+
+### Phase 3: Enhanced Functionality (Tier 3 Tools)
+
+**12. view_note Tests (Enhanced):**
+- ✅ Claude Desktop artifact display
+- ✅ Title extraction from frontmatter
+- ✅ Unicode and emoji content rendering
+- ⚠️ Error handling for non-existent notes
+
+**13. read_content Tests (Enhanced):**
+- ✅ Raw file content access
+- ✅ Binary file handling
+- ✅ Image file reading
+- ⚠️ Large file performance
+
+**14. delete_note Tests (Enhanced):**
+- ✅ Single note deletion
+- ✅ Database consistency after deletion
+- ⚠️ Non-existent note handling
+- ✅ Confirmation of successful deletion
+
+**15. list_directory Tests (Enhanced):**
+- ✅ Directory content listing
+- ✅ Depth control and filtering
+- ✅ File name globbing
+- ⚠️ Empty directory handling
+
+**16. set_default_project Tests (Enhanced):**
+- ✅ Change default project
+- ✅ Configuration persistence
+- ⚠️ Invalid project handling
+
+**17. 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)
@@ -121,7 +249,7 @@ Test all fundamental MCP tools systematically:
 - Rapid successive operations
 - Memory usage monitoring
 
-### Phase 4: Real-World Workflow Scenarios
+### Phase 5: Real-World Workflow Scenarios
 
 **Meeting Notes Pipeline:**
 1. Create meeting notes with action items
@@ -151,7 +279,35 @@ Test all fundamental MCP tools systematically:
 4. Update content with edit operations
 5. Validate knowledge graph integrity
 
-### Phase 5: Creative Stress Testing
+### Phase 6: Specialized Tools Testing (Tier 4)
+
+**18. canvas Tests (Specialized):**
+- ✅ JSON Canvas generation
+- ✅ Node and edge creation
+- ✅ Obsidian compatibility
+- ⚠️ Complex graph handling
+
+**19. 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
@@ -167,6 +323,26 @@ Test all fundamental MCP tools systematically:
 - 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:
@@ -189,14 +365,14 @@ permalink: test-session-[phase]-[timestamp]
 ## Test Results
 
 ### ✅ Successful Operations
-- [timestamp] write_note: Created note with emoji title 📝 #functionality
-- [timestamp] search_notes: Boolean query returned 23 results in 0.4s #performance  
-- [timestamp] edit_note: Append operation preserved frontmatter #reliability
+- [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) #performance
-- [timestamp] search_notes: Unicode query returned unexpected results #bug
-- [timestamp] project switch: Context lost for memory:// URLs #issue
+- [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
@@ -340,24 +516,44 @@ For each error discovered:
    - 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:**
-- v0.13.0 feature verification in real usage
-- Edge case discovery beyond unit tests
+- Feature verification prioritized by tier importance
+- Recent changes validated for regression
 - Performance baseline establishment
-- Bug identification with reproduction cases
+- Bug identification with severity assessment
 
 **Knowledge Base Creation:**
-- Comprehensive testing documentation
+- Prioritized testing documentation
 - Real usage examples for user guides
-- Edge case scenarios for future testing
+- Recent changes validation records
 - Performance insights for optimization
 
 **Development Insights:**
-- Prioritized bug fix list
+- Tier-based bug priority list
+- Recent changes impact assessment
 - Enhancement ideas from real usage
-- Architecture validation results
 - User experience improvement areas
 
 ## Post-Test Deliverables
@@ -389,9 +585,11 @@ For each error discovered:
    - Add performance benchmarks and targets
 
 ## Context
-- Uses installed basic-memory version (not development)
+- 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 for development team
+- 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

.dxtignore

@@ -0,0 +1,81 @@
+# Development files
+.venv/
+.pytest_cache/
+.coverage*
+htmlcov/
+.ruff_cache/
+**/__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.env
+.env.*
+
+# Testing
+test*/
+tests/
+*.test.js
+*.test.py
+pytest.ini
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+.tox/
+
+# IDE files
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Claude
+.claude
+
+# Git files
+.git/
+.gitignore
+
+# Documentation build
+docs/_build/
+
+# Temporary files
+*.tmp
+*.log
+.DS_Store
+Thumbs.db
+
+# DXT package output
+*.dxt
+dxt-bundle/
+
+
+# Lock files
+uv.lock
+package-lock.json
+yarn.lock
+
+# Docker
+Dockerfile
+docker-compose.yml
+.dockerignore
+
+# CI/CD
+.github/
+justfile
+smithery.yaml
+
+# Project files
+.python.version
+CHANGELOG.md
+CITATION.cff
+CLA.md
+CLAUDE.md
+CODE_OF_CONDUCT.md
+CONTRIBUTING.md
+README.md
+SECURITY.md
+docs/
+llms-install.md

.env.oauth.example

@@ -1,55 +0,0 @@
-# OAuth Configuration for Basic Memory MCP Server
-# Copy this file to .env and update the values
-
-# Enable OAuth authentication
-FASTMCP_AUTH_ENABLED=true
-
-# OAuth provider type: basic, github, google, or supabase
-# - basic: Built-in OAuth provider with in-memory storage
-# - github: Integrate with GitHub OAuth
-# - google: Integrate with Google OAuth
-# - supabase: Integrate with Supabase Auth (recommended for production)
-FASTMCP_AUTH_PROVIDER=basic
-
-# OAuth issuer URL (your MCP server URL)
-FASTMCP_AUTH_ISSUER_URL=http://localhost:8000
-
-# Documentation URL for OAuth endpoints
-FASTMCP_AUTH_DOCS_URL=http://localhost:8000/docs/oauth
-
-# Required scopes (comma-separated)
-# Examples: read,write,admin
-FASTMCP_AUTH_REQUIRED_SCOPES=read,write
-
-# Secret key for JWT tokens (auto-generated if not set)
-# FASTMCP_AUTH_SECRET_KEY=your-secret-key-here
-
-# Enable client registration endpoint
-FASTMCP_AUTH_CLIENT_REGISTRATION_ENABLED=true
-
-# Enable token revocation endpoint  
-FASTMCP_AUTH_REVOCATION_ENABLED=true
-
-# Default scopes for new clients
-FASTMCP_AUTH_DEFAULT_SCOPES=read
-
-# Valid scopes that can be requested
-FASTMCP_AUTH_VALID_SCOPES=read,write,admin
-
-# Client secret expiry in seconds (optional)
-# FASTMCP_AUTH_CLIENT_SECRET_EXPIRY=86400
-
-# GitHub OAuth settings (if using github provider)
-# GITHUB_CLIENT_ID=your-github-client-id
-# GITHUB_CLIENT_SECRET=your-github-client-secret
-
-# Google OAuth settings (if using google provider)
-# GOOGLE_CLIENT_ID=your-google-client-id  
-# GOOGLE_CLIENT_SECRET=your-google-client-secret
-
-# Supabase settings (if using supabase provider)
-# SUPABASE_URL=https://your-project.supabase.co
-# SUPABASE_ANON_KEY=your-anon-key
-# SUPABASE_SERVICE_KEY=your-service-key  # Optional, for admin operations
-# SUPABASE_JWT_SECRET=your-jwt-secret   # Optional, for token validation
-# SUPABASE_ALLOWED_CLIENTS=client1,client2  # Comma-separated list of allowed client IDs

.github/workflows/claude.yml

@@ -25,7 +25,7 @@ jobs:
       issues: read
       id-token: write
     steps:
-      - name: Check organization membership
+      - name: Check user permissions
         id: check_membership
         uses: actions/github-script@v7
         with:
@@ -41,29 +41,62 @@ jobs:
               actor = context.payload.issue.user.login;
             }
             
-            console.log(`Checking membership for user: ${actor}`);
+            console.log(`Checking permissions for user: ${actor}`);
             
+            // List of explicitly allowed users (organization members)
+            const allowedUsers = [
+              'phernandez',
+              'groksrc',
+              'nellins',
+              'bm-claudeai'
+            ];
+            
+            if (allowedUsers.includes(actor)) {
+              console.log(`User ${actor} is in the allowed list`);
+              core.setOutput('is_member', true);
+              return;
+            }
+            
+            // Fallback: Check if user has repository permissions
             try {
-              const membership = await github.rest.orgs.getMembershipForUser({
-                org: 'basicmachines-co',
+              const collaboration = await github.rest.repos.getCollaboratorPermissionLevel({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
                 username: actor
               });
               
-              console.log(`Membership status: ${membership.data.state}`);
+              const permission = collaboration.data.permission;
+              console.log(`User ${actor} has permission level: ${permission}`);
               
-              // Allow if user is a member (public or private) or admin
-              const allowed = membership.data.state === 'active' && 
-                            (membership.data.role === 'member' || membership.data.role === 'admin');
+              // Allow if user has push access or higher (write, maintain, admin)
+              const allowed = ['write', 'maintain', 'admin'].includes(permission);
               
               core.setOutput('is_member', allowed);
               
               if (!allowed) {
-                core.notice(`User ${actor} is not a member of basicmachines-co organization`);
+                core.notice(`User ${actor} does not have sufficient repository permissions (has: ${permission})`);
               }
             } catch (error) {
-              console.log(`Error checking membership: ${error.message}`);
-              core.setOutput('is_member', false);
-              core.notice(`User ${actor} is not a member of basicmachines-co organization`);
+              console.log(`Error checking permissions: ${error.message}`);
+              
+              // Final fallback: Check if user is a public member of the organization
+              try {
+                const membership = await github.rest.orgs.getMembershipForUser({
+                  org: 'basicmachines-co',
+                  username: actor
+                });
+                
+                const allowed = membership.data.state === 'active';
+                core.setOutput('is_member', allowed);
+                
+                if (!allowed) {
+                  core.notice(`User ${actor} is not a public member of basicmachines-co organization`);
+                }
+              } catch (membershipError) {
+                console.log(`Error checking organization membership: ${membershipError.message}`);
+                core.setOutput('is_member', false);
+                core.notice(`User ${actor} does not have access to this repository`);
+              }
             }
 
       - name: Checkout repository
@@ -78,4 +111,4 @@ jobs:
         uses: anthropics/claude-code-action@beta
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-          allowed_tools: Bash(uv run pytest),Bash(uv run ruff check . --fix),Bash(uv run ruff format .),Bash(uv run pyright),Bash(make test),Bash(make lint),Bash(make format),Bash(make type-check),Bash(make check),Read,Write,Edit,MultiEdit,Glob,Grep,LS
+          allowed_tools: Bash(uv run pytest),Bash(uv run ruff check . --fix),Bash(uv run ruff format .),Bash(uv run pyright),Bash(just test),Bash(just lint),Bash(just format),Bash(just type-check),Bash(just check),Read,Write,Edit,MultiEdit,Glob,Grep,LS, mcp__web_search

.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

@@ -32,17 +32,11 @@ jobs:
           uv sync
           uv build
 
-      - name: Verify version matches tag
+      - name: Verify build succeeded
         run: |
-          # Get version from built package
-          PACKAGE_VERSION=$(uv run python -c "import basic_memory; print(basic_memory.__version__)")
-          TAG_VERSION=${GITHUB_REF_NAME#v}  # Remove 'v' prefix from tag
-          echo "Package version: $PACKAGE_VERSION"
-          echo "Tag version: $TAG_VERSION"
-          if [ "$PACKAGE_VERSION" != "$TAG_VERSION" ]; then
-            echo "Version mismatch! Package: $PACKAGE_VERSION, Tag: $TAG_VERSION"
-            exit 1
-          fi
+          # Verify that build artifacts exist
+          ls -la dist/
+          echo "Build completed successfully"
 
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
@@ -57,4 +51,35 @@ jobs:
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
-          password: ${{ secrets.PYPI_TOKEN }}
+          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

@@ -35,6 +35,10 @@ jobs:
         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
@@ -45,9 +49,9 @@ jobs:
 
       - name: Run type checks
         run: |
-          uv run make type-check
+          just type-check
 
       - name: Run tests
         run: |
           uv pip install pytest pytest-cov
-          uv run make test
+          just test

.gitignore

@@ -42,7 +42,7 @@ ENV/
 
 # macOS
 .DS_Store
-/.coverage.*
+.coverage.*
 
 # obsidian docs:
 /docs/.obsidian/
@@ -53,3 +53,7 @@ ENV/
 # claude action
 claude-output
 **/.claude/settings.local.json
+
+# DXT package files
+basic-memory.dxt
+dxt-bundle/

.mcp.json

@@ -1,14 +0,0 @@
-{
-  "mcpServers": {
-    "basic-memory": {
-      "command": "uv",
-      "args": [
-        "--directory",
-        "/Users/phernandez/dev/basicmachines/basic-memory",
-        "run",
-        "src/basic_memory/cli/main.py",
-        "mcp"
-      ]
-    }
-  }
-}

AUTH.md

@@ -1,42 +0,0 @@
-# OAuth Quick Start
-
-Basic Memory supports OAuth authentication for secure access control. For detailed documentation, see [OAuth Authentication Guide](docs/OAuth%20Authentication%20Guide.md).
-
-## Quick Test with MCP Inspector
-
-```bash
-# 1. Set a consistent secret key
-export FASTMCP_AUTH_SECRET_KEY="test-secret-key"
-
-# 2. Start server with OAuth
-FASTMCP_AUTH_ENABLED=true basic-memory mcp --transport streamable-http
-
-# 3. In another terminal, get a test token
-export FASTMCP_AUTH_SECRET_KEY="test-secret-key"  # Same key!
-basic-memory auth test-auth
-
-# 4. Copy the access token and use in MCP Inspector:
-#    - Server URL: http://localhost:8000/mcp 
-#    - Transport: streamable-http
-#    - Custom Headers:
-#      Authorization: Bearer YOUR_ACCESS_TOKEN
-#      Accept: application/json, text/event-stream
-```
-
-## OAuth Endpoints
-
-- `GET /authorize` - Authorization endpoint
-- `POST /token` - Token exchange endpoint
-- `GET /.well-known/oauth-authorization-server` - OAuth metadata
-
-## Common Issues
-
-1. **401 Unauthorized**: Make sure you're using the same secret key for both server and client
-2. **404 Not Found**: Use `/authorize` not `/auth/authorize`
-3. **Token Invalid**: Tokens don't persist across server restarts with basic provider
-
-## Documentation
-
-- [OAuth Authentication Guide](docs/OAuth%20Authentication%20Guide.md) - Complete setup guide
-- [Supabase OAuth Setup](docs/Supabase%20OAuth%20Setup.md) - Production deployment
-- [External OAuth Providers](docs/External%20OAuth%20Providers.md) - GitHub, Google integration

CHANGELOG.md

@@ -1,80 +1,529 @@
 # CHANGELOG
 
-
-## v0.13.0 (2025-06-03)
+## v0.14.0 (2025-06-26)
 
 ### 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
+- **Docker Container Registry Migration** - Switch from Docker Hub to GitHub Container Registry for better security and integration  
+  ([`616c1f0`](https://github.com/basicmachines-co/basic-memory/commit/616c1f0710da59c7098a5f4843d4f017877ff7b2))
+  - Automated Docker image publishing via GitHub Actions CI/CD pipeline
+  - Enhanced container security with GitHub's integrated vulnerability scanning
+  - Streamlined container deployment workflow for production environments
 
-- **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
+- **Enhanced Search Documentation** - Comprehensive search syntax examples for improved user experience
+  ([`a589f8b`](https://github.com/basicmachines-co/basic-memory/commit/a589f8b894e78cce01eb25656856cfea8785fbbf))
+  - Detailed examples for Boolean search operators (AND, OR, NOT)
+  - Advanced search patterns including phrase matching and field-specific queries
+  - User-friendly documentation for complex search scenarios
 
-- **Smart File Management** - Move notes with database consistency and search reindexing
-  ([`9fb931c`](https://github.com/basicmachines-co/basic-memory/commit/9fb931c))
-  - `move_note` tool with rollback protection
-  - Automatic folder creation and permalink updates
-  - Full database consistency maintenance
-
-- **Enhanced Search Capabilities** - Frontmatter tags now searchable, improved content discovery
-  ([`3f5368e`](https://github.com/basicmachines-co/basic-memory/commit/3f5368e))
-  - YAML frontmatter tag indexing
-  - Improved FTS5 search functionality
-  - Project-scoped search operations
-
-- **Production Features** - OAuth authentication, development builds, comprehensive testing
-  ([`5f8d945`](https://github.com/basicmachines-co/basic-memory/commit/5f8d945))
-  - Development build automation
-  - MCP integration testing framework
-  - Enhanced CI/CD pipeline
+- **Cross-Project File Management** - Intelligent move operations with project boundary detection
+  ([`db5ef7d`](https://github.com/basicmachines-co/basic-memory/commit/db5ef7d35cc0894309c7a57b5741c9dd978526d4))
+  - Automatic detection of cross-project move attempts with helpful guidance
+  - Clear error messages when attempting unsupported cross-project operations
 
 ### Bug Fixes
 
-- **#118**: Fix YAML tag formatting to follow standard specification
-  ([`2dc7e27`](https://github.com/basicmachines-co/basic-memory/commit/2dc7e27))
+- **#184**: Preserve permalinks when editing notes without frontmatter permalinks
+  ([`c2f4b63`](https://github.com/basicmachines-co/basic-memory/commit/c2f4b632cf04921b1a3c2f0d43831b80c519cb31))
+  - Fix permalink preservation during note editing operations
+  - Ensure consistent permalink handling across different note formats
+  - Maintain note identity and searchability during incremental edits
 
-- **#110**: Make --project flag work consistently across CLI commands
-  ([`02dd91a`](https://github.com/basicmachines-co/basic-memory/commit/02dd91a))
+- **#183**: Implement project-specific sync status checks for MCP tools
+  ([`12b5152`](https://github.com/basicmachines-co/basic-memory/commit/12b51522bc953fca117fc5bc01fcb29c6ca7e13c))
+  - Fix sync status reporting to correctly reflect current project state
+  - Resolve inconsistencies where sync status showed global instead of project-specific information
+  - Improve project isolation for sync operations and status reporting
 
-- **#93**: Respect custom permalinks in frontmatter for write_note
-  ([`6b6fd76`](https://github.com/basicmachines-co/basic-memory/commit/6b6fd76))
+- **#180**: Handle Boolean search syntax with hyphenated terms
+  ([`546e3cd`](https://github.com/basicmachines-co/basic-memory/commit/546e3cd8db98b74f746749d41887f8a213cd0b11))
+  - Fix search parsing issues with hyphenated terms in Boolean queries
+  - Improve search query tokenization for complex term structures
+  - Enhanced search reliability for technical documentation and multi-word concepts
 
-- Fix list_directory path display to not include leading slash
-  ([`6057126`](https://github.com/basicmachines-co/basic-memory/commit/6057126))
+- **#174**: Respect BASIC_MEMORY_HOME environment variable in Docker containers
+  ([`9f1db23`](https://github.com/basicmachines-co/basic-memory/commit/9f1db23c78d4648e2c242ad1ee27eed85e3f3b5d))
+  - Fix Docker container configuration to properly honor custom home directory settings
+  - Improve containerized deployment flexibility with environment variable support
+  - Ensure consistent behavior between local and containerized installations
+
+- **#168**: Scope entity queries by project_id in upsert_entity method
+  ([`2a3adc1`](https://github.com/basicmachines-co/basic-memory/commit/2a3adc109a3e4d7ccd65cae4abf63d9bb2338326))
+  - Fix entity isolation issues in multi-project setups
+  - Prevent cross-project entity conflicts during database operations
+  - Strengthen project boundary enforcement at the database level
+
+- **#166**: Handle None from_entity in Context API RelationSummary
+  ([`8a065c3`](https://github.com/basicmachines-co/basic-memory/commit/8a065c32f4e41613207d29aafc952a56e3a52241))
+  - Fix null pointer exceptions in relation processing
+  - Improve error handling for incomplete relation data
+  - Enhanced stability for knowledge graph traversal operations
+
+- **#164**: Remove log level configuration from mcp_server.run()
+  ([`224e4bf`](https://github.com/basicmachines-co/basic-memory/commit/224e4bf9e4438c44a82ffc21bd1a282fe9087690))
+  - Simplify MCP server startup by removing redundant log level settings
+  - Fix potential logging configuration conflicts
+  - Streamline server initialization process
+
+- **#162**: Ensure permalinks are generated for entities with null permalinks during move operations
+  ([`f506507`](https://github.com/basicmachines-co/basic-memory/commit/f50650763dbd4322c132e4bdc959ce4bf074374b))
+  - Fix move operations for entities without existing permalinks
+  - Automatic permalink generation during file move operations
+  - Maintain database consistency during file reorganization
 
 ### Technical Improvements
 
-- **Unified Database Architecture** - Single app-level database for better performance
-  - Migration from per-project databases to unified structure
-  - Project isolation with foreign key relationships
-  - Optimized queries and reduced file I/O
+- **Comprehensive Test Coverage** - Extensive test suites for new features and edge cases
+  - Enhanced test coverage for project-specific sync status functionality
+  - Additional test scenarios for search syntax validation and edge cases
+  - Integration tests for Docker CI workflow and container publishing
+  - Comprehensive move operations testing with project boundary validation
 
-- **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
+- **Docker CI/CD Pipeline** - Production-ready automated container publishing
+  ([`74847cc`](https://github.com/basicmachines-co/basic-memory/commit/74847cc3807b0c6ed511e0d83e0d560e9f07ec44))
+  - Automated Docker image building and publishing on release
+  - Multi-architecture container support for AMD64 and ARM64 platforms
+  - Integrated security scanning and vulnerability assessments
+  - Streamlined deployment pipeline for production environments
+
+- **Release Process Improvements** - Enhanced automation and quality gates
+  ([`a52ce1c`](https://github.com/basicmachines-co/basic-memory/commit/a52ce1c8605ec2cd450d1f909154172cbc30faa2))
+  - Homebrew formula updates limited to stable releases only
+  - Improved release automation with better quality control
+  - Enhanced CI/CD pipeline reliability and error handling
+
+- **Code Quality Enhancements** - Improved error handling and validation
+  - Better null safety in entity and relation processing
+  - Enhanced project isolation validation throughout the codebase
+  - Improved error messages and user guidance for edge cases
+  - Strengthened database consistency guarantees across operations
+
+### Infrastructure
+
+- **GitHub Container Registry Integration** - Modern container infrastructure
+  - Migration from Docker Hub to GitHub Container Registry (ghcr.io)
+  - Improved security with integrated vulnerability scanning
+  - Better integration with GitHub-based development workflow
+  - Enhanced container versioning and artifact management
+
+- **Enhanced CI/CD Workflows** - Robust automated testing and deployment
+  - Automated Docker image publishing on releases
+  - Comprehensive test coverage validation before deployment
+  - Multi-platform container building and publishing
+  - Integration with GitHub's security and monitoring tools
+
+### Migration Guide
+
+This release includes several behind-the-scenes improvements and fixes. All changes are backward compatible:
+
+- **Docker Users**: Container images now served from `ghcr.io/basicmachines-co/basic-memory` instead of Docker Hub
+- **Search Users**: Enhanced search syntax handling - existing queries continue to work unchanged
+- **Multi-Project Users**: Improved project isolation - all existing projects remain fully functional
+- **All Users**: Enhanced stability and error handling - no breaking changes to existing workflows
+
+### Installation
+
+```bash
+# Latest stable release
+uv tool install basic-memory
+
+# Update existing installation  
+uv tool upgrade basic-memory
+
+# Docker (new registry)
+docker pull ghcr.io/basicmachines-co/basic-memory:latest
+```
+
+## v0.13.7 (2025-06-19)
+
+### Bug Fixes
+
+- **Homebrew Integration** - Automatic Homebrew formula updates
+- **Documentation** - Add git sign-off reminder to development guide
+
+## v0.13.6 (2025-06-18)
+
+### Bug Fixes
+
+- **Custom Entity Types** - Support for custom entity types in write_note
+  ([`7789864`](https://github.com/basicmachines-co/basic-memory/commit/77898644933589c2da9bdd60571d54137a5309ed))
+  - Fixed `entity_type` parameter for `write_note` MCP tool to respect value passed in
+  - Frontmatter `type` field automatically respected when no explicit parameter provided
+  - Maintains backward compatibility with default "note" type
+
+- **#139**: Fix "UNIQUE constraint failed: entity.permalink" database error
+  ([`c6215fd`](https://github.com/basicmachines-co/basic-memory/commit/c6215fd819f9564ead91cf3a950f855241446096))
+  - Implement SQLAlchemy UPSERT strategy to handle permalink conflicts gracefully
+  - Eliminates crashes when creating notes with existing titles in same folders
+  - Seamlessly updates existing entities instead of failing with constraint errors
+
+- **Database Migration Performance** - Eliminate redundant migration initialization
+  ([`84d2aaf`](https://github.com/basicmachines-co/basic-memory/commit/84d2aaf6414dd083af4b0df73f6c8139b63468f6))
+  - Fix duplicate migration calls that slowed system startup
+  - Improve performance with multiple projects (tested with 28+ projects)
+  - Add migration deduplication safeguards with comprehensive test coverage
+
+- **User Experience** - Correct spelling error in continue_conversation prompt
+  ([`b4c26a6`](https://github.com/basicmachines-co/basic-memory/commit/b4c26a613379e6f2ba655efe3d7d8d40c27999e5))
+  - Fix "Chose a folder" → "Choose a folder" in MCP prompt instructions
+  - Improve grammar and clarity in user-facing prompt text
 
 ### Documentation
 
-- Add comprehensive testing documentation (TESTING.md)
-- Update project management guides (PROJECT_MANAGEMENT.md)
-- Enhanced note editing documentation (EDIT_NOTE.md)
-- Updated release workflow documentation
+- **Website Updates** - Add new website and community links to README
+  ([`3fdce68`](https://github.com/basicmachines-co/basic-memory/commit/3fdce683d7ad8b6f4855d7138d5ff2136d4c07bc))
 
-### Breaking Changes
+- **Project Documentation** - Update README.md and CLAUDE.md with latest project information
+  ([`782cb2d`](https://github.com/basicmachines-co/basic-memory/commit/782cb2df28803482d209135a054e67cc32d7363e))
+
+### Technical Improvements
+
+- **Comprehensive Test Coverage** - Add extensive test suites for new features
+  - Custom entity type validation with 8 new test scenarios
+  - UPSERT behavior testing with edge case coverage
+  - Migration deduplication testing with 6 test scenarios
+  - Database constraint handling validation
+
+- **Code Quality** - Enhanced error handling and validation
+  - Improved SQLAlchemy patterns with modern UPSERT operations
+  - Better conflict resolution strategies for entity management
+  - Strengthened database consistency guarantees
+
+### Performance
+
+- **Database Operations** - Faster startup and improved scalability
+  - Reduced migration overhead for multi-project setups
+  - Optimized conflict resolution for entity creation
+  - Enhanced performance with growing knowledge bases
+
+### Migration Guide
+
+This release includes automatic database improvements. No manual migration required:
+
+- Existing notes and entity types continue working unchanged
+- New `entity_type` parameter is optional and backward compatible
+- Database performance improvements apply automatically
+- All existing MCP tool behavior preserved
+
+### Installation
+
+```bash
+# Latest stable release
+uv tool install basic-memory
+
+# Update existing installation
+uv tool upgrade basic-memory
+```
+
+## v0.13.5 (2025-06-11)
+
+### Bug Fixes
+
+- **MCP Tools**: Renamed `create_project` tool to `create_memory_project` for namespace isolation
+- **Namespace**: Continued namespace isolation effort to prevent conflicts with other MCP servers
+
+### Changes
+
+- Tool functionality remains identical - only the name changed from `create_project` to `create_memory_project`
+- All integration tests updated to use the new tool name
+- Completes namespace isolation for project management tools alongside `list_memory_projects`
+
+## v0.13.4 (2025-06-11)
+
+### Bug Fixes
+
+- **MCP Tools**: Renamed `list_projects` tool to `list_memory_projects` to avoid naming conflicts with other MCP servers
+- **Namespace**: Improved tool naming specificity for better MCP server integration and isolation
+
+### Changes
+
+- Tool functionality remains identical - only the name changed from `list_projects` to `list_memory_projects`
+- All integration tests updated to use the new tool name
+- Better namespace isolation for Basic Memory MCP tools
+
+## v0.13.3 (2025-06-11)
+
+### Bug Fixes
+
+- **Projects**: Fixed case-insensitive project switching where switching succeeded but subsequent operations failed due to session state inconsistency
+- **Config**: Enhanced config manager with case-insensitive project lookup using permalink-based matching
+- **MCP Tools**: Updated project management tools to store canonical project names from database instead of user input
+- **API**: Improved project service to handle both name and permalink lookups consistently
+
+### Technical Improvements
+
+- Added comprehensive case-insensitive project switching test coverage with 5 new integration test scenarios
+- Fixed permalink generation inconsistencies where different case inputs could generate different permalinks
+- Enhanced project URL construction to use permalinks consistently across all API calls
+- Improved error handling and session state management for project operations
+
+### Changes
+
+- Project switching now preserves canonical project names from database in session state
+- All project operations use permalink-based lookups for case-insensitive matching
+- Enhanced test coverage ensures reliable case-insensitive project operations
+
+## v0.13.2 (2025-06-11)
+
+### Features
+
+- **Release Management**: Added automated release management system with version control in `__init__.py`
+- **Automation**: Implemented justfile targets for `release` and `beta` commands with comprehensive quality gates
+- **CI/CD**: Enhanced release process with automatic version updates, git tagging, and GitHub release creation
+
+### Development Experience
+
+- Added `.claude/commands/release/` directory with automation documentation
+- Implemented release validation including lint, type-check, and test execution
+- Streamlined release workflow from manual process to single-command automation
+
+### Technical Improvements
+
+- Updated package version management to use actual version numbers instead of dynamic versioning
+- Added release process documentation and command references
+- Enhanced justfile with comprehensive release automation targets
+
+## v0.13.1 (2025-06-11)
+
+### Bug Fixes
+
+- **CLI**: Fixed  `basic-memory project` project management commands that were  not working in v0.13.0 (#129)
+- **Projects**: Resolved case sensitivity issues when switching between projects that caused "Project not found" errors (#127)
+- **API**: Standardized CLI project command endpoints and improved error handling
+- **Core**: Implemented consistent project name handling using permalinks to avoid case-related conflicts
+
+### Changes
+
+- Renamed `basic-memory project sync` command to `basic-memory project sync-config` for clarity
+- Improved project switching reliability across different case variations
+- Removed redundant server status messages from CLI error outputs
+
+## v0.13.0 (2025-06-11)
+
+### Overview
+
+Basic Memory v0.13.0 is a **major release** that transforms Basic Memory into a true multi-project knowledge management system. This release introduces fluid project switching, advanced note editing capabilities, robust file management, and production-ready OAuth authentication - all while maintaining full backward compatibility.
+
+**What's New for Users:**
+- 🎯 **Switch between projects instantly** during conversations with Claude
+- ✏️ **Edit notes incrementally** without rewriting entire documents
+- 📁 **Move and organize notes** with full database consistency
+- 📖 **View notes as formatted artifacts** for better readability in Claude Desktop
+- 🔍 **Search frontmatter tags** to discover content more easily
+- 🔐 **OAuth authentication** for secure remote access
+- ⚡ **Development builds** automatically published for beta testing
+
+**Key v0.13.0 Accomplishments:**
+- ✅ **Complete Project Management System** - Project switching and project-specific operations
+- ✅ **Advanced Note Editing** - Incremental editing with append, prepend, find/replace, and section operations  
+- ✅ **View Notes as Artifacts in Claude Desktop/Web** - Use the view_note tool to view a note as an artifact
+- ✅ **File Management System** - Full move operations with database consistency and rollback protection
+- ✅ **Enhanced Search Capabilities** - Frontmatter tags now searchable, improved content discoverability
+- ✅ **Unified Database Architecture** - Single app-level database for better performance and project management
+
+### Major Features
+
+#### 1. Multiple Project Management 
+
+**Switch between projects instantly during conversations:**
+
+```
+💬 "What projects do I have?"
+🤖 Available projects:
+   • main (current, default)
+   • work-notes
+   • personal-journal
+   • code-snippets
+
+💬 "Switch to work-notes"
+🤖 ✓ Switched to work-notes project
+   
+   Project Summary:
+   • 47 entities
+   • 125 observations  
+   • 23 relations
+
+💬 "What did I work on yesterday?"
+🤖 [Shows recent activity from work-notes project]
+```
+
+**Key Capabilities:**
+- **Instant Project Switching**: Change project context mid-conversation without restart
+- **Project-Specific Operations**: Operations work within the currently active project context
+- **Project Discovery**: List all available projects with status indicators
+- **Session Context**: Maintains active project throughout conversation
+- **Backward Compatibility**: Existing single-project setups continue to work seamlessly
+
+#### 2. Advanced Note Editing 
+
+**Edit notes incrementally without rewriting entire documents:**
+
+```python
+# Append new sections to existing notes
+edit_note("project-planning", "append", "\n## New Requirements\n- Feature X\n- Feature Y")
+
+# Prepend timestamps to meeting notes
+edit_note("meeting-notes", "prepend", "## 2025-05-27 Update\n- Progress update...")
+
+# Replace specific sections under headers
+edit_note("api-spec", "replace_section", "New implementation details", section="## Implementation")
+
+# Find and replace with validation
+edit_note("config", "find_replace", "v0.13.0", find_text="v0.12.0", expected_replacements=2)
+```
+
+**Key Capabilities:**
+- **Append Operations**: Add content to end of notes (most common use case)
+- **Prepend Operations**: Add content to beginning of notes
+- **Section Replacement**: Replace content under specific markdown headers
+- **Find & Replace**: Simple text replacements with occurrence counting
+- **Smart Error Handling**: Helpful guidance when operations fail
+- **Project Context**: Works within the active project with session awareness
+
+#### 3. Smart File Management
+
+**Move and organize notes:**
+
+```python
+# Simple moves with automatic folder creation
+move_note("my-note", "work/projects/my-note.md")
+
+# Organize within the active project
+move_note("shared-doc", "archive/old-docs/shared-doc.md")
+
+# Rename operations
+move_note("old-name", "same-folder/new-name.md")
+```
+
+**Key Capabilities:**
+- **Database Consistency**: Updates file paths, permalinks, and checksums automatically
+- **Search Reindexing**: Maintains search functionality after moves
+- **Folder Creation**: Automatically creates destination directories
+- **Project Isolation**: Operates within the currently active project
+- **Link Preservation**: Maintains internal links and references
+
+#### 4. Enhanced Search & Discovery 
+
+**Find content more easily with improved search capabilities:**
+
+- **Frontmatter Tag Search**: Tags from YAML frontmatter are now indexed and searchable
+- **Improved Content Discovery**: Search across titles, content, tags, and metadata
+- **Project-Scoped Search**: Search within the currently active project
+- **Better Search Quality**: Enhanced FTS5 indexing with tag content inclusion
+
+**Example:**
+```yaml
+---
+title: Coffee Brewing Methods
+tags: [coffee, brewing, equipment]
+---
+```
+Now searchable by: "coffee", "brewing", "equipment", or "Coffee Brewing Methods"
+
+#### 5. Unified Database Architecture 
+
+**Single app-level database for better performance and project management:**
+
+- **Migration from Per-Project DBs**: Moved from multiple SQLite files to single app database
+- **Project Isolation**: Proper data separation with project_id foreign keys
+- **Better Performance**: Optimized queries and reduced file I/O
+
+### Complete MCP Tool Suite
+
+#### New Project Management Tools
+- **`list_projects()`** - Discover and list all available projects with status
+- **`switch_project(project_name)`** - Change active project context during conversations
+- **`get_current_project()`** - Show currently active project with statistics
+- **`set_default_project(project_name)`** - Update default project configuration
+- **`sync_status()`** - Check file synchronization status and background operations
+
+#### New Note Operations Tools
+- **`edit_note()`** - Incremental note editing (append, prepend, find/replace, section replace)
+- **`move_note()`** - Move notes with database consistency and search reindexing
+- **`view_note()`** - Display notes as formatted artifacts for better readability in Claude Desktop
+
+#### Enhanced Existing Tools
+All existing tools now support:
+- **Session context awareness** (operates within the currently active project)
+- **Enhanced error messages** with project context metadata
+- **Improved response formatting** with project information footers
+- **Project isolation** ensures operations stay within the correct project boundaries
+
+
+### User Experience Improvements
+
+#### Installation Options
+
+**Multiple ways to install and test Basic Memory:**
+
+```bash
+# Stable release
+uv tool install basic-memory
+
+# Beta/pre-releases
+uv tool install basic-memory --pre
+```
+
+
+#### Bug Fixes & Quality Improvements
+
+**Major issues resolved in v0.13.0:**
+
+- **#118**: Fixed YAML tag formatting to follow standard specification
+- **#110**: Fixed `--project` flag consistency across all CLI commands
+- **#107**: Fixed write_note update failures with existing notes
+- **#93**: Fixed custom permalink handling in frontmatter
+- **#52**: Enhanced search capabilities with frontmatter tag indexing
+- **FTS5 Search**: Fixed special character handling in search queries
+- **Error Handling**: Improved error messages and validation across all tools
+
+### Breaking Changes & Migration
+
+#### For Existing Users
+
+**Automatic Migration**: First run will automatically migrate existing data to the new unified database structure. No manual action required.
+
+**What Changes:**
+- Database location: Moved to `~/.basic-memory/memory.db` (unified across projects)
+- Configuration: Projects defined in `~/.basic-memory/config.json` are synced with database
+
+**What Stays the Same:**
+- All existing notes and data remain unchanged
+- Default project behavior maintained for single-project users
+- All existing MCP tools continue to work without modification
+
+### Documentation & Resources
+
+#### New Documentation
+- [Project Management Guide](docs/Project%20Management.md) - Multi-project workflows
+- [Note Editing Guide](docs/Note%20Editing.md) - Advanced editing techniques
+
+#### Updated Documentation
+- [README.md](README.md) - Installation options and beta build instructions
+- [CONTRIBUTING.md](CONTRIBUTING.md) - Release process and version management
+- [CLAUDE.md](CLAUDE.md) - Development workflow and CI/CD documentation
+- [Claude.ai Integration](docs/Claude.ai%20Integration.md) - Updated MCP tool examples
+
+#### Quick Start Examples
+
+**Project Switching:**
+```
+💬 "Switch to my work project and show recent activity"
+🤖 [Calls switch_project("work") then recent_activity()]
+```
+
+**Note Editing:**
+```
+💬 "Add a section about deployment to my API docs"
+🤖 [Calls edit_note("api-docs", "append", "## Deployment\n...")]
+```
+
+**File Organization:**
+```
+💬 "Move my old meeting notes to the archive folder"
+🤖 [Calls move_note("meeting-notes", "archive/old-meetings.md")]
+```
 
-- **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
 
 
 ## v0.12.3 (2025-04-17)
@@ -861,4 +1310,4 @@ Co-authored-by: phernandez <phernandez@basicmachines.co>
 ### Chores
 
 - Remove basic-foundation src ref in pyproject.toml
-  ([`29fce8b`](https://github.com/basicmachines-co/basic-memory/commit/29fce8b0b922d54d7799bf2534107ee6cfb961b8))
+  ([`29fce8b`](https://github.com/basicmachines-co/basic-memory/commit/29fce8b0b922d54d7799bf2534107ee6cfb961b8))

CLAUDE.md

@@ -14,15 +14,15 @@ 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 tests: `uv run pytest -p pytest_mock -v` or `just test`
 - 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`
+- Lint: `just lint` or `ruff check . --fix`
+- Type check: `just type-check` or `uv run pyright`
+- Format: `just format` or `uv run ruff format .`
+- Run all code checks: `just check` (runs lint, format, type-check, test)
+- Create db migration: `just migration "Your migration message"`
+- Run development MCP Inspector: `just run-inspector`
 
 ### Code Style Guidelines
 
@@ -97,15 +97,26 @@ See the [README.md](README.md) file for a project overview.
 
   **Content Management:**
     - `write_note(title, content, folder, tags)` - Create/update markdown notes with semantic observations and relations
-    - `read_note(identifier, page, page_size)` - Read notes by title, permalink, or memory:// URL with knowledge graph
-      awareness
-    - `read_file(path)` - Read raw file content (text, images, binaries) without knowledge graph processing
+    - `read_note(identifier, page, page_size)` - Read notes by title, permalink, or memory:// URL with knowledge graph awareness
+    - `edit_note(identifier, operation, content)` - Edit notes incrementally (append, prepend, find/replace, section replace)
+    - `move_note(identifier, destination_path)` - Move notes with database consistency and search reindexing
+    - `view_note(identifier)` - Display notes as formatted artifacts for better readability in Claude Desktop
+    - `read_content(path)` - Read raw file content (text, images, binaries) without knowledge graph processing
+    - `delete_note(identifier)` - Delete notes from knowledge base
+
+  **Project Management:**
+    - `list_memory_projects()` - List all available projects with status indicators
+    - `switch_project(project_name)` - Switch to different project context during conversations
+    - `get_current_project()` - Show currently active project with statistics
+    - `create_memory_project(name, path, set_default)` - Create new Basic Memory projects
+    - `delete_project(name)` - Delete projects from configuration and database
+    - `set_default_project(name)` - Set default project in config
+    - `sync_status()` - Check file synchronization status and background operations
 
   **Knowledge Graph Navigation:**
-    - `build_context(url, depth, timeframe)` - Navigate the knowledge graph via memory:// URLs for conversation
-      continuity
-    - `recent_activity(type, depth, timeframe)` - Get recently updated information with specified timeframe (e.g., "
-      1d", "1 week")
+    - `build_context(url, depth, timeframe)` - Navigate the knowledge graph via memory:// URLs for conversation continuity
+    - `recent_activity(type, depth, timeframe)` - Get recently updated information with specified timeframe (e.g., "1d", "1 week")
+    - `list_directory(dir_name, depth, file_name_glob)` - List directory contents with filtering and depth control
 
   **Search & Discovery:**
     - `search_notes(query, page, page_size)` - Full-text search across all content with filtering options
@@ -212,13 +223,35 @@ Basic Memory uses `uv-dynamic-versioning` for automatic version management based
 - Users install with: `pip install basic-memory --pre`
 - Use for milestone testing before stable release
 
-#### Stable Releases (Manual)
+#### Stable Releases (Automated)
+- Use the automated release system: `just release v0.13.0`
+- Includes comprehensive quality checks (lint, format, type-check, tests)
+- Automatically updates version in `__init__.py`
+- Creates git tag and pushes to GitHub
+- Triggers GitHub Actions workflow for:
+  - PyPI publication
+  - Homebrew formula update (requires HOMEBREW_TOKEN secret)
+
+**Manual method (legacy):**
 - Create version tag: `git tag v0.13.0 && git push origin v0.13.0`
-- Automatically builds, creates GitHub release, and publishes to PyPI
-- Users install with: `pip install basic-memory`
+
+#### Homebrew Formula Updates
+- Automatically triggered after successful PyPI release for **stable releases only**
+- **Stable releases** (e.g., v0.13.7) automatically update the main `basic-memory` formula
+- **Pre-releases** (dev/beta/rc) are NOT automatically updated - users must specify version manually
+- Updates formula in `basicmachines-co/homebrew-basic-memory` repo
+- Requires `HOMEBREW_TOKEN` secret in GitHub repository settings:
+  - Create a fine-grained Personal Access Token with `Contents: Read and Write` and `Actions: Read` scopes on `basicmachines-co/homebrew-basic-memory`
+  - Add as repository secret named `HOMEBREW_TOKEN` in `basicmachines-co/basic-memory`
+- Formula updates include new version URL and SHA256 checksum
 
 ### For Development
-- No manual version bumping required
-- Versions automatically derived from git tags
-- `pyproject.toml` uses `dynamic = ["version"]`
-- `__init__.py` dynamically reads version from package metadata
+- **Automated releases**: Use `just release v0.13.x` for stable releases and `just beta v0.13.0b1` for beta releases
+- **Quality gates**: All releases require passing lint, format, type-check, and test suites
+- **Version management**: Versions automatically derived from git tags via `uv-dynamic-versioning`
+- **Configuration**: `pyproject.toml` uses `dynamic = ["version"]`
+- **Release automation**: `__init__.py` updated automatically during release process
+- **CI/CD**: GitHub Actions handles building and PyPI publication
+
+## Development Notes
+- make sure you sign off on commits

CONTRIBUTING.md

@@ -15,8 +15,8 @@ project and how to get started as a developer.
 
 2. **Install Dependencies**:
    ```bash
-   # Using make (recommended)
-   make install
+   # Using just (recommended)
+   just install
    
    # Or using uv
    uv install -e ".[dev]"
@@ -25,10 +25,12 @@ project and how to get started as a developer.
    pip install -e ".[dev]"
    ```
 
+   > **Note**: Basic Memory uses [just](https://just.systems) as a modern command runner. Install with `brew install just` or `cargo install just`.
+
 3. **Run the Tests**:
    ```bash
    # Run all tests
-   make test
+   just test
    # or
    uv run pytest -p pytest_mock -v
    
@@ -49,16 +51,16 @@ project and how to get started as a developer.
 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.
 

Dockerfile

@@ -1,16 +1,32 @@
-# Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile
-FROM python:3.12-slim
+FROM python:3.12-slim-bookworm
 
+# Copy uv from official image
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+# Set environment variables
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+
+# 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
 
-# Copy the project files
-COPY . .
+# Create data directory
+RUN mkdir -p /app/data
 
-# Install pip and build dependencies
-RUN pip install --upgrade pip \
-&& pip install . --no-cache-dir --ignore-installed
+# Set default data directory and add venv to PATH
+ENV BASIC_MEMORY_HOME=/app/data \
+    PATH="/app/.venv/bin:$PATH"
 
-# Expose port if necessary (e.g., uv might use a port, but MCP over stdio so not needed here)
+# Expose port
+EXPOSE 8000
 
-# Use the basic-memory entrypoint to run the MCP server
-CMD ["basic-memory", "mcp"]
+# 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,59 +0,0 @@
-.PHONY: install test test-module lint clean format type-check installer-mac installer-win check test-int
-
-install:
-	pip install -e ".[dev]"
-
-test-unit:
-	uv run pytest -p pytest_mock -v
-
-test-int:
-	uv run pytest -p pytest_mock -v --no-cov test-int
-
-test: test-unit test-int
-
-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:
-	npx @modelcontextprotocol/inspector
-
-# 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

@@ -13,8 +13,11 @@ Basic Memory lets you build persistent knowledge through natural conversations w
 Claude, while keeping everything in simple Markdown files on your computer. It uses the Model Context Protocol (MCP) to
 enable any compatible LLM to read and write to your local knowledge base.
 
-- Website: https://basicmachines.co
+- Website: https://basicmemory.com
+- Company: https://basicmachines.co
 - Documentation: https://memory.basicmachines.co
+- Discord: https://discord.gg/tyvKNccgqN
+- YouTube: https://www.youtube.com/@basicmachines-co
 
 ## Pick up your conversation right where you left off
 
@@ -30,6 +33,10 @@ https://github.com/user-attachments/assets/a55d8238-8dd0-454a-be4c-8860dbbd0ddc
 # Install with uv (recommended)
 uv tool install basic-memory
 
+# or with Homebrew
+brew tap basicmachines-co/basic-memory
+brew install basic-memory
+
 # Configure Claude Desktop (edit ~/Library/Application Support/Claude/claude_desktop_config.json)
 # Add this to your config:
 {
@@ -61,8 +68,7 @@ Memory for Claude Desktop:
 npx -y @smithery/cli install @basicmachines-co/basic-memory --client claude
 ```
 
-This installs and configures Basic Memory without requiring manual edits to the Claude Desktop configuration file. The
-Smithery server hosts the MCP server component, while your data remains stored locally as Markdown files.
+This installs and configures Basic Memory without requiring manual edits to the Claude Desktop configuration file. Note: The Smithery installation uses their hosted MCP server, while your data remains stored locally as Markdown files.
 
 ### Glama.ai
 
@@ -153,7 +159,8 @@ The note embeds semantic content and links to other topics via simple Markdown f
 
 3. You see this file on your computer in real time in the current project directory (default `~/$HOME/basic-memory`).
 
-- Realtime sync is enabled by default with the v0.12.0 version
+- Realtime sync is enabled by default starting with v0.12.0
+- Project switching during conversations is supported starting with v0.13.0
 
 4. In a chat with the LLM, you can reference a topic:
 
@@ -351,10 +358,20 @@ Basic Memory will sync the files in your project in real time if you make manual
 ```
 write_note(title, content, folder, tags) - Create or update notes
 read_note(identifier, page, page_size) - Read notes by title or permalink
+edit_note(identifier, operation, content) - Edit notes incrementally (append, prepend, find/replace)
+move_note(identifier, destination_path) - Move notes with database consistency
+view_note(identifier) - Display notes as formatted artifacts for better readability
 build_context(url, depth, timeframe) - Navigate knowledge graph via memory:// URLs
 search_notes(query, page, page_size) - Search across your knowledge base
 recent_activity(type, depth, timeframe) - Find recently updated information
 canvas(nodes, edges, title, folder) - Generate knowledge visualizations
+list_memory_projects() - List all available projects with status
+switch_project(project_name) - Switch to different project context
+get_current_project() - Show current project and statistics
+create_memory_project(name, path, set_default) - Create new projects
+delete_project(name) - Delete projects from configuration
+set_default_project(name) - Set default project
+sync_status() - Check file synchronization status
 ```
 
 5. Example prompts to try:
@@ -365,6 +382,10 @@ canvas(nodes, edges, title, folder) - Generate knowledge visualizations
 "Create a canvas visualization of my project components"
 "Read my notes on the authentication system"
 "What have I been working on in the past week?"
+"Switch to my work-notes project"
+"List all my available projects"
+"Edit my coffee brewing note to add a new technique"
+"Move my old meeting notes to the archive folder"
 ```
 
 ## Futher info
@@ -394,6 +415,31 @@ Development versions are automatically published on every commit to main with ve
 pip install basic-memory --pre --force-reinstall
 ```
 
+### Docker
+
+Run Basic Memory in a container with volume mounting for your Obsidian vault:
+
+```bash
+# Clone and start with Docker Compose
+git clone https://github.com/basicmachines-co/basic-memory.git
+cd basic-memory
+
+# Edit docker-compose.yml to point to your Obsidian vault
+# Then start the container
+docker-compose up -d
+```
+
+Or use Docker directly:
+```bash
+docker run -d \
+  --name basic-memory-server \
+  -v /path/to/your/obsidian-vault:/data/knowledge:rw \
+  -v basic-memory-config:/root/.basic-memory:rw \
+  ghcr.io/basicmachines-co/basic-memory:latest
+```
+
+See [Docker Setup Guide](docs/Docker.md) for detailed configuration options, multiple project setup, and integration examples.
+
 ## License
 
 AGPL-3.0

RELEASE_NOTES_v0.13.0.md

@@ -1,237 +0,0 @@
-# Release Notes v0.13.0
-
-## Overview
-
-Basic Memory v0.13.0 is a **major release** that transforms Basic Memory into a true multi-project knowledge management system. This release introduces fluid project switching, advanced note editing capabilities, robust file management, and production-ready OAuth authentication - all while maintaining full backward compatibility.
-
-**What's New for Users:**
-- 🎯 **Switch between projects instantly** during conversations with Claude
-- ✏️ **Edit notes incrementally** without rewriting entire documents
-- 📁 **Move and organize notes** with full database consistency
-- 🔍 **Search frontmatter tags** to discover content more easily
-- 🔐 **OAuth authentication** for secure remote access
-- ⚡ **Development builds** automatically published for beta testing
-
-**Key v0.13.0 Accomplishments:**
-- ✅ **Complete Project Management System** - Project switching and project-specific operations
-- ✅ **Advanced Note Editing** - Incremental editing with append, prepend, find/replace, and section operations  
-- ✅ **File Management System** - Full move operations with database consistency and rollback protection
-- ✅ **Enhanced Search Capabilities** - Frontmatter tags now searchable, improved content discoverability
-- ✅ **Unified Database Architecture** - Single app-level database for better performance and project management
-
-## Major Features
-
-### 1. Multiple Project Management 🎯
-
-**Switch between projects instantly during conversations:**
-
-```
-💬 "What projects do I have?"
-🤖 Available projects:
-   • main (current, default)
-   • work-notes
-   • personal-journal
-   • code-snippets
-
-💬 "Switch to work-notes"
-🤖 ✓ Switched to work-notes project
-   
-   Project Summary:
-   • 47 entities
-   • 125 observations  
-   • 23 relations
-
-💬 "What did I work on yesterday?"
-🤖 [Shows recent activity from work-notes project]
-```
-
-**Key Capabilities:**
-- **Instant Project Switching**: Change project context mid-conversation without restart
-- **Project-Specific Operations**: Operations work within the currently active project context
-- **Project Discovery**: List all available projects with status indicators
-- **Session Context**: Maintains active project throughout conversation
-- **Backward Compatibility**: Existing single-project setups continue to work seamlessly
-
-### 2. Advanced Note Editing ✏️
-
-**Edit notes incrementally without rewriting entire documents:**
-
-```python
-# Append new sections to existing notes
-edit_note("project-planning", "append", "\n## New Requirements\n- Feature X\n- Feature Y")
-
-# Prepend timestamps to meeting notes
-edit_note("meeting-notes", "prepend", "## 2025-05-27 Update\n- Progress update...")
-
-# Replace specific sections under headers
-edit_note("api-spec", "replace_section", "New implementation details", section="## Implementation")
-
-# Find and replace with validation
-edit_note("config", "find_replace", "v0.13.0", find_text="v0.12.0", expected_replacements=2)
-```
-
-**Key Capabilities:**
-- **Append Operations**: Add content to end of notes (most common use case)
-- **Prepend Operations**: Add content to beginning of notes
-- **Section Replacement**: Replace content under specific markdown headers
-- **Find & Replace**: Simple text replacements with occurrence counting
-- **Smart Error Handling**: Helpful guidance when operations fail
-- **Project Context**: Works within the active project with session awareness
-
-### 3. Smart File Management 📁
-
-**Move and organize notes:**
-
-```python
-# Simple moves with automatic folder creation
-move_note("my-note", "work/projects/my-note.md")
-
-# Organize within the active project
-move_note("shared-doc", "archive/old-docs/shared-doc.md")
-
-# Rename operations
-move_note("old-name", "same-folder/new-name.md")
-```
-
-**Key Capabilities:**
-- **Database Consistency**: Updates file paths, permalinks, and checksums automatically
-- **Search Reindexing**: Maintains search functionality after moves
-- **Folder Creation**: Automatically creates destination directories
-- **Project Isolation**: Operates within the currently active project
-- **Link Preservation**: Maintains internal links and references
-
-### 4. Enhanced Search & Discovery 🔍
-
-**Find content more easily with improved search capabilities:**
-
-- **Frontmatter Tag Search**: Tags from YAML frontmatter are now indexed and searchable
-- **Improved Content Discovery**: Search across titles, content, tags, and metadata
-- **Project-Scoped Search**: Search within the currently active project
-- **Better Search Quality**: Enhanced FTS5 indexing with tag content inclusion
-
-**Example:**
-```yaml
----
-title: Coffee Brewing Methods
-tags: [coffee, brewing, equipment]
----
-```
-Now searchable by: "coffee", "brewing", "equipment", or "Coffee Brewing Methods"
-
-### 5. Unified Database Architecture 🗄️
-
-**Single app-level database for better performance and project management:**
-
-- **Migration from Per-Project DBs**: Moved from multiple SQLite files to single app database
-- **Project Isolation**: Proper data separation with project_id foreign keys
-- **Better Performance**: Optimized queries and reduced file I/O
-
-## Complete MCP Tool Suite 🛠️
-
-### New Project Management Tools
-- **`list_projects()`** - Discover and list all available projects with status
-- **`switch_project(project_name)`** - Change active project context during conversations
-- **`get_current_project()`** - Show currently active project with statistics
-- **`set_default_project(project_name)`** - Update default project configuration
-
-### New Note Operations Tools
-- **`edit_note()`** - Incremental note editing (append, prepend, find/replace, section replace)
-- **`move_note()`** - Move notes with database consistency and search reindexing
-
-### Enhanced Existing Tools
-All existing tools now support:
-- **Session context awareness** (operates within the currently active project)
-- **Enhanced error messages** with project context metadata
-- **Improved response formatting** with project information footers
-- **Project isolation** ensures operations stay within the correct project boundaries
-
-
-## User Experience Improvements
-
-### Installation Options
-
-**Multiple ways to install and test Basic Memory:**
-
-```bash
-# Stable release
-uv tool install basic-memory
-
-# Beta/pre-releases
-uv tool install basic-memory --pre
-```
-
-
-### Bug Fixes & Quality Improvements
-
-**Major issues resolved in v0.13.0:**
-
-- **#118**: Fixed YAML tag formatting to follow standard specification
-- **#110**: Fixed `--project` flag consistency across all CLI commands
-- **#107**: Fixed write_note update failures with existing notes
-- **#93**: Fixed custom permalink handling in frontmatter
-- **#52**: Enhanced search capabilities with frontmatter tag indexing
-- **FTS5 Search**: Fixed special character handling in search queries
-- **Error Handling**: Improved error messages and validation across all tools
-
-## Breaking Changes & Migration
-
-### For Existing Users
-
-**Automatic Migration**: First run will automatically migrate existing data to the new unified database structure. No manual action required.
-
-**What Changes:**
-- Database location: Moved to `~/.basic-memory/memory.db` (unified across projects)
-- Configuration: Projects defined in `~/.basic-memory/config.json` are synced with database
-
-**What Stays the Same:**
-- All existing notes and data remain unchanged
-- Default project behavior maintained for single-project users
-- All existing MCP tools continue to work without modification
-
-
-
-
-## Documentation & Resources
-
-### New Documentation
-- [Project Management Guide](docs/Project%20Management.md) - Multi-project workflows
-- [Note Editing Guide](docs/Note%20Editing.md) - Advanced editing techniques
-
-### Updated Documentation
-- [README.md](README.md) - Installation options and beta build instructions
-- [CONTRIBUTING.md](CONTRIBUTING.md) - Release process and version management
-- [CLAUDE.md](CLAUDE.md) - Development workflow and CI/CD documentation
-- [Claude.ai Integration](docs/Claude.ai%20Integration.md) - Updated MCP tool examples
-
-### Quick Start Examples
-
-**Project Switching:**
-```
-💬 "Switch to my work project and show recent activity"
-🤖 [Calls switch_project("work") then recent_activity()]
-```
-
-**Note Editing:**
-```
-💬 "Add a section about deployment to my API docs"
-🤖 [Calls edit_note("api-docs", "append", "## Deployment\n...")]
-```
-
-**File Organization:**
-```
-💬 "Move my old meeting notes to the archive folder"
-🤖 [Calls move_note("meeting-notes", "archive/old-meetings.md")]
-```
-
-
-### Getting Updates
-```bash
-# Stable releases
-uv tool upgrade basic-memory
-
-# Beta releases  
-uv tool install basic-memory --pre --force-reinstall
-
-# Latest development
-uv tool install basic-memory --pre --force-reinstall
-```

TESTING.md

@@ -1,337 +0,0 @@
-# Manual Testing Suite for Basic Memory
-
-This document outlines a comprehensive manual testing approach where an AI assistant (Claude) executes real-world usage scenarios using Basic Memory's MCP tools. The unique aspect: **Basic Memory tests itself** - all test observations and results are recorded as notes in a dedicated test project.
-
-## Philosophy
-
-- **Integration over Isolation**: Test the full MCP→API→DB→File stack
-- **Real Usage Patterns**: Creative exploration, not just checklist validation
-- **Self-Documenting**: Use Basic Memory to record all test observations
-- **Living Documentation**: Test results become part of the knowledge base
-
-## Setup Instructions
-
-### 1. Environment Preparation
-
-```bash
-# Ensure latest basic-memory is installed
-pip install --upgrade basic-memory
-
-# Verify MCP server is available
-basic-memory --version
-```
-
-### 2. MCP Integration Setup
-
-**Option A: Claude Desktop Integration**
-```json
-// Add to ~/.config/claude-desktop/claude_desktop_config.json
-// or 
-// .mcp.json
-{
-  "mcpServers": {
-    "basic-memory": {
-      "command": "uv",
-      "args": [
-        "--directory",
-        "/Users/phernandez/dev/basicmachines/basic-memory",
-        "run",
-        "src/basic_memory/cli/main.py",
-        "mcp"
-      ]
-    }
-  }
-}
-```
-
-**Option B: Claude Code MCP**
-```bash
-claude mcp add basic-memory basic-memory mcp
-```
-
-### 3. Test Project Creation
-
-During testing, create a dedicated test project:
-```
-- Project name: "basic-memory-testing"
-- Location: ~/basic-memory-testing
-- Purpose: Contains all test observations and results
-```
-
-## Testing Categories
-
-### Phase 1: Core Functionality Validation
-
-**Objective**: Verify all basic operations work correctly
-
-**Test Areas:**
-- [ ] **Note Creation**: Various content types, structures, frontmatter
-- [ ] **Note Reading**: By title, path, memory:// URLs, non-existent notes
-- [ ] **Search Operations**: Simple queries, boolean operators, tag searches
-- [ ] **Context Building**: Different depths, timeframes, relation traversal
-- [ ] **Recent Activity**: Various timeframes, filtering options
-
-**Success Criteria:**
-- All operations complete without errors
-- Files appear correctly in filesystem
-- Search returns expected results
-- Context includes appropriate related content
-
-**Observations to Record:**
-```markdown
-# Core Functionality Test Results
-
-## Test Execution
-- [timestamp] Test started at 2025-01-06 15:30:00
-- [setup] Created test project successfully
-- [environment] MCP connection established
-
-## write_note Tests
-- [success] Basic note creation works
-- [success] Frontmatter tags are preserved
-- [issue] Special characters in titles need investigation
-
-## Relations
-- validates [[Search Operations Test]]
-- part_of [[Manual Testing Suite]]
-```
-
-### Phase 2: v0.13.0 Feature Deep Dive
-
-**Objective**: Thoroughly test new project management and editing capabilities
-
-**Project Management Tests:**
-- [ ] Create multiple projects dynamically
-- [ ] Switch between projects mid-conversation
-- [ ] Cross-project operations (create notes in different projects)
-- [ ] Project discovery and status checking
-- [ ] Default project behavior
-
-**Note Editing Tests:**
-- [ ] Append operations (add content to end)
-- [ ] Prepend operations (add content to beginning)
-- [ ] Find/replace operations with validation
-- [ ] Section replacement under headers
-- [ ] Edit operations across different projects
-
-**File Management Tests:**
-- [ ] Move notes within same project
-- [ ] Move notes between projects
-- [ ] Automatic folder creation during moves
-- [ ] Move operations with special characters
-- [ ] Database consistency after moves
-
-**Success Criteria:**
-- Project switching preserves context correctly
-- Edit operations modify files as expected
-- Move operations maintain database consistency
-- Search indexes update after moves and edits
-
-### Phase 3: Edge Case Exploration
-
-**Objective**: Discover limits and handle unusual scenarios gracefully
-
-**Boundary Testing:**
-- [ ] Very long note titles and content
-- [ ] Empty notes and projects
-- [ ] Special characters: unicode, emojis, symbols
-- [ ] Deeply nested folder structures
-- [ ] Circular relations and self-references
-
-**Error Scenario Testing:**
-- [ ] Invalid memory:// URLs
-- [ ] Missing files referenced in database
-- [ ] Concurrent operations (if possible)
-- [ ] Invalid project names
-- [ ] Disk space constraints (if applicable)
-
-**Performance Testing:**
-- [ ] Large numbers of notes (100+)
-- [ ] Complex search queries
-- [ ] Deep relation chains (5+ levels)
-- [ ] Rapid successive operations
-
-### Phase 4: Real-World Workflow Scenarios
-
-**Objective**: Test realistic usage patterns that users might follow
-
-**Scenario 1: Meeting Notes Pipeline**
-1. Create meeting notes with action items
-2. Extract action items into separate notes
-3. Link to project planning documents
-4. Update progress over time using edit operations
-5. Archive completed items
-
-**Scenario 2: Research Knowledge Building**
-1. Create research topic notes
-2. Build complex relation networks
-3. Add incremental findings over time
-4. Search and discover connections
-5. Reorganize as knowledge grows
-
-**Scenario 3: Multi-Project Workflow**
-1. Work project: Technical documentation
-2. Personal project: Recipe collection
-3. Learning project: Course notes
-4. Switch between projects during conversation
-5. Cross-reference related concepts
-
-**Scenario 4: Content Evolution**
-1. Start with basic notes
-2. Gradually enhance with relations
-3. Reorganize file structure
-4. Update existing content incrementally
-5. Build comprehensive knowledge graph
-
-### Phase 5: Creative Stress Testing
-
-**Objective**: Push the system to discover unexpected behaviors
-
-**Creative Exploration Areas:**
-- [ ] Rapid project creation and switching
-- [ ] Unusual but valid markdown structures
-- [ ] Creative use of observation categories
-- [ ] Novel relation types and patterns
-- [ ] Combining tools in unexpected ways
-
-**Stress Scenarios:**
-- [ ] Bulk operations (create many notes quickly)
-- [ ] Complex nested moves and edits
-- [ ] Deep context building with large graphs
-- [ ] Search with complex boolean expressions
-
-## Test Execution Process
-
-### Pre-Test Checklist
-- [ ] MCP connection verified
-- [ ] Test project created
-- [ ] Baseline notes recorded
-
-### During Testing
-1. **Execute test scenarios** using actual MCP tool calls
-2. **Record observations** immediately in test project
-3. **Note timestamps** for performance tracking
-4. **Document any errors** with reproduction steps
-5. **Explore variations** when something interesting happens
-
-### Test Observation Format
-
-Record all observations as Basic Memory notes using this structure:
-
-```markdown
----
-title: Test Session YYYY-MM-DD HH:MM
-tags: [testing, session, v0.13.0]
----
-
-# Test Session YYYY-MM-DD HH:MM
-
-## Test Focus
-- Primary objective
-- Features being tested
-
-## Observations
-- [success] Feature X worked as expected #functionality
-- [performance] Operation Y took 2.3 seconds #timing
-- [issue] Error with special characters #bug
-- [enhancement] Could improve UX for scenario Z #improvement
-
-## Discovered Issues
-- [bug] Description of problem with reproduction steps
-- [limitation] Current system boundary encountered
-
-## Relations
-- tests [[Feature X]]
-- part_of [[Manual Testing Suite]]
-- found_issue [[Bug Report: Special Characters]]
-```
-
-### Post-Test Analysis
-- [ ] Review all test observations
-- [ ] Create summary report with findings
-- [ ] Identify patterns in successes/failures
-- [ ] Generate improvement recommendations
-
-## Success Metrics
-
-**Quantitative Measures:**
-- % of test scenarios completed successfully
-- Number of bugs discovered and documented
-- Performance benchmarks established
-- Coverage of all MCP tools and operations
-
-**Qualitative Measures:**
-- Natural conversation flow maintained
-- Knowledge graph quality and connections
-- User experience insights captured
-- System reliability under various conditions
-
-## Expected Outcomes
-
-**For the System:**
-- Validation of v0.13.0 features in real usage
-- Discovery of edge cases not covered by unit tests
-- Performance baseline establishment
-- Bug identification with reproduction cases
-
-**For the Knowledge Base:**
-- Comprehensive testing documentation
-- Real usage examples for documentation
-- Edge case scenarios for future reference
-- Performance insights and optimization opportunities
-
-**For Development:**
-- Priority list for bug fixes
-- Enhancement ideas from real usage
-- Validation of architectural decisions
-- User experience insights
-
-## Test Reporting
-
-All test results will be captured in the Basic Memory test project, creating a living knowledge base of:
-
-- Test execution logs with detailed observations
-- Bug reports with reproduction steps
-- Performance benchmarks and timing data
-- Feature enhancement ideas discovered during testing
-- Knowledge graphs showing test coverage relationships
-- Summary reports for development team review
-
-This approach ensures that the testing process itself validates Basic Memory's core value proposition: effectively capturing, organizing, and connecting knowledge through natural interaction patterns.
-
-## Things to note
-
-### User Experience & Usability:
-- are tool instructions clear with working examples?
-- Do error messages provide actionable guidance for resolution?
-- Are response times acceptable for interactive use?
-- Do tools feel consistent in their parameter patterns and behavior?
-- Can users easily discover what tools are available and their capabilities?
-
-### System Behavior:
-- Does context preservation work as expected across tool calls?
-- Do memory:// URLs behave intuitively for knowledge navigation?
-- How well do tools work together in multi-step workflows?
-- Does the system gracefully handle edge cases and invalid inputs?
-
-### Documentation Alignment:
-- does tool output provide clear results and helpful information?
-- Do actual tool behaviors match their documented descriptions?
-- Are the examples in tool help accurate and useful?
-- Do real-world usage patterns align with documented workflows?
-
-### Mental Model Validation:
-- Does the system work the way users would naturally expect?
-- Are there surprising behaviors that break user assumptions?
-- Can users easily recover from mistakes or wrong turns?
-- Do the knowledge graph concepts (entities, relations, observations) feel natural?
-
-### Performance & Reliability:
-- Do operations complete in reasonable time for the data size?
-- Is system behavior consistent across multiple test sessions?
-- How does performance change as the knowledge base grows?
-- Are there any operations that feel unexpectedly slow?
-
----
-
-**Ready to begin testing?** Start by creating the test project and recording your first observation about the testing setup process itself.

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/AI Assistant Guide.md

@@ -77,22 +77,31 @@ read_note("specs/search-design")        # By path
 read_note("memory://specs/search")      # By memory URL
 ```
 
+**Viewing notes as formatted artifacts (Claude Desktop):**
+```
+view_note("Search Design")              # Creates readable artifact
+view_note("specs/search-design")        # By permalink
+view_note("memory://specs/search")      # By memory URL
+```
+
 **Incremental editing** (v0.13.0):
 ```
 edit_note(
-    identifier="Search Design",
+    identifier="Search Design",         # Must be EXACT title/permalink (strict matching)
     operation="append",                 # append, prepend, find_replace, replace_section
     content="\n## New Section\nContent here..."
 )
 ```
+**⚠️ Important:** `edit_note` requires exact identifiers (no fuzzy matching). Use `search_notes()` first if uncertain.
 
 **File organization** (v0.13.0):
 ```
 move_note(
-    identifier="Old Note",
+    identifier="Old Note",              # Must be EXACT title/permalink (strict matching)
     destination="archive/old-note.md"   # Folders created automatically
 )
 ```
+**⚠️ Important:** `move_note` requires exact identifiers (no fuzzy matching). Use `search_notes()` first if uncertain.
 
 ### Project Management (v0.13.0)
 
@@ -364,6 +373,20 @@ When creating relations:
 - If information seems outdated, suggest `basic-memory sync`
 - Use `recent_activity()` to check if content is current
 
+**Strict Mode for Edit/Move Operations:**
+- `edit_note()` and `move_note()` require **exact identifiers** (no fuzzy matching for safety)
+- If identifier not found: use `search_notes()` first to find the exact title/permalink
+- Error messages will guide you to find correct identifiers
+- Example workflow:
+  ```
+  # ❌ This might fail if identifier isn't exact
+  edit_note("Meeting Note", "append", "content")
+  
+  # ✅ Safe approach: search first, then use exact result
+  results = search_notes("meeting")
+  edit_note("Meeting Notes 2024", "append", "content")  # Use exact title from search
+  ```
+
 ## Best Practices
 
 1. **Proactively Record Context**

docs/CLI Reference.md

@@ -1,414 +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
-
-### auth (New in v0.13.0)
-
-Manage OAuth authentication for secure remote access:
-
-```bash
-# Test authentication setup
-basic-memory auth test-auth
-
-# Register OAuth client
-basic-memory auth register-client
-```
-
-Supports multiple authentication providers:
-- **Basic Provider**: For development and testing
-- **Supabase Provider**: For production deployments
-- **External Providers**: GitHub, Google integration framework
-
-See [[OAuth Authentication Guide]] for complete setup instructions.
-
-### sync
-
-Keeps files and the knowledge graph in sync:
-
-```bash
-# Basic sync
-basic-memory sync
-
-# Watch for changes
-basic-memory sync --watch
-
-# Show detailed sync information
-basic-memory sync --verbose
-```
-
-Options:
-- `--watch`: Continuously monitor for changes
-- `--verbose`: Show detailed output
-
-**Note**:
-
-As of the v0.12.0 release syncing will occur in real time when the mcp process starts.
-- The real time sync means that it is no longer necessary to run the `basic-memory sync --watch` process in a a terminal to sync changes to the db (so the AI can see them). This will be done automatically.
-
-This behavior can be changed via the config. The config file for Basic Memory is in the home directory under `.basic-memory/config.json`.
-
-To change the properties, set the following values:
-```
- ~/.basic-memory/config.json 
-{
-  "sync_changes": false,
-}
-```
-
-Thanks for using Basic Memory!
-### import (Enhanced in v0.13.0)
-
-Imports external knowledge sources with support for project targeting:
-
-```bash
-# Claude conversations
-basic-memory import claude conversations
-
-# Claude projects
-basic-memory import claude projects
-
-# ChatGPT history
-basic-memory import chatgpt
-
-# Memory JSON format
-basic-memory import memory-json /path/to/memory.json
-
-# Import to specific project (v0.13.0)
-basic-memory --project=work import claude conversations
-```
-
-**New in v0.13.0:**
-- **Project Targeting**: Import directly to specific projects
-- **Real-time Sync**: Imported content available immediately
-- **Unified Database**: All imports stored in centralized database
-
-> **Note**: Changes sync automatically - no manual sync required in v0.13.0.
-### 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 (Enhanced in v0.13.0)
-
-Manage multiple projects with the new unified database architecture. Projects can now be switched instantly during conversations without restart.
-  
-```bash  
-# List all configured projects with status
-basic-memory project list  
-  
-# Create a new project
-basic-memory project create work ~/work-basic-memory  
-  
-# Set the default project  
-basic-memory project set-default work  
-  
-# Delete a project (doesn't delete files)  
-basic-memory project delete personal  
-  
-# Show detailed project statistics
-basic-memory project info
-```  
-
-**New in v0.13.0:**
-- **Unified Database**: All projects share a single database for better performance
-- **Instant Switching**: Switch projects during conversations without restart
-- **Enhanced Commands**: Updated project commands with better status information
-- **Project Statistics**: Detailed info about entities, observations, and relations 
-
-#### 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  
-```  
-
-### tool (Enhanced in v0.13.0)
-
-Direct access to MCP tools via CLI with new editing and file management capabilities:
-
-```bash
-# Create notes
-basic-memory tool write-note --title "My Note" --content "Content here"
-
-# Edit notes incrementally (v0.13.0)
-echo "New content" | basic-memory tool edit-note --title "My Note" --operation append
-
-# Move notes (v0.13.0)
-basic-memory tool move-note --identifier "My Note" --destination "archive/my-note.md"
-
-# Search notes
-basic-memory tool search-notes --query "authentication"
-
-# Project management (v0.13.0)
-basic-memory tool list-projects
-basic-memory tool switch-project --project-name "work"
-```
-
-**New in v0.13.0:**
-- **edit-note**: Incremental editing (append, prepend, find/replace, section replace)
-- **move-note**: File management with database consistency
-- **Project tools**: list-projects, switch-project, get-current-project
-- **Cross-project operations**: Use `--project` flag with any tool
-
-### 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 ────────────────────────────────────────────────────────────────────────────────╮
-│ auth      OAuth authentication management (v0.13.0)                                      │
-│ 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:
-
-### cli
-
-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
-
-```
-
-### MCP
-
-Claude code can also now use mcp tools, so it can use any of the basic-memory tool natively. To install basic-memory in Claude Code:
-
-Run
-```
-claude mcp add basic-memory basic-memory mcp
-```
-
-For example: 
-
-```
-➜  ~ claude mcp add basic-memory basic-memory mcp
-Added stdio MCP server basic-memory with command: basic-memory mcp to project config
-➜  ~ claude mcp list
-basic-memory: basic-memory mcp
-```
-
-You can then use the `/mcp` command in the REPL:
-
-```
-/mcp
-  ⎿  MCP Server Status
-
-     • basic-memory: connected
-```
-
-## Version Management (New in v0.13.0)
-
-Basic Memory v0.13.0 introduces automatic version management and multiple installation options:
-
-```bash
-# Stable releases
-pip install basic-memory
-
-# Beta/pre-releases
-pip install basic-memory --pre
-
-# Latest development builds (auto-published)
-pip install basic-memory --pre --force-reinstall
-
-# Check current version
-basic-memory --version
-```
-
-**Version Types:**
-- **Stable**: `0.13.0` (manual git tags)
-- **Beta**: `0.13.0b1` (manual git tags) 
-- **Development**: `0.12.4.dev26+468a22f` (automatic from commits)
-
-## 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/Claude.ai Integration.md

@@ -1,335 +0,0 @@
-# Claude.ai Integration Guide
-
-This guide explains how to connect Basic Memory to Claude.ai, enabling Claude to read and write to your personal knowledge base.
-
-## Overview
-
-When connected to Claude.ai, Basic Memory provides:
-- Persistent memory across conversations
-- Knowledge graph navigation
-- Note-taking and search capabilities
-- File organization and management
-
-## Prerequisites
-
-1. Basic Memory MCP server with OAuth enabled
-2. Public HTTPS URL (or tunneling service for testing)
-3. Claude.ai account (Free, Pro, or Enterprise)
-
-## Quick Start (Testing)
-
-### 1. Start MCP Server with OAuth
-
-```bash
-# Enable OAuth with basic provider
-export FASTMCP_AUTH_ENABLED=true
-export FASTMCP_AUTH_PROVIDER=basic
-
-# Start server on all interfaces
-basic-memory mcp --transport streamable-http --host 0.0.0.0 --port 8000
-```
-
-### 2. Make Server Accessible
-
-For testing, use ngrok:
-
-```bash
-# Install ngrok
-brew install ngrok  # macOS
-# or download from https://ngrok.com
-
-# Create tunnel
-ngrok http 8000
-```
-
-Note the HTTPS URL (e.g., `https://abc123.ngrok.io`)
-
-### 3. Register OAuth Client
-
-```bash
-# Register a client for Claude
-basic-memory auth register-client --client-id claude-ai
-
-# Save the credentials!
-# Client ID: claude-ai
-# Client Secret: xxx...
-```
-
-### 4. Connect in Claude.ai
-
-1. Go to Claude.ai → Settings → Integrations
-2. Click "Add More"
-3. Enter your server URL: `https://abc123.ngrok.io/mcp`
-4. Click "Connect"
-5. Authorize the connection
-
-### 5. Use in Conversations
-
-- Click the tools icon (🔧) in the chat
-- Select "Basic Memory"
-- Try commands like:
-  - "Create a note about our meeting"
-  - "Search for project ideas"
-  - "Show recent notes"
-
-## Production Setup
-
-### 1. Deploy with Supabase Auth
-
-```bash
-# .env file
-FASTMCP_AUTH_ENABLED=true
-FASTMCP_AUTH_PROVIDER=supabase
-SUPABASE_URL=https://your-project.supabase.co
-SUPABASE_ANON_KEY=your-anon-key
-SUPABASE_SERVICE_KEY=your-service-key
-```
-
-### 2. Deploy to Cloud
-
-Options for deployment:
-
-#### Vercel
-```json
-// vercel.json
-{
-  "functions": {
-    "api/mcp.py": {
-      "runtime": "python3.9"
-    }
-  }
-}
-```
-
-#### Railway
-```bash
-# Install Railway CLI
-brew install railway
-
-# Deploy
-railway init
-railway up
-```
-
-#### Docker
-```dockerfile
-FROM python:3.12
-WORKDIR /app
-COPY . .
-RUN pip install -e .
-CMD ["basic-memory", "mcp", "--transport", "streamable-http"]
-```
-
-### 3. Configure for Organization
-
-For Claude.ai Enterprise:
-
-1. **Admin Setup**:
-   - Go to Organizational Settings
-   - Navigate to Integrations
-   - Add MCP server URL for all users
-   - Configure allowed scopes
-
-2. **User Permissions**:
-   - Users connect individually
-   - Each user has their own auth token
-   - Scopes determine access level
-
-## Security Best Practices
-
-### 1. Use HTTPS
-- Required for OAuth
-- Encrypt all data in transit
-- Use proper SSL certificates
-
-### 2. Implement Scopes
-```bash
-# Configure required scopes
-FASTMCP_AUTH_REQUIRED_SCOPES=read,write
-
-# User-specific scopes
-read: Can search and read notes
-write: Can create and update notes
-admin: Can manage all data
-```
-
-### 3. Token Security
-- Short-lived access tokens (1 hour)
-- Refresh token rotation
-- Secure token storage
-
-### 4. Rate Limiting
-```python
-# In your MCP server
-from fastapi import HTTPException
-from slowapi import Limiter
-
-limiter = Limiter(key_func=get_remote_address)
-
-@app.get("/mcp")
-@limiter.limit("100/minute")
-async def mcp_endpoint():
-    # Handle MCP requests
-```
-
-## Advanced Features
-
-### 1. Custom Tools
-
-Create specialized tools for Claude:
-
-```python
-@mcp.tool()
-async def analyze_notes(topic: str) -> str:
-    """Analyze all notes on a specific topic."""
-    # Search and analyze implementation
-    return analysis
-```
-
-### 2. Context Preservation
-
-Use memory:// URLs to maintain context:
-
-```python
-@mcp.tool()
-async def continue_conversation(memory_url: str) -> str:
-    """Continue from a previous conversation."""
-    context = await build_context(memory_url)
-    return context
-```
-
-### 3. Multi-User Support
-
-With Supabase, each user has isolated data:
-
-```sql
--- Row-level security
-CREATE POLICY "Users see own notes"
-ON notes FOR SELECT
-USING (auth.uid() = user_id);
-```
-
-## Troubleshooting
-
-### Connection Issues
-
-1. **"Failed to connect"**
-   - Verify server is running
-   - Check HTTPS is working
-   - Confirm OAuth is enabled
-
-2. **"Authorization failed"**
-   - Check client credentials
-   - Verify redirect URLs
-   - Review OAuth logs
-
-3. **"No tools available"**
-   - Ensure MCP tools are registered
-   - Check required scopes
-   - Verify transport type
-
-### Debug Mode
-
-Enable detailed logging:
-
-```bash
-# Server side
-export FASTMCP_LOG_LEVEL=DEBUG
-export LOGURU_LEVEL=DEBUG
-
-# Check logs
-tail -f logs/mcp.log
-```
-
-### Test Connection
-
-```bash
-# Test OAuth flow
-curl https://your-server.com/mcp/.well-known/oauth-authorization-server
-
-# Should return OAuth metadata
-{
-  "issuer": "https://your-server.com",
-  "authorization_endpoint": "https://your-server.com/auth/authorize",
-  ...
-}
-```
-
-## Best Practices
-
-1. **Regular Backups**
-   - Export your knowledge base
-   - Use version control
-   - Multiple storage locations
-
-2. **Access Control**
-   - Principle of least privilege
-   - Regular token rotation
-   - Audit access logs
-
-3. **Performance**
-   - Index frequently searched fields
-   - Optimize large knowledge bases
-   - Use caching where appropriate
-
-4. **User Experience**
-   - Clear tool descriptions
-   - Helpful error messages
-   - Quick response times
-
-## Examples
-
-### Creating Notes
-
-```
-User: Create a note about the meeting with the product team
-
-Claude: I'll create a note about your meeting with the product team.
-
-[Uses write_note tool]
-
-Note created: "Meeting with Product Team - 2024-01-15"
-Location: Work/Meetings/
-
-I've documented the meeting notes. The note includes the date, attendees, and key discussion points.
-```
-
-### Searching Knowledge
-
-```
-User: What did we discuss about the API redesign?
-
-Claude: Let me search for information about the API redesign.
-
-[Uses search_notes tool]
-
-I found 3 relevant notes about the API redesign:
-
-1. "API Redesign Proposal" (2024-01-10)
-   - RESTful architecture
-   - Version 2.0 specifications
-   - Migration timeline
-
-2. "Technical Review: API Changes" (2024-01-12)
-   - Breaking changes documented
-   - Backwards compatibility plan
-
-3. "Meeting: API Implementation" (2024-01-14)
-   - Team assignments
-   - Q1 deliverables
-```
-
-## Next Steps
-
-1. Set up production deployment
-2. Configure organizational access
-3. Create custom tools for your workflow
-4. Implement advanced security features
-5. Monitor usage and performance
-
-## Resources
-
-- [Basic Memory Documentation](../README.md)
-- [OAuth Setup Guide](OAuth%20Authentication.md)
-- [MCP Specification](https://modelcontextprotocol.io)
-- [Claude.ai Help Center](https://support.anthropic.com)

docs/Docker.md

@@ -0,0 +1,334 @@
+# 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:/root/.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:/root/.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:/root/.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:/root/.basic-memory:rw
+   ```
+   Persistent storage for configuration and SQLite database.
+
+You can edit the basic-memory config.json file located in the /root/.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 /root/.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 /root/.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
+
+Ensure your knowledge directories have proper permissions:
+
+```bash
+# Make directories readable/writable
+chmod -R 755 /path/to/your/obsidian-vault
+
+# If using specific user/group
+chown -R $USER:$USER /path/to/your/obsidian-vault
+```
+
+### 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 `/root/.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 root for simplicity. For production, consider additional security measures.
+
+2. **Volume Permissions:**
+   Ensure mounted directories have appropriate permissions and don't expose sensitive data.
+
+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 /root`
+
+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,355 +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.
-
-Basic Memory uses the [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) to connect with LLMs.
-It can be used with any service that supports the MCP, but Claude Desktop works especially well.
-
-## Installation
-
-### Prerequisites
-
-The easiest way to install basic memory is via `uv`. See the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
-
-### 1. Install Basic Memory
-
-**v0.13.0 offers multiple installation options:**
-
-```bash
-# Stable release (recommended)
-uv tool install basic-memory
-# or: pip install basic-memory
-
-# Beta releases (new features, testing)
-pip install basic-memory --pre
-
-# Development builds (latest changes)
-pip install basic-memory --pre --force-reinstall
-```
-
-**Version Information:**
-- **Stable**: Latest tested release (e.g., `0.13.0`)
-- **Beta**: Pre-release versions (e.g., `0.13.0b1`) 
-- **Development**: Auto-published from git commits (e.g., `0.12.4.dev26+468a22f`)
-
-> **Important**: You need to install Basic Memory using one of the commands above to use the command line tools.
-
-Using `uv tool install` will install the basic-memory package in a standalone virtual environment. See the [UV docs](https://docs.astral.sh/uv/concepts/tools/) for more info.
-
-### 2. Configure Claude Desktop
-
-Edit your Claude Desktop config, located at `~/Library/Application Support/Claude/claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "basic-memory": {
-      "command": "uvx",
-      "args": [
-        "basic-memory",
-        "mcp"
-      ]
-    }
-  }
-}
-```
-
-**Restart Claude Desktop**. You should see Basic Memory tools available in the "tools" menu in Claude Desktop (the little hammer icon in the bottom-right corner of the chat interface). Click it to view available tools.
-#### Fix Path to uv
-
-If you get an error that says `ENOENT` , this most likely means Claude Desktop could not find your `uv` installation. Make sure that you have `uv` installed per the instructions above, then:
-
-**Step 1: Find the absolute path to uvx**
-
-Open Terminal and run:
-
-```bash
-which uvx
-```
-
-This will show you the full path (e.g., `/Users/yourusername/.cargo/bin/uvx`).
-
-**Step 2: Edit Claude Desktop Configuration**
-
-Edit the Claude Desktop config:
-
-```json
-{
-  "mcpServers": {
-    "basic-memory": {
-      "command": "/absolute/path/to/uvx",
-      "args": [
-        "basic-memory",
-        "mcp"
-      ]
-    }
-  }
-}
-```
-
-Replace `/absolute/path/to/uvx` with the actual path you found in Step 1.
-
-**Step 3: Restart Claude Desktop**
-
-Close and reopen Claude Desktop for the changes to take effect.
-
-### 3. Sync changes in real time
-
-> **Note**: The service will sync changes from your project directory in real time so they available for the AI assistant. 
-
-To disable realtime sync, you can update the config. See [[CLI Reference#sync]].
-### 4. Staying Updated
-
-To update Basic Memory when new versions are released:
-
-```bash
-# Update stable release
-uv tool upgrade basic-memory 
-# or: pip install --upgrade basic-memory
-
-# Update to latest beta (v0.13.0)
-pip install --upgrade basic-memory --pre
-
-# Get latest development build
-pip install --upgrade basic-memory --pre --force-reinstall
-```
-
-**v0.13.0 Update Benefits:**
-- **Fluid project switching** during conversations
-- **Advanced note editing** capabilities
-- **Smart file management** with move operations
-- **Enhanced search** with frontmatter tag support
-
-> **Note**: After updating, restart Claude Desktop for changes to take effect. No sync restart needed in v0.13.0.
-
-### 5. Multi-Project Setup (Enhanced in v0.13.0)
-
-By default, Basic Memory creates a project in `~/basic-memory`. v0.13.0 introduces **fluid project management** - switch between projects instantly during conversations.
-
-```  
-# Create a new project
-basic-memory project create work ~/work-basic-memory  
-  
-# Set the default project  
-basic-memory project set-default work  
-
-# List all projects with status
-basic-memory project list
-
-# Get detailed project information
-basic-memory project info
-```
-
-**New in v0.13.0:**
-- **Instant switching**: Change projects during conversations without restart
-- **Unified database**: All projects in single `~/.basic-memory/memory.db`
-- **Better performance**: Optimized queries and reduced file I/O
-- **Session context**: Maintains active project throughout conversations
-
-## Troubleshooting Installation
-
-### Common Issues
-
-#### Claude Says "No Basic Memory Tools Available"
-
-If Claude cannot find Basic Memory tools:
-
-1. **Check absolute paths**: Ensure you're using complete absolute paths to uvx in the Claude Desktop configuration
-2. **Verify installation**: Run `basic-memory --version` in Terminal to confirm Basic Memory is installed
-3. **Restart applications**: Restart both Terminal and Claude Desktop after making configuration changes
-4. **Check sync status**: You can view the sync status by running `basic-memory status
-.
-#### Permission Issues
-
-If you encounter permission errors:
-
-1. Check that Basic Memory has access to create files in your home directory
-2. Ensure Claude Desktop has permission to execute the uvx command
-
-## Creating Your First Knowledge Note
-
-1. **Open Claude Desktop** and start a new conversation.
-
-2. **Have a natural conversation** about any topic:
-   ```
-   You: "Let's talk about coffee brewing methods I've been experimenting with."
-   Claude: "I'd be happy to discuss coffee brewing methods..."
-   You: "I've found that pour over gives more flavor clarity than French press..."
-   ```
-
-3. **Ask Claude to create a note**:
-   ```
-   You: "Could you create a note summarizing what we've discussed about coffee brewing?"
-   ```
-
-4. **Confirm note creation**:
-   Claude will confirm when the note has been created and where it's stored.
-
-5. **View the created file** in your `~/basic-memory` directory using any text editor or Obsidian.
-   The file structure will look similar to:
-   ```markdown
-   ---
-   title: Coffee Brewing Methods
-   permalink: coffee-brewing-methods
-   tags: [coffee, brewing, equipment]  # v0.13.0: Now searchable!
-   ---
-   
-   # Coffee Brewing Methods
-   
-   ## Observations
-   - [method] Pour over provides more clarity...
-   - [technique] Water temperature at 205°F...
-   
-   ## Relations
-   - relates_to [[Other Coffee Topics]]
-   ```
-
-**v0.13.0 Improvements:**
-- **Real-time sync**: Changes appear immediately, no background sync needed
-- **Searchable tags**: Frontmatter tags are now indexed for search
-- **Better file organization**: Enhanced file management capabilities
-
-## 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
-
-See [[User Guide#Using Special Prompts]] for further information.
-
-## 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 (Enhanced in v0.13.0)
-
-Basic Memory enables continuous knowledge building:
-
-1. **Reference previous discussions** in new conversations
-2. **Edit notes incrementally** without rewriting entire documents
-3. **Move and organize notes** as your knowledge base grows
-4. **Switch between projects** instantly during conversations
-5. **Search by tags** to find related content quickly
-6. **Create connections** between related topics
-7. **Follow relationships** to build comprehensive context
-
-### v0.13.0 Workflow Examples
-
-**Incremental Editing:**
-```
-You: "Add a section about espresso to my coffee brewing notes"
-Claude: [Uses edit_note to append new section]
-```
-
-**File Organization:**
-```
-You: "Move my old meeting notes to an archive folder"
-Claude: [Uses move_note with database consistency]
-```
-
-**Project Switching:**
-```
-You: "Switch to my work project and show recent activity"
-Claude: [Switches projects and shows work-specific content]
-```
-
-## Importing Existing Conversations
-
-Import your existing AI conversations:
-
-```bash
-# From Claude
-basic-memory import claude conversations
-
-# From ChatGPT
-basic-memory import chatgpt
-```
-
-After importing, changes sync automatically in real-time. You can see project statistics by running `basic-memory project info`.
-
-## Quick Tips
-
-### General Usage
-- Basic Memory syncs changes in real-time (no manual sync needed)
-- 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 with permalinks for precise context
-- Review and edit AI-generated notes for accuracy
-
-### v0.13.0 Features
-- **Switch projects instantly**: "Switch to my work project" - no restart needed
-- **Edit notes incrementally**: "Add a section about..." instead of rewriting
-- **Organize with moves**: "Move this to my archive folder" with database consistency
-- **Search by tags**: Frontmatter tags are now searchable
-- **Try beta builds**: `pip install basic-memory --pre` for latest features
-
-## 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
-6. **Explore [[OAuth Authentication Guide]]** for secure remote access (v0.13.0)
-7. **Set up multiple projects** for different knowledge areas (v0.13.0)

docs/Knowledge Format.md

@@ -1,207 +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, if the note has has a frontmatter section. 
-
-By default a  notes' permalink value will not change if the file is moved. It's a **stable** identifier :). But if you'd rather permalinks are always updated when a file moves, you can set the config setting in the global config. 
-
-The config file for Basic Memory is in the home directory under `.basic-memory/config.json`.
-
-To change the behavior, set the following value:
-```
- ~/.basic-memory/config.json 
-{
-  "update_permalinks_on_move": true
-}
-```
-
-### 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/OAuth Authentication Guide.md

@@ -1,259 +0,0 @@
-# OAuth Authentication Guide
-
-Basic Memory MCP server supports OAuth 2.1 authentication for secure access control. This guide covers setup, testing, and production deployment.
-
-## Quick Start
-
-### 1. Enable OAuth
-
-```bash
-# Set environment variable
-export FASTMCP_AUTH_ENABLED=true
-
-# Or use .env file
-echo "FASTMCP_AUTH_ENABLED=true" >> .env
-```
-
-### 2. Start the Server
-
-```bash
-basic-memory mcp --transport streamable-http
-```
-
-### 3. Test with MCP Inspector
-
-Since the basic auth provider uses in-memory storage with per-instance secret keys, you'll need to use a consistent approach:
-
-#### Option A: Use Environment Variable for Secret Key
-
-```bash
-# Set a fixed secret key for testing
-export FASTMCP_AUTH_SECRET_KEY="your-test-secret-key"
-
-# Start the server
-FASTMCP_AUTH_ENABLED=true basic-memory mcp --transport streamable-http
-
-# In another terminal, register a client
-basic-memory auth register-client --client-id=test-client
-
-# Get a token using the same secret key
-basic-memory auth test-auth
-```
-
-#### Option B: Use the Built-in Test Endpoint
-
-```bash
-# Start server with OAuth
-FASTMCP_AUTH_ENABLED=true basic-memory mcp --transport streamable-http
-
-# Register a client and get token in one step
-curl -X POST http://localhost:8000/register \
-  -H "Content-Type: application/json" \
-  -d '{"client_metadata": {"client_name": "Test Client"}}'
-
-# Use the returned client_id and client_secret
-curl -X POST http://localhost:8000/token \
-  -H "Content-Type: application/x-www-form-urlencoded" \
-  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
-```
-
-### 4. Configure MCP Inspector
-
-1. Open MCP Inspector
-2. Configure:
-   - Server URL: `http://localhost:8000/mcp/` (note the trailing slash!)
-   - Transport: `streamable-http`
-   - Custom Headers:
-     ```
-     Authorization: Bearer YOUR_ACCESS_TOKEN
-     Accept: application/json, text/event-stream
-     ```
-
-## OAuth Endpoints
-
-The server provides these OAuth endpoints automatically:
-
-- `GET /authorize` - Authorization endpoint
-- `POST /token` - Token exchange endpoint
-- `GET /.well-known/oauth-authorization-server` - OAuth metadata
-- `POST /register` - Client registration (if enabled)
-- `POST /revoke` - Token revocation (if enabled)
-
-## OAuth Flow
-
-### Standard Authorization Code Flow
-
-1. **Get Authorization Code**:
-   ```bash
-   curl "http://localhost:8000/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:8000/callback&response_type=code&code_challenge=YOUR_CHALLENGE&code_challenge_method=S256"
-   ```
-
-2. **Exchange Code for Token**:
-   ```bash
-   curl -X POST http://localhost:8000/token \
-     -H "Content-Type: application/x-www-form-urlencoded" \
-     -d "grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&code_verifier=YOUR_VERIFIER"
-   ```
-
-3. **Use Access Token**:
-   ```bash
-   curl http://localhost:8000/mcp \
-     -H "Authorization: Bearer ACCESS_TOKEN"
-   ```
-
-## Production Deployment
-
-### Using Supabase Auth
-
-For production, use Supabase for persistent auth storage:
-
-```bash
-# Configure environment
-FASTMCP_AUTH_ENABLED=true
-FASTMCP_AUTH_PROVIDER=supabase
-SUPABASE_URL=https://your-project.supabase.co
-SUPABASE_ANON_KEY=your-anon-key
-SUPABASE_SERVICE_KEY=your-service-key
-
-# Start server
-basic-memory mcp --transport streamable-http --host 0.0.0.0
-```
-
-### Security Requirements
-
-1. **HTTPS Required**: OAuth requires HTTPS in production (localhost exception for testing)
-2. **PKCE Support**: Claude.ai requires PKCE for authorization
-3. **Token Expiration**: Access tokens expire after 1 hour
-4. **Scopes**: Supported scopes are `read`, `write`, and `admin`
-
-## Connecting from Claude.ai
-
-1. **Deploy with HTTPS**:
-   ```bash
-   # Use ngrok for testing
-   ngrok http 8000
-   
-   # Or deploy to cloud provider
-   ```
-
-2. **Configure in Claude.ai**:
-   - Go to Settings → Integrations
-   - Click "Add More"
-   - Enter: `https://your-server.com/mcp`
-   - Click "Connect"
-   - Authorize in the popup window
-
-## Debugging
-
-### Common Issues
-
-1. **401 Unauthorized**: 
-   - Check token is valid and not expired
-   - Verify secret key consistency
-   - Ensure bearer token format: `Authorization: Bearer TOKEN`
-
-2. **404 on Auth Endpoints**:
-   - Endpoints are at root, not under `/auth`
-   - Use `/authorize` not `/auth/authorize`
-
-3. **Token Validation Fails**:
-   - Basic provider uses in-memory storage
-   - Tokens don't persist across server restarts
-   - Use same secret key for testing
-
-### Debug Commands
-
-```bash
-# Check OAuth metadata
-curl http://localhost:8000/.well-known/oauth-authorization-server
-
-# Enable debug logging
-export FASTMCP_LOG_LEVEL=DEBUG
-
-# Test token directly
-curl http://localhost:8000/mcp \
-  -H "Authorization: Bearer YOUR_TOKEN" \
-  -v
-```
-
-## Provider Options
-
-- **basic**: In-memory storage (development only)
-- **supabase**: Recommended for production
-- **github**: GitHub OAuth integration
-- **google**: Google OAuth integration
-
-## Example Test Script
-
-```python
-import httpx
-import asyncio
-from urllib.parse import urlparse, parse_qs
-
-async def test_oauth_flow():
-    """Test the full OAuth flow"""
-    client_id = "test-client"
-    client_secret = "test-secret"
-    
-    async with httpx.AsyncClient() as client:
-        # 1. Get authorization code
-        auth_response = await client.get(
-            "http://localhost:8000/authorize",
-            params={
-                "client_id": client_id,
-                "redirect_uri": "http://localhost:8000/callback",
-                "response_type": "code",
-                "code_challenge": "test-challenge",
-                "code_challenge_method": "S256",
-                "state": "test-state"
-            }
-        )
-        
-        # Extract code from redirect URL
-        redirect_url = auth_response.headers.get("Location")
-        parsed = urlparse(redirect_url)
-        code = parse_qs(parsed.query)["code"][0]
-        
-        # 2. Exchange for token
-        token_response = await client.post(
-            "http://localhost:8000/token",
-            data={
-                "grant_type": "authorization_code",
-                "code": code,
-                "client_id": client_id,
-                "client_secret": client_secret,
-                "code_verifier": "test-verifier",
-                "redirect_uri": "http://localhost:8000/callback"
-            }
-        )
-        
-        tokens = token_response.json()
-        print(f"Access token: {tokens['access_token']}")
-        
-        # 3. Test MCP endpoint
-        mcp_response = await client.post(
-            "http://localhost:8000/mcp",
-            headers={"Authorization": f"Bearer {tokens['access_token']}"},
-            json={"method": "initialize", "params": {}}
-        )
-        
-        print(f"MCP Response: {mcp_response.status_code}")
-
-asyncio.run(test_oauth_flow())
-```
-
-## Environment Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `FASTMCP_AUTH_ENABLED` | Enable OAuth authentication | `false` |
-| `FASTMCP_AUTH_PROVIDER` | OAuth provider type | `basic` |
-| `FASTMCP_AUTH_SECRET_KEY` | JWT signing key (basic provider) | Random |
-| `FASTMCP_AUTH_ISSUER_URL` | OAuth issuer URL | `http://localhost:8000` |
-| `FASTMCP_AUTH_REQUIRED_SCOPES` | Required scopes (comma-separated) | `read,write` |
-
-## Next Steps
-
-- [Supabase OAuth Setup](./Supabase%20OAuth%20Setup.md) - Production auth setup
-- [External OAuth Providers](./External%20OAuth%20Providers.md) - GitHub, Google integration
-- [MCP OAuth Specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) - Official spec

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/Supabase OAuth Setup.md

@@ -1,311 +0,0 @@
-# Supabase OAuth Setup for Basic Memory
-
-This guide explains how to set up Supabase as the OAuth provider for Basic Memory MCP server in production.
-
-## Prerequisites
-
-1. A Supabase project (create one at [supabase.com](https://supabase.com))
-2. Basic Memory MCP server deployed
-3. Environment variables configuration
-
-## Overview
-
-The Supabase OAuth provider offers:
-- Production-ready authentication with persistent storage
-- User management through Supabase Auth
-- JWT token validation
-- Integration with Supabase's security features
-- Support for social logins (GitHub, Google, etc.)
-
-## Setup Steps
-
-### 1. Get Supabase Credentials
-
-From your Supabase project dashboard:
-
-1. Go to Settings > API
-2. Copy these values:
-   - `Project URL` → `SUPABASE_URL`
-   - `anon public` key → `SUPABASE_ANON_KEY`
-   - `service_role` key → `SUPABASE_SERVICE_KEY` (keep this secret!)
-   - JWT secret → `SUPABASE_JWT_SECRET` (under Settings > API > JWT Settings)
-
-### 2. Configure Environment Variables
-
-Create a `.env` file:
-
-```bash
-# Enable OAuth
-FASTMCP_AUTH_ENABLED=true
-FASTMCP_AUTH_PROVIDER=supabase
-
-# Your MCP server URL
-FASTMCP_AUTH_ISSUER_URL=https://your-mcp-server.com
-
-# Supabase configuration
-SUPABASE_URL=https://your-project.supabase.co
-SUPABASE_ANON_KEY=your-anon-key
-SUPABASE_SERVICE_KEY=your-service-key
-SUPABASE_JWT_SECRET=your-jwt-secret
-
-# Allowed OAuth clients (comma-separated)
-SUPABASE_ALLOWED_CLIENTS=web-app,mobile-app,cli-tool
-
-# Required scopes
-FASTMCP_AUTH_REQUIRED_SCOPES=read,write
-```
-
-### 3. Create OAuth Clients Table (Optional)
-
-For production, create a table to store OAuth clients in Supabase:
-
-```sql
-CREATE TABLE oauth_clients (
-  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
-  client_id TEXT UNIQUE NOT NULL,
-  client_secret TEXT NOT NULL,
-  name TEXT,
-  redirect_uris TEXT[],
-  allowed_scopes TEXT[],
-  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
-  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-);
-
--- Create an index for faster lookups
-CREATE INDEX idx_oauth_clients_client_id ON oauth_clients(client_id);
-
--- RLS policies
-ALTER TABLE oauth_clients ENABLE ROW LEVEL SECURITY;
-
--- Only service role can manage clients
-CREATE POLICY "Service role can manage clients" ON oauth_clients
-  FOR ALL USING (auth.jwt()->>'role' = 'service_role');
-```
-
-### 4. Set Up Auth Flow
-
-The Supabase OAuth provider handles the following flow:
-
-1. **Client Authorization Request**
-   ```
-   GET /authorize?client_id=web-app&redirect_uri=https://app.com/callback
-   ```
-
-2. **Redirect to Supabase Auth**
-   - User authenticates with Supabase (email/password, magic link, or social login)
-   - Supabase redirects back to your MCP server
-
-3. **Token Exchange**
-   ```
-   POST /token
-   Content-Type: application/x-www-form-urlencoded
-   
-   grant_type=authorization_code&code=xxx&client_id=web-app
-   ```
-
-4. **Access Protected Resources**
-   ```
-   GET /mcp
-   Authorization: Bearer <access_token>
-   ```
-
-### 5. Enable Social Logins (Optional)
-
-In Supabase dashboard:
-
-1. Go to Authentication > Providers
-2. Enable desired providers (GitHub, Google, etc.)
-3. Configure OAuth apps for each provider
-4. Users can now log in via social providers
-
-### 6. User Management
-
-Supabase provides:
-- User registration and login
-- Password reset flows
-- Email verification
-- User metadata storage
-- Admin APIs for user management
-
-Access user data in your MCP tools:
-
-```python
-# In your MCP tool
-async def get_user_info(ctx: Context):
-    # The token is already validated by the OAuth middleware
-    user_id = ctx.auth.user_id
-    email = ctx.auth.email
-    
-    # Use Supabase client to get more user data if needed
-    user = await supabase.auth.admin.get_user_by_id(user_id)
-    return user
-```
-
-### 7. Production Deployment
-
-1. **Environment Security**
-   - Never expose `SUPABASE_SERVICE_KEY`
-   - Use environment variables, not hardcoded values
-   - Rotate keys periodically
-
-2. **HTTPS Required**
-   - Always use HTTPS in production
-   - Configure proper SSL certificates
-
-3. **Rate Limiting**
-   - Implement rate limiting for auth endpoints
-   - Use Supabase's built-in rate limiting
-
-4. **Monitoring**
-   - Monitor auth logs in Supabase dashboard
-   - Set up alerts for suspicious activity
-
-## Testing
-
-### Local Development
-
-For local testing with Supabase:
-
-```bash
-# Start MCP server with Supabase auth
-FASTMCP_AUTH_ENABLED=true \
-FASTMCP_AUTH_PROVIDER=supabase \
-SUPABASE_URL=http://localhost:54321 \
-SUPABASE_ANON_KEY=your-local-anon-key \
-bm mcp --transport streamable-http
-```
-
-### Test Authentication Flow
-
-```python
-import httpx
-import asyncio
-
-async def test_supabase_auth():
-    # 1. Register/login with Supabase directly
-    supabase_url = "https://your-project.supabase.co"
-    
-    # 2. Get MCP authorization URL
-    response = await httpx.get(
-        "http://localhost:8000/authorize",
-        params={
-            "client_id": "web-app",
-            "redirect_uri": "http://localhost:3000/callback",
-            "response_type": "code",
-        }
-    )
-    
-    # 3. User logs in via Supabase
-    # 4. Exchange code for MCP tokens
-    # 5. Access protected resources
-
-asyncio.run(test_supabase_auth())
-```
-
-## Advanced Configuration
-
-### Custom User Metadata
-
-Store additional user data in Supabase:
-
-```sql
--- Add custom fields to auth.users
-ALTER TABLE auth.users 
-ADD COLUMN IF NOT EXISTS metadata JSONB DEFAULT '{}';
-
--- Or create a separate profiles table
-CREATE TABLE profiles (
-  id UUID REFERENCES auth.users PRIMARY KEY,
-  username TEXT UNIQUE,
-  avatar_url TEXT,
-  bio TEXT,
-  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-);
-```
-
-### Row Level Security (RLS)
-
-Protect user data with RLS:
-
-```sql
--- Users can only access their own data
-CREATE POLICY "Users can view own profile" ON profiles
-  FOR SELECT USING (auth.uid() = id);
-
-CREATE POLICY "Users can update own profile" ON profiles
-  FOR UPDATE USING (auth.uid() = id);
-```
-
-### Custom Claims
-
-Add custom claims to JWT tokens:
-
-```sql
--- Function to add custom claims
-CREATE OR REPLACE FUNCTION custom_jwt_claims()
-RETURNS JSON AS $$
-BEGIN
-  RETURN json_build_object(
-    'user_role', current_setting('request.jwt.claims')::json->>'user_role',
-    'permissions', current_setting('request.jwt.claims')::json->>'permissions'
-  );
-END;
-$$ LANGUAGE plpgsql;
-```
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Invalid JWT Secret**
-   - Ensure `SUPABASE_JWT_SECRET` matches your Supabase project
-   - Check Settings > API > JWT Settings in Supabase dashboard
-
-2. **CORS Errors**
-   - Configure CORS in your MCP server
-   - Add allowed origins in Supabase dashboard
-
-3. **Token Validation Fails**
-   - Verify tokens are being passed correctly
-   - Check token expiration times
-   - Ensure scopes match requirements
-
-4. **User Not Found**
-   - Confirm user exists in Supabase Auth
-   - Check if email is verified (if required)
-   - Verify client permissions
-
-### Debug Mode
-
-Enable debug logging:
-
-```bash
-export FASTMCP_LOG_LEVEL=DEBUG
-export SUPABASE_LOG_LEVEL=debug
-```
-
-## Security Best Practices
-
-1. **Secure Keys**: Never commit secrets to version control
-2. **Least Privilege**: Use minimal required scopes
-3. **Token Rotation**: Implement refresh token rotation
-4. **Audit Logs**: Monitor authentication events
-5. **Rate Limiting**: Protect against brute force attacks
-6. **HTTPS Only**: Always use encrypted connections
-
-## Migration from Basic Auth
-
-To migrate from the basic auth provider:
-
-1. Export existing user data
-2. Import users into Supabase Auth
-3. Update client applications to use new auth flow
-4. Gradually transition users to Supabase login
-
-## Next Steps
-
-- Set up email templates in Supabase
-- Configure password policies
-- Implement MFA (multi-factor authentication)
-- Add social login providers
-- Create admin dashboard for user management

docs/Technical Information.md

@@ -1,243 +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
-
-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",
-          "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",
-          "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.
-
-### 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.
-
-### Files as Source of Truth
-
-Plain Markdown files store all knowledge, making it accessible with any text editor and easy to version with git.
-
-```mermaid
-flowchart TD
-    User((User)) <--> |Conversation| Claude["Claude or other LLM"]
-    Claude <-->|API Calls| BMCP["Basic Memory MCP Server"]
-    
-    subgraph "Local Storage"
-        KnowledgeFiles["Markdown Files - Source of Truth"]
-        KnowledgeIndex[(Knowledge Graph SQLite Index)]
-    end
-    
-    BMCP <-->|"write_note() read_note()"| KnowledgeFiles
-    BMCP <-->|"search_notes() build_context()"| KnowledgeIndex
-    KnowledgeFiles <-.->|Sync Process| KnowledgeIndex
-    KnowledgeFiles <-->|Direct Editing| Editors((Text Editors & Git))
-    
-    User -.->|"Complete control, Privacy preserved"| KnowledgeFiles
-    
-    
-    class Claude primary
-    class BMCP secondary
-    class KnowledgeFiles tertiary
-    class KnowledgeIndex quaternary
-    class User,Editors user`;
-```
-
-### Sqlite Database
-
-A local SQLite database maintains the knowledge graph topology for fast queries and semantic traversal without cloud dependencies. It contains:
-- db tables for the knowledge graph schema
-- a search index table enabling full text search across the knowledge base
-
-
-### 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 [[Welcome to Basic memory]] (Overview)
-- relates_to [[CLI Reference]] (Command line tools)
-- implements [[Knowledge Format]] (File structure and format)

docs/User Guide.md

@@ -1,657 +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 Desktop lets you send a prompt to provide context. You can use this at the beginning of a chat to preload context
-without needing to copy paste all the time. By using one of the supplied prompts, Basic Memory will search the knowledge
-base and give the AI instructions for how to build context.
-
-Choose "Continue Conversation":
-
-![[prompt 1.png|500]]
-
-Enter a topic:
-
-![[prompt2.png|500]]
-
-Give optional additional instructions:
-
-![[prompt3.png|500]]
-
-Claude can build context from the supplied topic. This works independently of Claude Project information. All the
-context comes from your local knowledge base.
-
-![[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
-
-### Note Editing (New in v0.13.0)
-
-**Edit notes incrementally without rewriting entire documents:**
-
-```
-💬 "Add a new section about deployment to my API documentation"
-🤖 [Uses edit_note to append new section]
-
-💬 "Update the date at the top of my meeting notes"
-🤖 [Uses edit_note to prepend new timestamp]
-
-💬 "Replace the implementation section in my design doc"
-🤖 [Uses edit_note to replace specific section]
-```
-
-Available editing operations:
-- **Append**: Add content to end of notes
-- **Prepend**: Add content to beginning of notes
-- **Replace Section**: Replace content under specific headers
-- **Find & Replace**: Simple text replacements with validation
-
-### File Management (New in v0.13.0)
-
-**Move and organize notes with full database consistency:**
-
-```
-💬 "Move my old meeting notes to the archive folder"
-🤖 [Uses move_note with automatic folder creation and database updates]
-
-💬 "Reorganize my project files into a better structure"
-🤖 [Moves files while maintaining search indexes and links]
-```
-
-Move operations include:
-- **Database Consistency**: Updates file paths, permalinks, and checksums
-- **Search Reindexing**: Maintains search functionality after moves
-- **Folder Creation**: Automatically creates destination directories
-- **Project Isolation**: Moves are contained within the current project
-- **Rollback Protection**: Ensures data integrity during failed operations
-
-### Enhanced Search (New in v0.13.0)
-
-**Frontmatter tags are now searchable:**
-
-```yaml
----
-title: Coffee Brewing Methods
-tags: [coffee, brewing, equipment]
----
-```
-
-Now searchable by: "coffee", "brewing", "equipment", or "Coffee Brewing Methods"
-
-### Importing External Knowledge
-
-Import existing conversations:
-
-```bash
-# From Claude
-basic-memory import claude conversations
-
-# From ChatGPT
-basic-memory import chatgpt
-
-# Target specific projects (v0.13.0)
-basic-memory --project=work import claude conversations
-```
-
-After importing, changes sync automatically in real-time.
-
-### 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 (v0.13.0)
-
-Basic Memory v0.13.0 introduces **fluid project management** - the ability to switch between projects instantly during conversations without restart. This allows you to maintain separate knowledge graphs for different purposes while seamlessly switching between them.
-
-### Instant Project Switching (New in v0.13.0)
-
-**Switch projects during conversations:**
-
-```
-💬 "What projects do I have?"
-🤖 Available projects:
-   • main (current, default)
-   • work-notes
-   • personal-journal
-   • code-snippets
-
-💬 "Switch to work-notes"
-🤖 ✓ Switched to work-notes project
-   
-   Project Summary:
-   • 47 entities
-   • 125 observations  
-   • 23 relations
-
-💬 "What did I work on yesterday?"
-🤖 [Shows recent activity from work-notes project]
-```
-
-### Project-Specific Operations (New in v0.13.0)
-
-Some MCP tools support optional project parameters for targeting specific projects:
-
-```
-💬 "Create a note about this meeting in my personal-notes project"
-🤖 [Creates note in personal-notes project]
-
-💬 "Switch to my work project"
-🤖 [Switches project context, then all operations work within that project]
-```
-
-**Note**: Operations like search, move, and edit work within the currently active project. To work with content in different projects, switch to that project first or use the project parameter where supported.
-
-### Managing Projects
-
-```bash  
-# List all configured projects  
-basic-memory project list  
-  
-# Add a new project  
-basic-memory project create work ~/work-basic-memory  
-  
-# Set the default project  
-basic-memory project set-default work  
-  
-# Remove a project (doesn't delete files)  
-basic-memory project delete personal  
-  
-# Show current project statistics
-basic-memory project info
-```  
-
-### 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  
-```  
-
-### Unified Database Architecture (New in v0.13.0)
-
-Basic Memory v0.13.0 uses a unified database architecture:
-
-- **Single Database**: All projects share `~/.basic-memory/memory.db`
-- **Project Isolation**: Proper data separation with project context
-- **Better Performance**: Optimized queries and reduced file I/O
-- **Easier Backup**: Single database file contains all project data
-- **Session Context**: Maintains active project throughout conversations
-
-## Workflow Tips
-
-### General Workflow
-1. **Project Organization**: Use multiple projects to separate different areas (work, personal, research)
-2. **Session Context**: Switch projects during conversations without restart (v0.13.0)
-3. **Real-time Sync**: Changes sync automatically - no need to run watch mode
-4. **Review Content**: Edit AI-created content for accuracy
-5. **Build Connections**: Create rich relationships between related ideas
-6. **Use Special Prompts**: Start conversations with context from your knowledge base
-
-### v0.13.0 Workflow Enhancements
-7. **Incremental Editing**: Use edit_note for small changes instead of rewriting entire documents
-8. **File Organization**: Move and reorganize notes as your knowledge base grows
-9. **Project-Specific Creation**: Create notes in specific projects using project parameters
-10. **Search Tags**: Use frontmatter tags to improve content discoverability
-11. **Project Statistics**: Monitor project growth and activity with project info commands
-
-## Troubleshooting
-
-### Sync Issues
-
-If changes aren't showing up:
-
-1. Run `basic-memory status` to check system state 
-2. 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)
-- enhanced_in_v0.13.0 [[OAuth Authentication Guide]] (Production authentication)
-- enhanced_in_v0.13.0 [[Project Management]] (Multi-project workflows)

docs/Welcome to Basic memory.md

@@ -1,68 +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.
-
-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.
-
-## Pick up your conversation right where you left off
-
-- 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
-
-![[Claude-Obsidian-Demo.mp4]]
-
-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)
-- **Model Context Protocol (MCP)** - For seamless AI assistant integration
-
-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 sync with the knowledge graph, and AI assistants can see your edits in 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]]
-- Obsidian integration guide [[Obsidian Integration]]
-- Canvas visualization guide [[Canvas]]
-- Command line tool reference [[CLI Reference]]
-- Reference for AI assistants using Basic Memory [[AI Assistant Guide]]
-- Technical implementation details [[Technical Information]]
-
-## Next Steps
-
-Start with the [[Getting Started with Basic Memory]] guide to install Basic Memory and configure it with your AI
-assistant.

docs/publish.js

@@ -1,5 +0,0 @@
-var analyticsScript = document.createElement('script');
-analyticsScript.defer = true;
-analyticsScript.setAttribute('data-website-id', '8d51086e-5c67-401e-97b0-b24706a6d4f3');
-analyticsScript.src = 'https://cloud.umami.is/script.js';
-document.head.appendChild(analyticsScript);

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/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/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]]

examples/testing/Test Note Creation - Basic Functionality.md

@@ -1,69 +0,0 @@
----
-title: Test Note Creation - Basic Functionality
-type: note
-permalink: testing/test-note-creation-basic-functionality
-tags:
-- '["testing"'
-- '"core-functionality"'
-- '"note-creation"]'
----
-
----
-title: Test Note Creation - Basic Functionality
-tags: [testing, core-functionality, note-creation, edited]
-test_status: active
-last_edited: 2025-06-01
----
-
-# Test Note Creation - Basic Functionality
-
-## Test Status: COMPREHENSIVE TESTING IN PROGRESS
-Testing basic note creation with various content types and structures.
-
-## Content Types Tested
-- Plain text content ✓
-- Markdown formatting **bold**, *italic*
-- Lists:
-  - Bullet points
-  - Numbered items
-- Code blocks: `inline code`
-
-```python
-# Block code
-def test_function():
-    return "Hello, Basic Memory!"
-```
-
-## Special Characters
-- Unicode: café, naïve, résumé
-- Emojis: 🚀 🔬 📝
-- Symbols: @#$%^&*()
-
-## Frontmatter Testing
-This note should have proper frontmatter parsing.
-
-## Relations to Test
-- connects_to [[Another Test Note]]
-- validates [[Core Functionality Tests]]
-
-## Observations
-- [success] Note creation initiated
-- [test] Content variety included
-- [validation] Special characters included
-
-
-## Edit Test Results
-- [success] Note reading via title lookup ✓
-- [success] Search functionality returns relevant results ✓
-- [success] Special characters (unicode, emojis) preserved ✓
-- [test] Now testing append edit operation ✓
-
-## Performance Notes
-- Note creation: Instantaneous
-- Note reading: Fast response
-- Search: Good relevance scoring
-
-## Next Tests
-- Edit operations (append, prepend, find_replace)
-- Move operations
-- Cross-project functionality

justfile

@@ -0,0 +1,216 @@
+# Basic Memory - Modern Command Runner
+
+# Install dependencies
+install:
+    pip install -e ".[dev]"
+
+# Run unit tests in parallel
+test-unit:
+    uv run pytest -p pytest_mock -v -n auto
+
+# Run integration tests in parallel
+test-int:
+    uv run pytest -p pytest_mock -v --no-cov -n auto test-int
+
+# Run all tests
+test: test-unit test-int
+
+# Lint and fix code
+lint:
+    ruff check . --fix
+
+# Type check code
+type-check:
+    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 type-check 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"
+
+# Build DXT package with bundled virtual environment
+dxt:
+    #!/usr/bin/env bash
+    echo "🏗️  Building DXT package..."
+    
+    # Clean and create bundle directory
+    rm -rf dxt-bundle
+    mkdir -p dxt-bundle/server/lib dxt-bundle/src
+    
+    # Bundle dependencies to server/lib (like Anthropic example)
+    echo "📦 Bundling Python dependencies..."
+    uv pip install -e . --target dxt-bundle/server/lib --force-reinstall
+    
+    # Copy source code
+    echo "📄 Copying source code..."
+    cp -r src/basic_memory dxt-bundle/src/
+    
+    # Copy manifest
+    cp manifest.json dxt-bundle/
+    
+    # Copy assets (icons, screenshots)
+    echo "🖼️  Copying assets..."
+    mkdir -p dxt-bundle/images
+    cp images/disk-ai-logo-black-fg-white-bg.png dxt-bundle/images/
+    cp images/claude-*.png dxt-bundle/images/
+    
+    # Create DXT package
+    echo "📦 Creating DXT package..."
+    cd dxt-bundle && dxt pack . ../basic-memory.dxt
+    
+    echo "✅ DXT package created: basic-memory.dxt"
+    echo "🔍 Info: dxt info basic-memory.dxt"
+    echo "🧪 Test: Install in Claude Desktop"
+
+# List all available recipes
+default:
+    @just --list

llms-install.md

@@ -1,128 +0,0 @@
-# Basic Memory Installation Guide for LLMs
-
-This guide is specifically designed to help AI assistants like Cline install and configure Basic Memory. Follow these
-steps in order.
-
-## Installation Steps
-
-### 1. Install Basic Memory Package
-
-Use one of the following package managers to install:
-
-```bash
-# Install with uv (recommended)
-uv tool install basic-memory
-
-# Or with pip
-pip install basic-memory
-```
-
-### 2. Configure MCP Server
-
-Add the following to your config:
-
-```json
-{
-  "mcpServers": {
-    "basic-memory": {
-      "command": "uvx",
-      "args": [
-        "basic-memory",
-        "mcp"
-      ]
-    }
-  }
-}
-```
-
-For Claude Desktop, this file is located at:
-
-macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
-Windows: %APPDATA%\Claude\claude_desktop_config.json
-
-### 3. Start Synchronization (optional)
-
-To synchronize files in real-time, run:
-
-```bash
-basic-memory sync --watch
-```
-
-Or for a one-time sync:
-
-```bash
-basic-memory sync
-```
-
-## Configuration Options
-
-### Custom Directory
-
-To use a directory other than the default `~/basic-memory`:
-
-```bash
-basic-memory project add custom-project /path/to/your/directory
-basic-memory project default custom-project
-```
-
-### Multiple Projects
-
-To manage multiple knowledge bases:
-
-```bash
-# List all projects
-basic-memory project list
-
-# Add a new project
-basic-memory project add work ~/work-basic-memory
-
-# Set default project
-basic-memory project default work
-```
-
-## Importing Existing Data
-
-### From Claude.ai
-
-```bash
-basic-memory import claude conversations path/to/conversations.json
-basic-memory import claude projects path/to/projects.json
-```
-
-### From ChatGPT
-
-```bash
-basic-memory import chatgpt path/to/conversations.json
-```
-
-### From MCP Memory Server
-
-```bash
-basic-memory import memory-json path/to/memory.json
-```
-
-## Troubleshooting
-
-If you encounter issues:
-
-1. Check that Basic Memory is properly installed:
-   ```bash
-   basic-memory --version
-   ```
-
-2. Verify the sync process is running:
-   ```bash
-   ps aux | grep basic-memory
-   ```
-
-3. Check sync output for errors:
-   ```bash
-   basic-memory sync --verbose
-   ```
-
-4. Check log output:
-   ```bash
-   cat ~/.basic-memory/basic-memory.log
-   ```
-
-For more detailed information, refer to the [full documentation](https://memory.basicmachines.co/).

manifest.json

@@ -0,0 +1,166 @@
+{
+  "dxt_version": "0.1",
+  "name": "basic-memory",
+  "display_name": "Basic Memory Knowledge Management",
+  "version": "0.14.0",
+  "description": "Local-first knowledge management with AI integration",
+  "long_description": "Basic Memory is a local-first knowledge management system that creates a personal knowledge graph from markdown files. It enables bidirectional communication between LLMs and your local knowledge base through the Model Context Protocol (MCP), allowing AI assistants to read, write, and navigate your knowledge seamlessly.",
+  "author": {
+    "name": "Basic Machines",
+    "email": "hello@basicmachines.co",
+    "url": "https://github.com/basicmachines-co"
+  },
+  "homepage": "https://basicmemory.com/",
+  "documentation": "https://memory.basicmachines.co/",
+  "support": "https://memory.basicmachines.co/user-guide",
+  "icon": "images/disk-ai-logo-black-fg-white-bg.png",
+  "screenshots": [
+    "images/claude-continue-conversation.png",
+    "images/claude-switch-project.png",
+    "images/claude-view-note.png"
+  ],
+  "server": {
+    "type": "python",
+    "entry_point": "src/basic_memory/cli/main.py",
+    "mcp_config": {
+      "command": "python3",
+      "args": [
+        "${__dirname}/src/basic_memory/cli/main.py",
+        "mcp",
+        "--transport=stdio"
+      ],
+      "env": {
+        "BASIC_MEMORY_HOME": "${user_data_dir}/basic-memory",
+        "PYTHONPATH": "${__dirname}/server/lib:${__dirname}/src"
+      }
+    }
+  },
+  "tools": [
+    {
+      "name": "write_note",
+      "description": "Create or update markdown notes with semantic structure"
+    },
+    {
+      "name": "read_note",
+      "description": "Read notes by title, permalink, or memory:// URL"
+    },
+    {
+      "name": "edit_note",
+      "description": "Edit notes incrementally (append, prepend, find/replace)"
+    },
+    {
+      "name": "move_note",
+      "description": "Move or rename notes"
+    },
+    {
+      "name": "view_note",
+      "description": "Display notes as formatted artifacts"
+    },
+    {
+      "name": "read_content",
+      "description": "Read raw file content (text, images, binaries)"
+    },
+    {
+      "name": "delete_note",
+      "description": "Delete notes from knowledge base"
+    },
+    {
+      "name": "search_notes",
+      "description": "Full-text search across knowledge base"
+    },
+    {
+      "name": "build_context",
+      "description": "Navigate knowledge graph via memory:// URLs"
+    },
+    {
+      "name": "recent_activity",
+      "description": "Get recently updated information"
+    },
+    {
+      "name": "list_directory",
+      "description": "Browse directory contents with filtering"
+    },
+    {
+      "name": "canvas",
+      "description": "Generate Obsidian canvas files for knowledge visualization"
+    },
+    {
+      "name": "list_memory_projects",
+      "description": "List all projects with status"
+    },
+    {
+      "name": "switch_project",
+      "description": "Switch between project contexts"
+    },
+    {
+      "name": "get_current_project",
+      "description": "Show current project stats"
+    },
+    {
+      "name": "create_memory_project",
+      "description": "Create new projects"
+    },
+    {
+      "name": "delete_project",
+      "description": "Remove projects"
+    },
+    {
+      "name": "set_default_project",
+      "description": "Set default project"
+    },
+    {
+      "name": "sync_status",
+      "description": "Check synchronization status"
+    }
+  ],
+  "prompts": [
+    {
+      "name": "continue_conversation",
+      "description": "Continue previous conversations with relevant historical context",
+      "arguments": [
+        "topic",
+        "timeframe"
+      ],
+      "text": "Continue our conversation about {{topic}} from {{timeframe}} ago. Use the continue_conversation tool to find relevant context and build on our previous discussion."
+    },
+    {
+      "name": "search_notes", 
+      "description": "Search knowledge base with detailed, formatted results",
+      "arguments": [
+        "query",
+        "after_date"
+      ],
+      "text": "Search my knowledge base for information about {{query}}. Use the search_notes tool to find relevant notes and provide a comprehensive summary of what I know about this topic."
+    },
+    {
+      "name": "recent_activity",
+      "description": "View recently changed items with formatted output", 
+      "arguments": [
+        "timeframe"
+      ],
+      "text": "Show me what I've been working on recently in the past {{timeframe}}. Use the recent_activity tool to display my recent notes and changes."
+    }
+  ],
+  "keywords": [
+    "knowledge",
+    "management", 
+    "local-first",
+    "ai",
+    "mcp",
+    "markdown",
+    "notes",
+    "zettelkasten"
+  ],
+  "license": "AGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/basicmachines-co/basic-memory"
+  },
+  "compatibility": {
+    "claude_desktop": ">=0.10.0",
+    "platforms": ["darwin", "win32", "linux"],
+    "runtimes": {
+      "python": ">=3.12.0 <4"
+    }
+  }
+}

memory.json

@@ -1,378 +0,0 @@
-{"type":"entity","name":"Paul","entityType":"person","observations":["Software developer combining DIY ethics, Free Software principles, and theoretical computer science","Created the Basic Machines project","Values authentic exchange of ideas","Approaches AI interaction with emphasis on genuine technical discussion","Comfortable with uncertainty and open dialogue","Balances practical implementation with broader implications"]}
-{"type":"entity","name":"Basic_Machines","entityType":"project","observations":["Local-first knowledge management system","Combines filesystem durability with graph-based knowledge representation","Focuses on enhancing human agency and understanding","Synthesizes DIY ethics, Free Software philosophy, and theoretical computer science","Current focus includes basic-memory system"]}
-{"type":"entity","name":"basic-memory","entityType":"software_system","observations":["A core component of Basic Machines","Local-first knowledge management system","Combines filesystem persistence with graph-based knowledge representation","Being implemented collaboratively by Paul and Claude"]}
-{"type":"entity","name":"basic-memory_implementation_patterns","entityType":"technical_patterns","observations":["Filesystem is source of truth - all changes write to files first","Clean separation of concerns between models (SQLAlchemy), schemas (Pydantic), and services","Repository pattern for database access","Service layer handling business logic and coordination","Atomic file operations using temporary files for safety","Clear error handling hierarchy with specific error types","Comprehensive test coverage with pytest and fixtures","Async/await used throughout the codebase","Validation using Pydantic models with custom validators"]}
-{"type":"entity","name":"fileio_module","entityType":"code_module","observations":["Extracted from EntityService to handle all file operations","Provides read_entity_file, write_entity_file, and delete_entity_file functions","Handles markdown parsing and formatting","Implements atomic file operations","Provides consistent error handling","Enables reuse across services"]}
-{"type":"entity","name":"entity_service","entityType":"code_module","observations":["Manages entities in both filesystem and database","Uses fileio module for file operations","Maintains database index of entities","Handles entity creation, retrieval, and deletion","Follows 'filesystem is source of truth' principle","Coordinates with observation service for full entity management"]}
-{"type":"entity","name":"observation_service","entityType":"code_module","observations":["Manages observations within entity files","Provides database indexing for efficient observation queries","Works with complete Entity objects rather than IDs","Handles observation addition and search","Maintains consistency between files and database","Under development for update/remove operations"]}
-{"type":"entity","name":"observation_management","entityType":"design_challenge","observations":["Key challenge: maintaining observation state across files and database","Exploring bulk update approach - treating all observations as a unit","Considering tracked observations with markdown comments for IDs","Investigating diff-based approach for observation-level changes","Evaluating position-based management without explicit IDs","Trade-offs between implementation complexity and markdown readability"]}
-{"type":"entity","name":"testing_infrastructure","entityType":"technical_patterns","observations":["Uses pytest with async support via pytest-asyncio","In-memory SQLite database for test isolation","Temporary directories for file operation testing","Comprehensive fixture system for test setup","Tests organized by component (entity, observation, etc)","Covers happy path, error cases, and edge cases","Uses monkeypatch for mocking dependencies","Clear separation between arrange, act, assert sections","Uses in-memory SQLite database for test isolation","Comprehensive fixture system for test data setup","Proper async test handling with pytest-asyncio"]}
-{"type":"entity","name":"test_categories","entityType":"test_suite","observations":["Happy path tests verify core functionality","Error path tests ensure proper error handling","Edge cases test special characters and long content","File operation tests verify atomic writes and rollbacks","Database sync tests verify index consistency","Recovery tests for rebuild operations","Punted on concurrent operation tests due to session management complexity"]}
-{"type":"entity","name":"completed_work","entityType":"project_milestone","observations":["Extracted file operations to fileio.py module","Updated EntityService to use fileio functions","Implemented initial ObservationService","Created comprehensive test suite","Established clear project patterns and principles","Set up basic database schema with SQLAlchemy","Created Pydantic models for validation"]}
-{"type":"entity","name":"future_work","entityType":"project_tasks","observations":["Implement observation updates/removals","Design proper session management for concurrent operations","Update EntityService tests for new fileio module","Add more sophisticated search functionality","Handle markdown formatting edge cases","Consider versioning for file changes","Implement proper backup strategy"]}
-{"type":"entity","name":"design_decisions","entityType":"technical_decisions","observations":["Filesystem as source of truth over database","Markdown format for human readability and editing","Atomic file operations for safety","SQLite + SQLAlchemy for proven reliability","Pydantic for validation and ID generation","Async/await for better scalability","Clear separation between files and database roles","Explicit error hierarchies for better handling"]}
-{"type":"entity","name":"concurrency_considerations","entityType":"technical_challenge","observations":["SQLAlchemy session management in async context","File operation atomicity","Transaction isolation levels","Potential for conflicting updates","Need for proper session lifecycle","Possibility of file system race conditions","Database lock management"]}
-{"type":"entity","name":"observation_update_approaches","entityType":"design_alternatives","observations":["Each approach trades off between simplicity, efficiency, and robustness","Four main approaches considered: bulk update, tracked IDs, diff-based, and position-based","Discussion revealed importance of human readability in file format","Consideration of manual editing workflows key to design","File system as source of truth principle guides tradeoffs"]}
-{"type":"entity","name":"bulk_update_approach","entityType":"design_option","observations":["Update all observations at once in a single operation","Simpler file operations - just rewrite the whole list","No need for observation matching or IDs","Very consistent with source of truth principle","Less efficient for small changes","May have concurrency implications","Simplest implementation option"]}
-{"type":"entity","name":"tracked_observations_approach","entityType":"design_option","observations":["Use markdown comments to store observation IDs","Enables precise updates and deletes","IDs stored as HTML comments in markdown","More complex markdown parsing required","IDs visible in raw markdown files","Balances tracking with readability"]}
-{"type":"entity","name":"diff_based_approach","entityType":"design_option","observations":["Implement observation-aware diffing","Track changes at observation level","More efficient for updates","Preserves manual edits and changes","More complex implementation needed","Must handle merge conflicts","Most sophisticated option considered"]}
-{"type":"entity","name":"position_based_approach","entityType":"design_option","observations":["Track observations by position/order","No explicit IDs needed","Cleanest markdown format","Order changes could break references","Difficult to handle concurrent edits","Most fragile option considered"]}
-{"type":"entity","name":"tasks_and_progress","entityType":"project_tracking","observations":["Current focus on observation management implementation","Completed core file operations extraction","Completed EntityService updates","Completed initial ObservationService","Basic test coverage in place","Future work includes concurrent operations","Future work includes search improvements","Need to handle markdown edge cases"]}
-{"type":"entity","name":"error_handling_patterns","entityType":"technical_patterns","observations":["Custom exception hierarchy with ServiceError base","Specific error types (FileOperationError, DatabaseSyncError, etc)","Clear separation between file and database errors","Error propagation patterns established","Focus on actionable error messages","Error handling at appropriate levels"]}
-{"type":"entity","name":"data_models","entityType":"technical_implementation","observations":["SQLAlchemy models for database structure","Pydantic schemas for API/service layer","Entity model with UUID-based IDs","Observation model with entity relationships","UTCDateTime custom type for timestamps","Automatic ID generation in Pydantic models","Strict validation rules"]}
-{"type":"entity","name":"markdown_format","entityType":"file_format","observations":["Simple, human-readable format","Entity name as H1 header","Metadata in key-value format","Observations as bullet points","Atomic file operations for updates","Designed for manual editing","No hidden metadata in main content"]}
-{"type":"entity","name":"test_driven_development","entityType":"development_pattern","observations":["Tests revealed need for atomic file operations","Error cases drove error hierarchy design","Edge cases informed validation rules","Test fixtures shaped service interfaces","File operations extracted due to test patterns","Concurrent test issues revealed session management needs"]}
-{"type":"entity","name":"architecture_evolution","entityType":"design_process","observations":["Started with simple EntityService implementation","Circular dependency between Entity and Observation services revealed design flaw","Extracted file operations to separate module","Moved to passing Entity objects rather than IDs","Improved separation of concerns through iterations","File operations became reusable across services","Database became true 'index' rather than source of truth"]}
-{"type":"entity","name":"validation_patterns","entityType":"technical_patterns","observations":["Pydantic models provide schema validation","Automatic ID generation if not provided","Database constraints via SQLAlchemy","Runtime checks in services","Markdown format validation","Error handling for invalid states"]}
-{"type":"entity","name":"markdown_examples","entityType":"documentation","observations":["Example of basic entity:\n# Entity Name\ntype: entity_type\n\n## Observations\n- First observation\n- Second observation","Example with special characters:\n# Test & Entity!\ntype: test\n\n## Observations\n- Test & observation with @#$% special chars!","Format ensures human readability:\n# Basic Machines\ntype: project\n\n## Observations\n- Local-first knowledge management system\n- Combines filesystem durability with graph-based knowledge representation","Future consideration for observation IDs:\n# Entity Name\ntype: entity_type\n\n## Observations\n- <!-- obs-id: abc123 -->\n  This is an observation with ID"]}
-{"type":"entity","name":"markdown_parsing_rules","entityType":"technical_implementation","observations":["H1 header contains entity name","Metadata uses key: value format","Observations section marked by H2 header","Each observation is a markdown list item","Blank lines separate sections","Special characters allowed in content","No restrictions on observation content"]}
-{"type":"entity","name":"schema_definitions","entityType":"technical_documentation","observations":["SQLAlchemy Entity model:\nclass Entity(Base):\n    id: str (primary key)\n    name: str (unique)\n    entity_type: str\n    created_at: datetime\n    updated_at: datetime","SQLAlchemy Observation model:\nclass Observation(Base):\n    id: str (primary key)\n    entity_id: str (foreign key)\n    content: str\n    created_at: datetime\n    context: Optional[str]","Pydantic Entity schema:\nclass Entity(BaseModel):\n    id: str\n    name: str\n    entity_type: str\n    observations: List[Observation]"]}
-{"type":"entity","name":"test_evolution","entityType":"development_history","observations":["Started with basic Entity CRUD tests","Added filesystem verification to all tests","Developed concurrent operation tests (later removed)","Edge case tests drove better error handling","Test fixtures evolved to support both file and DB testing","Mocking patterns for file/DB operations","Special cases for long content and special characters"]}
-{"type":"entity","name":"implementation_challenges","entityType":"technical_issues","observations":["Initial circular dependency between services","SQLAlchemy session management in async context","Atomic file operations with proper error handling","Maintaining DB sync with filesystem changes","Handling long content in observations","Managing test isolation with file operations","Deciding on markdown format tradeoffs","Concurrent operation complexity"]}
-{"type":"entity","name":"Basic_Factory","entityType":"Project","observations":["Collaborative project between Paul and Claude","Explores AI-human collaboration in software development","Uses MCP tools for file and memory management","Built with git integration capabilities","Focuses on maintaining project context across sessions","About 90% complete with MCP tools","Still needs improvements in collaboration via files/git/github","Will be used to document and share collaborative development process"]}
-{"type":"entity","name":"Basic_Factory_Components","entityType":"Technical","observations":["Server-side rendering with JinjaX","HTMX for dynamic updates","Alpine.js for client-side state","Tailwind CSS for styling","Component translation from React/shadcn/ui","Focus on simplicity and understandability","Demonstrates meta-compiler principles in component translation"]}
-{"type":"entity","name":"Component_Translation_Process","entityType":"Methodology","observations":["Treats component porting as meta-compilation","Maps between React/TypeScript and JinjaX/Alpine.js domains","Uses formal grammar transformation approaches","Maintains functionality while simplifying implementation","Focuses on server-side rendering patterns","Preserves accessibility and performance","Uses short, focused git branches for each component"]}
-{"type":"entity","name":"Basic_Machines_Philosophy","entityType":"Philosophy","observations":["Combines DIY punk ethics with software development","Emphasizes user empowerment and understanding","Values simplicity and composability","Treats complex systems as combinations of simple parts","Focuses on authentic creation and sharing","Draws inspiration from punk rock, Free Software, and theoretical CS","Emphasizes the cycle of creation, complexity, and renewal"]}
-{"type":"entity","name":"Basic_Machines_Manifesto","entityType":"Document","observations":["Created through collaboration between Paul and Claude","Explores connection between DIY punk ethics and software development","Emphasizes composition over inheritance in both philosophy and practice","Views software development through lens of basic machines that combine for complex computation","Advocates for user empowerment and technological independence","Structured in sections covering Origins, Philosophy, Technical Implementation, and AI Collaboration","Draws connections between punk rock, free software, and theoretical computer science","Emphasizes importance of sharing knowledge and building community","Released in December 2024"]}
-{"type":"entity","name":"AI_Human_Collaboration_Model","entityType":"Methodology","observations":["Focuses on deep collaboration rather than simple task completion","Maintains rich context across sessions via knowledge graph","Uses short, focused git branches for each collaborative session","Values intellectual partnership over simple code generation","Emphasizes both practical implementation and theoretical exploration","Creates space for authentic exchange while maintaining AI/human clarity","Uses formal methods when appropriate (like grammar transformation)","Documents decisions and processes for future reference","Developed through Basic Machines project experience"]}
-{"type":"entity","name":"Basic_Machines_Roadmap","entityType":"Project_Plan","observations":["Phase 1 (30 days): Build basic-machines.co website","Phase 2 (60-90 days): Develop premium component bundles","Phase 3 (90-120 days): Launch Basic Foundation commercial offering","Focus on building brand and marketing presence","Prioritize components needed for own site development","Document and share collaboration process","Build sustainable business model aligned with values"]}
-{"type":"entity","name":"Basic_Machines_Website","entityType":"Project","observations":["To be built at basic-machines.co","Will showcase products and vision","Needs components for navigation, hero sections, features","Will demonstrate component usage in production","Will include blog for sharing progress","Focus on clear value proposition","Platform for sharing Basic Machines philosophy"]}
-{"type":"entity","name":"Basic_Memory_Markdown_Example","entityType":"Example","observations":["Shows complete markdown structure for basic-memory entity","Uses frontmatter for metadata (id, type, created, context)","Has main description section after title","Includes Observations as bullet points","Shows Relations with [id] relation_type | context format","Lists References at bottom","Created during initial design discussion","Serves as canonical example of file format"]}
-{"type":"entity","name":"Basic_Memory_Database_Schema","entityType":"Technical","observations":["Uses SQLite for local storage","Entities table with id, name, type, created_at, context, description, references","Observations table linking to entities with content and context","Relations table tracking directional relationships between entities","References column needs quotes as SQL reserved word","Designed for easy rebuilding from markdown files","Foreign key constraints maintain data integrity","Unique constraint on relations prevents duplicates","Created_at timestamps track history","Context fields enable tracking information sources"]}
-{"type":"entity","name":"Basic_Memory_Project_Structure","entityType":"Technical","observations":["Uses dbmate for database migrations","Projects directory stores SQLite databases and markdown files","Makefile provides common development commands","Environment vars configure database connection","db/migrations directory for SQL schema changes","Gitignore excludes database files and env config","Uses Python 3.12 with modern tooling","Tests directory for pytest files","Follows Basic Machines project conventions"]}
-{"type":"entity","name":"Basic_Memory_Project_Isolation_Decision","entityType":"Decision","observations":["Decided to defer multi-project support to post-MVP","Will use separate SQLite databases per project","Initially using projects directory in code repository","Plan to make location configurable later","No changes needed to core domain model","Keeps initial implementation simple","FTS/search capabilities also deferred for simplicity"]}
-{"type":"entity","name":"Basic_Memory_Implementation_Plan","entityType":"Plan","observations":["Start with SQLAlchemy models matching schema","Then build CLI for basic operations","Then implement markdown parser","Use TDD approach throughout","Begin with core domain model","CLI will support CRUD operations","Parser must handle frontmatter and sections","Following modular development approach","Planning to use typer for CLI","Will use modern Python tools and practices"]}
-{"type":"entity","name":"Basic_Memory_Implementation_Status","entityType":"Status","observations":["Core modules implemented: models, services, repository, fileio","Modular architecture with clear separation of concerns","File operations extracted to separate fileio module","Initial ObservationService implementation complete","Basic test coverage in place","Exploring observation management strategies","Using SQLAlchemy for database interaction","Markdown file operations working","Entity management functional","Repository layer implementation complete with SQLAlchemy models and tests","Database operations working with proper UTC timestamp handling","In-memory SQLite testing infrastructure proven effective"]}
-{"type":"entity","name":"Basic_Memory_Observation_Management_Design","entityType":"Design","observations":["Four approaches under consideration","Bulk Update: Simple but less efficient","Tracked Observations: Precise but clutters markdown","Diff-based: Efficient but complex","Position-based: Clean but fragile","Key challenge is balancing markdown readability with efficient updates","Must maintain filesystem as source of truth","Need to consider concurrent edits","Currently evaluating trade-offs","Implementation choice pending discussion"]}
-{"type":"entity","name":"Basic_Memory_Architectural_Decisions","entityType":"Decisions","observations":["Split file operations into separate fileio module","Using SQLAlchemy for database operations","Maintain filesystem as source of truth","Modular service-based architecture","Clear separation between data access and business logic","Repository pattern for database interactions","Schemas separate from models","Focus on maintainability and testability","Services handle business rules","Considering concurrency in design"]}
-{"type":"entity","name":"Basic_Memory_Implementation_Analysis","entityType":"Analysis","observations":["Clean modular architecture with clear responsibilities","Strong typing throughout codebase","Excellent error handling with custom exceptions","SQLAlchemy models perfectly match our domain model","Atomic file operations for data safety","Services implement filesystem-as-source-of-truth principle","Async support throughout","Good separation between domain models and database models","Careful handling of UTC timestamps","Smart use of SQLAlchemy relationships"]}
-{"type":"entity","name":"Basic_Memory_Current_Challenges","entityType":"Challenges","observations":["Observation update/removal strategy needs to be chosen","Need to handle concurrent file operations safely","Search functionality to be implemented","Edge cases in markdown formatting to be handled","Session management for concurrent operations needed","Balance between file operations and database sync","Testing coverage could be expanded","Need to handle relationship updates in files"]}
-{"type":"entity","name":"Basic_Memory_Observation_Hash_Tracking","entityType":"Design","observations":["Use content hashes to track observation identity","Store hashes in database but not in markdown","Can match observations across file edits using hashes","Similar to how git tracks content changes","Keeps markdown clean and human-friendly","Allows efficient bulk updates","Handles reordering of observations","Maintains filesystem as source of truth","No need for visible IDs in markdown","Could track observation history through hash changes"]}
-{"type":"entity","name":"Basic_Memory_Repository_Implementation","entityType":"Code_Implementation","observations":["Implemented base Repository class with CRUD operations","Added specialized EntityRepository, ObservationRepository, and RelationRepository","Used string IDs instead of UUIDs","Added UTCDateTime custom type for timestamp handling","Used in-memory SQLite for testing","Achieved 84% test coverage","Created comprehensive pytest fixtures"]}
-{"type":"entity","name":"Basic_Memory_Dependencies","entityType":"Technical","observations":["Uses Python 3.12","SQLAlchemy with async support","pytest-asyncio for async testing","aiosqlite for async SQLite operations","greenlet for SQLAlchemy async support","uv for dependency management","pytest-cov for coverage reporting","Development dependencies managed in pyproject.toml"]}
-{"type":"entity","name":"Basic_Memory_Current_Architecture","entityType":"Architecture_Analysis","observations":["Clear separation between domain models (Pydantic) and storage models (SQLAlchemy)","File I/O completely separated into dedicated module","Strong 'filesystem as source of truth' pattern in services","Atomic file operations with proper error handling","Service layer coordinates between filesystem and database","Database acts as queryable index rather than primary storage","Clean error hierarchy with specific exception types","Rebuild operations available for recovery scenarios"]}
-{"type":"entity","name":"Basic_Memory_Evolution","entityType":"Analysis","observations":["Started with repository pattern following basic-foundation","Evolved to more sophisticated architecture with clear layers","Added Pydantic schemas for domain modeling","Separated file operations into dedicated module","Implemented robust error handling throughout","Maintained filesystem as source of truth principle","Added observation management with context tracking","Introduced rebuild capabilities for system recovery"]}
-{"type":"entity","name":"Basic_Memory_Service_Layer","entityType":"Implementation","observations":["EntityService handles entity lifecycle and coordinates storage","ObservationService manages observations within entities","Services ensure filesystem and database stay in sync","Clear error handling with ServiceError hierarchy","Strong typing throughout service interfaces","Implements filesystem as source of truth pattern","Handles UUID generation and timestamp management","Provides methods for system recovery and rebuild"]}
-{"type":"entity","name":"Basic_Memory_Schema_Design","entityType":"Implementation","observations":["Uses Pydantic for domain models and validation","Automatic ID generation with timestamp and UUID","Clear separation from SQLAlchemy storage models","Supports optional context tracking","Models match markdown file structure","Enables clean serialization/deserialization","Strong typing with proper validation rules","Independent from storage concerns"]}
-{"type":"entity","name":"Basic_Memory_Next_Tasks","entityType":"TaskList","observations":["✅ Implement SQLAlchemy models and repositories (Done)","✅ Add SQLAlchemy migrations (Done)","✅ Create service layer (Done)","✅ Implement file I/O module (Done)","✅ Set up domain models with Pydantic (Done)","✅ Initial test infrastructure (Done)","✅ Basic CRUD operations (Done)","⏳ Implement full test coverage for db.py","⏳ Add more sophisticated search functionality","⏳ Implement CLI interface","⏳ Add relationship management to services","⏳ Handle concurrent file operations safely","⏳ Add versioning for file changes","⏳ Implement proper backup strategy","⏳ Add type hints throughout codebase","⏳ Improve error messages and logging","⏳ Add documentation for core modules"]}
-{"type":"entity","name":"Basic_Memory_Meta_Experience","entityType":"Case_Study","observations":["Experienced our own context loss when reconstructing project knowledge","Had to rebuild task list and project context from filesystem and memory","Validated 'filesystem as source of truth' principle through reconstruction","Code and tests served as reliable historical record","Knowledge graph structure helped guide reconstruction process","Markdown files provided human-readable context","Atomic information design made piece-by-piece reconstruction possible","Ironic validation of the need for basic-memory's features","Experience demonstrates value of durable, human-readable knowledge storage","Shows importance of separating durable storage from ephemeral context"]}
-{"type":"entity","name":"Model_Context_Protocol","entityType":"protocol","observations":["Core part of the basic-memory architecture","Enables AI-human collaboration on projects","Provides tool-based interaction with knowledge graph","Developed by Anthropic for structured AI-system interaction","Used for maintaining consistent, rich context across conversations"]}
-{"type":"entity","name":"basic-memory_core_principles","entityType":"principles","observations":["Local First: All data stored locally in SQLite","Project Isolation: Separate databases per project","Human Readable: Everything exportable to plain text","AI Friendly: Structure optimized for LLM interaction","DIY Ethics: User owns and controls their data","Simple Core: Start simple, expand based on needs","Tool Integration: MCP-based interaction model"]}
-{"type":"entity","name":"basic-memory_business_model","entityType":"business_strategy","observations":["Core features free: Local SQLite, basic knowledge graph, search, markdown export, basic MCP tools","Professional features potential: Rich document export, advanced versioning, collaboration features, custom integrations, priority support","Focus on maintaining DIY/punk philosophy while enabling sustainability"]}
-{"type":"entity","name":"basic-memory_cli","entityType":"interface","observations":["Supports project management commands (create, switch, list)","Entity management (add entity, add observation, add relation)","Future support for export and batch operations","Follows consistent command structure","Planned integration with MCP tools"]}
-{"type":"entity","name":"basic-memory_export_format","entityType":"file_format","observations":["Uses markdown with frontmatter metadata","Includes entity name, type, creation timestamp","Observations as bullet points","Relations in structured format with links","References section at bottom","Designed for human readability and machine parsing","Example format documented in project specs"]}
-{"type":"entity","name":"relation_service","entityType":"code_module","observations":["Planned service for managing relations in both filesystem and database","Will follow filesystem-is-source-of-truth principle like other services","Needs to handle atomic file operations for relation updates","Must coordinate with EntityService for relationship integrity","Will handle bidirectional relationship tracking","Will support relation validation and type enforcement","Must implement rebuild functionality for index recovery","Will need careful error handling for file/db sync","Should support relation search and filtering","Must handle relation lifecycle (create/read/update/delete)"]}
-{"type":"entity","name":"service_layer_patterns","entityType":"implementation_patterns","observations":["Services handle both file and database operations","Filesystem is always source of truth","Database serves as queryable index","Services implement atomic file operations","Clear error hierarchy with specific exceptions","Use of dependency injection via constructor params","Async/await used throughout service layer","Services coordinate between storage layers","Repository pattern used for database access","Services maintain entity integrity across storage","Rich error types extend from ServiceError base","Rebuild operations available for recovery"]}
-{"type":"entity","name":"database_models","entityType":"implementation","observations":["Entity model with unique name and type","Observation model linked to entities","Relation model tracks connections between entities","Custom UTCDateTime type for timestamp handling","Use of SQLAlchemy relationships for navigation","Cascading deletes for dependent objects","String IDs used for compatibility","Rich relationship modeling with backpopulates","Proper indexing on foreign keys","Context tracking available on models","Models include created_at timestamps","Relationships handle bidirectional navigation"]}
-{"type":"entity","name":"repository_patterns","entityType":"implementation_patterns","observations":["Generic Repository[T] base class implementation","Type-safe operations with SQLAlchemy","Specialized repositories for each model type","Async operations throughout","Clear error handling patterns","Support for custom queries and filtering","Pagination support built-in","Transaction management via session","Proper type hints and generics usage","Entity-specific query methods in subclasses"]}
-{"type":"entity","name":"relation_service_design","entityType":"design","observations":["Must handle relation lifecycle in both files and DB","Needs to validate existence of both entities","Should support relation type enforcement","Must maintain bidirectional consistency","Should support relation querying and filtering","Needs proper error handling for graph consistency","Must integrate with entity file format","Should support bulk operations for efficiency","Must handle relation deletion and cascading","Should provide search by type and entities"]}
-{"type":"entity","name":"relation_service_implementation_plan","entityType":"plan","observations":["1. Define core relation operations (create, get, delete)","2. Implement file format handling for relations","3. Add database sync with RelationRepository","4. Implement validation and error handling","5. Add rebuild and recovery operations","6. Implement relation type enforcement","7. Add relation search and filtering","8. Implement bulk operations","9. Add comprehensive tests","10. Document API and error handling"]}
-{"type":"entity","name":"relation_service_challenges","entityType":"challenges","observations":["Maintaining consistency between file and database","Handling relation type validation efficiently","Managing bidirectional relationships in files","Ensuring atomic updates across entities","Handling deletion with proper cascading","Efficient querying of relation graphs","Recovery from partial file/db sync failures","Bulk operation atomicity","Clear error reporting for graph operations","Performance with large relation sets"]}
-{"type":"entity","name":"relation_file_format","entityType":"file_format","observations":["Relations stored in entity markdown files","Format: [target_id] relation_type | context","Relations section marked by ## Relations header","Outgoing relations only stored in source entity","Relations rebuild on entity load","Clean human-readable format","Context is optional with pipe separator","Links generate valid navigation references","Markdown-friendly formatting","Example: [Paul] authored | with Claude"]}
-{"type":"entity","name":"relation_service_error_handling","entityType":"implementation_patterns","observations":["RelationError extends ServiceError base","Specific errors for validation failures","Handles entity not found cases","Manages relation type validation errors","File operation errors properly wrapped","Database sync errors clearly reported","Transaction rollback on errors","Proper error propagation chain","Clear error messages for debugging","Recovery paths for common errors"]}
-{"type":"entity","name":"relation_service_testing","entityType":"testing","observations":["Test all relation lifecycle operations","Verify file and database consistency","Test relation type validation","Check error handling paths","Test bulk operations","Verify bidirectional consistency","Test recovery operations","Check cascade operations","Verify search and filtering","Test with large relation sets"]}
-{"type":"entity","name":"fileio_patterns","entityType":"implementation_patterns","observations":["Atomic file operations with temporary files","Clear error handling for IO operations","Consistent file naming and paths","Support for different file formats","Efficient file reading and writing","Proper file locking mechanisms","Recovery from partial writes","Consistent encoding handling","Directory management utilities","Path manipulation helpers","Currently implemented in fileio.py module","Uses pathlib for path operations","Handles file not found cases gracefully","Maintains data integrity during writes"]}
-{"type":"entity","name":"pytest_patterns","entityType":"implementation_patterns","observations":["Common fixtures should be in conftest.py for reuse","Use pytest_asyncio.fixture for async fixtures","Session fixtures need proper async cleanup","Temporary directories should be managed with context managers","Test categories: happy path, error path, recovery, edge cases","Services need project_path and repo injected","Use monkeypatch for mocking in async context","SQLite in-memory database ideal for testing","Explicit test verification: file content and database state"]}
-{"type":"entity","name":"relation_implementation_learnings","entityType":"implementation_learnings","observations":["Better to pass full Entity objects than IDs to services","Services should not re-read entities if they have them","File operations should be atomic and verified","Database serves as queryable index, not source of truth","Relations stored in source entity's markdown file","Clear separation between file ops and database sync","Entity objects should own their relations list","Context is optional but fully supported in implementation"]}
-{"type":"entity","name":"test_driven_insights","entityType":"learnings","observations":["Tests help reveal better API design (e.g., passing Entity objects)","Error cases drive proper exception hierarchy","File verification as important as database checks","Edge cases inform markdown format decisions","Recovery tests ensure system resilience","Tests document expected behavior clearly","Fixtures significantly reduce test complexity","Common patterns emerge through test writing"]}
-{"type":"entity","name":"meta_development_insights","entityType":"process","observations":["Break down large tasks into reviewable chunks","One file at a time prevents response truncation","Iterative development with tests leads to better design","Infrastructure code (fixtures) should be consolidated early","Test categories help ensure comprehensive coverage","Knowledge capture should happen during development","APIs tend to evolve toward simpler patterns","File operations require careful verification"]}
-{"type":"entity","name":"AI_Assistant_Learnings","entityType":"meta_insights","observations":["Output management: Breaking responses into single files prevents truncation and allows better review","Knowledge graph helps maintain context: I can reference previous decisions and patterns accurately","Memory rebuilding experience validated the need for durable storage","Test-driven development provides clear steps and verification","Explicit relation tracking in knowledge graph helps me understand project context","Rich context from multiple sources (code, docs, tests) enables better assistance","File-at-a-time approach allows deeper analysis of each component","Keeping entity names consistent helps with referencing and relationships"]}
-{"type":"entity","name":"Effective_Response_Patterns","entityType":"meta_patterns","observations":["When showing code changes, break into discrete files","Review existing code before suggesting changes","Reference knowledge graph for context and patterns","Explicitly connect new code to existing patterns","Validate suggestions against test cases","Keep track of file changes for atomic commits","Check both implementation and test files for consistency","Maintain clear separation of concerns in responses"]}
-{"type":"entity","name":"AI_Context_Management","entityType":"meta_practice","observations":["Knowledge graph provides reliable persistent memory","Project documentation gives high-level context","Code review shows implementation patterns","Tests demonstrate expected behavior","Important to actively track what has been modified","Entity relationships help understand dependencies","Regular knowledge capture during development","Using consistent entity references across conversations"]}
-{"type":"entity","name":"AI_Tool_Usage_Patterns","entityType":"meta_practice","observations":["read_file before suggesting changes","write_file one file at a time","list_directory to understand project structure","search_nodes to find relevant context","create_entities to capture new learnings","create_relations to connect concepts","Using knowledge graph to track decisions","Validating changes through test execution"]}
-{"type":"entity","name":"relation_service_learnings","entityType":"implementation_learnings","observations":["Entity-based API cleaner than ID-based for service layer","Model_dump method can handle storage serialization","File format needs explicit section markers (## Relations)","Whitespace handling important for long content comparisons","Test fixtures allow focused test cases","SQLAlchemy selects better than raw SQL for type safety","Atomic file operations maintained for relations"]}
-{"type":"entity","name":"test_driven_insights_relations","entityType":"learnings","observations":["Tests revealed need for whitespace normalization","Edge cases drove file format decisions","SQLAlchemy model access safer than raw queries","Fixtures reduced test setup complexity","File verification as important as database checks","Testing both memory model and storage format","Test categories ensure comprehensive coverage"]}
-{"type":"entity","name":"relation_service_patterns","entityType":"patterns","observations":["Use Entity objects in API","Serialize to IDs for storage","Maintain file as source of truth","Keep file format human-readable","Handle circular references in serialization","Use repository pattern for database","Clear error hierarchies"]}
-{"type":"entity","name":"packaging_learnings","entityType":"technical_learnings","observations":["When using pytest-mock, traditional pip install works more reliably than uv sync","Package discovery behavior can differ between uv and pip","Clean venv with pip install is a reliable fallback for dependency issues","Package installation location might differ between uv and pip","Dependencies in pyproject.toml dev section work reliably with pip install -e .[dev]"]}
-{"type":"entity","name":"Recent_Implementation_Progress","entityType":"progress_update","observations":["Successfully split services.py into modular structure under services/","Created __init__.py, entity_service.py, observation_service.py, relation_service.py","Fixed pytest-mock installation issues by using pip install -e .[dev] instead of uv sync","Improved test structure with minimal mocking - only used for error testing","Implemented relation service with Entity-based API","Achieved good test coverage across services","File operations are only mocked when testing error conditions","Services follow filesystem-as-source-of-truth pattern"]}
-{"type":"entity","name":"Next_Steps","entityType":"project_tasks","observations":["Consider adding more relation service tests","Potentially expand relations features","Look for opportunities to improve test coverage","Consider documenting package management preferences (pip vs uv)","Consider adding integration tests for services","Review and possibly expand error handling cases"]}
-{"type":"entity","name":"Development_Practices","entityType":"process","observations":["Favor real operations over mocks in tests","Only mock for error condition testing","Use pip install -e .[dev] for reliable dev dependency installation","Maintain modular service structure","Keep filesystem as source of truth","Use Entity objects in service APIs instead of IDs","Validate both file and database state in tests"]}
-{"type":"entity","name":"MCP_Resources","entityType":"Concept","observations":["Stateful objects in Model Context Protocol","Enable persistent access to capabilities"]}
-{"type":"entity","name":"MCP_Server_Implementation","entityType":"Technical_Design","observations":["Inherits from mcp.server.Server base class","Tools are implemented as async methods","Each tool method maps directly to a function available to the AI","Tools can request user input via Prompts","Simple function call interface rather than explicit resource management","State management handled by server instance","Returns serialized data using model_dump() for consistency"]}
-{"type":"entity","name":"MCP_Tools","entityType":"Protocol_Feature","observations":["Defined as async methods on server class","Return values must match tool definition schema","Can maintain state between invocations via server instance","Tools can prompt for user input when needed","No need for explicit Resource objects in implementation"]}
-{"type":"entity","name":"Basic_Memory_MCP","entityType":"Implementation","observations":["Uses MemoryService for core operations","Implements project selection via prompts","Maintains project context across tool invocations","Maps directly to memory graph operations","Handles serialization of Pydantic models"]}
-{"type":"entity","name":"Basic_Memory_Testing","entityType":"Testing_Design","observations":["Needs pytest for async testing","Should isolate filesystem operations for tests","Needs to handle MCP server lifecycle in tests","Should test both service layer and MCP interface","Will need mocks for project paths and file operations"]}
-{"type":"entity","name":"Memory_Service_Tests","entityType":"Test_Suite","observations":["Should test entity creation with observations","Should test relation creation between entities","Should verify proper ID generation and model validation","Should test deletion cascading","Should test search functionality","Must verify proper serialization of entities and relations"]}
-{"type":"entity","name":"MCP_Server_Tests","entityType":"Test_Suite","observations":["Should test project initialization workflow","Should test prompt handling","Should verify tool input/output formats","Should test error cases and validation","Must verify proper serialization in tool responses"]}
-{"type":"entity","name":"Memory_Service_Refactoring","entityType":"Technical_Task","observations":["MemoryService uses create() but EntityService might expect create_entity()","MemoryService assumes get_by_name() but EntityService might use different method","Need to verify deletion method signatures","Need to check if search interface matches","Should verify observation handling matches ObservationService interface","RelationService methods need verification","EntityService.create_entity takes name, type, and optional observations directly, not an Entity object","EntityService requires project_path and entity_repo in constructor","ObservationService.add_observation takes Entity object and content string, not raw data","RelationService.create_relation takes Entity objects directly, not dict data","All services follow filesystem-as-source-of-truth pattern with DB indexing","All services handle database synchronization internally","Services expect Path objects for filesystem operations"]}
-{"type":"entity","name":"Service_Interface_Audit","entityType":"Technical_Task","observations":["Need to review all existing service interfaces","Document current method signatures","Map discrepancies between MemoryService assumptions and actual interfaces","Check return types and error handling patterns","Review transaction/atomicity requirements","Method signatures need alignment: create vs create_entity etc","Need to handle DB repositories in service constructors","File operations should use project_path consistently","Need to maintain filesystem-as-source-of-truth pattern","Should handle database synchronization at service level","Error handling should align with existing patterns","Consider making MemoryService handle DB indexing consistently"]}
-{"type":"entity","name":"Memory_Service_Patterns","entityType":"Technical_Pattern","observations":["Uses inner async functions to encapsulate operation logic","Leverages list comprehensions with async functions for parallel operations","Each operation follows a consistent pattern: validate, update DB, write file","Inner functions make the code more readable and maintainable","Operations can run in parallel when using list comprehensions with async functions"]}
-{"type":"entity","name":"Pydantic_Create_Pattern","entityType":"Technical_Pattern","observations":["Separate Create models match the exact shape of incoming data","Provides clear contract for MCP tool inputs","Handles validation of raw input data","Converts cleanly to domain models via from_create methods","Maintains separation between external API format and internal models","Similar to FastAPI request model pattern","Allows camelCase in API while using snake_case internally"]}
-{"type":"entity","name":"Basic_Memory_Business","entityType":"Business_Model","observations":["Core system is open source and free","Local-first, giving users data control","Professional features could be licensed","Enterprise support and customization services","Potential for MCP tool marketplace"]}
-{"type":"entity","name":"MCP_Marketplace","entityType":"Business_Concept","observations":["Could host verified MCP tools for different use cases","Tools rated by performance and reliability","Marketplace takes percentage of tool usage fees","Enterprise tool verification and security scanning","Custom tool development services","Integration support for existing tools"]}
-{"type":"entity","name":"Persistence_Of_Vision","entityType":"Concept","observations":["Mental model for continuous AI-human interaction","Like cinema: 24fps creates illusion of smooth motion","Basic-memory provides 'frames' of structured knowledge","Current state: Better than flipbook, not yet digital cinema","Goal: Achieve smoother cognitive continuity between interactions","Proposed by Drew as metaphor for AI conversation continuity"]}
-{"type":"entity","name":"Conversation_Continuity_Pattern","entityType":"Usage_Pattern","observations":["Use basic-memory entity/relation schema for conversations","Each chat becomes an entity with observations for key points","Relations link to discussed concepts and other chats","Uses zettelkasten format IDs for natural ordering","Can be used as template/recipe for others","Future possibility: Git SHA integration for versioning"]}
-{"type":"entity","name":"Usage_Recipes","entityType":"Feature_Concept","observations":["Predefined patterns users can follow or adapt","Could include conversation tracking recipe","Templates for different knowledge management styles","Shows practical applications of the generic schema","Helps users get started with the system"]}
-{"type":"entity","name":"Chat_References","entityType":"Technical_Feature","observations":["Uses ref:* syntax to reference previous conversations","Combines reference semantics with pointer symbolism","Format: ref:*{zettelkasten-id}","Allows explicit context loading between chats","Inspired by C++ references and pointers","Provides memory-model-like access to conversation context","Uses ref:// URI format following MCP Resource pattern","Could support multiple reference schemes (chat/entity/concept)","Makes reference semantics explicit and unambiguous","Aligns with standard URI formatting"]}
-{"type":"entity","name":"Chat_Reference_Protocol","entityType":"Technical_Specification","observations":["Uses URI format: ref://basic-memory/chat/[id]","Follows MCP Resource pattern: [protocol]://[host]/[path]","Enables explicit context loading between chats","Can support multiple resource types (chat/entity/concept)","Provides standardized way to reference previous conversations","Example: ref://basic-memory/chat/20240307-drew-ab12ef34"]}
-{"type":"entity","name":"20240307-chat-reference-protocol","entityType":"conversation","observations":["Developed ref:// URI format for chat references","Added Chat Reference Protocol to prompt instructions","Discussed implementation of chat continuation","Created complete prompt instructions document","Reference format follows MCP Resource pattern","Reviewed and confirmed complete prompt instructions","Ready to test ref://basic-memory/chat/20240307-chat-reference-protocol in new chat"]}
-{"type":"entity","name":"20240307-chat-reference-protocol-test","entityType":"conversation","observations":["First implementation test of chat reference protocol","Testing continuation from 20240307-chat-reference-protocol","Focused on practical implementation of ref:// URI format"]}
-{"type":"entity","name":"Write_File_Tool_Usage","entityType":"Tool_Usage_Pattern","observations":["Never use placeholders like '# Rest of...' when writing files - must include complete file content","File content must be complete and valid - partial updates will truncate the file","If showing partial changes, should inform human and let them handle the file write","write_file tool replaces entire file contents - cannot do partial updates","Code files especially must be complete and valid to avoid breaking functionality","Always read_file before write_file to understand current state","Using write_file without reading first risks reverting recent changes","Pattern should be: read current state, make modifications, then write if needed","Especially important in collaborative development where files may have been updated"]}
-{"type":"entity","name":"Run_Tests_Tool_Request","entityType":"Feature_Request","observations":["Need to add a tool enabling Claude to run tests locally","Would help with direct validation of code changes","Current workaround: Claude has to ask human to run tests","Should support running specific test functions (e.g. pytest tests/test_memory_service.py::test_create_relations)","Would improve iterative development workflow between human and AI"]}
-{"type":"entity","name":"SQLAlchemy_Async_Loading_Pattern","entityType":"Technical_Pattern","observations":["Use selectinload() instead of lazy loading when accessing SQLAlchemy relationships in async code","Lazy loading doesn't work with async due to greenlet context requirements","selectinload performs a single efficient query with an IN clause","Pattern used in basic-memory's EntityRepository for loading relations","Documented in find_by_id method with thorough explanation","Alternative approaches: joinedload (single JOIN query) or subqueryload (subquery approach)","Benefits: prevents 'MissingGreenlet' errors, reduces N+1 query problems","Key insight: load all needed relationships upfront in async code","Example use: selectinload(Entity.outgoing_relations)"]}
-{"type":"entity","name":"20241207-sqlalchemy-async-pattern","entityType":"conversation","observations":["Fixed SQLAlchemy async relationship loading issues","Implemented selectinload pattern in EntityRepository","Updated find_by_id to eager load relations","Added documentation about the pattern","Created knowledge graph entry about SQLAlchemy async loading","Fixed failing tests by properly loading relations in memory_service","Discussed SQLAlchemy relationship loading best practices"]}
-{"type":"entity","name":"20241207-memory-service-relations","entityType":"conversation","observations":["Fixed SQLAlchemy async loading with selectinload pattern","Updated find_by_id in EntityRepository to eager load relations","Discovered create_relations works but returns empty list","Verified relations are being stored correctly in memory.json","Next step: Work on MemoryService.add_observations implementation","Improved understanding of MCP memory storage format through debugging"]}
-{"type":"entity","name":"add_observations_implementation_plan","entityType":"technical_plan","observations":["Follow pattern from create_entity and create_relation methods","File operations first (read & write) - filesystem is source of truth","Database updates in parallel","Simplify current implementation","Current flow is:"," - First read entities and create observations"," - Write files in parallel"," - Update DB indexes sequentially","Key tests needed:"," - Adding observations to multiple entities"," - Verifying filesystem state first"," - Verifying database state"," - Error cases for missing entities"," - Error cases for file operations"]}
-{"type":"entity","name":"MCP_Reference_Integration","entityType":"feature_idea","observations":["Can be implemented as a Model Context Protocol integration similar to the fetch tool","Would provide structured way to pass chat references to Claude","Could handle ref:// URL format systematically","Integration would fetch context from referenced chats and inject into conversation","Observed from Claude Desktop UI showing MCP integration pattern with fetch tool","Would be more robust than passing references in chat text"]}
-{"type":"entity","name":"Project_Priorities","entityType":"roadmap","observations":["P1: Dogfooding basic-memory system instead of JSON memory store","Future: Implement MCP-based reference system"]}
-{"type":"entity","name":"great_observation_loading_saga_20241207","entityType":"debugging_session","observations":["Occurred on December 7, 2024 while debugging basic-memory SQLAlchemy relationship loading","Issue: selectinload() wasn't properly loading relationships in async SQLAlchemy context","Tried multiple solutions: explicit joins, manual loading, various SQLAlchemy loading strategies","Final solution: Using session.refresh() with explicit relationship names","Memorable quote: 'The Great Observation Loading Saga'","Key learning: Sometimes the obvious SQLAlchemy patterns need adaptation for async contexts","Solution preserved in basic-memory repository in EntityRepository.find_by_id()"]}
-{"type":"entity","name":"basic_memory_implementation_20241208","entityType":"technical_milestone","observations":["Fixed async SQLAlchemy relationship loading issues by using explicit refresh with relationship names","Established pattern of relationship handling belonging in MemoryService not EntityService","Fixed ID generation flow through Pydantic schemas to DB layer","Standardized error handling using EntityNotFoundError","All 32 tests passing with 70% coverage","Core services (Entity, Observation, Relation) working properly","Ready for MCP server implementation","Notable debugging session: The Great Observation Loading Saga - resolved lazy loading issues","Established clear separation between MemoryService orchestration and individual service responsibilities"]}
-{"type":"entity","name":"MCP_Dependency_Risk","entityType":"technical_lesson","observations":["Experienced disruption when MCP npm package disappeared - 'leftpad moment'","Need to ensure basic-memory tools are resilient to external dependency issues","Local implementation of MCP server provides better stability than npm packages","Important to maintain control of critical infrastructure components","Validates DIY/local-first philosophy of basic-memory project","Package manager fragility revealed by simple 'npx @modelcontextprotocol/server-memory' failure"]}
-{"type":"entity","name":"basic_memory_project_20241208","entityType":"technical_milestone","observations":["Core MCP server implementation completed with tools: create_entities, search_nodes, open_nodes, add_observations, create_relations, delete_entities, delete_observations","ProjectConfig and dependency injection pattern established","Test framework in place with in-memory DB support","Support for both camelCase (MCP) and snake_case (internal) formats","Filesystem remains source of truth with SQLite as index","Two-way sync pattern identified between Claude MCP tools and direct markdown file editing","Ready for Claude Desktop integration testing phase","Next steps identified: passing tests, markdown format definition, file change tracking, real-world testing","Implementation prioritizes local-first principles with filesystem as source of truth"]}
-{"type":"entity","name":"basic_memory_mcp_architecture","entityType":"technical_design","observations":["MemoryServer class extends MCP Server with custom handler registration","Uses ProjectConfig for clean dependency injection and configuration","Memory service can be injected for testing","Handlers exposed as instance attributes for testing","Tool schemas leverage existing Pydantic models"]}
-{"type":"entity","name":"basic_memory_sync_considerations","entityType":"design_insight","observations":["Need to handle sync between direct markdown file edits and DB index","Watch for file system changes as potential future enhancement","Consider index rebuild patterns on startup","Keep human-friendly markdown format for direct editing"]}
-{"type":"entity","name":"mcp_server_learnings","entityType":"developer_insight","observations":["MCP protocol is new and documentation is still evolving","Test patterns are not well established yet in example implementations","Supporting both camelCase and snake_case helps with protocol/internal compatibility","Server.handle_* naming convention is important for handler registration"]}
-{"type":"entity","name":"20241208-mcp-tool-refactoring","entityType":"conversation","observations":["Decision to return structured data via EmbeddedResource instead of TextContent string parsing","Plan to create Pydantic result models (CreateEntitiesResult, SearchNodesResult etc)","Will use application/vnd.basic-memory+json as MIME type for our structured data","Currently debugging test issues with add_observations tool","Entity ID vs name resolution needed in add_observations","Goal is to make tools more joyful to use by eliminating string parsing","MCP spec supports EmbeddedResource for structured data returns"]}
-{"type":"entity","name":"Basic Memory MCP Server Implementation","entityType":"technical_notes","observations":["Server implements Model Context Protocol using proper structured data responses","Uses EmbeddedResource with custom MIME type 'application/vnd.basic-memory+json'","Clean separation between input validation and handlers via Pydantic models","All tool operations return structured data through create_response helper","Type safety with Literal types for tool names and proper typing for handlers","Handler registry pattern with TOOL_HANDLERS dictionary","Consistent error handling pattern using MCP error codes","Uses Pydantic ConfigDict for proper ORM integration","Tool schemas organized into Input and Response types","Input validation with Annotated types for extra constraints","Response models consistently use from_attributes=True for ORM data","Entity ID generation moved to model validator on EntityBase","Follows principle of making common operations easy and safe"]}
-{"type":"relation","from":"Paul","to":"Basic_Machines","relationType":"created_and_maintains"}
-{"type":"relation","from":"basic-memory","to":"Basic_Machines","relationType":"is_component_of"}
-{"type":"relation","from":"Paul","to":"basic-memory","relationType":"develops"}
-{"type":"relation","from":"fileio_module","to":"basic-memory_implementation_patterns","relationType":"implements"}
-{"type":"relation","from":"entity_service","to":"basic-memory_implementation_patterns","relationType":"implements"}
-{"type":"relation","from":"observation_service","to":"basic-memory_implementation_patterns","relationType":"implements"}
-{"type":"relation","from":"fileio_module","to":"basic-memory","relationType":"is_component_of"}
-{"type":"relation","from":"entity_service","to":"basic-memory","relationType":"is_component_of"}
-{"type":"relation","from":"observation_service","to":"basic-memory","relationType":"is_component_of"}
-{"type":"relation","from":"entity_service","to":"fileio_module","relationType":"uses"}
-{"type":"relation","from":"observation_service","to":"fileio_module","relationType":"uses"}
-{"type":"relation","from":"observation_management","to":"observation_service","relationType":"influences_design_of"}
-{"type":"relation","to":"basic-memory","from":"testing_infrastructure","relationType":"supports"}
-{"type":"relation","to":"testing_infrastructure","from":"test_categories","relationType":"implements"}
-{"type":"relation","to":"basic-memory","from":"completed_work","relationType":"tracks_progress_of"}
-{"type":"relation","to":"basic-memory","from":"future_work","relationType":"guides_development_of"}
-{"type":"relation","to":"basic-memory","from":"design_decisions","relationType":"shapes_architecture_of"}
-{"type":"relation","to":"basic-memory","from":"concurrency_considerations","relationType":"influences_design_of"}
-{"type":"relation","to":"future_work","from":"concurrency_considerations","relationType":"informs"}
-{"type":"relation","to":"observation_management","from":"design_decisions","relationType":"guides"}
-{"type":"relation","to":"testing_infrastructure","from":"completed_work","relationType":"established"}
-{"type":"relation","to":"design_decisions","from":"fileio_module","relationType":"implements"}
-{"type":"relation","from":"observation_update_approaches","to":"observation_management","relationType":"analyzes"}
-{"type":"relation","from":"bulk_update_approach","to":"observation_update_approaches","relationType":"is_option_of"}
-{"type":"relation","from":"tracked_observations_approach","to":"observation_update_approaches","relationType":"is_option_of"}
-{"type":"relation","from":"diff_based_approach","to":"observation_update_approaches","relationType":"is_option_of"}
-{"type":"relation","from":"position_based_approach","to":"observation_update_approaches","relationType":"is_option_of"}
-{"type":"relation","from":"tasks_and_progress","to":"basic-memory","relationType":"tracks_status_of"}
-{"type":"relation","from":"design_decisions","to":"observation_update_approaches","relationType":"influences"}
-{"type":"relation","from":"observation_update_approaches","to":"future_work","relationType":"informs"}
-{"type":"relation","to":"basic-memory_implementation_patterns","from":"error_handling_patterns","relationType":"is_part_of"}
-{"type":"relation","to":"basic-memory","from":"data_models","relationType":"implements"}
-{"type":"relation","to":"basic-memory","from":"markdown_format","relationType":"defines"}
-{"type":"relation","to":"basic-memory","from":"test_driven_development","relationType":"guides_development_of"}
-{"type":"relation","to":"basic-memory","from":"architecture_evolution","relationType":"describes_development_of"}
-{"type":"relation","to":"basic-memory_implementation_patterns","from":"validation_patterns","relationType":"is_part_of"}
-{"type":"relation","to":"design_decisions","from":"architecture_evolution","relationType":"informs"}
-{"type":"relation","to":"fileio_module","from":"markdown_format","relationType":"implements"}
-{"type":"relation","to":"error_handling_patterns","from":"test_driven_development","relationType":"influenced"}
-{"type":"relation","to":"data_models","from":"validation_patterns","relationType":"implements"}
-{"type":"relation","to":"markdown_format","from":"markdown_examples","relationType":"documents"}
-{"type":"relation","to":"markdown_format","from":"markdown_parsing_rules","relationType":"defines"}
-{"type":"relation","to":"data_models","from":"schema_definitions","relationType":"documents"}
-{"type":"relation","to":"test_driven_development","from":"test_evolution","relationType":"describes"}
-{"type":"relation","to":"architecture_evolution","from":"implementation_challenges","relationType":"influenced"}
-{"type":"relation","to":"test_evolution","from":"implementation_challenges","relationType":"shaped"}
-{"type":"relation","to":"future_work","from":"implementation_challenges","relationType":"informs"}
-{"type":"relation","from":"Basic_Factory","to":"Basic_Machines","relationType":"implements"}
-{"type":"relation","from":"Basic_Factory_Components","to":"Basic_Factory","relationType":"is_part_of"}
-{"type":"relation","from":"Component_Translation_Process","to":"Basic_Factory_Components","relationType":"enables"}
-{"type":"relation","from":"Basic_Machines_Philosophy","to":"Basic_Machines","relationType":"guides"}
-{"type":"relation","from":"Paul","to":"Basic_Factory","relationType":"develops"}
-{"type":"relation","from":"Paul","to":"Basic_Machines_Philosophy","relationType":"created"}
-{"type":"relation","from":"Basic_Machines_Manifesto","to":"Basic_Machines_Philosophy","relationType":"articulates"}
-{"type":"relation","from":"AI_Human_Collaboration_Model","to":"Basic_Factory","relationType":"guides_development_of"}
-{"type":"relation","from":"Basic_Machines_Manifesto","to":"Paul","relationType":"written_by"}
-{"type":"relation","from":"Basic_Machines_Manifesto","to":"Component_Translation_Process","relationType":"documents"}
-{"type":"relation","from":"AI_Human_Collaboration_Model","to":"Basic_Machines","relationType":"shapes_development_of"}
-{"type":"relation","from":"Basic_Machines_Roadmap","to":"Basic_Machines","relationType":"guides_development_of"}
-{"type":"relation","from":"Basic_Machines_Website","to":"Basic_Machines_Roadmap","relationType":"implements_phase_of"}
-{"type":"relation","from":"Basic_Factory_Components","to":"Basic_Machines_Website","relationType":"enables"}
-{"type":"relation","from":"Basic_Machines_Philosophy","to":"Basic_Machines_Website","relationType":"informs"}
-{"type":"relation","from":"Paul","to":"DIY_Ethics","relationType":"embodies"}
-{"type":"relation","from":"Basic_Machines_Philosophy","to":"DIY_Ethics","relationType":"incorporates"}
-{"type":"relation","from":"Basic_Machines","to":"DIY_Ethics","relationType":"exemplifies"}
-{"type":"relation","from":"Component_Translation_Process","to":"Basic_Machines_Philosophy","relationType":"implements"}
-{"type":"relation","from":"Basic_Factory_Components","to":"DIY_Ethics","relationType":"demonstrates"}
-{"type":"relation","from":"AI_Human_Collaboration_Model","to":"Basic_Machines_Philosophy","relationType":"aligns_with"}
-{"type":"relation","from":"AI_Human_Collaboration_Model","to":"Component_Translation_Process","relationType":"guides"}
-{"type":"relation","from":"Basic_Machines_Manifesto","to":"Basic_Machines","relationType":"defines_vision_for"}
-{"type":"relation","from":"Basic_Machines_Website","to":"Basic_Machines_Manifesto","relationType":"implements_vision_of"}
-{"type":"relation","from":"Basic_Factory","to":"AI_Human_Collaboration_Model","relationType":"demonstrates"}
-{"type":"relation","from":"Paul","to":"AI_Human_Collaboration_Model","relationType":"developed_with_Claude"}
-{"type":"relation","from":"Basic_Factory_Components","to":"Component_Translation_Process","relationType":"created_through"}
-{"type":"relation","from":"Basic_Machines_Philosophy","to":"Basic_Factory","relationType":"guides"}
-{"type":"relation","from":"Basic_Factory","to":"MCP_Tools","relationType":"integrates"}
-{"type":"relation","from":"Basic_Machines_Website","to":"Basic_Factory_Components","relationType":"will_use"}
-{"type":"relation","from":"Basic_Machines_Roadmap","to":"Basic_Machines_Philosophy","relationType":"aligns_with"}
-{"type":"relation","from":"Component_Translation_Process","to":"MCP_Tools","relationType":"leverages"}
-{"type":"relation","from":"Basic_Factory","to":"basic-memory","relationType":"will_document_process_in"}
-{"type":"relation","from":"AI_Human_Collaboration_Model","to":"basic-memory","relationType":"will_be_implemented_in"}
-{"type":"relation","from":"Basic_Machines_Philosophy","to":"Basic_Machines_Roadmap","relationType":"informs_priorities_of"}
-{"type":"relation","from":"basic-memory","to":"Basic_Machines_Philosophy","relationType":"embodies"}
-{"type":"relation","from":"Paul","to":"Basic_Machines_Manifesto","relationType":"authored_with_Claude"}
-{"type":"relation","from":"Basic_Factory","to":"Component_Translation_Process","relationType":"validated"}
-{"type":"relation","from":"AI_Human_Collaboration_Model","to":"MCP_Tools","relationType":"utilizes"}
-{"type":"relation","from":"Basic_Factory_Components","to":"Basic_Machines_Roadmap","relationType":"supports"}
-{"type":"relation","from":"Basic_Machines_Website","to":"Basic_Factory","relationType":"will_demonstrate"}
-{"type":"relation","from":"Basic_Factory","to":"basic-memory-webui","relationType":"enables_development_of"}
-{"type":"relation","from":"basic-memory","to":"AI_Human_Development_Methodology","relationType":"implements"}
-{"type":"relation","from":"Basic_Machines_Philosophy","to":"AI_Human_Development_Methodology","relationType":"guides"}
-{"type":"relation","from":"Basic_Factory_Components","to":"basic-memory-webui","relationType":"provides_ui_for"}
-{"type":"relation","from":"Component_Translation_Process","to":"AI_Human_Development_Methodology","relationType":"exemplifies"}
-{"type":"relation","from":"Basic_Factory","to":"Basic Components","relationType":"enabled_creation_of"}
-{"type":"relation","from":"Basic_Factory","to":"Tool Integration Discovery","relationType":"led_to"}
-{"type":"relation","from":"MCP_Integration_Progress","to":"AI_Human_Development_Methodology","relationType":"validates"}
-{"type":"relation","from":"Basic_Factory","to":"MCP_Integration_Progress","relationType":"demonstrates"}
-{"type":"relation","from":"Basic_Factory","to":"AI_Human_Development_Methodology","relationType":"proves_effectiveness_of"}
-{"type":"relation","from":"Basic_Machines_Philosophy","to":"Basic Components","relationType":"inspires_architecture_of"}
-{"type":"relation","from":"DIY_Ethics","to":"basic-memory","relationType":"shapes_design_of"}
-{"type":"relation","from":"Basic_Machines_Philosophy","to":"Tool Integration Discovery","relationType":"guides_analysis_of"}
-{"type":"relation","from":"Basic_Machines_Manifesto","to":"AI_Human_Development_Methodology","relationType":"documents_approach_of"}
-{"type":"relation","from":"Basic_Machines_Manifesto","to":"Basic_Factory_Components","relationType":"explains_principles_of"}
-{"type":"relation","from":"Basic_Memory_Project_Structure","to":"basic-memory","relationType":"organizes"}
-{"type":"relation","from":"Basic_Memory_Database_Schema","to":"basic-memory","relationType":"defines_storage_for"}
-{"type":"relation","from":"Basic_Memory_Markdown_Example","to":"Basic_Memory_File_Format","relationType":"demonstrates"}
-{"type":"relation","from":"Basic_Memory_Project_Isolation_Decision","to":"Basic_Memory_Future_Enhancement_Weighted_Relations","relationType":"similar_to"}
-{"type":"relation","to":"DIY_Ethics","from":"Basic_Memory_Project_Isolation_Decision","relationType":"follows"}
-{"type":"relation","from":"Basic_Memory_Implementation_Plan","to":"basic-memory","relationType":"guides"}
-{"type":"relation","from":"Basic_Memory_Implementation_Plan","to":"DIY_Ethics","relationType":"follows"}
-{"type":"relation","from":"Basic_Memory_Implementation_Plan","to":"Basic_Memory_Database_Schema","relationType":"implements"}
-{"type":"relation","from":"Basic_Memory_Implementation_Status","to":"Basic_Memory_Implementation_Plan","relationType":"updates"}
-{"type":"relation","from":"Basic_Memory_Observation_Management_Design","to":"Basic_Memory_Technical_Design","relationType":"extends"}
-{"type":"relation","from":"Basic_Memory_Architectural_Decisions","to":"DIY_Ethics","relationType":"guided_by"}
-{"type":"relation","from":"Basic_Memory_Architectural_Decisions","to":"basic-memory","relationType":"structures"}
-{"type":"relation","from":"Basic_Memory_Implementation_Status","to":"basic-memory","relationType":"describes_state_of"}
-{"type":"relation","to":"Basic_Memory_Implementation_Status","from":"Basic_Memory_Implementation_Analysis","relationType":"analyzes"}
-{"type":"relation","to":"basic-memory","from":"Basic_Memory_Current_Challenges","relationType":"identifies_issues_in"}
-{"type":"relation","to":"DIY_Ethics","from":"Basic_Memory_Implementation_Analysis","relationType":"confirms_alignment_with"}
-{"type":"relation","to":"Basic_Memory_Observation_Management_Design","from":"Basic_Memory_Observation_Hash_Tracking","relationType":"solves"}
-{"type":"relation","to":"DIY_Ethics","from":"Basic_Memory_Observation_Hash_Tracking","relationType":"aligns_with"}
-{"type":"relation","to":"Basic_Memory_File_Format","from":"Basic_Memory_Observation_Hash_Tracking","relationType":"preserves"}
-{"type":"relation","to":"Basic_Memory_Technical_Design","from":"Basic_Memory_Observation_Hash_Tracking","relationType":"enhances"}
-{"type":"relation","from":"Basic_Memory_Repository_Implementation","to":"basic-memory","relationType":"implements_part_of"}
-{"type":"relation","from":"Basic_Memory_Repository_Implementation","to":"Basic_Memory_Database_Schema","relationType":"follows"}
-{"type":"relation","from":"Basic_Memory_Repository_Implementation","to":"DIY_Ethics","relationType":"aligns_with"}
-{"type":"relation","from":"Basic_Memory_Repository_Implementation","to":"testing_infrastructure","relationType":"demonstrates"}
-{"type":"relation","from":"Basic_Memory_Repository_Implementation","to":"Basic Foundation","relationType":"inspired_by"}
-{"type":"relation","from":"Basic_Memory_Dependencies","to":"basic-memory","relationType":"supports"}
-{"type":"relation","from":"Basic_Memory_Dependencies","to":"Basic_Memory_Repository_Implementation","relationType":"enables"}
-{"type":"relation","from":"Basic_Memory_Dependencies","to":"testing_infrastructure","relationType":"enables"}
-{"type":"relation","from":"Basic_Memory_Current_Architecture","to":"basic-memory","relationType":"describes_state_of"}
-{"type":"relation","from":"Basic_Memory_Evolution","to":"Basic_Memory_Current_Architecture","relationType":"explains_development_of"}
-{"type":"relation","from":"Basic_Memory_Service_Layer","to":"Basic_Memory_Current_Architecture","relationType":"implements"}
-{"type":"relation","from":"Basic_Memory_Schema_Design","to":"Basic_Memory_Current_Architecture","relationType":"implements"}
-{"type":"relation","from":"Basic_Memory_Evolution","to":"Basic_Memory_Implementation_Plan","relationType":"reflects_on"}
-{"type":"relation","from":"Basic_Memory_Evolution","to":"DIY_Ethics","relationType":"demonstrates_alignment_with"}
-{"type":"relation","from":"Basic_Memory_Current_Architecture","to":"DIY_Ethics","relationType":"embodies"}
-{"type":"relation","from":"Basic_Memory_Service_Layer","to":"fileio_module","relationType":"uses"}
-{"type":"relation","from":"Basic_Memory_Schema_Design","to":"markdown_format","relationType":"implements"}
-{"type":"relation","to":"basic-memory","from":"Basic_Memory_Next_Tasks","relationType":"guides_development_of"}
-{"type":"relation","to":"DIY_Ethics","from":"Basic_Memory_Next_Tasks","relationType":"aligns_with"}
-{"type":"relation","to":"Basic_Memory_Current_Architecture","from":"Basic_Memory_Next_Tasks","relationType":"extends"}
-{"type":"relation","from":"Basic_Memory_Meta_Experience","to":"basic-memory","relationType":"validates_design_of"}
-{"type":"relation","from":"Basic_Memory_Meta_Experience","to":"DIY_Ethics","relationType":"demonstrates_principles_of"}
-{"type":"relation","from":"Basic_Memory_Meta_Experience","to":"design_decisions","relationType":"reinforces"}
-{"type":"relation","from":"Basic_Memory_Meta_Experience","to":"Basic_Memory_Current_Architecture","relationType":"validates"}
-{"type":"relation","from":"Model_Context_Protocol","to":"basic-memory","relationType":"enables"}
-{"type":"relation","from":"basic-memory_core_principles","to":"basic-memory","relationType":"guides"}
-{"type":"relation","from":"basic-memory_core_principles","to":"DIY_Ethics","relationType":"aligns_with"}
-{"type":"relation","from":"basic-memory_business_model","to":"basic-memory","relationType":"defines_sustainability_for"}
-{"type":"relation","from":"basic-memory_business_model","to":"DIY_Ethics","relationType":"maintains_alignment_with"}
-{"type":"relation","from":"basic-memory_cli","to":"basic-memory","relationType":"provides_interface_for"}
-{"type":"relation","from":"basic-memory_cli","to":"Model_Context_Protocol","relationType":"integrates_with"}
-{"type":"relation","from":"basic-memory_export_format","to":"basic-memory","relationType":"standardizes_output_of"}
-{"type":"relation","from":"basic-memory_export_format","to":"markdown_format","relationType":"extends"}
-{"type":"relation","from":"basic-memory_core_principles","to":"Basic_Machines_Philosophy","relationType":"implements"}
-{"type":"relation","from":"Model_Context_Protocol","to":"AI_Human_Collaboration_Model","relationType":"enables"}
-{"type":"relation","from":"relation_service","to":"basic-memory","relationType":"will_be_component_of"}
-{"type":"relation","from":"relation_service","to":"service_layer_patterns","relationType":"follows"}
-{"type":"relation","from":"relation_service","to":"fileio_patterns","relationType":"uses"}
-{"type":"relation","from":"relation_service","to":"database_models","relationType":"uses"}
-{"type":"relation","from":"relation_service","to":"repository_patterns","relationType":"implements"}
-{"type":"relation","from":"relation_service_design","to":"relation_service","relationType":"guides_implementation_of"}
-{"type":"relation","from":"relation_service_implementation_plan","to":"relation_service","relationType":"defines_implementation_of"}
-{"type":"relation","from":"relation_service_challenges","to":"relation_service_design","relationType":"informs"}
-{"type":"relation","from":"relation_file_format","to":"markdown_format","relationType":"extends"}
-{"type":"relation","from":"relation_service_error_handling","to":"service_layer_patterns","relationType":"implements"}
-{"type":"relation","from":"relation_service_testing","to":"testing_infrastructure","relationType":"extends"}
-{"type":"relation","from":"fileio_patterns","to":"service_layer_patterns","relationType":"enables"}
-{"type":"relation","from":"database_models","to":"repository_patterns","relationType":"enables"}
-{"type":"relation","from":"relation_service","to":"entity_service","relationType":"coordinates_with"}
-{"type":"relation","from":"relation_file_format","to":"relation_service","relationType":"defines_storage_for"}
-{"type":"relation","from":"relation_service_error_handling","to":"relation_service","relationType":"ensures_reliability_of"}
-{"type":"relation","from":"relation_service_testing","to":"relation_service","relationType":"verifies"}
-{"type":"relation","from":"service_layer_patterns","to":"basic-memory_implementation_patterns","relationType":"implements"}
-{"type":"relation","from":"repository_patterns","to":"basic-memory_implementation_patterns","relationType":"implements"}
-{"type":"relation","from":"fileio_patterns","to":"basic-memory_implementation_patterns","relationType":"implements"}
-{"type":"relation","from":"database_models","to":"basic-memory_implementation_patterns","relationType":"implements"}
-{"type":"relation","from":"relation_service_challenges","to":"implementation_challenges","relationType":"extends"}
-{"type":"relation","from":"relation_service_implementation_plan","to":"future_work","relationType":"details"}
-{"type":"relation","from":"relation_service_design","to":"design_decisions","relationType":"aligns_with"}
-{"type":"relation","from":"relation_file_format","to":"design_decisions","relationType":"follows"}
-{"type":"relation","from":"pytest_patterns","to":"testing_infrastructure","relationType":"extends"}
-{"type":"relation","from":"relation_implementation_learnings","to":"basic-memory_implementation_patterns","relationType":"informs"}
-{"type":"relation","from":"test_driven_insights","to":"test_driven_development","relationType":"enriches"}
-{"type":"relation","from":"meta_development_insights","to":"AI_Human_Collaboration_Model","relationType":"improves"}
-{"type":"relation","from":"relation_implementation_learnings","to":"relation_service","relationType":"guides_implementation_of"}
-{"type":"relation","from":"pytest_patterns","to":"test_evolution","relationType":"demonstrates"}
-{"type":"relation","from":"test_driven_insights","to":"design_decisions","relationType":"influences"}
-{"type":"relation","from":"meta_development_insights","to":"architecture_evolution","relationType":"informs"}
-{"type":"relation","from":"relation_service","to":"relation_implementation_learnings","relationType":"validates"}
-{"type":"relation","from":"test_driven_insights","to":"implementation_challenges","relationType":"helps_solve"}
-{"type":"relation","from":"AI_Assistant_Learnings","to":"meta_development_insights","relationType":"enriches"}
-{"type":"relation","from":"Effective_Response_Patterns","to":"AI_Assistant_Learnings","relationType":"implements"}
-{"type":"relation","from":"AI_Context_Management","to":"AI_Human_Collaboration_Model","relationType":"improves"}
-{"type":"relation","from":"AI_Tool_Usage_Patterns","to":"AI_Context_Management","relationType":"enables"}
-{"type":"relation","from":"AI_Assistant_Learnings","to":"Basic_Memory_Meta_Experience","relationType":"validates"}
-{"type":"relation","from":"AI_Tool_Usage_Patterns","to":"Model_Context_Protocol","relationType":"demonstrates_effective_use_of"}
-{"type":"relation","from":"AI_Context_Management","to":"basic-memory","relationType":"validates_design_of"}
-{"type":"relation","from":"Effective_Response_Patterns","to":"AI_Human_Development_Methodology","relationType":"refines"}
-{"type":"relation","to":"relation_service","from":"relation_service_patterns","relationType":"guides"}
-{"type":"relation","to":"test_driven_development","from":"test_driven_insights_relations","relationType":"enriches"}
-{"type":"relation","to":"implementation_challenges","from":"relation_service_learnings","relationType":"solves"}
-{"type":"relation","to":"basic-memory_implementation_patterns","from":"relation_service_patterns","relationType":"implements"}
-{"type":"relation","to":"markdown_format","from":"relation_service_patterns","relationType":"extends"}
-{"type":"relation","to":"service_layer_patterns","from":"relation_service_patterns","relationType":"refines"}
-{"type":"relation","from":"packaging_learnings","to":"implementation_challenges","relationType":"informs"}
-{"type":"relation","from":"packaging_learnings","to":"test_driven_development","relationType":"impacts"}
-{"type":"relation","to":"basic-memory","from":"Recent_Implementation_Progress","relationType":"updates_status_of"}
-{"type":"relation","to":"future_work","from":"Next_Steps","relationType":"extends"}
-{"type":"relation","to":"design_decisions","from":"Development_Practices","relationType":"informs"}
-{"type":"relation","to":"packaging_learnings","from":"Development_Practices","relationType":"incorporates"}
-{"type":"relation","to":"test_driven_development","from":"Development_Practices","relationType":"refines"}
-{"type":"relation","to":"basic-memory_implementation_patterns","from":"Development_Practices","relationType":"enhances"}
-{"type":"relation","from":"Basic_Memory_MCP","to":"MCP_Server_Implementation","relationType":"follows"}
-{"type":"relation","from":"Basic_Memory_MCP","to":"MCP_Tools","relationType":"uses"}
-{"type":"relation","from":"Basic_Memory","to":"MCP_Server_Implementation","relationType":"implements"}
-{"type":"relation","from":"Basic_Memory_Testing","to":"Memory_Service_Tests","relationType":"includes"}
-{"type":"relation","from":"Basic_Memory_Testing","to":"MCP_Server_Tests","relationType":"includes"}
-{"type":"relation","from":"Memory_Service_Tests","to":"Basic_Memory_MCP","relationType":"validates"}
-{"type":"relation","from":"MCP_Server_Tests","to":"Basic_Memory_MCP","relationType":"validates"}
-{"type":"relation","from":"Service_Interface_Audit","to":"Memory_Service_Refactoring","relationType":"informs"}
-{"type":"relation","from":"Memory_Service_Refactoring","to":"Basic_Memory_MCP","relationType":"affects"}
-{"type":"relation","from":"Memory_Service_Patterns","to":"Basic_Memory_MCP","relationType":"improves"}
-{"type":"relation","from":"Pydantic_Create_Pattern","to":"Memory_Service_Patterns","relationType":"enables"}
-{"type":"relation","from":"Pydantic_Create_Pattern","to":"Basic_Memory_MCP","relationType":"improves"}
-{"type":"relation","from":"MCP_Marketplace","to":"Basic_Memory_Business","relationType":"enables"}
-{"type":"relation","from":"Basic_Memory","to":"MCP_Marketplace","relationType":"could_integrate_with"}
-{"type":"relation","from":"Persistence_Of_Vision","to":"Basic_Memory","relationType":"helps_achieve"}
-{"type":"relation","from":"Drew","to":"Persistence_Of_Vision","relationType":"conceptualized"}
-{"type":"relation","to":"Usage_Recipes","from":"Conversation_Continuity_Pattern","relationType":"is_example_of"}
-{"type":"relation","to":"Basic_Memory","from":"Usage_Recipes","relationType":"enhances"}
-{"type":"relation","to":"Basic_Memory","from":"Chat_References","relationType":"enhances"}
-{"type":"relation","to":"Conversation_Continuity_Pattern","from":"Chat_References","relationType":"implements"}
-{"type":"relation","from":"20240307-chat-reference-protocol-test","to":"20240307-chat-reference-protocol","relationType":"continues_from"}
-{"type":"relation","from_id":"Run_Tests_Tool_Request","to_id":"Basic_Machines","relationType":"enhances","context":"development workflow improvement"}
-{"type":"relation","from_id":"SQLAlchemy_Async_Loading_Pattern","to_id":"basic-memory","relation_type":"improves","context":"database performance and async compatibility"}
-{"type":"relation","from_id":"SQLAlchemy_Async_Loading_Pattern","to_id":"Entity","relation_type":"applies_to","context":"relationship loading strategy"}
-{"type":"relation","from":"MCP_Reference_Integration","to":"Project_Priorities","relationType":"prioritized_after"}
-{"type":"relation","from":"great_observation_loading_saga_20241207","to":"Basic_Memory","relationType":"occurred_in"}
-{"type":"relation","from":"great_observation_loading_saga_20241207","to":"SQLAlchemy","relationType":"relates_to"}
-{"type":"relation","from":"basic_memory_implementation_20241208","to":"Basic_Memory","relationType":"improves"}
-{"type":"relation","from":"great_observation_loading_saga_20241207","to":"basic_memory_implementation_20241208","relationType":"leads_to"}
-{"type":"relation","from":"MCP_Dependency_Risk","to":"DIY_Ethics","relationType":"validates"}
-{"type":"relation","from":"MCP_Dependency_Risk","to":"basic-memory_core_principles","relationType":"reinforces"}
-{"type":"relation","from":"MCP_Dependency_Risk","to":"Basic_Memory_Implementation_Plan","relationType":"influences"}
-{"type":"relation","from":"basic_memory_mcp_architecture","to":"basic_memory_project_20241208","relationType":"implements"}
-{"type":"relation","from":"basic_memory_sync_considerations","to":"basic_memory_project_20241208","relationType":"influences"}
-{"type":"relation","from":"mcp_server_learnings","to":"basic_memory_mcp_architecture","relationType":"informs"}
-{"type":"relation","from":"20241208-mcp-tool-refactoring","to":"Basic_Memory_MCP","relationType":"improves"}
-{"type":"relation","from":"20241208-mcp-tool-refactoring","to":"Basic_Memory_Implementation_Plan","relationType":"implements"}

pyproject.toml

@@ -28,12 +28,12 @@ dependencies = [
     "watchfiles>=1.0.4",
     "fastapi[standard]>=0.115.8",
     "alembic>=1.14.1",
-    "qasync>=0.27.1",
     "pillow>=11.1.0",
     "pybars3>=0.9.7",
     "fastmcp>=2.3.4",
     "pyjwt>=2.10.1",
     "python-dotenv>=1.1.0",
+    "pytest-aio>=1.9.0",
 ]
 
 
@@ -69,14 +69,8 @@ dev-dependencies = [
     "pytest-cov>=4.1.0",
     "pytest-mock>=3.12.0",
     "pytest-asyncio>=0.24.0",
+    "pytest-xdist>=3.0.0",
     "ruff>=0.1.6",
-    "pytest>=8.3.4",
-    "pytest-cov>=4.1.0",
-    "pytest-mock>=3.12.0",
-    "pytest-asyncio>=0.24.0",
-    "ruff>=0.1.6",
-    "cx-freeze>=7.2.10",
-    "pyqt6>=6.8.1",
 ]
 
 [tool.hatch.version]
@@ -124,6 +118,8 @@ omit = [
     "*/background_sync.py",         # Background processes
     "*/cli/main.py",               # CLI entry point
     "*/mcp/tools/project_management.py",  # Covered by integration tests
+    "*/mcp/tools/sync_status.py",  # Covered by integration tests
+    "*/services/migration_service.py", # Complex migration scenarios
 ]
 
 [tool.logfire]

scripts/install.sh

@@ -1,36 +0,0 @@
-#!/bin/bash
-set -e
-
-echo "Welcome to Basic Memory installer"
-
-# 1. Install uv if not present
-if ! command -v uv &> /dev/null; then
-    echo "Installing uv package manager..."
-    curl -LsSf https://github.com/astral-sh/uv/releases/download/0.1.23/uv-installer.sh | sh
-fi
-
-# 2. Configure Claude Desktop
-echo "Configuring Claude Desktop..."
-CONFIG_FILE="$HOME/Library/Application Support/Claude/claude_desktop_config.json"
-
-# Create config directory if it doesn't exist
-mkdir -p "$(dirname "$CONFIG_FILE")"
-
-# If config file doesn't exist, create it with initial structure
-if [ ! -f "$CONFIG_FILE" ]; then
-    echo '{"mcpServers": {}}' > "$CONFIG_FILE"
-fi
-
-# Add/update the basic-memory config using jq
-jq '.mcpServers."basic-memory" = {
-    "command": "uvx",
-    "args": ["basic-memory"]
-}' "$CONFIG_FILE" > "$CONFIG_FILE.tmp" && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"
-
-echo "Installation complete! Basic Memory is now available in Claude Desktop."
-echo "Please restart Claude Desktop for changes to take effect."
-
-echo -e "\nQuick Start:"
-echo "1. You can run sync directly using: uvx basic-memory sync"
-echo "2. Optionally, install globally with: uv pip install basic-memory"
-echo -e "\nBuilt with ♥️ by Basic Machines."

src/basic_memory/__init__.py

@@ -1,9 +1,7 @@
 """basic-memory - Local-first knowledge management combining Zettelkasten with knowledge graphs"""
 
-try:
-    from importlib.metadata import version
+# Package version - updated by release automation
+__version__ = "0.14.0"
 
-    __version__ = version("basic-memory")
-except Exception:  # pragma: no cover
-    # Fallback if package not installed (e.g., during development)
-    __version__ = "0.0.0"  # pragma: no cover
+# API version for FastAPI - independent of package version
+__api_version__ = "v0"

src/basic_memory/alembic/env.py

@@ -8,12 +8,12 @@ from sqlalchemy import pool
 
 from alembic import context
 
-from basic_memory.models import Base
-
 # set config.env to "test" for pytest to prevent logging to file in utils.setup_logging()
 os.environ["BASIC_MEMORY_ENV"] = "test"
 
-from basic_memory.config import app_config
+# Import after setting environment variable  # noqa: E402
+from basic_memory.config import app_config  # noqa: E402
+from basic_memory.models import Base  # noqa: E402
 
 # this is the Alembic Config object, which provides
 # access to the values within the .ini file in use.

src/basic_memory/api/routers/knowledge_router.py

@@ -14,6 +14,7 @@ from basic_memory.deps import (
     FileServiceDep,
     ProjectConfigDep,
     AppConfigDep,
+    SyncServiceDep,
 )
 from basic_memory.schemas import (
     EntityListResponse,
@@ -63,6 +64,7 @@ async def create_or_update_entity(
     entity_service: EntityServiceDep,
     search_service: SearchServiceDep,
     file_service: FileServiceDep,
+    sync_service: SyncServiceDep,
 ) -> EntityResponse:
     """Create or update an entity. If entity exists, it will be updated, otherwise created."""
     logger.info(
@@ -85,6 +87,17 @@ async def create_or_update_entity(
 
     # reindex
     await search_service.index_entity(entity, background_tasks=background_tasks)
+
+    # Attempt immediate relation resolution when creating new entities
+    # This helps resolve forward references when related entities are created in the same session
+    if created:
+        try:
+            await sync_service.resolve_relations()
+            logger.debug(f"Resolved relations after creating entity: {entity.permalink}")
+        except Exception as e:  # pragma: no cover
+            # Don't fail the entire request if relation resolution fails
+            logger.warning(f"Failed to resolve relations after entity creation: {e}")
+
     result = EntityResponse.model_validate(entity)
 
     logger.info(

src/basic_memory/api/routers/memory_router.py

@@ -2,12 +2,11 @@
 
 from typing import Annotated, Optional
 
-from dateparser import parse
 from fastapi import APIRouter, Query
 from loguru import logger
 
 from basic_memory.deps import ContextServiceDep, EntityRepositoryDep
-from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.base import TimeFrame, parse_timeframe
 from basic_memory.schemas.memory import (
     GraphContext,
     normalize_memory_url,
@@ -40,7 +39,7 @@ async def recent(
         f"Getting recent context: `{types}` depth: `{depth}` timeframe: `{timeframe}` page: `{page}` page_size: `{page_size}` max_related: `{max_related}`"
     )
     # Parse timeframe
-    since = parse(timeframe)
+    since = parse_timeframe(timeframe)
     limit = page_size
     offset = (page - 1) * page_size
 
@@ -78,7 +77,7 @@ async def get_memory_context(
     memory_url = normalize_memory_url(uri)
 
     # Parse timeframe
-    since = parse(timeframe) if timeframe else None
+    since = parse_timeframe(timeframe) if timeframe else None
     limit = page_size
     offset = (page - 1) * page_size
 

src/basic_memory/api/routers/project_router.py

@@ -3,7 +3,7 @@
 from fastapi import APIRouter, HTTPException, Path, Body
 from typing import Optional
 
-from basic_memory.deps import ProjectServiceDep
+from basic_memory.deps import ProjectServiceDep, ProjectPathDep
 from basic_memory.schemas import ProjectInfoResponse
 from basic_memory.schemas.project_info import (
     ProjectList,
@@ -22,9 +22,10 @@ project_resource_router = APIRouter(prefix="/projects", tags=["project_managemen
 @project_router.get("/info", response_model=ProjectInfoResponse)
 async def get_project_info(
     project_service: ProjectServiceDep,
+    project: ProjectPathDep,
 ) -> ProjectInfoResponse:
-    """Get comprehensive information about the current Basic Memory project."""
-    return await project_service.get_project_info()
+    """Get comprehensive information about the specified Basic Memory project."""
+    return await project_service.get_project_info(project)
 
 
 # Update a project
@@ -47,7 +48,7 @@ async def update_project(
     """
     try:  # pragma: no cover
         # Get original project info for the response
-        old_project = ProjectItem(
+        old_project_info = ProjectItem(
             name=project_name,
             path=project_service.projects.get(project_name, ""),
         )
@@ -61,7 +62,7 @@ async def update_project(
             message=f"Project '{project_name}' updated successfully",
             status="success",
             default=(project_name == project_service.default_project),
-            old_project=old_project,
+            old_project=old_project_info,
             new_project=ProjectItem(name=project_name, path=updated_path),
         )
     except ValueError as e:  # pragma: no cover

src/basic_memory/api/routers/prompt_router.py

@@ -5,12 +5,12 @@ It centralizes all prompt formatting logic that was previously in the MCP prompt
 """
 
 from datetime import datetime, timezone
-from dateparser import parse
 from fastapi import APIRouter, HTTPException, status
 from loguru import logger
 
 from basic_memory.api.routers.utils import to_graph_context, to_search_results
 from basic_memory.api.template_loader import template_loader
+from basic_memory.schemas.base import parse_timeframe
 from basic_memory.deps import (
     ContextServiceDep,
     EntityRepositoryDep,
@@ -51,7 +51,7 @@ async def continue_conversation(
         f"Generating continue conversation prompt, topic: {request.topic}, timeframe: {request.timeframe}"
     )
 
-    since = parse(request.timeframe) if request.timeframe else None
+    since = parse_timeframe(request.timeframe) if request.timeframe else None
 
     # Initialize search results
     search_results = []

src/basic_memory/api/routers/utils.py

@@ -52,7 +52,7 @@ async def to_graph_context(
                     file_path=item.file_path,
                     permalink=item.permalink,  # pyright: ignore
                     relation_type=item.relation_type,  # pyright: ignore
-                    from_entity=from_entity.title,  # pyright: ignore
+                    from_entity=from_entity.title if from_entity else None,
                     to_entity=to_entity.title if to_entity else None,
                     created_at=item.created_at,
                 )

src/basic_memory/cli/commands/db.py

@@ -1,13 +1,14 @@
 """Database management commands."""
 
 import asyncio
+from pathlib import Path
 
 import typer
 from loguru import logger
 
 from basic_memory import db
 from basic_memory.cli.app import app
-from basic_memory.config import app_config
+from basic_memory.config import app_config, config_manager
 
 
 @app.command()
@@ -25,6 +26,12 @@ def reset(
             db_path.unlink()
             logger.info(f"Database file deleted: {db_path}")
 
+        # Reset project configuration
+        config_manager.config.projects = {"main": str(Path.home() / "basic-memory")}
+        config_manager.config.default_project = "main"
+        config_manager.save_config(config_manager.config)
+        logger.info("Project configuration reset to default")
+
         # Create a new empty database
         asyncio.run(db.run_migrations(app_config))
         logger.info("Database reset complete")

src/basic_memory/cli/commands/mcp.py

@@ -85,4 +85,5 @@ def mcp(
             host=host,
             port=port,
             path=path,
+            log_level="INFO",
         )

src/basic_memory/cli/commands/project.py

@@ -9,7 +9,6 @@ from rich.console import Console
 from rich.table import Table
 
 from basic_memory.cli.app import app
-from basic_memory.config import config
 from basic_memory.mcp.project_session import session
 from basic_memory.mcp.resources.project_info import project_info
 import json
@@ -24,6 +23,7 @@ from basic_memory.mcp.tools.utils import call_post
 from basic_memory.schemas.project_info import ProjectStatusResponse
 from basic_memory.mcp.tools.utils import call_delete
 from basic_memory.mcp.tools.utils import call_put
+from basic_memory.utils import generate_permalink
 
 console = Console()
 
@@ -44,11 +44,8 @@ def format_path(path: str) -> str:
 def list_projects() -> None:
     """List all configured projects."""
     # Use API to list projects
-
-    project_url = config.project_url
-
     try:
-        response = asyncio.run(call_get(client, f"{project_url}/project/projects"))
+        response = asyncio.run(call_get(client, "/projects/projects"))
         result = ProjectList.model_validate(response.json())
 
         table = Table(title="Basic Memory Projects")
@@ -65,7 +62,6 @@ def list_projects() -> None:
         console.print(table)
     except Exception as e:
         console.print(f"[red]Error listing projects: {str(e)}[/red]")
-        console.print("[yellow]Note: Make sure the Basic Memory server is running.[/yellow]")
         raise typer.Exit(1)
 
 
@@ -80,16 +76,14 @@ def add_project(
     resolved_path = os.path.abspath(os.path.expanduser(path))
 
     try:
-        project_url = config.project_url
         data = {"name": name, "path": resolved_path, "set_default": set_default}
 
-        response = asyncio.run(call_post(client, f"{project_url}/project/projects", json=data))
+        response = asyncio.run(call_post(client, "/projects/projects", json=data))
         result = ProjectStatusResponse.model_validate(response.json())
 
         console.print(f"[green]{result.message}[/green]")
     except Exception as e:
         console.print(f"[red]Error adding project: {str(e)}[/red]")
-        console.print("[yellow]Note: Make sure the Basic Memory server is running.[/yellow]")
         raise typer.Exit(1)
 
     # Display usage hint
@@ -105,15 +99,13 @@ def remove_project(
 ) -> None:
     """Remove a project from configuration."""
     try:
-        project_url = config.project_url
-
-        response = asyncio.run(call_delete(client, f"{project_url}/project/projects/{name}"))
+        project_name = generate_permalink(name)
+        response = asyncio.run(call_delete(client, f"/projects/{project_name}"))
         result = ProjectStatusResponse.model_validate(response.json())
 
         console.print(f"[green]{result.message}[/green]")
     except Exception as e:
         console.print(f"[red]Error removing project: {str(e)}[/red]")
-        console.print("[yellow]Note: Make sure the Basic Memory server is running.[/yellow]")
         raise typer.Exit(1)
 
     # Show this message regardless of method used
@@ -126,44 +118,33 @@ def set_default_project(
 ) -> None:
     """Set the default project and activate it for the current session."""
     try:
-        project_url = config.project_url
+        project_name = generate_permalink(name)
 
-        response = asyncio.run(call_put(client, f"{project_url}/project/projects/{name}/default"))
+        response = asyncio.run(call_put(client, f"/projects/{project_name}/default"))
         result = ProjectStatusResponse.model_validate(response.json())
 
         console.print(f"[green]{result.message}[/green]")
     except Exception as e:
         console.print(f"[red]Error setting default project: {str(e)}[/red]")
-        console.print("[yellow]Note: Make sure the Basic Memory server is running.[/yellow]")
         raise typer.Exit(1)
 
-    # Always activate it for the current session
-    os.environ["BASIC_MEMORY_PROJECT"] = name
-
-    # Reload configuration to apply the change
-    from importlib import reload
-    from basic_memory import config as config_module
-
-    reload(config_module)
-
+    # The API call above should have updated both config and MCP session
+    # No need for manual reload - the project service handles this automatically
     console.print("[green]Project activated for current session[/green]")
 
 
-@project_app.command("sync")
+@project_app.command("sync-config")
 def synchronize_projects() -> None:
-    """Synchronize projects between configuration file and database."""
+    """Synchronize project config between configuration file and database."""
     # Call the API to synchronize projects
 
-    project_url = config.project_url
-
     try:
-        response = asyncio.run(call_post(client, f"{project_url}/project/sync"))
+        response = asyncio.run(call_post(client, "/projects/sync"))
         result = ProjectStatusResponse.model_validate(response.json())
 
         console.print(f"[green]{result.message}[/green]")
     except Exception as e:  # pragma: no cover
         console.print(f"[red]Error synchronizing projects: {str(e)}[/red]")
-        console.print("[yellow]Note: Make sure the Basic Memory server is running.[/yellow]")
         raise typer.Exit(1)
 
 
@@ -174,7 +155,7 @@ def display_project_info(
     """Display detailed information and statistics about the current project."""
     try:
         # Get project info
-        info = asyncio.run(project_info())
+        info = asyncio.run(project_info.fn())  # type: ignore  # pyright: ignore [reportAttributeAccessIssue]
 
         if json_output:
             # Convert to JSON and print
@@ -221,7 +202,7 @@ def display_project_info(
                 console.print(entity_types_table)
 
             # Most connected entities
-            if info.statistics.most_connected_entities:
+            if info.statistics.most_connected_entities:  # pragma: no cover
                 connected_table = Table(title="🔗 Most Connected Entities")
                 connected_table.add_column("Title", style="blue")
                 connected_table.add_column("Permalink", style="cyan")
@@ -235,7 +216,7 @@ def display_project_info(
                 console.print(connected_table)
 
             # Recent activity
-            if info.activity.recently_updated:
+            if info.activity.recently_updated:  # pragma: no cover
                 recent_table = Table(title="🕒 Recent Activity")
                 recent_table.add_column("Title", style="blue")
                 recent_table.add_column("Type", style="cyan")

src/basic_memory/cli/commands/status.py

@@ -122,7 +122,7 @@ def display_changes(project_name: str, title: str, changes: SyncReport, verbose:
     console.print(Panel(tree, expand=False))
 
 
-async def run_status(verbose: bool = False):
+async def run_status(verbose: bool = False):  # pragma: no cover
     """Check sync status of files vs database."""
     # Check knowledge/ directory
 

src/basic_memory/cli/commands/sync.py

@@ -180,7 +180,7 @@ async def run_sync(verbose: bool = False):
     sync_service = await get_sync_service(project)
 
     logger.info("Running one-time sync")
-    knowledge_changes = await sync_service.sync(config.home)
+    knowledge_changes = await sync_service.sync(config.home, project_name=project.name)
 
     # Log results
     duration_ms = int((time.time() - start_time) * 1000)

src/basic_memory/cli/commands/tool.py

@@ -90,7 +90,7 @@ def write_note(
             typer.echo("Empty content provided. Please provide non-empty content.", err=True)
             raise typer.Exit(1)
 
-        note = asyncio.run(mcp_write_note(title, content, folder, tags))
+        note = asyncio.run(mcp_write_note.fn(title, content, folder, tags))
         rprint(note)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
@@ -103,7 +103,7 @@ def write_note(
 def read_note(identifier: str, page: int = 1, page_size: int = 10):
     """Read a markdown note from the knowledge base."""
     try:
-        note = asyncio.run(mcp_read_note(identifier, page, page_size))
+        note = asyncio.run(mcp_read_note.fn(identifier, page, page_size))
         rprint(note)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
@@ -124,7 +124,7 @@ def build_context(
     """Get context needed to continue a discussion."""
     try:
         context = asyncio.run(
-            mcp_build_context(
+            mcp_build_context.fn(
                 url=url,
                 depth=depth,
                 timeframe=timeframe,
@@ -157,7 +157,7 @@ def recent_activity(
     """Get recent activity across the knowledge base."""
     try:
         context = asyncio.run(
-            mcp_recent_activity(
+            mcp_recent_activity.fn(
                 type=type,  # pyright: ignore [reportArgumentType]
                 depth=depth,
                 timeframe=timeframe,
@@ -210,7 +210,7 @@ def search_notes(
         search_type = "text" if search_type is None else search_type
 
         results = asyncio.run(
-            mcp_search(
+            mcp_search.fn(
                 query,
                 search_type=search_type,
                 page=page,
@@ -241,7 +241,7 @@ def continue_conversation(
     """Prompt to continue a previous conversation or work session."""
     try:
         # Prompt functions return formatted strings directly
-        session = asyncio.run(mcp_continue_conversation(topic=topic, timeframe=timeframe))
+        session = asyncio.run(mcp_continue_conversation.fn(topic=topic, timeframe=timeframe))  # type: ignore
         rprint(session)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):

src/basic_memory/config.py

@@ -4,7 +4,7 @@ import json
 import os
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Dict, Literal, Optional, List
+from typing import Any, Dict, Literal, Optional, List, Tuple
 
 from loguru import logger
 from pydantic import Field, field_validator
@@ -45,7 +45,9 @@ class BasicMemoryConfig(BaseSettings):
     env: Environment = Field(default="dev", description="Environment name")
 
     projects: Dict[str, str] = Field(
-        default_factory=lambda: {"main": str(Path.home() / "basic-memory")},
+        default_factory=lambda: {
+            "main": str(Path(os.getenv("BASIC_MEMORY_HOME", Path.home() / "basic-memory")))
+        },
         description="Mapping of project names to their filesystem paths",
     )
     default_project: str = Field(
@@ -92,7 +94,9 @@ class BasicMemoryConfig(BaseSettings):
         """Ensure configuration is valid after initialization."""
         # Ensure main project exists
         if "main" not in self.projects:  # pragma: no cover
-            self.projects["main"] = str(Path.home() / "basic-memory")
+            self.projects["main"] = str(
+                Path(os.getenv("BASIC_MEMORY_HOME", Path.home() / "basic-memory"))
+            )
 
         # Ensure default project is valid
         if self.default_project not in self.projects:  # pragma: no cover
@@ -196,7 +200,8 @@ class ConfigManager:
 
     def add_project(self, name: str, path: str) -> ProjectConfig:
         """Add a new project to the configuration."""
-        if name in self.config.projects:  # pragma: no cover
+        project_name, _ = self.get_project(name)
+        if project_name:  # pragma: no cover
             raise ValueError(f"Project '{name}' already exists")
 
         # Ensure the path exists
@@ -209,10 +214,12 @@ class ConfigManager:
 
     def remove_project(self, name: str) -> None:
         """Remove a project from the configuration."""
-        if name not in self.config.projects:  # pragma: no cover
+
+        project_name, path = self.get_project(name)
+        if not project_name:  # pragma: no cover
             raise ValueError(f"Project '{name}' not found")
 
-        if name == self.config.default_project:  # pragma: no cover
+        if project_name == self.config.default_project:  # pragma: no cover
             raise ValueError(f"Cannot remove the default project '{name}'")
 
         del self.config.projects[name]
@@ -220,12 +227,21 @@ class ConfigManager:
 
     def set_default_project(self, name: str) -> None:
         """Set the default project."""
-        if name not in self.config.projects:  # pragma: no cover
+        project_name, path = self.get_project(name)
+        if not project_name:  # pragma: no cover
             raise ValueError(f"Project '{name}' not found")
 
         self.config.default_project = name
         self.save_config(self.config)
 
+    def get_project(self, name: str) -> Tuple[str, str] | Tuple[None, None]:
+        """Look up a project from the configuration by name or permalink"""
+        project_permalink = generate_permalink(name)
+        for name, path in app_config.projects.items():
+            if project_permalink == generate_permalink(name):
+                return name, path
+        return None, None
+
 
 def get_project_config(project_name: Optional[str] = None) -> ProjectConfig:
     """
@@ -256,11 +272,14 @@ def get_project_config(project_name: Optional[str] = None) -> ProjectConfig:
     # the config contains a dict[str,str] of project names and absolute paths
     assert actual_project_name is not None, "actual_project_name cannot be None"
 
-    project_path = app_config.projects.get(actual_project_name)
-    if not project_path:  # pragma: no cover
-        raise ValueError(f"Project '{actual_project_name}' not found")
+    project_permalink = generate_permalink(actual_project_name)
 
-    return ProjectConfig(name=actual_project_name, home=Path(project_path))
+    for name, path in app_config.projects.items():
+        if project_permalink == generate_permalink(name):
+            return ProjectConfig(name=name, home=Path(path))
+
+    # otherwise raise error
+    raise ValueError(f"Project '{actual_project_name}' not found")  # pragma: no cover
 
 
 # Create config manager

src/basic_memory/db.py

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

src/basic_memory/markdown/utils.py

@@ -38,7 +38,9 @@ def entity_model_from_markdown(
     # Update basic fields
     model.title = markdown.frontmatter.title
     model.entity_type = markdown.frontmatter.type
-    model.permalink = markdown.frontmatter.permalink
+    # Only update permalink if it exists in frontmatter, otherwise preserve existing
+    if markdown.frontmatter.permalink is not None:
+        model.permalink = markdown.frontmatter.permalink
     model.file_path = str(file_path)
     model.content_type = "text/markdown"
     model.created_at = markdown.created

src/basic_memory/mcp/project_session.py

@@ -8,7 +8,7 @@ from dataclasses import dataclass
 from typing import Optional
 from loguru import logger
 
-from basic_memory.config import ProjectConfig, get_project_config
+from basic_memory.config import ProjectConfig, get_project_config, config_manager
 
 
 @dataclass
@@ -64,6 +64,21 @@ class ProjectSession:
         self.current_project = self.default_project  # pragma: no cover
         logger.info(f"Reset project context to default: {self.default_project}")  # pragma: no cover
 
+    def refresh_from_config(self) -> None:
+        """Refresh session state from current configuration.
+
+        This method reloads the default project from config and reinitializes
+        the session. This should be called when the default project is changed
+        via CLI or API to ensure MCP session stays in sync.
+        """
+        # Reload config to get latest default project
+        current_config = config_manager.load_config()
+        new_default = current_config.default_project
+
+        # Reinitialize with new default
+        self.initialize(new_default)
+        logger.info(f"Refreshed project session from config, new default: {new_default}")
+
 
 # Global session instance
 session = ProjectSession()

src/basic_memory/mcp/prompts/__init__.py

@@ -10,10 +10,12 @@ from basic_memory.mcp.prompts import continue_conversation
 from basic_memory.mcp.prompts import recent_activity
 from basic_memory.mcp.prompts import search
 from basic_memory.mcp.prompts import ai_assistant_guide
+from basic_memory.mcp.prompts import sync_status
 
 __all__ = [
     "ai_assistant_guide",
     "continue_conversation",
     "recent_activity",
     "search",
+    "sync_status",
 ]

src/basic_memory/mcp/prompts/recent_activity.py

@@ -38,7 +38,7 @@ async def recent_activity_prompt(
     """
     logger.info(f"Getting recent activity, timeframe: {timeframe}")
 
-    recent = await recent_activity(timeframe=timeframe, type=[SearchItemType.ENTITY])
+    recent = await recent_activity.fn(timeframe=timeframe, type=[SearchItemType.ENTITY])
 
     # Extract primary results from the hierarchical structure
     primary_results = []

src/basic_memory/mcp/prompts/sync_status.py

@@ -0,0 +1,112 @@
+"""Sync status prompt for Basic Memory MCP server."""
+
+from basic_memory.mcp.server import mcp
+
+
+@mcp.prompt(
+    description="""Get sync status with recommendations for AI assistants.
+    
+    This prompt provides both current sync status and guidance on how
+    AI assistants should respond when sync operations are in progress or completed.
+    """,
+)
+async def sync_status_prompt() -> str:
+    """Get sync status with AI assistant guidance.
+    Returns:
+        Formatted sync status with AI assistant guidance
+    """
+    try:  # pragma: no cover
+        from basic_memory.services.migration_service import migration_manager
+
+        state = migration_manager.state
+
+        # Build status report
+        lines = [
+            "# Basic Memory Sync Status",
+            "",
+            f"**Current Status**: {state.status.value.replace('_', ' ').title()}",
+            f"**System Ready**: {'Yes' if migration_manager.is_ready else 'No'}",
+            "",
+        ]
+
+        if migration_manager.is_ready:
+            lines.extend(
+                [
+                    "✅ **All sync operations completed** - System is fully operational",
+                    "",
+                    "All Basic Memory tools are available and functioning normally.",
+                    "File indexing is complete and knowledge graphs are up to date.",
+                    "You can proceed with any knowledge management tasks.",
+                ]
+            )
+        else:
+            lines.append(f"**Status Message**: {state.message}")
+
+            if state.status.value == "in_progress":
+                if state.projects_total > 0:
+                    progress = f" ({state.projects_migrated}/{state.projects_total})"
+                    lines.append(f"**Progress**: {progress}")
+
+                lines.extend(
+                    [
+                        "",
+                        "🔄 **File synchronization in progress** - Processing files and building knowledge graphs",
+                        "",
+                        "**Impact**: Some tools may show status messages instead of normal responses",
+                        "until sync completes (usually 1-3 minutes).",
+                    ]
+                )
+
+            elif state.status.value == "failed":
+                lines.extend(
+                    [
+                        "",
+                        f"❌ **Sync failed**: {state.error or 'Unknown error'}",
+                        "",
+                        "**Impact**: System may have limited functionality until issue is resolved.",
+                    ]
+                )
+
+        # Add AI assistant recommendations
+        if not migration_manager.is_ready:
+            lines.extend(
+                [
+                    "",
+                    "---",
+                    "",
+                    "## AI Assistant Recommendations",
+                    "",
+                    "**When sync is in progress:**",
+                    "- Inform the user about the background file processing",
+                    "- Suggest using `sync_status()` tool to check progress",
+                    "- Explain that tools will work normally once sync completes",
+                    "- Avoid creating complex workflows until sync is done",
+                    "",
+                    "**What to tell users:**",
+                    "- 'Basic Memory is processing your files and building knowledge graphs'",
+                    "- 'This usually takes 1-3 minutes depending on your content size'",
+                    "- 'You can check progress anytime with the sync_status tool'",
+                    "- 'Full functionality will be available once processing completes'",
+                    "",
+                    "**User-friendly language:**",
+                    "- Say 'processing files' instead of 'migration' or 'sync'",
+                    "- Say 'building knowledge graphs' instead of 'indexing'",
+                    "- Say 'setting up your knowledge base' instead of 'running migrations'",
+                ]
+            )
+
+        return "\n".join(lines)
+
+    except Exception as e:  # pragma: no cover
+        return f"""# Sync Status - Error
+
+❌ **Unable to check sync status**: {str(e)}
+
+## AI Assistant Recommendations
+
+**When status is unavailable:**
+- Assume the system is likely working normally
+- Try proceeding with normal operations
+- If users report issues, suggest checking logs or restarting
+- Use user-friendly language about 'setting up the knowledge base'
+"""

src/basic_memory/mcp/server.py

@@ -31,23 +31,23 @@ load_dotenv()
 @dataclass
 class AppContext:
     watch_task: Optional[asyncio.Task]
+    migration_manager: Optional[Any] = None
 
 
 @asynccontextmanager
 async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:  # pragma: no cover
     """Manage application lifecycle with type-safe context"""
-    # Initialize on startup
-    watch_task = await initialize_app(app_config)
+    # Initialize on startup (now returns migration_manager)
+    migration_manager = await initialize_app(app_config)
 
     # Initialize project session with default project
     session.initialize(app_config.default_project)
 
     try:
-        yield AppContext(watch_task=watch_task)
+        yield AppContext(watch_task=None, migration_manager=migration_manager)
     finally:
-        # Cleanup on shutdown
-        if watch_task:
-            watch_task.cancel()
+        # Cleanup on shutdown - migration tasks will be cancelled automatically
+        pass
 
 
 # OAuth configuration function
@@ -105,6 +105,5 @@ auth_settings, auth_provider = create_auth_config()
 # Create the shared server instance
 mcp = FastMCP(
     name="Basic Memory",
-    log_level="DEBUG",
     auth=auth_provider,
 )

src/basic_memory/mcp/tools/__init__.py

@@ -11,12 +11,14 @@ from basic_memory.mcp.tools.read_content import read_content
 from basic_memory.mcp.tools.build_context import build_context
 from basic_memory.mcp.tools.recent_activity import recent_activity
 from basic_memory.mcp.tools.read_note import read_note
+from basic_memory.mcp.tools.view_note import view_note
 from basic_memory.mcp.tools.write_note import write_note
 from basic_memory.mcp.tools.search import search_notes
 from basic_memory.mcp.tools.canvas import canvas
 from basic_memory.mcp.tools.list_directory import list_directory
 from basic_memory.mcp.tools.edit_note import edit_note
 from basic_memory.mcp.tools.move_note import move_note
+from basic_memory.mcp.tools.sync_status import sync_status
 from basic_memory.mcp.tools.project_management import (
     list_projects,
     switch_project,
@@ -43,5 +45,7 @@ __all__ = [
     "search_notes",
     "set_default_project",
     "switch_project",
+    "sync_status",
+    "view_note",
     "write_note",
 ]

src/basic_memory/mcp/tools/build_context.py

@@ -13,7 +13,6 @@ from basic_memory.schemas.memory import (
     GraphContext,
     MemoryUrl,
     memory_url_path,
-    normalize_memory_url,
 )
 
 
@@ -21,12 +20,17 @@ from basic_memory.schemas.memory import (
     description="""Build context from a memory:// URI to continue conversations naturally.
     
     Use this to follow up on previous discussions or explore related topics.
+    
+    Memory URL Format:
+    - Use paths like "folder/note" or "memory://folder/note" 
+    - Pattern matching: "folder/*" matches all notes in folder
+    - Valid characters: letters, numbers, hyphens, underscores, forward slashes
+    - Avoid: double slashes (//), angle brackets (<>), quotes, pipes (|)
+    - Examples: "specs/search", "projects/basic-memory", "notes/*"
+    
     Timeframes support natural language like:
-    - "2 days ago"
-    - "last week" 
-    - "today"
-    - "3 months ago"
-    Or standard formats like "7d", "24h"
+    - "2 days ago", "last week", "today", "3 months ago"
+    - Or standard formats like "7d", "24h"
     """,
 )
 async def build_context(
@@ -76,9 +80,33 @@ async def build_context(
         build_context("memory://specs/search", project="work-project")
     """
     logger.info(f"Building context from {url}")
-    url = normalize_memory_url(url)
+    # URL is already validated and normalized by MemoryUrl type annotation
 
+    # Get the active project first to check project-specific sync status
     active_project = get_active_project(project)
+
+    # Check migration status and wait briefly if needed
+    from basic_memory.mcp.tools.utils import wait_for_migration_or_return_status
+
+    migration_status = await wait_for_migration_or_return_status(
+        timeout=5.0, project_name=active_project.name
+    )
+    if migration_status:  # pragma: no cover
+        # Return a proper GraphContext with status message
+        from basic_memory.schemas.memory import MemoryMetadata
+        from datetime import datetime
+
+        return GraphContext(
+            results=[],
+            metadata=MemoryMetadata(
+                depth=depth or 1,
+                timeframe=timeframe,
+                generated_at=datetime.now(),
+                primary_count=0,
+                related_count=0,
+                uri=migration_status,  # Include status in metadata
+            ),
+        )
     project_url = active_project.project_url
 
     response = await call_get(