Session Buddy

A session management MCP server for Claude Code.

A dedicated MCP server that manages session lifecycle, searchable memory, and cross-project intelligence for Claude Code sessions.

Quick Links

• What Makes Session Buddy Unique?

• Features

• Automatic Session Management

• Integration with Crackerjack

• Development

Quality & CI

Crackerjack is the standard quality-control and CI/CD gate for Session Buddy. Use the same Crackerjack workflow locally that the project expects in CI.

What Makes Session Buddy Unique?

Session Buddy focuses on three things that set it apart from a simple session log:

Automatic Knowledge Capture

Session Buddy can extract structured insights from conversation patterns and make them searchable in later sessions. That reduces manual note-taking and turns normal development work into reusable project memory.

Cross-Project Intelligence

Session Buddy can surface relevant knowledge across related repos, services, or packages, which is especially useful for monorepos, microservices, and tightly coupled project families.

Privacy-First Architecture

• Local processing by default

• Local embedding support

• No required external API dependency for core workflows

• Fast search and retrieval oriented toward interactive use

Features

Advanced Analytics & Integration

Session Buddy extends core session management with real-time monitoring, analytics, and cross-session learning.

Real-Time Monitoring

• WebSocket Server - Live dashboard streaming at 1-second intervals

  • Top 10 most active skills displayed in real-time

  • Performance anomaly detection with Z-score analysis

  • Client subscriptions (all skills or specific skill monitoring)

• Prometheus Metrics - Monitoring export

  • 5 metric types: Counters, Histograms, Gauges

  • HTTP endpoint on port 9090 for scraping

  • Thread-safe updates for concurrent access

Advanced Analytics

• Predictive Models - ML-based skill success prediction

  • RandomForest classifier with 7 features

  • 30-day historical training window

  • Feature importance analysis

• A/B Testing Framework - Experiment with recommendation strategies

  • Deterministic user assignment (SHA-256 hashing)

  • Statistical significance testing (t-test, p < 0.05)

  • Automated winner determination

• Time-Series Analysis - Trend detection and forecasting

  • Linear regression trend detection

  • Hourly aggregation for dashboards

  • Anomaly detection using Z-scores

Cross-Session Learning

• Collaborative Filtering - Learn from similar users

  • Jaccard similarity for user matching

  • Personalized recommendations

  • SHA-256 privacy hashing for user IDs

• Community Baselines - Global skill effectiveness

  • Cross-user aggregation

  • Percentile rankings

  • User vs global comparisons

Tool Integration

• Crackerjack Integration - Quality gate tracking

  • Phase mapping to workflow stages

  • Automatic failure recommendations

  • ASCII workflow visualizations

• IDE Plugin Protocol - Context-aware recommendations

  • Code pattern detection (tests, imports, async)

  • Language-specific skill patterns

  • Keyboard shortcut management

• CI/CD Tracking - Pipeline analytics

  • Stage-by-stage monitoring

  • Bottleneck identification (< 80% success)

  • JSON export for dashboards

Skills Taxonomy

• Categories - Organized skill domains

  • Code Quality, Testing, Documentation, Deployment, etc.

  • 6 predefined categories

  • Multi-modal skill types (code → diagnostics, testing → test_results)

• Dependencies - Co-occurrence patterns

  • Lift score calculation

  • Relationship mapping

  • Workflow-aware recommendations

Performance:

• Real-time metrics: < 100ms

• Anomaly detection: < 200ms

• Collaborative filtering: < 200ms

• MCP tools: < 50ms

Core Session Management

• Session Initialization: Setup with UV dependency management, project analysis, and automation tools

• Quality Checkpoints: Mid-session quality monitoring with workflow analysis and optimization recommendations

• Session Cleanup: Cleanup with learning capture and handoff file creation

• Status Monitoring: Real-time session status and project context analysis

• Auto-Generated Shortcuts: Automatically creates /start, /checkpoint, and /end Claude Code slash commands

Intelligence Features

Session Buddy includes local knowledge-capture and sharing features that help work carry across sessions and repos:

Automatic Insights Capture & Injection

What It Does:

• Automatically extracts educational insights from your conversations using deterministic pattern matching

• Stores insights with semantic embeddings for later retrieval

• Prevents duplicate capture through SHA-256 content hashing

• Makes insights available across sessions via semantic search

How It Works:

When you use explanatory mode (like this session!), Session Buddy automatically captures insights marked with the ★ Insight ───── delimiter:

Some explanation text.

`★ Insight ─────────────────────────────────────`
Always use async/await for database operations to prevent blocking the event loop
`─────────────────────────────────────────────────`

More text here.

Multi-Point Capture Strategy:

• Checkpoint Capture: Extracts insights during mid-session quality checkpoints

• Session End Capture: Additional extraction when session ends

• Deduplication: SHA-256 hashing prevents storing duplicate insights

• Session-Level Tracking: Maintains hash set across entire session

Benefits:

• ✅ Automatic Capture: Works automatically with explanatory mode

• ✅ No Hallucination: Rule-based extraction (not AI-generated)

• ✅ Conservative Capture: Better to miss an insight than invent one

• ✅ Measured Performance: <50ms extraction, <20ms semantic search

• ✅ Privacy-First: All processing done locally, no external APIs

Documentation: See docs/features/INSIGHTS_CAPTURE.md for complete details

Global Intelligence & Pattern Sharing

What It Does:

• Share knowledge across related projects automatically

• Track project dependencies (uses, extends, references, shares_code)

• Search across all projects with dependency-aware ranking

• Coordinate microservices, monorepo modules, or related repositories

How It Works:

Create groups of related projects and define their relationships:

# Create project group
group = ProjectGroup(
    name="microservices-app",
    projects=["auth-service", "user-service", "api-gateway"],
    description="Authentication and user management microservices",
)

# Define dependencies
deps = [
    ProjectDependency(
        source_project="user-service",
        target_project="auth-service",
        dependency_type="uses",
        description="User service depends on auth service for validation",
    ),
    ProjectDependency(
        source_project="api-gateway",
        target_project="user-service",
        dependency_type="extends",
        description="Gateway extends user service with rate limiting",
    ),
]

Cross-Project Search:

• Search across related projects automatically

• Results ranked by dependency relationships

• Understand how solutions propagate across your codebase

Benefits:

• ✅ Knowledge Reuse: Solutions found in one project help with related projects

• ✅ Dependency Awareness: Understand how changes ripple across projects

• ✅ Coordinated Development: Work effectively across multiple codebases

• ✅ Semantic Understanding: Find patterns even when projects use different terminology

Use Cases:

• Microservices: Coordinate related services with shared patterns

• Monorepos: Manage multiple packages/modules in one repository

• Multi-Repo: Track patterns across separate but related repositories

Automatic Session Management

For Git Repositories:

• ✅ Automatic initialization when Claude Code connects

• ✅ Automatic cleanup when session ends (quit, crash, or network failure)

• ✅ Automatic compaction during checkpoints

• ✅ Automatic in supported workflows

For Non-Git Projects:

• 📝 Use /start for manual initialization

• 📝 Use /end for manual cleanup

• 📝 Full session management features available on-demand

The server automatically detects git repositories and manages the session lifecycle with crash resilience and network failure recovery. Non-git projects retain manual control for flexible workflow management.

Session Lifecycle Visualization

stateDiagram-v2
    [*] --> GitRepo: Claude Code Connects
    [*] --> ManualInit: Non-Git Project

    GitRepo --> AutoStart: Auto-detect Git
    AutoStart: Initialize Session
    AutoStart --> Working: Development

    ManualInit --> ManualStart: User runs /start
    ManualStart: Initialize Session
    ManualStart --> Working: Development

    state Working {
        [*] --> Active
        Active --> Checkpoint: /checkpoint
        Checkpoint --> Active: Continue Work
        Active --> Monitoring: Track Quality
        Monitoring --> Active
    }

    Working --> AutoEnd: Disconnect/Quit
    Working --> ManualEnd: User runs /end

    AutoEnd: Auto Cleanup
    AutoEnd --> [*]: Session Handoff

    ManualEnd: Manual Cleanup
    ManualEnd --> [*]: Session Handoff

    note right of AutoStart
        Automatic Features:
        - UV sync
        - Project analysis
        - Setup .claude/
        - Create shortcuts
    end note

    note right of AutoEnd
        Crash Resilient:
        - Any disconnect
        - Network failure
        - System crash
        All handled gracefully
    end note

Git Repository Auto-Management Flow

flowchart TD
    Start([Claude Code Connects]) --> Detect{Git Repo?}

    Detect -->|Yes| AutoInit[Auto-Initialize]
    Detect -->|No| Manual{User runs /start?}

    AutoInit --> Setup[Session Setup]
    Setup --> UV[UV Sync]
    UV --> Analysis[Project Analysis]
    Analysis --> CreateDir[Create .claude/]
    CreateDir --> Shortcuts[Create Shortcuts]
    Shortcuts --> Ready([Session Ready])

    Manual -->|Yes| ManualInit[/start Command]
    Manual -->|No| Idle([No Session])
    ManualInit --> Ready

    Ready --> Work[Development Work]
    Work --> Checkpoint{Mid-session?}
    Checkpoint -->|Yes| Compact[Auto-Compact Context]
    Checkpoint -->|No| Continue{Continue?}
    Compact --> Work
    Continue -->|Yes| Work
    Continue -->|No| End

    Work --> End{Disconnect?}
    End -->|Yes| AutoCleanup[Auto Cleanup]
    End -->|No| Work

    AutoCleanup --> Handoff[Create Handoff Doc]
    Handoff --> Complete([Session Complete])

    Idle --> Manual
    Manual --> Complete

    style AutoInit fill:#c8e6c9
    style AutoCleanup fill:#c8e6c9
    style ManualInit fill:#fff9c4
    style Ready fill:#b2dfdb
    style Complete fill:#ffccbc

Available MCP Tools

This server provides 85+ specialized tools organized into 12 functional categories. For a complete list of tools, see the MCP Tools Reference.

Phase 4 Analytics Tools

Real-Time Monitoring:

• get_real_time_metrics - Get top skills by usage with live dashboard data

• detect_anomalies - Detect performance anomalies using Z-score analysis

Advanced Analytics:

• get_skill_trend - Analyze skill effectiveness trends over time

• get_collaborative_recommendations - Get personalized recommendations from similar users

• get_community_baselines - Compare user performance vs global community

• get_skill_dependencies - Explore skill co-occurrence patterns

Intelligence Tools

Insights Management:

• search_insights - Search captured insights by topic or query with semantic matching

• insights_statistics - View statistics about captured insights (types, topics, confidence scores)

• Wildcard search with * to view all captured insights

Multi-Project Coordination:

• create_project_group - Create groups of related projects for coordinated development

• add_project_dependency - Track relationships between projects (uses, extends, references)

• search_across_projects - Search across all projects with dependency-aware ranking

• get_project_insights - Get cross-project insights and collaboration opportunities

Team Collaboration:

• create_team - Create teams for knowledge sharing

• search_team_knowledge - Search across team reflections with access control

• get_team_statistics - View team activity and contribution metrics

• vote_on_reflection - Upvote/downvote team reflections for quality filtering

Core Session Management

• start - Session initialization with project analysis and memory setup

• checkpoint - Mid-session quality assessment with workflow analysis

• end - Complete session cleanup with learning capture

• status - Current session overview with health checks

Memory & Conversation Search

• store_reflection - Store insights with tagging and embeddings

• quick_search - Fast overview search with count and top results

• search_summary - Aggregated insights without individual result details

• get_more_results - Pagination support for large result sets

• search_by_file - Find conversations tied to a specific file

• search_by_concept - Semantic search by concept with optional file context

Knowledge Graph (DuckPGQ)

• Entity and relationship management for project knowledge

• SQL/PGQ graph queries for complex relationship analysis

• See Oneiric Migration Guide

All tools use local processing for privacy, with DuckDB vector storage (FLOAT[384] embeddings) and ONNX-based semantic search requiring no external API calls.

Integration with Crackerjack

Session Buddy includes deep integration with Crackerjack, the AI-driven Python development platform:

Key Features:

• Quality Metrics Tracking: Automatically captures and tracks quality scores over time

• Test Result Monitoring: Learns from test patterns, failures, and successful fixes

• Error Pattern Recognition: Remembers how specific errors were resolved and suggests solutions

Example Workflow:

1. 🚀 Session Buddy start - Sets up your session with accumulated context from previous work

2. 🔧 Crackerjack runs quality checks and applies AI agent fixes to resolve issues

3. 💾 Session Buddy captures successful patterns and error resolutions

4. 🧠 Next session starts with all accumulated knowledge

For detailed information on Crackerjack integration, see Crackerjack Integration Guide.

Installation

From Source

# Clone the repository
git clone https://github.com/lesleslie/session-buddy.git
cd session-buddy

# Install with all dependencies (development + testing)
uv sync --group dev

# Or install minimal production dependencies only
uv sync

# Or use pip (for production only)
pip install session-buddy

MCP Configuration

Add to your project's .mcp.json file:

{
  "mcpServers": {
    "session-buddy": {
      "command": "python",
      "args": ["-m", "session_buddy.server"],
      "cwd": "/path/to/session-buddy",
      "env": {
        "PYTHONPATH": "/path/to/session-buddy"
      }
    }
  }
}

Alternative: Use Script Entry Point

If installed with pip/uv, you can use the script entry point:

{
  "mcpServers": {
    "session-buddy": {
      "command": "session-buddy",
      "args": [],
      "env": {}
    }
  }
}

Dependencies: Requires Python 3.13+. For a complete list of dependencies, see pyproject.toml.

Setting Up Semantic Search (Optional)

Session Buddy includes semantic search capabilities using local AI embeddings with no external API dependencies.

Current Status:

• ✅ Text Search: Works out of the box (fast, keyword-based)

• ✅ Semantic Search: Works with ONNX model (no PyTorch required!)

For Text Search (Default): No additional setup needed! The system uses full-text search with FTS5 for fast, accurate results.

For Semantic Search (Optional):

The system uses pre-converted ONNX models for efficient semantic search without requiring PyTorch:

# Download the pre-converted ONNX model (one-time setup)
python scripts/download_embedding_model.py

This downloads the Xenova/all-MiniLM-L6-v2 model (~100MB) which includes:

• Pre-converted ONNX model (no PyTorch needed!)

• 384-dimensional embeddings for semantic similarity

• Fast CPU inference with ONNX Runtime

Note: Text search is highly effective and recommended for most use cases. Semantic search provides enhanced conceptual matching by understanding meaning beyond keywords.

Usage

Once configured, the following slash commands become available in Claude Code:

Primary Session Commands:

• /session-buddy:start - Full session initialization

• /session-buddy:checkpoint - Quality monitoring checkpoint with scoring

• /session-buddy:end - Complete session cleanup with learning capture

• /session-buddy:status - Current status overview with health checks

Auto-Generated Shortcuts: After running /session-buddy:start once, these shortcuts are automatically created:

• /start → /session-buddy:start

• /checkpoint [name] → /session-buddy:checkpoint

• /end → /session-buddy:end

These shortcuts are created in ~/.claude/commands/ and work across all projects

Memory & Search Commands:

• /session-buddy:quick_search - Fast search with overview results

• /session-buddy:search_summary - Aggregated insights without full result lists

• /session-buddy:get_more_results - Paginate search results

• /session-buddy:search_by_file - Find results tied to a specific file

• /session-buddy:search_by_concept - Semantic search by concept

• /session-buddy:search_code - Search code-related conversations

• /session-buddy:search_errors - Search error and failure discussions

• /session-buddy:search_temporal - Search using time expressions

• /session-buddy:store_reflection - Store important insights with tagging

• /session-buddy:reflection_stats - Stats about the reflection database

For running the server directly in development mode:

python -m session_buddy.server
# or
session-buddy

Memory System

Built-in Conversation Memory:

• Local Storage: DuckDB database at ~/.claude/data/reflection.duckdb

• Embeddings: Local ONNX models for semantic search (no external API needed)

• Privacy: Everything runs locally with no external dependencies

• Cross-Project: Conversations tagged by project context for organized retrieval

Search Capabilities:

• Semantic Search: Vector similarity matching with customizable thresholds

• Time Decay: Recent conversations prioritized in results

• Filtering: Search by project context or across all projects

Data Storage

This server manages its data locally in the user's home directory:

• Memory Storage: ~/.claude/data/reflection.duckdb

• Session Logs: ~/.claude/logs/

• Configuration: Uses pyproject.toml and environment variables

Recommended Session Workflow

1. Initialize Session: /session-buddy:start - Sets up project context, dependencies, and memory system

2. Monitor Progress: /session-buddy:checkpoint (every 30-45 minutes) - Quality scoring and optimization

3. Search Past Work: /session-buddy:quick_search or /session-buddy:search_summary - Find relevant past conversations and solutions

4. Store Important Insights: /session-buddy:store_reflection - Capture key learnings for future sessions

5. End Session: /session-buddy:end - Final assessment, learning capture, and cleanup

Why Teams Use It

Intelligence & Knowledge Sharing

• Automatic Insights Capture: Extracts educational insights from conversations without manual effort

• Semantic Pattern Discovery: Find related insights across sessions using vector embeddings

• Cross-Project Learning: Share knowledge between related projects automatically

• Dependency Awareness: Understand how solutions propagate across your codebase

• Team Knowledge Base: Collaborative filtering and voting for best practices

• No Hallucination: Rule-based extraction ensures only high-quality insights are captured

Coverage

• Session Quality: Real-time monitoring and optimization

• Memory Persistence: Cross-session conversation retention

• Project Structure: Context-aware development workflows

Reduced Friction

• Single Command Setup: One /session-buddy:start sets up everything

• Local Dependencies: No external API calls or services required

• Permission Memory: Reduces repeated permission prompts

• Automated Workflows: Structured processes for common tasks

Enhanced Productivity

• Quality Scoring: Guides session effectiveness

• Built-in Memory: Enables building on past work automatically

• Project Templates: Accelerates development setup

• Knowledge Persistence: Maintains context across sessions

Documentation

Complete documentation is available in the docs/ directory:

Intelligence Features

• Intelligence Features Quick Start](docs/features/INTELLIGENCE_QUICK_START.md) ⭐ Start Here - 5-minute practical guide

  • Automatic insights capture (how to use ★ Insight ───── delimiters)

  • Cross-project intelligence (group related projects)

  • Team collaboration (shared knowledge with voting)

  • Advanced search techniques (semantic, faceted, temporal)

  • Configuration and troubleshooting

• Insights Capture & Deduplication](docs/features/INSIGHTS_CAPTURE.md) ⭐ Deep Dive

  • Automatic extraction of educational insights from conversations

  • Multi-point capture strategy (checkpoint + session end)

  • SHA-256 deduplication to prevent duplicate insights

  • Semantic search with wildcard support

  • Complete test coverage (62/62 tests passing)

  • Architecture and implementation details

User Documentation

• User Documentation - Quick start, configuration, and deployment guides

  • Quick Start Guide - Get started in 5 minutes

  • Configuration Guide - Advanced configuration options

  • MCP Tools Reference - Complete tool documentation

Developer Documentation

• Developer Documentation - Architecture, testing, and integration guides

  • Oneiric Migration Guide - Database migration

  • Architecture Overview - System design and patterns

Feature Guides

• Feature Guides - In-depth documentation of specific features

  • Token Optimization - Context window management

  • Selective Auto-Store - Reflection storage policy

  • Auto Lifecycle - Automatic session management

Reference

• Reference - MCP schemas and command references

Troubleshooting

Common Issues:

• Memory/embedding issues: Ensure all dependencies are installed with uv sync

• Path errors: Verify cwd and PYTHONPATH are set correctly in .mcp.json

• Permission issues: Remove ~/.claude/sessions/trusted_permissions.json to reset trusted operations

Debug Mode:

# Run with verbose logging
PYTHONPATH=/path/to/session-buddy python -m session_buddy.server --debug

For more detailed troubleshooting guidance, see Configuration Guide or Quick Start Guide.