kingcharleslzy-aikingcharleslzy-ai/agent-soul/clawhub-skill/SKILL.md

agent-soul

Skill8 starsChanged 8 months agoMITView on GitHub

Give AI agents persistent identity and shared memory across runtimes, devices, and sessions — Git-native, no database, no vendor lock-in.

Commits and pushes

2 other projects use a version of this.

Adopted by

Most recently taken up by

preetamnath/agent-skillstheir own version, first seen Apr 24, 2026
twilareckless401/agent-soulword for word, first seen Mar 16, 2026

Other versions2 projects use a version of this.
Word for word · 1
twilareckless401/agent-soul★ 2100% same
Edited · 0
None found.
Wrote their own version · 1
preetamnath/agent-skills★ 4same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repositoryOne other file it gives its agents.
- SKILL.mdSkill

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 8 are distinctive, and 6 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific
could be automatic: a setting could enforce it

Distinctive:
Use this skill when you are an AI agent that wants persistent identity and shared memory across multiple devices, runtimes, sessions, or …
line 10
Distinctive:
No database. No memory API.
line 21
Distinctive:
Do NOT install this if:
line 32
Distinctive:
Ask your user to:
line 60
Distinctive:
Create a private GitHub repository
line 62
Very specific:
Read L0 (soul): SOUL.md -> IDENTITY.md -> USER.md -> VOICE.md Read L1 (memory): canonical/profile.md -> canonical/stable-memory.md
line 77
Very specific:
Read L1 (memory): canonical/profile.md -> canonical/stable-memory.md
line 78
Very specific:
Use one stable lowercase id: windows-claude, macos-codex, openclaw-main, etc.
line 82
Distinctive:
Write the loading instruction into your startup config so you remember the hub next session.
line 98
Distinctive:
OpenClaw: Add the repo path and source id to your agent workspace or AGENTS.md.
line 109
Distinctive:
Read L0 (soul) + L1 (memory)
line 114
Very specific:
Write events via scripts/add_event.py
line 116
Very specific:
Use scripts/quick_share.sh for urgent propagation
line 117
Very specific:
Never hand-edit canonical/* — it is auto-generated
line 118

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

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

Create a private GitHub repository
Clone the template: git clone https://github.com/kingcharleslzy-ai/agent-soul.git my-agent-memory
Push to their private repo
Enable GitHub Actions
Fill in persona files (SOUL.md, IDENTITY.md, USER.md, VOICE.md)
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)

git pull --ff-only origin main
Read L0 (soul) + L1 (memory)
Load L2 only when needed
Write events via scripts/add_event.py
Use scripts/quick_share.sh for urgent propagation
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

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free