composto

Composto

Causal memory layer for coding agents. Catches the bug your agent is about to reintroduce.

Composto is a repo-local graph of your git history that your AI coding agent consults before every edit. When a file was reverted recently, has a fix cluster in its history, or was last touched by someone who left the team, Composto surfaces that signal as in-context guidance before the agent writes the code. Hook-enforced on Claude Code, Cursor, and Gemini CLI. Local-first, MIT.

$ composto impact src/memory/signals/hotspot.ts

verdict:    medium
score:      0.52
confidence: 0.50
signals:
  revert_match       ■■■■■■■■■■ strength=1.00 precision=1.00
  hotspot            ■          strength=0.10 precision=0.54
  fix_ratio          ■          strength=0.07 precision=0.54
  author_churn       ·          strength=0.00 precision=0.16

# This file was touched by a Revert commit in history.
# blastradius remembers. Your LLM couldn't.

---

Quick Start

# Install
npm install -g composto-ai

# One-command setup, wires MCP + PreToolUse hook into your AI client
cd your-project
composto init --client=claude-code     # or cursor, or gemini-cli

# Restart your AI client. Hook fires on every Edit / Write / MultiEdit.
# On medium|high|unknown verdicts, the agent gets a composto_blastradius
# block in context before it acts. Passthrough on low.

# Observe
composto stats              # hook invocations, verdict distribution, latency
composto stats --disable    # local-only opt-out (writes .composto/telemetry-disabled)

# Query on demand
composto impact src/auth/login.ts
composto index --status     # diagnostics: schema, freshness, calibration

Also in the box: AST compression tools

Composto also ships a tree-sitter based AST compressor (about 89% token savings) and a smart context packer for bug-fix tasks. These are separate from the causal layer but live in the same binary.

composto ir src/app.ts                 # compress a file to IR (L0/L1/L2/L3)
composto context src/ --budget 2000    # smart context within a token budget
composto benchmark .                   # see compression stats

See the IR Layers, Health-Aware IR, and Context Budget sections below for details.

MCP plugin (Claude Code, Cursor, Claude Desktop)

The MCP server is bundled inside composto-ai. Install the package globally first, then register the server with your client:

npm install -g composto-ai

Claude Code:

claude mcp add composto -- composto-mcp

Cursor — add to ~/.cursor/mcp.json (or project-local .cursor/mcp.json):

{
  "mcpServers": {
    "composto": {
      "command": "composto-mcp"
    }
  }
}

Then restart Cursor and verify under Settings → MCP that composto is green.

Claude Desktop — add the same block to ~/Library/Application Support/Claude/claude_desktop_config.json.

Composto adds 5 tools to your AI assistant: composto_ir, composto_benchmark, composto_context, composto_scan, and composto_blastradius (the last one gated by COMPOSTO_BLASTRADIUS=1 during beta).

Cursor: one-command setup

Registering the MCP server only exposes the tools — Cursor's agent often defaults to its built-in read_file / codebase_search. To configure both the MCP server and a project rule that tells the agent when to call Composto, run:

cd your-project
composto init

This writes .cursor/mcp.json (project-local MCP registration) and .cursor/rules/composto.mdc (an alwaysApply: true rule that gets injected into every conversation). Existing files are merged, never overwritten. Restart Cursor and check Settings → MCP that composto is green.

Without the rule, hit rate is ~30-50%; with it, ~85-95%. The rule template is embedded in src/cli/init.ts (CURSOR_RULES_MDC) — open the generated .cursor/rules/composto.mdc to customize per-project.

Hook-enforced injection (v0.6.0+)

Instead of asking the agent to remember to call composto_blastradius, wire a hook so it gets consulted automatically before every Edit / Write / MultiEdit. The agent receives a <composto_blastradius> context block in-line when verdict is medium or high — you don't do anything, the warning just shows up where it's needed.

cd your-project
composto init --client=claude-code    # or cursor, or gemini-cli