# OpenSoul MCP

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

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MCP Protocol](https://img.shields.io/badge/MCP-Protocol-green.svg)](https://modelcontextprotocol.io/)

---

## 为什么需要 OpenSoul？

### 场景一：决策复盘
> "为什么我总是后悔自己的选择？"

OpenSoul 记录决策时的真实状态——AI 建议了什么、你实际选择了什么、为什么分歧。事后回看，你会发现自己的决策模式。

### 场景二：情绪追踪
> "我不知道自己为什么突然崩溃"

7维情绪坐标系，记录效价、强度、持续时间、触发源。找到隐藏的压力源，而不是事后猜测。

### 场景三：自我对话
> "我想更了解自己"

60题灵魂评测，从基础身份到存在主义，结构化地构建你的人格画像。不是标签，是流动的自我。

---

## 30秒快速开始

```bash
# 1. 克隆仓库
git clone https://github.com/zbfzbf704/opensoul-mcp.git
cd opensoul-mcp

# 2. 安装依赖
pip install -r requirements.txt

# 3. 配置 MCP（Claude Code）
python install.py
```

然后对 Claude 说：

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

---

## 核心能力

| 能力 | 说明 |
|------|------|
| **56 个 MCP 工具** | 录入、查询、分析、叙事引导全覆盖 |
| **INSERT-only 架构** | 只追加不修改，完整历史留存 |
| **SHA256 哈希链** | 每条记录加密链接，防篡改 |
| **三通道召回** | 语义向量 + 关键词 + 实体匹配 |
| **60题灵魂评测** | 基础→深化→灵魂，三阶梯画像 |
| **7维情绪坐标** | 效价、强度、时长、触发源等 |

---

## 技术栈

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

---

## 文档

- [快速开始](docs/quickstart.md) - 5分钟上手
- [完整教程](docs/tutorial.md) - 从入门到精通
- [核心概念](docs/concepts.md) - 灵魂录入是什么
- [完整工具列表](docs/tools.md) - 56个工具详解
- [示例数据](docs/examples.md) - 快速体验数据集
- [架构说明](docs/architecture.md) - 技术实现
- [自建部署](docs/self-hosting.md) - 服务器部署
- [常见问题](docs/faq.md)

---

## 开源协议

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

---

**OpenSoul** 由 [蝴蝶哥](https://github.com/zbfzbf704) 创建，域名 [opensoul.top](https://opensoul.top)

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