> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emergence.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'lineColor': '#555555', 'fontFamily': 'sans-serif', 'edgeLabelBackground': '#ffffff'}}}%%
flowchart TB
    Query["Agent Query"] --> S["Summary Layer<br/>(fast, always loaded)"]
    S --> M["Metadata Layer<br/>(selective, on match)"]
    M --> C["Content Layer<br/>(full detail, on demand)"]

    classDef query fill:#56B4E9,stroke:#555555,color:#000
    classDef layer fill:#E69F00,stroke:#555555,color:#000
    class Query query
    class S,M,C layer
```

| 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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="Phase 2: Retrieve">
    For matched packs, retrieve specific memories using semantic search within the pack's content layer. Returns ranked memory records with scores.
  </Step>
</Steps>

## 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)      |
| **team**         | Shared team knowledge and conventions                         | Conservative (months)      |
| **data\_source** | Data-source-specific schema, joins, and profiling context     | Conservative (months)      |

## Memory Record Schema

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

```json theme={null}
{
  "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

```python theme={null}
import httpx

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

### Create a Pack

```python theme={null}
response = httpx.post(
    "https://api.example.com/utils/context-packs",
    headers={"Authorization": f"Bearer {token}", "X-Project-ID": project_id},
    json={
        "name": "semiconductor_domain",
        "pack_type": "domain",
        "description": "Knowledge about semiconductor fabrication processes and terminology",
        "meta_data": {"tags": ["semiconductor", "fabrication", "yield"]}
    }
)
```

### Query a Pack (Phase 2 retrieval)

```python theme={null}
response = httpx.get(
    f"https://api.example.com/utils/context-packs/{pack_name}/memories",
    headers={"Authorization": f"Bearer {token}", "X-Project-ID": project_id},
    params={
        "memory_type": "fact",
        "page_size": 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

<CardGroup cols={2}>
  <Card title="Memory Service" icon="brain" href="/platform/memory-service">
    Overview of the memory system and API usage.
  </Card>

  <Card title="Memory Integration Guide" icon="code" href="/guides/memory-integration">
    Step-by-step guide to adding memory to your agents.
  </Card>
</CardGroup>