JSPM

��<p align="center"> <img src="assets/darksol-banner.png" alt="DARKSOL" width="600" /> </p> <h3 align="center">Built by DARKSOL a"�
��</h3> --- # context-kernel The brain between your agent and your models. Platform-agnostic context routing kernel for agent runtimes. Classifies inputs, routes to the right model, enforces policy gates, extracts memory candidates, and emits audit events ��� all before a single token gets generated. Drop it into any agent system and stop hardcoding your routing logic. [](https://www.npmjs.com/package/context-kernel) [](https://opensource.org/licenses/MIT) [](https://nodejs.org/) ## Install bash npm install context-kernel ## Quick Start ### Basic routing decision ts import { ContextKernel } from "context-kernel"; const kernel = new ContextKernel({ router: { tokenCompressionThreshold: 10000, allowPremiumEscalation: true, routeMap: { textDefault: "local_text", multimodal: "local_vision", urgent: "premium", codeHighContext: "premium", }, }, policy: { postOnlyMode: false }, }); const decision = await kernel.decide({ sessionId: "sess-001", timestamp: new Date().toISOString(), messages: [{ role: "user", content: "Help me refactor this repo" }], estimatedTokens: 12000, }); console.log(decision.route); // "premium" (code + high tokens) console.log(decision.compress); // true (over threshold) console.log(decision.taskType); // "code" ### Policy enforcement with quiet hours ts const kernel = new ContextKernel({ router: { tokenCompressionThreshold: 8000, allowPremiumEscalation: false }, policy: { postOnlyMode: false, quietHours: { startHour: 23, endHour: 7 }, rules: [ { id: "safe-actions", kind: "action_allowlist", actions: ["send", "post"] }, { id: "no-keys", kind: "secret_regex", patterns: ["AKIA[0-9A-Z]{16}"], severity: "high" }, ], }, }); ### OpenClaw adapter ts import { fromOpenClawEnvelope } from "context-kernel/adapters/openclaw"; const kernelInput = fromOpenClawEnvelope({ sessionKey: "oc-session-42", timestamp: new Date().toISOString(), messages: [{ role: "user", content: "Summarize this image" }], images: [{ name: "screenshot.png" }], }); const decision = await kernel.decide(kernelInput); // inputKind: "multimodal" ��� routes to vision model ### HTTP adapter ts import { fromHttpEnvelope } from "context-kernel/adapters/http"; const kernelInput = fromHttpEnvelope({ id: "req-abc", at: new Date().toISOString(), payload: { messages: [{ role: "user", content: "What's the weather?" }], estimatedTokens: 500, }, }); ### CLI usage bash npx context-kernel --config ./kernel.config.json --input ./input.json ## Input Classification The kernel classifies every input along two axes: Input kind ��� text or multimodal (detected from attachments) Task type ��� pattern-matched from message content: | Task Type | Triggers | |-----------|----------| | urgent | "urgent", "asap", "immediately" | | code | "refactor", "typescript", "bug", "test", "build", "npm", "repo", "PR" | | memory | "remember", "recall", "note this" | | admin | "config", "policy", "settings", "permission" | | chat | everything else | ## Model Routing Routes are resolved from your routeMap based on classification: ts routeMap: { textDefault: "local_text", // default for text chat multimodal: "local_vision", // any input with image/audio attachments urgent: "premium", // urgent requests escalate codeHighContext: "premium", // code tasks over token threshold premiumFallback: "premium", // fallback when escalation is allowed } Premium escalation (allowPremiumEscalation) controls whether urgent and high-context code tasks can jump to premium models. Disable it to keep everything local. ## Token Budget & Compression ts router: { tokenCompressionThreshold: 10000 // trigger compression above this } When estimatedTokens exceeds the threshold, the decision returns compress: true with a compressionReason. Your downstream worker handles the actual compression ��� the kernel just makes the call. ## Policy Engine Three built-in guards run on every request, plus a rule DSL for custom policies: ### Built-in guards - Post-only mode ��� restricts actions to post/send when postOnlyMode: true - Quiet hours ��� blocks during configured hours (supports overnight ranges like 23���7) - Secret detection ��� regex scan on message content (defaults: api_key, password, token, secret, AKIA...) ### Custom rules ts rules: [ // Only allow specific actions { id: "safe-actions", kind: "action_allowlist", actions: ["send", "post", "tool_call"] }, // Block during overnight hours { id: "overnight", kind: "quiet_hours", startHour: 1, endHour: 6, severity: "low" }, // Catch leaked credentials { id: "no-aws", kind: "secret_regex", patterns: ["AKIA[0-9A-Z]{16}"], severity: "high" }, // PII detection ��� block, warn, or redact { id: "no-pii", kind: "pii_guard", action: "block", types: ["email", "ssn"], severity: "high" }, ] Every guard and rule produces a PolicyVerdict with allowed, reason, ruleId, and severity. ## Memory Extraction The kernel scans user messages for memory-worthy content and returns MemoryCandidate[]: | Strategy | Trigger patterns | Priority | TTL | |----------|-----------------|----------|-----| | preference | "remember", "always", "never", "I prefer" | high | 365 days | | decision | "decided", "we will", "approved" | high | 180 days | | summary | long messages (>220 chars) | medium | 30 days | Each candidate includes writebackHint with namespace, optional upsert key, and TTL ��� ready for your memory store. Hook into extraction: ts const kernel = new ContextKernel(config, { onMemoryCandidates: (candidates, input) => { for (const c of candidates) { console.log([${c.priority}] ${c.source.strategy}: ${c.summary}); } }, }); ## Audit Events Every decision emits a lifecycle of events via the onEvent hook: ts const kernel = new ContextKernel(config, { onEvent: (event) => console.log(JSON.stringify(event)), }); Events: started ��� classified ��� guard_blocked? ��� compressed? ��� routed ��� completed | failed Each event carries sessionId, timestamp, and a detail object for observability. ## PII Detection Scan messages for personally identifiable information with configurable actions: ts import { scanForPII, scanMessages } from "context-kernel"; // Scan a single string const result = scanForPII("Email me at john@example.com", { action: "redact" }); console.log(result.detected); // true console.log(result.redactedText); // "Email me at [REDACTED]" // Scan all messages const msgResult = scanMessages(messages, { action: "warn", types: ["email", "ssn"] }); Supported PII types: email, phone, ssn. Actions: redact (mask), warn (flag but allow), block (reject). Integrates directly into the kernel as a pii_guard policy rule ��� see Custom rules above. ## Semantic Deduplication Detect and merge near-duplicate context entries using cosine similarity on term-frequency vectors: ts import { deduplicateEntries, findDuplicate } from "context-kernel"; const result = deduplicateEntries(entries, { similarityThreshold: 0.85 }); console.log(result.unique); // entries that survived console.log(result.merged); // groups of merged duplicates console.log(result.removedCount); // total entries removed // Check a single entry against a corpus const dup = findDuplicate(candidate, corpus, { similarityThreshold: 0.85 }); if (dup) console.log(Duplicate of ${dup.match.id} (${dup.similarity})); ## Priority Scoring Rank context entries by relevance, recency, and usage frequency: ts import { scoreEntries, topK } from "context-kernel"; const scored = scoreEntries(entries, "TypeScript generics", usageRecords, { relevanceWeight: 0.5, recencyWeight: 0.3, frequencyWeight: 0.2, recencyHalfLifeHours: 24, }); // Or just get the top results const top5 = topK(entries, "TypeScript generics", 5, usageRecords); Each ScoredEntry includes a breakdown with individual relevance, recency, and frequency scores. ## Eviction Policies Enforce bounded context stores with automatic eviction: ts import { evict } from "context-kernel"; // LRU ��� evict least recently used const lruResult = evict("lru", entries, { maxEntries: 100 }, accessRecords); // LFU ��� evict least frequently used const lfuResult = evict("lfu", entries, { maxEntries: 100 }, accessRecords); // TTL ��� evict entries older than 24 hours const ttlResult = evict("ttl", entries, { ttlMs: 24 * 60 * 60 * 1000 }); console.log(ttlResult.retained); // entries that survived console.log(ttlResult.evicted); // entries that were removed ## Audit Trail Structured audit logging with query API and JSONL export: ts import { createAuditTrail, createAuditHook, queryAuditTrail, exportJSONL } from "context-kernel"; const trail = createAuditTrail(); const kernel = new ContextKernel(config, { onEvent: createAuditHook(trail) }); // After running decisions... const result = queryAuditTrail(trail, { sessionId: "sess-001", eventTypes: ["completed", "guard_blocked"], limit: 50, }); // Export for log ingestion const jsonl = exportJSONL(trail); ## Shared Memory Pools Cross-session context sharing for multi-agent coordination: ts import { createSharedMemoryRegistry, createPool, publish, readPool, subscribe } from "context-kernel"; const registry = createSharedMemoryRegistry(); createPool(registry, "workspace", 1000); // max 1000 entries // Agent A publishes context publish(registry, "workspace", "agent-a", { id: "e1", content: "...", timestamp: "..." }); // Agent B subscribes and reads subscribe(registry, "workspace", "agent-b"); const entries = readPool(registry, "workspace", { excludeSessionId: "agent-b" }); ## Context Snapshots Save and restore full context state for session replay or branching: ts import { createSnapshotStore, takeSnapshot, restoreSnapshot } from "context-kernel"; const store = createSnapshotStore(); takeSnapshot(store, { id: "before-refactor", sessionId: "sess-001", entries: currentEntries, usageRecords: currentUsage, label: "pre-refactor checkpoint", }); // Later, restore the snapshot const { entries, usageRecords } = restoreSnapshot(store, "before-refactor"); ## Bulk Operations Efficient batch operations for context stores: ts import { createContextStore, bulkInsert, bulkDelete, bulkQuery, bulkGet } from "context-kernel"; const store = createContextStore(); // Batch insert const insertResult = bulkInsert(store, entries); console.log(insertResult.inserted); // count of successfully inserted console.log(insertResult.failed); // count of failures (duplicate ids, etc.) // Batch delete const deleteResult = bulkDelete(store, ["id-1", "id-2", "id-3"]); // Batch get const found = bulkGet(store, ["id-1", "id-2"]); // Query with predicate and pagination const queryResult = bulkQuery(store, (e) => e.content.includes("TypeScript"), { limit: 10, offset: 0, }); ## Zod Validation All inputs and configs are validated at runtime with Zod schemas. Import them directly: ts import { kernelInputSchema, kernelConfigSchema } from "context-kernel/schemas"; const config = kernelConfigSchema.parse(rawConfig); // throws on invalid const input = kernelInputSchema.parse(rawInput); ## Configuration Reference | Option | Type | Default | Description | |--------|------|---------|-------------| | router.tokenCompressionThreshold | number | 10000 | Token count that triggers compression | | router.allowPremiumEscalation | boolean | true | Allow urgent/code tasks to escalate to premium models | | router.modelRegistry | Record<string, {provider?, model}> | ��� | Named model targets (informational) | | router.routeMap | object | ��� | Maps task classifications to model keys | | policy.postOnlyMode | boolean | false | Restrict to post/send actions only | | policy.quietHours | {startHour, endHour, timezone?} | ��� | Global quiet hours window | | policy.blockedSecretPatterns | string[] | common patterns | Regex patterns for secret detection | | policy.rules | PolicyRule[] | [] | Custom policy rules (allowlist, quiet hours, secret regex, PII guard) | ## Links - GitHub: [github.com/darks0l/context-kernel](https://github.com/darks0l/context-kernel) - Changelog: CHANGELOG.md - Architecture: ARCHITECTURE.md - Security: SECURITY.md - License: MIT --- Built with teeth. a"�
��