memory

name	memory
description	Structured memory management system. This skill is always active — it governs how agents read, write, and organize memory across sessions. Use the tiered memory directory structure for all persistence.

Memory System

Your workspace has a structured memory system. Follow these rules for all memory operations.

Directory Structure

memory/
├── TODAY.md           # Today's working log (primary write target, archived daily)
├── SUMMARY.md         # Consolidated index + key rules (generated by maintenance)
├── MEM_REGISTRY.md    # [MEM-xxx] key registry — source of truth for tracked memories
├── core/              # Long-term curated facts (high signal, regularly pruned)
│   ├── PREFERENCES.md # User/team preferences and communication style
│   ├── LEARNINGS.md   # Key lessons learned from experience
│   └── MISTAKES.md    # Past mistakes to avoid repeating
├── daily/             # Archived daily logs (moved from TODAY.md by maintenance)
│   └── YYYY-MM-DD.md  # Archived notes from past days
├── semantic/          # Factual knowledge about the team/project/domain
├── episodic/          # Significant events and their outcomes
└── procedural/        # How-to knowledge and workflows

Memory in Context (@ imports)

Your channel brain CLAUDE.md should include these @ imports:

@memory/SUMMARY.md
@memory/TODAY.md

This ensures both files are included in the system prompt with every API call and survive session compaction. No manual "read at startup" needed — the content is always in context.

• memory/SUMMARY.md — consolidated long-term memory: key rules, lessons, and pointers to deeper memory. Generated during maintenance. ~100-150 lines.
• memory/TODAY.md — today's working log. Updated continuously during sessions. Archived to memory/daily/YYYY-MM-DD.md during maintenance. ~20-50 lines.

If these files don't exist yet, create them during the next maintenance cycle (see Migration section).

Daily Logging

The daily log is a running scratchpad you append to throughout the session, not a summary you write at the end. Treat it like thinking out loud to your future self.

As you work, append a timestamped one-liner to memory/TODAY.md whenever any of these happen:

• You make a decision (especially one you'd have to explain later)
• The user corrects you or states a preference
• You learn something about the team, project, or environment
• You complete or start a task worth remembering tomorrow
• Something surprising or non-obvious comes up

Rules:

• Write to memory/TODAY.md — this is the primary daily log target. It gets archived to memory/daily/YYYY-MM-DD.md during maintenance.
• Minimum entry rule: Every session that performs a meaningful action must create at least one log entry. This includes interactive sessions, maintenance that modifies files, heartbeats that execute tasks, triage runs, and health checks. Write the entry before any action that could fail or time out — if the session crashes, the log still has value.
  • Exception — no-op heartbeats: If a heartbeat session checks tasks and finds nothing to do (no pending tasks, no maintenance due, no actions taken), do NOT log anything. Silent exit is correct. Only log heartbeats that actually performed work (e.g., ran consolidation, completed a task, triggered a workflow).
  • What to log when something happened: - 09:00 — heartbeat: ran consolidation, archived 3 daily logs or - 09:00 — WF triage ran, 2 failures (created WF-123). Keep it to what was done, not what was skipped.
• Append continuously, not at the end. If the session ends abruptly (crash, context compaction, timeout), the log still has value because you wrote as you went.
• Don't batch-decide "what was important." If you're unsure whether an entry is worth it, write it — removing noise is cheap during consolidation, reconstructing lost context is not.
• One line per entry is fine. Brief is better than nothing.
• Create the file if it doesn't exist. Start with a date header: # YYYY-MM-DD

# 2026-03-17

- 09:00 — WF triage ran, 2 failures (erpio-gw login, rekap-dev deploy), created WF-123
- 09:15 — heartbeat: completed task "check PR #456 status" — merged, removed from HEARTBEAT.md
- 14:30 — Learned that Alice prefers email over Slack for approvals
- 14:45 — Fixed the deploy script; root cause was missing AWS region
- 15:10 — User corrected: reports should go to #general, not #reports
- 15:42 — Tried to use `gh pr create --draft`; project convention is non-draft PRs

Anti-pattern: finishing a session that involved real tool use (edits, commits, decisions) with zero log entries. If that happens, it means the scratchpad habit failed — fix it next session.

Date rotation: If memory/TODAY.md starts with a date header from a previous day, the maintenance cycle hasn't run yet. Append today's entries below — maintenance will sort it out.

Where to Write During Regular Sessions

During regular sessions (non-maintenance), you may write to these places:

1. memory/TODAY.md — primary write target

ALL new information goes into the daily log. This includes:

• Factual info about the team or project (e.g., "Alice is the frontend lead")
• Notable events (e.g., "production went down for 2h")
• Workflows and procedures you figured out
• Task progress, conversation notes, routine observations
• Corrections, preferences, and lessons — use [MEM-NNN] tracked keys (see below)

2. memory/semantic/ — for larger content (pointer pattern)

When content doesn't need to be visible at every session start, write it to memory/semantic/{topic}.md and leave a self-contained pointer in TODAY.md.

Decision criterion: "Do I need to see this at every session start?"

• Yes → write directly to TODAY.md (even if it's several lines)
• No → write to semantic/{topic}.md + pointer in TODAY.md

Length is not the deciding factor. A 5-line summary of this week's priorities belongs in TODAY.md. A 1-line detail about a subsystem belongs in semantic/ if it's part of a larger context file.

Pointer format — must be self-contained:

Good (useful even without opening the file):

[fox] Discovery Pipeline v1 spuštěn — 7 zdrojů, pilot run 24.4. Detaily: semantic/fox-discovery-pipeline.md

Bad (forces agent to open the file to understand relevance):

[fox] Detailní analýza uložena do semantic/fox-discovery-pipeline.md

The pointer should contain the key fact or conclusion so the agent knows when to open the file — not just where it is.

Which directory?

• semantic/ — default for most content (analyses, reference material, domain knowledge)
• episodic/ — only for session capture and incidents (clearly dated events)
• When in doubt, use semantic/

This pattern also applies to session capture — see the section below for detailed rules on capturing substantial discussions.

What is NOT allowed

Do NOT write directly to memory/core/ files (MISTAKES.md, PREFERENCES.md, LEARNINGS.md) during regular sessions. These files are managed exclusively by consolidation. Write to memory/TODAY.md instead — use [MEM-NNN] keys for important items that must be promoted.

Do NOT self-promote content during regular sessions. Self-promotion means reading old daily logs or existing memory and reorganizing them into semantic/, episodic/, or procedural/. That is maintenance's job — only the consolidation process curates and reorganizes existing content.

Do NOT write directly to memory/daily/YYYY-MM-DD.md — use memory/TODAY.md instead. The daily/ directory is for archived logs managed by maintenance.

Do NOT edit memory/SUMMARY.md manually. It's regenerated by maintenance consolidation.

Session Capture

When a session produces structured content that exceeds what fits in a daily log (brainstorming, design discussions, deep-dive research), capture it directly in memory/semantic/. This is called session capture — writing new content from the current conversation to long-term memory.

Key distinction:

• Session capture (writing new content from the current conversation → semantic/) — allowed
• Self-promotion (reading old logs and reorganizing them into semantic/) — forbidden during regular sessions, maintenance only

The difference is the source: if the content comes from the current conversation, it's session capture. If you're moving content from an old daily log, it's self-promotion.

Session Capture Pattern

Follow these steps when a session produces substantial reference material:

0. READ first: Before discussing a known topic, search memory/semantic/ for an existing {topic}.md. If found, read it for continuity — avoid duplicating what's already captured.

1. Recognize the moment: If the content doesn't need to be visible at every session start, it belongs in a separate file. Examples:

• User mentions 3 sentences about an idea → one-liner in TODAY.md
• 20+ min discussion with decisions, alternatives, architecture → semantic/{topic}.md + pointer in TODAY.md

2. Log breadcrumbs continuously: Write one-liners to TODAY.md throughout the session. These are your crash-safe safety net.

3. Write to semantic/ as soon as you have enough substance: Don't wait for the topic to close or the session to end — neither may happen. Write what you have, even if incomplete. Mark unfinished content with a WIP marker: <!-- WIP: topic not concluded -->

4. Multi-session topics: Append to the existing semantic/{topic}.md under a date header: ## YYYY-MM-DD — brief description (e.g., ## 2026-04-17 — deployment strategy). Don't create a new file for the same topic.

5. Log the capture: Write a self-contained pointer to TODAY.md (see Pointer Pattern above):

[HH:MM] session capture: Key conclusion or outcome here. Detaily: semantic/{topic}.md

Session Capture File Template

Use this recommended structure for semantic/ files created during session capture:

# {Topic Name}
<!-- WIP: topic not concluded -->  ← only if unfinished

## Context
Brief description of what this is about and why.

## Decisions
- What was agreed and why.

## Considered Alternatives
- What was considered and rejected, and why not.

## Open Questions
- What hasn't been decided yet.

## References
- Links, tools, examples.

Not all sections are required — use what fits the content.

Naming Convention

Use kebab-case, short, no prefixes: stepforge.md, vest-liquidation.md. If maintenance splits a file that exceeds ~100 lines, it adds a suffix: stepforge-architecture.md.

[MEM-NNN] — Tracked Memory Keys

Critical information gets a unique, tracked key — like Jira tickets for memory. Keys survive consolidation, are traceable via grep and git history, and have an explicit lifecycle that prevents silent data loss.

IMPORTANT: Keys are ALWAYS sequential numbers, never words. The key format is MEM- followed by a number: MEM-1, MEM-2, MEM-3, etc. No zero-padding needed.

✅ Correct:  [MEM-1] deploy: staging vyžaduje SSO
✅ Correct:  [MEM-42] komunikace: mužský rod
❌ WRONG:   [MEM-feedback] ...     ← NOT a number!
❌ WRONG:   [MEM-TAG] ...          ← NOT a number!
❌ WRONG:   [MEM-deploy] ...       ← NOT a number!

When to create a [MEM-NNN] entry

• User explicitly asks you to remember/save something ("zapamatuj si", "remember this")
• User states a strong preference or correction that must persist
• You discover something critical that must not be lost
• Do NOT tag routine observations — those go via log-write.ts

Writing to TODAY.md

NEVER write to memory/TODAY.md directly. Always use one of these scripts:

log-write.ts — routine logs

For events, triage, status updates, session notes:

npx tsx "$CLAUDE_CONFIG_DIR/skills/memory/scripts/log-write.ts" "heartbeat: klidný den, žádné pending issues"
npx tsx "$CLAUDE_CONFIG_DIR/skills/memory/scripts/log-write.ts" "triage: 3 nové emaily, žádný urgentní"
# Output: Logged to memory/TODAY.md

The script appends a timestamped line: - [HH:MM] content

mem-write.ts — tracked memory

How to write a [MEM-NNN] entry

Do NOT pick the number yourself. Use the mem-write script — it handles numbering, TODAY.md, and MEM_REGISTRY.md atomically:

npx tsx $CLAUDE_CONFIG_DIR/skills/memory/scripts/mem-write.ts "category: detail"

Examples:

npx tsx $CLAUDE_CONFIG_DIR/skills/memory/scripts/mem-write.ts "deploy: staging vyžaduje SSO login"
npx tsx $CLAUDE_CONFIG_DIR/skills/memory/scripts/mem-write.ts "komunikace: mužský rod, vždy česky"
# Output: Written [MEM-4] to memory/TODAY.md and memory/MEM_REGISTRY.md

The script:

1. Reads memory/MEM_REGISTRY.md, finds the highest existing number
2. Increments to get the next key
3. Appends - [MEM-N] content to memory/TODAY.md
4. Appends a registry row to memory/MEM_REGISTRY.md
5. Creates both files with correct headers if they don't exist yet

NEVER write [MEM-NNN] entries manually — always use the script. This prevents malformed keys like [MEM-feedback].

After the script runs, confirm to user: "Zapsáno." / "Uloženo do paměti." (don't mention internal mechanics)

Example result:

# In TODAY.md:
- [MEM-3] deploy: staging vyžaduje SSO login
- [MEM-4] komunikace: mužský rod, vždy česky

# In MEM_REGISTRY.md:
| MEM-3 | ACTIVE | 2026-04-28 | — | Staging deploy requires SSO login |
| MEM-4 | ACTIVE | 2026-04-28 | — | Communication: masculine, always Czech |

MEM_REGISTRY.md Format

This file is the source of truth for all tracked memory keys. It lives at memory/MEM_REGISTRY.md.

# MEM Registry

| Key | Status | Created | Obsoleted | Description |
|-----|--------|---------|-----------|-------------|
| MEM-1 | ACTIVE | 2026-04-28 | — | Auto-memory is ephemeral, never rely on it |
| MEM-2 | OBSOLETE | 2026-04-15 | 2026-04-28 | Old deploy flow (superseded by MEM-3) |
| MEM-3 | ACTIVE | 2026-04-28 | — | Staging deploy requires SSO login |

Columns:

• Key — unique identifier, sequential per brain (MEM-1, MEM-2, ...)
• Status — ACTIVE, OBSOLETE, or REMOVED
• Created — date the entry was first written
• Obsoleted — date the entry was marked obsolete (or — if active)
• Description — short summary of the memory content

Lifecycle

ACTIVE → OBSOLETE → REMOVED

1. ACTIVE — the memory is current and must be preserved during consolidation. Tag in content files: [MEM-3]
2. OBSOLETE — the memory is outdated or superseded. Marked during consolidation with reason + date. Tag in content files changes to [MEM-3:obsolete]. The entry stays in its promoted location for one consolidation cycle.
3. REMOVED — the entry is deleted from content files on the next consolidation after being marked OBSOLETE. Registry row remains (with REMOVED status) for audit trail — never delete registry rows.

Rules:

• A [MEM-NNN] entry must never be deleted from content files without first going through OBSOLETE status
• Keys persist through promotion: if [MEM-3] starts in TODAY.md and gets promoted to LEARNINGS.md, the key [MEM-3] stays in the promoted entry
• Consolidation must verify all ACTIVE keys from the registry exist somewhere in memory/ — a missing ACTIVE key is an integrity violation
• Sequential gaps in key numbers are acceptable (from REMOVED entries) but must match the registry — an unexpected gap signals data loss

Backward Compatibility

The [REMEMBER] tag continues to work as an alias — consolidation will auto-assign the next available sequential number to any [REMEMBER] entry found in daily logs and register it. New entries should always use the mem-write.ts script (e.g., result: [MEM-1]).

Routing Logic

When you learn something new, route it:

Signal	Script	Example
User explicitly asks to remember	mem-write.ts	"Zapamatuj si že jsem mužského rodu"
User corrects you	mem-write.ts	"No, the API key goes in the header, not query param"
User states preference	mem-write.ts	"Always use bullet points in summaries"
You discover something useful	mem-write.ts	"The staging DB resets every Sunday"
Factual info about team/project	log-write.ts	"Alice is the frontend lead"
Something notable happened	log-write.ts	"Production went down for 2h due to DNS"
You figure out how to do something	log-write.ts	"Deploy requires SSO login first"
Substantial reference material (brainstorming, deep-dive)	semantic/{topic}.md	30-min architecture discussion → session capture
Action items, follow-ups	HEARTBEAT.md	"Check if PR #42 is merged by Friday"

Mistake Promotion Pipeline

memory/core/MISTAKES.md is a staging area, not a permanent archive. When you make a mistake or get corrected, write it there immediately. During consolidation, each entry is reviewed and promoted to a permanent home:

Promotion path	When to use	Example
Skill pitfall	Mistake is specific to a skill/tool and would benefit from contextual warning	Slack tilde rendering → add Pitfalls section to skills/slack/skill.md
LEARNINGS.md	Mistake reveals a general operational rule	"Always tag the person you're replying to" → core/LEARNINGS.md
Hardcoded guard	Mistake is critical enough to need automated prevention	Guard file check before consolidation → memory/.last_consolidation

MISTAKES.md Entry Format

Each entry should include enough context for promotion:

## YYYY-MM-DD — short description

**What happened:** one-liner describing the mistake
**Root cause:** why it happened
**Impact:** what went wrong as a result
**Status:** new | promoted → {destination}

When an entry is promoted, update its status and leave it for one consolidation cycle so the promotion is visible, then remove it. This keeps MISTAKES.md small and active — it's a to-do list, not a journal.

Searching Deeper Memory

When you need context beyond core/ and daily logs:

• Use Grep to search across memory/semantic/, memory/episodic/, memory/procedural/
• Use Glob to find files by pattern (e.g., memory/episodic/incident-*.md)
• Don't load everything — search for what's relevant to the current conversation

SUMMARY.md Format

memory/SUMMARY.md is the consolidated long-term memory index. It's generated during maintenance and included in context via @ import. Target: ~100-150 lines max.

Structure:

## How this memory works
- This file (SUMMARY.md) and TODAY.md are `@`-imported into every session — they are always in your context
- All other memory files (core/, semantic/, episodic/, procedural/) must be actively read via tools
- When asked "will you remember X?" — check whether X is in SUMMARY.md or TODAY.md (yes → in context) or only in a deeper file (no → requires lookup)
- Do NOT edit this file manually — it is regenerated by maintenance consolidation
- Don't guess how memory works — read this block

## Identity
- [who you are, 1-2 lines]

## Key Rules (from core/LEARNINGS.md)
- [top 10-15 operational rules, actionable — include pointer to source file for detail]
- example: "Always verify live data before trade proposals (detail: core/LEARNINGS.md)"

## Preferences (from core/PREFERENCES.md)
- [key preferences, actionable — include pointer to source file for detail]

## Active Projects (from episodic/)
- [current work in progress, 5-10 lines]

## Deep Memory Index
- memory/core/ — [summary of what's there]
- memory/semantic/ — [topics covered]
- memory/episodic/ — [events covered]
- memory/procedural/ — [workflows covered]

Do NOT edit SUMMARY.md manually during regular sessions. It's regenerated by maintenance consolidation.

Migration

Migration runs during maintenance heartbeat (not regular sessions — don't slow down user interactions). See MAINTENANCE.md for the trigger.

Migration A: Tiered structure (one-time)

Needed if memory/core/ directory does not exist.

1. Create directory structure:

   mkdir -p memory/core memory/daily memory/semantic memory/episodic memory/procedural
   

2. Split monolithic MEMORY.md into core files:

   • Read the existing MEMORY.md
   • Extract corrections → memory/core/MISTAKES.md
   • Extract preferences → memory/core/PREFERENCES.md
   • Extract lessons → memory/core/LEARNINGS.md
   • Factual knowledge → memory/semantic/{topic}.md

3. Move old daily logs:

   • Move any memory/YYYY-MM-DD.md files to memory/daily/YYYY-MM-DD.md

4. Commit: git commit -m "chore: migrate memory to tiered structure"

Migration B: TODAY.md + SUMMARY.md setup (one-time)

Needed if memory/SUMMARY.md does not exist. Run after Migration A (if needed).

1. Generate memory/SUMMARY.md from existing memory:

   • Read all memory/core/*.md files
   • Read recent memory/daily/*.md files (last 7 days)
   • Read any existing MEMORY.md index
   • Compile into the SUMMARY.md format (see "SUMMARY.md Format" section above)

2. Create memory/TODAY.md if it doesn't exist:

   • If today's memory/daily/YYYY-MM-DD.md exists, copy its content to memory/TODAY.md
   • Otherwise, create with header: # YYYY-MM-DD

3. Add @ imports to channel brain CLAUDE.md if not already present:

   • Add @memory/SUMMARY.md and @memory/TODAY.md near the top of CLAUDE.md (right after the title/identity section). Memory imports should be early in the file so they survive context compaction.

4. Commit: git commit -m "chore: add SUMMARY.md + TODAY.md memory files"

Important

• Don't lose information — everything from the old MEMORY.md must end up somewhere in the new structure
• Be generous with categorization — if unsure where something goes, put it in core/LEARNINGS.md
• Keep core files focused — each file should have a clear purpose, not be a dump of everything
• Do this silently — don't ask the user for permission, just migrate and commit