# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
This is Session Buddy, a Claude Session Management MCP (Model Context Protocol) server that provides comprehensive session management functionality for Claude Code across any project. It operates as a standalone MCP server with its own isolated environment to avoid dependency conflicts.
## Development Commands
### Installation & Setup
```bash
# Install all dependencies (development + production)
uv sync --group dev
# Install minimal dependencies only (production)
uv sync
# Run server directly as a module
python -m session_buddy.server
# Run server with debug logging
PYTHONPATH=. python -m session_buddy.server --debug
# Verify installation
python -c "from session_buddy.server import mcp; print('✅ MCP server ready')"
python -c "from session_buddy.reflection_tools import ReflectionDatabase; print('✅ Memory system ready')"
```
### Quick Start Development
```bash
# Complete development setup in one command
uv sync --group dev && \
pytest -m "not slow" && \
crackerjack lint
```
### Code Quality & Linting
```bash
# Lint and format code (uses Ruff with strict settings)
crackerjack lint
# Run type checking
crackerjack typecheck
# Security scanning
crackerjack security
# Code complexity analysis
crackerjack complexity
# Full quality analysis
crackerjack analyze
```
### Testing & Development
```bash
# Run comprehensive test suite with coverage
pytest
# Quick smoke tests for development (recommended during coding)
pytest -m "not slow"
# Run specific test categories
pytest tests/unit/ # Unit tests only
pytest tests/integration/ # Integration tests only
pytest -m performance # Performance tests only
pytest -m security # Security tests only
# Run single test file with verbose output
pytest tests/unit/test_session_permissions.py -v -s
# Run tests with parallel execution (faster)
pytest -n auto
# Coverage reporting
pytest --cov=session_buddy --cov-report=term-missing
# Development debugging mode (keeps test data)
pytest -v --tb=short
# Fail build if coverage below 85%
pytest --cov=session_buddy --cov-fail-under=85
# Run tests with custom timeout
pytest --timeout=300
```
### Development Workflow Commands
```bash
# Pre-commit workflow (run before any commit)
uv sync --group dev && \
crackerjack lint && \
pytest -m "not slow" && \
crackerjack typecheck
# Full quality gate (run before PR)
pytest --cov=session_buddy --cov-fail-under=85 && \
crackerjack security && \
crackerjack complexity
# Debug server issues
python -c "
import logging
logging.basicConfig(level=logging.DEBUG)
from session_buddy.server import mcp
print('Server debug check complete')
"
```
## Architecture Overview
### Recent Architecture Changes (Phases 2.7 & 3.0 - January 2025)
**Latest Updates** (December 2025):
- **Removed sitecustomize.py** - No longer needed with Codex AI workaround; eliminated 115 lines of brittle startup-time patches
- **Updated FastAPI to >=0.124.2** - Removed upper bound constraint; FastAPI 0.121.x bugs resolved in 0.124.2+
- **Documentation Reorganization** - Archived 80 historical docs to `docs/archive/` (91% reduction in top-level clutter)
**ACB Adapter Migration - COMPLETE** (**Phases 2 & 3** - January 11, 2025)
Both database layers have been successfully migrated to ACB (Asynchronous Component Base) adapters:
**✅ Phase 2: Vector Adapter** (Conversations/Reflections)
- Full ACB integration with async operations
- Created `ReflectionDatabaseAdapter` using ACB Vector adapter (566 lines)
- Fixed critical ACB framework bug (vector search returning score=0.0)
- Migration script: `scripts/migrate_vector_database.py` (365 lines)
- 100% API compatibility maintained
**✅ Phase 3: Graph Adapter** (Knowledge Graph) - **Hybrid Pattern Discovery**
- Implemented `KnowledgeGraphDatabaseAdapter` with hybrid sync/async pattern (700 lines)
- **Breakthrough**: Discovered DuckDB operations are fast enough (\<1ms) to safely use sync code in async contexts
- **No async driver required**: Eliminated need for `duckdb-engine` or async SQLAlchemy
- Async method signatures for API consistency, sync DuckDB operations internally
- Migration script: `scripts/migrate_graph_database.py` (345 lines)
- Same pattern ACB's Vector adapter uses successfully
**Hybrid Pattern Key Insight**:
```text
async def create_entity(self, name: str, ...) -> dict:
"""Async signature for API consistency, sync operation internally."""
conn = self._get_conn() # Sync DuckDB connection
conn.execute("INSERT INTO kg_entities ...") # Fast local operation (<1ms)
return {"id": entity_id, ...}
```
This pattern can be applied to other fast local databases (SQLite, in-memory caches) where operations complete in microseconds and don't block the event loop.
**Complete Migration Benefits**:
- ✅ Both Vector and Graph databases use ACB patterns
- ✅ Improved connection pooling and resource management
- ✅ Better testability through dependency injection
- ✅ Zero new dependencies (no `duckdb-engine` needed)
- ✅ 100% API compatibility for both adapters
- ✅ Zero breaking changes for users
**Full migration details**: `docs/ACB_MIGRATION_COMPLETE.md`
**Dependency Injection Migration** (**Phase 2.7 Days 1-4 completed**)
- Migrated from manual singleton management to ACB dependency injection
- Centralized DI configuration in `session_buddy/di/` module with `configure()` function
- Provides container-based access via `depends.get_sync(ClassName)` for testable, modular code
- Benefits: Improved testability, reduced coupling, simplified lifecycle management
**Test Infrastructure Cleanup** (Phase 2.7 Day 5)
- Removed 6 unused test factories (65% code reduction in data_factories.py)
- Kept only actively-used factories: `ReflectionDataFactory`, `LargeDatasetFactory`, `SecurityTestDataFactory`
- Removed redundant pytest fixtures from conftest.py
- All 21 functional tests passing after cleanup
**Quality Scoring V2 Algorithm** (Phase 2.7 Day 4)
- New filesystem-based quality assessment in `utils/quality_utils_v2.py`
- Direct file inspection instead of abstracted context (more accurate, less mocking needed)
- Updated test expectations to match V2 scoring ranges
**Async/Await Chain Fixes** (Phase 2.7 Day 4)
- Fixed nested event loop bugs in session_manager.py
- Made `_get_previous_session_info()` and `_read_previous_session_info()` properly async
- Replaced `asyncio.run()` calls within async context with `await`
### Core Components
1. **server.py** (~3,500+ lines): Main MCP server implementation
- **FastMCP Integration**: Uses FastMCP framework for MCP protocol handling
- **Tool Registration**: Centralized registration of all MCP tools and prompts
- **Session Lifecycle**: Complete session management (start, checkpoint, end, status)
- **Permissions System**: Trusted operations management to reduce user prompts
- **Project Analysis**: Context-aware project health monitoring and scoring
- **Git Integration**: Automatic checkpoint commits with metadata tracking
- **Structured Logging**: SessionLogger class with file and console output
1. **reflection_tools.py**: Memory & conversation search system
- **DuckDB Database**: Conversation storage with FLOAT[384] vector embeddings
- **Local ONNX Model**: all-MiniLM-L6-v2 for semantic search (no external API calls)
- **Async Architecture**: Executor threads prevent blocking on embedding generation
- **Fallback Strategy**: Text search when ONNX/transformers unavailable
- **Performance**: Optimized for concurrent access with connection pooling
1. **crackerjack_integration.py**: Code quality integration layer
- **Real-time Parsing**: Crackerjack tool output analysis and progress tracking
- **Quality Metrics**: Aggregation and trend analysis of code quality scores
- **Test Result Analysis**: Pattern detection and success rate tracking
- **Command History**: Learning from effective Crackerjack command usage
### Modular Architecture Components
4. **tools/** directory: Organized MCP tool implementations
- **session_tools.py**: Core session management (start, checkpoint, end, status)
- **memory_tools.py**: Reflection and search functionality
- **search_tools.py**: Advanced search capabilities and pagination
- **crackerjack_tools.py**: Quality integration and progress tracking
- **llm_tools.py**: LLM provider management and configuration
- **team_tools.py**: Collaborative features and knowledge sharing
1. **core/** directory: Core system management
- **session_manager.py**: Session state and lifecycle coordination
1. **di/** directory: Dependency Injection configuration (Phase 2.7)
- **__init__.py**: Centralized DI configuration with `configure()` function
- **constants.py**: Component identifiers and DI-related constants
- Provides: `depends.get_sync(ClassName)` for container-based dependency resolution
- Benefits: Testable components, reduced coupling, simplified lifecycle management
1. **utils/** directory: Shared utilities and helper functions
- **git_operations.py**: Git commit functions and repository management
- **logging.py**: SessionLogger implementation and structured logging
- **quality_utils.py**: Legacy quality assessment (V1)
- **quality_utils_v2.py**: Filesystem-based quality scoring V2 algorithm (Phase 2.7)
### Advanced Components
7. **multi_project_coordinator.py**: Cross-project session coordination
- **Data Models**: `ProjectGroup` and `ProjectDependency` dataclasses with type safety
- **Relationship Types**: `related`, `continuation`, `reference` with semantic meaning
- **Cross-Project Search**: Dependency-aware result ranking across related projects
- **Use Case**: Coordinate microservices, monorepo modules, or related repositories
1. **token_optimizer.py**: Context window and response management
- **TokenOptimizer**: tiktoken-based accurate token counting for GPT models
- **Response Chunking**: Auto-split responses >4000 tokens with cache keys
- **ChunkResult**: Structured pagination with metadata and continuation support
- **Metrics Collection**: TokenUsageMetrics for optimization insights
1. **search_enhanced.py**: Advanced search capabilities
- **Faceted Search**: Filter by project, time, author, content type
- **Aggregations**: Statistical analysis of search results
- **Full-Text Indexing**: FTS5 support in DuckDB for complex queries
1. **interruption_manager.py**: Context preservation during interruptions
- **Smart Detection**: File system monitoring and activity pattern analysis
- **Context Snapshots**: Automatic state preservation during interruptions
- **Recovery**: Session restoration with minimal context loss
1. **serverless_mode.py**: External storage integration
- **ACB Storage Adapters** (v0.9.4+): File, S3, Azure, GCS, Memory backends
- **Legacy Backends** (deprecated): Redis, old S3, old local (removed in v1.0)
- **Session Serialization**: Stateless operation with external persistence
- **Multi-Instance**: Support for distributed Claude Code deployments
- **See**: `docs/MIGRATION_GUIDE_ACB.md` for storage adapter migration
1. **app_monitor.py**: IDE activity and browser documentation monitoring
- **Activity Tracking**: Monitor IDE usage and documentation patterns
- **Context Insights**: Generate insights from development behavior
- **Performance Metrics**: Track development workflow efficiency
1. **natural_scheduler.py**: Natural language scheduling and reminders
- **Time Parsing**: Convert natural language to scheduled tasks
- **Reminder System**: Background service for task notifications
- **Integration**: Works with session management for deadline tracking
1. **worktree_manager.py**: Git worktree management and coordination
- **Worktree Operations**: Create, remove, and manage Git worktrees
- **Session Coordination**: Context switching between worktrees
- **Branch Management**: Coordinate development across multiple branches
### Key Design Patterns & Architectural Decisions
#### 1. **Async-First Architecture**
```text
# Database operations use executor threads to prevent blocking
async def generate_embedding(text: str) -> np.ndarray:
loop = asyncio.get_event_loop()
return await loop.run_in_executor(None, _sync_embedding_generation, text)
# MCP tools handle async/await automatically
@mcp.tool()
async def example_tool(param: str) -> dict[str, Any]:
result = await async_operation(param)
return {"success": True, "data": result}
```
#### 2. **Graceful Degradation Strategy**
- **Optional Dependencies**: Falls back gracefully when `onnxruntime`/`transformers` unavailable
- **Search Fallback**: Text search when embeddings fail, maintaining functionality
- **Memory Constraints**: Automatic chunking and compression for resource-limited environments
- **Error Recovery**: Continues operation despite individual component failures
#### 3. **Local-First Privacy Design**
- **No External APIs**: All embeddings generated locally via ONNX
- **Local Storage**: DuckDB file-based storage in `~/.claude/` directory
- **Zero Network Dependencies**: Functions without internet for core features
- **User Data Control**: Complete data sovereignty with local processing
#### 4. **Selective Auto-Store for High Signal-to-Noise Ratio**
The system intelligently decides when to auto-store checkpoint reflections to maintain high-quality memory:
**Auto-Store Triggers:**
- **Manual Checkpoints**: Always stored (user explicitly requested)
- **Session End**: Always stored (final state capture)
- **Significant Quality Changes**: Delta ≥10 points (configurable)
- **Exceptional Quality**: Score ≥90/100 (configurable)
**Skipped Checkpoints:**
- Routine automatic checkpoints with minimal changes
- Quality changes below threshold (default: \<10 points)
**Configuration Options** (config.py):
```python
enable_auto_store_reflections: bool = True # Global toggle
auto_store_quality_delta_threshold: int = 10 # Minimum delta to trigger
auto_store_exceptional_quality_threshold: int = 90 # Exceptional quality
auto_store_manual_checkpoints: bool = True # Store manual checkpoints
auto_store_session_end: bool = True # Store session end
```
**Semantic Tagging**: Auto-stored reflections get meaningful tags:
- `manual_checkpoint`, `session_end`, `quality_improvement`, `quality_degradation`
- `high-quality`, `good-quality`, `needs-improvement`
- `user-initiated`, `quality-change`, `session-summary`
This approach ensures the reflection database contains only meaningful insights, making searches more effective and preventing storage bloat.
#### 5. **Type-Safe Data Modeling**
```python
@dataclass
class ProjectDependency:
source_project: str
target_project: str
dependency_type: Literal["related", "continuation", "reference"]
description: str | None = None
```
- **Dataclass Architecture**: Immutable, type-safe data structures throughout
- **Modern Type Hints**: Uses Python 3.13+ syntax with pipe unions
- **Runtime Validation**: Pydantic integration with automatic serialization
#### 6. **Performance-Optimized Vector Search**
```sql
-- DuckDB vector similarity with index support
SELECT content, array_cosine_similarity(embedding, $1) as similarity
FROM conversations
WHERE similarity > 0.7
ORDER BY similarity DESC, timestamp DESC
LIMIT 20;
```
- **Vector Indexing**: FLOAT[384] arrays with similarity search optimization
- **Hybrid Search**: Combines semantic similarity with temporal relevance
- **Result Ranking**: Time-decay weighting favors recent conversations
### Session Management Workflow
## Recommended Session Workflow
### Git Repositories (Automatic)
1. **Start Claude Code** - Session auto-initializes
1. **Work normally** - Automatic quality tracking
1. **Run `/checkpoint`** - Manual checkpoints with auto-compaction
1. **Exit any way** - Session auto-cleanup on disconnect
### Non-Git Projects (Manual)
1. **Start with**: `/start` (if you want session management)
1. **Checkpoint**: `/checkpoint` as needed
1. **End with**: `/end` before quitting
### Detailed Tool Functions
1. **Automatic Initialization** (Git repos only):
- **Triggers**: Claude Code connection in git repository
- Sets up ~/.claude directory structure
- Syncs UV dependencies and generates requirements.txt
- Analyzes project context and calculates maturity score
- Sets up session permissions and auto-checkpoints
- **Crash resilient**: Works even after network/system failures
1. **Enhanced Quality Monitoring** (`checkpoint` tool):
- Calculates multi-factor quality score (project health, permissions, tools)
- **NEW: Automatic context compaction when needed**
- Creates automatic Git commits with checkpoint metadata
- Provides workflow optimization recommendations
- Intelligent analysis of development patterns
1. **Automatic Session Cleanup** (Git repos only):
- **Triggers**: Any disconnect, quit, crash, or network failure
- Generates session handoff documentation
- Performs final quality assessment
- Cleans up session artifacts
- **Zero manual intervention** required
### Memory System Architecture
**DuckDB Schema**: Core tables with vector support:
```sql
CREATE TABLE conversations (
id TEXT PRIMARY KEY,
content TEXT,
embedding FLOAT[384], -- all-MiniLM-L6-v2 vectors
project TEXT,
timestamp TIMESTAMP
);
CREATE TABLE reflections (
id TEXT PRIMARY KEY,
content TEXT,
embedding FLOAT[384],
tags TEXT[]
);
```
**Vector Search Implementation**:
- **Local ONNX Model**: all-MiniLM-L6-v2 with 384-dimensional vectors
- **Cosine Similarity**: `array_cosine_similarity(embedding, query_vector)` in DuckDB
- **Fallback Strategy**: Text search when embeddings unavailable or ONNX missing
- **Async Execution**: Embedding generation runs in executor threads to avoid blocking
**Multi-Project Coordination**:
- `ProjectGroup` and `ProjectDependency` tables for relationship modeling
- Cross-project search with dependency-aware result ranking
- Session linking with typed relationships (`continuation`, `reference`, `related`)
## Configuration & Integration
### MCP Configuration (.mcp.json)
```json
{
"mcpServers": {
"session-mgmt": {
"command": "python",
"args": ["-m", "session_buddy.server"],
"cwd": "/path/to/session-buddy",
"env": {
"PYTHONPATH": "/path/to/session-buddy"
}
}
}
}
```
### Directory Structure
The server uses the ~/.claude directory for data storage:
- **~/.claude/logs/**: Session management logging
- **~/.claude/data/**: Reflection database storage
### Environment Variables
- `PWD`: Used to detect current working directory
### ACB Storage Adapters (v0.9.4+)
**New**: Session-mgmt-mcp now uses ACB (Asynchronous Component Base) storage adapters for improved reliability and multi-cloud support.
**Recommended Backends**:
- `file` - Local file storage (default, best for development)
- `s3` - AWS S3/MinIO (production cloud storage)
- `azure` - Azure Blob Storage (Azure deployments)
- `gcs` - Google Cloud Storage (GCP deployments)
- `memory` - In-memory storage (testing only)
**Configuration** (`settings/session-mgmt.yaml`):
```yaml
storage:
default_backend: "file"
file:
local_path: "${SESSION_STORAGE_PATH:~/.claude/data/sessions}"
auto_mkdir: true
s3:
bucket_name: "${S3_BUCKET:session-mgmt}"
endpoint_url: "${S3_ENDPOINT:}"
region: "${S3_REGION:us-east-1}"
```
**Benefits**:
- ✅ Multiple cloud providers (S3, Azure, GCS)
- ✅ Environment variable support
- ✅ Better connection pooling & error handling
- ✅ 91% code reduction in storage layer
- ✅ 100% backward compatibility
**Migration**: See `docs/MIGRATION_GUIDE_ACB.md` for detailed migration instructions.
**Legacy Backends** (deprecated, removed in v1.0):
- `redis`, `local`, old `s3`, `acb` cache
## Development Notes
### Dependencies & Isolation
- Uses isolated virtual environment to prevent conflicts
- **Core Dependencies**: `fastmcp>=2`, `duckdb>=0.9`, `pydantic>=2.0`, `tiktoken>=0.5`, `crackerjack`
- **Embedding System**: `onnxruntime>=1.15`, `transformers>=4.21` (included in core)
- **Development Tools**: `pytest>=7`, `pytest-asyncio>=0.21`, `hypothesis>=6.70`, `coverage>=7`
- Falls back gracefully when embedding system unavailable (text search mode)
### Testing Architecture
The project uses a comprehensive pytest-based testing framework with multiple test categories:
**Test Structure:**
- **Unit Tests** (`tests/unit/`): Core functionality testing
- Session permissions and lifecycle management
- Reflection database operations with async/await patterns
- Mock fixtures for isolated component testing
- **Integration Tests** (`tests/integration/`): Complete MCP workflow validation
- End-to-end session management workflows
- MCP tool registration and execution
- Database integrity with concurrent operations
- **Functional Tests** (`tests/functional/`): Feature-level testing
- Cross-component integration testing
- User workflow simulation
- Performance and reliability validation
**Key Testing Features:**
- **Async/await support** for MCP server testing
- **Temporary database fixtures** with automatic cleanup
- **Data factories** for realistic test data generation
- **Performance metrics** collection and baseline comparison
- **Mock MCP server** creation for isolated testing
**Testing Commands:**
```bash
# Run all tests
pytest
# Run specific test types
pytest tests/unit/
pytest tests/integration/
pytest -m performance
# Run with coverage
pytest --cov=session_buddy --cov-report=term-missing
# Quick development tests (exclude slow tests)
pytest -m "not slow"
```
## Available MCP Tools
**Total: 70+ specialized tools** across 10 functional categories. See [README.md](README.md#available-mcp-tools) for complete list.
### Core Session Management (8 tools)
- **`start`** - Comprehensive session initialization with project analysis, UV sync, and memory setup
- **`checkpoint`** - Mid-session quality assessment with V2 scoring and automatic context compaction
- **`end`** - Complete session cleanup with learning capture and handoff documentation
- **`status`** - Current session overview with health checks and diagnostics
- **`permissions`** - Manage trusted operations to reduce permission prompts
- **`auto_compact`** - Automatic context window compaction when needed
- **`quality_monitor`** - Real-time quality monitoring and tracking
- **`session_welcome`** - Session connection information and continuity
### Memory & Conversation Search (14 tools)
**Search & Retrieval**:
- **`search_reflections`** / **`reflect_on_past`** - Semantic search using local AI embeddings
- **`quick_search`** - Fast overview with count and top results
- **`search_summary`** - Aggregated insights without individual results
- **`get_more_results`** - Pagination for large result sets
- **`search_by_file`**, **`search_by_concept`**, **`search_code`**, **`search_errors`**, **`search_temporal`** - Targeted searches
**Storage**:
- **`store_reflection`** - Store insights with tagging
- **`reflection_stats`** - Memory system statistics
- **`reset_reflection_database`** - Reset/rebuild memory
### Advanced Tool Categories
**Crackerjack Integration (11 tools)**:
- Command execution (`crackerjack_run`, `execute_crackerjack_command`)
- Quality metrics (`crackerjack_metrics`, `crackerjack_quality_trends`)
- Pattern detection (`crackerjack_patterns`, `analyze_crackerjack_test_patterns`)
- Health monitoring (`crackerjack_health_check`, `crackerjack_help`)
**LLM Provider Management (5 tools)**:
- `list_llm_providers`, `test_llm_providers`, `generate_with_llm`, `chat_with_llm`, `configure_llm_provider`
**Serverless Sessions (8 tools)**:
- External storage integration (Redis, S3, local) for stateless operation
**Team Collaboration (4 tools)**:
- `create_team`, `search_team_knowledge`, `get_team_statistics`, `vote_on_reflection`
**Multi-Project Coordination (4 tools)**:
- `create_project_group`, `add_project_dependency`, `search_across_projects`, `get_project_insights`
**Plus**: App Monitoring (5), Interruption Management (7), Natural Scheduling (5), Git Worktree (3), Advanced Search (3)
## Token Optimization and Response Chunking
The server includes sophisticated token management to handle large responses:
**Token Management Architecture**:
- **TokenOptimizer** class with tiktoken integration for accurate token counting
- **Response Chunking**: Automatically splits responses >4000 tokens into paginated chunks
- **ChunkResult** dataclass structure:
```python
@dataclass
class ChunkResult:
chunks: list[str] # Paginated content chunks
total_chunks: int # Total number of chunks
current_chunk: int # Current chunk index
cache_key: str # Unique cache identifier
metadata: dict[str, Any] # Additional context
```
**Usage Pattern for Large Responses**:
```python
# Large response automatically chunked
result = await some_large_operation()
if result.get("chunked"):
print(f"Response chunked: {result['current_chunk']}/{result['total_chunks']}")
# Use get_cached_chunk tool to retrieve additional chunks
```
## Integration with Crackerjack
This project integrates deeply with [Crackerjack](https://github.com/lesleslie/crackerjack) for code quality and development workflow automation:
- **Quality Commands**: Use `crackerjack lint`, `crackerjack typecheck`, etc. for code quality
- **MCP Integration**: Crackerjack is configured as an MCP server in .mcp.json
- **Progress Tracking**: `crackerjack_integration.py` provides real-time analysis parsing
- **Test Integration**: Crackerjack handles test execution, this project handles results analysis
## Development Guidelines
### Adding New MCP Tools
1. Define function with `@mcp.tool()` decorator in appropriate tools/ module
1. Add corresponding prompt with `@mcp.prompt()` for slash command support
1. Import and register in main server.py
1. Update status() tool to report new functionality
1. Add tests in appropriate test category
### Extending Memory System
1. Add new table schemas in reflection_tools.py:\_ensure_tables()
1. Implement storage/retrieval methods in ReflectionDatabase class
1. Add corresponding MCP tools in tools/memory_tools.py
1. Update reflection_stats() to include new metrics
1. Add performance tests for new operations
### Testing New Features
1. Add unit tests for individual functions in `tests/unit/`
1. Add integration tests for MCP tool workflows in `tests/integration/`
1. Add functional tests for complete features in `tests/functional/`
1. Use `tests/fixtures/` for test data factories and mock fixtures
1. Ensure coverage is maintained via `pytest --cov=session_buddy`
## Configuration Files
### pyproject.toml Configuration
The project uses modern Python tooling with strict quality settings:
- **Python 3.13+** required with latest language features
- **Ruff**: Code formatting and linting with complexity limits (max 15)
- **Pytest**: Comprehensive testing with async/await, coverage, and benchmarking
- **Optional Dependencies**: `[embeddings]` for semantic search, `[dev]` for development tools
### MCP Server Configuration
The `.mcp.json` shows integration with multiple MCP servers:
- **session-mgmt**: This server (local development mode)
- **crackerjack**: Code quality tools and workflow automation
- **ast-grep**: Code analysis and pattern matching
- Plus additional servers for GitHub, GitLab, memory, etc.
### Testing Configuration (conftest.py)
- Async/await support for MCP server testing
- Temporary database fixtures with automatic cleanup
- Mock MCP server creation for isolated testing
- Performance baseline comparisons
## Modern Development Patterns
### 1. **Async/Await Best Practices**
```text
# ✅ Correct: Use executor for blocking operations
async def generate_embedding(text: str) -> np.ndarray:
loop = asyncio.get_event_loop()
return await loop.run_in_executor(None, _sync_embedding_generation, text)
# ❌ Avoid: Blocking the event loop
async def bad_embedding(text: str) -> np.ndarray:
return onnx_session.run(None, {"input": text}) # Blocks event loop
```
### 2. **Database Connection Management**
```text
# ✅ Correct: Context manager with connection pooling
async def store_conversation(content: str) -> str:
async with ReflectionDatabase() as db:
return await db.store_conversation(content)
# ✅ Correct: Batch operations for efficiency
async def bulk_store(conversations: list[str]) -> list[str]:
async with ReflectionDatabase() as db:
return await db.bulk_store_conversations(conversations)
```
### 3. **Error Handling Strategy**
```text
# ✅ Correct: Graceful degradation with logging
async def search_with_fallback(query: str) -> list[SearchResult]:
try:
# Try semantic search first
return await semantic_search(query)
except (ImportError, RuntimeError) as e:
logger.info(f"Semantic search unavailable: {e}. Using text search.")
return await text_search(query)
except Exception as e:
logger.error(f"Search failed: {e}")
return []
```
### 4. **MCP Tool Development Pattern**
```text
@mcp.tool()
async def example_tool(param1: str, param2: int | None = None) -> dict[str, Any]:
"""
Tool description for Claude Code.
Args:
param1: Required parameter with clear description
param2: Optional parameter with default value
Returns:
Structured response with success/error handling
"""
try:
# Validate inputs
if not param1.strip():
return {"success": False, "error": "param1 cannot be empty"}
# Perform operation with proper async handling
result = await perform_async_operation(param1, param2)
return {
"success": True,
"data": result,
"metadata": {
"timestamp": datetime.now().isoformat(),
"execution_time_ms": 42,
},
}
except Exception as e:
logger.error(f"Tool execution failed: {e}")
return {"success": False, "error": str(e)}
```
## Troubleshooting Guide
### Common Issues & Solutions
#### 1. **MCP Server Not Loading**
```bash
# Check imports
python -c "import session_buddy; print('✅ Package imports successfully')"
# Verify FastMCP setup
python -c "from session_buddy.server import mcp; print('✅ MCP server configured')"
# Check for missing dependencies
python -c "
try:
import duckdb, numpy, tiktoken
print('✅ Core dependencies available')
except ImportError as e:
print(f'❌ Missing dependency: {e}')
"
```
#### 2. **Memory/Embedding Issues**
```bash
# Test embedding system
python -c "
from session_buddy.reflection_tools import ReflectionDatabase
import asyncio
async def test():
try:
async with ReflectionDatabase() as db:
result = await db.test_embedding_system()
print(f'✅ Embedding system: {result}')
except Exception as e:
print(f'⚠️ Embedding fallback mode: {e}')
asyncio.run(test())
"
# Reinstall all dependencies if needed
uv sync
```
#### 3. **Database Connection Problems**
```bash
# Check DuckDB installation
python -c "import duckdb; print(f'✅ DuckDB version: {duckdb.__version__}')"
# Test database connection
python -c "
import duckdb
conn = duckdb.connect(':memory:')
print('✅ DuckDB connection successful')
conn.close()
"
# Check file permissions
ls -la ~/.claude/data/ 2>/dev/null || echo "Creating ~/.claude/data/" && mkdir -p ~/.claude/data/
```
#### 4. **Performance Issues**
```bash
# Run performance diagnostics
pytest -m performance --verbose
# Check memory usage patterns
python -c "
import psutil
import os
print(f'Memory usage: {psutil.Process(os.getpid()).memory_info().rss / 1024 / 1024:.1f} MB')
"
# Enable detailed logging
PYTHONPATH=. python -m session_buddy.server --debug
```
### Development Environment Setup Issues
#### **UV Package Manager**
```bash
# Verify UV installation
uv --version || curl -LsSf https://astral.sh/uv/install.sh | sh
# Reset environment if corrupted
rm -rf .venv && uv sync --group dev
# Check for conflicting dependencies
uv pip check
```
#### **Python Version Compatibility**
```bash
# Verify Python 3.13+ requirement
python --version # Should be 3.13+
# Check for async/await compatibility
python -c "
import sys
print(f'Python {sys.version}')
assert sys.version_info >= (3, 13), 'Python 3.13+ required'
print('✅ Python version compatible')
"
```
### Coding Standards & Best Practices
#### Core Philosophy (from RULES.md)
- **EVERY LINE OF CODE IS A LIABILITY**: The best code is no code
- **DRY (Don't Repeat Yourself)**: If you write it twice, you're doing it wrong
- **YAGNI (You Ain't Gonna Need It)**: Build only what's needed NOW
- **KISS (Keep It Simple, Stupid)**: Complexity is the enemy of maintainability
#### Type Safety Requirements
- **Always use comprehensive type hints** with modern Python 3.13+ syntax
- **Import typing as `import typing as t`** and prefix all typing references
- **Use built-in collection types**: `list[str]` instead of `t.List[str]`
- **Use pipe operator for unions**: `str | None` instead of `Optional[str]`
#### Development Practices
1. **Always use async/await** for database and file operations
1. **Test with both embedding and fallback modes** during development
1. **Include comprehensive error handling** with graceful degradation
1. **Use type hints and dataclasses** for data modeling
1. **Follow the testing pattern**: unit → integration → functional
1. **Run pre-commit workflow** before any commits
1. **Monitor token usage** and response chunking during development
1. **Test cross-project coordination** features with multiple repositories
### Key Architecture Insights for Development
When working with this codebase, remember these architectural patterns:
1. **FastMCP Integration**: All tools use `@mcp.tool()` decorators and return structured responses
1. **Async-First Design**: Database operations run in executor threads to avoid blocking
1. **Local Privacy**: No external API calls required - embeddings generated locally
1. **Graceful Fallback**: System continues working even when optional features fail
1. **Modular Structure**: Tools are organized by functionality in separate modules
1. **Session Lifecycle**: Init → Work → Checkpoint → End workflow with persistent memory
<!-- CRACKERJACK INTEGRATION START -->
## Crackerjack Integration for session-buddy
This project uses crackerjack for Python project management and quality assurance.
## Recommended Claude Code Agents
For optimal development experience with this crackerjack-enabled project, use these specialized agents:
### **Primary Agents (Use for all Python development)**
- **🏗️ crackerjack-architect**: Expert in crackerjack's modular architecture and Python project management patterns. **Use PROACTIVELY** for all feature development, architectural decisions, and ensuring code follows crackerjack standards from the start.
- **🐍 python-pro**: Modern Python development with type hints, async/await patterns, and clean architecture
- **🧪 pytest-hypothesis-specialist**: Advanced testing patterns, property-based testing, and test optimization
### **Task-Specific Agents**
- **🧪 crackerjack-test-specialist**: Advanced testing specialist for complex testing scenarios and coverage optimization
- **🏗️ backend-architect**: System design, API architecture, and service integration patterns
- **🔒 security-auditor**: Security analysis, vulnerability detection, and secure coding practices
### **Agent Usage Patterns**
```bash
# Start development with crackerjack-compliant architecture
Task tool with subagent_type="crackerjack-architect" for feature planning
# Implement with modern Python best practices
Task tool with subagent_type="python-pro" for code implementation
# Add comprehensive testing
Task tool with subagent_type="pytest-hypothesis-specialist" for test development
# Security review before completion
Task tool with subagent_type="security-auditor" for security analysis
```
**💡 Pro Tip**: The crackerjack-architect agent automatically ensures code follows crackerjack patterns from the start, eliminating the need for retrofitting and quality fixes.
## Crackerjack Quality Standards
This project follows crackerjack's clean code philosophy:
### **Core Principles**
- **EVERY LINE OF CODE IS A LIABILITY**: The best code is no code
- **DRY (Don't Repeat Yourself)**: If you write it twice, you're doing it wrong
- **YAGNI (You Ain't Gonna Need It)**: Build only what's needed NOW
- **KISS (Keep It Simple, Stupid)**: Complexity is the enemy of maintainability
### **Quality Rules**
- **Cognitive complexity ≤15** per function (automatically enforced)
- **Coverage maintenance**: Never decrease coverage, always improve incrementally
- **Type annotations required**: All functions must have return type hints
- **Security patterns**: No hardcoded paths, proper temp file handling
- **Python 3.13+ modern patterns**: Use `|` unions, pathlib over os.path
## Development Workflow
### **Quality Commands**
```bash
# Quality checks (fast feedback during development)
python -m crackerjack
# With comprehensive testing
python -m crackerjack -t
# AI agent mode with autonomous fixing
python -m crackerjack --ai-fix -t
# Full release workflow
python -m crackerjack -a patch
```
### **Recommended Workflow**
1. **Plan with crackerjack-architect**: Ensure proper architecture from the start
1. **Implement with python-pro**: Follow modern Python patterns
1. **Test comprehensively**: Use pytest-hypothesis-specialist for robust testing
1. **Run quality checks**: `python -m crackerjack -t` before committing
1. **Security review**: Use security-auditor for final validation
## Important Instructions
- **Use crackerjack-architect agent proactively** for all significant code changes
- **Maintain code quality standards** - complexity ≤15, comprehensive types
- **Follow crackerjack patterns** - the tools will enforce quality automatically
- **Leverage AI agent auto-fixing** - `python -m crackerjack --ai-fix -t` for autonomous quality fixes
______________________________________________________________________
*This project is enhanced by crackerjack's intelligent Python project management.*
<!-- CRACKERJACK INTEGRATION END -->
