Cog: a plain-text memory layer shared across AI agents

The problem Cog addresses: memory that lives inside one tool

The README states the case directly: agents have memory now, but it is siloed, and each tool remembers things its own way inside its own project. Switch tools or start a new project and you re-explain yourself. Cog's answer is a single memory folder shared by every agent you point at it. The intended user is someone running several agents (Claude Code, Codex, Cursor, Windsurf, Gemini CLI, GitHub Copilot, Opencode, Cowork) or several projects, who is tired of context being rebuilt per session. It is not aimed at a single-agent, single-project setup, where the overhead of conventions buys little. The README is explicit that you should not scaffold memory inside each project, because that fragments context. One folder, many projects.

Three primitives: L0 headers, three tiers, and one home per fact

The design rests on three ideas. First, L0 headers provide progressive context loading, so the agent scans before it reads. Second, memory is tiered: hot is always loaded, warm is loaded on demand, glacier is archived and indexed. Third, each fact lives in one place and is cross-referenced with wiki-links. The hot tier has a hard constraint in the layout: `hot-memory.md` is described as always loaded and under 50 lines. That ceiling is doing real work. It forces current state to stay short and pushes everything else down a tier. The single-source-of-truth rule is the part most likely to erode in practice, because nothing in the repository enforces it. Wiki-links and an auto-generated `link-index.md` make duplication visible, but visibility is not enforcement.

How the loading ladder actually works

The mechanism is a sequence of small reads rather than one large load. According to the README, the agent first reads `memory/hot-memory.md` (always) for current state, then `memory/domains.yml` (always) to learn which folders exist and what wakes them. When a domain matches, it reads `memory/{domain}/INDEX.md`, which carries the L0 line, file name and line count, subfolders, threads, and a glacier pointer. For files over 80 lines it runs `grep -n "^#" file` to find the section, then reads the file or one section. Large subfolders fold into a single index row plus their own `INDEX.md`, so a domain index stays one read no matter how many files accumulate. Two routing rules are stated: a query about your own life with no trigger match defaults to `personal`, and a name that no L0 mentions is found with one grep inside that domain, never across the whole tree. The claim that everything is observable is testable: `grep -rn "<!-- L0:" ~/cog/memory/` lists every summary the agent can reach.

Getting it running: clone, skills, and COG_HOME

The quick start is three commands. `git clone https://github.com/marciopuga/cog ~/cog`, then `cd ~/cog`, then `npx skills add marciopuga/cog-skills`. After that you start your agent and run `/cog` to bootstrap your domains, and the README says memory is then persistent at `~/cog/memory/`. Claude Code users skip the skills step for the bundled commands: the clone already ships them under `.claude/commands/`, vendored from cog-skills and carrying unprefixed names such as `/reflect` and `/housekeeping`. For other agents, `npx skills add` installs them through skills.sh with a `cog-` prefix, so the same skill becomes `/cog-reflect`. If you cloned somewhere other than `~/cog`, set `COG_HOME`, for example `export COG_HOME=~/projects/cog`, and add it to `~/.zshrc` or `~/.bashrc`. All agents read the same folder, `$COG_HOME/memory/`, which defaults to `~/cog/memory/`. One detail worth noting: the README says `npx skills add` auto-detects your agent, so the install path depends on that detection working for your tool.

The memory folder doubles as an Obsidian vault

The `memory/` directory is described as a valid Obsidian vault, and wiki-links in the form `[[domain/file]]` resolve natively in Obsidian's graph view. You can open `memory/` as a vault, or clone the repository into an existing vault as a subfolder. Edits made by hand in Obsidian are picked up by the agent next session. This is the clearest expression of what Cog is: the same markdown files serve as agent memory and as a human knowledge base, with no export step and no sync layer. The trade-off is that the graph view reflects link structure, not semantic structure, and any file you edit by hand is a file the agent may later rewrite during housekeeping or reflect.

Maintenance is optional, which means it is also optional to skip

The repository describes one scheduled pulse: run housekeeping then reflect in the same session, so reflect sees freshly pruned state. The cron example is `0 23 * * 0 cd "${COG_HOME:-$HOME/cog}" && claude -p "/housekeeping then /reflect"`. Housekeeping archives, prunes, rebuilds indexes, sweeps expired facts, and reports a Health table, which the README calls the system audit. Reflect consolidates observations into patterns, fixes contradictions, raises threads, and closes scenarios. Foresight, scenario, and history run only on demand. The README is honest that the pipeline is optional and that Cog works without it, but also that running it regularly keeps memory clean. Read that as the real cost of ownership: the skills define the conventions, and the conventions only hold if something runs them. There are no releases retrieved in the supplied material, so there is no version history to reason about upgrades from.

Where Cog is the wrong tool

Cog has no server, no database, and no application code. That is the pitch, and it is also the limit. Anything needing concurrent writes, transactional updates, or structured queries across memory is outside what markdown plus grep provides. The three-tier model depends on discipline: if hot memory exceeds its stated budget or facts get duplicated across domains, the loading ladder degrades and the agent reads more than it should. The single-source-of-truth rule is a convention, not a constraint, and the auto-generated `link-index.md` only reports what the files already say. The project is also tied to the skill ecosystem: `npx skills add` must detect your agent for the non-Claude Code path to work, and Claude Code users get a vendored copy of the skills rather than the canonical source, which means the two can drift. Finally, the material gives no performance numbers, no user counts, and no benchmark results, and none should be inferred from it.

Compared with memory built into each agent

The alternative most readers already have is the memory their agent ships with: Claude Code's own project memory, Cursor's rules and context files, or whatever a given tool persists between sessions. Those systems are integrated and require no setup, and they keep memory scoped to the tool and the project. Cog inverts that. State lives outside every tool in one folder, agents read it through documented conventions, and the same files open in Obsidian. The practical difference is portability against integration: a tool-native memory follows you nowhere, while a Cog folder follows you everywhere but depends on each agent's skill support to be read correctly. If you only ever use one agent on one project, the native option is simpler and Cog adds a layer you will not exercise.

Editorial conclusion

Adopt Cog if you already run more than one agent or project and are willing to keep a single ~/cog folder as the only place memory lives; the MIT licence and the absence of a server make that a low-risk experiment. Do not adopt it if you need structured queries, transactional writes, or per-tool isolation, because the state is markdown plus grep and nothing enforces consistency for you. Before committing, run `grep -rn "<!-- L0:" ~/cog/memory/` to confirm the L0 headers are actually being written, check whether your agent's skill format is among the ones `npx skills add` detects, and decide whether you will schedule the weekly `claude -p "/housekeeping then /reflect"` pulse, since without it the consolidation steps simply do not happen.

Official sources

1. Issues
2. License: MIT
3. marciopuga/cog on GitHub
4. README