cached-context 0.3.0

# cached-context

File cache with diff tracking for AI coding agents. Drop-in MCP server that cuts token usage by 26%.

[![Crates.io](https://img.shields.io/crates/v/cachebro.svg)](https://crates.io/crates/cachebro)
[![CI](https://github.com/terraphim/cachebro/actions/workflows/release.yml/badge.svg)](https://github.com/terraphim/cachebro/actions/workflows/release.yml)
[![Token Savings](https://img.shields.io/badge/token_savings-~26%25-brightgreen.svg)](#performance)
[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-blueviolet.svg)](https://modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

> **Built with Rust** for maximum reliability and performance. Uses [rusqlite](https://crates.io/crates/rusqlite) (bundled SQLite) and [rmcp](https://crates.io/crates/rmcp) for production-grade stability.

## What is cached-context?

cached-context is an MCP server that caches file reads for AI coding agents. Instead of re-reading entire files, cachebro returns diffs or "unchanged" confirmations, saving ~26% of token usage.

### How it works

```
First read:   agent reads src/auth.rs → cached-context caches content + hash → returns full file
Second read:  agent reads src/auth.rs → hash unchanged → returns "[unchanged, 245 lines, 1,837 tokens saved]"
After edit:   agent reads src/auth.ts → hash changed → returns unified diff (only changed lines)
```

## Installation

### Option 1: Homebrew (macOS/Linux)

```bash
brew tap terraphim/tap
brew install cached-context
```

### Option 2: Cargo (Rust toolchain required)

```bash
cargo install cached-context
```

### Option 3: Pre-built Binary

Download the latest release from [GitHub Releases](https://github.com/terraphim/cached-context/releases).

```bash
# macOS (Apple Silicon) - code signed
curl -L https://github.com/terraphim/cached-context/releases/latest/download/cached-context-macos-arm64.tar.gz | tar xz
sudo mv cached-context /usr/local/bin/

# macOS (Intel) - code signed
curl -L https://github.com/terraphim/cached-context/releases/latest/download/cached-context-macos-x86_64.tar.gz | tar xz
sudo mv cached-context /usr/local/bin/

# Linux
wget https://github.com/terraphim/cached-context/releases/latest/download/cached-context-linux-x86_64.tar.gz
tar xzf cachebro-linux-x86_64.tar.gz
sudo mv cached-context /usr/local/bin/
```

### macOS Security Note

If macOS blocks the binary after installation, you may need to remove the quarantine attribute:

```bash
sudo xattr -rd com.apple.quarantine /usr/local/bin/cached-context
```

Or allow it in System Settings > Privacy & Security.

### Option 4: Build from Source

```bash
git clone https://github.com/terraphim/cached-context.git
cd cached-context
cargo build --release
sudo cp target/release/cached-context /usr/local/bin/
```

## Quick Start

### 1. Verify Installation

```bash
cached-context --help
```

### 2. Configure MCP

#### Claude Code

Add to your `.claude.json`:

```json
{
  "mcpServers": {
    "cached_context": {
      "command": "cached-context",
      "args": ["serve"],
      "env": {
        "CACHED_CONTEXT_DIR": ".cached-context"
      }
    }
  }
}
```

#### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "cached_context": {
      "command": "cached-context",
      "args": ["serve"],
      "env": {
        "CACHED_CONTEXT_DIR": ".cached-context"
      }
    }
  }
}
```

#### OpenCode

Add to `.opencode/mcp.json`:

```json
{
  "mcpServers": {
    "cached_context": {
      "command": "cached-context",
      "args": ["serve"],
      "env": {
        "CACHED_CONTEXT_DIR": ".cached-context"
      }
    }
  }
}
```

### 3. Restart Your Agent

After configuring, restart Claude Code, Cursor, or OpenCode. The agent will automatically discover and use cachebro's `read_file` tool instead of the built-in Read tool.

## Usage

### Manual Testing

```bash
# Check cache status
cached-context status

# Clear the cache
cached-context clear

# Start MCP server (for manual testing)
cached-context serve
```

### Available Tools

When used as an MCP server, cached-context exposes:

| Tool | Description |
|------|-------------|
| `read_file` | Read a file with caching. Returns full content, "unchanged", or diff. |
| `read_files` | Batch read multiple files with caching. |
| `cache_status` | Show cache statistics. |
| `cache_clear` | Clear all cached data. |

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `CACHED_CONTEXT_DIR` | `.cached-context` | Directory for cache database |
| `RUST_LOG` | `info` | Logging level (error, warn, info, debug, trace) |

### Cache Location

By default, cached-context stores its database at `./.cached-context/cache.db` (relative to working directory). You can change this:

```bash
CACHED_CONTEXT_DIR=/path/to/cache cached-context serve
```

## Architecture

- **Rust implementation** for reliability and performance
- **SQLite backend** via [rusqlite](https://crates.io/crates/rusqlite) (bundled SQLite)
- **MCP protocol** via [rmcp](https://crates.io/crates/rmcp)
- **Diff algorithm** using [similar](https://crates.io/crates/similar)

## Performance

- File read: < 10ms for typical files
- Diff computation: < 5ms for typical changes
- MCP round-trip: < 50ms

## Testing

```bash
# Run all tests
cargo test

# Run tests quietly
cargo test --quiet
```

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Acknowledgments

- Original TypeScript implementation by [glommer/cachebro](https://github.com/glommer/cachebro)
- Built with [terraphim](https://github.com/terraphim/terraphim-ai) infrastructure

## Support

For issues and questions:
- GitHub Issues: https://github.com/terraphim/cached-context/issues
- Discussions: https://github.com/terraphim/cached-context/discussions