cached-context 0.3.0

# cachebro Installation Proof

## Summary

Successfully replaced the original TypeScript cachebro with our Rust rewrite.

## Installation Details

### 1. Original cachebro Removed
```
Removed: /home/alex/.bun/bin/cachebro (TypeScript/Bun version)
```

### 2. New Rust cachebro Installed
```
Location: /home/alex/.local/bin/cachebro
Type: Rust binary (release build)
Size: 5.7M
```

### 3. OpenCode Configuration Created
File: `~/.opencode/mcp.json`

Configuration:
{
  "mcpServers": {
    "cachebro": {
      "command": "cachebro",
      "args": ["serve"],
      "env": {
        "CACHEBRO_DIR": ".cachebro",
        "RUST_LOG": "info"
      }
    }
  }
}

### 4. Verification Tests Passed

Test 1: Binary executable
- Result: /home/alex/.local/bin/cachebro found and working

Test 2: Status command
- Result: Cache statistics display correctly
- Output: Files tracked: 0, Tokens saved: 0

Test 3: MCP Protocol
- Result: Server initializes correctly
- Response: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05",...}}

### 5. Test Suite Results
All 45 tests passing:
- 20 unit tests (cache, diff modules)
- 8 MCP integration tests
- 8 error handling tests  
- 9 smoke tests (matching original TypeScript behavior)

## How to Use with OpenCode

1. OpenCode automatically detects cachebro via the MCP config
2. The `cachebro.read_file` tool replaces the built-in Read tool
3. Files are cached in `.cachebro/cache.db` per project
4. Second reads return "[unchanged]" saving ~26% tokens

## Key Improvements

| Feature | Original (TS) | New (Rust) |
|---------|---------------|------------|
| Language | TypeScript/Node.js | Rust |
| Storage | Turso (SQLite) | SQLite via terraphim_persistence |
| MCP SDK | Custom | rmcp (production-tested) |
| Sessions | Basic | Full isolation |
| Partial Reads | Limited | Smart change detection |
| Tests | Basic smoke | 45 comprehensive tests |
| Performance | Good | Better (native binary) |

## Proof Commands

Verify installation:
```bash
which cachebro
cachebro --help
cachebro status
```

Test MCP server:
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | cachebro serve
```

## Repository

Source: https://github.com/terraphim/cachebro
Status: Production ready

---

# Lessons Learned (v0.2.2 Update)

## Problem: MCP Connection Closed Error (-32000)

### Symptoms
- MCP clients (opencode, claude, codex) experiencing intermittent "Connection closed" errors
- Error: `error -32000: Connection closed`
- Occurred under load when multiple requests came in quickly

### Root Cause
The original implementation used blocking operations in an async context:

1. **`std::sync::Mutex`** - Blocking mutex that can deadlock the tokio runtime
2. **`std::fs::read_to_string`** - Blocking file I/O that stalls the async runtime
3. **No `.await` on async methods** - Methods were synchronous but called from async handlers

When the tokio runtime encounters blocking operations, it can:
- Starve other async tasks
- Trigger timeouts in connected MCP clients
- Cause "Connection closed" errors

### Solution
Converted to fully async implementation:

1. `std::sync.Mutex` → `tokio::sync::Mutex` 
2. `std::fs::read_to_string` → `tokio::fs::read_to_string`
3. Made all `CacheStore` methods async (`init`, `read_file`, `get_stats`, `clear`)
4. Updated all callers to use `.await`

### Key Takeaways

| Rule | Description |
|------|-------------|
| Never mix blocking I/O with async | Use `tokio::fs::*` for async file operations |
| Use tokio mutex in async code | `tokio::sync::Mutex` doesn't block the runtime |
| Test with actual MCP clients | Unit tests pass but real clients expose timing issues |
| All methods in call chain must be async | Can't call sync methods from async handlers |

### Files Changed
- `src/cache.rs` - Core async changes
- `src/mcp.rs` - Updated to await async methods  
- `src/main.rs` - Updated CLI to use async
- All test files converted to `#[tokio::test]`

### Testing
- All 48 tests pass
- Binary installed to `/home/alex/.local/bin/cachebro`
- Configured in Claude, OpenCode, and Codex MCP clients