oh-my-pi/docs/tools/retain.md

retain

Queue durable facts for asynchronous write into the active Hindsight bank.

Source

• Entry: packages/coding-agent/src/tools/hindsight-retain.ts
• Model-facing prompt: packages/coding-agent/src/prompts/tools/retain.md
• Key collaborators:
  • packages/coding-agent/src/hindsight/state.ts — per-session queue, flush, auto-retain.
  • packages/coding-agent/src/hindsight/backend.ts — session bootstrap, prompt injection, subagent aliasing.
  • packages/coding-agent/src/hindsight/bank.ts — bank id derivation, tag scoping, mission setup.
  • packages/coding-agent/src/hindsight/client.ts — HTTP retain / retainBatch calls.
  • packages/coding-agent/src/hindsight/content.ts — retention transcript shaping, memory-tag stripping.
  • packages/coding-agent/src/hindsight/mental-models.ts — bank-scoped mental-model seeding and cache rendering.
  • packages/coding-agent/src/hindsight/seeds.json — built-in mental-model seed definitions.
  • packages/coding-agent/src/hindsight/transcript.ts — extracts user/assistant turns for auto-retain.

Inputs

Field	Type	Required	Description
items	Array<{ content: string; context?: string }>	Yes	One or more memories to queue. minItems: 1. Each item must be self-contained; context is optional per-item provenance.

Outputs

Returns a single-shot tool result:

• content[0].type = "text"
• content[0].text = "<count> memory queued." or "<count> memories queued."
• details = { count: number }

The write is not confirmed before the tool returns. The queue flushes later; flush failures emit a session warning notice and are not returned to the model.

Flow

1. HindsightRetainTool.createIf(...) only exposes the tool when memory.backend == "hindsight" in packages/coding-agent/src/tools/hindsight-retain.ts.
2. execute(...) fetches session.getHindsightSessionState() and throws if the Hindsight backend was not started.
3. Each input item is handed to HindsightSessionState.enqueueRetain(...) in packages/coding-agent/src/hindsight/state.ts.
4. HindsightRetainQueue.enqueue(...) appends the item and either:
   • flushes immediately when the queue reaches RETAIN_FLUSH_BATCH_SIZE, or
   • starts a debounce timer for RETAIN_FLUSH_INTERVAL_MS.
5. On flush, HindsightRetainQueue.#doFlush(...):
   • verifies the session still owns this state,
   • calls ensureBankMission(...) once per bank/process before writing,
   • maps queued items to MemoryItemInput with context ?? config.retainContext, metadata.session_id, and bank-scope tags,
   • sends one async retainBatch(...) request.
6. The tool returns immediately after enqueueing; it does not await the HTTP write.

Modes / Variants

• Tool path: queued batch write only.
• Bank scoping comes from computeBankScope(...) in packages/coding-agent/src/hindsight/bank.ts:
  • global — one shared bank, no project tags.
  • per-project — bank id gets -<cwd basename> appended.
  • per-project-tagged — shared bank plus project:<cwd basename> tags on retained memories.
• Session scope:
  • tool-called retains are per-session queued work in HindsightSessionState,
  • persisted memories are cross-session server-side bank data,
  • subagents alias the parent HindsightSessionState, so their retain calls write into the same bank and queue.

Side Effects

• Filesystem
  • None for retained memories. No local memory file is written.
• Network
  • POST /v1/default/banks/{bank_id}/memories via retainBatch(...) in packages/coding-agent/src/hindsight/client.ts.
  • Optional PUT /v1/default/banks/{bank_id} via ensureBankMission(...) before first write per bank/process.
• Session state (transcript, memory, jobs, checkpoints, registries)
  • Appends to the in-memory HindsightRetainQueue on the active HindsightSessionState.
  • Includes metadata.session_id on each retained item.
  • Shares parent state for subagents (aliasOf path in packages/coding-agent/src/hindsight/backend.ts).
• User-visible prompts / interactive UI
  • On async flush failure, emits session.emitNotice("warning", ...); the model is not told.
• Background work / cancellation
  • Flush runs later on timer, queue-size threshold, agent_end, backend enqueue(...), or backend clear(...).

Limits & Caps

• Input schema requires items.length >= 1 in packages/coding-agent/src/tools/hindsight-retain.ts.
• Queue flush threshold: RETAIN_FLUSH_BATCH_SIZE = 16 in packages/coding-agent/src/hindsight/state.ts.
• Queue debounce: RETAIN_FLUSH_INTERVAL_MS = 5_000 in packages/coding-agent/src/hindsight/state.ts.
• Queue writes use retainBatch(..., { async: true }); the client does not wait for server-side consolidation.
• Shared auto-retain settings on the same backend:
  • hindsight.retainEveryNTurns default 3
  • hindsight.retainOverlapTurns default 2
  • hindsight.retainContext default "omp"
  • hindsight.retainMode default "full-session" from packages/coding-agent/src/config/settings-schema.ts.

Errors

• Throws Hindsight backend is not initialised for this session. when no state exists.
• Queue enqueue on disposed state throws Hindsight retain queue is closed.
• Flush-time API failures are caught in HindsightRetainQueue.#doFlush(...), logged, and converted into a warning notice instead of a tool error.
• Mission creation failures are swallowed in ensureBankMission(...); writes continue.

Notes

• Storage is server-side. hindsightBackend.clear(...) only clears local cache/state and warns that upstream deletion must happen in Hindsight UI or deleteBank; see packages/coding-agent/src/hindsight/backend.ts.
• Auto-retain uses the same bank but a different path than this tool: retainSession(...) extracts plain user/assistant transcript from packages/coding-agent/src/hindsight/transcript.ts, strips <memories> / <mental_models> blocks via stripMemoryTags(...), and calls single-item retain(...).
• retain itself does not seed or read mental models. Mental-model bootstrap lives in the shared backend: HindsightSessionState.runMentalModelLoad(...) optionally resolves seeds from packages/coding-agent/src/hindsight/seeds.json, creates missing models with ensureMentalModels(...), then caches a rendered <mental_models> block for prompt injection.
• Built-in seeds are user-preferences, project-conventions, and project-decisions. projectTagged: true seeds inherit the active scope's retain tags; untagged seeds read the whole bank.
• Mental-model defaults from packages/coding-agent/src/config/settings-schema.ts: hindsight.mentalModelsEnabled = true, hindsight.mentalModelAutoSeed = true, hindsight.mentalModelRefreshIntervalMs = 5 * 60 * 1000, hindsight.mentalModelMaxRenderChars = 16_000. First-turn loading waits up to MENTAL_MODEL_FIRST_TURN_DEADLINE_MS = 1500 in packages/coding-agent/src/hindsight/mental-models.ts.
• Seed lifecycle is create-only. Changing packages/coding-agent/src/hindsight/seeds.json does not mutate existing server-side models.
• recall.md and reflect.md rely on the same bank, scoping, and mental-model bootstrap; refer back here for the shared backend behavior.