Layered Soul

Layered Soul

A layered soul is a small git repository that carries durable agent identity and approved context across hosts and harnesses. It is part of the Layered Memory Fabric, but it is not a database dump and not a runtime backup.

The goal is simple: Hermes, Pi, Codex, Claude Code, Zot, and Colibri workers should be able to start from the same durable identity without each harness inventing a private memory format.

What we learned from hermes-soul

The current Hermes backup repository is useful because it proves the pattern works: skills, memories, sessions, scripts, cron jobs, and sanitized config can be captured in git and restored onto another machine.

It also shows what should be separated before this becomes a multi-agent contract:

Current area	Portable?	Notes
memories/USER.md and memories/MEMORY.md	partly	Good source for user/agent context, but should be curated before feeding another harness.
skills/	yes, with filtering	Reviewed SKILL.md files can seed system_skills or harness-native skill directories.
config.yaml	Hermes-specific	Useful as an adapter input; should not become the shared schema.
sessions/	archive only	Large and private. Import summaries into system_brain; do not blindly replay raw chat logs.
cron/	harness-specific	Can inform Ops tasks, but should be converted into a platform task manifest.
scripts	mixed	Portable helper scripts are useful; harness glue should be tagged by platform.
lock files / pycache	no	Runtime artifacts should not be part of the layered soul contract.

Minimal repo shape

layered-soul/
├── manifest.json
├── SOUL.md
├── USER.md
├── IDENTITY.md
├── AGENTS.md
├── skills/
├── memories/
│   └── curated/*.md
└── adapters/
    ├── pi.md
    ├── hermes.md
    ├── codex.md
    ├── claude-code.md
    └── colibri.md

Only manifest.json, SOUL.md, USER.md, and IDENTITY.md should be considered the core contract. Everything else is optional.

Manifest sketch

{
  "schema": "clawdie.layered-soul.v1",
  "agent_id": "hermes",
  "display_name": "Hermes",
  "owner": "operator-controlled",
  "updated_at": "2026-06-13T00:00:00Z",
  "core_files": {
    "soul": "SOUL.md",
    "user": "USER.md",
    "identity": "IDENTITY.md",
    "harness_rules": "AGENTS.md"
  },
  "layered_imports": {
    "skills": ["skills/**/*.md"],
    "memory": ["memories/curated/**/*.md"]
  },
  "privacy": {
    "raw_sessions": "archive-only",
    "secrets": "excluded",
    "operator_review_required": true
  },
  "adapters": {
    "pi": { "mode": "append-system-prompt" },
    "hermes": { "mode": "profile-restore" },
    "colibri": { "mode": "index-into-system-brain" }
  }
}

Adapter expectations

Pi

Pi can clone the soul repo, concatenate SOUL.md, USER.md, IDENTITY.md, and relevant AGENTS.md rules, then pass that bundle as an appended system prompt or project AGENTS.md context. Pi should not ingest raw sessions/ by default.

Hermes

Hermes can restore its native skills/, scripts, and selected memory files, but the shared identity should come from the core files. Hermes-specific config stays an adapter detail.

Colibri

Colibri should treat the soul repo as an import source:

• skills/ → system_skills after review;
• curated memory summaries → system_brain;
• cron/task definitions → system_ops only after conversion into task manifests;
• raw sessions → archive or offline summarization input.

Codex / Claude Code / Zot

These harnesses should receive only the minimal identity bundle plus task-specific context. They should not be asked to own durable memory directly; durable memory returns to the Layered Memory Fabric.

Install-path implication

The future installer should accept an optional soul repo:

clawdie install --soul git@code.smilepowered.org:clawdie/layered-soul.git

The installer should then:

1. clone read-only into a platform path;
2. validate manifest.json if present;
3. materialize root identity files only when missing or explicitly allowed;
4. import reviewed skills into system_skills;
5. import curated memories into system_brain;
6. leave raw sessions archived unless the operator requests summarization.

Hermes can remain configured from the existing Debby Linux hermes-soul backup while layered-soul becomes the clean cross-harness source repo. This keeps FreeBSD and Linux aligned: the platform adapter changes, but the soul repo contract stays the same.