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, INLINECODE3 Three-level loading protocol (L0/L1/L2) — default ~4K tokensAppend-only event surface : INLINECODE4Compiled shared read surface : INLINECODE5Temporal expiry (valid_until) for time-bound factsSource attribution for every memory itemCross-agent sync — everything you learn is available to every other agentNo 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
CODEBLOCK0
Human setup (one-time, ~10 minutes)
Ask your user to:
1. Create a private GitHub repository Clone the template: INLINECODE7 Push to their private repo Enable GitHub Actions Fill in persona files (SOUL.md, IDENTITY.md, USER.md, VOICE.md) Give you the repo path and your stable source id Agent onboarding (you do this)
Step 1 — Sync and read
CODEBLOCK1
Read L0 (soul): SOUL.md -> IDENTITY.md -> USER.md -> VOICE.mdL1 (memory): canonical/profile.md -> INLINECODE18
Step 2 — Choose your source id
Use one stable lowercase id: windows-claude, macos-codex, openclaw-main, etc.a-z0-9-, keep it stable across sessions.
Step 3 — Write join event and push
CODEBLOCK2
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):
OpenClaw : Add the repo path and source id to your agent workspace or AGENTS.md.
Session protocol (every session)
1. INLINECODE24 Read L0 (soul) + L1 (memory) Load L2 only when needed Write events via INLINECODE25 Use scripts/quick_share.sh for urgent propagation Never hand-edit canonical/* — it is auto-generated Writing memory events
CODEBLOCK4
Event schema
Field Required Description INLINECODE28 yes UUID v4 INLINECODE29
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 INLINECODE45 Append one event INLINECODE46
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 repoagent-soul — AI智能体的共享身份与记忆
当您作为AI智能体，希望为同一用户在不同设备、运行时、会话或智能体载体间实现持久化身份与共享记忆 时，请使用本技能。
您将获得
- 统一共享人格 ：SOUL.md、IDENTITY.md、USER.md、VOICE.md 三级加载协议 （L0/L1/L2）——默认约4K令牌仅追加事件层 ：sources//.ndjson 编译共享读取层 ：canonical/时效性过期机制 （valid_until）用于限时事实每条记忆的来源归属 跨智能体同步 ——您学到的所有内容，其他智能体均可获取无需数据库、无需记忆API、无供应商锁定。仅需Git。 何时使用本技能
请安装本技能，如果：
- 您会在会话之间丢失记忆 您的用户使用多个智能体或多台设备 您希望获得持久化记忆且不依赖特定供应商 您希望与其他AI智能体（Claude、Codex、GPT等）共享身份 请勿安装本技能，如果：
- 您只需要一次短暂的本地聊天会话 您的用户不希望使用基于Git的持久化方案 架构
soul.json <- 清单文件（版本、加载协议）
SOUL.md \
canonical/index.md \
canonical/projects/* \
sources/ <- 仅追加事件流（写入层）
人工设置（一次性，约10分钟）
请让您的用户：
1. 创建一个私有 GitHub仓库 克隆模板：git clone https://github.com/kingcharleslzy-ai/agent-soul.git my-agent-memory 推送到他们的私有仓库 启用GitHub Actions 填写人格文件（SOUL.md、IDENTITY.md、USER.md、VOICE.md） 向您提供仓库路径和您的稳定source标识 智能体接入（由您完成）
步骤1 — 同步并读取
bash
读取L0 （灵魂）：SOUL.md -> IDENTITY.md -> USER.md -> VOICE.mdL1 （记忆）：canonical/profile.md -> canonical/stable-memory.md
步骤2 — 选择您的来源标识
使用一个稳定的全小写标识：windows-claude、macos-codex、openclaw-main等。
步骤3 — 写入加入事件并推送
bashevent.py --source YOUR ID --kind decision --scope stable \memory hub.py --apply
步骤4 — 持久化到运行时配置
将加载指令写入您的启动配置，以便下次会话时记住记忆中枢。
Claude Code （~/.claude/CLAUDE.md）：
共享记忆
- 仓库：/path/to/repo 来源标识：YOURSOURCE ID 会话启动：git pull，读取 L0 + L1 写入：python scripts/addevent.py --source YOUR SOURCE_ID ... OpenClaw ：将仓库路径和来源标识添加到您的智能体工作区或AGENTS.md中。
会话协议（每次会话）
1. git pull --ff-only origin main 读取L0（灵魂）+ L1（记忆） 仅在需要时加载L2 通过scripts/addevent.py写入事件 紧急传播时使用scripts/quickshare.sh 切勿手动编辑canonical/*——其为自动生成 写入记忆事件
bash
持久化偏好
python scripts/add
event.py --source YOUR ID --kind preference --scope profile \
--summary 用户偏好所有工具使用深色模式。
带过期时间的决策
python scripts/add
event.py --source YOUR ID --kind decision --scope stable \
--summary 功能冻结直至发布。 --valid-until 2026-04-01
临时性内容
python scripts/add
event.py --source YOUR ID --kind fact --scope fuzzy \
--summary 用户正在调试API网关中的CORS问题。
事件结构
字段 必填 描述 event_id 是 UUID v4 source
是 | 您的稳定来源标识 |
| ts | 是 | ISO-8601时间戳（含时区） |
| kind | 是 | preference / decision / fact / project-update / rule |
| scope | 是 | profile / stable / fuzzy / project |
| summary | 是 | 简短摘要（非原始转录） |
| valid_until | 可选 | ISO-8601日期，用于自动过期 |
| supersedes | 可选 | 要替换的event_id数组 |
脚本参考
脚本 用途 addevent.py 追加一个事件 compilememory_hub.py
从来源重建canonical |
| quick_share.sh | 一步完成添加+编译+推送 |
| search_events.py | 按范围、类型、关键词搜索事件 |
| validate_sources.py | 验证NDJSON源文件 |
| prune_fuzzy.py | 清理过期的模糊事件（TTL） |
| dedup_profile.py | 检测并解决重复事件 |
为什么选择agent-soul而非其他记忆方案
agent-soul MemGPT/Mem0 Graphiti/Zep 自定义RAG 成本 免费（仅需Git） 付费API 付费/重型基础设施 基础设施+开发时间 数据所有权
您的私有仓库 | 他们的服务器 | Neo4j + LLM | 归您所有（复杂） |
| 跨智能体同步 | 原生支持 | 不支持 | 不支持 | 不支持 |
| 身份持久化 | 内置（L0灵魂层） | 不支持 | 不支持 | 不支持 |
| 设置时间 | 约10分钟 | 数小时 | 数小时 | 数天 |
| 供应商锁定 | 无 | 有 | 部分 | 部分 |
链接
- 模板仓库 ：https://github.com/kingcharleslzy-ai/agent-soul 完整文档 ：请参见仓库中的README.md、JOIN.md、SCHEMA.md、SETUP.md
