basic-memory 0.2.11__tar.gz → 0.17.0__tar.gz

basic_memory-0.17.0/.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

basic_memory-0.17.0/.claude/commands/release/changelog.md

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

basic_memory-0.17.0/.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

basic_memory-0.17.0/.claude/commands/release/release.md

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

basic_memory-0.17.0/.claude/commands/spec.md

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