Cog – Claude Code를 위한 인지 아키텍처(마크다운 파일만 해당)

A plain-text cognitive architecture for Claude Code — simple by design, so the model can reason over its own memory with the same Unix tools (grep , find , git diff ) it already knows. Documentation | Why Text | Credits & Inspiration Cog is a set of conventions — not code — that teach Claude Code how to build and maintain its own memory. You define the rules in plain text. Claude scaffolds the structure and follows them. The filesystem is the interface. There is no server, no runtime, no application code. CLAUDE.md contains the conventions — how to tier memory, when to condense, how to route queries, when to archive. The skill files (.claude/commands/*.md ) teach Claude specific workflows: reflection, foresight, housekeeping, self-evolution. Claude reads these instructions and follows them to organize, maintain, and grow a persistent knowledge base across sessions. Everything is plain text by design. Not as a compromise — because plain text is what makes this work. Memory files are just markdown, which means Claude can grep for patterns, find what changed, wc to check file sizes, 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. Cog is a learning tool — an experiment in watching how a memory architecture evolves when given clear conventions and self-observation capabilities. You set the rules, Claude scaffolds the structure, and the pipeline skills refine the conventions over time. The model doesn't evolve — it follows whatever rules it finds. The rules are what change. Every decision is visible. Every rule is editable. Every change is in the git log. Requires Claude Code. git clone https://github.com/marciopuga/cog cd cog Open the project in Claude Code, then: /setup Cog will ask about your life and work — company, side projects, what you want to track. From that conversation, it generates everything: domain manifest, memory directories, skill files, and routing table. That's it. Start talking. Cog ships with .claude/settings.json that pre-approves 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. Say yes once and you won't be interrupted again. If you'd rather review everything manually, delete .claude/settings.json and Claude Code will prompt for each operation individually. CLAUDE.md defines the conventions below. Claude reads them at the start of every session and follows them to decide where to store facts, when to condense, how to route queries, and when to archive. The memory/ directory is the state that emerges from following these rules over time. memory/ ├── hot-memory.md ← Always loaded. ## 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 memory/personal/observations.md — raw events, append-only: - 2026-03-10 [family]: School called — Sam 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. memory/work/acme/entities.md — compact 3-line registry: ### Sarah Chen (Engineering Manager) - Direct report to VP Eng | Joined Jan 2025 | Runs platform team | Prefers async over meetings - status: active | last: 2026-03-10 Heavy entries get promoted to thread files — the entity stub just links: → [[work/acme/sarah-chen]] . Two processes: Condensation: observations → patterns → hot-memory. Each layer is smaller and more actionable than the one below. Archival: old observations → glacier. Indexed, retrievable, out of the way. Nothing is deleted — it moves to the right place. When a topic keeps coming up across observations, Cog raises it into a thread — a read-optimized synthesis file that pulls scattered fragments into a coherent narrative. Every thread has the same spine: - Current State — what's true right now (rewrite freely) - Timeline — dated entries, append-only, full detail preserved - Insights — patterns, learnings, what's different this time A thread gets raised when a topic appears in 3+ observations across 2+ weeks, or when you say "raise X" or "thread X". Threads grow long — that's the point. The texture is the value. One file forever, never condensed. Fragments (observations) never move. Threads reference them via wiki-links. See the full Thread Framework documentation for details. Every memory file has a one-line summary: . This is the first tier of a three-level retrieval protocol: - L0 — one-line summary. Decides whether to open a file at all. - L1 — secti