Context Packs

Context Packs are the storage containers for agent memories, organizing related memories into retrievable, structured units that agents query for relevant context.

Context Packs

A Context Pack is the fundamental storage unit for agent memories. It groups related memories into a named, typed container that agents query when they need relevant background knowledge before responding or acting.

Three-Layer Architecture

Context Packs use a three-layer structure that balances retrieval speed with information depth:

Layer	Contents	When Loaded
Summary	High-level description, topic tags, last-updated timestamp	Always, fast pack discovery
Metadata	Memory count, type distribution, confidence scores, access patterns	On pack selection
Content	Full memory records with embeddings, provenance, relationships	On demand, specific memory retrieval

Two-Phase Query Model

Agents retrieve context through a two-phase process that avoids loading unnecessary detail:

1. Phase 1: Discover

   Query Context Pack summaries to find relevant packs. Returns pack IDs, topic descriptions, and match scores. Fast, only summary layer is read.

2. Phase 2: Retrieve

   For matched packs, retrieve specific memories using semantic search within the pack’s content layer. Returns ranked memory records with scores.

Context Pack Types

Type	Purpose	Decay rate
session	Single conversation context, ephemeral, high detail	Aggressive (hours to days)
user	Long-term user preferences and history, persistent	Conservative (months)
domain	Domain knowledge, facts, rules, entity relationships	Very conservative (years)
project	Project-specific context, decisions, conventions, constraints	Conservative (months)
agent	Agent-specific learned behaviors and patterns	Conservative (months)

Memory Record Schema

Each memory stored in a Context Pack has the following structure:

{
  "id": "uuid",
  "content": "The main memory text (self-contained, context-independent)",
  "memory_type": "fact | experience | observation | instruction | preference | summary | glossary | ontology | textual_pattern | kpi | exemplar | join | numeric_pattern | policy",
  "name": "optional_label_for_direct_retrieval",
  "metadata": {
    "source": "conversation | document | agent_message",
    "confidence": 0.92,
    "created_at": "2026-04-07T10:30:00Z",
    "last_accessed": "2026-04-07T14:22:00Z",
    "access_count": 7,
    "superseded_by": null,
    "provenance": "Session #142, turn 3"
  },
  "embedding": [0.123, -0.456, ...],
  "relationships": [
    {"type": "supersedes", "target_id": "uuid-of-old-memory"},
    {"type": "related_to", "target_id": "uuid-of-related-memory"}
  ],
  "degradation_tier": "full | summary | key_facts | existence_marker | archived"
}

Managing Context Packs via API

List Packs

import httpx

response = httpx.get(
    "https://api.example.com/utils/context-packs",
    headers={"Authorization": f"Bearer {token}"},
    params={"type": "domain"}
)
packs = response.json()["data"]

Create a Pack

response = httpx.post(
    "https://api.example.com/utils/context-packs",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "name": "semiconductor_domain",
        "type": "domain",
        "description": "Knowledge about semiconductor fabrication processes and terminology",
        "tags": ["semiconductor", "fabrication", "yield"]
    }
)

Query a Pack (Phase 2 retrieval)

response = httpx.get(
    f"https://api.example.com/utils/context-packs/{pack_name}/memories",
    headers={"Authorization": f"Bearer {token}"},
    params={
        "memory_type": "fact",
        "limit": 5
    }
)
memories = response.json()["data"]

Degradation Tiers

Memories in Context Packs degrade gracefully over time when not accessed:

Tier	Description	Storage impact
full	Complete memory record with all detail	Full
summary	Key points only, detail compressed	~30%
key_facts	Core facts only, context removed	~10%
existence_marker	Memory existed, no content	Minimal
archived	Moved to cold storage, not retrieved	Off-heap

Any retrieval access re-promotes a memory to the full tier. This ensures frequently-used memories remain fully detailed while inactive memories are progressively compressed.

Related

Memory Service

Overview of the memory system and API usage.

Memory Integration Guide

Step-by-step guide to adding memory to your agents.