context-kernel sits between inbound agent context and the model call. It helps you classify requests, choose a route, trigger compaction, apply policy guards, extract memory candidates, and emit audit events before generation starts.

What it is good for

Use it when you are building:

• agent backends that need routing, guardrails, and memory hooks
• OpenClaw or OpenClaw-like runtimes that need a reusable pre-generation control layer
• multi-model systems where some requests should stay local and others should escalate
• compliance-sensitive assistants that need structured audit events
• multi-agent systems that benefit from shared-memory, snapshots, or utility scoring modules

What it is not

context-kernel is not a full agent framework, vector database, orchestration platform, or autonomous runtime. It is the decision layer in front of those systems.

Core capabilities

• Input classification - text vs multimodal, plus task types like chat, code, memory, admin, urgent
• Route selection - map classifications to local or premium model lanes
• Budget signaling - trigger compress: true when token thresholds are exceeded
• Policy enforcement - quiet hours, action allowlists, secret detection, and PII guard
• Memory hooks - extract memory candidates with writeback hints
• Versioned memory snapshots - compact and retain context history over time
• Audit events - emit lifecycle events like started, classified, routed, and completed
• Adapters - OpenClaw, HTTP, and file-backed storage surfaces
• Utilities - deduplication, priority scoring, eviction, snapshots, shared-memory pools, and bulk helpers

Install

npm install context-kernel

Quick start

import { ContextKernel } from "context-kernel";

const kernel = new ContextKernel({
  router: {
    tokenCompressionThreshold: 10_000,
    allowPremiumEscalation: true,
    routeMap: {
      textDefault: "local_text",
      multimodal: "local_vision",
      urgent: "premium",
      codeHighContext: "premium",
    },
  },
  policy: {
    postOnlyMode: false,
    rules: [
      { id: "safe-actions", kind: "action_allowlist", actions: ["send", "post", "tool_call"] },
    ],
  },
});

const decision = await kernel.decide({
  sessionId: "sess-001",
  timestamp: new Date().toISOString(),
  messages: [{ role: "user", content: "Help me refactor this repo" }],
  estimatedTokens: 12_000,
});

console.log(decision.taskType);  // "code"
console.log(decision.route);     // "premium"
console.log(decision.compress);  // true

Mental model

The kernel does not execute the model call for you. It returns a grounded decision object your runtime can act on.

{
  inputKind: "text",
  taskType: "code",
  route: "premium",
  compress: true,
  policyVerdicts: { ... },
  memoryCandidates: [ ... ],
  actions: [ ... ]
}

Main API surface

new ContextKernel(config, hooks?)

Creates the decision engine.

await kernel.decide(input)

Evaluates one inbound request and returns a KernelDecision.

Adapters

import { fromOpenClawEnvelope } from "context-kernel/adapters/openclaw";
import { fromHttpEnvelope } from "context-kernel/adapters/http";

Schemas

import { kernelInputSchema, kernelConfigSchema } from "context-kernel/schemas";

Common use cases

1. Route expensive requests selectively

Keep normal chat local, but escalate urgent or high-context code tasks.

2. Apply policy before tool execution

Use quiet hours, secret regex checks, and action allowlists before downstream workers act.

3. Extract memory candidates without hardcoding heuristics everywhere

Let the kernel suggest what belongs in user memory or durable workspace memory.

4. Add observability to agent decisions

Emit structured events so you can inspect why a route or block happened.

5. Reuse context utilities outside the kernel

Use exported modules like deduplication, priority scoring, snapshots, and shared-memory pools independently.

Included modules

Core runtime pieces

• ContextKernel
• MemoryManager
• compaction helpers
• identity drift helpers
• Zod schemas

Utility modules

• deduplicateEntries() / findDuplicate()
• scoreEntries() / topK()
• evict()
• snapshot store helpers
• shared-memory registry helpers
• audit trail helpers
• bulk context-store helpers
• PII scanning helpers

CLI

npx context-kernel --config ./kernel.config.json --input ./input.json
npx context-kernel --snapshots ./kernel-data
npx context-kernel --delete-snapshot 0.2.0 --storage ./kernel-data

Example configs

• examples/kernel.config.json
• examples/preset.openclaw.json
• examples/preset.generic.json
• examples/input.json

Current limits

Today the package is strongest as a library for agent builders, not a turnkey platform. A few things are intentionally left to the host runtime:

• actual model execution
• vector retrieval infrastructure
• long-term persistent backends beyond provided adapters
• workflow orchestration and retries
• product-specific policy semantics

Who should use this

Use context-kernel if you want a reusable, testable place for:

• model routing rules
• token-budget decisions
• preflight safety policy
• memory extraction contracts
• traceable agent decisions

If you just need a chatbot wrapper, this is probably too low-level.

Links

• Architecture: ARCHITECTURE.md
• Changelog: CHANGELOG.md
• Security: SECURITY.md
• Release notes / roadmap: ROADMAP_v0.7.0.md

Built with teeth. 🌑