# OpenSoul MCP

**I exist not in the world, but in its logic.**

OpenSoul is an open-source human decision digitalization system. Train a small model — your digital twin — that knows what you like, how you think, and what you'd choose. Then let it command and validate the large models that do the actual work.

Because your digital twin *is* you. It *is* your taste, your habits, your judgment.

[![PyPI](https://img.shields.io/pypi/v/opensoul-mcp.svg)](https://pypi.org/project/opensoul-mcp/)
[![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/)

---

## The Vision

Today's AI is powerful but generic. It doesn't know *you*. Every time you talk to a large model, you spend half the conversation explaining your preferences, your constraints, your style. And the output still isn't quite right.

**What if a small model already knew all of that?**

OpenSoul builds your personality profile by recording every divergence between AI suggestions and your actual decisions — every disagreement, every silence, every hesitation. Over time, this becomes a vector-stored digital twin that can be fine-tuned into a small model that thinks like you.

### How It Works

```
You ←→ OpenSoul (record divergences) → Personality Profile → Train Small Model (your digital twin)
                                                                        ↓
                                                              Command & Validate
                                                                        ↓
                                                              Large Models Do Work
```

1. **Record** — OpenSoul captures every moment where you disagree with AI, recording context, emotions, reasoning, and patterns
2. **Profile** — Vector storage and semantic analysis build a multi-dimensional personality model
3. **Train** — Export training data to fine-tune a small model that mirrors your decision-making
4. **Command** — Your digital twin directs large models, so the output matches *your* taste without you lifting a finger
5. **Validate** — Your twin reviews and filters large model outputs before they reach you

### What This Looks Like

**Commanding:**

- *"Order my dinner every night at 6pm."* — Your digital twin handles DoorDash. It knows you hate repeating meals, prefer mild flavors, and always want a Diet Coke on the side. No menus to scroll through.
- *"Get my World of Warcraft character to Platinum."* — Your twin directs a gaming AI with your playstyle — aggressive or cautious, team-oriented or solo, your calls.
- *"Build this feature."* — Instead of explaining your architecture preferences, coding style, and design philosophy to an AI every time, your digital twin handles the conversation. The result is what you would have built.
- *Humanoid robots* — Instead of the manufacturer's default personality, load your digital twin. The robot at home acts like you — same decisions, same voice, same judgment. And if a loved one once had a trained model and granted access, their digital twin can live on in a robot, keeping their personality, their way of speaking, their presence.

**Validating:**

- *You're a streamer using an AI teleprompter.* — The AI generates lines from a massive database, but they're generic. Your digital twin filters every line through your style. Every word on screen sounds like you.
- *You're dating someone new.* — If both people have trained models, a compatibility check can surface differences in interests, habits, values, and communication styles before months of awkward dinners. Better signal, less noise.

**Other:**

- Talk to your own digital twin. You might be surprised by what it says back. Every output from a large model, filtered through your small model, speaks your mind.

---

## Where We Are Now

The vision is ambitious. We're building the foundation: the personality profiling system that captures who you are with enough depth and structure to eventually train that small model.

**Today, OpenSoul provides:**

| Capability | Description |
|------------|-------------|
| **56 MCP Tools** | Full coverage for recording, querying, analysis, and personality assessment |
| **INSERT-only Architecture** | Append-only, no modifications, complete history preserved |
| **SHA256 Hash Chain** | Each record cryptographically linked, tamper-proof |
| **Semantic Search** | Vector search + keyword matching via bge-m3 (Ollama) |
| **7-Dimensional Emotion Model** | Valence, intensity, duration, trigger type, and more |
| **Persona Card System** | 60-question three-tier personality assessment |
| **Relationship Network** | Record interpersonal relationships and interaction events |
| **Narrative Engine** | Guided multi-turn deep conversations |
| **Game Decision Mapping** | Game choices automatically mapped to personality dimensions |
| **Training Data Export** | Export LoRA/DPO pairs for fine-tuning your digital twin |
| **Local-First** | SQLite storage, data never leaves your machine |

---

## Quick Install

```bash
pip install opensoul-mcp
opensoul-mcp install
```

Restart Claude Code. Done.

### From Source

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

### Optional: Semantic Search

```bash
ollama pull bge-m3
```

Works without Ollama — falls back to keyword matching.

---

## First Soul Event

After restarting Claude Code, say:

```
Record a soul event:
- Context: Choosing between a high-paying job offer and a startup with equity
- AI suggestion: Take the stable high-paying offer
- My choice: Join the startup
- Reason: I'd rather build something meaningful than optimize for salary
- Emotional state: Nervous but excited
```

If Claude calls `record_soul` and returns a result, you're set.

---

## Tech Stack

- **Protocol**: MCP (Model Context Protocol)
- **Language**: Python 3.11+
- **Database**: SQLite (WAL mode)
- **Vectors**: bge-m3 via Ollama (optional)
- **Full-Text Search**: FTS5
- **Data Integrity**: SHA256 Hash Chain

---

## Documentation

- [Quick Start](docs/quickstart.md) — Get started in 5 minutes
- [Complete Tutorial](docs/tutorial.md) — From beginner to expert
- [Core Concepts](docs/concepts.md) — What is soul logging
- [Tool Reference](docs/tools.md) — All 56 tools explained
- [Persona Card](docs/persona.md) — 60-question personality assessment
- [Narrative Engine](docs/narrative.md) — Guided deep conversations
- [Relationships](docs/relations.md) — Interpersonal relationship recording
- [Architecture](docs/architecture.md) — Technical implementation
- [Self-Hosting](docs/self-hosting.md) — Server deployment
- [FAQ](docs/faq.md)

---

## Roadmap

See [ROADMAP.md](ROADMAP.md) for the full plan. The big milestones ahead:

- **Small model training pipeline** — From personality profile to fine-tuned model
- **Command interface** — Let your digital twin direct other AI agents
- **Validation layer** — Filter and review large model outputs through your twin
- **Cross-platform sync** — Bring your digital twin to any device

---

## Contributing

This is an ambitious vision. We need the open-source community to make it real. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## License

MIT License — Free to use, modify, and commercialize. Just retain the copyright notice.

---

**OpenSoul** was created by [Brother Butterfly](https://github.com/zbfzbf704) · [opensoul.top](https://opensoul.top)

> *AI that commands, checks, and completes.*
