BotSoul 文档

把人格、记忆、技能从 AI 工具中解放出来，随身携带。

安装

BotSoul 基于 Node.js 20+ 开发。安装 CLI 后即可使用。

npm install -g @botsoul/cli

# 验证安装
botsoul --version

如果你更喜欢不安装全局包，也可以使用 npx：

npx @botsoul/cli --help

快速开始

初始化 BotSoul，创建第一个灵魂，绑定到本机的 OpenClaw 或 WorkBuddy。

# 1. 初始化灵魂仓库（默认 ~/.botsoul/）
botsoul init

# 2. 创建默认灵魂
botsoul soul create default

# 3. 绑定到 OpenClaw
botsoul soul bind default --agent openclaw

# 4. 启动后台同步
botsoul sync --watch

现在你在 OpenClaw 里修改 SOUL.md 或 MEMORY.md，BotSoul 会自动检测到变化并保存版本。同时会同步到其他已绑定的 Agent。

核心概念

灵魂（Soul）

灵魂是一个人格包，包含：

• SOUL.md：人格定义、沟通风格、价值观
• IDENTITY.md：名字、角色、Emoji 等基础身份
• preferences.json：可结构化的偏好设定
• memories/：属于该灵魂的记忆集合
• skills/：该灵魂安装的技能

Agent

Agent 是 AI 工具实例，例如 OpenClaw、WorkBuddy、DSH、Claude Code。每个 Agent 可以绑定一个灵魂。

记忆范围（Scope）

记忆可以设置范围，决定哪些 Agent 能读取：

• all：所有 Agent 都可见
• work：只给工作相关的 Agent
• personal：只给个人生活 Agent
• <agent-id>：只给指定 Agent

CLI 命令

灵魂管理

botsoul soul create <name>        # 创建灵魂
botsoul soul list                 # 列出所有灵魂
botsoul soul edit <name>          # 编辑灵魂
botsoul soul delete <name>        # 删除灵魂
botsoul soul bind <name> --agent <agent>  # 绑定到 Agent
botsoul soul export <name>        # 导出为 .soul.json
botsoul soul import <file>        # 导入灵魂

记忆管理

botsoul memory list               # 列出记忆
botsoul memory add "内容" --tag work --scope all
botsoul memory search "关键词"
botsoul memory toggle <id>        # 启用/禁用记忆

同步

botsoul sync                      # 手动同步一次
botsoul sync --watch              # 后台监听同步
botsoul sync --agent openclaw        # 只同步某个 Agent

MCP 工具

BotSoul 提供标准 MCP 服务器。安装后，任何 Agent 都可以通过自然语言调用这些工具管理你的灵魂。

安装到 OpenClaw

openclaw mcp add --name botsoul --command "npx" --args "@botsoul/mcp"

安装到 Claude Code

claude mcp add botsoul npx @botsoul/mcp

主要工具

• botsoul_soul_get：读取当前灵魂摘要
• botsoul_soul_set：更新灵魂配置
• botsoul_memory_add：添加一条记忆
• botsoul_memory_search：语义搜索记忆
• botsoul_memory_toggle：启用/禁用记忆
• botsoul_skills_list：列出已安装技能
• botsoul_skills_sync：同步技能到 Agent
• botsoul_status：查看同步状态

同步策略

BotSoul 默认使用双向文件监听同步：

• Agent 的 workspace 文件变化 → BotSoul 读取并保存到灵魂仓库
• 灵魂仓库变化 → BotSoul 写入到已绑定的 Agent workspace
• 冲突时默认通知用户，避免静默覆盖

你可以为每个 Agent 单独配置同步策略：

{
  "openclaw": { "mode": "auto", "scopes": ["all", "personal"] },
  "workbuddy": { "mode": "auto", "scopes": ["all", "work"] },
  "claude": { "mode": "manual" }
}

配置文件

全局配置文件位于 ~/.botsoul/config.json：

{
  "soulStore": "~/.botsoul/souls",
  "sync": {
    "enabled": true,
    "interval": 5000,
    "conflictPolicy": "notify"
  },
  "mcp": {
    "transport": "stdio"
  },
  "evolution": {
    "autoLearn": true,
    "protectedSections": ["SOUL.md##核心人格"]
  }
}

灵魂市场

灵魂市场允许你购买、出售、分享训练好的灵魂。

# 浏览市场
botsoul market list

# 安装一个灵魂到本地
botsoul market install product-manager

# 发布自己的灵魂（需注册开发者账号）
botsoul market publish default --price 99

市场功能仍在开发中，预计 2027 年 Q1 上线。