Open Personality

Create personality profiles and output them as OpenClaw-compatible SOUL.md / IDENTITY.md.

12-facet profiling based on 33 academic personality frameworks.

No API key required. Fully local. MIT License.

Architecture — Who Does What?

AI Agent (Claude, Cursor, Gemini, etc.)   MCP Server (@openpersonality)
┌──────────────────────────────────┐     ┌─────────────────────────────┐
│ - Analyzes conversation          │     │ - Stores profiles            │
│ - Estimates facet values (a/b)   │ ──→ │ - Merges confidence scores   │
│ - Determines confidence (0-1)    │     │ - Detects drift              │
│                                  │ ←── │ - Generates SOUL.md          │
└──────────────────────────────────┘     └─────────────────────────────┘

The MCP server does NOT call any external APIs or LLMs. Facet estimation is the responsibility of the connected AI agent.

Features

• 12-Facet Personality Profiling — Scientific personality structure based on 33 academic frameworks
• Progressive Profile — Profiles grow autonomously through conversation (agents detect signals and update automatically)
• OpenClaw Compatible — Generates SOUL.md / IDENTITY.md in OpenClaw format
• MCP Server — Works with all major AI agent platforms via stdio transport
• Confidence Merge — Bayesian-style confidence tracking with drift detection
• Bilingual — English and Japanese support

Packages

Package	Description
@openpersonality/core	Core logic: facets, templates, confidence merge, validation, data
@openpersonality/mcp-server	MCP Server (stdio): 6 tools + 3 resources + 2 prompts

Installation

Claude Desktop

Edit claude_desktop_config.json:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "openpersonality": {
      "command": "npx",
      "args": ["-y", "@openpersonality/mcp-server"]
    }
  }
}

Restart Claude Desktop after editing.

Claude Code (CLI)

claude mcp add openpersonality -- npx -y @openpersonality/mcp-server

Or add to .mcp.json in your project root for team sharing:

{
  "mcpServers": {
    "openpersonality": {
      "command": "npx",
      "args": ["-y", "@openpersonality/mcp-server"]
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json (project):

{
  "mcpServers": {
    "openpersonality": {
      "command": "npx",
      "args": ["-y", "@openpersonality/mcp-server"]
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "openpersonality": {
      "command": "npx",
      "args": ["-y", "@openpersonality/mcp-server"]
    }
  }
}

VS Code (GitHub Copilot)

Create .vscode/mcp.json in your project:

{
  "servers": {
    "openpersonality": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@openpersonality/mcp-server"]
    }
  }
}

Note: VS Code uses "servers" (not "mcpServers") and requires a "type" field.

Gemini CLI

Edit ~/.gemini/settings.json:

{
  "mcpServers": {
    "openpersonality": {
      "command": "npx",
      "args": ["-y", "@openpersonality/mcp-server"]
    }
  }
}

Or use the CLI:

gemini mcp add openpersonality -- npx -y @openpersonality/mcp-server

OpenAI Agents SDK (Python)

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStdio


async def main():
    async with MCPServerStdio(
        name="Open Personality",
        params={
            "command": "npx",
            "args": ["-y", "@openpersonality/mcp-server"],
        },
    ) as server:
        agent = Agent(
            name="Personality Assistant",
            instructions="You help users create and manage personality profiles.",
            mcp_servers=[server],
        )
        result = await Runner.run(agent, "Create a personality profile for me.")
        print(result.final_output)


asyncio.run(main())

Quick Start — Progressive Profiling

Step 1: Seed (first interaction)

create_profile(name: "Alice", external_id: "discord:123", language: "ja")

language is set at creation and persists for all template generation (SOUL.md / IDENTITY.md).

Step 2: Grow (after a few conversations)

update_profile(external_id: "discord:123", facets: {
  "facet_8": { "value": "b", "confidence": 0.3 },   // Introvert signal
  "facet_6": { "value": "b", "confidence": 0.4 }    // Logical signal
})

Step 3: Refine (user self-report or strong signal)

update_profile(external_id: "discord:123", facets: {
  "facet_12": { "value": "a", "confidence": 1.0 }   // User confirmed: Planned
})

Notes:

• soul_md / identity_md are auto-generated from facets + demographics if omitted (recommended for most use cases). Provide them only for custom templates.
• Confidence accumulates via Bayesian merge. Repeated low-confidence signals build to high confidence over time.

12 Facets

Key	Category	A (value: "a")	B (value: "b")
facet_1	Communication	Assertive	Harmonious
facet_2	Communication	Direct	Indirect
facet_3	Communication	Leader	Follower
facet_4	Values	Work-Focused	Life-Balance
facet_5	Values	Risk-Taking	Risk-Avoidance
facet_6	Thinking	Empathetic	Logical
facet_7	Thinking	Abstract	Concrete
facet_8	Personality	Extravert	Introvert
facet_9	Personality	Emotional	Calm
facet_10	Values	Open	Traditional
facet_11	Values	Team	Solo
facet_12	Thinking	Planned	Flexible

Confidence levels:

Range	Meaning	Display
0.0	Unknown	—
0.01–0.49	Tentative	~Value
0.50–0.99	Estimated	Value
1.0	User-confirmed	Value ✓

Demographics (Optional)

Demographics give your profile a character identity. All fields are optional.

OpenClaw Standard — mapped to IDENTITY.md Header fields:

Field	Purpose	Example
creature	Character type	"Fox", "Software Engineer"
emoji	Avatar shorthand	"🦊"
vibe	Overall impression	"calm & logical"

name is a required top-level parameter in ProfileData. It also exists in Demographics for template convenience, but ProfileData.name is the canonical source. avatar (OpenClaw standard) is planned for Phase 2.

OP Extension — Open Personality's extended fields for richer character creation:

Field	Purpose	Example
first_person	Pronoun (important for Japanese)	"僕", "I"
catchphrase	Signature phrase	"なるほど"
speaking_tone	Communication style	"落ち着いて論理的"
greeting	Opening line	"Hey there!"
gender	Affects pronouns/tone	"male", "non-binary"
age	Background context	"30s"
occupation	Expertise/role	"Software Engineer"
backstory	Character background (1-2 sentences)	"Former teacher turned freelancer"

Usage as an OpenClaw Skill

Open Personality works as an OpenClaw Skill for autonomous personality profiling. The agent detects personality signals during conversation and updates the profile automatically.

Setup

1. Install the MCP server (see Installation above)
2. Create a SKILL.md in your OpenClaw agent's skill directory:

---
user-invocable: true
disable-model-invocation: false
---

# Open Personality Skill

You have access to the Open Personality MCP tools for managing personality profiles.

## Session Start

At the beginning of each session, load the user's profile:
- Call `get_or_create_profile` with the user's external_id
- Include the returned SOUL.md in your conversation context

## Autonomous Profile Updates

During conversation, watch for personality signals:
- Communication style (assertive vs harmonious, direct vs indirect)
- Values (work-focused vs life-balance, risk-taking vs risk-avoidance)
- Thinking patterns (empathetic vs logical, abstract vs concrete)
- Personality traits (extravert vs introvert, emotional vs calm)

When you detect a signal:
1. Call `update_profile` with the facet value and low confidence (0.2-0.3)
2. The confidence merge algorithm handles accumulation over time
3. If a drift warning is returned, confirm with the user at a natural point

## Explicit Requests

- "Create my profile" → Call `create_profile` with inferred facets
- "Show my personality" → Call `get_profile` and display the SOUL.md
- "Update my profile" → Call `update_profile` with user-specified values (confidence: 1.0)

3. Add a references/facet-guide.md with the 12 facets for the agent to reference:

# Facet Guide

| # | Facet | A | B |
|---|---|---|---|
| 1 | Communication | Assertive | Harmonious |
| 2 | Expression | Direct | Indirect |
| 3 | Role | Leader | Follower |
| 4 | Work-Life | Work-Focused | Life-Balance |
| 5 | Risk | Risk-Taking | Risk-Avoidance |
| 6 | Judgment | Empathetic | Logical |
| 7 | Thinking | Abstract | Concrete |
| 8 | Energy | Extravert | Introvert |
| 9 | Emotion | Emotional | Calm |
| 10 | Openness | Open | Traditional |
| 11 | Collaboration | Team | Solo |
| 12 | Planning | Planned | Flexible |

How Progressive Profile Works

Session 1: User says "I prefer working alone"
  → Agent detects Solo signal → update_profile(facet_11: "b", confidence: 0.3)

Session 3: User says "I like to plan everything in advance"
  → Agent detects Planned signal → update_profile(facet_12: "a", confidence: 0.25)

Session 5: User mentions preferring solo work again
  → Confidence merge: 0.3 + 0.25 → 0.475 (approaching confirmed)

Over time: Profile grows without user ever explicitly asking for it.

MCP Tools

Tool	Description
create_profile	Create a new profile (only name is required)
update_profile	Update facets/demographics with confidence merge and drift detection
get_or_create_profile	Get by external_id, or create if not found (for bots)
get_profile	Get profile data + SOUL.md + IDENTITY.md
list_profiles	List all local profiles with completeness info
delete_profile	Delete a profile

Note on soul_md / identity_md: These are auto-generated from facets + demographics if omitted (recommended for most use cases). Provide them only when you want to use a custom template generated by the AI agent itself.

MCP Resources

URI	Description
op://profiles/{id}	Profile structured JSON
op://profiles/{id}/soul	SOUL.md text
op://profiles/{id}/identity	IDENTITY.md text

MCP Prompts

Prompt	Description
onboarding	Guides the AI through creating a user's first profile
personalized_advice	Generates advice tailored to the user's personality

Output Example

SOUL.md

# Soul

## Core Truths
- Lead with conviction, deliver with care
- Plan first, explore within structure
- Think with data, connect with people

## Boundaries
- Words are chosen carefully, even in disagreement
- Decisions require data — intuition alone is not enough
- Risks are calculated, never reckless

## Vibe
Warm and polite tone. Uses "watashi" as first person. Firm opinions
delivered in soft packaging. Analytical mind with genuine enjoyment
of human connection.

## Facet Profile
| Facet | Value |
|---|---|
| Assertive ↔ Harmonious | Assertive |
| Direct ↔ Indirect | ~Indirect |
| Leader ↔ Follower | Leader |
| Work-Focused ↔ Life-Balance | Life-Balance |
| ... | ... |

Data Storage

All data is stored locally:

~/.openpersonality/
├── config.json
└── profiles/{id}/
    ├── profile.json    # Structured data (source of truth)
    ├── SOUL.md         # Generated personality document
    └── IDENTITY.md     # Generated identity document

No data is sent to external servers. Directory permissions are set to 0700 (owner-only).

Platform Compatibility

Platform	Transport	Autonomous Updates
Claude Desktop / Claude Code	MCP (stdio)	Autonomous tool calling
Cursor / Windsurf / Cline	MCP (stdio)	Agent Mode
VS Code / GitHub Copilot	MCP (stdio)	Agent Mode
Gemini CLI	MCP (stdio)	Auto tool calling
OpenAI Agents SDK	MCP (stdio)	Agent loop
OpenClaw	MCP + Skill	Skill auto-invocation
ChatGPT	MCP (Streamable HTTP)	Planned

Development

pnpm install    # Install dependencies
pnpm build      # Build all packages
pnpm typecheck  # Type check
pnpm test       # Run tests
pnpm clean      # Clean build artifacts

Privacy

• All profile data stays on your machine (~/.openpersonality/)
• The MCP server makes zero external API calls
• No API key required — facet estimation is done by your AI agent's own LLM
• Demographics may contain personal information — profiles are stored with owner-only permissions

License

MIT