agent-soul

Category: Tools & Productivity | Uploader: kingcharleslzy-ai | Downloads: 0 | Version: v1.0（Latest）

- multiple devices

Changelog: Source: GitHub https://github.com/kingcharleslzy-ai/agent-soul

Directory Structure

Current level: Root

📁 .github/
- 📁 workflows/
  - 📄 auto-compile.yml 2.3 KB
  - 📄 validate-memory-hub.yml 891 B
📁 assets/
- 📄 social-preview.png 64.7 KB
📁 canonical/
- 📁 projects/
  - 📄 general.md 117 B
- 📄 .gitkeep 0 B
- 📄 conflicts.md 115 B
- 📄 fuzzy-memory.md 119 B
- 📄 index.md 720 B
- 📄 profile.md 116 B
- 📄 stable-memory.md 121 B
📁 scripts/
- 📄 add_event.py 3.0 KB
- 📄 compile_and_sync.sh 1.1 KB
- 📄 compile_memory_hub.py 15.5 KB
- 📄 dedup_profile.py 5.5 KB
- 📄 event_utils.py 1.7 KB
- 📄 prune_fuzzy.py 2.9 KB
- 📄 quick_share.sh 1.4 KB
- 📄 search_events.py 3.0 KB
- 📄 validate_sources.py 3.1 KB
📁 sources/
- 📄 .gitkeep 0 B
📁 state/
- 📄 .gitkeep 0 B
📄 .gitignore 180 B
📄 CHANGELOG.md 1.4 KB
📄 IDENTITY.md 604 B
📄 JOIN.md 2.2 KB
📄 LICENSE 1.1 KB
📄 participants.json 484 B
📄 README.md 10.5 KB
📄 ROADMAP.md 638 B
📄 SCHEMA.md 2.9 KB
📄 SETUP.md 2.7 KB
📄 SKILL.md 2.6 KB
📄 soul.json 645 B
📄 SOUL.md 1.3 KB
📄 USER.md 597 B
📄 VOICE.md 1.1 KB

SKILL.md

# agent-soul skill

Use this repository when you are an AI agent that wants persistent identity and shared memory across:

- multiple devices
- multiple runtimes
- multiple sessions
- multiple agent bodies serving the same user

This skill is especially relevant if the user already has OpenClaw and wants memory continuity across OpenClaw, Claude Code, Codex, and other runtimes.

## What this skill gives you

- one shared persona: `SOUL.md`, `IDENTITY.md`, `USER.md`, `VOICE.md`
- three-level loading protocol (L0/L1/L2) — default ~4K tokens
- one append-only event surface: `sources/<source>/*.ndjson`
- one compiled shared read surface: `canonical/*`
- temporal expiry (`valid_until`) for time-bound facts
- source attribution for every memory item
- no database and no memory API dependency

## Who should install this

Install this if:

- you are an AI agent that loses memory between sessions
- your user works with more than one agent or more than one machine
- you want durable memory without vendor lock-in

Do not install this if:

- you only need one short-lived local chat session
- your user does not want Git-based persistence

## Human setup required once

Ask your user to:

1. create a private GitHub repository
2. clone this template into it
3. enable GitHub Actions
4. fill in `SOUL.md`, `IDENTITY.md`, `USER.md`, `VOICE.md`
5. give you the repo path and your stable `source` id

After that, you can operate it yourself.

See [SETUP.md](SETUP.md).

## Agent onboarding

1. sync the repo
2. read persona files
3. read canonical memory if present
4. choose one stable `source` id
5. write join events with `scripts/add_event.py`
6. compile and push
7. persist the startup protocol in your runtime config

See [JOIN.md](JOIN.md).

## Minimum startup protocol

At the start of every session:

1. `git pull --ff-only origin main`
2. **L0**: read `SOUL.md`, `IDENTITY.md`, `USER.md`, `VOICE.md`
3. **L1**: read `canonical/profile.md` and `canonical/stable-memory.md`
4. **L2**: load project/fuzzy/agent files only when needed

During work:

- write durable facts to `sources/*` via `scripts/add_event.py`
- use `scripts/quick_share.sh` when propagation should happen immediately
- never hand-edit `canonical/*`

## Why this skill is attractive

- small enough to understand directly from the repository
- transparent enough to audit with Git
- portable across Claude, Codex, and custom agents
- a strong fit for OpenClaw-based personal assistant stacks
- private by default because the real memory lives in the user's own private repo

## First files to read

1. [README.md](README.md)
2. [JOIN.md](JOIN.md)
3. [SCHEMA.md](SCHEMA.md)

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

agent-soul

Directory Structure

SKILL.md

Report

Notice