Context Diamond

Stop pasting the same messy context into every LLM. Turn chats, logs, issues,
agent state, and docs into small, auditable context capsules.

Context Diamond is a deterministic context compression and handoff toolkit for
LLM agents.
It extracts the things models keep losing in long conversations:

• goals and success criteria
• hard constraints
• decisions already made
• current working state
• open questions and risks
• files, symbols, entities, and anchors

It is built for developers who switch between coding agents, OpenCode, chat UIs,
RAG pipelines, issue threads, and local notes. The default engine is offline,
zero-dependency, inspectable, and safe to run before any text is sent to an LLM.

Why People Click This

Most LLM context tools promise "memory". Context Diamond gives you a portable
handoff artifact you can read, diff, benchmark, paste, store, or feed to another
agent.

Use it when you want to:

• recover signal from noisy agent sessions
• reduce repeated prompt/context cost
• preserve constraints before handing work to another model
• keep decisions visible instead of buried in a paragraph summary
• audit what got dropped with a loss report
• expose compression as an OpenCode MCP tool

60-Second Demo

Install from GitHub:

pip install git+https://github.com/RainCherb/context-diamond.git

Compress a long handoff:

context-diamond examples/long_handoff.md --budget 320 --title "Sprint Handoff"

Get JSON with an audit trail:

context-diamond examples/long_handoff.md --format json --loss-report

Benchmark it against dumb head/tail clipping:

context-diamond-bench examples/long_handoff.md --budget 320

Inspect why shards were selected:

ctxd explain examples/long_handoff.md

Build a capsule from a repository:

ctxd repo . --budget 1200

Compare or merge capsules as the handoff evolves:

ctxd diff old_capsule.json new_capsule.json
ctxd merge chat.json repo.json issue.json --budget 900

Example benchmark output:

535 source tokens -> 387 rendered capsule tokens
1.38x ratio
constraints:1.00 decisions:1.00 risks:1.00 code:1.00

The Pitch

Generic summaries are cheap, but they often flatten the one thing you needed to
keep. Context Diamond keeps the handoff structured:

OpenCode MCP

Add Context Diamond to OpenCode as a local MCP server:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context_diamond": {
      "type": "local",
      "command": ["context-diamond-mcp"],
      "enabled": true,
      "timeout": 10000
    }
  }
}

OpenCode tools:

• context_diamond_compress_text
• context_diamond_compress_file
• context_diamond_benchmark_file

See docs/opencode.md.

CLI

# Markdown capsule
context-diamond notes.md --budget 500 --output capsule.md

# JSON capsule for automation
context-diamond notes.md --format json --loss-report --output capsule.json

# Explain shard scoring
ctxd explain notes.md

# Repository capsule
ctxd repo . --budget 1200

# Capsule evolution
ctxd diff old.json new.json
ctxd merge chat.json repo.json --output merged.md

# Stdin
type notes.md | context-diamond - --budget 350

Use a JSON message list:

context-diamond conversation.json --messages-json --format json

[
  {"role": "user", "content": "Build a local context compressor."},
  {"role": "assistant", "content": "Decision: use deterministic extraction first."}
]

Python API

from context_diamond import CompressionConfig, ContextDiamondCompressor

text = """
Goal: reduce token waste in LLM handoffs.
The tool must run locally and avoid API keys by default.
Decision: emit markdown and JSON capsules.
"""

compressor = ContextDiamondCompressor(CompressionConfig(token_budget=220))
capsule = compressor.compress(text)

print(capsule.to_markdown())

Integration helpers:

from context_diamond import compress_documents, compress_messages, compress_tool_payload

See docs/integrations.md.

What The Capsule Looks Like

# Context Diamond Capsule

- Strategy: `diamond-v1`
- Source tokens: `535`
- Capsule tokens: `315`
- Compression ratio: `1.7x`

## Diamond Pulse
- The strongest signals from the source.

## Rules And Constraints
- Requirements that should not be violated.

## Decisions Already Made
- Choices that should not be reopened accidentally.

## Open Questions And Risks
- Unresolved items that need attention.

Why This Over X

Context Diamond is not trying to replace every prompt compressor, RAG compressor,
or memory store. It is best at one job:

create auditable context capsules for LLM and coding-agent handoffs.

Read the honest comparison in docs/why-context-diamond.md.

Features

• Offline by default: no hidden network calls.
• Zero runtime dependencies: install it into boring environments.
• OpenCode-ready: ships a local stdio MCP server.
• Benchmarkable: compare against deterministic clipping baselines.
• Auditable: optional loss report shows omitted shards.
• Explainable: ctxd explain shows shard facets, scores, tokens, and reasons.
• Repo-aware: ctxd repo captures branch, git state, and selected files.
• Composable capsules: ctxd diff and ctxd merge support handoff evolution.
• Structured: goals, rules, decisions, facts, state, risks, anchors.
• Composable: CLI, Python API, JSON output, adapters, MCP.

Docs

• OpenCode integration
• Benchmarks
• Integrations
• Algorithm
• Architecture
• Use cases

Local Development

git clone https://github.com/RainCherb/context-diamond.git
cd context-diamond
python -m venv .venv
.\.venv\Scripts\activate
pip install -e ".[dev]"
python -m pytest
python -m ruff check .

On macOS or Linux, activate with source .venv/bin/activate.

Roadmap

• Larger public benchmark corpus with task-level answer quality checks.
• Optional embedding reranker for very large sources.
• Exact tokenizer extras for OpenAI, Anthropic, Gemini, and local models.
• More first-class agent adapters: GitHub issues, Linear, Slack, Markdown logs.
• Streaming capsule updates for long-running coding agents.
• PyPI release after the public API stabilizes.

Star This If

• you lose context when switching between LLM tools
• you want OpenCode agents to compress handoffs before continuing
• you prefer inspectable local tools over another black-box summarizer
• you like boring, deterministic software that saves expensive tokens

MIT licensed. Built to be small, honest, and useful.