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
每一个不被记录的念头，都是一次微小的遗忘。
