# Cog Memory Cog is a plain-text cognitive architecture for [[Claude Code]]. It is a set of conventions, not code, that teach Claude Code how to build and maintain its own persistent memory across sessions. The filesystem is the interface; there is no server, no runtime, no application code. Created by Marcio Puga. ## How it works `CLAUDE.md` contains the conventions: how to tier memory, when to condense, how to route queries, when to archive. Skill files (`.claude/commands/*.md`) teach Claude specific workflows like reflection, foresight, housekeeping, and self-evolution. Claude reads these instructions and follows them to organize, maintain, and grow a persistent knowledge base. Everything is [[Markdown]]. Claude can `grep` for patterns, `find` what changed, and `git diff` to see what the last pipeline run touched. The same Unix tools that make Linux powerful make Cog's memory observable and maintainable. ## Three-tier memory - **Hot**: Always loaded, under 50 lines. Current state, top priorities. Lives in `memory/hot-memory.md` - **Warm**: Domain-specific files loaded when relevant. Includes observations (append-only event log), action items, entities (people, places, things) - **Glacier**: Cold archived data with YAML frontmatter. Indexed, searched on demand via `glacier/index.md` Domains (personal, work, side projects) each get their own memory directory and slash command, configured via a conversational `/setup` flow. ## Progressive condensation Two processes maintain memory health: 1. **Condensation**: observations are promoted to patterns, which are promoted to hot-memory. Each layer is smaller and more actionable 2. **Archival**: old observations move to glacier. Indexed, retrievable, out of the way Nothing is deleted; it moves to the right place. This is conceptually similar to [[Progressive summarization]] applied to AI memory. ## Thread framework When a topic keeps coming up across observations, Cog raises it into a thread: a read-optimized synthesis file. Every thread has the same spine: Current State (rewrite freely), Timeline (dated, append-only), and Insights (patterns, learnings). A thread gets raised when a topic appears in 3+ observations across 2+ weeks. ## Tiered retrieval protocol Every memory file has a one-line summary comment (`L0`). Retrieval uses three levels: - **L0**: one-line summary, decides whether to open the file - **L1**: section header scan, identifies which part of a long file to read - **L2**: full file read, when full context is needed ## Built-in skills Cog ships with pipeline skills for memory maintenance: `/housekeeping` (archive, prune, link audit), `/reflect` (mine conversations, extract patterns), `/evolve` (audit architecture, propose rule changes), `/foresight` (cross-domain strategic nudges), `/scenario` (decision simulation), `/explainer` (writing), and `/humanizer` (remove AI patterns). ## Design influences Draws from RLM (recursive memory hierarchy), A-MEM (bi-directional back-linking), OpenViking (L0/L1/L2 tiered context loading), Zep/Graphiti (temporal validity), Mem0 (contradiction detection), the [[Zettelkasten method]] (thread framework), and single source of truth principles (canonical fact storage). Works with [[Claude Code]], Cowork (Claude Desktop's agentic mode), and any Claude-powered tool that reads `CLAUDE.md` and has file access. Can connect to external tools via [[Model Context Protocol (MCP)]]. ## References - https://lab.puga.com.br/cog/#/architecture - https://github.com/marciopuga/cog ## Related - [[Claude Code]] - [[Cognitive Architecture]] - [[Model Context Protocol (MCP)]] - [[Zettelkasten method]] - [[Progressive summarization]] - [[Markdown]]