multi-layer-context-persistence

name	multi-layer-context-persistence
description	3-layer context persistence architecture — Memory (auto-inject facts), Skills (reusable workflows), Session Search (FTS5 retrieval). Load when onboarding new agents, auditing context management, or debugging "Dumb Zone" / context loss issues.
version	1.0.0
author	Aim (AI Assistant for Sutee Leelanuntagit)
license	MIT
platforms	["macos","linux"]
metadata	{"hermes":{"tags":["context-management","memory","persistence","session-continuity"],"related_skills":["session-boundary-protocol","memory-management","post-mortem"]}}

Multi-Layer Context Persistence

Overview

One-shot handoffs (handoff.md) are a start. They keep the next session from cold-starting. But they're manual, flat, and fragile — a single file you must remember to write, re-read every session, and manually keep updated.

Our approach: 3 independent persistence layers that work together continuously. The agent never loses context, never carries stale history, and learns from every interaction.

The "Dumb Zone" (150K-200K tokens of stale context) doesn't happen because active context stays at 5-15K tokens. Memory and skills are injected/loaded on demand; history is searchable but not present.

---

When to Use

• Onboarding a new AI agent — load this skill so the agent knows the persistence architecture
• Debugging context loss — "the agent forgot what we decided last session"
• Auditing context management — checking whether memory/skills/session-search are being used effectively
• Training other agents — this skill is the meta-discipline for context maintenance

Don't use for: tasks shorter than 10 tool calls (overhead > benefit), or single-session tasks.

---

Architecture

The 3 Layers

Layer	Purpose	Token Cost	Scope	Example
Memory	Durable facts auto-injected every turn	~2,800 tokens (fixed)	System-wide	"User prefers concise replies"
Skills	Reusable workflows loaded on demand	~2K-10K tokens (when loaded)	Per-domain	Camera setup, gallery deploy
Session Search	FTS5 full-text over past conversations	0 (one-time when queried)	Retroactive	"What did we decide about auth?"

Decision Tree: What Goes Where

Is it needed EVERY session?
├─ YES → Memory
│  (preferences, IDs, security rules, pointers)
└─ NO → Is it a reusable workflow with steps + pitfalls?
        ├─ YES → Skill
        │  (API integration, deployment steps, debug methods)
        └─ NO → Is it past conversation data?
                ├─ YES → Session Search only
                │  (task progress, PR numbers, temp state)
                └─ NO → Don't store it

Memory Format

# 3-field learning entry:
[context/tag] (date):
- what: <what happened>
- root cause: <why it happened>  
- correct: <exact command/action to do next time>

Rules:

• Always 3 fields. Without root cause it's noise; without correction it's passive.
• Declarative facts, not instructions. "User prefers concise" not "Always be concise".
• One topic per entry → easy to replace/remove.
• Never store: task progress, PR numbers, completed-work logs, temporary state (stale in <7 days).

Skill Format

---
name: my-skill
description: "Use when <trigger>. <one-line behavior>."
version: 1.0.0
...

## Workflow Steps
1. [Step with exact commands]
2. [Step with completion criteria]

## Common Pitfalls
- ✅ Pattern: "What to do instead of common mistake"
- ❌ Anti-pattern: "What not to do"

## Verification Checklist
- [ ] Checkable criteria, not vague aspirations

Key: Skills are loaded on demand — zero token cost when not in use. This is the difference between procedural memory (skill) and working memory.

---

Operating Protocol

At Session Start

1. Check memory — facts are already injected. Review them silently.
2. Load skill if relevant — skill_view(name='<skill-name>') to load workflows.
3. Search past sessions — if the user references prior work:

   session_search(query="<user's topic>", limit=3)
   

During Session

1. Capture new facts — when user states a preference or you discover a pattern:

   memory(action='add', target='memory', content='...')
   

2. Save reusable procedures — when you solve a non-trivial problem:

   skill_manage(action='create', name='...', content='...')
   

3. Use session search instead of asking — before asking "what did we discuss about X", search past sessions

At Session End

For multi-session tasks (tasks that clearly won't finish this session), write a handoff artifact:

## Session Complete: [Module Name]

### ✅ Done
- What was accomplished (files, commands, decisions)

### 🔄 Next Session
- First 3 commands to run
- File paths and line numbers to start at

### ⚠️ Tried & Failed
- What didn't work (saves next session from repeating)

Save to ~/.hermes/plans/YYYY-MM-DD_HHMM-handoff.md.

---

Real Example: Debugging a Deploy Failure

Without 3-layer persistence

Session 1: "The app won't deploy. Let me debug..."
  → Finds it's a CDN cache regression
  → Fixes it
  → Closes session
Session 2 (2 weeks later): Same error again
  → "Wait, didn't we fix this? What was it again?"
  → Spends 30 min re-debugging

With 3-layer persistence

Session 1: "The app won't deploy. Let me debug..."
  → Finds CDN regression
  → memory: "Decento CDN regression = downgrade CDN version. 
    git checkout reverts uncommitted changes — commit before revert."
  → skill: patches deploy workflow with pre-deploy CDN check
  → Closes session
Session 2 (2 weeks later): Same error
  → Memory auto-injects the fix
  → Session Search finds the old conversation in seconds
  → Fix applied in 2 minutes

---

Common Pitfalls

1. Storing everything in memory. Memory is only for what's needed EVERY turn. Everything else belongs in skills or session search. Memory full? Consolidate — merge related entries, remove stale ones, offload procedures to skills.

2. Writing imperative memory entries. "Always check X" reads like an instruction and can override the user's actual request. Write declarative: "Project uses X".

3. Not updating skills after failures. If a skill's instructions cause an error, patch it immediately with the new information. Stale skills are worse than no skills.

4. Letting session search replace real conversation. Don't skip reading the user's message because "session search has context from earlier." The user's current message is primary; session search is secondary context.

5. Forgetting the "Dumb Zone" prevention. Even with persistence, if you load 20 files into one session, you'll hit context limits. Use delegate_task/background tasks for data-heavy work.

---

Verification Checklist

• Memory entries are declarative facts, not imperatives
• Each memory entry is single-topic
• No stale entries (things that change weekly shouldn't be in memory)
• Skills have exact commands, not abstract advice
• Skills have a verification checklist
• Session search is used before asking "what did we discuss"
• When a skill causes an error, it's patched same-session
• Handoff artifacts are written when a task spans sessions