> ## 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 > Multi-agent memory management for CRAFT, how agents remember and learn from interactions using Context Packs. # 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](#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](/platform/memory-context-packs) for the detailed architecture. ### Memory Lifecycle ```mermaid theme={null} %%{init: {'theme': 'base', 'themeVariables': {'lineColor': '#555555', 'fontFamily': 'sans-serif', 'edgeLabelBackground': '#ffffff'}}}%% stateDiagram-v2 [*] --> Active : extracted + worthiness score passes Active --> Summarized : inactivity decay Summarized --> KeyFacts : further decay KeyFacts --> ExistenceMarker : further decay ExistenceMarker --> Archived : maximum decay Archived --> [*] : purged after retention period Summarized --> Active : retrieved (re-promotion) KeyFacts --> Active : retrieved (re-promotion) ExistenceMarker --> Active : retrieved (re-promotion) Archived --> Active : explicitly re-promoted ``` 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 | 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: ```python theme={null} 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 ```python theme={null} # 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 ```python theme={null} 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 ```python theme={null} 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 ```python theme={null} 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 ```python theme={null} # 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 ```python theme={null} # 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 ```http theme={null} Authorization: Bearer X-Project-ID: ``` ## Related Deep dive into the Context Pack storage architecture. How-to guide for integrating memory into your agents. Full memory endpoint API reference.