Memory Profiles

Memory profiles let you configure how memory retrieval works on a per-agent basis. Instead of applying global settings to all agents, you can create named profiles with different tier configurations, TTLs, relevance thresholds, and context chunk limits — then assign them to specific agents.

All profile fields are actively enforced inside searchAllTiers() — the function that runs before every agent turn. Disabled tiers are skipped entirely (no Typesense or pgvector query is issued), maxContextChunks caps the total results injected across all tiers, and minRelevanceScore filters out low-signal chunks before they reach context. systemPromptSuffix is threaded through assembleContext() and appended to the agent's system prompt on every turn the profile is active.

Profile configuration

json

{
  "tiersEnabled": {
    "session":    true,   // Tier 1 — session messages
    "daily":      true,   // Tier 2 — daily notes
    "profile":    true,   // Tier 3 — user profile (always injected in full)
    "graph":      true,   // Tier 4 — knowledge graph
    "procedural": true    // Tier 5 — procedural memory
  },
  "ttlDays":           null,   // int 1–3650, null = use global TTL
  "maxContextChunks":  20,     // int 1–100
  "minRelevanceScore": 0.5,    // float 0–1
  "systemPromptSuffix": ""     // appended to the agent's system prompt
}

Field	Default	Description
`tiersEnabled`	All true	Toggle individual memory tiers on/off for retrieval. Disabling a tier reduces latency and token usage at the cost of less context.
`ttlDays`	null (global)	Memory entries written by agents using this profile expire after this many days. Overrides the workspace-level TTL.
`maxContextChunks`	20	Maximum number of memory results injected into context across all enabled tiers. Range: 1–100.
`minRelevanceScore`	0.5	Minimum RRF score for a memory result to be included. Higher values = fewer, more relevant results.
`systemPromptSuffix`	null	Appended to the agent's system prompt when this profile is active. Useful for profile-specific instructions.

API

Endpoint	Description
`POST /memory-profiles`	Create a new profile
`GET /memory-profiles`	List all profiles for the workspace
`GET /memory-profiles/:id`	Get a specific profile
`PUT /memory-profiles/:id`	Update name, description, or config
`DELETE /memory-profiles/:id`	Delete a profile (does not affect already-assigned agents)
`POST /memory-profiles/:id/assign`	Assign the profile to an agent by `agentId`

Creating a profile

bash

# Create a memory profile for a high-volume customer support agent
curl -X POST http://localhost:3000/memory-profiles \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-lean",
    "description": "Low-context profile for fast support responses",
    "config": {
      "tiersEnabled": {
        "session": true,
        "daily": true,
        "profile": true,
        "graph": false,
        "procedural": true
      },
      "maxContextChunks": 8,
      "minRelevanceScore": 0.7,
      "ttlDays": 30
    }
  }'

Assigning to an agent

bash

# Assign the profile to an agent
curl -X POST "http://localhost:3000/memory-profiles/mp_01j.../assign" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "support-agent" }'

An agent can only have one active profile at a time. Assigning a new profile replaces the previous assignment. Without an explicit profile, the agent uses the workspace-level global memory settings.

Profile patterns

Profile name	Tiers disabled	maxContextChunks	Best for
`lean`	graph	8	Fast customer support agents where latency matters
`research`	none	40	Deep research agents that need maximum context
`ephemeral`	daily, graph, procedural	5	Short-lived task agents that shouldn't accumulate memory
`private`	none, TTL 7 days	20	Agents handling sensitive data with short retention

See also: 5-Tier Memory System for how each tier works, Performance Tuning for tier trade-off guidance.