Memory consolidation
Agents that write to memory stores for months collect clutter: the same fact saved five times in slightly different words, old facts contradicted by newer ones, notes nobody has read in a year. Clutter makes memory search less precise and costs tokens every time memories are loaded. Consolidation jobs clean a store in the background.
Strategies
| Strategy | What it does | Example |
|---|---|---|
merge_duplicates | Folds memories that say the same thing into one, keeping the clearest wording and the union of tags. | ”Prefers email” + “Customer likes to be contacted by email” become one memory. |
resolve_conflicts | When two memories contradict, keeps the newer and rewrites or expires the older. | ”Account manager is Priya” (March) vs “Account manager is Omar” (October). |
expire_stale | Sets an expiry on memories no session has read for stale_after_days. | A one-off delivery note from last year. |
Running a job
Start with a dry run and read the report:
{ "scope": "customer:*", "strategies": ["merge_duplicates", "resolve_conflicts"], "dry_run": true }When finished, report_file_id points to a JSONL file listing each proposed change with the old and new text. If it looks right, run it again without dry_run. A nightly deployment can run consolidation on a schedule.
Safety
- Every change keeps the previous text in the memory’s history for 30 days.
- Jobs never touch memories with the tag
pinned. - Only one job can run on overlapping scopes at a time.
- The judging model sees only the memories in scope, never session transcripts.
Cost
Jobs are billed as ordinary model usage on the job’s model (default Amara Quick). As a guide, examining 1,000 short memories uses roughly 150,000 input tokens; the actual figure is reported in the job’s usage.
API reference: Consolidation jobs.