| name | memory-consolidate |
| description | End-of-session or on-demand memory consolidation into agentmemory + STATE.md. Use when the session is wrapping up, context is near 80%, the user says "save state", "/state", "consolidate", "quicksave", or when loop-runtime Phase 3 fires. Routes each item to the correct memory type and enforces the user-approval gate on user-model changes. |
Memory Consolidate
Routing table (memory types from the spec)
| Item observed | Type | Destination | Gate |
|---|
| What happened (events, outcomes) | episodic | agentmemory memory_save w/ session tag | none — factual log |
| What is true (env facts, versions, paths) | semantic | memory_save, verified this session only — never from recall of recall | evidence artifact |
| How to do it (proven procedure) | procedural | skill-forge (if gate passes) else memory_lesson_save | forge gate |
| Known unknowns (what failed to resolve) | metacognitive | memory_lesson_save prefixed UNKNOWN: | none |
| Who the user is (preference/habit delta) | user model | PROPOSE first. Write only on explicit approval (hard rule 3). Log approval in ledger. | user yes |
STATE.md vs carry-packet (do not conflate)
STATE.md ($SIA_STATE_PATH) = living project state, state-architect skill, overwrite-in-place. Carry-packet ($SIA_PACKET_DIR) = one-shot session handoff via context-transference/imi-state, foreign-receive contract, consumed once. Session-end on low context → packet. Session-end normally → STATE.md. Both may fire; neither substitutes for the other.
STATE.md (read by boot.sh)
Write to the CANONICAL path $SIA_STATE_PATH (default ~/Documents/02/STATE.md), using the doctrine schema in templates/STATE.md: Goal/Constraints/Preferences/Tasks/In-progress/Blocked(+Reason)/Key Decisions(+Reason)/Next Steps(+done-condition)/Critical/Completed/Verified. Completed never implies Verified — Verified cites its artifact. One next action, not a menu. .sia/STATE.md may hold a machine-local copy; canonical wins.
Recall transparency (hard rule 4)
Whenever consolidation reads memory to dedupe or validate, list to the user: item recalled → one-line why it was relevant. Black-box recall is a defect.
Failure modes — do NOT use when
- Mid-task with no natural boundary — consolidating half-states writes fiction.
- The only content is the tick log itself — the ledger already has it; don't double-write.
- agentmemory is unreachable — write everything to
.sia/dangling.md instead and say so; never claim a memory write that didn't return an ID.
