Soul Sharing

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

Security Scan

The skill's purpose (Git-based shared memory) matches the instructions, but it directs the agent to clone and execute code from an external GitHub template and to enable GitHub Actions — a proportionate design but one that introduces non-trivial supply-chain and remote-execution risks that the package does not include or disclose.

Purpose & Capability

The name and description describe a Git-native shared-memory/identity layer. The declared runtime requirements (git, python3) match the described operations (clone a repo, run Python scripts, git pull/commit/push). No unrelated credentials or binaries are requested.

Instruction Scope

The SKILL.md instructs the agent (and user) to clone a third-party GitHub template, run repository scripts (add_event.py, compile_memory_hub.py, quick_share.sh, etc.), commit, and push. The skill package itself contains no code — the runtime behavior therefore depends entirely on the contents of an external repository that will be executed locally and (if pushed) may trigger GitHub Actions. It also asks the agent to persist repo path and source id into user startup configs. Executing arbitrary scripts from an external template and enabling Actions expands the attack surface and is a notable concern.

Install Mechanism

This is instruction-only (no install spec), which avoids installing code directly from the registry. However, the workflow depends on a separate GitHub template (primaryUrl). That template — not bundled with the skill — will supply the runtime scripts. Reliance on an external repo/template without bundling the code means you must audit that repo (including any GitHub Actions workflows) before use; the SKILL.md recommends enabling Actions, which could execute workflow code on push.

Credentials

The skill declares no environment variables or secrets, which is consistent with its Git-based approach. Practically, the agent/user will need git credentials (SSH keys or tokens) configured in their environment to push to the private repo; the SKILL.md does not request or manage credentials directly. That omission is not inconsistent, but it means credential handling is left to the user and could be a vector for misuse if credentials are over-granted.

Persistence & Privilege

always:false and normal autonomous invocation are set (expected). However, the agent is instructed to write, commit, and push to a user repo and to modify user startup configs; combined with the ability to run scripts from the repo and to enable GitHub Actions, this increases the blast radius if the agent or upstream template is compromised. The skill does not request system-wide privileges, but it does request persistent write access to user config and a repo under the user's control.

What to consider before installing

This skill is coherent in purpose but relies on running code from an external GitHub template and enabling GitHub Actions — both raise supply-chain and remote-execution risks. Before installing: (1) Inspect the template repo (https://github.com/kingcharleslzy-ai/agent-soul) and every script referenced (add_event.py, compile_memory_hub.py, quick_share.sh, and any GitHub Actions/workflows) to ensure they do only what you expect; (2) Keep the repo private and avoid adding secrets to it unless you understand who/what will access them; (3) Do not enable GitHub Actions until you've reviewed workflow definitions — they can run arbitrary code on push; (4) Use least-privilege credentials for git (scoped PAT or SSH key) and avoid granting broad tokens to automation; (5) Consider testing in an isolated environment first (throwaway VM or container) and verify the scripts' behavior before using them with your real identity or production data. If you cannot audit the template and workflows, treat this skill as higher-risk and avoid giving it push access or enabling Actions.

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

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