HazelJS Context Package

@hazeljs/context is the unified Agent Context Engine. It plans which substrates to call and assembles their output for the LLM under a shared token budget.

One planner. Four context layers.

CAG, RAG, KAG, and Memory stay independently useful. This package is the planner + assembler — not a wrapper that replaces them.

Reach for @hazeljs/context when a single user utterance needs more than one layer (e.g. policy + ledger + handbook + preference). Use a package alone when you only need one substrate.

Quick Reference

Purpose: Orchestrate CAG + RAG + KAG + Memory without hard-coupling Agent OS to any one package.
When to use: Hybrid support / ops desks; any agent whose questions mix stable policy, docs, structured “why”, and user preferences.
Key APIs: ContextModule.forRoot / forRootAsync, ContextService.assemble, ContextPlanner (auto | all | explicit), ContextAssembler, duck-typed ports (cag, rag, kag, memory), contributor adapters.
Dependencies: Peer @hazeljs/core. Optional peers: @hazeljs/cag, @hazeljs/rag, @hazeljs/kag, @hazeljs/memory.
Common mistakes: Expecting context to replace RAG/CAG/KAG; skipping tenantId on assemble(); treating plan.rationale as model chain-of-thought; wiring only one port when the query needs several.

Architecture

Query → ContextPlanner → CAG | RAG | KAG | Memory → ContextAssembler → LLM

Source	Package	Role
cache / CAG	@hazeljs/cag	Stable, reusable context
RAG	@hazeljs/rag	Query-relevant passages
knowledge / KAG	@hazeljs/kag	Entities, facts, relations
Memory	@hazeljs/memory	Continuity & preferences

Background: RAG vs CAG vs KAG.

Installation

npm install @hazeljs/context @hazeljs/core
# optional peers as needed:
npm install @hazeljs/cag @hazeljs/kag @hazeljs/rag @hazeljs/memory

Quick Start

import { ContextModule, ContextService } from '@hazeljs/context';

ContextModule.forRoot({
  strategy: 'auto',
  sources: ['cache', 'rag', 'knowledge', 'memory'],
  cag: cagService,     // duck-typed @hazeljs/cag
  rag: ragService,     // duck-typed @hazeljs/rag
  kag: kagService,     // duck-typed @hazeljs/kag
  memory: memoryService,
});

const assembled = await context.assemble({
  query: 'Why was settlement lower given our refund policy and my VAT preference?',
  tenantId: 'merchant-123',
  namespace: 'support',
  userId: 'ops-1',
});

// assembled.text          → labeled blocks for the LLM
// assembled.plan.sources  → which contributors ran
// assembled.plan.rationale → why (observability, not model CoT)
// assembled.sourcesUsed / tokenEstimate

Strategies

Strategy	Behavior
`auto`	Heuristic selection from the query (policy → CAG, why/entity → KAG, preference → memory, lookup → RAG; complex queries combine)
`all`	Every registered contributor
`explicit`	Only the `sources` list

Aliases: cache → CAG, knowledge → KAG.

Contributors soft-fail independently so one outage does not blank the entire prompt.

Agent Integration

Inject as AgentRuntimeConfig.contextService. When present, it is preferred over calling CAG/RAG/KAG ports individually.

DNA may declare:

{
  "context": {
    "strategy": "auto",
    "sources": ["cache", "rag", "knowledge", "memory"]
  }
}

Individual context.cag / rag / kag / memory flags remain valid for simpler agents.

Production Guide

Always pass tenantId on assemble()
Inspect assembled.plan.rationale in logs / Inspector — it is planner observability, not hidden model CoT
Register only the peers you need; unused ports are skipped
Keep token budgets aligned with your LLM context window
Soft-fail behavior is intentional — alert on per-contributor errors separately

Try it offline

Local Agent OS + context (apply / HITL path):

hazel new agent my-desk --template=context
# or in-repo: examples/support-desk-context → npm run demo && npm run demo:hitl

See Local Agent OS — context desk.

Package-only Meridian labs (not hazeld apply):

# from hazeljs-meridian-ops/
npm run example:install
npm run example:context

context-auto-agent auto-plans CAG + RAG + KAG + Memory for a hybrid settlement question.

Also useful: example:rag · example:cag · example:kag in the same examples/ folder.

CAG Package
RAG Package
KAG Package
Memory Package
Agent Package — contextService runtime port
RAG vs CAG vs KAG
support-desk-context example
Meridian Ops examples
Package README

License

Apache-2.0