Layered Soul

Layered Soul is a public template for harness-agnostic agent identity and context bundles.

It is designed for Clawdie-compatible agents that may run through Pi, Hermes, Colibri, Codex, Claude Code, Zot, or future harnesses. The repository carries durable identity, reviewed user context, curated memories, and approved skills without copying a full runtime backup.

It is both the template and a working reference: the identity files, curated memories, and skills here are real, usable content — not placeholders. Spin off <agent>-layered-soul instances from it when you need a separate identity bundle (see "Template usage").

Why this exists

Agent runtimes already keep useful state, but their native backups are not safe or portable as-is. For example, a private hermes-soul repository may contain Hermes sessions, sanitized config, cron state, scripts, and memory files from a Debby Linux host. That is useful for Hermes restore, but it should not be pushed publicly or blindly imported into other harnesses.

layered-soul is the clean public layer:

private runtime backup          reviewed export             portable public/private soul
----------------------          ---------------             ----------------------------
hermes-soul/            ─────►  review queue      ─────►    layered-soul/
  sessions/                     no raw sessions             SOUL.md
  config.yaml                   no secrets                  USER.md
  memories/*.md                 curated summaries           IDENTITY.md
  skills/**/*.md                selected skills             AGENTS.md

Core files

• SOUL.md — durable agent identity, values, voice, and operating style
• USER.md — operator/user context that may be shared with this agent
• IDENTITY.md — short runtime identity and boundaries
• AGENTS.md — harness-facing operating rules
• manifest.json — schema, provenance, privacy, and adapter hints

Optional layers

• skills/ — reviewed reusable procedures that can seed system_skills or harness-native skill directories
• memories/curated/ — reviewed memory summaries that can seed system_brain
• adapters/ — notes for materializing the same soul into specific harnesses
• examples/private-sources/ — safe example configs for connecting private runtime backups
• scripts/layered_soul.py — stdlib helper for validation, prompt rendering, and private-source planning

Rules

• No secrets.
• No raw chat logs by default.
• No harness lock files or runtime caches.
• Runtime backups such as hermes-soul stay private unless the operator deliberately creates a sanitized export.
• Durable memory returns to the Layered Memory Fabric.

Quick start

Validate the repository:

python3 scripts/layered_soul.py validate .

Render a compact prompt bundle for a task harness:

python3 scripts/layered_soul.py render-prompt . --output /tmp/layered-soul-prompt.md

Inspect a private Hermes backup without copying private content:

python3 scripts/layered_soul.py plan-private-source \
  examples/private-sources/hermes-soul.example.json \
  --source-root ~/hermes-soul

The planner reports what could be reviewed/exported and what must remain private. It does not copy raw sessions or secrets.

Connecting hermes-soul properly

Use hermes-soul as the private Hermes-native backup and layered-soul as the portable contract.

Recommended flow:

1. Back up Hermes into the private hermes-soul repo from Debby Linux.
2. Run the private-source planner against that checkout.
3. Review candidate memories/skills manually.
4. Copy only sanitized summaries or selected skills into this repo.
5. Validate before committing.

Example private-source config:

{
  "name": "hermes-soul-private",
  "kind": "hermes-soul",
  "repo": "git@code.smilepowered.org:clawdie/hermes-soul.git",
  "visibility": "private",
  "export_policy": {
    "raw_sessions": "exclude",
    "runtime_config": "exclude",
    "secrets": "exclude",
    "memories": "review-required",
    "skills": "review-required"
  }
}

See docs/CONNECT-HERMES-SOUL.md for the longer playbook.

Template usage

This repository can be used as a Forgejo template. Create concrete soul repos from it when you want a separate identity bundle for a person, agent, project, or customer environment.

Suggested split:

clawdie/layered-soul          public template/schema
clawdie/hermes-soul           private Hermes runtime backup
clawdie/<agent>-layered-soul  curated identity instance when needed