How memory works

This page explains how a piece of information enters memory, how it changes, and how it comes back in the next task.

Memory is a loopCopy Anchor Link

 task start             during the task           task end                  once the outcome is known
 search_memory  ──►  add_memory (same runId) ──►  consolidate(runId)  ──►  report_outcome(runId, receiptId)
      ▲                                                                              │
      └──────────────────── the next task starts with learned context ◄──────────────┘

The MCP server passes this loop to connected agents as server instructions (instructions). If you use REST or an SDK, your application implements the loop.

1. Writing: information is stored as-isCopy Anchor Link

add_memory or POST /v1/memory/append stores the text you send as-is; no LLM extraction happens at write time. During a write:

1. Type and permission check. The type must be registered; your credential must have write permission and (if sent) permission to act on behalf of the given agent/user.

2. Content scanning. Content that looks like prompt-injection patterns is quarantined (hidden from search, awaiting review). If personal data (PII) is detected, the record gets a pii tag; it is not rejected.

3. Duplicate check (dedup). Within the same type and facet:

   • if identical content exists from the last hour, no new record is created and the existing record's counters are incremented;
   • if a record is semantically very close (embedding similarity > 0.87) or has high word overlap (≥ 0.8), the new one is merged into it.

   Records with a different visibility, owner, user, or application are never merged. The merged and contentReplaced fields in the response tell you the result.

4. Persistent write. A record in the Workspace layer is saved in the same transaction together with its history, revision, change feed entry, and intake receipt; its embedding is computed immediately and the record becomes searchable.

5. Relation extraction. Link edges to similar records (for example CONFIRMS, BUILDS_ON) are added.

The same record also lands in the run layer (Redis, 48 hours); that run's "current context" comes from there.

2. Distillation: consolidationCopy Anchor Link

consolidate(runId) turns a run into persistent knowledge:

1. Every record in the run becomes an episode event.
2. Promotable records become facts. decision, correction, violation, approved_pattern, artifact_ref, and preference are promoted as-is; raw text is split into facts (with an LLM if one is available, otherwise rule-based).
3. Each fact goes through a contradiction check: a new decision can supersede an older, very similar decision; a correction can invalidate an old decision; contradictions that cannot be resolved are left open and show up in explain_memory.
4. The run's success score is computed; approved patterns from successful runs become procedures, and things to avoid are extracted from failed runs.
5. Abstractions (generalized facts) can be produced from multiple successful episodes.
6. Decisions that recur across multiple projects become tenant-wide rule candidates (admin approval required).

If the agent forgets to call consolidate, then on installations running the maintenance service, runs idle for 30 minutes are consolidated automatically in the background (see Consolidation).

Details: Consolidation, episodes and procedures.

3. Recall: context compilationCopy Anchor Link

search_memory / POST /v1/memory/retrieve returns a compiled context, not a single list of records:

1. The query runs in parallel across several search "legs": vector similarity, full text, entity name matching, episode sentences, 2-hop expansion in the relation graph, and type-based structural search.
2. Results are combined with reciprocal-rank fusion, then scored with relevance, recency, importance, and confidence weights. Visibility, application, facet, user, and time filters are applied before ranking; superseded records are hidden by default.
3. The context compiler fits blocks, the user profile, platform/tenant rules, procedures, workspace records, similar episodes, and run context into the token budget (default 4000). What was included and what was cut appears in the compilation report in the response.
4. A receipt is written for the delivered records, and the records' usage counters are updated.

There are two recall modes:

Details: Search and context compilation.

4. Learning: outcomes and feedbackCopy Anchor Link

• report_outcome reports the real result (build, tests, deploy, error count, user rating). The episode score is updated and procedures are validated; facts from low-scoring runs are flagged for review.
• record_retrieval_feedback reports which records you actually used.
• When learning is on, the utility of the records in the receipt is updated. By default, utility affects the confidence score; it affects ranking only when "value-aware" selection is enabled.

Details: Feedback and outcomes.

5. Changing and forgettingCopy Anchor Link

• Content can be corrected in place (update_memory, with optimistic concurrency). Each correction opens a new revision.
• A record can supersede another (supersedes, supersede_memory). The old one is not deleted; it is hidden from default searches.
• Deletion blanks the record's content immediately and cleans up derived copies. If live records are derived from it, deletion is rejected until cascade is requested; the derived records are not deleted but marked "stale".

Details: Updating, superseding and deleting.

When are AI components involved?Copy Anchor Link

The service also works without an LLM and without semantic embeddings; in that case the corresponding steps fall back to rule-based paths:

The default installation keeps paid AI services turned off. To enable them, see Configuration.