Skill: kingcharleslzy-ai/soul-sharing (version 1.0.0)

--- 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/<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: 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 ```bash 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 ```bash 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`): ```markdown ## 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 ```bash # 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


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)