Cog-Cybernet

A file-based cognitive architecture for governing many concurrent LLM-agent projects.

Cog-Cybernet takes the components that cognitive architectures (ACT-R, SOAR, CoALA) give a single agent, a working memory, an episodic buffer, declarative long-term memory, a decision cycle, and builds them out of plain Markdown files so that they survive the agent. It adds what one agent does not need and a person running thirty projects does: a central executive over a global workspace that watches every project, a significance-weighted decay rule so memory forgets on purpose, a consolidation protocol that moves what one project learns into the store every project reads, and a session cycle that rewrites the situation model instead of appending to it. Cog for the cognitive architecture; cybernet for cybernetics, the science of steering a system from above.

It is the protocol one researcher used for six months to run about thirty projects at once (papers, grant and legal work, software, creative projects) with Claude Code as the runtime, across three machines and a few hundred sessions. Everything the agents know lives in files in each project folder. Any agent, on any machine, in any session, reads the files and continues. The agent is stateless; the files carry the state.

your-projects/
  _executive/             the central executive: protocol authority, global workspace, alert engine
  paper-alpha/            a project: its own memory files, its own sessions
  grant-beta/
  garden-gamma/

Why

Three things go wrong when one person runs many agent projects:

1. Sessions die. Context windows end, machines change, weeks pass. Whatever the agent knew is gone unless it was written down in a form the next agent can use.
2. Memory bloats. Append-only notes grow until they are read by nobody and the important line is buried under a hundred routine ones.
3. Nobody is above the projects. Each project's agent sees only its own folder. Deadlines collide, blockers go stale for a month, a finished project sits unshipped because its status file still says "in progress" and nothing reads it against a calendar.

Cog-Cybernet answers each: a per-project file protocol that survives any restart; a situation model that is rewritten every session and a working memory with class-based decay; and an Executive agent that reads every project's status fresh, runs an alert engine, and owns the rules.

The architecture

Layer	What it is	Files
Central executive	A meta-agent (the Executive) that reads every project's status blackboard fresh each session into one global-workspace view, runs the alert engine, advises on priority, onboards new projects, owns the templates and rules. It does no project work.	_executive/CLAUDE.md, .executive/status.md in every project
Per-project memory	Long-term schema; a situation model rewritten each session; an episodic buffer with five significance classes and explicit decay; a raw archive; a decision log; a transferable-knowledge outbox.	CLAUDE.md, SITUATION_MODEL.md, WORKING_MEMORY.md, sessions/, DECISIONS.md, INSIGHTS.md
Session cycle	Start: read schema, shared world model, methods index, situation model, working memory, last log, siblings; brief in three lines; gate on confirmation (wait mode) or proceed (flow mode). End: rewrite, decay, log, update the blackboard, append insights.	protocol/PROJECT_PROTOCOL.md

Memory that forgets on purpose

WORKING_MEMORY.md is an episodic buffer. Every entry carries a significance class, and the class sets how it decays at each session boundary:

Class	What it is	Decay
pin	constraints from the operator, unresolved blockers, active warnings	never; removed only when resolved
decision	choices that constrain future work	slow: full detail one session, one line for three, then background
discovery	results that change understanding	slow, as decision
failed	approaches that did not work	medium: full detail one session, one line for two, then dropped
routine	completed tasks, fixes, regenerated outputs	fast: dropped at the next session

SITUATION_MODEL.md is not appended to at all. At the end of every session the agent rewrites it from scratch, under fifty lines: where the project stands, what is next, what to remember. Contradictions get resolved, obsolete lines disappear, and the file the next agent reads first is always current. Details and the formal reading are in protocol/DECAY.md.

Four mechanisms you will not find in a memory template

1. Systems consolidation (consolidate). Projects learn things other projects need: a tool quirk, a method, a dead end, a reusable asset. Each project has an INSIGHTS.md outbox; the Executive also scans working memories and decision logs since a per-project watermark. Candidates are classified into five tiers, each with its own home (universal rule, environment fact, method, failure, asset), reviewed by the operator, then promoted and propagated. A ledger records provenance; the process is incremental and idempotent. protocol/CONSOLIDATION.md
2. Sibling clusters. Related projects stay aware of each other by pull, not push: each reads its siblings' SITUATION_MODEL.md at session start. Nothing is copied, nothing goes stale, nobody writes into another project. protocol/SIBLINGS.md
3. Project states. ACTIVE, RESTING, GATED, DORMANT, decoupled from status colour. Age only carries information for projects that are supposed to be moving. If the operator parked a project, silence is correct behaviour and nagging is a bug. protocol/EXECUTIVE.md
4. Mechanical enforcement. Rules the agent kept forgetting were moved into hooks the harness runs. The shipped example: every image is capped at 1800 px on the long edge before it enters a session, which removes a whole class of API failures in long image-heavy sessions. hooks/

Cognitive-science grounding

The design borrows deliberately from memory research; the names are not decoration.

Component	Grounding
The Executive	central executive (Baddeley, 2000) over a global workspace (Baars, 1988): one place where every project's state is visible and priorities are set
SITUATION_MODEL.md, rewritten	Baddeley's episodic buffer "manipulates and creates new representations rather than simply activating old memories"; consolidation as actively computing new summaries (Mattar and Daw, 2018)
WORKING_MEMORY.md with class-based decay	ACT-R base-level activation (Anderson et al., 2004) with the fixed decay exponent replaced by a per-class one; normatively, retain what has high expected value of being needed (Mattar and Daw, 2018)
CLAUDE.md	declarative long-term memory: stable schema, goals, rules
ECOSYSTEM.md	distributed cognition (Hutchins, 1995): the shared world model lives in the environment
files, not the agent	extended mind and the parity principle (Clark and Chalmers, 1998): the notebook is the memory
session start and end	a decision cycle with an explicit consolidation phase, in the spirit of SOAR and ACT-R

Quickstart

Requires Claude Code (or any agent runtime that reads a project instructions file; the protocol is plain Markdown). The hooks use jq and macOS sips.

git clone https://github.com/panosalef/cog-cybernet.git
cd cog-cybernet

# 1. Create a fleet root with the Executive in it
scripts/new-fleet.sh ~/projects

# 2. Onboard a project (creates the protocol files, the status blackboard, the _executive link)
scripts/onboard-project.sh ~/projects/my-paper --mode wait --type research

# 3. Optional: install the image-capping hooks into ~/.claude
scripts/install-hooks.sh

# 4. Work
cd ~/projects/my-paper && claude          # say: start session
cd ~/projects/_executive && claude        # say: start session | meta | consolidate

Each project's CLAUDE.md tells its agent what to read at start and what to rewrite at the end. The Executive's CLAUDE.md tells it how to build the global-workspace view, what to alert on, and how to onboard. The operator's own words drive the modes: wait mode agents brief and stop; flow mode agents brief and proceed.

Repository layout

README.md               this file
DESIGN.md               design rationale, grounding, lessons, open questions
protocol/               the specification
  PROJECT_PROTOCOL.md     required files, modes, session start and end, file formats
  DECAY.md                significance classes, decay rules, formal note
  EXECUTIVE.md            the central executive: global workspace, states, alert engine, onboarding
  CONSOLIDATION.md              knowledge transfer: tiers, homes, push and pull, ledger
  SIBLINGS.md             sibling clusters, pull not push
  META.md              working on the system itself
  RULES.md                universal rules and how a rule becomes a hook
templates/              copy-ready files for a project and for the Executive
hooks/                  cap_image_long_edge.sh, cap_images_at_session_start.sh, settings snippet
scripts/                new-fleet.sh, onboard-project.sh, install-hooks.sh, prep-images.sh
examples/fleet/         a fictional three-project fleet with an Executive, filled in as after a few sessions
CITATION.cff            how to cite
docs/                   the architecture figure

The example fleet

examples/fleet/ is a small fleet a few sessions in: paper-alpha (a research paper in wait mode), grant-beta (an application with a hard deadline), garden-gamma (a creative project in flow mode, currently RESTING). Open any of them in Claude Code and say "start session" to see the briefing the protocol produces; open _executive/ and say "start session" to see the global workspace and the alert engine read those three status files.

Status, scope, limitations

• Built for and tested with Claude Code on macOS; the protocol itself is runtime-agnostic Markdown.
• One operator, one fleet, six months. No controlled comparison against append-only memory; the benchmark that would provide one is described in DESIGN.md as future work.
• The public repository contains the protocol, templates, hooks, scripts and a fictional example. The author's live fleet is not included.

Citing

@software{alefantis2026cog-cybernet,
  author = {Alefantis, Panos},
  title  = {Cog-Cybernet: a file-based cognitive architecture for governing many concurrent LLM-agent projects},
  year   = {2026},
  url    = {https://github.com/panosalef/cog-cybernet}
}

Licence

MIT.