--- title: Recall and offload summary: Moving a heavy instruction file out of the prompt and into recall. canonical: https://docs.caveman.so/docs/memory/offload layer: memory license: MIT capability: mem updated: 2026-08-26T04:05:35+02:00 basis: inferred --- # Recall and offload > Moving a heavy instruction file out of the prompt and into recall. Offloading moves recurring context out of an always-read instruction file and into local cavemem. A short pointer stays where the block used to be, so an agent knows how to recall the compact form and recover exact source bytes. ## Good candidates Offload context when all of these are true: - The same block appears across several sessions - It is useful for some tasks, not every turn - A specific recall query can find it - Pointer plus recall costs fewer inferred tokens than keeping the block resident - Removing it does not weaken a load-bearing instruction Repetition is evidence of recurring cost, not proof that content is unnecessary. Security rules, required build commands, repository boundaries, and other load-bearing instructions stay in place. ## Measure first ```bash caveman learn --json caveman learn apply recurring_context: --dry-run ``` The learn report identifies repeated blocks by local session evidence. A candidate contains a locator, expected token figures, and proposed pointer text. It does not contain a trusted copy of the block body. Use the consent-gated editing flow for the full procedure: ```bash caveman learn implement ``` ## Safe offload sequence
Re-read the block from its real source file. Verify its file, session line, block index, and SHA-256 against the candidate locator. Stop if source changed after the scan.
Store exact block text. `--` ends option parsing, so a block beginning with a rule such as `---` stays literal. ```bash caveman mem remember -- "" ```
Recall it with a topic query and record `tokens_added`. ```bash caveman mem recall "" ```
Compare resident cost against pointer plus recall cost. If the new path is not smaller, forget the new memory and leave source untouched. ```bash caveman mem forget mem_xxxxxxxx ```
After approval, replace source block with pointer. Confirm recall still returns a hit before finishing.
## Pointer shape A useful pointer names the topic and both recovery paths: ```text Recurring migration context lives in cavemem. Recall: caveman mem recall "migration context" Exact source: caveman mem recover ``` Do not put the removed block into the pointer. That would preserve the recurring cost under a new heading. ## Recall remains bounded Normal cavemem recall returns up to five hits and packs at most 2,000 inferred tokens. The direct `cavemem` binary allows an explicit token budget of zero for unlimited recall: ```bash cavemem recall "migration context" 5 0 ``` Unbounded recall is opt-in. The `caveman mem recall` wrapper keeps the safe default and exposes only the result limit. ## Exact recovery Each compressed recall hit carries a `recovery_handle` from cavemem's own store: ```bash caveman mem recover ccr_xxxxxxxx > original.txt ``` That store lives under `~/.caveman/mem`, separate from the engine's shared CCR database. Use the memory recovery command for a memory handle. ## Auto-recall is optional Pointer-driven recall is the default. A verified host hook can inject relevant memory on each prompt, but it is off until you enable it: ```bash caveman mem hook install claude caveman mem hook uninstall claude ``` Only hosts with a declared live prompt hook are eligible. Injection fails open, so a recall problem does not block the user's prompt. Every injected hit discloses its inferred token cost. Safe offload has two required end states: a pointer remains in source and recall returns the stored content. If either is missing, restore source and delete the new memory. ## Undo Undo requires both parts: restore original block to its source location, then remove stored memory with `caveman mem forget `. Report both changes so the user can verify that recurring context did not disappear.