opensoul-mcp 0.3.0

Open Source Personality Profiling System based on MCP Protocol

OpenSoul MCP

你有多久没有认真听自己说话了？

OpenSoul 是一个开源的人格画像系统。它记录你与 AI 的每一次分歧、每一个沉默、每一回纠结——不是为了监控你，是为了帮你看见自己。

---

一键安装

方式一：pip 安装（推荐）

pip install opensoul-mcp
opensoul-mcp install

完成。重启 Claude Code 即可使用。

opensoul-mcp install 会自动：

• 创建配置目录 ~/.opensoul/ 和数据目录 ~/.opensoul/data/
• 生成随机 API 密钥
• 将 OpenSoul 注册到 Claude Code 的 MCP 设置（~/.claude/settings.json）

方式二：从源码安装

git clone https://github.com/OpenSoul-MCP/opensoul-mcp.git
cd opensoul-mcp
pip install -e .
opensoul-mcp install

方式三：手动配置（不用 pip）

git clone https://github.com/OpenSoul-MCP/opensoul-mcp.git
cd opensoul-mcp
pip install -r requirements.txt

然后编辑 ~/.claude/settings.json：

{
  "mcpServers": {
    "opensoul": {
      "command": "python3",
      "args": ["/你的路径/opensoul-mcp/src/opensoul_mcp/server.py"]
    }
  }
}

可选：语义搜索

安装 Ollama 并拉取向量模型，启用语义搜索：

ollama pull bge-m3

没有 Ollama 也能正常使用，搜索会退化为关键词匹配。

---

验证安装

重启 Claude Code 后，对 Claude 说：

记录一个灵魂片段：
- 场景：选择工作 offer
- AI 建议：选高薪的
- 我的选择：选成长空间大的
- 原因：现阶段学习比钱重要

如果 Claude 调用了 record_soul 并返回结果，说明安装成功。

其他命令：

opensoul-mcp version   # 查看版本
opensoul-mcp run       # 手动启动 MCP server（调试用）

---

为什么需要 OpenSoul？

场景	痛点	OpenSoul 做什么
决策复盘	"为什么我总是后悔自己的选择？"	记录 AI 建议 vs 你的选择，发现决策模式
情绪追踪	"我不知道自己为什么突然崩溃"	7维情绪坐标系，找到隐藏的压力源
自我对话	"我想更了解自己"	持续记录构建人格画像，不是标签，是流动的自我

---

核心能力

能力	说明
40+ 个 MCP 工具	录入、查询、分析、人格评估全覆盖
INSERT-only 架构	只追加不修改，完整历史留存
SHA256 哈希链	每条记录加密链接，防篡改
语义搜索	向量搜索 + 关键词匹配（需配置 Ollama）
人格画像	7维人格模型分析
情绪坐标	效价、强度、持续时间、触发源
人格卡系统	60题三阶梯人格评估（与文案系统共享题库）
关系网络	记录人际关系及互动事件
叙事引擎	引导式深度对话，逐层挖掘
本地优先	SQLite 存储，数据不出你的电脑

---

技术栈

• 协议: MCP (Model Context Protocol)
• 语言: Python 3.11+
• 数据库: SQLite (WAL模式)
• 向量: bge-m3 via Ollama（可选，离线可用）
• 全文检索: FTS5
• 数据完整性: SHA256 哈希链

---

文档

• 快速开始 - 5分钟上手
• 完整教程 - 从入门到精通
• 核心概念 - 灵魂录入是什么
• 完整工具列表 - 40+个工具详解
• 人格卡系统 - 60题三阶梯人格评估
• 叙事引擎 - 引导式深度对话
• 关系网络 - 人际关系记录
• 示例数据 - 快速体验数据集
• 架构说明 - 技术实现
• 自建部署 - 服务器部署
• 常见问题

---

开源协议

MIT License - 自由使用、修改、商用，保留版权声明即可。

---

OpenSoul 由 蝴蝶哥 创建，域名 opensoul.top

每一个不被记录的念头，都是一次微小的遗忘。