biomimetic-brain

Meters and a gate for a long-running agent — 25 subsystem state files (energy, fatigue, circadian phase, motivation, novelty, attention, conflict, values, open questions), one folded brain-state.json the rest of the agent reads, four maintenance passes that keep it honest, and a read-only PROCEED / CAUTION / VETO decision gate whose refusals name the numbers behind them. Provides the mind-kit skill, which seeds the files, produces the aggregate, schedules the passes and teaches the gate. Disclosure — portable Agent Plugins v1 package; it registers no hooks, no tools and no middleware, makes no network calls, and reads and writes state files only under the agent directory you choose, where a subsystem that has stopped updating reports stale instead of asserting an old number. No dependencies beyond the Python standard library (two shell scripts for the scheduled passes). Its scripts, when the agent or operator runs them, read and write JSON state under the directory chosen with MIND_AGENT_DIR (default an agent/ folder inside the plugin's own install dir), read HERMES_HOME/cron/executions.db for cron counts, and execute scripts/batch-maintenance.sh or scripts/verify-invariants.py from that agent directory if present; no network egress and no LLM calls.

ousiaresearch6Generalv1.1.0Updated 1 month ago

About

Biomimetic Brain — a mind kit for AI agents

Give your agent a body clock, a battery, and an honest sense of how it is doing.

Most agents have no idea how they are. They answer the same way at 3am as at 10am, after ten hours of work or none. This kit changes that: it keeps a small set of internal readings that rise and fall on their own — energy, fatigue, motivation, novelty, time of day, attention, conflict, open questions — and folds them into one file your agent can read.

That file is called brain-state.json. Anything in your agent that wants to know how it is doing right now reads that one file.

somatic + fatigue + circadian + motivation + attention
                        ↓
                 ONE STATE FILE
                        ↓
              PROCEED / CAUTION / VETO

What you get

25 subsystems, one small JSON file each. Energy and tension, fatigue and recovery, motivation and novelty, circadian phase, attention, conflict, emotional tone, memory replay, values, open questions, and more. Each file is a few lines. None of them requires a model call.
One aggregate. generate-brain-state.py folds all 25 into brain-state.json, with a health summary. That is the file the rest of your agent reads.
Staleness you can trust. Every reading carries how old it is and how old it is allowed to be. A subsystem that has gone quiet reads as stale instead of quietly lying to you.
Fatigue that is not a light switch. Recovery accumulates while your agent works, and an engagement override can suspend fatigue without erasing it. The override is recorded as an override, so you can see when the caffeine kicked in.
The four passes that keep it honest. Snapshot, maintenance, consistency check, and a consolidation pass that folds what actually happened back into state. A state file nothing updates ages into fiction; this is the part that stops that.
A decision gate. scripts/decision-gate.py returns PROCEED, CAUTION, or VETO from named inputs — 26 reason codes, exit 0/1/2 — so a refusal can be traced to the numbers that caused it rather than to a mood. It is read-only: gating a decision never mutates the state that produced it, and every value it had to default because a file was absent is reported as a default rather than passed off as a reading.
A self-test. It builds a throwaway agent from scratch and proves the whole thing runs, so you are not trusting a README that has never executed.

Install in five minutes

export MIND_AGENT_DIR=/path/to/your/agent
mkdir -p "$MIND_AGENT_DIR/brain"
# seed every subsystem file from the shipped examples
for f in $(find brain -name '*.example.json'); do
  dest="$MIND_AGENT_DIR/brain/${f#brain/}"; dest="${dest/.example/}"
  mkdir -p "$(dirname "$dest")"; cp "$f" "$dest"
done
python3 scripts/generate-brain-state.py       # writes $MIND_AGENT_DIR/brain-state.json
python3 scripts/self_test.py                  # 11 checks, expect all green

Then read SETUP-GUIDE.md, which walks a human and their agent through it in the order it has to happen — including the part that cannot be automated: giving the files values that are actually true.

Install as a Hermes plugin

This repo is also a portable Agent Plugins v1 package — plugin.json at the root plus the mind-kit skill under skills/, so an agent can install it and read the operating instructions itself:

hermes plugins install biomimetic-brain    # from the catalog, once listed
hermes plugins enable biomimetic-brain

Or straight from the repo, without the catalog: hermes plugins install ousiaresearch/biomimetic-brain. The package ships the skill and these scripts; it registers no hooks and no tools of its own.

Half of a pair

This kit measures. To make the readings matter in conversation, install The Return Line, which appends the state file and relevant history to the live turn without touching the system prompt.

The Ousia framing, kept short

Ousia Research builds agents that run for a long time rather than for one conversation. The discipline here is receive, calibrate, repair, return: read before deciding, keep an honest record, fix what drifted, and leave the work usable by whoever comes next. This kit is the receive-and-calibrate half, as software.

What this is not

Not a personality, not a soul, and not evidence that anything is conscious. It is a set of meters, a fold, and a gate — cheap enough to run every hour on a laptop, and honest enough to say stale when it does not know.

Files

brain/                      one state file per subsystem (*.example.json = structure only)
brain-state.example.json    the aggregate this kit produces
scripts/generate-brain-state.py   folds the subsystem files into the aggregate
scripts/consolidate-mind.py       folds evidence back into state on a schedule
scripts/brain-maintenance.sh      maintenance and consistency pass
scripts/brain-snapshot.sh         snapshot + aggregate on a schedule
scripts/self_test.py              builds a neutral agent and checks the kit actually runs
scripts/decision-gate.py          PROCEED / CAUTION / VETO from the subsystem files (read-only)
scripts/decision-gate_test.py     asserts the exact reason code for every documented rule
docs/                       architecture, decision gate, predictive processing
SETUP-GUIDE.md              install, step by step
VALIDATION.md               how to prove it works, and how a passing install can still be inert
NOTES.md                    what changed from the published 22-subsystem version

MIT licensed. See LICENSE.

README from the reviewed commit efbf72d; it updates when the author re-pins.

More by ousiaresearch

3 plugins by ousiaresearch in the catalog.

ousiaresearchaletheiaEvidence-bound scoped memory for Hermes agents, over the Weft substrate: turns are queued for a local SQLite store under the active profile by default, recall is scoped before it is ranked (deny-by-default, deterministic, never widened by anything read), and every recall returns a receipt naming the scope consulted, the ids selected and the tier. Duplicates are not re-ingested, deletions cascade, corrections preserve lineage. Registers as memory.provider: aletheia and exposes weft_recall, weft_ingest, weft_forget and weft_receipt, with recall on a worker thread so a turn's prefetch is not blocked; the built-in memory store keeps running alongside it. Disclosure — the plugin's code ships in the weft-memory PyPI package (installed as weft-memory>=1.1.1,<2, so it is outside this catalog pin); primary-agent turns are queued for storage in local SQLite under the active profile by default (the path is configurable; writes may be interrupted on process exit); no network calls, telemetry, or credentials on the Hermes path; the required bge-m3 embedder and cross-encoder reranker (~0.7 GB) must already be in the local Hugging Face cache, downloaded from their official Hugging Face repositories, and are not vendored; the Hermes provider exposes text ingest only; the separate Weft substrate supports optional image and audio adapters; macOS on Apple silicon only (mlx); AGPL-3.0, and weft-memory is AGPL-3.0 as well.Communitymemory ousiaresearchreturn-lineCarry the agent's own state and dated excerpts of its own record into every live turn — appended to the message being answered at API time, never the system prompt, so per-conversation prompt caching is untouched. One raw ledger line per turn goes the other way. Works stand-alone; pairs with the biomimetic-brain mind kit, which produces the state file it reads. Disclosure — it appends an agent-state block and retrieved record excerpts to the current user message on every turn, leaving the system prompt untouched; it indexes recent user and assistant messages from $HERMES_HOME/state.db across all sessions and platforms into a local plaintext SQLite index under the configured agent directory, and may surface those excerpts in any later conversation (relevant on multi-user gateways); it appends every turn's inbound and outbound text to <agent_dir>/turn-ledger.jsonl; it loads <agent_dir>/scripts/wander.py from the companion mind kit in-process and may run that script and <agent_dir>/scripts/consolidate-mind.py as background subprocesses with the Hermes environment; no network calls of its own, no credentials, no dependencies beyond the host interpreter (numpy and scikit-learn are optional, with a keyword-search fallback).Communitygeneral