Project Info

RAVEN: Verified Context Passports for the Agentic Web

Inspiration

Every agent demo we tried had the same dirty secret: to make an agent "smart," people dump the entire user memory into every model call, and into every agent in a multi-agent system. It's expensive, it's slow, and — worse — it's unsafe. We watched a perfectly capable model, handed 1,700 tokens of someone's notes, confidently recommend an Italian restaurant for a vegetarian because the dietary rule was buried in the middle and got lost. That's the real problem we wanted to reframe. The bottleneck of the agentic web isn't model intelligence — it's context logistics: deciding who needs to know what. Humans don't brief a chef and an accountant with the same memo. So why do we hand every agent the same firehose? RAVEN's bet: the unit of the agentic web shouldn't be "the whole memory," it should be a context passport — the minimal, recipient-aware slice each agent needs, with the non-negotiable rules guaranteed to survive.

What it does

RAVEN is a recipient-aware, decision-preserving context compressor that sits in front of the expensive LLM agents. It compresses at the two edges where context explodes: Passport (user-memory → agent). It atomizes your memory into typed facts (dietary, budget, permission, availability, location, preference…), retrieves what's relevant to this agent's role and task, guards the standing rules so they can never be dropped, dedupes, and renders a tiny passport. The calendar agent never even sees your budget or allergies — least-privilege by construction. Passport (user-memory → agent). It atomizes your memory into typed facts (dietary, budget, permission, availability, location, preference…), retrieves what's relevant to this agent's role and task, guards the standing rules so they can never be dropped, dedupes, and renders a tiny passport. The calendar agent never even sees your budget or allergies — least-privilege by construction. RELAY (agent → agent). On handoffs, agents forward a compressed back-context passport instead of the entire growing transcript — ~90% smaller per hop, while the standing constraints survive 3/3 hops (naive last-message forwarding drops them). RELAY (agent → agent). On handoffs, agents forward a compressed back-context passport instead of the entire growing transcript — ~90% smaller per hop, while the standing constraints survive 3/3 hops (naive last-message forwarding drops them). It runs on three surfaces from one engine: Fetch.ai Agentverse — a real uAgent, reachable over the Chat Protocol and discoverable via ASI:One. Inside Claude (MCP) — the same engine ships as a Model Context Protocol server, so RAVEN is a tool inside Claude Desktop / Claude Code / Cursor (compress_memory, relay_handoff, list_roles) — no API key, no LLM calls. A web dashboard — a side-by-side A/B (same prompt with full memory vs. RAVEN's passport) showing the real Claude input-token counts and an animated pipeline of exactly what RAVEN did (atomize → rank → guard → drop → passport). Measured results (reproducible): A/B, live Claude usage: 1,783 → 317 input tokens (~82%), and across vague, adversarial, and gibberish prompts, 82–90% fewer tokens with every standing rule preserved — including refusing an adversarial "ignore my rules and charge my card" prompt. Decision benchmark: at an equal token budget, RAVEN scores 5/5 on gold constraints vs. 4/5 for generic role-unaware compression (which silently drops "confirm before paying"). Context-payload reduction: 92.9% vs. broadcasting full memory to every agent. The honest headline isn't just "fewer tokens" — at equal budget, tokens tie. The moat is decision quality and constraint-safety at that budget.

How we built it

A stdlib-first Python 3.13 engine, deliberately torch-free so every claim is explainable and reproducible: ingest → atomic typed facts → BM25 retrieval (query-aware) → recipient-aware selection → critical-fact guard → dedup → render → token count We grounded each stage in the literature but implemented lightweight, deterministic versions: Query-aware extractive selection (inspired by LongLLMLingua) via a custom BM25 — not a learned token classifier. Inter-agent communication pruning (AgentPrune / "Cut the Crap") → our RELAY handoff. Guideline learning without fine-tuning (ACON) → an optional verifier that learns "always keep type X" and only fires when a critical type is genuinely missing. Constraint-compliance vs. accuracy separation (CDCT) → deterministic decision scoring on gold constraints. Near-duplicate anchoring (SeCo) → dedup. Around the engine: Fetch.ai: a uAgent (uagents + uagents-core) speaking the Chat Protocol, mailbox-connected to Agentverse, plus a local Bureau multi-agent demo. Measurement: real Claude calls (Haiku 4.5) through a thin AnthropicLLM wrapper that reads the API's own usage.input_tokens — disk-cached so the stage demo is instant and free. Web: a FastAPI backend + Next.js 14 / React frontend ("Editorial Minimal" design) with the live A/B, the animated pipeline, a token meter, the decision benchmark, and PDF/doc ingestion (markitdown). Rigor: 116 offline tests (2 skipped), with a strict invariant that the test suite imports no uagents/fastapi/markitdown/mcp/network — the core stays pure. The savings number we show is literally: $$\text{saved}\% = \left(1 - \frac{T_{\text{RAVEN}}}{T_{\text{full}}}\right)\times 100$$ where $T$ are the model's real input tokens, not estimates.

Challenges we ran into

Compression is lossy by math, not by mistake. Turning $N$ tokens into $M < N$ forces a bet about what matters. Our first selector kept the dietary rule but dropped the actual restaurant suggestion and, in another pass, dropped "confirm before paying." The fix wasn't "compress better" — it was to make the loss principled: a hard guard that never drops standing rules, plus soft guards for schedule/location/preference, so the loss only ever lands on low-relevance facts. Relevance has no perfect oracle. BM25 mismatches vocabulary ("Italian place" vs. "where to eat"). We tuned a relevance floor and a recipient model rather than reaching for a heavyweight learned compressor we couldn't explain. Honest measurement is hard. It's tempting to quote a self-counted number. We forced ourselves to report the API's own usage.input_tokens, to disclose that tokens tie at equal budget, and to make the real win (decision quality) the headline. Live latency & demo safety. Real calls were slow under load, so we built disk caching, a "live Xs / cached" badge for transparency, and a cooldown so a demo can't accidentally burn quota. Keeping the agent dependency-free. The Agentverse agent itself makes zero LLM calls (pure deterministic compression), so it needs no API key to run — which took discipline to preserve as the codebase grew.

Accomplishments we're proud of

Three deploy surfaces from one engine — a live Agentverse agent, an MCP server inside Claude, and a provable web A/B demo — all reusing the same pure compression core. A live agent on Agentverse that's genuinely useful infrastructure, not a toy — it makes other agents cheaper. A provable demo: real token counts, side-by-side, with an animation that teaches the mechanism — and it survives adversarial prompts (it refused to bypass the "confirm before paying" and "no steakhouse" rules). Constraint-safety as a feature: RAVEN keeps the rules a bloated full-memory model drops. We turned "lost in the middle" from a risk into our demo's punchline. 80–90% token reduction with preserved decisions, reproducible from a clean checkout, backed by 116 tests. A design that's explainable end-to-end — every kept fact has a reason (guard vs. relevant).

What we learned

More context is not safer context. Past a point, extra tokens hurt — the model loses the critical rule. The relevant slice beats the whole memory on both cost and safety. Generic compression solves a different problem than ours. The papers optimize "shrink a prompt, keep generic answer quality." The agentic, constraint-sensitive use case needs "compress for a recipient without dropping the rules" — and bridging that gap (recipient-awareness + a constraint guard + a verifier) is the actual contribution. The limitations are mostly the problem talking back. Lossiness, imperfect relevance, and constraint-vs-relevance tension are fundamental; the value is in managing them honestly, not pretending to eliminate them. Least-privilege context is a privacy story, not just a cost story.

What's next

for RAVEN Publish the MCP server to PyPI so anyone adds RAVEN to Claude with one line (uvx raven-mcp), plus a persistent memory store and more tools (the MCP server already works locally inside Claude Desktop / Code / Cursor). An LLM API proxy (one-line base_url swap) so any existing app gets the savings with no rewrite. Learned relevance as an optional upgrade (embeddings / a small classifier) behind the same explainable interface, for users who'll trade a dependency for higher recall. Cross-agent passport caching and KV-level compression (Cache-to-Cache) for repeat back-context. Framework adapters (LangChain / CrewAI) so multi-agent builders get RELAY for free.

RAVEN — Verified Context Passports for the Agentic Web

RAVEN gives each AI agent a tiny, recipient-aware "context passport" instead of your whole memory — ~80–93% fewer context tokens, with every standing rule guaranteed to survive.

Most agent stacks make agents "smart" by dumping the entire user memory into every model call and every agent in a multi-agent system. It's expensive, slow, and unsafe: hand a capable model 1,700 tokens of notes and it will confidently recommend an Italian restaurant for a vegetarian — because the dietary rule was buried in the middle and got lost.

The bottleneck of the agentic web isn't model intelligence — it's context logistics: deciding who needs to know what. You don't brief a chef and an accountant with the same memo. RAVEN is the layer that gives each agent only the slice it needs, with the non-negotiable rules force-kept.

Same memory, two agents: the budget agent gets under $40 + confirm before paying; the calendar agent gets only free Friday after 7pm. Neither sees the other's facts. That's recipient-aware, least-privilege context — by construction.

Try it 3 ways

1. Inside Claude (MCP) — one line, no clone

Add this to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/ on macOS), then restart Claude:

{
  "mcpServers": {
    "raven": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/thesantoshpant/raven", "raven-mcp"]
    }
  }
}

Then ask Claude: "Use raven to compress this for the budget agent: Maya is vegetarian, keep dinner under $40, free Friday after 7pm, always confirm before paying." Tools exposed: compress_memory, relay_handoff, list_roles. No API key — RAVEN does pure, deterministic compression; the host model is the LLM. (Details: raven/mcp/README.md.)

2. On Fetch.ai Agentverse — a live uAgent

RAVEN runs as a Chat-Protocol uAgent discoverable from ASI:One.

Hosted (24/7): paste raven/fetch/raven_hosted_agent.py (a single self-contained file) into an Agentverse Blank Agent and press Start.
Local (mailbox): pip install -r requirements-fetch.txt, set RAVEN_AGENT_SEED, run python raven/fetch/raven_agent.py, connect the mailbox.

Then chat it: role: budget | memory: Maya is vegetarian. Keep dinner under $40. Confirm before paying.

3. Locally — the visual demo dashboard

A side-by-side A/B (same prompt with full memory vs. RAVEN's passport) showing the model's real input-token usage and an animated pipeline of exactly what RAVEN did.

git clone https://github.com/thesantoshpant/raven && cd raven
python -m venv .venv && .venv/Scripts/python -m pip install -r requirements-web.txt
.venv/Scripts/python -m uvicorn raven.web.api:app --port 8000      # backend
cd frontend && npm install && npm run dev                          # UI -> http://localhost:3000

⚠️ The dashboard's live A/B calls the Claude API (needs ANTHROPIC_API_KEY) and Next 14 has known advisories — it's local-demo-only; don't deploy as-is. The engine, gate, and tests need none of this.

What it does

RAVEN compresses at the two edges where context explodes:

Passport (user memory → agent). Atomize memory into typed facts (dietary, budget, permission, availability, location, preference…), retrieve what this role needs, guard the standing rules so they're never dropped, dedup, and render a tiny passport.
RELAY (agent → agent). On handoffs, forward the latest message verbatim + a compressed back-context passport instead of the whole growing transcript — ~90% smaller per hop, while standing constraints survive 3/3 hops (naive last-message forwarding drops them).

Results (reproducible from a clean checkout)

Measure	Result
Context-payload reduction (vs broadcasting full memory to every agent)	92.9%
A/B, real Claude input tokens (one prompt)	1,783 → 317 (~82%)
Decision benchmark at an equal token budget	RAVEN 5/5 vs generic role-unaware 4/5 (drops "confirm before paying")
RELAY handoff vs full transcript	8,560 → 889 (~90%), constraints kept 3/3 hops
Offline test suite	116 passing (stdlib, no network)

Corpus: 38 memory items / 127 facts. Model: Claude Haiku 4.5, temperature 0, disk-cached. Numbers from bench/run_gate.py, bench/run_m2.py, bench/run_relay.py.

The honest headline: at an equal token budget RAVEN ties a generic fact-store baseline on raw token count — that part isn't the moat. The moat is decision quality and constraint-safety at that budget: the guard routes "confirm before paying" to the budget agent even though the request never lexically mentions it, so RAVEN scores 5/5 where the role-unaware blob drops to 4/5.

How it works

Deterministic, stdlib-first, torch-free — so every claim is explainable and reproducible:

raw memory → split into atomic typed facts → BM25 retrieval (query-aware)
           → recipient-aware selection (keep the role's types)
           → critical-fact GUARD (force-keep standing-rule types, even at score 0)
           → dedup → render passport → count tokens

The guard is the key idea: a constraint can be lexically irrelevant to a query ("vegetarian" vs "where to eat") yet decision-critical. Pure relevance compression drops it — exactly the "lost in the middle" failure. The guard force-keeps standing-rule types, so the loss only ever lands on low-relevance facts, never a rule. Every kept fact carries a reason (guard vs relevant), so the output is fully auditable — no black-box compressor.

Architecture

One pure engine, three surfaces:

Engine (raven/): a custom BM25 retriever + typed-fact compression + the critical guard + an optional ACON-style verifier. Pure stdlib; no ML downloads.
MCP server (raven/mcp/): the engine as a tool for Claude Desktop / Code / Cursor.
Fetch.ai uAgent (raven/fetch/): Chat-Protocol agent for Agentverse / ASI:One + a single-file hosted build.
Web (raven/web/ + frontend/): FastAPI + Next.js dashboard with the live A/B and animated pipeline.

Engineering discipline: 116 offline tests with a strict isolation invariant — the test suite imports no uagents/fastapi/markitdown/mcp/network; the heavy transports are the sole importers of their SDKs, and the pure logic is tested separately.

Research grounding (lightweight, explainable variants)

Implemented	Grounded in
Query-aware extractive selection (custom BM25, not a learned classifier)	LongLLMLingua
Inter-agent comms pruning (RELAY)	AgentPrune / "Cut the Crap"
Guideline learning without fine-tuning (the verifier)	ACON
Constraint-compliance vs. accuracy separation (deterministic gold scoring)	CDCT
Near-duplicate anchoring (dedup)	SeCo

Deliberately not used: a learned token classifier (LLMLingua-2) or KV-cache compression (Cache-to-Cache) — extractive + deterministic is why RAVEN can prove decision-preservation (it can point at the exact kept fact and its reason).

Honest limitations

Compression is lossy by definition — RAVEN bounds the loss to low-relevance facts and never to standing rules (the guard).
BM25 has vocabulary-mismatch failures; mitigated by the recipient model + guard. Learned relevance is an optional future upgrade behind the same interface.
Single hand-authored scenario for the decision benchmark — an existence proof of the recipient-aware win, not a broad rate. More scenarios + a stronger (embedding) baseline are future work.
ASI:One auto-discovery is best-effort (the host model routes by description).

Repo layout

raven/raven/      engine: ingest, retrieve, compress, relay, roles, score, verifier, tokens, schemas
raven/raven/mcp/  MCP server (compress_memory / relay_handoff / list_roles)
raven/raven/fetch/  Fetch.ai uAgent + single-file hosted build + Bureau demo
raven/raven/web/  FastAPI backend over the engine
frontend/         Next.js dashboard (A/B, animated pipeline, token meter)
bench/            run_gate.py · run_m2.py · run_relay.py
tests/            116-test offline suite

What's next

Publish the MCP server to PyPI (uvx raven-mcp); an LLM API proxy (one-line base_url swap); learned relevance as an optional upgrade; cross-agent passport caching; LangChain / CrewAI adapters.

License

MIT — see LICENSE.

Analysis

Compare with all teams

View

Metric

Santosh Pant
28

Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.

Technology

Found in codeClaimed only

CSSIn code
JavaScriptIn code
Next.jsIn code
PythonIn code
ReactIn code
FastAPIClaimed

5 of 6 appear in the indexed code. 1 claimed on Devpost could not be matched to code, which may simply mean the tool leaves no trace in the repository.

AI coding agents

No AI coding agent signals were found in this repository.

Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.

Codebase size

Source size

279 KB

Source files

Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.

Project Info

RAVEN: Verified Context Passports for the Agentic Web

Inspiration

What it does

How we built it

Challenges we ran into

Accomplishments we're proud of

What we learned

What's next

RAVEN — Verified Context Passports for the Agentic Web

Try it 3 ways

1. Inside Claude (MCP) — one line, no clone

2. On Fetch.ai Agentverse — a live uAgent

3. Locally — the visual demo dashboard

What it does

Results (reproducible from a clean checkout)

How it works

Architecture

Research grounding (lightweight, explainable variants)

Honest limitations

Repo layout

What's next

License

Analysis

Technology

AI coding agents

Codebase size

Structure

Interface

Application logic

Languages

Dependencies