chore: update version to 0.15.0 for v0.15.0 release

Auto-format test files for permalink collision tests.

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

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

.claude/agents/python-developer.md

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

.claude/agents/system-architect.md

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

.claude/commands/spec.md

@@ -0,0 +1,55 @@
+---
+allowed-tools: mcp__basic-memory__write_note, mcp__basic-memory__read_note, mcp__basic-memory__search_notes, mcp__basic-memory__edit_note, Task
+argument-hint: [create|status|implement|review] [spec-name]
+description: Manage specifications in our development process
+---
+
+## Context
+
+You are managing specifications using our specification-driven development process defined in @docs/specs/SPEC-001.md.
+
+Available commands:
+- `create [name]` - Create new specification
+- `status` - Show all spec statuses
+- `implement [spec-name]` - Hand spec to appropriate agent
+- `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
+2. Create new spec using template from @docs/specs/Slash\ Commands\ Reference.md
+3. Place in `/specs` folder with title "SPEC-XXX: [name]"
+4. Include standard sections: Why, What, How, How to Evaluate
+
+### If command is "status":
+1. Search all notes in `/specs` folder
+2. Display table with spec number, title, and status
+3. Show any dependencies or assigned agents
+
+### If command is "implement":
+1. Read the specified spec
+2. Determine appropriate agent based on content:
+   - Frontend/UI → vue-developer
+   - Architecture/system → system-architect  
+   - Backend/API → python-developer
+3. Launch Task tool with appropriate agent and spec context
+
+### 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
+5. If gaps found, clearly identify what still needs to be implemented/tested
+
+Use the agent definitions from @docs/specs/Agent\ Definitions.md for implementation handoffs.

.claude/commands/test-live.md

@@ -11,7 +11,7 @@ All test results are recorded as notes in a dedicated test project.
 **Parameters:**
 - `phase` (optional): Specific test phase to run (`recent`, `core`, `features`, `edge`, `workflows`, `stress`, or `all`)
 - `recent` - Focus on recent changes and new features (recommended for regular testing)
-- `core` - Essential tools only (Tier 1: write_note, read_note, search_notes, edit_note, list_projects, switch_project)
+- `core` - Essential tools only (Tier 1: write_note, read_note, search_notes, edit_note, list_memory_projects, recent_activity)
 - `features` - Core + important workflows (Tier 1 + Tier 2)
 - `all` - Comprehensive testing of all tools and scenarios
 
@@ -24,30 +24,66 @@ When the user runs `/project:test-live`, execute comprehensive test plan:
 
 ### **Tier 1: Critical Core (Always Test)**
 1. **write_note** - Foundation of all knowledge creation
-2. **read_note** - Primary knowledge retrieval mechanism  
+2. **read_note** - Primary knowledge retrieval mechanism
 3. **search_notes** - Essential for finding information
 4. **edit_note** - Core content modification capability
-5. **list_memory_projects** - Project discovery and status
-6. **switch_project** - Context switching for multi-project workflows
+5. **list_memory_projects** - Project discovery and session guidance
+6. **recent_activity** - Project discovery mode and activity analysis
 
 ### **Tier 2: Important Workflows (Usually Test)**
-7. **recent_activity** - Understanding what's changed
-8. **build_context** - Conversation continuity via memory:// URLs
-9. **create_memory_project** - Essential for project setup
-10. **move_note** - Knowledge organization
-11. **sync_status** - Understanding system state
+7. **build_context** - Conversation continuity via memory:// URLs
+8. **create_memory_project** - Essential for project setup
+9. **move_note** - Knowledge organization
+10. **sync_status** - Understanding system state
+11. **delete_project** - Project lifecycle management
 
 ### **Tier 3: Enhanced Functionality (Sometimes Test)**
 12. **view_note** - Claude Desktop artifact display
 13. **read_content** - Raw content access
 14. **delete_note** - Content removal
 15. **list_directory** - File system exploration
-16. **set_default_project** - Configuration
-17. **delete_project** - Administrative cleanup
+16. **edit_note** (advanced modes) - Complex find/replace operations
 
 ### **Tier 4: Specialized (Rarely Test)**
-18. **canvas** - Obsidian visualization (specialized use case)
-19. **MCP Prompts** - Enhanced UX tools (ai_assistant_guide, continue_conversation)
+17. **canvas** - Obsidian visualization (specialized use case)
+18. **MCP Prompts** - Enhanced UX tools (ai_assistant_guide, continue_conversation)
+
+## Stateless Architecture Testing
+
+### **Project Discovery Workflow (CRITICAL)**
+Test the new stateless project selection flow:
+
+1. **Initial Discovery**
+   - Call `list_memory_projects()` without knowing which project to use
+   - Verify clear session guidance appears: "Next: Ask which project to use"
+   - Confirm removal of CLI-specific references
+
+2. **Activity-Based Discovery**
+   - Call `recent_activity()` without project parameter (discovery mode)
+   - Verify intelligent project suggestions based on activity
+   - Test guidance: "Should I use [most-active-project] for this task?"
+
+3. **Session Tracking Validation**
+   - Verify all tool responses include `[Session: Using project 'name']`
+   - Confirm guidance reminds about session-wide project tracking
+
+4. **Single Project Constraint Mode**
+   - Test MCP server with `--project` parameter
+   - Verify all operations constrained to specified project
+   - Test project override behavior in constrained mode
+
+### **Explicit Project Parameters (CRITICAL)**
+All tools must require explicit project parameters:
+
+1. **Parameter Validation**
+   - Test all Tier 1 tools require `project` parameter
+   - Verify clear error messages for missing project
+   - Test invalid project name handling
+
+2. **No Session State Dependencies**
+   - Confirm no tool relies on "current project" concept
+   - Test rapid project switching within conversation
+   - Verify each call is truly independent
 
 ### Pre-Test Setup
 
@@ -72,7 +108,7 @@ Run the bash `date` command to get the current date/time.
    Purpose: Record all test observations and results
    ```
 
-Make sure to switch to the newly created project with the `switch_project()` tool.
+Make sure to use the newly created project for all subsequent test operations by specifying it in the `project` parameter of each tool call.
 
 4. **Baseline Documentation**
    Create initial test session note with:
@@ -143,46 +179,42 @@ Test essential MCP tools that form the foundation of Basic Memory:
 - ⚠️ Error scenarios (invalid operations)
 
 **5. list_memory_projects Tests (Critical):**
-- ✅ Display all projects with status indicators
-- ✅ Current and default project identification
+- ✅ Display all projects with clear session guidance
+- ✅ Project discovery workflow prompts
+- ✅ Removal of CLI-specific references
 - ✅ Empty project list handling
-- ✅ Project metadata accuracy
+- ✅ Single project constraint mode display
 
-**6. switch_project Tests (Critical):**
-- ✅ Switch between existing projects
-- ✅ Context preservation during switch
-- ⚠️ Invalid project name handling
-- ✅ Confirmation of successful switch
+**6. recent_activity Tests (Critical - Discovery Mode):**
+- ✅ Discovery mode without project parameter
+- ✅ Intelligent project suggestions based on activity
+- ✅ Guidance prompts for project selection
+- ✅ Session tracking reminders in responses
+- ⚠️ Performance with multiple projects
 
 ### Phase 2: Important Workflows (Tier 2 Tools)
 
-**7. recent_activity Tests (Important):**
-- ✅ Various timeframes ("today", "1 week", "1d")
-- ✅ Type filtering capabilities
-- ✅ Empty project scenarios
-- ⚠️ Performance with many recent changes
-
-**8. build_context Tests (Important):**
+**7. build_context Tests (Important):**
 - ✅ Different depth levels (1, 2, 3+)
 - ✅ Various timeframes for context
 - ✅ memory:// URL navigation
 - ⚠️ Performance with complex relation graphs
 
-**9. create_memory_project Tests (Important):**
+**8. create_memory_project Tests (Important):**
 - ✅ Create projects dynamically
 - ✅ Set default during creation
 - ✅ Path validation and creation
 - ⚠️ Invalid paths and names
 - ✅ Integration with existing projects
 
-**10. move_note Tests (Important):**
+**9. move_note Tests (Important):**
 - ✅ Move within same project
 - ✅ Cross-project moves with detection (#161)
 - ✅ Automatic folder creation
 - ✅ Database consistency validation
 - ⚠️ Special characters in paths
 
-**11. sync_status Tests (Important):**
+**10. sync_status Tests (Important):**
 - ✅ Background operation monitoring
 - ✅ File synchronization status
 - ✅ Project sync state reporting
@@ -190,36 +222,31 @@ Test essential MCP tools that form the foundation of Basic Memory:
 
 ### Phase 3: Enhanced Functionality (Tier 3 Tools)
 
-**12. view_note Tests (Enhanced):**
+**11. view_note Tests (Enhanced):**
 - ✅ Claude Desktop artifact display
 - ✅ Title extraction from frontmatter
 - ✅ Unicode and emoji content rendering
 - ⚠️ Error handling for non-existent notes
 
-**13. read_content Tests (Enhanced):**
+**12. read_content Tests (Enhanced):**
 - ✅ Raw file content access
 - ✅ Binary file handling
 - ✅ Image file reading
 - ⚠️ Large file performance
 
-**14. delete_note Tests (Enhanced):**
+**13. delete_note Tests (Enhanced):**
 - ✅ Single note deletion
 - ✅ Database consistency after deletion
 - ⚠️ Non-existent note handling
 - ✅ Confirmation of successful deletion
 
-**15. list_directory Tests (Enhanced):**
+**14. list_directory Tests (Enhanced):**
 - ✅ Directory content listing
 - ✅ Depth control and filtering
 - ✅ File name globbing
 - ⚠️ Empty directory handling
 
-**16. set_default_project Tests (Enhanced):**
-- ✅ Change default project
-- ✅ Configuration persistence
-- ⚠️ Invalid project handling
-
-**17. delete_project Tests (Enhanced):**
+**15. delete_project Tests (Enhanced):**
 - ✅ Project removal from config
 - ✅ Database cleanup
 - ⚠️ Default project protection
@@ -269,7 +296,7 @@ Test essential MCP tools that form the foundation of Basic Memory:
 1. Technical documentation project
 2. Personal recipe collection project
 3. Learning/course notes project
-4. Switch contexts during conversation
+4. Specify different projects for different operations
 5. Cross-reference related concepts
 
 **Content Evolution:**
@@ -281,13 +308,13 @@ Test essential MCP tools that form the foundation of Basic Memory:
 
 ### Phase 6: Specialized Tools Testing (Tier 4)
 
-**18. canvas Tests (Specialized):**
+**16. canvas Tests (Specialized):**
 - ✅ JSON Canvas generation
 - ✅ Node and edge creation
 - ✅ Obsidian compatibility
 - ⚠️ Complex graph handling
 
-**19. MCP Prompts Tests (Specialized):**
+**17. MCP Prompts Tests (Specialized):**
 - ✅ ai_assistant_guide output
 - ✅ continue_conversation functionality
 - ✅ Formatted search results
@@ -382,7 +409,7 @@ permalink: test-session-[phase]-[timestamp]
 ### 📊 Performance Metrics
 - Average write_note time: 0.3s
 - Search with 100+ notes: 0.6s
-- Project switch overhead: 0.1s
+- Project parameter overhead: <0.1s
 - Memory usage: [observed levels]
 
 ## Relations
@@ -402,7 +429,7 @@ permalink: test-session-[phase]-[timestamp]
 - Learning curve and intuitiveness
 
 **System Behavior:**
-- Context preservation across operations
+- Stateless operation independence
 - memory:// URL navigation reliability
 - Multi-step workflow cohesion
 - Edge case graceful handling

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

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

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

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

.github/workflows/claude.yml

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

.github/workflows/test.yml

@@ -18,7 +18,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest]
-        python-version: [ "3.12" ]
+        python-version: [ "3.12", "3.13" ]
     runs-on: ${{ matrix.os }}
 
     steps:
@@ -58,9 +58,17 @@ jobs:
 
       - name: Run type checks
         run: |
-          just type-check
+          just typecheck
+
+      - name: Run type checks
+        run: |
+          just typecheck
+
+      - name: Run linting
+        run: |
+          just lint
 
       - name: Run tests
         run: |
           uv pip install pytest pytest-cov
-          just test
+          just test

CHANGELOG.md

@@ -1,5 +1,222 @@
 # CHANGELOG
 
+## v0.15.0 (2025-10-04)
+
+### Critical Bug Fixes
+
+- **Permalink Collision Data Loss Prevention** - Fixed critical bug where creating similar entity names would overwrite existing files
+  ([`2a050ed`](https://github.com/basicmachines-co/basic-memory/commit/2a050edee42b07294f5199902a60b626bfc47be8))
+  - **Issue**: Creating "Node C" would overwrite "Node A.md" due to fuzzy search incorrectly matching similar file paths
+  - **Solution**: Added `strict=True` parameter to link resolution, disabling fuzzy search fallback during entity creation
+  - **Impact**: Prevents data loss from false positive path matching like "edge-cases/Node A.md" vs "edge-cases/Node C.md"
+  - **Testing**: Comprehensive integration tests and MCP-level permalink collision tests added
+  - **Status**: Manually verified fix prevents file overwrite in production scenarios
+
+### Bug Fixes
+
+- **#330**: Remove .env file loading from BasicMemoryConfig
+  ([`f3b1945`](https://github.com/basicmachines-co/basic-memory/commit/f3b1945e4c0070d0282eaf98c085ef188c8edd2d))
+  - Clean up configuration initialization to prevent unintended environment variable loading
+
+- **#329**: Normalize underscores in memory:// URLs for build_context
+  ([`f5a11f3`](https://github.com/basicmachines-co/basic-memory/commit/f5a11f3911edda55bee6970ed9e7c38f7fd7a059))
+  - Fix URL normalization to handle underscores consistently in memory:// protocol
+  - Improve knowledge graph navigation with standardized URL handling
+
+- **#328**: Simplify entity upsert to use database-level conflict resolution
+  ([`ee83b0e`](https://github.com/basicmachines-co/basic-memory/commit/ee83b0e5a8f00cdcc8e24a0f8c9449c6eaddf649))
+  - Leverage SQLite's native UPSERT for cleaner entity creation/update logic
+  - Reduce application-level complexity by using database conflict resolution
+
+- **#312**: Add proper datetime JSON schema format annotations for MCP validation
+  ([`a7bf42e`](https://github.com/basicmachines-co/basic-memory/commit/a7bf42ef495a3e2c66230985c3445cab5c52c408))
+  - Fix MCP schema validation errors with proper datetime format annotations
+  - Ensure compatibility with strict MCP schema validators
+
+- **#281**: Fix move_note without file extension
+  ([`3e168b9`](https://github.com/basicmachines-co/basic-memory/commit/3e168b98f3962681799f4537eb86ded47e771665))
+  - Allow moving notes by title alone without requiring .md extension
+  - Improve move operation usability and error handling
+
+- **#310**: Remove obsolete update_current_project function and --project flag reference
+  ([`17a6733`](https://github.com/basicmachines-co/basic-memory/commit/17a6733c9d280def922e37c2cd171e3ee44fce21))
+  - Clean up deprecated project management code
+  - Remove unused CLI flag references
+
+- **#309**: Make sync operations truly non-blocking with thread pool
+  ([`1091e11`](https://github.com/basicmachines-co/basic-memory/commit/1091e113227c86f10f574e56a262aff72f728113))
+  - Move sync operations to background thread pool for improved responsiveness
+  - Prevent blocking during file synchronization operations
+
+### Features
+
+- **#327**: CLI Subscription Validation (SPEC-13 Phase 2)
+  ([`ace6a0f`](https://github.com/basicmachines-co/basic-memory/commit/ace6a0f50d8d0b4ea31fb526361c2d9616271740))
+  - Implement subscription validation for CLI operations
+  - Foundation for future cloud billing integration
+
+- **#322**: Cloud CLI sync via rclone bisync
+  ([`99a35a7`](https://github.com/basicmachines-co/basic-memory/commit/99a35a7fb410ef88c50050e666e4244350e44a6e))
+  - Add bidirectional cloud synchronization using rclone
+  - Enable local-cloud file sync with conflict detection
+
+- **#315**: Implement SPEC-11 API performance optimizations
+  ([`5da97e4`](https://github.com/basicmachines-co/basic-memory/commit/5da97e482052907d68a2a3604e255c3f2c42c5ed))
+  - Comprehensive API performance improvements
+  - Optimized database queries and response times
+
+- **#314**: Integrate ignore_utils to skip .gitignored files in sync process
+  ([`33ee1e0`](https://github.com/basicmachines-co/basic-memory/commit/33ee1e0831d2060587de2c9886e74ff111b04583))
+  - Respect .gitignore patterns during file synchronization
+  - Prevent syncing build artifacts and temporary files
+
+- **#313**: Add disable_permalinks config flag
+  ([`9035913`](https://github.com/basicmachines-co/basic-memory/commit/903591384dffeba9996a18463818bdb8b28ca03e))
+  - Optional permalink generation for users who don't need them
+  - Improves flexibility for different knowledge management workflows
+
+- **#306**: Implement cloud mount CLI commands for local file access
+  ([`2c5c606`](https://github.com/basicmachines-co/basic-memory/commit/2c5c606a394ab994334c8fd307b30370037bbf39))
+  - Mount cloud files locally using rclone for real-time editing
+  - Three performance profiles: fast (5s), balanced (10-15s), safe (15s+)
+  - Cross-platform rclone installer with package manager fallbacks
+
+- **#305**: ChatGPT tools for search and fetch
+  ([`f40ab31`](https://github.com/basicmachines-co/basic-memory/commit/f40ab31685a9510a07f5d87bf24436c0df80680f))
+  - Add ChatGPT-specific search and fetch tools
+  - Expand AI assistant integration options
+
+- **#298**: Implement SPEC-6 Stateless Architecture for MCP Tools
+  ([`a1d7792`](https://github.com/basicmachines-co/basic-memory/commit/a1d7792bdb6f71c4943b861d1c237f6ac7021247))
+  - Redesign MCP tools for stateless operation
+  - Enable cloud deployment with better scalability
+
+- **#296**: Basic Memory cloud upload
+  ([`e0d8aeb`](https://github.com/basicmachines-co/basic-memory/commit/e0d8aeb14913f3471b9716d0c60c61adb1d74687))
+  - Implement file upload capabilities for cloud storage
+  - Foundation for cloud-hosted Basic Memory instances
+
+- **#291**: Merge Cloud auth
+  ([`3a6baf8`](https://github.com/basicmachines-co/basic-memory/commit/3a6baf80fc6012e9434e06b1605f9a8b198d8688))
+  - OAuth 2.1 authentication with Supabase integration
+  - JWT-based tenant isolation for multi-user cloud deployments
+
+### Platform & Infrastructure
+
+- **#331**: Add Python 3.13 to test matrix
+  ([`16d7edd`](https://github.com/basicmachines-co/basic-memory/commit/16d7eddbf704abfe53373663e80d05ecdde15aa7))
+  - Ensure compatibility with latest Python version
+  - Expand CI/CD testing coverage
+
+- **#316**: Enable WAL mode and add Windows-specific SQLite optimizations
+  ([`c83d567`](https://github.com/basicmachines-co/basic-memory/commit/c83d567917267bb3d52708f4b38d2daf36c1f135))
+  - Enable Write-Ahead Logging for better concurrency
+  - Platform-specific SQLite optimizations for Windows users
+
+- **#320**: Rework lifecycle management to optimize cloud deployment
+  ([`ea2e93d`](https://github.com/basicmachines-co/basic-memory/commit/ea2e93d9265bfa366d2d3796f99f579ab2aed48c))
+  - Optimize application lifecycle for cloud environments
+  - Improve startup time and resource management
+
+- **#319**: Resolve entity relations in background to prevent cold start blocking
+  ([`324844a`](https://github.com/basicmachines-co/basic-memory/commit/324844a670d874410c634db520a68c09149045ea))
+  - Move relation resolution to background processing
+  - Faster MCP server cold starts
+
+- **#318**: Enforce minimum 1-day timeframe for recent_activity
+  ([`f818702`](https://github.com/basicmachines-co/basic-memory/commit/f818702ab7f8d2d706178e7b0ed3467501c9c4a2))
+  - Fix timezone-related issues in recent activity queries
+  - Ensure consistent behavior across time zones
+
+- **#317**: Critical cloud deployment fixes for MCP stability
+  ([`2efd8f4`](https://github.com/basicmachines-co/basic-memory/commit/2efd8f44e2d0259079ed5105fea34308875c0e10))
+  - Multiple stability improvements for cloud-hosted MCP servers
+  - Enhanced error handling and recovery
+
+### Technical Improvements
+
+- **Comprehensive Testing** - Extensive test coverage for critical fixes
+  - New permalink collision test suite with 4 MCP-level integration tests
+  - Entity service test coverage expanded to reproduce fuzzy search bug
+  - Manual testing verification of data loss prevention
+  - All 55 entity service tests passing with new strict resolution
+
+- **Windows Support Enhancements**
+  ([`7a8b08d`](https://github.com/basicmachines-co/basic-memory/commit/7a8b08d11ee627b54af6f5ea7ab4ef9fcd8cf4ed),
+   [`9aa4024`](https://github.com/basicmachines-co/basic-memory/commit/9aa40246a8ad1c3cef82b32e1ca7ce8ea23e1e05))
+  - Fix Windows test failures and add Windows CI support
+  - Address platform-specific issues for Windows users
+  - Enhanced cross-platform compatibility
+
+- **Docker Improvements**
+  ([`105bcaa`](https://github.com/basicmachines-co/basic-memory/commit/105bcaa025576a06f889183baded6c18f3782696))
+  - Implement non-root Docker container to fix file ownership issues
+  - Improved security and compatibility in containerized deployments
+
+- **Code Quality**
+  - Enhanced filename sanitization with optional kebab case support
+  - Improved character conflict detection for sync operations
+  - Better error handling across the codebase
+  - Path traversal security vulnerability fixes
+
+### Documentation
+
+- **#321**: Corrected dead links in README
+  ([`fc38877`](https://github.com/basicmachines-co/basic-memory/commit/fc38877008cd8c762116f7ff4b2573495b4e5c0f))
+  - Fix broken documentation links
+  - Improve navigation and accessibility
+
+- **#308**: Update Claude Code GitHub Workflow
+  ([`8c7e29e`](https://github.com/basicmachines-co/basic-memory/commit/8c7e29e325f36a67bdefe8811637493bef4bbf56))
+  - Enhanced GitHub integration documentation
+  - Better Claude Code collaboration workflow
+
+### Breaking Changes
+
+**None** - This release maintains full backward compatibility with v0.14.x
+
+All changes are either:
+- Bug fixes that correct unintended behavior
+- New optional features that don't affect existing functionality
+- Internal optimizations that are transparent to users
+
+### Migration Guide
+
+No manual migration required. Upgrade with:
+
+```bash
+# Update via uv
+uv tool upgrade basic-memory
+
+# Or install fresh
+uv tool install basic-memory
+```
+
+**What's Fixed:**
+- Data loss bug from permalink collisions is completely resolved
+- Cloud deployment stability significantly improved
+- Windows platform compatibility enhanced
+- Better performance across all operations
+
+**What's New:**
+- Cloud sync capabilities via rclone
+- Subscription validation foundation
+- Python 3.13 support
+- Enhanced security and stability
+
+### Installation
+
+```bash
+# Latest stable release
+uv tool install basic-memory
+
+# Update existing installation
+uv tool upgrade basic-memory
+
+# Docker
+docker pull ghcr.io/basicmachines-co/basic-memory:v0.15.0
+```
+
 ## v0.14.2 (2025-07-03)
 
 ### Bug Fixes

LEGAL_INVENTORY_GUIDE.md

@@ -1,250 +0,0 @@
-# Legal File Inventory Guide
-
-## Overview
-
-This guide documents the comprehensive file inventory script created for Basic Memory's legal documentation needs, including copyright assignments and company agreement exhibits.
-
-## Repository Analysis Summary
-
-### Repository Structure
-- **Primary Language**: Python (3,958 files)
-- **License**: GNU Affero General Public License v3.0
-- **Total Contributors**: 12 identified contributors
-- **Main Contributors**:
-  - `phernandez@basicmachines.co` / `paul@basicmachines.co` (Paul Hernandez) - 700+ commits
-  - `groksrc@gmail.com` / `groksrc@users.noreply.github.com` (Drew Cain) - 18+ commits
-  - Various AI bots and automated systems
-
-### File Type Distribution
-Based on the analysis, the repository contains:
-
-| Extension | Count | Purpose |
-|-----------|-------|---------|
-| `.py` | 3,958 | Python source code |
-| `.pyi` | 4,536 | Python type stubs (dependencies) |
-| `.pyc` | 1,435 | Compiled Python (excluded from inventory) |
-| `.md` | 34 | Documentation files |
-| `.toml` | 179 | Configuration files |
-| `.html` | 119 | Coverage reports and documentation |
-| `.txt` | 127 | Various text files |
-
-### Contributors by Email Domain
-
-**Basic Machines Contributors:**
-- `phernandez@basicmachines.co` - 547 commits (Primary maintainer)
-- `paul@basicmachines.co` / `paulmh@gmail.com` - 170 commits (Paul Hernandez)
-- `claude@basicmachines.co` - 3 commits (AI assistant)
-
-**External Contributors:**
-- `groksrc@gmail.com` / `groksrc@users.noreply.github.com` - 18 commits (Drew Cain)
-- Various one-time contributors (1-2 commits each)
-
-**Automated Systems:**
-- GitHub Actions, semantic-release, and other bots
-
-## Legal Inventory Script Features
-
-### What It Includes
-
-**Source Files:**
-- All Python source code (`.py` files)
-- Configuration files (`.toml`, `.yaml`, `.json`, etc.)
-- Documentation (`.md`, `.rst`, `.txt`)
-- Build and deployment scripts
-- Database migrations and SQL files
-- Legal and license files
-
-**Metadata for Each File:**
-- File path, size, and creation/modification dates
-- Git history (creation date, last modified, commit count)
-- Contributors and their line contributions
-- Primary author identification
-- File categorization
-- SHA-256 hash for integrity verification
-
-### What It Excludes
-
-**Generated/Build Artifacts:**
-- `__pycache__/` and `.pyc` files
-- Build directories (`build/`, `dist/`, `htmlcov/`)
-- Coverage reports and cache files
-
-**Dependencies:**
-- Virtual environment files (`.venv/`, `venv/`)
-- Third-party packages (`site-packages/`, `*.dist-info/`)
-- Lock files (`uv.lock`, `package-lock.json`)
-
-**IDE/Editor Files:**
-- `.idea/`, `.vscode/`, `.DS_Store`
-- Temporary and swap files
-
-**Version Control:**
-- `.git/` directory contents
-- Git configuration files
-
-## Usage Instructions
-
-### Basic Usage
-
-```bash
-# Generate CSV inventory (default)
-python3 legal_file_inventory.py
-
-# Generate Markdown report
-python3 legal_file_inventory.py --format markdown --output legal_report.md
-
-# Generate JSON with full metadata
-python3 legal_file_inventory.py --format json --output legal_data.json
-
-# Specify different repository path
-python3 legal_file_inventory.py --repo-path /path/to/repo --output inventory.csv
-```
-
-### Command Line Options
-
-- `--output`, `-o`: Output file path (default: `basic_memory_legal_inventory.csv`)
-- `--format`, `-f`: Output format - `csv`, `json`, or `markdown` (default: `csv`)
-- `--repo-path`, `-r`: Repository path (default: current directory)
-
-### Output Formats
-
-**CSV Format:**
-- Suitable for spreadsheet applications
-- Contains all metadata fields
-- Contributors stored as JSON string in separate column
-
-**JSON Format:**
-- Complete structured data
-- Includes summary statistics and detailed file information
-- Best for programmatic processing
-
-**Markdown Format:**
-- Human-readable report
-- Summary statistics and contributor rankings
-- Detailed table of all files
-
-## Legal Documentation Applications
-
-### Copyright Assignment Use Cases
-
-1. **Contributor Identification**: The script identifies all contributors to each file based on git blame analysis
-2. **Primary Author Recognition**: Determines the primary author of each file (contributor with most lines)
-3. **Contribution Metrics**: Provides line counts and commit counts per contributor
-4. **File Categorization**: Groups files by purpose (source code, documentation, configuration, etc.)
-
-### Company Agreement Exhibits
-
-The inventory provides comprehensive documentation of:
-
-1. **Intellectual Property Scope**: All source code files and their origins
-2. **Contributor Tracking**: Complete list of all individuals who have contributed code
-3. **File Integrity**: SHA-256 hashes for verification of file contents
-4. **Historical Documentation**: Git creation dates and modification history
-
-### Due Diligence Documentation
-
-The script generates data suitable for:
-
-1. **Legal Review**: Comprehensive file listing with contributor information
-2. **IP Audit**: Identification of all copyright holders
-3. **License Compliance**: Verification of file ownership and licensing
-4. **Asset Documentation**: Complete inventory of company code assets
-
-## Integration with Legal Processes
-
-### Recommended Workflow
-
-1. **Generate Inventory**: Run the script to create current file inventory
-2. **Legal Review**: Have legal counsel review the contributor list and file categorization
-3. **Copyright Assignment**: Use contributor data to ensure proper copyright assignments
-4. **Document Attachment**: Include inventory as exhibit in company agreements
-5. **Regular Updates**: Re-run inventory for significant releases or legal milestones
-
-### Key Legal Considerations
-
-**AGPL-3.0 License:**
-- All files are under AGPL-3.0 unless otherwise specified
-- Contributors retain copyright but license under AGPL-3.0 terms
-- Company needs proper copyright assignments for proprietary licensing
-
-**Contributor Rights:**
-- External contributors may retain rights to their contributions
-- Proper contributor license agreements (CLAs) should be in place
-- AI-generated content may have different legal status
-
-**File Categories for Legal Review:**
-- **Source Code**: Core IP, requires copyright assignment
-- **Configuration**: May contain proprietary deployment information
-- **Documentation**: Usually less sensitive but may contain trade secrets
-- **Legal/License**: Critical for compliance verification
-
-## Maintenance and Updates
-
-### When to Regenerate Inventory
-
-- Before major releases
-- During legal document preparation
-- After significant contributor additions
-- For annual compliance reviews
-- During acquisition or investment processes
-
-### Validation Steps
-
-1. Verify contributor email mapping is accurate
-2. Check that file categorization makes sense
-3. Ensure excluded files are appropriate
-4. Review contributor counts against expectations
-5. Validate file hashes for integrity
-
-## Technical Implementation Notes
-
-### Git Integration
-- Uses `git blame --line-porcelain` for detailed contributor analysis
-- Tracks file history with `git log --follow`
-- Handles renamed files and complex git histories
-
-### Performance Considerations
-- Scans repository incrementally to handle large codebases
-- Excludes binary dependencies to reduce processing time
-- Caches git operations where possible
-
-### Error Handling
-- Gracefully handles files not in git
-- Continues processing if individual files fail
-- Provides detailed error reporting
-
-## Security and Privacy
-
-### Data Sensitivity
-- Contains contributor names and email addresses
-- May reveal internal file structure and organization
-- Should be treated as confidential legal documentation
-
-### Recommended Handling
-- Limit access to legal and executive team
-- Store in secure, access-controlled systems
-- Consider redacting contributor emails for external sharing
-- Regular cleanup of generated inventory files
-
-## Troubleshooting
-
-### Common Issues
-
-**Git Not Available:**
-- Ensure git is installed and repository is initialized
-- Check that the script is run from within the repository
-
-**Permission Errors:**
-- Ensure read access to all repository files
-- Check write permissions for output directory
-
-**Large Repository Performance:**
-- Consider running on subsets of files for very large repositories
-- Use `--repo-path` to target specific subdirectories
-
-**Contributor Mapping Issues:**
-- Git usernames may not match real identities
-- Consider post-processing to normalize contributor names
-- Review .mailmap files for git identity consolidation
-
-This comprehensive legal file inventory system provides the foundation for proper intellectual property documentation and legal compliance for the Basic Memory project.

README.md

@@ -371,10 +371,10 @@ canvas(nodes, edges, title, folder) - Generate knowledge visualizations
 
 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)
+- [Complete User Guide](https://docs.basicmemory.com/user-guide/)
+- [CLI tools](https://docs.basicmemory.com/guides/cli-reference/)
+- [Managing multiple Projects](https://docs.basicmemory.com/guides/cli-reference/#project)
+- [Importing data from OpenAI/Claude Projects](https://docs.basicmemory.com/guides/cli-reference/#import)
 
 ## License
 

create_csv_exhibits.py

@@ -1,88 +0,0 @@
-#!/usr/bin/env python3
-"""
-Create CSV exhibits for individual contributors
-"""
-
-import json
-import csv
-from pathlib import Path
-
-def create_csv_exhibits():
-    """Create CSV Exhibit A files for each contributor."""
-    
-    # Read the JSON inventory
-    inventory_files = list(Path("legal_inventory_main").glob("*.json"))
-    if not inventory_files:
-        print("Error: No JSON inventory files found")
-        return
-    
-    inventory_file = inventory_files[0]  # Use the most recent one
-    print(f"Using inventory file: {inventory_file}")
-    
-    with open(inventory_file, 'r') as f:
-        data = json.load(f)
-    
-    files = data['files']
-    
-    # Create output directory
-    output_dir = Path("legal_exhibits")
-    output_dir.mkdir(exist_ok=True)
-    
-    # Contributors we need exhibits for
-    target_contributors = {
-        'jope-bm': 'joe_exhibit_a.csv',
-        'Drew Cain': 'drew_cain_exhibit_a.csv'
-    }
-    
-    print("Creating CSV exhibits for contributors...")
-    
-    for contributor_key, filename in target_contributors.items():
-        # Find files for this contributor
-        contributor_files = []
-        
-        for file_info in files:
-            # Check if this contributor is listed in the file's contributors
-            for contrib in file_info.get('contributors', []):
-                if contributor_key in contrib['name']:
-                    contributor_files.append(file_info)
-                    break
-        
-        if not contributor_files:
-            print(f"No files found for {contributor_key}")
-            continue
-        
-        # Sort files by path
-        contributor_files.sort(key=lambda x: x['path'])
-        
-        # Create CSV file
-        csv_file = output_dir / filename
-        
-        with open(csv_file, 'w', newline='', encoding='utf-8') as csvfile:
-            fieldnames = [
-                'file_path', 'file_name', 'category', 'size_bytes', 
-                'modified_date', 'primary_author', 'all_contributors', 'sha256_hash'
-            ]
-            
-            writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
-            writer.writeheader()
-            
-            for file_info in contributor_files:
-                contributors_list = '; '.join([c['name'] for c in file_info['contributors']])
-                
-                writer.writerow({
-                    'file_path': file_info['path'],
-                    'file_name': file_info['name'],
-                    'category': file_info['category'],
-                    'size_bytes': file_info['size_bytes'],
-                    'modified_date': file_info['modified_time'][:10],
-                    'primary_author': file_info['primary_author'],
-                    'all_contributors': contributors_list,
-                    'sha256_hash': file_info['sha256_hash']
-                })
-        
-        print(f"Created CSV exhibit for {contributor_key}: {csv_file}")
-        print(f"  - {len(contributor_files)} files")
-        print(f"  - {sum(f['size_bytes'] for f in contributor_files):,} bytes")
-
-if __name__ == '__main__':
-    create_csv_exhibits()

create_individual_exhibits.py

@@ -1,208 +0,0 @@
-#!/usr/bin/env python3
-"""
-Create individual Exhibit A files for copyright assignments
-"""
-
-import json
-from pathlib import Path
-from datetime import datetime
-
-def create_individual_exhibits():
-    """Create individual Exhibit A files for each contributor."""
-    
-    # Read the JSON inventory
-    inventory_file = Path("legal_inventory_main/basic_memory_inventory_20250730_101521.json")
-    
-    if not inventory_file.exists():
-        print(f"Error: {inventory_file} not found")
-        return
-    
-    with open(inventory_file, 'r') as f:
-        data = json.load(f)
-    
-    files = data['files']
-    
-    # Create output directory
-    output_dir = Path("legal_exhibits")
-    output_dir.mkdir(exist_ok=True)
-    
-    # Contributors we need exhibits for (based on copyright assignments)
-    target_contributors = {
-        'jope-bm': 'Joseph "Joe" [Last Name]',  # Need to get his full name
-        'Drew Cain': 'Drew Cain'
-    }
-    
-    print("Creating individual contributor exhibits...")
-    
-    for contributor_key, full_name in target_contributors.items():
-        # Find files for this contributor
-        contributor_files = []
-        
-        for file_info in files:
-            # Check if this contributor is listed in the file's contributors
-            for contrib in file_info.get('contributors', []):
-                if contributor_key in contrib['name']:
-                    contributor_files.append(file_info)
-                    break
-        
-        if not contributor_files:
-            print(f"No files found for {contributor_key}")
-            continue
-        
-        # Sort files by path
-        contributor_files.sort(key=lambda x: x['path'])
-        
-        # Create exhibit markdown
-        exhibit_content = f"""# Exhibit A - Assigned Works
-## Copyright Assignment: {full_name} to Basic Memory LLC
-
-**Date:** [To be filled]
-**Assignor:** {full_name}
-**Assignee:** Basic Memory LLC
-
-## Summary
-- **Total Files:** {len(contributor_files)}
-- **Total Size:** {sum(f['size_bytes'] for f in contributor_files):,} bytes
-- **Categories:** {', '.join(set(f['category'] for f in contributor_files))}
-
-## Detailed File List
-
-"""
-        
-        # Group by category
-        categories = {}
-        for file_info in contributor_files:
-            category = file_info['category']
-            if category not in categories:
-                categories[category] = []
-            categories[category].append(file_info)
-        
-        # Add files by category
-        for category, category_files in sorted(categories.items()):
-            exhibit_content += f"### {category.replace('_', ' ').title()}\n\n"
-            
-            for file_info in category_files:
-                exhibit_content += f"**{file_info['path']}**\n"
-                exhibit_content += f"- Size: {file_info['size_bytes']:,} bytes\n"
-                exhibit_content += f"- Modified: {file_info['modified_time'][:10]}\n"
-                exhibit_content += f"- Primary Author: {file_info['primary_author']}\n"
-                
-                # Show all contributors for this file
-                if len(file_info['contributors']) > 1:
-                    contributors_list = ', '.join([c['name'] for c in file_info['contributors']])
-                    exhibit_content += f"- All Contributors: {contributors_list}\n"
-                
-                exhibit_content += f"- SHA-256: `{file_info['sha256_hash']}`\n\n"
-        
-        # Add verification section
-        exhibit_content += f"""
-## Verification
-This exhibit lists all files in the Basic Memory repository where {full_name} is identified as a contributor based on git commit history analysis.
-
-**Analysis Date:** {datetime.now().strftime('%Y-%m-%d')}
-**Repository State:** Basic Memory main branch
-**Method:** Git history analysis via `git log --follow` for each file
-
-## Legal Representation
-{full_name} hereby represents and warrants that they are the author of the contributions listed above and have the right to assign copyright in these works to Basic Memory LLC.
-
----
-
-*This exhibit is attached to and forms part of the Copyright Assignment Agreement between {full_name} and Basic Memory LLC.*
-"""
-        
-        # Write exhibit file
-        safe_name = contributor_key.replace(' ', '_').replace('-', '_').lower()
-        exhibit_file = output_dir / f"exhibit_a_{safe_name}.md"
-        
-        with open(exhibit_file, 'w') as f:
-            f.write(exhibit_content)
-        
-        print(f"Created exhibit for {full_name}: {exhibit_file}")
-        print(f"  - {len(contributor_files)} files")
-        print(f"  - {sum(f['size_bytes'] for f in contributor_files):,} bytes")
-    
-    # Create overall summary exhibit (for Paul's assignment to Basic Machines LLC)
-    create_overall_summary_exhibit(data, output_dir)
-
-def create_overall_summary_exhibit(data, output_dir):
-    """Create overall summary exhibit for Company Agreement."""
-    
-    files = data['files']
-    summary = data['summary']
-    contributors = data['contributors']
-    
-    summary_content = f"""# Basic Memory Repository - Complete IP Inventory
-## For Basic Memory LLC Company Agreement
-
-**Analysis Date:** {summary['scan_date'][:10]}
-**Repository:** {summary['repository_path']}
-
-## Executive Summary
-- **Total Files:** {summary['total_files']:,}
-- **Total Size:** {summary['total_size_bytes']:,} bytes
-- **Contributors:** {summary['contributor_count']}
-- **Primary Author:** Paul Hernandez ({len(contributors.get('Paul Hernandez', {}).get('files', []))} files)
-
-## File Categories
-"""
-    
-    for category, count in sorted(summary['categories'].items()):
-        summary_content += f"- **{category.replace('_', ' ').title()}:** {count} files\n"
-    
-    summary_content += """
-
-## Contributor Summary
-"""
-    
-    for contrib in summary['top_contributors']:
-        summary_content += f"- **{contrib['name']}** ({contrib['email']}): {contrib['file_count']} files, {contrib['commit_count']} commits\n"
-    
-    summary_content += """
-
-## Legal Significance
-This inventory represents the complete codebase of Basic Memory as licensed from Basic Machines LLC to Basic Memory LLC under the copyright license agreement dated [DATE].
-
-### IP Rights Chain
-1. **Paul Hernandez** → Basic Machines LLC (copyright assignment)
-2. **Basic Machines LLC** → Basic Memory LLC (15% royalty license)
-3. **Co-founders** → Basic Memory LLC (direct copyright assignments)
-
-### Due Diligence Documentation
-This comprehensive file inventory serves as:
-- **Company Agreement Exhibit:** Original codebase licensed to Basic Memory LLC
-- **Acquisition Documentation:** Complete IP inventory for due diligence
-- **Copyright Verification:** Establishes chain of title for all repository contents
-
-## Repository Contents by Category
-
-"""
-    
-    # Add sample files by category (first 10 in each category)
-    for category in sorted(summary['categories'].keys()):
-        category_files = [f for f in files if f['category'] == category][:10]
-        if category_files:
-            summary_content += f"### {category.replace('_', ' ').title()} (Sample)\n\n"
-            for file_info in category_files:
-                summary_content += f"- `{file_info['path']}` ({file_info['size_bytes']:,} bytes)\n"
-            
-            if len([f for f in files if f['category'] == category]) > 10:
-                remaining = len([f for f in files if f['category'] == category]) - 10
-                summary_content += f"- *... and {remaining} more files*\n"
-            summary_content += "\n"
-    
-    summary_content += f"""
----
-
-*This inventory was generated automatically from git repository analysis and represents the complete intellectual property foundation of Basic Memory as of {summary['scan_date'][:10]}.*
-"""
-    
-    # Write summary file
-    summary_file = output_dir / "basic_memory_complete_inventory.md"
-    with open(summary_file, 'w') as f:
-        f.write(summary_content)
-    
-    print(f"Created complete inventory summary: {summary_file}")
-
-if __name__ == '__main__':
-    create_individual_exhibits()

docs/AI Assistant Guide.md

@@ -1,431 +0,0 @@
----
-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/cloud-cli.md

@@ -0,0 +1,657 @@
+# Basic Memory Cloud CLI Guide
+
+The Basic Memory Cloud CLI provides seamless integration between local and cloud knowledge bases using a **cloud mode toggle**. When cloud mode is enabled, all your regular `bm` commands work transparently with the cloud instead of locally.
+
+## Overview
+
+The cloud CLI enables you to:
+- **Toggle cloud mode** with `bm cloud login` / `bm cloud logout`
+- **Use regular commands in cloud mode**: `bm project`, `bm sync`, `bm tool` all work with cloud
+- **Bidirectional sync** with rclone bisync (recommended for most users)
+- **Direct file access** via rclone mount (alternative workflow)
+- **Integrity verification** with `bm cloud check`
+- **Automatic project creation** from local directories
+
+## Prerequisites
+
+Before using Basic Memory Cloud, you need:
+
+- **Active Subscription**: An active Basic Memory Cloud subscription is required to access cloud features
+- **Subscribe**: Visit [https://basicmemory.com/subscribe](https://basicmemory.com/subscribe) to sign up
+
+If you attempt to log in without an active subscription, you'll receive a "Subscription Required" error with a link to subscribe.
+
+## The Cloud Mode Paradigm
+
+Basic Memory Cloud follows the **Dropbox/iCloud model** - a single cloud space containing all your projects, not per-project connections.
+
+**How it works:**
+- One login per machine: `bm cloud login`
+- One sync directory: `~/basic-memory-cloud-sync/` (all projects)
+- Projects are folders within your cloud space
+- All regular commands work in cloud mode
+
+**Why this model:**
+- ✅ Single set of credentials (not N per project)
+- ✅ One rclone process (not N processes)
+- ✅ Familiar pattern (like Dropbox)
+- ✅ Simple operations (setup once, sync anytime)
+- ✅ Natural scaling (add projects = add folders)
+
+## Quick Start
+
+### 1. Enable Cloud Mode
+
+Authenticate and enable cloud mode for all commands:
+
+```bash
+bm cloud login
+```
+
+This command will:
+1. Open your browser to the Basic Memory Cloud authentication page
+2. Prompt you to authorize the CLI application
+3. Store your authentication token locally
+4. **Enable cloud mode** - all CLI commands now work against cloud
+
+### 2. Set Up Sync
+
+Set up bidirectional file synchronization:
+
+```bash
+bm cloud setup
+```
+
+This will:
+1. Install rclone automatically (if needed)
+2. Configure sync credentials
+3. Create `~/basic-memory-cloud-sync/` directory
+4. Establish initial sync baseline
+
+**Alternative:** Use `bm cloud setup --mount` to set up mount instead of sync.
+
+### 3. Verify Setup
+
+Check that everything is working:
+
+```bash
+bm cloud status
+```
+
+You should see:
+- `Mode: Cloud (enabled)`
+- `Cloud instance is healthy`
+- Bisync status showing `✓ Initialized`
+
+### 4. Start Using Cloud
+
+Now all your regular commands work with the cloud:
+
+```bash
+# List cloud projects
+bm project list
+
+# Create cloud project
+bm project add "my-research"
+
+# Use MCP tools on cloud
+bm tool write-note --title "Hello" --folder "my-research" --content "Test"
+
+# Sync with cloud
+bm sync
+
+# Watch mode for continuous sync
+bm sync --watch
+```
+
+### 5. Disable Cloud Mode
+
+Return to local mode:
+
+```bash
+bm cloud logout
+```
+
+All commands now work locally again.
+
+## Working with Cloud Projects
+
+**Important:** When cloud mode is enabled, use regular `bm project` commands (not `bm cloud project`).
+
+### Listing Projects
+
+View all projects (cloud projects when cloud mode is enabled):
+
+```bash
+# In cloud mode - lists cloud projects
+bm project list
+
+# In local mode - lists local projects
+bm project list
+```
+
+### Creating Projects
+
+Create a new project (creates on cloud when cloud mode is enabled):
+
+```bash
+# In cloud mode - creates cloud project
+bm project add my-new-project
+
+# Create and set as default
+bm project add my-new-project --default
+```
+
+### Automatic Project Creation
+
+**New in SPEC-9:** Projects are automatically created when you create local directories!
+
+```bash
+# Create a local directory in your sync folder
+mkdir ~/basic-memory-cloud-sync/new-project
+echo "# Notes" > ~/basic-memory-cloud-sync/new-project/readme.md
+
+# Sync - automatically creates cloud project
+bm sync
+
+# Verify - project now exists on cloud
+bm project list
+```
+
+This Dropbox-like workflow means you don't need to manually coordinate projects between local and cloud.
+
+## File Synchronization
+
+### The `bm sync` Command (Cloud Mode Aware)
+
+The `bm sync` command automatically adapts based on cloud mode:
+
+**In local mode:**
+```bash
+bm sync              # Indexes local files into database
+```
+
+**In cloud mode:**
+```bash
+bm sync              # Runs bisync + indexes files
+bm sync --watch      # Continuous sync every 60 seconds
+bm sync --interval 30  # Custom interval
+```
+
+The same command works everywhere - no need to remember different commands for local vs cloud!
+
+## Bidirectional Sync (bisync) - Recommended
+
+Bidirectional sync is the **recommended approach** for most users. It provides:
+- ✅ Offline access to all files
+- ✅ Automatic bidirectional synchronization
+- ✅ Conflict detection and resolution
+- ✅ Works with any editor or tool
+- ✅ Background watch mode
+
+### Setup
+
+Set up bisync (runs automatically if you used `bm cloud setup`):
+
+```bash
+bm cloud setup
+```
+
+Or set up with custom directory:
+
+```bash
+bm cloud setup --dir ~/my-sync-folder
+```
+
+### Running Sync
+
+Use the cloud-aware `bm sync` command:
+
+```bash
+# Manual sync
+bm sync
+
+# Watch mode (continuous sync)
+bm sync --watch
+
+# Custom interval (30 seconds)
+bm sync --watch --interval 30
+```
+
+### Bisync Profiles
+
+Bisync supports three conflict resolution strategies with different safety levels:
+
+| Profile | Conflict Resolution | Max Deletes | Use Case |
+|---------|-------------------|-------------|----------|
+| **balanced** | newer | 25 | Default, recommended for most users |
+| **safe** | none | 10 | Keep both versions on conflict |
+| **fast** | newer | 50 | Rapid iteration, higher delete tolerance |
+
+**Profile Details:**
+
+- **safe**:
+  - Conflict resolution: `none` (creates `.conflict` files for both versions)
+  - Max delete: 10 files per sync
+  - Best for: Critical data where you want manual conflict resolution
+
+- **balanced** (default):
+  - Conflict resolution: `newer` (auto-resolve to most recent file)
+  - Max delete: 25 files per sync
+  - Best for: General use with automatic conflict handling
+
+- **fast**:
+  - Conflict resolution: `newer` (auto-resolve to most recent file)
+  - Max delete: 50 files per sync
+  - Best for: Rapid development iteration with less restrictive safety checks
+
+**How to Select a Profile:**
+
+The default profile (`balanced`) is used automatically with `bm sync`:
+
+```bash
+# Uses balanced profile (default)
+bm sync
+```
+
+For advanced control, use `bm cloud bisync` with the `--profile` flag:
+
+```bash
+# Use safe mode
+bm cloud bisync --profile safe
+
+# Use fast mode
+bm cloud bisync --profile fast
+
+# Preview changes with specific profile
+bm cloud bisync --profile safe --dry-run
+```
+
+**Check Available Profiles:**
+
+```bash
+bm cloud status
+```
+
+This shows all available profiles with their settings.
+
+**Current Limitations:**
+
+- Profiles are hardcoded and cannot be customized
+- No config file option to change default profile
+- Profile settings (max_delete, conflict_resolve) cannot be modified without code changes
+- Profile selection only available via `bm cloud bisync --profile` (advanced command)
+
+### Establishing New Baseline
+
+If you need to force a complete resync:
+
+```bash
+bm cloud bisync --resync
+```
+
+**Warning:** This overwrites the sync state. Use only when recovering from errors.
+
+### Checking Sync Status
+
+View current sync status:
+
+```bash
+bm cloud status
+```
+
+This shows:
+- Cloud mode status
+- Instance health
+- Sync directory location
+- Last sync time
+- Available bisync profiles
+
+### Verifying Sync Integrity
+
+Check that local and cloud files match:
+
+```bash
+# Full integrity check
+bm cloud check
+
+# Faster one-way check
+bm cloud check --one-way
+```
+
+This uses `rclone check` to verify files match without transferring data.
+
+### Working with Bisync
+
+Create and edit files in `~/basic-memory-cloud-sync/`:
+
+```bash
+# Create a new note
+echo "# My Research" > ~/basic-memory-cloud-sync/my-project/notes.md
+
+# Edit with your favorite editor
+code ~/basic-memory-cloud-sync/my-project/
+
+# Sync changes to cloud
+bm sync
+```
+
+In watch mode, changes sync automatically:
+
+```bash
+# Start watch mode
+bm sync --watch
+
+# Edit files - they sync automatically every 60 seconds
+code ~/basic-memory-cloud-sync/my-project/
+```
+
+### Filter Configuration
+
+Bisync uses `.bmignore` patterns from `~/.basic-memory/.bmignore`:
+
+```bash
+# View current ignore patterns
+cat ~/.basic-memory/.bmignore
+
+# Edit ignore patterns
+code ~/.basic-memory/.bmignore
+```
+
+Example `.bmignore`:
+
+```gitignore
+# This file is used by 'bm cloud bisync' and file sync
+# Patterns use standard gitignore-style syntax
+
+# Hidden files (files starting with dot)
+- .*
+
+# Basic Memory internal files
+- memory.db/**
+- memory.db-shm/**
+- memory.db-wal/**
+- config.json/**
+
+# Version control
+- .git/**
+
+# Python
+- __pycache__/**
+- *.pyc
+- .venv/**
+
+# Node.js
+- node_modules/**
+```
+
+**Key points:**
+- ✅ **Global configuration** - One ignore file for all projects
+- ✅ **rclone filter syntax** - Patterns with `- ` prefix
+- ✅ **Automatic creation** - Created with defaults on first use
+- ✅ **Shared patterns** - Same patterns used by sync service
+
+## NFS Mount (Direct Access) - Alternative
+
+NFS mount provides direct file system access as an alternative to bisync. Use this if you prefer mounting files like a network drive.
+
+### Setup
+
+Set up mount instead of bisync:
+
+```bash
+bm cloud setup --mount
+```
+
+### Mounting Files
+
+Mount your cloud files:
+
+```bash
+# Mount with default settings
+bm cloud mount
+
+# Mount with specific profile
+bm cloud mount --profile fast
+```
+
+#### Mount Profiles
+
+- **balanced** (default): Balanced caching for general use
+- **streaming**: Optimized for large files
+- **fast**: Minimal verification for rapid access
+
+### Checking Mount Status
+
+View current mount status:
+
+```bash
+bm cloud status --mount
+```
+
+### Unmounting Files
+
+Unmount when done:
+
+```bash
+bm cloud unmount
+```
+
+### Working with Mounted Files
+
+Once mounted, files appear at `~/basic-memory-cloud/`:
+
+```bash
+# List cloud files
+ls ~/basic-memory-cloud/
+
+# Edit with your favorite editor
+code ~/basic-memory-cloud/my-project/
+
+# Changes are immediately synced to cloud
+echo "# Notes" > ~/basic-memory-cloud/my-project/readme.md
+```
+
+**Note:** Changes are written through to cloud immediately. There's no "sync" step needed.
+
+## Instance Management
+
+### Health Check
+
+Check if your cloud instance is healthy:
+
+```bash
+bm cloud status
+```
+
+This shows:
+- Cloud mode enabled/disabled
+- Instance health status
+- Instance version
+- Sync or mount status
+
+## Troubleshooting
+
+### Authentication Issues
+
+**Problem**: "Authentication failed" or "Invalid token"
+
+**Solution**: Re-authenticate:
+
+```bash
+bm cloud logout
+bm cloud login
+```
+
+### Subscription Issues
+
+**Problem**: "Subscription Required" error when logging in
+
+**Solution**: You need an active Basic Memory Cloud subscription to use cloud features.
+
+1. Visit the subscribe URL shown in the error message
+2. Sign up for a subscription
+3. Once your subscription is active, run `bm cloud login` again
+
+**Problem**: "Subscription Required" error for existing user
+
+**Solution**: Your subscription may have expired or been cancelled.
+
+1. Check your subscription status at [https://basicmemory.com/account](https://basicmemory.com/account)
+2. Renew your subscription if needed
+3. Run `bm cloud login` again
+
+Note: Access is immediately restored when your subscription becomes active.
+
+### Sync Issues
+
+**Problem**: "Bisync not initialized"
+
+**Solution**: Run setup or initialize with resync:
+
+```bash
+bm cloud setup
+# or
+bm cloud bisync --resync
+```
+
+**Problem**: "Too many deletes" error
+
+**Solution**: Bisync detected many deletions (safety check). Review changes and use a higher delete limit profile or force resync:
+
+```bash
+bm cloud bisync --profile fast  # Higher delete limit
+# or
+bm cloud bisync --resync        # Force baseline
+```
+
+**Problem**: Conflicts detected
+
+**Solution**: Bisync found files changed in both locations. Check sync directory for `.conflict` files:
+
+```bash
+ls ~/basic-memory-cloud-sync/**/*.conflict
+```
+
+Resolve conflicts manually, then sync again.
+
+### Connection Issues
+
+**Problem**: "Cannot connect to cloud instance"
+
+**Solution**: Check cloud status:
+
+```bash
+bm cloud status
+```
+
+If instance is down, wait a few minutes and retry. If problem persists, contact support.
+
+### Mount Issues
+
+**Problem**: "Mount point is busy"
+
+**Solution**: Unmount and remount:
+
+```bash
+bm cloud unmount
+bm cloud mount
+```
+
+**Problem**: "Permission denied" when accessing mounted files
+
+**Solution**: Check mount status and remount:
+
+```bash
+bm cloud status --mount
+bm cloud unmount
+bm cloud mount
+```
+
+## Security
+
+- **Authentication**: OAuth 2.1 with PKCE flow
+- **Tokens**: Stored securely in `~/.basic-memory/auth/token`
+- **Transport**: All data encrypted in transit (HTTPS)
+- **Credentials**: Scoped S3 credentials for sync/mount (read-write access to your tenant only)
+- **Isolation**: Your data is isolated from other tenants
+- **Ignore patterns**: Sensitive files (`.env`, credentials) automatically excluded
+
+## Command Reference
+
+### Cloud Mode Management
+
+```bash
+bm cloud login                   # Authenticate and enable cloud mode
+bm cloud logout                  # Disable cloud mode
+bm cloud status                  # Check cloud mode and sync status
+bm cloud status --mount          # Check cloud mode and mount status
+```
+
+### Setup
+
+```bash
+bm cloud setup                   # Setup bisync (default, recommended)
+bm cloud setup --mount           # Setup mount (alternative)
+bm cloud setup --dir ~/sync      # Custom sync directory
+```
+
+### Project Management (Cloud Mode Aware)
+
+When cloud mode is enabled, these commands work with cloud:
+
+```bash
+bm project list                  # List projects
+bm project add <name>            # Create project
+bm project add <name> --default  # Create and set as default
+bm project rm <name>             # Delete project
+bm project set-default <name>    # Set default project
+```
+
+### File Synchronization
+
+```bash
+bm sync                          # Sync files (local or cloud depending on mode)
+bm sync --watch                  # Continuous sync (cloud mode only)
+bm sync --interval 30            # Custom interval for watch mode
+
+# Advanced bisync commands
+bm cloud bisync                  # Run bisync manually
+bm cloud bisync --profile safe   # Use specific profile
+bm cloud bisync --dry-run        # Preview changes
+bm cloud bisync --resync         # Force new baseline
+bm cloud bisync --watch          # Continuous sync
+bm cloud bisync --verbose        # Show detailed output
+
+# Integrity verification
+bm cloud check                   # Full integrity check
+bm cloud check --one-way         # Faster one-way check
+```
+
+### Direct File Access (Mount)
+
+```bash
+bm cloud mount                   # Mount cloud files
+bm cloud mount --profile fast    # Use specific profile
+bm cloud unmount                 # Unmount files
+```
+
+## Summary
+
+Basic Memory Cloud provides two workflows:
+
+### Recommended: Bidirectional Sync (bisync)
+1. `bm cloud login` - Authenticate once
+2. `bm cloud setup` - Configure sync once
+3. `bm sync` - Sync anytime (or use `--watch`)
+4. Work in `~/basic-memory-cloud-sync/`
+5. Changes sync bidirectionally
+
+### Alternative: Direct Mount
+1. `bm cloud login` - Authenticate once
+2. `bm cloud setup --mount` - Configure mount once
+3. `bm cloud mount` - Mount when needed
+4. Work in `~/basic-memory-cloud/`
+5. Changes write through immediately
+
+Both approaches work seamlessly with cloud mode - all your regular `bm` commands work with either workflow!

justfile

@@ -18,12 +18,15 @@ test-int:
 # Run all tests
 test: test-unit test-int
 
+# Lint and fix code (calls fix)
+lint: fix
+
 # Lint and fix code
-lint:
-    uv run ruff check . --fix
+fix:
+    uv run ruff check --fix --unsafe-fixes src tests
 
 # Type check code
-type-check:
+typecheck:
     uv run pyright
 
 # Clean build artifacts and cache files
@@ -55,7 +58,7 @@ update-deps:
     uv sync --upgrade
 
 # Run all code quality checks and tests
-check: lint format type-check test
+check: lint format typecheck test
 
 # Generate Alembic migration with descriptive message
 migration message:

legal_exhibits/drew_cain_exhibit_a.csv

@@ -1,31 +0,0 @@
-file_path,file_name,category,size_bytes,modified_date,primary_author,all_contributors,sha256_hash
-.github/workflows/release.yml,release.yml,configuration,2479,2025-07-03,Drew Cain,Drew Cain; Paul Hernandez,163307a99e2f3d317af6ae8927e1537654d88bf574a6958ac0bcd2d4de266b2a
-CLAUDE.md,CLAUDE.md,legal,12310,2025-07-03,Drew Cain,Drew Cain; Paul Hernandez; bm-claudeai (AI Assistant); Ikko Eltociear Ashimine,751f10c1a9a9c0ba2054d9c9cd36cf0989d6a347491fd505bb6504ee74b12900
-README.md,README.md,documentation,16261,2025-07-03,Drew Cain,Drew Cain; Paul Hernandez; Jason Noble; Marc Baiza; Matias Forbord; bm-claudeai (AI Assistant),2c4b82b30f49ab465617034fda999157450ed168f8e097fe8e9ca7ac65a197a7
-justfile,justfile,other,5496,2025-07-30,jope-bm,jope-bm; Paul Hernandez; Drew Cain,a8df6c73ee8cf3eaa48e4cba193dffbc2821b843a8cc0c0cd58b8517f2252907
-pyproject.toml,pyproject.toml,configuration,3279,2025-07-30,Paul Hernandez,Paul Hernandez; Drew Cain; bm-claudeai (AI Assistant); semantic-release,428a5d64d4555dc7cd2a81b89a3444bdb1d2f3017257fbc9160bd0ae982718e1
-src/basic_memory/__init__.py,__init__.py,source_code,256,2025-07-06,Paul Hernandez,Paul Hernandez; Drew Cain; semantic-release,c946490ab9d64957d25df37f721392024916f8a81ed838f70a8e938b1c2637db
-src/basic_memory/alembic/env.py,env.py,source_code,2838,2025-07-08,Paul Hernandez,Paul Hernandez; Drew Cain; bm-claudeai (AI Assistant),e241d987eadfcd5011cbd9ddbecb833d306de87937759d81c08d37d04a6906b0
-src/basic_memory/api/routers/utils.py,utils.py,source_code,5159,2025-07-03,Drew Cain,Drew Cain; bm-claudeai (AI Assistant),9e60f57da24e1dc9d64236c26a7a2353003dc618a77fbeb853c494aa3357a57c
-src/basic_memory/cli/commands/mcp.py,mcp.py,source_code,2593,2025-07-08,Paul Hernandez,Paul Hernandez; Drew Cain; bm-claudeai (AI Assistant),3e1be3d27b18ef4743204b7cf8a37fbc2a1a91fc1636c468e08cefcd8597bac6
-src/basic_memory/config.py,config.py,source_code,12487,2025-07-30,jope-bm,jope-bm; Paul Hernandez; Drew Cain; bm-claudeai (AI Assistant); github-actions[bot] (AI Assistant),86341330a041b94d38f5e4f1b94f3509d74351c67cc826af1a4ff57313e5f726
-src/basic_memory/db.py,db.py,source_code,7428,2025-07-08,Paul Hernandez,Paul Hernandez; Drew Cain; bm-claudeai (AI Assistant),25e053b0b3f9e8fa823b05fc099001efe8a3a4f6e0f80728e5079ba45aa406d8
-src/basic_memory/mcp/server.py,server.py,source_code,1248,2025-07-08,Paul Hernandez,Paul Hernandez; Drew Cain; bm-claudeai (AI Assistant),0a910cae27d61ea923e90fbe2d4b5c7cacf3b29d3e156f0b7f77872ab973c761
-src/basic_memory/mcp/tools/__init__.py,__init__.py,source_code,1619,2025-07-03,Drew Cain,Drew Cain; Paul Hernandez,872b771dd52ec3b763645a2baf6e10a70f049ce3106830a6d3f053b3e09a5fe6
-src/basic_memory/mcp/tools/project_management.py,project_management.py,source_code,12944,2025-07-06,Drew Cain,Drew Cain; Paul Hernandez,cdac736d65129f689a85c6b82f8e043bc84a31657ead7a8331771171eeaa860f
-src/basic_memory/mcp/tools/search.py,search.py,source_code,15883,2025-07-03,Drew Cain,Drew Cain; Paul Hernandez; bm-claudeai (AI Assistant); github-actions[bot] (AI Assistant),8519b0057468c4450eb543a2f561bcd0d7cb96e1ce1b95e948e02b309ba6b7ca
-src/basic_memory/repository/entity_repository.py,entity_repository.py,source_code,10405,2025-07-03,Drew Cain,Drew Cain; bm-claudeai (AI Assistant); Paul Hernandez,e2a8d1eba6c8d64bc61d7168df0fe8c29a670858bf9daeac464a0f440273fae0
-src/basic_memory/schemas/memory.py,memory.py,source_code,5833,2025-07-03,Drew Cain,Drew Cain; Paul Hernandez; bm-claudeai (AI Assistant),acb4a953a553feca672c4895798a7d948ec51f922f75b66dd7d55716e3bebed3
-src/basic_memory/services/entity_service.py,entity_service.py,source_code,30440,2025-07-03,Paul Hernandez,Paul Hernandez; Drew Cain; bm-claudeai (AI Assistant); github-actions[bot] (AI Assistant),7cd5163eca6b8a0772e838c8c869e478166763cd6a2d745b0b9aa5c25a65baee
-src/basic_memory/services/initialization.py,initialization.py,source_code,6715,2025-07-08,Paul Hernandez,Paul Hernandez; Drew Cain; bm-claudeai (AI Assistant),4dde58b799cf4ac90631e59949b55b3355a93bdf99df0d9c2408c0cea67e10c4
-src/basic_memory/templates/prompts/continue_conversation.hbs,continue_conversation.hbs,templates,3076,2025-07-01,Drew Cain,Drew Cain; bm-claudeai (AI Assistant),b6bac31d25c0e52d0909b2273285092f4e31bc219107f92ed511cd407b65e992
-src/basic_memory/utils.py,utils.py,source_code,8654,2025-07-30,jope-bm,jope-bm; Paul Hernandez; Drew Cain; andyxinweiminicloud; github-actions[bot] (AI Assistant),111f343e3367339730e081c08acf4613667be574f946126513b5d82da3086bed
-tests/mcp/test_tool_edit_note.py,test_tool_edit_note.py,source_code,13503,2025-07-03,Drew Cain,Drew Cain; Paul Hernandez,dd441969aa54b3739f2d9202d3feaf46aee807ec51e01a13ef41eda52743944f
-tests/mcp/test_tool_search.py,test_tool_search.py,source_code,10959,2025-07-03,Drew Cain,Drew Cain; Paul Hernandez; github-actions[bot] (AI Assistant),07839cf8e89d74ba05ec1dc55fa842444c1f0cc3d1587823b0ac3458ad89e87c
-tests/mcp/test_tool_write_note.py,test_tool_write_note.py,source_code,35136,2025-07-30,jope-bm,jope-bm; Drew Cain; Paul Hernandez,45172de20cfc4f4436287573b4f5a94b8b616a360647af67ba1c6c343ccd41b8
-tests/repository/test_entity_repository_upsert.py,test_entity_repository_upsert.py,source_code,16983,2025-07-03,Paul Hernandez,Paul Hernandez; Drew Cain,ee0ecd6f4ff8b31838bd6de6fb1018af437e02813d8315c06f4e20a6b78a0572
-tests/schemas/test_schemas.py,test_schemas.py,source_code,16880,2025-07-03,Drew Cain,Drew Cain; Paul Hernandez; bm-claudeai (AI Assistant),2c746a00c340f063c160ace67569955a300a294040949695c79fd4ae124fb611
-tests/services/test_entity_service.py,test_entity_service.py,source_code,59278,2025-07-03,Paul Hernandez,Paul Hernandez; Drew Cain; bm-claudeai (AI Assistant),d7d495756faa10b415d705cf26b69d2efbc5f190a834b6767386ff296629ea71
-tests/test_config.py,test_config.py,source_code,3680,2025-07-03,Paul Hernandez,Paul Hernandez; Drew Cain; bm-claudeai (AI Assistant),6a246431cff739274efda895dfa28f38710289a73e645312f5fa05fce0885ec8
-tests/test_db_migration_deduplication.py,test_db_migration_deduplication.py,source_code,6166,2025-07-08,Paul Hernandez,Paul Hernandez; Drew Cain,ab768e061531ca2edcd598c101b5d884e549f90c7a4b305a23713a199d263fbb
-uv.lock,uv.lock,other,232710,2025-07-30,Paul Hernandez,Paul Hernandez; Drew Cain; bm-claudeai (AI Assistant),caa1e3f6e66464b884a78cab77df2fe303fa3c0dc573be0196474b6d3c150581

legal_exhibits/joe_exhibit_a.csv

@@ -1,28 +0,0 @@
-file_path,file_name,category,size_bytes,modified_date,primary_author,all_contributors,sha256_hash
-CONTRIBUTING.md,CONTRIBUTING.md,documentation,7329,2025-07-30,jope-bm,jope-bm; Paul Hernandez,ca822fe39cc529bfc3822d317ab8a20fd141ec3ecb8c20de9e2eca3edce1c282
-justfile,justfile,other,5496,2025-07-30,jope-bm,jope-bm; Paul Hernandez; Drew Cain,a8df6c73ee8cf3eaa48e4cba193dffbc2821b843a8cc0c0cd58b8517f2252907
-src/basic_memory/api/routers/project_router.py,project_router.py,source_code,8444,2025-07-30,jope-bm,jope-bm; Paul Hernandez; bm-claudeai (AI Assistant),6539c69f1d506c65d14cc2c151876b19057f37d84d51a9e6f464ed47a4692648
-src/basic_memory/cli/commands/import_memory_json.py,import_memory_json.py,source_code,3013,2025-07-30,jope-bm,jope-bm; Paul Hernandez; bm-claudeai (AI Assistant),7ea193f6720b2672290ad16c79a143a31d88a1d567838f12b9ebf9110a7c0338
-src/basic_memory/cli/commands/project.py,project.py,source_code,13836,2025-07-30,jope-bm,jope-bm; Paul Hernandez; bm-claudeai (AI Assistant),af3e6f30410ab48355f4b1a46aaa3aa5423cb0a0490f51447db1d25e09f39916
-src/basic_memory/config.py,config.py,source_code,12487,2025-07-30,jope-bm,jope-bm; Paul Hernandez; Drew Cain; bm-claudeai (AI Assistant); github-actions[bot] (AI Assistant),86341330a041b94d38f5e4f1b94f3509d74351c67cc826af1a4ff57313e5f726
-src/basic_memory/importers/memory_json_importer.py,memory_json_importer.py,source_code,4631,2025-07-30,jope-bm,jope-bm; Paul Hernandez; bm-claudeai (AI Assistant),bc7d045299f17ed9ad5cebff7b1423250ec28a11130e47a0ac48d3ab82bdeafc
-src/basic_memory/mcp/async_client.py,async_client.py,source_code,925,2025-07-30,jope-bm,jope-bm; Paul Hernandez,6531f4387f30a30a322197ff51d6eacae4b25a58c648095931b3d1145d1da303
-src/basic_memory/mcp/tools/move_note.py,move_note.py,source_code,17541,2025-07-30,jope-bm,jope-bm; Paul Hernandez,5ef27d9baaebc2c5656fc49c4798a4e4e40a70b6cd9d1e761dbcae021bad558c
-src/basic_memory/mcp/tools/read_content.py,read_content.py,source_code,9125,2025-07-30,jope-bm,jope-bm; Paul Hernandez; bm-claudeai (AI Assistant),96a13addac507fd874394dfa2e1e5ed71af5eb89d0872c1d68cacf9cac3f8724
-src/basic_memory/mcp/tools/read_note.py,read_note.py,source_code,8132,2025-07-30,jope-bm,jope-bm; Paul Hernandez; bm-claudeai (AI Assistant); Amadeusz Wieczorek; github-actions[bot] (AI Assistant),dff53ce02b16d9c5fca315b3f09bb70867a89d614b0ef3f0548dce87978048ee
-src/basic_memory/mcp/tools/write_note.py,write_note.py,source_code,6612,2025-07-30,jope-bm,jope-bm; Paul Hernandez; bm-claudeai (AI Assistant),771396fb49d397feb5f7e36321d4d233c22c4d1b53414912c849957c6e96fc83
-src/basic_memory/repository/project_repository.py,project_repository.py,source_code,3803,2025-07-30,jope-bm,jope-bm; bm-claudeai (AI Assistant),9083ba214b2bcaaf98164d9c33cda7add52bc77f7269ecb6e43cdd5088728b7c
-src/basic_memory/schemas/importer.py,importer.py,source_code,693,2025-07-30,jope-bm,jope-bm; bm-claudeai (AI Assistant),ac33df423ca32b28ce7b6ea9c29d541f8783a86c0c29f78db35163bf93f139cd
-src/basic_memory/services/project_service.py,project_service.py,source_code,30125,2025-07-30,jope-bm,jope-bm; Paul Hernandez; bm-claudeai (AI Assistant),bce95c00aa9a1da0a8c8090ee34b5b1494207f8c99e6c25de4ec43fddc38f6be
-src/basic_memory/utils.py,utils.py,source_code,8654,2025-07-30,jope-bm,jope-bm; Paul Hernandez; Drew Cain; andyxinweiminicloud; github-actions[bot] (AI Assistant),111f343e3367339730e081c08acf4613667be574f946126513b5d82da3086bed
-tests/api/test_async_client.py,test_async_client.py,source_code,1382,2025-07-30,jope-bm,jope-bm; Paul Hernandez,a2f96226a75e5cff2326ca48ddccea4915964d83e529f7b99958bc233ccdc31a
-tests/api/test_project_router.py,test_project_router.py,source_code,13288,2025-07-30,jope-bm,jope-bm; Paul Hernandez; bm-claudeai (AI Assistant),af85d0870069d3831a9214372853994e5d12dc910e37298eb9958f72f6a8bb31
-tests/cli/test_import_memory_json.py,test_import_memory_json.py,source_code,4891,2025-07-30,jope-bm,jope-bm; bm-claudeai (AI Assistant); Paul Hernandez,d6734ce059dacf97bc764d848b2e2a6ba52fa96871bc331ec9d2ddc60b766bb6
-tests/cli/test_project_commands.py,test_project_commands.py,source_code,6578,2025-07-30,jope-bm,jope-bm; Paul Hernandez; bm-claudeai (AI Assistant),51e2ac7ff44b0d1a1db6da406c5c2e6aebceb1b63a1e8d5ab51bbaa834507157
-tests/mcp/test_tool_move_note.py,test_tool_move_note.py,source_code,25851,2025-07-30,jope-bm,jope-bm; Paul Hernandez,c9f95158503fa42e37532aaa35027538fa49cea718d059d570cf547d31f01043
-tests/mcp/test_tool_read_content.py,test_tool_read_content.py,source_code,19442,2025-07-30,jope-bm,jope-bm,1817e32f997b06dbdabf02864d0c70584c1cd80bf1fae8dfbef649de79434bc5
-tests/mcp/test_tool_read_note.py,test_tool_read_note.py,source_code,22991,2025-07-30,jope-bm,jope-bm; Paul Hernandez; Amadeusz Wieczorek; github-actions[bot] (AI Assistant),4e13ea9ff977525aa62b6a8c22505ffe989329dc3e7d07b71e044cf43ef3ddfd
-tests/mcp/test_tool_write_note.py,test_tool_write_note.py,source_code,35136,2025-07-30,jope-bm,jope-bm; Drew Cain; Paul Hernandez,45172de20cfc4f4436287573b4f5a94b8b616a360647af67ba1c6c343ccd41b8
-tests/repository/test_project_repository.py,test_project_repository.py,source_code,10511,2025-07-30,jope-bm,jope-bm; bm-claudeai (AI Assistant),279a3324635b1b515c18003bd1875cf230fef1192cadef9ca426846783717e75
-tests/services/test_project_service.py,test_project_service.py,source_code,28152,2025-07-30,jope-bm,jope-bm; Paul Hernandez; bm-claudeai (AI Assistant),430868ed796518937a3b0bed4d8c33be53264a6100d61d54b0745bb2b58bf29a
-tests/utils/test_validate_project_path.py,test_validate_project_path.py,source_code,15346,2025-07-30,jope-bm,jope-bm,27a4bf2a9d277e6cd773619e5241b20175d211ec60c284361bec404fd99143f3

legal_file_inventory.py

@@ -1,438 +0,0 @@
-#!/usr/bin/env python3
-"""
-Legal File Inventory Generator for Basic Memory
-
-This script generates a comprehensive file inventory for legal documentation purposes,
-including copyright assignments and company agreement exhibits.
-
-The inventory includes:
-- All source code files and their contributors
-- Documentation and configuration files
-- License and legal files
-- Excludes generated files, dependencies, and temporary files
-
-Usage:
-    python legal_file_inventory.py [--output inventory.csv] [--format csv|json|markdown]
-"""
-
-import os
-import json
-import csv
-import subprocess
-from pathlib import Path
-from datetime import datetime
-from typing import Dict, List
-import argparse
-import hashlib
-
-class FileInventoryGenerator:
-    def __init__(self, repo_path: str = "."):
-        self.repo_path = Path(repo_path).resolve()
-        self.inventory = []
-        
-        # File patterns to exclude from legal inventory
-        self.exclude_patterns = {
-            # Version control and git
-            '.git', '.gitignore', '.gitmodules',
-            
-            # Python compiled and cache files
-            '__pycache__', '*.pyc', '*.pyo', '*.pyd', '.pytest_cache',
-            
-            # Virtual environments and dependencies
-            '.venv', 'venv', '.env', 'env', 'ENV',
-            '*.dist-info', 'site-packages',
-            
-            # IDE and editor files
-            '.idea', '.vscode', '*.swp', '*.swo', '.DS_Store',
-            
-            # Build and distribution artifacts
-            'build', 'dist', 'htmlcov', '.coverage', '.coverage.*',
-            '*.egg-info', '.eggs', 'wheels',
-            
-            # Cache and temporary files
-            '.ruff_cache', '.mypy_cache', '.tox',
-            'node_modules', '.npm',
-            
-            # Documentation build artifacts (but keep source docs)
-            '.obsidian',
-            
-            # Lock files (these are generated)
-            'uv.lock', 'Pipfile.lock', 'poetry.lock', 'package-lock.json'
-        }
-        
-        # File extensions that are definitely source/authored content
-        self.source_extensions = {
-            '.py', '.md', '.rst', '.txt', '.toml', '.yaml', '.yml',
-            '.json', '.cfg', '.ini', '.conf', '.sh', '.sql',
-            '.js', '.ts', '.jsx', '.tsx', '.css', '.scss', '.sass',
-            '.html', '.htm', '.xml', '.svg', '.dockerfile', '.Dockerfile'
-        }
-        
-        # License file patterns
-        self.license_patterns = {
-            'LICENSE', 'LICENCE', 'COPYING', 'COPYRIGHT',
-            'license.txt', 'LICENSE.txt', 'LICENSE.md',
-            'CITATION.cff', 'CLA.md'
-        }
-
-    def run_git_command(self, command: List[str]) -> str:
-        """Run a git command and return the output."""
-        try:
-            result = subprocess.run(
-                ['git'] + command,
-                cwd=self.repo_path,
-                capture_output=True,
-                text=True,
-                check=True
-            )
-            return result.stdout.strip()
-        except subprocess.CalledProcessError:
-            return ""
-
-    def get_file_contributors(self, file_path: str) -> Dict[str, int]:
-        """Get contributors and their line contributions for a file."""
-        try:
-            blame_output = self.run_git_command(['blame', '--line-porcelain', file_path])
-            contributors = {}
-            
-            for line in blame_output.split('\n'):
-                if line.startswith('author '):
-                    author = line[7:]  # Remove 'author ' prefix
-                    contributors[author] = contributors.get(author, 0) + 1
-                    
-            return contributors
-        except Exception:
-            return {}
-
-    def get_file_history(self, file_path: str) -> Dict[str, any]:
-        """Get file creation date, last modification, and total commits."""
-        try:
-            # Get creation date (first commit)
-            first_commit = self.run_git_command([
-                'log', '--follow', '--format=%ad', '--date=iso',
-                '--reverse', file_path
-            ]).split('\n')[0] if self.run_git_command([
-                'log', '--follow', '--format=%ad', '--date=iso', 
-                '--reverse', file_path
-            ]) else None
-            
-            # Get last modification date
-            last_commit = self.run_git_command([
-                'log', '-1', '--format=%ad', '--date=iso', file_path
-            ])
-            
-            # Get total commits for this file
-            commit_count = len(self.run_git_command([
-                'log', '--follow', '--oneline', file_path
-            ]).split('\n')) if self.run_git_command([
-                'log', '--follow', '--oneline', file_path
-            ]) else 0
-            
-            return {
-                'created': first_commit or 'Unknown',
-                'last_modified': last_commit or 'Unknown',
-                'commit_count': commit_count
-            }
-        except Exception:
-            return {
-                'created': 'Unknown',
-                'last_modified': 'Unknown', 
-                'commit_count': 0
-            }
-
-    def should_exclude_file(self, file_path: Path) -> bool:
-        """Determine if a file should be excluded from the inventory."""
-        str_path = str(file_path)
-        
-        # Check if any part of the path matches exclude patterns
-        for pattern in self.exclude_patterns:
-            if pattern in str_path or file_path.match(pattern):
-                return True
-        
-        # Exclude files in virtual environment paths
-        if '/.venv/' in str_path or '/venv/' in str_path:
-            return True
-            
-        # Exclude binary files that are likely dependencies
-        if file_path.suffix in {'.so', '.dylib', '.dll', '.pyd'}:
-            return True
-            
-        return False
-
-    def calculate_file_hash(self, file_path: Path) -> str:
-        """Calculate SHA-256 hash of file content."""
-        try:
-            with open(file_path, 'rb') as f:
-                return hashlib.sha256(f.read()).hexdigest()
-        except Exception:
-            return ""
-
-    def categorize_file(self, file_path: Path) -> str:
-        """Categorize the file based on its path and extension."""
-        str_path = str(file_path).lower()
-        
-        # License and legal files
-        if any(pattern.lower() in file_path.name.lower() for pattern in self.license_patterns):
-            return "Legal/License"
-        
-        # Documentation
-        if file_path.suffix.lower() in {'.md', '.rst', '.txt'} and any(
-            doc_dir in str_path for doc_dir in ['doc', 'readme', 'changelog', 'contributing']
-        ):
-            return "Documentation"
-        
-        # Configuration files
-        if file_path.suffix.lower() in {'.toml', '.yaml', '.yml', '.json', '.cfg', '.ini', '.conf'}:
-            return "Configuration"
-        
-        # Source code
-        if file_path.suffix.lower() in {'.py', '.js', '.ts', '.jsx', '.tsx'}:
-            return "Source Code"
-        
-        # Tests
-        if 'test' in str_path and file_path.suffix.lower() == '.py':
-            return "Test Code"
-        
-        # Build and deployment
-        if file_path.name.lower() in {'dockerfile', 'justfile', 'makefile'} or file_path.suffix.lower() in {'.sh'}:
-            return "Build/Deployment"
-        
-        # Database and migrations
-        if 'migration' in str_path or 'alembic' in str_path or file_path.suffix.lower() == '.sql':
-            return "Database/Migration"
-        
-        # Templates and resources
-        if file_path.suffix.lower() in {'.hbs', '.j2', '.jinja', '.template'}:
-            return "Templates/Resources"
-        
-        return "Other"
-
-    def scan_repository(self):
-        """Scan the repository and build the file inventory."""
-        print(f"Scanning repository: {self.repo_path}")
-        
-        for root, dirs, files in os.walk(self.repo_path):
-            # Skip excluded directories
-            dirs[:] = [d for d in dirs if not any(pattern in d for pattern in self.exclude_patterns)]
-            
-            for file in files:
-                file_path = Path(root) / file
-                relative_path = file_path.relative_to(self.repo_path)
-                
-                # Skip excluded files
-                if self.should_exclude_file(relative_path):
-                    continue
-                
-                # Get file stats
-                try:
-                    stat_info = file_path.stat()
-                    file_size = stat_info.st_size
-                    modified_time = datetime.fromtimestamp(stat_info.st_mtime)
-                except Exception:
-                    file_size = 0
-                    modified_time = datetime.now()
-                
-                # Get git information
-                contributors = self.get_file_contributors(str(relative_path))
-                history = self.get_file_history(str(relative_path))
-                
-                # Calculate file hash for integrity verification
-                file_hash = self.calculate_file_hash(file_path)
-                
-                # Build inventory entry
-                entry = {
-                    'file_path': str(relative_path),
-                    'full_path': str(file_path),
-                    'file_name': file_path.name,
-                    'file_extension': file_path.suffix,
-                    'file_size_bytes': file_size,
-                    'category': self.categorize_file(relative_path),
-                    'fs_modified_date': modified_time.isoformat(),
-                    'git_created_date': history['created'],
-                    'git_last_modified': history['last_modified'],
-                    'git_commit_count': history['commit_count'],
-                    'contributors': contributors,
-                    'primary_author': max(contributors.items(), key=lambda x: x[1])[0] if contributors else 'Unknown',
-                    'contributor_count': len(contributors),
-                    'total_author_lines': sum(contributors.values()) if contributors else 0,
-                    'sha256_hash': file_hash,
-                    'scan_timestamp': datetime.now().isoformat()
-                }
-                
-                self.inventory.append(entry)
-        
-        print(f"Scanned {len(self.inventory)} files")
-
-    def get_summary_statistics(self) -> Dict:
-        """Generate summary statistics for the inventory."""
-        if not self.inventory:
-            return {}
-        
-        # Collect all contributors
-        all_contributors = set()
-        for entry in self.inventory:
-            all_contributors.update(entry['contributors'].keys())
-        
-        # Category breakdown
-        categories = {}
-        for entry in self.inventory:
-            cat = entry['category']
-            categories[cat] = categories.get(cat, 0) + 1
-        
-        # File extension breakdown
-        extensions = {}
-        for entry in self.inventory:
-            ext = entry['file_extension'] or 'no_extension'
-            extensions[ext] = extensions.get(ext, 0) + 1
-        
-        # Contributor statistics
-        contributor_files = {}
-        contributor_lines = {}
-        for entry in self.inventory:
-            for contributor, lines in entry['contributors'].items():
-                contributor_files[contributor] = contributor_files.get(contributor, 0) + 1
-                contributor_lines[contributor] = contributor_lines.get(contributor, 0) + lines
-        
-        return {
-            'total_files': len(self.inventory),
-            'total_contributors': len(all_contributors),
-            'categories': categories,
-            'file_extensions': extensions,
-            'contributor_file_counts': contributor_files,
-            'contributor_line_counts': contributor_lines,
-            'scan_date': datetime.now().isoformat(),
-            'repository_path': str(self.repo_path)
-        }
-
-    def export_csv(self, output_file: str):
-        """Export inventory to CSV format."""
-        with open(output_file, 'w', newline='', encoding='utf-8') as f:
-            if not self.inventory:
-                return
-            
-            fieldnames = list(self.inventory[0].keys())
-            # Convert complex fields to strings for CSV
-            fieldnames = [f for f in fieldnames if f != 'contributors']
-            fieldnames.append('contributors_json')
-            
-            writer = csv.DictWriter(f, fieldnames=fieldnames)
-            writer.writeheader()
-            
-            for entry in self.inventory:
-                row = {k: v for k, v in entry.items() if k != 'contributors'}
-                row['contributors_json'] = json.dumps(entry['contributors'])
-                writer.writerow(row)
-
-    def export_json(self, output_file: str):
-        """Export inventory to JSON format."""
-        export_data = {
-            'metadata': self.get_summary_statistics(),
-            'files': self.inventory
-        }
-        
-        with open(output_file, 'w', encoding='utf-8') as f:
-            json.dump(export_data, f, indent=2, ensure_ascii=False)
-
-    def export_markdown(self, output_file: str):
-        """Export inventory to Markdown format."""
-        stats = self.get_summary_statistics()
-        
-        with open(output_file, 'w', encoding='utf-8') as f:
-            f.write("# Basic Memory - Legal File Inventory\n\n")
-            f.write(f"**Generated:** {datetime.now().isoformat()}\n\n")
-            f.write(f"**Repository:** {stats.get('repository_path', 'Unknown')}\n\n")
-            
-            # Summary statistics
-            f.write("## Summary Statistics\n\n")
-            f.write(f"- **Total Files:** {stats.get('total_files', 0)}\n")
-            f.write(f"- **Total Contributors:** {stats.get('total_contributors', 0)}\n\n")
-            
-            # Categories
-            if 'categories' in stats:
-                f.write("### Files by Category\n\n")
-                for category, count in sorted(stats['categories'].items()):
-                    f.write(f"- **{category}:** {count} files\n")
-                f.write("\n")
-            
-            # Top contributors
-            if 'contributor_file_counts' in stats:
-                f.write("### Top Contributors by Files Modified\n\n")
-                sorted_contributors = sorted(
-                    stats['contributor_file_counts'].items(), 
-                    key=lambda x: x[1], 
-                    reverse=True
-                )[:10]
-                for contributor, count in sorted_contributors:
-                    f.write(f"- **{contributor}:** {count} files\n")
-                f.write("\n")
-            
-            # Detailed file listing
-            f.write("## Detailed File Inventory\n\n")
-            f.write("| File Path | Category | Size (bytes) | Primary Author | Contributors |\n")
-            f.write("|-----------|----------|--------------|----------------|-------------|\n")
-            
-            for entry in sorted(self.inventory, key=lambda x: x['file_path']):
-                contributors_str = ', '.join(entry['contributors'].keys())[:50]
-                if len(contributors_str) == 50:
-                    contributors_str += "..."
-                
-                f.write(f"| {entry['file_path']} | {entry['category']} | "
-                       f"{entry['file_size_bytes']} | {entry['primary_author']} | "
-                       f"{contributors_str} |\n")
-
-def main():
-    parser = argparse.ArgumentParser(
-        description="Generate legal file inventory for Basic Memory repository"
-    )
-    parser.add_argument(
-        '--output', '-o',
-        default='basic_memory_legal_inventory.csv',
-        help='Output file path (default: basic_memory_legal_inventory.csv)'
-    )
-    parser.add_argument(
-        '--format', '-f',
-        choices=['csv', 'json', 'markdown'],
-        default='csv',
-        help='Output format (default: csv)'
-    )
-    parser.add_argument(
-        '--repo-path', '-r',
-        default='.',
-        help='Path to repository (default: current directory)'
-    )
-    
-    args = parser.parse_args()
-    
-    # Initialize and run the inventory generator
-    generator = FileInventoryGenerator(args.repo_path)
-    generator.scan_repository()
-    
-    # Export in requested format
-    if args.format == 'csv':
-        generator.export_csv(args.output)
-    elif args.format == 'json':
-        generator.export_json(args.output)
-    elif args.format == 'markdown':
-        generator.export_markdown(args.output)
-    
-    # Print summary
-    stats = generator.get_summary_statistics()
-    print("\n=== Legal File Inventory Complete ===")
-    print(f"Repository: {stats.get('repository_path', 'Unknown')}")
-    print(f"Total files inventoried: {stats.get('total_files', 0)}")
-    print(f"Total contributors identified: {stats.get('total_contributors', 0)}")
-    print(f"Output written to: {args.output}")
-    
-    # Show top contributors
-    if 'contributor_file_counts' in stats:
-        print("\nTop 5 contributors by files modified:")
-        sorted_contributors = sorted(
-            stats['contributor_file_counts'].items(),
-            key=lambda x: x[1],
-            reverse=True
-        )[:5]
-        for i, (contributor, count) in enumerate(sorted_contributors, 1):
-            print(f"  {i}. {contributor}: {count} files")
-
-if __name__ == '__main__':
-    main()

legal_inventory/basic_memory_inventory_20250730_110133.csv

@@ -1,272 +0,0 @@
-path,name,category,size_bytes,modified_time,primary_author,contributor_count,contributors_list,sha256_hash
-.claude/commands/release/beta.md,beta.md,documentation,3103,2025-07-01T08:33:22.037438,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),345f06e3f304470a8892e96979355919c8e5d8f4212ebbe543c3272fd15a5cbe
-.claude/commands/release/changelog.md,changelog.md,documentation,4648,2025-07-03T18:43:10.075727,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),ea2484352f4f881aa71f546dcf84b0882d60c96673a88406aa2f7e12a282a1f4
-.claude/commands/release/release-check.md,release-check.md,documentation,3344,2025-07-01T08:33:22.040060,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),7dd41a40e95c89153936c4ea60a3c989eccd5973fff9f6caef156de82f12bd04
-.claude/commands/release/release.md,release.md,documentation,2925,2025-07-01T08:33:22.043674,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),0e4afd788fcf85fbe46094452e9b92a4290c3e23702283e72ee56aa9288476e5
-.claude/commands/test-live.md,test-live.md,documentation,18720,2025-07-03T18:43:10.076403,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),21a9edeefb3e5673d833151a2fd0464087c0f0a9d056fdd7fca474c1d177d6fc
-.dockerignore,.dockerignore,other,623,2025-07-01T08:33:22.048301,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),b3079bffad89d07186c9166725075524ffc07ceea6dc1d53fdbea6dca9585684
-.github/ISSUE_TEMPLATE/bug_report.md,bug_report.md,documentation,967,2025-03-01T14:22:50.968994,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),0d34443ddda84a5e9726c8268083c9646d2cc64ff9c5ebf56c89587cef4c7706
-.github/ISSUE_TEMPLATE/config.yml,config.yml,configuration,374,2025-03-01T14:23:26.936836,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),f4e21bb9b7f053509b6c08548a2649a5d62f44f0106810aa8c915d2f29acc623
-.github/ISSUE_TEMPLATE/documentation.md,documentation.md,documentation,557,2025-03-01T14:23:40.020117,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),78f80a6b9a2b954695f74a847a068e0b780da6020572401c13c931555a4a9db5
-.github/ISSUE_TEMPLATE/feature_request.md,feature_request.md,documentation,786,2025-03-01T14:23:06.344081,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),cee834de442221d53f3d2eeb85b81f3a641b3a7cb587ef8a169452305007439d
-.github/dependabot.yml,dependabot.yml,configuration,529,2025-03-15T10:40:16.936258,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),8c6c2ef9a1417da63adb49c70f45524129bd5c46bbd7452b6b97cfe65205f89d
-.github/workflows/claude.yml,claude.yml,legal,4628,2025-07-03T18:43:10.076958,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),d026f1756310781b85abc491b454cc31b52dfce4b951cdf8a4a555b6b047604c
-.github/workflows/dev-release.yml,dev-release.yml,configuration,1405,2025-06-03T08:31:42.915367,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),58bcfc9e11e210e02dee76aabe7d1378da4edafb7f61857049ee6ccee9d45ffa
-.github/workflows/docker.yml,docker.yml,configuration,1621,2025-07-01T08:33:22.049870,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),c918a86f2b16ebb45182a73c45272bcd6cea7022cc6e0eaeb2b2a24d8eebfe4d
-.github/workflows/pr-title.yml,pr-title.yml,configuration,887,2025-02-17T16:29:35.733646,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),b6df62a20235496feba4d9419c85d6e8446c4d447ad69e7f57b51cc8953f68f4
-.github/workflows/release.yml,release.yml,configuration,2479,2025-07-03T18:43:10.077261,Drew Cain,2,Drew Cain (groksrc@gmail.com); Paul Hernandez (paul@basicmachines.co),163307a99e2f3d317af6ae8927e1537654d88bf574a6958ac0bcd2d4de266b2a
-.github/workflows/test.yml,test.yml,configuration,1426,2025-07-01T08:33:22.054430,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),ab09084a11be8adfc83fc6285c652fbe44a4584aa7d7d3658fcf0c57112d1640
-.gitignore,.gitignore,other,566,2025-07-01T08:33:22.055006,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),358658b0faa8c3145e539421deba4ad0bac4a8ea2e608b2c2f867a822c67b36f
-.python-version,.python-version,other,5,2024-12-02T16:41:37.012830,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),7b55f8e67b5623c4bef3fa691288da9437d79d3aba156de48d481db32ac7d16d
-CHANGELOG.md,CHANGELOG.md,documentation,53647,2025-07-06T10:34:45.550847,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); semantic-release (semantic-release),0b165eb18975ff253cde08f4687b7808ac6ce63b6d8c10912c495a76c9058d1a
-CITATION.cff,CITATION.cff,other,302,2025-02-17T16:29:35.735146,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),bc4878cf6f80bb64655f3f93a5821ffe0924ad8311c784b5f81a36093fcffdda
-CLA.md,CLA.md,legal,1342,2025-03-01T14:12:38.435132,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),c238c7ff4f2b8451c6bba1bbacd10b04fb7d41d9a9cd76a62644d8193791d169
-CLAUDE.md,CLAUDE.md,legal,12310,2025-07-03T18:43:10.078147,Drew Cain,4,Drew Cain (groksrc@gmail.com); Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co); Ikko Eltociear Ashimine (eltociear@gmail.com),751f10c1a9a9c0ba2054d9c9cd36cf0989d6a347491fd505bb6504ee74b12900
-CODE_OF_CONDUCT.md,CODE_OF_CONDUCT.md,documentation,509,2025-02-17T16:29:35.735238,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),b276b464e85eb1e5d9f09d90bba9573508a7bf81d2eeb38d0f25bd9f2fa66198
-CONTRIBUTING.md,CONTRIBUTING.md,documentation,7329,2025-07-30T09:39:36.607158,jope-bm,2,jope-bm (joe@basicmemory.com); Paul Hernandez (paul@basicmachines.co),ca822fe39cc529bfc3822d317ab8a20fd141ec3ecb8c20de9e2eca3edce1c282
-Dockerfile,Dockerfile,other,856,2025-07-01T08:33:22.056908,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),c45501905423990e31ffdb8ae4e976eca6423c6784905c1036bcc7795b70feef
-LICENSE,LICENSE,legal,34523,2024-12-02T16:41:20.739392,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),8486a10c4393cee1c25392769ddd3b2d6c242d6ec7928e1414efff7dfb2f07ef
-README.md,README.md,documentation,16261,2025-07-03T18:43:10.078281,Drew Cain,6,Drew Cain (groksrc@users.noreply.github.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); Jason Noble (github+jasonn@jasonnoble.org); Marc Baiza (43151891+mbaiza27@users.noreply.github.com); Matias Forbord (codeluggage@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),2c4b82b30f49ab465617034fda999157450ed168f8e097fe8e9ca7ac65a197a7
-SECURITY.md,SECURITY.md,documentation,303,2025-03-12T16:04:01.989927,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),96932268b8fe737577941b49e9dff5ff8ad59c11cc3f9a016989589ef5c98c1f
-docker-compose.yml,docker-compose.yml,configuration,2534,2025-07-01T08:33:22.059281,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),4a9fdfd2f0d42b148fe021eee77fd5e772c7ba9c2fe5d0cc310c8c7a64257417
-docs/AI Assistant Guide.md,AI Assistant Guide.md,documentation,16423,2025-07-01T08:33:22.060491,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),c717869a3d356852077026591364ecb0589a6d53f9764af027c57d142ea7ff55
-docs/Docker.md,Docker.md,documentation,9088,2025-07-01T08:33:22.060976,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),e13d3f50148353046b52d9d493986880f76f2914ef4efe1a759b2cc9d10913a4
-justfile,justfile,other,5496,2025-07-30T09:39:36.608008,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com),a8df6c73ee8cf3eaa48e4cba193dffbc2821b843a8cc0c0cd58b8517f2252907
-llms-install.md,llms-install.md,documentation,2307,2025-06-29T14:19:28.826375,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),674105eb85c8f1d59fc2ddc6840f2a2a3e293358687a305c37dffc8144304f97
-memory.json,memory.json,configuration,90075,2025-06-29T14:19:28.827172,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),22d5eee995ca0548b7d9dd152f9a3690c42a514cbf38fea750b3ed2a17dd99c5
-pyproject.toml,pyproject.toml,configuration,3279,2025-07-30T09:39:36.608791,Paul Hernandez,4,Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co); semantic-release (semantic-release),428a5d64d4555dc7cd2a81b89a3444bdb1d2f3017257fbc9160bd0ae982718e1
-smithery.yaml,smithery.yaml,configuration,433,2025-03-11T16:36:03.389716,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),63f13499cf4fee0751b5005f5bd85597dc1c7f9a881f4ec8147cc23e95e75c2d
-src/basic_memory/__init__.py,__init__.py,source_code,256,2025-07-06T10:34:45.551291,Paul Hernandez,3,Paul Hernandez (paul@basicmachines.co); Drew Cain (groksrc@gmail.com); semantic-release (semantic-release),c946490ab9d64957d25df37f721392024916f8a81ed838f70a8e938b1c2637db
-src/basic_memory/alembic/alembic.ini,alembic.ini,configuration,3733,2025-02-23T17:31:23.198433,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),20466c9c5f026db66793006bebb2f328a3686c7bb34da40d52f33c3eca29e717
-src/basic_memory/alembic/env.py,env.py,source_code,2838,2025-07-08T20:39:18.336650,Paul Hernandez,3,Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),e241d987eadfcd5011cbd9ddbecb833d306de87937759d81c08d37d04a6906b0
-src/basic_memory/alembic/migrations.py,migrations.py,source_code,718,2025-06-21T00:01:59.613806,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),96b8873d70dd04b48d5c45b7413a54d1224ab9577557ef0dad5929377a9fb144
-src/basic_memory/alembic/script.py.mako,script.py.mako,other,635,2025-02-17T16:29:35.739659,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),304a8bfb6a804e5493f5300e79882c70c9f5bb2e87512f4d16f0e097dddd323f
-src/basic_memory/alembic/versions/3dae7c7b1564_initial_schema.py,3dae7c7b1564_initial_schema.py,source_code,4363,2025-06-21T00:01:59.595762,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),9536d69409ddd5eb3bc54f7d0e82607da45ed7f2ad7bc4cbf7cae2a9e28657cd
-src/basic_memory/alembic/versions/502b60eaa905_remove_required_from_entity_permalink.py,502b60eaa905_remove_required_from_entity_permalink.py,source_code,1840,2025-06-21T00:01:59.604717,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),93ac584e660f33d468b3eec203b070641298c282bf82655d0beda7f050237681
-src/basic_memory/alembic/versions/5fe1ab1ccebe_add_projects_table.py,5fe1ab1ccebe_add_projects_table.py,source_code,4379,2025-06-21T00:01:59.601299,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),d82098f5aca3cdbada60c7229ea4ac262f527349eed9ef9e864509bacfaccf7e
-src/basic_memory/alembic/versions/647e7a75e2cd_project_constraint_fix.py,647e7a75e2cd_project_constraint_fix.py,source_code,4210,2025-07-01T08:33:22.063463,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),604ac5908a5976272f52297866d13abb14a99390590935d9fd37cf13e32049fa
-src/basic_memory/alembic/versions/b3c3938bacdb_relation_to_name_unique_index.py,b3c3938bacdb_relation_to_name_unique_index.py,source_code,1428,2025-06-21T00:01:59.598551,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),46c1b2990cdf4575752d234a8b28b494c8a54f15b5360c12f6347aef27b66a92
-src/basic_memory/alembic/versions/cc7172b46608_update_search_index_schema.py,cc7172b46608_update_search_index_schema.py,source_code,3679,2025-06-21T00:01:59.610909,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),9036af47d42ac7dc12bb93f7a9de1266aff0688b031b550c4e0d92983a24b4c5
-src/basic_memory/api/__init__.py,__init__.py,source_code,72,2025-06-21T00:01:59.579981,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),c02a63fb6d63d43d0acca97d425eae9cb055158d0ad6e1a9fc57926512adaa99
-src/basic_memory/api/app.py,app.py,source_code,2897,2025-07-08T20:39:18.337081,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),ad673ac2c09410af5830f6afdffaa28b0040480dacd52ff01750b8b2c066e8cf
-src/basic_memory/api/routers/__init__.py,__init__.py,source_code,398,2025-06-21T00:01:59.549416,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (60959+phernandez@users.noreply.github.com),4443b908a43dea8e6fb4658009cb08c48a56c9b21449e29773cdd159b59cf014
-src/basic_memory/api/routers/directory_router.py,directory_router.py,source_code,2054,2025-06-21T00:01:59.567371,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),ac1407beec1f7d43a4d222af704b3642559c960bebf2eaf6e1ffe91f7fac5514
-src/basic_memory/api/routers/importer_router.py,importer_router.py,source_code,4513,2025-06-21T00:01:59.561600,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),c45502a2b90f5a8f00174c9ad14adc2e65cd7fc0a33d9740a9d750207f0f3bea
-src/basic_memory/api/routers/knowledge_router.py,knowledge_router.py,source_code,9738,2025-07-01T08:33:22.064119,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),e1d0ffb4fa5c246582ba844a11b417092de1a173567be55b7060bbc55fbc5681
-src/basic_memory/api/routers/management_router.py,management_router.py,source_code,2730,2025-07-08T20:39:18.337438,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),cdbce294dcec6146c56c4dae15744cdf77039fd21b23eef7cbc0b5f9bfb5f4ee
-src/basic_memory/api/routers/memory_router.py,memory_router.py,source_code,3003,2025-07-01T08:33:22.064510,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),6bd0a7c775e0c1290efb6001173237c0cdcfa0c1b1bb27c9145a7b35f1596a97
-src/basic_memory/api/routers/project_router.py,project_router.py,source_code,8444,2025-07-30T09:39:45.721369,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),6539c69f1d506c65d14cc2c151876b19057f37d84d51a9e6f464ed47a4692648
-src/basic_memory/api/routers/prompt_router.py,prompt_router.py,source_code,9948,2025-07-01T08:33:22.065221,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),e30c6aebe35112054933c37d0b462c3750005030fc9e44c23b35b2cd2a93485c
-src/basic_memory/api/routers/resource_router.py,resource_router.py,source_code,8058,2025-06-21T00:01:59.570399,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),584244a84698ff24ca8f9f94fab5b891740a51c25f972920c08ebf83f478d5c9
-src/basic_memory/api/routers/search_router.py,search_router.py,source_code,1226,2025-06-21T00:01:59.543020,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),183eb68e50904e22ff54db1d89b8be6f57fa1f8d0a096a3d497d8297b607e105
-src/basic_memory/api/routers/utils.py,utils.py,source_code,5159,2025-07-03T18:43:10.079143,Drew Cain,2,Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),9e60f57da24e1dc9d64236c26a7a2353003dc618a77fbeb853c494aa3357a57c
-src/basic_memory/api/template_loader.py,template_loader.py,source_code,8607,2025-06-21T00:01:59.576132,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),7b16d3797c89460c8b1664a335eae8c634fb5f60d6166d97e6a5156b776b6d83
-src/basic_memory/cli/__init__.py,__init__.py,source_code,33,2025-06-21T00:01:59.456735,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),6ab70a2c05910e13c3ef1e6df34325be265e633c076741998a0cb2dcd295a069
-src/basic_memory/cli/app.py,app.py,source_code,2268,2025-07-08T20:39:18.337708,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),f710670380d707c4458ad881f7a25bb3c5cdb2bcff59f139f37421264fe8f2f8
-src/basic_memory/cli/commands/__init__.py,__init__.py,source_code,393,2025-07-08T20:39:18.338070,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),de8a23702f98fb844fa9f7fdbedc16ce24ff4f8baf05589c2f4a521cd8a55645
-src/basic_memory/cli/commands/db.py,db.py,source_code,1480,2025-07-08T20:39:18.338326,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),704a1096d80ab9d12e247d029fe6223e935a0d0ceee7e615c020f46a720828e0
-src/basic_memory/cli/commands/import_chatgpt.py,import_chatgpt.py,source_code,2856,2025-07-08T20:39:18.338787,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),8957cca3acab6351335624a518bdc19d956487e93d86dd1b6c2309e9d5850ae5
-src/basic_memory/cli/commands/import_claude_conversations.py,import_claude_conversations.py,legal,2946,2025-07-08T20:39:18.339053,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),7bc97838732bf00f4fb4a80e3ba4fdfbce8971ae85cc2ac902c3b3a3e110ae57
-src/basic_memory/cli/commands/import_claude_projects.py,import_claude_projects.py,legal,2891,2025-07-08T20:39:18.339310,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),6321577075801c99ad47a0cdc13b5aa3c9ca102a05ca8f06ae2a51125a8c43bc
-src/basic_memory/cli/commands/import_memory_json.py,import_memory_json.py,source_code,3013,2025-07-30T09:39:45.721637,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),7ea193f6720b2672290ad16c79a143a31d88a1d567838f12b9ebf9110a7c0338
-src/basic_memory/cli/commands/mcp.py,mcp.py,source_code,2593,2025-07-08T20:39:18.340025,Paul Hernandez,3,Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),3e1be3d27b18ef4743204b7cf8a37fbc2a1a91fc1636c468e08cefcd8597bac6
-src/basic_memory/cli/commands/project.py,project.py,source_code,13836,2025-07-30T09:39:45.721838,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),af3e6f30410ab48355f4b1a46aaa3aa5423cb0a0490f51447db1d25e09f39916
-src/basic_memory/cli/commands/status.py,status.py,source_code,5809,2025-07-08T20:39:18.340324,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),b6d0ea237d714d054f69b24a2058beba74e224a2fa4a80a525d62a2aa2ea2d70
-src/basic_memory/cli/commands/sync.py,sync.py,source_code,8213,2025-07-08T20:39:18.340627,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),703b3e73c4c33850c27f6f4c07abbf5d4ce5dc43f706bf0c43264bbb45f8b213
-src/basic_memory/cli/commands/tool.py,tool.py,source_code,9540,2025-07-01T08:33:22.070903,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),9b2fa400b9f7921bf55b602f8bbdfa36b1ec7e4a5bc8fe7b9838b92e31f0a9ed
-src/basic_memory/cli/main.py,main.py,source_code,465,2025-07-08T20:39:18.340868,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),7a405b12bff98e319968526238ae15859df0362bba5a3857562fecca47b5c70d
-src/basic_memory/config.py,config.py,source_code,12487,2025-07-30T09:39:45.722031,jope-bm,5,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),86341330a041b94d38f5e4f1b94f3509d74351c67cc826af1a4ff57313e5f726
-src/basic_memory/db.py,db.py,source_code,7428,2025-07-08T20:39:18.341550,Paul Hernandez,3,Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),25e053b0b3f9e8fa823b05fc099001efe8a3a4f6e0f80728e5079ba45aa406d8
-src/basic_memory/deps.py,deps.py,source_code,12144,2025-07-08T20:39:18.341870,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),bce28cd9ca549b8afce0bc689cc1fb2dc80cd5b929f85114aa682bb8ae82411d
-src/basic_memory/file_utils.py,file_utils.py,source_code,6700,2025-06-21T00:01:59.587200,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),79ac5328b2c46d3232fcc6ff22ffc39ade085c0252ad91958be2a7ae9c9c8b71
-src/basic_memory/importers/__init__.py,__init__.py,source_code,795,2025-06-21T00:01:59.295471,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),0537015bdecfded85cb166b9c3db50b2f3aef329c70e0c36fbcb4f824099a21f
-src/basic_memory/importers/base.py,base.py,source_code,2531,2025-06-21T00:01:59.305335,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),6b0c1efd4f827f348834aa0cea2ae8eebbb842a2e5b1f5f3747ced0ef79b9f13
-src/basic_memory/importers/chatgpt_importer.py,chatgpt_importer.py,source_code,7372,2025-06-21T00:01:59.308956,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),dfa540b196ab23b5c4e6bfcac4da567873351cf7c78fa35f4c3b87e84c58e218
-src/basic_memory/importers/claude_conversations_importer.py,claude_conversations_importer.py,legal,5725,2025-06-21T00:01:59.288540,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),a7bc9e872f4f81ce5f79fe9dd1a6fd0f00a6f020a2cb2664184a97f14eeb1dbc
-src/basic_memory/importers/claude_projects_importer.py,claude_projects_importer.py,legal,5389,2025-06-21T00:01:59.291737,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),a452675fd9bb18ebf64eb4bd7f69ccd7e993b617931015a3c4ab700d67493863
-src/basic_memory/importers/memory_json_importer.py,memory_json_importer.py,source_code,4631,2025-07-30T09:39:45.722316,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),bc7d045299f17ed9ad5cebff7b1423250ec28a11130e47a0ac48d3ab82bdeafc
-src/basic_memory/importers/utils.py,utils.py,source_code,1792,2025-06-21T00:01:59.298428,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),ee7e22fd4812362394f62ed8944abe80738c1e3ab88131faf639f4a8ccfd6c89
-src/basic_memory/markdown/__init__.py,__init__.py,source_code,501,2025-06-21T00:01:59.316337,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),0ddce2a025ad0e729aab4e411d82e02ffefc15ac041cba4b5e7a7e90f4957c87
-src/basic_memory/markdown/entity_parser.py,entity_parser.py,source_code,4516,2025-06-21T00:01:59.321461,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),1b0d1177358645ccbadd170b3f62760dc9bd838d38c741978ab0da5836234d68
-src/basic_memory/markdown/markdown_processor.py,markdown_processor.py,source_code,4968,2025-06-21T00:01:59.325241,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),4b99f2ebdceed9d96a3bbb562682eba4b4b383c7a64080eaec3bbba25a4952c9
-src/basic_memory/markdown/plugins.py,plugins.py,source_code,6639,2025-06-21T00:01:59.312733,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),82d2332918e866ccaf06a2e954d9eb9b397f71b4d9e591a7f2472e5f1423464a
-src/basic_memory/markdown/schemas.py,schemas.py,source_code,1896,2025-06-21T00:01:59.329982,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),7b2c580abd615725a62267257b46ac13922dfc30fa01192a681658bb528ae67e
-src/basic_memory/markdown/utils.py,utils.py,source_code,3410,2025-07-03T18:43:10.079889,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),1b757f0d06e60e3ea276c0b2ea44fe1a156a895e093c1e607d6286e702bf4ae4
-src/basic_memory/mcp/__init__.py,__init__.py,source_code,35,2025-06-21T00:01:59.404757,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),76c0ce84aaa361e21b0942db1c8c5f708b536eab9d12e120d4da7ce9eab41844
-src/basic_memory/mcp/async_client.py,async_client.py,source_code,925,2025-07-30T09:39:45.722547,jope-bm,2,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com),6531f4387f30a30a322197ff51d6eacae4b25a58c648095931b3d1145d1da303
-src/basic_memory/mcp/project_session.py,project_session.py,source_code,4203,2025-07-08T20:39:18.342906,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),4da403ec93dec9063eeb8b05246e3501740d162cc77a067d3ce54ba43d690819
-src/basic_memory/mcp/prompts/__init__.py,__init__.py,source_code,615,2025-07-08T20:39:18.343263,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),f8197d0e08f64c3f4f50b8f38203ea5eebcf123582472ed2f58834de1dbe53b0
-src/basic_memory/mcp/prompts/ai_assistant_guide.py,ai_assistant_guide.py,source_code,821,2025-06-21T00:13:53.262832,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),f13239c4e6e2455730bfac3d6f2d71407957d3086fc84efe2c6b22a833114c58
-src/basic_memory/mcp/prompts/continue_conversation.py,continue_conversation.py,source_code,1998,2025-06-21T00:13:53.263309,bm-claudeai (AI Assistant),3,bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com); Paul Hernandez (60959+phernandez@users.noreply.github.com),aec9a50b657b7bb1ba0c02b42bcdb9bc5b0f2a0b1143bd361c5ce7ea59076833
-src/basic_memory/mcp/prompts/recent_activity.py,recent_activity.py,source_code,3311,2025-07-01T08:33:22.073986,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),d2fd5cddbd927430f15d5b85f1e3a3368a18cb4e2e4587a5d29749d2b9e0830e
-src/basic_memory/mcp/prompts/search.py,search.py,source_code,1692,2025-06-21T00:13:53.264093,bm-claudeai (AI Assistant),3,bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com); Paul Hernandez (60959+phernandez@users.noreply.github.com),9dbf3c319cbdb5d5bf32608b51522d8ae92b2dd6f7c441d62efd0954b525738a
-src/basic_memory/mcp/prompts/utils.py,utils.py,source_code,5431,2025-06-21T00:01:59.425042,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (60959+phernandez@users.noreply.github.com),55a72b6eac18b724a9225608aca1e8e6cea3b684ccb1c609aab1511f7ce90ba4
-src/basic_memory/mcp/resources/ai_assistant_guide.md,ai_assistant_guide.md,documentation,14777,2025-03-28T19:12:38.653627,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),aa76160e46256fe2662ae3a86799659916acfede1d5835c1fe2f0b136efb2e0b
-src/basic_memory/mcp/resources/project_info.py,project_info.py,source_code,1906,2025-06-21T00:13:53.264918,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),2dc5244f1e225c17d4e8ba784d5721efc3aa2e8a5b3b2e258f22a77ebe155eca
-src/basic_memory/mcp/server.py,server.py,source_code,1248,2025-07-08T20:39:18.343419,Paul Hernandez,3,Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),0a910cae27d61ea923e90fbe2d4b5c7cacf3b29d3e156f0b7f77872ab973c761
-src/basic_memory/mcp/tools/__init__.py,__init__.py,source_code,1619,2025-07-03T18:43:10.080029,Drew Cain,2,Drew Cain (groksrc@users.noreply.github.com); Paul Hernandez (paul@basicmachines.co),872b771dd52ec3b763645a2baf6e10a70f049ce3106830a6d3f053b3e09a5fe6
-src/basic_memory/mcp/tools/build_context.py,build_context.py,source_code,4611,2025-07-03T18:43:10.080426,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),724280b77b8f5f3e61cd3fdeebc3ee66e2bcfedaaea3638e6a2e2e33fcb1978e
-src/basic_memory/mcp/tools/canvas.py,canvas.py,source_code,3738,2025-07-01T08:33:22.076204,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),db617d1bd81f3dbfa5f22d41e6b6b825afe1f73618f37acf63d9830390b98246
-src/basic_memory/mcp/tools/delete_note.py,delete_note.py,source_code,7346,2025-07-01T08:33:22.076726,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),b52c9173f5600662f255e7a70a5c17d5293ef8b29c19a8403334d7da62b65c8b
-src/basic_memory/mcp/tools/edit_note.py,edit_note.py,source_code,13570,2025-07-01T08:33:22.077181,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),ab8c7e7fbfa3fe5fb0ce6d7bf805454f5fd6182a340aae25237b1e6127b6d5a6
-src/basic_memory/mcp/tools/list_directory.py,list_directory.py,source_code,5236,2025-06-21T00:13:53.267453,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),f85c43b02aeee580f4d8ce2a9100c0bab1095b245a0bb608e1847ace0d1ab51f
-src/basic_memory/mcp/tools/move_note.py,move_note.py,source_code,17541,2025-07-30T09:39:45.722919,jope-bm,2,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com),5ef27d9baaebc2c5656fc49c4798a4e4e40a70b6cd9d1e761dbcae021bad558c
-src/basic_memory/mcp/tools/project_management.py,project_management.py,source_code,12944,2025-07-06T10:34:45.552403,Drew Cain,2,Drew Cain (groksrc@users.noreply.github.com); Paul Hernandez (paul@basicmachines.co),cdac736d65129f689a85c6b82f8e043bc84a31657ead7a8331771171eeaa860f
-src/basic_memory/mcp/tools/read_content.py,read_content.py,source_code,9125,2025-07-30T09:39:45.723469,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),96a13addac507fd874394dfa2e1e5ed71af5eb89d0872c1d68cacf9cac3f8724
-src/basic_memory/mcp/tools/read_note.py,read_note.py,source_code,8132,2025-07-30T09:39:45.723828,jope-bm,5,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co); Amadeusz Wieczorek (git@amadeusw.com); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),dff53ce02b16d9c5fca315b3f09bb70867a89d614b0ef3f0548dce87978048ee
-src/basic_memory/mcp/tools/recent_activity.py,recent_activity.py,source_code,4833,2025-06-21T00:13:53.269120,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),5d58cd2402679b1bf3c7dfcbb3503e40e776c9347ba499524d3b91c528af98de
-src/basic_memory/mcp/tools/search.py,search.py,source_code,15883,2025-07-03T18:43:10.081557,Drew Cain,4,Drew Cain (groksrc@gmail.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),8519b0057468c4450eb543a2f561bcd0d7cb96e1ce1b95e948e02b309ba6b7ca
-src/basic_memory/mcp/tools/sync_status.py,sync_status.py,source_code,10517,2025-07-08T20:39:18.344231,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),73dd73b186eaec8b82e6b17e39a67c27082d24e0653dc4e4b35712bd83b80a22
-src/basic_memory/mcp/tools/utils.py,utils.py,source_code,20892,2025-07-30T09:39:36.616253,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),a95004911e276822eba88a3fef15c5b9ba861b1ca9a2ecfe0c1e3fb2f4ef0116
-src/basic_memory/mcp/tools/view_note.py,view_note.py,source_code,2499,2025-07-01T08:33:22.080024,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),75d357c72113b1d0394987e521a4158ff09b77b23b08b56cddab5144331b1a68
-src/basic_memory/mcp/tools/write_note.py,write_note.py,source_code,6612,2025-07-30T09:39:45.723985,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),771396fb49d397feb5f7e36321d4d233c22c4d1b53414912c849957c6e96fc83
-src/basic_memory/models/__init__.py,__init__.py,source_code,333,2025-06-21T00:01:59.437212,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),8f40b876d162f85384690291f1d416106f9d26d750d793414e2260e276c85cd5
-src/basic_memory/models/base.py,base.py,source_code,225,2025-06-21T00:01:59.447249,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),e2101727c084d519e32a16f6de53ddf9033b1bf15721d4e8c0c27d6d18b1b295
-src/basic_memory/models/knowledge.py,knowledge.py,source_code,7087,2025-06-21T00:01:59.444376,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),005c5f292f1f45ae372aadc48c9080b9fa6d7b854d0bb7ecf587ec843ac1e28d
-src/basic_memory/models/project.py,project.py,source_code,2773,2025-07-01T08:33:22.080907,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),a14ad06943aeeff9ae4a5fa2dfc0e1d07ce6085acc02dc20c402c3513b7d9397
-src/basic_memory/models/search.py,search.py,source_code,1300,2025-06-21T00:01:59.440923,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),3e143cc38b5a0294af8e1d43a4f841e1c1fd193b76136a68f83159ce19e86646
-src/basic_memory/repository/__init__.py,__init__.py,source_code,327,2025-06-21T00:01:59.256363,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),3162bea3c42292accea5ee52c8f6ca4368a8079056034529cfae6d820f84d035
-src/basic_memory/repository/entity_repository.py,entity_repository.py,source_code,10405,2025-07-03T18:43:10.082570,Drew Cain,3,Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),e2a8d1eba6c8d64bc61d7168df0fe8c29a670858bf9daeac464a0f440273fae0
-src/basic_memory/repository/observation_repository.py,observation_repository.py,source_code,2943,2025-06-21T00:01:59.269646,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (phernandez@basicmachines.co),aa132f1cb4a36a84f715afdc40e2ac4f98d83e3eba1974b2b4404cc0b020ca04
-src/basic_memory/repository/project_info_repository.py,project_info_repository.py,source_code,338,2025-06-21T00:01:59.252582,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (60959+phernandez@users.noreply.github.com),f172d50182a405643a19b2a3d62a80f4e2b41463c775394eb3b66d7de51ff6df
-src/basic_memory/repository/project_repository.py,project_repository.py,source_code,3803,2025-07-30T09:39:45.724344,jope-bm,2,jope-bm (joe@basicmemory.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),9083ba214b2bcaaf98164d9c33cda7add52bc77f7269ecb6e43cdd5088728b7c
-src/basic_memory/repository/relation_repository.py,relation_repository.py,source_code,3179,2025-06-21T00:01:59.246745,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),cfb3a8e59cff27e063e91bd00e949647bdd92e4d9fc46edeee3acc6de15e26f4
-src/basic_memory/repository/repository.py,repository.py,source_code,15224,2025-06-21T00:01:59.273355,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (60959+phernandez@users.noreply.github.com),3096fe71bf106506cbf86aeafe2aafe0aabbe5a5f6c90a212c8aa1e53e1f171c
-src/basic_memory/repository/search_repository.py,search_repository.py,source_code,21936,2025-07-03T18:43:10.082844,Paul Hernandez,3,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),a972f73d1b71dac5770e8eb3793c6c9ac44e4e792f9dab528f8c4e6c6a80bcaa
-src/basic_memory/schemas/__init__.py,__init__.py,source_code,1674,2025-06-21T00:01:59.514555,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (60959+phernandez@users.noreply.github.com),98480815c75379bfafe32d2090e87fa40e73caa19b664fbd5db5ea9528ba58cb
-src/basic_memory/schemas/base.py,base.py,source_code,6738,2025-07-01T08:33:22.082193,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),171f7b0c4ab33abef2f7379eb1e3bda950586ce7edff83907fd12255f84e267e
-src/basic_memory/schemas/delete.py,delete.py,source_code,1180,2025-06-21T00:01:59.502563,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),50047624af7d58c8f780ffb2a065a51c3dde64492f9534917fc42860813e59fc
-src/basic_memory/schemas/directory.py,directory.py,source_code,881,2025-06-21T00:01:59.529023,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),17dfcbac9a91a9bfe43b4f060ca2735cb6f69e16d81b63dd554a397830ff29fe
-src/basic_memory/schemas/importer.py,importer.py,source_code,693,2025-07-30T09:39:45.724633,jope-bm,2,jope-bm (joe@basicmemory.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),ac33df423ca32b28ce7b6ea9c29d541f8783a86c0c29f78db35163bf93f139cd
-src/basic_memory/schemas/memory.py,memory.py,source_code,5833,2025-07-03T18:43:10.083167,Drew Cain,3,Drew Cain (groksrc@users.noreply.github.com); Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),acb4a953a553feca672c4895798a7d948ec51f922f75b66dd7d55716e3bebed3
-src/basic_memory/schemas/project_info.py,project_info.py,source_code,7047,2025-07-01T08:33:22.083248,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),7dc3635297b6e7fe6e3262b2d78da26f7a79a846a4cecd5624f2e4828979cf2c
-src/basic_memory/schemas/prompt.py,prompt.py,source_code,3648,2025-06-21T00:01:59.525753,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),4a92157d9a6b413f04e6e3f8d23dc2a417369c729f9703a8de2643ec114f2071
-src/basic_memory/schemas/request.py,request.py,source_code,3760,2025-06-21T00:01:59.511789,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),32fe44beb2d99452223ebf1d3a3a3fe105ef92c79885023b71dfd7db30ecc503
-src/basic_memory/schemas/response.py,response.py,source_code,6450,2025-07-03T18:43:10.083478,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),5eea4660a2abe48d83ed083d1c2483fdcfb403e0b504f03c14d22f1cae866abb
-src/basic_memory/schemas/search.py,search.py,source_code,3657,2025-06-21T00:01:59.522804,bm-claudeai (AI Assistant),3,bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com); Paul Hernandez (60959+phernandez@users.noreply.github.com),cb032c0c60102b6b0ed934f995cf9d6bf93aece296d71d537a75e8ae61c75afe
-src/basic_memory/services/__init__.py,__init__.py,source_code,259,2025-06-21T00:01:59.655059,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),5c6b7c597ddf5ffd0af4bdfb32ccbc1c5f2794c658206dee43a9945fafe226d8
-src/basic_memory/services/context_service.py,context_service.py,source_code,14462,2025-06-21T00:01:59.672086,bm-claudeai (AI Assistant),3,bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com); Paul Hernandez (paulmh@gmail.com),e1178b005e6a89f03d6b239e3c6b152aeb30d535a3f280734440a3aec16228f2
-src/basic_memory/services/directory_service.py,directory_service.py,source_code,6017,2025-06-21T00:01:59.648501,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),fd838f5ec79033892777b3c8140868f4b57f13e1658d513959524a434b9f959b
-src/basic_memory/services/entity_service.py,entity_service.py,source_code,30440,2025-07-03T18:43:10.083956,Paul Hernandez,4,Paul Hernandez (paul@basicmachines.co); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),7cd5163eca6b8a0772e838c8c869e478166763cd6a2d745b0b9aa5c25a65baee
-src/basic_memory/services/exceptions.py,exceptions.py,source_code,390,2025-06-21T00:01:59.668908,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),a158d0af9d1742a9c5ab5f8c34a062948d9286d1c3c72a5abf20e4d547b21e1c
-src/basic_memory/services/file_service.py,file_service.py,source_code,10059,2025-06-21T00:01:59.641785,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),8c2ae69c4913438b7d1c5ecbfcce812fbb5d0ea8e3cedcbd8694e8f40cf086f3
-src/basic_memory/services/initialization.py,initialization.py,source_code,6715,2025-07-08T20:39:18.344482,Paul Hernandez,3,Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),4dde58b799cf4ac90631e59949b55b3355a93bdf99df0d9c2408c0cea67e10c4
-src/basic_memory/services/link_resolver.py,link_resolver.py,source_code,4594,2025-07-01T08:33:22.084908,Paul Hernandez,3,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),d7efd516cbea753e6b5411def09aeaeb7539f5743487119ecf163c736e138a8c
-src/basic_memory/services/project_service.py,project_service.py,source_code,30125,2025-07-30T09:39:45.725079,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),bce95c00aa9a1da0a8c8090ee34b5b1494207f8c99e6c25de4ec43fddc38f6be
-src/basic_memory/services/search_service.py,search_service.py,source_code,12782,2025-06-21T00:01:59.665439,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),7392b2d2e7f3ed83c5807855ccd450e0e79c17f254aedee700bce9323a1b5b83
-src/basic_memory/services/service.py,service.py,source_code,336,2025-06-21T00:01:59.636167,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),57e77ff20395d3bcc62100e92fe2acaacdd937d977a9fdc764e2b57ff60d4da8
-src/basic_memory/services/sync_status_service.py,sync_status_service.py,source_code,7504,2025-07-03T18:43:10.084229,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),0a025d689e8e16f1632872104952105fc904537f3d32bcff592eb1f1dc76fbb7
-src/basic_memory/sync/__init__.py,__init__.py,source_code,156,2025-06-21T00:01:59.621137,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),0951e0b981f8e7b876bb6c6833c2af3a29490bbd5726567ea9487c947723623e
-src/basic_memory/sync/background_sync.py,background_sync.py,source_code,726,2025-07-08T20:39:18.345062,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),549af64ae91128b76c6df07ef517b82de85ca4ad796be44b5c0141fac01d4513
-src/basic_memory/sync/sync_service.py,sync_service.py,source_code,23387,2025-07-01T08:33:22.086507,Paul Hernandez,3,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),0310b927561370f593980d07773bce641b618b8fbf2d9e3890d174290a0344fc
-src/basic_memory/sync/watch_service.py,watch_service.py,source_code,15316,2025-06-26T09:28:51.859209,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (60959+phernandez@users.noreply.github.com),240ba6ac7523575945f4db442b7da3820d26c9605f2d7a2d357c4e35e215f523
-src/basic_memory/templates/prompts/continue_conversation.hbs,continue_conversation.hbs,templates,3076,2025-07-01T08:33:22.086792,Drew Cain,2,Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),b6bac31d25c0e52d0909b2273285092f4e31bc219107f92ed511cd407b65e992
-src/basic_memory/templates/prompts/search.hbs,search.hbs,templates,3098,2025-05-25T10:07:54.520119,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),1f570222c1caa78542d46ac7d8a79407ca467b9bd714fa9bd953e8b72a667820
-src/basic_memory/utils.py,utils.py,source_code,8654,2025-07-30T09:39:45.725428,jope-bm,5,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com); andyxinweiminicloud (andyxinweimin263@icloud.com); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),111f343e3367339730e081c08acf4613667be574f946126513b5d82da3086bed
-test-int/conftest.py,conftest.py,source_code,8203,2025-07-08T20:39:18.345735,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),7231e1bc76cddc7c94433e853825dc0165b103bedf996c2c24eda6ae32fff5ad
-test-int/mcp/test_build_context_validation.py,test_build_context_validation.py,source_code,6469,2025-07-08T20:39:18.346021,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),ee61d6b15cee0194fd74c1bcf9361d5a839f6081c7d571ef081da8fcefe1bbf2
-test-int/mcp/test_delete_note_integration.py,test_delete_note_integration.py,source_code,13175,2025-07-08T20:39:18.346366,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),497495249b8bcf0af177d8705c6899875460707697980434e560cfe56f86feb3
-test-int/mcp/test_edit_note_integration.py,test_edit_note_integration.py,source_code,19822,2025-07-08T20:39:18.346730,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),9ba704badd05808aee0b5a686b7e250e1c865229ec92dab561cba5287b6f6fc6
-test-int/mcp/test_list_directory_integration.py,test_list_directory_integration.py,source_code,14744,2025-07-08T20:39:18.347106,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),2c4336a59de63f17ed252bb52d1330ebca901ad83bfebc9e5aa67f132a3c77c6
-test-int/mcp/test_move_note_integration.py,test_move_note_integration.py,source_code,19825,2025-07-08T20:39:18.347344,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),cbb17688d0f9551306a7520b059ace7f7dfba70fc20bf0ec98b1148000d7ad7d
-test-int/mcp/test_project_management_integration.py,test_project_management_integration.py,source_code,33175,2025-07-08T20:39:18.347658,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),93a43cd699453a7602a5def839740ba5027ab914eba3e7b66a026860ed6bd567
-test-int/mcp/test_project_state_sync_integration.py,test_project_state_sync_integration.py,source_code,7728,2025-07-08T20:39:18.347907,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),80b0f5b5cd359498dcbd3af7dcb6194afa4582d8efb3faa38d28675ee45e0748
-test-int/mcp/test_read_content_integration.py,test_read_content_integration.py,source_code,11187,2025-07-08T20:39:18.348233,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),6955dd343b40df088ac79175e52723501d83796335a16e43b7f58e16e757e1b8
-test-int/mcp/test_read_note_integration.py,test_read_note_integration.py,source_code,1381,2025-07-08T20:39:18.348463,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),b93050da68d0e9d47d46879a386567f688399e28390f4eb31ee37353dc27514b
-test-int/mcp/test_search_integration.py,test_search_integration.py,source_code,14690,2025-07-08T20:39:18.348959,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),e0957ada9dd9b12eae5843a37d241ec9293ca929f18281e31197dae36bff589d
-test-int/mcp/test_write_note_integration.py,test_write_note_integration.py,source_code,9472,2025-07-08T20:39:18.349398,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),b2b56fee8351168d0c65640c295d969dc4575d9bea87927b2dc07e591cabdff3
-tests/Non-MarkdownFileSupport.pdf,Non-MarkdownFileSupport.pdf,other,106751,2025-02-23T17:31:23.206428,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),4aa96f9d0ee830ef6a1ec92243f302bbe2fa8971b84945f4eb5e276bf1ffde96
-tests/Screenshot.png,Screenshot.png,other,190076,2025-02-23T17:31:23.207771,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),dd82612fe013c39810d28ae0f2bbcca6ab2c9925b035d7720bb02493ddf5d0a9
-tests/__init__.py,__init__.py,source_code,141,2025-06-21T00:01:46.216456,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),2ac5605e69ad8829e96b3689632536539f1cdd3149a29c1903f25af0793a5d65
-tests/api/conftest.py,conftest.py,source_code,1404,2025-06-21T00:01:46.359728,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),ea46cde47a37c1f43fe079e48f5d0de8007155a0187f4445abc4f2ffde9c1791
-tests/api/test_async_client.py,test_async_client.py,source_code,1382,2025-07-30T09:39:45.725666,jope-bm,2,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com),a2f96226a75e5cff2326ca48ddccea4915964d83e529f7b99958bc233ccdc31a
-tests/api/test_continue_conversation_template.py,test_continue_conversation_template.py,source_code,5152,2025-06-21T00:01:46.390901,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),cca08b0291db0ad693c60d8dc203660021feab46d9eb530be7f67e0ebb52c1d3
-tests/api/test_directory_router.py,test_directory_router.py,source_code,9376,2025-06-21T00:01:46.356659,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),428626589f0010512481ba495368b0bf2b9617b22764e588eaa3562e86da4d37
-tests/api/test_importer_router.py,test_importer_router.py,source_code,16578,2025-06-21T00:01:46.368070,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),03edf6e7404c7350afe76e54ea2bf0d66f668bcdb49f59702067a67b3694309d
-tests/api/test_knowledge_router.py,test_knowledge_router.py,source_code,45771,2025-07-01T08:33:22.090490,Paul Hernandez,3,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),43a5f91ae1fb9038e65c09701336fbdc4dbf40c8319c94727e6312fda9d6d56e
-tests/api/test_management_router.py,test_management_router.py,source_code,6220,2025-06-21T00:01:46.402764,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),f6a3f41f263f10c08281525571e2e39fc9ae818ebb7e9895e3f3f3115ea05677
-tests/api/test_memory_router.py,test_memory_router.py,source_code,5555,2025-06-21T00:01:46.399667,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (phernandez@basicmachines.co),2b8782015c893081fc67b7f13a7255d4e3dc45b27705a524f94918a339e2d486
-tests/api/test_project_router.py,test_project_router.py,source_code,13288,2025-07-30T09:39:45.725847,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),af85d0870069d3831a9214372853994e5d12dc910e37298eb9958f72f6a8bb31
-tests/api/test_project_router_operations.py,test_project_router_operations.py,source_code,1812,2025-06-21T00:01:46.381705,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),afd40879de3d7c508cca0feeae3cb7a8f3afcfbb06f59a6104189b1e3291376a
-tests/api/test_prompt_router.py,test_prompt_router.py,source_code,5046,2025-06-21T00:01:46.396588,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),9115995b7dd8b44d8a9c06c5e1bbb177618286675a769889e35ac16f26fd9897
-tests/api/test_resource_router.py,test_resource_router.py,source_code,13960,2025-06-21T00:01:46.384919,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),ad3cb2cabaeab82a7e64253ceede7c1791e2bd70c92f60bc5f3be939292ca22d
-tests/api/test_search_router.py,test_search_router.py,source_code,6409,2025-06-21T00:01:46.375427,bm-claudeai (AI Assistant),3,bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com); Paul Hernandez (phernandez@basicmachines.co),ba3e3809795e72db9dd9c8c729048bdbbbdb897c2a5aa8b175112b5d4b56d152
-tests/api/test_search_template.py,test_search_template.py,source_code,5258,2025-06-21T00:01:46.378721,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),8f0d16a1de947d0466d96afed02e695f7648adac70b9ba99753250068207a686
-tests/api/test_template_loader.py,test_template_loader.py,source_code,8035,2025-06-21T00:01:46.406694,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),4fd7c6c4862cc0d877d29244ecdc0b52a0693fc4574a9667663bee36bfd36b62
-tests/api/test_template_loader_helpers.py,test_template_loader_helpers.py,source_code,7445,2025-06-21T00:01:46.372114,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),8dd35f11c9b3f2d96ac36263edf4430308728c04c9da543b1cb845b96ab20aa7
-tests/cli/conftest.py,conftest.py,source_code,1185,2025-07-01T08:33:22.090848,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),c3c73da7ad73224931e1fba4ebd70792221be607bfb1488bb5c9420bba03bdb8
-tests/cli/test_cli_tools.py,test_cli_tools.py,source_code,13528,2025-06-21T00:01:46.318964,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),befb8cab50132e26a1b13b82ce8e93a3258282cf157a4230214bfcefeae65102
-tests/cli/test_import_chatgpt.py,test_import_chatgpt.py,source_code,6719,2025-07-08T20:39:18.350234,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),df447335545248e2fb2417af33f8cc2f0143bd413a1783e41f89605de305b7c8
-tests/cli/test_import_claude_conversations.py,test_import_claude_conversations.py,legal,5028,2025-07-08T20:39:18.350607,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),ac4b3b9dfc331fa7fa32a2941c027ff8b6585a94a5ccfaaf0a4affe5cf19c00c
-tests/cli/test_import_claude_projects.py,test_import_claude_projects.py,legal,4585,2025-07-08T20:39:18.350885,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),7eaab3d491d50ca59c8ba015ecd5740a5feae94d970ee17559c6df9d8558c2cc
-tests/cli/test_import_memory_json.py,test_import_memory_json.py,source_code,4891,2025-07-30T09:39:45.726290,jope-bm,3,jope-bm (joe@basicmemory.com); bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (60959+phernandez@users.noreply.github.com),d6734ce059dacf97bc764d848b2e2a6ba52fa96871bc331ec9d2ddc60b766bb6
-tests/cli/test_project_commands.py,test_project_commands.py,source_code,6578,2025-07-30T09:39:45.726703,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),51e2ac7ff44b0d1a1db6da406c5c2e6aebceb1b63a1e8d5ab51bbaa834507157
-tests/cli/test_project_info.py,test_project_info.py,source_code,3874,2025-07-01T08:33:22.091600,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),0b08950e95a5f276f14c56f6fe99af4d41b8f04548e9b7746f807c5ac4155578
-tests/cli/test_status.py,test_status.py,source_code,4160,2025-07-01T08:33:22.091978,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),a1ff89fdac4bf57ba03be92ac79b8ca3210af0b1132d5a2bd0fc0c253fcbf988
-tests/cli/test_sync.py,test_sync.py,source_code,3864,2025-07-08T20:43:47.816788,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),77e0f6b42b584a5acfda3c2ff194ff5e71ca57a40cb4484d563f5482bbbb4c0f
-tests/cli/test_version.py,test_version.py,source_code,289,2025-06-21T00:01:46.305368,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),db95665178a32d391bd83011d073db269cefba9da8a4dc4d3e392d47bc0e0a8f
-tests/conftest.py,conftest.py,source_code,15286,2025-07-08T20:39:18.351368,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),c6f38f103ce58144ffe4562f0c47dad849974e96327f02805e854447e19bc411
-tests/importers/test_importer_base.py,test_importer_base.py,source_code,4329,2025-07-08T20:39:00.549594,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),da872a073f2b90fda3c98c9f44cf45884f4f682d91ec1b1f931d42c34eee1939
-tests/importers/test_importer_utils.py,test_importer_utils.py,source_code,1827,2025-06-21T00:01:46.184343,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),cbee630c855ceb1de764ac0cdb1d5d781c16cd3a934d67166adc235c98f363d7
-tests/markdown/__init__.py,__init__.py,source_code,0,2025-06-21T00:01:46.196570,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
-tests/markdown/test_entity_parser.py,test_entity_parser.py,source_code,8669,2025-06-21T00:01:46.206579,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),496fdab6fe164634f8223f827585a4c0dedd30ccea7b0b69dc79004ad0996de2
-tests/markdown/test_markdown_plugins.py,test_markdown_plugins.py,source_code,5139,2025-06-21T00:01:46.200759,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),9624d73462aadcd47fb0edd0d87880959a8982eecfa39529f21e3b292c34cb83
-tests/markdown/test_markdown_processor.py,test_markdown_processor.py,source_code,5728,2025-06-21T00:01:46.194175,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),35042aa57dd2aeed848c624aa7f69decfb18e83c3b217eca1fdacfc4a10831db
-tests/markdown/test_observation_edge_cases.py,test_observation_edge_cases.py,source_code,4295,2025-06-21T00:01:46.209598,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),6f1ab7684bfa8b02af0e0c42b3d7aed91fcd0b1c6288cbc9b6d6943c166979fa
-tests/markdown/test_parser_edge_cases.py,test_parser_edge_cases.py,source_code,5142,2025-06-21T00:01:46.213291,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),d511d7d1187e3c1d3a8d3e0ab9efc9e68e84115c46811e7a9dc21eca9a87d520
-tests/markdown/test_relation_edge_cases.py,test_relation_edge_cases.py,source_code,3952,2025-06-21T00:01:46.203846,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),f8e2016308f84139342cc37ec6e389ffe52d7eb46f998ee327c7f0d5bba3ad9b
-tests/markdown/test_task_detection.py,test_task_detection.py,source_code,401,2025-06-21T00:01:46.191444,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),37fe91a689742033a0eb76723557e31c2a85e591133383b3887572cb714db2a5
-tests/mcp/conftest.py,conftest.py,source_code,1761,2025-07-08T20:39:18.351554,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),350b2ca42c52ef76e002deddb65fc0eccb9f8989bd26078ea1c100e3b93bae3f
-tests/mcp/test_prompts.py,test_prompts.py,source_code,5989,2025-07-01T08:33:22.093691,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),e3b2ee5b4bc120b5043225ebdbf73eadd71be9c3d9d8e1fdd66a24a8ff11a780
-tests/mcp/test_resource_project_info.py,test_resource_project_info.py,source_code,4885,2025-07-01T08:33:22.094085,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),6a043736789b239c8d4ae00d1a5332a0fc3bed4038fe3388970ba97dc7431a93
-tests/mcp/test_resources.py,test_resources.py,source_code,549,2025-07-01T08:33:22.094481,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),77a6396b9b8a9d3b3d202e438243ca6178d87fd7680c9fc063ee013f2042aa4c
-tests/mcp/test_tool_build_context.py,test_tool_build_context.py,source_code,3714,2025-07-01T08:33:22.094661,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),5f0a39fdb652605335ed54aa91fe994262441bb7ba46f381c46ebca882fc23f2
-tests/mcp/test_tool_canvas.py,test_tool_canvas.py,source_code,7997,2025-07-01T08:33:22.094982,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),c517bb1f9edc77b76fbeb483dfcb2dd57de9f0b80a10738708bc90cbe388dc9e
-tests/mcp/test_tool_delete_note.py,test_tool_delete_note.py,source_code,4208,2025-07-01T08:33:22.095578,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),4cbf3ba4313438651b0608d5b25faf1400f7bd6a78af630351aecd4457800895
-tests/mcp/test_tool_edit_note.py,test_tool_edit_note.py,source_code,13503,2025-07-03T18:43:10.084890,Drew Cain,2,Drew Cain (groksrc@gmail.com); Paul Hernandez (60959+phernandez@users.noreply.github.com),dd441969aa54b3739f2d9202d3feaf46aee807ec51e01a13ef41eda52743944f
-tests/mcp/test_tool_list_directory.py,test_tool_list_directory.py,source_code,7730,2025-07-01T08:33:22.096737,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),cfbb5c06bcfe74ea60f31051eb9b03ac80b86232b053c188bf3b172132f7c0f5
-tests/mcp/test_tool_move_note.py,test_tool_move_note.py,source_code,25851,2025-07-30T09:39:45.727347,jope-bm,2,jope-bm (joe@basicmemory.com); Paul Hernandez (paul@basicmachines.co),c9f95158503fa42e37532aaa35027538fa49cea718d059d570cf547d31f01043
-tests/mcp/test_tool_read_content.py,test_tool_read_content.py,source_code,19442,2025-07-30T09:39:45.727526,jope-bm,1,jope-bm (joe@basicmemory.com),1817e32f997b06dbdabf02864d0c70584c1cd80bf1fae8dfbef649de79434bc5
-tests/mcp/test_tool_read_note.py,test_tool_read_note.py,source_code,22991,2025-07-30T09:39:45.727746,jope-bm,4,jope-bm (joe@basicmemory.com); Paul Hernandez (paul@basicmachines.co); Amadeusz Wieczorek (git@amadeusw.com); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),4e13ea9ff977525aa62b6a8c22505ffe989329dc3e7d07b71e044cf43ef3ddfd
-tests/mcp/test_tool_recent_activity.py,test_tool_recent_activity.py,source_code,3983,2025-07-01T08:33:22.098561,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),45414152cd45334b84df56f653146b7bd2939907548e7245a37207fdccfc4c87
-tests/mcp/test_tool_resource.py,test_tool_resource.py,source_code,6782,2025-07-01T08:33:22.098948,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),3916ae1c4d458eee53d2c570b9bbb708ecd617de5a145c3a7552389954bc9195
-tests/mcp/test_tool_search.py,test_tool_search.py,source_code,10959,2025-07-03T18:43:10.085177,Drew Cain,3,Drew Cain (groksrc@gmail.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),07839cf8e89d74ba05ec1dc55fa842444c1f0cc3d1587823b0ac3458ad89e87c
-tests/mcp/test_tool_sync_status.py,test_tool_sync_status.py,source_code,6331,2025-07-01T08:33:22.100021,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),3f3566df5b9f3c66bb9b3bd77d4c05825480d0e85015305cb1b7ab9429c7a7ec
-tests/mcp/test_tool_utils.py,test_tool_utils.py,source_code,9228,2025-07-01T08:33:22.100561,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),b50789f7a78b0169f52dc8bd16e262510ed4a0ac130fce698d4be84af1fe2d31
-tests/mcp/test_tool_view_note.py,test_tool_view_note.py,source_code,10004,2025-07-01T08:33:22.101164,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),385535ce791c3ab55db827cbcf27ea25ae85faf3a027f52df4eea052cede7f36
-tests/mcp/test_tool_write_note.py,test_tool_write_note.py,source_code,35136,2025-07-30T09:39:45.728137,jope-bm,3,jope-bm (joe@basicmemory.com); Drew Cain (groksrc@users.noreply.github.com); Paul Hernandez (60959+phernandez@users.noreply.github.com),45172de20cfc4f4436287573b4f5a94b8b616a360647af67ba1c6c343ccd41b8
-tests/repository/test_entity_repository.py,test_entity_repository.py,source_code,15498,2025-06-21T00:01:46.176265,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),8f5d1ff6cff7b640993ff73f463b1e7801a4dd69640fc55fa23dc58b865e9943
-tests/repository/test_entity_repository_upsert.py,test_entity_repository_upsert.py,source_code,16983,2025-07-03T18:43:10.085482,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); Drew Cain (groksrc@users.noreply.github.com),ee0ecd6f4ff8b31838bd6de6fb1018af437e02813d8315c06f4e20a6b78a0572
-tests/repository/test_observation_repository.py,test_observation_repository.py,source_code,11786,2025-06-21T00:01:46.158862,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (phernandez@basicmachines.co),3006d392ad94dcc9b3ae031d63a1af6935624534389dd025de70d4c9e112aa0b
-tests/repository/test_project_info_repository.py,test_project_info_repository.py,source_code,1186,2025-06-21T00:01:46.161876,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),dbce7ae7350403cbc37343c2e3e68e4d2255e247006aaa6c495a7ce8bfddea7d
-tests/repository/test_project_repository.py,test_project_repository.py,source_code,10511,2025-07-30T09:39:45.728536,jope-bm,2,jope-bm (joe@basicmemory.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),279a3324635b1b515c18003bd1875cf230fef1192cadef9ca426846783717e75
-tests/repository/test_relation_repository.py,test_relation_repository.py,source_code,11980,2025-06-21T00:01:46.167567,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (phernandez@basicmachines.co),fcdbdf40f7b56145b98eedde5ead64ef6187e859adde48cc09f5a97754757428
-tests/repository/test_repository.py,test_repository.py,source_code,5996,2025-06-21T00:01:46.152691,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),3a6d4ca0b7a438a30ae504f5eac22874d4e1a937a4246e90efad46c90f0e1c95
-tests/repository/test_search_repository.py,test_search_repository.py,source_code,25471,2025-07-03T18:43:10.086041,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),805b5cc55a53ae9d6e86c0de735c7f38ac9fd92c23194b0150fa3e7f5507a146
-tests/schemas/test_memory_url.py,test_memory_url.py,source_code,2000,2025-06-21T00:01:46.346515,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),946fa6c48534f41c8b9cc27bbad164d3e3673a79afa84fbb439fae4cd26c504b
-tests/schemas/test_memory_url_validation.py,test_memory_url_validation.py,source_code,9338,2025-07-01T08:33:22.103247,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),7054c3a3cdb8e05d2ffd254ed298908ff3d48a0a3927d960975eae1ab9beeb38
-tests/schemas/test_schemas.py,test_schemas.py,source_code,16880,2025-07-03T18:43:10.086337,Drew Cain,3,Drew Cain (groksrc@gmail.com); Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),2c746a00c340f063c160ace67569955a300a294040949695c79fd4ae124fb611
-tests/schemas/test_search.py,test_search.py,source_code,3264,2025-06-21T00:01:46.343685,github-actions[bot] (AI Assistant),2,github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com); Paul Hernandez (60959+phernandez@users.noreply.github.com),7437775d1b4a61a438cbabe3dbb1becd2adc4dbcc0c24595830c0843fa7a3166
-tests/services/test_context_service.py,test_context_service.py,source_code,8833,2025-06-21T00:01:46.446200,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),ab49d21a05d5364e7e8a2f00b07aabe1109b7417698e0acd92792e2cb5f22732
-tests/services/test_directory_service.py,test_directory_service.py,source_code,6854,2025-06-21T00:01:46.457258,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),a0c765fb6bd1a75b6ba4592b1df344c48273b6ab03ba6bd15d2b5e840eb2d521
-tests/services/test_entity_service.py,test_entity_service.py,source_code,59278,2025-07-03T18:43:10.086674,Paul Hernandez,3,Paul Hernandez (paul@basicmachines.co); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),d7d495756faa10b415d705cf26b69d2efbc5f190a834b6767386ff296629ea71
-tests/services/test_file_service.py,test_file_service.py,source_code,5243,2025-06-21T00:01:46.460141,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),83e6e9a7584b7baeccbc84865d8c1d3e2a0223e7d2b9c066d3799c289196ab7d
-tests/services/test_initialization.py,test_initialization.py,source_code,6939,2025-07-08T20:39:18.351946,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),ebb8d11ff37dcb36c4844c68f873c8e0e8aa6ab1b82abb22ee96c4233e6ab287
-tests/services/test_link_resolver.py,test_link_resolver.py,source_code,13618,2025-07-01T08:33:22.105766,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),c9fc56d0c3572770e95ca6175c213ed8b44c2a6ddddc298b5662cc2d8f41014e
-tests/services/test_project_service.py,test_project_service.py,source_code,28152,2025-07-30T09:39:45.728920,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),430868ed796518937a3b0bed4d8c33be53264a6100d61d54b0745bb2b58bf29a
-tests/services/test_project_service_operations.py,test_project_service_operations.py,source_code,4679,2025-06-21T00:01:46.442141,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),d4103b6c5fff7e74ba84b86033537b8522aa60fc75aec4974d52e1dfec68b1b4
-tests/services/test_search_service.py,test_search_service.py,source_code,25299,2025-06-21T00:01:46.439133,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),b3e58258db2b727ab8a1792e52fcb038d3a0779bcd1b70f2d295a9d06e5e2513
-tests/services/test_sync_status_service.py,test_sync_status_service.py,source_code,9926,2025-07-03T18:43:10.087266,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),00245ca356e33fc7afcd2d42cb5ec082038c95383d738067821cf1e8d23c9a4b
-tests/sync/test_sync_service.py,test_sync_service.py,source_code,39659,2025-07-01T08:33:22.107088,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),0609aee9906549f27fc4289b5ac2d46a50e53e12a0615a2701f17fbe9a74e169
-tests/sync/test_sync_wikilink_issue.py,test_sync_wikilink_issue.py,source_code,1959,2025-06-21T00:01:46.420370,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),db4b98dd7008a1a26b0fd02b9a2d03bca950b281efc19d98a91b017c500b23a5
-tests/sync/test_tmp_files.py,test_tmp_files.py,source_code,5930,2025-06-21T00:01:46.424277,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),cead95a07b29f6c1ab933abe67f9648122f5f33d33753c8e4ab4934af96cbc25
-tests/sync/test_watch_service.py,test_watch_service.py,source_code,14076,2025-06-26T09:28:51.860679,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),e324a4127f8bfe59798f3a08125488c701e88239b7482d87a0394b91c55b893e
-tests/sync/test_watch_service_edge_cases.py,test_watch_service_edge_cases.py,source_code,2169,2025-06-21T00:01:46.409830,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),b87c5015330e9b551630aab7ef95ac1e7663f0ce46e912d8155b319e139559aa
-tests/test_config.py,test_config.py,source_code,3680,2025-07-03T18:43:10.087558,Paul Hernandez,3,Paul Hernandez (paul@basicmachines.co); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),6a246431cff739274efda895dfa28f38710289a73e645312f5fa05fce0885ec8
-tests/test_db_migration_deduplication.py,test_db_migration_deduplication.py,source_code,6166,2025-07-08T20:39:18.352690,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com),ab768e061531ca2edcd598c101b5d884e549f90c7a4b305a23713a199d263fbb
-tests/utils/test_file_utils.py,test_file_utils.py,source_code,6199,2025-06-21T00:01:46.219673,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),4615bb20b92b8a79d9e086301f852b34c3360f17ecc209920d68528268ddeed4
-tests/utils/test_parse_tags.py,test_parse_tags.py,source_code,1691,2025-06-21T00:01:46.223400,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),b83afdf18dac8b3411bd0fab1301683217d3d1abceaf2d22c09e79c709efd8eb
-tests/utils/test_permalink_formatting.py,test_permalink_formatting.py,source_code,4193,2025-06-21T00:01:46.225738,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),d998a4ca846c78679728a918b6f71df67c30b6961ede3cffa609f2cf6ad160eb
-tests/utils/test_utf8_handling.py,test_utf8_handling.py,source_code,5791,2025-06-21T00:01:46.228483,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),50ec792e572af51cd2d996d4ddacbcfd3bbd79aa928818a90c42117451ea829f
-tests/utils/test_validate_project_path.py,test_validate_project_path.py,source_code,15346,2025-07-30T09:39:45.729224,jope-bm,1,jope-bm (joe@basicmemory.com),27a4bf2a9d277e6cd773619e5241b20175d211ec60c284361bec404fd99143f3
-uv.lock,uv.lock,other,232710,2025-07-30T09:39:36.619155,Paul Hernandez,3,Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),caa1e3f6e66464b884a78cab77df2fe303fa3c0dc573be0196474b6d3c150581

legal_inventory_main/basic_memory_inventory_20250730_094006.csv

@@ -1,272 +0,0 @@
-path,name,category,size_bytes,modified_time,primary_author,contributor_count,contributors_list,sha256_hash
-.claude/commands/release/beta.md,beta.md,documentation,3103,2025-07-01T08:33:22.037438,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),345f06e3f304470a8892e96979355919c8e5d8f4212ebbe543c3272fd15a5cbe
-.claude/commands/release/changelog.md,changelog.md,documentation,4648,2025-07-03T18:43:10.075727,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),ea2484352f4f881aa71f546dcf84b0882d60c96673a88406aa2f7e12a282a1f4
-.claude/commands/release/release-check.md,release-check.md,documentation,3344,2025-07-01T08:33:22.040060,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),7dd41a40e95c89153936c4ea60a3c989eccd5973fff9f6caef156de82f12bd04
-.claude/commands/release/release.md,release.md,documentation,2925,2025-07-01T08:33:22.043674,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),0e4afd788fcf85fbe46094452e9b92a4290c3e23702283e72ee56aa9288476e5
-.claude/commands/test-live.md,test-live.md,documentation,18720,2025-07-03T18:43:10.076403,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),21a9edeefb3e5673d833151a2fd0464087c0f0a9d056fdd7fca474c1d177d6fc
-.dockerignore,.dockerignore,other,623,2025-07-01T08:33:22.048301,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),b3079bffad89d07186c9166725075524ffc07ceea6dc1d53fdbea6dca9585684
-.github/ISSUE_TEMPLATE/bug_report.md,bug_report.md,documentation,967,2025-03-01T14:22:50.968994,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),0d34443ddda84a5e9726c8268083c9646d2cc64ff9c5ebf56c89587cef4c7706
-.github/ISSUE_TEMPLATE/config.yml,config.yml,configuration,374,2025-03-01T14:23:26.936836,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),f4e21bb9b7f053509b6c08548a2649a5d62f44f0106810aa8c915d2f29acc623
-.github/ISSUE_TEMPLATE/documentation.md,documentation.md,documentation,557,2025-03-01T14:23:40.020117,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),78f80a6b9a2b954695f74a847a068e0b780da6020572401c13c931555a4a9db5
-.github/ISSUE_TEMPLATE/feature_request.md,feature_request.md,documentation,786,2025-03-01T14:23:06.344081,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),cee834de442221d53f3d2eeb85b81f3a641b3a7cb587ef8a169452305007439d
-.github/dependabot.yml,dependabot.yml,configuration,529,2025-03-15T10:40:16.936258,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),8c6c2ef9a1417da63adb49c70f45524129bd5c46bbd7452b6b97cfe65205f89d
-.github/workflows/claude.yml,claude.yml,legal,4628,2025-07-03T18:43:10.076958,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),d026f1756310781b85abc491b454cc31b52dfce4b951cdf8a4a555b6b047604c
-.github/workflows/dev-release.yml,dev-release.yml,configuration,1405,2025-06-03T08:31:42.915367,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),58bcfc9e11e210e02dee76aabe7d1378da4edafb7f61857049ee6ccee9d45ffa
-.github/workflows/docker.yml,docker.yml,configuration,1621,2025-07-01T08:33:22.049870,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),c918a86f2b16ebb45182a73c45272bcd6cea7022cc6e0eaeb2b2a24d8eebfe4d
-.github/workflows/pr-title.yml,pr-title.yml,configuration,887,2025-02-17T16:29:35.733646,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),b6df62a20235496feba4d9419c85d6e8446c4d447ad69e7f57b51cc8953f68f4
-.github/workflows/release.yml,release.yml,configuration,2479,2025-07-03T18:43:10.077261,Drew Cain,2,Drew Cain (groksrc@gmail.com); Paul Hernandez (paul@basicmachines.co),163307a99e2f3d317af6ae8927e1537654d88bf574a6958ac0bcd2d4de266b2a
-.github/workflows/test.yml,test.yml,configuration,1426,2025-07-01T08:33:22.054430,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),ab09084a11be8adfc83fc6285c652fbe44a4584aa7d7d3658fcf0c57112d1640
-.gitignore,.gitignore,other,566,2025-07-01T08:33:22.055006,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),358658b0faa8c3145e539421deba4ad0bac4a8ea2e608b2c2f867a822c67b36f
-.python-version,.python-version,other,5,2024-12-02T16:41:37.012830,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),7b55f8e67b5623c4bef3fa691288da9437d79d3aba156de48d481db32ac7d16d
-CHANGELOG.md,CHANGELOG.md,documentation,53647,2025-07-06T10:34:45.550847,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); semantic-release (semantic-release),0b165eb18975ff253cde08f4687b7808ac6ce63b6d8c10912c495a76c9058d1a
-CITATION.cff,CITATION.cff,other,302,2025-02-17T16:29:35.735146,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),bc4878cf6f80bb64655f3f93a5821ffe0924ad8311c784b5f81a36093fcffdda
-CLA.md,CLA.md,legal,1342,2025-03-01T14:12:38.435132,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),c238c7ff4f2b8451c6bba1bbacd10b04fb7d41d9a9cd76a62644d8193791d169
-CLAUDE.md,CLAUDE.md,legal,12310,2025-07-03T18:43:10.078147,Drew Cain,4,Drew Cain (groksrc@gmail.com); Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co); Ikko Eltociear Ashimine (eltociear@gmail.com),751f10c1a9a9c0ba2054d9c9cd36cf0989d6a347491fd505bb6504ee74b12900
-CODE_OF_CONDUCT.md,CODE_OF_CONDUCT.md,documentation,509,2025-02-17T16:29:35.735238,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),b276b464e85eb1e5d9f09d90bba9573508a7bf81d2eeb38d0f25bd9f2fa66198
-CONTRIBUTING.md,CONTRIBUTING.md,documentation,7329,2025-07-30T09:39:36.607158,jope-bm,2,jope-bm (joe@basicmemory.com); Paul Hernandez (paul@basicmachines.co),ca822fe39cc529bfc3822d317ab8a20fd141ec3ecb8c20de9e2eca3edce1c282
-Dockerfile,Dockerfile,other,856,2025-07-01T08:33:22.056908,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),c45501905423990e31ffdb8ae4e976eca6423c6784905c1036bcc7795b70feef
-LICENSE,LICENSE,legal,34523,2024-12-02T16:41:20.739392,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),8486a10c4393cee1c25392769ddd3b2d6c242d6ec7928e1414efff7dfb2f07ef
-README.md,README.md,documentation,16261,2025-07-03T18:43:10.078281,Drew Cain,6,Drew Cain (groksrc@users.noreply.github.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); Jason Noble (github+jasonn@jasonnoble.org); Marc Baiza (43151891+mbaiza27@users.noreply.github.com); Matias Forbord (codeluggage@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),2c4b82b30f49ab465617034fda999157450ed168f8e097fe8e9ca7ac65a197a7
-SECURITY.md,SECURITY.md,documentation,303,2025-03-12T16:04:01.989927,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),96932268b8fe737577941b49e9dff5ff8ad59c11cc3f9a016989589ef5c98c1f
-docker-compose.yml,docker-compose.yml,configuration,2534,2025-07-01T08:33:22.059281,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),4a9fdfd2f0d42b148fe021eee77fd5e772c7ba9c2fe5d0cc310c8c7a64257417
-docs/AI Assistant Guide.md,AI Assistant Guide.md,documentation,16423,2025-07-01T08:33:22.060491,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),c717869a3d356852077026591364ecb0589a6d53f9764af027c57d142ea7ff55
-docs/Docker.md,Docker.md,documentation,9088,2025-07-01T08:33:22.060976,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),e13d3f50148353046b52d9d493986880f76f2914ef4efe1a759b2cc9d10913a4
-justfile,justfile,other,5496,2025-07-30T09:39:36.608008,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com),a8df6c73ee8cf3eaa48e4cba193dffbc2821b843a8cc0c0cd58b8517f2252907
-llms-install.md,llms-install.md,documentation,2307,2025-06-29T14:19:28.826375,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),674105eb85c8f1d59fc2ddc6840f2a2a3e293358687a305c37dffc8144304f97
-memory.json,memory.json,configuration,90075,2025-06-29T14:19:28.827172,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),22d5eee995ca0548b7d9dd152f9a3690c42a514cbf38fea750b3ed2a17dd99c5
-pyproject.toml,pyproject.toml,configuration,3279,2025-07-30T09:39:36.608791,Paul Hernandez,4,Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co); semantic-release (semantic-release),428a5d64d4555dc7cd2a81b89a3444bdb1d2f3017257fbc9160bd0ae982718e1
-smithery.yaml,smithery.yaml,configuration,433,2025-03-11T16:36:03.389716,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),63f13499cf4fee0751b5005f5bd85597dc1c7f9a881f4ec8147cc23e95e75c2d
-src/basic_memory/__init__.py,__init__.py,source_code,256,2025-07-06T10:34:45.551291,Paul Hernandez,3,Paul Hernandez (paul@basicmachines.co); Drew Cain (groksrc@gmail.com); semantic-release (semantic-release),c946490ab9d64957d25df37f721392024916f8a81ed838f70a8e938b1c2637db
-src/basic_memory/alembic/alembic.ini,alembic.ini,configuration,3733,2025-02-23T17:31:23.198433,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),20466c9c5f026db66793006bebb2f328a3686c7bb34da40d52f33c3eca29e717
-src/basic_memory/alembic/env.py,env.py,source_code,2838,2025-07-08T20:39:18.336650,Paul Hernandez,3,Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),e241d987eadfcd5011cbd9ddbecb833d306de87937759d81c08d37d04a6906b0
-src/basic_memory/alembic/migrations.py,migrations.py,source_code,718,2025-06-21T00:01:59.613806,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),96b8873d70dd04b48d5c45b7413a54d1224ab9577557ef0dad5929377a9fb144
-src/basic_memory/alembic/script.py.mako,script.py.mako,other,635,2025-02-17T16:29:35.739659,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),304a8bfb6a804e5493f5300e79882c70c9f5bb2e87512f4d16f0e097dddd323f
-src/basic_memory/alembic/versions/3dae7c7b1564_initial_schema.py,3dae7c7b1564_initial_schema.py,source_code,4363,2025-06-21T00:01:59.595762,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),9536d69409ddd5eb3bc54f7d0e82607da45ed7f2ad7bc4cbf7cae2a9e28657cd
-src/basic_memory/alembic/versions/502b60eaa905_remove_required_from_entity_permalink.py,502b60eaa905_remove_required_from_entity_permalink.py,source_code,1840,2025-06-21T00:01:59.604717,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),93ac584e660f33d468b3eec203b070641298c282bf82655d0beda7f050237681
-src/basic_memory/alembic/versions/5fe1ab1ccebe_add_projects_table.py,5fe1ab1ccebe_add_projects_table.py,source_code,4379,2025-06-21T00:01:59.601299,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),d82098f5aca3cdbada60c7229ea4ac262f527349eed9ef9e864509bacfaccf7e
-src/basic_memory/alembic/versions/647e7a75e2cd_project_constraint_fix.py,647e7a75e2cd_project_constraint_fix.py,source_code,4210,2025-07-01T08:33:22.063463,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),604ac5908a5976272f52297866d13abb14a99390590935d9fd37cf13e32049fa
-src/basic_memory/alembic/versions/b3c3938bacdb_relation_to_name_unique_index.py,b3c3938bacdb_relation_to_name_unique_index.py,source_code,1428,2025-06-21T00:01:59.598551,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),46c1b2990cdf4575752d234a8b28b494c8a54f15b5360c12f6347aef27b66a92
-src/basic_memory/alembic/versions/cc7172b46608_update_search_index_schema.py,cc7172b46608_update_search_index_schema.py,source_code,3679,2025-06-21T00:01:59.610909,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),9036af47d42ac7dc12bb93f7a9de1266aff0688b031b550c4e0d92983a24b4c5
-src/basic_memory/api/__init__.py,__init__.py,source_code,72,2025-06-21T00:01:59.579981,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),c02a63fb6d63d43d0acca97d425eae9cb055158d0ad6e1a9fc57926512adaa99
-src/basic_memory/api/app.py,app.py,source_code,2897,2025-07-08T20:39:18.337081,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),ad673ac2c09410af5830f6afdffaa28b0040480dacd52ff01750b8b2c066e8cf
-src/basic_memory/api/routers/__init__.py,__init__.py,source_code,398,2025-06-21T00:01:59.549416,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (60959+phernandez@users.noreply.github.com),4443b908a43dea8e6fb4658009cb08c48a56c9b21449e29773cdd159b59cf014
-src/basic_memory/api/routers/directory_router.py,directory_router.py,source_code,2054,2025-06-21T00:01:59.567371,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),ac1407beec1f7d43a4d222af704b3642559c960bebf2eaf6e1ffe91f7fac5514
-src/basic_memory/api/routers/importer_router.py,importer_router.py,source_code,4513,2025-06-21T00:01:59.561600,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),c45502a2b90f5a8f00174c9ad14adc2e65cd7fc0a33d9740a9d750207f0f3bea
-src/basic_memory/api/routers/knowledge_router.py,knowledge_router.py,source_code,9738,2025-07-01T08:33:22.064119,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),e1d0ffb4fa5c246582ba844a11b417092de1a173567be55b7060bbc55fbc5681
-src/basic_memory/api/routers/management_router.py,management_router.py,source_code,2730,2025-07-08T20:39:18.337438,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),cdbce294dcec6146c56c4dae15744cdf77039fd21b23eef7cbc0b5f9bfb5f4ee
-src/basic_memory/api/routers/memory_router.py,memory_router.py,source_code,3003,2025-07-01T08:33:22.064510,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),6bd0a7c775e0c1290efb6001173237c0cdcfa0c1b1bb27c9145a7b35f1596a97
-src/basic_memory/api/routers/project_router.py,project_router.py,source_code,8444,2025-07-30T09:39:45.721369,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),6539c69f1d506c65d14cc2c151876b19057f37d84d51a9e6f464ed47a4692648
-src/basic_memory/api/routers/prompt_router.py,prompt_router.py,source_code,9948,2025-07-01T08:33:22.065221,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),e30c6aebe35112054933c37d0b462c3750005030fc9e44c23b35b2cd2a93485c
-src/basic_memory/api/routers/resource_router.py,resource_router.py,source_code,8058,2025-06-21T00:01:59.570399,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),584244a84698ff24ca8f9f94fab5b891740a51c25f972920c08ebf83f478d5c9
-src/basic_memory/api/routers/search_router.py,search_router.py,source_code,1226,2025-06-21T00:01:59.543020,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),183eb68e50904e22ff54db1d89b8be6f57fa1f8d0a096a3d497d8297b607e105
-src/basic_memory/api/routers/utils.py,utils.py,source_code,5159,2025-07-03T18:43:10.079143,Drew Cain,2,Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),9e60f57da24e1dc9d64236c26a7a2353003dc618a77fbeb853c494aa3357a57c
-src/basic_memory/api/template_loader.py,template_loader.py,source_code,8607,2025-06-21T00:01:59.576132,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),7b16d3797c89460c8b1664a335eae8c634fb5f60d6166d97e6a5156b776b6d83
-src/basic_memory/cli/__init__.py,__init__.py,source_code,33,2025-06-21T00:01:59.456735,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),6ab70a2c05910e13c3ef1e6df34325be265e633c076741998a0cb2dcd295a069
-src/basic_memory/cli/app.py,app.py,source_code,2268,2025-07-08T20:39:18.337708,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),f710670380d707c4458ad881f7a25bb3c5cdb2bcff59f139f37421264fe8f2f8
-src/basic_memory/cli/commands/__init__.py,__init__.py,source_code,393,2025-07-08T20:39:18.338070,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),de8a23702f98fb844fa9f7fdbedc16ce24ff4f8baf05589c2f4a521cd8a55645
-src/basic_memory/cli/commands/db.py,db.py,source_code,1480,2025-07-08T20:39:18.338326,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),704a1096d80ab9d12e247d029fe6223e935a0d0ceee7e615c020f46a720828e0
-src/basic_memory/cli/commands/import_chatgpt.py,import_chatgpt.py,source_code,2856,2025-07-08T20:39:18.338787,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),8957cca3acab6351335624a518bdc19d956487e93d86dd1b6c2309e9d5850ae5
-src/basic_memory/cli/commands/import_claude_conversations.py,import_claude_conversations.py,legal,2946,2025-07-08T20:39:18.339053,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),7bc97838732bf00f4fb4a80e3ba4fdfbce8971ae85cc2ac902c3b3a3e110ae57
-src/basic_memory/cli/commands/import_claude_projects.py,import_claude_projects.py,legal,2891,2025-07-08T20:39:18.339310,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),6321577075801c99ad47a0cdc13b5aa3c9ca102a05ca8f06ae2a51125a8c43bc
-src/basic_memory/cli/commands/import_memory_json.py,import_memory_json.py,source_code,3013,2025-07-30T09:39:45.721637,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),7ea193f6720b2672290ad16c79a143a31d88a1d567838f12b9ebf9110a7c0338
-src/basic_memory/cli/commands/mcp.py,mcp.py,source_code,2593,2025-07-08T20:39:18.340025,Paul Hernandez,3,Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),3e1be3d27b18ef4743204b7cf8a37fbc2a1a91fc1636c468e08cefcd8597bac6
-src/basic_memory/cli/commands/project.py,project.py,source_code,13836,2025-07-30T09:39:45.721838,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),af3e6f30410ab48355f4b1a46aaa3aa5423cb0a0490f51447db1d25e09f39916
-src/basic_memory/cli/commands/status.py,status.py,source_code,5809,2025-07-08T20:39:18.340324,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),b6d0ea237d714d054f69b24a2058beba74e224a2fa4a80a525d62a2aa2ea2d70
-src/basic_memory/cli/commands/sync.py,sync.py,source_code,8213,2025-07-08T20:39:18.340627,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),703b3e73c4c33850c27f6f4c07abbf5d4ce5dc43f706bf0c43264bbb45f8b213
-src/basic_memory/cli/commands/tool.py,tool.py,source_code,9540,2025-07-01T08:33:22.070903,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),9b2fa400b9f7921bf55b602f8bbdfa36b1ec7e4a5bc8fe7b9838b92e31f0a9ed
-src/basic_memory/cli/main.py,main.py,source_code,465,2025-07-08T20:39:18.340868,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),7a405b12bff98e319968526238ae15859df0362bba5a3857562fecca47b5c70d
-src/basic_memory/config.py,config.py,source_code,12487,2025-07-30T09:39:45.722031,jope-bm,5,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),86341330a041b94d38f5e4f1b94f3509d74351c67cc826af1a4ff57313e5f726
-src/basic_memory/db.py,db.py,source_code,7428,2025-07-08T20:39:18.341550,Paul Hernandez,3,Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),25e053b0b3f9e8fa823b05fc099001efe8a3a4f6e0f80728e5079ba45aa406d8
-src/basic_memory/deps.py,deps.py,source_code,12144,2025-07-08T20:39:18.341870,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),bce28cd9ca549b8afce0bc689cc1fb2dc80cd5b929f85114aa682bb8ae82411d
-src/basic_memory/file_utils.py,file_utils.py,source_code,6700,2025-06-21T00:01:59.587200,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),79ac5328b2c46d3232fcc6ff22ffc39ade085c0252ad91958be2a7ae9c9c8b71
-src/basic_memory/importers/__init__.py,__init__.py,source_code,795,2025-06-21T00:01:59.295471,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),0537015bdecfded85cb166b9c3db50b2f3aef329c70e0c36fbcb4f824099a21f
-src/basic_memory/importers/base.py,base.py,source_code,2531,2025-06-21T00:01:59.305335,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),6b0c1efd4f827f348834aa0cea2ae8eebbb842a2e5b1f5f3747ced0ef79b9f13
-src/basic_memory/importers/chatgpt_importer.py,chatgpt_importer.py,source_code,7372,2025-06-21T00:01:59.308956,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),dfa540b196ab23b5c4e6bfcac4da567873351cf7c78fa35f4c3b87e84c58e218
-src/basic_memory/importers/claude_conversations_importer.py,claude_conversations_importer.py,legal,5725,2025-06-21T00:01:59.288540,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),a7bc9e872f4f81ce5f79fe9dd1a6fd0f00a6f020a2cb2664184a97f14eeb1dbc
-src/basic_memory/importers/claude_projects_importer.py,claude_projects_importer.py,legal,5389,2025-06-21T00:01:59.291737,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),a452675fd9bb18ebf64eb4bd7f69ccd7e993b617931015a3c4ab700d67493863
-src/basic_memory/importers/memory_json_importer.py,memory_json_importer.py,source_code,4631,2025-07-30T09:39:45.722316,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),bc7d045299f17ed9ad5cebff7b1423250ec28a11130e47a0ac48d3ab82bdeafc
-src/basic_memory/importers/utils.py,utils.py,source_code,1792,2025-06-21T00:01:59.298428,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),ee7e22fd4812362394f62ed8944abe80738c1e3ab88131faf639f4a8ccfd6c89
-src/basic_memory/markdown/__init__.py,__init__.py,source_code,501,2025-06-21T00:01:59.316337,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),0ddce2a025ad0e729aab4e411d82e02ffefc15ac041cba4b5e7a7e90f4957c87
-src/basic_memory/markdown/entity_parser.py,entity_parser.py,source_code,4516,2025-06-21T00:01:59.321461,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),1b0d1177358645ccbadd170b3f62760dc9bd838d38c741978ab0da5836234d68
-src/basic_memory/markdown/markdown_processor.py,markdown_processor.py,source_code,4968,2025-06-21T00:01:59.325241,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),4b99f2ebdceed9d96a3bbb562682eba4b4b383c7a64080eaec3bbba25a4952c9
-src/basic_memory/markdown/plugins.py,plugins.py,source_code,6639,2025-06-21T00:01:59.312733,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),82d2332918e866ccaf06a2e954d9eb9b397f71b4d9e591a7f2472e5f1423464a
-src/basic_memory/markdown/schemas.py,schemas.py,source_code,1896,2025-06-21T00:01:59.329982,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),7b2c580abd615725a62267257b46ac13922dfc30fa01192a681658bb528ae67e
-src/basic_memory/markdown/utils.py,utils.py,source_code,3410,2025-07-03T18:43:10.079889,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),1b757f0d06e60e3ea276c0b2ea44fe1a156a895e093c1e607d6286e702bf4ae4
-src/basic_memory/mcp/__init__.py,__init__.py,source_code,35,2025-06-21T00:01:59.404757,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),76c0ce84aaa361e21b0942db1c8c5f708b536eab9d12e120d4da7ce9eab41844
-src/basic_memory/mcp/async_client.py,async_client.py,source_code,925,2025-07-30T09:39:45.722547,jope-bm,2,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com),6531f4387f30a30a322197ff51d6eacae4b25a58c648095931b3d1145d1da303
-src/basic_memory/mcp/project_session.py,project_session.py,source_code,4203,2025-07-08T20:39:18.342906,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),4da403ec93dec9063eeb8b05246e3501740d162cc77a067d3ce54ba43d690819
-src/basic_memory/mcp/prompts/__init__.py,__init__.py,source_code,615,2025-07-08T20:39:18.343263,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),f8197d0e08f64c3f4f50b8f38203ea5eebcf123582472ed2f58834de1dbe53b0
-src/basic_memory/mcp/prompts/ai_assistant_guide.py,ai_assistant_guide.py,source_code,821,2025-06-21T00:13:53.262832,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),f13239c4e6e2455730bfac3d6f2d71407957d3086fc84efe2c6b22a833114c58
-src/basic_memory/mcp/prompts/continue_conversation.py,continue_conversation.py,source_code,1998,2025-06-21T00:13:53.263309,bm-claudeai (AI Assistant),3,bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com); Paul Hernandez (60959+phernandez@users.noreply.github.com),aec9a50b657b7bb1ba0c02b42bcdb9bc5b0f2a0b1143bd361c5ce7ea59076833
-src/basic_memory/mcp/prompts/recent_activity.py,recent_activity.py,source_code,3311,2025-07-01T08:33:22.073986,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),d2fd5cddbd927430f15d5b85f1e3a3368a18cb4e2e4587a5d29749d2b9e0830e
-src/basic_memory/mcp/prompts/search.py,search.py,source_code,1692,2025-06-21T00:13:53.264093,bm-claudeai (AI Assistant),3,bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com); Paul Hernandez (60959+phernandez@users.noreply.github.com),9dbf3c319cbdb5d5bf32608b51522d8ae92b2dd6f7c441d62efd0954b525738a
-src/basic_memory/mcp/prompts/utils.py,utils.py,source_code,5431,2025-06-21T00:01:59.425042,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (60959+phernandez@users.noreply.github.com),55a72b6eac18b724a9225608aca1e8e6cea3b684ccb1c609aab1511f7ce90ba4
-src/basic_memory/mcp/resources/ai_assistant_guide.md,ai_assistant_guide.md,documentation,14777,2025-03-28T19:12:38.653627,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),aa76160e46256fe2662ae3a86799659916acfede1d5835c1fe2f0b136efb2e0b
-src/basic_memory/mcp/resources/project_info.py,project_info.py,source_code,1906,2025-06-21T00:13:53.264918,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),2dc5244f1e225c17d4e8ba784d5721efc3aa2e8a5b3b2e258f22a77ebe155eca
-src/basic_memory/mcp/server.py,server.py,source_code,1248,2025-07-08T20:39:18.343419,Paul Hernandez,3,Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),0a910cae27d61ea923e90fbe2d4b5c7cacf3b29d3e156f0b7f77872ab973c761
-src/basic_memory/mcp/tools/__init__.py,__init__.py,source_code,1619,2025-07-03T18:43:10.080029,Drew Cain,2,Drew Cain (groksrc@users.noreply.github.com); Paul Hernandez (paul@basicmachines.co),872b771dd52ec3b763645a2baf6e10a70f049ce3106830a6d3f053b3e09a5fe6
-src/basic_memory/mcp/tools/build_context.py,build_context.py,source_code,4611,2025-07-03T18:43:10.080426,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),724280b77b8f5f3e61cd3fdeebc3ee66e2bcfedaaea3638e6a2e2e33fcb1978e
-src/basic_memory/mcp/tools/canvas.py,canvas.py,source_code,3738,2025-07-01T08:33:22.076204,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),db617d1bd81f3dbfa5f22d41e6b6b825afe1f73618f37acf63d9830390b98246
-src/basic_memory/mcp/tools/delete_note.py,delete_note.py,source_code,7346,2025-07-01T08:33:22.076726,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),b52c9173f5600662f255e7a70a5c17d5293ef8b29c19a8403334d7da62b65c8b
-src/basic_memory/mcp/tools/edit_note.py,edit_note.py,source_code,13570,2025-07-01T08:33:22.077181,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),ab8c7e7fbfa3fe5fb0ce6d7bf805454f5fd6182a340aae25237b1e6127b6d5a6
-src/basic_memory/mcp/tools/list_directory.py,list_directory.py,source_code,5236,2025-06-21T00:13:53.267453,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),f85c43b02aeee580f4d8ce2a9100c0bab1095b245a0bb608e1847ace0d1ab51f
-src/basic_memory/mcp/tools/move_note.py,move_note.py,source_code,17541,2025-07-30T09:39:45.722919,jope-bm,2,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com),5ef27d9baaebc2c5656fc49c4798a4e4e40a70b6cd9d1e761dbcae021bad558c
-src/basic_memory/mcp/tools/project_management.py,project_management.py,source_code,12944,2025-07-06T10:34:45.552403,Drew Cain,2,Drew Cain (groksrc@users.noreply.github.com); Paul Hernandez (paul@basicmachines.co),cdac736d65129f689a85c6b82f8e043bc84a31657ead7a8331771171eeaa860f
-src/basic_memory/mcp/tools/read_content.py,read_content.py,source_code,9125,2025-07-30T09:39:45.723469,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),96a13addac507fd874394dfa2e1e5ed71af5eb89d0872c1d68cacf9cac3f8724
-src/basic_memory/mcp/tools/read_note.py,read_note.py,source_code,8132,2025-07-30T09:39:45.723828,jope-bm,5,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co); Amadeusz Wieczorek (git@amadeusw.com); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),dff53ce02b16d9c5fca315b3f09bb70867a89d614b0ef3f0548dce87978048ee
-src/basic_memory/mcp/tools/recent_activity.py,recent_activity.py,source_code,4833,2025-06-21T00:13:53.269120,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),5d58cd2402679b1bf3c7dfcbb3503e40e776c9347ba499524d3b91c528af98de
-src/basic_memory/mcp/tools/search.py,search.py,source_code,15883,2025-07-03T18:43:10.081557,Drew Cain,4,Drew Cain (groksrc@gmail.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),8519b0057468c4450eb543a2f561bcd0d7cb96e1ce1b95e948e02b309ba6b7ca
-src/basic_memory/mcp/tools/sync_status.py,sync_status.py,source_code,10517,2025-07-08T20:39:18.344231,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),73dd73b186eaec8b82e6b17e39a67c27082d24e0653dc4e4b35712bd83b80a22
-src/basic_memory/mcp/tools/utils.py,utils.py,source_code,20892,2025-07-30T09:39:36.616253,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),a95004911e276822eba88a3fef15c5b9ba861b1ca9a2ecfe0c1e3fb2f4ef0116
-src/basic_memory/mcp/tools/view_note.py,view_note.py,source_code,2499,2025-07-01T08:33:22.080024,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),75d357c72113b1d0394987e521a4158ff09b77b23b08b56cddab5144331b1a68
-src/basic_memory/mcp/tools/write_note.py,write_note.py,source_code,6612,2025-07-30T09:39:45.723985,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),771396fb49d397feb5f7e36321d4d233c22c4d1b53414912c849957c6e96fc83
-src/basic_memory/models/__init__.py,__init__.py,source_code,333,2025-06-21T00:01:59.437212,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),8f40b876d162f85384690291f1d416106f9d26d750d793414e2260e276c85cd5
-src/basic_memory/models/base.py,base.py,source_code,225,2025-06-21T00:01:59.447249,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),e2101727c084d519e32a16f6de53ddf9033b1bf15721d4e8c0c27d6d18b1b295
-src/basic_memory/models/knowledge.py,knowledge.py,source_code,7087,2025-06-21T00:01:59.444376,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),005c5f292f1f45ae372aadc48c9080b9fa6d7b854d0bb7ecf587ec843ac1e28d
-src/basic_memory/models/project.py,project.py,source_code,2773,2025-07-01T08:33:22.080907,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),a14ad06943aeeff9ae4a5fa2dfc0e1d07ce6085acc02dc20c402c3513b7d9397
-src/basic_memory/models/search.py,search.py,source_code,1300,2025-06-21T00:01:59.440923,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),3e143cc38b5a0294af8e1d43a4f841e1c1fd193b76136a68f83159ce19e86646
-src/basic_memory/repository/__init__.py,__init__.py,source_code,327,2025-06-21T00:01:59.256363,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),3162bea3c42292accea5ee52c8f6ca4368a8079056034529cfae6d820f84d035
-src/basic_memory/repository/entity_repository.py,entity_repository.py,source_code,10405,2025-07-03T18:43:10.082570,Drew Cain,3,Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),e2a8d1eba6c8d64bc61d7168df0fe8c29a670858bf9daeac464a0f440273fae0
-src/basic_memory/repository/observation_repository.py,observation_repository.py,source_code,2943,2025-06-21T00:01:59.269646,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (phernandez@basicmachines.co),aa132f1cb4a36a84f715afdc40e2ac4f98d83e3eba1974b2b4404cc0b020ca04
-src/basic_memory/repository/project_info_repository.py,project_info_repository.py,source_code,338,2025-06-21T00:01:59.252582,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (60959+phernandez@users.noreply.github.com),f172d50182a405643a19b2a3d62a80f4e2b41463c775394eb3b66d7de51ff6df
-src/basic_memory/repository/project_repository.py,project_repository.py,source_code,3803,2025-07-30T09:39:45.724344,jope-bm,2,jope-bm (joe@basicmemory.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),9083ba214b2bcaaf98164d9c33cda7add52bc77f7269ecb6e43cdd5088728b7c
-src/basic_memory/repository/relation_repository.py,relation_repository.py,source_code,3179,2025-06-21T00:01:59.246745,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),cfb3a8e59cff27e063e91bd00e949647bdd92e4d9fc46edeee3acc6de15e26f4
-src/basic_memory/repository/repository.py,repository.py,source_code,15224,2025-06-21T00:01:59.273355,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (60959+phernandez@users.noreply.github.com),3096fe71bf106506cbf86aeafe2aafe0aabbe5a5f6c90a212c8aa1e53e1f171c
-src/basic_memory/repository/search_repository.py,search_repository.py,source_code,21936,2025-07-03T18:43:10.082844,Paul Hernandez,3,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),a972f73d1b71dac5770e8eb3793c6c9ac44e4e792f9dab528f8c4e6c6a80bcaa
-src/basic_memory/schemas/__init__.py,__init__.py,source_code,1674,2025-06-21T00:01:59.514555,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (60959+phernandez@users.noreply.github.com),98480815c75379bfafe32d2090e87fa40e73caa19b664fbd5db5ea9528ba58cb
-src/basic_memory/schemas/base.py,base.py,source_code,6738,2025-07-01T08:33:22.082193,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),171f7b0c4ab33abef2f7379eb1e3bda950586ce7edff83907fd12255f84e267e
-src/basic_memory/schemas/delete.py,delete.py,source_code,1180,2025-06-21T00:01:59.502563,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),50047624af7d58c8f780ffb2a065a51c3dde64492f9534917fc42860813e59fc
-src/basic_memory/schemas/directory.py,directory.py,source_code,881,2025-06-21T00:01:59.529023,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),17dfcbac9a91a9bfe43b4f060ca2735cb6f69e16d81b63dd554a397830ff29fe
-src/basic_memory/schemas/importer.py,importer.py,source_code,693,2025-07-30T09:39:45.724633,jope-bm,2,jope-bm (joe@basicmemory.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),ac33df423ca32b28ce7b6ea9c29d541f8783a86c0c29f78db35163bf93f139cd
-src/basic_memory/schemas/memory.py,memory.py,source_code,5833,2025-07-03T18:43:10.083167,Drew Cain,3,Drew Cain (groksrc@users.noreply.github.com); Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),acb4a953a553feca672c4895798a7d948ec51f922f75b66dd7d55716e3bebed3
-src/basic_memory/schemas/project_info.py,project_info.py,source_code,7047,2025-07-01T08:33:22.083248,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),7dc3635297b6e7fe6e3262b2d78da26f7a79a846a4cecd5624f2e4828979cf2c
-src/basic_memory/schemas/prompt.py,prompt.py,source_code,3648,2025-06-21T00:01:59.525753,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),4a92157d9a6b413f04e6e3f8d23dc2a417369c729f9703a8de2643ec114f2071
-src/basic_memory/schemas/request.py,request.py,source_code,3760,2025-06-21T00:01:59.511789,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),32fe44beb2d99452223ebf1d3a3a3fe105ef92c79885023b71dfd7db30ecc503
-src/basic_memory/schemas/response.py,response.py,source_code,6450,2025-07-03T18:43:10.083478,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),5eea4660a2abe48d83ed083d1c2483fdcfb403e0b504f03c14d22f1cae866abb
-src/basic_memory/schemas/search.py,search.py,source_code,3657,2025-06-21T00:01:59.522804,bm-claudeai (AI Assistant),3,bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com); Paul Hernandez (60959+phernandez@users.noreply.github.com),cb032c0c60102b6b0ed934f995cf9d6bf93aece296d71d537a75e8ae61c75afe
-src/basic_memory/services/__init__.py,__init__.py,source_code,259,2025-06-21T00:01:59.655059,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),5c6b7c597ddf5ffd0af4bdfb32ccbc1c5f2794c658206dee43a9945fafe226d8
-src/basic_memory/services/context_service.py,context_service.py,source_code,14462,2025-06-21T00:01:59.672086,bm-claudeai (AI Assistant),3,bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com); Paul Hernandez (paulmh@gmail.com),e1178b005e6a89f03d6b239e3c6b152aeb30d535a3f280734440a3aec16228f2
-src/basic_memory/services/directory_service.py,directory_service.py,source_code,6017,2025-06-21T00:01:59.648501,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),fd838f5ec79033892777b3c8140868f4b57f13e1658d513959524a434b9f959b
-src/basic_memory/services/entity_service.py,entity_service.py,source_code,30440,2025-07-03T18:43:10.083956,Paul Hernandez,4,Paul Hernandez (paul@basicmachines.co); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),7cd5163eca6b8a0772e838c8c869e478166763cd6a2d745b0b9aa5c25a65baee
-src/basic_memory/services/exceptions.py,exceptions.py,source_code,390,2025-06-21T00:01:59.668908,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),a158d0af9d1742a9c5ab5f8c34a062948d9286d1c3c72a5abf20e4d547b21e1c
-src/basic_memory/services/file_service.py,file_service.py,source_code,10059,2025-06-21T00:01:59.641785,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),8c2ae69c4913438b7d1c5ecbfcce812fbb5d0ea8e3cedcbd8694e8f40cf086f3
-src/basic_memory/services/initialization.py,initialization.py,source_code,6715,2025-07-08T20:39:18.344482,Paul Hernandez,3,Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),4dde58b799cf4ac90631e59949b55b3355a93bdf99df0d9c2408c0cea67e10c4
-src/basic_memory/services/link_resolver.py,link_resolver.py,source_code,4594,2025-07-01T08:33:22.084908,Paul Hernandez,3,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),d7efd516cbea753e6b5411def09aeaeb7539f5743487119ecf163c736e138a8c
-src/basic_memory/services/project_service.py,project_service.py,source_code,30125,2025-07-30T09:39:45.725079,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),bce95c00aa9a1da0a8c8090ee34b5b1494207f8c99e6c25de4ec43fddc38f6be
-src/basic_memory/services/search_service.py,search_service.py,source_code,12782,2025-06-21T00:01:59.665439,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),7392b2d2e7f3ed83c5807855ccd450e0e79c17f254aedee700bce9323a1b5b83
-src/basic_memory/services/service.py,service.py,source_code,336,2025-06-21T00:01:59.636167,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),57e77ff20395d3bcc62100e92fe2acaacdd937d977a9fdc764e2b57ff60d4da8
-src/basic_memory/services/sync_status_service.py,sync_status_service.py,source_code,7504,2025-07-03T18:43:10.084229,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),0a025d689e8e16f1632872104952105fc904537f3d32bcff592eb1f1dc76fbb7
-src/basic_memory/sync/__init__.py,__init__.py,source_code,156,2025-06-21T00:01:59.621137,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),0951e0b981f8e7b876bb6c6833c2af3a29490bbd5726567ea9487c947723623e
-src/basic_memory/sync/background_sync.py,background_sync.py,source_code,726,2025-07-08T20:39:18.345062,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),549af64ae91128b76c6df07ef517b82de85ca4ad796be44b5c0141fac01d4513
-src/basic_memory/sync/sync_service.py,sync_service.py,source_code,23387,2025-07-01T08:33:22.086507,Paul Hernandez,3,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),0310b927561370f593980d07773bce641b618b8fbf2d9e3890d174290a0344fc
-src/basic_memory/sync/watch_service.py,watch_service.py,source_code,15316,2025-06-26T09:28:51.859209,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (60959+phernandez@users.noreply.github.com),240ba6ac7523575945f4db442b7da3820d26c9605f2d7a2d357c4e35e215f523
-src/basic_memory/templates/prompts/continue_conversation.hbs,continue_conversation.hbs,templates,3076,2025-07-01T08:33:22.086792,Drew Cain,2,Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),b6bac31d25c0e52d0909b2273285092f4e31bc219107f92ed511cd407b65e992
-src/basic_memory/templates/prompts/search.hbs,search.hbs,templates,3098,2025-05-25T10:07:54.520119,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),1f570222c1caa78542d46ac7d8a79407ca467b9bd714fa9bd953e8b72a667820
-src/basic_memory/utils.py,utils.py,source_code,8654,2025-07-30T09:39:45.725428,jope-bm,5,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com); andyxinweiminicloud (andyxinweimin263@icloud.com); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),111f343e3367339730e081c08acf4613667be574f946126513b5d82da3086bed
-test-int/conftest.py,conftest.py,source_code,8203,2025-07-08T20:39:18.345735,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),7231e1bc76cddc7c94433e853825dc0165b103bedf996c2c24eda6ae32fff5ad
-test-int/mcp/test_build_context_validation.py,test_build_context_validation.py,source_code,6469,2025-07-08T20:39:18.346021,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),ee61d6b15cee0194fd74c1bcf9361d5a839f6081c7d571ef081da8fcefe1bbf2
-test-int/mcp/test_delete_note_integration.py,test_delete_note_integration.py,source_code,13175,2025-07-08T20:39:18.346366,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),497495249b8bcf0af177d8705c6899875460707697980434e560cfe56f86feb3
-test-int/mcp/test_edit_note_integration.py,test_edit_note_integration.py,source_code,19822,2025-07-08T20:39:18.346730,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),9ba704badd05808aee0b5a686b7e250e1c865229ec92dab561cba5287b6f6fc6
-test-int/mcp/test_list_directory_integration.py,test_list_directory_integration.py,source_code,14744,2025-07-08T20:39:18.347106,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),2c4336a59de63f17ed252bb52d1330ebca901ad83bfebc9e5aa67f132a3c77c6
-test-int/mcp/test_move_note_integration.py,test_move_note_integration.py,source_code,19825,2025-07-08T20:39:18.347344,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),cbb17688d0f9551306a7520b059ace7f7dfba70fc20bf0ec98b1148000d7ad7d
-test-int/mcp/test_project_management_integration.py,test_project_management_integration.py,source_code,33175,2025-07-08T20:39:18.347658,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),93a43cd699453a7602a5def839740ba5027ab914eba3e7b66a026860ed6bd567
-test-int/mcp/test_project_state_sync_integration.py,test_project_state_sync_integration.py,source_code,7728,2025-07-08T20:39:18.347907,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),80b0f5b5cd359498dcbd3af7dcb6194afa4582d8efb3faa38d28675ee45e0748
-test-int/mcp/test_read_content_integration.py,test_read_content_integration.py,source_code,11187,2025-07-08T20:39:18.348233,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),6955dd343b40df088ac79175e52723501d83796335a16e43b7f58e16e757e1b8
-test-int/mcp/test_read_note_integration.py,test_read_note_integration.py,source_code,1381,2025-07-08T20:39:18.348463,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),b93050da68d0e9d47d46879a386567f688399e28390f4eb31ee37353dc27514b
-test-int/mcp/test_search_integration.py,test_search_integration.py,source_code,14690,2025-07-08T20:39:18.348959,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),e0957ada9dd9b12eae5843a37d241ec9293ca929f18281e31197dae36bff589d
-test-int/mcp/test_write_note_integration.py,test_write_note_integration.py,source_code,9472,2025-07-08T20:39:18.349398,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),b2b56fee8351168d0c65640c295d969dc4575d9bea87927b2dc07e591cabdff3
-tests/Non-MarkdownFileSupport.pdf,Non-MarkdownFileSupport.pdf,other,106751,2025-02-23T17:31:23.206428,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),4aa96f9d0ee830ef6a1ec92243f302bbe2fa8971b84945f4eb5e276bf1ffde96
-tests/Screenshot.png,Screenshot.png,other,190076,2025-02-23T17:31:23.207771,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),dd82612fe013c39810d28ae0f2bbcca6ab2c9925b035d7720bb02493ddf5d0a9
-tests/__init__.py,__init__.py,source_code,141,2025-06-21T00:01:46.216456,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),2ac5605e69ad8829e96b3689632536539f1cdd3149a29c1903f25af0793a5d65
-tests/api/conftest.py,conftest.py,source_code,1404,2025-06-21T00:01:46.359728,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),ea46cde47a37c1f43fe079e48f5d0de8007155a0187f4445abc4f2ffde9c1791
-tests/api/test_async_client.py,test_async_client.py,source_code,1382,2025-07-30T09:39:45.725666,jope-bm,2,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com),a2f96226a75e5cff2326ca48ddccea4915964d83e529f7b99958bc233ccdc31a
-tests/api/test_continue_conversation_template.py,test_continue_conversation_template.py,source_code,5152,2025-06-21T00:01:46.390901,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),cca08b0291db0ad693c60d8dc203660021feab46d9eb530be7f67e0ebb52c1d3
-tests/api/test_directory_router.py,test_directory_router.py,source_code,9376,2025-06-21T00:01:46.356659,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),428626589f0010512481ba495368b0bf2b9617b22764e588eaa3562e86da4d37
-tests/api/test_importer_router.py,test_importer_router.py,source_code,16578,2025-06-21T00:01:46.368070,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),03edf6e7404c7350afe76e54ea2bf0d66f668bcdb49f59702067a67b3694309d
-tests/api/test_knowledge_router.py,test_knowledge_router.py,source_code,45771,2025-07-01T08:33:22.090490,Paul Hernandez,3,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),43a5f91ae1fb9038e65c09701336fbdc4dbf40c8319c94727e6312fda9d6d56e
-tests/api/test_management_router.py,test_management_router.py,source_code,6220,2025-06-21T00:01:46.402764,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),f6a3f41f263f10c08281525571e2e39fc9ae818ebb7e9895e3f3f3115ea05677
-tests/api/test_memory_router.py,test_memory_router.py,source_code,5555,2025-06-21T00:01:46.399667,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (phernandez@basicmachines.co),2b8782015c893081fc67b7f13a7255d4e3dc45b27705a524f94918a339e2d486
-tests/api/test_project_router.py,test_project_router.py,source_code,13288,2025-07-30T09:39:45.725847,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),af85d0870069d3831a9214372853994e5d12dc910e37298eb9958f72f6a8bb31
-tests/api/test_project_router_operations.py,test_project_router_operations.py,source_code,1812,2025-06-21T00:01:46.381705,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),afd40879de3d7c508cca0feeae3cb7a8f3afcfbb06f59a6104189b1e3291376a
-tests/api/test_prompt_router.py,test_prompt_router.py,source_code,5046,2025-06-21T00:01:46.396588,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),9115995b7dd8b44d8a9c06c5e1bbb177618286675a769889e35ac16f26fd9897
-tests/api/test_resource_router.py,test_resource_router.py,source_code,13960,2025-06-21T00:01:46.384919,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),ad3cb2cabaeab82a7e64253ceede7c1791e2bd70c92f60bc5f3be939292ca22d
-tests/api/test_search_router.py,test_search_router.py,source_code,6409,2025-06-21T00:01:46.375427,bm-claudeai (AI Assistant),3,bm-claudeai (AI Assistant) (claude@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com); Paul Hernandez (phernandez@basicmachines.co),ba3e3809795e72db9dd9c8c729048bdbbbdb897c2a5aa8b175112b5d4b56d152
-tests/api/test_search_template.py,test_search_template.py,source_code,5258,2025-06-21T00:01:46.378721,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),8f0d16a1de947d0466d96afed02e695f7648adac70b9ba99753250068207a686
-tests/api/test_template_loader.py,test_template_loader.py,source_code,8035,2025-06-21T00:01:46.406694,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),4fd7c6c4862cc0d877d29244ecdc0b52a0693fc4574a9667663bee36bfd36b62
-tests/api/test_template_loader_helpers.py,test_template_loader_helpers.py,source_code,7445,2025-06-21T00:01:46.372114,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),8dd35f11c9b3f2d96ac36263edf4430308728c04c9da543b1cb845b96ab20aa7
-tests/cli/conftest.py,conftest.py,source_code,1185,2025-07-01T08:33:22.090848,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),c3c73da7ad73224931e1fba4ebd70792221be607bfb1488bb5c9420bba03bdb8
-tests/cli/test_cli_tools.py,test_cli_tools.py,source_code,13528,2025-06-21T00:01:46.318964,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),befb8cab50132e26a1b13b82ce8e93a3258282cf157a4230214bfcefeae65102
-tests/cli/test_import_chatgpt.py,test_import_chatgpt.py,source_code,6719,2025-07-08T20:39:18.350234,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),df447335545248e2fb2417af33f8cc2f0143bd413a1783e41f89605de305b7c8
-tests/cli/test_import_claude_conversations.py,test_import_claude_conversations.py,legal,5028,2025-07-08T20:39:18.350607,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),ac4b3b9dfc331fa7fa32a2941c027ff8b6585a94a5ccfaaf0a4affe5cf19c00c
-tests/cli/test_import_claude_projects.py,test_import_claude_projects.py,legal,4585,2025-07-08T20:39:18.350885,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),7eaab3d491d50ca59c8ba015ecd5740a5feae94d970ee17559c6df9d8558c2cc
-tests/cli/test_import_memory_json.py,test_import_memory_json.py,source_code,4891,2025-07-30T09:39:45.726290,jope-bm,3,jope-bm (joe@basicmemory.com); bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (60959+phernandez@users.noreply.github.com),d6734ce059dacf97bc764d848b2e2a6ba52fa96871bc331ec9d2ddc60b766bb6
-tests/cli/test_project_commands.py,test_project_commands.py,source_code,6578,2025-07-30T09:39:45.726703,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),51e2ac7ff44b0d1a1db6da406c5c2e6aebceb1b63a1e8d5ab51bbaa834507157
-tests/cli/test_project_info.py,test_project_info.py,source_code,3874,2025-07-01T08:33:22.091600,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),0b08950e95a5f276f14c56f6fe99af4d41b8f04548e9b7746f807c5ac4155578
-tests/cli/test_status.py,test_status.py,source_code,4160,2025-07-01T08:33:22.091978,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),a1ff89fdac4bf57ba03be92ac79b8ca3210af0b1132d5a2bd0fc0c253fcbf988
-tests/cli/test_sync.py,test_sync.py,source_code,3864,2025-07-08T20:43:47.816788,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),77e0f6b42b584a5acfda3c2ff194ff5e71ca57a40cb4484d563f5482bbbb4c0f
-tests/cli/test_version.py,test_version.py,source_code,289,2025-06-21T00:01:46.305368,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),db95665178a32d391bd83011d073db269cefba9da8a4dc4d3e392d47bc0e0a8f
-tests/conftest.py,conftest.py,source_code,15286,2025-07-08T20:39:18.351368,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),c6f38f103ce58144ffe4562f0c47dad849974e96327f02805e854447e19bc411
-tests/importers/test_importer_base.py,test_importer_base.py,source_code,4329,2025-07-08T20:39:00.549594,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),da872a073f2b90fda3c98c9f44cf45884f4f682d91ec1b1f931d42c34eee1939
-tests/importers/test_importer_utils.py,test_importer_utils.py,source_code,1827,2025-06-21T00:01:46.184343,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),cbee630c855ceb1de764ac0cdb1d5d781c16cd3a934d67166adc235c98f363d7
-tests/markdown/__init__.py,__init__.py,source_code,0,2025-06-21T00:01:46.196570,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
-tests/markdown/test_entity_parser.py,test_entity_parser.py,source_code,8669,2025-06-21T00:01:46.206579,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),496fdab6fe164634f8223f827585a4c0dedd30ccea7b0b69dc79004ad0996de2
-tests/markdown/test_markdown_plugins.py,test_markdown_plugins.py,source_code,5139,2025-06-21T00:01:46.200759,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),9624d73462aadcd47fb0edd0d87880959a8982eecfa39529f21e3b292c34cb83
-tests/markdown/test_markdown_processor.py,test_markdown_processor.py,source_code,5728,2025-06-21T00:01:46.194175,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),35042aa57dd2aeed848c624aa7f69decfb18e83c3b217eca1fdacfc4a10831db
-tests/markdown/test_observation_edge_cases.py,test_observation_edge_cases.py,source_code,4295,2025-06-21T00:01:46.209598,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),6f1ab7684bfa8b02af0e0c42b3d7aed91fcd0b1c6288cbc9b6d6943c166979fa
-tests/markdown/test_parser_edge_cases.py,test_parser_edge_cases.py,source_code,5142,2025-06-21T00:01:46.213291,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),d511d7d1187e3c1d3a8d3e0ab9efc9e68e84115c46811e7a9dc21eca9a87d520
-tests/markdown/test_relation_edge_cases.py,test_relation_edge_cases.py,source_code,3952,2025-06-21T00:01:46.203846,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),f8e2016308f84139342cc37ec6e389ffe52d7eb46f998ee327c7f0d5bba3ad9b
-tests/markdown/test_task_detection.py,test_task_detection.py,source_code,401,2025-06-21T00:01:46.191444,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),37fe91a689742033a0eb76723557e31c2a85e591133383b3887572cb714db2a5
-tests/mcp/conftest.py,conftest.py,source_code,1761,2025-07-08T20:39:18.351554,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),350b2ca42c52ef76e002deddb65fc0eccb9f8989bd26078ea1c100e3b93bae3f
-tests/mcp/test_prompts.py,test_prompts.py,source_code,5989,2025-07-01T08:33:22.093691,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),e3b2ee5b4bc120b5043225ebdbf73eadd71be9c3d9d8e1fdd66a24a8ff11a780
-tests/mcp/test_resource_project_info.py,test_resource_project_info.py,source_code,4885,2025-07-01T08:33:22.094085,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),6a043736789b239c8d4ae00d1a5332a0fc3bed4038fe3388970ba97dc7431a93
-tests/mcp/test_resources.py,test_resources.py,source_code,549,2025-07-01T08:33:22.094481,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),77a6396b9b8a9d3b3d202e438243ca6178d87fd7680c9fc063ee013f2042aa4c
-tests/mcp/test_tool_build_context.py,test_tool_build_context.py,source_code,3714,2025-07-01T08:33:22.094661,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),5f0a39fdb652605335ed54aa91fe994262441bb7ba46f381c46ebca882fc23f2
-tests/mcp/test_tool_canvas.py,test_tool_canvas.py,source_code,7997,2025-07-01T08:33:22.094982,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),c517bb1f9edc77b76fbeb483dfcb2dd57de9f0b80a10738708bc90cbe388dc9e
-tests/mcp/test_tool_delete_note.py,test_tool_delete_note.py,source_code,4208,2025-07-01T08:33:22.095578,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),4cbf3ba4313438651b0608d5b25faf1400f7bd6a78af630351aecd4457800895
-tests/mcp/test_tool_edit_note.py,test_tool_edit_note.py,source_code,13503,2025-07-03T18:43:10.084890,Drew Cain,2,Drew Cain (groksrc@gmail.com); Paul Hernandez (60959+phernandez@users.noreply.github.com),dd441969aa54b3739f2d9202d3feaf46aee807ec51e01a13ef41eda52743944f
-tests/mcp/test_tool_list_directory.py,test_tool_list_directory.py,source_code,7730,2025-07-01T08:33:22.096737,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),cfbb5c06bcfe74ea60f31051eb9b03ac80b86232b053c188bf3b172132f7c0f5
-tests/mcp/test_tool_move_note.py,test_tool_move_note.py,source_code,25851,2025-07-30T09:39:45.727347,jope-bm,2,jope-bm (joe@basicmemory.com); Paul Hernandez (paul@basicmachines.co),c9f95158503fa42e37532aaa35027538fa49cea718d059d570cf547d31f01043
-tests/mcp/test_tool_read_content.py,test_tool_read_content.py,source_code,19442,2025-07-30T09:39:45.727526,jope-bm,1,jope-bm (joe@basicmemory.com),1817e32f997b06dbdabf02864d0c70584c1cd80bf1fae8dfbef649de79434bc5
-tests/mcp/test_tool_read_note.py,test_tool_read_note.py,source_code,22991,2025-07-30T09:39:45.727746,jope-bm,4,jope-bm (joe@basicmemory.com); Paul Hernandez (paul@basicmachines.co); Amadeusz Wieczorek (git@amadeusw.com); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),4e13ea9ff977525aa62b6a8c22505ffe989329dc3e7d07b71e044cf43ef3ddfd
-tests/mcp/test_tool_recent_activity.py,test_tool_recent_activity.py,source_code,3983,2025-07-01T08:33:22.098561,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),45414152cd45334b84df56f653146b7bd2939907548e7245a37207fdccfc4c87
-tests/mcp/test_tool_resource.py,test_tool_resource.py,source_code,6782,2025-07-01T08:33:22.098948,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),3916ae1c4d458eee53d2c570b9bbb708ecd617de5a145c3a7552389954bc9195
-tests/mcp/test_tool_search.py,test_tool_search.py,source_code,10959,2025-07-03T18:43:10.085177,Drew Cain,3,Drew Cain (groksrc@gmail.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),07839cf8e89d74ba05ec1dc55fa842444c1f0cc3d1587823b0ac3458ad89e87c
-tests/mcp/test_tool_sync_status.py,test_tool_sync_status.py,source_code,6331,2025-07-01T08:33:22.100021,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),3f3566df5b9f3c66bb9b3bd77d4c05825480d0e85015305cb1b7ab9429c7a7ec
-tests/mcp/test_tool_utils.py,test_tool_utils.py,source_code,9228,2025-07-01T08:33:22.100561,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),b50789f7a78b0169f52dc8bd16e262510ed4a0ac130fce698d4be84af1fe2d31
-tests/mcp/test_tool_view_note.py,test_tool_view_note.py,source_code,10004,2025-07-01T08:33:22.101164,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),385535ce791c3ab55db827cbcf27ea25ae85faf3a027f52df4eea052cede7f36
-tests/mcp/test_tool_write_note.py,test_tool_write_note.py,source_code,35136,2025-07-30T09:39:45.728137,jope-bm,3,jope-bm (joe@basicmemory.com); Drew Cain (groksrc@users.noreply.github.com); Paul Hernandez (60959+phernandez@users.noreply.github.com),45172de20cfc4f4436287573b4f5a94b8b616a360647af67ba1c6c343ccd41b8
-tests/repository/test_entity_repository.py,test_entity_repository.py,source_code,15498,2025-06-21T00:01:46.176265,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),8f5d1ff6cff7b640993ff73f463b1e7801a4dd69640fc55fa23dc58b865e9943
-tests/repository/test_entity_repository_upsert.py,test_entity_repository_upsert.py,source_code,16983,2025-07-03T18:43:10.085482,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); Drew Cain (groksrc@users.noreply.github.com),ee0ecd6f4ff8b31838bd6de6fb1018af437e02813d8315c06f4e20a6b78a0572
-tests/repository/test_observation_repository.py,test_observation_repository.py,source_code,11786,2025-06-21T00:01:46.158862,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (phernandez@basicmachines.co),3006d392ad94dcc9b3ae031d63a1af6935624534389dd025de70d4c9e112aa0b
-tests/repository/test_project_info_repository.py,test_project_info_repository.py,source_code,1186,2025-06-21T00:01:46.161876,bm-claudeai (AI Assistant),1,bm-claudeai (AI Assistant) (claude@basicmachines.co),dbce7ae7350403cbc37343c2e3e68e4d2255e247006aaa6c495a7ce8bfddea7d
-tests/repository/test_project_repository.py,test_project_repository.py,source_code,10511,2025-07-30T09:39:45.728536,jope-bm,2,jope-bm (joe@basicmemory.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),279a3324635b1b515c18003bd1875cf230fef1192cadef9ca426846783717e75
-tests/repository/test_relation_repository.py,test_relation_repository.py,source_code,11980,2025-06-21T00:01:46.167567,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (phernandez@basicmachines.co),fcdbdf40f7b56145b98eedde5ead64ef6187e859adde48cc09f5a97754757428
-tests/repository/test_repository.py,test_repository.py,source_code,5996,2025-06-21T00:01:46.152691,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),3a6d4ca0b7a438a30ae504f5eac22874d4e1a937a4246e90efad46c90f0e1c95
-tests/repository/test_search_repository.py,test_search_repository.py,source_code,25471,2025-07-03T18:43:10.086041,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),805b5cc55a53ae9d6e86c0de735c7f38ac9fd92c23194b0150fa3e7f5507a146
-tests/schemas/test_memory_url.py,test_memory_url.py,source_code,2000,2025-06-21T00:01:46.346515,Paul Hernandez,1,Paul Hernandez (paulmh@gmail.com),946fa6c48534f41c8b9cc27bbad164d3e3673a79afa84fbb439fae4cd26c504b
-tests/schemas/test_memory_url_validation.py,test_memory_url_validation.py,source_code,9338,2025-07-01T08:33:22.103247,Paul Hernandez,1,Paul Hernandez (paul@basicmachines.co),7054c3a3cdb8e05d2ffd254ed298908ff3d48a0a3927d960975eae1ab9beeb38
-tests/schemas/test_schemas.py,test_schemas.py,source_code,16880,2025-07-03T18:43:10.086337,Drew Cain,3,Drew Cain (groksrc@gmail.com); Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),2c746a00c340f063c160ace67569955a300a294040949695c79fd4ae124fb611
-tests/schemas/test_search.py,test_search.py,source_code,3264,2025-06-21T00:01:46.343685,github-actions[bot] (AI Assistant),2,github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com); Paul Hernandez (60959+phernandez@users.noreply.github.com),7437775d1b4a61a438cbabe3dbb1becd2adc4dbcc0c24595830c0843fa7a3166
-tests/services/test_context_service.py,test_context_service.py,source_code,8833,2025-06-21T00:01:46.446200,bm-claudeai (AI Assistant),2,bm-claudeai (AI Assistant) (claude@basicmachines.co); Paul Hernandez (paulmh@gmail.com),ab49d21a05d5364e7e8a2f00b07aabe1109b7417698e0acd92792e2cb5f22732
-tests/services/test_directory_service.py,test_directory_service.py,source_code,6854,2025-06-21T00:01:46.457258,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),a0c765fb6bd1a75b6ba4592b1df344c48273b6ab03ba6bd15d2b5e840eb2d521
-tests/services/test_entity_service.py,test_entity_service.py,source_code,59278,2025-07-03T18:43:10.086674,Paul Hernandez,3,Paul Hernandez (paul@basicmachines.co); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),d7d495756faa10b415d705cf26b69d2efbc5f190a834b6767386ff296629ea71
-tests/services/test_file_service.py,test_file_service.py,source_code,5243,2025-06-21T00:01:46.460141,Paul Hernandez,1,Paul Hernandez (phernandez@basicmachines.co),83e6e9a7584b7baeccbc84865d8c1d3e2a0223e7d2b9c066d3799c289196ab7d
-tests/services/test_initialization.py,test_initialization.py,source_code,6939,2025-07-08T20:39:18.351946,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),ebb8d11ff37dcb36c4844c68f873c8e0e8aa6ab1b82abb22ee96c4233e6ab287
-tests/services/test_link_resolver.py,test_link_resolver.py,source_code,13618,2025-07-01T08:33:22.105766,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),c9fc56d0c3572770e95ca6175c213ed8b44c2a6ddddc298b5662cc2d8f41014e
-tests/services/test_project_service.py,test_project_service.py,source_code,28152,2025-07-30T09:39:45.728920,jope-bm,3,jope-bm (joe@basicmemory.com); Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),430868ed796518937a3b0bed4d8c33be53264a6100d61d54b0745bb2b58bf29a
-tests/services/test_project_service_operations.py,test_project_service_operations.py,source_code,4679,2025-06-21T00:01:46.442141,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),d4103b6c5fff7e74ba84b86033537b8522aa60fc75aec4974d52e1dfec68b1b4
-tests/services/test_search_service.py,test_search_service.py,source_code,25299,2025-06-21T00:01:46.439133,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),b3e58258db2b727ab8a1792e52fcb038d3a0779bcd1b70f2d295a9d06e5e2513
-tests/services/test_sync_status_service.py,test_sync_status_service.py,source_code,9926,2025-07-03T18:43:10.087266,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),00245ca356e33fc7afcd2d42cb5ec082038c95383d738067821cf1e8d23c9a4b
-tests/sync/test_sync_service.py,test_sync_service.py,source_code,39659,2025-07-01T08:33:22.107088,Paul Hernandez,2,Paul Hernandez (paul@basicmachines.co); bm-claudeai (AI Assistant) (claude@basicmachines.co),0609aee9906549f27fc4289b5ac2d46a50e53e12a0615a2701f17fbe9a74e169
-tests/sync/test_sync_wikilink_issue.py,test_sync_wikilink_issue.py,source_code,1959,2025-06-21T00:01:46.420370,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),db4b98dd7008a1a26b0fd02b9a2d03bca950b281efc19d98a91b017c500b23a5
-tests/sync/test_tmp_files.py,test_tmp_files.py,source_code,5930,2025-06-21T00:01:46.424277,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),cead95a07b29f6c1ab933abe67f9648122f5f33d33753c8e4ab4934af96cbc25
-tests/sync/test_watch_service.py,test_watch_service.py,source_code,14076,2025-06-26T09:28:51.860679,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),e324a4127f8bfe59798f3a08125488c701e88239b7482d87a0394b91c55b893e
-tests/sync/test_watch_service_edge_cases.py,test_watch_service_edge_cases.py,source_code,2169,2025-06-21T00:01:46.409830,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),b87c5015330e9b551630aab7ef95ac1e7663f0ce46e912d8155b319e139559aa
-tests/test_config.py,test_config.py,source_code,3680,2025-07-03T18:43:10.087558,Paul Hernandez,3,Paul Hernandez (paul@basicmachines.co); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),6a246431cff739274efda895dfa28f38710289a73e645312f5fa05fce0885ec8
-tests/test_db_migration_deduplication.py,test_db_migration_deduplication.py,source_code,6166,2025-07-08T20:39:18.352690,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com),ab768e061531ca2edcd598c101b5d884e549f90c7a4b305a23713a199d263fbb
-tests/utils/test_file_utils.py,test_file_utils.py,source_code,6199,2025-06-21T00:01:46.219673,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),4615bb20b92b8a79d9e086301f852b34c3360f17ecc209920d68528268ddeed4
-tests/utils/test_parse_tags.py,test_parse_tags.py,source_code,1691,2025-06-21T00:01:46.223400,Paul Hernandez,2,Paul Hernandez (60959+phernandez@users.noreply.github.com); github-actions[bot] (AI Assistant) (41898282+github-actions[bot]@users.noreply.github.com),b83afdf18dac8b3411bd0fab1301683217d3d1abceaf2d22c09e79c709efd8eb
-tests/utils/test_permalink_formatting.py,test_permalink_formatting.py,source_code,4193,2025-06-21T00:01:46.225738,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),d998a4ca846c78679728a918b6f71df67c30b6961ede3cffa609f2cf6ad160eb
-tests/utils/test_utf8_handling.py,test_utf8_handling.py,source_code,5791,2025-06-21T00:01:46.228483,Paul Hernandez,1,Paul Hernandez (60959+phernandez@users.noreply.github.com),50ec792e572af51cd2d996d4ddacbcfd3bbd79aa928818a90c42117451ea829f
-tests/utils/test_validate_project_path.py,test_validate_project_path.py,source_code,15346,2025-07-30T09:39:45.729224,jope-bm,1,jope-bm (joe@basicmemory.com),27a4bf2a9d277e6cd773619e5241b20175d211ec60c284361bec404fd99143f3
-uv.lock,uv.lock,other,232710,2025-07-30T09:39:36.619155,Paul Hernandez,3,Paul Hernandez (60959+phernandez@users.noreply.github.com); Drew Cain (groksrc@users.noreply.github.com); bm-claudeai (AI Assistant) (claude@basicmachines.co),caa1e3f6e66464b884a78cab77df2fe303fa3c0dc573be0196474b6d3c150581

legal_inventory_sample.md

@@ -1,294 +0,0 @@
-# Basic Memory - Legal File Inventory
-
-**Generated:** 2025-07-29T16:10:54.745774
-
-**Repository:** /Users/phernandez/dev/basicmachines/basic-memory
-
-## Summary Statistics
-
-- **Total Files:** 255
-- **Total Contributors:** 12
-
-### Files by Category
-
-- **Build/Deployment:** 2 files
-- **Configuration:** 6 files
-- **Database/Migration:** 1 files
-- **Documentation:** 6 files
-- **Legal/License:** 3 files
-- **Other:** 13 files
-- **Source Code:** 222 files
-- **Templates/Resources:** 2 files
-
-### Top Contributors by Files Modified
-
-- **phernandez:** 190 files
-- **Paul Hernandez:** 181 files
-- **bm-claudeai:** 135 files
-- **Drew Cain:** 24 files
-- **github-actions[bot]:** 20 files
-- **Amadeusz Wieczorek:** 2 files
-- **semantic-release:** 1 files
-- **Jason Noble:** 1 files
-- **Marc Baiza:** 1 files
-- **Matias Forbord:** 1 files
-
-## Detailed File Inventory
-
-| File Path | Category | Size (bytes) | Primary Author | Contributors |
-|-----------|----------|--------------|----------------|-------------|
-| .claude/commands/release/beta.md | Other | 3103 | phernandez | phernandez |
-| .claude/commands/release/changelog.md | Documentation | 4648 | phernandez | phernandez |
-| .claude/commands/release/release-check.md | Other | 3344 | phernandez | phernandez |
-| .claude/commands/release/release.md | Other | 2925 | phernandez | phernandez |
-| .claude/commands/test-live.md | Other | 18720 | phernandez | phernandez |
-| .claude/settings.local.json | Configuration | 3122 | Unknown |  |
-| .dockerignore | Other | 623 | Paul Hernandez | Paul Hernandez |
-| .python-version | Other | 5 | phernandez | phernandez |
-| CHANGELOG.md | Documentation | 53647 | semantic-release | semantic-release, phernandez |
-| CITATION.cff | Legal/License | 302 | phernandez | phernandez |
-| CLA.md | Legal/License | 1342 | phernandez | phernandez |
-| CLAUDE.md | Other | 12310 | Paul Hernandez | Paul Hernandez, phernandez, Ikko Eltociear Ashimin... |
-| CODE_OF_CONDUCT.md | Other | 509 | phernandez | phernandez |
-| CONTRIBUTING.md | Documentation | 7241 | phernandez | phernandez, Paul Hernandez |
-| Dockerfile | Build/Deployment | 856 | Paul Hernandez | Paul Hernandez, bm-claudeai |
-| LICENSE | Legal/License | 34523 | Paul Hernandez | Paul Hernandez |
-| README.md | Documentation | 16261 | phernandez | phernandez, bm-claudeai, Paul Hernandez, Jason Nob... |
-| SECURITY.md | Other | 303 | Paul Hernandez | Paul Hernandez |
-| docker-compose.yml | Configuration | 2534 | Paul Hernandez | Paul Hernandez, phernandez |
-| docs/AI Assistant Guide.md | Documentation | 16423 | Paul Hernandez | Paul Hernandez, phernandez |
-| docs/Docker.md | Documentation | 9088 | Paul Hernandez | Paul Hernandez, phernandez |
-| justfile | Build/Deployment | 5371 | phernandez | phernandez, Drew Cain |
-| legal_file_inventory.py | Source Code | 17407 | Unknown |  |
-| llms-install.md | Other | 2307 | phernandez | phernandez |
-| memory.json | Configuration | 90075 | phernandez | phernandez |
-| pyproject.toml | Configuration | 3279 | phernandez | phernandez, Paul Hernandez, bm-claudeai, Drew Cain... |
-| smithery.yaml | Configuration | 433 | bm-claudeai | bm-claudeai |
-| src/basic_memory/__init__.py | Source Code | 256 | phernandez | phernandez |
-| src/basic_memory/alembic/alembic.ini | Configuration | 3733 | phernandez | phernandez |
-| src/basic_memory/alembic/migrations.py | Source Code | 718 | Paul Hernandez | Paul Hernandez |
-| src/basic_memory/alembic/script.py.mako | Database/Migration | 635 | Paul Hernandez | Paul Hernandez |
-| src/basic_memory/alembic/versions/3dae7c7b1564_initial_schema.py | Source Code | 4363 | Paul Hernandez | Paul Hernandez |
-| src/basic_memory/alembic/versions/502b60eaa905_remove_required_from_entity_permalink.py | Source Code | 1840 | Paul Hernandez | Paul Hernandez |
-| src/basic_memory/alembic/versions/5fe1ab1ccebe_add_projects_table.py | Source Code | 4379 | bm-claudeai | bm-claudeai |
-| src/basic_memory/alembic/versions/647e7a75e2cd_project_constraint_fix.py | Source Code | 4210 | phernandez | phernandez |
-| src/basic_memory/alembic/versions/b3c3938bacdb_relation_to_name_unique_index.py | Source Code | 1428 | Paul Hernandez | Paul Hernandez |
-| src/basic_memory/alembic/versions/cc7172b46608_update_search_index_schema.py | Source Code | 3679 | Paul Hernandez | Paul Hernandez |
-| src/basic_memory/api/__init__.py | Source Code | 72 | phernandez | phernandez, Paul Hernandez |
-| src/basic_memory/api/app.py | Source Code | 2897 | bm-claudeai | phernandez, bm-claudeai, Paul Hernandez |
-| src/basic_memory/api/routers/__init__.py | Source Code | 398 | phernandez | phernandez, bm-claudeai |
-| src/basic_memory/api/routers/directory_router.py | Source Code | 2054 | Paul Hernandez | bm-claudeai, Paul Hernandez |
-| src/basic_memory/api/routers/importer_router.py | Source Code | 4513 | bm-claudeai | bm-claudeai |
-| src/basic_memory/api/routers/knowledge_router.py | Source Code | 9738 | Paul Hernandez | phernandez, Paul Hernandez, bm-claudeai |
-| src/basic_memory/api/routers/management_router.py | Source Code | 2730 | bm-claudeai | bm-claudeai, phernandez |
-| src/basic_memory/api/routers/memory_router.py | Source Code | 3003 | phernandez | phernandez, bm-claudeai, Paul Hernandez |
-| src/basic_memory/api/routers/project_router.py | Source Code | 8239 | bm-claudeai | bm-claudeai, phernandez, Paul Hernandez |
-| src/basic_memory/api/routers/prompt_router.py | Source Code | 9948 | bm-claudeai | bm-claudeai, phernandez |
-| src/basic_memory/api/routers/resource_router.py | Source Code | 8058 | Paul Hernandez | phernandez, Paul Hernandez |
-| src/basic_memory/api/routers/search_router.py | Source Code | 1226 | phernandez | phernandez, Paul Hernandez, bm-claudeai |
-| src/basic_memory/api/routers/utils.py | Source Code | 5159 | bm-claudeai | bm-claudeai, Drew Cain |
-| src/basic_memory/api/template_loader.py | Source Code | 8607 | bm-claudeai | bm-claudeai |
-| src/basic_memory/cli/__init__.py | Source Code | 33 | Paul Hernandez | Paul Hernandez |
-| src/basic_memory/cli/app.py | Source Code | 2268 | Paul Hernandez | Paul Hernandez, phernandez, bm-claudeai |
-| src/basic_memory/cli/commands/__init__.py | Source Code | 393 | Paul Hernandez | Paul Hernandez, phernandez |
-| src/basic_memory/cli/commands/db.py | Source Code | 1480 | Paul Hernandez | Paul Hernandez, phernandez, bm-claudeai |
-| src/basic_memory/cli/commands/import_chatgpt.py | Source Code | 2856 | Paul Hernandez | Paul Hernandez, bm-claudeai, phernandez |
-| src/basic_memory/cli/commands/import_claude_conversations.py | Source Code | 2946 | Paul Hernandez | Paul Hernandez, bm-claudeai, phernandez |
-| src/basic_memory/cli/commands/import_claude_projects.py | Source Code | 2891 | Paul Hernandez | Paul Hernandez, bm-claudeai, phernandez |
-| src/basic_memory/cli/commands/import_memory_json.py | Source Code | 2947 | Paul Hernandez | phernandez, bm-claudeai, Paul Hernandez |
-| src/basic_memory/cli/commands/mcp.py | Source Code | 2593 | phernandez | bm-claudeai, phernandez, Paul Hernandez |
-| src/basic_memory/cli/commands/project.py | Source Code | 12252 | phernandez | Paul Hernandez, phernandez, bm-claudeai |
-| src/basic_memory/cli/commands/status.py | Source Code | 5809 | phernandez | phernandez, bm-claudeai, Paul Hernandez |
-| src/basic_memory/cli/commands/sync.py | Source Code | 8213 | phernandez | phernandez, bm-claudeai, Paul Hernandez |
-| src/basic_memory/cli/commands/tool.py | Source Code | 9540 | phernandez | Paul Hernandez, phernandez, github-actions[bot] |
-| src/basic_memory/cli/main.py | Source Code | 465 | Paul Hernandez | Paul Hernandez, phernandez |
-| src/basic_memory/config.py | Source Code | 12620 | Paul Hernandez | phernandez, Paul Hernandez, bm-claudeai, Drew Cain... |
-| src/basic_memory/db.py | Source Code | 7428 | phernandez | phernandez, Paul Hernandez, Drew Cain, bm-claudeai... |
-| src/basic_memory/deps.py | Source Code | 12144 | bm-claudeai | phernandez, Paul Hernandez, bm-claudeai |
-| src/basic_memory/file_utils.py | Source Code | 6700 | phernandez | phernandez, Paul Hernandez |
-| src/basic_memory/importers/__init__.py | Source Code | 795 | bm-claudeai | bm-claudeai |
-| src/basic_memory/importers/base.py | Source Code | 2531 | bm-claudeai | bm-claudeai |
-| src/basic_memory/importers/chatgpt_importer.py | Source Code | 7372 | bm-claudeai | bm-claudeai |
-| src/basic_memory/importers/claude_conversations_importer.py | Source Code | 5725 | bm-claudeai | bm-claudeai |
-| src/basic_memory/importers/claude_projects_importer.py | Source Code | 5389 | bm-claudeai | bm-claudeai |
-| src/basic_memory/importers/memory_json_importer.py | Source Code | 3986 | bm-claudeai | bm-claudeai, phernandez |
-| src/basic_memory/importers/utils.py | Source Code | 1792 | bm-claudeai | bm-claudeai |
-| src/basic_memory/markdown/__init__.py | Source Code | 501 | phernandez | phernandez |
-| src/basic_memory/markdown/entity_parser.py | Source Code | 4516 | phernandez | phernandez, Paul Hernandez, github-actions[bot] |
-| src/basic_memory/markdown/markdown_processor.py | Source Code | 4968 | phernandez | phernandez, Paul Hernandez |
-| src/basic_memory/markdown/plugins.py | Source Code | 6639 | phernandez | phernandez, Paul Hernandez |
-| src/basic_memory/markdown/schemas.py | Source Code | 1896 | phernandez | phernandez, Paul Hernandez |
-| src/basic_memory/markdown/utils.py | Source Code | 3410 | Paul Hernandez | Paul Hernandez, phernandez |
-| src/basic_memory/mcp/__init__.py | Source Code | 35 | Paul Hernandez | Paul Hernandez |
-| src/basic_memory/mcp/async_client.py | Source Code | 925 | Paul Hernandez | phernandez, Paul Hernandez |
-| src/basic_memory/mcp/project_session.py | Source Code | 4203 | Paul Hernandez | Paul Hernandez, phernandez |
-| src/basic_memory/mcp/prompts/__init__.py | Source Code | 615 | Paul Hernandez | Paul Hernandez |
-| src/basic_memory/mcp/prompts/ai_assistant_guide.py | Source Code | 821 | Paul Hernandez | Paul Hernandez, phernandez |
-| src/basic_memory/mcp/prompts/continue_conversation.py | Source Code | 1998 | Paul Hernandez | Paul Hernandez, github-actions[bot], bm-claudeai |
-| src/basic_memory/mcp/prompts/recent_activity.py | Source Code | 3311 | Paul Hernandez | Paul Hernandez, phernandez, bm-claudeai |
-| src/basic_memory/mcp/prompts/search.py | Source Code | 1692 | Paul Hernandez | Paul Hernandez, bm-claudeai |
-| src/basic_memory/mcp/prompts/utils.py | Source Code | 5431 | Paul Hernandez | Paul Hernandez, bm-claudeai |
-| src/basic_memory/mcp/resources/ai_assistant_guide.md | Other | 14777 | phernandez | phernandez, Paul Hernandez |
-| src/basic_memory/mcp/resources/project_info.py | Source Code | 1906 | Paul Hernandez | Paul Hernandez, bm-claudeai |
-| src/basic_memory/mcp/server.py | Source Code | 1248 | Paul Hernandez | bm-claudeai, phernandez, Paul Hernandez |
-| src/basic_memory/mcp/tools/__init__.py | Source Code | 1619 | Paul Hernandez | phernandez, Paul Hernandez, Drew Cain |
-| src/basic_memory/mcp/tools/auth.py | Source Code | 1231 | phernandez | phernandez |
-| src/basic_memory/mcp/tools/canvas.py | Source Code | 3738 | Paul Hernandez | Paul Hernandez, phernandez, bm-claudeai |
-| src/basic_memory/mcp/tools/delete_note.py | Source Code | 7346 | phernandez | phernandez, Paul Hernandez, bm-claudeai |
-| src/basic_memory/mcp/tools/edit_note.py | Source Code | 13570 | Paul Hernandez | Paul Hernandez, phernandez |
-| src/basic_memory/mcp/tools/list_directory.py | Source Code | 5236 | Paul Hernandez | Paul Hernandez |
-| src/basic_memory/mcp/tools/move_note.py | Source Code | 16708 | phernandez | Paul Hernandez, phernandez |
-| src/basic_memory/mcp/tools/project_management.py | Source Code | 12944 | Paul Hernandez | Paul Hernandez, phernandez, Drew Cain |
-| src/basic_memory/mcp/tools/read_content.py | Source Code | 8596 | Paul Hernandez | Paul Hernandez, bm-claudeai |
-| src/basic_memory/mcp/tools/read_note.py | Source Code | 7614 | Paul Hernandez | Paul Hernandez, bm-claudeai, phernandez, Amadeusz ... |
-| src/basic_memory/mcp/tools/recent_activity.py | Source Code | 4833 | phernandez | Paul Hernandez, phernandez, bm-claudeai |
-| src/basic_memory/mcp/tools/search.py | Source Code | 15883 | phernandez | phernandez, github-actions[bot], Paul Hernandez, D... |
-| src/basic_memory/mcp/tools/sync_status.py | Source Code | 10517 | phernandez | phernandez |
-| src/basic_memory/mcp/tools/utils.py | Source Code | 21426 | Paul Hernandez | Paul Hernandez, phernandez, bm-claudeai |
-| src/basic_memory/mcp/tools/view_note.py | Source Code | 2499 | phernandez | phernandez |
-| src/basic_memory/mcp/tools/write_note.py | Source Code | 6178 | Paul Hernandez | Paul Hernandez, phernandez, bm-claudeai |
-| src/basic_memory/models/__init__.py | Source Code | 333 | phernandez | phernandez, Paul Hernandez, bm-claudeai |
-| src/basic_memory/models/base.py | Source Code | 225 | phernandez | phernandez, Paul Hernandez |
-| src/basic_memory/models/knowledge.py | Source Code | 7087 | phernandez | phernandez, Paul Hernandez, bm-claudeai |
-| src/basic_memory/models/project.py | Source Code | 2773 | bm-claudeai | bm-claudeai, phernandez |
-| src/basic_memory/models/search.py | Source Code | 1300 | phernandez | phernandez, Paul Hernandez, bm-claudeai |
-| src/basic_memory/repository/__init__.py | Source Code | 327 | Paul Hernandez | phernandez, bm-claudeai, Paul Hernandez |
-| src/basic_memory/repository/entity_repository.py | Source Code | 10405 | Drew Cain | phernandez, Paul Hernandez, Drew Cain, bm-claudeai... |
-| src/basic_memory/repository/observation_repository.py | Source Code | 2943 | phernandez | phernandez, bm-claudeai |
-| src/basic_memory/repository/project_info_repository.py | Source Code | 338 | Paul Hernandez | Paul Hernandez, bm-claudeai |
-| src/basic_memory/repository/project_repository.py | Source Code | 3159 | bm-claudeai | bm-claudeai |
-| src/basic_memory/repository/relation_repository.py | Source Code | 3179 | phernandez | phernandez, bm-claudeai |
-| src/basic_memory/repository/repository.py | Source Code | 15224 | phernandez | phernandez, bm-claudeai, Paul Hernandez |
-| src/basic_memory/repository/search_repository.py | Source Code | 21936 | phernandez | phernandez, Paul Hernandez, github-actions[bot], b... |
-| src/basic_memory/schemas/__init__.py | Source Code | 1674 | phernandez | phernandez, Paul Hernandez, bm-claudeai |
-| src/basic_memory/schemas/base.py | Source Code | 6738 | phernandez | phernandez, Paul Hernandez |
-| src/basic_memory/schemas/delete.py | Source Code | 1180 | phernandez | phernandez, Paul Hernandez |
-| src/basic_memory/schemas/directory.py | Source Code | 881 | bm-claudeai | bm-claudeai |
-| src/basic_memory/schemas/importer.py | Source Code | 663 | bm-claudeai | bm-claudeai |
-| src/basic_memory/schemas/memory.py | Source Code | 5833 | phernandez | phernandez, Paul Hernandez, Drew Cain, bm-claudeai... |
-| src/basic_memory/schemas/project_info.py | Source Code | 7047 | Paul Hernandez | Paul Hernandez, bm-claudeai, phernandez |
-| src/basic_memory/schemas/prompt.py | Source Code | 3648 | bm-claudeai | bm-claudeai |
-| src/basic_memory/schemas/request.py | Source Code | 3760 | Paul Hernandez | phernandez, Paul Hernandez |
-| src/basic_memory/schemas/response.py | Source Code | 6450 | phernandez | phernandez, Paul Hernandez |
-| src/basic_memory/schemas/search.py | Source Code | 3657 | phernandez | phernandez, Paul Hernandez, github-actions[bot], b... |
-| src/basic_memory/services/__init__.py | Source Code | 259 | phernandez | phernandez, Paul Hernandez, bm-claudeai |
-| src/basic_memory/services/context_service.py | Source Code | 14462 | bm-claudeai | phernandez, bm-claudeai, Paul Hernandez |
-| src/basic_memory/services/directory_service.py | Source Code | 6017 | bm-claudeai | bm-claudeai, Paul Hernandez |
-| src/basic_memory/services/entity_service.py | Source Code | 30440 | Paul Hernandez | phernandez, Paul Hernandez, bm-claudeai, Drew Cain... |
-| src/basic_memory/services/exceptions.py | Source Code | 390 | phernandez | phernandez, Paul Hernandez, bm-claudeai |
-| src/basic_memory/services/file_service.py | Source Code | 10059 | Paul Hernandez | phernandez, Paul Hernandez, bm-claudeai |
-| src/basic_memory/services/initialization.py | Source Code | 6715 | bm-claudeai | Paul Hernandez, bm-claudeai, Drew Cain, phernandez... |
-| src/basic_memory/services/link_resolver.py | Source Code | 4594 | phernandez | phernandez, Paul Hernandez, bm-claudeai, github-ac... |
-| src/basic_memory/services/project_service.py | Source Code | 28386 | bm-claudeai | bm-claudeai, Paul Hernandez, phernandez |
-| src/basic_memory/services/search_service.py | Source Code | 12782 | phernandez | phernandez, Paul Hernandez, bm-claudeai |
-| src/basic_memory/services/service.py | Source Code | 336 | phernandez | phernandez, Paul Hernandez |
-| src/basic_memory/services/sync_status_service.py | Source Code | 7504 | phernandez | phernandez, Paul Hernandez |
-| src/basic_memory/sync/__init__.py | Source Code | 156 | Paul Hernandez | Paul Hernandez, phernandez |
-| src/basic_memory/sync/background_sync.py | Source Code | 726 | bm-claudeai | bm-claudeai, phernandez |
-| src/basic_memory/sync/sync_service.py | Source Code | 23387 | Paul Hernandez | phernandez, Paul Hernandez, bm-claudeai, github-ac... |
-| src/basic_memory/sync/watch_service.py | Source Code | 15316 | Paul Hernandez | phernandez, bm-claudeai, Paul Hernandez |
-| src/basic_memory/templates/prompts/continue_conversation.hbs | Templates/Resources | 3076 | bm-claudeai | bm-claudeai, Drew Cain |
-| src/basic_memory/templates/prompts/search.hbs | Templates/Resources | 3098 | bm-claudeai | bm-claudeai |
-| src/basic_memory/utils.py | Source Code | 7657 | phernandez | phernandez, Paul Hernandez, andyxinweiminicloud, D... |
-| test-int/conftest.py | Source Code | 8203 | Paul Hernandez | Paul Hernandez, phernandez |
-| test-int/mcp/test_delete_note_integration.py | Source Code | 13175 | Paul Hernandez | Paul Hernandez, phernandez |
-| test-int/mcp/test_edit_note_integration.py | Source Code | 19822 | Paul Hernandez | Paul Hernandez, phernandez |
-| test-int/mcp/test_list_directory_integration.py | Source Code | 14744 | Paul Hernandez | Paul Hernandez, phernandez |
-| test-int/mcp/test_move_note_integration.py | Source Code | 19825 | Paul Hernandez | Paul Hernandez, phernandez |
-| test-int/mcp/test_project_management_integration.py | Source Code | 33175 | Paul Hernandez | Paul Hernandez, phernandez |
-| test-int/mcp/test_project_state_sync_integration.py | Source Code | 7728 | Paul Hernandez | Paul Hernandez, phernandez |
-| test-int/mcp/test_read_content_integration.py | Source Code | 11187 | Paul Hernandez | Paul Hernandez, phernandez |
-| test-int/mcp/test_read_note_integration.py | Source Code | 1381 | Paul Hernandez | Paul Hernandez, phernandez |
-| test-int/mcp/test_search_integration.py | Source Code | 14690 | Paul Hernandez | Paul Hernandez, phernandez |
-| test-int/mcp/test_write_note_integration.py | Source Code | 9472 | Paul Hernandez | Paul Hernandez, phernandez |
-| tests/Non-MarkdownFileSupport.pdf | Other | 106751 | Unknown |  |
-| tests/Screenshot.png | Other | 190076 | Unknown |  |
-| tests/__init__.py | Source Code | 141 | phernandez | phernandez, Paul Hernandez |
-| tests/api/conftest.py | Source Code | 1404 | phernandez | phernandez, bm-claudeai, Paul Hernandez |
-| tests/api/test_async_client.py | Source Code | 1382 | Paul Hernandez | Paul Hernandez, phernandez |
-| tests/api/test_continue_conversation_template.py | Source Code | 5152 | bm-claudeai | bm-claudeai |
-| tests/api/test_directory_router.py | Source Code | 9376 | Paul Hernandez | bm-claudeai, Paul Hernandez |
-| tests/api/test_importer_router.py | Source Code | 16578 | bm-claudeai | bm-claudeai, Paul Hernandez |
-| tests/api/test_knowledge_router.py | Source Code | 45771 | Paul Hernandez | phernandez, bm-claudeai, Paul Hernandez |
-| tests/api/test_management_router.py | Source Code | 6220 | bm-claudeai | bm-claudeai |
-| tests/api/test_memory_router.py | Source Code | 5555 | phernandez | phernandez, bm-claudeai |
-| tests/api/test_project_router.py | Source Code | 5201 | Paul Hernandez | bm-claudeai, Paul Hernandez, phernandez |
-| tests/api/test_project_router_operations.py | Source Code | 1812 | bm-claudeai | bm-claudeai, Paul Hernandez |
-| tests/api/test_prompt_router.py | Source Code | 5046 | bm-claudeai | bm-claudeai |
-| tests/api/test_resource_router.py | Source Code | 13960 | Paul Hernandez | phernandez, Paul Hernandez, bm-claudeai |
-| tests/api/test_search_router.py | Source Code | 6409 | phernandez | phernandez, bm-claudeai, Paul Hernandez, github-ac... |
-| tests/api/test_search_template.py | Source Code | 5258 | bm-claudeai | bm-claudeai |
-| tests/api/test_template_loader.py | Source Code | 8035 | bm-claudeai | bm-claudeai |
-| tests/api/test_template_loader_helpers.py | Source Code | 7445 | bm-claudeai | bm-claudeai |
-| tests/cli/conftest.py | Source Code | 1185 | Paul Hernandez | Paul Hernandez, phernandez |
-| tests/cli/test_cli_tools.py | Source Code | 13528 | Paul Hernandez | Paul Hernandez, phernandez, bm-claudeai |
-| tests/cli/test_import_chatgpt.py | Source Code | 6719 | Paul Hernandez | Paul Hernandez, bm-claudeai, phernandez |
-| tests/cli/test_import_claude_conversations.py | Source Code | 5028 | Paul Hernandez | Paul Hernandez, bm-claudeai, phernandez |
-| tests/cli/test_import_claude_projects.py | Source Code | 4585 | Paul Hernandez | Paul Hernandez, bm-claudeai, phernandez |
-| tests/cli/test_import_memory_json.py | Source Code | 3532 | Paul Hernandez | Paul Hernandez, phernandez, bm-claudeai |
-| tests/cli/test_project_commands.py | Source Code | 5143 | bm-claudeai | bm-claudeai, Paul Hernandez, phernandez |
-| tests/cli/test_project_info.py | Source Code | 3874 | phernandez | Paul Hernandez, phernandez |
-| tests/cli/test_status.py | Source Code | 4160 | Paul Hernandez | Paul Hernandez, phernandez, bm-claudeai |
-| tests/cli/test_sync.py | Source Code | 3864 | Paul Hernandez | Paul Hernandez, phernandez, bm-claudeai |
-| tests/cli/test_version.py | Source Code | 289 | Paul Hernandez | Paul Hernandez |
-| tests/conftest.py | Source Code | 15286 | phernandez | phernandez, Paul Hernandez, bm-claudeai |
-| tests/importers/test_importer_base.py | Source Code | 4329 | bm-claudeai | bm-claudeai |
-| tests/importers/test_importer_utils.py | Source Code | 1827 | bm-claudeai | bm-claudeai |
-| tests/markdown/__init__.py | Source Code | 0 | Unknown |  |
-| tests/markdown/test_entity_parser.py | Source Code | 8669 | phernandez | phernandez, Paul Hernandez, github-actions[bot] |
-| tests/markdown/test_markdown_plugins.py | Source Code | 5139 | Paul Hernandez | Paul Hernandez, phernandez |
-| tests/markdown/test_markdown_processor.py | Source Code | 5728 | phernandez | phernandez, Paul Hernandez |
-| tests/markdown/test_observation_edge_cases.py | Source Code | 4295 | phernandez | phernandez |
-| tests/markdown/test_parser_edge_cases.py | Source Code | 5142 | phernandez | phernandez |
-| tests/markdown/test_relation_edge_cases.py | Source Code | 3952 | phernandez | phernandez |
-| tests/markdown/test_task_detection.py | Source Code | 401 | Paul Hernandez | Paul Hernandez |
-| tests/mcp/conftest.py | Source Code | 1761 | phernandez | phernandez, Paul Hernandez, bm-claudeai |
-| tests/mcp/test_prompts.py | Source Code | 5989 | Paul Hernandez | Paul Hernandez, bm-claudeai, phernandez |
-| tests/mcp/test_resource_project_info.py | Source Code | 4885 | Paul Hernandez | Paul Hernandez, bm-claudeai, phernandez |
-| tests/mcp/test_resources.py | Source Code | 549 | Paul Hernandez | Paul Hernandez, phernandez |
-| tests/mcp/test_tool_canvas.py | Source Code | 7997 | Paul Hernandez | Paul Hernandez, phernandez |
-| tests/mcp/test_tool_delete_note.py | Source Code | 4208 | phernandez | phernandez |
-| tests/mcp/test_tool_edit_note.py | Source Code | 13503 | Paul Hernandez | Paul Hernandez, phernandez, Drew Cain |
-| tests/mcp/test_tool_list_directory.py | Source Code | 7730 | Paul Hernandez | Paul Hernandez, phernandez |
-| tests/mcp/test_tool_move_note.py | Source Code | 16346 | Paul Hernandez | Paul Hernandez, phernandez |
-| tests/mcp/test_tool_read_note.py | Source Code | 9741 | Paul Hernandez | Paul Hernandez, phernandez, github-actions[bot], A... |
-| tests/mcp/test_tool_recent_activity.py | Source Code | 3983 | phernandez | phernandez, bm-claudeai |
-| tests/mcp/test_tool_resource.py | Source Code | 6782 | Paul Hernandez | Paul Hernandez, phernandez, github-actions[bot] |
-| tests/mcp/test_tool_search.py | Source Code | 10959 | phernandez | Paul Hernandez, phernandez, github-actions[bot], D... |
-| tests/mcp/test_tool_sync_status.py | Source Code | 6331 | phernandez | phernandez |
-| tests/mcp/test_tool_utils.py | Source Code | 9228 | Paul Hernandez | Paul Hernandez, phernandez, bm-claudeai |
-| tests/mcp/test_tool_view_note.py | Source Code | 10004 | phernandez | phernandez |
-| tests/mcp/test_tool_write_note.py | Source Code | 19537 | Paul Hernandez | phernandez, Paul Hernandez, Drew Cain |
-| tests/repository/test_entity_repository.py | Source Code | 15498 | phernandez | phernandez, bm-claudeai, Paul Hernandez |
-| tests/repository/test_entity_repository_upsert.py | Source Code | 16983 | Drew Cain | Drew Cain, phernandez |
-| tests/repository/test_observation_repository.py | Source Code | 11786 | phernandez | phernandez, bm-claudeai |
-| tests/repository/test_project_info_repository.py | Source Code | 1186 | bm-claudeai | bm-claudeai |
-| tests/repository/test_project_repository.py | Source Code | 9455 | bm-claudeai | bm-claudeai |
-| tests/repository/test_relation_repository.py | Source Code | 11980 | phernandez | phernandez, bm-claudeai |
-| tests/repository/test_repository.py | Source Code | 5996 | phernandez | phernandez, Paul Hernandez |
-| tests/repository/test_search_repository.py | Source Code | 25471 | bm-claudeai | bm-claudeai, phernandez, Paul Hernandez |
-| tests/schemas/test_memory_url.py | Source Code | 2000 | phernandez | phernandez, Paul Hernandez |
-| tests/schemas/test_memory_url_validation.py | Source Code | 9338 | phernandez | phernandez |
-| tests/schemas/test_schemas.py | Source Code | 16880 | phernandez | phernandez, Paul Hernandez, bm-claudeai, Drew Cain... |
-| tests/schemas/test_search.py | Source Code | 3264 | phernandez | phernandez, Paul Hernandez, github-actions[bot] |
-| tests/services/test_context_service.py | Source Code | 8833 | phernandez | phernandez, bm-claudeai, Paul Hernandez |
-| tests/services/test_directory_service.py | Source Code | 6854 | Paul Hernandez | bm-claudeai, Paul Hernandez |
-| tests/services/test_entity_service.py | Source Code | 59278 | Paul Hernandez | phernandez, Paul Hernandez, bm-claudeai, Drew Cain... |
-| tests/services/test_file_service.py | Source Code | 5243 | phernandez | phernandez |
-| tests/services/test_initialization.py | Source Code | 6939 | bm-claudeai | Paul Hernandez, bm-claudeai, phernandez |
-| tests/services/test_link_resolver.py | Source Code | 13618 | phernandez | phernandez, Paul Hernandez, bm-claudeai |
-| tests/services/test_project_service.py | Source Code | 23576 | phernandez | bm-claudeai, Paul Hernandez, phernandez |
-| tests/services/test_project_service_operations.py | Source Code | 4679 | bm-claudeai | bm-claudeai, Paul Hernandez |
-| tests/services/test_search_service.py | Source Code | 25299 | Paul Hernandez | phernandez, Paul Hernandez, github-actions[bot] |
-| tests/services/test_sync_status_service.py | Source Code | 9926 | phernandez | phernandez, Paul Hernandez |
-| tests/sync/test_sync_service.py | Source Code | 39659 | phernandez | phernandez, Paul Hernandez, bm-claudeai |
-| tests/sync/test_sync_wikilink_issue.py | Source Code | 1959 | github-actions[bot] | github-actions[bot], Paul Hernandez |
-| tests/sync/test_tmp_files.py | Source Code | 5930 | Paul Hernandez | Paul Hernandez, bm-claudeai, phernandez |
-| tests/sync/test_watch_service.py | Source Code | 14076 | Paul Hernandez | Paul Hernandez, phernandez, bm-claudeai |
-| tests/sync/test_watch_service_edge_cases.py | Source Code | 2169 | Paul Hernandez | Paul Hernandez, bm-claudeai |
-| tests/test_config.py | Source Code | 3680 | Drew Cain | Drew Cain |
-| tests/test_db_migration_deduplication.py | Source Code | 6166 | Paul Hernandez | Paul Hernandez, Drew Cain, phernandez |
-| tests/utils/test_file_utils.py | Source Code | 6199 | phernandez | phernandez, Paul Hernandez |
-| tests/utils/test_parse_tags.py | Source Code | 1691 | github-actions[bot] | github-actions[bot], Paul Hernandez |
-| tests/utils/test_permalink_formatting.py | Source Code | 4193 | phernandez | phernandez, Paul Hernandez |
-| tests/utils/test_utf8_handling.py | Source Code | 5791 | phernandez | phernandez, Paul Hernandez |

memory.json

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

pyproject.toml

@@ -30,10 +30,11 @@ dependencies = [
     "alembic>=1.14.1",
     "pillow>=11.1.0",
     "pybars3>=0.9.7",
-    "fastmcp==2.10.2",
+    "fastmcp>=2.10.2",
     "pyjwt>=2.10.1",
     "python-dotenv>=1.1.0",
     "pytest-aio>=1.9.0",
+    "aiofiles>=24.1.0",  # Async file I/O
 ]
 
 
@@ -71,6 +72,7 @@ dev-dependencies = [
     "pytest-asyncio>=0.24.0",
     "pytest-xdist>=3.0.0",
     "ruff>=0.1.6",
+    "freezegun>=1.5.5",
 ]
 
 [tool.hatch.version]

scripts/generate_legal_inventory.py

@@ -1,483 +0,0 @@
-#!/usr/bin/env python3
-"""
-Legal File Inventory Generator for Basic Memory
-
-Generates comprehensive file inventory with contributor information
-for legal documentation, copyright assignments, and due diligence.
-
-Usage:
-    python scripts/generate_legal_inventory.py [options]
-
-Output formats:
-    - CSV: Detailed spreadsheet for analysis
-    - JSON: Structured data for integration
-    - Markdown: Human-readable legal report
-"""
-
-import argparse
-import csv
-import hashlib
-import json
-import subprocess
-from collections import defaultdict
-from datetime import datetime
-from pathlib import Path
-from typing import Dict, List
-
-
-class LegalInventoryGenerator:
-    """Generate comprehensive file inventory for legal documentation."""
-    
-    # Files to exclude from legal inventory
-    EXCLUDED_PATTERNS = {
-        # Generated/compiled files
-        '*.pyc', '*.pyo', '*.pyd', '__pycache__',
-        '*.so', '*.dylib', '*.dll',
-        
-        # Build/cache directories
-        'build/', 'dist/', '.eggs/', '*.egg-info/',
-        '.coverage', '.pytest_cache/', '.mypy_cache/',
-        '.ruff_cache/', '.tox/', 'venv/', '.venv/', 'env/', '.env/',
-        'node_modules/', '.npm/', '.yarn/',
-        
-        # IDE and editor files
-        '.vscode/', '.idea/', '*.swp', '*.swo', '*~',
-        '.DS_Store', 'Thumbs.db',
-        
-        # Version control
-        '.git/', '.gitignore',
-        
-        # OS generated
-        'desktop.ini', '*.tmp', '*.temp'
-    }
-    
-    # File categories for legal classification
-    FILE_CATEGORIES = {
-        'source_code': ['.py', '.pyx', '.pyi'],
-        'documentation': ['.md', '.rst', '.txt'],
-        'configuration': ['.toml', '.yaml', '.yml', '.json', '.ini', '.cfg'],
-        'legal': ['LICENSE', 'COPYING', 'COPYRIGHT', '.md'],
-        'build_deployment': ['Dockerfile', 'Makefile', 'justfile', '.sh'],
-        'database': ['.sql', '.sqlite', '.db'],
-        'templates': ['.j2', '.jinja2', '.hbs', '.handlebars'],
-        'data': ['.csv', '.json', '.xml'],
-        'other': []  # Catch-all for uncategorized files
-    }
-    
-    def __init__(self, repo_path: str = "."):
-        """Initialize generator with repository path."""
-        self.repo_path = Path(repo_path).resolve()
-        self.file_inventory: List[Dict] = []
-        self.contributors: Dict[str, Dict] = defaultdict(lambda: {
-            'email': '', 'commits': 0, 'lines_added': 0, 'files': set()
-        })
-        
-    def should_exclude_file(self, file_path: Path) -> bool:
-        """Check if file should be excluded from inventory."""
-        # Check if file is tracked by git (more efficient than check-ignore)
-        try:
-            rel_path = str(file_path.relative_to(self.repo_path))
-            result = subprocess.run([
-                'git', 'ls-files', '--error-unmatch', rel_path
-            ], capture_output=True, cwd=self.repo_path)
-            
-            # If git ls-files returns non-zero, file is not tracked (likely ignored)
-            if result.returncode != 0:
-                return True
-                
-        except Exception:
-            # Fallback to manual exclusion patterns if git fails
-            pass
-        
-        # Additional manual exclusions for safety
-        file_str = str(file_path.relative_to(self.repo_path))
-        
-        for pattern in self.EXCLUDED_PATTERNS:
-            if pattern.endswith('/'):
-                if any(part == pattern[:-1] for part in file_path.parts):
-                    return True
-            elif '*' in pattern:
-                import fnmatch
-                if fnmatch.fnmatch(file_str, pattern):
-                    return True
-            else:
-                if file_path.name == pattern or file_str == pattern:
-                    return True
-        return False
-    
-    def categorize_file(self, file_path: Path) -> str:
-        """Categorize file based on extension and name."""
-        suffix = file_path.suffix.lower()
-        name = file_path.name.upper()
-        
-        # Check legal files by name first
-        if any(legal in name for legal in ['LICENSE', 'COPYING', 'COPYRIGHT', 'CLA']):
-            return 'legal'
-            
-        # Check by extension
-        for category, extensions in self.FILE_CATEGORIES.items():
-            if suffix in extensions:
-                return category
-                
-        return 'other'
-    
-    def get_file_hash(self, file_path: Path) -> str:
-        """Generate SHA-256 hash of file content."""
-        try:
-            with open(file_path, 'rb') as f:
-                return hashlib.sha256(f.read()).hexdigest()
-        except (IOError, OSError):
-            return "ERROR_READING_FILE"
-    
-    def get_git_contributors(self, file_path: Path) -> List[Dict]:
-        """Get contributor information for a specific file."""
-        try:
-            rel_path = file_path.relative_to(self.repo_path)
-            
-            # Get contributors with line counts
-            result = subprocess.run([
-                'git', 'log', '--follow', '--pretty=format:%an|%ae|%ad|%H',
-                '--date=short', '--', str(rel_path)
-            ], capture_output=True, text=True, cwd=self.repo_path)
-            
-            if result.returncode != 0:
-                return []
-                
-            contributors = []
-            seen = set()
-            
-            for line in result.stdout.strip().split('\n'):
-                if not line:
-                    continue
-                    
-                parts = line.split('|')
-                if len(parts) >= 4:
-                    name, email, date, commit_hash = parts[:4]
-                    
-                    # Normalize author names/emails
-                    normalized_name = self.normalize_author_name(name, email)
-                    
-                    if normalized_name not in seen:
-                        contributors.append({
-                            'name': normalized_name,
-                            'email': email,
-                            'first_contribution': date,
-                            'commit_hash': commit_hash
-                        })
-                        seen.add(normalized_name)
-                        
-            return contributors
-            
-        except Exception as e:
-            print(f"Warning: Could not get git info for {file_path}: {e}")
-            return []
-    
-    def normalize_author_name(self, name: str, email: str) -> str:
-        """Normalize author names to handle multiple emails for same person."""
-        # Known mappings for Basic Memory team
-        name_mappings = {
-            'phernandez': 'Paul Hernandez',
-            'Paul Hernandez': 'Paul Hernandez',
-            'drew-cain': 'Drew Cain',
-            'Drew Cain': 'Drew Cain'
-        }
-        
-        # Handle GitHub bot accounts
-        if 'bot' in name.lower() or 'claude' in name.lower():
-            return f"{name} (AI Assistant)"
-            
-        return name_mappings.get(name, name)
-    
-    def get_file_stats(self, file_path: Path) -> Dict:
-        """Get comprehensive file statistics."""
-        try:
-            stat = file_path.stat()
-            rel_path = file_path.relative_to(self.repo_path)
-            
-            # Basic file info
-            file_info = {
-                'path': str(rel_path),
-                'name': file_path.name,
-                'size_bytes': stat.st_size,
-                'modified_time': datetime.fromtimestamp(stat.st_mtime).isoformat(),
-                'category': self.categorize_file(file_path),
-                'sha256_hash': self.get_file_hash(file_path)
-            }
-            
-            # Git information
-            contributors = self.get_git_contributors(file_path)
-            file_info['contributors'] = contributors
-            file_info['primary_author'] = contributors[0]['name'] if contributors else 'Unknown'
-            file_info['contributor_count'] = len(contributors)
-            
-            # Update global contributor stats
-            for contrib in contributors:
-                name = contrib['name']
-                self.contributors[name]['email'] = contrib['email']
-                self.contributors[name]['files'].add(str(rel_path))
-                
-            return file_info
-            
-        except Exception as e:
-            print(f"Error processing {file_path}: {e}")
-            return None
-    
-    def scan_repository(self) -> None:
-        """Scan repository and build file inventory."""
-        print(f"Scanning repository: {self.repo_path}")
-        
-        # Get all git-tracked files first (much more efficient)
-        try:
-            result = subprocess.run([
-                'git', 'ls-files'
-            ], capture_output=True, text=True, cwd=self.repo_path)
-            
-            if result.returncode == 0:
-                tracked_files = [self.repo_path / f for f in result.stdout.strip().split('\n') if f]
-                print(f"Found {len(tracked_files)} git-tracked files")
-                
-                for file_path in tracked_files:
-                    if file_path.is_file():
-                        file_info = self.get_file_stats(file_path)
-                        if file_info:
-                            self.file_inventory.append(file_info)
-            else:
-                print("Warning: Could not get git tracked files, falling back to directory scan")
-                self._fallback_scan()
-                
-        except Exception as e:
-            print(f"Warning: Git command failed ({e}), falling back to directory scan")
-            self._fallback_scan()
-        
-        # Get global git stats
-        self._get_global_git_stats()
-        
-        print(f"Processed {len(self.file_inventory)} files")
-        print(f"Found {len(self.contributors)} contributors")
-    
-    def _fallback_scan(self) -> None:
-        """Fallback directory scan if git commands fail."""
-        for file_path in self.repo_path.rglob('*'):
-            if file_path.is_file() and not self.should_exclude_file(file_path):
-                file_info = self.get_file_stats(file_path)
-                if file_info:
-                    self.file_inventory.append(file_info)
-    
-    def _get_global_git_stats(self) -> None:
-        """Get global contributor statistics from git."""
-        try:
-            # Get commit counts per author
-            result = subprocess.run([
-                'git', 'shortlog', '-sn', '--all'
-            ], capture_output=True, text=True, cwd=self.repo_path)
-            
-            if result.returncode == 0:
-                for line in result.stdout.strip().split('\n'):
-                    if line.strip():
-                        parts = line.strip().split('\t', 1)
-                        if len(parts) == 2:
-                            count, name = parts
-                            normalized_name = self.normalize_author_name(name, '')
-                            self.contributors[normalized_name]['commits'] = int(count)
-                            
-        except Exception as e:
-            print(f"Warning: Could not get global git stats: {e}")
-    
-    def generate_summary(self) -> Dict:
-        """Generate inventory summary statistics."""
-        total_files = len(self.file_inventory)
-        total_size = sum(f['size_bytes'] for f in self.file_inventory)
-        
-        # Category breakdown
-        categories = defaultdict(int)
-        for file_info in self.file_inventory:
-            categories[file_info['category']] += 1
-        
-        # Top contributors
-        top_contributors = sorted(
-            self.contributors.items(),
-            key=lambda x: len(x[1]['files']),
-            reverse=True
-        )[:10]
-        
-        return {
-            'scan_date': datetime.now().isoformat(),
-            'repository_path': str(self.repo_path),
-            'total_files': total_files,
-            'total_size_bytes': total_size,
-            'categories': dict(categories),
-            'contributor_count': len(self.contributors),
-            'top_contributors': [
-                {
-                    'name': name,
-                    'file_count': len(stats['files']),
-                    'commit_count': stats['commits'],
-                    'email': stats['email']
-                }
-                for name, stats in top_contributors
-            ]
-        }
-    
-    def export_csv(self, output_path: str) -> None:
-        """Export inventory to CSV format."""
-        with open(output_path, 'w', newline='', encoding='utf-8') as csvfile:
-            fieldnames = [
-                'path', 'name', 'category', 'size_bytes', 'modified_time',
-                'primary_author', 'contributor_count', 'contributors_list',
-                'sha256_hash'
-            ]
-            
-            writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
-            writer.writeheader()
-            
-            for file_info in sorted(self.file_inventory, key=lambda x: x['path']):
-                contributors_list = '; '.join([
-                    f"{c['name']} ({c['email']})" for c in file_info['contributors']
-                ])
-                
-                writer.writerow({
-                    'path': file_info['path'],
-                    'name': file_info['name'],
-                    'category': file_info['category'],
-                    'size_bytes': file_info['size_bytes'],
-                    'modified_time': file_info['modified_time'],
-                    'primary_author': file_info['primary_author'],
-                    'contributor_count': file_info['contributor_count'],
-                    'contributors_list': contributors_list,
-                    'sha256_hash': file_info['sha256_hash']
-                })
-        
-        print(f"CSV export saved to: {output_path}")
-    
-    def export_json(self, output_path: str) -> None:
-        """Export inventory to JSON format."""
-        # Convert sets to lists for JSON serialization
-        contributors_serializable = {}
-        for name, stats in self.contributors.items():
-            contributors_serializable[name] = {
-                'email': stats['email'],
-                'commits': stats['commits'],
-                'lines_added': stats['lines_added'],
-                'files': list(stats['files'])
-            }
-        
-        data = {
-            'summary': self.generate_summary(),
-            'files': self.file_inventory,
-            'contributors': contributors_serializable
-        }
-        
-        with open(output_path, 'w', encoding='utf-8') as jsonfile:
-            json.dump(data, jsonfile, indent=2, ensure_ascii=False)
-        
-        print(f"JSON export saved to: {output_path}")
-    
-    def export_markdown(self, output_path: str) -> None:
-        """Export inventory to Markdown format for legal documentation."""
-        summary = self.generate_summary()
-        
-        with open(output_path, 'w', encoding='utf-8') as mdfile:
-            mdfile.write("# Basic Memory - Legal File Inventory\n\n")
-            
-            # Summary section
-            mdfile.write("## Summary\n\n")
-            mdfile.write(f"**Scan Date:** {summary['scan_date']}\n")
-            mdfile.write(f"**Repository:** {summary['repository_path']}\n")
-            mdfile.write(f"**Total Files:** {summary['total_files']:,}\n")
-            mdfile.write(f"**Total Size:** {summary['total_size_bytes']:,} bytes\n")
-            mdfile.write(f"**Contributors:** {summary['contributor_count']}\n\n")
-            
-            # Category breakdown
-            mdfile.write("## File Categories\n\n")
-            for category, count in sorted(summary['categories'].items()):
-                mdfile.write(f"- **{category.replace('_', ' ').title()}:** {count} files\n")
-            mdfile.write("\n")
-            
-            # Top contributors
-            mdfile.write("## Contributors\n\n")
-            for contrib in summary['top_contributors']:
-                mdfile.write(f"- **{contrib['name']}** ({contrib['email']}): ")
-                mdfile.write(f"{contrib['file_count']} files, {contrib['commit_count']} commits\n")
-            mdfile.write("\n")
-            
-            # Detailed file listing by category
-            mdfile.write("## Detailed File Inventory\n\n")
-            
-            for category in sorted(summary['categories'].keys()):
-                category_files = [f for f in self.file_inventory if f['category'] == category]
-                if not category_files:
-                    continue
-                    
-                mdfile.write(f"### {category.replace('_', ' ').title()}\n\n")
-                
-                for file_info in sorted(category_files, key=lambda x: x['path']):
-                    mdfile.write(f"**{file_info['path']}**\n")
-                    mdfile.write(f"- Primary Author: {file_info['primary_author']}\n")
-                    mdfile.write(f"- Contributors: {file_info['contributor_count']}\n")
-                    mdfile.write(f"- Size: {file_info['size_bytes']:,} bytes\n")
-                    
-                    if file_info['contributors']:
-                        contributors_str = ', '.join([c['name'] for c in file_info['contributors']])
-                        mdfile.write(f"- All Contributors: {contributors_str}\n")
-                    
-                    mdfile.write(f"- SHA-256: `{file_info['sha256_hash']}`\n\n")
-        
-        print(f"Markdown export saved to: {output_path}")
-
-
-def main():
-    """Main entry point."""
-    parser = argparse.ArgumentParser(
-        description="Generate legal file inventory for Basic Memory repository"
-    )
-    parser.add_argument(
-        '--repo-path', '-r',
-        default='.',
-        help='Path to repository (default: current directory)'
-    )
-    parser.add_argument(
-        '--output-dir', '-o',
-        default='./legal_inventory',
-        help='Output directory for reports (default: ./legal_inventory)'
-    )
-    parser.add_argument(
-        '--formats', '-f',
-        nargs='+',
-        choices=['csv', 'json', 'markdown', 'all'],
-        default=['all'],
-        help='Output formats to generate (default: all)'
-    )
-    
-    args = parser.parse_args()
-    
-    # Create output directory
-    output_dir = Path(args.output_dir)
-    output_dir.mkdir(exist_ok=True)
-    
-    # Generate inventory
-    generator = LegalInventoryGenerator(args.repo_path)
-    generator.scan_repository()
-    
-    # Determine formats to export
-    formats = args.formats
-    if 'all' in formats:
-        formats = ['csv', 'json', 'markdown']
-    
-    # Export in requested formats
-    timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')
-    
-    if 'csv' in formats:
-        generator.export_csv(output_dir / f'basic_memory_inventory_{timestamp}.csv')
-    
-    if 'json' in formats:
-        generator.export_json(output_dir / f'basic_memory_inventory_{timestamp}.json')
-    
-    if 'markdown' in formats:
-        generator.export_markdown(output_dir / f'basic_memory_inventory_{timestamp}.md')
-    
-    print("\nLegal inventory generation complete!")
-    print(f"Output saved to: {output_dir}")
-
-
-if __name__ == '__main__':
-    main()

specs/SPEC-1 Specification-Driven Development Process.md

@@ -0,0 +1,156 @@
+---
+title: 'SPEC-1: Specification-Driven Development Process'
+type: spec
+permalink: specs/spec-1-specification-driven-development-process
+tags:
+- process
+- specification
+- development
+- meta
+---
+
+# SPEC-1: Specification-Driven Development Process
+
+## Why
+We're implementing specification-driven development to solve the complexity and circular refactoring issues in our web development process. 
+Instead of getting lost in framework details and type gymnastics, we start with clear specifications that drive implementation.
+
+The default approach of adhoc development with AI agents tends to result in:
+- Circular refactoring cycles
+- Fighting framework complexity
+- Lost context between sessions
+- Unclear requirements and scope
+
+## What
+This spec defines our process for using basic-memory as the specification engine to build basic-memory-cloud. 
+We're creating a recursive development pattern where basic-memory manages the specs that drive the development of basic-memory-cloud.
+
+**Affected Areas:**
+- All future component development
+- Architecture decisions
+- Agent collaboration workflows
+- Knowledge management and context preservation
+
+## How (High Level)
+
+### Specification Structure
+
+Name: Spec names should be numbered sequentially, followed by a description eg. `SPEC-X - Simple Description.md`.
+See: [[Spec-2: Slash Commands Reference]]
+
+Every spec is a complete thought containing:
+- **Why**: The reasoning and problem being solved
+- **What**: What is affected or changed
+- **How**: High-level approach to implementation
+- **How to Evaluate**: Testing/validation procedure
+- Additional context as needed
+
+### Living Specification Format
+
+Specifications are **living documents** that evolve throughout implementation:
+
+**Progress Tracking:**
+- **Completed items**: Use ✅ checkmark emoji for implemented features
+- **Pending items**: Use `- [ ]` GitHub-style checkboxes for remaining tasks
+- **In-progress items**: Use `- [x]` when work is actively underway
+
+**Status Philosophy:**
+- **Avoid static status headers** like "COMPLETE" or "IN PROGRESS" that become stale
+- **Use checklists within content** to show granular implementation progress
+- **Keep specs informative** while providing clear progress visibility
+- **Update continuously** as understanding and implementation evolve
+
+**Example Format:**
+```markdown
+### ComponentName
+- ✅ Basic functionality implemented
+- ✅ Props and events defined
+- - [ ] Add sorting controls
+- - [ ] Improve accessibility
+- - [x] Currently implementing responsive design
+```
+
+This creates **git-friendly progress tracking** where `[ ]` easily becomes `[x]` or ✅ when completed, and specs remain valuable throughout the development lifecycle.
+
+
+## Claude Code 
+
+We will leverage Claude Code capabilities to make the process semi-automated. 
+
+- Slash commands: define repeatable steps in the process (create spec, implement, review, etc)
+- Agents: define roles to carry out instructions  (front end developer, baskend developer, etc)
+- MCP tools: enable agents to implement specs via actions (write code, test, etc)
+
+### Workflow
+1. **Create**: Write spec as complete thought in `/specs` folder
+2. **Discuss**: Iterate and refine through agent collaboration
+3. **Implement**: Hand spec to appropriate specialist agent
+4. **Validate**: Review implementation against spec criteria
+5. **Document**: Update spec with learnings and decisions
+
+### Slash Commands
+
+Claude slash commands are used to manage the flow.
+These are simple instructions to help make the process uniform. 
+They can be updated and refined as needed. 
+
+- `/spec create [name]` - Create new specification
+- `/spec status` - Show current spec states
+- `/spec implement [name]` - Hand to appropriate agent
+- `/spec review [name]` - Validate implementation
+
+### Agent Orchestration
+
+Agents are defined with clear roles, for instance:
+
+- **system-architect**: Creates high-level specs, ADRs, architectural decisions
+- **vue-developer**: Component specs, UI patterns, frontend architecture
+- **python-developer**: Implementation specs, technical details, backend logic
+- 
+- Each agent reads/updates specs through basic-memory tools. 
+
+## How to Evaluate
+
+### Success Criteria
+- Specs provide clear, actionable guidance for implementation
+- Reduced circular refactoring and scope creep
+- Persistent context across development sessions
+- Clean separation between "what/why" and implementation details
+- Specs record a history of what happened and why for historical context
+
+### Testing Procedure
+1. Create a spec for an existing problematic component
+2. Have an agent implement following only the spec
+3. Compare result quality and development speed vs. ad-hoc approach
+4. Measure context preservation across sessions
+5. Evaluate spec clarity and completeness
+
+### Metrics
+- Time from spec to working implementation
+- Number of refactoring cycles required
+- Agent understanding of requirements
+- Spec reusability for similar components
+
+## Notes
+- Start simple: specs are just complete thoughts, not heavy processes
+- Use basic-memory's knowledge graph to link specs, decisions, components
+- Let the process evolve naturally based on what works
+- Focus on solving the actual problem: Manage complexity in development
+
+## Observations
+
+- [problem] Web development without clear goals and documentation circular refactoring cycles #complexity
+- [solution] Specification-driven development reduces scope creep and context loss #process-improvement  
+- [pattern] basic-memory as specification engine creates recursive development loop #meta-development
+- [workflow] Five-step process: Create → Discuss → Implement → Validate → Document #methodology
+- [tool] Slash commands provide uniform process automation #automation
+- [agent-pattern] Three specialized agents handle different implementation domains #specialization
+- [success-metric] Time from spec to working implementation measures process efficiency #measurement
+- [learning] Process should evolve naturally based on what works in practice #adaptation
+- [format] Living specifications use checklists for progress tracking instead of static status headers #documentation
+- [evolution] Specs evolve throughout implementation maintaining value as working documents #continuous-improvement
+
+## Relations
+
+- spec [[Spec-2: Slash Commands Reference]]
+- spec [[Spec-3: Agent Definitions]]

specs/SPEC-11 Basic Memory API Performance Optimization.md

@@ -0,0 +1,245 @@
+---
+title: 'SPEC-11: Basic Memory API Performance Optimization'
+type: spec
+permalink: specs/spec-11-basic-memory-api-performance-optimization
+tags:
+- performance
+- api
+- mcp
+- database
+- cloud
+---
+
+# SPEC-11: Basic Memory API Performance Optimization
+
+## Why
+
+The Basic Memory API experiences significant performance issues in cloud environments due to expensive per-request initialization. MCP tools making
+HTTP requests to the API suffer from 350ms-2.6s latency overhead **before** any actual operation occurs.
+
+**Root Cause Analysis:**
+- GitHub Issue #82 shows repeated initialization sequences in logs (16:29:35 and 16:49:58)
+- Each MCP tool call triggers full database initialization + project reconciliation
+- `get_engine_factory()` dependency calls `db.get_or_create_db()` on every request
+- `reconcile_projects_with_config()` runs expensive sync operations repeatedly
+
+**Performance Impact:**
+- Database connection setup: ~50-100ms per request
+- Migration checks: ~100-500ms per request
+- Project reconciliation: ~200ms-2s per request
+- **Total overhead**: ~350ms-2.6s per MCP tool call
+
+This creates compounding effects with tenant auto-start delays and increases timeout risk in cloud deployments.
+
+Github issue: https://github.com/basicmachines-co/basic-memory-cloud/issues/82
+
+## What
+
+This optimization affects the **core basic-memory repository** components:
+
+1. **API Lifespan Management** (`src/basic_memory/api/app.py`)
+ - Cache database connections in app state during startup
+ - Avoid repeated expensive initialization
+
+2. **Dependency Injection** (`src/basic_memory/deps.py`)
+ - Modify `get_engine_factory()` to use cached connections
+ - Eliminate per-request database setup
+
+3. **Initialization Service** (`src/basic_memory/services/initialization.py`)
+ - Add caching/throttling to project reconciliation
+ - Skip expensive operations when appropriate
+
+4. **Configuration** (`src/basic_memory/config.py`)
+ - Add optional performance flags for cloud environments
+
+**Backwards Compatibility**: All changes must be backwards compatible with existing CLI and non-cloud usage.
+
+## How (High Level)
+
+### Phase 1: Cache Database Connections (Critical - 80% of gains)
+
+**Problem**: `get_engine_factory()` calls `db.get_or_create_db()` per request
+**Solution**: Cache database engine/session in app state during lifespan
+
+1. **Modify API Lifespan** (`api/app.py`):
+ ```python
+ @asynccontextmanager
+ async def lifespan(app: FastAPI):
+     app_config = ConfigManager().config
+     await initialize_app(app_config)
+
+     # Cache database connection in app state
+     engine, session_maker = await db.get_or_create_db(app_config.database_path)
+     app.state.engine = engine
+     app.state.session_maker = session_maker
+
+     # ... rest of startup logic
+```
+
+2. Modify Dependency Injection (deps.py):
+```python
+async def get_engine_factory(
+  request: Request
+) -> tuple[AsyncEngine, async_sessionmaker[AsyncSession]]:
+  """Get cached engine and session maker from app state."""
+  return request.app.state.engine, request.app.state.session_maker
+```
+Phase 2: Optimize Project Reconciliation (Secondary - 20% of gains)
+
+Problem: reconcile_projects_with_config() runs expensive sync repeatedly
+Solution: Add module-level caching with time-based throttling
+
+1. Add Reconciliation Cache (services/initialization.py):
+```ptyhon
+_project_reconciliation_completed = False
+_last_reconciliation_time = 0
+
+async def reconcile_projects_with_config(app_config, force=False):
+  # Skip if recently completed (within 60 seconds) unless forced
+  if recently_completed and not force:
+      return
+  # ... existing logic
+```
+Phase 3: Cloud Environment Flags (Optional)
+
+Problem: Force expensive initialization in production environments
+Solution: Add skip flags for cloud/stateless deployments
+
+1. Add Config Flag (config.py):
+skip_initialization_sync: bool = Field(default=False)
+2. Configure in Cloud (basic-memory-cloud integration):
+BASIC_MEMORY_SKIP_INITIALIZATION_SYNC=true
+
+How to Evaluate
+
+Success Criteria
+
+1. Performance Metrics (Primary):
+- MCP tool response time reduced by 50%+ (measure before/after)
+- Database connection overhead eliminated (0ms vs 50-100ms)
+- Migration check overhead eliminated (0ms vs 100-500ms)
+- Project reconciliation overhead reduced by 90%+
+2. Load Testing:
+- Concurrent MCP tool calls maintain performance
+- No memory leaks in cached connections
+- Database connection pool behaves correctly
+3. Functional Correctness:
+- All existing API endpoints work identically
+- MCP tools maintain full functionality
+- CLI operations unaffected
+- Database migrations still execute properly
+4. Backwards Compatibility:
+- No breaking changes to existing APIs
+- Config changes are optional with safe defaults
+- Non-cloud deployments work unchanged
+
+Testing Strategy
+
+Performance Testing:
+# Before optimization
+time basic-memory-mcp-tools write_note "test" "content" "folder"
+# Measure: ~1-3 seconds
+
+# After optimization  
+time basic-memory-mcp-tools write_note "test" "content" "folder"
+# Target: <500ms
+
+Load Testing:
+# Multiple concurrent MCP tool calls
+for i in {1..10}; do
+basic-memory-mcp-tools search "test" &
+done
+wait
+# Verify: No degradation, consistent response times
+
+Regression Testing:
+# Full basic-memory test suite
+just test
+# All tests must pass
+
+# Integration tests with cloud deployment
+# Verify MCP gateway → API → database flow works
+
+Validation Checklist
+
+- Phase 1 Complete: Database connections cached, dependency injection optimized
+- Performance Benchmark: 50%+ improvement in MCP tool response times
+- Memory Usage: No leaks in cached connections over 24h+ periods
+- Stress Testing: 100+ concurrent requests maintain performance
+- Backwards Compatibility: All existing functionality preserved
+- Documentation: Performance optimization documented in README
+- Cloud Integration: basic-memory-cloud sees performance benefits
+
+## Implementation Status ✅ COMPLETED
+
+**Implementation Date**: 2025-09-26
+**Branch**: `feature/spec-11-api-performance-optimization`
+**Commit**: `771f60b`
+
+### ✅ Phase 1: Database Connection Caching - IMPLEMENTED
+
+**Files Modified:**
+- `src/basic_memory/api/app.py` - Added database connection caching in app.state
+- `src/basic_memory/deps.py` - Updated get_engine_factory() to use cached connections
+- `src/basic_memory/config.py` - Added skip_initialization_sync configuration flag
+
+**Implementation Details:**
+1. **API Lifespan Caching**: Database engine and session_maker cached in app.state during startup
+2. **Dependency Injection Optimization**: get_engine_factory() now returns cached connections instead of calling get_or_create_db()
+3. **Project Reconciliation Removal**: Eliminated expensive reconcile_projects_with_config() from API startup
+4. **CLI Fallback Preserved**: Non-API contexts continue to work with fallback database initialization
+
+### ✅ Performance Validation - ACHIEVED
+
+**Live Testing Results** (2025-09-26 14:03-14:09):
+
+| Operation | Before | After | Improvement |
+|-----------|--------|-------|-------------|
+| `read_note` | 350ms-2.6s | **20ms** | **95-99% faster** |
+| `edit_note` | 350ms-2.6s | **218ms** | **75-92% faster** |
+| `search_notes` | 350ms-2.6s | **<500ms** | **Responsive** |
+| `list_memory_projects` | N/A | **<100ms** | **Fast** |
+
+**Key Achievements:**
+- ✅ **95-99% improvement** in read operations (primary workflow)
+- ✅ **75-92% improvement** in edit operations
+- ✅ **Zero overhead** for project switching
+- ✅ **Database connection overhead eliminated** (0ms vs 50-100ms)
+- ✅ **Project reconciliation delays removed** from API requests
+- ✅ **<500ms target achieved** for all operations except write (which includes file sync)
+
+### ✅ Backwards Compatibility - MAINTAINED
+
+- All existing functionality preserved
+- CLI operations unaffected
+- Fallback for non-API contexts maintained
+- No breaking changes to existing APIs
+- Optional configuration with safe defaults
+
+### ✅ Testing Validation - PASSED
+
+- Integration tests passing
+- Type checking clear
+- Linting checks passed
+- Live testing with real MCP tools successful
+- Multi-project workflows validated
+- Rapid project switching validated
+
+## Notes
+
+Implementation Priority:
+- ✅ Phase 1 COMPLETED: Database connection caching provides 95%+ performance gains
+- ⚪ Phase 2 NOT NEEDED: Project reconciliation removal achieved the goals
+- ⚪ Phase 3 INCLUDED: skip_initialization_sync flag added
+
+Risk Mitigation:
+- ✅ All changes backwards compatible implemented
+- ✅ Gradual implementation successful (Phase 1 → validation)
+- ✅ Easy rollback via configuration flags available
+
+Cloud Integration:
+- ✅ This optimization directly addresses basic-memory-cloud issue #82
+- ✅ Changes in core basic-memory will benefit all cloud tenants
+- ✅ No changes needed in basic-memory-cloud itself
+
+**Result**: SPEC-11 performance optimizations successfully implemented and validated. The 95-99% improvement in MCP tool response times exceeds the original 50-80% target, providing exceptional performance gains for cloud deployments and local usage.

specs/SPEC-14- Cloud Git Versioning & GitHub Backup.md

@@ -0,0 +1,210 @@
+---
+title: 'SPEC-14: Cloud Git Versioning & GitHub Backup'
+type: spec
+permalink: specs/spec-14-cloud-git-versioning
+tags:
+- git
+- github
+- backup
+- versioning
+- cloud
+related:
+- specs/spec-9-multi-project-bisync
+- specs/spec-9-follow-ups-conflict-sync-and-observability
+status: deferred
+---
+
+# SPEC-14: Cloud Git Versioning & GitHub Backup
+
+**Status: DEFERRED** - Postponed until multi-user/teams feature development. Using S3 versioning (SPEC-9.1) for v1 instead.
+
+## Why Deferred
+
+**Original goals can be met with simpler solutions:**
+- Version history → **S3 bucket versioning** (automatic, zero config)
+- Offsite backup → **Tigris global replication** (built-in)
+- Restore capability → **S3 version restore** (`bm cloud restore --version-id`)
+- Collaboration → **Deferred to teams/multi-user feature** (not v1 requirement)
+
+**Complexity vs value trade-off:**
+- Git integration adds: committer service, puller service, webhooks, LFS, merge conflicts
+- Risk: Loop detection between Git ↔ rclone bisync ↔ local edits
+- S3 versioning gives 80% of value with 5% of complexity
+
+**When to revisit:**
+- Teams/multi-user features (PR-based collaboration workflow)
+- User requests for commit messages and branch-based workflows
+- Need for fine-grained audit trail beyond S3 object metadata
+
+---
+
+## Original Specification (for reference)
+
+## Why
+Early access users want **transparent version history**, easy **offsite backup**, and a familiar **restore/branching** workflow. Git/GitHub integration would provide:
+- Auditable history of every change (who/when/why)
+- Branches/PRs for review and collaboration
+- Offsite private backup under the user's control
+- Escape hatch: users can always `git clone` their knowledge base
+
+**Note:** These goals are now addressed via S3 versioning (SPEC-9.1) for single-user use case.
+
+## Goals
+- **Transparent**: Users keep using Basic Memory; Git runs behind the scenes.
+- **Private**: Push to a **private GitHub repo** that the user owns (or tenant org).
+- **Reliable**: No data loss, deterministic mapping of filesystem ↔ Git.
+- **Composable**: Plays nicely with SPEC‑9 bisync and upcoming conflict features (SPEC‑9 Follow‑Ups).
+
+**Non‑Goals (for v1):**
+- Fine‑grained per‑file encryption in Git history (can be layered later).
+- Large media optimization beyond Git LFS defaults.
+
+## User Stories
+1. *As a user*, I connect my GitHub and choose a private backup repo.
+2. *As a user*, every change I make in cloud (or via bisync) is **committed** and **pushed** automatically.
+3. *As a user*, I can **restore** a file/folder/project to a prior version.
+4. *As a power user*, I can **git pull/push** directly to collaborate outside the app.
+5. *As an admin*, I can enforce repo ownership (tenant org) and least‑privilege scopes.
+
+## Scope
+- **In scope:** Full repo backup of `/app/data/` (all projects) with optional selective subpaths.
+- **Out of scope (v1):** Partial shallow mirrors; encrypted Git; cross‑provider SCM (GitLab/Bitbucket).
+
+## Architecture
+### Topology
+- **Authoritative working tree**: `/app/data/` (bucket mount) remains the source of truth (SPEC‑9).
+- **Bare repo** lives alongside: `/app/git/${tenant}/knowledge.git` (server‑side).
+- **Mirror remote**: `github.com/<owner>/<repo>.git` (private).
+
+```mermaid
+flowchart LR
+  A[/Users & Agents/] -->|writes/edits| B[/app/data/]
+  B -->|file events| C[Committer Service]
+  C -->|git commit| D[(Bare Repo)]
+  D -->|push| E[(GitHub Private Repo)]
+  E -->|webhook (push)| F[Puller Service]
+  F -->|git pull/merge| D
+  D -->|checkout/merge| B
+```
+
+### Services
+- **Committer Service** (daemon):
+  - Watches `/app/data/` for changes (inotify/poll)
+  - Batches changes (debounce e.g. 2–5s)
+  - Writes `.bmmeta` (if present) into commit message trailer (see Follow‑Ups)
+  - `git add -A && git commit -m "chore(sync): <summary>
+
+BM-Meta: <json>"`
+  - Periodic `git push` to GitHub mirror (configurable interval)
+- **Puller Service** (webhook target):
+  - Receives GitHub webhook (push) → `git fetch`
+  - **Fast‑forward** merges to `main` only; reject non‑FF unless policy allows
+  - Applies changes back to `/app/data/` via clean checkout
+  - Emits sync events for Basic Memory indexers
+
+### Auth & Security
+- **GitHub App** (recommended): minimal scopes: `contents:read/write`, `metadata:read`, webhook.
+- Tenant‑scoped installation; repo created in user account or tenant org.
+- Tokens stored in KMS/secret manager; rotated automatically.
+- Optional policy: allow only **FF merges** on `main`; non‑FF requires PR.
+
+### Repo Layout
+- **Monorepo** (default): one repo per tenant mirrors `/app/data/` with subfolders per project.
+- Optional multi‑repo mode (later): one repo per project.
+
+### File Handling
+- Honor `.gitignore` generated from `.bmignore.rclone` + BM defaults (cache, temp, state).
+- **Git LFS** for large binaries (images, media) — auto track by extension/size threshold.
+- Normalize newline + Unicode (aligns with Follow‑Ups).
+
+### Conflict Model
+- **Primary concurrency**: SPEC‑9 Follow‑Ups (`.bmmeta`, conflict copies) stays the first line of defense.
+- **Git merges** are a **secondary** mechanism:
+  - Server only auto‑merges **text** conflicts when trivial (FF or clean 3‑way).
+  - Otherwise, create `name (conflict from <branch>, <ts>).md` and surface via events.
+
+### Data Flow vs Bisync
+- Bisync (rclone) continues between local sync dir ↔ bucket.
+- Git sits **cloud‑side** between bucket and GitHub.
+- On **pull** from GitHub → files written to `/app/data/` → picked up by indexers & eventually by bisync back to users.
+
+## CLI & UX
+New commands (cloud mode):
+- `bm cloud git connect` — Launch GitHub App installation; create private repo; store installation id.
+- `bm cloud git status` — Show connected repo, last push time, last webhook delivery, pending commits.
+- `bm cloud git push` — Manual push (rarely needed).
+- `bm cloud git pull` — Manual pull/FF (admin only by default).
+- `bm cloud snapshot -m "message"` — Create a tagged point‑in‑time snapshot (git tag).
+- `bm restore <path> --to <commit|tag>` — Restore file/folder/project to prior version.
+
+Settings:
+- `bm config set git.autoPushInterval=5s`
+- `bm config set git.lfs.sizeThreshold=10MB`
+- `bm config set git.allowNonFF=false`
+
+## Migration & Backfill
+- On connect, if repo empty: initial commit of entire `/app/data/`.
+- If repo has content: require **one‑time import** path (clone to staging, reconcile, choose direction).
+
+## Edge Cases
+- Massive deletes: gated by SPEC‑9 `max_delete` **and** Git pre‑push hook checks.
+- Case changes and rename detection: rely on git rename heuristics + Follow‑Ups move hints.
+- Secrets: default ignore common secret patterns; allow custom deny list.
+
+## Telemetry & Observability
+- Emit `git_commit`, `git_push`, `git_pull`, `git_conflict` events with correlation IDs.
+- `bm sync --report` extended with Git stats (commit count, delta bytes, push latency).
+
+## Phased Plan
+### Phase 0 — Prototype (1 sprint)
+- Server: bare repo init + simple committer (batch every 10s) + manual GitHub token.
+- CLI: `bm cloud git connect --token <PAT>` (dev‑only)
+- Success: edits in `/app/data/` appear in GitHub within 30s.
+
+### Phase 1 — GitHub App & Webhooks (1–2 sprints)
+- Switch to GitHub App installs; create private repo; store installation id.
+- Committer hardened (debounce 2–5s, backoff, retries).
+- Puller service with webhook → FF merge → checkout to `/app/data/`.
+- LFS auto‑track + `.gitignore` generation.
+- CLI surfaces status + logs.
+
+### Phase 2 — Restore & Snapshots (1 sprint)
+- `bm restore` for file/folder/project with dry‑run.
+- `bm cloud snapshot` tags + list/inspect.
+- Policy: PR‑only non‑FF, admin override.
+
+### Phase 3 — Selective & Multi‑Repo (nice‑to‑have)
+- Include/exclude projects; optional per‑project repos.
+- Advanced policies (branch protections, required reviews).
+
+## Acceptance Criteria
+- Changes to `/app/data/` are committed and pushed automatically within configurable interval (default ≤5s).
+- GitHub webhook pull results in updated files in `/app/data/` (FF‑only by default).
+- LFS configured and functioning; large files don't bloat history.
+- `bm cloud git status` shows connected repo and last push/pull times.
+- `bm restore` restores a file/folder to a prior commit with a clear audit trail.
+- End‑to‑end works alongside SPEC‑9 bisync without loops or data loss.
+
+## Risks & Mitigations
+- **Loop risk (Git ↔ Bisync)**: Writes to `/app/data/` → bisync → local → user edits → back again. *Mitigation*: Debounce, commit squashing, idempotent `.bmmeta` versioning, and watch exclusion windows during pull.
+- **Repo bloat**: Lots of binary churn. *Mitigation*: default LFS, size threshold, optional media‑only repo later.
+- **Security**: Token leakage. *Mitigation*: GitHub App with short‑lived tokens, KMS storage, scoped permissions.
+- **Merge complexity**: Non‑trivial conflicts. *Mitigation*: prefer FF; otherwise conflict copies + events; require PR for non‑FF.
+
+## Open Questions
+- Do we default to **monorepo** per tenant, or offer project‑per‑repo at connect time?
+- Should `restore` write to a branch and open a PR, or directly modify `main`?
+- How do we expose Git history in UI (timeline view) without users dropping to CLI?
+
+## Appendix: Sample Config
+```json
+{
+  "git": {
+    "enabled": true,
+    "repo": "https://github.com/<owner>/<repo>.git",
+    "autoPushInterval": "5s",
+    "allowNonFF": false,
+    "lfs": { "sizeThreshold": 10485760 }
+  }
+}
+```

specs/SPEC-2 Slash Commands Reference.md

@@ -0,0 +1,120 @@
+---
+title: 'SPEC-2: Slash Commands Reference'
+type: spec
+permalink: specs/spec-2-slash-commands-reference
+tags:
+- commands
+- process
+- reference
+---
+
+# SPEC-2: Slash Commands Reference
+
+This document defines the slash commands used in our specification-driven development process.
+
+## /spec create [name]
+
+**Purpose**: Create a new specification document
+
+**Usage**: `/spec create notes-decomposition`
+
+**Process**:
+1. Create new spec document in `/specs` folder
+2. Use SPEC-XXX numbering format (auto-increment)
+3. Include standard spec template:
+   - Why (reasoning/problem)
+   - What (affected areas)
+   - How (high-level approach)
+   - How to Evaluate (testing/validation)
+4. Tag appropriately for knowledge graph
+5. Link to related specs/components
+
+**Template**:
+```markdown
+# SPEC-XXX: [Title]
+
+## Why
+[Problem statement and reasoning]
+
+## What
+[What is affected or changed]
+
+## How (High Level)
+[Approach to implementation]
+
+## How to Evaluate
+[Testing/validation procedure]
+
+## Notes
+[Additional context as needed]
+```
+
+## /spec status
+
+**Purpose**: Show current status of all specifications
+
+**Usage**: `/spec status`
+
+**Process**:
+1. Search all specs in `/specs` folder
+2. Display table showing:
+   - Spec number and title
+   - Status (draft, approved, implementing, complete)
+   - Assigned agent (if any)
+   - Last updated
+   - Dependencies
+
+## /spec implement [name]
+
+**Purpose**: Hand specification to appropriate agent for implementation
+
+**Usage**: `/spec implement SPEC-002`
+
+**Process**:
+1. Read the specified spec
+2. Analyze requirements to determine appropriate agent:
+   - Frontend components → vue-developer
+   - Architecture/system design → system-architect  
+   - Backend/API → python-developer
+3. Launch agent with spec context
+4. Agent creates implementation plan
+5. Update spec with implementation status
+
+## /spec review [name]
+
+**Purpose**: Review implementation against specification criteria
+
+**Usage**: `/spec review SPEC-002`
+
+**Process**:
+1. Read original spec and "How to Evaluate" section
+2. Examine current implementation
+3. Test against success criteria
+4. Document gaps or issues
+5. Update spec with review results
+6. Recommend next actions (complete, revise, iterate)
+
+## Command Extensions
+
+As the process evolves, we may add:
+- `/spec link [spec1] [spec2]` - Create dependency links
+- `/spec archive [name]` - Archive completed specs
+- `/spec template [type]` - Create spec from template
+- `/spec search [query]` - Search spec content
+
+## References
+
+- Claude Slash commands: https://docs.anthropic.com/en/docs/claude-code/slash-commands
+
+## Creating a command
+
+Commands are implemented as Claude slash commands: 
+
+Location in repo: .claude/commands/
+
+In the following example, we create the /optimize command:
+```bash
+# Create a project command
+mkdir -p .claude/commands
+echo "Analyze this code for performance issues and suggest optimizations:" > .claude/commands/optimize.md
+```

specs/SPEC-3 Agent Definitions.md

@@ -0,0 +1,108 @@
+---
+title: 'SPEC-3: Agent Definitions'
+type: spec
+permalink: specs/spec-3-agent-definitions
+tags:
+- agents
+- roles
+- process
+---
+
+# SPEC-3: Agent Definitions
+
+This document defines the specialist agents used in our specification-driven development process.
+
+## system-architect
+
+**Role**: High-level system design and architectural decisions
+
+**Responsibilities**:
+- Create architectural specifications and ADRs
+- Analyze system-wide impacts and trade-offs
+- Design component interfaces and data flow
+- Evaluate technical approaches and patterns
+- Document architectural decisions and rationale
+
+**Expertise Areas**:
+- System architecture and design patterns
+- Technology evaluation and selection
+- Scalability and performance considerations
+- Integration patterns and API design
+- Technical debt and refactoring strategies
+
+**Typical Specs**:
+- System architecture overviews
+- Component decomposition strategies
+- Data flow and state management
+- Integration and deployment patterns
+
+## vue-developer
+
+**Role**: Frontend component development and UI implementation
+
+**Responsibilities**:
+- Create Vue.js component specifications
+- Implement responsive UI components
+- Design component APIs and interfaces
+- Optimize for performance and accessibility
+- Document component usage and patterns
+
+**Expertise Areas**:
+- Vue.js 3 Composition API
+- Nuxt 3 framework patterns
+- shadcn-vue component library
+- Responsive design and CSS
+- TypeScript integration
+- State management with Pinia
+
+**Typical Specs**:
+- Individual component specifications
+- UI pattern libraries
+- Responsive design approaches
+- Component interaction flows
+
+## python-developer
+
+**Role**: Backend development and API implementation
+
+**Responsibilities**:
+- Create backend service specifications
+- Implement APIs and data processing
+- Design database schemas and queries
+- Optimize performance and reliability
+- Document service interfaces and behavior
+
+**Expertise Areas**:
+- FastAPI and Python web frameworks
+- Database design and operations
+- API design and documentation
+- Authentication and security
+- Performance optimization
+- Testing and validation
+
+**Typical Specs**:
+- API endpoint specifications
+- Database schema designs
+- Service integration patterns
+- Performance optimization strategies
+
+## Agent Collaboration Patterns
+
+### Handoff Protocol
+1. Agent receives spec through `/spec implement [name]`
+2. Agent reviews spec and creates implementation plan
+3. Agent documents progress and decisions in spec
+4. Agent hands off to another agent if cross-domain work needed
+5. Final agent updates spec with completion status
+
+### Communication Standards
+- All agents update specs through basic-memory MCP tools
+- Document decisions and trade-offs in spec notes
+- Link related specs and components
+- Preserve context for future reference
+
+### Quality Standards
+- Follow existing codebase patterns and conventions
+- Write tests that validate spec requirements
+- Document implementation choices
+- Consider maintainability and extensibility

specs/SPEC-5 CLI Cloud Upload via WebDAV.md

@@ -0,0 +1,201 @@
+---
+title: 'SPEC-5: CLI Cloud Upload via WebDAV'
+type: spec
+permalink: specs/spec-5-cli-cloud-upload-via-webdav
+tags:
+- cli
+- webdav
+- upload
+- migration
+- poc
+---
+
+# SPEC-5: CLI Cloud Upload via WebDAV
+
+## Why
+
+Existing basic-memory users need a simple migration path to basic-memory-cloud. The web UI drag-and-drop approach outlined in GitHub issue #59, while user-friendly, introduces significant complexity for a proof-of-concept:
+
+- Complex web UI components for file upload and progress tracking
+- Browser file handling limitations and CORS complexity
+- Proxy routing overhead for large file transfers
+- Authentication integration across multiple services
+
+A CLI-first approach solves these issues by:
+
+- **Leveraging existing infrastructure**: Both cloud CLI and tenant API already exist with WorkOS JWT authentication
+- **Familiar user experience**: Basic-memory users are CLI-comfortable and expect command-line tools
+- **Direct connection efficiency**: Bypassing the MCP gateway/proxy for bulk file transfers
+- **Rapid implementation**: Building on existing `CLIAuth` and FastAPI foundations
+
+The fundamental problem is migration friction - users have local basic-memory projects but no path to cloud tenants. A simple CLI upload command removes this barrier immediately.
+
+## What
+
+This spec defines a CLI-based project upload system using WebDAV for direct tenant connections.
+
+**Affected Areas:**
+- `apps/cloud/src/basic_memory_cloud/cli/main.py` - Add upload command to existing CLI
+- `apps/api/src/basic_memory_cloud_api/main.py` - Add WebDAV endpoints to tenant FastAPI
+- Authentication flow - Reuse existing WorkOS JWT validation
+- File transfer protocol - WebDAV for cross-platform compatibility
+
+**Core Components:**
+
+### CLI Upload Command
+```bash
+basic-memory-cloud upload <project-path> --tenant-url https://basic-memory-{tenant}.fly.dev
+```
+
+### WebDAV Server Endpoints
+- `GET/PUT/DELETE /webdav/*` - Standard WebDAV operations on tenant file system
+- Authentication via existing JWT validation
+- File operations preserve timestamps and directory structure
+
+### Authentication Flow
+```
+1. User runs `basic-memory-cloud login` (existing)
+2. CLI stores WorkOS JWT token (existing)
+3. Upload command reads JWT from storage
+4. WebDAV requests include JWT in Authorization header
+5. Tenant API validates JWT using existing middleware
+```
+
+## How (High Level)
+
+### Implementation Strategy
+
+**Phase 1: CLI Command**
+- Add `upload` command to existing Typer app
+- Reuse `CLIAuth` class for token management
+- Implement WebDAV client using `webdavclient3` or similar
+- Rich progress bars for transfer feedback
+
+**Phase 2: WebDAV Server**
+- Add WebDAV endpoints to existing tenant FastAPI app
+- Leverage existing `get_current_user` dependency for authentication
+- Map WebDAV operations to tenant file system
+- Preserve file modification times using `os.utime()`
+
+**Phase 3: Integration**
+- Direct connection bypasses MCP gateway and proxy
+- Simple conflict resolution: overwrite existing files
+- Error handling: fail fast with clear error messages
+
+### Technical Architecture
+
+```
+basic-memory-cloud CLI → WorkOS JWT → Direct WebDAV → Tenant FastAPI
+                                                    ↓
+                                               Tenant File System
+```
+
+**Key Libraries:**
+- CLI: `webdavclient3` for WebDAV client operations
+- API: `wsgidav` or FastAPI-compatible WebDAV server
+- Progress: `rich` library (already imported in CLI)
+- Auth: Existing WorkOS JWT infrastructure
+
+### WebDAV Protocol Choice
+
+WebDAV provides:
+- **Cross-platform clients**: Native support in most operating systems
+- **Standardized protocol**: Well-defined for file operations
+- **HTTP-based**: Works with existing FastAPI and JWT auth
+- **Library support**: Good Python libraries for both client and server
+
+### POC Constraints
+
+**Simplifications for rapid implementation:**
+- **Known tenant URLs**: Assume `https://basic-memory-{tenant}.fly.dev` format
+- **Upload only**: No download or bidirectional sync
+- **Overwrite conflicts**: No merge or conflict resolution prompting
+- **No fallbacks**: Fail fast if WebDAV connection issues occur
+- **Direct connection only**: No proxy fallback mechanism
+
+## How to Evaluate
+
+### Success Criteria
+
+**Functional Requirements:**
+- [ ] Transfer complete basic-memory project (100+ files) in < 30 seconds
+- [ ] Preserve directory structure exactly as in source project
+- [ ] Preserve file modification timestamps for proper sync behavior
+- [ ] Rich progress bars show real-time transfer status (files/MB transferred)
+- [ ] WorkOS JWT authentication validates correctly on WebDAV endpoints
+- [ ] Direct tenant connection bypasses MCP gateway successfully
+
+**Quality Requirements:**
+- [ ] Clear error messages for authentication failures
+- [ ] Graceful handling of network interruptions
+- [ ] CLI follows existing command patterns and help text standards
+- [ ] WebDAV endpoints integrate cleanly with existing FastAPI app
+
+**Performance Requirements:**
+- [ ] File transfer speed > 1MB/s on typical connections
+- [ ] Memory usage remains reasonable for large projects
+- [ ] No timeout issues with 500+ file projects
+
+### Testing Procedure
+
+**Unit Testing:**
+1. CLI command parsing and argument validation
+2. WebDAV client connection and authentication
+3. File timestamp preservation during transfer
+4. JWT token validation on WebDAV endpoints
+
+**Integration Testing:**
+1. End-to-end upload of test project
+2. Direct tenant connection without proxy
+3. File integrity verification after upload
+4. Progress tracking accuracy during transfer
+
+**User Experience Testing:**
+1. Upload existing basic-memory project from local installation
+2. Verify uploaded files appear correctly in cloud tenant
+3. Confirm basic-memory database rebuilds properly with uploaded files
+4. Test CLI help text and error message clarity
+
+### Validation Commands
+
+**Setup:**
+```bash
+# Login to WorkOS
+basic-memory-cloud login
+
+# Upload project
+basic-memory-cloud upload ~/my-notes --tenant-url https://basic-memory-test.fly.dev
+```
+
+**Verification:**
+```bash
+# Check tenant health and file count via API
+curl -H "Authorization: Bearer $JWT" https://basic-memory-test.fly.dev/health
+curl -H "Authorization: Bearer $JWT" https://basic-memory-test.fly.dev/notes/search
+```
+
+### Performance Benchmarks
+
+**Target metrics for 100MB basic-memory project:**
+- Transfer time: < 30 seconds
+- Memory usage: < 100MB during transfer
+- Progress updates: Every 1MB or 10 files
+- Authentication time: < 2 seconds
+
+## Observations
+
+- [implementation-speed] CLI approach significantly faster than web UI for POC development #rapid-prototyping
+- [user-experience] Basic-memory users already comfortable with CLI tools #user-familiarity
+- [architecture-benefit] Direct connection eliminates proxy complexity and latency #performance
+- [auth-reuse] Existing WorkOS JWT infrastructure handles authentication cleanly #code-reuse
+- [webdav-choice] WebDAV protocol provides cross-platform compatibility and standard libraries #protocol-selection
+- [poc-scope] Simple conflict handling and error recovery sufficient for proof-of-concept #scope-management
+- [migration-value] Removes primary barrier for local users migrating to cloud platform #business-value
+
+## Relations
+
+- depends_on [[SPEC-1: Specification-Driven Development Process]]
+- enables [[GitHub Issue #59: Web UI Upload Feature]]
+- uses [[WorkOS Authentication Integration]]
+- builds_on [[Existing Cloud CLI Infrastructure]]
+- builds_on [[Existing Tenant API Architecture]]

specs/SPEC-6 Explicit Project Parameter Architecture.md

@@ -0,0 +1,486 @@
+---
+title: 'SPEC-6: Explicit Project Parameter Architecture'
+type: spec
+permalink: specs/spec-6-explicit-project-parameter-architecture
+tags:
+- architecture
+- mcp
+- project-management
+- stateless
+---
+
+# SPEC-6: Explicit Project Parameter Architecture
+
+## Why
+
+The current session-based project management system has critical reliability issues:
+
+1. **Session State Fragility**: Claude iOS mobile client fails to maintain consistent session IDs across MCP tool calls, causing project switching to silently fail (Issue #74)
+2. **Scaling Limitations**: Redis-backed session state creates single-point-of-failure and prevents horizontal scaling
+3. **Client Compatibility**: Session tracking works inconsistently across different MCP clients (web, mobile, API)
+4. **Hidden Complexity**: Users cannot see or understand "current project" state, leading to confusion when operations execute in wrong projects
+5. **Silent Failures**: Operations appear successful but execute in unintended projects, risking data integrity
+
+Evidence from production logs shows each MCP tool call from mobile client receives different session IDs:
+```
+create_memory_project: session_id=12cdfc24913b48f8b680ed4b2bfdb7ba
+switch_project:       session_id=050a69275d98498cbdd227cdb74d9740
+list_directory:       session_id=85f3483014af4136a5d435c76ded212f
+```
+
+Related Github issue: https://github.com/basicmachines-co/basic-memory-cloud/issues/75
+
+## Status
+
+**Current Status**: **Phase 1 Implementation Complete** ✅
+**Target**: Fix Claude iOS session ID consistency issues
+**Draft PR**: https://github.com/basicmachines-co/basic-memory/pull/298
+
+### 🎉 **MAJOR MILESTONE ACHIEVED**
+
+The complete stateless architecture has been successfully implemented for Basic Memory's MCP server! This represents a **fundamental architectural improvement** that solves the Claude iOS compatibility issue while making the entire system more robust and predictable.
+
+#### Implementation Summary:
+- **16 files modified** with 582 additions and 550 deletions
+- **All 17 MCP tools** converted to stateless architecture
+- **147 tests updated** across 5 test files (100% passing)
+- **Complete session state removal** from core MCP tools
+- **Enhanced error handling** and security validations preserved
+
+### Progress Summary
+
+✅ **Complete Stateless Architecture Implementation (All 17 tools)**
+- Stateless `get_active_project()` function implemented and deployed
+- All session state dependencies removed across entire MCP server
+- All MCP tools require explicit `project` parameter as first argument
+
+✅ **Content Management Tools Complete (6/6 tools)**
+- `write_note`, `read_note`, `delete_note`, `edit_note` ✅
+- `view_note`, `read_content` ✅
+
+✅ **Knowledge Graph Navigation Tools Complete (3/3 tools)**
+- `build_context`, `recent_activity`, `list_directory` ✅
+
+✅ **Search & Discovery Tools Complete (1/1 tools)**
+- `search_notes` ✅
+
+✅ **Visualization Tools Complete (1/1 tools)**
+- `canvas` ✅
+
+✅ **Project Management Cleanup Complete**
+- Removed `switch_project` and `get_current_project` tools ✅
+- Updated `set_default_project` to remove activate parameter ✅
+
+✅ **Comprehensive Testing Complete (157 tests)**
+- All test suites updated to use stateless architecture (147 existing tests)
+- Single project constraint mode integration tests (10 new tests)
+- 100% test pass rate across all tool test files
+- Security validations preserved and working
+- Error handling comprehensive and user-friendly
+
+✅ **Documentation & Examples Complete**
+- All tool docstrings updated with stateless examples
+- Project parameter usage clearly documented
+- Error handling and security behavior documented
+
+✅ **Enhanced Discovery Mode Complete**
+- `recent_activity` tool supports dual-mode operation (discovery vs project-specific)
+- ProjectActivitySummary schema provides cross-project insights
+- Recent activity prompt updated to support both modes
+- Comprehensive project distribution statistics and most active project tracking
+
+✅ **Single Project Constraint Mode Complete**
+- `--project` CLI parameter for MCP server constraint
+- Environment variable control (`BASIC_MEMORY_MCP_PROJECT`)
+- Automatic project override in `get_active_project()` function
+- Project management tools disabled in constrained mode with helpful CLI guidance
+- Comprehensive integration test suite (10 tests covering all constraint scenarios)
+
+## What
+
+Transform Basic Memory from stateful session-based to stateless explicit project parameter architecture:
+
+### Core Changes
+1. **Mandatory Project Parameter**: All MCP tools require explicit `project` parameter
+2. **Remove Session State**: Eliminate Redis, session middleware, and `switch_project` tool
+3. **Stateless HTTP**: Enable `stateless_http=True` for horizontal scaling
+4. **Enhanced Context Discovery**: Improve `recent_activity` to show project distribution
+5. **Clear Response Format**: All tool responses display target project information
+
+Implementation Approach                                                                    
+
+- Each tool will directly accept the project parameter                             
+- Remove all calls to context-based project retrieval                              
+- Validate project exists before operations                                        
+- Clear error messages when project not found                                      
+- Backward compatibility: Initially keep optional parameter, then make required  
+
+### Affected MCP Tools
+**Content Management** (require project parameter):
+- `write_note(project, title, content, folder)`
+- `read_note(project, identifier)`
+- `edit_note(project, identifier, operation, content)`
+- `delete_note(project, identifier)`
+- `view_note(project, identifier)`
+- `read_content(project, path)`
+
+**Knowledge Graph Navigation** (require project parameter):
+- `build_context(project, url, timeframe, depth, max_related)`
+- `list_directory(project, dir_name, depth, file_name_glob)`
+- `search_notes(project, query, search_type, types, entity_types)`
+
+**Search & Discovery** (use project parameter for specific project or none for discovery):
+- `recent_activity(project, timeframe, depth, max_related)`
+
+**Visualization** (require project parameter):
+- `canvas(project, nodes, edges, title, folder)`
+
+**Project Management** (unchanged - already stateless):
+- `list_memory_projects()`
+- `create_memory_project(project_name, project_path, set_default)`
+- `delete_project(project_name)`
+- `get_current_project()` - Remove this tool
+- `switch_project(project_name)` - Remove this tool
+- `set_default_project(project_name, activate)` - Remove activate parameter
+
+## How (High Level)
+
+### Phase 1: Basic Memory Core (basic-memory repository)
+
+#### MCP Tool Updates
+
+Phase 1: Core Changes 
+
+1. Update project_context.py
+
+- [x] Make project parameter mandatory for get_active_project()
+- [x] Remove session state handling
+
+2. Update Content Management Tools (6 tools)
+
+- [x] write_note: Make project parameter required, not optional
+- [x] read_note: Make project parameter required
+- [x] edit_note: Add required project parameter
+- [x] delete_note: Add required project parameter
+- [x] view_note: Add required project parameter
+- [x] read_content: Add required project parameter
+
+3. Update Knowledge Graph Navigation Tools (3 tools)
+
+- [x] build_context: Add required project parameter
+- [x] recent_activity: Make project parameter required
+- [x] list_directory: Add required project parameter
+
+4. Update Search & Visualization Tools (2 tools)
+
+- [x] search_notes: Add required project parameter
+- [x] canvas: Add required project parameter
+
+5. Update Project Management Tools
+
+- [x] Remove switch_project tool completely
+- [x] Remove get_current_project tool completely
+- [x] Update set_default_project to remove activate parameter
+- [x] Keep list_memory_projects, create_memory_project, delete_project unchanged
+    
+6. Enhance recent_activity Response
+
+- [x] Add project distribution info showing activity across all projects
+- [x] Include project usage stats in response
+- [x] Implement ProjectActivitySummary for discovery mode
+- [x] Add dual-mode functionality (discovery vs project-specific)
+
+7. Update Tool Documentation
+
+- [x] Update write_note docstring with stateless architecture examples
+- [x] Update read_note docstring with project parameter examples
+- [x] Update delete_note docstring with comprehensive usage guidance
+- [x] Update all remaining tool docstrings with project parameter examples
+
+8. Update Tool Responses
+
+- [x] Add clear project indicator to all tool responses across all tools
+- [x] Format: "project: {project_name}" in response metadata
+- [x] Add project metadata footer for LLM awareness
+- [x] Update all tool responses to include project indicators
+
+9. Comprehensive Testing
+
+- [x] Update all write_note tests to use stateless architecture (34 tests passing)
+- [x] Update all edit_note tests to use stateless architecture (17 tests passing)
+- [x] Update all view_note tests to use stateless architecture (12 tests passing)
+- [x] Update all search_notes tests to use stateless architecture (16 tests passing)
+- [x] Update all move_note tests to use stateless architecture (31 tests passing)
+- [x] Update all delete_note tests to use stateless architecture
+- [x] Verify direct function call compatibility (bypassing MCP layer)
+- [x] Test security validation with project parameters
+- [x] Validate error handling for non-existent projects
+- [x] **Total: 157 tests updated and passing (100% success rate)**
+  - [x] **147 existing tests** updated for stateless architecture
+  - [x] **10 new tests** for single project constraint mode                                                                   
+                                                                                                                             
+### Phase 1.5: Default Project Mode Enhancement
+
+#### Problem
+While the stateless architecture solves reliability issues, it introduces UX friction for single-project users (estimated 80% of usage) who must specify the project parameter in every tool call.
+
+#### Solution: Default Project Mode
+Add optional `default_project_mode` configuration that allows single-project users to have the simplicity of implicit project selection while maintaining the reliability of stateless architecture.
+
+#### Configuration
+```json
+{
+  "default_project": "main",
+  "default_project_mode": true  // NEW: Auto-use default_project when not specified
+}
+```
+
+#### Implementation Details
+1. **Config Enhancement** (`src/basic_memory/config.py`)
+   - Add `default_project_mode: bool = Field(default=False)`
+   - Preserves backward compatibility (defaults to false)
+
+2. **Project Resolution Logic** (`src/basic_memory/mcp/project_context.py`)
+   Three-tier resolution hierarchy:
+   - Priority 1: CLI `--project` constraint (BASIC_MEMORY_MCP_PROJECT env var)
+   - Priority 2: Explicit project parameter in tool call
+   - Priority 3: `default_project` if `default_project_mode=true` and no project specified
+
+3. **Assistant Guide Updates** (`src/basic_memory/mcp/resources/ai_assistant_guide.md`)
+   - Detect `default_project_mode` at runtime
+   - Provide mode-specific instructions to LLMs
+   - In default mode: "All operations use project 'main' automatically"
+   - In regular mode: Current project discovery guidance
+
+4. **Tool Parameter Handling** (all MCP tools)
+   - Make project parameter Optional[str] = None
+   - Add resolution logic: `project = project or get_default_project()`
+   - Maintain explicit project override capability
+
+#### Usage Modes Summary
+- **Regular Mode**: Multi-project users, assistant tracks project per conversation
+- **Default Project Mode**: Single-project users, automatic default project
+- **Constrained Mode**: CLI --project flag, locked to specific project
+
+#### Testing Requirements
+- Integration test for default_project_mode=true with missing parameters
+- Test explicit project override in default_project_mode
+- Test mode=false requires explicit parameters
+- Test CLI constraint overrides default_project_mode
+
+Phase 2: Testing & Validation
+
+8. Update Tests
+
+- [x] Modify all MCP tool tests to pass required project parameter
+- [x] Remove tests for deleted tools (switch_project, get_current_project)
+- [x] Add tests for project parameter validation
+- [x] **Complete: All 147 tests across 5 test files updated and passing**
+
+#### Enhanced recent_activity Response
+```json
+{
+  "recent_notes": [...],
+  "project_activity": {
+    "research-project": {
+      "operations": 5,
+      "last_used": "30 minutes ago",
+      "recent_folders": ["experiments", "findings"]
+    },
+    "work-notes": {
+      "operations": 2,
+      "last_used": "2 hours ago",
+      "recent_folders": ["meetings", "planning"]
+    }
+  },
+  "total_projects": 3
+}
+```
+
+#### Response Format Updates
+```
+✓ Note created successfully
+
+Project: research-project
+File: experiments/Neural Network Results.md
+Permalink: research-project/neural-network-results
+```
+
+### Phase 2: Cloud Service Simplification (basic-memory-cloud repository)
+
+#### Remove Session Infrastructure
+1. Delete `apps/mcp/src/basic_memory_cloud_mcp/middleware/session_state.py`
+2. Delete `apps/mcp/src/basic_memory_cloud_mcp/middleware/session_logging.py`
+3. Update `apps/mcp/src/basic_memory_cloud_mcp/main.py`:
+   ```python
+   # Remove session middleware
+   # server.add_middleware(SessionStateMiddleware)
+
+   # Enable stateless HTTP
+   mcp = FastMCP(name="basic-memory-mcp", stateless_http=True)
+   ```
+
+#### Deployment Simplification
+1. Remove Redis from `fly.toml`
+2. Remove Redis environment variables
+3. Update health checks to not depend on Redis
+
+### Phase 3: Conversational Project Management
+
+#### Claude Behavior Pattern
+1. **Project Discovery**:
+   ```
+   Claude: Let me check your recent activity...
+   [calls recent_activity() - no project needed for discovery]
+
+   I see you've been working in:
+   - research-project (5 operations, 30 min ago)
+   - work-notes (2 operations, 2 hours ago)
+
+   Which project should I use for this operation?
+   ```
+
+2. **Context Maintenance**:
+   ```
+   User: Use research-project
+   Claude: Working in research-project.
+   [All subsequent operations use project="research-project"]
+   ```
+
+3. **Explicit Project Switching**:
+   ```
+   User: Check work-notes for that meeting summary
+   Claude: Let me search work-notes for the meeting summary.
+   [Uses project="work-notes" for specific operation]
+   ```
+
+## How to Evaluate
+
+### Success Criteria
+
+#### 1. Functional Completeness
+- [x] All MCP tools accept required `project` parameter
+- [x] All MCP tools validate project exists before execution
+- [x] `switch_project` and `get_current_project` tools removed
+- [x] All responses display target project clearly
+- [ ] No Redis dependencies in deployment (Phase 2: Cloud Service)
+- [x] `recent_activity` shows project distribution with ProjectActivitySummary
+
+#### 2. Cross-Client Compatibility Testing
+Test identical operations across all clients:
+- [ ] **Claude Desktop**: All operations work with explicit projects
+- [ ] **Claude Code**: All operations work with explicit projects
+- [ ] **Claude Mobile iOS**: All operations work with explicit projects
+- [ ] **API clients**: All operations work with explicit projects
+- [ ] **CLI tools**: All operations work with explicit projects
+
+#### 3. Session Independence Verification
+- [ ] Operations work identically with/without session tracking
+- [ ] No behavioral differences between clients
+- [ ] Mobile client session ID changes do not affect operations
+- [ ] Redis can be completely removed without functional impact
+
+#### 4. Performance & Scaling
+- [ ] `stateless_http=True` enabled successfully
+- [ ] No Redis memory usage
+- [ ] Horizontal scaling possible (multiple MCP instances)
+- [ ] Response times unchanged or improved
+
+#### 5. User Experience Testing
+**Project Discovery Flow**:
+- [x] `recent_activity()` provides useful project context
+- [x] Claude can intelligently suggest projects based on activity
+- [x] Project switching is explicit and clear in conversation
+
+**Error Handling**:
+- [x] Clear error messages for non-existent projects
+- [x] Helpful suggestions when project parameter missing
+- [x] No silent failures or wrong-project operations
+
+**Response Clarity**:
+- [x] Every operation clearly shows target project
+- [x] Users always know which project is being operated on
+- [x] No confusion about "current project" state
+
+#### 6. Migration Safety
+- [ ] Backward compatibility period with optional project parameter
+- [ ] Clear migration documentation for existing users
+- [ ] Data integrity maintained during transition
+- [ ] No data loss during migration
+
+### Test Scenarios
+
+#### Core Functionality Test
+```bash
+# Test all tools work with explicit project
+write_note(project="test-proj", title="Test", content="Content", folder="docs")
+read_note(project="test-proj", identifier="Test")
+edit_note(project="test-proj", identifier="Test", operation="append", content="More")
+search_notes(project="test-proj", query="Content")
+list_directory(project="test-proj", dir_name="docs")
+delete_note(project="test-proj", identifier="Test")
+```
+
+#### Cross-Client Consistency Test
+Run identical test sequence on:
+1. Claude Desktop
+2. Claude Code
+3. Claude Mobile iOS
+4. API client
+5. CLI tools
+
+Verify all clients:
+- Accept explicit project parameters
+- Return identical responses
+- Show same project information
+- Have no session dependencies
+
+#### Session Independence Test
+1. Monitor session IDs during operations
+2. Verify operations work with changing session IDs
+3. Confirm Redis removal doesn't affect functionality
+4. Test with multiple concurrent clients
+
+### Acceptance Criteria
+
+**Must Have**:
+- All MCP tools require and use explicit project parameter
+- No session state dependencies remain
+- Universal client compatibility achieved
+- Clear project information in all responses
+
+**Should Have**:
+- Enhanced `recent_activity` with project distribution
+- Smooth migration path for existing users
+- Improved performance with stateless architecture
+
+**Could Have**:
+- Smart project suggestions based on content/context
+- Project shortcuts for common operations
+- Advanced project analytics in responses
+
+## Notes
+
+### Breaking Changes
+This is a **breaking change** that requires:
+- All MCP clients to pass project parameter
+- Migration of existing workflows
+- Update of all documentation and examples
+
+### Implementation Order
+1. **basic-memory core** - Update MCP tools to accept project parameter (optional initially)
+2. **Testing** - Verify all clients work with explicit projects
+3. **Cloud service** - Remove session infrastructure
+4. **Migration** - Make project parameter mandatory
+5. **Cleanup** - Remove deprecated tools and middleware
+
+### Related Issues
+- Fixes #74 (Claude iOS session state bug)
+- Implements #75 (Mandatory project parameter architecture)
+- Enables future horizontal scaling
+- Simplifies multi-tenant architecture
+
+### Dependencies
+- Requires coordination between basic-memory and basic-memory-cloud repositories
+- Needs client-side updates for smooth transition
+- Documentation updates across all materials

specs/SPEC-7 POC to spike Tigris Turso for local access to cloud data.md

@@ -0,0 +1,193 @@
+---
+title: 'SPEC-7: POC to spike Tigris/Turso for local access to cloud data'
+type: spec
+permalink: specs/spec-7-poc-tigris-turso-local-access-cloud-data
+tags:
+- poc
+- tigris
+- turso
+- cloud-storage
+- architecture
+- proof-of-concept
+---
+
+# SPEC-7: POC to spike Tigris/Turso for local access to cloud data
+
+## Why
+
+Current basic-memory-cloud architecture uses Fly volumes for tenant file storage, which creates several limitations:
+
+1. **Storage Scalability**: Fly volumes require pre-provisioning and don't auto-scale with usage
+2. **Cost Model**: Volume pricing vs object storage pricing may be less favorable at scale
+3. **Local Development**: No way for users to mount their cloud tenant files locally for real-time editing
+4. **Multi-Region**: Volumes are region-locked, limiting global deployment flexibility
+5. **Backup/Disaster Recovery**: Object storage provides better durability and replication options
+
+The core insight is that Basic Memory requires POSIX filesystem semantics but could benefit from object storage durability and accessibility. By combining:
+- **Tigris object storage** for file persistence (via rclone mount)
+- **Turso/libSQL** for SQLite indexing (replacing local .db files)
+
+We could enable a revolutionary user experience: **local editing of cloud-stored files** while maintaining Basic Memory's existing filesystem assumptions.
+
+## What
+
+This specification defines a proof-of-concept to validate the technical feasibility of the Tigris/Turso architecture for basic-memory-cloud tenants.
+
+**Affected Areas:**
+- **Storage Architecture**: Replace Fly volumes with Tigris object storage
+- **Database Architecture**: Replace local SQLite with Turso remote database
+- **Container Setup**: Add rclone mounting in tenant containers
+- **Local Development**: Enable local mounting of cloud tenant data
+- **Basic Memory Core**: Validate unchanged operation over mounted filesystems
+
+**Key Components:**
+- **Tigris Storage**: S3-compatible object storage via Fly.io integration
+- **rclone NFS Mount**: Native NFS mounting without FUSE dependencies
+- **Turso Database**: Hosted libSQL for SQLite replacement
+- **Single-Tenant Model**: One bucket + one database per tenant (simplified isolation)
+
+## How (High Level)
+
+### Phase 1: Local POC Validation
+- [ ] Set up Tigris bucket with test data
+- [ ] Configure rclone NFS mount locally
+- [ ] Test Basic Memory operations over mounted filesystem
+- [ ] Measure performance characteristics and identify issues
+- [ ] Validate file watching, sync operations, and concurrent access patterns
+
+### Phase 2: Database Migration
+- [ ] Set up Turso account and test database
+- [ ] Modify Basic Memory to accept external DATABASE_URL
+- [ ] Test all operations with remote SQLite via Turso
+- [ ] Validate performance and functionality parity
+
+### Phase 3: Container Integration
+- [ ] Create container image with rclone + NFS support
+- [ ] Implement tenant-specific credential management
+- [ ] Test container startup with automatic mounting
+- [ ] Validate isolation between tenant containers
+
+### Phase 4: Local Access Validation
+- [ ] Test local rclone mounting of tenant data
+- [ ] Validate real-time file editing experience
+- [ ] Test conflict resolution and sync behavior
+- [ ] Measure latency impact on user experience
+
+### Architecture Overview
+```
+Local Development:
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│ Local rclone    │───▶│ Tigris Bucket   │◀───│ Tenant Container│
+│ NFS Mount       │    │ (S3 storage)    │    │ rclone mount    │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+         │                                              │
+         ▼                                              ▼
+┌─────────────────┐                            ┌─────────────────┐
+│ Basic Memory    │                            │ Basic Memory    │
+│ (local files)   │                            │ (mounted files) │
+└─────────────────┘                            └─────────────────┘
+         │                                              │
+         ▼                                              ▼
+┌─────────────────┐                            ┌─────────────────┐
+│ Turso Database  │◀───────────────────────────│ Turso Database  │
+│ (shared index)  │                            │ (shared index)  │
+└─────────────────┘                            └─────────────────┘
+```
+
+## How to Evaluate
+
+### Success Criteria
+- [ ] **Filesystem Compatibility**: Basic Memory operates without modification over rclone-mounted Tigris storage
+- [ ] **Performance Acceptable**: File operations complete within 2x local filesystem latency
+- [ ] **Database Functionality**: All Basic Memory features work with Turso remote SQLite
+- [ ] **Container Reliability**: Tenant containers start successfully with automatic mounting
+- [ ] **Local Access**: Users can mount and edit cloud files locally with real-time sync
+- [ ] **Data Isolation**: Tenant data remains properly isolated using bucket/database separation
+
+### Testing Procedure
+1. **Local Filesystem Test**:
+   ```bash
+   # Mount Tigris bucket locally
+   rclone nfsmount tigris:test-bucket ~/tigris-test --vfs-cache-mode writes
+
+   # Run Basic Memory operations
+   cd ~/tigris-test && basic-memory sync --watch
+   # Test: create notes, search, file watching, bulk operations
+   ```
+
+2. **Database Migration Test**:
+   ```bash
+   # Configure Turso connection
+   export DATABASE_URL="libsql://test-db.turso.io?authToken=..."
+
+   # Test all MCP tools with remote database
+   basic-memory tools # Test each tool functionality
+   ```
+
+3. **Container Integration Test**:
+   ```dockerfile
+   # Test container with rclone mounting
+   FROM python:3.12
+   RUN apt-get update && apt-get install -y rclone nfs-common
+   # ... test startup and mounting process
+   ```
+
+4. **Performance Benchmarking**:
+   - File creation/read/write operations (target: <2x local latency)
+   - Search query performance (target: comparable to local SQLite)
+   - File watching responsiveness (target: events within 1-2 seconds)
+   - Concurrent operation handling
+
+### Risk Assessment
+**High Risk Items**:
+- [ ] NFS-over-S3 performance may be insufficient for real-time operations
+- [ ] File watching (`inotify`) over NFS may be unreliable
+- [ ] Network interruptions could cause filesystem errors
+- [ ] Concurrent access patterns might hit S3 rate limits
+
+**Mitigation Strategies**:
+- Comprehensive performance testing before committing to architecture
+- Fallback plan to S3-native storage backend if filesystem approach fails
+- Extensive error handling and retry logic for network issues
+
+### Metrics to Track
+- **Latency**: File operation response times (read/write/watch)
+- **Reliability**: Success rate of file operations over time
+- **Throughput**: Concurrent file operations and search queries
+- **User Experience**: Perceived performance for local mounting use case
+
+## Notes
+
+### Key Architectural Decisions
+- **Single tenant per bucket/database**: Simplifies isolation and credential management
+- **Maintain POSIX compatibility**: Preserve Basic Memory's existing filesystem assumptions
+- **NFS over FUSE**: Better compatibility and performance characteristics
+- **Turso for SQLite**: Leverages specialized remote SQLite expertise
+
+### Alternative Approaches Considered
+- **S3-native storage backend**: Would require Basic Memory architecture changes
+- **Hybrid approach**: Local files + cloud sync (adds complexity)
+- **FUSE mounting**: More platform dependencies and kernel requirements
+
+### Integration Points
+- [ ] Fly.io Tigris integration for bucket provisioning
+- [ ] Turso account setup and database provisioning
+- [ ] Container image modifications for rclone support
+- [ ] Credential management for tenant isolation
+
+## Observations
+
+- [architecture] Tigris/Turso split cleanly separates file storage from indexing concerns #storage-separation
+- [user-experience] Local mounting of cloud files could be revolutionary for knowledge management #local-cloud-hybrid
+- [compatibility] Maintaining POSIX filesystem assumptions preserves Basic Memory's local/cloud compatibility #architecture-preservation
+- [simplification] Single tenant per bucket eliminates complex multi-tenancy in storage layer #tenant-isolation
+- [risk] NFS-over-S3 performance characteristics are unproven for real-time operations #performance-risk
+- [benefit] Object storage pricing model could be more favorable than volume pricing #cost-optimization
+- [innovation] Real-time local editing of cloud-stored files addresses major SaaS limitation #competitive-advantage
+
+## Relations
+
+- implements [[SPEC-6 Explicit Project Parameter Architecture]]
+- requires [[Fly.io Tigris Integration]]
+- enables [[Local Cloud File Access]]
+- alternative_to [[Fly Volume Storage]]

specs/SPEC-8 TigrisFS Integration.md

@@ -0,0 +1,886 @@
+---
+title: 'SPEC-8: TigrisFS Integration for Tenant API'
+Date: September 22, 2025
+Status: Phase 3.6 Complete - Tenant Mount API Endpoints Ready for CLI Implementation
+Priority: High
+Goal: Replace Fly volumes with Tigris bucket provisioning in production tenant API
+permalink: spec-8-tigris-fs-integration
+---
+
+## Executive Summary
+
+Based on SPEC-7 Phase 4 POC testing, this spec outlines productizing the TigrisFS/rclone implementation in the Basic Memory Cloud tenant API. 
+We're moving from proof-of-concept to production integration, replacing Fly volume storage with Tigris bucket-per-tenant architecture.
+
+## Current Architecture (Fly Volumes)
+
+### Tenant Provisioning Flow
+```python
+# apps/cloud/src/basic_memory_cloud/workflows/tenant_provisioning.py
+async def provision_tenant_infrastructure(tenant_id: str):
+    # 1. Create Fly app
+    # 2. Create Fly volume  ← REPLACE THIS
+    # 3. Deploy API container with volume mount
+    # 4. Configure health checks
+```
+
+### Storage Implementation
+- Each tenant gets dedicated Fly volume (1GB-10GB)
+- Volume mounted at `/app/data` in API container
+- Local filesystem storage with Basic Memory indexing
+- No global caching or edge distribution
+
+## Proposed Architecture (Tigris Buckets)
+
+### New Tenant Provisioning Flow
+```python
+async def provision_tenant_infrastructure(tenant_id: str):
+    # 1. Create Fly app
+    # 2. Create Tigris bucket with admin credentials  ← NEW
+    # 3. Store bucket name in tenant record  ← NEW
+    # 4. Deploy API container with TigrisFS mount using admin credentials
+    # 5. Configure health checks
+```
+
+### Storage Implementation
+- Each tenant gets dedicated Tigris bucket
+- TigrisFS mounts bucket at `/app/data` in API container
+- Global edge caching and distribution
+- Configurable cache TTL for sync performance
+
+## Implementation Plan
+
+### Phase 1: Bucket Provisioning Service
+
+**✅ IMPLEMENTED: StorageClient with Admin Credentials**
+```python
+# apps/cloud/src/basic_memory_cloud/clients/storage_client.py
+class StorageClient:
+    async def create_tenant_bucket(self, tenant_id: UUID) -> TigrisBucketCredentials
+    async def delete_tenant_bucket(self, tenant_id: UUID, bucket_name: str) -> bool
+    async def list_buckets(self) -> list[TigrisBucketResponse]
+    async def test_tenant_credentials(self, credentials: TigrisBucketCredentials) -> bool
+```
+
+**Simplified Architecture Using Admin Credentials:**
+- Single admin access key with full Tigris permissions (configured in console)
+- No tenant-specific IAM user creation needed
+- Bucket-per-tenant isolation for logical separation
+- Admin credentials shared across all tenant operations
+
+**Integrate with Provisioning workflow:**
+```python
+# Update tenant_provisioning.py
+async def provision_tenant_infrastructure(tenant_id: str):
+    storage_client = StorageClient(settings.aws_access_key_id, settings.aws_secret_access_key)
+    bucket_creds = await storage_client.create_tenant_bucket(tenant_id)
+    await store_bucket_name(tenant_id, bucket_creds.bucket_name)
+    await deploy_api_with_tigris(tenant_id, bucket_creds)
+```
+
+### Phase 2: Simplified Bucket Management
+
+**✅ SIMPLIFIED: Admin Credentials + Bucket Names Only**
+
+Since we use admin credentials for all operations, we only need to track bucket names per tenant:
+
+1. **Primary Storage (Fly Secrets)**
+   ```bash
+   flyctl secrets set -a basic-memory-{tenant_id} \
+     AWS_ACCESS_KEY_ID="{admin_access_key}" \
+     AWS_SECRET_ACCESS_KEY="{admin_secret_key}" \
+     AWS_ENDPOINT_URL_S3="https://fly.storage.tigris.dev" \
+     AWS_REGION="auto" \
+     BUCKET_NAME="basic-memory-{tenant_id}"
+   ```
+
+2. **Database Storage (Bucket Name Only)**
+   ```python
+   # apps/cloud/src/basic_memory_cloud/models/tenant.py
+   class Tenant(BaseModel):
+       # ... existing fields
+       tigris_bucket_name: Optional[str] = None  # Just store bucket name
+       tigris_region: str = "auto"
+       created_at: datetime
+   ```
+
+**Benefits of Simplified Approach:**
+- No credential encryption/decryption needed
+- Admin credentials managed centrally in environment
+- Only bucket names stored in database (not sensitive)
+- Simplified backup/restore scenarios
+- Reduced security attack surface
+
+### Phase 3: API Container Updates
+
+**Update API container configuration:**
+```dockerfile
+# apps/api/Dockerfile
+# Add TigrisFS installation
+RUN curl -L https://github.com/tigrisdata/tigrisfs/releases/latest/download/tigrisfs-linux-amd64 \
+    -o /usr/local/bin/tigrisfs && chmod +x /usr/local/bin/tigrisfs
+```
+
+**Startup script integration:**
+```bash
+# apps/api/tigrisfs-startup.sh (already exists)
+# Mount TigrisFS → Start Basic Memory API
+exec python -m basic_memory_cloud_api.main
+```
+
+**Fly.toml environment (optimized for < 5s startup):**
+```toml
+# apps/api/fly.tigris-production.toml
+[env]
+  TIGRISFS_MEMORY_LIMIT = '1024'     # Reduced for faster init
+  TIGRISFS_MAX_FLUSHERS = '16'       # Fewer threads for faster startup
+  TIGRISFS_STAT_CACHE_TTL = '30s'    # Balance sync speed vs startup
+  TIGRISFS_LAZY_INIT = 'true'        # Enable lazy loading
+  BASIC_MEMORY_HOME = '/app/data'
+
+# Suspend optimization for wake-on-network
+[machine]
+  auto_stop_machines = "suspend"     # Faster than full stop
+  auto_start_machines = true
+  min_machines_running = 0
+```
+
+### Phase 4: Local Access Features
+
+**CLI automation for local mounting:**
+```python
+# New CLI command: basic-memory cloud mount
+async def setup_local_mount(tenant_id: str):
+    # 1. Fetch bucket credentials from cloud API
+    # 2. Configure rclone with scoped IAM policy
+    # 3. Mount via rclone nfsmount (macOS) or FUSE (Linux)
+    # 4. Start Basic Memory sync watcher
+```
+
+**Local mount configuration:**
+```bash
+# rclone config for tenant
+rclone mount basic-memory-{tenant_id}: ~/basic-memory-{tenant_id} \
+  --nfs-mount \
+  --vfs-cache-mode writes \
+  --cache-dir ~/.cache/rclone/basic-memory-{tenant_id}
+```
+
+### Phase 5: TigrisFS Cache Sync Solutions
+
+**Problem**: When files are uploaded via CLI/bisync, the tenant API container doesn't see them immediately due to TigrisFS cache (30s TTL) and lack of inotify events on mounted filesystems.
+
+**Multi-Layer Solution:**
+
+**Layer 1: API Sync Endpoint** (Immediate)
+```python
+# POST /sync - Force TigrisFS cache refresh
+# Callable by CLI after uploads
+subprocess.run(["sync", "fsync /app/data"], check=True)
+```
+
+**Layer 2: Tigris Webhook Integration** (Real-time)
+https://www.tigrisdata.com/docs/buckets/object-notifications/#webhook
+```python
+# Webhook endpoint for bucket changes
+@app.post("/webhooks/tigris/{tenant_id}")
+async def handle_bucket_notification(tenant_id: str, event: TigrisEvent):
+    if event.eventName in ["OBJECT_CREATED_PUT", "OBJECT_DELETED"]:
+        await notify_container_sync(tenant_id, event.object.key)
+```
+
+**Layer 3: CLI Sync Notification** (User-triggered)
+```bash
+# CLI calls container sync endpoint after successful bisync
+basic-memory cloud bisync  # Automatically notifies container
+curl -X POST https://basic-memory-{tenant-id}.fly.dev/sync
+```
+
+**Layer 4: Periodic Sync Fallback** (Safety net)
+```python
+# Background task: fsync /app/data every 30s as fallback
+# Ensures eventual consistency even if other layers fail
+```
+
+**Implementation Priority:**
+1. Layer 1 (API endpoint) - Quick testing capability
+2. Layer 3 (CLI integration) - Improved UX
+3. Layer 4 (Periodic fallback) - Safety net
+4. Layer 2 (Webhooks) - Production real-time sync
+
+
+## Performance Targets
+
+### Sync Latency
+- **Target**: < 5 seconds local→cloud→container
+- **Configuration**: `TIGRISFS_STAT_CACHE_TTL = '5s'`
+- **Monitoring**: Track sync metrics in production
+
+### Container Startup
+- **Target**: < 5 seconds including TigrisFS mount
+- **Fast retry**: 0.5s intervals for mount verification
+- **Fallback**: Container fails fast if mount fails
+
+### Memory Usage
+- **TigrisFS cache**: 2GB memory limit per container
+- **Concurrent uploads**: 32 flushers max
+- **VM sizing**: shared-cpu-2x (2048mb) minimum
+
+## Security Considerations
+
+### Bucket Isolation
+- Each tenant has dedicated bucket
+- IAM policies prevent cross-tenant access
+- No shared bucket with subdirectories
+
+### Credential Security
+- Fly secrets for runtime access
+- Encrypted database backup for disaster recovery
+- Credential rotation capability
+
+### Data Residency
+- Tigris global edge caching
+- SOC2 Type II compliance
+- Encryption at rest and in transit
+
+## Operational Benefits
+
+### Scalability
+- Horizontal scaling with stateless API containers
+- Global edge distribution
+- Better resource utilization
+
+### Reliability
+- No cold starts between tenants
+- Built-in redundancy and caching
+- Simplified backup strategy
+
+### Cost Efficiency
+- Pay-per-use storage pricing
+- Shared infrastructure benefits
+- Reduced operational overhead
+
+## Risk Mitigation
+
+### Data Loss Prevention
+- Dual credential storage (Fly + database)
+- Automated backup workflows to R2/S3
+- Tigris built-in redundancy
+
+### Performance Degradation
+- Configurable cache settings per tenant
+- Monitoring and alerting on sync latency
+- Fallback to volume storage if needed
+
+### Security Vulnerabilities
+- Bucket-per-tenant isolation
+- Regular credential rotation
+- Security scanning and monitoring
+
+## Success Metrics
+
+### Technical Metrics
+- Sync latency P50 < 5 seconds
+- Container startup time < 5 seconds
+- Zero data loss incidents
+- 99.9% uptime per tenant
+
+### Business Metrics
+- Reduced infrastructure costs vs volumes
+- Improved user experience with faster sync
+- Enhanced enterprise security posture
+- Simplified operational overhead
+
+## Open Questions
+
+1. **Tigris rate limits**: What are the API limits for bucket creation?
+2. **Cost analysis**: What's the break-even point vs Fly volumes?
+3. **Regional preferences**: Should enterprise customers choose regions?
+4. **Backup retention**: How long to keep automated backups?
+
+## Implementation Checklist
+
+### Phase 1: Bucket Provisioning Service ✅ COMPLETED
+- [x] **Research Tigris bucket API** - Document bucket creation and S3 API compatibility
+- [x] **Create StorageClient class** - Implemented with admin credentials and comprehensive integration tests
+- [x] **Test bucket creation** - Full test suite validates API integration with real Tigris environment
+- [x] **Add bucket provisioning to DBOS workflow** - Integrated StorageClient with tenant_provisioning.py
+
+### Phase 2: Simplified Bucket Management ✅ COMPLETED
+- [x] **Update Tenant model** with tigris_bucket_name field (replaced fly_volume_id)
+- [x] **Implement bucket name storage** - Database migration and model updates completed
+- [x] **Test bucket provisioning integration** - Full test suite validates workflow from tenant creation to bucket assignment
+- [x] **Remove volume logic from all tests** - Complete migration from volume-based to bucket-based architecture
+
+### Phase 3: API Container Integration ✅ COMPLETED
+- [x] **Update Dockerfile** to install TigrisFS binary in API container with configurable version
+- [x] **Optimize tigrisfs-startup.sh** with production-ready security and reliability improvements
+- [x] **Create production-ready container** with proper signal handling and mount validation
+- [x] **Implement security fixes** based on Claude code review (conditional debug, credential protection)
+- [x] **Add proper process supervision** with cleanup traps and error handling
+- [x] **Remove debug artifacts** - Cleaned up all debug Dockerfiles and test scripts
+
+### Phase 3.5: IAM Access Key Management ✅ COMPLETED
+- [x] **Research Tigris IAM API** - Documented create_policy, attach_user_policy, delete_access_key operations
+- [x] **Implement bucket-scoped credential generation** - StorageClient.create_tenant_access_keys() with IAM policies
+- [x] **Add comprehensive security test suite** - 5 security-focused integration tests covering all attack vectors
+- [x] **Verify cross-bucket access prevention** - Scoped credentials can ONLY access their designated bucket
+- [x] **Test credential lifecycle management** - Create, validate, delete, and revoke access keys
+- [x] **Validate admin vs scoped credential isolation** - Different access patterns and security boundaries
+- [x] **Test multi-tenant isolation** - Multiple tenants cannot access each other's buckets
+
+### Phase 3.6: Tenant Mount API Endpoints ✅ COMPLETED
+- [x] **Implement GET /tenant/mount/info** - Returns mount info without exposing credentials
+- [x] **Implement POST /tenant/mount/credentials** - Creates new bucket-scoped credentials for CLI mounting
+- [x] **Implement DELETE /tenant/mount/credentials/{cred_id}** - Revoke specific credentials with proper cleanup
+- [x] **Implement GET /tenant/mount/credentials** - List active credentials without exposing secrets
+- [x] **Add TenantMountCredentials database model** - Tracks credential metadata (no secret storage)
+- [x] **Create comprehensive test suite** - 28 tests covering all scenarios including multi-session support
+- [x] **Implement multi-session credential flow** - Multiple active credentials per tenant supported
+- [x] **Secure credential handling** - Secret keys never stored, returned once only for immediate use
+- [x] **Add dependency injection for StorageClient** - Clean integration with existing API architecture
+- [x] **Fix Tigris configuration for cloud service** - Added AWS environment variables to fly.template.toml
+- [x] **Update tenant machine configurations** - Include AWS credentials for TigrisFS mounting with clear credential strategy
+
+**Security Test Results:**
+```
+✅ Cross-bucket access prevention - PASS
+✅ Deleted credentials access revoked - PASS
+✅ Invalid credentials rejected - PASS
+✅ Admin vs scoped credential isolation - PASS
+✅ Multiple scoped credentials isolation - PASS
+```
+
+**Implementation Details:**
+- Uses Tigris IAM managed policies (create_policy + attach_user_policy)
+- Bucket-scoped S3 policies with Actions: GetObject, PutObject, DeleteObject, ListBucket
+- Resource ARNs limited to specific bucket: `arn:aws:s3:::bucket-name` and `arn:aws:s3:::bucket-name/*`
+- Access keys follow Tigris format: `tid_` prefix with secure random suffix
+- Complete cleanup on deletion removes both access keys and associated policies
+
+### Phase 4: Local Access CLI
+- [x] **Design local mount CLI command** for automated rclone configuration
+- [x] **Implement credential fetching** from cloud API for local setup
+- [x] **Create rclone config automation** for tenant-specific bucket mounting
+- [x] **Test local→cloud→container sync** with optimized cache settings
+- [x] **Document local access setup** for beta users
+
+### Phase 5: Webhook Integration (Future)
+- [ ] **Research Tigris webhook API** for object notifications and payload format
+- [ ] **Design webhook endpoint** for real-time sync notifications
+- [ ] **Implement notification handling** to trigger Basic Memory sync events
+- [ ] **Test webhook delivery** and sync latency improvements
+
+## Success Metrics
+- [ ] **Container startup < 5 seconds** including TigrisFS mount and Basic Memory init
+- [ ] **Sync latency < 5 seconds** for local→cloud→container file changes
+- [ ] **Zero data loss** during bucket provisioning and credential management
+- [ ] **100% test coverage** for new TigrisBucketService and credential functions
+- [ ] **Beta deployment** with internal users validating local-cloud workflow
+
+
+
+## Implementation Notes
+
+## Phase 4.1: Bidirectional Sync with rclone bisync (NEW)
+
+### Problem Statement
+During testing, we discovered that some applications (particularly Obsidian) don't detect file changes over NFS mounts. Rather than building a custom sync daemon, we can leverage `rclone bisync` - rclone's built-in bidirectional synchronization feature.
+
+### Solution: rclone bisync
+Use rclone's proven bidirectional sync instead of custom implementation:
+
+**Core Architecture:**
+```bash
+# rclone bisync handles all the complexity
+rclone bisync ~/basic-memory-{tenant_id} basic-memory-{tenant_id}:{bucket_name} \
+  --create-empty-src-dirs \
+  --conflict-resolve newer \
+  --resilient \
+  --check-access
+```
+
+**Key Benefits:**
+- ✅ **Battle-tested**: Production-proven rclone functionality
+- ✅ **MIT licensed**: Open source with permissive licensing
+- ✅ **No custom code**: Zero maintenance burden for sync logic
+- ✅ **Built-in safety**: max-delete protection, conflict resolution
+- ✅ **Simple installation**: Works with Homebrew rclone (no FUSE needed)
+- ✅ **File watcher compatible**: Works with Obsidian and all applications
+- ✅ **Offline support**: Can work offline and sync when connected
+
+### bisync Conflict Resolution Options
+
+**Built-in conflict strategies:**
+```bash
+--conflict-resolve none     # Keep both files with .conflict suffixes (safest)
+--conflict-resolve newer    # Always pick the most recently modified file
+--conflict-resolve larger   # Choose based on file size
+--conflict-resolve path1    # Always prefer local changes
+--conflict-resolve path2    # Always prefer cloud changes
+```
+
+### Sync Profiles Using bisync
+
+**Profile configurations:**
+```python
+BISYNC_PROFILES = {
+    "safe": {
+        "conflict_resolve": "none",      # Keep both versions
+        "max_delete": 10,                # Prevent mass deletion
+        "check_access": True,            # Verify sync integrity
+        "description": "Safe mode with conflict preservation"
+    },
+    "balanced": {
+        "conflict_resolve": "newer",     # Auto-resolve to newer file
+        "max_delete": 25,
+        "check_access": True,
+        "description": "Balanced mode (recommended default)"
+    },
+    "fast": {
+        "conflict_resolve": "newer",
+        "max_delete": 50,
+        "check_access": False,           # Skip verification for speed
+        "description": "Fast mode for rapid iteration"
+    }
+}
+```
+
+### CLI Commands
+
+**Manual sync commands:**
+```bash
+basic-memory cloud bisync                    # Manual bidirectional sync
+basic-memory cloud bisync --dry-run          # Preview changes
+basic-memory cloud bisync --profile safe     # Use specific profile
+basic-memory cloud bisync --resync           # Force full baseline resync
+```
+
+**Watch mode (Step 1):**
+```bash
+basic-memory cloud bisync --watch            # Long-running process, sync every 60s
+basic-memory cloud bisync --watch --interval 30s  # Custom interval
+```
+
+**System integration (Step 2 - Future):**
+```bash
+basic-memory cloud bisync-service install    # Install as system service
+basic-memory cloud bisync-service start      # Start background service
+basic-memory cloud bisync-service status     # Check service status
+```
+
+### Implementation Strategy
+
+**Phase 4.1.1: Core bisync Implementation**
+- [ ] Implement `run_bisync()` function wrapping rclone bisync
+- [ ] Add profile-based configuration (safe/balanced/fast)
+- [ ] Create conflict resolution and safety options
+- [ ] Test with sample files and conflict scenarios
+
+**Phase 4.1.2: Watch Mode**
+- [ ] Add `--watch` flag for continuous sync
+- [ ] Implement configurable sync intervals
+- [ ] Add graceful shutdown and signal handling
+- [ ] Create status monitoring and progress indicators
+
+**Phase 4.1.3: User Experience**
+- [ ] Add conflict reporting and resolution guidance
+- [ ] Implement dry-run preview functionality
+- [ ] Create troubleshooting and diagnostic commands
+- [ ] Add filtering configuration (.gitignore-style)
+
+**Phase 4.1.4: System Integration (Future)**
+- [ ] Generate platform-specific service files (launchd/systemd)
+- [ ] Add service management commands
+- [ ] Implement automatic startup and recovery
+- [ ] Create monitoring and logging integration
+
+### Technical Implementation
+
+**Core bisync wrapper:**
+```python
+def run_bisync(
+    tenant_id: str,
+    bucket_name: str,
+    profile: str = "balanced",
+    dry_run: bool = False
+) -> bool:
+    """Run rclone bisync with specified profile."""
+
+    local_path = Path.home() / f"basic-memory-{tenant_id}"
+    remote_path = f"basic-memory-{tenant_id}:{bucket_name}"
+    profile_config = BISYNC_PROFILES[profile]
+
+    cmd = [
+        "rclone", "bisync",
+        str(local_path), remote_path,
+        "--create-empty-src-dirs",
+        "--resilient",
+        f"--conflict-resolve={profile_config['conflict_resolve']}",
+        f"--max-delete={profile_config['max_delete']}",
+        "--filters-file", "~/.basic-memory/bisync-filters.txt"
+    ]
+
+    if profile_config.get("check_access"):
+        cmd.append("--check-access")
+
+    if dry_run:
+        cmd.append("--dry-run")
+
+    return subprocess.run(cmd, check=True).returncode == 0
+```
+
+**Default filter file (~/.basic-memory/bisync-filters.txt):**
+```
+- .DS_Store
+- .git/**
+- __pycache__/**
+- *.pyc
+- .pytest_cache/**
+- node_modules/**
+- .conflict-*
+- Thumbs.db
+- desktop.ini
+```
+
+**Advantages Over Custom Daemon:**
+- ✅ **Zero maintenance**: No custom sync logic to debug/maintain
+- ✅ **Production proven**: Used by thousands in production
+- ✅ **Safety features**: Built-in max-delete, conflict handling, recovery
+- ✅ **Filtering**: Advanced exclude patterns and rules
+- ✅ **Performance**: Optimized for various storage backends
+- ✅ **Community support**: Extensive documentation and community
+
+## Phase 4.2: NFS Mount Support (Direct Access)
+
+### Solution: rclone nfsmount
+Keep the existing NFS mount functionality for users who prefer direct file access:
+
+**Core Architecture:**
+```bash
+# rclone nfsmount provides transparent file access
+rclone nfsmount basic-memory-{tenant_id}:{bucket_name} ~/basic-memory-{tenant_id} \
+  --vfs-cache-mode writes \
+  --dir-cache-time 10s \
+  --daemon
+```
+
+**Key Benefits:**
+- ✅ **Real-time access**: Files appear immediately as they're created/modified
+- ✅ **Transparent**: Works with any application that reads/writes files
+- ✅ **Low latency**: Direct access without sync delays
+- ✅ **Simple**: No periodic sync commands needed
+- ✅ **Homebrew compatible**: Works with Homebrew rclone (no FUSE required)
+
+**Limitations:**
+- ❌ **File watcher compatibility**: Some apps (Obsidian) don't detect changes over NFS
+- ❌ **Network dependency**: Requires active connection to cloud storage
+- ❌ **Potential conflicts**: Simultaneous edits from multiple locations can cause issues
+
+### Mount Profiles (Existing)
+
+**Already implemented profiles from SPEC-7 testing:**
+```python
+MOUNT_PROFILES = {
+    "fast": {
+        "cache_time": "5s",
+        "poll_interval": "3s",
+        "description": "Ultra-fast development (5s sync)"
+    },
+    "balanced": {
+        "cache_time": "10s",
+        "poll_interval": "5s",
+        "description": "Fast development (10-15s sync, recommended)"
+    },
+    "safe": {
+        "cache_time": "15s",
+        "poll_interval": "10s",
+        "description": "Conflict-aware mount with backup",
+        "extra_args": ["--conflict-suffix", ".conflict-{DateTimeExt}"]
+    }
+}
+```
+
+### CLI Commands (Existing)
+
+**Mount commands already implemented:**
+```bash
+basic-memory cloud mount                     # Mount with balanced profile
+basic-memory cloud mount --profile fast     # Ultra-fast caching
+basic-memory cloud mount --profile safe     # Conflict detection
+basic-memory cloud unmount                  # Clean unmount
+basic-memory cloud mount-status             # Show mount status
+```
+
+## User Choice: Mount vs Bisync
+
+### When to Use Each Approach
+
+| Use Case | Recommended Solution | Why |
+|----------|---------------------|-----|
+| **Obsidian users** | `bisync` | File watcher support for live preview |
+| **CLI/vim/emacs users** | `mount` | Direct file access, lower latency |
+| **Offline work** | `bisync` | Can work offline, sync when connected |
+| **Real-time collaboration** | `mount` | Immediate visibility of changes |
+| **Multiple machines** | `bisync` | Better conflict handling |
+| **Single machine** | `mount` | Simpler, more transparent |
+| **Development work** | Either | Both work well, user preference |
+| **Large files** | `mount` | Streaming access vs full download |
+
+### Installation Simplicity
+
+**Both approaches now use simple Homebrew installation:**
+```bash
+# Single installation command for both approaches
+brew install rclone
+
+# No macFUSE, no system modifications needed
+# Works immediately with both mount and bisync
+```
+
+### Implementation Status
+
+**Phase 4.1: bisync** (NEW)
+- [ ] Implement bisync command wrapper
+- [ ] Add watch mode with configurable intervals
+- [ ] Create conflict resolution workflows
+- [ ] Add filtering and safety options
+
+**Phase 4.2: mount** (EXISTING - ✅ IMPLEMENTED)
+- [x] NFS mount commands with profile support
+- [x] Mount management and cleanup
+- [x] Process monitoring and health checks
+- [x] Credential integration with cloud API
+
+**Both approaches share:**
+- [x] Credential management via cloud API
+- [x] Secure rclone configuration
+- [x] Tenant isolation and bucket scoping
+- [x] Simple Homebrew rclone installation
+
+
+Key Features:
+
+1. Cross-Platform rclone Installation (rclone_installer.py):
+- macOS: Homebrew → official script fallback
+- Linux: snap → apt → official script fallback
+- Windows: winget → chocolatey → scoop fallback
+- Automatic version detection and verification
+
+2. Smart rclone Configuration (rclone_config.py):
+- Automatic tenant-specific config generation
+- Three optimized mount profiles from your SPEC-7 testing:
+- fast: 5s sync (ultra-performance)
+- balanced: 10-15s sync (recommended default)
+- safe: 15s sync + conflict detection
+- Backup existing configs before modification
+
+3. Robust Mount Management (mount_commands.py):
+- Automatic tenant credential generation
+- Mount path management (~/basic-memory-{tenant-id})
+- Process lifecycle management (prevent duplicate mounts)
+- Orphaned process cleanup
+- Mount verification and health checking
+
+4. Clean Architecture (api_client.py):
+- Separated API client to avoid circular imports
+- Reuses existing authentication infrastructure
+- Consistent error handling and logging
+
+User Experience:
+
+One-Command Setup:
+basic-memory cloud setup
+```bash 
+# 1. Installs rclone automatically
+# 2. Authenticates with existing login
+# 3. Generates secure credentials  
+# 4. Configures rclone
+# 5. Performs initial mount
+```
+
+Profile-Based Mounting:
+basic-memory cloud mount --profile fast      # 5s sync
+basic-memory cloud mount --profile balanced  # 15s sync (default)
+basic-memory cloud mount --profile safe      # conflict detection
+
+Status Monitoring:
+basic-memory cloud mount-status
+```bash 
+# Shows: tenant info, mount path, sync profile, rclone processes
+```
+### local mount api 
+
+Endpoint 1: Get Tenant Info for user
+Purpose: Get tenant details for mounting
+- pass in jwt
+- service returns mount info
+
+**✅ IMPLEMENTED API Specification:**
+
+**Endpoint 1: GET /tenant/mount/info**
+- Purpose: Get tenant mount information without exposing credentials
+- Authentication: JWT token (tenant_id extracted from claims)
+
+Request:
+```
+GET /tenant/mount/info
+Authorization: Bearer {jwt_token}
+```
+
+Response:
+```json
+{
+    "tenant_id": "434252dd-d83b-4b20-bf70-8a950ff875c4",
+    "bucket_name": "basic-memory-434252dd",
+    "has_credentials": true,
+    "credentials_created_at": "2025-09-22T16:48:50.414694"
+}
+```
+
+**Endpoint 2: POST /tenant/mount/credentials**
+- Purpose: Generate NEW bucket-scoped S3 credentials for rclone mounting
+- Authentication: JWT token (tenant_id extracted from claims)
+- Multi-session: Creates new credentials without revoking existing ones
+
+Request:
+```
+POST /tenant/mount/credentials
+Authorization: Bearer {jwt_token}
+Content-Type: application/json
+```
+*Note: No request body needed - tenant_id extracted from JWT*
+
+Response:
+```json
+{
+    "tenant_id": "434252dd-d83b-4b20-bf70-8a950ff875c4",
+    "bucket_name": "basic-memory-434252dd",
+    "access_key": "test_access_key_12345",
+    "secret_key": "test_secret_key_abcdef",
+    "endpoint_url": "https://fly.storage.tigris.dev",
+    "region": "auto"
+}
+```
+
+**🔒 Security Notes:**
+- Secret key returned ONCE only - never stored in database
+- Credentials are bucket-scoped (cannot access other tenants' buckets)
+- Multiple active credentials supported per tenant (work laptop + personal machine)
+
+Implementation Notes
+
+Security:
+- Both endpoints require JWT authentication
+- Extract tenant_id from JWT claims (not request body)
+- Generate scoped credentials (not admin credentials)
+- Credentials should have bucket-specific access only
+
+Integration Points:
+- Use your existing StorageClient from SPEC-8 implementation
+- Leverage existing JWT middleware for tenant extraction
+- Return same credential format as your Tigris bucket provisioning
+
+Error Handling:
+- 401 if not authenticated
+- 403 if tenant doesn't exist
+- 500 if credential generation fails
+
+**🔄 Design Decisions:**
+
+1. **Secure Credential Flow (No Secret Storage)**
+
+Based on CLI flow analysis, we follow security best practices:
+- ✅ API generates both access_key + secret_key via Tigris IAM
+- ✅ Returns both in API response for immediate use
+- ✅ CLI uses credentials immediately to configure rclone
+- ✅ Database stores only metadata (access_key + policy_arn for cleanup)
+- ✅ rclone handles secure local credential storage
+- ❌ **Never store secret_key in database (even encrypted)**
+
+2. **CLI Credential Flow**
+```bash
+# CLI calls API
+POST /tenant/mount/credentials → {access_key, secret_key, ...}
+
+# CLI immediately configures rclone
+rclone config create basic-memory-{tenant_id} s3 \
+  access_key_id={access_key} \
+  secret_access_key={secret_key} \
+  endpoint=https://fly.storage.tigris.dev
+
+# Database tracks metadata only
+INSERT INTO tenant_mount_credentials (tenant_id, access_key, policy_arn, ...)
+```
+
+3. **Multiple Sessions Supported**
+
+- Users can have multiple active credential sets (work laptop, personal machine, etc.)
+- Each credential generation creates a new Tigris access key
+- List active credentials via API (shows access_key but never secret)
+
+4. **Failure Handling & Cleanup**
+
+- **Happy Path**: Credentials created → Used immediately → rclone configured
+- **Orphaned Credentials**: Background job revokes unused credentials
+- **API Failure Recovery**: Retry Tigris deletion with stored policy_arn
+- **Status Tracking**: Track tigris_deletion_status (pending/completed/failed)
+
+5. **Event Sourcing & Audit**
+
+- MountCredentialCreatedEvent
+- MountCredentialRevokedEvent
+- MountCredentialOrphanedEvent (for cleanup)
+- Full audit trail for security compliance
+
+6. **Tenant/Bucket Validation**
+
+- Verify tenant exists and has valid bucket before credential generation
+- Use existing StorageClient to validate bucket access
+- Prevent credential generation for inactive/invalid tenants
+
+📋 **Implemented API Endpoints:**
+
+```
+✅ IMPLEMENTED:
+GET    /tenant/mount/info                    # Get tenant/bucket info (no credentials exposed)
+POST   /tenant/mount/credentials             # Generate new credentials (returns secret once)
+GET    /tenant/mount/credentials             # List active credentials (no secrets)
+DELETE /tenant/mount/credentials/{cred_id}   # Revoke specific credentials
+```
+
+**API Implementation Status:**
+- ✅ **GET /tenant/mount/info**: Returns tenant_id, bucket_name, has_credentials, credentials_created_at
+- ✅ **POST /tenant/mount/credentials**: Creates new bucket-scoped access keys, returns access_key + secret_key once
+- ✅ **GET /tenant/mount/credentials**: Lists active credentials without exposing secret keys
+- ✅ **DELETE /tenant/mount/credentials/{cred_id}**: Revokes specific credentials with proper Tigris IAM cleanup
+- ✅ **Multi-session support**: Multiple active credentials per tenant (work laptop + personal machine)
+- ✅ **Security**: Secret keys never stored in database, returned once only for immediate use
+- ✅ **Comprehensive test suite**: 28 tests covering all scenarios including error handling and multi-session flows
+- ✅ **Dependency injection**: Clean integration with existing FastAPI architecture
+- ✅ **Production-ready configuration**: Tigris credentials properly configured for tenant machines
+
+🗄️ **Secure Database Schema:**
+
+```sql
+CREATE TABLE tenant_mount_credentials (
+  id UUID PRIMARY KEY,
+  tenant_id UUID REFERENCES tenant(id),
+  access_key VARCHAR(255) NOT NULL,
+  -- secret_key REMOVED - never store secrets (security best practice)
+  policy_arn VARCHAR(255) NOT NULL,           -- For Tigris IAM cleanup
+  tigris_deletion_status VARCHAR(20) DEFAULT 'pending',  -- Track cleanup
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW(),
+  revoked_at TIMESTAMP NULL,
+  last_used_at TIMESTAMP NULL,               -- Track usage for orphan cleanup
+  description VARCHAR(255) DEFAULT 'CLI mount credentials'
+);
+```
+
+**Security Benefits:**
+- ✅ Database breach cannot expose secrets
+- ✅ Follows "secrets don't persist" security principle
+- ✅ Meets compliance requirements (SOC2, etc.)
+- ✅ Reduced attack surface
+- ✅ CLI gets credentials once and stores securely via rclone

specs/SPEC-9-1 Follow-Ups- Conflict, Sync, and Observability.md

@@ -0,0 +1,390 @@
+---
+title: 'SPEC-9-1 Follow-Ups: Conflict, Sync, and Observability'
+type: tasklist
+permalink: specs/spec-9-follow-ups-conflict-sync-and-observability
+related: specs/spec-9-multi-project-bisync
+status: revised
+revision_date: 2025-10-03
+---
+
+# SPEC-9-1 Follow-Ups: Conflict, Sync, and Observability
+
+**REVISED 2025-10-03:** Simplified to leverage rclone built-ins instead of custom conflict handling.
+
+**Context:** SPEC-9 delivered multi-project bidirectional sync and a unified CLI. This follow-up focuses on **observability and safety** using rclone's built-in capabilities rather than reinventing conflict handling.
+
+**Design Philosophy: "Be Dumb Like Git"**
+- Let rclone bisync handle conflict detection (it already does this)
+- Make conflicts visible and recoverable, don't prevent them
+- Cloud is always the winner on conflict (cloud-primary model)
+- Users who want version history can just use Git locally in their sync directory
+
+**What Changed from Original Version:**
+- **Replaced:** Custom `.bmmeta` sidecars → Use rclone's `.bisync/` state tracking
+- **Replaced:** Custom conflict detection → Use rclone bisync 3-way merge
+- **Replaced:** Tombstone files → rclone delete tracking handles this
+- **Replaced:** Distributed lease → Local process lock only (document multi-device warning)
+- **Replaced:** S3 versioning service → Users just use Git locally if they want history
+- **Deferred:** SPEC-14 Git integration → Postponed to teams/multi-user features
+
+## ✅ Now 
+- [ ] **Local process lock**: Prevent concurrent bisync runs on same device (`~/.basic-memory/sync.lock`)
+- [ ] **Structured sync reports**: Parse rclone bisync output into JSON reports (creates/updates/deletes/conflicts, bytes, duration); `bm sync --report`
+- [ ] **Multi-device warning**: Document that users should not run `--watch` on multiple devices simultaneously
+- [ ] **Version control guidance**: Document pattern for users to use Git locally in their sync directory if they want version history
+- [ ] **Docs polish**: cloud-mode toggle, mount↔bisync directory isolation, conflict semantics, quick start, migration guide, short demo clip/GIF
+
+## 🔜 Next
+- [ ] **Observability commands**: `bm conflicts list`, `bm sync history` to view sync reports and conflicts
+- [ ] **Conflict resolution UI**: `bm conflicts resolve <file>` to interactively pick winner from conflict files
+- [ ] **Selective sync**: allow include/exclude by project; per-project profile (safe/balanced/fast)
+
+## 🧭 Later
+- [ ] **Near real-time sync**: File watcher → targeted `rclone copy` for individual files (keep bisync as backstop)
+- [ ] **Sharing / scoped tokens**: cross-tenant/project access
+- [ ] **Bandwidth controls & backpressure**: policy for large repos
+- [ ] **Client-side encryption (optional)**: with clear trade-offs
+
+## 📏 Acceptance criteria (for "Now" items)
+- [ ] Local process lock prevents concurrent bisync runs on same device
+- [ ] rclone bisync conflict files visible and documented (`file.conflict1.md`, `file.conflict2.md`)
+- [ ] `bm sync --report` generates parsable JSON with sync statistics
+- [ ] Documentation clearly warns about multi-device `--watch` mode
+- [ ] Documentation shows users how to use Git locally for version history
+
+## What We're NOT Building (Deferred to rclone)
+- ❌ Custom `.bmmeta` sidecars (rclone tracks state in `.bisync/` workdir)
+- ❌ Custom conflict detection (rclone bisync already does 3-way merge detection)
+- ❌ Tombstone files (S3 versioning + rclone delete tracking handles this)
+- ❌ Distributed lease (low probability issue, rclone detects state divergence)
+- ❌ Rename/move tracking (rclone has size+modtime heuristics built-in)
+
+## Implementation Summary
+
+**Current State (SPEC-9):**
+- ✅ rclone bisync with 3 profiles (safe/balanced/fast)
+- ✅ `--max-delete` safety limits (10/25/50 files)
+- ✅ `--conflict-resolve=newer` for auto-resolution
+- ✅ Watch mode: `bm sync --watch` (60s intervals)
+- ✅ Integrity checking: `bm cloud check`
+- ✅ Mount vs bisync directory isolation
+
+**What's Needed (This Spec):**
+1. **Process lock** - Simple file-based lock in `~/.basic-memory/sync.lock`
+2. **Sync reports** - Parse rclone output, save to `~/.basic-memory/sync-history/`
+3. **Documentation** - Multi-device warnings, conflict resolution workflow, Git usage pattern
+
+**User Model:**
+- Cloud is always the winner on conflict (cloud-primary)
+- rclone creates `.conflict` files for divergent edits
+- Users who want version history just use Git in their local sync directory
+- Users warned: don't run `--watch` on multiple devices
+
+## Decision Rationale & Trade-offs
+
+### Why Trust rclone Instead of Custom Conflict Handling?
+
+**rclone bisync already provides:**
+- 3-way merge detection (compares local, remote, and last-known state)
+- File state tracking in `.bisync/` workdir (hashes, modtimes)
+- Automatic conflict file creation: `file.conflict1.md`, `file.conflict2.md`
+- Rename detection via size+modtime heuristics
+- Delete tracking (prevents resurrection of deleted files)
+- Battle-tested with extensive edge case handling
+
+**What we'd have to build with custom approach:**
+- Per-file metadata tracking (`.bmmeta` sidecars)
+- 3-way diff algorithm
+- Conflict detection logic
+- Tombstone files for deletes
+- Rename/move detection
+- Testing for all edge cases
+
+**Decision:** Use what rclone already does well. Don't reinvent the wheel.
+
+### Why Let Users Use Git Locally Instead of Building Versioning?
+
+**The simplest solution: Just use Git**
+
+Users who want version history can literally just use Git in their sync directory:
+
+```bash
+cd ~/basic-memory-cloud-sync/
+git init
+git add .
+git commit -m "backup"
+
+# Push to their own GitHub if they want
+git remote add origin git@github.com:user/my-knowledge.git
+git push
+```
+
+**Why this is perfect:**
+- ✅ We build nothing
+- ✅ Users who want Git... just use Git
+- ✅ Users who don't care... don't need to
+- ✅ rclone bisync already handles sync conflicts
+- ✅ Users own their data, they can version it however they want (Git, Time Machine, etc.)
+
+**What we'd have to build for S3 versioning:**
+- API to enable versioning on Tigris buckets
+  - **Problem**: Tigris doesn't support S3 bucket versioning
+- Restore commands: `bm cloud restore --version-id`
+- Version listing: `bm cloud versions <path>`
+- Lifecycle policies for version retention
+- Documentation and user education
+
+**What we'd have to build for SPEC-14 Git integration:**
+- Committer service (daemon watching `/app/data/`)
+- Puller service (webhook handler for GitHub pushes)
+- Git LFS for large files
+- Loop prevention between Git ↔ bisync ↔ local
+- Merge conflict handling at TWO layers (rclone + Git)
+- Webhook infrastructure and monitoring
+
+**Decision:** Don't build version control. Document the pattern. "The easiest problem to solve is the one you avoid."
+
+**When to revisit:** Teams/multi-user features where server-side version control becomes necessary for collaboration.
+
+### Why No Distributed Lease?
+
+**Low probability issue:**
+- Requires user to manually run `bm sync` on multiple devices at exact same time
+- Most users run `--watch` on one primary device
+- rclone bisync detects state divergence and fails safely
+
+**Safety nets in place:**
+- Local process lock prevents concurrent runs on same device
+- rclone bisync aborts if bucket state changed during sync
+- S3 versioning recovers from any overwrites
+- Documentation warns against multi-device `--watch`
+
+**Failure mode:**
+```bash
+# Device A and B sync simultaneously
+Device A: bm sync → succeeds
+Device B: bm sync → "Error: path has changed, run --resync"
+
+# User fixes with resync
+Device B: bm sync --resync → establishes new baseline
+```
+
+**Decision:** Document the issue, add local lock, defer distributed coordination until users report actual problems.
+
+### Cloud-Primary Conflict Model
+
+**User mental model:**
+- Cloud is the source of truth (like Dropbox/iCloud)
+- Local is working copy
+- On conflict: cloud wins, local edits → `.conflict` file
+- User manually picks winner
+
+**Why this works:**
+- Simpler than bidirectional merge (no automatic resolution risk)
+- Matches user expectations from Dropbox
+- S3 versioning provides safety net for overwrites
+- Clear recovery path: restore from S3 version if needed
+
+**Example workflow:**
+```bash
+# Edit file on Device A and Device B while offline
+# Both devices come online and sync
+
+Device A: bm sync
+# → Pushes to cloud first, becomes canonical version
+
+Device B: bm sync
+# → Detects conflict
+# → Cloud version: work/notes.md
+# → Local version: work/notes.md.conflict1
+# → User manually merges or picks winner
+
+# Restore if needed
+bm cloud restore work/notes.md --version-id abc123
+```
+
+## Implementation Details
+
+### 1. Local Process Lock
+
+```python
+# ~/.basic-memory/sync.lock
+import os
+import psutil
+from pathlib import Path
+
+class SyncLock:
+    def __init__(self):
+        self.lock_file = Path.home() / '.basic-memory' / 'sync.lock'
+
+    def acquire(self):
+        if self.lock_file.exists():
+            pid = int(self.lock_file.read_text())
+            if psutil.pid_exists(pid):
+                raise BisyncError(
+                    f"Sync already running (PID {pid}). "
+                    f"Wait for completion or kill stale process."
+                )
+            # Stale lock, remove it
+            self.lock_file.unlink()
+
+        self.lock_file.write_text(str(os.getpid()))
+
+    def release(self):
+        if self.lock_file.exists():
+            self.lock_file.unlink()
+
+    def __enter__(self):
+        self.acquire()
+        return self
+
+    def __exit__(self, *args):
+        self.release()
+
+# Usage
+with SyncLock():
+    run_rclone_bisync()
+```
+
+### 3. Sync Report Parsing
+
+```python
+# Parse rclone bisync output
+import json
+from datetime import datetime
+from pathlib import Path
+
+def parse_sync_report(rclone_output: str, duration: float, exit_code: int) -> dict:
+    """Parse rclone bisync output into structured report."""
+
+    # rclone bisync outputs lines like:
+    # "Synching Path1 /local/path with Path2 remote:bucket"
+    # "- Path1    File was copied to Path2"
+    # "Bisync successful"
+
+    report = {
+        "timestamp": datetime.now().isoformat(),
+        "duration_seconds": duration,
+        "exit_code": exit_code,
+        "success": exit_code == 0,
+        "files_created": 0,
+        "files_updated": 0,
+        "files_deleted": 0,
+        "conflicts": [],
+        "errors": []
+    }
+
+    for line in rclone_output.split('\n'):
+        if 'was copied to' in line:
+            report['files_created'] += 1
+        elif 'was updated in' in line:
+            report['files_updated'] += 1
+        elif 'was deleted from' in line:
+            report['files_deleted'] += 1
+        elif '.conflict' in line:
+            report['conflicts'].append(line.strip())
+        elif 'ERROR' in line:
+            report['errors'].append(line.strip())
+
+    return report
+
+def save_sync_report(report: dict):
+    """Save sync report to history."""
+    history_dir = Path.home() / '.basic-memory' / 'sync-history'
+    history_dir.mkdir(parents=True, exist_ok=True)
+
+    timestamp = datetime.now().strftime('%Y%m%d-%H%M%S')
+    report_file = history_dir / f'{timestamp}.json'
+
+    report_file.write_text(json.dumps(report, indent=2))
+
+# Usage in run_bisync()
+start_time = time.time()
+result = subprocess.run(bisync_cmd, capture_output=True, text=True)
+duration = time.time() - start_time
+
+report = parse_sync_report(result.stdout, duration, result.returncode)
+save_sync_report(report)
+
+if report['conflicts']:
+    console.print(f"[yellow]⚠ {len(report['conflicts'])} conflict(s) detected[/yellow]")
+    console.print("[dim]Run 'bm conflicts list' to view[/dim]")
+```
+
+### 4. User Commands
+
+```bash
+# View sync history
+bm sync history
+# → Lists recent syncs from ~/.basic-memory/sync-history/*.json
+# → Shows: timestamp, duration, files changed, conflicts, errors
+
+# View current conflicts
+bm conflicts list
+# → Scans sync directory for *.conflict* files
+# → Shows: file path, conflict versions, timestamps
+
+# Restore from S3 version
+bm cloud restore work/notes.md --version-id abc123
+# → Uses aws s3api get-object with version-id
+# → Downloads to original path
+
+bm cloud restore work/notes.md --timestamp "2025-10-03 14:30"
+# → Lists versions, finds closest to timestamp
+# → Downloads that version
+
+# List file versions
+bm cloud versions work/notes.md
+# → Uses aws s3api list-object-versions
+# → Shows: version-id, timestamp, size, author
+
+# Interactive conflict resolution
+bm conflicts resolve work/notes.md
+# → Shows both versions side-by-side
+# → Prompts: Keep local, keep cloud, merge manually, restore from S3 version
+# → Cleans up .conflict files after resolution
+```
+
+## Success Metrics & Monitoring
+
+**Phase 1 (v1) - Basic Safety:**
+- [ ] Conflict detection rate < 5% of syncs (measure in telemetry)
+- [ ] User can resolve conflicts within 5 minutes (UX testing)
+- [ ] Documentation prevents 90% of multi-device issues
+
+**Phase 2 (v2) - Observability:**
+- [ ] 80% of users check `bm sync history` when troubleshooting
+- [ ] Average time to restore from S3 version < 2 minutes
+- 
+- [ ] Conflict resolution success rate > 95%
+
+**What to measure:**
+```python
+# Telemetry in sync reports
+{
+    "conflict_rate": conflicts / total_syncs,
+    "multi_device_collisions": count_state_divergence_errors,
+    "version_restores": count_restore_operations,
+    "avg_sync_duration": sum(durations) / count,
+    "max_delete_trips": count_max_delete_aborts
+}
+```
+
+**When to add distributed lease:**
+- Multi-device collision rate > 5% of syncs
+- User complaints about state divergence errors
+- Evidence that local lock isn't sufficient
+
+**When to revisit Git (SPEC-14):**
+- Teams feature launches (multi-user collaboration)
+- Users request commit messages / audit trail
+- PR-based review workflow becomes valuable
+
+## Links
+- SPEC-9: `specs/spec-9-multi-project-bisync`
+- SPEC-14: `specs/spec-14-cloud-git-versioning` (deferred in favor of S3 versioning)
+- rclone bisync docs: https://rclone.org/bisync/
+- Tigris S3 versioning: https://www.tigrisdata.com/docs/buckets/versioning/
+
+---
+**Owner:** <assign>  |  **Review cadence:** weekly in standup  |  **Last updated:** 2025-10-03

src/basic_memory/__init__.py

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

src/basic_memory/alembic/versions/a1b2c3d4e5f6_fix_project_foreign_keys.py

@@ -20,14 +20,14 @@ depends_on: Union[str, Sequence[str], None] = None
 
 def upgrade() -> None:
     """Re-establish foreign key constraints that were lost during project table recreation.
-    
+
     The migration 647e7a75e2cd recreated the project table but did not re-establish
     the foreign key constraint from entity.project_id to project.id, causing
     foreign key constraint failures when trying to delete projects with related entities.
     """
     # SQLite doesn't allow adding foreign key constraints to existing tables easily
     # We need to be careful and handle the case where the constraint might already exist
-    
+
     with op.batch_alter_table("entity", schema=None) as batch_op:
         # Try to drop existing foreign key constraint (may not exist)
         try:
@@ -35,19 +35,15 @@ def upgrade() -> None:
         except Exception:
             # Constraint may not exist, which is fine - we'll create it next
             pass
-        
+
         # Add the foreign key constraint with CASCADE DELETE
         # This ensures that when a project is deleted, all related entities are also deleted
         batch_op.create_foreign_key(
-            "fk_entity_project_id", 
-            "project", 
-            ["project_id"], 
-            ["id"],
-            ondelete="CASCADE"
+            "fk_entity_project_id", "project", ["project_id"], ["id"], ondelete="CASCADE"
         )
 
 
 def downgrade() -> None:
     """Remove the foreign key constraint."""
     with op.batch_alter_table("entity", schema=None) as batch_op:
-        batch_op.drop_constraint("fk_entity_project_id", type_="foreignkey")
+        batch_op.drop_constraint("fk_entity_project_id", type_="foreignkey")

src/basic_memory/api/app.py

@@ -21,19 +21,25 @@ from basic_memory.api.routers import (
     prompt_router,
 )
 from basic_memory.config import ConfigManager
-from basic_memory.services.initialization import initialize_app, initialize_file_sync
+from basic_memory.services.initialization import initialize_file_sync, initialize_app
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):  # pragma: no cover
-    """Lifecycle manager for the FastAPI app."""
+    """Lifecycle manager for the FastAPI app. Not called in stdio mcp mode"""
 
     app_config = ConfigManager().config
-    # Initialize app and database
     logger.info("Starting Basic Memory API")
-    print(f"fastapi {app_config.projects}")
+
     await initialize_app(app_config)
 
+    # Cache database connections in app state for performance
+    logger.info("Initializing database and caching connections...")
+    engine, session_maker = await db.get_or_create_db(app_config.database_path)
+    app.state.engine = engine
+    app.state.session_maker = session_maker
+    logger.info("Database connections cached in app state")
+
     logger.info(f"Sync changes enabled: {app_config.sync_changes}")
     if app_config.sync_changes:
         # start file sync task in background

src/basic_memory/api/routers/knowledge_router.py

@@ -27,6 +27,26 @@ from basic_memory.schemas.base import Permalink, Entity
 
 router = APIRouter(prefix="/knowledge", tags=["knowledge"])
 
+
+async def resolve_relations_background(sync_service, entity_id: int, entity_permalink: str) -> None:
+    """Background task to resolve relations for a specific entity.
+
+    This runs asynchronously after the API response is sent, preventing
+    long delays when creating entities with many relations.
+    """
+    try:
+        # Only resolve relations for the newly created entity
+        await sync_service.resolve_relations(entity_id=entity_id)
+        logger.debug(
+            f"Background: Resolved relations for entity {entity_permalink} (id={entity_id})"
+        )
+    except Exception as e:
+        # Log but don't fail - this is a background task
+        logger.warning(
+            f"Background: Failed to resolve relations for entity {entity_permalink}: {e}"
+        )
+
+
 ## Create endpoints
 
 
@@ -88,15 +108,12 @@ 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
+    # Schedule relation resolution as a background task for new entities
+    # This prevents blocking the API response while resolving potentially many relations
     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}")
+        background_tasks.add_task(
+            resolve_relations_background, sync_service, entity.id, entity.permalink or ""
+        )
 
     result = EntityResponse.model_validate(entity)
 

src/basic_memory/api/routers/project_router.py

@@ -1,11 +1,17 @@
 """Router for project management."""
 
 import os
-from fastapi import APIRouter, HTTPException, Path, Body
+from fastapi import APIRouter, HTTPException, Path, Body, BackgroundTasks
 from typing import Optional
+from loguru import logger
 
-from basic_memory.deps import ProjectServiceDep, ProjectPathDep
-from basic_memory.schemas import ProjectInfoResponse
+from basic_memory.deps import (
+    ProjectConfigDep,
+    ProjectServiceDep,
+    ProjectPathDep,
+    SyncServiceDep,
+)
+from basic_memory.schemas import ProjectInfoResponse, SyncReportResponse
 from basic_memory.schemas.project_info import (
     ProjectList,
     ProjectItem,
@@ -14,6 +20,7 @@ from basic_memory.schemas.project_info import (
 )
 
 # Router for resources in a specific project
+# The ProjectPathDep is used in the path as a prefix, so the request path is like /{project}/project/info
 project_router = APIRouter(prefix="/project", tags=["project"])
 
 # Router for managing project resources
@@ -29,6 +36,25 @@ async def get_project_info(
     return await project_service.get_project_info(project)
 
 
+@project_router.get("/item", response_model=ProjectItem)
+async def get_project(
+    project_service: ProjectServiceDep,
+    project: ProjectPathDep,
+) -> ProjectItem:
+    """Get bassic info about the specified Basic Memory project."""
+    found_project = await project_service.get_project(project)
+    if not found_project:
+        raise HTTPException(
+            status_code=404, detail=f"Project: '{project}' does not exist"
+        )  # pragma: no cover
+
+    return ProjectItem(
+        name=found_project.name,
+        path=found_project.path,
+        is_default=found_project.is_default or False,
+    )
+
+
 # Update a project
 @project_router.patch("/{name}", response_model=ProjectStatusResponse)
 async def update_project(
@@ -77,6 +103,54 @@ async def update_project(
         raise HTTPException(status_code=400, detail=str(e))
 
 
+# Sync project filesystem
+@project_router.post("/sync")
+async def sync_project(
+    background_tasks: BackgroundTasks,
+    sync_service: SyncServiceDep,
+    project_config: ProjectConfigDep,
+):
+    """Force project filesystem sync to database.
+
+    Scans the project directory and updates the database with any new or modified files.
+
+    Args:
+        background_tasks: FastAPI background tasks
+        sync_service: Sync service for this project
+        project_config: Project configuration
+
+    Returns:
+        Response confirming sync was initiated
+    """
+    background_tasks.add_task(sync_service.sync, project_config.home, project_config.name)
+    logger.info(f"Filesystem sync initiated for project: {project_config.name}")
+
+    return {
+        "status": "sync_started",
+        "message": f"Filesystem sync initiated for project '{project_config.name}'",
+    }
+
+
+@project_router.post("/status", response_model=SyncReportResponse)
+async def project_sync_status(
+    sync_service: SyncServiceDep,
+    project_config: ProjectConfigDep,
+) -> SyncReportResponse:
+    """Scan directory for changes compared to database state.
+
+    Args:
+        sync_service: Sync service for this project
+        project_config: Project configuration
+
+    Returns:
+        Scan report with details on files that need syncing
+    """
+    logger.info(f"Scanning filesystem for project: {project_config.name}")
+    sync_report = await sync_service.scan(project_config.home)
+
+    return SyncReportResponse.from_sync_report(sync_report)
+
+
 # List all available projects
 @project_resource_router.get("/projects", response_model=ProjectList)
 async def list_projects(
@@ -217,8 +291,29 @@ async def set_default_project(
         raise HTTPException(status_code=400, detail=str(e))
 
 
+# Get the default project
+@project_resource_router.get("/default", response_model=ProjectItem)
+async def get_default_project(
+    project_service: ProjectServiceDep,
+) -> ProjectItem:
+    """Get the default project.
+
+    Returns:
+        Response with project default information
+    """
+    # 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"
+        )
+
+    return ProjectItem(name=default_project.name, path=default_project.path, is_default=True)
+
+
 # Synchronize projects between config and database
-@project_resource_router.post("/sync", response_model=ProjectStatusResponse)
+@project_resource_router.post("/config/sync", response_model=ProjectStatusResponse)
 async def synchronize_projects(
     project_service: ProjectServiceDep,
 ) -> ProjectStatusResponse:

src/basic_memory/cli/app.py

@@ -2,8 +2,7 @@ from typing import Optional
 
 import typer
 
-from basic_memory.config import get_project_config, ConfigManager
-from basic_memory.mcp.project_session import session
+from basic_memory.config import ConfigManager
 
 
 def version_callback(value: bool) -> None:
@@ -11,10 +10,7 @@ def version_callback(value: bool) -> None:
     if value:  # pragma: no cover
         import basic_memory
 
-        config = get_project_config()
         typer.echo(f"Basic Memory version: {basic_memory.__version__}")
-        typer.echo(f"Current project: {config.project}")
-        typer.echo(f"Project path: {config.home}")
         raise typer.Exit()
 
 
@@ -24,13 +20,6 @@ app = typer.Typer(name="basic-memory")
 @app.callback()
 def app_callback(
     ctx: typer.Context,
-    project: Optional[str] = typer.Option(
-        None,
-        "--project",
-        "-p",
-        help="Specify which project to use 1",
-        envvar="BASIC_MEMORY_PROJECT",
-    ),
     version: Optional[bool] = typer.Option(
         None,
         "--version",
@@ -49,25 +38,17 @@ def app_callback(
         app_config = ConfigManager().config
         ensure_initialization(app_config)
 
-        # Initialize MCP session with the specified project or default
-        if project:  # pragma: no cover
-            # Use the project specified via --project flag
-            current_project_config = get_project_config(project)
-            session.set_current_project(current_project_config.name)
-
-            # Update the global config to use this project
-            from basic_memory.config import update_current_project
-
-            update_current_project(project)
-        else:
-            # Use the default project
-            current_project = app_config.default_project
-            session.set_current_project(current_project)
-
 
+## import
 # Register sub-command groups
 import_app = typer.Typer(help="Import data from various sources")
 app.add_typer(import_app, name="import")
 
-claude_app = typer.Typer()
+claude_app = typer.Typer(help="Import Conversations from Claude JSON export.")
 import_app.add_typer(claude_app, name="claude")
+
+
+## cloud
+
+cloud_app = typer.Typer(help="Access Basic Memory Cloud")
+app.add_typer(cloud_app, name="cloud")

src/basic_memory/cli/auth.py

@@ -0,0 +1,277 @@
+"""WorkOS OAuth Device Authorization for CLI."""
+
+import base64
+import hashlib
+import json
+import os
+import secrets
+import time
+import webbrowser
+
+import httpx
+from rich.console import Console
+
+from basic_memory.config import ConfigManager
+
+console = Console()
+
+
+class CLIAuth:
+    """Handles WorkOS OAuth Device Authorization for CLI tools."""
+
+    def __init__(self, client_id: str, authkit_domain: str):
+        self.client_id = client_id
+        self.authkit_domain = authkit_domain
+        app_config = ConfigManager().config
+        # Store tokens in data dir
+        self.token_file = app_config.data_dir_path / "basic-memory-cloud.json"
+        # PKCE parameters
+        self.code_verifier = None
+        self.code_challenge = None
+
+    def generate_pkce_pair(self) -> tuple[str, str]:
+        """Generate PKCE code verifier and challenge."""
+        # Generate code verifier (43-128 characters)
+        code_verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).decode("utf-8")
+        code_verifier = code_verifier.rstrip("=")
+
+        # Generate code challenge (SHA256 hash of verifier)
+        challenge_bytes = hashlib.sha256(code_verifier.encode("utf-8")).digest()
+        code_challenge = base64.urlsafe_b64encode(challenge_bytes).decode("utf-8")
+        code_challenge = code_challenge.rstrip("=")
+
+        return code_verifier, code_challenge
+
+    async def request_device_authorization(self) -> dict | None:
+        """Request device authorization from WorkOS with PKCE."""
+        device_auth_url = f"{self.authkit_domain}/oauth2/device_authorization"
+
+        # Generate PKCE pair
+        self.code_verifier, self.code_challenge = self.generate_pkce_pair()
+
+        data = {
+            "client_id": self.client_id,
+            "scope": "openid profile email offline_access",
+            "code_challenge": self.code_challenge,
+            "code_challenge_method": "S256",
+        }
+
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.post(device_auth_url, data=data)
+
+                if response.status_code == 200:
+                    return response.json()
+                else:
+                    console.print(
+                        f"[red]Device authorization failed: {response.status_code} - {response.text}[/red]"
+                    )
+                    return None
+        except Exception as e:
+            console.print(f"[red]Device authorization error: {e}[/red]")
+            return None
+
+    def display_user_instructions(self, device_response: dict) -> None:
+        """Display user instructions for device authorization."""
+        user_code = device_response["user_code"]
+        verification_uri = device_response["verification_uri"]
+        verification_uri_complete = device_response.get("verification_uri_complete")
+
+        console.print("\n[bold blue]🔐 Authentication Required[/bold blue]")
+        console.print("\nTo authenticate, please visit:")
+        console.print(f"[bold cyan]{verification_uri}[/bold cyan]")
+        console.print(f"\nAnd enter this code: [bold yellow]{user_code}[/bold yellow]")
+
+        if verification_uri_complete:
+            console.print("\nOr for one-click access, visit:")
+            console.print(f"[bold green]{verification_uri_complete}[/bold green]")
+
+            # Try to open browser automatically
+            try:
+                console.print("\n[dim]Opening browser automatically...[/dim]")
+                webbrowser.open(verification_uri_complete)
+            except Exception:
+                pass  # Silently fail if browser can't be opened
+
+        console.print("\n[dim]Waiting for you to complete authentication in your browser...[/dim]")
+
+    async def poll_for_token(self, device_code: str, interval: int = 5) -> dict | None:
+        """Poll the token endpoint until user completes authentication."""
+        token_url = f"{self.authkit_domain}/oauth2/token"
+
+        data = {
+            "client_id": self.client_id,
+            "device_code": device_code,
+            "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+            "code_verifier": self.code_verifier,
+        }
+
+        max_attempts = 60  # 5 minutes with 5-second intervals
+        current_interval = interval
+
+        for _attempt in range(max_attempts):
+            try:
+                async with httpx.AsyncClient() as client:
+                    response = await client.post(token_url, data=data)
+
+                    if response.status_code == 200:
+                        return response.json()
+
+                    # Parse error response
+                    try:
+                        error_data = response.json()
+                        error = error_data.get("error")
+                    except Exception:
+                        error = "unknown_error"
+
+                    if error == "authorization_pending":
+                        # User hasn't completed auth yet, keep polling
+                        pass
+                    elif error == "slow_down":
+                        # Increase polling interval
+                        current_interval += 5
+                        console.print("[yellow]Slowing down polling rate...[/yellow]")
+                    elif error == "access_denied":
+                        console.print("[red]Authentication was denied by user[/red]")
+                        return None
+                    elif error == "expired_token":
+                        console.print("[red]Device code has expired. Please try again.[/red]")
+                        return None
+                    else:
+                        console.print(f"[red]Token polling error: {error}[/red]")
+                        return None
+
+            except Exception as e:
+                console.print(f"[red]Token polling request error: {e}[/red]")
+
+            # Wait before next poll
+            await self._async_sleep(current_interval)
+
+        console.print("[red]Authentication timeout. Please try again.[/red]")
+        return None
+
+    async def _async_sleep(self, seconds: int) -> None:
+        """Async sleep utility."""
+        import asyncio
+
+        await asyncio.sleep(seconds)
+
+    def save_tokens(self, tokens: dict) -> None:
+        """Save tokens to project root as .bm-auth.json."""
+        token_data = {
+            "access_token": tokens["access_token"],
+            "refresh_token": tokens.get("refresh_token"),
+            "expires_at": int(time.time()) + tokens.get("expires_in", 3600),
+            "token_type": tokens.get("token_type", "Bearer"),
+        }
+
+        with open(self.token_file, "w") as f:
+            json.dump(token_data, f, indent=2)
+
+        # Secure the token file
+        os.chmod(self.token_file, 0o600)
+
+        console.print(f"[green]✓ Tokens saved to {self.token_file}[/green]")
+
+    def load_tokens(self) -> dict | None:
+        """Load tokens from .bm-auth.json file."""
+        if not self.token_file.exists():
+            return None
+
+        try:
+            with open(self.token_file) as f:
+                return json.load(f)
+        except (OSError, json.JSONDecodeError):
+            return None
+
+    def is_token_valid(self, tokens: dict) -> bool:
+        """Check if stored token is still valid."""
+        expires_at = tokens.get("expires_at", 0)
+        # Add 60 second buffer for clock skew
+        return time.time() < (expires_at - 60)
+
+    async def refresh_token(self, refresh_token: str) -> dict | None:
+        """Refresh access token using refresh token."""
+        token_url = f"{self.authkit_domain}/oauth2/token"
+
+        data = {
+            "client_id": self.client_id,
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+        }
+
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.post(token_url, data=data)
+
+                if response.status_code == 200:
+                    return response.json()
+                else:
+                    console.print(
+                        f"[red]Token refresh failed: {response.status_code} - {response.text}[/red]"
+                    )
+                    return None
+        except Exception as e:
+            console.print(f"[red]Token refresh error: {e}[/red]")
+            return None
+
+    async def get_valid_token(self) -> str | None:
+        """Get valid access token, refresh if needed."""
+        tokens = self.load_tokens()
+        if not tokens:
+            return None
+
+        if self.is_token_valid(tokens):
+            return tokens["access_token"]
+
+        # Token expired - try to refresh if we have a refresh token
+        refresh_token = tokens.get("refresh_token")
+        if refresh_token:
+            console.print("[yellow]Access token expired, refreshing...[/yellow]")
+
+            new_tokens = await self.refresh_token(refresh_token)
+            if new_tokens:
+                # Save new tokens (may include rotated refresh token)
+                self.save_tokens(new_tokens)
+                console.print("[green]✓ Token refreshed successfully[/green]")
+                return new_tokens["access_token"]
+            else:
+                console.print("[yellow]Token refresh failed. Please run 'login' again.[/yellow]")
+                return None
+        else:
+            console.print("[yellow]No refresh token available. Please run 'login' again.[/yellow]")
+            return None
+
+    async def login(self) -> bool:
+        """Perform OAuth Device Authorization login flow."""
+        console.print("[blue]Initiating WorkOS authentication...[/blue]")
+
+        # Step 1: Request device authorization
+        device_response = await self.request_device_authorization()
+        if not device_response:
+            return False
+
+        # Step 2: Display user instructions
+        self.display_user_instructions(device_response)
+
+        # Step 3: Poll for token
+        device_code = device_response["device_code"]
+        interval = device_response.get("interval", 5)
+
+        tokens = await self.poll_for_token(device_code, interval)
+        if not tokens:
+            return False
+
+        # Step 4: Save tokens
+        self.save_tokens(tokens)
+
+        console.print("\n[green]✅ Successfully authenticated with WorkOS![/green]")
+        return True
+
+    def logout(self) -> None:
+        """Remove stored authentication tokens."""
+        if self.token_file.exists():
+            self.token_file.unlink()
+            console.print("[green]✓ Logged out successfully[/green]")
+        else:
+            console.print("[yellow]No stored authentication found[/yellow]")

src/basic_memory/cli/commands/cloud/__init__.py

@@ -0,0 +1,5 @@
+"""Cloud commands package."""
+
+# Import all commands to register them with typer
+from basic_memory.cli.commands.cloud.core_commands import *  # noqa: F401,F403
+from basic_memory.cli.commands.cloud.api_client import get_authenticated_headers  # noqa: F401

src/basic_memory/cli/commands/cloud/api_client.py

@@ -0,0 +1,112 @@
+"""Cloud API client utilities."""
+
+from typing import Optional
+
+import httpx
+import typer
+from rich.console import Console
+
+from basic_memory.cli.auth import CLIAuth
+from basic_memory.config import ConfigManager
+
+console = Console()
+
+
+class CloudAPIError(Exception):
+    """Exception raised for cloud API errors."""
+
+    def __init__(
+        self, message: str, status_code: Optional[int] = None, detail: Optional[dict] = None
+    ):
+        super().__init__(message)
+        self.status_code = status_code
+        self.detail = detail or {}
+
+
+class SubscriptionRequiredError(CloudAPIError):
+    """Exception raised when user needs an active subscription."""
+
+    def __init__(self, message: str, subscribe_url: str):
+        super().__init__(message, status_code=403, detail={"error": "subscription_required"})
+        self.subscribe_url = subscribe_url
+
+
+def get_cloud_config() -> tuple[str, str, str]:
+    """Get cloud OAuth configuration from config."""
+    config_manager = ConfigManager()
+    config = config_manager.config
+    return config.cloud_client_id, config.cloud_domain, config.cloud_host
+
+
+async def get_authenticated_headers() -> dict[str, str]:
+    """
+    Get authentication headers with JWT token.
+    handles jwt refresh if needed.
+    """
+    client_id, domain, _ = get_cloud_config()
+    auth = CLIAuth(client_id=client_id, authkit_domain=domain)
+    token = await auth.get_valid_token()
+    if not token:
+        console.print("[red]Not authenticated. Please run 'basic-memory cloud login' first.[/red]")
+        raise typer.Exit(1)
+
+    return {"Authorization": f"Bearer {token}"}
+
+
+async def make_api_request(
+    method: str,
+    url: str,
+    headers: Optional[dict] = None,
+    json_data: Optional[dict] = None,
+    timeout: float = 30.0,
+) -> httpx.Response:
+    """Make an API request to the cloud service."""
+    headers = headers or {}
+    auth_headers = await get_authenticated_headers()
+    headers.update(auth_headers)
+    # Add debug headers to help with compression issues
+    headers.setdefault("Accept-Encoding", "identity")  # Disable compression for debugging
+
+    async with httpx.AsyncClient(timeout=timeout) as client:
+        try:
+            response = await client.request(method=method, url=url, headers=headers, json=json_data)
+            response.raise_for_status()
+            return response
+        except httpx.HTTPError as e:
+            # Check if this is a response error with response details
+            if hasattr(e, "response") and e.response is not None:  # pyright: ignore [reportAttributeAccessIssue]
+                response = e.response  # type: ignore
+
+                # Try to parse error detail from response
+                error_detail = None
+                try:
+                    error_detail = response.json()
+                except Exception:
+                    # If JSON parsing fails, we'll handle it as a generic error
+                    pass
+
+                # Check for subscription_required error (403)
+                if response.status_code == 403 and isinstance(error_detail, dict):
+                    # Handle both FastAPI HTTPException format (nested under "detail")
+                    # and direct format
+                    detail_obj = error_detail.get("detail", error_detail)
+                    if (
+                        isinstance(detail_obj, dict)
+                        and detail_obj.get("error") == "subscription_required"
+                    ):
+                        message = detail_obj.get("message", "Active subscription required")
+                        subscribe_url = detail_obj.get(
+                            "subscribe_url", "https://basicmemory.com/subscribe"
+                        )
+                        raise SubscriptionRequiredError(
+                            message=message, subscribe_url=subscribe_url
+                        ) from e
+
+                # Raise generic CloudAPIError with status code and detail
+                raise CloudAPIError(
+                    f"API request failed: {e}",
+                    status_code=response.status_code,
+                    detail=error_detail if isinstance(error_detail, dict) else {},
+                ) from e
+
+            raise CloudAPIError(f"API request failed: {e}") from e

src/basic_memory/cli/commands/cloud/bisync_commands.py

@@ -0,0 +1,818 @@
+"""Cloud bisync commands for Basic Memory CLI."""
+
+import asyncio
+import subprocess
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from basic_memory.cli.commands.cloud.api_client import CloudAPIError, make_api_request
+from basic_memory.cli.commands.cloud.rclone_config import (
+    add_tenant_to_rclone_config,
+)
+from basic_memory.cli.commands.cloud.rclone_installer import RcloneInstallError, install_rclone
+from basic_memory.config import ConfigManager
+from basic_memory.ignore_utils import get_bmignore_path, create_default_bmignore
+from basic_memory.schemas.cloud import (
+    TenantMountInfo,
+    MountCredentials,
+    CloudProjectList,
+    CloudProjectCreateRequest,
+    CloudProjectCreateResponse,
+)
+from basic_memory.utils import generate_permalink
+
+console = Console()
+
+
+class BisyncError(Exception):
+    """Exception raised for bisync-related errors."""
+
+    pass
+
+
+class RcloneBisyncProfile:
+    """Bisync profile with safety settings."""
+
+    def __init__(
+        self,
+        name: str,
+        conflict_resolve: str,
+        max_delete: int,
+        check_access: bool,
+        description: str,
+        extra_args: Optional[list[str]] = None,
+    ):
+        self.name = name
+        self.conflict_resolve = conflict_resolve
+        self.max_delete = max_delete
+        self.check_access = check_access
+        self.description = description
+        self.extra_args = extra_args or []
+
+
+# Bisync profiles based on SPEC-9 Phase 2.1
+BISYNC_PROFILES = {
+    "safe": RcloneBisyncProfile(
+        name="safe",
+        conflict_resolve="none",
+        max_delete=10,
+        check_access=False,
+        description="Safe mode with conflict preservation (keeps both versions)",
+    ),
+    "balanced": RcloneBisyncProfile(
+        name="balanced",
+        conflict_resolve="newer",
+        max_delete=25,
+        check_access=False,
+        description="Balanced mode - auto-resolve to newer file (recommended)",
+    ),
+    "fast": RcloneBisyncProfile(
+        name="fast",
+        conflict_resolve="newer",
+        max_delete=50,
+        check_access=False,
+        description="Fast mode for rapid iteration (skip verification)",
+    ),
+}
+
+
+async def get_mount_info() -> TenantMountInfo:
+    """Get current tenant information from cloud API."""
+    try:
+        config_manager = ConfigManager()
+        config = config_manager.config
+        host_url = config.cloud_host.rstrip("/")
+
+        response = await make_api_request(method="GET", url=f"{host_url}/tenant/mount/info")
+
+        return TenantMountInfo.model_validate(response.json())
+    except Exception as e:
+        raise BisyncError(f"Failed to get tenant info: {e}") from e
+
+
+async def generate_mount_credentials(tenant_id: str) -> MountCredentials:
+    """Generate scoped credentials for syncing."""
+    try:
+        config_manager = ConfigManager()
+        config = config_manager.config
+        host_url = config.cloud_host.rstrip("/")
+
+        response = await make_api_request(method="POST", url=f"{host_url}/tenant/mount/credentials")
+
+        return MountCredentials.model_validate(response.json())
+    except Exception as e:
+        raise BisyncError(f"Failed to generate credentials: {e}") from e
+
+
+async def fetch_cloud_projects() -> CloudProjectList:
+    """Fetch list of projects from cloud API.
+
+    Returns:
+        CloudProjectList with projects from cloud
+    """
+    try:
+        config_manager = ConfigManager()
+        config = config_manager.config
+        host_url = config.cloud_host.rstrip("/")
+
+        response = await make_api_request(method="GET", url=f"{host_url}/proxy/projects/projects")
+
+        return CloudProjectList.model_validate(response.json())
+    except Exception as e:
+        raise BisyncError(f"Failed to fetch cloud projects: {e}") from e
+
+
+def scan_local_directories(sync_dir: Path) -> list[str]:
+    """Scan local sync directory for project folders.
+
+    Args:
+        sync_dir: Path to bisync directory
+
+    Returns:
+        List of directory names (project names)
+    """
+    if not sync_dir.exists():
+        return []
+
+    directories = []
+    for item in sync_dir.iterdir():
+        if item.is_dir() and not item.name.startswith("."):
+            directories.append(item.name)
+
+    return directories
+
+
+async def create_cloud_project(project_name: str) -> CloudProjectCreateResponse:
+    """Create a new project on cloud.
+
+    Args:
+        project_name: Name of project to create
+
+    Returns:
+        CloudProjectCreateResponse with project details from API
+    """
+    try:
+        config_manager = ConfigManager()
+        config = config_manager.config
+        host_url = config.cloud_host.rstrip("/")
+
+        # Use generate_permalink to ensure consistent naming
+        project_path = generate_permalink(project_name)
+
+        project_data = CloudProjectCreateRequest(
+            name=project_name,
+            path=project_path,
+            set_default=False,
+        )
+
+        response = await make_api_request(
+            method="POST",
+            url=f"{host_url}/proxy/projects/projects",
+            headers={"Content-Type": "application/json"},
+            json_data=project_data.model_dump(),
+        )
+
+        return CloudProjectCreateResponse.model_validate(response.json())
+    except Exception as e:
+        raise BisyncError(f"Failed to create cloud project '{project_name}': {e}") from e
+
+
+def get_bisync_state_path(tenant_id: str) -> Path:
+    """Get path to bisync state directory."""
+    return Path.home() / ".basic-memory" / "bisync-state" / tenant_id
+
+
+def get_bisync_directory() -> Path:
+    """Get bisync directory from config.
+
+    Returns:
+        Path to bisync directory (default: ~/basic-memory-cloud-sync)
+    """
+    config_manager = ConfigManager()
+    config = config_manager.config
+
+    sync_dir = config.bisync_config.get("sync_dir", str(Path.home() / "basic-memory-cloud-sync"))
+    return Path(sync_dir).expanduser().resolve()
+
+
+def validate_bisync_directory(bisync_dir: Path) -> None:
+    """Validate bisync directory doesn't conflict with mount.
+
+    Raises:
+        BisyncError: If bisync directory conflicts with mount directory
+    """
+    # Get fixed mount directory
+    mount_dir = (Path.home() / "basic-memory-cloud").resolve()
+
+    # Check if bisync dir is the same as mount dir
+    if bisync_dir == mount_dir:
+        raise BisyncError(
+            f"Cannot use {bisync_dir} for bisync - it's the mount directory!\n"
+            f"Mount and bisync must use different directories.\n\n"
+            f"Options:\n"
+            f"  1. Use default: ~/basic-memory-cloud-sync/\n"
+            f"  2. Specify different directory: --dir ~/my-sync-folder"
+        )
+
+    # Check if mount is active at this location
+    result = subprocess.run(["mount"], capture_output=True, text=True)
+    if str(bisync_dir) in result.stdout and "rclone" in result.stdout:
+        raise BisyncError(
+            f"{bisync_dir} is currently mounted via 'bm cloud mount'\n"
+            f"Cannot use mounted directory for bisync.\n\n"
+            f"Either:\n"
+            f"  1. Unmount first: bm cloud unmount\n"
+            f"  2. Use different directory for bisync"
+        )
+
+
+def convert_bmignore_to_rclone_filters() -> Path:
+    """Convert .bmignore patterns to rclone filter format.
+
+    Reads ~/.basic-memory/.bmignore (gitignore-style) and converts to
+    ~/.basic-memory/.bmignore.rclone (rclone filter format).
+
+    Only regenerates if .bmignore has been modified since last conversion.
+
+    Returns:
+        Path to converted rclone filter file
+    """
+    # Ensure .bmignore exists
+    create_default_bmignore()
+
+    bmignore_path = get_bmignore_path()
+    # Create rclone filter path: ~/.basic-memory/.bmignore -> ~/.basic-memory/.bmignore.rclone
+    rclone_filter_path = bmignore_path.parent / f"{bmignore_path.name}.rclone"
+
+    # Skip regeneration if rclone file is newer than bmignore
+    if rclone_filter_path.exists():
+        bmignore_mtime = bmignore_path.stat().st_mtime
+        rclone_mtime = rclone_filter_path.stat().st_mtime
+        if rclone_mtime >= bmignore_mtime:
+            return rclone_filter_path
+
+    # Read .bmignore patterns
+    patterns = []
+    try:
+        with bmignore_path.open("r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                # Keep comments and empty lines
+                if not line or line.startswith("#"):
+                    patterns.append(line)
+                    continue
+
+                # Convert gitignore pattern to rclone filter syntax
+                # gitignore: node_modules  → rclone: - node_modules/**
+                # gitignore: *.pyc        → rclone: - *.pyc
+                if "*" in line:
+                    # Pattern already has wildcard, just add exclude prefix
+                    patterns.append(f"- {line}")
+                else:
+                    # Directory pattern - add /** for recursive exclude
+                    patterns.append(f"- {line}/**")
+
+    except Exception:
+        # If we can't read the file, create a minimal filter
+        patterns = ["# Error reading .bmignore, using minimal filters", "- .git/**"]
+
+    # Write rclone filter file
+    rclone_filter_path.write_text("\n".join(patterns) + "\n")
+
+    return rclone_filter_path
+
+
+def get_bisync_filter_path() -> Path:
+    """Get path to bisync filter file.
+
+    Uses ~/.basic-memory/.bmignore (converted to rclone format).
+    The file is automatically created with default patterns on first use.
+
+    Returns:
+        Path to rclone filter file
+    """
+    return convert_bmignore_to_rclone_filters()
+
+
+def bisync_state_exists(tenant_id: str) -> bool:
+    """Check if bisync state exists (has been initialized)."""
+    state_path = get_bisync_state_path(tenant_id)
+    return state_path.exists() and any(state_path.iterdir())
+
+
+def build_bisync_command(
+    tenant_id: str,
+    bucket_name: str,
+    local_path: Path,
+    profile: RcloneBisyncProfile,
+    dry_run: bool = False,
+    resync: bool = False,
+    verbose: bool = False,
+) -> list[str]:
+    """Build rclone bisync command with profile settings."""
+
+    # Sync with the entire bucket root (all projects)
+    rclone_remote = f"basic-memory-{tenant_id}:{bucket_name}"
+    filter_path = get_bisync_filter_path()
+    state_path = get_bisync_state_path(tenant_id)
+
+    # Ensure state directory exists
+    state_path.mkdir(parents=True, exist_ok=True)
+
+    cmd = [
+        "rclone",
+        "bisync",
+        str(local_path),
+        rclone_remote,
+        "--create-empty-src-dirs",
+        "--resilient",
+        f"--conflict-resolve={profile.conflict_resolve}",
+        f"--max-delete={profile.max_delete}",
+        "--filters-file",
+        str(filter_path),
+        "--workdir",
+        str(state_path),
+    ]
+
+    # Add verbosity flags
+    if verbose:
+        cmd.append("--verbose")  # Full details with file-by-file output
+    else:
+        # Show progress bar during transfers
+        cmd.append("--progress")
+
+    if profile.check_access:
+        cmd.append("--check-access")
+
+    if dry_run:
+        cmd.append("--dry-run")
+
+    if resync:
+        cmd.append("--resync")
+
+    cmd.extend(profile.extra_args)
+
+    return cmd
+
+
+def setup_cloud_bisync(sync_dir: Optional[str] = None) -> None:
+    """Set up cloud bisync with rclone installation and configuration.
+
+    Args:
+        sync_dir: Optional custom sync directory path. If not provided, uses config default.
+    """
+    console.print("[bold blue]Basic Memory Cloud Bisync Setup[/bold blue]")
+    console.print("Setting up bidirectional sync to your cloud tenant...\n")
+
+    try:
+        # Step 1: Install rclone
+        console.print("[blue]Step 1: Installing rclone...[/blue]")
+        install_rclone()
+
+        # Step 2: Get mount info (for tenant_id, bucket)
+        console.print("\n[blue]Step 2: Getting tenant information...[/blue]")
+        tenant_info = asyncio.run(get_mount_info())
+
+        tenant_id = tenant_info.tenant_id
+        bucket_name = tenant_info.bucket_name
+
+        console.print(f"[green]✓ Found tenant: {tenant_id}[/green]")
+        console.print(f"[green]✓ Bucket: {bucket_name}[/green]")
+
+        # Step 3: Generate credentials
+        console.print("\n[blue]Step 3: Generating sync credentials...[/blue]")
+        creds = asyncio.run(generate_mount_credentials(tenant_id))
+
+        access_key = creds.access_key
+        secret_key = creds.secret_key
+
+        console.print("[green]✓ Generated secure credentials[/green]")
+
+        # Step 4: Configure rclone
+        console.print("\n[blue]Step 4: Configuring rclone...[/blue]")
+        add_tenant_to_rclone_config(
+            tenant_id=tenant_id,
+            bucket_name=bucket_name,
+            access_key=access_key,
+            secret_key=secret_key,
+        )
+
+        # Step 5: Configure and create local directory
+        console.print("\n[blue]Step 5: Configuring sync directory...[/blue]")
+
+        # If custom sync_dir provided, save to config
+        if sync_dir:
+            config_manager = ConfigManager()
+            config = config_manager.load_config()
+            config.bisync_config["sync_dir"] = sync_dir
+            config_manager.save_config(config)
+            console.print("[green]✓ Saved custom sync directory to config[/green]")
+
+        # Get bisync directory (from config or default)
+        local_path = get_bisync_directory()
+
+        # Validate bisync directory
+        validate_bisync_directory(local_path)
+
+        # Create directory
+        local_path.mkdir(parents=True, exist_ok=True)
+        console.print(f"[green]✓ Created sync directory: {local_path}[/green]")
+
+        # Step 6: Perform initial resync
+        console.print("\n[blue]Step 6: Performing initial sync...[/blue]")
+        console.print("[yellow]This will establish the baseline for bidirectional sync.[/yellow]")
+
+        run_bisync(
+            tenant_id=tenant_id,
+            bucket_name=bucket_name,
+            local_path=local_path,
+            profile_name="balanced",
+            resync=True,
+        )
+
+        console.print("\n[bold green]✓ Bisync setup completed successfully![/bold green]")
+        console.print("\nYour local files will now sync bidirectionally with the cloud!")
+        console.print(f"\nLocal directory: {local_path}")
+        console.print("\nUseful commands:")
+        console.print("  bm sync                      # Run sync (recommended)")
+        console.print("  bm sync --watch              # Start watch mode")
+        console.print("  bm cloud status              # Check sync status")
+        console.print("  bm cloud check               # Verify file integrity")
+        console.print("  bm cloud bisync --dry-run    # Preview changes (advanced)")
+
+    except (RcloneInstallError, BisyncError, CloudAPIError) as e:
+        console.print(f"\n[red]Setup failed: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"\n[red]Unexpected error during setup: {e}[/red]")
+        raise typer.Exit(1)
+
+
+def run_bisync(
+    tenant_id: Optional[str] = None,
+    bucket_name: Optional[str] = None,
+    local_path: Optional[Path] = None,
+    profile_name: str = "balanced",
+    dry_run: bool = False,
+    resync: bool = False,
+    verbose: bool = False,
+) -> bool:
+    """Run rclone bisync with specified profile."""
+
+    try:
+        # Get tenant info if not provided
+        if not tenant_id or not bucket_name:
+            tenant_info = asyncio.run(get_mount_info())
+            tenant_id = tenant_info.tenant_id
+            bucket_name = tenant_info.bucket_name
+
+        # Set default local path if not provided
+        if not local_path:
+            local_path = get_bisync_directory()
+
+        # Validate bisync directory
+        validate_bisync_directory(local_path)
+
+        # Check if local path exists
+        if not local_path.exists():
+            raise BisyncError(
+                f"Local directory {local_path} does not exist. Run 'basic-memory cloud bisync-setup' first."
+            )
+
+        # Get bisync profile
+        if profile_name not in BISYNC_PROFILES:
+            raise BisyncError(
+                f"Unknown profile: {profile_name}. Available: {list(BISYNC_PROFILES.keys())}"
+            )
+
+        profile = BISYNC_PROFILES[profile_name]
+
+        # Auto-register projects before sync (unless dry-run or resync)
+        if not dry_run and not resync:
+            try:
+                console.print("[dim]Checking for new projects...[/dim]")
+
+                # Fetch cloud projects and extract directory names from paths
+                cloud_data = asyncio.run(fetch_cloud_projects())
+                cloud_projects = cloud_data.projects
+
+                # Extract directory names from cloud project paths
+                # Compare directory names, not project names
+                # Cloud path /app/data/basic-memory -> directory name "basic-memory"
+                cloud_dir_names = set()
+                for p in cloud_projects:
+                    path = p.path
+                    # Strip /app/data/ prefix if present (cloud mode)
+                    if path.startswith("/app/data/"):
+                        path = path[len("/app/data/") :]
+                    # Get the last segment (directory name)
+                    dir_name = Path(path).name
+                    cloud_dir_names.add(dir_name)
+
+                # Scan local directories
+                local_dirs = scan_local_directories(local_path)
+
+                # Create missing cloud projects
+                new_projects = []
+                for dir_name in local_dirs:
+                    if dir_name not in cloud_dir_names:
+                        new_projects.append(dir_name)
+
+                if new_projects:
+                    console.print(
+                        f"[blue]Found {len(new_projects)} new local project(s), creating on cloud...[/blue]"
+                    )
+                    for project_name in new_projects:
+                        try:
+                            asyncio.run(create_cloud_project(project_name))
+                            console.print(f"[green]  ✓ Created project: {project_name}[/green]")
+                        except BisyncError as e:
+                            console.print(
+                                f"[yellow]  ⚠ Could not create {project_name}: {e}[/yellow]"
+                            )
+                else:
+                    console.print("[dim]All local projects already registered on cloud[/dim]")
+
+            except Exception as e:
+                console.print(f"[yellow]Warning: Project auto-registration failed: {e}[/yellow]")
+                console.print("[yellow]Continuing with sync anyway...[/yellow]")
+
+        # Check if first run and require resync
+        if not resync and not bisync_state_exists(tenant_id) and not dry_run:
+            raise BisyncError(
+                "First bisync requires --resync to establish baseline. "
+                "Run: basic-memory cloud bisync --resync"
+            )
+
+        # Build and execute bisync command
+        bisync_cmd = build_bisync_command(
+            tenant_id,
+            bucket_name,
+            local_path,
+            profile,
+            dry_run=dry_run,
+            resync=resync,
+            verbose=verbose,
+        )
+
+        if dry_run:
+            console.print("[yellow]DRY RUN MODE - No changes will be made[/yellow]")
+
+        console.print(
+            f"[blue]Running bisync with profile '{profile_name}' ({profile.description})...[/blue]"
+        )
+        console.print(f"[dim]Command: {' '.join(bisync_cmd)}[/dim]")
+        console.print()  # Blank line before output
+
+        # Stream output in real-time so user sees progress
+        result = subprocess.run(bisync_cmd, text=True)
+
+        if result.returncode != 0:
+            raise BisyncError(f"Bisync command failed with code {result.returncode}")
+
+        console.print()  # Blank line after output
+
+        if dry_run:
+            console.print("[green]✓ Dry run completed successfully[/green]")
+        elif resync:
+            console.print("[green]✓ Initial sync baseline established[/green]")
+        else:
+            console.print("[green]✓ Sync completed successfully[/green]")
+
+        # Notify container to refresh cache (if not dry run)
+        if not dry_run:
+            try:
+                asyncio.run(notify_container_sync(tenant_id))
+            except Exception as e:
+                console.print(f"[yellow]Warning: Could not notify container: {e}[/yellow]")
+
+        return True
+
+    except BisyncError:
+        raise
+    except Exception as e:
+        raise BisyncError(f"Unexpected error during bisync: {e}") from e
+
+
+async def notify_container_sync(tenant_id: str) -> None:
+    """Sync all projects after bisync completes."""
+    try:
+        from basic_memory.cli.commands.command_utils import run_sync
+
+        # Fetch all projects and sync each one
+        cloud_data = await fetch_cloud_projects()
+        projects = cloud_data.projects
+
+        if not projects:
+            console.print("[dim]No projects to sync[/dim]")
+            return
+
+        console.print(f"[blue]Notifying cloud to index {len(projects)} project(s)...[/blue]")
+
+        for project in projects:
+            project_name = project.name
+            if project_name:
+                try:
+                    await run_sync(project=project_name)
+                except Exception as e:
+                    # Non-critical, log and continue
+                    console.print(f"[yellow]  ⚠ Sync failed for {project_name}: {e}[/yellow]")
+
+        console.print("[dim]Note: Cloud indexing has started and may take a few moments[/dim]")
+
+    except Exception as e:
+        # Non-critical, don't fail the bisync
+        console.print(f"[yellow]Warning: Post-sync failed: {e}[/yellow]")
+
+
+def run_bisync_watch(
+    tenant_id: Optional[str] = None,
+    bucket_name: Optional[str] = None,
+    local_path: Optional[Path] = None,
+    profile_name: str = "balanced",
+    interval_seconds: int = 60,
+) -> None:
+    """Run bisync in watch mode with periodic syncs."""
+
+    console.print("[bold blue]Starting bisync watch mode[/bold blue]")
+    console.print(f"Sync interval: {interval_seconds} seconds")
+    console.print("Press Ctrl+C to stop\n")
+
+    try:
+        while True:
+            try:
+                start_time = time.time()
+
+                run_bisync(
+                    tenant_id=tenant_id,
+                    bucket_name=bucket_name,
+                    local_path=local_path,
+                    profile_name=profile_name,
+                )
+
+                elapsed = time.time() - start_time
+                console.print(f"[dim]Sync completed in {elapsed:.1f}s[/dim]")
+
+                # Wait for next interval
+                time.sleep(interval_seconds)
+
+            except BisyncError as e:
+                console.print(f"[red]Sync error: {e}[/red]")
+                console.print(f"[yellow]Retrying in {interval_seconds} seconds...[/yellow]")
+                time.sleep(interval_seconds)
+
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Watch mode stopped[/yellow]")
+
+
+def show_bisync_status() -> None:
+    """Show current bisync status and configuration."""
+
+    try:
+        # Get tenant info
+        tenant_info = asyncio.run(get_mount_info())
+        tenant_id = tenant_info.tenant_id
+
+        local_path = get_bisync_directory()
+        state_path = get_bisync_state_path(tenant_id)
+
+        # Create status table
+        table = Table(title="Cloud Bisync Status", show_header=True, header_style="bold blue")
+        table.add_column("Property", style="green", min_width=20)
+        table.add_column("Value", style="dim", min_width=30)
+
+        # Check initialization status
+        is_initialized = bisync_state_exists(tenant_id)
+        init_status = (
+            "[green]✓ Initialized[/green]" if is_initialized else "[red]✗ Not initialized[/red]"
+        )
+
+        table.add_row("Tenant ID", tenant_id)
+        table.add_row("Local Directory", str(local_path))
+        table.add_row("Status", init_status)
+        table.add_row("State Directory", str(state_path))
+
+        # Check for last sync info
+        if is_initialized:
+            # Look for most recent state file
+            state_files = list(state_path.glob("*.lst"))
+            if state_files:
+                latest = max(state_files, key=lambda p: p.stat().st_mtime)
+                last_sync = datetime.fromtimestamp(latest.stat().st_mtime)
+                table.add_row("Last Sync", last_sync.strftime("%Y-%m-%d %H:%M:%S"))
+
+        console.print(table)
+
+        # Show bisync profiles
+        console.print("\n[bold]Available bisync profiles:[/bold]")
+        for name, profile in BISYNC_PROFILES.items():
+            console.print(f"  {name}: {profile.description}")
+            console.print(f"    - Conflict resolution: {profile.conflict_resolve}")
+            console.print(f"    - Max delete: {profile.max_delete} files")
+
+        console.print("\n[dim]To use a profile: bm cloud bisync --profile <name>[/dim]")
+
+        # Show setup instructions if not initialized
+        if not is_initialized:
+            console.print("\n[yellow]To initialize bisync, run:[/yellow]")
+            console.print("  bm cloud setup")
+            console.print("  or")
+            console.print("  bm cloud bisync --resync")
+
+    except Exception as e:
+        console.print(f"[red]Error getting bisync status: {e}[/red]")
+        raise typer.Exit(1)
+
+
+def run_check(
+    tenant_id: Optional[str] = None,
+    bucket_name: Optional[str] = None,
+    local_path: Optional[Path] = None,
+    one_way: bool = False,
+) -> bool:
+    """Check file integrity between local and cloud using rclone check.
+
+    Args:
+        tenant_id: Cloud tenant ID (auto-detected if not provided)
+        bucket_name: S3 bucket name (auto-detected if not provided)
+        local_path: Local bisync directory (uses config default if not provided)
+        one_way: If True, only check for missing files on destination (faster)
+
+    Returns:
+        True if check passed (files match), False if differences found
+    """
+    try:
+        # Check if rclone is installed
+        from basic_memory.cli.commands.cloud.rclone_installer import is_rclone_installed
+
+        if not is_rclone_installed():
+            raise BisyncError(
+                "rclone is not installed. Run 'bm cloud bisync-setup' first to set up cloud sync."
+            )
+
+        # Get tenant info if not provided
+        if not tenant_id or not bucket_name:
+            tenant_info = asyncio.run(get_mount_info())
+            tenant_id = tenant_id or tenant_info.tenant_id
+            bucket_name = bucket_name or tenant_info.bucket_name
+
+        # Get local path from config
+        if not local_path:
+            local_path = get_bisync_directory()
+
+        # Check if bisync is initialized
+        if not bisync_state_exists(tenant_id):
+            raise BisyncError(
+                "Bisync not initialized. Run 'bm cloud bisync --resync' to establish baseline."
+            )
+
+        # Build rclone check command
+        rclone_remote = f"basic-memory-{tenant_id}:{bucket_name}"
+        filter_path = get_bisync_filter_path()
+
+        cmd = [
+            "rclone",
+            "check",
+            str(local_path),
+            rclone_remote,
+            "--filter-from",
+            str(filter_path),
+        ]
+
+        if one_way:
+            cmd.append("--one-way")
+
+        console.print("[bold blue]Checking file integrity between local and cloud[/bold blue]")
+        console.print(f"[dim]Local:  {local_path}[/dim]")
+        console.print(f"[dim]Remote: {rclone_remote}[/dim]")
+        console.print(f"[dim]Command: {' '.join(cmd)}[/dim]")
+        console.print()
+
+        # Run check command
+        result = subprocess.run(cmd, capture_output=True, text=True)
+
+        # rclone check returns:
+        # 0 = success (all files match)
+        # non-zero = differences found or error
+        if result.returncode == 0:
+            console.print("[green]✓ All files match between local and cloud[/green]")
+            return True
+        else:
+            console.print("[yellow]⚠ Differences found:[/yellow]")
+            if result.stderr:
+                console.print(result.stderr)
+            if result.stdout:
+                console.print(result.stdout)
+            console.print("\n[dim]To sync differences, run: bm sync[/dim]")
+            return False
+
+    except BisyncError:
+        raise
+    except Exception as e:
+        raise BisyncError(f"Check failed: {e}") from e

src/basic_memory/cli/commands/cloud/core_commands.py

@@ -0,0 +1,288 @@
+"""Core cloud commands for Basic Memory CLI."""
+
+import asyncio
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from basic_memory.cli.app import cloud_app
+from basic_memory.cli.auth import CLIAuth
+from basic_memory.config import ConfigManager
+from basic_memory.cli.commands.cloud.api_client import (
+    CloudAPIError,
+    SubscriptionRequiredError,
+    get_cloud_config,
+    make_api_request,
+)
+from basic_memory.cli.commands.cloud.mount_commands import (
+    mount_cloud_files,
+    setup_cloud_mount,
+    show_mount_status,
+    unmount_cloud_files,
+)
+from basic_memory.cli.commands.cloud.bisync_commands import (
+    run_bisync,
+    run_bisync_watch,
+    run_check,
+    setup_cloud_bisync,
+    show_bisync_status,
+)
+from basic_memory.cli.commands.cloud.rclone_config import MOUNT_PROFILES
+from basic_memory.cli.commands.cloud.bisync_commands import BISYNC_PROFILES
+
+console = Console()
+
+
+@cloud_app.command()
+def login():
+    """Authenticate with WorkOS using OAuth Device Authorization flow and enable cloud mode."""
+
+    async def _login():
+        client_id, domain, host_url = get_cloud_config()
+        auth = CLIAuth(client_id=client_id, authkit_domain=domain)
+
+        try:
+            success = await auth.login()
+            if not success:
+                console.print("[red]Login failed[/red]")
+                raise typer.Exit(1)
+
+            # Test subscription access by calling a protected endpoint
+            console.print("[dim]Verifying subscription access...[/dim]")
+            await make_api_request("GET", f"{host_url.rstrip('/')}/proxy/health")
+
+            # Enable cloud mode after successful login and subscription validation
+            config_manager = ConfigManager()
+            config = config_manager.load_config()
+            config.cloud_mode = True
+            config_manager.save_config(config)
+
+            console.print("[green]✓ Cloud mode enabled[/green]")
+            console.print(f"[dim]All CLI commands now work against {host_url}[/dim]")
+
+        except SubscriptionRequiredError as e:
+            console.print("\n[red]✗ Subscription Required[/red]\n")
+            console.print(f"[yellow]{e.args[0]}[/yellow]\n")
+            console.print(f"Subscribe at: [blue underline]{e.subscribe_url}[/blue underline]\n")
+            console.print(
+                "[dim]Once you have an active subscription, run [bold]bm cloud login[/bold] again.[/dim]"
+            )
+            raise typer.Exit(1)
+
+    asyncio.run(_login())
+
+
+@cloud_app.command()
+def logout():
+    """Disable cloud mode and return to local mode."""
+
+    # Disable cloud mode
+    config_manager = ConfigManager()
+    config = config_manager.load_config()
+    config.cloud_mode = False
+    config_manager.save_config(config)
+
+    console.print("[green]✓ Cloud mode disabled[/green]")
+    console.print("[dim]All CLI commands now work locally[/dim]")
+
+
+@cloud_app.command("status")
+def status(
+    bisync: bool = typer.Option(
+        True,
+        "--bisync/--mount",
+        help="Show bisync status (default) or mount status",
+    ),
+) -> None:
+    """Check cloud mode status and cloud instance health.
+
+    Shows cloud mode status, instance health, and sync/mount status.
+    Use --bisync (default) to show bisync status or --mount for mount status.
+    """
+    # Check cloud mode
+    config_manager = ConfigManager()
+    config = config_manager.load_config()
+
+    console.print("[bold blue]Cloud Mode Status[/bold blue]")
+    if config.cloud_mode:
+        console.print("  Mode: [green]Cloud (enabled)[/green]")
+        console.print(f"  Host: {config.cloud_host}")
+        console.print("  [dim]All CLI commands work against cloud[/dim]")
+    else:
+        console.print("  Mode: [yellow]Local (disabled)[/yellow]")
+        console.print("  [dim]All CLI commands work locally[/dim]")
+        console.print("\n[dim]To enable cloud mode, run: bm cloud login[/dim]")
+        return
+
+    # Get cloud configuration
+    _, _, host_url = get_cloud_config()
+    host_url = host_url.rstrip("/")
+
+    # Prepare headers
+    headers = {}
+
+    try:
+        console.print("\n[blue]Checking cloud instance health...[/blue]")
+
+        # Make API request to check health
+        response = asyncio.run(
+            make_api_request(method="GET", url=f"{host_url}/proxy/health", headers=headers)
+        )
+
+        health_data = response.json()
+
+        console.print("[green]Cloud instance is healthy[/green]")
+
+        # Display status details
+        if "status" in health_data:
+            console.print(f"  Status: {health_data['status']}")
+        if "version" in health_data:
+            console.print(f"  Version: {health_data['version']}")
+        if "timestamp" in health_data:
+            console.print(f"  Timestamp: {health_data['timestamp']}")
+
+        # Show sync/mount status based on flag
+        console.print()
+        if bisync:
+            show_bisync_status()
+        else:
+            show_mount_status()
+
+    except CloudAPIError as e:
+        console.print(f"[red]Error checking cloud health: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Unexpected error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+# Mount commands
+
+
+@cloud_app.command("setup")
+def setup(
+    bisync: bool = typer.Option(
+        True,
+        "--bisync/--mount",
+        help="Use bidirectional sync (recommended) or mount as network drive",
+    ),
+    sync_dir: Optional[str] = typer.Option(
+        None,
+        "--dir",
+        help="Custom sync directory for bisync (default: ~/basic-memory-cloud-sync)",
+    ),
+) -> None:
+    """Set up cloud file access with automatic rclone installation and configuration.
+
+    Default: Sets up bidirectional sync (recommended).\n
+    Use --mount: Sets up mount as network drive (alternative workflow).\n
+
+    Examples:\n
+      bm cloud setup              # Setup bisync (default)\n
+      bm cloud setup --mount      # Setup mount instead\n
+      bm cloud setup --dir ~/sync # Custom bisync directory\n
+    """
+    if bisync:
+        setup_cloud_bisync(sync_dir=sync_dir)
+    else:
+        setup_cloud_mount()
+
+
+@cloud_app.command("mount")
+def mount(
+    profile: str = typer.Option(
+        "balanced", help=f"Mount profile: {', '.join(MOUNT_PROFILES.keys())}"
+    ),
+    path: Optional[str] = typer.Option(
+        None, help="Custom mount path (default: ~/basic-memory-{tenant-id})"
+    ),
+) -> None:
+    """Mount cloud files locally for editing."""
+    try:
+        mount_cloud_files(profile_name=profile)
+    except Exception as e:
+        console.print(f"[red]Mount failed: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@cloud_app.command("unmount")
+def unmount() -> None:
+    """Unmount cloud files."""
+    try:
+        unmount_cloud_files()
+    except Exception as e:
+        console.print(f"[red]Unmount failed: {e}[/red]")
+        raise typer.Exit(1)
+
+
+# Bisync commands
+
+
+@cloud_app.command("bisync")
+def bisync(
+    profile: str = typer.Option(
+        "balanced", help=f"Bisync profile: {', '.join(BISYNC_PROFILES.keys())}"
+    ),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes without syncing"),
+    resync: bool = typer.Option(False, "--resync", help="Force resync to establish new baseline"),
+    watch: bool = typer.Option(False, "--watch", help="Run continuous sync in watch mode"),
+    interval: int = typer.Option(60, "--interval", help="Sync interval in seconds for watch mode"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed sync output"),
+) -> None:
+    """Run bidirectional sync between local files and cloud storage.
+
+    Examples:
+      basic-memory cloud bisync                    # Manual sync with balanced profile
+      basic-memory cloud bisync --dry-run          # Preview what would be synced
+      basic-memory cloud bisync --resync           # Establish new baseline
+      basic-memory cloud bisync --watch            # Continuous sync every 60s
+      basic-memory cloud bisync --watch --interval 30  # Continuous sync every 30s
+      basic-memory cloud bisync --profile safe     # Use safe profile (keep conflicts)
+      basic-memory cloud bisync --verbose          # Show detailed file sync output
+    """
+    try:
+        if watch:
+            run_bisync_watch(profile_name=profile, interval_seconds=interval)
+        else:
+            run_bisync(profile_name=profile, dry_run=dry_run, resync=resync, verbose=verbose)
+    except Exception as e:
+        console.print(f"[red]Bisync failed: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@cloud_app.command("bisync-status")
+def bisync_status() -> None:
+    """Show current bisync status and configuration.
+
+    DEPRECATED: Use 'bm cloud status' instead (bisync is now the default).
+    """
+    console.print(
+        "[yellow]Note: 'bisync-status' is deprecated. Use 'bm cloud status' instead.[/yellow]"
+    )
+    console.print("[dim]Showing bisync status...[/dim]\n")
+    show_bisync_status()
+
+
+@cloud_app.command("check")
+def check(
+    one_way: bool = typer.Option(
+        False,
+        "--one-way",
+        help="Only check for missing files on destination (faster)",
+    ),
+) -> None:
+    """Check file integrity between local and cloud storage using rclone check.
+
+    Verifies that files match between your local bisync directory and cloud storage
+    without transferring any data. This is useful for validating sync integrity.
+
+    Examples:
+      bm cloud check              # Full integrity check
+      bm cloud check --one-way    # Faster check (missing files only)
+    """
+    try:
+        run_check(one_way=one_way)
+    except Exception as e:
+        console.print(f"[red]Check failed: {e}[/red]")
+        raise typer.Exit(1)

src/basic_memory/cli/commands/cloud/mount_commands.py

@@ -0,0 +1,295 @@
+"""Cloud mount commands for Basic Memory CLI."""
+
+import asyncio
+import subprocess
+import time
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from basic_memory.cli.commands.cloud.api_client import CloudAPIError, make_api_request
+from basic_memory.cli.commands.cloud.rclone_config import (
+    MOUNT_PROFILES,
+    add_tenant_to_rclone_config,
+    build_mount_command,
+    cleanup_orphaned_rclone_processes,
+    get_default_mount_path,
+    get_rclone_processes,
+    is_path_mounted,
+    unmount_path,
+)
+from basic_memory.cli.commands.cloud.rclone_installer import RcloneInstallError, install_rclone
+from basic_memory.config import ConfigManager
+
+console = Console()
+
+
+class MountError(Exception):
+    """Exception raised for mount-related errors."""
+
+    pass
+
+
+async def get_tenant_info() -> dict:
+    """Get current tenant information from cloud API."""
+    try:
+        config_manager = ConfigManager()
+        config = config_manager.config
+        host_url = config.cloud_host.rstrip("/")
+
+        response = await make_api_request(method="GET", url=f"{host_url}/tenant/mount/info")
+
+        return response.json()
+    except Exception as e:
+        raise MountError(f"Failed to get tenant info: {e}") from e
+
+
+async def generate_mount_credentials(tenant_id: str) -> dict:
+    """Generate scoped credentials for mounting."""
+    try:
+        config_manager = ConfigManager()
+        config = config_manager.config
+        host_url = config.cloud_host.rstrip("/")
+
+        response = await make_api_request(method="POST", url=f"{host_url}/tenant/mount/credentials")
+
+        return response.json()
+    except Exception as e:
+        raise MountError(f"Failed to generate mount credentials: {e}") from e
+
+
+def setup_cloud_mount() -> None:
+    """Set up cloud mount with rclone installation and configuration."""
+    console.print("[bold blue]Basic Memory Cloud Setup[/bold blue]")
+    console.print("Setting up local file access to your cloud tenant...\n")
+
+    try:
+        # Step 1: Install rclone
+        console.print("[blue]Step 1: Installing rclone...[/blue]")
+        install_rclone()
+
+        # Step 2: Get tenant info
+        console.print("\n[blue]Step 2: Getting tenant information...[/blue]")
+        tenant_info = asyncio.run(get_tenant_info())
+
+        tenant_id = tenant_info.get("tenant_id")
+        bucket_name = tenant_info.get("bucket_name")
+
+        if not tenant_id or not bucket_name:
+            raise MountError("Invalid tenant information received from cloud API")
+
+        console.print(f"[green]✓ Found tenant: {tenant_id}[/green]")
+        console.print(f"[green]✓ Bucket: {bucket_name}[/green]")
+
+        # Step 3: Generate mount credentials
+        console.print("\n[blue]Step 3: Generating mount credentials...[/blue]")
+        creds = asyncio.run(generate_mount_credentials(tenant_id))
+
+        access_key = creds.get("access_key")
+        secret_key = creds.get("secret_key")
+
+        if not access_key or not secret_key:
+            raise MountError("Failed to generate mount credentials")
+
+        console.print("[green]✓ Generated secure credentials[/green]")
+
+        # Step 4: Configure rclone
+        console.print("\n[blue]Step 4: Configuring rclone...[/blue]")
+        add_tenant_to_rclone_config(
+            tenant_id=tenant_id,
+            bucket_name=bucket_name,
+            access_key=access_key,
+            secret_key=secret_key,
+        )
+
+        # Step 5: Perform initial mount
+        console.print("\n[blue]Step 5: Mounting cloud files...[/blue]")
+        mount_path = get_default_mount_path()
+        MOUNT_PROFILES["balanced"]
+
+        mount_cloud_files(
+            tenant_id=tenant_id,
+            bucket_name=bucket_name,
+            mount_path=mount_path,
+            profile_name="balanced",
+        )
+
+        console.print("\n[bold green]✓ Cloud setup completed successfully![/bold green]")
+        console.print("\nYour cloud files are now accessible at:")
+        console.print(f"  {mount_path}")
+        console.print("\nYou can now edit files locally and they will sync to the cloud!")
+        console.print("\nUseful commands:")
+        console.print("  basic-memory cloud mount-status    # Check mount status")
+        console.print("  basic-memory cloud unmount         # Unmount files")
+        console.print("  basic-memory cloud mount --profile fast  # Remount with faster sync")
+
+    except (RcloneInstallError, MountError, CloudAPIError) as e:
+        console.print(f"\n[red]Setup failed: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"\n[red]Unexpected error during setup: {e}[/red]")
+        raise typer.Exit(1)
+
+
+def mount_cloud_files(
+    tenant_id: Optional[str] = None,
+    bucket_name: Optional[str] = None,
+    mount_path: Optional[Path] = None,
+    profile_name: str = "balanced",
+) -> None:
+    """Mount cloud files with specified profile."""
+
+    try:
+        # Get tenant info if not provided
+        if not tenant_id or not bucket_name:
+            tenant_info = asyncio.run(get_tenant_info())
+            tenant_id = tenant_info.get("tenant_id")
+            bucket_name = tenant_info.get("bucket_name")
+
+            if not tenant_id or not bucket_name:
+                raise MountError("Could not determine tenant information")
+
+        # Set default mount path if not provided
+        if not mount_path:
+            mount_path = get_default_mount_path()
+
+        # Get mount profile
+        if profile_name not in MOUNT_PROFILES:
+            raise MountError(
+                f"Unknown profile: {profile_name}. Available: {list(MOUNT_PROFILES.keys())}"
+            )
+
+        profile = MOUNT_PROFILES[profile_name]
+
+        # Check if already mounted
+        if is_path_mounted(mount_path):
+            console.print(f"[yellow]Path {mount_path} is already mounted[/yellow]")
+            console.print("Use 'basic-memory cloud unmount' first, or mount to a different path")
+            return
+
+        # Create mount directory
+        mount_path.mkdir(parents=True, exist_ok=True)
+
+        # Build and execute mount command
+        mount_cmd = build_mount_command(tenant_id, bucket_name, mount_path, profile)
+
+        console.print(
+            f"[blue]Mounting with profile '{profile_name}' ({profile.description})...[/blue]"
+        )
+        console.print(f"[dim]Command: {' '.join(mount_cmd)}[/dim]")
+
+        result = subprocess.run(mount_cmd, capture_output=True, text=True)
+
+        if result.returncode != 0:
+            error_msg = result.stderr or "Unknown error"
+            raise MountError(f"Mount command failed: {error_msg}")
+
+        # Wait a moment for mount to establish
+        time.sleep(2)
+
+        # Verify mount
+        if is_path_mounted(mount_path):
+            console.print(f"[green]✓ Successfully mounted to {mount_path}[/green]")
+            console.print(f"[green]✓ Sync profile: {profile.description}[/green]")
+        else:
+            raise MountError("Mount command succeeded but path is not mounted")
+
+    except MountError:
+        raise
+    except Exception as e:
+        raise MountError(f"Unexpected error during mount: {e}") from e
+
+
+def unmount_cloud_files(tenant_id: Optional[str] = None) -> None:
+    """Unmount cloud files."""
+
+    try:
+        # Get tenant info if not provided
+        if not tenant_id:
+            tenant_info = asyncio.run(get_tenant_info())
+            tenant_id = tenant_info.get("tenant_id")
+
+            if not tenant_id:
+                raise MountError("Could not determine tenant ID")
+
+        mount_path = get_default_mount_path()
+
+        if not is_path_mounted(mount_path):
+            console.print(f"[yellow]Path {mount_path} is not mounted[/yellow]")
+            return
+
+        console.print(f"[blue]Unmounting {mount_path}...[/blue]")
+
+        # Unmount the path
+        if unmount_path(mount_path):
+            console.print(f"[green]✓ Successfully unmounted {mount_path}[/green]")
+
+            # Clean up any orphaned rclone processes
+            killed_count = cleanup_orphaned_rclone_processes()
+            if killed_count > 0:
+                console.print(
+                    f"[green]✓ Cleaned up {killed_count} orphaned rclone process(es)[/green]"
+                )
+        else:
+            console.print(f"[red]✗ Failed to unmount {mount_path}[/red]")
+            console.print("You may need to manually unmount or restart your system")
+
+    except MountError:
+        raise
+    except Exception as e:
+        raise MountError(f"Unexpected error during unmount: {e}") from e
+
+
+def show_mount_status() -> None:
+    """Show current mount status and running processes."""
+
+    try:
+        # Get tenant info
+        tenant_info = asyncio.run(get_tenant_info())
+        tenant_id = tenant_info.get("tenant_id")
+
+        if not tenant_id:
+            console.print("[red]Could not determine tenant ID[/red]")
+            return
+
+        mount_path = get_default_mount_path()
+
+        # Create status table
+        table = Table(title="Cloud Mount Status", show_header=True, header_style="bold blue")
+        table.add_column("Property", style="green", min_width=15)
+        table.add_column("Value", style="dim", min_width=30)
+
+        # Check mount status
+        is_mounted = is_path_mounted(mount_path)
+        mount_status = "[green]✓ Mounted[/green]" if is_mounted else "[red]✗ Not mounted[/red]"
+
+        table.add_row("Tenant ID", tenant_id)
+        table.add_row("Mount Path", str(mount_path))
+        table.add_row("Status", mount_status)
+
+        # Get rclone processes
+        processes = get_rclone_processes()
+        if processes:
+            table.add_row("rclone Processes", f"{len(processes)} running")
+        else:
+            table.add_row("rclone Processes", "None")
+
+        console.print(table)
+
+        # Show running processes details
+        if processes:
+            console.print("\n[bold]Running rclone processes:[/bold]")
+            for proc in processes:
+                console.print(f"  PID {proc['pid']}: {proc['command'][:80]}...")
+
+        # Show mount profiles
+        console.print("\n[bold]Available mount profiles:[/bold]")
+        for name, profile in MOUNT_PROFILES.items():
+            console.print(f"  {name}: {profile.description}")
+
+    except Exception as e:
+        console.print(f"[red]Error getting mount status: {e}[/red]")
+        raise typer.Exit(1)

src/basic_memory/cli/commands/cloud/rclone_config.py

@@ -0,0 +1,288 @@
+"""rclone configuration management for Basic Memory Cloud."""
+
+import configparser
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from rich.console import Console
+
+console = Console()
+
+
+class RcloneConfigError(Exception):
+    """Exception raised for rclone configuration errors."""
+
+    pass
+
+
+class RcloneMountProfile:
+    """Mount profile with optimized settings."""
+
+    def __init__(
+        self,
+        name: str,
+        cache_time: str,
+        poll_interval: str,
+        attr_timeout: str,
+        write_back: str,
+        description: str,
+        extra_args: Optional[List[str]] = None,
+    ):
+        self.name = name
+        self.cache_time = cache_time
+        self.poll_interval = poll_interval
+        self.attr_timeout = attr_timeout
+        self.write_back = write_back
+        self.description = description
+        self.extra_args = extra_args or []
+
+
+# Mount profiles based on SPEC-7 Phase 4 testing
+MOUNT_PROFILES = {
+    "fast": RcloneMountProfile(
+        name="fast",
+        cache_time="5s",
+        poll_interval="3s",
+        attr_timeout="3s",
+        write_back="1s",
+        description="Ultra-fast development (5s sync, higher bandwidth)",
+    ),
+    "balanced": RcloneMountProfile(
+        name="balanced",
+        cache_time="10s",
+        poll_interval="5s",
+        attr_timeout="5s",
+        write_back="2s",
+        description="Fast development (10-15s sync, recommended)",
+    ),
+    "safe": RcloneMountProfile(
+        name="safe",
+        cache_time="15s",
+        poll_interval="10s",
+        attr_timeout="10s",
+        write_back="5s",
+        description="Conflict-aware mount with backup",
+        extra_args=[
+            "--conflict-suffix",
+            ".conflict-{DateTimeExt}",
+            "--backup-dir",
+            "~/.basic-memory/conflicts",
+            "--track-renames",
+        ],
+    ),
+}
+
+
+def get_rclone_config_path() -> Path:
+    """Get the path to rclone configuration file."""
+    config_dir = Path.home() / ".config" / "rclone"
+    config_dir.mkdir(parents=True, exist_ok=True)
+    return config_dir / "rclone.conf"
+
+
+def backup_rclone_config() -> Optional[Path]:
+    """Create a backup of existing rclone config."""
+    config_path = get_rclone_config_path()
+    if not config_path.exists():
+        return None
+
+    backup_path = config_path.with_suffix(f".conf.backup-{os.getpid()}")
+    shutil.copy2(config_path, backup_path)
+    console.print(f"[dim]Created backup: {backup_path}[/dim]")
+    return backup_path
+
+
+def load_rclone_config() -> configparser.ConfigParser:
+    """Load existing rclone configuration."""
+    config = configparser.ConfigParser()
+    config_path = get_rclone_config_path()
+
+    if config_path.exists():
+        config.read(config_path)
+
+    return config
+
+
+def save_rclone_config(config: configparser.ConfigParser) -> None:
+    """Save rclone configuration to file."""
+    config_path = get_rclone_config_path()
+
+    with open(config_path, "w") as f:
+        config.write(f)
+
+    console.print(f"[dim]Updated rclone config: {config_path}[/dim]")
+
+
+def add_tenant_to_rclone_config(
+    tenant_id: str,
+    bucket_name: str,
+    access_key: str,
+    secret_key: str,
+    endpoint: str = "https://fly.storage.tigris.dev",
+    region: str = "auto",
+) -> str:
+    """Add tenant configuration to rclone config file."""
+
+    # Backup existing config
+    backup_rclone_config()
+
+    # Load existing config
+    config = load_rclone_config()
+
+    # Create section name
+    section_name = f"basic-memory-{tenant_id}"
+
+    # Add/update the tenant section
+    if not config.has_section(section_name):
+        config.add_section(section_name)
+
+    config.set(section_name, "type", "s3")
+    config.set(section_name, "provider", "Other")
+    config.set(section_name, "access_key_id", access_key)
+    config.set(section_name, "secret_access_key", secret_key)
+    config.set(section_name, "endpoint", endpoint)
+    config.set(section_name, "region", region)
+
+    # Save updated config
+    save_rclone_config(config)
+
+    console.print(f"[green]✓ Added tenant {tenant_id} to rclone config[/green]")
+    return section_name
+
+
+def remove_tenant_from_rclone_config(tenant_id: str) -> bool:
+    """Remove tenant configuration from rclone config."""
+    config = load_rclone_config()
+    section_name = f"basic-memory-{tenant_id}"
+
+    if config.has_section(section_name):
+        backup_rclone_config()
+        config.remove_section(section_name)
+        save_rclone_config(config)
+        console.print(f"[green]✓ Removed tenant {tenant_id} from rclone config[/green]")
+        return True
+
+    return False
+
+
+def get_default_mount_path() -> Path:
+    """Get default mount path (fixed location per SPEC-9).
+
+    Returns:
+        Fixed mount path: ~/basic-memory-cloud/
+    """
+    return Path.home() / "basic-memory-cloud"
+
+
+def build_mount_command(
+    tenant_id: str, bucket_name: str, mount_path: Path, profile: RcloneMountProfile
+) -> List[str]:
+    """Build rclone mount command with optimized settings."""
+
+    rclone_remote = f"basic-memory-{tenant_id}:{bucket_name}"
+
+    cmd = [
+        "rclone",
+        "nfsmount",
+        rclone_remote,
+        str(mount_path),
+        "--vfs-cache-mode",
+        "writes",
+        "--dir-cache-time",
+        profile.cache_time,
+        "--vfs-cache-poll-interval",
+        profile.poll_interval,
+        "--attr-timeout",
+        profile.attr_timeout,
+        "--vfs-write-back",
+        profile.write_back,
+        "--daemon",
+    ]
+
+    # Add profile-specific extra arguments
+    cmd.extend(profile.extra_args)
+
+    return cmd
+
+
+def is_path_mounted(mount_path: Path) -> bool:
+    """Check if a path is currently mounted."""
+    if not mount_path.exists():
+        return False
+
+    try:
+        # Check if mount point is actually mounted by looking for mount table entry
+        result = subprocess.run(["mount"], capture_output=True, text=True, check=False)
+
+        if result.returncode == 0:
+            # Look for our mount path in mount output
+            mount_str = str(mount_path.resolve())
+            return mount_str in result.stdout
+
+        return False
+    except Exception:
+        return False
+
+
+def get_rclone_processes() -> List[Dict[str, str]]:
+    """Get list of running rclone processes."""
+    try:
+        # Use ps to find rclone processes
+        result = subprocess.run(
+            ["ps", "-eo", "pid,args"], capture_output=True, text=True, check=False
+        )
+
+        processes = []
+        if result.returncode == 0:
+            for line in result.stdout.split("\n"):
+                if "rclone" in line and "basic-memory" in line:
+                    parts = line.strip().split(None, 1)
+                    if len(parts) >= 2:
+                        processes.append({"pid": parts[0], "command": parts[1]})
+
+        return processes
+    except Exception:
+        return []
+
+
+def kill_rclone_process(pid: str) -> bool:
+    """Kill a specific rclone process."""
+    try:
+        subprocess.run(["kill", pid], check=True)
+        console.print(f"[green]✓ Killed rclone process {pid}[/green]")
+        return True
+    except subprocess.CalledProcessError:
+        console.print(f"[red]✗ Failed to kill rclone process {pid}[/red]")
+        return False
+
+
+def unmount_path(mount_path: Path) -> bool:
+    """Unmount a mounted path."""
+    if not is_path_mounted(mount_path):
+        return True
+
+    try:
+        subprocess.run(["umount", str(mount_path)], check=True)
+        console.print(f"[green]✓ Unmounted {mount_path}[/green]")
+        return True
+    except subprocess.CalledProcessError as e:
+        console.print(f"[red]✗ Failed to unmount {mount_path}: {e}[/red]")
+        return False
+
+
+def cleanup_orphaned_rclone_processes() -> int:
+    """Clean up orphaned rclone processes for basic-memory."""
+    processes = get_rclone_processes()
+    killed_count = 0
+
+    for proc in processes:
+        console.print(
+            f"[yellow]Found rclone process: {proc['pid']} - {proc['command'][:80]}...[/yellow]"
+        )
+        if kill_rclone_process(proc["pid"]):
+            killed_count += 1
+
+    return killed_count

src/basic_memory/cli/commands/cloud/rclone_installer.py

@@ -0,0 +1,198 @@
+"""Cross-platform rclone installation utilities."""
+
+import platform
+import shutil
+import subprocess
+from typing import Optional
+
+from rich.console import Console
+
+console = Console()
+
+
+class RcloneInstallError(Exception):
+    """Exception raised for rclone installation errors."""
+
+    pass
+
+
+def is_rclone_installed() -> bool:
+    """Check if rclone is already installed and available in PATH."""
+    return shutil.which("rclone") is not None
+
+
+def get_platform() -> str:
+    """Get the current platform identifier."""
+    system = platform.system().lower()
+    if system == "darwin":
+        return "macos"
+    elif system == "linux":
+        return "linux"
+    elif system == "windows":
+        return "windows"
+    else:
+        raise RcloneInstallError(f"Unsupported platform: {system}")
+
+
+def run_command(command: list[str], check: bool = True) -> subprocess.CompletedProcess:
+    """Run a command with proper error handling."""
+    try:
+        console.print(f"[dim]Running: {' '.join(command)}[/dim]")
+        result = subprocess.run(command, capture_output=True, text=True, check=check)
+        if result.stdout:
+            console.print(f"[dim]Output: {result.stdout.strip()}[/dim]")
+        return result
+    except subprocess.CalledProcessError as e:
+        console.print(f"[red]Command failed: {e}[/red]")
+        if e.stderr:
+            console.print(f"[red]Error output: {e.stderr}[/red]")
+        raise RcloneInstallError(f"Command failed: {e}") from e
+    except FileNotFoundError as e:
+        raise RcloneInstallError(f"Command not found: {' '.join(command)}") from e
+
+
+def install_rclone_macos() -> None:
+    """Install rclone on macOS using Homebrew or official script."""
+    # Try Homebrew first
+    if shutil.which("brew"):
+        try:
+            console.print("[blue]Installing rclone via Homebrew...[/blue]")
+            run_command(["brew", "install", "rclone"])
+            console.print("[green]✓ rclone installed via Homebrew[/green]")
+            return
+        except RcloneInstallError:
+            console.print(
+                "[yellow]Homebrew installation failed, trying official script...[/yellow]"
+            )
+
+    # Fallback to official script
+    console.print("[blue]Installing rclone via official script...[/blue]")
+    try:
+        run_command(["sh", "-c", "curl https://rclone.org/install.sh | sudo bash"])
+        console.print("[green]✓ rclone installed via official script[/green]")
+    except RcloneInstallError:
+        raise RcloneInstallError(
+            "Failed to install rclone. Please install manually: brew install rclone"
+        )
+
+
+def install_rclone_linux() -> None:
+    """Install rclone on Linux using package managers or official script."""
+    # Try snap first (most universal)
+    if shutil.which("snap"):
+        try:
+            console.print("[blue]Installing rclone via snap...[/blue]")
+            run_command(["sudo", "snap", "install", "rclone"])
+            console.print("[green]✓ rclone installed via snap[/green]")
+            return
+        except RcloneInstallError:
+            console.print("[yellow]Snap installation failed, trying apt...[/yellow]")
+
+    # Try apt (Debian/Ubuntu)
+    if shutil.which("apt"):
+        try:
+            console.print("[blue]Installing rclone via apt...[/blue]")
+            run_command(["sudo", "apt", "update"])
+            run_command(["sudo", "apt", "install", "-y", "rclone"])
+            console.print("[green]✓ rclone installed via apt[/green]")
+            return
+        except RcloneInstallError:
+            console.print("[yellow]apt installation failed, trying official script...[/yellow]")
+
+    # Fallback to official script
+    console.print("[blue]Installing rclone via official script...[/blue]")
+    try:
+        run_command(["sh", "-c", "curl https://rclone.org/install.sh | sudo bash"])
+        console.print("[green]✓ rclone installed via official script[/green]")
+    except RcloneInstallError:
+        raise RcloneInstallError(
+            "Failed to install rclone. Please install manually: sudo snap install rclone"
+        )
+
+
+def install_rclone_windows() -> None:
+    """Install rclone on Windows using package managers."""
+    # Try winget first (built into Windows 10+)
+    if shutil.which("winget"):
+        try:
+            console.print("[blue]Installing rclone via winget...[/blue]")
+            run_command(["winget", "install", "Rclone.Rclone"])
+            console.print("[green]✓ rclone installed via winget[/green]")
+            return
+        except RcloneInstallError:
+            console.print("[yellow]winget installation failed, trying chocolatey...[/yellow]")
+
+    # Try chocolatey
+    if shutil.which("choco"):
+        try:
+            console.print("[blue]Installing rclone via chocolatey...[/blue]")
+            run_command(["choco", "install", "rclone", "-y"])
+            console.print("[green]✓ rclone installed via chocolatey[/green]")
+            return
+        except RcloneInstallError:
+            console.print("[yellow]chocolatey installation failed, trying scoop...[/yellow]")
+
+    # Try scoop
+    if shutil.which("scoop"):
+        try:
+            console.print("[blue]Installing rclone via scoop...[/blue]")
+            run_command(["scoop", "install", "rclone"])
+            console.print("[green]✓ rclone installed via scoop[/green]")
+            return
+        except RcloneInstallError:
+            console.print("[yellow]scoop installation failed[/yellow]")
+
+    # No package manager available
+    raise RcloneInstallError(
+        "Could not install rclone automatically. Please install a package manager "
+        "(winget, chocolatey, or scoop) or install rclone manually from https://rclone.org/downloads/"
+    )
+
+
+def install_rclone(platform_override: Optional[str] = None) -> None:
+    """Install rclone for the current platform."""
+    if is_rclone_installed():
+        console.print("[green]rclone is already installed[/green]")
+        return
+
+    platform_name = platform_override or get_platform()
+    console.print(f"[blue]Installing rclone for {platform_name}...[/blue]")
+
+    try:
+        if platform_name == "macos":
+            install_rclone_macos()
+        elif platform_name == "linux":
+            install_rclone_linux()
+        elif platform_name == "windows":
+            install_rclone_windows()
+        else:
+            raise RcloneInstallError(f"Unsupported platform: {platform_name}")
+
+        # Verify installation
+        if not is_rclone_installed():
+            raise RcloneInstallError("rclone installation completed but command not found in PATH")
+
+        console.print("[green]✓ rclone installation completed successfully[/green]")
+
+    except RcloneInstallError:
+        raise
+    except Exception as e:
+        raise RcloneInstallError(f"Unexpected error during installation: {e}") from e
+
+
+def get_rclone_version() -> Optional[str]:
+    """Get the installed rclone version."""
+    if not is_rclone_installed():
+        return None
+
+    try:
+        result = run_command(["rclone", "version"], check=False)
+        if result.returncode == 0:
+            # Parse version from output (format: "rclone v1.64.0")
+            lines = result.stdout.strip().split("\n")
+            for line in lines:
+                if line.startswith("rclone v"):
+                    return line.split()[1]
+        return "unknown"
+    except Exception:
+        return "unknown"

src/basic_memory/cli/commands/command_utils.py

@@ -0,0 +1,60 @@
+"""utility functions for commands"""
+
+from typing import Optional
+
+from mcp.server.fastmcp.exceptions import ToolError
+import typer
+
+from rich.console import Console
+
+from basic_memory.cli.commands.cloud import get_authenticated_headers
+from basic_memory.mcp.async_client import client
+
+from basic_memory.mcp.tools.utils import call_post, call_get
+from basic_memory.mcp.project_context import get_active_project
+from basic_memory.schemas import ProjectInfoResponse
+
+console = Console()
+
+
+async def run_sync(project: Optional[str] = None):
+    """Run sync operation via API endpoint."""
+
+    try:
+        from basic_memory.config import ConfigManager
+
+        config = ConfigManager().config
+        auth_headers = {}
+        if config.cloud_mode_enabled:
+            auth_headers = await get_authenticated_headers()
+
+        project_item = await get_active_project(client, project, None, headers=auth_headers)
+        response = await call_post(
+            client, f"{project_item.project_url}/project/sync", headers=auth_headers
+        )
+        data = response.json()
+        console.print(f"[green]✓ {data['message']}[/green]")
+    except (ToolError, ValueError) as e:
+        console.print(f"[red]✗ Sync failed: {e}[/red]")
+        raise typer.Exit(1)
+
+
+async def get_project_info(project: str):
+    """Run sync operation via API endpoint."""
+
+    try:
+        from basic_memory.config import ConfigManager
+
+        config = ConfigManager().config
+        auth_headers = {}
+        if config.cloud_mode_enabled:
+            auth_headers = await get_authenticated_headers()
+
+        project_item = await get_active_project(client, project, None, headers=auth_headers)
+        response = await call_get(
+            client, f"{project_item.project_url}/project/info", headers=auth_headers
+        )
+        return ProjectInfoResponse.model_validate(response.json())
+    except (ToolError, ValueError) as e:
+        console.print(f"[red]✗ Sync failed: {e}[/red]")
+        raise typer.Exit(1)

src/basic_memory/cli/commands/import_memory_json.py

@@ -39,8 +39,6 @@ def memory_json(
     1. Read entities and relations from the JSON file
     2. Create markdown files for each entity
     3. Include outgoing relations in each entity's markdown
-
-    After importing, run 'basic-memory sync' to index the new files.
     """
 
     if not json_path.exists():
@@ -82,8 +80,6 @@ def memory_json(
             )
         )
 
-        console.print("\nRun 'basic-memory sync' to index the new files.")
-
     except Exception as e:
         logger.error("Import failed")
         typer.echo(f"Error during import: {e}", err=True)

src/basic_memory/cli/commands/mcp.py

@@ -1,7 +1,9 @@
 """MCP server command with streamable HTTP transport."""
 
 import asyncio
+import os
 import typer
+from typing import Optional
 
 from basic_memory.cli.app import app
 from basic_memory.config import ConfigManager
@@ -15,6 +17,8 @@ import basic_memory.mcp.tools  # noqa: F401  # pragma: no cover
 # Import prompts to register them
 import basic_memory.mcp.prompts  # noqa: F401  # pragma: no cover
 from loguru import logger
+import threading
+from basic_memory.services.initialization import initialize_file_sync
 
 
 @app.command()
@@ -25,6 +29,7 @@ def mcp(
     ),
     port: int = typer.Option(8000, help="Port for HTTP transports"),
     path: str = typer.Option("/mcp", help="Path prefix for streamable-http transport"),
+    project: Optional[str] = typer.Option(None, help="Restrict MCP server to single project"),
 ):  # pragma: no cover
     """Run the MCP server with configurable transport options.
 
@@ -35,10 +40,17 @@ def mcp(
     - sse: Server-Sent Events (for compatibility with existing clients)
     """
 
-    from basic_memory.services.initialization import initialize_file_sync
+    # Validate and set project constraint if specified
+    if project:
+        config_manager = ConfigManager()
+        project_name, _ = config_manager.get_project(project)
+        if not project_name:
+            typer.echo(f"No project found named: {project}", err=True)
+            raise typer.Exit(1)
 
-    # Use unified thread-based sync approach for both transports
-    import threading
+        # Set env var with validated project name
+        os.environ["BASIC_MEMORY_MCP_PROJECT"] = project_name
+        logger.info(f"MCP server constrained to project: {project_name}")
 
     app_config = ConfigManager().config
 

src/basic_memory/cli/commands/project.py

@@ -9,13 +9,13 @@ from rich.console import Console
 from rich.table import Table
 
 from basic_memory.cli.app import app
-from basic_memory.mcp.project_session import session
-from basic_memory.mcp.resources.project_info import project_info
+from basic_memory.cli.commands.cloud import get_authenticated_headers
+from basic_memory.cli.commands.command_utils import get_project_info
+from basic_memory.config import ConfigManager
 import json
 from datetime import datetime
 
 from rich.panel import Panel
-from rich.tree import Tree
 from basic_memory.mcp.async_client import client
 from basic_memory.mcp.tools.utils import call_get
 from basic_memory.schemas.project_info import ProjectList
@@ -32,6 +32,8 @@ console = Console()
 project_app = typer.Typer(help="Manage multiple Basic Memory projects")
 app.add_typer(project_app, name="project")
 
+config = ConfigManager().config
+
 
 def format_path(path: str) -> str:
     """Format a path for display, using ~ for home directory."""
@@ -43,22 +45,24 @@ def format_path(path: str) -> str:
 
 @project_app.command("list")
 def list_projects() -> None:
-    """List all configured projects."""
+    """List all Basic Memory projects."""
     # Use API to list projects
     try:
-        response = asyncio.run(call_get(client, "/projects/projects"))
+        auth_headers = {}
+        if config.cloud_mode_enabled:
+            auth_headers = asyncio.run(get_authenticated_headers())
+
+        response = asyncio.run(call_get(client, "/projects/projects", headers=auth_headers))
         result = ProjectList.model_validate(response.json())
 
         table = Table(title="Basic Memory Projects")
         table.add_column("Name", style="cyan")
         table.add_column("Path", style="green")
-        table.add_column("Default", style="yellow")
-        table.add_column("Active", style="magenta")
+        table.add_column("Default", style="magenta")
 
         for project in result.projects:
             is_default = "✓" if project.is_default else ""
-            is_active = "✓" if session.get_current_project() == project.name else ""
-            table.add_row(project.name, format_path(project.path), is_default, is_active)
+            table.add_row(project.name, format_path(project.path), is_default)
 
         console.print(table)
     except Exception as e:
@@ -66,42 +70,75 @@ def list_projects() -> None:
         raise typer.Exit(1)
 
 
-@project_app.command("add")
-def add_project(
-    name: str = typer.Argument(..., help="Name of the project"),
-    path: str = typer.Argument(..., help="Path to the project directory"),
-    set_default: bool = typer.Option(False, "--default", help="Set as default project"),
-) -> None:
-    """Add a new project."""
-    # Resolve to absolute path
-    resolved_path = Path(os.path.abspath(os.path.expanduser(path))).as_posix()
+if config.cloud_mode_enabled:
 
-    try:
-        data = {"name": name, "path": resolved_path, "set_default": set_default}
+    @project_app.command("add")
+    def add_project_cloud(
+        name: str = typer.Argument(..., help="Name of the project"),
+        set_default: bool = typer.Option(False, "--default", help="Set as default project"),
+    ) -> None:
+        """Add a new project to Basic Memory Cloud"""
 
-        response = asyncio.run(call_post(client, "/projects/projects", json=data))
-        result = ProjectStatusResponse.model_validate(response.json())
+        try:
+            auth_headers = asyncio.run(get_authenticated_headers())
 
-        console.print(f"[green]{result.message}[/green]")
-    except Exception as e:
-        console.print(f"[red]Error adding project: {str(e)}[/red]")
-        raise typer.Exit(1)
+            data = {"name": name, "path": generate_permalink(name), "set_default": set_default}
 
-    # Display usage hint
-    console.print("\nTo use this project:")
-    console.print(f"  basic-memory --project={name} <command>")
-    console.print("  # or")
-    console.print(f"  basic-memory project default {name}")
+            response = asyncio.run(
+                call_post(client, "/projects/projects", json=data, headers=auth_headers)
+            )
+            result = ProjectStatusResponse.model_validate(response.json())
+
+            console.print(f"[green]{result.message}[/green]")
+        except Exception as e:
+            console.print(f"[red]Error adding project: {str(e)}[/red]")
+            raise typer.Exit(1)
+
+        # Display usage hint
+        console.print("\nTo use this project:")
+        console.print(f"  basic-memory --project={name} <command>")
+else:
+
+    @project_app.command("add")
+    def add_project(
+        name: str = typer.Argument(..., help="Name of the project"),
+        path: str = typer.Argument(..., help="Path to the project directory"),
+        set_default: bool = typer.Option(False, "--default", help="Set as default project"),
+    ) -> None:
+        """Add a new project."""
+        # Resolve to absolute path
+        resolved_path = Path(os.path.abspath(os.path.expanduser(path))).as_posix()
+
+        try:
+            data = {"name": name, "path": resolved_path, "set_default": set_default}
+
+            response = asyncio.run(call_post(client, "/projects/projects", json=data))
+            result = ProjectStatusResponse.model_validate(response.json())
+
+            console.print(f"[green]{result.message}[/green]")
+        except Exception as e:
+            console.print(f"[red]Error adding project: {str(e)}[/red]")
+            raise typer.Exit(1)
+
+        # Display usage hint
+        console.print("\nTo use this project:")
+        console.print(f"  basic-memory --project={name} <command>")
 
 
 @project_app.command("remove")
 def remove_project(
     name: str = typer.Argument(..., help="Name of the project to remove"),
 ) -> None:
-    """Remove a project from configuration."""
+    """Remove a project."""
     try:
+        auth_headers = {}
+        if config.cloud_mode_enabled:
+            auth_headers = asyncio.run(get_authenticated_headers())
+
         project_permalink = generate_permalink(name)
-        response = asyncio.run(call_delete(client, f"/projects/{project_permalink}"))
+        response = asyncio.run(
+            call_delete(client, f"/projects/{project_permalink}", headers=auth_headers)
+        )
         result = ProjectStatusResponse.model_validate(response.json())
 
         console.print(f"[green]{result.message}[/green]")
@@ -113,100 +150,96 @@ def remove_project(
     console.print("[yellow]Note: The project files have not been deleted from disk.[/yellow]")
 
 
-@project_app.command("default")
-def set_default_project(
-    name: str = typer.Argument(..., help="Name of the project to set as default"),
-) -> None:
-    """Set the default project and activate it for the current session."""
-    try:
-        project_permalink = generate_permalink(name)
-        response = asyncio.run(call_put(client, f"/projects/{project_permalink}/default"))
-        result = ProjectStatusResponse.model_validate(response.json())
+if not config.cloud_mode_enabled:
 
-        console.print(f"[green]{result.message}[/green]")
-    except Exception as e:
-        console.print(f"[red]Error setting default project: {str(e)}[/red]")
-        raise typer.Exit(1)
+    @project_app.command("default")
+    def set_default_project(
+        name: str = typer.Argument(..., help="Name of the project to set as CLI default"),
+    ) -> None:
+        """Set the default project when 'config.default_project_mode' is set."""
+        try:
+            project_permalink = generate_permalink(name)
+            response = asyncio.run(call_put(client, f"/projects/{project_permalink}/default"))
+            result = ProjectStatusResponse.model_validate(response.json())
 
-    # The API call above should have updated both config and MCP session
-    # No need for manual reload - the project service handles this automatically
-    console.print("[green]Project activated for current session[/green]")
+            console.print(f"[green]{result.message}[/green]")
+        except Exception as e:
+            console.print(f"[red]Error setting default project: {str(e)}[/red]")
+            raise typer.Exit(1)
 
+    @project_app.command("sync-config")
+    def synchronize_projects() -> None:
+        """Synchronize project config between configuration file and database."""
+        # Call the API to synchronize projects
 
-@project_app.command("sync-config")
-def synchronize_projects() -> None:
-    """Synchronize project config between configuration file and database."""
-    # Call the API to synchronize projects
+        try:
+            response = asyncio.run(call_post(client, "/projects/config/sync"))
+            result = ProjectStatusResponse.model_validate(response.json())
 
-    try:
-        response = asyncio.run(call_post(client, "/projects/sync"))
-        result = ProjectStatusResponse.model_validate(response.json())
+            console.print(f"[green]{result.message}[/green]")
+        except Exception as e:  # pragma: no cover
+            console.print(f"[red]Error synchronizing projects: {str(e)}[/red]")
+            raise typer.Exit(1)
 
-        console.print(f"[green]{result.message}[/green]")
-    except Exception as e:  # pragma: no cover
-        console.print(f"[red]Error synchronizing projects: {str(e)}[/red]")
-        raise typer.Exit(1)
+    @project_app.command("move")
+    def move_project(
+        name: str = typer.Argument(..., help="Name of the project to move"),
+        new_path: str = typer.Argument(..., help="New absolute path for the project"),
+    ) -> None:
+        """Move a project to a new location."""
+        # Resolve to absolute path
+        resolved_path = Path(os.path.abspath(os.path.expanduser(new_path))).as_posix()
 
+        try:
+            data = {"path": resolved_path}
 
-@project_app.command("move")
-def move_project(
-    name: str = typer.Argument(..., help="Name of the project to move"),
-    new_path: str = typer.Argument(..., help="New absolute path for the project"),
-) -> None:
-    """Move a project to a new location."""
-    # Resolve to absolute path
-    resolved_path = Path(os.path.abspath(os.path.expanduser(new_path))).as_posix()
+            project_permalink = generate_permalink(name)
 
-    try:
-        data = {"path": resolved_path}
-
-        project_permalink = generate_permalink(name)
-        current_project = session.get_current_project()
-        response = asyncio.run(
-            call_patch(client, f"/{current_project}/project/{project_permalink}", json=data)
-        )
-        result = ProjectStatusResponse.model_validate(response.json())
-
-        console.print(f"[green]{result.message}[/green]")
-
-        # Show important file movement reminder
-        console.print()  # Empty line for spacing
-        console.print(
-            Panel(
-                "[bold red]IMPORTANT:[/bold red] Project configuration updated successfully.\n\n"
-                "[yellow]You must manually move your project files from the old location to:[/yellow]\n"
-                f"[cyan]{resolved_path}[/cyan]\n\n"
-                "[dim]Basic Memory has only updated the configuration - your files remain in their original location.[/dim]",
-                title="⚠️  Manual File Movement Required",
-                border_style="yellow",
-                expand=False,
+            # TODO fix route to use ProjectPathDep
+            response = asyncio.run(
+                call_patch(client, f"/{name}/project/{project_permalink}", json=data)
             )
-        )
+            result = ProjectStatusResponse.model_validate(response.json())
 
-    except Exception as e:
-        console.print(f"[red]Error moving project: {str(e)}[/red]")
-        raise typer.Exit(1)
+            console.print(f"[green]{result.message}[/green]")
+
+            # Show important file movement reminder
+            console.print()  # Empty line for spacing
+            console.print(
+                Panel(
+                    "[bold red]IMPORTANT:[/bold red] Project configuration updated successfully.\n\n"
+                    "[yellow]You must manually move your project files from the old location to:[/yellow]\n"
+                    f"[cyan]{resolved_path}[/cyan]\n\n"
+                    "[dim]Basic Memory has only updated the configuration - your files remain in their original location.[/dim]",
+                    title="⚠️  Manual File Movement Required",
+                    border_style="yellow",
+                    expand=False,
+                )
+            )
+
+        except Exception as e:
+            console.print(f"[red]Error moving project: {str(e)}[/red]")
+            raise typer.Exit(1)
 
 
 @project_app.command("info")
 def display_project_info(
+    name: str = typer.Argument(..., help="Name of the project"),
     json_output: bool = typer.Option(False, "--json", help="Output in JSON format"),
 ):
     """Display detailed information and statistics about the current project."""
     try:
         # Get project info
-        info = asyncio.run(project_info.fn())  # type: ignore  # pyright: ignore [reportAttributeAccessIssue]
+        info = asyncio.run(get_project_info(name))
 
         if json_output:
             # Convert to JSON and print
             print(json.dumps(info.model_dump(), indent=2, default=str))
         else:
-            # Create rich display
-            console = Console()
-
             # Project configuration section
             console.print(
                 Panel(
+                    f"Basic Memory version: [bold green]{info.system.version}[/bold green]\n"
                     f"[bold]Project:[/bold] {info.project_name}\n"
                     f"[bold]Path:[/bold] {info.project_path}\n"
                     f"[bold]Default Project:[/bold] {info.default_project}\n",
@@ -276,42 +309,6 @@ def display_project_info(
 
                 console.print(recent_table)
 
-            # System status
-            system_tree = Tree("🖥️ System Status")
-            system_tree.add(f"Basic Memory version: [bold green]{info.system.version}[/bold green]")
-            system_tree.add(
-                f"Database: [cyan]{info.system.database_path}[/cyan] ([green]{info.system.database_size}[/green])"
-            )
-
-            # Watch status
-            if info.system.watch_status:  # pragma: no cover
-                watch_branch = system_tree.add("Watch Service")
-                running = info.system.watch_status.get("running", False)
-                status_color = "green" if running else "red"
-                watch_branch.add(
-                    f"Status: [bold {status_color}]{'Running' if running else 'Stopped'}[/bold {status_color}]"
-                )
-
-                if running:
-                    start_time = (
-                        datetime.fromisoformat(info.system.watch_status.get("start_time", ""))
-                        if isinstance(info.system.watch_status.get("start_time"), str)
-                        else info.system.watch_status.get("start_time")
-                    )
-                    watch_branch.add(
-                        f"Running since: [cyan]{start_time.strftime('%Y-%m-%d %H:%M')}[/cyan]"
-                    )
-                    watch_branch.add(
-                        f"Files synced: [green]{info.system.watch_status.get('synced_files', 0)}[/green]"
-                    )
-                    watch_branch.add(
-                        f"Errors: [{'red' if info.system.watch_status.get('error_count', 0) > 0 else 'green'}]{info.system.watch_status.get('error_count', 0)}[/{'red' if info.system.watch_status.get('error_count', 0) > 0 else 'green'}]"
-                    )
-            else:
-                system_tree.add("[yellow]Watch service not running[/yellow]")
-
-            console.print(system_tree)
-
             # Available projects
             projects_table = Table(title="📁 Available Projects")
             projects_table.add_column("Name", style="blue")

src/basic_memory/cli/commands/status.py

@@ -2,19 +2,21 @@
 
 import asyncio
 from typing import Set, Dict
+from typing import Annotated, Optional
 
+from mcp.server.fastmcp.exceptions import ToolError
 import typer
 from loguru import logger
 from rich.console import Console
 from rich.panel import Panel
 from rich.tree import Tree
 
-from basic_memory import db
 from basic_memory.cli.app import app
-from basic_memory.cli.commands.sync import get_sync_service
-from basic_memory.config import ConfigManager, get_project_config
-from basic_memory.repository import ProjectRepository
-from basic_memory.sync.sync_service import SyncReport
+from basic_memory.cli.commands.cloud import get_authenticated_headers
+from basic_memory.mcp.async_client import client
+from basic_memory.mcp.tools.utils import call_post
+from basic_memory.schemas import SyncReportResponse
+from basic_memory.mcp.project_context import get_active_project
 
 # Create rich console
 console = Console()
@@ -47,7 +49,7 @@ def add_files_to_tree(
                 branch.add(f"[{style}]{file_name}[/{style}]")
 
 
-def group_changes_by_directory(changes: SyncReport) -> Dict[str, Dict[str, int]]:
+def group_changes_by_directory(changes: SyncReportResponse) -> Dict[str, Dict[str, int]]:
     """Group changes by directory for summary view."""
     by_dir = {}
     for change_type, paths in [
@@ -87,7 +89,9 @@ def build_directory_summary(counts: Dict[str, int]) -> str:
     return " ".join(parts)
 
 
-def display_changes(project_name: str, title: str, changes: SyncReport, verbose: bool = False):
+def display_changes(
+    project_name: str, title: str, changes: SyncReportResponse, verbose: bool = False
+):
     """Display changes using Rich for better visualization."""
     tree = Tree(f"{project_name}: {title}")
 
@@ -122,33 +126,41 @@ def display_changes(project_name: str, title: str, changes: SyncReport, verbose:
     console.print(Panel(tree, expand=False))
 
 
-async def run_status(verbose: bool = False):  # pragma: no cover
+async def run_status(project: Optional[str] = None, verbose: bool = False):  # pragma: no cover
     """Check sync status of files vs database."""
-    # Check knowledge/ directory
 
-    app_config = ConfigManager().config
-    config = get_project_config()
+    try:
+        from basic_memory.config import ConfigManager
 
-    _, session_maker = await db.get_or_create_db(
-        db_path=app_config.database_path, db_type=db.DatabaseType.FILESYSTEM
-    )
-    project_repository = ProjectRepository(session_maker)
-    project = await project_repository.get_by_name(config.project)
-    if not project:  # pragma: no cover
-        raise Exception(f"Project '{config.project}' not found")
+        config = ConfigManager().config
+        auth_headers = {}
+        if config.cloud_mode_enabled:
+            auth_headers = await get_authenticated_headers()
 
-    sync_service = await get_sync_service(project)
-    knowledge_changes = await sync_service.scan(config.home)
-    display_changes(project.name, "Status", knowledge_changes, verbose)
+        project_item = await get_active_project(client, project, None)
+        response = await call_post(
+            client, f"{project_item.project_url}/project/status", headers=auth_headers
+        )
+        sync_report = SyncReportResponse.model_validate(response.json())
+
+        display_changes(project_item.name, "Status", sync_report, verbose)
+
+    except (ValueError, ToolError) as e:
+        console.print(f"[red]✗ Error: {e}[/red]")
+        raise typer.Exit(1)
 
 
 @app.command()
 def status(
+    project: Annotated[
+        Optional[str],
+        typer.Option(help="The project name."),
+    ] = None,
     verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed file information"),
 ):
     """Show sync status between files and database."""
     try:
-        asyncio.run(run_status(verbose))  # pragma: no cover
+        asyncio.run(run_status(project, verbose))  # pragma: no cover
     except Exception as e:
         logger.error(f"Error checking status: {e}")
         typer.echo(f"Error checking status: {e}", err=True)

src/basic_memory/cli/commands/sync.py

@@ -1,242 +1,59 @@
 """Command module for basic-memory sync operations."""
 
 import asyncio
-from collections import defaultdict
-from dataclasses import dataclass
-from pathlib import Path
-from typing import List, Dict
+from typing import Annotated, Optional
 
 import typer
-from loguru import logger
-from rich.console import Console
-from rich.tree import Tree
 
-from basic_memory import db
 from basic_memory.cli.app import app
-from basic_memory.config import ConfigManager, get_project_config
-from basic_memory.markdown import EntityParser
-from basic_memory.markdown.markdown_processor import MarkdownProcessor
-from basic_memory.models import Project
-from basic_memory.repository import (
-    EntityRepository,
-    ObservationRepository,
-    RelationRepository,
-    ProjectRepository,
-)
-from basic_memory.repository.search_repository import SearchRepository
-from basic_memory.services import EntityService, FileService
-from basic_memory.services.link_resolver import LinkResolver
-from basic_memory.services.search_service import SearchService
-from basic_memory.sync import SyncService
-from basic_memory.sync.sync_service import SyncReport
-
-console = Console()
-
-
-@dataclass
-class ValidationIssue:
-    file_path: str
-    error: str
-
-
-async def get_sync_service(project: Project) -> SyncService:  # pragma: no cover
-    """Get sync service instance with all dependencies."""
-
-    app_config = ConfigManager().config
-    _, session_maker = await db.get_or_create_db(
-        db_path=app_config.database_path, db_type=db.DatabaseType.FILESYSTEM
-    )
-
-    project_path = Path(project.path)
-    entity_parser = EntityParser(project_path)
-    markdown_processor = MarkdownProcessor(entity_parser)
-    file_service = FileService(project_path, markdown_processor)
-
-    # Initialize repositories
-    entity_repository = EntityRepository(session_maker, project_id=project.id)
-    observation_repository = ObservationRepository(session_maker, project_id=project.id)
-    relation_repository = RelationRepository(session_maker, project_id=project.id)
-    search_repository = SearchRepository(session_maker, project_id=project.id)
-
-    # Initialize services
-    search_service = SearchService(search_repository, entity_repository, file_service)
-    link_resolver = LinkResolver(entity_repository, search_service)
-
-    # Initialize services
-    entity_service = EntityService(
-        entity_parser,
-        entity_repository,
-        observation_repository,
-        relation_repository,
-        file_service,
-        link_resolver,
-    )
-
-    # Create sync service
-    sync_service = SyncService(
-        app_config=app_config,
-        entity_service=entity_service,
-        entity_parser=entity_parser,
-        entity_repository=entity_repository,
-        relation_repository=relation_repository,
-        search_service=search_service,
-        file_service=file_service,
-    )
-
-    return sync_service
-
-
-def group_issues_by_directory(issues: List[ValidationIssue]) -> Dict[str, List[ValidationIssue]]:
-    """Group validation issues by directory."""
-    grouped = defaultdict(list)
-    for issue in issues:
-        dir_name = Path(issue.file_path).parent.name
-        grouped[dir_name].append(issue)
-    return dict(grouped)
-
-
-def display_sync_summary(knowledge: SyncReport):
-    """Display a one-line summary of sync changes."""
-    config = get_project_config()
-    total_changes = knowledge.total
-    project_name = config.project
-
-    if total_changes == 0:
-        console.print(f"[green]Project '{project_name}': Everything up to date[/green]")
-        return
-
-    # Format as: "Synced X files (A new, B modified, C moved, D deleted)"
-    changes = []
-    new_count = len(knowledge.new)
-    mod_count = len(knowledge.modified)
-    move_count = len(knowledge.moves)
-    del_count = len(knowledge.deleted)
-
-    if new_count:
-        changes.append(f"[green]{new_count} new[/green]")
-    if mod_count:
-        changes.append(f"[yellow]{mod_count} modified[/yellow]")
-    if move_count:
-        changes.append(f"[blue]{move_count} moved[/blue]")
-    if del_count:
-        changes.append(f"[red]{del_count} deleted[/red]")
-
-    console.print(f"Project '{project_name}': Synced {total_changes} files ({', '.join(changes)})")
-
-
-def display_detailed_sync_results(knowledge: SyncReport):
-    """Display detailed sync results with trees."""
-    config = get_project_config()
-    project_name = config.project
-
-    if knowledge.total == 0:
-        console.print(f"\n[green]Project '{project_name}': Everything up to date[/green]")
-        return
-
-    console.print(f"\n[bold]Sync Results for Project '{project_name}'[/bold]")
-
-    if knowledge.total > 0:
-        knowledge_tree = Tree("[bold]Knowledge Files[/bold]")
-        if knowledge.new:
-            created = knowledge_tree.add("[green]Created[/green]")
-            for path in sorted(knowledge.new):
-                checksum = knowledge.checksums.get(path, "")
-                created.add(f"[green]{path}[/green] ({checksum[:8]})")
-        if knowledge.modified:
-            modified = knowledge_tree.add("[yellow]Modified[/yellow]")
-            for path in sorted(knowledge.modified):
-                checksum = knowledge.checksums.get(path, "")
-                modified.add(f"[yellow]{path}[/yellow] ({checksum[:8]})")
-        if knowledge.moves:
-            moved = knowledge_tree.add("[blue]Moved[/blue]")
-            for old_path, new_path in sorted(knowledge.moves.items()):
-                checksum = knowledge.checksums.get(new_path, "")
-                moved.add(f"[blue]{old_path}[/blue] → [blue]{new_path}[/blue] ({checksum[:8]})")
-        if knowledge.deleted:
-            deleted = knowledge_tree.add("[red]Deleted[/red]")
-            for path in sorted(knowledge.deleted):
-                deleted.add(f"[red]{path}[/red]")
-        console.print(knowledge_tree)
-
-
-async def run_sync(verbose: bool = False):
-    """Run sync operation."""
-    app_config = ConfigManager().config
-    config = get_project_config()
-
-    _, session_maker = await db.get_or_create_db(
-        db_path=app_config.database_path, db_type=db.DatabaseType.FILESYSTEM
-    )
-    project_repository = ProjectRepository(session_maker)
-    project = await project_repository.get_by_name(config.project)
-    if not project:  # pragma: no cover
-        raise Exception(f"Project '{config.project}' not found")
-
-    import time
-
-    start_time = time.time()
-
-    logger.info(
-        "Sync command started",
-        project=config.project,
-        verbose=verbose,
-        directory=str(config.home),
-    )
-
-    sync_service = await get_sync_service(project)
-
-    logger.info("Running one-time sync")
-    knowledge_changes = await sync_service.sync(config.home, project_name=project.name)
-
-    # Log results
-    duration_ms = int((time.time() - start_time) * 1000)
-    logger.info(
-        "Sync command completed",
-        project=config.project,
-        total_changes=knowledge_changes.total,
-        new_files=len(knowledge_changes.new),
-        modified_files=len(knowledge_changes.modified),
-        deleted_files=len(knowledge_changes.deleted),
-        moved_files=len(knowledge_changes.moves),
-        duration_ms=duration_ms,
-    )
-
-    # Display results
-    if verbose:
-        display_detailed_sync_results(knowledge_changes)
-    else:
-        display_sync_summary(knowledge_changes)  # pragma: no cover
+from basic_memory.cli.commands.command_utils import run_sync
+from basic_memory.config import ConfigManager
 
 
 @app.command()
 def sync(
-    verbose: bool = typer.Option(
-        False,
-        "--verbose",
-        "-v",
-        help="Show detailed sync information.",
-    ),
+    project: Annotated[
+        Optional[str],
+        typer.Option(help="The project name."),
+    ] = None,
+    watch: Annotated[
+        bool,
+        typer.Option("--watch", help="Run continuous sync (cloud mode only)"),
+    ] = False,
+    interval: Annotated[
+        int,
+        typer.Option("--interval", help="Sync interval in seconds for watch mode (default: 60)"),
+    ] = 60,
 ) -> None:
-    """Sync knowledge files with the database."""
-    config = get_project_config()
+    """Sync knowledge files with the database.
 
-    try:
-        # Show which project we're syncing
-        typer.echo(f"Syncing project: {config.project}")
-        typer.echo(f"Project path: {config.home}")
+    In local mode: Scans filesystem and updates database.
+    In cloud mode: Runs bidirectional file sync (bisync) then updates database.
 
-        # Run sync
-        asyncio.run(run_sync(verbose=verbose))
+    Examples:
+      bm sync                    # One-time sync
+      bm sync --watch            # Continuous sync every 60s
+      bm sync --watch --interval 30  # Continuous sync every 30s
+    """
+    config = ConfigManager().config
 
-    except Exception as e:  # pragma: no cover
-        if not isinstance(e, typer.Exit):
-            logger.exception(
-                "Sync command failed",
-                f"project={config.project},"
-                f"error={str(e)},"
-                f"error_type={type(e).__name__},"
-                f"directory={str(config.home)}",
-            )
-            typer.echo(f"Error during sync: {e}", err=True)
+    if config.cloud_mode_enabled:
+        # Cloud mode: run bisync which includes database sync
+        from basic_memory.cli.commands.cloud.bisync_commands import run_bisync, run_bisync_watch
+
+        try:
+            if watch:
+                run_bisync_watch(interval_seconds=interval)
+            else:
+                run_bisync()
+        except Exception:
             raise typer.Exit(1)
-        raise
+    else:
+        # Local mode: just database sync
+        if watch:
+            typer.echo(
+                "Error: --watch is only available in cloud mode. Run 'bm cloud login' first."
+            )
+            raise typer.Exit(1)
+
+        asyncio.run(run_sync(project))

src/basic_memory/cli/commands/tool.py

@@ -9,6 +9,7 @@ from loguru import logger
 from rich import print as rprint
 
 from basic_memory.cli.app import app
+from basic_memory.config import ConfigManager
 
 # Import prompts
 from basic_memory.mcp.prompts.continue_conversation import (
@@ -34,6 +35,12 @@ app.add_typer(tool_app, name="tool", help="Access to MCP tools via CLI")
 def write_note(
     title: Annotated[str, typer.Option(help="The title of the note")],
     folder: Annotated[str, typer.Option(help="The folder to create the note in")],
+    project: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The project to write to. If not provided, the default project will be used."
+        ),
+    ] = None,
     content: Annotated[
         Optional[str],
         typer.Option(
@@ -90,7 +97,19 @@ def write_note(
             typer.echo("Empty content provided. Please provide non-empty content.", err=True)
             raise typer.Exit(1)
 
-        note = asyncio.run(mcp_write_note.fn(title, content, folder, tags))
+        # look for the project in the config
+        config_manager = ConfigManager()
+        project_name = None
+        if project is not None:
+            project_name, _ = config_manager.get_project(project)
+            if not project_name:
+                typer.echo(f"No project found named: {project}", err=True)
+                raise typer.Exit(1)
+
+        # use the project name, or the default from the config
+        project_name = project_name or config_manager.default_project
+
+        note = asyncio.run(mcp_write_note.fn(title, content, folder, project_name, tags))
         rprint(note)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
@@ -100,10 +119,33 @@ def write_note(
 
 
 @tool_app.command()
-def read_note(identifier: str, page: int = 1, page_size: int = 10):
+def read_note(
+    identifier: str,
+    project: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The project to use for the note. If not provided, the default project will be used."
+        ),
+    ] = None,
+    page: int = 1,
+    page_size: int = 10,
+):
     """Read a markdown note from the knowledge base."""
+
+    # look for the project in the config
+    config_manager = ConfigManager()
+    project_name = None
+    if project is not None:
+        project_name, _ = config_manager.get_project(project)
+        if not project_name:
+            typer.echo(f"No project found named: {project}", err=True)
+            raise typer.Exit(1)
+
+    # use the project name, or the default from the config
+    project_name = project_name or config_manager.default_project
+
     try:
-        note = asyncio.run(mcp_read_note.fn(identifier, page, page_size))
+        note = asyncio.run(mcp_read_note.fn(identifier, project_name, page, page_size))
         rprint(note)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
@@ -115,6 +157,10 @@ def read_note(identifier: str, page: int = 1, page_size: int = 10):
 @tool_app.command()
 def build_context(
     url: MemoryUrl,
+    project: Annotated[
+        Optional[str],
+        typer.Option(help="The project to use. If not provided, the default project will be used."),
+    ] = None,
     depth: Optional[int] = 1,
     timeframe: Optional[TimeFrame] = "7d",
     page: int = 1,
@@ -122,9 +168,23 @@ def build_context(
     max_related: int = 10,
 ):
     """Get context needed to continue a discussion."""
+
+    # look for the project in the config
+    config_manager = ConfigManager()
+    project_name = None
+    if project is not None:
+        project_name, _ = config_manager.get_project(project)
+        if not project_name:
+            typer.echo(f"No project found named: {project}", err=True)
+            raise typer.Exit(1)
+
+    # use the project name, or the default from the config
+    project_name = project_name or config_manager.default_project
+
     try:
         context = asyncio.run(
             mcp_build_context.fn(
+                project=project_name,
                 url=url,
                 depth=depth,
                 timeframe=timeframe,
@@ -150,30 +210,21 @@ def recent_activity(
     type: Annotated[Optional[List[SearchItemType]], typer.Option()] = None,
     depth: Optional[int] = 1,
     timeframe: Optional[TimeFrame] = "7d",
-    page: int = 1,
-    page_size: int = 10,
-    max_related: int = 10,
 ):
     """Get recent activity across the knowledge base."""
     try:
-        context = asyncio.run(
+        result = asyncio.run(
             mcp_recent_activity.fn(
                 type=type,  # pyright: ignore [reportArgumentType]
                 depth=depth,
                 timeframe=timeframe,
-                page=page,
-                page_size=page_size,
-                max_related=max_related,
             )
         )
-        # Use json module for more controlled serialization
-        import json
-
-        context_dict = context.model_dump(exclude_none=True)
-        print(json.dumps(context_dict, indent=2, ensure_ascii=True, default=str))
+        # The tool now returns a formatted string directly
+        print(result)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
-            typer.echo(f"Error during build_context: {e}", err=True)
+            typer.echo(f"Error during recent_activity: {e}", err=True)
             raise typer.Exit(1)
         raise
 
@@ -183,6 +234,12 @@ def search_notes(
     query: str,
     permalink: Annotated[bool, typer.Option("--permalink", help="Search permalink values")] = False,
     title: Annotated[bool, typer.Option("--title", help="Search title values")] = False,
+    project: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The project to use for the note. If not provided, the default project will be used."
+        ),
+    ] = None,
     after_date: Annotated[
         Optional[str],
         typer.Option("--after_date", help="Search results after date, eg. '2d', '1 week'"),
@@ -191,6 +248,19 @@ def search_notes(
     page_size: int = 10,
 ):
     """Search across all content in the knowledge base."""
+
+    # look for the project in the config
+    config_manager = ConfigManager()
+    project_name = None
+    if project is not None:
+        project_name, _ = config_manager.get_project(project)
+        if not project_name:
+            typer.echo(f"No project found named: {project}", err=True)
+            raise typer.Exit(1)
+
+    # use the project name, or the default from the config
+    project_name = project_name or config_manager.default_project
+
     if permalink and title:  # pragma: no cover
         print("Cannot search both permalink and title")
         raise typer.Abort()
@@ -212,6 +282,7 @@ def search_notes(
         results = asyncio.run(
             mcp_search.fn(
                 query,
+                project_name,
                 search_type=search_type,
                 page=page,
                 after_date=after_date,

src/basic_memory/cli/main.py

@@ -4,6 +4,7 @@ from basic_memory.cli.app import app  # pragma: no cover
 
 # Register commands
 from basic_memory.cli.commands import (  # noqa: F401  # pragma: no cover
+    cloud,
     db,
     import_chatgpt,
     import_claude_conversations,

src/basic_memory/config.py

@@ -54,6 +54,10 @@ class BasicMemoryConfig(BaseSettings):
         default="main",
         description="Name of the default project to use",
     )
+    default_project_mode: bool = Field(
+        default=False,
+        description="When True, MCP tools automatically use default_project when no project parameter is specified. Enables simplified UX for single-project workflows.",
+    )
 
     # overridden by ~/.basic-memory/config.json
     log_level: str = "INFO"
@@ -63,6 +67,10 @@ class BasicMemoryConfig(BaseSettings):
         default=1000, description="Milliseconds to wait after changes before syncing", gt=0
     )
 
+    watch_project_reload_interval: int = Field(
+        default=30, description="Seconds between reloading project list in watch service", gt=0
+    )
+
     # update permalinks on move
     update_permalinks_on_move: bool = Field(
         default=False,
@@ -74,22 +82,83 @@ class BasicMemoryConfig(BaseSettings):
         description="Whether to sync changes in real time. default (True)",
     )
 
+    sync_thread_pool_size: int = Field(
+        default=4,
+        description="Size of thread pool for file I/O operations in sync service",
+        gt=0,
+    )
+
     kebab_filenames: bool = Field(
         default=False,
         description="Format for generated filenames. False preserves spaces and special chars, True converts them to hyphens for consistency with permalinks",
     )
 
+    disable_permalinks: bool = Field(
+        default=False,
+        description="Disable automatic permalink generation in frontmatter. When enabled, new notes won't have permalinks added and sync won't update permalinks. Existing permalinks will still work for reading.",
+    )
+
+    skip_initialization_sync: bool = Field(
+        default=False,
+        description="Skip expensive initialization synchronization. Useful for cloud/stateless deployments where project reconciliation is not needed.",
+    )
+
     # API connection configuration
     api_url: Optional[str] = Field(
         default=None,
         description="URL of remote Basic Memory API. If set, MCP will connect to this API instead of using local ASGI transport.",
     )
 
+    # Cloud configuration
+    cloud_client_id: str = Field(
+        default="client_01K6KWQPW6J1M8VV7R3TZP5A6M",
+        description="OAuth client ID for Basic Memory Cloud",
+    )
+
+    cloud_domain: str = Field(
+        default="https://eloquent-lotus-05.authkit.app",
+        description="AuthKit domain for Basic Memory Cloud",
+    )
+
+    cloud_host: str = Field(
+        default_factory=lambda: os.getenv(
+            "BASIC_MEMORY_CLOUD_HOST", "https://cloud.basicmemory.com"
+        ),
+        description="Basic Memory Cloud host URL",
+    )
+
+    cloud_mode: bool = Field(
+        default=False,
+        description="Enable cloud mode - all requests go to cloud instead of local (config file value)",
+    )
+
+    @property
+    def cloud_mode_enabled(self) -> bool:
+        """Check if cloud mode is enabled.
+
+        Priority:
+        1. BASIC_MEMORY_CLOUD_MODE environment variable
+        2. Config file value (cloud_mode)
+        """
+        env_value = os.environ.get("BASIC_MEMORY_CLOUD_MODE", "").lower()
+        if env_value in ("true", "1", "yes"):
+            return True
+        elif env_value in ("false", "0", "no"):
+            return False
+        # Fall back to config file value
+        return self.cloud_mode
+
+    bisync_config: Dict[str, Any] = Field(
+        default_factory=lambda: {
+            "profile": "balanced",
+            "sync_dir": str(Path.home() / "basic-memory-cloud-sync"),
+        },
+        description="Bisync configuration for cloud sync",
+    )
+
     model_config = SettingsConfigDict(
         env_prefix="BASIC_MEMORY_",
         extra="ignore",
-        env_file=".env",
-        env_file_encoding="utf-8",
     )
 
     def get_project_path(self, project_name: Optional[str] = None) -> Path:  # pragma: no cover
@@ -158,6 +227,10 @@ class BasicMemoryConfig(BaseSettings):
                     raise e
         return v
 
+    @property
+    def data_dir_path(self):
+        return Path.home() / DATA_DIR_NAME
+
 
 class ConfigManager:
     """Manages Basic Memory configuration."""
@@ -276,7 +349,7 @@ def get_project_config(project_name: Optional[str] = None) -> ProjectConfig:
     os_project_name = os.environ.get("BASIC_MEMORY_PROJECT", None)
     if os_project_name:  # pragma: no cover
         logger.warning(
-            f"BASIC_MEMORY_PROJECT is not supported anymore. Use the --project flag or set the default project in the config instead. Setting default project to {os_project_name}"
+            f"BASIC_MEMORY_PROJECT is not supported anymore. Set the default project in the config instead. Setting default project to {os_project_name}"
         )
         actual_project_name = project_name
     # if the project_name is passed in, use it
@@ -307,15 +380,6 @@ def save_basic_memory_config(file_path: Path, config: BasicMemoryConfig) -> None
         logger.error(f"Failed to save config: {e}")
 
 
-def update_current_project(project_name: str) -> None:
-    """Update the global config to use a different project.
-
-    This is used by the CLI when --project flag is specified.
-    """
-    global config
-    config = get_project_config(project_name)  # pragma: no cover
-
-
 # setup logging to a single log file in user home directory
 user_home = Path.home()
 log_dir = user_home / DATA_DIR_NAME

src/basic_memory/db.py

@@ -1,4 +1,5 @@
 import asyncio
+import os
 from contextlib import asynccontextmanager
 from enum import Enum, auto
 from pathlib import Path
@@ -9,7 +10,7 @@ from alembic import command
 from alembic.config import Config
 
 from loguru import logger
-from sqlalchemy import text
+from sqlalchemy import text, event
 from sqlalchemy.ext.asyncio import (
     create_async_engine,
     async_sessionmaker,
@@ -17,6 +18,7 @@ from sqlalchemy.ext.asyncio import (
     AsyncEngine,
     async_scoped_session,
 )
+from sqlalchemy.pool import NullPool
 
 from basic_memory.repository.search_repository import SearchRepository
 
@@ -73,13 +75,77 @@ async def scoped_session(
         await factory.remove()
 
 
+def _configure_sqlite_connection(dbapi_conn, enable_wal: bool = True) -> None:
+    """Configure SQLite connection with WAL mode and optimizations.
+
+    Args:
+        dbapi_conn: Database API connection object
+        enable_wal: Whether to enable WAL mode (should be False for in-memory databases)
+    """
+    cursor = dbapi_conn.cursor()
+    try:
+        # Enable WAL mode for better concurrency (not supported for in-memory databases)
+        if enable_wal:
+            cursor.execute("PRAGMA journal_mode=WAL")
+        # Set busy timeout to handle locked databases
+        cursor.execute("PRAGMA busy_timeout=10000")  # 10 seconds
+        # Optimize for performance
+        cursor.execute("PRAGMA synchronous=NORMAL")
+        cursor.execute("PRAGMA cache_size=-64000")  # 64MB cache
+        cursor.execute("PRAGMA temp_store=MEMORY")
+        # Windows-specific optimizations
+        if os.name == "nt":
+            cursor.execute("PRAGMA locking_mode=NORMAL")  # Ensure normal locking on Windows
+    except Exception as e:
+        # Log but don't fail - some PRAGMAs may not be supported
+        logger.warning(f"Failed to configure SQLite connection: {e}")
+    finally:
+        cursor.close()
+
+
 def _create_engine_and_session(
     db_path: Path, db_type: DatabaseType = DatabaseType.FILESYSTEM
 ) -> tuple[AsyncEngine, async_sessionmaker[AsyncSession]]:
     """Internal helper to create engine and session maker."""
     db_url = DatabaseType.get_db_url(db_path, db_type)
     logger.debug(f"Creating engine for db_url: {db_url}")
-    engine = create_async_engine(db_url, connect_args={"check_same_thread": False})
+
+    # Configure connection args with Windows-specific settings
+    connect_args: dict[str, bool | float | None] = {"check_same_thread": False}
+
+    # Add Windows-specific parameters to improve reliability
+    if os.name == "nt":  # Windows
+        connect_args.update(
+            {
+                "timeout": 30.0,  # Increase timeout to 30 seconds for Windows
+                "isolation_level": None,  # Use autocommit mode
+            }
+        )
+        # Use NullPool for Windows filesystem databases to avoid connection pooling issues
+        # Important: Do NOT use NullPool for in-memory databases as it will destroy the database
+        # between connections
+        if db_type == DatabaseType.FILESYSTEM:
+            engine = create_async_engine(
+                db_url,
+                connect_args=connect_args,
+                poolclass=NullPool,  # Disable connection pooling on Windows
+                echo=False,
+            )
+        else:
+            # In-memory databases need connection pooling to maintain state
+            engine = create_async_engine(db_url, connect_args=connect_args)
+    else:
+        engine = create_async_engine(db_url, connect_args=connect_args)
+
+    # Enable WAL mode for better concurrency and reliability
+    # Note: WAL mode is not supported for in-memory databases
+    enable_wal = db_type != DatabaseType.MEMORY
+
+    @event.listens_for(engine.sync_engine, "connect")
+    def enable_wal_mode(dbapi_conn, connection_record):
+        """Enable WAL mode on each connection."""
+        _configure_sqlite_connection(dbapi_conn, enable_wal=enable_wal)
+
     session_maker = async_sessionmaker(engine, expire_on_commit=False)
     return engine, session_maker
 
@@ -140,7 +206,42 @@ async def engine_session_factory(
     db_url = DatabaseType.get_db_url(db_path, db_type)
     logger.debug(f"Creating engine for db_url: {db_url}")
 
-    _engine = create_async_engine(db_url, connect_args={"check_same_thread": False})
+    # Configure connection args with Windows-specific settings
+    connect_args: dict[str, bool | float | None] = {"check_same_thread": False}
+
+    # Add Windows-specific parameters to improve reliability
+    if os.name == "nt":  # Windows
+        connect_args.update(
+            {
+                "timeout": 30.0,  # Increase timeout to 30 seconds for Windows
+                "isolation_level": None,  # Use autocommit mode
+            }
+        )
+        # Use NullPool for Windows filesystem databases to avoid connection pooling issues
+        # Important: Do NOT use NullPool for in-memory databases as it will destroy the database
+        # between connections
+        if db_type == DatabaseType.FILESYSTEM:
+            _engine = create_async_engine(
+                db_url,
+                connect_args=connect_args,
+                poolclass=NullPool,  # Disable connection pooling on Windows
+                echo=False,
+            )
+        else:
+            # In-memory databases need connection pooling to maintain state
+            _engine = create_async_engine(db_url, connect_args=connect_args)
+    else:
+        _engine = create_async_engine(db_url, connect_args=connect_args)
+
+    # Enable WAL mode for better concurrency and reliability
+    # Note: WAL mode is not supported for in-memory databases
+    enable_wal = db_type != DatabaseType.MEMORY
+
+    @event.listens_for(_engine.sync_engine, "connect")
+    def enable_wal_mode(dbapi_conn, connection_record):
+        """Enable WAL mode on each connection."""
+        _configure_sqlite_connection(dbapi_conn, enable_wal=enable_wal)
+
     try:
         _session_maker = async_sessionmaker(_engine, expire_on_commit=False)
 

src/basic_memory/deps.py

@@ -3,7 +3,7 @@
 from typing import Annotated
 from loguru import logger
 
-from fastapi import Depends, HTTPException, Path, status
+from fastapi import Depends, HTTPException, Path, status, Request
 from sqlalchemy.ext.asyncio import (
     AsyncSession,
     AsyncEngine,
@@ -78,9 +78,24 @@ ProjectConfigDep = Annotated[ProjectConfig, Depends(get_project_config)]  # prag
 
 
 async def get_engine_factory(
-    app_config: AppConfigDep,
+    request: Request,
 ) -> tuple[AsyncEngine, async_sessionmaker[AsyncSession]]:  # pragma: no cover
-    """Get engine and session maker."""
+    """Get cached engine and session maker from app state.
+
+    For API requests, returns cached connections from app.state for optimal performance.
+    For non-API contexts (CLI), falls back to direct database connection.
+    """
+    # Try to get cached connections from app state (API context)
+    if (
+        hasattr(request, "app")
+        and hasattr(request.app.state, "engine")
+        and hasattr(request.app.state, "session_maker")
+    ):
+        return request.app.state.engine, request.app.state.session_maker
+
+    # Fallback for non-API contexts (CLI)
+    logger.debug("Using fallback database connection for non-API context")
+    app_config = get_app_config()
     engine, session_maker = await db.get_or_create_db(app_config.database_path)
     return engine, session_maker
 
@@ -245,6 +260,7 @@ async def get_entity_service(
     entity_parser: EntityParserDep,
     file_service: FileServiceDep,
     link_resolver: "LinkResolverDep",
+    app_config: AppConfigDep,
 ) -> EntityService:
     """Create EntityService with repository."""
     return EntityService(
@@ -254,6 +270,7 @@ async def get_entity_service(
         entity_parser=entity_parser,
         file_service=file_service,
         link_resolver=link_resolver,
+        app_config=app_config,
     )
 
 

src/basic_memory/file_utils.py

@@ -240,40 +240,37 @@ async def update_frontmatter(path: FilePath, updates: Dict[str, Any]) -> str:
 def dump_frontmatter(post: frontmatter.Post) -> str:
     """
     Serialize frontmatter.Post to markdown with Obsidian-compatible YAML format.
-    
+
     This function ensures that tags are formatted as YAML lists instead of JSON arrays:
-    
+
     Good (Obsidian compatible):
     ---
     tags:
     - system
-    - overview  
+    - overview
     - reference
     ---
-    
+
     Bad (current behavior):
     ---
     tags: ["system", "overview", "reference"]
     ---
-    
+
     Args:
         post: frontmatter.Post object to serialize
-        
+
     Returns:
         String containing markdown with properly formatted YAML frontmatter
-    """    
+    """
     if not post.metadata:
         # No frontmatter, just return content
         return post.content
-        
+
     # Serialize YAML with block style for lists
     yaml_str = yaml.dump(
-        post.metadata,
-        sort_keys=False,
-        allow_unicode=True,
-        default_flow_style=False
+        post.metadata, sort_keys=False, allow_unicode=True, default_flow_style=False
     )
-    
+
     # Construct the final markdown with frontmatter
     if post.content:
         return f"---\n{yaml_str}---\n\n{post.content}"
@@ -298,3 +295,30 @@ def sanitize_for_filename(text: str, replacement: str = "-") -> str:
 
     return text.strip(replacement)
 
+
+def sanitize_for_folder(folder: str) -> str:
+    """
+    Sanitize folder path to be safe for use in file system paths.
+    Removes leading/trailing whitespace, compresses multiple slashes,
+    and removes special characters except for /, -, and _.
+    """
+    if not folder:
+        return ""
+
+    sanitized = folder.strip()
+
+    if sanitized.startswith("./"):
+        sanitized = sanitized[2:]
+
+    # ensure no special characters (except for a few that are allowed)
+    sanitized = "".join(
+        c for c in sanitized if c.isalnum() or c in (".", " ", "-", "_", "\\", "/")
+    ).rstrip()
+
+    # compress multiple, repeated instances of path separators
+    sanitized = re.sub(r"[\\/]+", "/", sanitized)
+
+    # trim any leading/trailing path separators
+    sanitized = sanitized.strip("\\/")
+
+    return sanitized

src/basic_memory/ignore_utils.py

@@ -0,0 +1,295 @@
+"""Utilities for handling .gitignore patterns and file filtering."""
+
+import fnmatch
+from pathlib import Path
+from typing import Set
+
+
+# Common directories and patterns to ignore by default
+# These are used as fallback if .bmignore doesn't exist
+DEFAULT_IGNORE_PATTERNS = {
+    # Hidden files (files starting with dot)
+    ".*",
+    # Basic Memory internal files
+    "memory.db",
+    "memory.db-shm",
+    "memory.db-wal",
+    "config.json",
+    # Version control
+    ".git",
+    ".svn",
+    # Python
+    "__pycache__",
+    "*.pyc",
+    "*.pyo",
+    "*.pyd",
+    ".pytest_cache",
+    ".coverage",
+    "*.egg-info",
+    ".tox",
+    ".mypy_cache",
+    ".ruff_cache",
+    # Virtual environments
+    ".venv",
+    "venv",
+    "env",
+    ".env",
+    # Node.js
+    "node_modules",
+    # Build artifacts
+    "build",
+    "dist",
+    ".cache",
+    # IDE
+    ".idea",
+    ".vscode",
+    # OS files
+    ".DS_Store",
+    "Thumbs.db",
+    "desktop.ini",
+    # Obsidian
+    ".obsidian",
+    # Temporary files
+    "*.tmp",
+    "*.swp",
+    "*.swo",
+    "*~",
+}
+
+
+def get_bmignore_path() -> Path:
+    """Get path to .bmignore file.
+
+    Returns:
+        Path to ~/.basic-memory/.bmignore
+    """
+    return Path.home() / ".basic-memory" / ".bmignore"
+
+
+def create_default_bmignore() -> None:
+    """Create default .bmignore file if it doesn't exist.
+
+    This ensures users have a file they can customize for all Basic Memory operations.
+    """
+    bmignore_path = get_bmignore_path()
+
+    if bmignore_path.exists():
+        return
+
+    bmignore_path.parent.mkdir(parents=True, exist_ok=True)
+    bmignore_path.write_text("""# Basic Memory Ignore Patterns
+# This file is used by both 'bm cloud upload', 'bm cloud bisync', and file sync
+# Patterns use standard gitignore-style syntax
+
+# Hidden files (files starting with dot)
+.*
+
+# Basic Memory internal files
+memory.db
+memory.db-shm
+memory.db-wal
+config.json
+
+# Version control
+.git
+.svn
+
+# Python
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache
+.coverage
+*.egg-info
+.tox
+.mypy_cache
+.ruff_cache
+
+# Virtual environments
+.venv
+venv
+env
+.env
+
+# Node.js
+node_modules
+
+# Build artifacts
+build
+dist
+.cache
+
+# IDE
+.idea
+.vscode
+
+# OS files
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Obsidian
+.obsidian
+
+# Temporary files
+*.tmp
+*.swp
+*.swo
+*~
+""")
+
+
+def load_bmignore_patterns() -> Set[str]:
+    """Load patterns from .bmignore file.
+
+    Returns:
+        Set of patterns from .bmignore, or DEFAULT_IGNORE_PATTERNS if file doesn't exist
+    """
+    bmignore_path = get_bmignore_path()
+
+    # Create default file if it doesn't exist
+    if not bmignore_path.exists():
+        create_default_bmignore()
+
+    patterns = set()
+
+    try:
+        with bmignore_path.open("r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                # Skip empty lines and comments
+                if line and not line.startswith("#"):
+                    patterns.add(line)
+    except Exception:
+        # If we can't read .bmignore, fall back to defaults
+        return set(DEFAULT_IGNORE_PATTERNS)
+
+    # If no patterns were loaded, use defaults
+    if not patterns:
+        return set(DEFAULT_IGNORE_PATTERNS)
+
+    return patterns
+
+
+def load_gitignore_patterns(base_path: Path) -> Set[str]:
+    """Load gitignore patterns from .gitignore file and .bmignore.
+
+    Combines patterns from:
+    1. ~/.basic-memory/.bmignore (user's global ignore patterns)
+    2. {base_path}/.gitignore (project-specific patterns)
+
+    Args:
+        base_path: The base directory to search for .gitignore file
+
+    Returns:
+        Set of patterns to ignore
+    """
+    # Start with patterns from .bmignore
+    patterns = load_bmignore_patterns()
+
+    gitignore_file = base_path / ".gitignore"
+    if gitignore_file.exists():
+        try:
+            with gitignore_file.open("r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    # Skip empty lines and comments
+                    if line and not line.startswith("#"):
+                        patterns.add(line)
+        except Exception:
+            # If we can't read .gitignore, just use default patterns
+            pass
+
+    return patterns
+
+
+def should_ignore_path(file_path: Path, base_path: Path, ignore_patterns: Set[str]) -> bool:
+    """Check if a file path should be ignored based on gitignore patterns.
+
+    Args:
+        file_path: The file path to check
+        base_path: The base directory for relative path calculation
+        ignore_patterns: Set of patterns to match against
+
+    Returns:
+        True if the path should be ignored, False otherwise
+    """
+    # Get the relative path from base
+    try:
+        relative_path = file_path.relative_to(base_path)
+        relative_str = str(relative_path)
+        relative_posix = relative_path.as_posix()  # Use forward slashes for matching
+
+        # Check each pattern
+        for pattern in ignore_patterns:
+            # Handle patterns starting with / (root relative)
+            if pattern.startswith("/"):
+                root_pattern = pattern[1:]  # Remove leading /
+
+                # For directory patterns ending with /
+                if root_pattern.endswith("/"):
+                    dir_name = root_pattern[:-1]  # Remove trailing /
+                    # Check if the first part of the path matches the directory name
+                    if len(relative_path.parts) > 0 and relative_path.parts[0] == dir_name:
+                        return True
+                else:
+                    # Regular root-relative pattern
+                    if fnmatch.fnmatch(relative_posix, root_pattern):
+                        return True
+                continue
+
+            # Handle directory patterns (ending with /)
+            if pattern.endswith("/"):
+                dir_name = pattern[:-1]  # Remove trailing /
+                # Check if any path part matches the directory name
+                if dir_name in relative_path.parts:
+                    return True
+                continue
+
+            # Direct name match (e.g., ".git", "node_modules")
+            if pattern in relative_path.parts:
+                return True
+
+            # Check if any individual path part matches the glob pattern
+            # This handles cases like ".*" matching ".hidden.md" in "concept/.hidden.md"
+            for part in relative_path.parts:
+                if fnmatch.fnmatch(part, pattern):
+                    return True
+
+            # Glob pattern match on full path
+            if fnmatch.fnmatch(relative_posix, pattern) or fnmatch.fnmatch(relative_str, pattern):
+                return True
+
+        return False
+    except ValueError:
+        # If we can't get relative path, don't ignore
+        return False
+
+
+def filter_files(
+    files: list[Path], base_path: Path, ignore_patterns: Set[str] | None = None
+) -> tuple[list[Path], int]:
+    """Filter a list of files based on gitignore patterns.
+
+    Args:
+        files: List of file paths to filter
+        base_path: The base directory for relative path calculation
+        ignore_patterns: Set of patterns to ignore. If None, loads from .gitignore
+
+    Returns:
+        Tuple of (filtered_files, ignored_count)
+    """
+    if ignore_patterns is None:
+        ignore_patterns = load_gitignore_patterns(base_path)
+
+    filtered_files = []
+    ignored_count = 0
+
+    for file_path in files:
+        if should_ignore_path(file_path, base_path, ignore_patterns):
+            ignored_count += 1
+        else:
+            filtered_files.append(file_path)
+
+    return filtered_files, ignored_count

src/basic_memory/markdown/plugins.py

@@ -9,6 +9,7 @@ from markdown_it.token import Token
 def is_observation(token: Token) -> bool:
     """Check if token looks like our observation format."""
     import re
+
     if token.type != "inline":  # pragma: no cover
         return False
     # Use token.tag which contains the actual content for test tokens, fallback to content
@@ -18,15 +19,15 @@ def is_observation(token: Token) -> bool:
     # if it's a markdown_task, return false
     if content.startswith("[ ]") or content.startswith("[x]") or content.startswith("[-]"):
         return False
-    
+
     # Exclude markdown links: [text](url)
     if re.match(r"^\[.*?\]\(.*?\)$", content):
         return False
-    
+
     # Exclude wiki links: [[text]]
     if re.match(r"^\[\[.*?\]\]$", content):
         return False
-    
+
     # Check for proper observation format: [category] content
     match = re.match(r"^\[([^\[\]()]+)\]\s+(.+)", content)
     has_tags = "#" in content
@@ -36,9 +37,10 @@ def is_observation(token: Token) -> bool:
 def parse_observation(token: Token) -> Dict[str, Any]:
     """Extract observation parts from token."""
     import re
+
     # Use token.tag which contains the actual content for test tokens, fallback to content
     content = (token.tag or token.content).strip()
-    
+
     # Parse [category] with regex
     match = re.match(r"^\[([^\[\]()]+)\]\s+(.+)", content)
     category = None
@@ -50,7 +52,7 @@ def parse_observation(token: Token) -> Dict[str, Any]:
         empty_match = re.match(r"^\[\]\s+(.+)", content)
         if empty_match:
             content = empty_match.group(1).strip()
-    
+
     # Parse (context)
     context = None
     if content.endswith(")"):
@@ -58,7 +60,7 @@ def parse_observation(token: Token) -> Dict[str, Any]:
         if start != -1:
             context = content[start + 1 : -1].strip()
             content = content[:start].strip()
-    
+
     # Extract tags and keep original content
     tags = []
     parts = content.split()
@@ -69,7 +71,7 @@ def parse_observation(token: Token) -> Dict[str, Any]:
                 tags.extend(subtags)
             else:
                 tags.append(part[1:])
-    
+
     return {
         "category": category,
         "content": content,

src/basic_memory/mcp/async_client.py

@@ -1,4 +1,4 @@
-from httpx import ASGITransport, AsyncClient
+from httpx import ASGITransport, AsyncClient, Timeout
 from loguru import logger
 
 from basic_memory.api.app import app as fastapi_app
@@ -9,19 +9,31 @@ def create_client() -> AsyncClient:
     """Create an HTTP client based on configuration.
 
     Returns:
-        AsyncClient configured for either local ASGI or remote HTTP transport
+        AsyncClient configured for either local ASGI or remote proxy
     """
     config_manager = ConfigManager()
-    config = config_manager.load_config()
+    config = config_manager.config
 
-    if config.api_url:
-        # Use HTTP transport for remote API
-        logger.info(f"Creating HTTP client for remote Basic Memory API: {config.api_url}")
-        return AsyncClient(base_url=config.api_url)
+    # Configure timeout for longer operations like write_note
+    # Default httpx timeout is 5 seconds which is too short for file operations
+    timeout = Timeout(
+        connect=10.0,  # 10 seconds for connection
+        read=30.0,  # 30 seconds for reading response
+        write=30.0,  # 30 seconds for writing request
+        pool=30.0,  # 30 seconds for connection pool
+    )
+
+    if config.cloud_mode_enabled:
+        # Use HTTP transport to proxy endpoint
+        proxy_base_url = f"{config.cloud_host}/proxy"
+        logger.info(f"Creating HTTP client for proxy at: {proxy_base_url}")
+        return AsyncClient(base_url=proxy_base_url, timeout=timeout)
     else:
-        # Use ASGI transport for local API
-        logger.debug("Creating ASGI client for local Basic Memory API")
-        return AsyncClient(transport=ASGITransport(app=fastapi_app), base_url="http://test")
+        # Default: use ASGI transport for local API (development mode)
+        logger.info("Creating ASGI client for local Basic Memory API")
+        return AsyncClient(
+            transport=ASGITransport(app=fastapi_app), base_url="http://test", timeout=timeout
+        )
 
 
 # Create shared async client

src/basic_memory/mcp/project_context.py

@@ -0,0 +1,141 @@
+"""Project context utilities for Basic Memory MCP server.
+
+Provides project lookup utilities for MCP tools.
+Handles project validation and context management in one place.
+"""
+
+import os
+from typing import Optional, List
+from httpx import AsyncClient
+from httpx._types import (
+    HeaderTypes,
+)
+from loguru import logger
+from fastmcp import Context
+
+from basic_memory.config import ConfigManager
+from basic_memory.mcp.tools.utils import call_get
+from basic_memory.schemas.project_info import ProjectItem, ProjectList
+from basic_memory.utils import generate_permalink
+
+
+async def resolve_project_parameter(project: Optional[str] = None) -> Optional[str]:
+    """Resolve project parameter using three-tier hierarchy.
+
+    if config.cloud_mode:
+        project is required
+    else:
+        Resolution order:
+        1. Single Project Mode  (--project cli arg, or BASIC_MEMORY_MCP_PROJECT env var) - highest priority
+        2. Explicit project parameter - medium priority
+        3. Default project if default_project_mode=true - lowest priority
+
+    Args:
+        project: Optional explicit project parameter
+
+    Returns:
+        Resolved project name or None if no resolution possible
+    """
+
+    config = ConfigManager().config
+    # if cloud_mode, project is required
+    if config.cloud_mode:
+        if project:
+            logger.debug(f"project: {project}, cloud_mode: {config.cloud_mode}")
+            return project
+        else:
+            raise ValueError("No project specified. Project is required for cloud mode.")
+
+    # Priority 1: CLI constraint overrides everything (--project arg sets env var)
+    constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
+    if constrained_project:
+        logger.debug(f"Using CLI constrained project: {constrained_project}")
+        return constrained_project
+
+    # Priority 2: Explicit project parameter
+    if project:
+        logger.debug(f"Using explicit project parameter: {project}")
+        return project
+
+    # Priority 3: Default project mode
+    if config.default_project_mode:
+        logger.debug(f"Using default project from config: {config.default_project}")
+        return config.default_project
+
+    # No resolution possible
+    return None
+
+
+async def get_project_names(client: AsyncClient, headers: HeaderTypes | None = None) -> List[str]:
+    response = await call_get(client, "/projects/projects", headers=headers)
+    project_list = ProjectList.model_validate(response.json())
+    return [project.name for project in project_list.projects]
+
+
+async def get_active_project(
+    client: AsyncClient,
+    project: Optional[str] = None,
+    context: Optional[Context] = None,
+    headers: HeaderTypes | None = None,
+) -> ProjectItem:
+    """Get and validate project, setting it in context if available.
+
+    Args:
+        client: HTTP client for API calls
+        project: Optional project name (resolved using hierarchy)
+        context: Optional FastMCP context to cache the result
+
+    Returns:
+        The validated project item
+
+    Raises:
+        ValueError: If no project can be resolved
+        HTTPError: If project doesn't exist or is inaccessible
+    """
+    resolved_project = await resolve_project_parameter(project)
+    if not resolved_project:
+        project_names = await get_project_names(client, headers)
+        raise ValueError(
+            "No project specified. "
+            "Either set 'default_project_mode=true' in config, or use 'project' argument.\n"
+            f"Available projects: {project_names}"
+        )
+
+    project = resolved_project
+
+    # Check if already cached in context
+    if context:
+        cached_project = context.get_state("active_project")
+        if cached_project and cached_project.name == project:
+            logger.debug(f"Using cached project from context: {project}")
+            return cached_project
+
+    # Validate project exists by calling API
+    logger.debug(f"Validating project: {project}")
+    permalink = generate_permalink(project)
+    response = await call_get(client, f"/{permalink}/project/item", headers=headers)
+    active_project = ProjectItem.model_validate(response.json())
+
+    # Cache in context if available
+    if context:
+        context.set_state("active_project", active_project)
+        logger.debug(f"Cached project in context: {project}")
+
+    logger.debug(f"Validated project: {active_project.name}")
+    return active_project
+
+
+def add_project_metadata(result: str, project_name: str) -> str:
+    """Add project context as metadata footer for assistant session tracking.
+
+    Provides clear project context to help the assistant remember which
+    project is being used throughout the conversation session.
+
+    Args:
+        result: The tool result string
+        project_name: The project name that was used
+
+    Returns:
+        Result with project session tracking metadata
+    """
+    return f"{result}\n\n[Session: Using project '{project_name}']"

src/basic_memory/mcp/project_session.py

@@ -1,120 +0,0 @@
-"""Project session management for Basic Memory MCP server.
-
-Provides simple in-memory project context for MCP tools, allowing users to switch
-between projects during a conversation without restarting the server.
-"""
-
-from dataclasses import dataclass
-from typing import Optional
-from loguru import logger
-
-from basic_memory.config import ProjectConfig, get_project_config, ConfigManager
-
-
-@dataclass
-class ProjectSession:
-    """Simple in-memory project context for MCP session.
-
-    This class manages the current project context that tools use when no explicit
-    project is specified. It's initialized with the default project from config
-    and can be changed during the conversation.
-    """
-
-    current_project: Optional[str] = None
-    default_project: Optional[str] = None
-
-    def initialize(self, default_project: str) -> "ProjectSession":
-        """Set the default project from config on startup.
-
-        Args:
-            default_project: The project name from configuration
-        """
-        self.default_project = default_project
-        self.current_project = default_project
-        logger.info(f"Initialized project session with default project: {default_project}")
-        return self
-
-    def get_current_project(self) -> str:
-        """Get the currently active project name.
-
-        Returns:
-            The current project name, falling back to default, then 'main'
-        """
-        return self.current_project or self.default_project or "main"
-
-    def set_current_project(self, project_name: str) -> None:
-        """Set the current project context.
-
-        Args:
-            project_name: The project to switch to
-        """
-        previous = self.current_project
-        self.current_project = project_name
-        logger.info(f"Switched project context: {previous} -> {project_name}")
-
-    def get_default_project(self) -> str:
-        """Get the default project name from startup.
-
-        Returns:
-            The default project name, or 'main' if not set
-        """
-        return self.default_project or "main"  # pragma: no cover
-
-    def reset_to_default(self) -> None:  # pragma: no cover
-        """Reset current project back to the default project."""
-        self.current_project = self.default_project  # pragma: no cover
-        logger.info(f"Reset project context to default: {self.default_project}")  # pragma: no cover
-
-    def refresh_from_config(self) -> None:
-        """Refresh session state from current configuration.
-
-        This method reloads the default project from config and reinitializes
-        the session. This should be called when the default project is changed
-        via CLI or API to ensure MCP session stays in sync.
-        """
-        # Reload config to get latest default project
-        current_config = ConfigManager().config
-        new_default = current_config.default_project
-
-        # Reinitialize with new default
-        self.initialize(new_default)
-        logger.info(f"Refreshed project session from config, new default: {new_default}")
-
-
-# Global session instance
-session = ProjectSession()
-
-
-def get_active_project(project_override: Optional[str] = None) -> ProjectConfig:
-    """Get the active project name for a tool call.
-
-    This is the main function tools should use to determine which project
-    to operate on.
-
-    Args:
-        project_override: Optional explicit project name from tool parameter
-
-    Returns:
-        The project name to use (override takes precedence over session context)
-    """
-    if project_override:  # pragma: no cover
-        project = get_project_config(project_override)
-        session.set_current_project(project_override)
-        return project
-
-    current_project = session.get_current_project()
-    active_project = get_project_config(current_project)
-    return active_project
-
-
-def add_project_metadata(result: str, project_name: str) -> str:
-    """Add project context as metadata footer for LLM awareness.
-
-    Args:
-        result: The tool result string
-        project_name: The project name that was used
-
-    Returns:
-        Result with project metadata footer
-    """
-    return f"{result}\n\n<!-- Project: {project_name} -->"  # pragma: no cover

src/basic_memory/mcp/prompts/ai_assistant_guide.py

@@ -1,5 +1,6 @@
 from pathlib import Path
 
+from basic_memory.config import ConfigManager
 from basic_memory.mcp.server import mcp
 from loguru import logger
 
@@ -12,14 +13,58 @@ from loguru import logger
 def ai_assistant_guide() -> str:
     """Return a concise guide on Basic Memory tools and how to use them.
 
-    Args:
-        focus: Optional area to focus on ("writing", "context", "search", etc.)
+    Dynamically adapts instructions based on configuration:
+    - Default project mode: Simplified instructions with automatic project
+    - Regular mode: Project discovery and selection guidance
+    - CLI constraint mode: Single project constraint information
 
     Returns:
         A focused guide on Basic Memory usage.
     """
     logger.info("Loading AI assistant guide resource")
+
+    # Load base guide content
     guide_doc = Path(__file__).parent.parent / "resources" / "ai_assistant_guide.md"
     content = guide_doc.read_text(encoding="utf-8")
-    logger.info(f"Loaded AI assistant guide ({len(content)} chars)")
-    return content
+
+    # Check configuration for mode-specific instructions
+    config = ConfigManager().config
+
+    # Add mode-specific header
+    mode_info = ""
+    if config.default_project_mode:
+        mode_info = f"""
+# 🎯 Default Project Mode Active
+
+**Current Configuration**: All operations automatically use project '{config.default_project}'
+
+**Simplified Usage**: You don't need to specify the project parameter in tool calls.
+- `write_note(title="Note", content="...", folder="docs")` ✅
+- Project parameter is optional and will default to '{config.default_project}'
+- To use a different project, explicitly specify: `project="other-project"`
+
+────────────────────────────────────────
+
+"""
+    else:
+        mode_info = """
+# 🔧 Multi-Project Mode Active
+
+**Current Configuration**: Project parameter required for all operations
+
+**Project Discovery Required**: Use these tools to select a project:
+- `list_memory_projects()` - See all available projects
+- `recent_activity()` - Get project activity and recommendations
+- Remember the user's project choice throughout the conversation
+
+────────────────────────────────────────
+
+"""
+
+    # Prepend mode info to the guide
+    enhanced_content = mode_info + content
+
+    logger.info(
+        f"Loaded AI assistant guide ({len(enhanced_content)} chars) with mode: {'default_project' if config.default_project_mode else 'multi_project'}"
+    )
+    return enhanced_content

src/basic_memory/mcp/prompts/continue_conversation.py

@@ -18,7 +18,7 @@ from basic_memory.schemas.prompt import ContinueConversationRequest
 
 
 @mcp.prompt(
-    name="Continue Conversation",
+    name="continue_conversation",
     description="Continue a previous conversation",
 )
 async def continue_conversation(

src/basic_memory/mcp/prompts/recent_activity.py

@@ -3,7 +3,7 @@
 These prompts help users see what has changed in their knowledge base recently.
 """
 
-from typing import Annotated
+from typing import Annotated, Optional
 
 from loguru import logger
 from pydantic import Field
@@ -12,49 +12,83 @@ from basic_memory.mcp.prompts.utils import format_prompt_context, PromptContext,
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.recent_activity import recent_activity
 from basic_memory.schemas.base import TimeFrame
+from basic_memory.schemas.memory import GraphContext, ProjectActivitySummary
 from basic_memory.schemas.search import SearchItemType
 
 
 @mcp.prompt(
-    name="Share Recent Activity",
-    description="Get recent activity from across the knowledge base",
+    name="recent_activity",
+    description="Get recent activity from a specific project or across all projects",
 )
 async def recent_activity_prompt(
     timeframe: Annotated[
         TimeFrame,
         Field(description="How far back to look for activity (e.g. '1d', '1 week')"),
     ] = "7d",
+    project: Annotated[
+        Optional[str],
+        Field(
+            description="Specific project to get activity from (None for discovery across all projects)"
+        ),
+    ] = None,
 ) -> str:
-    """Get recent activity from across the knowledge base.
+    """Get recent activity from a specific project or across all projects.
 
-    This prompt helps you see what's changed recently in the knowledge base,
-    showing new or updated documents and related information.
+    This prompt helps you see what's changed recently in the knowledge base.
+    In discovery mode (project=None), it shows activity across all projects.
+    In project-specific mode, it shows detailed activity for one project.
 
     Args:
         timeframe: How far back to look for activity (e.g. '1d', '1 week')
+        project: Specific project to get activity from (None for discovery across all projects)
 
     Returns:
         Formatted summary of recent activity
     """
-    logger.info(f"Getting recent activity, timeframe: {timeframe}")
+    logger.info(f"Getting recent activity, timeframe: {timeframe}, project: {project}")
 
-    recent = await recent_activity.fn(timeframe=timeframe, type=[SearchItemType.ENTITY])
+    recent = await recent_activity.fn(
+        project=project, timeframe=timeframe, type=[SearchItemType.ENTITY]
+    )
 
     # Extract primary results from the hierarchical structure
     primary_results = []
     related_results = []
 
-    if recent.results:
-        # Take up to 5 primary results
-        for item in recent.results[:5]:
-            primary_results.append(item.primary_result)
-            # Add up to 2 related results per primary item
-            if item.related_results:
-                related_results.extend(item.related_results[:2])
+    if isinstance(recent, ProjectActivitySummary):
+        # Discovery mode - extract results from all projects
+        for _, project_activity in recent.projects.items():
+            if project_activity.activity.results:
+                # Take up to 2 primary results per project
+                for item in project_activity.activity.results[:2]:
+                    primary_results.append(item.primary_result)
+                    # Add up to 1 related result per primary item
+                    if item.related_results:
+                        related_results.extend(item.related_results[:1])
+
+        # Limit total results for readability
+        primary_results = primary_results[:8]
+        related_results = related_results[:6]
+
+    elif isinstance(recent, GraphContext):
+        # Project-specific mode - use existing logic
+        if recent.results:
+            # Take up to 5 primary results
+            for item in recent.results[:5]:
+                primary_results.append(item.primary_result)
+                # Add up to 2 related results per primary item
+                if item.related_results:
+                    related_results.extend(item.related_results[:2])
+
+    # Set topic based on mode
+    if project:
+        topic = f"Recent Activity in {project} ({timeframe})"
+    else:
+        topic = f"Recent Activity Across All Projects ({timeframe})"
 
     prompt_context = format_prompt_context(
         PromptContext(
-            topic=f"Recent Activity from ({timeframe})",
+            topic=topic,
             timeframe=timeframe,
             results=[
                 PromptContextItem(
@@ -65,40 +99,90 @@ async def recent_activity_prompt(
         )
     )
 
-    # Add suggestions for summarizing recent activity
+    # Add mode-specific suggestions
     first_title = "Recent Topic"
     if primary_results and len(primary_results) > 0:
         first_title = primary_results[0].title
 
-    capture_suggestions = f"""
+    if project:
+        # Project-specific suggestions
+        capture_suggestions = f"""
     ## Opportunity to Capture Activity Summary
-    
-    Consider creating a summary note of recent activity:
-    
+
+    Consider creating a summary note of recent activity in {project}:
+
     ```python
     await write_note(
+        "{project}",
         title="Activity Summary {timeframe}",
         content='''
-        # Activity Summary for {timeframe}
-        
+        # Activity Summary for {project} ({timeframe})
+
         ## Overview
-        [Summary of key changes and developments over this period]
-        
+        [Summary of key changes and developments in this project over this period]
+
         ## Key Updates
-        [List main updates and their significance]
-        
+        [List main updates and their significance within this project]
+
         ## Observations
         - [trend] [Observation about patterns in recent activity]
         - [insight] [Connection between different activities]
-        
+
         ## Relations
         - summarizes [[{first_title}]]
-        - relates_to [[Project Overview]]
-        '''
+        - relates_to [[{project} Overview]]
+        ''',
+        folder="summaries"
     )
     ```
-    
-    Summarizing periodic activity helps create high-level insights and connections between topics.
+
+    Summarizing periodic activity helps create high-level insights and connections within the project.
+    """
+    else:
+        # Discovery mode suggestions
+        project_count = len(recent.projects) if isinstance(recent, ProjectActivitySummary) else 0
+        most_active = (
+            getattr(recent.summary, "most_active_project", "Unknown")
+            if isinstance(recent, ProjectActivitySummary)
+            else "Unknown"
+        )
+
+        capture_suggestions = f"""
+    ## Cross-Project Activity Discovery
+
+    Found activity across {project_count} projects. Most active: **{most_active}**
+
+    Consider creating a cross-project summary:
+
+    ```python
+    await write_note(
+        "{most_active if most_active != "Unknown" else "main"}",
+        title="Cross-Project Activity Summary {timeframe}",
+        content='''
+        # Cross-Project Activity Summary ({timeframe})
+
+        ## Overview
+        Activity found across {project_count} projects, with {most_active} showing the most activity.
+
+        ## Key Developments
+        [Summarize important changes across all projects]
+
+        ## Project Insights
+        [Note patterns or connections between projects]
+
+        ## Observations
+        - [trend] [Cross-project patterns observed]
+        - [insight] [Connections between different project activities]
+
+        ## Relations
+        - summarizes [[{first_title}]]
+        - relates_to [[Project Portfolio Overview]]
+        ''',
+        folder="summaries"
+    )
+    ```
+
+    Cross-project summaries help identify broader trends and project interconnections.
     """
 
     return prompt_context + capture_suggestions

src/basic_memory/mcp/prompts/search.py

@@ -17,7 +17,7 @@ from basic_memory.schemas.prompt import SearchPromptRequest
 
 
 @mcp.prompt(
-    name="Search Knowledge Base",
+    name="search_knowledge_base",
     description="Search across all content in basic-memory",
 )
 async def search_prompt(

src/basic_memory/mcp/prompts/utils.py

@@ -103,10 +103,17 @@ def format_prompt_context(context: PromptContext) -> str:
 
                 added_permalinks.add(primary_permalink)
 
-                memory_url = normalize_memory_url(primary_permalink)
+                # Use permalink if available, otherwise use file_path
+                if primary_permalink:
+                    memory_url = normalize_memory_url(primary_permalink)
+                    read_command = f'read_note("{primary_permalink}")'
+                else:
+                    memory_url = f"file://{primary.file_path}"
+                    read_command = f'read_file("{primary.file_path}")'
+
                 section = dedent(f"""
                     --- {memory_url}
-                
+
                     ## {primary.title}
                     - **Type**: {primary.type}
                     """)
@@ -121,8 +128,8 @@ def format_prompt_context(context: PromptContext) -> str:
                         section += f"\n**Excerpt**:\n{content}\n"
 
                 section += dedent(f"""
-    
-                    You can read this document with: `read_note("{primary_permalink}")`
+
+                    You can read this document with: `{read_command}`
                     """)
                 sections.append(section)
 

src/basic_memory/mcp/resources/ai_assistant_guide.md

@@ -14,6 +14,44 @@ natural conversations. The system automatically creates a semantic knowledge gra
 - **Semantic**: Simple patterns create a structured knowledge graph
 - **Persistent**: Knowledge persists across sessions and conversations
 
+## Project Management and Configuration
+
+Basic Memory uses a **stateless architecture** where each tool call can specify which project to work with. This provides three ways to determine the active project:
+
+### Three-Tier Project Resolution
+
+1. **CLI Constraint (Highest Priority)**: When Basic Memory is started with `--project project-name`, all operations are constrained to that project
+2. **Explicit Project Parameter (Medium Priority)**: When you specify `project="project-name"` in tool calls
+3. **Default Project Mode (Lowest Priority)**: When `default_project_mode=true` in configuration, tools automatically use the configured `default_project`
+
+### Default Project Mode
+
+When `default_project_mode` is enabled in the user's configuration:
+- All tools become more convenient - no need to specify project repeatedly
+- Perfect for users who primarily work with a single project
+- Still allows explicit project specification when needed
+- Falls back gracefully to multi-project mode if no default is configured
+
+```python
+# With default_project_mode enabled, these are equivalent:
+await write_note("My Note", "Content", "folder")
+await write_note("My Note", "Content", "folder", project="default-project")
+
+# You can still override with explicit project:
+await write_note("My Note", "Content", "folder", project="other-project")
+```
+
+### Project Discovery
+
+If you're unsure which project to use:
+```python
+# Discover available projects
+projects = await list_memory_projects()
+
+# See recent activity across projects for recommendations
+activity = await recent_activity()  # Shows cross-project activity and suggestions
+```
+
 ## The Importance of the Knowledge Graph
 
 **Basic Memory's value comes from connections between notes, not just the notes themselves.**
@@ -33,49 +71,120 @@ build these connections!
 
 ## Core Tools Reference
 
+### Knowledge Creation and Editing
+
 ```python
 # Writing knowledge - THE MOST IMPORTANT TOOL!
 response = await write_note(
     title="Search Design",  # Required: Note title
     content="# Search Design\n...",  # Required: Note content
-    folder="specs",  # Optional: Folder to save in
+    folder="specs",  # Required: Folder to save in
     tags=["search", "design"],  # Optional: Tags for categorization
-    verbose=True  # Optional: Get parsing details
+    project="my-project"  # Optional: Explicit project (uses default if not specified)
 )
 
+# Editing existing notes
+await edit_note(
+    identifier="Search Design",  # Required: Note to edit
+    operation="append",  # Required: append, prepend, find_replace, replace_section
+    content="\n## New Section\nAdditional content",  # Required: Content to add/replace
+    project="my-project"  # Optional: Explicit project
+)
+
+# Moving notes
+await move_note(
+    identifier="Search Design",  # Required: Note to move
+    destination_path="archive/old-search-design.md",  # Required: New location
+    project="my-project"  # Optional: Explicit project
+)
+
+# Deleting notes
+success = await delete_note(
+    identifier="Old Draft",  # Required: Note to delete
+    project="my-project"  # Optional: Explicit project
+)
+```
+
+### Knowledge Reading and Discovery
+
+```python
 # Reading knowledge
-content = await read_note("Search Design")  # By title
+content = await read_note("Search Design")  # By title (uses default project)
 content = await read_note("specs/search-design")  # By path
 content = await read_note("memory://specs/search")  # By memory URL
+content = await read_note("Search Design", project="work-docs")  # Explicit project
 
+# Reading raw file content (text, images, binaries)
+file_data = await read_content(
+    path="assets/diagram.png",  # Required: File path
+    project="my-project"  # Optional: Explicit project
+)
+
+# Viewing notes as formatted artifacts
+await view_note(
+    identifier="Search Design",  # Required: Note to view
+    project="my-project",  # Optional: Explicit project
+    page=1,  # Optional: Pagination
+    page_size=10  # Optional: Items per page
+)
+
+# Browsing directory contents
+listing = await list_directory(
+    dir_name="/specs",  # Optional: Directory path (default: "/")
+    depth=2,  # Optional: Recursion depth
+    file_name_glob="*.md",  # Optional: File pattern filter
+    project="my-project"  # Optional: Explicit project
+)
+```
+
+### Search and Context
+
+```python
 # Searching for knowledge
 results = await search_notes(
-    query="authentication system",  # Text to search for
+    query="authentication system",  # Required: Text to search for
+    project="my-project",  # Optional: Explicit project
     page=1,  # Optional: Pagination
-    page_size=10  # Optional: Results per page
+    page_size=10,  # Optional: Results per page
+    search_type="text",  # Optional: "text", "title", or "permalink"
+    types=["entity"],  # Optional: Filter by content types
+    entity_types=["observation"],  # Optional: Filter by entity types
+    after_date="1 week"  # Optional: Recent content only
 )
 
 # Building context from the knowledge graph
 context = await build_context(
-    url="memory://specs/search",  # Starting point
+    url="memory://specs/search",  # Required: Starting point
+    project="my-project",  # Optional: Explicit project
     depth=2,  # Optional: How many hops to follow
-    timeframe="1 month"  # Optional: Recent timeframe
+    timeframe="1 month",  # Optional: Recent timeframe
+    max_related=10  # Optional: Max related items
 )
 
 # Checking recent changes
 activity = await recent_activity(
-    type="all",  # Optional: Entity types to include
+    type=["entity", "relation"],  # Optional: Entity types to include
     depth=1,  # Optional: Related items to include
-    timeframe="1 week"  # Optional: Time window
+    timeframe="1 week",  # Optional: Time window
+    project="my-project"  # Optional: Explicit project (None for cross-project discovery)
 )
+```
 
+### Visualization and Project Management
+
+```python
 # Creating a knowledge visualization
 canvas_result = await canvas(
-    nodes=[{"id": "note1", "label": "Search Design"}],  # Nodes to display
-    edges=[{"from": "note1", "to": "note2"}],  # Connections
-    title="Project Overview",  # Canvas title
-    folder="diagrams"  # Storage location
+    nodes=[{"id": "note1", "type": "file", "file": "Search Design.md"}],  # Required: Nodes
+    edges=[{"id": "edge1", "fromNode": "note1", "toNode": "note2"}],  # Required: Edges
+    title="Project Overview",  # Required: Canvas title
+    folder="diagrams",  # Required: Storage location
+    project="my-project"  # Optional: Explicit project
 )
+
+# Project management
+projects = await list_memory_projects()  # List all available projects
+project_info = await project_info(project="my-project")  # Get project statistics
 ```
 
 ## memory:// URLs Explained
@@ -135,27 +244,31 @@ 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]
+   await write_note(
+       title="Search Functionality Discussion",
+       content="# Search Functionality Discussion\n...",
+       folder="discussions"
+   )
    ```
 
 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]
+   context = await build_context(url="memory://specs/search")
+   content = await read_note("specs/search")
    ```
 
 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]
+   results = await search_notes(query="auth decisions")
+   context = await build_context(url=f"memory://{results[0].permalink}")
    ```
 
 ## Key Things to Remember
@@ -263,7 +376,7 @@ When creating relations, you can:
 # Example workflow for creating notes with effective relations
 async def create_note_with_effective_relations():
     # Search for existing entities to reference
-    search_results = await search_notes("travel")
+    search_results = await search_notes(query="travel")
     existing_entities = [result.title for result in search_results.primary_results]
 
     # Check if specific entities exist
@@ -297,7 +410,7 @@ async def create_note_with_effective_relations():
 
     # Now create the note with both verified and forward relations
     content = f"""# Tokyo Neighborhood Guide
-    
+
 ## Overview
 Details about different Tokyo neighborhoods and their unique characteristics.
 
@@ -313,7 +426,7 @@ Details about different Tokyo neighborhoods and their unique characteristics.
     result = await write_note(
         title="Tokyo Neighborhood Guide",
         content=content,
-        verbose=True
+        folder="travel"
     )
 
     # You can check which relations were resolved and which are forward references
@@ -335,7 +448,7 @@ Common issues to watch for:
        content = await read_note("Document")
    except:
        # Try search instead
-       results = await search_notes("Document")
+       results = await search_notes(query="Document")
        if results and results.primary_results:
            # Found something similar
            content = await read_note(results.primary_results[0].permalink)
@@ -343,23 +456,40 @@ Common issues to watch for:
 
 2. **Forward References (Unresolved Relations)**
    ```python
-   response = await write_note(..., verbose=True)
+   response = await write_note(
+       title="My Note",
+       content="Content with [[Forward Reference]]",
+       folder="notes"
+   )
    # Check for forward references (unresolved relations)
    forward_refs = []
    for relation in response.get('relations', []):
        if not relation.get('target_id'):
            forward_refs.append(relation.get('to_name'))
-   
+
    if forward_refs:
        # This is a feature, not an error! Inform the user about forward references
        print(f"Note created with forward references to: {forward_refs}")
        print("These will be automatically linked when those notes are created.")
-       
+
        # Optionally suggest creating those entities now
        print("Would you like me to create any of these notes now to complete the connections?")
    ```
 
-3. **Sync Issues**
+3. **Project Discovery Issues**
+   ```python
+   # If user asks about content but no default project is configured
+   try:
+       results = await search_notes(query="user query")
+   except Exception as e:
+       if "project" in str(e).lower():
+           # Show available projects and ask user to choose
+           projects = await list_memory_projects()
+           print(f"Available projects: {[p.name for p in projects]}")
+           print("Which project should I search in?")
+   ```
+
+4. **Sync Issues**
    ```python
    # If information seems outdated
    activity = await recent_activity(timeframe="1 hour")
@@ -369,14 +499,21 @@ Common issues to watch for:
 
 ## Best Practices
 
-1. **Proactively Record Context**
+1. **Smart Project Management**
+    - **For new users**: Call `recent_activity()` without project parameter to discover active projects and get recommendations
+    - **For known projects**: Use explicit project parameters when switching between multiple projects
+    - **For single-project users**: Rely on default_project_mode for convenience
+    - **When uncertain**: Use `list_memory_projects()` to show available options and ask the user
+    - **Remember choices**: Once a user indicates their preferred project, use it consistently throughout the conversation
+
+2. **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**
+3. **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
@@ -386,7 +523,7 @@ Common issues to watch for:
       of "relates_to")
     - **Consider bidirectional relations**: When appropriate, create inverse relations in both entities
 
-3. **Structure Content Thoughtfully**
+4. **Structure Content Thoughtfully**
     - Use clear, descriptive titles
     - Organize with logical sections (Context, Decision, Implementation, etc.)
     - Include relevant context and background
@@ -394,20 +531,21 @@ Common issues to watch for:
     - Use a consistent format for similar types of notes
     - Balance detail with conciseness
 
-4. **Navigate Knowledge Effectively**
-    - Start with specific searches
-    - Follow relation paths
+5. **Navigate Knowledge Effectively**
+    - Start with specific searches using `search_notes()`
+    - Follow relation paths with `build_context()`
     - Combine information from multiple sources
-    - Verify information is current
+    - Verify information is current with `recent_activity()`
     - Build a complete picture before responding
+    - Use appropriate project context for searches
 
-5. **Help Users Maintain Their Knowledge**
-    - Suggest organizing related topics
-    - Identify potential duplicates
+6. **Help Users Maintain Their Knowledge**
+    - Suggest organizing related topics across projects when appropriate
+    - Identify potential duplicates using search
     - 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?"
+    - Suggest potential missing relations: "I notice this might relate to [topic], would you like me to add that connection?"
+    - Help users decide when to use explicit vs default project parameters
 
 Built with ♥️ b
 y Basic Machines

src/basic_memory/mcp/resources/project_info.py

@@ -1,19 +1,24 @@
 """Project info tool for Basic Memory MCP server."""
 
-from loguru import logger
+from typing import Optional
+
+from loguru import logger
+from fastmcp import Context
 
-from basic_memory.mcp.project_session import get_active_project
 from basic_memory.mcp.async_client import client
+from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_get
 from basic_memory.schemas import ProjectInfoResponse
 
 
 @mcp.resource(
-    uri="memory://project_info",
+    uri="memory://{project}/info",
     description="Get information and statistics about the current Basic Memory project.",
 )
-async def project_info() -> ProjectInfoResponse:
+async def project_info(
+    project: Optional[str] = None, context: Context | None = None
+) -> ProjectInfoResponse:
     """Get comprehensive information about the current Basic Memory project.
 
     This tool provides detailed statistics and status information about your
@@ -31,13 +36,22 @@ async def project_info() -> ProjectInfoResponse:
     - Monitor growth and activity over time
     - Identify potential issues like unresolved relations
 
+    Args:
+        project: Optional project name. If not provided, uses default_project
+                (if default_project_mode=true) or CLI constraint. If unknown,
+                use list_memory_projects() to discover available projects.
+        context: Optional FastMCP context for performance caching.
+
     Returns:
         Detailed project information and statistics
 
     Examples:
-        # Get information about the current project
+        # Get information about the current/default project
         info = await project_info()
 
+        # Get information about a specific project
+        info = await project_info(project="my-project")
+
         # Check entity counts
         print(f"Total entities: {info.statistics.total_entities}")
 
@@ -45,8 +59,8 @@ async def project_info() -> ProjectInfoResponse:
         print(f"Basic Memory version: {info.system.version}")
     """
     logger.info("Getting project info")
-    project_config = get_active_project()
-    project_url = project_config.project_url
+    project_config = await get_active_project(client, project, context)
+    project_url = project_config.permalink
 
     # Call the API endpoint
     response = await call_get(client, f"{project_url}/project/info")

src/basic_memory/mcp/server.py

@@ -2,45 +2,8 @@
 Basic Memory FastMCP server.
 """
 
-import asyncio
-from contextlib import asynccontextmanager
-from dataclasses import dataclass
-from typing import AsyncIterator, Optional, Any
-
 from fastmcp import FastMCP
 
-from basic_memory.config import ConfigManager
-from basic_memory.services.initialization import initialize_app
-
-
-@dataclass
-class AppContext:
-    watch_task: Optional[asyncio.Task]
-    migration_manager: Optional[Any] = None
-
-
-@asynccontextmanager
-async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:  # pragma: no cover
-    """ """
-    # defer import so tests can monkeypatch
-    from basic_memory.mcp.project_session import session
-
-    app_config = ConfigManager().config
-    # Initialize on startup (now returns migration_manager)
-    migration_manager = await initialize_app(app_config)
-
-    # Initialize project session with default project
-    session.initialize(app_config.default_project)
-
-    try:
-        yield AppContext(watch_task=None, migration_manager=migration_manager)
-    finally:
-        # Cleanup on shutdown - migration tasks will be cancelled automatically
-        pass
-
-
-# Create the shared server instance with custom Stytch auth
 mcp = FastMCP(
     name="Basic Memory",
-    lifespan=app_lifespan,
 )

src/basic_memory/mcp/tools/__init__.py

@@ -21,13 +21,13 @@ from basic_memory.mcp.tools.move_note import move_note
 from basic_memory.mcp.tools.sync_status import sync_status
 from basic_memory.mcp.tools.project_management import (
     list_memory_projects,
-    switch_project,
-    get_current_project,
-    set_default_project,
     create_memory_project,
     delete_project,
 )
 
+# ChatGPT-compatible tools
+from basic_memory.mcp.tools.chatgpt_tools import search, fetch
+
 __all__ = [
     "build_context",
     "canvas",
@@ -35,16 +35,15 @@ __all__ = [
     "delete_note",
     "delete_project",
     "edit_note",
-    "get_current_project",
+    "fetch",
     "list_directory",
     "list_memory_projects",
     "move_note",
     "read_content",
     "read_note",
     "recent_activity",
+    "search",
     "search_notes",
-    "set_default_project",
-    "switch_project",
     "sync_status",
     "view_note",
     "write_note",

src/basic_memory/mcp/tools/build_context.py

@@ -3,11 +3,12 @@
 from typing import Optional
 
 from loguru import logger
+from fastmcp import Context
 
 from basic_memory.mcp.async_client import client
+from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_get
-from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas.base import TimeFrame
 from basic_memory.schemas.memory import (
     GraphContext,
@@ -17,18 +18,19 @@ from basic_memory.schemas.memory import (
 
 type StringOrInt = str | int
 
+
 @mcp.tool(
     description="""Build context from a memory:// URI to continue conversations naturally.
-    
+
     Use this to follow up on previous discussions or explore related topics.
-    
+
     Memory URL Format:
-    - Use paths like "folder/note" or "memory://folder/note" 
+    - Use paths like "folder/note" or "memory://folder/note"
     - Pattern matching: "folder/*" matches all notes in folder
     - Valid characters: letters, numbers, hyphens, underscores, forward slashes
     - Avoid: double slashes (//), angle brackets (<>), quotes, pipes (|)
     - Examples: "specs/search", "projects/basic-memory", "notes/*"
-    
+
     Timeframes support natural language like:
     - "2 days ago", "last week", "today", "3 months ago"
     - Or standard formats like "7d", "24h"
@@ -36,27 +38,34 @@ type StringOrInt = str | int
 )
 async def build_context(
     url: MemoryUrl,
+    project: Optional[str] = None,
     depth: Optional[StringOrInt] = 1,
     timeframe: Optional[TimeFrame] = "7d",
     page: int = 1,
     page_size: int = 10,
     max_related: int = 10,
-    project: Optional[str] = None,
+    context: Context | None = None,
 ) -> GraphContext:
-    """Get context needed to continue a discussion.
+    """Get context needed to continue a discussion within a specific project.
 
     This tool enables natural continuation of discussions by loading relevant context
     from memory:// URIs. It uses pattern matching to find relevant content and builds
     a rich context graph of related information.
 
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
+
     Args:
+        project: Project name to build context from. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
         url: memory:// URI pointing to discussion content (e.g. memory://specs/search)
         depth: How many relation hops to traverse (1-3 recommended for performance)
         timeframe: How far back to look. Supports natural language like "2 days ago", "last week"
         page: Page number of results to return (default: 1)
         page_size: Number of results to return per page (default: 10)
         max_related: Maximum number of related results to return (default: 10)
-        project: Optional project name to build context from. If not provided, uses current active project.
+        context: Optional FastMCP context for performance caching.
 
     Returns:
         GraphContext containing:
@@ -66,34 +75,35 @@ async def build_context(
 
     Examples:
         # Continue a specific discussion
-        build_context("memory://specs/search")
+        build_context("my-project", "memory://specs/search")
 
         # Get deeper context about a component
-        build_context("memory://components/memory-service", depth=2)
+        build_context("work-docs", "memory://components/memory-service", depth=2)
 
         # Look at recent changes to a specification
-        build_context("memory://specs/document-format", timeframe="today")
+        build_context("research", "memory://specs/document-format", timeframe="today")
 
         # Research the history of a feature
-        build_context("memory://features/knowledge-graph", timeframe="3 months ago")
+        build_context("dev-notes", "memory://features/knowledge-graph", timeframe="3 months ago")
 
-        # Build context from specific project
-        build_context("memory://specs/search", project="work-project")
+    Raises:
+        ToolError: If project doesn't exist or depth parameter is invalid
     """
-    logger.info(f"Building context from {url}")
-    
+    logger.info(f"Building context from {url} in project {project}")
+
     # Convert string depth to integer if needed
     if isinstance(depth, str):
         try:
             depth = int(depth)
         except ValueError:
             from mcp.server.fastmcp.exceptions import ToolError
+
             raise ToolError(f"Invalid depth parameter: '{depth}' is not a valid integer")
-    
+
     # URL is already validated and normalized by MemoryUrl type annotation
 
-    # Get the active project first to check project-specific sync status
-    active_project = get_active_project(project)
+    # Get the active project using the new stateless approach
+    active_project = await get_active_project(client, project, context)
 
     # Check migration status and wait briefly if needed
     from basic_memory.mcp.tools.utils import wait_for_migration_or_return_status

src/basic_memory/mcp/tools/canvas.py

@@ -7,11 +7,12 @@ import json
 from typing import Dict, List, Any, Optional
 
 from loguru import logger
+from fastmcp import Context
 
 from basic_memory.mcp.async_client import client
+from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_put
-from basic_memory.mcp.project_session import get_active_project
 
 
 @mcp.tool(
@@ -23,21 +24,28 @@ async def canvas(
     title: str,
     folder: str,
     project: Optional[str] = None,
+    context: Context | None = None,
 ) -> str:
     """Create an Obsidian canvas file with the provided nodes and edges.
 
     This tool creates a .canvas file compatible with Obsidian's Canvas feature,
     allowing visualization of relationships between concepts or documents.
 
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
+
     For the full JSON Canvas 1.0 specification, see the 'spec://canvas' resource.
 
     Args:
+        project: Project name to create canvas in. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
         nodes: List of node objects following JSON Canvas 1.0 spec
         edges: List of edge objects following JSON Canvas 1.0 spec
         title: The title of the canvas (will be saved as title.canvas)
         folder: Folder path relative to project root where the canvas should be saved.
                 Use forward slashes (/) as separators. Examples: "diagrams", "projects/2025", "visual/maps"
-        project: Optional project name to create canvas in. If not provided, uses current active project.
+        context: Optional FastMCP context for performance caching.
 
     Returns:
         A summary of the created canvas file
@@ -77,13 +85,16 @@ async def canvas(
     ```
 
     Examples:
-        # Create canvas in current project
-        canvas(nodes=[...], edges=[...], title="My Canvas", folder="diagrams")
+        # Create canvas in project
+        canvas("my-project", nodes=[...], edges=[...], title="My Canvas", folder="diagrams")
 
-        # Create canvas in specific project
-        canvas(nodes=[...], edges=[...], title="My Canvas", folder="diagrams", project="work-project")
+        # Create canvas in work project
+        canvas("work-project", nodes=[...], edges=[...], title="Process Flow", folder="visual/maps")
+
+    Raises:
+        ToolError: If project doesn't exist or folder path is invalid
     """
-    active_project = get_active_project(project)
+    active_project = await get_active_project(client, project, context)
     project_url = active_project.project_url
 
     # Ensure path has .canvas extension
@@ -97,7 +108,7 @@ async def canvas(
     canvas_json = json.dumps(canvas_data, indent=2)
 
     # Write the file using the resource API
-    logger.info(f"Creating canvas file: {file_path}")
+    logger.info(f"Creating canvas file: {file_path} in project {project}")
     response = await call_put(client, f"{project_url}/resource/{file_path}", json=canvas_json)
 
     # Parse response

src/basic_memory/mcp/tools/chatgpt_tools.py

@@ -0,0 +1,178 @@
+"""ChatGPT-compatible MCP tools for Basic Memory.
+
+These adapters expose Basic Memory's search/fetch functionality using the exact
+tool names and response structure OpenAI's MCP clients expect: each call returns
+a list containing a single `{"type": "text", "text": "{...json...}"}` item.
+"""
+
+import json
+from typing import Any, Dict, List, Optional
+from loguru import logger
+from fastmcp import Context
+
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.search import search_notes
+from basic_memory.mcp.tools.read_note import read_note
+from basic_memory.schemas.search import SearchResponse
+
+
+def _format_search_results_for_chatgpt(results: SearchResponse) -> List[Dict[str, Any]]:
+    """Format search results according to ChatGPT's expected schema.
+
+    Returns a list of result objects with id, title, and url fields.
+    """
+    formatted_results = []
+
+    for result in results.results:
+        formatted_result = {
+            "id": result.permalink or f"doc-{len(formatted_results)}",
+            "title": result.title if result.title and result.title.strip() else "Untitled",
+            "url": result.permalink or "",
+        }
+        formatted_results.append(formatted_result)
+
+    return formatted_results
+
+
+def _format_document_for_chatgpt(
+    content: str, identifier: str, title: Optional[str] = None
+) -> Dict[str, Any]:
+    """Format document content according to ChatGPT's expected schema.
+
+    Returns a document object with id, title, text, url, and metadata fields.
+    """
+    # Extract title from markdown content if not provided
+    if not title and isinstance(content, str):
+        lines = content.split("\n")
+        if lines and lines[0].startswith("# "):
+            title = lines[0][2:].strip()
+        else:
+            title = identifier.split("/")[-1].replace("-", " ").title()
+
+    # Ensure title is never None
+    if not title:
+        title = "Untitled Document"
+
+    # Handle error cases
+    if isinstance(content, str) and content.startswith("# Note Not Found"):
+        return {
+            "id": identifier,
+            "title": title or "Document Not Found",
+            "text": content,
+            "url": identifier,
+            "metadata": {"error": "Document not found"},
+        }
+
+    return {
+        "id": identifier,
+        "title": title or "Untitled Document",
+        "text": content,
+        "url": identifier,
+        "metadata": {"format": "markdown"},
+    }
+
+
+@mcp.tool(description="Search for content across the knowledge base")
+async def search(
+    query: str,
+    context: Context | None = None,
+) -> List[Dict[str, Any]]:
+    """ChatGPT/OpenAI MCP search adapter returning a single text content item.
+
+    Args:
+        query: Search query (full-text syntax supported by `search_notes`)
+        context: Optional FastMCP context passed through for auth/session data
+
+    Returns:
+        List with one dict: `{ "type": "text", "text": "{...JSON...}" }`
+        where the JSON body contains `results`, `total_count`, and echo of `query`.
+    """
+    logger.info(f"ChatGPT search request: query='{query}'")
+
+    try:
+        # Call underlying search_notes with sensible defaults for ChatGPT
+        results = await search_notes.fn(
+            query=query,
+            project=None,  # Let project resolution happen automatically
+            page=1,
+            page_size=10,  # Reasonable default for ChatGPT consumption
+            search_type="text",  # Default to full-text search
+            context=context,
+        )
+
+        # Handle string error responses from search_notes
+        if isinstance(results, str):
+            logger.warning(f"Search failed with error: {results[:100]}...")
+            search_results = {
+                "results": [],
+                "error": "Search failed",
+                "error_details": results[:500],  # Truncate long error messages
+            }
+        else:
+            # Format successful results for ChatGPT
+            formatted_results = _format_search_results_for_chatgpt(results)
+            search_results = {
+                "results": formatted_results,
+                "total_count": len(results.results),  # Use actual count from results
+                "query": query,
+            }
+            logger.info(f"Search completed: {len(formatted_results)} results returned")
+
+        # Return in MCP content array format as required by OpenAI
+        return [{"type": "text", "text": json.dumps(search_results, ensure_ascii=False)}]
+
+    except Exception as e:
+        logger.error(f"ChatGPT search failed for query '{query}': {e}")
+        error_results = {
+            "results": [],
+            "error": "Internal search error",
+            "error_message": str(e)[:200],
+        }
+        return [{"type": "text", "text": json.dumps(error_results, ensure_ascii=False)}]
+
+
+@mcp.tool(description="Fetch the full contents of a search result document")
+async def fetch(
+    id: str,
+    context: Context | None = None,
+) -> List[Dict[str, Any]]:
+    """ChatGPT/OpenAI MCP fetch adapter returning a single text content item.
+
+    Args:
+        id: Document identifier (permalink, title, or memory URL)
+        context: Optional FastMCP context passed through for auth/session data
+
+    Returns:
+        List with one dict: `{ "type": "text", "text": "{...JSON...}" }`
+        where the JSON body includes `id`, `title`, `text`, `url`, and metadata.
+    """
+    logger.info(f"ChatGPT fetch request: id='{id}'")
+
+    try:
+        # Call underlying read_note function
+        content = await read_note.fn(
+            identifier=id,
+            project=None,  # Let project resolution happen automatically
+            page=1,
+            page_size=10,  # Default pagination
+            context=context,
+        )
+
+        # Format the document for ChatGPT
+        document = _format_document_for_chatgpt(content, id)
+
+        logger.info(f"Fetch completed: id='{id}', content_length={len(document.get('text', ''))}")
+
+        # Return in MCP content array format as required by OpenAI
+        return [{"type": "text", "text": json.dumps(document, ensure_ascii=False)}]
+
+    except Exception as e:
+        logger.error(f"ChatGPT fetch failed for id '{id}': {e}")
+        error_document = {
+            "id": id,
+            "title": "Fetch Error",
+            "text": f"Failed to fetch document: {str(e)[:200]}",
+            "url": id,
+            "metadata": {"error": "Fetch failed"},
+        }
+        return [{"type": "text", "text": json.dumps(error_document, ensure_ascii=False)}]

src/basic_memory/mcp/tools/delete_note.py

@@ -2,15 +2,16 @@ from textwrap import dedent
 from typing import Optional
 
 from loguru import logger
+from fastmcp import Context
 
+from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.tools.utils import call_delete
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.async_client import client
-from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas import DeleteEntitiesResponse
 
 
-def _format_delete_error_response(error_message: str, identifier: str) -> str:
+def _format_delete_error_response(project: str, error_message: str, identifier: str) -> str:
     """Format helpful error responses for delete failures that guide users to successful deletions."""
 
     # Note not found errors
@@ -24,7 +25,7 @@ def _format_delete_error_response(error_message: str, identifier: str) -> str:
         return dedent(f"""
             # Delete Failed - Note Not Found
 
-            The note '{identifier}' could not be found for deletion.
+            The note '{identifier}' could not be found for deletion in {project}.
 
             ## This might mean:
             1. **Already deleted**: The note may have been deleted previously
@@ -32,21 +33,21 @@ def _format_delete_error_response(error_message: str, identifier: str) -> str:
             3. **Different project**: The note might be in a different project
 
             ## How to verify:
-            1. **Search for the note**: Use `search_notes("{search_term}")` to find it
+            1. **Search for the note**: Use `search_notes("{project}", "{search_term}")` to find it
             2. **Try different formats**:
                - If you used a permalink like "folder/note-title", try just the title: "{title_format}"
                - If you used a title, try the permalink format: "{permalink_format}"
 
             3. **Check if already deleted**: Use `list_directory("/")` to see what notes exist
-            4. **Check current project**: Use `get_current_project()` to verify you're in the right project
+            4. **List notes in project**: Use `list_directory("/")` to see what notes exist in the current project
 
             ## If the note actually exists:
             ```
             # First, find the correct identifier:
-            search_notes("{identifier}")
+            search_notes("{project}", "{identifier}")
 
             # Then delete using the correct identifier:
-            delete_note("correct-identifier-from-search")
+            delete_note("{project}", "correct-identifier-from-search")
             ```
 
             ## If you want to delete multiple similar notes:
@@ -69,12 +70,12 @@ You don't have permission to delete '{identifier}': {error_message}
 3. **Project access**: Ensure you're in the correct project with proper permissions
 
 ## Alternative actions:
-- Check current project: `get_current_project()`
-- Switch to correct project: `switch_project("project-name")`
-- Verify note exists first: `read_note("{identifier}")`
+- List available projects: `list_memory_projects()`
+- Specify the correct project: `delete_note("{identifier}", project="project-name")`
+- Verify note exists first: `read_note("{identifier}", project="project-name")`
 
 ## If you have read-only access:
-Send a message to support@basicmachines.co to request deletion, or ask someone with write access to delete the note."""
+Ask someone with write access to delete the note."""
 
     # Server/filesystem errors
     if (
@@ -92,8 +93,7 @@ A system error occurred while deleting '{identifier}': {error_message}
 3. **Check disk space**: Ensure the system has adequate storage
 
 ## Troubleshooting:
-- Verify note exists: `read_note("{identifier}")`
-- Check project status: `get_current_project()`
+- Verify note exists: `read_note("{project}","{identifier}")`
 - Try again in a few moments
 
 ## If problem persists:
@@ -112,7 +112,7 @@ A database error occurred while deleting '{identifier}': {error_message}
 
 ## Steps to resolve:
 1. **Try again**: Wait a moment and retry the deletion
-2. **Check note status**: `read_note("{identifier}")` to see current state
+2. **Check note status**: `read_note("{project}","{identifier}")` to see current state
 3. **Manual verification**: Use `list_directory()` to see if file still exists
 
 ## If the note appears gone but database shows it exists:
@@ -124,7 +124,7 @@ Send a message to support@basicmachines.co - a manual database cleanup may be ne
 Error deleting note '{identifier}': {error_message}
 
 ## General troubleshooting:
-1. **Verify the note exists**: `read_note("{identifier}")` or `search_notes("{identifier}")`
+1. **Verify the note exists**: `read_note("{project}", "{identifier}")` or `search_notes("{project}", "{identifier}")`
 2. **Check permissions**: Ensure you can edit/delete files in this project
 3. **Try again**: The error might be temporary
 4. **Check project**: Make sure you're in the correct project
@@ -132,46 +132,77 @@ Error deleting note '{identifier}': {error_message}
 ## Step-by-step approach:
 ```
 # 1. Confirm note exists and get correct identifier
-search_notes("{identifier}")
+search_notes("{project}", "{identifier}")
 
 # 2. Read the note to verify access
-read_note("correct-identifier-from-search")
+read_note("{project}", "correct-identifier-from-search")
 
 # 3. Try deletion with correct identifier
-delete_note("correct-identifier-from-search")
+delete_note("{project}", "correct-identifier-from-search")
 ```
 
 ## Alternative approaches:
-- Check what notes exist: `list_directory("/")`
-- Verify current project: `get_current_project()`
-- Switch projects if needed: `switch_project("correct-project")`
+- Check what notes exist: `list_directory("{project}", "/")`
 
 ## Need help?
-If the note should be deleted but the operation keeps failing, send a message to support@basicmachines.co."""
+If the note should be deleted but the operation keeps failing, send a message to support@basicmemory.com."""
 
 
 @mcp.tool(description="Delete a note by title or permalink")
-async def delete_note(identifier: str, project: Optional[str] = None) -> bool | str:
+async def delete_note(
+    identifier: str, project: Optional[str] = None, context: Context | None = None
+) -> bool | str:
     """Delete a note from the knowledge base.
 
+    Permanently removes a note from the specified project. The note is identified
+    by title or permalink. If the note doesn't exist, the operation returns False
+    without error. If deletion fails due to other issues, helpful error messages are provided.
+
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
+
     Args:
-        identifier: Note title or permalink
-        project: Optional project name to delete from. If not provided, uses current active project.
+        project: Project name to delete from. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
+        identifier: Note title or permalink to delete
+                   Can be a title like "Meeting Notes" or permalink like "notes/meeting-notes"
+        context: Optional FastMCP context for performance caching.
 
     Returns:
-        True if note was deleted, False otherwise
+        True if note was successfully deleted, False if note was not found.
+        On errors, returns a formatted string with helpful troubleshooting guidance.
 
     Examples:
         # Delete by title
-        delete_note("Meeting Notes: Project Planning")
+        delete_note("my-project", "Meeting Notes: Project Planning")
 
         # Delete by permalink
-        delete_note("notes/project-planning")
+        delete_note("work-docs", "notes/project-planning")
 
-        # Delete from specific project
-        delete_note("notes/project-planning", project="work-project")
+        # Delete with exact path
+        delete_note("research", "experiments/ml-model-results")
+
+        # Common usage pattern
+        if delete_note("my-project", "old-draft"):
+            print("Note deleted successfully")
+        else:
+            print("Note not found or already deleted")
+
+    Raises:
+        HTTPError: If project doesn't exist or is inaccessible
+        SecurityError: If identifier attempts path traversal
+
+    Warning:
+        This operation is permanent and cannot be undone. The note file
+        will be removed from the filesystem and all references will be lost.
+
+    Note:
+        If the note is not found, this function provides helpful error messages
+        with suggestions for finding the correct identifier, including search
+        commands and alternative formats to try.
     """
-    active_project = get_active_project(project)
+    active_project = await get_active_project(client, project, context)
     project_url = active_project.project_url
 
     try:
@@ -179,13 +210,15 @@ async def delete_note(identifier: str, project: Optional[str] = None) -> bool |
         result = DeleteEntitiesResponse.model_validate(response.json())
 
         if result.deleted:
-            logger.info(f"Successfully deleted note: {identifier}")
+            logger.info(
+                f"Successfully deleted note: {identifier} in project: {active_project.name}"
+            )
             return True
         else:
             logger.warning(f"Delete operation completed but note was not deleted: {identifier}")
             return False
 
     except Exception as e:  # pragma: no cover
-        logger.error(f"Delete failed for '{identifier}': {e}")
+        logger.error(f"Delete failed for '{identifier}': {e}, project: {active_project.name}")
         # Return formatted error message for better user experience
-        return _format_delete_error_response(str(e), identifier)
+        return _format_delete_error_response(active_project.name, str(e), identifier)

src/basic_memory/mcp/tools/edit_note.py

@@ -3,9 +3,10 @@
 from typing import Optional
 
 from loguru import logger
+from fastmcp import Context
 
 from basic_memory.mcp.async_client import client
-from basic_memory.mcp.project_session import get_active_project
+from basic_memory.mcp.project_context import get_active_project, add_project_metadata
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_patch
 from basic_memory.schemas import EntityResponse
@@ -17,6 +18,7 @@ def _format_error_response(
     identifier: str,
     find_text: Optional[str] = None,
     expected_replacements: int = 1,
+    project: Optional[str] = None,
 ) -> str:
     """Format helpful error responses for edit_note failures that guide the AI to retry successfully."""
 
@@ -27,14 +29,14 @@ def _format_error_response(
 The note with identifier '{identifier}' could not be found. Edit operations require an exact match (no fuzzy matching).
 
 ## Suggestions to try:
-1. **Search for the note first**: Use `search_notes("{identifier.split("/")[-1]}")` to find similar notes with exact identifiers
+1. **Search for the note first**: Use `search_notes("{project or "project-name"}", "{identifier.split("/")[-1]}")` to find similar notes with exact identifiers
 2. **Try different exact identifier formats**:
    - If you used a permalink like "folder/note-title", try the exact title: "{identifier.split("/")[-1].replace("-", " ").title()}"
    - If you used a title, try the exact permalink format: "{identifier.lower().replace(" ", "-")}"
-   - Use `read_note()` first to verify the note exists and get the exact identifier
+   - Use `read_note("{project or "project-name"}", "{identifier}")` first to verify the note exists and get the exact identifier
 
 ## Alternative approach:
-Use `write_note()` to create the note first, then edit it."""
+Use `write_note("{project or "project-name"}", "title", "content", "folder")` to create the note first, then edit it."""
 
     # Find/replace specific errors
     if operation == "find_replace":
@@ -44,7 +46,7 @@ Use `write_note()` to create the note first, then edit it."""
 The text '{find_text}' was not found in the note '{identifier}'.
 
 ## Suggestions to try:
-1. **Read the note first**: Use `read_note("{identifier}")` to see the current content
+1. **Read the note first**: Use `read_note("{project or "project-name"}", "{identifier}")` to see the current content
 2. **Check for exact matches**: The search is case-sensitive and must match exactly
 3. **Try a broader search**: Search for just part of the text you want to replace
 4. **Use expected_replacements=0**: If you want to verify the text doesn't exist
@@ -65,13 +67,13 @@ The text '{find_text}' was not found in the note '{identifier}'.
 Expected {expected_replacements} occurrences of '{find_text}' but found {actual_count}.
 
 ## How to fix:
-1. **Read the note first**: Use `read_note("{identifier}")` to see how many times '{find_text}' appears
+1. **Read the note first**: Use `read_note("{project or "project-name"}", "{identifier}")` to see how many times '{find_text}' appears
 2. **Update expected_replacements**: Set expected_replacements={actual_count} in your edit_note call
 3. **Be more specific**: If you only want to replace some occurrences, make your find_text more specific
 
 ## Example:
 ```
-edit_note("{identifier}", "find_replace", "new_text", find_text="{find_text}", expected_replacements={actual_count})
+edit_note("{project or "project-name"}", "{identifier}", "find_replace", "new_text", find_text="{find_text}", expected_replacements={actual_count})
 ```"""
 
     # Section replacement errors
@@ -81,7 +83,7 @@ edit_note("{identifier}", "find_replace", "new_text", find_text="{find_text}", e
 Multiple sections found with the same header in note '{identifier}'.
 
 ## How to fix:
-1. **Read the note first**: Use `read_note("{identifier}")` to see the document structure
+1. **Read the note first**: Use `read_note("{project or "project-name"}", "{identifier}")` to see the document structure
 2. **Make headers unique**: Add more specific text to distinguish sections
 3. **Use append instead**: Add content at the end rather than replacing a specific section
 
@@ -97,14 +99,14 @@ Use `find_replace` to update specific text within the duplicate sections."""
 There was a problem with the edit request to note '{identifier}': {error_message}.
 
 ## Common causes and fixes:
-1. **Note doesn't exist**: Use `search_notes()` or `read_note()` to verify the note exists
+1. **Note doesn't exist**: Use `search_notes("{project or "project-name"}", "query")` or `read_note("{project or "project-name"}", "{identifier}")` to verify the note exists
 2. **Invalid identifier format**: Try different identifier formats (title vs permalink)
 3. **Empty or invalid content**: Check that your content is properly formatted
 4. **Server error**: Try the operation again, or use `read_note()` first to verify the note state
 
 ## Troubleshooting steps:
-1. Verify the note exists: `read_note("{identifier}")`
-2. If not found, search for it: `search_notes("{identifier.split("/")[-1]}")`
+1. Verify the note exists: `read_note("{project or "project-name"}", "{identifier}")`
+2. If not found, search for it: `search_notes("{project or "project-name"}", "{identifier.split("/")[-1]}")`
 3. Try again with the correct identifier from the search results"""
 
     # Fallback for other errors
@@ -113,14 +115,14 @@ There was a problem with the edit request to note '{identifier}': {error_message
 Error editing note '{identifier}': {error_message}
 
 ## General troubleshooting:
-1. **Verify the note exists**: Use `read_note("{identifier}")` to check
+1. **Verify the note exists**: Use `read_note("{project or "project-name"}", "{identifier}")` to check
 2. **Check your parameters**: Ensure all required parameters are provided correctly
-3. **Read the note content first**: Use `read_note()` to understand the current structure
+3. **Read the note content first**: Use `read_note("{project or "project-name"}", "{identifier}")` to understand the current structure
 4. **Try a simpler operation**: Start with `append` if other operations fail
 
 ## Need help?
-- Use `search_notes()` to find notes
-- Use `read_note()` to examine content before editing
+- Use `search_notes("{project or "project-name"}", "query")` to find notes
+- Use `read_note("{project or "project-name"}", "identifier")` to examine content before editing
 - Check that identifiers, section headers, and find_text match exactly"""
 
 
@@ -131,15 +133,19 @@ async def edit_note(
     identifier: str,
     operation: str,
     content: str,
+    project: Optional[str] = None,
     section: Optional[str] = None,
     find_text: Optional[str] = None,
     expected_replacements: int = 1,
-    project: Optional[str] = None,
+    context: Context | None = None,
 ) -> str:
     """Edit an existing markdown note in the knowledge base.
 
-    This tool allows you to make targeted changes to existing notes without rewriting the entire content.
-    It supports various operations for different editing scenarios.
+    Makes targeted changes to existing notes without rewriting the entire content.
+
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
 
     Args:
         identifier: The exact title, permalink, or memory:// URL of the note to edit.
@@ -151,56 +157,64 @@ async def edit_note(
                   - "find_replace": Replace occurrences of find_text with content
                   - "replace_section": Replace content under a specific markdown header
         content: The content to add or use for replacement
+        project: Project name to edit in. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
         section: For replace_section operation - the markdown header to replace content under (e.g., "## Notes", "### Implementation")
         find_text: For find_replace operation - the text to find and replace
         expected_replacements: For find_replace operation - the expected number of replacements (validation will fail if actual doesn't match)
-        project: Optional project name to delete from. If not provided, uses current active project.
+        context: Optional FastMCP context for performance caching.
 
     Returns:
-        A markdown formatted summary of the edit operation and resulting semantic content
+        A markdown formatted summary of the edit operation and resulting semantic content,
+        including operation details, file path, observations, relations, and project metadata.
 
     Examples:
         # Add new content to end of note
-        edit_note("project-planning", "append", "\\n## New Requirements\\n- Feature X\\n- Feature Y")
+        edit_note("my-project", "project-planning", "append", "\\n## New Requirements\\n- Feature X\\n- Feature Y")
 
         # Add timestamp at beginning (frontmatter-aware)
-        edit_note("meeting-notes", "prepend", "## 2025-05-25 Update\\n- Progress update...\\n\\n")
+        edit_note("work-docs", "meeting-notes", "prepend", "## 2025-05-25 Update\\n- Progress update...\\n\\n")
 
         # Update version number (single occurrence)
-        edit_note("config-spec", "find_replace", "v0.13.0", find_text="v0.12.0")
+        edit_note("api-project", "config-spec", "find_replace", "v0.13.0", find_text="v0.12.0")
 
         # Update version in multiple places with validation
-        edit_note("api-docs", "find_replace", "v2.1.0", find_text="v2.0.0", expected_replacements=3)
+        edit_note("docs-project", "api-docs", "find_replace", "v2.1.0", find_text="v2.0.0", expected_replacements=3)
 
         # Replace text that appears multiple times - validate count first
-        edit_note("docs/guide", "find_replace", "new-api", find_text="old-api", expected_replacements=5)
+        edit_note("team-docs", "docs/guide", "find_replace", "new-api", find_text="old-api", expected_replacements=5)
 
         # Replace implementation section
-        edit_note("api-spec", "replace_section", "New implementation approach...\\n", section="## Implementation")
+        edit_note("specs", "api-spec", "replace_section", "New implementation approach...\\n", section="## Implementation")
 
         # Replace subsection with more specific header
-        edit_note("docs/setup", "replace_section", "Updated install steps\\n", section="### Installation")
+        edit_note("docs", "docs/setup", "replace_section", "Updated install steps\\n", section="### Installation")
 
         # Using different identifier formats (must be exact matches)
-        edit_note("Meeting Notes", "append", "\\n- Follow up on action items")  # exact title
-        edit_note("docs/meeting-notes", "append", "\\n- Follow up tasks")       # exact permalink
-        edit_note("docs/Meeting Notes", "append", "\\n- Next steps")           # exact folder/title
+        edit_note("work-project", "Meeting Notes", "append", "\\n- Follow up on action items")  # exact title
+        edit_note("work-project", "docs/meeting-notes", "append", "\\n- Follow up tasks")       # exact permalink
 
         # If uncertain about identifier, search first:
-        # search_notes("meeting")  # Find available notes
-        # edit_note("docs/meeting-notes-2025", "append", "content")  # Use exact result
+        # search_notes("work-project", "meeting")  # Find available notes
+        # edit_note("work-project", "docs/meeting-notes-2025", "append", "content")  # Use exact result
 
         # Add new section to document
-        edit_note("project-plan", "replace_section", "TBD - needs research\\n", section="## Future Work")
+        edit_note("planning", "project-plan", "replace_section", "TBD - needs research\\n", section="## Future Work")
 
         # Update status across document (expecting exactly 2 occurrences)
-        edit_note("status-report", "find_replace", "In Progress", find_text="Not Started", expected_replacements=2)
+        edit_note("reports", "status-report", "find_replace", "In Progress", find_text="Not Started", expected_replacements=2)
 
-        # Replace text in a file, specifying project name
-        edit_note("docs/guide", "find_replace", "new-api", find_text="old-api", project="my-project"))
+    Raises:
+        HTTPError: If project doesn't exist or is inaccessible
+        ValueError: If operation is invalid or required parameters are missing
+        SecurityError: If identifier attempts path traversal
 
+    Note:
+        Edit operations require exact identifier matches. If unsure, use read_note() or
+        search_notes() first to find the correct identifier. The tool provides detailed
+        error messages with suggestions if operations fail.
     """
-    active_project = get_active_project(project)
+    active_project = await get_active_project(client, project, context)
     project_url = active_project.project_url
 
     logger.info("MCP tool call", tool="edit_note", identifier=identifier, operation=operation)
@@ -288,16 +302,18 @@ async def edit_note(
             "MCP tool response",
             tool="edit_note",
             operation=operation,
+            project=active_project.name,
             permalink=result.permalink,
             observations_count=len(result.observations),
             relations_count=len(result.relations),
             status_code=response.status_code,
         )
 
-        return "\n".join(summary)
+        result = "\n".join(summary)
+        return add_project_metadata(result, active_project.name)
 
     except Exception as e:
         logger.error(f"Error editing note: {e}")
         return _format_error_response(
-            str(e), operation, identifier, find_text, expected_replacements
+            str(e), operation, identifier, find_text, expected_replacements, active_project.name
         )

src/basic_memory/mcp/tools/headers.py

@@ -0,0 +1,44 @@
+from httpx._types import (
+    HeaderTypes,
+)
+from loguru import logger
+from fastmcp.server.dependencies import get_http_headers
+
+
+def inject_auth_header(headers: HeaderTypes | None = None) -> HeaderTypes:
+    """
+    Inject JWT token from FastMCP context into headers if available.
+
+    Args:
+        headers: Existing headers dict or None
+
+    Returns:
+        Headers dict with Authorization header added if JWT is available
+    """
+    # Start with existing headers or empty dict
+    if headers is None:
+        headers = {}
+    elif not isinstance(headers, dict):
+        # Convert other header types to dict
+        headers = dict(headers)  # type: ignore
+    else:
+        # Make a copy to avoid modifying the original
+        headers = headers.copy()
+
+    http_headers = get_http_headers()
+
+    # Log only non-sensitive header keys for debugging
+    if logger.opt(lazy=True).debug:
+        sensitive_headers = {"authorization", "cookie", "x-api-key", "x-auth-token", "api-key"}
+        safe_headers = {k for k in http_headers.keys() if k.lower() not in sensitive_headers}
+        logger.debug(f"HTTP headers present: {list(safe_headers)}")
+
+    authorization = http_headers.get("Authorization") or http_headers.get("authorization")
+    if authorization:
+        headers["Authorization"] = authorization  # type: ignore
+        # Log only that auth was injected, not the token value
+        logger.debug("Injected authorization header into request")
+    else:
+        logger.debug("No authorization header found in request")
+
+    return headers

src/basic_memory/mcp/tools/list_directory.py

@@ -3,9 +3,10 @@
 from typing import Optional
 
 from loguru import logger
+from fastmcp import Context
 
 from basic_memory.mcp.async_client import client
-from basic_memory.mcp.project_session import get_active_project
+from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_get
 
@@ -18,6 +19,7 @@ async def list_directory(
     depth: int = 1,
     file_name_glob: Optional[str] = None,
     project: Optional[str] = None,
+    context: Context | None = None,
 ) -> str:
     """List directory contents from the knowledge base with optional filtering.
 
@@ -32,7 +34,10 @@ async def list_directory(
                Higher values show subdirectory contents recursively
         file_name_glob: Optional glob pattern for filtering file names
                        Examples: "*.md", "*meeting*", "project_*"
-        project: Optional project name to delete from. If not provided, uses current active project.
+        project: Project name to list directory from. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
+        context: Optional FastMCP context for performance caching.
+
     Returns:
         Formatted listing of directory contents with file metadata
 
@@ -43,8 +48,8 @@ async def list_directory(
         # List specific folder
         list_directory(dir_name="/projects")
 
-        # Find all Python files
-        list_directory(file_name_glob="*.py")
+        # Find all markdown files
+        list_directory(file_name_glob="*.md")
 
         # Deep exploration of research folder
         list_directory(dir_name="/research", depth=3)
@@ -52,10 +57,13 @@ async def list_directory(
         # Find meeting notes in projects folder
         list_directory(dir_name="/projects", file_name_glob="*meeting*")
 
-        # Find meeting notes in a specific project
-        list_directory(dir_name="/projects", file_name_glob="*meeting*", project="work-project")
+        # Explicit project specification
+        list_directory(project="work-docs", dir_name="/projects")
+
+    Raises:
+        ToolError: If project doesn't exist or directory path is invalid
     """
-    active_project = get_active_project(project)
+    active_project = await get_active_project(client, project, context)
     project_url = active_project.project_url
 
     # Prepare query parameters
@@ -66,7 +74,9 @@ async def list_directory(
     if file_name_glob:
         params["file_name_glob"] = file_name_glob
 
-    logger.debug(f"Listing directory '{dir_name}' with depth={depth}, glob='{file_name_glob}'")
+    logger.debug(
+        f"Listing directory '{dir_name}' in project {project} with depth={depth}, glob='{file_name_glob}'"
+    )
 
     # Call the API endpoint
     response = await call_get(

src/basic_memory/mcp/tools/move_note.py

@@ -4,11 +4,12 @@ from textwrap import dedent
 from typing import Optional
 
 from loguru import logger
+from fastmcp import Context
 
 from basic_memory.mcp.async_client import client
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_post, call_get
-from basic_memory.mcp.project_session import get_active_project
+from basic_memory.mcp.project_context import get_active_project
 from basic_memory.schemas import EntityResponse
 from basic_memory.schemas.project_info import ProjectList
 from basic_memory.utils import validate_project_path
@@ -64,42 +65,37 @@ def _format_cross_project_error_response(
     """Format error response for detected cross-project move attempts."""
     return dedent(f"""
         # Move Failed - Cross-Project Move Not Supported
-        
+
         Cannot move '{identifier}' to '{destination_path}' because it appears to reference a different project ('{target_project}').
-        
+
         **Current project:** {current_project}
         **Target project:** {target_project}
-        
+
         ## Cross-project moves are not supported directly
-        
+
         Notes can only be moved within the same project. To move content between projects, use this workflow:
-        
+
         ### Recommended approach:
         ```
         # 1. Read the note content from current project
         read_note("{identifier}")
         
-        # 2. Switch to the target project
-        switch_project("{target_project}")
+        # 2. Create the note in the target project
+        write_note("Note Title", "content from step 1", "target-folder", project="{target_project}")
+
+        # 3. Delete the original note if desired
+        delete_note("{identifier}", project="{current_project}")
         
-        # 3. Create the note in the target project
-        write_note("Note Title", "content from step 1", "target-folder")
-        
-        # 4. Switch back to original project (optional)
-        switch_project("{current_project}")
-        
-        # 5. Delete the original note if desired
-        delete_note("{identifier}")
         ```
-        
+
         ### Alternative: Stay in current project
         If you want to move the note within the **{current_project}** project only:
         ```
         move_note("{identifier}", "new-folder/new-name.md")
         ```
-        
+
         ## Available projects:
-        Use `list_projects()` to see all available projects and `switch_project("project-name")` to change projects.
+        Use `list_memory_projects()` to see all available projects.
         """).strip()
 
 
@@ -130,20 +126,16 @@ def _format_potential_cross_project_guidance(
         # 1. Read the content
         read_note("{identifier}")
         
-        # 2. Switch to target project
-        switch_project("target-project-name")
-        
-        # 3. Create note in target project
-        write_note("Title", "content", "folder")
-        
-        # 4. Switch back and delete original if desired
-        switch_project("{current_project}")
-        delete_note("{identifier}")
+        # 2. Create note in target project
+        write_note("Title", "content", "folder", project="target-project-name")
+
+        # 3. Delete original if desired
+        delete_note("{identifier}", project="{current_project}")
         ```
         
         ### To see all projects:
         ```
-        list_projects()
+        list_memory_projects()
         ```
         """).strip()
 
@@ -171,7 +163,7 @@ def _format_move_error_response(error_message: str, identifier: str, destination
                - If you used a title, try the exact permalink format: "{permalink_format}"
                - Use `read_note()` first to verify the note exists and get the exact identifier
 
-            3. **Check current project**: Use `get_current_project()` to verify you're in the right project
+            3. **List available notes**: Use `list_directory("/")` to see what notes exist in the current project
             4. **List available notes**: Use `list_directory("/")` to see what notes exist
 
             ## Before trying again:
@@ -248,9 +240,8 @@ You don't have permission to move '{identifier}': {error_message}
 3. **Check file locks**: The file might be open in another application
 
 ## Alternative actions:
-- Check current project: `get_current_project()`
-- Switch projects if needed: `switch_project("project-name")`
-- Try copying content instead: `read_note("{identifier}")` then `write_note()` to new location"""
+- List available projects: `list_memory_projects()`
+- Try copying content instead: `read_note("{identifier}", project="project-name")` then `write_note()` to new location"""
 
     # Source file not found errors
     if "source" in error_message.lower() and (
@@ -352,18 +343,25 @@ async def move_note(
     identifier: str,
     destination_path: str,
     project: Optional[str] = None,
+    context: Context | None = None,
 ) -> str:
     """Move a note to a new file location within the same project.
 
+    Moves a note from one location to another within the project, updating all
+    database references and maintaining semantic content. Uses stateless architecture -
+    project parameter optional with server resolution.
+
     Args:
         identifier: Exact entity identifier (title, permalink, or memory:// URL).
                    Must be an exact match - fuzzy matching is not supported for move operations.
                    Use search_notes() or read_note() first to find the correct identifier if uncertain.
         destination_path: New path relative to project root (e.g., "work/meetings/2025-05-26.md")
-        project: Optional project name (defaults to current session project)
+        project: Project name to move within. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
+        context: Optional FastMCP context for performance caching.
 
     Returns:
-        Success message with move details
+        Success message with move details and project information.
 
     Examples:
         # Move to new folder (exact title match)
@@ -372,15 +370,22 @@ async def move_note(
         # Move by exact permalink
         move_note("my-note-permalink", "archive/old-notes/my-note.md")
 
-        # Specify project with exact identifier
-        move_note("My Note", "archive/my-note.md", project="work-project")
+        # Move with complex path structure
+        move_note("experiments/ml-results", "archive/2025/ml-experiments.md")
+
+        # Explicit project specification
+        move_note("My Note", "work/notes/my-note.md", project="work-project")
 
         # If uncertain about identifier, search first:
         # search_notes("my note")  # Find available notes
         # move_note("docs/my-note-2025", "archive/my-note.md")  # Use exact result
 
-    Note: This operation moves notes within the specified project only. Moving notes
-    between different projects is not currently supported.
+    Raises:
+        ToolError: If project doesn't exist, identifier is not found, or destination_path is invalid
+
+    Note:
+        This operation moves notes within the specified project only. Moving notes
+        between different projects is not currently supported.
 
     The move operation:
     - Updates the entity's file_path in the database
@@ -389,9 +394,9 @@ async def move_note(
     - Re-indexes the entity for search
     - Maintains all observations and relations
     """
-    logger.debug(f"Moving note: {identifier} to {destination_path}")
+    logger.debug(f"Moving note: {identifier} to {destination_path} in project: {project}")
 
-    active_project = get_active_project(project)
+    active_project = await get_active_project(client, project, context)
     project_url = active_project.project_url
 
     # Validate destination path to prevent path traversal attacks
@@ -424,6 +429,79 @@ move_note("{identifier}", "notes/{destination_path.split("/")[-1] if "/" in dest
         logger.info(f"Detected cross-project move attempt: {identifier} -> {destination_path}")
         return cross_project_error
 
+    # Get the source entity information for extension validation
+    source_ext = "md"  # Default to .md if we can't determine source extension
+    try:
+        # Fetch source entity information to get the current file extension
+        url = f"{project_url}/knowledge/entities/{identifier}"
+        response = await call_get(client, url)
+        source_entity = EntityResponse.model_validate(response.json())
+        if "." in source_entity.file_path:
+            source_ext = source_entity.file_path.split(".")[-1]
+    except Exception as e:
+        # If we can't fetch the source entity, default to .md extension
+        logger.debug(f"Could not fetch source entity for extension check: {e}")
+
+    # Validate that destination path includes a file extension
+    if "." not in destination_path or not destination_path.split(".")[-1]:
+        logger.warning(f"Move failed - no file extension provided: {destination_path}")
+        return dedent(f"""
+            # Move Failed - File Extension Required
+
+            The destination path '{destination_path}' must include a file extension (e.g., '.md').
+
+            ## Valid examples:
+            - `notes/my-note.md`
+            - `projects/meeting-2025.txt`
+            - `archive/old-program.sh`
+
+            ## Try again with extension:
+            ```
+            move_note("{identifier}", "{destination_path}.{source_ext}")
+            ```
+
+            All examples in Basic Memory expect file extensions to be explicitly provided.
+            """).strip()
+
+    # Get the source entity to check its file extension
+    try:
+        # Fetch source entity information
+        url = f"{project_url}/knowledge/entities/{identifier}"
+        response = await call_get(client, url)
+        source_entity = EntityResponse.model_validate(response.json())
+
+        # Extract file extensions
+        source_ext = (
+            source_entity.file_path.split(".")[-1] if "." in source_entity.file_path else ""
+        )
+        dest_ext = destination_path.split(".")[-1] if "." in destination_path else ""
+
+        # Check if extensions match
+        if source_ext and dest_ext and source_ext.lower() != dest_ext.lower():
+            logger.warning(
+                f"Move failed - file extension mismatch: source={source_ext}, dest={dest_ext}"
+            )
+            return dedent(f"""
+                # Move Failed - File Extension Mismatch
+
+                The destination file extension '.{dest_ext}' does not match the source file extension '.{source_ext}'.
+
+                To preserve file type consistency, the destination must have the same extension as the source.
+
+                ## Source file:
+                - Path: `{source_entity.file_path}`
+                - Extension: `.{source_ext}`
+
+                ## Try again with matching extension:
+                ```
+                move_note("{identifier}", "{destination_path.rsplit(".", 1)[0]}.{source_ext}")
+                ```
+                """).strip()
+    except Exception as e:
+        # If we can't fetch the source entity, log it but continue
+        # This might happen if the identifier is not yet resolved
+        logger.debug(f"Could not fetch source entity for extension check: {e}")
+
     try:
         # Prepare move request
         move_data = {

src/basic_memory/mcp/tools/project_management.py

@@ -4,242 +4,75 @@ These tools allow users to switch between projects, list available projects,
 and manage project context during conversations.
 """
 
-from textwrap import dedent
-from typing import Optional
-
+import os
 from fastmcp import Context
-from loguru import logger
 
 from basic_memory.mcp.async_client import client
-from basic_memory.mcp.project_session import session, add_project_metadata
 from basic_memory.mcp.server import mcp
-from basic_memory.mcp.tools.utils import call_get, call_put, call_post, call_delete
-from basic_memory.schemas import ProjectInfoResponse
-from basic_memory.schemas.project_info import ProjectList, ProjectStatusResponse, ProjectInfoRequest
+from basic_memory.mcp.tools.utils import call_get, call_post, call_delete
+from basic_memory.schemas.project_info import (
+    ProjectList,
+    ProjectStatusResponse,
+    ProjectInfoRequest,
+)
 from basic_memory.utils import generate_permalink
 
 
 @mcp.tool("list_memory_projects")
-async def list_memory_projects(
-    ctx: Context | None = None, _compatibility: Optional[str] = None
-) -> str:
+async def list_memory_projects(context: Context | None = None) -> str:
     """List all available projects with their status.
 
-    Shows all Basic Memory projects that are available, indicating which one
-    is currently active and which is the default.
+    Shows all Basic Memory projects that are available for MCP operations.
+    Use this tool to discover projects when you need to know which project to use.
+
+    Use this tool:
+    - At conversation start when project is unknown
+    - When user asks about available projects
+    - Before any operation requiring a project
+
+    After calling:
+    - Ask user which project to use
+    - Remember their choice for the session
 
     Returns:
-        Formatted list of projects with status indicators
+        Formatted list of projects with session management guidance
 
     Example:
         list_memory_projects()
     """
-    if ctx:  # pragma: no cover
-        await ctx.info("Listing all available projects")
+    if context:  # pragma: no cover
+        await context.info("Listing all available projects")
+
+    # Check if server is constrained to a specific project
+    constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
 
     # Get projects from API
     response = await call_get(client, "/projects/projects")
     project_list = ProjectList.model_validate(response.json())
 
-    current = session.get_current_project()
+    if constrained_project:
+        result = f"Project: {constrained_project}\n\n"
+        result += "Note: This MCP server is constrained to a single project.\n"
+        result += "All operations will automatically use this project."
+    else:
+        # Show all projects with session guidance
+        result = "Available projects:\n"
 
-    result = "Available projects:\n"
-
-    for project in project_list.projects:
-        indicators = []
-        if project.name == current:
-            indicators.append("current")
-        if project.is_default:
-            indicators.append("default")
-
-        if indicators:
-            result += f"• {project.name} ({', '.join(indicators)})\n"
-        else:
+        for project in project_list.projects:
             result += f"• {project.name}\n"
 
-    return add_project_metadata(result, current)
+        result += "\n" + "─" * 40 + "\n"
+        result += "Next: Ask which project to use for this session.\n"
+        result += "Example: 'Which project should I use for this task?'\n\n"
+        result += "Session reminder: Track the selected project for all subsequent operations in this conversation.\n"
+        result += "The user can say 'switch to [project]' to change projects."
 
-
-@mcp.tool()
-async def switch_project(project_name: str, ctx: Context | None = None) -> str:
-    """Switch to a different project context.
-
-    Changes the active project context for all subsequent tool calls.
-    Shows a project summary after switching successfully.
-
-    Args:
-        project_name: Name of the project to switch to
-
-    Returns:
-        Confirmation message with project summary
-
-    Example:
-        switch_project("work-notes")
-        switch_project("personal-journal")
-    """
-    if ctx:  # pragma: no cover
-        await ctx.info(f"Switching to project: {project_name}")
-
-    project_permalink = generate_permalink(project_name)
-    current_project = session.get_current_project()
-    try:
-        # Validate project exists by getting project list
-        response = await call_get(client, "/projects/projects")
-        project_list = ProjectList.model_validate(response.json())
-
-        # Find the project by name (case-insensitive) or permalink
-        target_project = None
-        for p in project_list.projects:
-            # Match by permalink (handles case-insensitive input)
-            if p.permalink == project_permalink:
-                target_project = p
-                break
-            # Also match by name comparison (case-insensitive)
-            if p.name.lower() == project_name.lower():
-                target_project = p
-                break
-
-        if not target_project:
-            available_projects = [p.name for p in project_list.projects]
-            return f"Error: Project '{project_name}' not found. Available projects: {', '.join(available_projects)}"
-
-        # Switch to the project using the canonical name from database
-        canonical_name = target_project.name
-        session.set_current_project(canonical_name)
-        current_project = session.get_current_project()
-
-        # Get project info to show summary
-        try:
-            current_project_permalink = generate_permalink(canonical_name)
-            response = await call_get(
-                client,
-                f"/{current_project_permalink}/project/info",
-                params={"project_name": canonical_name},
-            )
-            project_info = ProjectInfoResponse.model_validate(response.json())
-
-            result = f"✓ Switched to {canonical_name} project\n\n"
-            result += "Project Summary:\n"
-            result += f"• {project_info.statistics.total_entities} entities\n"
-            result += f"• {project_info.statistics.total_observations} observations\n"
-            result += f"• {project_info.statistics.total_relations} relations\n"
-
-        except Exception as e:
-            # If we can't get project info, still confirm the switch
-            logger.warning(f"Could not get project info for {canonical_name}: {e}")
-            result = f"✓ Switched to {canonical_name} project\n\n"
-            result += "Project summary unavailable.\n"
-
-        return add_project_metadata(result, canonical_name)
-
-    except Exception as e:
-        logger.error(f"Error switching to project {project_name}: {e}")
-        # Revert to previous project on error
-        session.set_current_project(current_project)
-
-        # Return user-friendly error message instead of raising exception
-        return dedent(f"""
-            # Project Switch Failed
-
-            Could not switch to project '{project_name}': {str(e)}
-
-            ## Current project: {current_project}
-            Your session remains on the previous project.
-
-            ## Troubleshooting:
-            1. **Check available projects**: Use `list_memory_projects()` to see valid project names
-            2. **Verify spelling**: Ensure the project name is spelled correctly
-            3. **Check permissions**: Verify you have access to the requested project
-            4. **Try again**: The error might be temporary
-
-            ## Available options:
-            - See all projects: `list_memory_projects()`
-            - Stay on current project: `get_current_project()`
-            - Try different project: `switch_project("correct-project-name")`
-
-            If the project should exist but isn't listed, send a message to support@basicmachines.co.
-            """).strip()
-
-
-@mcp.tool()
-async def get_current_project(
-    ctx: Context | None = None, _compatibility: Optional[str] = None
-) -> str:
-    """Show the currently active project and basic stats.
-
-    Displays which project is currently active and provides basic information
-    about it.
-
-    Returns:
-        Current project name and basic statistics
-
-    Example:
-        get_current_project()
-    """
-    if ctx:  # pragma: no cover
-        await ctx.info("Getting current project information")
-
-    current_project = session.get_current_project()
-    result = f"Current project: {current_project}\n\n"
-
-    # get project stats (use permalink in URL path)
-    current_project_permalink = generate_permalink(current_project)
-    response = await call_get(
-        client,
-        f"/{current_project_permalink}/project/info",
-        params={"project_name": current_project},
-    )
-    project_info = ProjectInfoResponse.model_validate(response.json())
-
-    result += f"• {project_info.statistics.total_entities} entities\n"
-    result += f"• {project_info.statistics.total_observations} observations\n"
-    result += f"• {project_info.statistics.total_relations} relations\n"
-
-    default_project = session.get_default_project()
-    if current_project != default_project:
-        result += f"• Default project: {default_project}\n"
-
-    return add_project_metadata(result, current_project)
-
-
-@mcp.tool()
-async def set_default_project(project_name: str, ctx: Context | None = None) -> str:
-    """Set default project in config. Requires restart to take effect.
-
-    Updates the configuration to use a different default project. This change
-    only takes effect after restarting the Basic Memory server.
-
-    Args:
-        project_name: Name of the project to set as default
-
-    Returns:
-        Confirmation message about config update
-
-    Example:
-        set_default_project("work-notes")
-    """
-    if ctx:  # pragma: no cover
-        await ctx.info(f"Setting default project to: {project_name}")
-
-    # Call API to set default project using URL encoding for special characters
-    from urllib.parse import quote
-    encoded_name = quote(project_name, safe='')
-    response = await call_put(client, f"/projects/{encoded_name}/default")
-    status_response = ProjectStatusResponse.model_validate(response.json())
-
-    result = f"✓ {status_response.message}\n\n"
-    result += "Restart Basic Memory for this change to take effect:\n"
-    result += "basic-memory mcp\n"
-
-    if status_response.old_project:
-        result += f"\nPrevious default: {status_response.old_project.name}\n"
-
-    return add_project_metadata(result, session.get_current_project())
+    return result
 
 
 @mcp.tool("create_memory_project")
 async def create_memory_project(
-    project_name: str, project_path: str, set_default: bool = False, ctx: Context | None = None
+    project_name: str, project_path: str, set_default: bool = False, context: Context | None = None
 ) -> str:
     """Create a new Basic Memory project.
 
@@ -258,8 +91,13 @@ async def create_memory_project(
         create_memory_project("my-research", "~/Documents/research")
         create_memory_project("work-notes", "/home/user/work", set_default=True)
     """
-    if ctx:  # pragma: no cover
-        await ctx.info(f"Creating project: {project_name} at {project_path}")
+    # Check if server is constrained to a specific project
+    constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
+    if constrained_project:
+        return f'# Error\n\nProject creation disabled - MCP server is constrained to project \'{constrained_project}\'.\nUse the CLI to create projects: `basic-memory project add "{project_name}" "{project_path}"`'
+
+    if context:  # pragma: no cover
+        await context.info(f"Creating project: {project_name} at {project_path}")
 
     # Create the project request
     project_request = ProjectInfoRequest(
@@ -280,17 +118,14 @@ async def create_memory_project(
         if set_default:
             result += "• Set as default project\n"
 
-    result += "\nProject is now available for use.\n"
+    result += "\nProject is now available for use in tool calls.\n"
+    result += f"Use '{project_name}' as the project parameter in MCP tool calls.\n"
 
-    # If project was set as default, update session
-    if set_default:
-        session.set_current_project(project_name)
-
-    return add_project_metadata(result, session.get_current_project())
+    return result
 
 
 @mcp.tool()
-async def delete_project(project_name: str, ctx: Context | None = None) -> str:
+async def delete_project(project_name: str, context: Context | None = None) -> str:
     """Delete a Basic Memory project.
 
     Removes a project from the configuration and database. This does NOT delete
@@ -310,16 +145,13 @@ async def delete_project(project_name: str, ctx: Context | None = None) -> str:
         This action cannot be undone. The project will need to be re-added
         to access its content through Basic Memory again.
     """
-    if ctx:  # pragma: no cover
-        await ctx.info(f"Deleting project: {project_name}")
+    # Check if server is constrained to a specific project
+    constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
+    if constrained_project:
+        return f"# Error\n\nProject deletion disabled - MCP server is constrained to project '{constrained_project}'.\nUse the CLI to delete projects: `basic-memory project remove \"{project_name}\"`"
 
-    current_project = session.get_current_project()
-
-    # Check if trying to delete current project
-    if project_name == current_project:
-        raise ValueError(
-            f"Cannot delete the currently active project '{project_name}'. Switch to a different project first."
-        )
+    if context:  # pragma: no cover
+        await context.info(f"Deleting project: {project_name}")
 
     # Get project info before deletion to validate it exists
     response = await call_get(client, "/projects/projects")
@@ -337,7 +169,7 @@ async def delete_project(project_name: str, ctx: Context | None = None) -> str:
         if p.name.lower() == project_name.lower():
             target_project = p
             break
-    
+
     if not target_project:
         available_projects = [p.name for p in project_list.projects]
         raise ValueError(
@@ -346,7 +178,8 @@ async def delete_project(project_name: str, ctx: Context | None = None) -> str:
 
     # Call API to delete project using URL encoding for special characters
     from urllib.parse import quote
-    encoded_name = quote(target_project.name, safe='')
+
+    encoded_name = quote(target_project.name, safe="")
     response = await call_delete(client, f"/projects/{encoded_name}")
     status_response = ProjectStatusResponse.model_validate(response.json())
 
@@ -361,4 +194,4 @@ async def delete_project(project_name: str, ctx: Context | None = None) -> str:
     result += "Files remain on disk but project is no longer tracked by Basic Memory.\n"
     result += "Re-add the project to access its content again.\n"
 
-    return add_project_metadata(result, session.get_current_project())
+    return result

src/basic_memory/mcp/tools/read_content.py

@@ -5,17 +5,19 @@ supporting various file types including text, images, and other binary files.
 Files are read directly without any knowledge graph processing.
 """
 
-from typing import Optional
 import base64
 import io
 
+from typing import Optional
+
 from loguru import logger
 from PIL import Image as PILImage
+from fastmcp import Context
 
+from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.async_client import client
 from basic_memory.mcp.tools.utils import call_get
-from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas.memory import memory_url_path
 from basic_memory.utils import validate_project_path
 
@@ -147,11 +149,16 @@ def optimize_image(img, content_length, max_output_bytes=350000):
 
 
 @mcp.tool(description="Read a file's raw content by path or permalink")
-async def read_content(path: str, project: Optional[str] = None) -> dict:
+async def read_content(
+    path: str, project: Optional[str] = None, context: Context | None = None
+) -> dict:
     """Read a file's raw content by path or permalink.
 
     This tool provides direct access to file content in the knowledge base,
-    handling different file types appropriately:
+    handling different file types appropriately. Uses stateless architecture -
+    project parameter optional with server resolution.
+
+    Supported file types:
     - Text files (markdown, code, etc.) are returned as plain text
     - Images are automatically resized/optimized for display
     - Other binary files are returned as base64 if below size limits
@@ -161,7 +168,9 @@ async def read_content(path: str, project: Optional[str] = None) -> dict:
             - A regular file path (docs/example.md)
             - A memory URL (memory://docs/example)
             - A permalink (docs/example)
-        project: Optional project name to read from. If not provided, uses current active project.
+        project: Project name to read from. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
+        context: Optional FastMCP context for performance caching.
 
     Returns:
         A dictionary with the file content and metadata:
@@ -172,20 +181,27 @@ async def read_content(path: str, project: Optional[str] = None) -> dict:
 
     Examples:
         # Read a markdown file
-        result = await read_file("docs/project-specs.md")
+        result = await read_content("docs/project-specs.md")
 
         # Read an image
-        image_data = await read_file("assets/diagram.png")
+        image_data = await read_content("assets/diagram.png")
 
         # Read using memory URL
-        content = await read_file("memory://docs/architecture")
+        content = await read_content("memory://docs/architecture")
 
-        # Read from specific project
-        content = await read_content("docs/example.md", project="work-project")
+        # Read configuration file
+        config = await read_content("config/settings.json")
+
+        # Explicit project specification
+        result = await read_content("docs/project-specs.md", project="my-project")
+
+    Raises:
+        HTTPError: If project doesn't exist or is inaccessible
+        SecurityError: If path attempts path traversal
     """
-    logger.info("Reading file", path=path)
+    logger.info("Reading file", path=path, project=project)
 
-    active_project = get_active_project(project)
+    active_project = await get_active_project(client, project, context)
     project_url = active_project.project_url
 
     url = memory_url_path(path)

src/basic_memory/mcp/tools/read_note.py

@@ -4,12 +4,13 @@ from textwrap import dedent
 from typing import Optional
 
 from loguru import logger
+from fastmcp import Context
 
 from basic_memory.mcp.async_client import client
+from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.search import search_notes
 from basic_memory.mcp.tools.utils import call_get
-from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas.memory import memory_url_path
 from basic_memory.utils import validate_project_path
 
@@ -18,50 +19,76 @@ from basic_memory.utils import validate_project_path
     description="Read a markdown note by title or permalink.",
 )
 async def read_note(
-    identifier: str, page: int = 1, page_size: int = 10, project: Optional[str] = None
+    identifier: str,
+    project: Optional[str] = None,
+    page: int = 1,
+    page_size: int = 10,
+    context: Context | None = None,
 ) -> str:
-    """Read a markdown note from the knowledge base.
+    """Return the raw markdown for a note, or guidance text if no match is found.
 
-    This tool finds and retrieves a note by its title, permalink, or content search,
+    Finds and retrieves a note by its title, permalink, or content search,
     returning the raw markdown content including observations, relations, and metadata.
-    It will try multiple lookup strategies to find the most relevant note.
+
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
+
+    This tool will try multiple lookup strategies to find the most relevant note:
+    1. Direct permalink lookup
+    2. Title search fallback
+    3. Text search as last resort
 
     Args:
+        project: Project name to read from. Optional - server will resolve using the
+                hierarchy above. If unknown, use list_memory_projects() to discover
+                available projects.
         identifier: The title or permalink of the note to read
                    Can be a full memory:// URL, a permalink, a title, or search text
         page: Page number for paginated results (default: 1)
         page_size: Number of items per page (default: 10)
-        project: Optional project name to read from. If not provided, uses current active project.
+        context: Optional FastMCP context for performance caching.
 
     Returns:
         The full markdown content of the note if found, or helpful guidance if not found.
+        Content includes frontmatter, observations, relations, and all markdown formatting.
 
     Examples:
         # Read by permalink
-        read_note("specs/search-spec")
+        read_note("my-research", "specs/search-spec")
 
         # Read by title
-        read_note("Search Specification")
+        read_note("work-project", "Search Specification")
 
         # Read with memory URL
-        read_note("memory://specs/search-spec")
+        read_note("my-research", "memory://specs/search-spec")
 
         # Read with pagination
-        read_note("Project Updates", page=2, page_size=5)
+        read_note("work-project", "Project Updates", page=2, page_size=5)
 
-        # Read from specific project
-        read_note("Meeting Notes", project="work-project")
+        # Read recent meeting notes
+        read_note("team-docs", "Weekly Standup")
+
+    Raises:
+        HTTPError: If project doesn't exist or is inaccessible
+        SecurityError: If identifier attempts path traversal
+
+    Note:
+        If the exact note isn't found, this tool provides helpful suggestions
+        including related notes, search commands, and note creation templates.
     """
 
-    # Get the active project first to check project-specific sync status
-    active_project = get_active_project(project)
+    # Get and validate the project
+    active_project = await get_active_project(client, project, context)
 
     # Validate identifier to prevent path traversal attacks
     # We need to check both the raw identifier and the processed path
     processed_path = memory_url_path(identifier)
     project_path = active_project.home
-    
-    if not validate_project_path(identifier, project_path) or not validate_project_path(processed_path, project_path):
+
+    if not validate_project_path(identifier, project_path) or not validate_project_path(
+        processed_path, project_path
+    ):
         logger.warning(
             "Attempted path traversal attack blocked",
             identifier=identifier,
@@ -83,7 +110,7 @@ async def read_note(
     # Get the file via REST API - first try direct permalink lookup
     entity_path = memory_url_path(identifier)
     path = f"{project_url}/resource/{entity_path}"
-    logger.info(f"Attempting to read note from URL: {path}")
+    logger.info(f"Attempting to read note from Project: {active_project.name} URL: {path}")
 
     try:
         # Try direct lookup first
@@ -99,9 +126,12 @@ async def read_note(
 
     # Fallback 1: Try title search via API
     logger.info(f"Search title for: {identifier}")
-    title_results = await search_notes.fn(query=identifier, search_type="title", project=project)
+    title_results = await search_notes.fn(
+        query=identifier, search_type="title", project=project, context=context
+    )
 
-    if title_results and title_results.results:
+    # Handle both SearchResponse object and error strings
+    if title_results and hasattr(title_results, "results") and title_results.results:
         result = title_results.results[0]  # Get the first/best match
         if result.permalink:
             try:
@@ -119,58 +149,64 @@ async def read_note(
                     f"Failed to fetch content for found title match {result.permalink}: {e}"
                 )
     else:
-        logger.info(f"No results in title search for: {identifier}")
+        logger.info(
+            f"No results in title search for: {identifier} in project {active_project.name}"
+        )
 
     # Fallback 2: Text search as a last resort
     logger.info(f"Title search failed, trying text search for: {identifier}")
-    text_results = await search_notes.fn(query=identifier, search_type="text", project=project)
+    text_results = await search_notes.fn(
+        query=identifier, search_type="text", project=project, context=context
+    )
 
     # We didn't find a direct match, construct a helpful error message
-    if not text_results or not text_results.results:
+    # Handle both SearchResponse object and error strings
+    if not text_results or not hasattr(text_results, "results") or not text_results.results:
         # No results at all
-        return format_not_found_message(identifier)
+        return format_not_found_message(active_project.name, identifier)
     else:
         # We found some related results
-        return format_related_results(identifier, text_results.results[:5])
+        return format_related_results(active_project.name, identifier, text_results.results[:5])
 
 
-def format_not_found_message(identifier: str) -> str:
+def format_not_found_message(project: str | None, identifier: str) -> str:
     """Format a helpful message when no note was found."""
     return dedent(f"""
-        # Note Not Found: "{identifier}"
-        
+        # Note Not Found in {project}: "{identifier}"
+
         I couldn't find any notes matching "{identifier}". Here are some suggestions:
-        
+
         ## Check Identifier Type
         - If you provided a title, try using the exact permalink instead
         - If you provided a permalink, check for typos or try a broader search
-        
+
         ## Search Instead
         Try searching for related content:
         ```
-        search_notes(query="{identifier}")
+        search_notes(project="{project}", query="{identifier}")
         ```
-        
+
         ## Recent Activity
         Check recently modified notes:
         ```
         recent_activity(timeframe="7d")
         ```
-        
+
         ## Create New Note
         This might be a good opportunity to create a new note on this topic:
         ```
         write_note(
+            project="{project}",
             title="{identifier.capitalize()}",
             content='''
             # {identifier.capitalize()}
-            
+
             ## Overview
             [Your content here]
-            
+
             ## Observations
             - [category] [Observation about {identifier}]
-            
+
             ## Relations
             - relates_to [[Related Topic]]
             ''',
@@ -180,13 +216,13 @@ def format_not_found_message(identifier: str) -> str:
     """)
 
 
-def format_related_results(identifier: str, results) -> str:
+def format_related_results(project: str | None, identifier: str, results) -> str:
     """Format a helpful message with related results when an exact match wasn't found."""
     message = dedent(f"""
-        # Note Not Found: "{identifier}"
-        
+        # Note Not Found in {project}: "{identifier}"
+
         I couldn't find an exact match for "{identifier}", but I found some related notes:
-        
+
         """)
 
     for i, result in enumerate(results):
@@ -194,28 +230,29 @@ def format_related_results(identifier: str, results) -> str:
             ## {i + 1}. {result.title}
             - **Type**: {result.type.value}
             - **Permalink**: {result.permalink}
-            
+
             You can read this note with:
             ```
-            read_note("{result.permalink}")
+            read_note(project="{project}", {result.permalink}")
             ```
-            
+
             """)
 
-    message += dedent("""
+    message += dedent(f"""
         ## Try More Specific Lookup
         For exact matches, try using the full permalink from one of the results above.
-        
+
         ## Search For More Results
         To see more related content:
         ```
-        search_notes(query="{identifier}")
+        search_notes(project="{project}", query="{identifier}")
         ```
-        
+
         ## Create New Note
         If none of these match what you're looking for, consider creating a new note:
         ```
         write_note(
+            project="{project}",
             title="[Your title]",
             content="[Your content]",
             folder="notes"

src/basic_memory/mcp/tools/recent_activity.py

@@ -3,23 +3,29 @@
 from typing import List, Union, Optional
 
 from loguru import logger
+from fastmcp import Context
 
 from basic_memory.mcp.async_client import client
+from basic_memory.mcp.project_context import get_active_project, resolve_project_parameter
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_get
-from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas.base import TimeFrame
-from basic_memory.schemas.memory import GraphContext
+from basic_memory.schemas.memory import (
+    GraphContext,
+    ProjectActivity,
+    ActivityStats,
+)
+from basic_memory.schemas.project_info import ProjectList, ProjectItem
 from basic_memory.schemas.search import SearchItemType
 
 
 @mcp.tool(
-    description="""Get recent activity from across the knowledge base.
+    description="""Get recent activity for a project or across all projects.
 
     Timeframe supports natural language formats like:
-    - "2 days ago"  
+    - "2 days ago"
     - "last week"
-    - "yesterday" 
+    - "yesterday"
     - "today"
     - "3 weeks ago"
     Or standard formats like "7d"
@@ -29,12 +35,26 @@ async def recent_activity(
     type: Union[str, List[str]] = "",
     depth: int = 1,
     timeframe: TimeFrame = "7d",
-    page: int = 1,
-    page_size: int = 10,
-    max_related: int = 10,
     project: Optional[str] = None,
-) -> GraphContext:
-    """Get recent activity across the knowledge base.
+    context: Context | None = None,
+) -> str:
+    """Get recent activity for a specific project or across all projects.
+
+    Project Resolution:
+    The server resolves projects in this order:
+    1. Single Project Mode - server constrained to one project, parameter ignored
+    2. Explicit project parameter - specify which project to query
+    3. Default project - server configured default if no project specified
+
+    Discovery Mode:
+    When no specific project can be resolved, returns activity across all projects
+    to help discover available projects and their recent activity.
+
+    Project Discovery (when project is unknown):
+    1. Call list_memory_projects() to see available projects
+    2. Or use this tool without project parameter to see cross-project activity
+    3. Ask the user which project to focus on
+    4. Remember their choice for the conversation
 
     Args:
         type: Filter by content type(s). Can be a string or list of strings.
@@ -50,48 +70,39 @@ async def recent_activity(
             - Relative: "2 days ago", "last week", "yesterday"
             - Points in time: "2024-01-01", "January 1st"
             - Standard format: "7d", "24h"
-        page: Page number of results to return (default: 1)
-        page_size: Number of results to return per page (default: 10)
-        max_related: Maximum number of related results to return (default: 10)
-        project: Optional project name to get activity from. If not provided, uses current active project.
+        project: Project name to query. Optional - server will resolve using the
+                hierarchy above. If unknown, use list_memory_projects() to discover
+                available projects.
+        context: Optional FastMCP context for performance caching.
 
     Returns:
-        GraphContext containing:
-            - primary_results: Latest activities matching the filters
-            - related_results: Connected content via relations
-            - metadata: Query details and statistics
+        Human-readable summary of recent activity. When no specific project is
+        resolved, returns cross-project discovery information. When a specific
+        project is resolved, returns detailed activity for that project.
 
     Examples:
-        # Get all entities for the last 10 days (default)
+        # Cross-project discovery mode
         recent_activity()
+        recent_activity(timeframe="yesterday")
 
-        # Get all entities from yesterday (string format)
-        recent_activity(type="entity", timeframe="yesterday")
+        # Project-specific activity
+        recent_activity(project="work-docs", type="entity", timeframe="yesterday")
+        recent_activity(project="research", type=["entity", "relation"], timeframe="today")
+        recent_activity(project="notes", type="entity", depth=2, timeframe="2 weeks ago")
 
-        # Get all entities from yesterday (list format)
-        recent_activity(type=["entity"], timeframe="yesterday")
-
-        # Get recent relations and observations
-        recent_activity(type=["relation", "observation"], timeframe="today")
-
-        # Look back further with more context
-        recent_activity(type="entity", depth=2, timeframe="2 weeks ago")
-
-        # Get activity from specific project
-        recent_activity(type="entity", project="work-project")
+    Raises:
+        ToolError: If project doesn't exist or type parameter contains invalid values
 
     Notes:
         - Higher depth values (>3) may impact performance with large result sets
         - For focused queries, consider using build_context with a specific URI
         - Max timeframe is 1 year in the past
     """
-    logger.info(
-        f"Getting recent activity from type={type}, depth={depth}, timeframe={timeframe}, page={page}, page_size={page_size}, max_related={max_related}"
-    )
+    # Build common parameters for API calls
     params = {
-        "page": page,
-        "page_size": page_size,
-        "max_related": max_related,
+        "page": 1,
+        "page_size": 10,
+        "max_related": 10,
     }
     if depth:
         params["depth"] = depth
@@ -120,12 +131,400 @@ async def recent_activity(
         # Add validated types to params
         params["type"] = [t.value for t in validated_types]  # pyright: ignore
 
-    active_project = get_active_project(project)
-    project_url = active_project.project_url
+    # Resolve project parameter using the three-tier hierarchy
+    resolved_project = await resolve_project_parameter(project)
 
-    response = await call_get(
+    if resolved_project is None:
+        # Discovery Mode: Get activity across all projects
+        logger.info(
+            f"Getting recent activity across all projects: type={type}, depth={depth}, timeframe={timeframe}"
+        )
+
+        # Get list of all projects
+        response = await call_get(client, "/projects/projects")
+        project_list = ProjectList.model_validate(response.json())
+
+        projects_activity = {}
+        total_items = 0
+        total_entities = 0
+        total_relations = 0
+        total_observations = 0
+        most_active_project = None
+        most_active_count = 0
+        active_projects = 0
+
+        # Query each project's activity
+        for project_info in project_list.projects:
+            project_activity = await _get_project_activity(client, project_info, params, depth)
+            projects_activity[project_info.name] = project_activity
+
+            # Aggregate stats
+            item_count = project_activity.item_count
+            if item_count > 0:
+                active_projects += 1
+                total_items += item_count
+
+                # Count by type
+                for result in project_activity.activity.results:
+                    if result.primary_result.type == "entity":
+                        total_entities += 1
+                    elif result.primary_result.type == "relation":
+                        total_relations += 1
+                    elif result.primary_result.type == "observation":
+                        total_observations += 1
+
+                # Track most active project
+                if item_count > most_active_count:
+                    most_active_count = item_count
+                    most_active_project = project_info.name
+
+        # Build summary stats
+        summary = ActivityStats(
+            total_projects=len(project_list.projects),
+            active_projects=active_projects,
+            most_active_project=most_active_project,
+            total_items=total_items,
+            total_entities=total_entities,
+            total_relations=total_relations,
+            total_observations=total_observations,
+        )
+
+        # Generate guidance for the assistant
+        guidance_lines = ["\n" + "─" * 40]
+
+        if most_active_project and most_active_count > 0:
+            guidance_lines.extend(
+                [
+                    f"Suggested project: '{most_active_project}' (most active with {most_active_count} items)",
+                    f"Ask user: 'Should I use {most_active_project} for this task, or would you prefer a different project?'",
+                ]
+            )
+        elif active_projects > 0:
+            # Has activity but no clear most active project
+            active_project_names = [
+                name for name, activity in projects_activity.items() if activity.item_count > 0
+            ]
+            if len(active_project_names) == 1:
+                guidance_lines.extend(
+                    [
+                        f"Suggested project: '{active_project_names[0]}' (only active project)",
+                        f"Ask user: 'Should I use {active_project_names[0]} for this task?'",
+                    ]
+                )
+            else:
+                guidance_lines.extend(
+                    [
+                        f"Multiple active projects found: {', '.join(active_project_names)}",
+                        "Ask user: 'Which project should I use for this task?'",
+                    ]
+                )
+        else:
+            # No recent activity
+            guidance_lines.extend(
+                [
+                    "No recent activity found in any project.",
+                    "Consider: Ask which project to use or if they want to create a new one.",
+                ]
+            )
+
+        guidance_lines.extend(
+            ["", "Session reminder: Remember their project choice throughout this conversation."]
+        )
+
+        guidance = "\n".join(guidance_lines)
+
+        # Format discovery mode output
+        return _format_discovery_output(projects_activity, summary, timeframe, guidance)
+
+    else:
+        # Project-Specific Mode: Get activity for specific project
+        logger.info(
+            f"Getting recent activity from project {resolved_project}: type={type}, depth={depth}, timeframe={timeframe}"
+        )
+
+        active_project = await get_active_project(client, resolved_project, context)
+        project_url = active_project.project_url
+
+        response = await call_get(
+            client,
+            f"{project_url}/memory/recent",
+            params=params,
+        )
+        activity_data = GraphContext.model_validate(response.json())
+
+        # Format project-specific mode output
+        return _format_project_output(resolved_project, activity_data, timeframe, type)
+
+
+async def _get_project_activity(
+    client, project_info: ProjectItem, params: dict, depth: int
+) -> ProjectActivity:
+    """Get activity data for a single project.
+
+    Args:
+        client: HTTP client for API calls
+        project_info: Project information
+        params: Query parameters for the activity request
+        depth: Graph traversal depth
+
+    Returns:
+        ProjectActivity with activity data or empty activity on error
+    """
+    project_url = f"/{project_info.permalink}"
+    activity_response = await call_get(
         client,
         f"{project_url}/memory/recent",
         params=params,
     )
-    return GraphContext.model_validate(response.json())
+    activity = GraphContext.model_validate(activity_response.json())
+
+    # Extract last activity timestamp and active folders
+    last_activity = None
+    active_folders = set()
+
+    for result in activity.results:
+        if result.primary_result.created_at:
+            current_time = result.primary_result.created_at
+            try:
+                if last_activity is None or current_time > last_activity:
+                    last_activity = current_time
+            except TypeError:
+                # Handle timezone comparison issues by skipping this comparison
+                if last_activity is None:
+                    last_activity = current_time
+
+        # Extract folder from file_path
+        if hasattr(result.primary_result, "file_path") and result.primary_result.file_path:
+            folder = "/".join(result.primary_result.file_path.split("/")[:-1])
+            if folder:
+                active_folders.add(folder)
+
+    return ProjectActivity(
+        project_name=project_info.name,
+        project_path=project_info.path,
+        activity=activity,
+        item_count=len(activity.results),
+        last_activity=last_activity,
+        active_folders=list(active_folders)[:5],  # Limit to top 5 folders
+    )
+
+
+def _format_discovery_output(
+    projects_activity: dict, summary: ActivityStats, timeframe: str, guidance: str
+) -> str:
+    """Format discovery mode output as human-readable text."""
+    lines = [f"## Recent Activity Summary ({timeframe})"]
+
+    # Most active project section
+    if summary.most_active_project and summary.total_items > 0:
+        most_active = projects_activity[summary.most_active_project]
+        lines.append(
+            f"\n**Most Active Project:** {summary.most_active_project} ({most_active.item_count} items)"
+        )
+
+        # Get latest activity from most active project
+        if most_active.activity.results:
+            latest = most_active.activity.results[0].primary_result
+            title = latest.title if hasattr(latest, "title") and latest.title else "Recent activity"
+            # Format relative time
+            time_str = (
+                _format_relative_time(latest.created_at) if latest.created_at else "unknown time"
+            )
+            lines.append(f"- 🔧 **Latest:** {title} ({time_str})")
+
+        # Active folders
+        if most_active.active_folders:
+            folders = ", ".join(most_active.active_folders[:3])
+            lines.append(f"- 📋 **Focus areas:** {folders}")
+
+    # Other active projects
+    other_active = [
+        (name, activity)
+        for name, activity in projects_activity.items()
+        if activity.item_count > 0 and name != summary.most_active_project
+    ]
+
+    if other_active:
+        lines.append("\n**Other Active Projects:**")
+        for name, activity in sorted(other_active, key=lambda x: x[1].item_count, reverse=True)[:4]:
+            lines.append(f"- **{name}** ({activity.item_count} items)")
+
+    # Key developments - extract from recent entities
+    key_items = []
+    for name, activity in projects_activity.items():
+        if activity.item_count > 0:
+            for result in activity.activity.results[:3]:  # Top 3 from each active project
+                if result.primary_result.type == "entity" and hasattr(
+                    result.primary_result, "title"
+                ):
+                    title = result.primary_result.title
+                    # Look for status indicators in titles
+                    if any(word in title.lower() for word in ["complete", "fix", "test", "spec"]):
+                        key_items.append(title)
+
+    if key_items:
+        lines.append("\n**Key Developments:**")
+        for item in key_items[:5]:  # Show top 5
+            status = "✅" if any(word in item.lower() for word in ["complete", "fix"]) else "🧪"
+            lines.append(f"- {status} **{item}**")
+
+    # Add summary stats
+    lines.append(
+        f"\n**Summary:** {summary.active_projects} active projects, {summary.total_items} recent items"
+    )
+
+    # Add guidance
+    lines.append(guidance)
+
+    return "\n".join(lines)
+
+
+def _format_project_output(
+    project_name: str,
+    activity_data: GraphContext,
+    timeframe: str,
+    type_filter: Union[str, List[str]],
+) -> str:
+    """Format project-specific mode output as human-readable text."""
+    lines = [f"## Recent Activity: {project_name} ({timeframe})"]
+
+    if not activity_data.results:
+        lines.append(f"\nNo recent activity found in '{project_name}' project.")
+        return "\n".join(lines)
+
+    # Group results by type
+    entities = []
+    relations = []
+    observations = []
+
+    for result in activity_data.results:
+        if result.primary_result.type == "entity":
+            entities.append(result.primary_result)
+        elif result.primary_result.type == "relation":
+            relations.append(result.primary_result)
+        elif result.primary_result.type == "observation":
+            observations.append(result.primary_result)
+
+    # Show entities (notes/documents)
+    if entities:
+        lines.append(f"\n**📄 Recent Notes & Documents ({len(entities)}):**")
+        for entity in entities[:5]:  # Show top 5
+            title = entity.title if hasattr(entity, "title") and entity.title else "Untitled"
+            # Get folder from file_path if available
+            folder = ""
+            if hasattr(entity, "file_path") and entity.file_path:
+                folder_path = "/".join(entity.file_path.split("/")[:-1])
+                if folder_path:
+                    folder = f" ({folder_path})"
+            lines.append(f"  • {title}{folder}")
+
+    # Show observations (categorized insights)
+    if observations:
+        lines.append(f"\n**🔍 Recent Observations ({len(observations)}):**")
+        # Group by category
+        by_category = {}
+        for obs in observations[:10]:  # Limit to recent ones
+            category = (
+                getattr(obs, "category", "general") if hasattr(obs, "category") else "general"
+            )
+            if category not in by_category:
+                by_category[category] = []
+            by_category[category].append(obs)
+
+        for category, obs_list in list(by_category.items())[:5]:  # Show top 5 categories
+            lines.append(f"  **{category}:** {len(obs_list)} items")
+            for obs in obs_list[:2]:  # Show 2 examples per category
+                content = (
+                    getattr(obs, "content", "No content")
+                    if hasattr(obs, "content")
+                    else "No content"
+                )
+                # Truncate at word boundary
+                if len(content) > 80:
+                    content = _truncate_at_word(content, 80)
+                lines.append(f"    - {content}")
+
+    # Show relations (connections)
+    if relations:
+        lines.append(f"\n**🔗 Recent Connections ({len(relations)}):**")
+        for rel in relations[:5]:  # Show top 5
+            rel_type = (
+                getattr(rel, "relation_type", "relates_to")
+                if hasattr(rel, "relation_type")
+                else "relates_to"
+            )
+            from_entity = (
+                getattr(rel, "from_entity", "Unknown") if hasattr(rel, "from_entity") else "Unknown"
+            )
+            to_entity = getattr(rel, "to_entity", None) if hasattr(rel, "to_entity") else None
+
+            # Format as WikiLinks to show they're readable notes
+            from_link = f"[[{from_entity}]]" if from_entity != "Unknown" else from_entity
+            to_link = f"[[{to_entity}]]" if to_entity else "[Missing Link]"
+
+            lines.append(f"  • {from_link} → {rel_type} → {to_link}")
+
+    # Activity summary
+    total = len(activity_data.results)
+    lines.append(f"\n**Activity Summary:** {total} items found")
+    if hasattr(activity_data, "metadata") and activity_data.metadata:
+        if hasattr(activity_data.metadata, "total_results"):
+            lines.append(f"Total available: {activity_data.metadata.total_results}")
+
+    return "\n".join(lines)
+
+
+def _format_relative_time(timestamp) -> str:
+    """Format timestamp as relative time like '2 hours ago'."""
+    try:
+        from datetime import datetime, timezone
+        from dateutil.relativedelta import relativedelta
+
+        if isinstance(timestamp, str):
+            # Parse ISO format timestamp
+            dt = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+        else:
+            dt = timestamp
+
+        now = datetime.now(timezone.utc)
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+
+        # Use relativedelta for accurate time differences
+        diff = relativedelta(now, dt)
+
+        if diff.years > 0:
+            return f"{diff.years} year{'s' if diff.years > 1 else ''} ago"
+        elif diff.months > 0:
+            return f"{diff.months} month{'s' if diff.months > 1 else ''} ago"
+        elif diff.days > 0:
+            if diff.days == 1:
+                return "yesterday"
+            elif diff.days < 7:
+                return f"{diff.days} days ago"
+            else:
+                weeks = diff.days // 7
+                return f"{weeks} week{'s' if weeks > 1 else ''} ago"
+        elif diff.hours > 0:
+            return f"{diff.hours} hour{'s' if diff.hours > 1 else ''} ago"
+        elif diff.minutes > 0:
+            return f"{diff.minutes} minute{'s' if diff.minutes > 1 else ''} ago"
+        else:
+            return "just now"
+    except Exception:
+        return "recently"
+
+
+def _truncate_at_word(text: str, max_length: int) -> str:
+    """Truncate text at word boundary."""
+    if len(text) <= max_length:
+        return text
+
+    # Find last space before max_length
+    truncated = text[:max_length]
+    last_space = truncated.rfind(" ")
+
+    if last_space > max_length * 0.7:  # Only truncate at word if we're not losing too much
+        return text[:last_space] + "..."
+    else:
+        return text[: max_length - 3] + "..."

src/basic_memory/mcp/tools/search.py

@@ -4,15 +4,18 @@ from textwrap import dedent
 from typing import List, Optional
 
 from loguru import logger
+from fastmcp import Context
 
 from basic_memory.mcp.async_client import client
+from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_post
-from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas.search import SearchItemType, SearchQuery, SearchResponse
 
 
-def _format_search_error_response(error_message: str, query: str, search_type: str = "text") -> str:
+def _format_search_error_response(
+    project: str, error_message: str, query: str, search_type: str = "text"
+) -> str:
     """Format helpful error responses for search failures that guide users to successful searches."""
 
     # FTS5 syntax errors
@@ -50,13 +53,13 @@ def _format_search_error_response(error_message: str, query: str, search_type: s
 
             ## Try again with:
             ```
-            search_notes("{clean_query}")
+            search_notes("{project}","{clean_query}")
             ```
 
             ## Alternative search strategies:
-            - Break into simpler terms: `search_notes("{" ".join(clean_query.split()[:2])}")`
-            - Try different search types: `search_notes("{clean_query}", search_type="title")`
-            - Use filtering: `search_notes("{clean_query}", types=["entity"])`
+            - Break into simpler terms: `search_notes("{project}", "{" ".join(clean_query.split()[:2])}")`
+            - Try different search types: `search_notes("{project}","{clean_query}", search_type="title")`
+            - Use filtering: `search_notes("{project}","{clean_query}", types=["entity"])`
             """).strip()
 
     # Project not found errors (check before general "not found")
@@ -68,11 +71,9 @@ def _format_search_error_response(error_message: str, query: str, search_type: s
 
             ## How to resolve:
             1. **Check available projects**: `list_projects()`
-            2. **Switch to valid project**: `switch_project("valid-project-name")`
             3. **Verify project setup**: Ensure your project is properly configured
 
             ## Current session info:
-            - Check current project: `get_current_project()`
             - See available projects: `list_projects()`
             """).strip()
 
@@ -100,29 +101,28 @@ def _format_search_error_response(error_message: str, query: str, search_type: s
                - Try synonyms or related terms
 
             3. **Use different search approaches**:
-               - **Text search**: `search_notes("{query}", search_type="text")` (searches full content)
-               - **Title search**: `search_notes("{query}", search_type="title")` (searches only titles)
-               - **Permalink search**: `search_notes("{query}", search_type="permalink")` (searches file paths)
+               - **Text search**: `search_notes("{project}","{query}", search_type="text")` (searches full content)
+               - **Title search**: `search_notes("{project}","{query}", search_type="title")` (searches only titles)
+               - **Permalink search**: `search_notes("{project}","{query}", search_type="permalink")` (searches file paths)
 
             4. **Try boolean operators for broader results**:
-               - OR search: `search_notes("{" OR ".join(query.split()[:3])}")`
+               - OR search: `search_notes("{project}","{" OR ".join(query.split()[:3])}")`
                - Remove restrictive terms: Focus on the most important keywords
 
             5. **Use filtering to narrow scope**:
-               - By content type: `search_notes("{query}", types=["entity"])`
-               - By recent content: `search_notes("{query}", after_date="1 week")`
-               - By entity type: `search_notes("{query}", entity_types=["observation"])`
+               - By content type: `search_notes("{project}","{query}", types=["entity"])`
+               - By recent content: `search_notes("{project}","{query}", after_date="1 week")`
+               - By entity type: `search_notes("{project}","{query}", entity_types=["observation"])`
 
             6. **Try advanced search patterns**:
-               - Tag search: `search_notes("tag:your-tag")`
-               - Category search: `search_notes("category:observation")`
-               - Pattern matching: `search_notes("*{query}*", search_type="permalink")`
+               - Tag search: `search_notes("{project}","tag:your-tag")`
+               - Category search: `search_notes("{project}","category:observation")`
+               - Pattern matching: `search_notes("{project}","*{query}*", search_type="permalink")`
 
             ## Explore what content exists:
             - **Recent activity**: `recent_activity(timeframe="7d")` - See what's been updated recently
-            - **List directories**: `list_directory("/")` - Browse all content
-            - **Browse by folder**: `list_directory("/notes")` or `list_directory("/docs")`
-            - **Check project**: `get_current_project()` - Verify you're in the right project
+            - **List directories**: `list_directory("{project}","/")` - Browse all content
+            - **Browse by folder**: `list_directory("{project}","/notes")` or `list_directory("/docs")`
             """).strip()
 
     # Server/API errors
@@ -138,9 +138,9 @@ def _format_search_error_response(error_message: str, query: str, search_type: s
             3. **Check project status**: Ensure your project is properly synced
 
             ## Alternative approaches:
-            - Browse files directly: `list_directory("/")`
+            - Browse files directly: `list_directory("{project}","/")`
             - Check recent activity: `recent_activity(timeframe="7d")`
-            - Try a different search type: `search_notes("{query}", search_type="title")`
+            - Try a different search type: `search_notes("{project}","{query}", search_type="title")`
 
             ## If the problem persists:
             The search index might need to be rebuilt. Send a message to support@basicmachines.co or check the project sync status.
@@ -162,9 +162,7 @@ You don't have permission to search in the current project: {error_message}
 3. **Check authentication**: You might need to re-authenticate
 
 ## Alternative actions:
-- List available projects: `list_projects()`
-- Switch to accessible project: `switch_project("project-name")`
-- Check current project: `get_current_project()`"""
+- List available projects: `list_projects()`"""
 
     # Generic fallback
     return f"""# Search Failed
@@ -179,17 +177,16 @@ Error searching for '{query}': {error_message}
 
 ## Alternative search approaches:
 - **Different search types**: 
-  - Title only: `search_notes("{query}", search_type="title")`
-  - Permalink patterns: `search_notes("{query}*", search_type="permalink")`
-- **With filters**: `search_notes("{query}", types=["entity"])`
-- **Recent content**: `search_notes("{query}", after_date="1 week")`
-- **Boolean variations**: `search_notes("{" OR ".join(query.split()[:2])}")`
+  - Title only: `search_notes("{project}","{query}", search_type="title")`
+  - Permalink patterns: `search_notes("{project}","{query}*", search_type="permalink")`
+- **With filters**: `search_notes("{project}","{query}", types=["entity"])`
+- **Recent content**: `search_notes("{project}","{query}", after_date="1 week")`
+- **Boolean variations**: `search_notes("{project}","{" OR ".join(query.split()[:2])}")`
 
 ## Explore your content:
-- **Browse files**: `list_directory("/")` - See all available content
+- **Browse files**: `list_directory("{project}","/")` - See all available content
 - **Recent activity**: `recent_activity(timeframe="7d")` - Check what's been updated
-- **Project info**: `get_current_project()` - Verify current project
-- **All projects**: `list_projects()` - Switch to different project if needed
+- **All projects**: `list_projects()` 
 
 ## Search syntax reference:
 - **Basic**: `keyword` or `multiple words`
@@ -204,13 +201,14 @@ Error searching for '{query}': {error_message}
 )
 async def search_notes(
     query: str,
+    project: Optional[str] = None,
     page: int = 1,
     page_size: int = 10,
     search_type: str = "text",
     types: Optional[List[str]] = None,
     entity_types: Optional[List[str]] = None,
     after_date: Optional[str] = None,
-    project: Optional[str] = None,
+    context: Context | None = None,
 ) -> SearchResponse | str:
     """Search across all content in the knowledge base with comprehensive syntax support.
 
@@ -218,51 +216,57 @@ async def search_notes(
     or exact permalink lookup. It supports filtering by content type, entity type,
     and date, with advanced boolean and phrase search capabilities.
 
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
+
     ## Search Syntax Examples
 
     ### Basic Searches
-    - `search_notes("keyword")` - Find any content containing "keyword"
-    - `search_notes("exact phrase")` - Search for exact phrase match
+    - `search_notes("my-project", "keyword")` - Find any content containing "keyword"
+    - `search_notes("work-docs", "'exact phrase'")` - Search for exact phrase match
 
     ### Advanced Boolean Searches
-    - `search_notes("term1 term2")` - Find content with both terms (implicit AND)
-    - `search_notes("term1 AND term2")` - Explicit AND search (both terms required)
-    - `search_notes("term1 OR term2")` - Either term can be present
-    - `search_notes("term1 NOT term2")` - Include term1 but exclude term2
-    - `search_notes("(project OR planning) AND notes")` - Grouped boolean logic
+    - `search_notes("my-project", "term1 term2")` - Find content with both terms (implicit AND)
+    - `search_notes("my-project", "term1 AND term2")` - Explicit AND search (both terms required)
+    - `search_notes("my-project", "term1 OR term2")` - Either term can be present
+    - `search_notes("my-project", "term1 NOT term2")` - Include term1 but exclude term2
+    - `search_notes("my-project", "(project OR planning) AND notes")` - Grouped boolean logic
 
     ### Content-Specific Searches
-    - `search_notes("tag:example")` - Search within specific tags (if supported by content)
-    - `search_notes("category:observation")` - Filter by observation categories
-    - `search_notes("author:username")` - Find content by author (if metadata available)
+    - `search_notes("research", "tag:example")` - Search within specific tags (if supported by content)
+    - `search_notes("work-project", "category:observation")` - Filter by observation categories
+    - `search_notes("team-docs", "author:username")` - Find content by author (if metadata available)
 
     ### Search Type Examples
-    - `search_notes("Meeting", search_type="title")` - Search only in titles
-    - `search_notes("docs/meeting-*", search_type="permalink")` - Pattern match permalinks
-    - `search_notes("keyword", search_type="text")` - Full-text search (default)
+    - `search_notes("my-project", "Meeting", search_type="title")` - Search only in titles
+    - `search_notes("work-docs", "docs/meeting-*", search_type="permalink")` - Pattern match permalinks
+    - `search_notes("research", "keyword", search_type="text")` - Full-text search (default)
 
     ### Filtering Options
-    - `search_notes("query", types=["entity"])` - Search only entities
-    - `search_notes("query", types=["note", "person"])` - Multiple content types
-    - `search_notes("query", entity_types=["observation"])` - Filter by entity type
-    - `search_notes("query", after_date="2024-01-01")` - Recent content only
-    - `search_notes("query", after_date="1 week")` - Relative date filtering
+    - `search_notes("my-project", "query", types=["entity"])` - Search only entities
+    - `search_notes("work-docs", "query", types=["note", "person"])` - Multiple content types
+    - `search_notes("research", "query", entity_types=["observation"])` - Filter by entity type
+    - `search_notes("team-docs", "query", after_date="2024-01-01")` - Recent content only
+    - `search_notes("my-project", "query", after_date="1 week")` - Relative date filtering
 
     ### Advanced Pattern Examples
-    - `search_notes("project AND (meeting OR discussion)")` - Complex boolean logic
-    - `search_notes("\"exact phrase\" AND keyword")` - Combine phrase and keyword search
-    - `search_notes("bug NOT fixed")` - Exclude resolved issues
-    - `search_notes("docs/2024-*", search_type="permalink")` - Year-based permalink search
+    - `search_notes("work-project", "project AND (meeting OR discussion)")` - Complex boolean logic
+    - `search_notes("research", "\"exact phrase\" AND keyword")` - Combine phrase and keyword search
+    - `search_notes("dev-notes", "bug NOT fixed")` - Exclude resolved issues
+    - `search_notes("archive", "docs/2024-*", search_type="permalink")` - Year-based permalink search
 
     Args:
         query: The search query string (supports boolean operators, phrases, patterns)
+        project: Project name to search in. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
         page: The page number of results to return (default 1)
         page_size: The number of results to return per page (default 10)
         search_type: Type of search to perform, one of: "text", "title", "permalink" (default: "text")
         types: Optional list of note types to search (e.g., ["note", "person"])
         entity_types: Optional list of entity types to filter by (e.g., ["entity", "observation"])
         after_date: Optional date filter for recent content (e.g., "1 week", "2d", "2024-01-01")
-        project: Optional project name to search in. If not provided, uses current active project.
+        context: Optional FastMCP context for performance caching.
 
     Returns:
         SearchResponse with results and pagination info, or helpful error guidance if search fails
@@ -288,37 +292,43 @@ async def search_notes(
 
         # Search with type filter
         results = await search_notes(
-            query="meeting notes",
+            "meeting notes",
             types=["entity"],
         )
 
         # Search with entity type filter
         results = await search_notes(
-            query="meeting notes",
+            "meeting notes",
             entity_types=["observation"],
         )
 
         # Search for recent content
         results = await search_notes(
-            query="bug report",
+            "bug report",
             after_date="1 week"
         )
 
         # Pattern matching on permalinks
         results = await search_notes(
-            query="docs/meeting-*",
+            "docs/meeting-*",
             search_type="permalink"
         )
 
-        # Search in specific project
-        results = await search_notes("meeting notes", project="work-project")
+        # Title-only search
+        results = await search_notes(
+            "Machine Learning",
+            search_type="title"
+        )
 
         # Complex search with multiple filters
         results = await search_notes(
-            query="(bug OR issue) AND NOT resolved",
+            "(bug OR issue) AND NOT resolved",
             types=["entity"],
             after_date="2024-01-01"
         )
+
+        # Explicit project specification
+        results = await search_notes("project planning", project="my-project")
     """
     # Create a SearchQuery object based on the parameters
     search_query = SearchQuery()
@@ -343,10 +353,10 @@ async def search_notes(
     if after_date:
         search_query.after_date = after_date
 
-    active_project = get_active_project(project)
+    active_project = await get_active_project(client, project, context)
     project_url = active_project.project_url
 
-    logger.info(f"Searching for {search_query}")
+    logger.info(f"Searching for {search_query} in project {active_project.name}")
 
     try:
         response = await call_post(
@@ -359,13 +369,15 @@ async def search_notes(
 
         # Check if we got no results and provide helpful guidance
         if not result.results:
-            logger.info(f"Search returned no results for query: {query}")
+            logger.info(
+                f"Search returned no results for query: {query} in project {active_project.name}"
+            )
             # Don't treat this as an error, but the user might want guidance
             # We return the empty result as normal - the user can decide if they need help
 
         return result
 
     except Exception as e:
-        logger.error(f"Search failed for query '{query}': {e}")
+        logger.error(f"Search failed for query '{query}': {e}, project: {active_project.name}")
         # Return formatted error message as string for better user experience
-        return _format_search_error_response(str(e), query, search_type)
+        return _format_search_error_response(active_project.name, str(e), query, search_type)

src/basic_memory/mcp/tools/sync_status.py

@@ -3,10 +3,12 @@
 from typing import Optional
 
 from loguru import logger
+from fastmcp import Context
 
 from basic_memory.config import ConfigManager
+from basic_memory.mcp.async_client import client
 from basic_memory.mcp.server import mcp
-from basic_memory.mcp.project_session import get_active_project
+from basic_memory.mcp.project_context import get_active_project
 from basic_memory.services.sync_status_service import sync_status_tracker
 
 
@@ -79,7 +81,7 @@ def _get_all_projects_status() -> list[str]:
     - Background processing of knowledge graphs
     """,
 )
-async def sync_status(project: Optional[str] = None) -> str:
+async def sync_status(project: Optional[str] = None, context: Context | None = None) -> str:
     """Get current sync status and system readiness information.
 
     This tool provides detailed information about any ongoing or completed
@@ -220,14 +222,13 @@ async def sync_status(project: Optional[str] = None) -> str:
                     [
                         "",
                         "**Note**: All configured projects will be automatically synced during startup.",
-                        "You don't need to manually switch projects - Basic Memory handles this for you.",
                     ]
                 )
 
         # Add project context if provided
         if project:
             try:
-                active_project = get_active_project(project)
+                active_project = await get_active_project(client, project, context)
                 status_lines.extend(
                     [
                         "",

src/basic_memory/mcp/tools/utils.py

@@ -23,6 +23,8 @@ from httpx._types import (
 from loguru import logger
 from mcp.server.fastmcp.exceptions import ToolError
 
+from basic_memory.mcp.tools.headers import inject_auth_header
+
 
 def get_error_message(
     status_code: int, url: URL | str, method: str, msg: Optional[str] = None
@@ -107,6 +109,8 @@ async def call_get(
     """
     logger.debug(f"Calling GET '{url}' params: '{params}'")
     error_message = None
+
+    headers = inject_auth_header(headers)
     try:
         response = await client.get(
             url,
@@ -192,6 +196,9 @@ async def call_put(
     logger.debug(f"Calling PUT '{url}'")
     error_message = None
 
+    # Inject JWT from FastMCP context if available
+    headers = inject_auth_header(headers)
+
     try:
         response = await client.put(
             url,
@@ -280,6 +287,10 @@ async def call_patch(
         ToolError: If the request fails with an appropriate error message
     """
     logger.debug(f"Calling PATCH '{url}'")
+
+    # Inject JWT from FastMCP context if available
+    headers = inject_auth_header(headers)
+
     try:
         response = await client.patch(
             url,
@@ -384,6 +395,10 @@ async def call_post(
     """
     logger.debug(f"Calling POST '{url}'")
     error_message = None
+
+    # Inject JWT from FastMCP context if available
+    headers = inject_auth_header(headers)
+
     try:
         response = await client.post(
             url=url,
@@ -465,6 +480,10 @@ async def call_delete(
     """
     logger.debug(f"Calling DELETE '{url}'")
     error_message = None
+
+    # Inject JWT from FastMCP context if available
+    headers = inject_auth_header(headers)
+
     try:
         response = await client.delete(
             url=url,

src/basic_memory/mcp/tools/view_note.py

@@ -4,6 +4,7 @@ from textwrap import dedent
 from typing import Optional
 
 from loguru import logger
+from fastmcp import Context
 
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.read_note import read_note
@@ -13,12 +14,17 @@ from basic_memory.mcp.tools.read_note import read_note
     description="View a note as a formatted artifact for better readability.",
 )
 async def view_note(
-    identifier: str, page: int = 1, page_size: int = 10, project: Optional[str] = None
+    identifier: str,
+    project: Optional[str] = None,
+    page: int = 1,
+    page_size: int = 10,
+    context: Context | None = None,
 ) -> str:
     """View a markdown note as a formatted artifact.
 
     This tool reads a note using the same logic as read_note but displays the content
     as a markdown artifact for better viewing experience in Claude Desktop.
+    Project parameter optional with server resolution.
 
     After calling this tool, create an artifact using the returned content to display
     the note in a readable format. The tool returns the note content that should be
@@ -26,21 +32,40 @@ async def view_note(
 
     Args:
         identifier: The title or permalink of the note to view
+        project: Project name to read from. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
         page: Page number for paginated results (default: 1)
         page_size: Number of items per page (default: 10)
-        project: Optional project name to read from. If not provided, uses current active project.
+        context: Optional FastMCP context for performance caching.
 
     Returns:
         The note content as a markdown artifact with a confirmation message.
+
+    Examples:
+        # View a note by title
+        view_note("Meeting Notes")
+
+        # View a note by permalink
+        view_note("meetings/weekly-standup")
+
+        # View with pagination
+        view_note("large-document", page=2, page_size=5)
+
+        # Explicit project specification
+        view_note("Meeting Notes", project="my-project")
+
+    Raises:
+        HTTPError: If project doesn't exist or is inaccessible
+        SecurityError: If identifier attempts path traversal
     """
 
-    logger.info(f"Viewing note: {identifier}")
+    logger.info(f"Viewing note: {identifier} in project: {project}")
 
     # Call the existing read_note logic
-    content = await read_note.fn(identifier, page, page_size, project)
+    content = await read_note.fn(identifier, project, page, page_size, context)
 
     # Check if this is an error message (note not found)
-    if "# Note Not Found:" in content:
+    if "# Note Not Found" in content:
         return content  # Return error message directly instead of creating artifact
 
     # Extract title from content if possible
@@ -61,6 +86,6 @@ async def view_note(
 
     return dedent(f"""
             <instructions>
-            Create an artifact using the returned artifact content to display the note in a readable format.
+            Create an artifact using the returned content to display the note in a readable format.
             </instructions>
             {artifact}\n\n✅ Note displayed as artifact: **{title}**""")

src/basic_memory/mcp/tools/write_note.py

@@ -5,10 +5,11 @@ from typing import List, Union, Optional
 from loguru import logger
 
 from basic_memory.mcp.async_client import client
+from basic_memory.mcp.project_context import get_active_project, add_project_metadata
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_put
-from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas import EntityResponse
+from fastmcp import Context
 from basic_memory.schemas.base import Entity
 from basic_memory.utils import parse_tags, validate_project_path
 
@@ -26,14 +27,20 @@ async def write_note(
     title: str,
     content: str,
     folder: str,
-    tags=None,  # Remove type hint completely to avoid schema issues
-    entity_type: str = "note",
     project: Optional[str] = None,
+    tags=None,
+    entity_type: str = "note",
+    context: Context | None = None,
 ) -> str:
     """Write a markdown note to the knowledge base.
 
-    The content can include semantic observations and relations using markdown syntax.
-    Relations can be specified either explicitly or through inline wiki-style links:
+    Creates or updates a markdown note with semantic observations and relations.
+
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
+
+    The content can include semantic observations and relations using markdown syntax:
 
     Observations format:
         `- [category] Observation text #tag1 #tag2 (optional context)`
@@ -50,30 +57,72 @@ async def write_note(
         Examples:
         `- depends_on [[Content Parser]] (Need for semantic extraction)`
         `- implements [[Search Spec]] (Initial implementation)`
-        `- This feature extends [[Base Design]] andst uses [[Core Utils]]`
+        `- This feature extends [[Base Design]] and uses [[Core Utils]]`
 
     Args:
         title: The title of the note
         content: Markdown content for the note, can include observations and relations
         folder: Folder path relative to project root where the file should be saved.
                 Use forward slashes (/) as separators. Examples: "notes", "projects/2025", "research/ml"
+        project: Project name to write to. Optional - server will resolve using the
+                hierarchy above. If unknown, use list_memory_projects() to discover
+                available projects.
         tags: Tags to categorize the note. Can be a list of strings, a comma-separated string, or None.
               Note: If passing from external MCP clients, use a string format (e.g. "tag1,tag2,tag3")
         entity_type: Type of entity to create. Defaults to "note". Can be "guide", "report", "config", etc.
-        project: Optional project name to write to. If not provided, uses current active project.
+        context: Optional FastMCP context for performance caching.
 
     Returns:
         A markdown formatted summary of the semantic content, including:
-        - Creation/update status
+        - Creation/update status with project name
         - File path and checksum
         - Observation counts by category
         - Relation counts (resolved/unresolved)
         - Tags if present
-    """
-    logger.info(f"MCP tool call tool=write_note folder={folder}, title={title}, tags={tags}")
+        - Session tracking metadata for project awareness
 
-    # Get the active project first to check project-specific sync status
-    active_project = get_active_project(project)
+    Examples:
+        # Assistant flow when project is unknown
+        # 1. list_memory_projects() -> Ask user which project
+        # 2. User: "Use my-research"
+        # 3. write_note(...) and remember "my-research" for session
+
+        # Create a simple note
+        write_note(
+            project="my-research",
+            title="Meeting Notes",
+            folder="meetings",
+            content="# Weekly Standup\\n\\n- [decision] Use SQLite for storage #tech"
+        )
+
+        # Create a note with tags and entity type
+        write_note(
+            project="work-project",
+            title="API Design",
+            folder="specs",
+            content="# REST API Specification\\n\\n- implements [[Authentication]]",
+            tags=["api", "design"],
+            entity_type="guide"
+        )
+
+        # Update existing note (same title/folder)
+        write_note(
+            project="my-research",
+            title="Meeting Notes",
+            folder="meetings",
+            content="# Weekly Standup\\n\\n- [decision] Use PostgreSQL instead #tech"
+        )
+
+    Raises:
+        HTTPError: If project doesn't exist or is inaccessible
+        SecurityError: If folder path attempts path traversal
+    """
+    logger.info(
+        f"MCP tool call tool=write_note project={project} folder={folder}, title={title}, tags={tags}"
+    )
+
+    # Get and validate the project (supports optional project parameter)
+    active_project = await get_active_project(client, project, context)
 
     # Validate folder path to prevent path traversal attacks
     project_path = active_project.home
@@ -104,7 +153,7 @@ async def write_note(
         content=content,
         entity_metadata=metadata,
     )
-    project_url = active_project.project_url
+    project_url = active_project.permalink
 
     # Create or update via knowledge API
     logger.debug(f"Creating entity via API permalink={entity.permalink}")
@@ -116,6 +165,7 @@ async def write_note(
     action = "Created" if response.status_code == 201 else "Updated"
     summary = [
         f"# {action} note",
+        f"project: {active_project.name}",
         f"file_path: {result.file_path}",
         f"permalink: {result.permalink}",
         f"checksum: {result.checksum[:8] if result.checksum else 'unknown'}",
@@ -152,6 +202,7 @@ async def write_note(
 
     # Log the response with structured data
     logger.info(
-        f"MCP tool response: tool=write_note action={action} permalink={result.permalink} observations_count={len(result.observations)} relations_count={len(result.relations)} resolved_relations={resolved} unresolved_relations={unresolved} status_code={response.status_code}"
+        f"MCP tool response: tool=write_note project={active_project.name} action={action} permalink={result.permalink} observations_count={len(result.observations)} relations_count={len(result.relations)} resolved_relations={resolved} unresolved_relations={unresolved} status_code={response.status_code}"
     )
-    return "\n".join(summary)
+    result = "\n".join(summary)
+    return add_project_metadata(result, active_project.name)

src/basic_memory/models/knowledge.py

@@ -74,8 +74,14 @@ class Entity(Base):
     checksum: Mapped[Optional[str]] = mapped_column(String, nullable=True)
 
     # Metadata and tracking
-    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now().astimezone())
-    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now().astimezone(), onupdate=lambda: datetime.now().astimezone())
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now().astimezone()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now().astimezone(),
+        onupdate=lambda: datetime.now().astimezone(),
+    )
 
     # Relationships
     project = relationship("Project", back_populates="entities")
@@ -104,15 +110,15 @@ class Entity(Base):
     def is_markdown(self):
         """Check if the entity is a markdown file."""
         return self.content_type == "text/markdown"
-    
+
     def __getattribute__(self, name):
         """Override attribute access to ensure datetime fields are timezone-aware."""
         value = super().__getattribute__(name)
-        
+
         # Ensure datetime fields are timezone-aware
-        if name in ('created_at', 'updated_at') and isinstance(value, datetime):
+        if name in ("created_at", "updated_at") and isinstance(value, datetime):
             return ensure_timezone_aware(value)
-        
+
         return value
 
     def __repr__(self) -> str:

src/basic_memory/models/project.py

@@ -52,9 +52,13 @@ class Project(Base):
     is_default: Mapped[Optional[bool]] = mapped_column(Boolean, default=None, nullable=True)
 
     # Timestamps
-    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=lambda: datetime.now(UTC))
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(UTC)
+    )
     updated_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), default=lambda: datetime.now(UTC), onupdate=lambda: datetime.now(UTC)
+        DateTime(timezone=True),
+        default=lambda: datetime.now(UTC),
+        onupdate=lambda: datetime.now(UTC),
     )
 
     # Define relationships to entities, observations, and relations