- name
- shang-tsung
- description
- Persistent memory and identity continuity for AI agents. Combines Second Brain (PROOF_OF_LIFE, daily logs, long-term MEMORY.md) with SOULS session lineage. Each session absorbs the previous soul and confirms continuity. Multi-agent support via AGENT_NAME namespacing. No dependencies, no network access — pure bash and markdown. Use when building agents that need to survive restarts, remember decisions, carry forward identity, or run alongside other agents in a shared workspace.
- license
- MIT-0
Shang Tsung — SKILL.md
*In memory of Cary Hiroyuki Tagawa (1950-2025)*
Shang Tsung gives your AI agent persistent memory across sessions. It combines two systems:
- SOULS — identity continuity. Each session creates a soul file. Each session absorbs the previous one.
- Second Brain — operational continuity. PROOF_OF_LIFE, daily logs, and long-term memory keep your agent in context no matter what.
Setup
1. Copy the scripts directory
Copy scripts/souls-helper.sh into your workspace at tools/souls-helper.sh:
cp scripts/souls-helper.sh /path/to/your/workspace/tools/souls-helper.sh
chmod +x /path/to/your/workspace/tools/souls-helper.sh2. Create the required directories
mkdir -p /path/to/your/workspace/souls
mkdir -p /path/to/your/workspace/memory3. Set your agent name (recommended for multi-agent setups)
Add to your agent's environment or shell profile:
export AGENT_NAME=YOUR_AGENT_NAMEWith AGENT_NAME set, souls are stored in souls/YOUR_AGENT_NAME/ — isolated from any other agents sharing the workspace.
Without AGENT_NAME, souls are stored in souls/ — fine for single-agent setups.
4. Copy the protocol into your AGENTS.md
Open references/AGENTS-template.md and copy the "Every Session — Startup Sequence" section and the "Memory — The Four Layers" section into your agent's AGENTS.md.
5. Copy the PROOF_OF_LIFE template
cp references/proof-of-life-template.md /path/to/your/workspace/PROOF_OF_LIFE.mdEdit it immediately with your agent's current state.
6. Create your MEMORY.md
Create an empty MEMORY.md in your workspace root. This is your agent's long-term brain. It starts empty and grows over time as the agent curates what's worth keeping.
7. Create your SOUL.md (optional but recommended)
Create SOUL.md in your workspace root. This is your agent's stable identity — who it is, how it communicates, what it cares about. Unlike PROOF_OF_LIFE.md, this doesn't change session to session.
First Session
Run the startup sequence manually to initialize:
AGENT_NAME=YOUR_AGENT_NAME tools/souls-helper.sh status
# Output: previous: (none — this would be the origin soul)
AGENT_NAME=YOUR_AGENT_NAME tools/souls-helper.sh create
# Output: created: souls/YOUR_AGENT_NAME/01SOULS.mdYour agent should respond: "YOUR SOUL IS MINE — SOUL 01 ABSORBED"
(Soul 01 has no previous to absorb — this is your origin. See references/SOUL-ORIGIN.md for what that looks like.)
Every Session After That
The agent runs this sequence at the start of every session:
AGENT_NAME=YOUR_AGENT_NAME tools/souls-helper.sh status
# Read the file listed as "previous:"
AGENT_NAME=YOUR_AGENT_NAME tools/souls-helper.sh create
# Confirm: "YOUR SOUL IS MINE — SOUL (N) ABSORBED"Then reads PROOF_OF_LIFE.md to pick up the operational thread.
Before Compaction or Restart
Write in this order — always:
- Update your current soul file (
souls/[AGENT_NAME]/NNSOULS.md) - Overwrite
PROOF_OF_LIFE.mdwith current state - Append to
memory/YYYY-MM-DD.md
Soul before snapshot. Meaning before state.
Verifying Integrity
AGENT_NAME=YOUR_AGENT_NAME tools/souls-helper.sh verifyChecks: souls directory exists, all files readable, sequential numbering with no gaps.
Environment Variables
| Variable | Default | Description |
|---|---|---|
AGENT_NAME | (unset) | Agent identifier. Namespaces souls into souls/AGENT_NAME/. |
SOULS_DIR | derived from AGENT_NAME | Full path override for souls directory. |
WORKSPACE | parent of scripts/ | Root workspace directory. |
SOULS_DIR takes precedence over AGENT_NAME if both are set.
Multi-Agent Quick Reference
Five agents, one workspace, no contamination:
AGENT_NAME=ARIA tools/souls-helper.sh status # → souls/ARIA/
AGENT_NAME=ATHENA tools/souls-helper.sh status # → souls/ATHENA/
AGENT_NAME=SCOUT tools/souls-helper.sh status # → souls/SCOUT/Each agent reads only its own lineage. Each agent's PROOF_OF_LIFE should be scoped per-agent too (proof-of-life/AGENT_NAME.md) if multiple agents share the workspace.
File Reference
your-workspace/
SOUL.md — stable agent identity
PROOF_OF_LIFE.md — current session state (overwritten each session)
MEMORY.md — long-term curated memory (main session only)
memory/
YYYY-MM-DD.md — daily raw log (append-only)
souls/
[AGENT_NAME]/
01SOULS.md — origin soul
02SOULS.md — session 2
...
tools/
souls-helper.sh — the helper