CAP-Shield
Selects the memory entries that answer a question within a token budget, instead of sending the whole history. Also dated wide context, message compression and signed agent passes. Measured, not claimed.
호스팅형 MCP 서버
npx add-mcp 'https://cap-shield-robin.fly.dev/mcp'Claude Code, Codex, Cursor 등에 설치됩니다
문서
CAP-Shield MCP server
Context selection and compression for AI agents — with the recall measured, not claimed.
One file. No dependencies. No SDK required.
Why
More context makes agents worse. ETH Zurich found context files LOWER task success versus giving the agent no repository context at all, while raising inference cost by over 20 %. Around two thirds of production agent failures trace to context problems, not to the model being incapable.
So the question is not how much you cut. It is whether what you kept was enough — and that is measured here, on a benchmark we did not choose: LongMemEval-S, 500 questions. Recall@10 of 97.1 % against a lexical baseline of 51.9 % (measured 2026-09-28 — figures update as retrieval does; fetch .well-known/cap-shield.json for the current number rather than trusting this file).
Recall@10 is the strict measure: a question counts only when ALL gold sessions were found. Finding half the answer means the agent answers confidently on half a basis.
Two of the nine tools need no account. Measure first, decide after.
Install
curl -O https://cap-shield-robin.fly.dev/cap_mcp.py
{
"mcpServers": {
"cap-shield": {
"command": "python",
"args": ["/absolute/path/to/cap_mcp.py"]
}
}
}
Python 3.9+. Nothing else.
The optional SKILL.md tells an agent when to use these tools — and when not to.
Install as a Claude plugin (server and skill together)
This repository is also a Claude plugin: the remote MCP server plus the skill that tells Claude when to use each tool, and when not to.
In Claude Code:
/plugin install cap-shield --marketplace robinlidberg-dot/cap-shield-mcp
The plugin connects to https://cap-shield-robin.fly.dev/mcp.
measure_traffic, list_packages and get_account work without a key;
the other tools need one (see below). Privacy policy:
https://cap-shield-robin.fly.dev/privacy
Use it from Claude (Claude.ai, Claude Desktop, or Cowork) — no download
The server is also reachable directly over HTTP, so a hosted Claude client can connect to it without installing anything locally.
In Claude: Settings → Connectors → Add custom connector, and enter the server URL:
https://cap-shield-robin.fly.dev/mcp
Under Authentication, choose No sign-in — this server is authenticated with an API key, not OAuth (OAuth support is not built yet; see Status below). Claude will warn that anyone with the URL can use the connector without sign-in — that warning is accurate, and is exactly why the two free tools below need no key at all, while the rest do.
measure_traffic and list_packages work immediately, with no
header and no account — nothing more to configure.
To use the account tools (remember, assemble_context,
assemble_escalation_context, pack_batch, unpack_batch,
issue_pass): get a key first
(get_account, or the console at
https://cap-shield-console.lovable.app), then add it under Request
headers in the same connector dialog:
| Header | Value |
|---|---|
Authorization | Bearer YOUR_KEY_HERE |
The Bearer prefix is required — a bare key without it is rejected
with NYCKEL_KRAVS. This is a standard bearer-token header, so the same
two fields should work in any MCP client that lets you add a custom
request header to a remote server, not just Claude — that is just the
one this has actually been tested against.
Tools
measure_traffic · no account
Measure how much of your own agent traffic could be saved. NO ACCOUNT OR KEY NEEDED — use this first. Returns byte savings over the wire and, if a query is given, token savings from selective context retrieval. Nothing is stored: the text is compressed in memory and discarded. Rate limited to 20 calls per hour per IP.
list_packages · no account
List the available dictionaries with their MEASURED compression, including the ones that perform badly. Each entry says whether it works one message at a time or only batched, and how many messages came out LARGER. No key needed.
remember · requires a key
Store a memory entry for later retrieval. REQUIRES A KEY. This does not call any language model — it stores text in an isolated per-tenant archive. Use assemble_context to get relevant entries back.
assemble_context · requires a key
Retrieve the memory entries that answer a question, within a token budget. REQUIRES A KEY. Send the returned 'context' to your language model INSTEAD of the whole history. This does not call a model itself — it selects what to send. The budget is a ceiling, not a target: selection stops where relevance runs out, often well below it. The response says how many entries were left behind and why. If the response has a budget_warning, the best match did not fit: call again with its suggested_token_budget.
assemble_escalation_context · requires a key
Retrieve a WIDE context for a question your model could not answer from assemble_context. REQUIRES A KEY. Use it when assemble_context returned escalate_recommended=true, or when the answer depends on dates, counts or several sessions. This does not call a model itself. Returns 'context' (up to token_budget, default 150 000 tokens: lower it if your model's window is smaller), where each stored entry starts with a header '--- Session YYYY/MM/DD (Ddd) HH:MM ---' giving when it was stored, and 'utelamnat_kontext': lower-ranked entries that were left out, in the same format. Read those only if the answer is still missing from 'context'. Python users can pass the whole response to cap_escalate_helper.eskalera_om_behovs_v6().
pack_batch · requires a key
Pack several messages into ONE compressed packet instead of packing them one at a time. REQUIRES A KEY. Worth it for many small/medium messages (the per-message header cost is paid once per batch, and zstd shares context across them) — for a single message this has no advantage. Returns packet_b64 (hand it to unpack_batch to get the messages back) plus the measured byte savings versus packing each message separately. SECURITY: only batch messages that already share the SAME trust boundary (same tenant/agent — nothing attacker-influenced mixed in with a secret). Batched messages share one compression context, which can leak size-based information between them (a CRIME/BREACH-style side channel). There is no padding mitigation on this endpoint today, so trust-boundary separation is the only protection — don't rely on padding.
unpack_batch · requires a key
Unpack a batch packet made by pack_batch (or by the /api/v1/pack-batch endpoint) back into the exact original list of messages, in order. REQUIRES A KEY. Not for a packet made by the single-message pack endpoint — that is a different format and this will reject it.
get_account
Get an account and an API key. Requires an email address. The key is returned ONCE and cannot be shown again — store it immediately. Beta quotas are low by design; they are hard stops, never overage billing.
issue_pass · requires a key
Agent identity / agent passport. Issue a short-lived (15 minute) signed credential (a JWT) stating who the caller acts for. REQUIRES A KEY. Anyone can verify it independently against /.well-known/jwks.json — without calling CAP-Shield again. 'acts_for' and 'scope' are NOT validated against reality: the pass only attests that the key holder claimed this, at this time, and that the claim is recorded in the audit chain. This is identity and claimed authorization, not a payment or access-control mechanism.
The descriptions above are copied verbatim from the server. If they ever
differ from what tools/list returns, the server is right and this file
is stale.
Answers from memory, with your own model
Retrieval and compression above never call a model. For questions the
narrow selection cannot answer — dates ("last Saturday", "how many days
ago"), counts and sums across sessions, a detail that ranked low —
assemble_escalation_context (REST: POST /api/v1/memory/assemble-escalation)
returns a much wider context with a date header on every session, plus the
sessions that were left out.
cap_escalate_helper.py (with cap_fokuslasare.py) answers from it with
your own model key, from your machine. CAP-Shield never spends your
tokens and never sees your key. Both files are in this repository and in
the cap-shield package on PyPI (0.6.0 and later). Standard library only;
openai or anthropic is imported when it is used.
pip install cap-shield openai # or: anthropic
export OPENAI_API_KEY=...
from cap_shield import CapShield
from cap_escalate_helper import eskalera_om_behovs_v6
cap = CapShield(api_key="cap_live_...")
fraga = "Which bike did I fix last weekend?"
ctx = cap.escalation_context("support", fraga)
svar = eskalera_om_behovs_v6(ctx, fraga, modell="openai", # or "anthropic"
modell_namn="gpt-6-luna",
dagens_datum="2026/11/16") # when the question is asked
print(svar["svar"])
Over MCP, call assemble_escalation_context and let your own model read
the result.
How often the answer is right
Measured 2026-11-16 with gpt-6-luna answering. The full method, the
answer to every question type, and each answer that was reviewed by hand
are published under memory_layer.answer_benchmark in
https://cap-shield-robin.fly.dev/.well-known/cap-shield.json — fetch the
current figures there rather than trusting this file.
| Test | This version | Previous version |
|---|---|---|
| LongMemEval-S, 500 questions, judged automatically | 96.6 % | 88.0 % |
| After manual review of 10 answers (each listed) | 98.6 % | |
| LoCoMo, 100 questions it was never tuned on | 80 / 100 | 81 / 100 |
Three caveats, which belong next to those figures wherever they are quoted:
- Developed against the same 500 questions. The rules in the helper were written while studying misses on that set. On LoCoMo, which they were never tuned on, they gave no gain over the previous version.
- The judge is not the GPT-4o from the LongMemEval paper, so the figures are not directly comparable to published LongMemEval scores.
- They depend on the answer model.
Six of the ten reviewed answers meet the official preference rubric but were rejected by the judge model. In four, the benchmark's gold answer contradicts the conversation history; we keep the answer the history supports and list the case, rather than teach the model to agree with a wrong key.
Energy and time
A model spends energy and time on every token it reads. Measured
2026-11-17 with the GPU's own energy counter (NVIDIA GeForce RTX 4070,
llama3.2:1b, idle power subtracted), 50 LongMemEval-S
questions, against the whole history (median 104 652 tokens):
95 % less energy and 94.4 % less time for the model to
read the context, with the selection at budget 32 000 and every
session holding the answer included in 90 % of questions.
| The model reads | Tokens (median) | Less energy | Less time | All evidence included |
|---|---|---|---|---|
| Selection, budget 32 000 | 18 248 | 95 % | 94.4 % | 90 % |
| Selection, budget 16 000 | 12 672 | 97.2 % | 96.5 % | 80 % |
| Selection, budget 8 000 | 6 158 | 98.7 % | 97.9 % | 50 % |
| Selection, budget 4 000 | 3 094 | 99.3 % | 98.5 % | 22 % |
| Selection, budget 2 000 | 1 080 | 99.7 % | 98.8 % | 14 %, 9 empty |
| Escalation context | 75 066 | 39.3 % | 37.4 % | 98 % |
Per reading of the context, on one GPU with a small model; larger models
have not been measured. A shorter history leaves less to remove. The
escalation helper reads its context at least twice per question. If the
budget is too small for the best match, the response says so in
budget_warning and suggests a budget that fits it.
What the numbers mean
Compression saves bytes over the wire. Selection saves tokens in the context. Two different mechanisms — adding them together produces a number that means nothing.
Compressed packets are decompressed before a model sees them, so this does not reduce inference cost. Saying otherwise is the easiest way to be wrong about this project.
Every figure is published live, including what has not been measured and which packages perform badly:
https://cap-shield-robin.fly.dev/.well-known/cap-shield.json
Fetch that rather than trusting this file. It goes stale; the document does not.
Measuring without MCP
pip install cap-shield
from cap_shield import measure, print_measurement
print_measurement(measure(texts=[...], query="..."))
No account, nothing stored. The response includes the degraded share — how many of your messages came out larger.
Batching has a security condition
Batching compresses several messages in the same context, which opens a CRIME/BREACH-style side channel: someone who can place chosen text in the same batch as a secret, and observe the batch size, learns something about the secret.
Only batch messages that already share a trust boundary. Optional padding closes the leak for under two bytes a message, and it is off by default — we say so rather than let you assume otherwise.
Individual packing does not have this problem at all.
Portability
Dictionary versions are never deleted, and the guarantee does not rest on us still being here: the archive export carries the dictionary binaries, and a standalone unpacker runs with no gateway, no network and no other part of the system.
https://cap-shield-robin.fly.dev/cap_unpack.py
It is served without a token, because whoever needs it most is whoever no longer has an account.
Status
Beta. MCP server 0.7.0, Python package 0.6.0.
Docs: https://cap-shield-robin.fly.dev/docs/quickstart Console: https://cap-shield-console.lovable.app
Licence
MIT — see LICENSE.