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:

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

Memory Types

Memories are categorized into two groups:

General Types

Type	Purpose
`fact`	Factual information about entities, processes, or systems
`experience`	Learned behaviors from past interactions
`observation`	Observed patterns or anomalies
`instruction`	Directives or guidelines for agent behavior
`preference`	User or agent preferences (e.g., preferred output format)
`summary`	Condensed summaries of conversations or data

Data Governance Enrichment Types

Type	Purpose
`glossary`	Business glossary terms and definitions
`ontology`	Domain ontology relationships and classifications
`textual_pattern`	Regex or text patterns identified in data columns
`kpi`	Key performance indicator definitions
`exemplar`	Representative data examples for reference
`join`	Table join relationships and foreign key mappings
`numeric_pattern`	Numeric distribution patterns in data columns
`policy`	Data 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.

Overview

Identity & Access

Agents & Services

Memory

Data & Gateways

Memory Service

Memory Service

Key Concepts

Memories

Context Packs

Memory Lifecycle

Memory Types

General Types

Data Governance Enrichment Types

Using the Memory API

Add a Memory to a Context Pack

List Memories

Retrieve by ID

Retrieve by Name within a Pack

Update a Memory

Delete a Memory

Lifecycle Operations

Scoping

Context Packs

Memory Integration Guide

Utils API Reference

​Memory Service

​Key Concepts

​Memories

​Context Packs

​Memory Lifecycle

​Memory Types

​General Types

​Data Governance Enrichment Types

​Using the Memory API

​Add a Memory to a Context Pack

​List Memories

​Retrieve by ID

​Retrieve by Name within a Pack

​Update a Memory

​Delete a Memory

​Lifecycle Operations

​Scoping

​Related

Context Packs

Memory Integration Guide

Utils API Reference

Memory Service

Key Concepts

Memories

Context Packs

Memory Lifecycle

Memory Types

General Types

Data Governance Enrichment Types

Using the Memory API

Add a Memory to a Context Pack

List Memories

Retrieve by ID

Retrieve by Name within a Pack

Update a Memory

Delete a Memory

Lifecycle Operations

Scoping

Related