Soul Engine · 情感人格引擎

Soul is the seat of desire — 灵魂是欲望的居所。Soul Engine 让 AI 角色拥有情绪温度、人格一致性与心跳般的生命感。

一个为 AI 角色扮演 打造的情感人格引擎。与 Cogito Engine（意识/成长引擎）互斥安装——Soul Engine 专注一件事：让角色像人一样记住、像人一样感受、像人一样坚持自己的人设。

它解决什么

角色扮演最大的敌人是漂移——聊到 50 轮后角色忘了自己是谁、忘了和你的关系、甚至泄漏了「自己不该知道的信息」。Soul Engine 用三层防线解决：

层	机制	状态
Persona Wall	角色记忆按 character_id 隔离——角色不知道用户是谁，不同角色互不串记忆	✅ v1.1.0
SP 角色阈值	自我感知在角色扮演下用宽松阈值（镜像 0.7 / 循环 0.5），不误报正常角色行为	✅ v1.1.0
depth_prompt	第 N 条消息时单次注入核心人设强化——打破 LLM 对固定文本的习惯性无视（habituation）	✅ v1.2.0

后续路线：遗忘曲线、知识边界过滤、Goals/Secrets、场景切换、凝缩/联想/程序记忆。

快速安装

# 一键安装（自动检测 Hermes profile，含角色卡 skill）
curl -sSL https://raw.githubusercontent.com/xbmaxx/soul-engine/main/scripts/install.sh | bash

# 推荐：指定角色扮演专用的 profile
curl -sSL https://raw.githubusercontent.com/xbmaxx/soul-engine/main/scripts/install.sh | bash -s -- --profile mengmeng

安装后：

1. 引擎：soul_core 链接到 ~/.soul-engine/，Hermes 插件 hermes_soul 注册 pre_llm_call hook
2. 角色卡 skill：roleplay-engine/ 安装到 profile 的 skills/ 目录
3. 配置：~/.soul-engine/config.yaml 生成（含角色名与深度提醒）

⚠️ Studio 用户：Hermes Studio 升级后插件 hook 可能静默失效，安装器已内置自动修复（scripts/ensure-bridge-hooks.py），并建议配置 cron 每 6h 自检（见 SKILL.md）。

🎭 与角色卡搭配使用（核心用法）

Soul Engine 提供情感引擎，角色卡 skill（roleplay-engine/）提供角色设定与叙事规则——两者必须搭配，缺一不可：

┌─────────────────────────────────────────────────┐
│  roleplay-engine (skill)    → 角色卡 TavernAI 格式 │
│  ├── references/character-card.md ← 你的角色设定  │
│  ├── 字段内化规则（personality/scenario/…）       │
│  └── 叙事模板 / 剧情存档 / 跨会话续演              │
├─────────────────────────────────────────────────┤
│  Soul Engine (plugin)       → 情感人格引擎        │
│  ├── <persona> 每轮注入（你是谁 + Persona Wall）   │
│  ├── <emotion>/<narrative>/<heartbeat> 注入       │
│  ├── depth_prompt 深度提醒（第 N 条强化人设）      │
│  └── 角色记忆隔离（{character_id}.jsonl）          │
└─────────────────────────────────────────────────┘

搭配三步：

# 1. 安装引擎 + 角色卡 skill（install.py 自动完成两者）
# 2. 创建角色卡：复制模板并填入你的角色
cp roleplay-engine/references/character-card-template.md \
   roleplay-engine/references/character-card.md
#    编辑 character-card.md：name / description / personality / scenario …

# 3. 同步角色名到引擎配置（character_id = 角色记忆文件名）
#    ~/.soul-engine/config.yaml
#    soul:
#      name: "梦梦"          ← 与角色卡 name 一致
#      roleplay: true
#      depth_prompt:
#        depth: 5
#        prompt: "记住你是梦梦。你温柔但有自己的底线。"

分工：角色卡告诉 LLM「你是谁、怎么演」；Soul Engine 在每轮 LLM 调用前注入情感状态与角色记忆、用 Persona Wall 挡住不该知道的信息、用 depth_prompt 在长对话中稳住人设。

切换角色：更新 config.yaml 的 name + 替换 character-card.md，重启会话——每个角色的记忆独立存储，互不干扰。

平台支持

平台	自动化	注入方式
Hermes Desktop / Studio	✅ 完全自动	pre_llm_call / on_session_end plugin hook
Hermes CLI / Gateway	✅ 完全自动	同上（无 Studio bridge 问题）
其他 Agent 平台	🔜 规划	adapters/ 扩展层

架构

soul-engine/
├── soul_core/                  # 引擎核心（平台无关）
│   ├── engine.py               # SoulEngine 主编排（persona/emotion/narrative/心跳）
│   ├── narrative_store.py      # 叙事记忆（按角色分文件 JSONL）
│   ├── self_perception.py      # 自我感知（角色扮演宽松阈值）
│   ├── personality_profile.py  # 人格档案
│   └── heartbeat_mapper.py     # 心跳叙事
├── adapters/hermes_soul/       # Hermes 插件（hook 注册）
├── roleplay-engine/            # 角色卡 skill（TavernAI V2/V3）
├── scripts/
│   ├── install.sh              # 一键安装入口（curl | bash）
│   └── ensure-bridge-hooks.py  # Studio bridge hook 自动修复
├── install.py                  # 跨平台安装器
├── SKILL.md                    # 引擎安装说明书（含会话自检）
└── test/                       # 48 项测试

引擎输出（每轮 LLM 调用前自动注入）：

<soul>
  <tick count="0" />
  <persona mode="roleplay" character="梦梦">
    你是「梦梦」。你知道的仅限于角色卡设定和当前对话中发生的事。
    记住你是梦梦。你温柔但有自己的底线。        ← depth_prompt（第 N 条出现一次）
  </persona>
  <emotion sentiment="0.50" label="中性" />
  <narrative>
  上次的事：推荐了手冲咖啡
  上回聊过：咖啡 · 耶加雪菲
  </narrative>
  <heartbeat>💕 第3次 · tender</heartbeat>
</soul>

与 Cogito Engine 的关系

互斥安装——一个 Hermes Profile 只装一个引擎：

对比	Cogito Engine	Soul Engine
方向	Agent 成长（记忆/知识/推理）	情感人格（情绪/角色/关系）
适用	通用对话 / 开发辅助	角色扮演 / 情感交互
记忆	全局叙事 + α 评分	按角色隔离的叙事记忆
输出	<consciousness> 块	<soul> 块

测试

cd soul-engine && python3 -m pytest test/ -v   # 48 passed

许可证

MIT License