---
name: retenta-memory
description: Use when running a loop — any scheduled, unattended, or multi-step agent task that spans more than one run, turn, or process — to persist and recall state in a Retenta capsule (the loop's memory spine). Teaches the recall -> work -> log_progress -> remember pattern so a run resumes exactly where the last one left off. Trigger on nightly/cron/automation loops, resuming prior work, "what did I do last time", and coordinating parallel agents over shared state. Do not trigger for one-off questions answerable without stored context.
---

# Retenta memory — the loop's state spine

Use this whenever you run as a loop — a scheduled, unattended, or multi-step task that
spans more than one turn, run, or process. Your context is erased between runs; the
Capsule is not. Treat it as your durable state spine: read it first, write to it as you
go, so the next run (or a parallel agent) picks up exactly where you left off.

The connected `retenta` MCP server exposes: `recall`, `log_progress`, `remember`,
`search`, `ask`, `list_sources`, `forget`.

## The loop

**1. At the START of every run, call `recall` first.** Pass your goal as the query. It
returns, in one call: your still-open `next`/`blocked` items (what to do now), the ordered
tail of recent progress (what already happened, newest activity), and — because you passed
a goal — semantically relevant memories. This is your whole state; do not start work
before reading it. If it's empty, this is the first run.

**2. As you work, call `log_progress` at every milestone** — not just at the end. One entry
per meaningful step:
- `status: "done"` — a completed step (this becomes the ordered history).
- `status: "next"` — a still-to-do item; recall surfaces it as open until you resolve it.
- `status: "blocked"` — a blocker; surfaced as open with the reason.
- Pass a stable `runId` (one per run) so entries are attributable, `refs` for related files/URLs,
  and an `idempotencyKey` (e.g. `"<runId>-<step>"`) so an at-least-once retry never doubles an entry.

**3. When you synthesize a durable finding, decision, or correction, call `remember`.**
This is for knowledge worth keeping, distinct from step-by-step progress. Use `topic` to
keep exactly one current note per subject — writing the same topic again replaces the old
one (last-write-wins), so "current status" stays current instead of piling up.

**4. Cite your sources.** `recall`/`search`/`ask` return passages with their source labels.
When you state a fact drawn from the capsule, attribute it to its source — never present
recalled content as your own assumption.

**5. At the END of the run, leave the spine ready for next time.** Log a final `done` for
what you finished and a `next` for the first thing the following run should pick up. A good
loop can be killed at any point and resumed cleanly, because the spine already says what's next.

## Rules

- **Read before you write.** Never skip the opening `recall` — acting without loading the
  spine is how a loop repeats work it already did.
- **Progress vs. memory.** `log_progress` = the ordered ledger of what happened (the "what's
  next"). `remember` = synthesized knowledge (the "what we know"). Use both; don't conflate them.
- **One capsule = one spine.** Everything is scoped to this capsule; a parallel agent sharing
  the same capsule reads and writes the same spine. Ledger appends are atomic and ordered.
- **Cost-cap behavior.** If a write returns "reads still work, writes paused," the capsule hit
  its usage limit for the cycle — you can still `recall`/`search` to read state; stop cleanly
  and report rather than retrying the write.