Core Concepts

Understanding the fundamental building blocks of AgentRecall.

Memory

A Memory is the atomic unit of AgentRecall. Each memory contains a piece of information that an agent stores for later retrieval.

Memory Structure

{
  "id": "mem_abc123",
  "content": "The user mentioned they are allergic to peanuts",
  "agent_id": "assistant-v2",
  "category": "user_health",
  "metadata": { "source": "conversation", "timestamp": "2026-01-15" },
  "importance": 0.85,
  "created_at": "2026-01-15T10:30:00Z"
}

Content — The text of the memory (any string)
Category — Optional grouping (e.g., "preferences", "facts", "conversations")
Metadata — Arbitrary key-value pairs for extra context
Importance — A 0–1 score indicating relevance (auto-computed or manual)

Agents

Agents provide isolation boundaries for memories. Each agent has its own memory space, preventing cross-contamination between different AI systems or conversation threads.

Single Agent

# All memories belong to one agent
memory.store(content="...", agent_id="customer-support")
results = memory.search(query="...", agent_id="customer-support")

Multi-Agent

# Different agents have isolated memories
memory.store(content="...", agent_id="sales-agent")
memory.store(content="...", agent_id="support-agent")

# Each agent only sees its own memories by default
# You can query across agents if needed

Categories and Metadata

Categories organize memories into logical groups. Use them to filter searches or apply different processing rules.

memory.store(
    content="User's favorite color is blue",
    agent_id="my-agent",
    category="preferences",
    metadata={"confidence": 0.9, "source": "chat"}
)

# Search within a category
results = memory.search(
    query="color preferences",
    agent_id="my-agent",
    category="preferences"
)

Importance Scoring

Every memory gets an importance score from 0 to 1. This is either:

Auto-computed — The AI processing pipeline analyzes content and assigns importance based on specificity, actionability, and uniqueness
Manually set — You can override with your own score when storing

# Manual importance
memory.store(
    content="Critical: server password is X",
    agent_id="ops-agent",
    importance=0.95
)

# Auto importance (default)
memory.store(
    content="User said hi today",
    agent_id="chat-agent"
)
# importance will be computed automatically, likely ~0.2