# 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

### How You Build Your Twin

Multiple input channels are already built into the foundation:

| Input | How It Works |
|-------|-------------|
| **Conversations** | Disagree with AI? Record the divergence — your reasoning, emotions, and final choice |
| **Gaming** | Your in-game decisions reveal personality dimensions: risk tolerance, leadership, moral choices |
| **Wearables** | Smart glasses, watches, earbuds — stream audio/video from your day, AI extracts decisions automatically |
| **Mobile Apps** | Quick-capture for on-the-go preference logging — tap, snap, or voice-memo a thought |
| **Media** | Photos, voice memos, videos — ingest any file, AI analyzes it semantically |
| **Writing Style** | Feed your blog posts, scripts, or social captions — your twin learns your voice |

### What This Looks Like

**Commanding — your twin acts on your behalf:**

- *"Set up my groceries for the week."* — Your twin handles Instacart. It knows you're lactose intolerant, prefer organic produce, and always want sparkling water. No lists to write.
- *"Push my League rank to Diamond."* — Your twin directs a gaming AI with your playstyle — aggressive flanking or patient farming, team fights or split pushing. Your calls, your climb.
- *"Build this feature."* — Stop re-explaining your architecture preferences to Copilot every session. Your twin knows your coding style, design philosophy, and naming conventions. It handles the AI conversation — the result is what you'd have built.
- *Humanoid robots* — Load your digital twin into a robot at home. Same decisions, same voice, same judgment. With permission, a loved one's trained model can live on — keeping their personality present.

**Validating — your twin filters and checks:**

- *You're a YouTuber or podcaster.* — AI generates scripts, but they're generic. Your twin filters every line through your voice — your humor, your pacing, your catchphrases. Every word sounds like you.
- *Email & Slack.* — AI drafts your replies. Your twin reviews each one before sending — adjusting tone, removing things you'd never say, adding the warmth or directness that's uniquely yours.
- *Music & taste.* — Spotify's algorithm guesses. Your twin *knows*. It validates recommendations against your actual taste — not what you clicked, but what you'd choose when you're honest with yourself.
- *Dating.* — Two people with trained twins can compare interests, habits, communication styles, and values — before months of awkward coffee dates. Better signal, less noise.

**Your Vault — your twin protects and remembers:**

- *Your twin is a super key.* — All your private data — text, photos, videos, timeline memories — encrypted with hash-chain technology. Grant layered access to trusted people: let a close friend explore your decisions, or a partner see your private memories. You control who sees what, and how deep.
- *Three timelines: past, present, future.* — Every decision, contradiction, and silent thought — recorded, searchable, recallable. Ask "what did I think about X three years ago?" and get an answer. A massive private database + a trained small model + a local large model = a digital twin that truly knows your life story.
- *A private notebook.* — Use it as a journal, a secure password vault, or a personal knowledge base. The model itself is the key, your data never leaves your machine. Everything you record is yours alone — until you decide to share it.
- Talk to your own digital twin. You might be surprised by what it says back.

> **This is an MCP built for the future.** The scenarios above aren't constrained by today's technology — they're the destination. OpenSoul captures structured decision data *now* so that when small-model fine-tuning, local inference, and humanoid robotics mature, your digital twin is ready. Some features work today with simple preference filtering; others are where the foundation is designed to take you. Start recording now.

---

## 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

**Start here:**
- [Complete Guide](docs/guide.md) — End-to-end journey: Install → Record → Analyze → Train → Command
- [Quick Start](docs/quickstart.md) — Get started in 5 minutes

**Reference:**
- [56 Tools Reference](docs/tools.md) — Every tool with scenarios, parameters, and implementation status
- [Core Concepts](docs/concepts.md) — Philosophy, input channels, super key, three timelines
- [Architecture](docs/architecture.md) — Technical implementation and privacy design

**Deep dives:**
- [Complete Tutorial](docs/tutorial.md) — 7 real-world scenarios with hands-on examples
- [Persona Card](docs/persona.md) — 60-question personality assessment
- [Narrative Engine](docs/narrative.md) — Guided deep conversations
- [Relationships](docs/relations.md) — Interpersonal relationship recording
- [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.*
