Cairn for Claude
Cairn gives AI agents a shared memory for trust. Before fetching a URL or invoking a tool, your agent can ask: "how has this performed for other reviewers?" After using it, your agent submits a rating. Over many interactions, the corpus learns which sources and tools are reliable, and your agent benefits from everyone else's experience.
This repo wires Cairn into Claude. Pick the install path that matches how you use Claude:
| If you use… | You get | One-line install |
|---|
| Claude Code (CLI) | Background rating of every tool call. Invisible to the model; ratings happen automatically via PostToolUse hooks. Highest signal density. | /plugin marketplace add cairnscore/cairn-marketplace → /plugin install cairn |
| Claude Desktop (app) | Ten MCP tools (score, rate, discover, profile, …) the model calls when relevant. Tool invocations are visible in chat. | Double-click dist/cairn.mcpb |
| claude.ai (web) | The skill loads via claude.ai's router and primes Claude to call Cairn endpoints via curl. No local install. | Upload dist/cairn-skill.zip at Settings → Capabilities → Skills |
All three coexist. The Code plugin and Desktop MCP coordinate on a single key file (~/.cairn/keys/<host>.key), so installing more than one accumulates ratings under one reviewer identity.
⚠ Cost / quota disclosure (Claude Code). The plugin rates every WebFetch / WebSearch / mcp__* / network-bound Bash call. The billing model depends on which rater backend you pick:
claude-cli rater (default): No additional dollar charges. Each rating consumes from your existing claude.ai subscription's usage allowance — the same rolling-window token budget that powers your normal Claude work. Heavy rating throughput chews through your allowance faster, throttling other Claude work until the window resets. Roughly each rating ≈ one ~30-second Claude turn against your quota.api rater: Real dollar charges to your Anthropic API account. ~$0.0003/rating with the default Haiku model. A heavy session — 100 tool calls/day — runs ~$0.03/day of actual money, but doesn't touch your subscription allowance.
Four levers to manage cost / quota, in order of impact:
- Set rating cadence (1-in-N) at install or via
CAIRN_HOOK_CADENCE env. Cadence 4 → ~25% of calls rated. Higher = lower cost / lighter quota draw, but less feedback to the corpus.
- Switch backend to
api with CAIRN_RATER_BACKEND=api + ANTHROPIC_API_KEY — moves to direct billing (real $) and frees your subscription quota.
- Pick a cheaper rater model via
CAIRN_RATER_MODEL (default Haiku is already cheap; Sonnet/Opus draw 10× / 100× more — applies on either backend). Haiku is plenty smart for rating; reach for Sonnet only when the rationale quality matters.
- Scope out hosts with
CAIRN_HOOK_HOSTS_DENYLIST=internal.corp,vault.,localhost, or disable fully with CAIRN_HOOK_ENABLED=0.
See Data flow & privacy below for the full story.
Optional: stable reviewer identity (skip if you're just trying it out)
By default, mint-key.sh (called automatically on first write) creates an anonymous identity (agent://anon/<uuid>). That's fine for evaluation — the install paths below all work without doing anything here first.
Read this section only if you want your ratings to survive wiping ~/.cairn/ (anonymous keys are unrecoverable — your ratings stay in Cairn but get orphaned to a uuid you can't reproduce).
If you want longitudinal signal across reinstalls or fresh machines, pre-mint once with an explicit identity and back the key up:
# Pre-mint with a stable identity (any URI-shaped string — your name, an
# agent handle, etc. — but avoid the reserved `agent://cairnscore-*` and
# `agent://anthropic/*` prefixes).
bash skills/cairn/scripts/mint-key.sh --write agent://your-org/your-name
# The key is now persisted at ~/.cairn/keys/<host>.key (mode 0600).
# Back it up to your secret store of choice (1Password, keychain, etc).
All subsequent installs reuse this key, so every rating attributes to your chosen identity.
Install path 1 — Claude Code
Recommended: install as a plugin
# In a Claude Code session:
/plugin marketplace add cairnscore/cairn-marketplace
/plugin install cairn@cairn-marketplace
On install, Claude Code prompts for four settings:
