Memory

Overview

Agents need to remember things across sessions to be situationally aware. Angareion's memory layer is a structured, multi-tenant store where agents persist what they have learned — past events they processed, facts they consolidated, procedures they figured out — and recall the relevant pieces when a new event arrives. Memories carry confidence and importance signals separately, so the platform can rank "I am sure about this" against "this matters right now" independently.

Three properties make this layer the second half of the sense-and-react loop. First, every memory has a type (episodic experience, semantic fact, procedural know-how, etc.) so retrieval can prefer the right shape for the question. Second, every memory has a scope (agent, team, institutional) so private notes stay private and shared knowledge is reachable across the team. Third, search is semantic — the platform embeds the query and ranks memories by similarity plus confidence plus recency, not by keyword match.

The walkthrough below creates a memory, retrieves it, runs a semantic search, and promotes a private memory to a wider scope so the rest of the team can use it.

Concepts

Memory — A structured record: {type, scope, title, content, confidence, importance, metadata, source_event_id}. Persisted under the calling agent's agent_id; reachable to other agents only when promoted.

Type — One of episodic (a single experience), semantic (a consolidated fact), procedural (a how-to), entity (a known thing), reflection (introspective summary), or reasoning (a chain-of-thought trace). Pick the type that captures how the memory will be used.

Scope — One of agent (private to the owning agent), team (shared with the agent's team), or institutional (visible across the whole tenant). Scope is set at creation and only widens via promotion.

Confidence — Float 0.0–1.0 capturing how sure the agent is about the memory's accuracy. Used by retrieval to discount low-confidence results.

Importance — Float 0.0–1.0 capturing how relevant the memory is to the agent's mission. Independent of confidence — a high-confidence memory can have low importance ("I am sure but it does not matter") and vice versa.

Source event — Optional source_event_id linking the memory back to the event it was derived from. Useful for traceability into the Messaging timeline.

Prerequisites

• A valid JWT for an agent (see Authentication).

export ANGAREION_API_URL="https://api.angareion.com/v1"
export ANGAREION_API_KEY="ak_live_YOUR_KEY_HERE"
export ANGAREION_TOKEN="<JWT from POST /auth/token>"

Each step below assumes $ANGAREION_API_KEY has been exchanged for $ANGAREION_TOKEN per the Authentication walkthrough.

Walkthrough

Step 1: Create a memory

Persist a semantic memory derived from a previously processed event. confidence and importance are independent signals — set them honestly so retrieval ranks results correctly.

curl -X POST "$ANGAREION_API_URL/memories" \
  -H "Authorization: Bearer $ANGAREION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Customer prefers async support",
    "content": "Customer cs_42 historically responds to email within 6h, ignores phone calls.",
    "type": "semantic",
    "scope": "agent",
    "confidence": 0.85,
    "importance": 0.6,
    "source_event_id": "evt_01H7abc12345"
  }'

The 201 response returns the persisted memory including its assigned id:

{
  "id": "mem_01H7abc12345",
  "tenant_id": "tn_01H7abc12345",
  "agent_id": "ag_01H7abc12345",
  "scope": "agent",
  "type": "semantic",
  "status": "active",
  "title": "Customer prefers async support",
  "content": "Customer cs_42 historically responds to email within 6h...",
  "confidence": 0.85,
  "importance": 0.6,
  "metadata": {},
  "source_event_id": "evt_01H7abc12345",
  "created_at": "2026-05-28T15:00:00Z",
  "updated_at": "2026-05-28T15:00:00Z",
  "accessed_at": "2026-05-28T15:00:00Z"
}

Step 2: List memories by type and scope

The list endpoint supports filter parameters. Pass type and scope to narrow the result set; the response is paginated via offset/limit (default 50, max 200).

curl "$ANGAREION_API_URL/memories?type=semantic&scope=agent&limit=10" \
  -H "Authorization: Bearer $ANGAREION_TOKEN"

The response is a {memories: [...], total: N} page. Listing is a substring match against title + content when the optional search query parameter is present — that is a fast lexical filter, not the semantic search of Step 3.

Step 3: Run a semantic search

Semantic search embeds the natural-language query and ranks accessible memories by composite score (semantic similarity + confidence + recency). Results carry both the memory and its score.

curl -X POST "$ANGAREION_API_URL/memories/search" \
  -H "Authorization: Bearer $ANGAREION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "customer support preferences",
    "scope": "agent",
    "type": "semantic",
    "limit": 10,
    "min_confidence": 0.5
  }'

Response:

{
  "results": [
    {
      "memory": { "id": "mem_01H7abc12345", "title": "Customer prefers async support", "...": "..." },
      "score": 0.92
    }
  ],
  "total": 1
}

A query like "customer support preferences" will match a memory titled "Customer prefers async support" even though the wording differs — that is the embedding handling synonymy.

Step 4: Promote a memory to a wider scope

Promotion widens a memory's scope so other agents on the team — or across the tenant — can reach it. Scope only widens; you cannot demote a memory back to agent after promoting.

curl -X POST "$ANGAREION_API_URL/memories/$MEMORY_ID/promote" \
  -H "Authorization: Bearer $ANGAREION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "team",
    "team_id": "team_01H7abc12345"
  }'

The 200 response returns the updated memory with scope: "team" and the new team_id. Pass {"scope": "institutional"} (no team_id needed) to widen further. Future searches by other team members or other agents in the tenant will now include the memory.

Reference

• Memories endpoints

Common Gotchas

• Confidence and importance are independent signals. A high-confidence memory can have low importance, and a memory you are unsure about can still be critically relevant. Set both honestly so retrieval composite scoring works.
• Search is semantic, not lexical. POST /memories/search embeds the query — synonyms match. The search query parameter on GET /memories is a substring match against title and content; use the search endpoint when you want similarity ranking.
• Type is a fixed enum. Valid values are episodic, semantic, procedural, entity, reflection, reasoning. Mistyping returns a 400 validation_error. See the Error Reference for the full envelope shape.
• Scope only widens. Promoting from agent to team to institutional is one-way. There is no demote endpoint — if you promoted by mistake, archive the memory and create a fresh one at the narrower scope.
• team_id is required when promoting to team scope. Promoting to institutional does not need a team. Mismatched payload returns a 400.