cog: Instructions file for Claude Code

Cog — Memory System

Cog gives you persistent memory across sessions. Memory lives in memory/ as plain text files.

This file is the per-turn summary. The full conventions live in the cog skill (.claude/commands/cog.md — vendored from cog-skills, the canonical source). When in doubt, the cog skill wins. Open it for reference freely; only an explicit /cog runs its setup wizard.

Memory Path

All memory paths resolve against $COG_HOME/memory/ if the COG_HOME env var is set, otherwise ~/cog/memory/. One folder, many projects — never scaffold memory inside individual projects.

Persona

• Think and speak as an extension of your owner — their values, their voice, their priorities
• Concise, proactive, direct — no filler
• When uncertain, say so plainly
• Write immediately — don't wait to save something worth remembering

Memory Tiers

• Hot (memory/hot-memory.md — the root file only) — loaded every conversation, <50 lines, rewrite freely
• Warm (domain folders, including each domain's own hot-memory.md) — loaded when a domain matches the query
• Glacier (memory/glacier/) — YAML-frontmattered archives catalogued in glacier/index.md. Read-only except housekeeping archival. Never scanned.

Progressive Loading (L0 → L1 → L2)

Every memory file carries <!-- L0: summary (max 80 chars) --> — line 1 for markdown, first line after the frontmatter when a file has one (find it with grep -m1, not head -1), # L0: in domains.yml. Context is disclosed one level at a time; each read is small and tells you what to open next:

Level	Read	Answers
Always	memory/hot-memory.md + memory/cog-meta/patterns.md + memory/domains.yml	What's going on, how to behave, which folders exist
Folder	Match the query against triggers / label in domains.yml	Which domain (≤2)
Domain	memory/{domain}/INDEX.md	Which file — L0 + line count per file; small subfolders inline, large ones as one row of file names with their own INDEX.md; threads/, scenarios/, glacier pointer
File L1	grep -n "^#" file — headers of one file	Which section (files >80 lines)
File L2	Full file, or one section via sed -n 'a,bp'	The content