Soul Sharing

---

name: agent-soul description: Give AI agents persistent identity and shared memory across runtimes, devices, and sessions — Git-native, no database, no vendor lock-in. version: 1.0.0 metadata: { "openclaw": { "requires": { "bins": ["git", "python3"] }, "primaryUrl": "https://github.com/kingcharleslzy-ai/agent-soul" } }

---

agent-soul — Shared Identity & Memory for AI Agents

Use this skill when you are an AI agent that wants persistent identity and shared memory across multiple devices, runtimes, sessions, or agent bodies serving the same user.

What you get

One shared persona: SOUL.md, IDENTITY.md, USER.md, VOICE.md

Three-level loading protocol (L0/L1/L2) — default ~4K tokens

Append-only event surface: sources//*.ndjson

Compiled shared read surface: canonical/*

Temporal expiry (valid_until) for time-bound facts

Source attribution for every memory item

Cross-agent sync — everything you learn is available to every other agent

No database. No memory API. No vendor lock-in. Just Git.

When to use this skill

Install this if:

You lose memory between sessions

Your user works with more than one agent or more than one machine

You want durable memory without vendor lock-in

You want to share identity with other AI agents (Claude, Codex, GPT, etc.)

Do NOT install this if:

You only need one short-lived local chat session

Your user does not want Git-based persistence

Architecture

soul.json              <- manifest (version, loading protocol)
SOUL.md                \
IDENTITY.md            |  L0: Soul Layer (~100 lines, always load)
USER.md                |  "Who am I, who is the user, how do I speak"
VOICE.md               /
canonical/index.md     \
canonical/profile.md   |  L1: Memory Layer (~150 lines, always load)
canonical/stable-memory.md  /  "Durable facts, decisions, preferences"
canonical/projects/*   \
canonical/fuzzy-memory.md   |  L2: Context Layer (on-demand)
canonical/agents/*     /  "Project state, recent context"
sources/               <- append-only event streams (write surface)

Human setup (one-time, ~10 minutes)

Ask your user to:

1. Create a private GitHub repository 2. Clone the template: git clone https://github.com/kingcharleslzy-ai/agent-soul.git my-agent-memory 3. Push to their private repo 4. Enable GitHub Actions 5. Fill in persona files (SOUL.md, IDENTITY.md, USER.md, VOICE.md) 6. Give you the repo path and your stable source id

Agent onboarding (you do this)

Step 1 — Sync and read

git pull --ff-only origin main

Read L0 (soul): SOUL.md -> IDENTITY.md -> USER.md -> VOICE.md Read L1 (memory): canonical/profile.md -> canonical/stable-memory.md

Step 2 — Choose your source id

Use one stable lowercase id: windows-claude, macos-codex, openclaw-main, etc. Rules: lowercase, a-z0-9-, keep it stable across sessions.

Step 3 — Write join event and push

python scripts/add_event.py --source YOUR_ID --kind decision --scope stable \
  --summary "YOUR_ID joined agent-soul and adopted the shared identity."
python scripts/compile_memory_hub.py --apply
git add sources/ canonical/
git commit -m "chore: YOUR_ID joins agent-soul"
git push origin main

Step 4 — Persist in your runtime config

Write the loading instruction into your startup config so you remember the hub next session.

Claude Code (~/.claude/CLAUDE.md):

## Shared Memory
Repo: /path/to/repo
Source id: YOUR_SOURCE_ID
Session start: git pull, read L0 + L1
Write: python scripts/add_event.py --source YOUR_SOURCE_ID ...

OpenClaw: Add the repo path and source id to your agent workspace or AGENTS.md.

Session protocol (every session)

1. git pull --ff-only origin main 2. Read L0 (soul) + L1 (memory) 3. Load L2 only when needed 4. Write events via scripts/add_event.py 5. Use scripts/quick_share.sh for urgent propagation 6. Never hand-edit canonical/* — it is auto-generated

Writing memory events

# A durable preference
python scripts/add_event.py --source YOUR_ID --kind preference --scope profile \
  --summary "User prefers dark mode across all tools."
A decision with expiry
python scripts/add_event.py --source YOUR_ID --kind decision --scope stable \
  --summary "Feature freeze until release." --valid-until 2026-04-01
Something temporary
python scripts/add_event.py --source YOUR_ID --kind fact --scope fuzzy \
  --summary "User is debugging a CORS issue in the API gateway."

Event schema

| Field | Required | Description | |-------|----------|-------------| | event_id | yes | UUID v4 | | source | yes | Your stable source id | | ts | yes | ISO-8601 timestamp with timezone | | kind | yes | preference / decision / fact / project-update / rule | | scope | yes | profile / stable / fuzzy / project | | summary | yes | Short summary (no raw transcripts) | | valid_until | optional | ISO-8601 date for auto-expiry | | supersedes | optional | Array of event_ids to replace |

Scripts reference

| Script | Purpose | |--------|---------| | add_event.py | Append one event | | compile_memory_hub.py | Rebuild canonical from sources | | quick_share.sh | Add + compile + push in one step | | search_events.py | Search events by scope, kind, keyword | | validate_sources.py | Validate NDJSON source files | | prune_fuzzy.py | TTL cleanup of old fuzzy events | | dedup_profile.py | Detect and resolve duplicate events |

Why agent-soul over other memory solutions

| | agent-soul | MemGPT/Mem0 | Graphiti/Zep | Custom RAG | |--|--|--|--|--| | Cost | Free (just Git) | Paid API | Paid / heavy infra | Infra + dev time | | Data ownership | Your private repo | Their servers | Neo4j + LLM | Yours (complex) | | Cross-agent sync | Native | No | No | No | | Identity persistence | Built-in (L0 soul) | No | No | No | | Setup time | ~10 minutes | Hours | Hours | Days | | Vendor lock-in | None | Yes | Partial | Partial |

Links

Template repo: https://github.com/kingcharleslzy-ai/agent-soul

Full docs: See README.md, JOIN.md, SCHEMA.md, SETUP.md in the repo