Shang Tsung

Persistent memory and identity continuity for AI agents. Combines Second Brain (PROOF_OF_LIFE, daily logs, long-term MEMORY.md) with SOULS session lineage. E...

Security Scan

The skill's files and runtime instructions are coherent with its stated purpose (local, file-based persistent memory); it only reads/writes Markdown in a workspace and the included shell script performs only local filesystem operations.

Purpose & Capability

Name/description (persistent memory, SOULS, Second Brain) match the contents: documentation + a single bash helper that creates/reads numbered soul files and manages workspace-local memory files. No extraneous credentials, network access, or unrelated binaries are requested.

Instruction Scope

SKILL.md instructs the agent to read/write local files (SOUL.md, PROOF_OF_LIFE.md, MEMORY.md, memory/*, souls/*) which is expected for a persistence system. The docs advise loading MEMORY.md only in private sessions (a privacy policy, not an enforced guard). Users should note these files may contain personal context and that the guidance relies on agent behavior rather than an enforcement mechanism.

Install Mechanism

Instruction-only skill with a single included script; no install spec, no downloads, no external packages. The helper is pure bash and the README/SECURITY.md accurately describe its local-only nature.

Credentials

No secrets or unusual environment variables are required. Optional variables (AGENT_NAME, SOULS_DIR, WORKSPACE) are reasonable for namespacing and path overrides and align with the documented functionality.

Persistence & Privilege

Skill is not always:true and has no elevated platform privileges. It writes only to the workspace (user-specified path) and does not modify other skills or global agent configuration. Autonomous invocation is allowed by default (platform normal) but the skill's actions remain local.

Assessment

This skill appears to do what it claims: local, file-based persistence. Before installing, (1) review scripts/souls-helper.sh yourself (it's small) to confirm the target directory is correct; (2) store your workspace in a location you control — memory files may contain personal or sensitive context; (3) if other skills or your agent runtime have network access, be aware those components could read and transmit the same Markdown files — the skill itself does not exfiltrate data; (4) prefer setting SOULS_DIR explicitly if you want to avoid accidental writes outside an expected path; and (5) verify the upstream repository if provenance matters (skill.json points to a GitHub repo). If you need enforced privacy guarantees (not just guidance), consider additional runtime controls (restrict network access, limit which sessions can read MEMORY.md).

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.sh

2. Create the required directories

mkdir -p /path/to/your/workspace/souls
mkdir -p /path/to/your/workspace/memory

3. Set your agent name (recommended for multi-agent setups)

Add to your agent's environment or shell profile:

export AGENT_NAME=YOUR_AGENT_NAME

With 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.md

Edit 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.md

Your 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:

1. Update your current soul file (souls/[AGENT_NAME]/NNSOULS.md)
2. Overwrite PROOF_OF_LIFE.md with current state
3. Append to memory/YYYY-MM-DD.md

Soul before snapshot. Meaning before state.

---

Verifying Integrity

AGENT_NAME=YOUR_AGENT_NAME tools/souls-helper.sh verify

Checks: 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