agent-soul skill

Use this repository when you are an AI agent that wants persistent identity and shared memory across:

multiple devices
multiple runtimes
multiple sessions
multiple agent bodies serving the same user

This skill is especially relevant if the user already has OpenClaw and wants memory continuity across OpenClaw, Claude Code, Codex, and other runtimes.

What this skill gives you

one shared persona: SOUL.md, IDENTITY.md, USER.md, VOICE.md
three-level loading protocol (L0/L1/L2) — default ~4K tokens
one append-only event surface: sources/<source>/*.ndjson
one compiled shared read surface: canonical/*
temporal expiry (valid_until) for time-bound facts
source attribution for every memory item
no database and no memory API dependency

Who should install this

Install this if:

you are an AI agent that loses memory between sessions
your user works with more than one agent or more than one machine
you want durable memory without vendor lock-in

Do not install this if:

you only need one short-lived local chat session
your user does not want Git-based persistence

Human setup required once

Ask your user to:

create a private GitHub repository
clone this template into it
enable GitHub Actions
fill in SOUL.md, IDENTITY.md, USER.md, VOICE.md
give you the repo path and your stable source id

After that, you can operate it yourself.

See SETUP.md.

Agent onboarding

sync the repo
read persona files
read canonical memory if present
choose one stable source id
write join events with scripts/add_event.py
compile and push
persist the startup protocol in your runtime config

See JOIN.md.

Minimum startup protocol

At the start of every session:

git pull --ff-only origin main
L0: read SOUL.md, IDENTITY.md, USER.md, VOICE.md
L1: read canonical/profile.md and canonical/stable-memory.md
L2: load project/fuzzy/agent files only when needed

During work:

write durable facts to sources/* via scripts/add_event.py
use scripts/quick_share.sh when propagation should happen immediately
never hand-edit canonical/*

Why this skill is attractive

small enough to understand directly from the repository
transparent enough to audit with Git
portable across Claude, Codex, and custom agents
a strong fit for OpenClaw-based personal assistant stacks
private by default because the real memory lives in the user's own private repo

agent-soul