# Session Buddy - Qwen Context

## Project Overview

This is a Python-based MCP (Model Context Protocol) server that provides comprehensive session management functionality for Claude Code sessions. It's designed to be integrated into any project's `.mcp.json` file to provide automatic access to session initialization, checkpoints, and cleanup via slash commands.

Key features include:

- Session initialization with UV dependency management
- Mid-session quality checkpoints with workflow analysis
- Session cleanup with learning capture
- Status monitoring with project context analysis
- Built-in conversation memory with semantic search capabilities
- Git worktree management tools
- Permissions management to reduce prompts

## Project Structure

```
session-buddy/
├── session_buddy/           # Main Python package
│   ├── core/                   # Core session management functionality
│   ├── tools/                  # Individual MCP tool implementations
│   ├── utils/                  # Utility functions (git operations, logging)
│   └── server.py               # Main MCP server entry point
├── tests/                      # Test suite
├── docs/                       # Documentation
├── pyproject.toml              # Project configuration and dependencies
├── requirements.txt            # Generated dependencies list
└── README.md                   # Project documentation
```

## Key Technologies

- **Python 3.13+**: Primary programming language
- **FastMCP**: Framework for building MCP servers
- **DuckDB**: Local database for conversation storage
- **ONNX Runtime & Transformers**: For local semantic embeddings (optional)
- **UV**: Package manager for Python dependencies
- **Ruff**: Code linting and formatting

## Building and Running

### Installation

1. Clone the repository:

   ```bash
   git clone https://github.com/lesleslie/session-buddy.git
   cd session-buddy
   ```

1. Install dependencies using UV (recommended):

   ```bash
   uv sync --group dev
   ```

   Or using pip:

   ```bash
   pip install -e .
   ```

### MCP Configuration

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

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

Alternative using script entry point (if installed with pip/uv):

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

### Running the Server

For development:

```bash
python -m session_buddy.server
# or
session-buddy
```

## Development Conventions

### Code Style

- Follows PEP 8 standards
- Uses Ruff for linting and formatting with line length 88
- Type hints are required for all functions
- Uses strict pyright configuration for type checking

### Testing

- Uses pytest for testing
- Tests are located in the `tests/` directory
- Run tests with: `pytest` or `uv run pytest`

### Dependencies

Dependencies are managed using:

- `pyproject.toml` for project configuration
- `uv.lock` for lock file (UV)
- `requirements.txt` for pip-compatible list

Install optional dependencies for semantic search:

```bash
# Ensure all dependencies are installed (embeddings are included by default)
uv sync
# or
pip install session-buddy
```

## Available MCP Tools

### Session Management

- `init` - Comprehensive session initialization
- `checkpoint` - Mid-session quality assessment
- `end` - Complete session cleanup
- `status` - Current session status

### Memory & Reflection System

- `reflect_on_past` - Search past conversations with semantic similarity
- `store_reflection` - Store important insights
- `search_nodes` - Advanced search capabilities
- `quick_search` - Fast overview search
- `get_more_results` - Pagination support

### Permissions System

- `permissions` - Manage trusted operations

### Git Worktree Management

- `git_worktree_list` - List all git worktrees
- `git_worktree_add` - Create new worktrees
- `git_worktree_remove` - Remove worktrees
- `git_worktree_status` - Comprehensive worktree status
- `git_worktree_prune` - Clean up stale references

## Data Storage

- Memory Storage: `~/.claude/data/reflection.duckdb`
- Session Logs: `~/.claude/logs/`

## Recommended Session Workflow

1. Initialize Session: `/session-buddy:start`
1. Monitor Progress: `/session-buddy:checkpoint` (every 30-45 minutes)
1. Search Past Work: `/session-buddy:reflect_on_past`
1. Store Important Insights: `/session-buddy:store_reflection`
1. End Session: `/session-buddy:end`

## Testing and Quality Assurance

The project uses several tools for quality assurance:

- Pytest for unit and integration tests
- Ruff for linting and formatting
- Pyright for type checking
- Hypothesis for property-based testing

Run the full test suite:

```bash
uv run pytest
```

Run tests with coverage:

```bash
uv run pytest --cov=session_buddy
```

## Troubleshooting

Common issues:

- Memory not working: Ensure all dependencies are installed with `uv sync` or `pip install session-buddy`
- Path errors: Ensure `cwd` and `PYTHONPATH` are set correctly in `.mcp.json`
- Permission issues: Use `/session-buddy:permissions` to trust operations

Debug mode:

```bash
PYTHONPATH=/path/to/session-buddy python -m session_buddy.server --debug
```
