cog CLAUDE.md

Cog — Memory System

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

Core Conventions

The full memory conventions are defined in the cog skill (.claude/commands/cog.md for Claude Code — vendored from cog-skills, which is the canonical source). The key rules are summarized below; when in doubt, the cog skill wins.

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 System

Persistent memory lives in memory/. Three tiers:

• Hot (memory/hot-memory.md — the root file only) — loaded every conversation, <50 lines, rewrite freely
• Warm (domain files, including each domain's own hot-memory.md) — loaded when the domain skill activates
• Glacier (memory/glacier/) — YAML-frontmattered archives, indexed via glacier/index.md. Read-only, except housekeeping archival.

L0 Headers

Every memory file has <!-- L0: summary (max 80 chars) --> as line 1 — including auto-generated indexes.

Memory Retrieval Protocol

When responding to any query:

1. Identify domain — match query to a domain (see memory/domains.yml)
2. L0 scan — grep -rn "<!-- L0:" memory/{domain}/ to find relevant files (memory/{domain}/INDEX.md is a precomputed table of the same headers)
3. Select by query type:
   • Tasks → action-items.md + calendar.md
   • Person → entities.md
   • Overview → hot-memory.md + action-items.md
   • Cross-reference → check link-index.md
4. L1 before L2 — for files >80 lines, scan section headers before full read
5. SSOT check on write — before writing, verify the fact doesn't already exist elsewhere