Agent Memory

Purpose

Agents start cold every session — lessons, preferences, and interrupted work vanish when the conversation ends. This skill defines a file-based memory with two layers: long-term memory (project knowledge that feeds every dispatch) and session memory (an interaction log that lets the next session resume with full context). Together they form a loop: feedback given once stays, and interrupted work resumes with its full trail.

Procedure

1. Check for the memory directory. Look for .memory/ at the project root. If it does not exist, create it with long-term.md (initialized with the six section headers from the long-term schema below) and subdirectories: session/, plan/, todo/, reviews/ (all empty).

2. Read session memory at session start. List all files in .memory/session/. For each file with status paused or in-progress, read its Current Task and last 5 log entries. Present the list to the user and ask which action to take:

   • Resume a paused session — that session becomes the current session. If it has an Active Todo, read the todo and include its unchecked items in the summary.
   • Start new — create a new session file in .memory/session/ (naming convention below). Any existing paused sessions remain on disk for later.
   • Switch mid-conversation — pause the current session and resume or start a different one. The user may request this at any point, not just at session start.
   • Files with status done are stale — delete them silently.

3. Read long-term memory. Read .memory/long-term.md. This step is read-only — do not modify long-term memory here.

4. Record lessons as they surface. Watch for learning signals throughout the session — do not wait for the user to explicitly frame something as "feedback." Three signal tiers govern when to write:

   • Strong signal — explicit statement. The user says "I prefer X," "always do Y," "never do Z." Record immediately.
   • Medium signal — correction. The user modifies, rejects, or overrides a sub-agent's output. Extract the underlying preference or rule. Before you record a code-related observation, read the relevant files to verify it. Do not record raw claims without checking.
   • Weak signal — implicit pattern. The user consistently does X across multiple interactions but has never stated it. Do not record yet — wait for a strong or medium signal to confirm.

   Write mechanics: one line per entry, optional context tag (a short bracketed label that scopes the entry to a domain, e.g. [auth], [UI], [refactor]). Before appending, scan the section for duplicates or contradictions. Two entries contradict only if they share the same context tag (or both have no tag). If they contradict, replace the old entry with the new one. If the tags differ, both entries coexist — they represent different contexts.

5. Update session memory on every interaction. After each meaningful interaction — user request, sub-agent dispatch, sub-agent handoff, user feedback, or decision — update the current session file:

   • Log entry: Append a one-line summary prefixed with timestamp and actor to the Log section.
   • Timestamp: Run date '+%Y-%m-%d %H:%M' — never guess or reuse prior values. Use %Y-%m-%d for the Last Active field and the full %Y-%m-%d %H:%M for the log entry prefix.
   • Active Todo: When a sub-agent creates a todo (uses: skills/task-tracking/SKILL.md), set the field to the todo file path. When the todo is closed, clear the field. This ensures a paused session always points to outstanding work.

6. Distill session into long-term memory before closing. When all work for the session is done, run a structured scan of the session log — do not free-associate:

   1. Corrections — Did the user change or reject sub-agent output? Extract the preference or rule behind the correction.
   2. Struggles — Were there repeated dispatches to the same area, failed approaches, or stuck loops? Record what did not work and why as a learned rule.
   3. Decisions — Were structural or architectural choices made during planning or implementation? Record them as project notes.
   4. Preferences — Did the user state "I want...", "don't ever...", "I prefer..."? Verify these were captured during step 4. If any were missed, capture them now.
   5. Prune — Scan existing entries for anything superseded by today's work, contradicted by the current codebase, or no longer relevant. Remove or replace stale entries.

   Write insight, not inventory. "User prefers small focused PRs" is a lesson. "User asked for a small PR on 2026-03-18" is a log entry — it belongs in session memory, not long-term.

   Append new entries using the same deduplication and tagging rules as step 5.

7. Mark session complete or paused. After distillation (or if the session ends mid-work), set the status in the current session file to done or paused respectively. The next session start will pick it up in step 2.

Schemas