Cog: Add Persistent Memory and Self-Reflection to Claude Code with Just Markdown
What It Does — A Text-Based Cognitive Architecture
Cog is an open-source framework that transforms Claude Code from a session-based assistant into a continuously aware agent with memory, self-reflection, and foresight. Unlike complex agent frameworks requiring servers or runtimes, Cog implements everything through plain Markdown files in your project's .claude/ directory.
The system organizes knowledge into three memory tiers:
- Hot Memory (
memory/hot-memory.md): Always loaded (under 50 lines). Contains current priorities, active situations, and system notes. - Warm Memory (
memory/personal/,memory/work/): Domain-specific files loaded when relevant skills activate. - Glacier Memory (
memory/glacier/): Archived, indexed content retrieved on demand via YAML frontmatter.
Setup — One Command to Get Started
Getting Cog running takes less than a minute:
git clone https://github.com/marciopuga/cog
cd cog
Open the project in Claude Code, then type:
/setup
Cog will initiate a conversation about your life and work—company, side projects, what you want to track. From that conversation, it generates:
- Domain manifests
- Memory directory structure
- Skill files
- Routing tables
Cog ships with .claude/settings.json pre-configured to approve the tools it needs (file reads, writes, edits, search, and git operations). When you first open the project, Claude Code will ask you to accept these project-level permissions. Accept once and you won't be interrupted again.
How It Works in Practice — Memory That Builds Over Time
Here's what emerges from your conversations with Claude Code after installing Cog:
Hot Memory Example (memory/hot-memory.md):
# Hot Memory
<!-- L0: Current priorities, active situations, system notes -->
## Identity
- Software engineer at Acme Corp, 2 kids, based in Melbourne
- Side project: open-source CLI tools
## Watch
- Performance review cycle opens next week — prep doc started [[work/acme/action-items]]
- Kid's speech therapy showing progress — 3 new words this month [[personal/health]]
## System
- /reflect found 3 observation clusters ready to promote to patterns
Observations Log (memory/personal/observations.md):
- 2026-03-10 [family]: School called — Gabe had a great day, shared toys unprompted for the first time
- 2026-03-11 [health]: Ran 5k in 28min. Knee felt fine. Third run this week without pain.
- 2026-03-12 [insight]: Realized I've been avoiding the budget conversation. Not about money — about control
Action Items (memory/personal/action-items.md):
- [ ] Review Q3 OKRs with team — due 2026-03-15
- [ ] Call dentist for cleaning appointment — due 2026-03-20
- [x] Submit conference talk proposal — completed 2026-03-08
Why Text-Only Architecture Matters
Cog's plain-text design has several advantages for Claude Code users:
- Full Observability: You can see exactly how Claude organizes knowledge and where self-improvement succeeds or fails.
- Zero Lock-in: Your memories remain accessible even if you stop using Cog.
- Git-Compatible: All changes are tracked through your existing version control workflow.
- No Performance Overhead: Unlike vector databases or external services, text files add minimal latency.
When To Use It — Specific Workflows That Benefit
Cog shines in these Claude Code scenarios:
- Long-running projects: Maintain context across weeks or months of development
- Personal knowledge management: Track insights, decisions, and progress alongside code
- Team onboarding: Share domain knowledge and project history with new team members
- Reflective development: Analyze patterns in your coding habits and decision-making
The Self-Improvement Experiment
Beyond memory, Cog attempts something more ambitious: giving Claude the ability to self-evolve. The system includes mechanisms for:
- Reflecting on its own behavior
- Auditing its own rules
- Improving how it operates over time
This happens through periodic /reflect commands that analyze observation clusters and promote them to patterns, creating a feedback loop where Claude Code gets better at helping you.
Getting Started Today
If you use Claude Code daily and want continuity between sessions, Cog provides the simplest possible implementation. The entire system lives in your project directory, works with your existing workflow, and gives you complete transparency into how Claude remembers and reasons about your work.
Clone the repository, run /setup, and start building a memory system that grows with your projects.
