Skip to main content

​
Memory Service

The Memory Service provides multi-agent memory management for CRAFT. It gives agents the ability to remember information across conversations, accumulate domain knowledge, and personalize responses based on prior interactions. Memory is built into the Utils service (em-runtime-utils). No separate service is required — the same Utils API that handles schedules, metadata, and catalog tags also manages Context Packs and Memories.

​
Key Concepts

​
Memories

A memory is a discrete, self-contained piece of information extracted from conversations, documents, or agent messages. Each memory has:
  • Content: The information itself (a fact, preference, insight, or relationship)
  • Type: The category of memory (fact, preference, observation, glossary, policy, etc., see Memory Types below)
  • Name: An optional label for direct retrieval
  • Metadata: Source, timestamp, confidence, access count
  • Embeddings: Vector representation for semantic search

​
Context Packs

A Context Pack is the storage container for a related set of memories. Context Packs organize memories by domain or purpose and provide efficient retrieval. See Context Packs for the detailed architecture.

​
Memory Lifecycle

Memories move through a managed lifecycle:
  1. Created, extracted from input and scored for worthiness
  2. Active, retrievable and contributing to agent context
  3. Degraded, fading through summarization tiers (full → key facts → existence marker)
  4. Archived, removed from active retrieval but preserved for audit
  5. Re-promoted, any retrieval restores a degraded memory to active state

​
Memory Types

Memories are categorized into two groups:

​
General Types

TypePurpose
factFactual information about entities, processes, or systems
experienceLearned behaviors from past interactions
observationObserved patterns or anomalies
instructionDirectives or guidelines for agent behavior
preferenceUser or agent preferences (e.g., preferred output format)
summaryCondensed summaries of conversations or data

​
Data Governance Enrichment Types

TypePurpose
glossaryBusiness glossary terms and definitions
ontologyDomain ontology relationships and classifications
textual_patternRegex or text patterns identified in data columns
kpiKey performance indicator definitions
exemplarRepresentative data examples for reference
joinTable join relationships and foreign key mappings
numeric_patternNumeric distribution patterns in data columns
policyData governance policies and rules

​
Using the Memory API

All memory operations go through the Utils service (/api/utils/). Authentication uses the same JWT tokens as all other platform APIs, plus an X-Project-ID header to scope results to the current project.

​
Add a Memory to a Context Pack

Memories are created within a named Context Pack: 
import httpx

response = httpx.post(
    f"https://api.example.com/utils/context-packs/{pack_name}/memories",
    headers={
        "Authorization": f"Bearer {token}",
        "X-Project-ID": project_id,
    },
    json={
        "name": "sql_explanation_style",
        "content": {
            "type": "text",
            "text": "The user prefers detailed SQL explanations with comments",
        },
        "memory_type": "preference",
        "source": {"type": "conversation"},
    },
)
memory = response.json()
print(memory["id"])  # UUID of the created memory

​
List Memories

# All memories in the project (across all packs)
response = httpx.get(
    "https://api.example.com/utils/memories",
    headers={"Authorization": f"Bearer {token}", "X-Project-ID": project_id},
)
all_memories = response.json()  # {"data": [...], "pagination": {...}}

# Memories within a specific Context Pack
response = httpx.get(
    f"https://api.example.com/utils/context-packs/{pack_name}/memories",
    headers={"Authorization": f"Bearer {token}", "X-Project-ID": project_id},
)
pack_memories = response.json()

​
Retrieve by ID

response = httpx.get(
    f"https://api.example.com/utils/memories/{memory_id}",
    headers={"Authorization": f"Bearer {token}", "X-Project-ID": project_id},
)
memory = response.json()

​
Retrieve by Name within a Pack

response = httpx.get(
    f"https://api.example.com/utils/context-packs/{pack_name}/memories/{memory_name}",
    headers={"Authorization": f"Bearer {token}", "X-Project-ID": project_id},
)
memory = response.json()

​
Update a Memory

response = httpx.patch(
    f"https://api.example.com/utils/memories/{memory_id}",
    headers={"Authorization": f"Bearer {token}", "X-Project-ID": project_id},
    json={
        "content": {
            "type": "text",
            "text": "The user prefers concise SQL explanations with minimal comments",
        },
    },
)

​
Delete a Memory

# Soft delete (moves to deleted state, recoverable)
response = httpx.delete(
    f"https://api.example.com/utils/memories/{memory_id}",
    headers={"Authorization": f"Bearer {token}", "X-Project-ID": project_id},
)
# Returns 200 OK with a MemoryDeleteResponse body confirming the soft-delete.

# Permanent delete (irreversible)
response = httpx.post(
    f"https://api.example.com/utils/memories/{memory_id}/permanent-delete",
    headers={"Authorization": f"Bearer {token}", "X-Project-ID": project_id},
)

​
Lifecycle Operations

# Pin a memory — keeps it in the Active tier, bypasses inactivity decay
httpx.post(
    f"https://api.example.com/utils/memories/{memory_id}/pin",
    headers={"Authorization": f"Bearer {token}", "X-Project-ID": project_id},
)

# Archive a memory — moves it to Archived state
httpx.post(
    f"https://api.example.com/utils/memories/{memory_id}/archive",
    headers={"Authorization": f"Bearer {token}", "X-Project-ID": project_id},
)

# Supersede — mark old_memory_id as superseded by new_memory_id
httpx.post(
    f"https://api.example.com/utils/memories/{old_memory_id}/supersede/{new_memory_id}",
    headers={"Authorization": f"Bearer {token}", "X-Project-ID": project_id},
)

​
Scoping

Memories are scoped per organization and project:
  • Organization: determined automatically from the JWT’s org_id claim — no separate header needed
  • Project: pass the X-Project-ID header on every request
Authorization: Bearer <jwt>
X-Project-ID: <project-uuid>

Context Packs

Deep dive into the Context Pack storage architecture.

Memory Integration Guide

How-to guide for integrating memory into your agents.

Utils API Reference

Full memory endpoint API reference.