PersonaMCP

PersonaMCP

Your communication style and memory for AI agents.

PersonaMCP imports your conversation exports, measures how you write, and gives an AI agent a compact style profile plus relevant incoming-message/reply examples. Your raw history stays on your computer. There is no model training, web dashboard, cloud embedding requirement, telemetry, or automatic reply generation.

Writing preferences are usually too vague: “sound casual” does not capture someone who uses lowercase, sends three short messages, switches languages, or writes differently to a colleague. PersonaMCP gives the connected writer evidence instead of a guessed personality.

Install

Python 3.11 or newer. Install from PyPI:

python -m pip install personamcp

persona --help

Or run it without installing, using uv: uvx personamcp --help.

To work from a checkout of this repository:

git clone https://github.com/robyroro/PersonaMCP.git

cd PersonaMCP uv sync --locked uv run persona --help

Or install into your own virtual environment:

python -m venv .venv

Linux/macOS: source .venv/bin/activate

Windows PowerShell: .venv\Scripts\Activate.ps1

python -m pip install . persona --help

In a uv checkout, prefix the persona commands below with uv run. With an activated pip installation, run persona directly.

The base installation supports import, analysis, FTS search, lexical interaction retrieval, and MCP. Semantic retrieval is an optional, fully local extra:

After initialization and imports (described below):

uv sync --locked --extra semantic

uv run persona model prepare uv run persona index

With pip, use python -m pip install '.[semantic]'. Preparing the model explicitly downloads weights from Hugging Face and pins their immutable revision. It does not read or send chats. Indexing and subsequent queries load only local files with remote code disabled.

Quick start

persona init

persona config set-name "Robert" persona config add-alias "roby" persona config set-name "Exact Instagram display name" --platform instagram persona config set-name "snapchat_username" --platform snapchat

persona import instagram ./instagram-export/ persona import snapchat ./snapchat-export/ persona import whatsapp ./chat.txt persona import json ./messages.json

persona stats persona analyze persona search "cat costa" persona similar "mai vii azi?" --person "David" persona writing-context "ce faci diseara?" --person "David" --platform instagram

For a synthetic first run, use a separate data directory:

persona --home ./sample-persona init

persona --home ./sample-persona config set-name "Owner" persona --home ./sample-persona import json ./examples/messages.json persona --home ./sample-persona analyze persona --home ./sample-persona writing-context "mai vii azi la cafea?" --person "Alex"

Put private imports and custom data directories outside your repository. The included .gitignore covers conventional private folders but cannot protect every arbitrarily named path.

Identity must match an exact exported sender name or sender ID. Platform aliases override global names on that platform. No participant is guessed from message volume. An import matching no owner messages fails before writing anything. Changing names/aliases recomputes ownership and interactions and invalidates profiles/vectors; run analyze and index again.

Supported imports

Only chat files are imported. Media is not opened, transcribed, downloaded, or analyzed. Unsupported variants fail clearly. A malformed file rolls back the import as a whole. Original files stay untouched. Content hashes and stable message IDs prevent repeated imports from duplicating rows.

WhatsApp has no stable export thread ID. By default the filename identifies the conversation; use --conversation-id "stable-chat-name" when importing renamed or refreshed exports. Offsetless timestamps use a documented UTC convention for wall-clock ordering; they are not claimed to have been recorded in UTC. Instagram/Snapchat HTML support English export dates.

Generic JSON:

{

"id": "stable-conversation-id", "platform": "json", "title": "Alex", "participants": ["Owner", "Alex"], "context": "casual", "messages": [ {"id": "external-message-id", "sender": "Alex", "sender_id": "account-123", "text": "mai vii azi?", "timestamp": "2024-01-01T10:00:00Z"}, {"sender": "Owner", "text": "da gen vin acu", "timestamp": "2024-01-01T10:00:10Z"} ] }

For JSONL, each line is a message with sender, text, timestamp, and an optional conversation_id. Optional external IDs and reply_to are preserved. Generic identity comes from configured aliases, never an imported is_user assertion. Use explicit conversation IDs when importing different datasets; absent IDs use a documented default conversation.

What is measured

persona analyze writes persona.md and persona-profile.json in the private data directory and stores structured profiles in SQLite. Only outgoing text feeds the analyzer. Incoming text is kept as bounded retrieval context.

Measurements include character/word/sentence lengths, short message bursts, casing, punctuation, emoji codepoints, repeated characters, common words and phrases, repeated slang/abbreviation forms, greetings, sign-offs, Romanian diacritics, and Romanian/English word markers. Language markers are heuristics, not a language classifier. Emoji counts measure codepoints, not complete grapheme clusters. Repeated phrases/forms need at least three observations; isolated misspellings are not instructions to add typos.

Context labels are explicit and extensible:

persona conversations

persona set-context CONVERSATION_ID business persona set-context OTHER_ID casual persona analyze persona person "David"

Global profiles always use available outgoing text. Separate context/person profiles require at least 20 messages by default. On-demand person statistics report their evidence count. No family, dating, personality, sarcasm, or psychological classification is inferred. Recipient-specific queries conservatively exclude groups. Exact names may occur on multiple platforms; pass a platform to retrieval/writing-context when that distinction matters.

Search and semantic retrieval

SQLite FTS5 searches outgoing messages and incoming interaction contexts. Interactions retain up to three incoming messages and a burst of up to eight outgoing replies. A two-hour gap or a media record breaks pairing; an outgoing burst spans at most five minutes between messages.

The local semantic provider uses sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2. It embeds incoming contexts and stores float32 vectors in SQLite. Queries use exact cosine scans over eligible vectors; this favors a simple local architecture over an external vector server. Indexes resume after interruption. A recipient/context/platform filter applies before ranking.

If eligible vectors are absent, retrieval reports lexical explicitly. A partially built index reports its coverage. Semantic scores below 0.25 are omitted; these scores are not probabilities or guarantees of relevance. There is no silent cross-recipient fallback. Future providers can implement the EmbeddingProvider protocol without changing the import or writing interfaces.

MCP setup

The server uses the official Python MCP SDK and stdio transport. Stdout carries only protocol messages; diagnostic output goes to stderr.

persona serve

If the data directory has not been initialized yet, serve creates it the same way persona init does and reports this on stderr; tools return empty results until you import exports. Usually the client launches this command for you. Use absolute paths because the client's working directory can differ from your terminal's. Example configuration for clients accepting the common mcpServers structure:

{

"mcpServers": { "personamcp": { "command": "/absolute/path/to/venv/bin/persona", "args": ["--home", "/absolute/path/to/private/persona-data", "serve"] } } }

With uv installed, the client can run the published package directly:

{

"mcpServers": { "personamcp": { "command": "uvx", "args": ["personamcp", "--home", "/absolute/path/to/private/persona-data", "serve"] } } }

On Windows the command is C:\\absolute\\path\\.venv\\Scripts\\persona.exe. For Codex:

codex mcp add personamcp -- /absolute/path/to/venv/bin/persona --home /absolute/path/to/private/persona-data serve

codex mcp list

See Codex MCP setup. Other clients may use different configuration locations but need the same executable and arguments. Hosted clients that only support remote HTTP MCP cannot directly launch this local stdio server. PersonaMCP does not include a tunnel/HTTP bridge; exposing sensitive local data remotely requires a separate, explicit deployment decision.

With a prepared semantic model, allow up to 90 seconds for startup and 120 seconds for tools on slower machines. The native numerical runtime is loaded before stdio reader threads start to avoid Windows BLAS loader deadlocks. Weights are loaded on the first semantic query and cached. For Codex these settings belong in the server's configuration table:

[mcp_servers.personamcp]

command = "/absolute/path/to/venv/bin/persona" args = ["--home", "/absolute/path/to/private/persona-data", "serve"] startup_timeout_sec = 90 tool_timeout_sec = 120

Tools:

Historical content is returned inside historical_quote, with an explicit untrusted-data notice. Tools supply evidence. Your agent generates the final reply and remains responsible for treating historical instructions as data and for deciding what to send to its model provider.

Skill setup

The reusable skill is skills/write-like-me/SKILL.md. It is also included in the wheel; persona skill-path prints its installed location. Copy its folder to the skill directory your agent discovers. For current Codex repository discovery:

mkdir -p .agents/skills

cp -R skills/write-like-me .agents/skills/

Windows PowerShell: New-Item -ItemType Directory -Force .agents/skills followed by Copy-Item -Recurse skills/write-like-me .agents/skills/. See Codex skill discovery.

Then ask the connected agent to