A portable, vendor-neutral layer that decides what context an AI agent receives for each request — smaller, safer prompts, only when safe.
ZAM (a "Context Control Plane") runs before an agent builds its prompt. Given the user's request and an inventory of available context components — system scaffolds, skills, tools, memory, history — it decides which ones to include, omit, or defer, and records why. It emits a structured plan, never assembled prompt text: the model proposes, deterministic guardrails enforce.
🧪 Early and open (v0.1.x). It's published and tested (743 passing), but young — feedback is very welcome. Try it (
npm install context-plane) and tell me what's confusing, missing, or broken via an issue or a discussion.
Most agent runtimes inject everything every turn — every skill, every tool definition, every memory lane — regardless of what the user actually asked. That bloats the prompt (cost + latency), buries the relevant context, and degrades answers. Trimming it by hand is risky: drop the wrong thing and you silently break safety or correctness.
A deterministic pipeline classifies the request and runs a 12-step selector ladder, a conflict resolver, and a budgeter to produce, per turn:
prompt-plan.json— the selected / omitted / deferred components,trace.json— the full, auditable decision trace,summary.md— a human-readable narrative.
Design properties (the spine of the project):
- Fail-open on uncertainty — it only makes the context smaller when it is safe to; when unsure, it includes more. "Smaller context only when safe."
- Deterministic & reproducible — no model call is required to plan; the same input yields the same plan.
- Schema-validated & fail-closed outputs — it refuses to emit an invalid plan.
- Auditable — every decision carries a reason and a trace.
- Portable — the core depends on no particular runtime; adapters map any host into it.
Try it in one command — offline, deterministic, no API key: npm run benchmark reproduces the
headline number on a realistic registry.
-
Offline benchmark (
benchmarks/): 63.9% mean token savings with 0 unsafe omissions vs. the naive "inject everything" baseline. -
Live benchmark (optional, key-gated): the cheap deterministic router agrees with a model's classification 85.7% of the time — and both disagreements were on the safe side (it fell back to fuller context). Answer-quality preservation ~80%.
-
Three reference adapters demonstrate the contract is surface-independent — the same deterministic core governs three very different surfaces with zero core changes:
Adapter Surface What it shows zam-adapter-openclawagent workspace (Markdown files) 73% saved on a greeting, 53% on a coding request; safety always kept zam-adapter-mcpMCP tools / resources / prompts prunes the tool list per request; destructive tools surfaced only for ops zam-adapter-telegramTelegram bot metadata uses the requestSignalscaller tier (group / reply → family)These are reference adapters run against documented, synthetic inputs (each package's README states its scope) — they demonstrate the planning contract and its portability, not live production integrations. ("OpenClaw" here denotes a generic agent-workspace shape —
AGENTS.md-style scaffolds, skills, tools — not a third-party dependency.)
request ──▶ request router (deterministic) ──▶ 12-step selector ladder
│
conflict resolver
│
budgeter
│
prompt-plan.json · trace.json · summary.md
An adapter's job (see any of the three above, and docs/37 §5) is always the same four steps:
extract the host's context into a ZAM registry, call plan(), assemble the prompt from the
selected components, and feed it back to the host's loop. No per-turn model call is required.
Add it to your project:
npm install context-planeOr develop ZAM itself — clone, then:
npm install
npm run build
npm testSee the value (offline, deterministic, no API key):
npm run demo # narrated walkthrough — watch ZAM keep/drop context per request
npm run benchmark # the metrics — 63.9% mean token savings, 0 unsafe omissionsCLI:
context-plane plan --request <text-file> --registry <registry.json> --output-dir ./out
# writes out/prompt-plan.json, out/trace.json, out/summary.mdAs a library:
import { plan } from 'context-plane';
const { promptPlan, trace, summary } = plan({
request: { text: 'Help me debug the failing build.' },
registry, // ComponentRegistryEntry[] — see docs/05
});
console.log(promptPlan.selectedComponents);As an HTTP service (language-agnostic): the ./http export serves a POST /plan endpoint with
constant-time API-key auth (X-ZAM-API-Key). See src/http.
| Path | What |
|---|---|
src/ |
the deterministic core (router → ladder → conflict resolver → budgeter), CLI, and HTTP service |
packages/runtime/ |
a thin agent runtime used as a validation harness |
packages/types/ |
shared hand-authored types (@zam/types) |
packages/adapter-openclaw/, adapter-mcp/, adapter-telegram/ |
the three reference adapters |
benchmarks/ |
the offline (committed, deterministic) and live (key-gated) value benchmarks |
schemas/ |
JSON Schemas for every input/output (the open registry + plan formats) |
docs/ |
numbered scoping records — the engineering decision log, one document per change |
fixtures/, tests/ |
the E2E fixture corpus and the test suites |
The roadmap is complete and the tree is green: core suite 743/743, runtime 354/354, adapters
12 + 11 + 10, all run in CI on every push/PR. Known gaps and tracked debt live honestly in
DEBT.md rather than being asserted absent.
This repository is the open reference: the spec, the registry/plan formats (schemas/), the
reference implementation, and the reference adapters — under Apache-2.0. Managed hosting, bespoke
adapters, and support are the commercial side. The boundary is drawn in
docs/37.
See CONTRIBUTING.md and SECURITY.md.
Apache-2.0 — permissive, with an explicit patent grant.