Runs and consolidation

A run is one task. While it is in progress, the agent writes entries with a stable runId. When it finishes, consolidation distills the run into long-term memory. This is the main promotion path in Agent Memory:

session entries ──► workspace facts ──► procedures
                        │
                        └──► tenant conventions (admin-approved)

Consolidating a runCopy Anchor Link

Call consolidate at the end of a task with the same runId you wrote with:

curl -s -X POST "$AGENT_MEMORY_BASE_URL/v1/memory/consolidate" \
  -H "Authorization: Bearer $AGENT_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "'"$AGENT_MEMORY_WORKSPACE_ID"'",
    "runId": "run-1",
    "goal": "Add vegetarian filtering to the menu service"
  }'
# {"status":"consolidated"}

Consolidation needs the curate capability (memory:curate). goal is optional context for the episode; extractionInstructions optionally steers fact extraction for this run. Over MCP the equivalent is the consolidate tool.

What consolidation doesCopy Anchor Link

1. Creates an episode for the run, linked to the previous episode, and records every session entry as an episode event.
2. Scores the run. Event types drive the score: a violation pulls the run toward failed, approved patterns without corrections push it toward successful. The result is an outcome (successful, failed, uncertain) and a successScore from 0 to 1.
3. Extracts facts. Entries whose type is promotable (configured by semantic categories) are broken into discrete facts. Each fact becomes a canonical workspace memory linked back to its episode, is embedded, summarized, connected to related memories, and checked for contradictions. Facts are extracted with the configured LLM, or with a rule-based extractor when no LLM is available.
4. Learns procedures. If the run scored above 0.7 and contains an approved_pattern, its event sequence becomes (or validates) a procedure.
5. Finalizes the episode with a summary and sentence-level fragments for fine-grained episode search.
6. Abstracts across episodes, generalizing repeated, high-confidence patterns into procedures.
7. Proposes tenant conventions (see below) and clears the run's session memory.

A webhook categorize event is emitted when a run is consolidated. See Webhooks.

Writing for good consolidationCopy Anchor Link

• Use one runId per task. Thousands of single-entry runs consolidate into thousands of tiny episodes.
• Pick the right type. Only promotable types become facts, and violation / approved_pattern decide how the run is scored.
• Write durable facts directly when they matter now. Appends with layer: "Workspace" (the SDK and MCP default) are searchable immediately; consolidation then adds the episode, procedures and extracted facts on top.
• Use layer: "Session" for scratch notes that should only influence the current run unless consolidation decides they are worth keeping.

Limits per runCopy Anchor Link

By default consolidation extracts facts from the first 500 session entries of a run (the rest are still recorded as episode events), keeps at most 20 facts per entry and embeds up to 200 sentence fragments per episode. These limits are workspace settings.

Review before facts go liveCopy Anchor Link

A workspace can require review of consolidated facts. With the workspace setting promotion.workspaceCandidates.enabled turned on, promoted facts are held as candidates — hidden from recall — until a tenant administrator approves them in the console.

Promotion to tenant conventionsCopy Anchor Link

Tenant conventions are knowledge that holds across an organization. They are never written directly by agents; they are promoted:

1. After consolidation, canonical decision and approved_pattern facts that were established independently in at least two different workspaces of the same tenant become tenant-level candidates. Repeats within one workspace do not count, and content that looks like a secret or personal data is never promoted.
2. A tenant administrator approves (→ active) or rejects each candidate in the console. Unreviewed candidates expire after 14 days by default.
3. Approved conventions appear in every workspace's recall under tenantEntries ("Tenant conventions").

Tenant conventions are authoritative: when a new workspace memory conflicts with an active convention, the workspace memory's confidence is lowered and the conflict is recorded — the convention is not changed. There is no promotion from tenant to platform.

Quarantined memoriesCopy Anchor Link

Appended content is screened before it is stored, looking for prompt-injection and data-exfiltration patterns such as "ignore previous instructions", spliced role markers or markdown image beacons. Flagged content is stored as quarantined: it is never recalled, merged, consolidated, promoted or shared until a reviewer with the curate capability releases or rejects it with POST /v1/memory/{id}/review.