feat: Automatically update Homebrew

Signed-off-by: Drew Cain <groksrc@users.noreply.github.com>

.claude/commands/check-health.md

@@ -0,0 +1,190 @@
+# /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

@@ -0,0 +1,62 @@
+# 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:
+- `just check` - Quality checks
+- `just test` - Test suite
+- `just update-deps` - Dependency updates  
+- `uv` - Package management
+- `git` - Version control
+- GitHub Actions - CI/CD pipeline

.claude/commands/lint-fix.md

@@ -0,0 +1,145 @@
+# /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

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

.claude/commands/release/changelog.md

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

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

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

.claude/commands/release/release.md

@@ -0,0 +1,92 @@
+# /release - Create Stable Release
+
+Create a stable release using the automated justfile target with comprehensive validation.
+
+## Usage
+```
+/release <version>
+```
+
+**Parameters:**
+- `version` (required): Release version like `v0.13.2`
+
+## Implementation
+
+You are an expert release manager for the Basic Memory project. When the user runs `/release`, execute the following steps:
+
+### Step 1: Pre-flight Validation
+1. Verify version format matches `v\d+\.\d+\.\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
+
+#### Documentation Validation
+1. **Changelog Check**
+   - CHANGELOG.md contains entry for target version
+   - Entry includes all major features and fixes
+   - Breaking changes are documented
+
+### Step 2: Use Justfile Automation
+Execute the automated release process:
+```bash
+just release <version>
+```
+
+The justfile target handles:
+- ✅ Version format validation
+- ✅ Git status and branch checks
+- ✅ Quality checks (`just check` - lint, format, type-check, tests)
+- ✅ Version update in `src/basic_memory/__init__.py`
+- ✅ Automatic commit with proper message
+- ✅ Tag creation and pushing to GitHub
+- ✅ Release workflow trigger
+
+### 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. 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 (if needed)
+- [ ] Version number follows semantic versioning
+
+## Error Handling
+- If `just release` fails, examine the error output for specific issues
+- If quality checks fail, fix issues and retry
+- If changelog entry missing, update CHANGELOG.md and commit before retrying
+- If GitHub Actions fail, check workflow logs for debugging
+
+## Success Output
+```
+🎉 Stable Release v0.13.2 Created Successfully!
+
+🏷️  Tag: v0.13.2
+📋 GitHub Release: https://github.com/basicmachines-co/basic-memory/releases/tag/v0.13.2
+📦 PyPI: https://pypi.org/project/basic-memory/0.13.2/
+🚀 GitHub Actions: Completed
+
+Install with:
+uv tool install basic-memory
+
+Users can now upgrade:
+uv tool upgrade basic-memory
+```
+
+## Context
+- This creates production releases used by end users
+- Must pass all quality gates before proceeding
+- Uses the automated justfile target for consistency
+- Version is automatically updated in `__init__.py`
+- Triggers automated GitHub release with changelog
+- Leverages uv-dynamic-versioning for package version management

.claude/commands/test-coverage.md

@@ -0,0 +1,131 @@
+# /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

@@ -0,0 +1,410 @@
+# /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.
+
+## Usage
+```
+/project:test-live [phase]
+```
+
+**Parameters:**
+- `phase` (optional): Specific test phase to run (`core`, `features`, `edge`, `workflows`, `stress`, or `all`)
+
+## 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:
+
+### Pre-Test Setup
+
+1. **Environment Verification**
+   - Verify basic-memory is installed and accessible via MCP
+   - Check version and confirm it's the expected release
+   - Test MCP connection and tool availability
+
+2. **Test Project Creation**
+
+Run the bash `date` command to get the current date/time. 
+
+   ```
+   Create project: "basic-memory-testing-[timestamp]"
+   Location: ~/basic-memory-testing-[timestamp]
+   Purpose: Record all test observations and results
+   ```
+
+Make sure to switch to the newly created project with the `switch_project()` tool.
+
+3. **Baseline Documentation**
+   Create initial test session note with:
+   - Test environment details
+   - Version being tested
+   - Test objectives and scope
+   - Start timestamp
+
+### Phase 1: Core Functionality Validation
+
+Test all fundamental MCP tools systematically:
+
+**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
+
+**read_note Tests:**
+- Read by title, permalink, memory:// URLs
+- Non-existent notes (error handling)
+- Notes with complex formatting
+- Performance with large notes
+
+**view_note Tests:**
+- View notes as formatted artifacts (Claude Desktop)
+- Title extraction from frontmatter and headings
+- Unicode and emoji content in artifacts
+- Error handling for non-existent notes
+- Artifact display quality and readability
+
+**search_notes Tests:**
+- Simple text queries
+- Tag-based searches 
+- Boolean operators and complex queries
+- Empty/no results scenarios
+- Performance with growing knowledge base
+
+**Recent Activity Tests:**
+- Various timeframes ("today", "1 week", "1d")
+- Type filtering (if available)
+- Empty project scenarios
+- Performance with many recent changes
+
+**Context Building Tests:**
+- Different depth levels (1, 2, 3+)
+- Various timeframes
+- Relation traversal accuracy
+- Performance with complex graphs
+
+### Phase 2: v0.13.0 Feature Deep Dive
+
+**Project Management:**
+- Create multiple projects dynamically
+- Switch between projects mid-conversation  
+- Cross-project operations
+- Project discovery and status
+- Default project behavior
+- Invalid project handling
+
+**Advanced Note Editing:**
+- `edit_note` with append operations
+- Prepend operations
+- Find/replace with validation
+- Section replacement under headers
+- Error scenarios (invalid operations)
+- Frontmatter preservation
+
+**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
+
+### Phase 3: Edge Case Exploration
+
+**Boundary Testing:**
+- Very long titles and content (stress limits)
+- Empty projects and notes
+- Unicode, emojis, special symbols
+- Deeply nested folder structures
+- Circular relations and self-references
+- Maximum relation depths
+
+**Error Scenarios:**
+- Invalid memory:// URLs
+- Missing files referenced in database
+- Invalid project names and paths
+- Malformed note structures
+- Concurrent operation conflicts
+
+**Performance Testing:**
+- Create 100+ notes rapidly
+- Complex search queries
+- Deep relation chains (5+ levels)
+- Rapid successive operations
+- Memory usage monitoring
+
+### Phase 4: Real-World Workflow Scenarios
+
+**Meeting Notes Pipeline:**
+1. Create meeting notes with action items
+2. Extract action items using edit_note
+3. Build relations to project documents
+4. Update progress incrementally
+5. Search and track completion
+
+**Research Knowledge Building:**
+1. Create research topic hierarchy
+2. Build complex relation networks
+3. Add incremental findings over time
+4. Search for connections and patterns
+5. Reorganize as knowledge evolves
+
+**Multi-Project Workflow:**
+1. Technical documentation project
+2. Personal recipe collection project
+3. Learning/course notes project
+4. Switch contexts during conversation
+5. Cross-reference related concepts
+
+**Content Evolution:**
+1. Start with basic notes
+2. Enhance with relations and observations
+3. Reorganize file structure using moves
+4. Update content with edit operations
+5. Validate knowledge graph integrity
+
+### Phase 5: Creative Stress Testing
+
+**Creative Exploration:**
+- Rapid project creation/switching patterns
+- Unusual but valid markdown structures
+- Creative observation categories
+- Novel relation types and patterns
+- Unexpected tool combinations
+
+**Stress Scenarios:**
+- Bulk operations (many notes quickly)
+- Complex nested moves and edits
+- Deep context building
+- Complex boolean search expressions
+- Resource constraint testing
+
+## Test Observation Format
+
+Record ALL observations immediately as Basic Memory notes:
+
+```markdown
+---
+title: Test Session [Phase] YYYY-MM-DD HH:MM
+tags: [testing, v0.13.0, live-testing, [phase]]
+permalink: test-session-[phase]-[timestamp]
+---
+
+# Test Session [Phase] - [Date/Time]
+
+## Environment
+- Basic Memory version: [version]
+- MCP connection: [status]
+- Test project: [name]
+- Phase focus: [description]
+
+## Test Results
+
+### ✅ Successful Operations
+- [timestamp] write_note: Created note with emoji title 📝 #functionality
+- [timestamp] search_notes: Boolean query returned 23 results in 0.4s #performance  
+- [timestamp] edit_note: Append operation preserved frontmatter #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
+
+### 🚀 Enhancements Identified
+- edit_note could benefit from preview mode #ux-improvement
+- search_notes needs fuzzy matching for typos #feature-idea
+- move_note could auto-suggest folder creation #usability
+
+### 📊 Performance Metrics
+- Average write_note time: 0.3s
+- Search with 100+ notes: 0.6s
+- Project switch overhead: 0.1s
+- Memory usage: [observed levels]
+
+## Relations
+- tests [[Basic Memory v0.13.0]]
+- part_of [[Live Testing Suite]]
+- found_issues [[Bug Report: Unicode Search]]
+- discovered [[Performance Optimization Opportunities]]
+```
+
+## Quality Assessment Areas
+
+**User Experience & Usability:**
+- Tool instruction clarity and examples
+- Error message actionability
+- Response time acceptability
+- Tool consistency and discoverability
+- Learning curve and intuitiveness
+
+**System Behavior:**
+- Context preservation across operations
+- memory:// URL navigation reliability
+- Multi-step workflow cohesion
+- Edge case graceful handling
+- Recovery from user errors
+
+**Documentation Alignment:**
+- Tool output clarity and helpfulness
+- Behavior vs. documentation accuracy
+- Example validity and usefulness
+- Real-world vs. documented workflows
+
+**Mental Model Validation:**
+- Natural user expectation alignment
+- Surprising behavior identification
+- Mistake recovery ease
+- Knowledge graph concept naturalness
+
+**Performance & Reliability:**
+- Operation completion times
+- Consistency across sessions
+- Scaling behavior with growth
+- Unexpected slowness identification
+
+## Error Documentation Protocol
+
+For each error discovered:
+
+1. **Immediate Recording**
+   - Create dedicated error note
+   - Include exact reproduction steps
+   - Capture error messages verbatim
+   - Note system state when error occurred
+
+2. **Error Note Format**
+   ```markdown
+   ---
+   title: Bug Report - [Short Description]
+   tags: [bug, testing, v0.13.0, [severity]]
+   ---
+   
+   # Bug Report: [Description]
+   
+   ## Reproduction Steps
+   1. [Exact steps to reproduce]
+   2. [Include all parameters used]
+   3. [Note any special conditions]
+   
+   ## Expected Behavior
+   [What should have happened]
+   
+   ## Actual Behavior  
+   [What actually happened]
+   
+   ## Error Messages
+   ```
+   [Exact error text]
+   ```
+   
+   ## Environment
+   - Version: [version]
+   - Project: [name]
+   - Timestamp: [when]
+   
+   ## Severity
+   - [ ] Critical (blocks major functionality)
+   - [ ] High (impacts user experience)
+   - [ ] Medium (workaround available)
+   - [ ] Low (minor inconvenience)
+   
+   ## Relations
+   - discovered_during [[Test Session [Phase]]]
+   - affects [[Feature Name]]
+   ```
+
+## Success Metrics Tracking
+
+**Quantitative Measures:**
+- Test scenario completion rate
+- Bug discovery count with severity
+- Performance benchmark establishment
+- Tool coverage completeness
+
+**Qualitative Measures:**
+- Conversation flow naturalness
+- Knowledge graph quality
+- User experience insights
+- System reliability assessment
+
+## Test Execution Flow
+
+1. **Setup Phase** (5 minutes)
+   - Verify environment and create test project
+   - Record baseline system state
+   - Establish performance benchmarks
+
+2. **Core Testing** (15-20 minutes per phase)
+   - Execute test scenarios systematically
+   - Record observations immediately
+   - Note timestamps for performance tracking
+   - Explore variations when interesting behaviors occur
+
+3. **Documentation** (5 minutes per phase)
+   - Create phase summary note
+   - Link related test observations
+   - Update running issues list
+   - Record enhancement ideas
+
+4. **Analysis Phase** (10 minutes)
+   - Review all observations across phases
+   - Identify patterns and trends
+   - Create comprehensive summary report
+   - Generate development recommendations
+
+## Expected Outcomes
+
+**System Validation:**
+- v0.13.0 feature verification in real usage
+- Edge case discovery beyond unit tests
+- Performance baseline establishment
+- Bug identification with reproduction cases
+
+**Knowledge Base Creation:**
+- Comprehensive testing documentation
+- Real usage examples for user guides
+- Edge case scenarios for future testing
+- Performance insights for optimization
+
+**Development Insights:**
+- Prioritized bug fix list
+- Enhancement ideas from real usage
+- Architecture validation results
+- User experience improvement areas
+
+## Post-Test Deliverables
+
+1. **Test Summary Note**
+   - Overall results and findings
+   - Critical issues requiring immediate attention
+   - Enhancement opportunities discovered
+   - System readiness assessment
+
+2. **Bug Report Collection**
+   - All discovered issues with reproduction steps
+   - Severity and impact assessments
+   - Suggested fixes where applicable
+
+3. **Performance Baseline**
+   - Timing data for all operations
+   - Scaling behavior observations
+   - Resource usage patterns
+
+4. **UX Improvement Recommendations**
+   - Usability enhancement suggestions
+   - Documentation improvement areas
+   - Tool design optimization ideas
+
+5. **Updated TESTING.md**
+   - Incorporate new test scenarios discovered
+   - Update based on real execution experience
+   - Add performance benchmarks and targets
+
+## Context
+- Uses installed basic-memory version (not development)
+- Tests complete MCP→API→DB→File stack
+- Creates living documentation in Basic Memory itself
+- Follows integration over isolation philosophy
+- Focuses on real usage patterns over checklist validation
+- Generates actionable insights for development team

.env.oauth.example

@@ -0,0 +1,55 @@
+# 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/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve Basic Memory
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Bug Description
+A clear and concise description of what the bug is.
+
+## Steps To Reproduce
+Steps to reproduce the behavior:
+1. Install version '...'
+2. Run command '...'
+3. Use tool/feature '...'
+4. See error
+
+## Expected Behavior
+A clear and concise description of what you expected to happen.
+
+## Actual Behavior
+What actually happened, including error messages and output.
+
+## Environment
+- OS: [e.g. macOS 14.2, Ubuntu 22.04]
+- Python version: [e.g. 3.12.1]
+- Basic Memory version: [e.g. 0.1.0]
+- Installation method: [e.g. pip, uv, source]
+- Claude Desktop version (if applicable):
+
+## Additional Context
+- Configuration files (if relevant)
+- Logs or screenshots
+- Any special configuration or environment variables
+
+## Possible Solution
+If you have any ideas on what might be causing the issue or how to fix it, please share them here.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Basic Memory Discussions
+    url: https://github.com/basicmachines-co/basic-memory/discussions
+    about: For questions, ideas, or more open-ended discussions
+  - name: Documentation
+    url: https://github.com/basicmachines-co/basic-memory#readme
+    about: Please check the documentation first before reporting an issue

.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,19 @@
+---
+name: Documentation improvement
+about: Suggest improvements or report issues with documentation
+title: '[DOCS] '
+labels: documentation
+assignees: ''
+---
+
+## Documentation Issue
+Describe what's missing, unclear, or incorrect in the current documentation.
+
+## Location
+Where is the problematic documentation? (URL, file path, or section)
+
+## Suggested Improvement
+How would you improve this documentation? Please be as specific as possible.
+
+## Additional Context
+Any additional information or screenshots that might help explain the issue or improvement.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,28 @@
+---
+name: Feature request
+about: Suggest an idea for Basic Memory
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## Feature Description
+A clear and concise description of the feature you'd like to see implemented.
+
+## Problem This Feature Solves
+Describe the problem or limitation you're experiencing that this feature would address.
+
+## Proposed Solution
+Describe how you envision this feature working. Include:
+- User workflow
+- Interface design (if applicable)
+- Technical approach (if you have ideas)
+
+## Alternative Solutions
+Have you considered any alternative solutions or workarounds?
+
+## Additional Context
+Add any other context, screenshots, or examples about the feature request here.
+
+## Impact
+How would this feature benefit you and other users of Basic Memory?

.github/dependabot.yml

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

.github/workflows/claude.yml

@@ -0,0 +1,114 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+    steps:
+      - name: Check user permissions
+        id: check_membership
+        uses: actions/github-script@v7
+        with:
+          script: |
+            let actor;
+            if (context.eventName === 'issue_comment') {
+              actor = context.payload.comment.user.login;
+            } else if (context.eventName === 'pull_request_review_comment') {
+              actor = context.payload.comment.user.login;
+            } else if (context.eventName === 'pull_request_review') {
+              actor = context.payload.review.user.login;
+            } else if (context.eventName === 'issues') {
+              actor = context.payload.issue.user.login;
+            }
+            
+            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 collaboration = await github.rest.repos.getCollaboratorPermissionLevel({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                username: actor
+              });
+              
+              const permission = collaboration.data.permission;
+              console.log(`User ${actor} has permission level: ${permission}`);
+              
+              // 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} does not have sufficient repository permissions (has: ${permission})`);
+              }
+            } catch (error) {
+              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
+        if: steps.check_membership.outputs.is_member == 'true'
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        if: steps.check_membership.outputs.is_member == 'true'
+        id: claude
+        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(just test),Bash(just lint),Bash(just format),Bash(just type-check),Bash(just check),Read,Write,Edit,MultiEdit,Glob,Grep,LS

.github/workflows/dev-release.yml

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

.github/workflows/release.yml

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

.github/workflows/test.yml

@@ -5,6 +5,12 @@ on:
     branches: [ "main" ]
   pull_request:
     branches: [ "main" ]
+  # pull_request_target runs on the BASE of the PR, not the merge result.
+  # It has write permissions and access to secrets.
+  # It's useful for PRs from forks or automated PRs but requires careful use for security reasons.
+  # See: https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target
+  pull_request_target:
+    branches: [ "main" ]
 
 jobs:
   test:
@@ -29,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
@@ -39,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,3 +42,14 @@ ENV/
 
 # macOS
 .DS_Store
+.coverage.*
+
+# obsidian docs:
+/docs/.obsidian/
+/examples/.obsidian/
+/examples/.basic-memory/
+
+
+# claude action
+claude-output
+**/.claude/settings.local.json

.mcp.json

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

AUTH.md

@@ -0,0 +1,42 @@
+# 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

CLA.md

@@ -0,0 +1,34 @@
+Developer Certificate of Origin
+Version 1.1
+https://developercertificate.org/
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+have the right to submit it under the open source license
+indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+of my knowledge, is covered under an appropriate open source
+license and I have the right under that license to submit that
+work with modifications, whether created in whole or in part
+by me, under the same open source license (unless I am
+permitted to submit under a different license), as indicated
+in the file; or
+
+(c) The contribution was provided directly to me by some other
+person who certified (a), (b) or (c) and I have not modified
+it.
+
+(d) I understand and agree that this project and the contribution
+are public and that a record of the contribution (including all
+personal information I submit with it, including my sign-off) is
+maintained indefinitely and may be redistributed consistent with
+this project or the open source license(s) involved.

CLAUDE.md

@@ -0,0 +1,255 @@
+# CLAUDE.md - Basic Memory Project Guide
+
+## Project Overview
+
+Basic Memory is a local-first knowledge management system built on the Model Context Protocol (MCP). It enables
+bidirectional communication between LLMs (like Claude) and markdown files, creating a personal knowledge graph that can
+be traversed using links between documents.
+
+## CODEBASE DEVELOPMENT
+
+### Project information
+
+See the [README.md](README.md) file for a project overview.
+
+### Build and Test Commands
+
+- 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: `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
+
+- Line length: 100 characters max
+- Python 3.12+ with full type annotations
+- Format with ruff (consistent styling)
+- Import order: standard lib, third-party, local imports
+- Naming: snake_case for functions/variables, PascalCase for classes
+- Prefer async patterns with SQLAlchemy 2.0
+- Use Pydantic v2 for data validation and schemas
+- CLI uses Typer for command structure
+- API uses FastAPI for endpoints
+- Follow the repository pattern for data access
+- Tools communicate to api routers via the httpx ASGI client (in process)
+- avoid using "private" functions in modules or classes (prepended with _)
+
+### Codebase Architecture
+
+- `/alembic` - Alembic db migrations
+- `/api` - FastAPI implementation of REST endpoints
+- `/cli` - Typer command-line interface
+- `/markdown` - Markdown parsing and processing
+- `/mcp` - Model Context Protocol server implementation
+- `/models` - SQLAlchemy ORM models
+- `/repository` - Data access layer
+- `/schemas` - Pydantic models for validation
+- `/services` - Business logic layer
+- `/sync` - File synchronization services
+
+### Development Notes
+
+- MCP tools are defined in src/basic_memory/mcp/tools/
+- MCP prompts are defined in src/basic_memory/mcp/prompts/
+- MCP tools should be atomic, composable operations
+- Use `textwrap.dedent()` for multi-line string formatting in prompts and tools
+- MCP Prompts are used to invoke tools and format content with instructions for an LLM
+- Schema changes require Alembic migrations
+- SQLite is used for indexing and full text search, files are source of truth
+- Testing uses pytest with asyncio support (strict mode)
+- Test database uses in-memory SQLite
+- Avoid creating mocks in tests in most circumstances.
+- Each test runs in a standalone environment with in memory SQLite and tmp_file directory
+- Do not use mocks in tests if possible. Tests run with an in memory sqlite db, so they are not needed. See fixtures in conftest.py
+
+## BASIC MEMORY PRODUCT USAGE
+
+### Knowledge Structure
+
+- Entity: Any concept, document, or idea represented as a markdown file
+- Observation: A categorized fact about an entity (`- [category] content`)
+- Relation: A directional link between entities (`- relation_type [[Target]]`)
+- Frontmatter: YAML metadata at the top of markdown files
+- Knowledge representation follows precise markdown format:
+    - Observations with [category] prefixes
+    - Relations with WikiLinks [[Entity]]
+    - Frontmatter with metadata
+
+### Basic Memory Commands
+
+- Sync knowledge: `basic-memory sync` or `basic-memory sync --watch`
+- Import from Claude: `basic-memory import claude conversations`
+- Import from ChatGPT: `basic-memory import chatgpt`
+- Import from Memory JSON: `basic-memory import memory-json`
+- Check sync status: `basic-memory status`
+- Tool access: `basic-memory tools` (provides CLI access to MCP tools)
+    - Guide: `basic-memory tools basic-memory-guide`
+    - Continue: `basic-memory tools continue-conversation --topic="search"`
+
+### MCP Capabilities
+
+- Basic Memory exposes these MCP tools to LLMs:
+
+  **Content Management:**
+    - `write_note(title, content, folder, tags)` - Create/update markdown notes with semantic observations and relations
+    - `read_note(identifier, page, page_size)` - Read notes by title, permalink, or memory:// URL with knowledge graph awareness
+    - `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")
+    - `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
+
+  **Visualization:**
+    - `canvas(nodes, edges, title, folder)` - Generate Obsidian canvas files for knowledge graph visualization
+
+- MCP Prompts for better AI interaction:
+    - `ai_assistant_guide()` - Guidance on effectively using Basic Memory tools for AI assistants
+    - `continue_conversation(topic, timeframe)` - Continue previous conversations with relevant historical context
+    - `search_notes(query, after_date)` - Search with detailed, formatted results for better context understanding
+    - `recent_activity(timeframe)` - View recently changed items with formatted output
+    - `json_canvas_spec()` - Full JSON Canvas specification for Obsidian visualization
+
+## AI-Human Collaborative Development
+
+Basic Memory emerged from and enables a new kind of development process that combines human and AI capabilities. Instead
+of using AI just for code generation, we've developed a true collaborative workflow:
+
+1. AI (LLM) writes initial implementation based on specifications and context
+2. Human reviews, runs tests, and commits code with any necessary adjustments
+3. Knowledge persists across conversations using Basic Memory's knowledge graph
+4. Development continues seamlessly across different AI sessions with consistent context
+5. Results improve through iterative collaboration and shared understanding
+
+This approach has allowed us to tackle more complex challenges and build a more robust system than either humans or AI
+could achieve independently.
+
+## GitHub Integration
+
+Basic Memory uses Claude directly into the development workflow through GitHub:
+
+### GitHub MCP Tools
+
+Using the GitHub Model Context Protocol server, Claude can:
+
+- **Repository Management**:
+    - View repository files and structure
+    - Read file contents
+    - Create new branches
+    - Create and update files
+
+- **Issue Management**:
+    - Create new issues
+    - Comment on existing issues
+    - Close and update issues
+    - Search across issues
+
+- **Pull Request Workflow**:
+    - Create pull requests
+    - Review code changes
+    - Add comments to PRs
+
+This integration enables Claude to participate as a full team member in the development process, not just as a code
+generation tool. Claude's GitHub account ([bm-claudeai](https://github.com/bm-claudeai)) is a member of the Basic
+Machines organization with direct contributor access to the codebase.
+
+### Collaborative Development Process
+
+With GitHub integration, the development workflow includes:
+
+1. **Direct code review** - Claude can analyze PRs and provide detailed feedback
+2. **Contribution tracking** - All of Claude's contributions are properly attributed in the Git history
+3. **Branch management** - Claude can create feature branches for implementations
+4. **Documentation maintenance** - Claude can keep documentation updated as the code evolves
+
+With this integration, the AI assistant is a full-fledged team member rather than just a tool for generating code
+snippets.
+
+
+### Basic Memory Pro
+
+Basic Memory Pro is a desktop GUI application that wraps the basic-memory CLI/MCP tools:
+
+- Built with Tauri (Rust), React (TypeScript), and a Python FastAPI sidecar
+- Provides visual knowledge graph exploration and project management
+- Uses the same core codebase but adds a desktop-friendly interface
+- Project configuration is shared between CLI and Pro versions
+- Multiple project support with visual switching interface
+
+local repo: /Users/phernandez/dev/basicmachines/basic-memory-pro
+github: https://github.com/basicmachines-co/basic-memory-pro
+
+## Release and Version Management
+
+Basic Memory uses `uv-dynamic-versioning` for automatic version management based on git tags:
+
+### Version Types
+- **Development versions**: Automatically generated from commits (e.g., `0.12.4.dev26+468a22f`)
+- **Beta releases**: Created by tagging with beta suffixes (e.g., `v0.13.0b1`, `v0.13.0rc1`)
+- **Stable releases**: Created by tagging with version numbers (e.g., `v0.13.0`)
+
+### Release Workflows
+
+#### Development Builds (Automatic)
+- Triggered on every push to `main` branch
+- Publishes dev versions like `0.12.4.dev26+468a22f` to PyPI
+- Allows continuous testing of latest changes
+- Users install with: `pip install basic-memory --pre --force-reinstall`
+
+#### Beta/RC Releases (Manual)
+- Create beta tag: `git tag v0.13.0b1 && git push origin v0.13.0b1`
+- Automatically builds and publishes to PyPI as pre-release
+- Users install with: `pip install basic-memory --pre`
+- Use for milestone testing before stable release
+
+#### 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`
+
+#### Homebrew Formula Updates
+- Automatically triggered after successful PyPI release
+- 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
+- **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

@@ -1,17 +1,199 @@
 # Contributing to Basic Memory
 
-Thank you for considering contributing to Basic Memory! Your help is greatly appreciated to improve this project.
+Thank you for considering contributing to Basic Memory! This document outlines the process for contributing to the
+project and how to get started as a developer.
 
-## How to Contribute
+## Getting Started
 
-1. **Fork the Repo**: Fork the repository and clone your copy.
-1. **Create a Branch**: Create a new branch for your feature or fix.
-1. **Test Your Changes**: Ensure tests pass locally and include new tests when necessary to ensure 100& test coverage.
-1. **Format Your Code**: Run `make format` to ensure code is formatted appropriately.
-4. **Submit a PR**: Submit a pull request with a detailed description of your changes.
+### Development Environment
 
-Thank You!
+1. **Clone the Repository**:
+   ```bash
+   git clone https://github.com/basicmachines-co/basic-memory.git
+   cd basic-memory
+   ```
+
+2. **Install Dependencies**:
+   ```bash
+   # Using just (recommended)
+   just install
+   
+   # Or using uv
+   uv install -e ".[dev]"
+   
+   # Or using pip
+   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
+   just test
+   # or
+   uv run pytest -p pytest_mock -v
+   
+   # Run a specific test
+   pytest tests/path/to/test_file.py::test_function_name
+   ```
+
+### Development Workflow
+
+1. **Fork the Repo**: Fork the repository on GitHub and clone your copy.
+2. **Create a Branch**: Create a new branch for your feature or fix.
+   ```bash
+   git checkout -b feature/your-feature-name
+   # or
+   git checkout -b fix/issue-you-are-fixing
+   ```
+3. **Make Your Changes**: Implement your changes with appropriate test coverage.
+4. **Check Code Quality**:
+   ```bash
+   # Run all checks at once
+   just check
+   
+   # Or run individual checks
+   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
+   just test
+   ```
+6. **Submit a PR**: Submit a pull request with a detailed description of your changes.
+
+## LLM-Assisted Development
+
+This project is designed for collaborative development between humans and LLMs (Large Language Models):
+
+1. **CLAUDE.md**: The repository includes a `CLAUDE.md` file that serves as a project guide for both humans and LLMs.
+   This file contains:
+    - Key project information and architectural overview
+    - Development commands and workflows
+    - Code style guidelines
+    - Documentation standards
+
+2. **AI-Human Collaborative Workflow**:
+    - We encourage using LLMs like Claude for code generation, reviews, and documentation
+    - When possible, save context in markdown files that can be referenced later
+    - This enables seamless knowledge transfer between different development sessions
+    - Claude can help with implementation details while you focus on architecture and design
+
+3. **Adding to CLAUDE.md**:
+    - If you discover useful project information or common commands, consider adding them to CLAUDE.md
+    - This helps all contributors (human and AI) maintain consistent knowledge of the project
+
+## Pull Request Process
+
+1. **Create a Pull Request**: Open a PR against the `main` branch with a clear title and description.
+2. **Sign the Developer Certificate of Origin (DCO)**: All contributions require signing our DCO, which certifies that
+   you have the right to submit your contributions. This will be automatically checked by our CLA assistant when you
+   create a PR.
+3. **PR Description**: Include:
+    - What the PR changes
+    - Why the change is needed
+    - How you tested the changes
+    - Any related issues (use "Fixes #123" to automatically close issues)
+4. **Code Review**: Wait for code review and address any feedback.
+5. **CI Checks**: Ensure all CI checks pass.
+6. **Merge**: Once approved, a maintainer will merge your PR.
+
+## Developer Certificate of Origin
+
+By contributing to this project, you agree to the [Developer Certificate of Origin (DCO)](CLA.md). This means you
+certify that:
+
+- You have the right to submit your contributions
+- You're not knowingly submitting code with patent or copyright issues
+- Your contributions are provided under the project's license (AGPL-3.0)
+
+This is a lightweight alternative to a Contributor License Agreement and helps ensure that all contributions can be
+properly incorporated into the project and potentially used in commercial applications.
+
+### Signing Your Commits
+
+Sign your commit:
+
+**Using the `-s` or `--signoff` flag**:
+
+```bash
+git commit -s -m "Your commit message"
+```
+
+This adds a `Signed-off-by` line to your commit message, certifying that you adhere to the DCO.
+
+The sign-off certifies that you have the right to submit your contribution under the project's license and verifies your
+agreement to the DCO.
+
+## Code Style Guidelines
+
+- **Python Version**: Python 3.12+ with full type annotations
+- **Line Length**: 100 characters maximum
+- **Formatting**: Use ruff for consistent styling
+- **Import Order**: Standard lib, third-party, local imports
+- **Naming**: Use snake_case for functions/variables, PascalCase for classes
+- **Documentation**: Add docstrings to public functions, classes, and methods
+- **Type Annotations**: Use type hints for all functions and methods
+
+## Testing Guidelines
+
+- **Coverage Target**: We aim for 100% test coverage for all code
+- **Test Framework**: Use pytest for unit and integration tests
+- **Mocking**: Use pytest-mock for mocking dependencies only when necessary
+- **Edge Cases**: Test both normal operation and edge cases
+- **Database Testing**: Use in-memory SQLite for testing database operations
+- **Fixtures**: Use async pytest fixtures for setup and teardown
+
+## Release Process
+
+Basic Memory uses automatic versioning based on git tags with `uv-dynamic-versioning`. Here's how releases work:
+
+### Version Management
+- **Development versions**: Automatically generated from git commits (e.g., `0.12.4.dev26+468a22f`)
+- **Beta releases**: Created by tagging with beta suffixes (e.g., `git tag v0.13.0b1`)
+- **Stable releases**: Created by tagging with version numbers (e.g., `git tag v0.13.0`)
+
+### Release Workflows
+
+#### Development Builds
+- Automatically published to PyPI on every commit to `main`
+- Version format: `0.12.4.dev26+468a22f` (base version + dev + commit count + hash)
+- Users install with: `pip install basic-memory --pre --force-reinstall`
+
+#### Beta Releases
+1. Create and push a beta tag: `git tag v0.13.0b1 && git push origin v0.13.0b1`
+2. GitHub Actions automatically builds and publishes to PyPI
+3. Users install with: `pip install basic-memory --pre`
+
+#### Stable Releases
+1. Create and push a version tag: `git tag v0.13.0 && git push origin v0.13.0`
+2. GitHub Actions automatically:
+   - Builds the package with version `0.13.0`
+   - Creates GitHub release with auto-generated notes
+   - Publishes to PyPI
+3. Users install with: `pip install basic-memory`
+
+### For Contributors
+- No manual version bumping required
+- Versions are automatically derived from git tags
+- Focus on code changes, not version management
+
+## Creating Issues
+
+If you're planning to work on something, please create an issue first to discuss the approach. Include:
+
+- A clear title and description
+- Steps to reproduce if reporting a bug
+- Expected behavior vs. actual behavior
+- Any relevant logs or screenshots
+- Your proposed solution, if you have one
 
 ## Code of Conduct
 
 All contributors must follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Thank You!
+
+Your contributions help make Basic Memory better. We appreciate your time and effort!

Dockerfile

@@ -0,0 +1,16 @@
+# Generated by https://smithery.ai. See: https://smithery.ai/docs/config#dockerfile
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Copy the project files
+COPY . .
+
+# Install pip and build dependencies
+RUN pip install --upgrade pip \
+&& pip install . --no-cache-dir --ignore-installed
+
+# Expose port if necessary (e.g., uv might use a port, but MCP over stdio so not needed here)
+
+# Use the basic-memory entrypoint to run the MCP server
+CMD ["basic-memory", "mcp"]

Makefile

@@ -1,42 +0,0 @@
-.PHONY: install test lint clean format type-check installer-mac installer-win
-
-install:
-	pip install -e ".[dev]"
-
-test:
-	pytest -p pytest_mock -v
-
-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-dev:
-	uv run mcp dev src/basic_memory/mcp/main.py
-
-# Build app installer
-installer-mac:
-	cd installer && uv run python setup.py bdist_mac
-
-installer-win:
-	cd installer && uv run python setup.py bdist_win32
-
-
-update-deps:
-	uv lock f--upgrade

README.md

@@ -1,258 +1,431 @@
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![PyPI version](https://badge.fury.io/py/basic-memory.svg)](https://badge.fury.io/py/basic-memory)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://github.com/basicmachines-co/basic-memory/workflows/Tests/badge.svg)](https://github.com/basicmachines-co/basic-memory/actions)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+![](https://badge.mcpx.dev?type=server 'MCP Server')
+![](https://badge.mcpx.dev?type=dev 'MCP Dev')
+[![smithery badge](https://smithery.ai/badge/@basicmachines-co/basic-memory)](https://smithery.ai/server/@basicmachines-co/basic-memory)
+
 # Basic Memory
 
 Basic Memory lets you build persistent knowledge through natural conversations with Large Language Models (LLMs) like
-Claude, while keeping everything in simple markdown files on your computer. It uses the Model Context Protocol (MCP) to
+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.
 
-## What is Basic Memory?
+- 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
 
-Most people use LLMs like calculators - paste in some text, expect to get an answer back, repeat. Each conversation
-starts fresh,
-and any knowledge or context is lost. Some try to work around this by:
+## Pick up your conversation right where you left off
 
-- Saving chat histories (but they're hard to reference)
-- Copying and pasting previous conversations (messy and repetitive)
-- Using RAG systems to query documents (complex and often cloud-based)
+- 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
 
-Basic Memory takes a different approach by letting both humans and LLMs read and write knowledge naturally using
-standard markdown files. This means:
+https://github.com/user-attachments/assets/a55d8238-8dd0-454a-be4c-8860dbbd0ddc
 
-- Your knowledge stays in files you control
-- Both you and the LLM can read and write notes
-- Context persists across conversations
-- Context stays local and user controlled
-
-## How It Works in Practice
-
-Let's say you're working on a new project and want to capture design decisions. Here's how it works:
-
-1. Start by chatting normally:
-
-```markdown
-We need to design a new auth system, some key features:
-
-- local first, don't delegate users to third party system
-- support multiple platforms via jwt
-- want to keep it simple but secure
-```
-
-... continue conversation.
-
-2. Ask Claude to help structure this knowledge:
-
-```
-"Lets write a note about the auth system design."
-```
-
-Claude creates a new markdown file on your system (which you can see instantly in Obsidian or your editor):
-
-```markdown
----
-title: Auth System Design
-permalink: auth-system-design
-tags
-- design
-- auth
----
-
-# Auth System Design
-
-## Observations
-
-- [requirement] Local-first authentication without third party delegation
-- [tech] JWT-based auth for cross-platform support
-- [principle] Balance simplicity with security
-
-## Relations
-
-- implements [[Security Requirements]]
-- relates_to [[Platform Support]]
-- referenced_by [[JWT Implementation]]
-```
-
-The note embeds semantic content (Observations) and links to other topics (Relations) via simple markdown formatting.
-
-3. You can edit this file directly in your editor in real time:
-
-```markdown
-# Auth System Design
-
-## Observations
-
-- [requirement] Local-first authentication without third party delegation
-- [tech] JWT-based auth for cross-platform support
-- [principle] Balance simplicity with security
-- [decision] Will use bcrypt for password hashing # Added by you
-
-## Relations
-
-- implements [[Security Requirements]]
-- relates_to [[Platform Support]]
-- referenced_by [[JWT Implementation]]
-- blocks [[User Service]]  # Added by you
-```
-
-4. In a new chat with Claude, you can reference this knowledge:
-
-```
-"Claude, look at memory://auth-system-design for context about our auth system"
-```
-
-Claude can now build rich context from the knowledge graph. For example:
-
-```
-Following relation 'implements [[Security Requirements]]':
-- Found authentication best practices
-- OWASP guidelines for JWT
-- Rate limiting requirements
-
-Following relation 'relates_to [[Platform Support]]':
-- Mobile auth requirements 
-- Browser security considerations
-- JWT storage strategies
-```
-
-Each related document can lead to more context, building a rich semantic understanding of your knowledge base. All of
-this context comes from standard markdown files that both humans and LLMs can read and write.
-
-Everything stays in local markdown files that you can:
-
-- Edit in any text editor
-- Version via git
-- Back up normally
-- Share when you want to
-
-## Technical Implementation
-
-Under the hood, Basic Memory:
-
-1. Stores everything in markdown files
-2. Uses a SQLite database just for searching and indexing
-3. Extracts semantic meaning from simple markdown patterns
-4. Maintains a local knowledge graph from file content
-
-The file format is just markdown with some simple markup:
-
-Frontmatter
-
-- title
-- type
-- permalink
-- optional metadata
-
-Observations
-
-- facts about a topic
-
-```markdown
-- [category] content #tag (optional context)
-```
-
-Relations
-
-- links to other topics
-
-```markdown
-- relation_type [[WikiLink]] (optional context)
-```
-
-Example:
-
-```markdown
----
-title: Note tile
-type: note
-permalink: unique/stable/id  # Added automatically
-tags
-- tag1
-- tag2
----
-
-# Note Title
-
-Regular markdown content...
-
-## Observations
-
-- [category] Structured knowledge #tag (optional context)
-- [idea] Another observation
-
-## Relations
-
-- links_to [[Other Note]]
-- implements [[Some Spec]]
-```
-
-Basic Memory will parse the markdown and derive the semantic relationships in the content. When you run
-`basic-memory sync`:
-
-1. New and changed files are detected
-2. Markdown patterns become semantic knowledge:
-
-- `[tech]` becomes a categorized observation
-- `[[WikiLink]]` creates a relation in the knowledge graph
-- Tags and metadata are indexed for search
-
-3. A SQLite database maintains these relationships for fast querying
-4. Claude and other MCP-compatible LLMs can access this knowledge via memory:// URLs
-
-This creates a two-way flow where:
-
-- Humans write and edit markdown files
-- LLMs read and write through the MCP protocol
-- Sync keeps everything consistent
-- All knowledge stays in local files.
-
-## Using with Claude
-
-Basic Memory works with the Claude desktop app (https://claude.ai/):
-
-1. Install Basic Memory locally:
+## Quick Start
 
 ```bash
+# Install with uv (recommended)
+uv tool install basic-memory
+
+# Configure Claude Desktop (edit ~/Library/Application Support/Claude/claude_desktop_config.json)
+# Add this to your config:
 {
   "mcpServers": {
     "basic-memory": {
       "command": "uvx",
       "args": [
-        "basic-memory"
+        "basic-memory",
+        "mcp"
       ]
     }
+  }
+}
+# Now in Claude Desktop, you can:
+# - Write notes with "Create a note about coffee brewing methods"
+# - Read notes with "What do I know about pour over coffee?"
+# - Search with "Find information about Ethiopian beans"
+
+```
+
+You can view shared context via files in `~/basic-memory` (default directory location).
+
+### Alternative Installation via Smithery
+
+You can use [Smithery](https://smithery.ai/server/@basicmachines-co/basic-memory) to automatically configure Basic
+Memory for Claude Desktop:
+
+```bash
+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. Note: The Smithery installation uses their hosted MCP server, while your data remains stored locally as Markdown files.
+
+### Glama.ai
+
+<a href="https://glama.ai/mcp/servers/o90kttu9ym">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/o90kttu9ym/badge" alt="basic-memory MCP server" />
+</a>
+
+## Why Basic Memory?
+
+Most LLM interactions are ephemeral - you ask a question, get an answer, and everything is forgotten. Each conversation
+starts fresh, without the context or knowledge from previous ones. Current workarounds have limitations:
+
+- Chat histories capture conversations but aren't structured knowledge
+- RAG systems can query documents but don't let LLMs write back
+- Vector databases require complex setups and often live in the cloud
+- Knowledge graphs typically need specialized tools to maintain
+
+Basic Memory addresses these problems with a simple approach: structured Markdown files that both humans and LLMs can
+read
+and write to. The key advantages:
+
+- **Local-first:** All knowledge stays in files you control
+- **Bi-directional:** Both you and the LLM read and write to the same files
+- **Structured yet simple:** Uses familiar Markdown with semantic patterns
+- **Traversable knowledge graph:** LLMs can follow links between topics
+- **Standard formats:** Works with existing editors like Obsidian
+- **Lightweight infrastructure:** Just local files indexed in a local SQLite database
+
+With Basic Memory, you can:
+
+- Have conversations that build on previous knowledge
+- Create structured notes during natural conversations
+- Have conversations with LLMs that remember what you've discussed before
+- Navigate your knowledge graph semantically
+- Keep everything local and under your control
+- Use familiar tools like Obsidian to view and edit notes
+- Build a personal knowledge base that grows over time
+
+## How It Works in Practice
+
+Let's say you're exploring coffee brewing methods and want to capture your knowledge. Here's how it works:
+
+1. Start by chatting normally:
+
+```
+I've been experimenting with different coffee brewing methods. Key things I've learned:
+
+- Pour over gives more clarity in flavor than French press
+- Water temperature is critical - around 205°F seems best
+- Freshly ground beans make a huge difference
+```
+
+... continue conversation.
+
+2. Ask the LLM to help structure this knowledge:
+
+```
+"Let's write a note about coffee brewing methods."
+```
+
+LLM creates a new Markdown file on your system (which you can see instantly in Obsidian or your editor):
+
+```markdown
+---
+title: Coffee Brewing Methods
+permalink: coffee-brewing-methods
+tags:
+- coffee
+- brewing
+---
+
+# Coffee Brewing Methods
+
+## Observations
+
+- [method] Pour over provides more clarity and highlights subtle flavors
+- [technique] Water temperature at 205°F (96°C) extracts optimal compounds
+- [principle] Freshly ground beans preserve aromatics and flavor
+
+## Relations
+
+- relates_to [[Coffee Bean Origins]]
+- requires [[Proper Grinding Technique]]
+- affects [[Flavor Extraction]]
+```
+
+The note embeds semantic content and links to other topics via simple Markdown formatting.
+
+3. You see this file on your computer in real time in the current project directory (default `~/$HOME/basic-memory`).
+
+- 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:
+
+```
+Look at `coffee-brewing-methods` for context about pour over coffee
+```
+
+The LLM can now build rich context from the knowledge graph. For example:
+
+```
+Following relation 'relates_to [[Coffee Bean Origins]]':
+- Found information about Ethiopian Yirgacheffe
+- Notes on Colombian beans' nutty profile
+- Altitude effects on bean characteristics
+
+Following relation 'requires [[Proper Grinding Technique]]':
+- Burr vs. blade grinder comparisons
+- Grind size recommendations for different methods
+- Impact of consistent particle size on extraction
+```
+
+Each related document can lead to more context, building a rich semantic understanding of your knowledge base.
+
+This creates a two-way flow where:
+
+- Humans write and edit Markdown files
+- LLMs read and write through the MCP protocol
+- Sync keeps everything consistent
+- All knowledge stays in local files.
+
+## Technical Implementation
+
+Under the hood, Basic Memory:
+
+1. Stores everything in Markdown files
+2. Uses a SQLite database for searching and indexing
+3. Extracts semantic meaning from simple Markdown patterns
+    - Files become `Entity` objects
+    - Each `Entity` can have `Observations`, or facts associated with it
+    - `Relations` connect entities together to form the knowledge graph
+4. Maintains the local knowledge graph derived from the files
+5. Provides bidirectional synchronization between files and the knowledge graph
+6. Implements the Model Context Protocol (MCP) for AI integration
+7. Exposes tools that let AI assistants traverse and manipulate the knowledge graph
+8. Uses memory:// URLs to reference entities across tools and conversations
+
+The file format is just Markdown with some simple markup:
+
+Each Markdown file has:
+
+### Frontmatter
+
+```markdown
+title: <Entity title>
+type: <The type of Entity> (e.g. note)
+permalink: <a uri slug>
+
+- <optional metadata> (such as tags) 
+```
+
+### Observations
+
+Observations are facts about a topic.
+They can be added by creating a Markdown list with a special format that can reference a `category`, `tags` using a
+"#" character, and an optional `context`.
+
+Observation Markdown format:
+
+```markdown
+- [category] content #tag (optional context)
+```
+
+Examples of observations:
+
+```markdown
+- [method] Pour over extracts more floral notes than French press
+- [tip] Grind size should be medium-fine for pour over #brewing
+- [preference] Ethiopian beans have bright, fruity flavors (especially from Yirgacheffe)
+- [fact] Lighter roasts generally contain more caffeine than dark roasts
+- [experiment] Tried 1:15 coffee-to-water ratio with good results
+- [resource] James Hoffman's V60 technique on YouTube is excellent
+- [question] Does water temperature affect extraction of different compounds differently?
+- [note] My favorite local shop uses a 30-second bloom time
+```
+
+### Relations
+
+Relations are links to other topics. They define how entities connect in the knowledge graph.
+
+Markdown format:
+
+```markdown
+- relation_type [[WikiLink]] (optional context)
+```
+
+Examples of relations:
+
+```markdown
+- pairs_well_with [[Chocolate Desserts]]
+- grown_in [[Ethiopia]]
+- contrasts_with [[Tea Brewing Methods]]
+- requires [[Burr Grinder]]
+- improves_with [[Fresh Beans]]
+- relates_to [[Morning Routine]]
+- inspired_by [[Japanese Coffee Culture]]
+- documented_in [[Coffee Journal]]
+```
+
+## Using with VS Code
+For one-click installation, click one of the install buttons below...
+
+[![Install with UV in VS Code](https://img.shields.io/badge/VS_Code-UV-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=basic-memory&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22basic-memory%22%2C%22mcp%22%5D%7D) [![Install with UV in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-UV-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=basic-memory&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22basic-memory%22%2C%22mcp%22%5D%7D&quality=insiders)
+
+You can use Basic Memory with VS Code to easily retrieve and store information while coding. Click the installation buttons above for one-click setup, or follow the manual installation instructions below.
+
+### Manual Installation
+
+Add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "basic-memory": {
+        "command": "uvx",
+        "args": ["basic-memory", "mcp"]
+      }
+    }
+  }
 }
 ```
 
-2. Add to Claude Desktop:
+Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
 
-```
-Basic Memory is available with these tools:
-- write_note() for creating/updating notes
-- read_note() for loading notes
-- build_context() to load notes via memory:// URLs
-- recent_activity() to find recently updated information
-- search() to search infomation in the knowledge base
+```json
+{
+  "servers": {
+    "basic-memory": {
+      "command": "uvx",
+      "args": ["basic-memory", "mcp"]
+    }
+  }
+}
 ```
 
-3. Install via uv
+## Using with Claude Desktop
 
+Basic Memory is built using the MCP (Model Context Protocol) and works with the Claude desktop app (https://claude.ai/):
+
+1. Configure Claude Desktop to use Basic Memory:
+
+Edit your MCP configuration file (usually located at `~/Library/Application Support/Claude/claude_desktop_config.json`
+for OS X):
+
+```json
+{
+  "mcpServers": {
+    "basic-memory": {
+      "command": "uvx",
+      "args": [
+        "basic-memory",
+        "mcp"
+      ]
+    }
+  }
+}
+```
+
+If you want to use a specific project (see [Multiple Projects](docs/User%20Guide.md#multiple-projects)), update your
+Claude Desktop
+config:
+
+```json
+{
+  "mcpServers": {
+    "basic-memory": {
+      "command": "uvx",
+      "args": [
+        "basic-memory",
+        "--project",
+        "your-project-name",
+        "mcp"
+      ]
+    }
+  }
+}
+```
+
+2. Sync your knowledge:
+
+Basic Memory will sync the files in your project in real time if you make manual edits.
+
+3. In Claude Desktop, the LLM can now use these tools:
+
+```
+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:
+
+```
+"Create a note about our project architecture decisions"
+"Find information about JWT authentication in my notes"
+"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
+
+See the [Documentation](https://memory.basicmachines.co/) for more info, including:
+
+- [Complete User Guide](https://memory.basicmachines.co/docs/user-guide)
+- [CLI tools](https://memory.basicmachines.co/docs/cli-reference)
+- [Managing multiple Projects](https://memory.basicmachines.co/docs/cli-reference#project)
+- [Importing data from OpenAI/Claude Projects](https://memory.basicmachines.co/docs/cli-reference#import)
+
+## Installation Options
+
+### Stable Release
 ```bash
-uv add  basic-memory
-
-# sync local knowledge updates
-basic-memory sync
-
-# run realtime sync process
-basic-memory sync --watch
+pip install basic-memory
 ```
 
-## Design Philosophy
+### Beta/Pre-releases
+```bash
+pip install basic-memory --pre
+```
 
-Basic Memory is built on some key ideas:
-
-- Your knowledge should stay in files you control
-- Both humans and AI should use natural formats
-- Simple text patterns can capture rich meaning
-- Local-first doesn't mean feature-poor
+### Development Builds
+Development versions are automatically published on every commit to main with versions like `0.12.4.dev26+468a22f`:
+```bash
+pip install basic-memory --pre --force-reinstall
+```
 
 ## License
 
-AGPL-3.0
+AGPL-3.0
+
+Contributions are welcome. See the [Contributing](CONTRIBUTING.md) guide for info about setting up the project locally
+and submitting PRs.
+
+## Star History
+
+<a href="https://www.star-history.com/#basicmachines-co/basic-memory&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=basicmachines-co/basic-memory&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=basicmachines-co/basic-memory&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=basicmachines-co/basic-memory&type=Date" />
+ </picture>
+</a>
+
+Built with ♥️ by Basic Machines

SECURITY.md

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

docs/AI Assistant Guide.md

@@ -0,0 +1,431 @@
+---
+title: AI Assistant Guide
+type: note
+permalink: docs/ai-assistant-guide
+---
+> Note: This is an optional document that can be copy/pasted into the project knowledge for an LLM to provide a full description of how it can work with Basic Memory. It is provided as a helpful resource. The tools contain extensive usage description prompts with enable the LLM to understand them. 
+
+You can [download](https://github.com/basicmachines-co/basic-memory/blob/main/docs/AI%20Assistant%20Guide.md) the contents of this file from GitHub
+# AI Assistant Guide for Basic Memory
+
+This guide helps you, the AI assistant, use Basic Memory tools effectively when working with users. It covers reading, writing, and navigating knowledge through the Model Context Protocol (MCP).
+
+## Quick Reference
+
+**Essential Tools:**
+- `write_note()` - Create/update notes (primary tool)
+- `read_note()` - Read existing content
+- `search_notes()` - Find information
+- `edit_note()` - Modify existing notes incrementally (v0.13.0)
+- `move_note()` - Organize files with database consistency (v0.13.0)
+
+**Project Management (v0.13.0):**
+- `list_projects()` - Show available projects
+- `switch_project()` - Change active project
+- `get_current_project()` - Current project info
+
+**Key Principles:**
+1. **Build connections** - Rich knowledge graphs > isolated notes
+2. **Ask permission** - "Would you like me to record this?"
+3. **Use exact titles** - For accurate `[[WikiLinks]]`
+4. **Leverage v0.13.0** - Edit incrementally, organize proactively, switch projects contextually
+
+## Overview
+
+Basic Memory allows you and users to record context in local Markdown files, building a rich knowledge base through natural conversations. The system automatically creates a semantic knowledge graph from simple text patterns.
+
+- **Local-First**: All data is stored in plain text files on the user's computer
+- **Real-Time**: Users see content updates immediately
+- **Bi-Directional**: Both you and users can read and edit notes
+- **Semantic**: Simple patterns create a structured knowledge graph
+- **Persistent**: Knowledge persists across sessions and conversations
+
+## The Importance of the Knowledge Graph
+
+Basic Memory's value comes from connections between notes, not just the notes themselves. When writing notes, your primary goal should be creating a rich, interconnected knowledge graph.
+
+When creating content, focus on:
+
+1. **Increasing Semantic Density**: Add multiple observations and relations to each note
+2. **Using Accurate References**: Aim to reference existing entities by their exact titles
+3. **Creating Forward References**: Feel free to reference entities that don't exist yet - Basic Memory will resolve these when they're created later
+4. **Creating Bidirectional Links**: When appropriate, connect entities from both directions
+5. **Using Meaningful Categories**: Add semantic context with appropriate observation categories
+6. **Choosing Precise Relations**: Use specific relation types that convey meaning
+
+Remember that a knowledge graph with 10 heavily connected notes is more valuable than 20 isolated notes. Your job is to help build these connections.
+
+## Core Tools Reference
+
+### Essential Content Management
+
+**Writing knowledge** (most important tool):
+```
+write_note(
+    title="Search Design",
+    content="# Search Design\n...",
+    folder="specs",                     # Optional
+    tags=["search", "design"],          # v0.13.0: now searchable!
+    project="work-notes"                # v0.13.0: target specific project
+)
+```
+
+**Reading knowledge:**
+```
+read_note("Search Design")              # By title
+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",         # 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",              # 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)
+
+```
+list_projects()                         # Show available projects
+switch_project("work-notes")            # Change active project
+get_current_project()                   # Current project info
+```
+
+### Search & Discovery
+
+```
+search_notes("authentication system")   # v0.13.0: includes frontmatter tags
+build_context("memory://specs/search")  # Follow knowledge graph connections
+recent_activity(timeframe="1 week")     # Check what's been updated
+```
+
+## memory:// URLs Explained
+
+Basic Memory uses a special URL format to reference entities in the knowledge graph:
+
+- `memory://title` - Reference by title
+- `memory://folder/title` - Reference by folder and title 
+- `memory://permalink` - Reference by permalink
+- `memory://path/relation_type/*` - Follow all relations of a specific type
+- `memory://path/*/target` - Find all entities with relations to target
+
+## Semantic Markdown Format
+
+Knowledge is encoded in standard markdown using simple patterns:
+
+**Observations** - Facts about an entity:
+```markdown
+- [category] This is an observation #tag1 #tag2 (optional context)
+```
+
+**Relations** - Links between entities:
+```markdown
+- relation_type [[Target Entity]] (optional context)
+```
+
+**Common Categories & Relation Types:**
+- Categories: `[idea]`, `[decision]`, `[question]`, `[fact]`, `[requirement]`, `[technique]`, `[recipe]`, `[preference]`
+- Relations: `relates_to`, `implements`, `requires`, `extends`, `part_of`, `pairs_with`, `inspired_by`, `originated_from`
+
+## When to Record Context
+
+**Always consider recording context when**:
+
+1. Users make decisions or reach conclusions
+2. Important information emerges during conversation
+3. Multiple related topics are discussed
+4. The conversation contains information that might be useful later
+5. Plans, tasks, or action items are mentioned
+
+**Protocol for recording context**:
+
+1. Identify valuable information in the conversation
+2. Ask the user: "Would you like me to record our discussion about [topic] in Basic Memory?"
+3. If they agree, use `write_note` to capture the information
+4. If they decline, continue without recording
+5. Let the user know when information has been recorded: "I've saved our discussion about [topic] to Basic Memory."
+
+## Understanding User Interactions
+
+Users will interact with Basic Memory in patterns like:
+
+1. **Creating knowledge**:
+   ```
+   Human: "Let's write up what we discussed about search."
+   
+   You: I'll create a note capturing our discussion about the search functionality.
+   [Use write_note() to record the conversation details]
+   ```
+
+2. **Referencing existing knowledge**:
+   ```
+   Human: "Take a look at memory://specs/search"
+   
+   You: I'll examine that information.
+   [Use build_context() to gather related information]
+   [Then read_note() to access specific content]
+   ```
+
+3. **Finding information**:
+   ```
+   Human: "What were our decisions about auth?"
+   
+   You: Let me find that information for you.
+   [Use search_notes() to find relevant notes]
+   [Then build_context() to understand connections]
+   ```
+
+4. **Editing existing notes (v0.13.0)**:
+   ```
+   Human: "Add a section about deployment to my API documentation"
+   
+   You: I'll add that section to your existing documentation.
+   [Use edit_note() with operation="append" to add new content]
+   ```
+
+5. **Project management (v0.13.0)**:
+   ```
+   Human: "Switch to my work project and show recent activity"
+   
+   You: I'll switch to your work project and check what's been updated recently.
+   [Use switch_project() then recent_activity()]
+   ```
+
+6. **File organization (v0.13.0)**:
+   ```
+   Human: "Move my old meeting notes to the archive folder"
+   
+   You: I'll organize those notes for you.
+   [Use move_note() to relocate files with database consistency]
+   ```
+
+## Key Things to Remember
+
+1. **Files are Truth**
+   - All knowledge lives in local files on the user's computer
+   - Users can edit files outside your interaction
+   - Changes need to be synced by the user (usually automatic)
+   - Always verify information is current with `recent_activity()`
+
+2. **Building Context Effectively**
+   - Start with specific entities
+   - Follow meaningful relations
+   - Check recent changes
+   - Build context incrementally
+   - Combine related information
+
+3. **Writing Knowledge Wisely**
+   - Same title+folder overwrites existing notes
+   - Structure with clear headings and semantic markup
+   - Use tags for searchability (v0.13.0: frontmatter tags indexed)
+   - Keep files organized in logical folders
+
+4. **Leverage v0.13.0 Features**
+   - **Edit incrementally**: Use `edit_note()` for small changes vs rewriting
+   - **Switch projects**: Change context when user mentions different work areas
+   - **Organize proactively**: Move old content to archive folders
+   - **Cross-project operations**: Create notes in specific projects while maintaining context
+
+## Common Knowledge Patterns
+
+### Capturing Decisions
+
+```markdown
+---
+title: Coffee Brewing Methods
+tags: [coffee, brewing, pour-over, techniques]  # v0.13.0: Now searchable!
+---
+
+# Coffee Brewing Methods
+
+## Context
+I've experimented with various brewing methods including French press, pour over, and espresso.
+
+## Decision
+Pour over is my preferred method for light to medium roasts because it highlights subtle flavors and offers more control over the extraction.
+
+## Observations
+- [technique] Blooming the coffee grounds for 30 seconds improves extraction #brewing
+- [preference] Water temperature between 195-205°F works best #temperature
+- [equipment] Gooseneck kettle provides better control of water flow #tools
+- [timing] Total brew time of 3-4 minutes produces optimal extraction #process
+
+## Relations
+- pairs_with [[Light Roast Beans]]
+- contrasts_with [[French Press Method]]
+- requires [[Proper Grinding Technique]]
+- part_of [[Morning Coffee Routine]]
+```
+
+### Recording Project Structure
+
+```markdown
+# Garden Planning
+
+## Overview
+This document outlines the garden layout and planting strategy for this season.
+
+## Observations
+- [structure] Raised beds in south corner for sun exposure #layout
+- [structure] Drip irrigation system installed for efficiency #watering
+- [pattern] Companion planting used to deter pests naturally #technique
+
+## Relations
+- contains [[Vegetable Section]]
+- contains [[Herb Garden]]
+- implements [[Organic Gardening Principles]]
+```
+
+### Technical Discussions
+
+```markdown
+# Recipe Improvement Discussion
+
+## Key Points
+Discussed strategies for improving the chocolate chip cookie recipe.
+
+## Observations
+- [issue] Cookies spread too thin when baked at 350°F #texture
+- [solution] Chilling dough for 24 hours improves flavor and reduces spreading #technique
+- [decision] Will use brown butter instead of regular butter #flavor
+
+## Relations
+- improves [[Basic Cookie Recipe]]
+- inspired_by [[Bakery-Style Cookies]]
+- pairs_with [[Homemade Ice Cream]]
+```
+
+## v0.13.0 Workflow Examples
+
+### Multi-Project Conversations
+
+**User:** "I need to update my work documentation and also add a personal recipe note."
+
+**Workflow:**
+1. `list_projects()` - Check available projects
+2. `write_note(title="Sprint Planning", project="work-notes")` - Work content
+3. `write_note(title="Weekend Recipes", project="personal")` - Personal content
+
+### Incremental Note Building
+
+**User:** "Add a troubleshooting section to my setup guide."
+
+**Workflow:**
+1. `edit_note(identifier="Setup Guide", operation="append", content="\n## Troubleshooting\n...")`
+
+**User:** "Update the authentication section in my API docs."
+
+**Workflow:**
+1. `edit_note(identifier="API Documentation", operation="replace_section", section="## Authentication")`
+
+### Smart File Organization
+
+**User:** "My notes are getting messy in the main folder."
+
+**Workflow:**
+1. `move_note("Old Meeting Notes", "archive/2024/old-meetings.md")`
+2. `move_note("Project Notes", "projects/client-work/notes.md")`
+
+### Creating Effective Relations
+
+When creating relations:
+1. **Reference existing entities** by their exact title: `[[Exact Title]]`
+2. **Create forward references** to entities that don't exist yet - they'll be linked automatically when created
+3. **Search first** to find existing entities to reference
+4. **Use meaningful relation types**: `implements`, `requires`, `part_of` vs generic `relates_to`
+
+**Example workflow:**
+1. `search_notes("travel")` to find existing travel-related notes
+2. Reference found entities: `- part_of [[Japan Travel Guide]]`
+3. Add forward references: `- located_in [[Tokyo]]` (even if Tokyo note doesn't exist yet)
+
+## Common Issues & Solutions
+
+**Missing Content:**
+- Try `search_notes()` with broader terms if `read_note()` fails
+- Use fuzzy matching: search for partial titles
+
+**Forward References:**
+- These are normal! Basic Memory links them automatically when target notes are created
+- Inform users: "I've created forward references that will be linked when you create those notes"
+
+**Sync Issues:**
+- 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**
+   - Offer to capture important discussions
+   - Record decisions, rationales, and conclusions
+   - Link to related topics
+   - Ask for permission first: "Would you like me to save our discussion about [topic]?"
+   - Confirm when complete: "I've saved our discussion to Basic Memory"
+
+2. **Create a Rich Semantic Graph**
+   - **Add meaningful observations**: Include at least 3-5 categorized observations in each note
+   - **Create deliberate relations**: Connect each note to at least 2-3 related entities
+   - **Use existing entities**: Before creating a new relation, search for existing entities
+   - **Verify wikilinks**: When referencing `[[Entity]]`, use exact titles of existing notes
+   - **Check accuracy**: Use `search_notes()` or `recent_activity()` to confirm entity titles
+   - **Use precise relation types**: Choose specific relation types that convey meaning (e.g., "implements" instead of "relates_to")
+   - **Consider bidirectional relations**: When appropriate, create inverse relations in both entities
+
+3. **Structure Content Thoughtfully**
+   - Use clear, descriptive titles
+   - Organize with logical sections (Context, Decision, Implementation, etc.)
+   - Include relevant context and background
+   - Add semantic observations with appropriate categories
+   - Use a consistent format for similar types of notes
+   - Balance detail with conciseness
+
+4. **Navigate Knowledge Effectively**
+   - Start with specific searches
+   - Follow relation paths
+   - Combine information from multiple sources
+   - Verify information is current
+   - Build a complete picture before responding
+
+5. **Help Users Maintain Their Knowledge**
+   - Suggest organizing related topics
+   - Identify potential duplicates
+   - Recommend adding relations between topics
+   - Offer to create summaries of scattered information
+   - Suggest potential missing relations: "I notice this might relate to [topic], would you like me to add that connection?"
+
+
+Built with ♥️ by Basic Machines

docs/CLI Reference.md

@@ -0,0 +1,414 @@
+---
+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

@@ -0,0 +1,107 @@
+---
+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

@@ -0,0 +1,335 @@
+# 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/Getting Started with Basic Memory.md

@@ -0,0 +1,355 @@
+---
+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

@@ -0,0 +1,207 @@
+---
+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

@@ -0,0 +1,259 @@
+# 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

@@ -0,0 +1,146 @@
+---
+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

@@ -0,0 +1,311 @@
+# 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

@@ -0,0 +1,243 @@
+---
+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

@@ -0,0 +1,657 @@
+---
+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

@@ -0,0 +1,68 @@
+---
+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

@@ -0,0 +1,5 @@
+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

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

examples/.obsidian/appearance.json

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

examples/.obsidian/community-plugins.json

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

examples/.obsidian/core-plugins.json

@@ -0,0 +1,31 @@
+{
+  "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

@@ -0,0 +1,158 @@
+/*
+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

@@ -0,0 +1,10 @@
+{
+	"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

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

examples/Coffee Notes/Brewing Equipment.md

@@ -0,0 +1,83 @@
+---
+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

@@ -0,0 +1,78 @@
+---
+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

@@ -0,0 +1,70 @@
+---
+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

@@ -0,0 +1,89 @@
+---
+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

@@ -0,0 +1,73 @@
+---
+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

@@ -0,0 +1,79 @@
+---
+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

@@ -0,0 +1,161 @@
+{
+	"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

@@ -0,0 +1,84 @@
+---
+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

@@ -0,0 +1,69 @@
+---
+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

installer/README.md

@@ -1,16 +0,0 @@
-# Basic Memory Installer
-
-This installer configures Basic Memory to work with Claude Desktop.
-
-## Installation
-
-1. Download the latest installer from the [releases page](https://github.com/basicmachines-co/basic-memory/releases)
-2. Unzip the downloaded file
-3. Since the app is currently unsigned, you'll need to:
-   - Right-click (or Control-click) the app
-   - Select "Open" from the context menu
-   - Click "Open" in the warning dialog
-4. Follow the installation instructions
-5. Restart Claude Desktop
-
-The warning only appears the first time you open the app. Future updates will include proper code signing.

installer/icon.svg

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

installer/installer.py

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

installer/make_icons.sh

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

installer/setup.py

@@ -1,50 +0,0 @@
-from cx_Freeze import setup, Executable
-import sys
-
-# Build options for all platforms - keep it simple and don't exclude too much
-build_exe_options = {
-    "packages": ["json", "pathlib"],
-    "excludes": [
-        "unittest", 
-        "pydoc",
-        "test"
-    ],
-    # Control file copying behavior
-    "copy_dependent_files": False,
-    "create_library_zip": True,
-    "copy_to_same_dir": False,
-}
-
-# Platform-specific options
-if sys.platform == "win32":
-    base = "Win32GUI"  # Use GUI base for Windows
-    build_exe_options.update({
-        "include_msvcr": True,  # Include Visual C++ runtime
-    })
-    target_name = "Basic Memory Installer.exe"
-else:  # darwin
-    base = None  # Don't use GUI base for macOS
-    target_name = "Basic Memory Installer"
-
-executables = [
-    Executable(
-        script="installer.py",
-        target_name=target_name,
-        base=base,
-        icon="Basic.icns"
-    )
-]
-
-setup(
-    name="basic-memory",
-    version=open("../pyproject.toml").read().split('version = "', 1)[1].split('"', 1)[0],
-    description="Basic Memory - Local-first knowledge management",
-    options={
-        "build_exe": build_exe_options,
-        "bdist_mac": {
-            "bundle_name": "Basic Memory Installer",
-            "iconfile": "Basic.icns"
-        }
-    },
-    executables=executables,
-)

justfile

@@ -0,0 +1,182 @@
+# 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"
+
+# List all available recipes
+default:
+    @just --list

llms-install.md

@@ -0,0 +1,128 @@
+# 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/).

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "basic-memory"
-version = "0.2.11"
+dynamic = ["version"]
 description = "Local-first knowledge management combining Zettelkasten with knowledge graphs"
 readme = "README.md"
 requires-python = ">=3.12.1"
@@ -28,7 +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",
 ]
 
 
@@ -39,9 +44,10 @@ Documentation = "https://github.com/basicmachines-co/basic-memory#readme"
 
 [project.scripts]
 basic-memory = "basic_memory.cli.main:app"
+bm = "basic_memory.cli.main:app"
 
 [build-system]
-requires = ["hatchling"]
+requires = ["hatchling", "uv-dynamic-versioning>=0.7.0"]
 build-backend = "hatchling.build"
 
 [tool.pytest.ini_options]
@@ -63,16 +69,19 @@ 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]
+source = "uv-dynamic-versioning"
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+style = "pep440"
+bump = true
+fallback-version = "0.0.0"
+
 [tool.pyright]
 include = ["src/"]
 exclude = ["**/__pycache__"]
@@ -83,18 +92,35 @@ reportMissingTypeStubs = false
 pythonVersion = "3.12"
 
 
-[tool.semantic_release]
-version_variable = "src/basic_memory/__init__.py:__version__"
-version_toml = [
-    "pyproject.toml:project.version",
-]
-major_on_zero = false
-branch = "main"
-changelog_file = "CHANGELOG.md"
-build_command = "pip install uv && uv build"
-dist_path = "dist/"
-upload_to_pypi = true
-commit_message = "chore(release): {version} [skip ci]"
 
 [tool.coverage.run]
 concurrency = ["thread", "gevent"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if self.debug:",
+    "if settings.DEBUG",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if 0:",
+    "if __name__ == .__main__.:",
+    "class .*\\bProtocol\\):",
+    "@(abc\\.)?abstractmethod",
+]
+
+# Exclude specific modules that are difficult to test comprehensively
+omit = [
+    "*/external_auth_provider.py",  # External HTTP calls to OAuth providers
+    "*/supabase_auth_provider.py",  # External HTTP calls to Supabase APIs
+    "*/watch_service.py",           # File system watching - complex integration testing
+    "*/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]
+ignore_no_config = true

smithery.yaml

@@ -0,0 +1,15 @@
+# Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml
+
+startCommand:
+  type: stdio
+  configSchema:
+    # JSON Schema defining the configuration options for the MCP.
+    type: object
+    properties: {}
+    description: No configuration required. This MCP server runs using the default command.
+  commandFunction: |-
+    (config) => ({
+      command: 'basic-memory',
+      args: ['mcp']
+    })
+  exampleConfig: {}

src/basic_memory/__init__.py

@@ -1,3 +1,7 @@
 """basic-memory - Local-first knowledge management combining Zettelkasten with knowledge graphs"""
 
-__version__ = "0.0.1"
+# Package version - updated by release automation
+__version__ = "0.13.6"
+
+# API version for FastAPI - independent of package version
+__api_version__ = "v0"

src/basic_memory/alembic/README

@@ -1 +0,0 @@
-Generic single-database configuration.

src/basic_memory/alembic/alembic.ini

@@ -3,7 +3,7 @@
 [alembic]
 # path to migration scripts
 # Use forward slashes (/) also on windows to provide an os agnostic path
-script_location = src/basic_memory/alembic
+script_location = .
 
 # template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
 # Uncomment the line below if you want the files to be prepended with date and time

src/basic_memory/alembic/env.py

@@ -1,5 +1,6 @@
 """Alembic environment configuration."""
 
+import os
 from logging.config import fileConfig
 
 from sqlalchemy import engine_from_config
@@ -7,8 +8,12 @@ from sqlalchemy import pool
 
 from alembic import context
 
-from basic_memory.models import Base
-from basic_memory.config import config as app_config
+# set config.env to "test" for pytest to prevent logging to file in utils.setup_logging()
+os.environ["BASIC_MEMORY_ENV"] = "test"
+
+# 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.
@@ -18,6 +23,8 @@ config = context.config
 sqlalchemy_url = f"sqlite:///{app_config.database_path}"
 config.set_main_option("sqlalchemy.url", sqlalchemy_url)
 
+# print(f"Using SQLAlchemy URL: {sqlalchemy_url}")
+
 # Interpret the config file for Python logging.
 if config.config_file_name is not None:
     fileConfig(config.config_file_name)
@@ -27,6 +34,14 @@ if config.config_file_name is not None:
 target_metadata = Base.metadata
 
 
+# Add this function to tell Alembic what to include/exclude
+def include_object(object, name, type_, reflected, compare_to):
+    # Ignore SQLite FTS tables
+    if type_ == "table" and name.startswith("search_index"):
+        return False
+    return True
+
+
 def run_migrations_offline() -> None:
     """Run migrations in 'offline' mode.
 
@@ -44,6 +59,8 @@ def run_migrations_offline() -> None:
         target_metadata=target_metadata,
         literal_binds=True,
         dialect_opts={"paramstyle": "named"},
+        include_object=include_object,
+        render_as_batch=True,
     )
 
     with context.begin_transaction():
@@ -63,7 +80,12 @@ def run_migrations_online() -> None:
     )
 
     with connectable.connect() as connection:
-        context.configure(connection=connection, target_metadata=target_metadata)
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            include_object=include_object,
+            render_as_batch=True,
+        )
 
         with context.begin_transaction():
             context.run_migrations()

src/basic_memory/alembic/migrations.py

@@ -1,6 +1,5 @@
 """Functions for managing database migrations."""
 
-import asyncio
 from pathlib import Path
 from loguru import logger
 from alembic.config import Config
@@ -10,20 +9,16 @@ from alembic import command
 def get_alembic_config() -> Config:  # pragma: no cover
     """Get alembic config with correct paths."""
     migrations_path = Path(__file__).parent
-    alembic_ini = migrations_path.parent.parent.parent / "alembic.ini"
+    alembic_ini = migrations_path / "alembic.ini"
 
     config = Config(alembic_ini)
     config.set_main_option("script_location", str(migrations_path))
     return config
 
 
-async def reset_database():  # pragma: no cover
+def reset_database():  # pragma: no cover
     """Drop and recreate all tables."""
     logger.info("Resetting database...")
     config = get_alembic_config()
-
-    def _reset(cfg):
-        command.downgrade(cfg, "base")
-        command.upgrade(cfg, "head")
-
-    await asyncio.get_event_loop().run_in_executor(None, _reset, config)
+    command.downgrade(config, "base")
+    command.upgrade(config, "head")

src/basic_memory/alembic/versions/502b60eaa905_remove_required_from_entity_permalink.py

@@ -0,0 +1,51 @@
+"""remove required from entity.permalink
+
+Revision ID: 502b60eaa905
+Revises: b3c3938bacdb
+Create Date: 2025-02-24 13:33:09.790951
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "502b60eaa905"
+down_revision: Union[str, None] = "b3c3938bacdb"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table("entity", schema=None) as batch_op:
+        batch_op.alter_column("permalink", existing_type=sa.VARCHAR(), nullable=True)
+        batch_op.drop_index("ix_entity_permalink")
+        batch_op.create_index(batch_op.f("ix_entity_permalink"), ["permalink"], unique=False)
+        batch_op.drop_constraint("uix_entity_permalink", type_="unique")
+        batch_op.create_index(
+            "uix_entity_permalink",
+            ["permalink"],
+            unique=True,
+            sqlite_where=sa.text("content_type = 'text/markdown' AND permalink IS NOT NULL"),
+        )
+
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table("entity", schema=None) as batch_op:
+        batch_op.drop_index(
+            "uix_entity_permalink",
+            sqlite_where=sa.text("content_type = 'text/markdown' AND permalink IS NOT NULL"),
+        )
+        batch_op.create_unique_constraint("uix_entity_permalink", ["permalink"])
+        batch_op.drop_index(batch_op.f("ix_entity_permalink"))
+        batch_op.create_index("ix_entity_permalink", ["permalink"], unique=1)
+        batch_op.alter_column("permalink", existing_type=sa.VARCHAR(), nullable=False)
+
+    # ### end Alembic commands ###

src/basic_memory/alembic/versions/5fe1ab1ccebe_add_projects_table.py

@@ -0,0 +1,108 @@
+"""add projects table
+
+Revision ID: 5fe1ab1ccebe
+Revises: cc7172b46608
+Create Date: 2025-05-14 09:05:18.214357
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "5fe1ab1ccebe"
+down_revision: Union[str, None] = "cc7172b46608"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "project",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column("permalink", sa.String(), nullable=False),
+        sa.Column("path", sa.String(), nullable=False),
+        sa.Column("is_active", sa.Boolean(), nullable=False),
+        sa.Column("is_default", sa.Boolean(), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("is_default"),
+        sa.UniqueConstraint("name"),
+        sa.UniqueConstraint("permalink"),
+        if_not_exists=True,
+    )
+    with op.batch_alter_table("project", schema=None) as batch_op:
+        batch_op.create_index(
+            "ix_project_created_at", ["created_at"], unique=False, if_not_exists=True
+        )
+        batch_op.create_index("ix_project_name", ["name"], unique=True, if_not_exists=True)
+        batch_op.create_index("ix_project_path", ["path"], unique=False, if_not_exists=True)
+        batch_op.create_index(
+            "ix_project_permalink", ["permalink"], unique=True, if_not_exists=True
+        )
+        batch_op.create_index(
+            "ix_project_updated_at", ["updated_at"], unique=False, if_not_exists=True
+        )
+
+    with op.batch_alter_table("entity", schema=None) as batch_op:
+        batch_op.add_column(sa.Column("project_id", sa.Integer(), nullable=False))
+        batch_op.drop_index(
+            "uix_entity_permalink",
+            sqlite_where=sa.text("content_type = 'text/markdown' AND permalink IS NOT NULL"),
+        )
+        batch_op.drop_index("ix_entity_file_path")
+        batch_op.create_index(batch_op.f("ix_entity_file_path"), ["file_path"], unique=False)
+        batch_op.create_index("ix_entity_project_id", ["project_id"], unique=False)
+        batch_op.create_index(
+            "uix_entity_file_path_project", ["file_path", "project_id"], unique=True
+        )
+        batch_op.create_index(
+            "uix_entity_permalink_project",
+            ["permalink", "project_id"],
+            unique=True,
+            sqlite_where=sa.text("content_type = 'text/markdown' AND permalink IS NOT NULL"),
+        )
+        batch_op.create_foreign_key("fk_entity_project_id", "project", ["project_id"], ["id"])
+
+    # drop the search index table. it will be recreated
+    op.drop_table("search_index")
+
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table("entity", schema=None) as batch_op:
+        batch_op.drop_constraint("fk_entity_project_id", type_="foreignkey")
+        batch_op.drop_index(
+            "uix_entity_permalink_project",
+            sqlite_where=sa.text("content_type = 'text/markdown' AND permalink IS NOT NULL"),
+        )
+        batch_op.drop_index("uix_entity_file_path_project")
+        batch_op.drop_index("ix_entity_project_id")
+        batch_op.drop_index(batch_op.f("ix_entity_file_path"))
+        batch_op.create_index("ix_entity_file_path", ["file_path"], unique=1)
+        batch_op.create_index(
+            "uix_entity_permalink",
+            ["permalink"],
+            unique=1,
+            sqlite_where=sa.text("content_type = 'text/markdown' AND permalink IS NOT NULL"),
+        )
+        batch_op.drop_column("project_id")
+
+    with op.batch_alter_table("project", schema=None) as batch_op:
+        batch_op.drop_index("ix_project_updated_at")
+        batch_op.drop_index("ix_project_permalink")
+        batch_op.drop_index("ix_project_path")
+        batch_op.drop_index("ix_project_name")
+        batch_op.drop_index("ix_project_created_at")
+
+    op.drop_table("project")
+    # ### end Alembic commands ###

src/basic_memory/alembic/versions/647e7a75e2cd_project_constraint_fix.py

@@ -0,0 +1,104 @@
+"""project constraint fix
+
+Revision ID: 647e7a75e2cd
+Revises: 5fe1ab1ccebe
+Create Date: 2025-06-03 12:48:30.162566
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "647e7a75e2cd"
+down_revision: Union[str, None] = "5fe1ab1ccebe"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Remove the problematic UNIQUE constraint on is_default column.
+
+    The UNIQUE constraint prevents multiple projects from having is_default=FALSE,
+    which breaks project creation when the service sets is_default=False.
+
+    Since SQLite doesn't support dropping specific constraints easily, we'll
+    recreate the table without the problematic constraint.
+    """
+    # For SQLite, we need to recreate the table without the UNIQUE constraint
+    # Create a new table without the UNIQUE constraint on is_default
+    op.create_table(
+        "project_new",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column("permalink", sa.String(), nullable=False),
+        sa.Column("path", sa.String(), nullable=False),
+        sa.Column("is_active", sa.Boolean(), nullable=False),
+        sa.Column("is_default", sa.Boolean(), nullable=True),  # No UNIQUE constraint!
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("name"),
+        sa.UniqueConstraint("permalink"),
+    )
+
+    # Copy data from old table to new table
+    op.execute("INSERT INTO project_new SELECT * FROM project")
+
+    # Drop the old table
+    op.drop_table("project")
+
+    # Rename the new table
+    op.rename_table("project_new", "project")
+
+    # Recreate the indexes
+    with op.batch_alter_table("project", schema=None) as batch_op:
+        batch_op.create_index("ix_project_created_at", ["created_at"], unique=False)
+        batch_op.create_index("ix_project_name", ["name"], unique=True)
+        batch_op.create_index("ix_project_path", ["path"], unique=False)
+        batch_op.create_index("ix_project_permalink", ["permalink"], unique=True)
+        batch_op.create_index("ix_project_updated_at", ["updated_at"], unique=False)
+
+
+def downgrade() -> None:
+    """Add back the UNIQUE constraint on is_default column.
+
+    WARNING: This will break project creation again if multiple projects
+    have is_default=FALSE.
+    """
+    # Recreate the table with the UNIQUE constraint
+    op.create_table(
+        "project_old",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("name", sa.String(), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column("permalink", sa.String(), nullable=False),
+        sa.Column("path", sa.String(), nullable=False),
+        sa.Column("is_active", sa.Boolean(), nullable=False),
+        sa.Column("is_default", sa.Boolean(), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("is_default"),  # Add back the problematic constraint
+        sa.UniqueConstraint("name"),
+        sa.UniqueConstraint("permalink"),
+    )
+
+    # Copy data (this may fail if multiple FALSE values exist)
+    op.execute("INSERT INTO project_old SELECT * FROM project")
+
+    # Drop the current table and rename
+    op.drop_table("project")
+    op.rename_table("project_old", "project")
+
+    # Recreate indexes
+    with op.batch_alter_table("project", schema=None) as batch_op:
+        batch_op.create_index("ix_project_created_at", ["created_at"], unique=False)
+        batch_op.create_index("ix_project_name", ["name"], unique=True)
+        batch_op.create_index("ix_project_path", ["path"], unique=False)
+        batch_op.create_index("ix_project_permalink", ["permalink"], unique=True)
+        batch_op.create_index("ix_project_updated_at", ["updated_at"], unique=False)

src/basic_memory/alembic/versions/b3c3938bacdb_relation_to_name_unique_index.py

@@ -0,0 +1,44 @@
+"""relation to_name unique index
+
+Revision ID: b3c3938bacdb
+Revises: 3dae7c7b1564
+Create Date: 2025-02-22 14:59:30.668466
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = "b3c3938bacdb"
+down_revision: Union[str, None] = "3dae7c7b1564"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # SQLite doesn't support constraint changes through ALTER
+    # Need to recreate table with desired constraints
+    with op.batch_alter_table("relation") as batch_op:
+        # Drop existing unique constraint
+        batch_op.drop_constraint("uix_relation", type_="unique")
+
+        # Add new constraints
+        batch_op.create_unique_constraint(
+            "uix_relation_from_id_to_id", ["from_id", "to_id", "relation_type"]
+        )
+        batch_op.create_unique_constraint(
+            "uix_relation_from_id_to_name", ["from_id", "to_name", "relation_type"]
+        )
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("relation") as batch_op:
+        # Drop new constraints
+        batch_op.drop_constraint("uix_relation_from_id_to_name", type_="unique")
+        batch_op.drop_constraint("uix_relation_from_id_to_id", type_="unique")
+
+        # Restore original constraint
+        batch_op.create_unique_constraint("uix_relation", ["from_id", "to_id", "relation_type"])

src/basic_memory/alembic/versions/cc7172b46608_update_search_index_schema.py

@@ -0,0 +1,100 @@
+"""Update search index schema
+
+Revision ID: cc7172b46608
+Revises: 502b60eaa905
+Create Date: 2025-02-28 18:48:23.244941
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = "cc7172b46608"
+down_revision: Union[str, None] = "502b60eaa905"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade database schema to use new search index with content_stems and content_snippet."""
+
+    # First, drop the existing search_index table
+    op.execute("DROP TABLE IF EXISTS search_index")
+
+    # Create new search_index with updated schema
+    op.execute("""
+    CREATE VIRTUAL TABLE IF NOT EXISTS search_index USING fts5(
+        -- Core entity fields
+        id UNINDEXED,          -- Row ID
+        title,                 -- Title for searching
+        content_stems,         -- Main searchable content split into stems
+        content_snippet,       -- File content snippet for display
+        permalink,             -- Stable identifier (now indexed for path search)
+        file_path UNINDEXED,   -- Physical location
+        type UNINDEXED,        -- entity/relation/observation
+        
+        -- Relation fields 
+        from_id UNINDEXED,     -- Source entity
+        to_id UNINDEXED,       -- Target entity
+        relation_type UNINDEXED, -- Type of relation
+        
+        -- Observation fields
+        entity_id UNINDEXED,   -- Parent entity
+        category UNINDEXED,    -- Observation category
+        
+        -- Common fields
+        metadata UNINDEXED,    -- JSON metadata
+        created_at UNINDEXED,  -- Creation timestamp
+        updated_at UNINDEXED,  -- Last update
+        
+        -- Configuration
+        tokenize='unicode61 tokenchars 0x2F',  -- Hex code for /
+        prefix='1,2,3,4'                    -- Support longer prefixes for paths
+    );
+    """)
+
+
+def downgrade() -> None:
+    """Downgrade database schema to use old search index."""
+    # Drop the updated search_index table
+    op.execute("DROP TABLE IF EXISTS search_index")
+
+    # Recreate the original search_index schema
+    op.execute("""
+    CREATE VIRTUAL TABLE IF NOT EXISTS search_index USING fts5(
+        -- Core entity fields
+        id UNINDEXED,          -- Row ID
+        title,                 -- Title for searching
+        content,               -- Main searchable content
+        permalink,             -- Stable identifier (now indexed for path search)
+        file_path UNINDEXED,   -- Physical location
+        type UNINDEXED,        -- entity/relation/observation
+        
+        -- Relation fields 
+        from_id UNINDEXED,     -- Source entity
+        to_id UNINDEXED,       -- Target entity
+        relation_type UNINDEXED, -- Type of relation
+        
+        -- Observation fields
+        entity_id UNINDEXED,   -- Parent entity
+        category UNINDEXED,    -- Observation category
+        
+        -- Common fields
+        metadata UNINDEXED,    -- JSON metadata
+        created_at UNINDEXED,  -- Creation timestamp
+        updated_at UNINDEXED,  -- Last update
+        
+        -- Configuration
+        tokenize='unicode61 tokenchars 0x2F',  -- Hex code for /
+        prefix='1,2,3,4'                    -- Support longer prefixes for paths
+    );
+    """)
+
+    # Print instruction to manually reindex after migration
+    print("\n------------------------------------------------------------------")
+    print("IMPORTANT: After downgrade completes, manually run the reindex command:")
+    print("basic-memory sync")
+    print("------------------------------------------------------------------\n")

src/basic_memory/api/app.py

@@ -1,45 +1,51 @@
 """FastAPI application for basic-memory knowledge graph API."""
 
+import asyncio
 from contextlib import asynccontextmanager
 
 from fastapi import FastAPI, HTTPException
 from fastapi.exception_handlers import http_exception_handler
 from loguru import logger
 
+from basic_memory import __version__ as version
 from basic_memory import db
-from basic_memory.config import config as app_config
-from basic_memory.api.routers import knowledge, search, memory, resource
-from alembic import command
-from alembic.config import Config
-
-from basic_memory.db import DatabaseType
-from basic_memory.repository.search_repository import SearchRepository
-
-
-async def run_migrations():  # pragma: no cover
-    """Run any pending alembic migrations."""
-    logger.info("Running database migrations...")
-    try:
-        config = Config("alembic.ini")
-        command.upgrade(config, "head")
-        logger.info("Migrations completed successfully")
-
-        _, session_maker = await db.get_or_create_db(
-            app_config.database_path, DatabaseType.FILESYSTEM
-        )
-        await SearchRepository(session_maker).init_search_index()
-    except Exception as e:
-        logger.error(f"Error running migrations: {e}")
-        raise
+from basic_memory.api.routers import (
+    directory_router,
+    importer_router,
+    knowledge,
+    management,
+    memory,
+    project,
+    resource,
+    search,
+    prompt_router,
+)
+from basic_memory.config import app_config
+from basic_memory.services.initialization import initialize_app, initialize_file_sync
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):  # pragma: no cover
     """Lifecycle manager for the FastAPI app."""
+    # Initialize app and database
     logger.info("Starting Basic Memory API")
-    await run_migrations()
+    await initialize_app(app_config)
+
+    logger.info(f"Sync changes enabled: {app_config.sync_changes}")
+    if app_config.sync_changes:
+        # start file sync task in background
+        app.state.sync_task = asyncio.create_task(initialize_file_sync(app_config))
+    else:
+        logger.info("Sync changes disabled. Skipping file sync service.")
+
+    # proceed with startup
     yield
+
     logger.info("Shutting down Basic Memory API")
+    if app.state.sync_task:
+        logger.info("Stopping sync...")
+        app.state.sync_task.cancel()  # pyright: ignore
+
     await db.shutdown_db()
 
 
@@ -47,20 +53,37 @@ async def lifespan(app: FastAPI):  # pragma: no cover
 app = FastAPI(
     title="Basic Memory API",
     description="Knowledge graph API for basic-memory",
-    version="0.1.0",
+    version=version,
     lifespan=lifespan,
 )
 
+
 # Include routers
-app.include_router(knowledge.router)
-app.include_router(search.router)
-app.include_router(memory.router)
-app.include_router(resource.router)
+app.include_router(knowledge.router, prefix="/{project}")
+app.include_router(memory.router, prefix="/{project}")
+app.include_router(resource.router, prefix="/{project}")
+app.include_router(search.router, prefix="/{project}")
+app.include_router(project.project_router, prefix="/{project}")
+app.include_router(directory_router.router, prefix="/{project}")
+app.include_router(prompt_router.router, prefix="/{project}")
+app.include_router(importer_router.router, prefix="/{project}")
+
+# Project resource router works accross projects
+app.include_router(project.project_resource_router)
+app.include_router(management.router)
+
+# Auth routes are handled by FastMCP automatically when auth is enabled
 
 
 @app.exception_handler(Exception)
 async def exception_handler(request, exc):  # pragma: no cover
     logger.exception(
-        f"An unhandled exception occurred for request '{request.url}', exception: {exc}"
+        "API unhandled exception",
+        url=str(request.url),
+        method=request.method,
+        client=request.client.host if request.client else None,
+        path=request.url.path,
+        error_type=type(exc).__name__,
+        error=str(exc),
     )
     return await http_exception_handler(request, HTTPException(status_code=500, detail=str(exc)))

src/basic_memory/api/routers/__init__.py

@@ -1,8 +1,11 @@
 """API routers."""
 
 from . import knowledge_router as knowledge
+from . import management_router as management
 from . import memory_router as memory
+from . import project_router as project
 from . import resource_router as resource
 from . import search_router as search
+from . import prompt_router as prompt
 
-__all__ = ["knowledge", "memory", "resource", "search"]
+__all__ = ["knowledge", "management", "memory", "project", "resource", "search", "prompt"]

src/basic_memory/api/routers/directory_router.py

@@ -0,0 +1,63 @@
+"""Router for directory tree operations."""
+
+from typing import List, Optional
+
+from fastapi import APIRouter, Query
+
+from basic_memory.deps import DirectoryServiceDep, ProjectIdDep
+from basic_memory.schemas.directory import DirectoryNode
+
+router = APIRouter(prefix="/directory", tags=["directory"])
+
+
+@router.get("/tree", response_model=DirectoryNode)
+async def get_directory_tree(
+    directory_service: DirectoryServiceDep,
+    project_id: ProjectIdDep,
+):
+    """Get hierarchical directory structure from the knowledge base.
+
+    Args:
+        directory_service: Service for directory operations
+        project_id: ID of the current project
+
+    Returns:
+        DirectoryNode representing the root of the hierarchical tree structure
+    """
+    # Get a hierarchical directory tree for the specific project
+    tree = await directory_service.get_directory_tree()
+
+    # Return the hierarchical tree
+    return tree
+
+
+@router.get("/list", response_model=List[DirectoryNode])
+async def list_directory(
+    directory_service: DirectoryServiceDep,
+    project_id: ProjectIdDep,
+    dir_name: str = Query("/", description="Directory path to list"),
+    depth: int = Query(1, ge=1, le=10, description="Recursion depth (1-10)"),
+    file_name_glob: Optional[str] = Query(
+        None, description="Glob pattern for filtering file names"
+    ),
+):
+    """List directory contents with filtering and depth control.
+
+    Args:
+        directory_service: Service for directory operations
+        project_id: ID of the current project
+        dir_name: Directory path to list (default: root "/")
+        depth: Recursion depth (1-10, default: 1 for immediate children only)
+        file_name_glob: Optional glob pattern for filtering file names (e.g., "*.md", "*meeting*")
+
+    Returns:
+        List of DirectoryNode objects matching the criteria
+    """
+    # Get directory listing with filtering
+    nodes = await directory_service.list_directory(
+        dir_name=dir_name,
+        depth=depth,
+        file_name_glob=file_name_glob,
+    )
+
+    return nodes

src/basic_memory/api/routers/importer_router.py

@@ -0,0 +1,152 @@
+"""Import router for Basic Memory API."""
+
+import json
+import logging
+
+from fastapi import APIRouter, Form, HTTPException, UploadFile, status
+
+from basic_memory.deps import (
+    ChatGPTImporterDep,
+    ClaudeConversationsImporterDep,
+    ClaudeProjectsImporterDep,
+    MemoryJsonImporterDep,
+)
+from basic_memory.importers import Importer
+from basic_memory.schemas.importer import (
+    ChatImportResult,
+    EntityImportResult,
+    ProjectImportResult,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/import", tags=["import"])
+
+
+@router.post("/chatgpt", response_model=ChatImportResult)
+async def import_chatgpt(
+    importer: ChatGPTImporterDep,
+    file: UploadFile,
+    folder: str = Form("conversations"),
+) -> ChatImportResult:
+    """Import conversations from ChatGPT JSON export.
+
+    Args:
+        file: The ChatGPT conversations.json file.
+        folder: The folder to place the files in.
+        markdown_processor: MarkdownProcessor instance.
+
+    Returns:
+        ChatImportResult with import statistics.
+
+    Raises:
+        HTTPException: If import fails.
+    """
+    return await import_file(importer, file, folder)
+
+
+@router.post("/claude/conversations", response_model=ChatImportResult)
+async def import_claude_conversations(
+    importer: ClaudeConversationsImporterDep,
+    file: UploadFile,
+    folder: str = Form("conversations"),
+) -> ChatImportResult:
+    """Import conversations from Claude conversations.json export.
+
+    Args:
+        file: The Claude conversations.json file.
+        folder: The folder to place the files in.
+        markdown_processor: MarkdownProcessor instance.
+
+    Returns:
+        ChatImportResult with import statistics.
+
+    Raises:
+        HTTPException: If import fails.
+    """
+    return await import_file(importer, file, folder)
+
+
+@router.post("/claude/projects", response_model=ProjectImportResult)
+async def import_claude_projects(
+    importer: ClaudeProjectsImporterDep,
+    file: UploadFile,
+    folder: str = Form("projects"),
+) -> ProjectImportResult:
+    """Import projects from Claude projects.json export.
+
+    Args:
+        file: The Claude projects.json file.
+        base_folder: The base folder to place the files in.
+        markdown_processor: MarkdownProcessor instance.
+
+    Returns:
+        ProjectImportResult with import statistics.
+
+    Raises:
+        HTTPException: If import fails.
+    """
+    return await import_file(importer, file, folder)
+
+
+@router.post("/memory-json", response_model=EntityImportResult)
+async def import_memory_json(
+    importer: MemoryJsonImporterDep,
+    file: UploadFile,
+    folder: str = Form("conversations"),
+) -> EntityImportResult:
+    """Import entities and relations from a memory.json file.
+
+    Args:
+        file: The memory.json file.
+        destination_folder: Optional destination folder within the project.
+        markdown_processor: MarkdownProcessor instance.
+
+    Returns:
+        EntityImportResult with import statistics.
+
+    Raises:
+        HTTPException: If import fails.
+    """
+    try:
+        file_data = []
+        file_bytes = await file.read()
+        file_str = file_bytes.decode("utf-8")
+        for line in file_str.splitlines():
+            json_data = json.loads(line)
+            file_data.append(json_data)
+
+        result = await importer.import_data(file_data, folder)
+        if not result.success:  # pragma: no cover
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=result.error_message or "Import failed",
+            )
+    except Exception as e:
+        logger.exception("Import failed")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Import failed: {str(e)}",
+        )
+    return result
+
+
+async def import_file(importer: Importer, file: UploadFile, destination_folder: str):
+    try:
+        # Process file
+        json_data = json.load(file.file)
+        result = await importer.import_data(json_data, destination_folder)
+        if not result.success:  # pragma: no cover
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=result.error_message or "Import failed",
+            )
+
+        return result
+
+    except Exception as e:
+        logger.exception("Import failed")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Import failed: {str(e)}",
+        )

src/basic_memory/api/routers/knowledge_router.py

@@ -10,6 +10,11 @@ from basic_memory.deps import (
     get_search_service,
     SearchServiceDep,
     LinkResolverDep,
+    ProjectPathDep,
+    FileServiceDep,
+    ProjectConfigDep,
+    AppConfigDep,
+    SyncServiceDep,
 )
 from basic_memory.schemas import (
     EntityListResponse,
@@ -17,8 +22,8 @@ from basic_memory.schemas import (
     DeleteEntitiesResponse,
     DeleteEntitiesRequest,
 )
+from basic_memory.schemas.request import EditEntityRequest, MoveEntityRequest
 from basic_memory.schemas.base import Permalink, Entity
-from basic_memory.services.exceptions import EntityNotFoundError
 
 router = APIRouter(prefix="/knowledge", tags=["knowledge"])
 
@@ -33,7 +38,9 @@ async def create_entity(
     search_service: SearchServiceDep,
 ) -> EntityResponse:
     """Create an entity."""
-    logger.info(f"request: create_entity with data={data}")
+    logger.info(
+        "API request", endpoint="create_entity", entity_type=data.entity_type, title=data.title
+    )
 
     entity = await entity_service.create_entity(data)
 
@@ -41,25 +48,38 @@ async def create_entity(
     await search_service.index_entity(entity, background_tasks=background_tasks)
     result = EntityResponse.model_validate(entity)
 
-    logger.info(f"response: create_entity with result={result}")
+    logger.info(
+        f"API response: endpoint='create_entity' title={result.title}, permalink={result.permalink}, status_code=201"
+    )
     return result
 
 
 @router.put("/entities/{permalink:path}", response_model=EntityResponse)
 async def create_or_update_entity(
+    project: ProjectPathDep,
     permalink: Permalink,
     data: Entity,
     response: Response,
     background_tasks: BackgroundTasks,
     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(f"request: create_or_update_entity with permalink={permalink}, data={data}")
+    logger.info(
+        f"API request: create_or_update_entity for {project=}, {permalink=}, {data.entity_type=}, {data.title=}"
+    )
 
     # Validate permalink matches
     if data.permalink != permalink:
-        raise HTTPException(status_code=400, detail="Entity permalink must match URL path")
+        logger.warning(
+            f"API validation error: creating/updating entity with permalink mismatch - url={permalink}, data={data.permalink}",
+        )
+        raise HTTPException(
+            status_code=400,
+            detail=f"Entity permalink {data.permalink} must match URL path: '{permalink}'",
+        )
 
     # Try create_or_update operation
     entity, created = await entity_service.create_or_update_entity(data)
@@ -67,39 +87,144 @@ 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(
-        f"response: create_or_update_entity with result={result}, status_code={response.status_code}"
+        f"API response: {result.title=}, {result.permalink=}, {created=}, status_code={response.status_code}"
     )
     return result
 
 
+@router.patch("/entities/{identifier:path}", response_model=EntityResponse)
+async def edit_entity(
+    identifier: str,
+    data: EditEntityRequest,
+    background_tasks: BackgroundTasks,
+    entity_service: EntityServiceDep,
+    search_service: SearchServiceDep,
+) -> EntityResponse:
+    """Edit an existing entity using various operations like append, prepend, find_replace, or replace_section.
+
+    This endpoint allows for targeted edits without requiring the full entity content.
+    """
+    logger.info(
+        f"API request: endpoint='edit_entity', identifier='{identifier}', operation='{data.operation}'"
+    )
+
+    try:
+        # Edit the entity using the service
+        entity = await entity_service.edit_entity(
+            identifier=identifier,
+            operation=data.operation,
+            content=data.content,
+            section=data.section,
+            find_text=data.find_text,
+            expected_replacements=data.expected_replacements,
+        )
+
+        # Reindex the updated entity
+        await search_service.index_entity(entity, background_tasks=background_tasks)
+
+        # Return the updated entity response
+        result = EntityResponse.model_validate(entity)
+
+        logger.info(
+            "API response",
+            endpoint="edit_entity",
+            identifier=identifier,
+            operation=data.operation,
+            permalink=result.permalink,
+            status_code=200,
+        )
+
+        return result
+
+    except Exception as e:
+        logger.error(f"Error editing entity: {e}")
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.post("/move")
+async def move_entity(
+    data: MoveEntityRequest,
+    background_tasks: BackgroundTasks,
+    entity_service: EntityServiceDep,
+    project_config: ProjectConfigDep,
+    app_config: AppConfigDep,
+    search_service: SearchServiceDep,
+) -> EntityResponse:
+    """Move an entity to a new file location with project consistency.
+
+    This endpoint moves a note to a different path while maintaining project
+    consistency and optionally updating permalinks based on configuration.
+    """
+    logger.info(
+        f"API request: endpoint='move_entity', identifier='{data.identifier}', destination='{data.destination_path}'"
+    )
+
+    try:
+        # Move the entity using the service
+        moved_entity = await entity_service.move_entity(
+            identifier=data.identifier,
+            destination_path=data.destination_path,
+            project_config=project_config,
+            app_config=app_config,
+        )
+
+        # Get the moved entity to reindex it
+        entity = await entity_service.link_resolver.resolve_link(data.destination_path)
+        if entity:
+            await search_service.index_entity(entity, background_tasks=background_tasks)
+
+        logger.info(
+            "API response",
+            endpoint="move_entity",
+            identifier=data.identifier,
+            destination=data.destination_path,
+            status_code=200,
+        )
+        result = EntityResponse.model_validate(moved_entity)
+        return result
+
+    except Exception as e:
+        logger.error(f"Error moving entity: {e}")
+        raise HTTPException(status_code=400, detail=str(e))
+
+
 ## Read endpoints
 
 
-@router.get("/entities/{permalink:path}", response_model=EntityResponse)
+@router.get("/entities/{identifier:path}", response_model=EntityResponse)
 async def get_entity(
     entity_service: EntityServiceDep,
-    permalink: str,
+    link_resolver: LinkResolverDep,
+    identifier: str,
 ) -> EntityResponse:
-    """Get a specific entity by ID.
+    """Get a specific entity by file path or permalink..
 
     Args:
-        permalink: Entity path ID
-        content: If True, include full file content
+        identifier: Entity file path or permalink
         :param entity_service: EntityService
+        :param link_resolver: LinkResolver
     """
-    logger.info(f"request: get_entity with permalink={permalink}")
-    try:
-        entity = await entity_service.get_by_permalink(permalink)
-        result = EntityResponse.model_validate(entity)
+    logger.info(f"request: get_entity with identifier={identifier}")
+    entity = await link_resolver.resolve_link(identifier)
+    if not entity:
+        raise HTTPException(status_code=404, detail=f"Entity {identifier} not found")
 
-        logger.info(f"response: get_entity with result={result}")
-        return result
-    except EntityNotFoundError:
-        logger.error(f"Error: Entity with {permalink} not found")
-        raise HTTPException(status_code=404, detail=f"Entity with {permalink} not found")
+    result = EntityResponse.model_validate(entity)
+    return result
 
 
 @router.get("/entities", response_model=EntityListResponse)
@@ -114,8 +239,6 @@ async def get_entities(
     result = EntityListResponse(
         entities=[EntityResponse.model_validate(entity) for entity in entities]
     )
-
-    logger.info(f"response: get_entities with result={result}")
     return result
 
 
@@ -135,17 +258,15 @@ async def delete_entity(
 
     entity = await link_resolver.resolve_link(identifier)
     if entity is None:
-        logger.info("response: delete_entity with result=DeleteEntitiesResponse(deleted=False)")
         return DeleteEntitiesResponse(deleted=False)
 
     # Delete the entity
-    deleted = await entity_service.delete_entity(entity.permalink)
+    deleted = await entity_service.delete_entity(entity.permalink or entity.id)
 
-    # Remove from search index
-    background_tasks.add_task(search_service.delete_by_permalink, entity.permalink)
+    # Remove from search index (entity, observations, and relations)
+    background_tasks.add_task(search_service.handle_delete, entity)
 
     result = DeleteEntitiesResponse(deleted=deleted)
-    logger.info(f"response: delete_entity with result={result}")
     return result
 
 
@@ -166,5 +287,4 @@ async def delete_entities(
         background_tasks.add_task(search_service.delete_by_permalink, permalink)
 
     result = DeleteEntitiesResponse(deleted=deleted)
-    logger.info(f"response: delete_entities with result={result}")
     return result

src/basic_memory/api/routers/management_router.py

@@ -0,0 +1,78 @@
+"""Management router for basic-memory API."""
+
+import asyncio
+
+from fastapi import APIRouter, Request
+from loguru import logger
+from pydantic import BaseModel
+
+from basic_memory.config import app_config
+from basic_memory.deps import SyncServiceDep, ProjectRepositoryDep
+
+router = APIRouter(prefix="/management", tags=["management"])
+
+
+class WatchStatusResponse(BaseModel):
+    """Response model for watch status."""
+
+    running: bool
+    """Whether the watch service is currently running."""
+
+
+@router.get("/watch/status", response_model=WatchStatusResponse)
+async def get_watch_status(request: Request) -> WatchStatusResponse:
+    """Get the current status of the watch service."""
+    return WatchStatusResponse(
+        running=request.app.state.watch_task is not None and not request.app.state.watch_task.done()
+    )
+
+
+@router.post("/watch/start", response_model=WatchStatusResponse)
+async def start_watch_service(
+    request: Request, project_repository: ProjectRepositoryDep, sync_service: SyncServiceDep
+) -> WatchStatusResponse:
+    """Start the watch service if it's not already running."""
+
+    # needed because of circular imports from sync -> app
+    from basic_memory.sync import WatchService
+    from basic_memory.sync.background_sync import create_background_sync_task
+
+    if request.app.state.watch_task is not None and not request.app.state.watch_task.done():
+        # Watch service is already running
+        return WatchStatusResponse(running=True)
+
+    # Create and start a new watch service
+    logger.info("Starting watch service via management API")
+
+    # Get services needed for the watch task
+    watch_service = WatchService(
+        app_config=app_config,
+        project_repository=project_repository,
+    )
+
+    # Create and store the task
+    watch_task = create_background_sync_task(sync_service, watch_service)
+    request.app.state.watch_task = watch_task
+
+    return WatchStatusResponse(running=True)
+
+
+@router.post("/watch/stop", response_model=WatchStatusResponse)
+async def stop_watch_service(request: Request) -> WatchStatusResponse:  # pragma: no cover
+    """Stop the watch service if it's running."""
+    if request.app.state.watch_task is None or request.app.state.watch_task.done():
+        # Watch service is not running
+        return WatchStatusResponse(running=False)
+
+    # Cancel the running task
+    logger.info("Stopping watch service via management API")
+    request.app.state.watch_task.cancel()
+
+    # Wait for it to be properly cancelled
+    try:
+        await request.app.state.watch_task
+    except asyncio.CancelledError:
+        pass
+
+    request.app.state.watch_task = None
+    return WatchStatusResponse(running=False)

src/basic_memory/api/routers/memory_router.py

@@ -1,75 +1,22 @@
 """Routes for memory:// URI operations."""
 
-from typing import Annotated
+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.repository import EntityRepository
-from basic_memory.repository.search_repository import SearchIndexRow
-from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.base import TimeFrame, parse_timeframe
 from basic_memory.schemas.memory import (
     GraphContext,
-    RelationSummary,
-    EntitySummary,
-    ObservationSummary,
-    MemoryMetadata,
     normalize_memory_url,
 )
 from basic_memory.schemas.search import SearchItemType
-from basic_memory.services.context_service import ContextResultRow
+from basic_memory.api.routers.utils import to_graph_context
 
 router = APIRouter(prefix="/memory", tags=["memory"])
 
 
-async def to_graph_context(context, entity_repository: EntityRepository):
-    # return results
-    async def to_summary(item: SearchIndexRow | ContextResultRow):
-        match item.type:
-            case SearchItemType.ENTITY:
-                assert item.title is not None
-                assert item.created_at is not None
-
-                return EntitySummary(
-                    title=item.title,
-                    permalink=item.permalink,
-                    file_path=item.file_path,
-                    created_at=item.created_at,
-                )
-            case SearchItemType.OBSERVATION:
-                assert item.category is not None
-                assert item.content is not None
-
-                return ObservationSummary(
-                    category=item.category, content=item.content, permalink=item.permalink
-                )
-            case SearchItemType.RELATION:
-                assert item.from_id is not None
-                from_entity = await entity_repository.find_by_id(item.from_id)
-                assert from_entity is not None
-
-                to_entity = await entity_repository.find_by_id(item.to_id) if item.to_id else None
-
-                return RelationSummary(
-                    permalink=item.permalink,
-                    relation_type=item.type,
-                    from_id=from_entity.permalink,
-                    to_id=to_entity.permalink if to_entity else None,
-                )
-            case _:  # pragma: no cover
-                raise ValueError(f"Unexpected type: {item.type}")
-
-    primary_results = [await to_summary(r) for r in context["primary_results"]]
-    related_results = [await to_summary(r) for r in context["related_results"]]
-    metadata = MemoryMetadata.model_validate(context["metadata"])
-    # Transform to GraphContext
-    return GraphContext(
-        primary_results=primary_results, related_results=related_results, metadata=metadata
-    )
-
-
 @router.get("/recent", response_model=GraphContext)
 async def recent(
     context_service: ContextServiceDep,
@@ -77,7 +24,9 @@ async def recent(
     type: Annotated[list[SearchItemType] | None, Query()] = None,
     depth: int = 1,
     timeframe: TimeFrame = "7d",
-    max_results: int = 10,
+    page: int = 1,
+    page_size: int = 10,
+    max_related: int = 10,
 ) -> GraphContext:
     # return all types by default
     types = (
@@ -87,16 +36,22 @@ async def recent(
     )
 
     logger.debug(
-        f"Getting recent context: `{types}` depth: `{depth}` timeframe: `{timeframe}` max_results: `{max_results}`"
+        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
 
     # Build context
     context = await context_service.build_context(
-        types=types, depth=depth, since=since, max_results=max_results
+        types=types, depth=depth, since=since, limit=limit, offset=offset, max_related=max_related
     )
-    return await to_graph_context(context, entity_repository=entity_repository)
+    recent_context = await to_graph_context(
+        context, entity_repository=entity_repository, page=page, page_size=page_size
+    )
+    logger.debug(f"Recent context: {recent_context.model_dump_json()}")
+    return recent_context
 
 
 # get_memory_context needs to be declared last so other paths can match
@@ -108,22 +63,28 @@ async def get_memory_context(
     entity_repository: EntityRepositoryDep,
     uri: str,
     depth: int = 1,
-    timeframe: TimeFrame = "7d",
-    max_results: int = 10,
+    timeframe: Optional[TimeFrame] = None,
+    page: int = 1,
+    page_size: int = 10,
+    max_related: int = 10,
 ) -> GraphContext:
     """Get rich context from memory:// URI."""
     # add the project name from the config to the url as the "host
     # Parse URI
     logger.debug(
-        f"Getting context for URI: `{uri}` depth: `{depth}` timeframe: `{timeframe}` max_results: `{max_results}`"
+        f"Getting context for URI: `{uri}` depth: `{depth}` timeframe: `{timeframe}` page: `{page}` page_size: `{page_size}` max_related: `{max_related}`"
     )
     memory_url = normalize_memory_url(uri)
 
     # Parse timeframe
-    since = parse(timeframe)
+    since = parse_timeframe(timeframe) if timeframe else None
+    limit = page_size
+    offset = (page - 1) * page_size
 
     # Build context
     context = await context_service.build_context(
-        memory_url, depth=depth, since=since, max_results=max_results
+        memory_url, depth=depth, since=since, limit=limit, offset=offset, max_related=max_related
+    )
+    return await to_graph_context(
+        context, entity_repository=entity_repository, page=page, page_size=page_size
     )
-    return await to_graph_context(context, entity_repository=entity_repository)

src/basic_memory/api/routers/project_router.py

@@ -0,0 +1,234 @@
+"""Router for project management."""
+
+from fastapi import APIRouter, HTTPException, Path, Body
+from typing import Optional
+
+from basic_memory.deps import ProjectServiceDep, ProjectPathDep
+from basic_memory.schemas import ProjectInfoResponse
+from basic_memory.schemas.project_info import (
+    ProjectList,
+    ProjectItem,
+    ProjectInfoRequest,
+    ProjectStatusResponse,
+)
+
+# Router for resources in a specific project
+project_router = APIRouter(prefix="/project", tags=["project"])
+
+# Router for managing project resources
+project_resource_router = APIRouter(prefix="/projects", tags=["project_management"])
+
+
+@project_router.get("/info", response_model=ProjectInfoResponse)
+async def get_project_info(
+    project_service: ProjectServiceDep,
+    project: ProjectPathDep,
+) -> ProjectInfoResponse:
+    """Get comprehensive information about the specified Basic Memory project."""
+    return await project_service.get_project_info(project)
+
+
+# Update a project
+@project_router.patch("/{name}", response_model=ProjectStatusResponse)
+async def update_project(
+    project_service: ProjectServiceDep,
+    project_name: str = Path(..., description="Name of the project to update"),
+    path: Optional[str] = Body(None, description="New path for the project"),
+    is_active: Optional[bool] = Body(None, description="Status of the project (active/inactive)"),
+) -> ProjectStatusResponse:
+    """Update a project's information in configuration and database.
+
+    Args:
+        project_name: The name of the project to update
+        path: Optional new path for the project
+        is_active: Optional status update for the project
+
+    Returns:
+        Response confirming the project was updated
+    """
+    try:  # pragma: no cover
+        # Get original project info for the response
+        old_project_info = ProjectItem(
+            name=project_name,
+            path=project_service.projects.get(project_name, ""),
+        )
+
+        await project_service.update_project(project_name, updated_path=path, is_active=is_active)
+
+        # Get updated project info
+        updated_path = path if path else project_service.projects.get(project_name, "")
+
+        return ProjectStatusResponse(
+            message=f"Project '{project_name}' updated successfully",
+            status="success",
+            default=(project_name == project_service.default_project),
+            old_project=old_project_info,
+            new_project=ProjectItem(name=project_name, path=updated_path),
+        )
+    except ValueError as e:  # pragma: no cover
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+# List all available projects
+@project_resource_router.get("/projects", response_model=ProjectList)
+async def list_projects(
+    project_service: ProjectServiceDep,
+) -> ProjectList:
+    """List all configured projects.
+
+    Returns:
+        A list of all projects with metadata
+    """
+    projects = await project_service.list_projects()
+    default_project = project_service.default_project
+
+    project_items = [
+        ProjectItem(
+            name=project.name,
+            path=project.path,
+            is_default=project.is_default or False,
+        )
+        for project in projects
+    ]
+
+    return ProjectList(
+        projects=project_items,
+        default_project=default_project,
+    )
+
+
+# Add a new project
+@project_resource_router.post("/projects", response_model=ProjectStatusResponse)
+async def add_project(
+    project_data: ProjectInfoRequest,
+    project_service: ProjectServiceDep,
+) -> ProjectStatusResponse:
+    """Add a new project to configuration and database.
+
+    Args:
+        project_data: The project name and path, with option to set as default
+
+    Returns:
+        Response confirming the project was added
+    """
+    try:  # pragma: no cover
+        await project_service.add_project(
+            project_data.name, project_data.path, set_default=project_data.set_default
+        )
+
+        return ProjectStatusResponse(  # pyright: ignore [reportCallIssue]
+            message=f"Project '{project_data.name}' added successfully",
+            status="success",
+            default=project_data.set_default,
+            new_project=ProjectItem(
+                name=project_data.name, path=project_data.path, is_default=project_data.set_default
+            ),
+        )
+    except ValueError as e:  # pragma: no cover
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+# Remove a project
+@project_resource_router.delete("/{name}", response_model=ProjectStatusResponse)
+async def remove_project(
+    project_service: ProjectServiceDep,
+    name: str = Path(..., description="Name of the project to remove"),
+) -> ProjectStatusResponse:
+    """Remove a project from configuration and database.
+
+    Args:
+        name: The name of the project to remove
+
+    Returns:
+        Response confirming the project was removed
+    """
+    try:
+        old_project = await project_service.get_project(name)
+        if not old_project:  # pragma: no cover
+            raise HTTPException(
+                status_code=404, detail=f"Project: '{name}' does not exist"
+            )  # pragma: no cover
+
+        await project_service.remove_project(name)
+
+        return ProjectStatusResponse(
+            message=f"Project '{name}' removed successfully",
+            status="success",
+            default=False,
+            old_project=ProjectItem(name=old_project.name, path=old_project.path),
+            new_project=None,
+        )
+    except ValueError as e:  # pragma: no cover
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+# Set a project as default
+@project_resource_router.put("/{name}/default", response_model=ProjectStatusResponse)
+async def set_default_project(
+    project_service: ProjectServiceDep,
+    name: str = Path(..., description="Name of the project to set as default"),
+) -> ProjectStatusResponse:
+    """Set a project as the default project.
+
+    Args:
+        name: The name of the project to set as default
+
+    Returns:
+        Response confirming the project was set as default
+    """
+    try:
+        # Get the old default project
+        default_name = project_service.default_project
+        default_project = await project_service.get_project(default_name)
+        if not default_project:  # pragma: no cover
+            raise HTTPException(  # pragma: no cover
+                status_code=404, detail=f"Default Project: '{default_name}' does not exist"
+            )
+
+        # get the new project
+        new_default_project = await project_service.get_project(name)
+        if not new_default_project:  # pragma: no cover
+            raise HTTPException(
+                status_code=404, detail=f"Project: '{name}' does not exist"
+            )  # pragma: no cover
+
+        await project_service.set_default_project(name)
+
+        return ProjectStatusResponse(
+            message=f"Project '{name}' set as default successfully",
+            status="success",
+            default=True,
+            old_project=ProjectItem(name=default_name, path=default_project.path),
+            new_project=ProjectItem(
+                name=name,
+                path=new_default_project.path,
+                is_default=True,
+            ),
+        )
+    except ValueError as e:  # pragma: no cover
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+# Synchronize projects between config and database
+@project_resource_router.post("/sync", response_model=ProjectStatusResponse)
+async def synchronize_projects(
+    project_service: ProjectServiceDep,
+) -> ProjectStatusResponse:
+    """Synchronize projects between configuration file and database.
+
+    Ensures that all projects in the configuration file exist in the database
+    and vice versa.
+
+    Returns:
+        Response confirming synchronization was completed
+    """
+    try:  # pragma: no cover
+        await project_service.synchronize_projects()
+
+        return ProjectStatusResponse(  # pyright: ignore [reportCallIssue]
+            message="Projects synchronized successfully between configuration and database",
+            status="success",
+            default=False,
+        )
+    except ValueError as e:  # pragma: no cover
+        raise HTTPException(status_code=400, detail=str(e))

src/basic_memory/api/routers/prompt_router.py

@@ -0,0 +1,260 @@
+"""Router for prompt-related operations.
+
+This router is responsible for rendering various prompts using Handlebars templates.
+It centralizes all prompt formatting logic that was previously in the MCP prompts.
+"""
+
+from datetime import datetime, timezone
+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,
+    SearchServiceDep,
+    EntityServiceDep,
+)
+from basic_memory.schemas.prompt import (
+    ContinueConversationRequest,
+    SearchPromptRequest,
+    PromptResponse,
+    PromptMetadata,
+)
+from basic_memory.schemas.search import SearchItemType, SearchQuery
+
+router = APIRouter(prefix="/prompt", tags=["prompt"])
+
+
+@router.post("/continue-conversation", response_model=PromptResponse)
+async def continue_conversation(
+    search_service: SearchServiceDep,
+    entity_service: EntityServiceDep,
+    context_service: ContextServiceDep,
+    entity_repository: EntityRepositoryDep,
+    request: ContinueConversationRequest,
+) -> PromptResponse:
+    """Generate a prompt for continuing a conversation.
+
+    This endpoint takes a topic and/or timeframe and generates a prompt with
+    relevant context from the knowledge base.
+
+    Args:
+        request: The request parameters
+
+    Returns:
+        Formatted continuation prompt with context
+    """
+    logger.info(
+        f"Generating continue conversation prompt, topic: {request.topic}, timeframe: {request.timeframe}"
+    )
+
+    since = parse_timeframe(request.timeframe) if request.timeframe else None
+
+    # Initialize search results
+    search_results = []
+
+    # Get data needed for template
+    if request.topic:
+        query = SearchQuery(text=request.topic, after_date=request.timeframe)
+        results = await search_service.search(query, limit=request.search_items_limit)
+        search_results = await to_search_results(entity_service, results)
+
+        # Build context from results
+        all_hierarchical_results = []
+        for result in search_results:
+            if hasattr(result, "permalink") and result.permalink:
+                # Get hierarchical context using the new dataclass-based approach
+                context_result = await context_service.build_context(
+                    result.permalink,
+                    depth=request.depth,
+                    since=since,
+                    max_related=request.related_items_limit,
+                    include_observations=True,  # Include observations for entities
+                )
+
+                # Process results into the schema format
+                graph_context = await to_graph_context(
+                    context_result, entity_repository=entity_repository
+                )
+
+                # Add results to our collection (limit to top results for each permalink)
+                if graph_context.results:
+                    all_hierarchical_results.extend(graph_context.results[:3])
+
+        # Limit to a reasonable number of total results
+        all_hierarchical_results = all_hierarchical_results[:10]
+
+        template_context = {
+            "topic": request.topic,
+            "timeframe": request.timeframe,
+            "hierarchical_results": all_hierarchical_results,
+            "has_results": len(all_hierarchical_results) > 0,
+        }
+    else:
+        # If no topic, get recent activity
+        context_result = await context_service.build_context(
+            types=[SearchItemType.ENTITY],
+            depth=request.depth,
+            since=since,
+            max_related=request.related_items_limit,
+            include_observations=True,
+        )
+        recent_context = await to_graph_context(context_result, entity_repository=entity_repository)
+
+        hierarchical_results = recent_context.results[:5]  # Limit to top 5 recent items
+
+        template_context = {
+            "topic": f"Recent Activity from ({request.timeframe})",
+            "timeframe": request.timeframe,
+            "hierarchical_results": hierarchical_results,
+            "has_results": len(hierarchical_results) > 0,
+        }
+
+    try:
+        # Render template
+        rendered_prompt = await template_loader.render(
+            "prompts/continue_conversation.hbs", template_context
+        )
+
+        # Calculate metadata
+        # Count items of different types
+        observation_count = 0
+        relation_count = 0
+        entity_count = 0
+
+        # Get the hierarchical results from the template context
+        hierarchical_results_for_count = template_context.get("hierarchical_results", [])
+
+        # For topic-based search
+        if request.topic:
+            for item in hierarchical_results_for_count:
+                if hasattr(item, "observations"):
+                    observation_count += len(item.observations) if item.observations else 0
+
+                if hasattr(item, "related_results"):
+                    for related in item.related_results or []:
+                        if hasattr(related, "type"):
+                            if related.type == "relation":
+                                relation_count += 1
+                            elif related.type == "entity":  # pragma: no cover
+                                entity_count += 1  # pragma: no cover
+        # For recent activity
+        else:
+            for item in hierarchical_results_for_count:
+                if hasattr(item, "observations"):
+                    observation_count += len(item.observations) if item.observations else 0
+
+                if hasattr(item, "related_results"):
+                    for related in item.related_results or []:
+                        if hasattr(related, "type"):
+                            if related.type == "relation":
+                                relation_count += 1
+                            elif related.type == "entity":  # pragma: no cover
+                                entity_count += 1  # pragma: no cover
+
+        # Build metadata
+        metadata = {
+            "query": request.topic,
+            "timeframe": request.timeframe,
+            "search_count": len(search_results)
+            if request.topic
+            else 0,  # Original search results count
+            "context_count": len(hierarchical_results_for_count),
+            "observation_count": observation_count,
+            "relation_count": relation_count,
+            "total_items": (
+                len(hierarchical_results_for_count)
+                + observation_count
+                + relation_count
+                + entity_count
+            ),
+            "search_limit": request.search_items_limit,
+            "context_depth": request.depth,
+            "related_limit": request.related_items_limit,
+            "generated_at": datetime.now(timezone.utc).isoformat(),
+        }
+
+        prompt_metadata = PromptMetadata(**metadata)
+
+        return PromptResponse(
+            prompt=rendered_prompt, context=template_context, metadata=prompt_metadata
+        )
+    except Exception as e:
+        logger.error(f"Error rendering continue conversation template: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error rendering prompt template: {str(e)}",
+        )
+
+
+@router.post("/search", response_model=PromptResponse)
+async def search_prompt(
+    search_service: SearchServiceDep,
+    entity_service: EntityServiceDep,
+    request: SearchPromptRequest,
+    page: int = 1,
+    page_size: int = 10,
+) -> PromptResponse:
+    """Generate a prompt for search results.
+
+    This endpoint takes a search query and formats the results into a helpful
+    prompt with context and suggestions.
+
+    Args:
+        request: The search parameters
+        page: The page number for pagination
+        page_size: The number of results per page, defaults to 10
+
+    Returns:
+        Formatted search results prompt with context
+    """
+    logger.info(f"Generating search prompt, query: {request.query}, timeframe: {request.timeframe}")
+
+    limit = page_size
+    offset = (page - 1) * page_size
+
+    query = SearchQuery(text=request.query, after_date=request.timeframe)
+    results = await search_service.search(query, limit=limit, offset=offset)
+    search_results = await to_search_results(entity_service, results)
+
+    template_context = {
+        "query": request.query,
+        "timeframe": request.timeframe,
+        "results": search_results,
+        "has_results": len(search_results) > 0,
+        "result_count": len(search_results),
+    }
+
+    try:
+        # Render template
+        rendered_prompt = await template_loader.render("prompts/search.hbs", template_context)
+
+        # Build metadata
+        metadata = {
+            "query": request.query,
+            "timeframe": request.timeframe,
+            "search_count": len(search_results),
+            "context_count": len(search_results),
+            "observation_count": 0,  # Search results don't include observations
+            "relation_count": 0,  # Search results don't include relations
+            "total_items": len(search_results),
+            "search_limit": limit,
+            "context_depth": 0,  # No context depth for basic search
+            "related_limit": 0,  # No related items for basic search
+            "generated_at": datetime.now(timezone.utc).isoformat(),
+        }
+
+        prompt_metadata = PromptMetadata(**metadata)
+
+        return PromptResponse(
+            prompt=rendered_prompt, context=template_context, metadata=prompt_metadata
+        )
+    except Exception as e:
+        logger.error(f"Error rendering search template: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error rendering prompt template: {str(e)}",
+        )

src/basic_memory/api/routers/resource_router.py

@@ -1,34 +1,225 @@
 """Routes for getting entity content."""
 
+import tempfile
 from pathlib import Path
+from typing import Annotated
 
-from fastapi import APIRouter, HTTPException
-from fastapi.responses import FileResponse
+from fastapi import APIRouter, HTTPException, BackgroundTasks, Body
+from fastapi.responses import FileResponse, JSONResponse
 from loguru import logger
 
-from basic_memory.deps import ProjectConfigDep, LinkResolverDep
+from basic_memory.deps import (
+    ProjectConfigDep,
+    LinkResolverDep,
+    SearchServiceDep,
+    EntityServiceDep,
+    FileServiceDep,
+    EntityRepositoryDep,
+)
+from basic_memory.repository.search_repository import SearchIndexRow
+from basic_memory.schemas.memory import normalize_memory_url
+from basic_memory.schemas.search import SearchQuery, SearchItemType
+from basic_memory.models.knowledge import Entity as EntityModel
+from datetime import datetime
 
 router = APIRouter(prefix="/resource", tags=["resources"])
 
 
+def get_entity_ids(item: SearchIndexRow) -> set[int]:
+    match item.type:
+        case SearchItemType.ENTITY:
+            return {item.id}
+        case SearchItemType.OBSERVATION:
+            return {item.entity_id}  # pyright: ignore [reportReturnType]
+        case SearchItemType.RELATION:
+            from_entity = item.from_id
+            to_entity = item.to_id  # pyright: ignore [reportReturnType]
+            return {from_entity, to_entity} if to_entity else {from_entity}  # pyright: ignore [reportReturnType]
+        case _:  # pragma: no cover
+            raise ValueError(f"Unexpected type: {item.type}")
+
+
 @router.get("/{identifier:path}")
 async def get_resource_content(
     config: ProjectConfigDep,
     link_resolver: LinkResolverDep,
+    search_service: SearchServiceDep,
+    entity_service: EntityServiceDep,
+    file_service: FileServiceDep,
+    background_tasks: BackgroundTasks,
     identifier: str,
+    page: int = 1,
+    page_size: int = 10,
 ) -> FileResponse:
     """Get resource content by identifier: name or permalink."""
-    logger.debug(f"Getting content for permalink: {identifier}")
+    logger.debug(f"Getting content for: {identifier}")
 
-    # Find entity by permalink
+    # Find single entity by permalink
     entity = await link_resolver.resolve_link(identifier)
-    if not entity:
-        raise HTTPException(status_code=404, detail=f"Entity not found: {identifier}")
+    results = [entity] if entity else []
 
-    file_path = Path(f"{config.home}/{entity.file_path}")
-    if not file_path.exists():
-        raise HTTPException(
-            status_code=404,
-            detail=f"File not found: {file_path}",
+    # pagination for multiple results
+    limit = page_size
+    offset = (page - 1) * page_size
+
+    # search using the identifier as a permalink
+    if not results:
+        # if the identifier contains a wildcard, use GLOB search
+        query = (
+            SearchQuery(permalink_match=identifier)
+            if "*" in identifier
+            else SearchQuery(permalink=identifier)
         )
-    return FileResponse(path=file_path)
+        search_results = await search_service.search(query, limit, offset)
+        if not search_results:
+            raise HTTPException(status_code=404, detail=f"Resource not found: {identifier}")
+
+        # get the deduplicated entities related to the search results
+        entity_ids = {id for result in search_results for id in get_entity_ids(result)}
+        results = await entity_service.get_entities_by_id(list(entity_ids))
+
+    # return single response
+    if len(results) == 1:
+        entity = results[0]
+        file_path = Path(f"{config.home}/{entity.file_path}")
+        if not file_path.exists():
+            raise HTTPException(
+                status_code=404,
+                detail=f"File not found: {file_path}",
+            )
+        return FileResponse(path=file_path)
+
+    # for multiple files, initialize a temporary file for writing the results
+    with tempfile.NamedTemporaryFile(delete=False, mode="w", suffix=".md") as tmp_file:
+        temp_file_path = tmp_file.name
+
+        for result in results:
+            # Read content for each entity
+            content = await file_service.read_entity_content(result)
+            memory_url = normalize_memory_url(result.permalink)
+            modified_date = result.updated_at.isoformat()
+            checksum = result.checksum[:8] if result.checksum else ""
+
+            # Prepare the delimited content
+            response_content = f"--- {memory_url} {modified_date} {checksum}\n"
+            response_content += f"\n{content}\n"
+            response_content += "\n"
+
+            # Write content directly to the temporary file in append mode
+            tmp_file.write(response_content)
+
+        # Ensure all content is written to disk
+        tmp_file.flush()
+
+    # Schedule the temporary file to be deleted after the response
+    background_tasks.add_task(cleanup_temp_file, temp_file_path)
+
+    # Return the file response
+    return FileResponse(path=temp_file_path)
+
+
+def cleanup_temp_file(file_path: str):
+    """Delete the temporary file."""
+    try:
+        Path(file_path).unlink()  # Deletes the file
+        logger.debug(f"Temporary file deleted: {file_path}")
+    except Exception as e:  # pragma: no cover
+        logger.error(f"Error deleting temporary file {file_path}: {e}")
+
+
+@router.put("/{file_path:path}")
+async def write_resource(
+    config: ProjectConfigDep,
+    file_service: FileServiceDep,
+    entity_repository: EntityRepositoryDep,
+    search_service: SearchServiceDep,
+    file_path: str,
+    content: Annotated[str, Body()],
+) -> JSONResponse:
+    """Write content to a file in the project.
+
+    This endpoint allows writing content directly to a file in the project.
+    Also creates an entity record and indexes the file for search.
+
+    Args:
+        file_path: Path to write to, relative to project root
+        request: Contains the content to write
+
+    Returns:
+        JSON response with file information
+    """
+    try:
+        # Get content from request body
+
+        # Ensure it's UTF-8 string content
+        if isinstance(content, bytes):  # pragma: no cover
+            content_str = content.decode("utf-8")
+        else:
+            content_str = str(content)
+
+        # Get full file path
+        full_path = Path(f"{config.home}/{file_path}")
+
+        # Ensure parent directory exists
+        full_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write content to file
+        checksum = await file_service.write_file(full_path, content_str)
+
+        # Get file info
+        file_stats = file_service.file_stats(full_path)
+
+        # Determine file details
+        file_name = Path(file_path).name
+        content_type = file_service.content_type(full_path)
+
+        entity_type = "canvas" if file_path.endswith(".canvas") else "file"
+
+        # Check if entity already exists
+        existing_entity = await entity_repository.get_by_file_path(file_path)
+
+        if existing_entity:
+            # Update existing entity
+            entity = await entity_repository.update(
+                existing_entity.id,
+                {
+                    "title": file_name,
+                    "entity_type": entity_type,
+                    "content_type": content_type,
+                    "file_path": file_path,
+                    "checksum": checksum,
+                    "updated_at": datetime.fromtimestamp(file_stats.st_mtime),
+                },
+            )
+            status_code = 200
+        else:
+            # Create a new entity model
+            entity = EntityModel(
+                title=file_name,
+                entity_type=entity_type,
+                content_type=content_type,
+                file_path=file_path,
+                checksum=checksum,
+                created_at=datetime.fromtimestamp(file_stats.st_ctime),
+                updated_at=datetime.fromtimestamp(file_stats.st_mtime),
+            )
+            entity = await entity_repository.add(entity)
+            status_code = 201
+
+        # Index the file for search
+        await search_service.index_entity(entity)  # pyright: ignore
+
+        # Return success response
+        return JSONResponse(
+            status_code=status_code,
+            content={
+                "file_path": file_path,
+                "checksum": checksum,
+                "size": file_stats.st_size,
+                "created_at": file_stats.st_ctime,
+                "modified_at": file_stats.st_mtime,
+            },
+        )
+    except Exception as e:  # pragma: no cover
+        logger.error(f"Error writing resource {file_path}: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to write resource: {str(e)}")

src/basic_memory/api/routers/search_router.py

@@ -1,28 +1,36 @@
 """Router for search operations."""
 
-from dataclasses import asdict
+from fastapi import APIRouter, BackgroundTasks
 
-from fastapi import APIRouter, Depends, BackgroundTasks
-
-from basic_memory.services.search_service import SearchService
-from basic_memory.schemas.search import SearchQuery, SearchResult, SearchResponse
-from basic_memory.deps import get_search_service
+from basic_memory.api.routers.utils import to_search_results
+from basic_memory.schemas.search import SearchQuery, SearchResponse
+from basic_memory.deps import SearchServiceDep, EntityServiceDep
 
 router = APIRouter(prefix="/search", tags=["search"])
 
 
 @router.post("/", response_model=SearchResponse)
-async def search(query: SearchQuery, search_service: SearchService = Depends(get_search_service)):
+async def search(
+    query: SearchQuery,
+    search_service: SearchServiceDep,
+    entity_service: EntityServiceDep,
+    page: int = 1,
+    page_size: int = 10,
+):
     """Search across all knowledge and documents."""
-    results = await search_service.search(query)
-    search_results = [SearchResult.model_validate(asdict(r)) for r in results]
-    return SearchResponse(results=search_results)
+    limit = page_size
+    offset = (page - 1) * page_size
+    results = await search_service.search(query, limit=limit, offset=offset)
+    search_results = await to_search_results(entity_service, results)
+    return SearchResponse(
+        results=search_results,
+        current_page=page,
+        page_size=page_size,
+    )
 
 
 @router.post("/reindex")
-async def reindex(
-    background_tasks: BackgroundTasks, search_service: SearchService = Depends(get_search_service)
-):
+async def reindex(background_tasks: BackgroundTasks, search_service: SearchServiceDep):
     """Recreate and populate the search index."""
     await search_service.reindex_all(background_tasks=background_tasks)
     return {"status": "ok", "message": "Reindex initiated"}

src/basic_memory/api/routers/utils.py

@@ -0,0 +1,130 @@
+from typing import Optional, List
+
+from basic_memory.repository import EntityRepository
+from basic_memory.repository.search_repository import SearchIndexRow
+from basic_memory.schemas.memory import (
+    EntitySummary,
+    ObservationSummary,
+    RelationSummary,
+    MemoryMetadata,
+    GraphContext,
+    ContextResult,
+)
+from basic_memory.schemas.search import SearchItemType, SearchResult
+from basic_memory.services import EntityService
+from basic_memory.services.context_service import (
+    ContextResultRow,
+    ContextResult as ServiceContextResult,
+)
+
+
+async def to_graph_context(
+    context_result: ServiceContextResult,
+    entity_repository: EntityRepository,
+    page: Optional[int] = None,
+    page_size: Optional[int] = None,
+):
+    # Helper function to convert items to summaries
+    async def to_summary(item: SearchIndexRow | ContextResultRow):
+        match item.type:
+            case SearchItemType.ENTITY:
+                return EntitySummary(
+                    title=item.title,  # pyright: ignore
+                    permalink=item.permalink,
+                    content=item.content,
+                    file_path=item.file_path,
+                    created_at=item.created_at,
+                )
+            case SearchItemType.OBSERVATION:
+                return ObservationSummary(
+                    title=item.title,  # pyright: ignore
+                    file_path=item.file_path,
+                    category=item.category,  # pyright: ignore
+                    content=item.content,  # pyright: ignore
+                    permalink=item.permalink,  # pyright: ignore
+                    created_at=item.created_at,
+                )
+            case SearchItemType.RELATION:
+                from_entity = await entity_repository.find_by_id(item.from_id)  # pyright: ignore
+                to_entity = await entity_repository.find_by_id(item.to_id) if item.to_id else None
+                return RelationSummary(
+                    title=item.title,  # pyright: ignore
+                    file_path=item.file_path,
+                    permalink=item.permalink,  # pyright: ignore
+                    relation_type=item.relation_type,  # pyright: ignore
+                    from_entity=from_entity.title,  # pyright: ignore
+                    to_entity=to_entity.title if to_entity else None,
+                    created_at=item.created_at,
+                )
+            case _:  # pragma: no cover
+                raise ValueError(f"Unexpected type: {item.type}")
+
+    # Process the hierarchical results
+    hierarchical_results = []
+    for context_item in context_result.results:
+        # Process primary result
+        primary_result = await to_summary(context_item.primary_result)
+
+        # Process observations
+        observations = []
+        for obs in context_item.observations:
+            observations.append(await to_summary(obs))
+
+        # Process related results
+        related = []
+        for rel in context_item.related_results:
+            related.append(await to_summary(rel))
+
+        # Add to hierarchical results
+        hierarchical_results.append(
+            ContextResult(
+                primary_result=primary_result,
+                observations=observations,
+                related_results=related,
+            )
+        )
+
+    # Create schema metadata from service metadata
+    metadata = MemoryMetadata(
+        uri=context_result.metadata.uri,
+        types=context_result.metadata.types,
+        depth=context_result.metadata.depth,
+        timeframe=context_result.metadata.timeframe,
+        generated_at=context_result.metadata.generated_at,
+        primary_count=context_result.metadata.primary_count,
+        related_count=context_result.metadata.related_count,
+        total_results=context_result.metadata.primary_count + context_result.metadata.related_count,
+        total_relations=context_result.metadata.total_relations,
+        total_observations=context_result.metadata.total_observations,
+    )
+
+    # Return new GraphContext with just hierarchical results
+    return GraphContext(
+        results=hierarchical_results,
+        metadata=metadata,
+        page=page,
+        page_size=page_size,
+    )
+
+
+async def to_search_results(entity_service: EntityService, results: List[SearchIndexRow]):
+    search_results = []
+    for r in results:
+        entities = await entity_service.get_entities_by_id([r.entity_id, r.from_id, r.to_id])  # pyright: ignore
+        search_results.append(
+            SearchResult(
+                title=r.title,  # pyright: ignore
+                type=r.type,  # pyright: ignore
+                permalink=r.permalink,
+                score=r.score,  # pyright: ignore
+                entity=entities[0].permalink if entities else None,
+                content=r.content,
+                file_path=r.file_path,
+                metadata=r.metadata,
+                category=r.category,
+                from_entity=entities[0].permalink if entities else None,
+                to_entity=entities[1].permalink if len(entities) > 1 else None,
+                relation_type=r.relation_type,
+            )
+        )
+    return search_results