Layered Memory Fabric

Clawdie’s memory model is a Layered Memory Fabric: reviewed skills, learned memory, agent identity, and operational state live in one PostgreSQL-backed data plane with separate lifecycle boundaries.

This replaces the older promotional phrase “split brain”. Split brain is a distributed-systems failure mode; Clawdie’s design goal is the opposite: one source of truth with clear ownership. The model is broader than “manuals included”: it is how a multi-agent system carries skills, memories, identities, and runtime state across hosts and harnesses.

Three planes

Plane	Shared database	What belongs there	Source of truth
Skills	`system_skills`	Reviewed skills, install docs, operator workflows, harness notes	committed artifacts + PostgreSQL import
Brain	`system_brain`	User/agent memory, preferences, compaction summaries	PostgreSQL rows + optional vector embeddings
Ops	`system_ops`	Messages, tasks, sessions, routing, runtime health	PostgreSQL rows and runtime control-plane state

Embeddings and full-text indexes improve recall, but they are not the authority. The authoritative record is PostgreSQL plus the committed skill artifacts that seeded it.

Agent souls and portable identity

Each agent can have its own portable identity bundle — its “soul” — without tying that identity to one runtime harness. Today Clawdie already reads root identity files such as SOUL.md, USER.md, and IDENTITY.md, plus per-group AGENTS.md files. The Layered Memory Fabric treats those as agent context, not as infrastructure names.

A layered soul bundle should be multi-agent agnostic. See Layered Soul for the compatibility contract. Minimal shape:

layered-soul-repo/
├── SOUL.md        # durable agent identity, values, voice, operating style
├── USER.md        # operator/user context shared with this agent when allowed
├── IDENTITY.md    # short runtime identity and boundaries
├── AGENTS.md      # harness-facing rules, if the harness supports it
├── skills/        # optional reviewed skill snippets or links
└── manifest.json  # schema version, intended agents, provenance, sharing rules

Pi, Hermes, Codex, Claude Code, or a future Colibri worker should be able to pull the same dedicated soul repo and adapt it into that harness’s native prompt/config format. A Pi lane might materialize it as AGENTS.md plus an appended system prompt; Hermes might hydrate its own operator notes; a Colibri worker might index selected files into system_brain or attach them to a task context. The source identity stays portable.

Sharing is explicit:

one agent can keep a private soul repo;
multiple hosts can clone the same soul repo for continuity;
selected USER.md or memory summaries can be shared across agents;
secrets and volatile runtime state stay out of the soul repo and belong in Ops or the platform secret store.

FreeBSD-first implementation

The FreeBSD path remains the reference implementation:

ZFS datasets protect persistent platform state.
FreeBSD jails isolate workers and optional services.
PostgreSQL runs on the host by default (DB_RUNTIME=host) or in the optional Data Service jail (DB_RUNTIME=jail).
system_skills, system_brain, and system_ops keep the same names regardless of assistant name or tenant label.

Linux-compatible contract

Linux should implement the same contracts instead of inventing a second product model:

PostgreSQL remains the database substrate.
OpenZFS is preferred when available; a plain filesystem fallback can exist for development or small installs.
Linux-native worker isolation should satisfy the same worker contract that FreeBSD jails satisfy.
The installer should select platform adapters, not rename the data model.

Installer unification target

The future install path should emit a common manifest shape on both platforms:

{
  "platform": "freebsd",
  "storage": "zfs",
  "database_runtime": "postgres-host",
  "isolation_runtime": "freebsd-jail",
  "databases": ["system_skills", "system_brain", "system_ops"]
}

Linux can use the same shape with Linux-native adapter values such as linux-service, linux-container, or filesystem where appropriate.

Naming rules

Use Layered Memory Fabric in public/promo copy.
Use skills / brain / ops planes in technical docs.
Keep system_brain as the database name; that name is intentional.
Avoid “split brain” except when referring to legacy filenames or historical changelog entries.