capy

Context-Aware Prompting ...or "Yet another solution to LLM context problem"

[!IMPORTANT] This project was created with the help of Claude-Code. It is, however, reviewed, tested, and reworked with a human-in-the-loop.

No AI slop here. Purely AI-made skills are hot garbage, and that's putting it mildly.

That said, if you have any problems with code that is written by AI - you've been warned. But, then again, why would you be interested in AI-related configs and skills in the first place... ¯\_(ツ)_/¯

ToC

• Privacy & Architecture
• The Problem
• Benchmarks
  • Retrieval Quality
  • Context Reduction
• Quick Start
  • Install
  • Setup
  • Setup (Codex CLI)
• How It Works — By Example
  • Before capy
  • After capy
  • The intent parameter
• Configuration
• Encryption
  • Setup
  • Project credentials
  • Upgrade and credential migration
    • Rollback
  • Initial encryption
  • Cross-machine sync
  • Keeping the DB out of your project repo (recommended)
  • Key rotation
  • Passphrase recommendations
• Session Vault
  • Setup
  • Quick start
  • Archiving sessions
  • Codex sessions
  • Commands
  • Restore and resume
  • Naming sessions
  • Cross-machine sync
  • Key rotation
  • Storage and limits
  • Environment variables
• CLI Commands
  • Shell Completions
• MCP Tools
  • Execution
  • Knowledge
  • Utility
• Security
  • Sandbox protections
• Hook System
  • What gets intercepted
  • Platform support
• Troubleshooting
• Acknowledgements
• Contributing
• License

Privacy & Architecture

capy is not a CLI output filter or a cloud analytics dashboard. It operates at the MCP protocol layer — raw data stays in a sandboxed subprocess and never enters your context window. Web pages, API responses, file analysis, log files — everything is processed in complete isolation.

Nothing leaves your machine. No telemetry, no cloud sync, no usage tracking, no account required. Your code, your prompts, your session data — all local. The SQLite databases are encrypted at rest. Knowledge credentials come from local project files or the launch environment and are never sent to a remote service.

This is a deliberate architectural choice, not a missing feature. Context optimization should happen at the source, not in a dashboard behind a per-seat subscription. Privacy-first is our philosophy — and every design decision follows from it. License

The Problem

Every MCP tool call dumps raw data into your context window. A single API response costs 56 KB. Twenty GitHub issues cost 59 KB. One access log — 45 KB. After 30 minutes, 40% of your context is gone. And when the agent compacts the conversation to free space, it forgets which files it was editing, what tasks are in progress, and what you last asked for. The sessions themselves are disposable, too — Claude Code deletes them after 30 days, /compact rewrites them in place, and nothing survives across projects or an accidental delete.

capy is an MCP server and Claude Code plugin that addresses every layer of this — from the live context window down to the permanence of the sessions themselves:

1. Context Saving — Sandbox tools keep raw data out of the context window. 315 KB becomes 5.4 KB. ~98% reduction.
2. Searchable Knowledge Base — All sandboxed output is indexed into SQLite FTS5 with BM25 ranking. Use capy_search to retrieve specific sections on demand. Multi-layer search: Porter stemming, trigram substring, fuzzy Levenshtein correction, with Reciprocal Rank Fusion and proximity reranking.
3. Session Memory — Past conversation transcripts are automatically indexed on server start. When the conversation compacts, the LLM can search prior sessions for context via BM25 search.
4. Session Vault — A durable, cross-project, encrypted archive of every Claude Code session. Search, view, restore, or resume past conversations long after Claude Code's 30-day cleanup, compaction, or accidental deletion would have lost them. See Session Vault.

Benchmarks

capy ships with a benchmark suite that validates its claims with deterministic, reproducible metrics — no LLM-in-the-loop evaluation. Run make bench to reproduce on your machine. Measured across 156 synthetic test cases spanning 5 content types (markdown, JSON, plaintext, transcripts, curated knowledge).

Retrieval Quality

Metric	Score
R@1 (at least one relevant result in top 1)	0.897
R@5	0.987
R@10	0.994
MRR (mean reciprocal rank)	0.938
NDCG@10	0.950

Context Reduction

"Bytes saved" is a vanity metric. NIAH measures whether specific facts survive compression — not just how many bytes were removed:

| Metric