Persistent Memory (native, local-first)

Session handoffs (.agentloop/handoff.md) are short-term continuity.
.agentloop/memory/ is durable knowledge that survives new chats.

Inspired by Supermemory’s extract → store → update → retrieve loop — implemented fully offline with files + scripts/memory.sh.

Store layout

.agentloop/memory/
  index.json
  DIGEST.md
  entries/<key>.md

Init if missing: scripts/memory.sh init

Loop (do this explicitly)

1. Retrieve (session start / before plan)

scripts/memory.sh session-brief
# or
scripts/memory.sh session-brief "keyword"
scripts/memory.sh search "keyword"
scripts/memory.sh get some.key

Cite what you loaded in one short block. Honor constraint and preference entries.

2. Extract (what is worth remembering?)

Store only if it should survive a cold start:

• Architectural decision
• User preference / constraint (“never X”, “always Y”)
• Stable system map
• Lesson from a failed approach
• Durable fact about this repo

Do not store: transcripts, secrets, ephemeral debug, green-CI fantasies.

3. Store / upsert

scripts/memory.sh upsert \
  --key conductor.plan-gate \
  --kind decision \
  --title "Conductor approval gate" \
  --summary "Multi-step work requires /plan approval before Execute." \
  --tags harness,plan \
  --pointers skills/conductor-plan/SKILL.md,commands/plan.md

Kinds: decision | preference | constraint | map | lesson | fact

4. Update / supersede

When knowledge changes, do not silently edit history. Supersede:

scripts/memory.sh supersede old.key \
  --key new.key \
  --kind decision \
  --summary "New truth..." \
  --tags harness

Old entry → status: superseded + superseded_by. New entry → active + supersedes.

5. Contradictions

When two active memories conflict and both must remain visible:

scripts/memory.sh contradict a.key --with b.key --note "why they conflict"

Both become contradicted and cross-link. Resolve later by superseding one or both with a unifying decision.

6. Handoff integration

On every meaningful run end / slice boundary:

1. Refresh .agentloop/handoff.md
2. Upsert durable facts discovered this run
3. Set memory_keys: [keys...] on the handoff
4. scripts/memory.sh digest

7. Context-surgeon integration

When compacting:

• Prefer memory keys + DIGEST over chat archaeology
• Promote durable conclusions with upsert/supersede before dropping chat detail
• Never drop current failing gate logs into memory as “facts”

Cloud (future only)

Entries include cloud_sync: local_only. Do not integrate Supermemory or other cloud APIs now. A future adapter may flip pending → synced.

Agent checklist

• session-brief at cold start
• Upsert after durable decisions
• Supersede on knowledge updates
• List memory_keys on handoff
• No secrets in entries