opensoul-mcp 0.3.1

Open Source Personality Profiling System based on MCP Protocol

OpenSoul MCP

When was the last time you truly listened to yourself?

OpenSoul is an open-source personality profiling system. It records every disagreement with AI, every moment of silence, every hesitation—not to monitor you, but to help you see yourself.

---

Quick Install

Option 1: pip Install (Recommended)

pip install opensoul-mcp
opensoul-mcp install

Done. Restart Claude Code and you're ready to go.

opensoul-mcp install automatically:

• Creates config directory ~/.opensoul/ and data directory ~/.opensoul/data/
• Generates a random API key
• Registers OpenSoul in Claude Code's MCP settings (~/.claude/settings.json)

Option 2: Install from Source

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

Option 3: Manual Configuration (No pip)

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

Then edit ~/.claude/settings.json:

{
  "mcpServers": {
    "opensoul": {
      "command": "python3",
      "args": ["/your/path/opensoul-mcp/src/opensoul_mcp/server.py"]
    }
  }
}

Optional: Semantic Search

Install Ollama and pull the embedding model to enable semantic search:

ollama pull bge-m3

OpenSoul works without Ollama—search will fall back to keyword matching.

---

Verify Installation

After restarting Claude Code, say to Claude:

Record a soul fragment:
- Context: Choosing between job offers
- AI suggestion: Pick the high-paying one
- My choice: Choose the one with growth potential
- Reason: Learning matters more than money at this stage

If Claude calls record_soul and returns results, installation is successful.

Other commands:

opensoul-mcp version   # Check version
opensoul-mcp run       # Start MCP server manually (for debugging)

---

Why OpenSoul?

Scenario	Pain Point	What OpenSoul Does
Decision Review	"Why do I always regret my choices?"	Records AI suggestions vs your choices to discover decision patterns
Emotion Tracking	"I don't know why I suddenly broke down"	7-dimensional emotion coordinates to find hidden stress sources
Self-Dialogue	"I want to understand myself better"	Continuous recording builds a personality profile—not labels, but a flowing self

---

Core Capabilities

Capability	Description
40+ 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 (requires Ollama configuration)
Personality Profile	7-dimensional personality model analysis
Emotion Coordinates	Valence, intensity, duration, trigger source
Persona Card System	60-question three-tier personality assessment (shares question bank with copywriting system)
Relationship Network	Record interpersonal relationships and interaction events
Narrative Engine	Guided deep conversations, layer-by-layer exploration
Local-First	SQLite storage, data never leaves your computer

---

Tech Stack

• Protocol: MCP (Model Context Protocol)
• Language: Python 3.11+
• Database: SQLite (WAL mode)
• Vectors: bge-m3 via Ollama (optional, works offline)
• 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
• Complete Tool List - 40+ tools explained
• Persona Card System - 60-question three-tier personality assessment
• Narrative Engine - Guided deep conversations
• Relationship Network - Interpersonal relationship recording
• Example Data - Quick experience dataset
• Architecture - Technical implementation
• Self-Hosting - Server deployment
• FAQ

---

License

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

---

OpenSoul was created by Butterfly Brother. Domain: opensoul.top

Every thought that goes unrecorded is a tiny act of forgetting.