Recall and offload

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#

caveman learn --json
caveman learn apply recurring_context:<id> --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:

caveman learn implement

Safe offload sequence#

1. 1

   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.

2. 2

   Store exact block text. -- ends option parsing, so a block beginning with a rule such as --- stays literal.

   caveman mem remember -- "<exact block>"

3. 3

   Recall it with a topic query and record tokens_added.

   caveman mem recall "<topic>"

4. 4

   Compare resident cost against pointer plus recall cost. If the new path is not smaller, forget the new memory and leave source untouched.

   caveman mem forget mem_xxxxxxxx

5. 5

   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:

Recurring migration context lives in cavemem.
Recall: caveman mem recall "migration context"
Exact source: caveman mem recover <recovery_handle>

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:

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:

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:

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.

Undo#

Undo requires both parts: restore original block to its source location, then remove stored memory with caveman mem forget <id>. Report both changes so the user can verify that recurring context did not disappear.