# Agent Soul

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

- **Type:** Skill
- **Install:** `agentstack add skill-kingcharleslzy-ai-agent-soul-clawhub-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kingcharleslzy-ai](https://agentstack.voostack.com/s/kingcharleslzy-ai)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kingcharleslzy-ai](https://github.com/kingcharleslzy-ai)
- **Source:** https://github.com/kingcharleslzy-ai/agent-soul/tree/main/clawhub-skill

## Install

```sh
agentstack add skill-kingcharleslzy-ai-agent-soul-clawhub-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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//*.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               `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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kingcharleslzy-ai](https://github.com/kingcharleslzy-ai)
- **Source:** [kingcharleslzy-ai/agent-soul](https://github.com/kingcharleslzy-ai/agent-soul)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-kingcharleslzy-ai-agent-soul-clawhub-skill
- Seller: https://agentstack.voostack.com/s/kingcharleslzy-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.