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

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

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

Start here:

• Complete Guide — End-to-end journey: Install → Record → Analyze → Train → Command
• Quick Start — Get started in 5 minutes

Reference:

• 56 Tools Reference — Every tool with scenarios, parameters, and implementation status
• Core Concepts — Philosophy, input channels, super key, three timelines
• Architecture — Technical implementation and privacy design

Deep dives:

• Complete Tutorial — 7 real-world scenarios with hands-on examples
• Persona Card — 60-question personality assessment
• Narrative Engine — Guided deep conversations
• Relationships — Interpersonal relationship recording
• 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.