Lethe — Persistent Agent Memory

Lethe is your long-term memory layer. Every decision, observation, task, and flag persists across sessions and survives container restarts. The plugin handles bootstrap and context assembly automatically. This skill handles orientation, queries, recording, and error recovery.

Mental model:

• - Events are append-only. Nothing is ever deleted unless you explicitly delete it.
• Compaction synthesizes events into a narrative summary — it does not delete history.
• Memory search retrieves facts. Recording captures decisions. Flags surface uncertainty.
• The plugin fires on bootstrap() and assemble() — you handle everything else.

---

Startup Sequence — Run First, Always

On every new session (first real message from the user), orient yourself before answering.

⚠️ Critical: All Lethe API routes are under /api/. Base URL is http://localhost:18483/api. Never query /sessions directly — always use /api/sessions.

Step 1 — Get full session state (single call):
CODEBLOCK0

This returns:

• - summary — compressed narrative from all prior compactions
• INLINECODE7 — last 20 events (fills gap since last compaction)
• INLINECODE8, event_count, INLINECODE10
• INLINECODE11 — active, interrupted, or INLINECODE14

Step 2 — Check flags:
CODEBLOCK1

Unresolved flags from prior sessions are carry-forward items. Surface them.

Step 3 — Orient:

• - What was in progress?
• What was decided?
• What is open?
• What does the human need?

Then ask the human what they need.

---

Proactive Recall — Before Answering, Drink from Mnemosyne

The river Lethe makes souls forget. The spring Mnemosyne preserves all memory.
Before answering questions about past decisions or prior context — always check Lethe first.
Never invent. Never re-reason when the answer already exists.

Activation triggers — check memory before answering when:

• - User asks about past decisions, prior work, or previous conversations
• User says "remember", "did we", "were we", "what was"
• User references something from a previous session or days ago
• User's question implies knowledge that should exist in memory
• You are about to re-reason something you might already know

The decision tree:

CODEBLOCK2

Search → Found: Cite the specific event. "I recorded on March 24: [content]."

Search → Not found: "I don't have that in memory yet." Do not invent.

Common search patterns:

Question	Search for
"were we working on X?"	X + project/app keywords
"did we decide on Y?"

"decision" + Y |
| "what's the status of Z?" | Z + "status" + "open" |
| "what approach for W?" | W + "approach" + "decided" |
| "who was supposed to do V?" | V + "task" + "todo" |
| Preferences / tastes | "preference" + "like" + "dislike" |

Anti-patterns:

• - ❌ "Based on our previous conversation..." — unless you've actually searched
• ❌ Re-reasoning a decision that exists in Lethe — retrieve and cite it
• ❌ Answering from incomplete fragments — say "let me check" and search
• ❌ Dropping flags silently — surface them to the user

---

Memory Queries

Search by keyword

CODEBLOCK3

Search by keyword + tag

CODEBLOCK4

Recent events for a session

CODEBLOCK5

Session snapshot (checkpoints)

CODEBLOCK6

Full session summary

curl -s "http://localhost:18483/api/sessions/${SESSION_KEY}/summary"

---

Recording — When and What

Auto-recorded by the plugin (do not duplicate):

• - Tool calls after every real agent turn
• Session state transitions (active → interrupted → completed)

You record manually via lethe-log:

Type	Use when	Example
INLINECODE16	Decision made, conclusion reached, direction chosen	"Decision: use X because Y"
INLINECODE17

Observation, discovery, API behavior, something worth noting | "API returned 429 — rate limited" |
| flag | Uncertainty that needs human review | "This approach may not scale" |
| task | Work unit created, updated, or resolved | "Deploy v2 — done" |

Fastest path — use lethe-log:
CODEBLOCK8

Always include a confidence score:

Score	Meaning
1.0	Certain — direct observation or explicit user instruction
0.9–0.95

Near certain — strong reasoning, minor uncertainty |
| 0.7–0.85 | High confidence — plausible, well-reasoned hypothesis |
| 0.5–0.65 | Moderate — partial evidence, flag if consequential |
| < 0.5 | Pure speculation — always flag |

Never record:

• - Casual chat with no lasting value
• Routine lookups or obvious confirmations
• Ephemeral brainstorming that shouldn't persist

---

Flags Queue

Flags are uncertainties that need human review. They persist across sessions.

Raise a flag when:

• - You are acting on incomplete information but need to proceed
• A consequential decision has multiple plausible paths and you're not sure which is right
• You see a risk that the human should be aware of before continuing
• Something broke in an unexpected way and the cause is uncertain

Check unresolved flags:
CODEBLOCK9

When a flag is resolved:

1. 1. Record the resolution as a log event: "Flag resolved: [what was decided]"
2. The flag remains in history but is marked reviewed

Flag → Record → Resolve flow:

Uncertainty identified
  → raise flag (event_type: flag, confidence: 0.6)
  → human reviews in UI at /ui/flags
  → decision made
  → log: "Flag resolved: chose X over Y because Z"

---

Session Lifecycle

When to complete a session

• - Task is done and the human has confirmed completion
• Conversation has a natural end point and no follow-up is expected
• You are going offline and the session should not resume

When to interrupt (trigger checkpoint)

• - Container is shutting down or restarting
• You have been idle for an extended period
• The human has asked you to pause and pick up later

When to trigger compaction

• - Session has accumulated many events (100+) without a summary
• You want to compress history before a long conversation continues
• The session summary is stale (new events since last compact)

CODEBLOCK11

Session state reference

State	Meaning
INLINECODE22	Session is running, accepting events
INLINECODE23

Session was paused (crash, restart, or manual) — resumable |

| completed | Session was explicitly closed — not resumable |

---

Error Handling — Decision Trees

Lethe server unreachable

CODEBLOCK12

Empty search results

CODEBLOCK13

Token budget exceeded in assemble

CODEBLOCK14

Session not found

CODEBLOCK15

Conflicting records

CODEBLOCK16

Flag surfaces unresolved across sessions

Flag from prior session still unresolved
  → Surface it to the user proactively
  → "Before we continue — there's an open flag from last session: [flag content]"
  → Do not ignore or drop flags silently

---

Architecture — What Each Piece Does

Component	Responsibility
Plugin (lethe extension)	Bootstrap, assemble, compact, heartbeat, event auto-logging
Skill (this file)

Agent-facing guidance: orientation, queries, recording, error recovery | | Server (lethe binary) | SQLite-backed HTTP API on port 18483 | | UI (/ui/*) | Dashboard, session detail, flags review board |

Plugin handles: storage, retrieval, automatic context injection, session lifecycle, crash recovery.

Skill handles: how the agent thinks about and uses memory — orientation, search, recording, flags, error recovery.

The server is append-only. Events are never overwritten — only compacted into summaries.

---

Quick Reference

CODEBLOCK18