Cog is a plain-text cognitive architecture for Claude Code created by Marcio Puga. It is a set of conventions, not code, that teaches 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.
## 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`
## 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.
## 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
## 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).