opensoul-mcp 0.3.2

Open source human decision digitalization system — train your digital twin to command and validate AI

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.

---

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

pip install opensoul-mcp
opensoul-mcp install

Restart Claude Code. Done.

From Source

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

Optional: Semantic Search

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 — Get started in 5 minutes
• Complete Tutorial — From beginner to expert
• Core Concepts — What is soul logging
• Tool Reference — All 56 tools explained
• Persona Card — 60-question personality assessment
• Narrative Engine — Guided deep conversations
• Relationships — Interpersonal relationship recording
• Architecture — Technical implementation
• Self-Hosting — Server deployment
• FAQ

---

Roadmap

See 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 for guidelines.

---

License

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

---

OpenSoul was created by Brother Butterfly · opensoul.top

AI that commands, checks, and completes.