Cog

One memory, not one per tool. A centralised, plain-text memory layer shared across all your AI agents and projects.

Documentation | Skills | Why Text

What is Cog?

AI agents have memory now — but it's siloed. Each tool remembers things its own way, locked inside its own project. Switch tools or start a new project, and you're re-explaining yourself. Cog gives you one shared memory — structured plain-text files that any agent can read, search, and maintain.

Three primitives:

• L0 headers — progressive context loading (scan before you read)
• Three tiers — hot (always loaded), warm (on demand), glacier (archived)
• Single source of truth — each fact in one place, cross-referenced via wiki-links

No server, no database, no application code. Just markdown files with conventions.

Quick Start

git clone https://github.com/marciopuga/cog ~/cog
cd ~/cog
npx skills add marciopuga/cog-skills

Start your agent and run /cog to bootstrap your domains. Your agent now has persistent memory at ~/cog/memory/.

Claude Code users: the clone already ships the skills at .claude/commands/ (vendored from cog-skills, the canonical source, under their unprefixed names — /reflect, /housekeeping, ...). The npx skills add step is what installs them for other agents, where they carry a cog- prefix (/cog-reflect, ...).

One folder, many projects. ~/cog is your agent's single brain — it works across every project and session. Don't scaffold memory inside each project. That fragments your context. One place where everything connects.

Custom install location

If you cloned somewhere other than ~/cog, set the COG_HOME env var:

export COG_HOME=~/projects/cog  # add to ~/.zshrc or ~/.bashrc

Supported Agents

npx skills add auto-detects your agent and installs skills into its native format via skills.sh:

• Claude Code
• Codex (OpenAI)
• Cursor
• Windsurf
• Gemini CLI
• GitHub Copilot
• Opencode
• Cowork (Claude Desktop)

All agents read the same memory folder ($COG_HOME/memory/, defaults to ~/cog/memory/).

Use with Obsidian

The memory/ folder is a valid Obsidian vault. Wiki-links ([[domain/file]]) work natively in Obsidian's graph view and link resolution.

You can:

• Clone ~/cog and open memory/ as a vault in Obsidian
• Or clone directly into an existing vault as a subfolder
• Edit files manually in Obsidian — your agent picks up changes next session
• Use Obsidian's graph view to visualize connections between memory files

The folder works as both an AI memory system and a human knowledge base. No conflict — they're the same markdown files.

Memory Structure

~/cog/memory/
├── hot-memory.md           ← Always loaded. <50 lines. Current state.
├── domains.yml             ← Domain manifest (SSOT)
├── link-index.md           ← Backlink index (auto-generated)
├── personal/               ← Warm. Loaded when relevant.
│   ├── hot-memory.md
│   ├── observations.md     ← Append-only event log
│   ├── action-items.md     ← Tasks
│   ├── entities.md         ← People, places, things
│   ├── threads/            ← Synthesis files for recurring topics
│   ├── INDEX.md            ← Domain L0 index: file, line count, summary; subfolders inline or folded (auto-generated)
│   └── ...
├── work/                   ← Your work domains (created by /cog)
├── cog-meta/               ← System self-knowledge
│   ├── patterns.md         ← Distilled rules
│   ├── self-observations.md
│   ├── action-items.md     ← System tasks (over-cap metrics, ideas)
│   ├── run-log.md          ← Pipeline run log
│   ├── foresight-nudge.md  ← Latest on-demand nudge
│   ├── scenarios/          ← Active decision simulations
│   └── INDEX.md
└── glacier/                ← Cold archive. Indexed.
    └── index.md

Skills

Installed via npx skills add marciopuga/cog-skills (names carry a cog- prefix) or bundled with this repo for Claude Code (unprefixed):

The Claude Code bundle also includes writing extras (/explainer, /humanizer) and a /commit utility.

Optional: Automated Maintenance

One scheduled pulse. Run housekeeping → reflect in the same session so reflect sees freshly-pruned state:

# Weekly maintenance pulse
0 23 * * 0  cd "${COG_HOME:-$HOME/cog}" && claude -p "/housekeeping then /reflect"

Foresight, scenario, and history run when you ask for them. Housekeeping's Health table is the system audit.

(Skill names carry a cog- prefix when installed via skills.sh: /cog-housekeeping then /cog-reflect.)

The pipeline is optional. Cog works without it — but running it regularly keeps memory clean and surfaces insights you'd miss.

How It Works

npx skills add installs SKILL.md files that teach your agent the conventions: how to tier memory, when to consolidate, how to route queries, where to write facts. The memory/ directory is the state that emerges from following these rules over time.

Everything is observable. The agent never loads the whole tree — it climbs a ladder of small reads, each one saying what to open next:

memory/hot-memory.md          always          → what's going on
memory/domains.yml            always          → which folders exist, what wakes them
memory/{domain}/INDEX.md      domain matched  → which file (L0 + line count, subfolders, threads, glacier pointer)
grep -n "^#" file             files >80 lines → which section
the file, or one section      L2              → the content

Large subfolders fold into one index row of file names plus their own INDEX.md, so a domain index stays one read however many files it grows. A query about your own life with no trigger match defaults to personal; a name no L0 mentions is found with one grep inside that domain, never across the tree.

Run grep -rn "<!-- L0:" ~/cog/memory/ yourself to see every summary the agent can reach. No black box.

Credits

Built on research: RLM (recursive memory) | A-MEM (back-linking) | OpenViking (L0 tiered loading) | Zettelkasten (threads) | SSOT (canonical facts)

Citation

Cog: Plain-Text Memory System for AI Agents
https://github.com/marciopuga/cog
Marcio Puga, 2026

License

MIT