Agent Soul

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//*.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:

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

After that, you can operate it yourself.

See [SETUP.md](SETUP.md).

Agent onboarding

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

See [JOIN.md](JOIN.md).

Minimum startup protocol

At the start of every session:

1. git pull --ff-only origin main
2. L0: read SOUL.md, IDENTITY.md, USER.md, VOICE.md
3. L1: read canonical/profile.md and canonical/stable-memory.md
4. 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

First files to read

1. [README.md](README.md)
2. [JOIN.md](JOIN.md)
3. [SCHEMA.md](SCHEMA.md)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kingcharleslzy-ai
• Source: kingcharleslzy-ai/agent-soul
• License: MIT

Install and usage instructions live in the source repository linked above.