A plain-text cognitive architecture for OpenCode — simple by design, so the model can reason over its own memory with the same Unix tools (grep, find, git diff) it already knows.
OpenCog is a set of conventions — not code — that teach OpenCode how to build and maintain its own memory. You define the rules in plain text. OpenCode scaffolds the structure and follows them. The filesystem is the interface.
There is no server, no runtime, no application code. OPENCODE.md contains the conventions — how to tier memory, when to condense, how to route queries, when to archive. The command files (.opencode/command/*.md) teach OpenCode specific workflows: reflection, foresight, housekeeping, self-evolution. OpenCode 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 OpenCode 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 OpenCog's memory observable and maintainable.
OpenCog 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, OpenCode 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.
Note
OpenCog is heavily inspired by Marcio Puga's cog — a similar memory architecture designed for Claude (Claude Code). OpenCog adapts these concepts for OpenCode while extending them with additional conventions for tiers, condensation, and self-evolution.
Requires OpenCode.
git clone https://github.com/anomalyco/opencode
cd opencodeOpen the project in OpenCode, then:
/setup
OpenCog 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, command files, and routing table.
That's it. Start talking.
OPENCODE.md defines the conventions below. OpenCode 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. <50 lines. What matters right now.
├── personal/ ← Warm. Loaded when relevant.
│ ├── hot-memory.md
│ ├── observations.md ← Append-only event log
│ ├── action-items.md ← Tasks with due dates
│ ├── entities.md ← People, places, things
│ └── ...
├── work/acme/ ← Your work domain (created by /setup)
│ └── ...
└── glacier/ ← Cold. Archived, indexed, retrieved on demand.
└── index.md
- Hot: Loaded every conversation. Current state, top priorities.
- Warm: Domain-specific files loaded when a skill activates.
- Glacier: YAML-frontmattered archives. Searched via
glacier/index.md.
Here's what builds up over time. None of this is pre-filled — it emerges from your conversations.
memory/hot-memory.md — the 30,000-foot view:
# 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 patternsmemory/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-10Heavy 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, OpenCog 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.
Every memory file has a one-line summary: <!-- L0: what's in this file -->. This is the first tier of a three-level retrieval protocol:
- L0 — one-line summary. Decides whether to open a file at all.
- L1 — section header scan. Identifies which part of a long file to read.
- L2 — full file read. Used when the full context is needed.
Scan L0s first, confirm relevance, use L1 for long files, read only what's needed.
Each fact lives in one canonical file. entities.md owns people. action-items.md owns tasks. hot-memory.md holds pointers — not the authoritative version of any fact. Other files reference with [[wiki-links]] instead of copying.
Files cross-reference each other with [[domain/filename]] links. A link index is auto-generated by /housekeeping so you can discover what connects to what.
Domains are areas of your life — personal, work, side projects. Each domain gets its own memory directory and slash command.
/setup → conversational → domains.yml → directories + commands + routing
| Type | Purpose | Examples |
|---|---|---|
personal |
Personal life | Always created |
work |
Day job | /acme, /google |
side-project |
Ventures, hobbies | /myapp, /substack |
system |
OpenCog internals | Auto-created (cog-meta) |
Built-in commands in .opencode/command/:
| Command | What it does |
|---|---|
/setup |
Conversational domain setup |
/personal |
Family, health, calendar, day-to-day |
/reflect |
Mine conversations, extract patterns, condense |
/evolve |
Audit memory architecture, propose rule changes |
/foresight |
Cross-domain strategic nudge |
/scenario |
Decision simulation with timeline overlay |
/housekeeping |
Archive, prune, link audit, glacier index |
/history |
Deep search across memory files |
/explainer |
Writing and explanation (Atkins + Montaigne method) |
/humanizer |
Remove AI patterns from text |
/commit |
Git commit and push |
/ai-deps |
AI dependency management |
/rmslop |
Remove slop from generated code |
/spellcheck |
Spell checking |
/learn |
Learn from interactions |
Domain commands (/work, /sideproject, etc.) are auto-generated by /setup.
OpenCog includes pipeline commands that maintain memory health over time. Run them manually:
/housekeeping # Archive stale data, prune hot-memory, rebuild indexes
/reflect # Mine recent work, condense patterns, detect threads
/evolve # Audit architecture, check rule effectiveness
/foresight # Cross-domain scan, surface one strategic nudge
The pipeline is optional. OpenCog works without it — but running it regularly keeps memory clean and surfaces insights you'd miss.
OpenCog's architecture lives entirely in instructions — OPENCODE.md for conventions and .opencode/command/*.md for workflows. There is no application code. The instructions define how memory is structured, how queries are routed, and how the system maintains itself. OpenCode reads these files and acts on them. The memory/ directory is just the state that accumulates.
This makes OpenCog interface-agnostic. It works with any AI assistant that reads OPENCODE.md and has file access.
MIT
@software{clavijo2026cog,
author = {Clavijo, Dario},
title = {OpenCog: Cognitive Architecture for OpenCode},
year = {2026},
url = {https://github.com/daedalus/opencog},
note = {Persistent memory, self-reflection, and foresight for AI agents}
}