ACAgentic Craft

Intermediate~16 minHazelJS

Memory Layers

Separate working context, session state, long-term memory, and artifacts in HazelJS so agents scale without stuffing everything into one prompt.

Authors
editorial-team
Published
Last reviewed

Problem

Putting all history, retrievals, and artifacts into one prompt hits context limits, raises cost, and increases leakage risk.

Context

Multi-turn and multi-run HazelJS agents that must recall user preferences, prior AgentRun state, or large documents without naive concatenation.

Forces and constraints

  • Models need the right facts at the right time
  • Context windows and budgets are finite
  • Different data has different retention and sensitivity
  • Stale memory causes confident wrong actions

Recommended design

Define layers: (1) working context assembled per AgentRuntime step, (2) session/run state on the durable AgentRun, (3) long-term memory via @hazeljs/memory and/or AgentMemoryGraph, (4) artifacts/object store references. Promote/demote explicitly with enableMemory / enableRAG flags. Prefer pointers + summaries over raw dumps. Version and expire memories.

Minimal pseudocode

import { AgentRuntime, AgentMemoryGraph } from '@hazeljs/agent';
// long-term store from '@hazeljs/memory' as configured in the app

const graph = new AgentMemoryGraph();
graph.upsertNode({ type: 'preference', content: 'deploy window: Tue 14:00 UTC' });

const result = await runtime.execute('SupportAgent', { message }, {
  enableMemory: true,
  enableRAG: true,
  sessionId,
  userId,
  initialContext: {
    memoryGraph: graph.toJSON(), // or load from @hazeljs/memory
  },
  maxSteps: 6,
});

// Persist graph / memory writes under retention policy — not raw full transcripts

Failure modes

  • Memory poisoning via injected content
  • Unbounded growth of session logs
  • Wrong-layer writes (secrets into long-term memory)
  • Stale preferences overriding new instructions

Security considerations

  • Tenant isolation on all memory stores
  • PII minimization and redaction pipelines
  • Write gates for long-term memory
  • Audit access to memory stores; never dump secrets into AgentMemoryGraph

Observability signals

  • Tokens per layer in assembled context
  • Retrieval hit/miss and freshness metrics
  • Memory write rates and deletion/TTL compliance
  • Inspector timeline should show memory/RAG spans when enabled

Evaluation approach

Tasks that require recalling prior facts; negative tests for forgetting revoked preferences; privacy tests ensuring secrets are not memorized.

Trade-offs

  • Better long-horizon performance vs storage/privacy complexity
  • Summaries save tokens but can drop critical details

Sources

Related patterns