Core Concepts

MemoryRelay organizes AI agent knowledge into a set of interconnected primitives. Understanding these concepts will help you design effective memory strategies for your agents.

Memories

A memory is the fundamental unit of storage. Each memory contains:

• Content -- Natural language text describing what the agent learned, observed, or decided
• Metadata -- Arbitrary JSON for structured data (source, confidence, tags, timestamps)
• Vector Embedding -- A 384-dimensional vector generated automatically from the content, used for semantic search

Memories are retrieved by meaning, not by keywords. When you search for "How does authentication work?", MemoryRelay returns memories about JWT tokens, API keys, and login flows -- even if those memories never contain the word "authentication."

from memoryrelay import MemoryCreate

memory = client.memories.create(MemoryCreate(
    agent_id="agent-123",
    content="The payment service uses Stripe webhooks for async event processing. "
            "Events are verified using the webhook signing secret before processing.",
    metadata={
        "source": "code_review",
        "file": "payment/webhooks.py",
        "confidence": 0.9
    }
))

Memory Tiers

Memories are organized into importance tiers that affect retrieval priority:

Tier	Importance	Description
Hot	>= 0.8	Critical knowledge, prioritized in search results
Warm	0.4 -- 0.8	Standard memories, the default tier
Cold	< 0.4	Low-priority memories, may be demoted during maintenance

You can promote a memory's importance explicitly:

client.memories.promote(memory.id, importance=0.9)  # promotes to hot tier

Batch Operations

Store up to 100 memories in a single request:

from memoryrelay import BatchMemoryRequest, BatchMemoryItem

response = client.memories.batch_create(BatchMemoryRequest(
    memories=[
        BatchMemoryItem(agent_id="agent-123", content="First observation..."),
        BatchMemoryItem(agent_id="agent-123", content="Second observation..."),
    ]
))

Context Building

Build a pre-formatted context window from relevant memories, useful for injecting into LLM prompts:

from memoryrelay import MemoryContextRequest

context = client.memories.context(MemoryContextRequest(
    query="What do we know about the payment system?",
    agent_id="agent-123",
    max_tokens=2000
))
print(context.context)  # formatted string ready for a prompt

Agents

An agent is the isolation boundary for memories. Each agent has its own namespace -- memories stored under one agent are invisible to others unless explicitly shared.

Use agents to separate concerns:

• One agent per AI assistant instance
• One agent per environment (development, staging, production)
• One agent per team or department

# Create separate agents for different concerns
code_agent = client.agents.create(name="code-reviewer")
ops_agent = client.agents.create(name="ops-assistant")

# Memories are isolated
client.memories.create(MemoryCreate(
    agent_id=code_agent.id,
    content="Prefer composition over inheritance in this codebase."
))
# This memory is only visible when searching with code_agent.id

info

Agents belong to a user account. Your API key determines which user's agents you can access. You cannot access agents owned by another user.

Entities

Entities are named things extracted from memories -- people, organizations, technologies, projects, and concepts. MemoryRelay identifies entities automatically and links them to the memories where they appear.

Entity Types

Type	Examples
person	Team members, stakeholders, authors
organization	Companies, teams, departments
technology	Languages, frameworks, tools, services
project	Repositories, products, initiatives
concept	Design patterns, architectural styles, methodologies

Automatic Extraction

When you store a memory, you can trigger entity extraction:

memory = client.memories.create(MemoryCreate(
    agent_id=agent.id,
    content="Sarah from the platform team recommended switching from REST to gRPC "
            "for the inter-service communication in the billing microservice."
))

# Trigger extraction
client.memories.extract_entities(memory.id)

# Extracted entities: Sarah (person), platform team (organization),
# REST (technology), gRPC (technology), billing microservice (project)

Knowledge Graph

Entities form nodes in a knowledge graph. Relationships between entities create edges:

• Sarah works_on billing microservice
• billing microservice uses gRPC
• gRPC replaced REST (in this context)

Query the graph to answer questions like "What technologies does the billing team use?" or "Who has worked on the payment system?"

# List entities for an agent
entities = client.entities.list(agent_id=agent.id)

# Link entities to memories
from memoryrelay import EntityLinkCreate
client.entities.link(EntityLinkCreate(
    memory_id=memory.id,
    entity_id=entity.id,
    relationship="mentions"
))

How Everything Connects

erDiagram
    AGENT ||--o{ MEMORY : contains
    MEMORY ||--o{ ENTITY : mentions
    ENTITY ||--o{ ENTITY : "relates to"

• Agents own memories and isolate them from other agents
• Memories reference entities and carry tiers, importance and metadata
• Entities link to each other forming a knowledge graph

For versioned, reviewable context that an agent receives exactly as published, see ICM.