layered-soul/README.md

# 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:

```text
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:

```sh
python3 scripts/layered_soul.py validate .
```

Render a compact prompt bundle for a task harness:

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

Inspect a private Hermes backup without copying private content:

```sh
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:

```json
{
  "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:

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