Skip to main content

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.

​
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 endpoints are available through the Platform Utils API (/v2/api) and are backed by the em-memory-service storage engine.

​
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

​
Integration with em-runtime Utils

Memory endpoints are exposed through the em-runtime-utils service via the /v2/api prefix. Authentication uses the same JWT tokens as all other platform APIs.

​
Add a Memory to a Context Pack

Memories are created within a context pack using the pack’s ID: 
import httpx

# Add a memory to a context pack via Utils API
response = httpx.post(
    "https://api.example.com/v2/api/memories",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "content": "The user prefers detailed SQL explanations with comments",
        "memory_type": "preference",
        "name": "sql_explanation_style",
        "context_pack_id": "<pack-uuid>",
        "metadata": {"source": "conversation", "confidence": 0.9}
    }
)
memory = response.json()
print(memory["id"])  # UUID

​
List Memories

Memories support retrieval through a two-phase search API: 
# Phase 1: Discover relevant context packs
response = httpx.post(
    "https://api.example.com/v2/api/search/discover",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "query": "SQL explanation preferences",
        "limit": 5
    }
)
packs = response.json()

# Phase 2: Retrieve memories from a specific pack
response = httpx.post(
    "https://api.example.com/v2/api/search/retrieve",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "context_pack_id": "<pack-uuid>",
        "query": "SQL explanation preferences",
        "limit": 10
    }
)
memories = response.json()

​
Retrieve by ID

response = httpx.get(
    f"https://api.example.com/v2/api/memories/{memory_id}",
    headers={"Authorization": f"Bearer {token}"}
)

​
Update a Memory

response = httpx.patch(
    f"https://api.example.com/v2/api/memories/{memory_id}",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "content": "The user prefers concise SQL explanations with minimal comments",
        "metadata": {"updated_reason": "feedback from session #42"}
    }
)

​
Delete a Memory

response = httpx.delete(
    f"https://api.example.com/v2/api/memories/{memory_id}",
    headers={"Authorization": f"Bearer {token}"}
)

​
Batch Operations

# Create multiple memories at once
response = httpx.post(
    "https://api.example.com/v2/api/memories/batch",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "context_pack_id": "<pack-uuid>",
        "memories": [
            {"content": "User prefers dark mode", "memory_type": "preference"},
            {"content": "User is a senior data engineer", "memory_type": "fact"}
        ]
    }
)

​
Scoping

Memories are scoped per organization by default, matching the platform’s multi-tenancy model. The org_id is extracted from the JWT token, no separate header is needed: 
Authorization: Bearer <jwt>
The JWT’s org_id claim determines which organization’s memories are accessible.

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.