cached-context

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

Built with Rust for maximum reliability and performance. Uses rusqlite (bundled SQLite) and 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)

brew tap terraphim/tap
brew install cached-context

Option 2: Cargo (Rust toolchain required)

cargo install cached-context

Option 3: Pre-built Binary

Download the latest release from GitHub Releases.

# 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:

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

Or allow it in System Settings > Privacy & Security.

Option 4: Build from Source

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

cached-context --help

2. Configure MCP

Claude Code

Add to your .claude.json:

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

Cursor

Add to .cursor/mcp.json:

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

OpenCode

Add to .opencode/mcp.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

# 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:

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

Architecture

Rust implementation for reliability and performance
SQLite backend via rusqlite (bundled SQLite)
MCP protocol via rmcp
Diff algorithm using similar

Performance

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

Testing

# Run all tests
cargo test

# Run tests quietly
cargo test --quiet

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE file for details.

Acknowledgments

Original TypeScript implementation by glommer/cachebro
Built with terraphim infrastructure

Support

For issues and questions:

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

cached-context 0.3.0