One memory, not one per tool. A centralised, plain-text memory layer shared across all your AI agents and projects.
Documentation | Skills | Why Text
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.
git clone https://github.com/marciopuga/cog ~/cog
cd ~/cog
npx skills add marciopuga/cog-skillsStart 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.
If you cloned somewhere other than ~/cog, set the COG_HOME env var:
export COG_HOME=~/projects/cog # add to ~/.zshrc or ~/.bashrcnpx 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/).
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
~/cogand openmemory/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.
~/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
Installed via npx skills add marciopuga/cog-skills (names carry a cog- prefix) or bundled with this repo for Claude Code (unprefixed):
| Skill | Purpose |
|---|---|
/cog |
Memory conventions + setup — bootstraps domains, folders, and their indexes (no per-domain skills; routing is domains.yml → INDEX.md) |
/housekeeping |
Weekly, automated — archive, prune, rebuild indexes, sweep expired facts, report a Health table |
/reflect |
Weekly, automated (same session) — consolidate observations into patterns, fix contradictions, raise threads, close scenarios |
/foresight |
On demand — one cross-domain strategic nudge, flags decisions worth simulating |
/scenario |
On demand — branch a decision into 2-3 modeled paths |
/history |
On demand — deep memory search, piece together a narrative across files |
The Claude Code bundle also includes writing extras (/explainer, /humanizer) and a /commit utility.
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.
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.
Built on research: RLM (recursive memory) | A-MEM (back-linking) | OpenViking (L0 tiered loading) | Zettelkasten (threads) | SSOT (canonical facts)
Cog: Plain-Text Memory System for AI Agents
https://github.com/marciopuga/cog
Marcio Puga, 2026
MIT