PersonaMCP

PersonaMCP

为 AI Agent 提供沟通风格和记忆。

PersonaMCP 会导入你的对话导出数据，分析你的写作风格，并为 AI Agent 提供精简的风格档案，以及相关的收到的消息／回复示例。你的原始历史记录始终保留在自己的电脑上。它不训练模型、不提供 Web 控制面板、不要求云端嵌入、不进行遥测，也不会自动生成回复。

写作偏好通常过于模糊：“语气随意些”无法体现一个人习惯使用小写字母、连续发送三条短消息、切换语言，或面对同事时写作方式不同。PersonaMCP 会为接入的写作者提供依据，而不是猜测其个性。

安装

需要 Python 3.11 或更高版本。从 PyPI 安装：

python -m pip install personamcp
persona --help

也可以使用 uv 运行，无需安装：uvx personamcp --help。

若要从此代码库的本地检出版本运行：

git clone https://github.com/robyroro/PersonaMCP.git
cd PersonaMCP
uv sync --locked
uv run persona --help

也可以安装到自己的虚拟环境中：

python -m venv .venv
# Linux/macOS: source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install .
persona --help

在 uv 检出版本中，以下 persona 命令前需加上 uv run。如果已激活 pip 安装的环境，则可直接运行 persona。

基础安装支持导入、分析、FTS 搜索、词汇交互检索和 MCP。语义检索是完全在本地运行的可选扩展：

完成初始化和导入后（如下所述）：

uv sync --locked --extra semantic
uv run persona model prepare
uv run persona index

使用 pip 时，运行 python -m pip install '.[semantic]'。显式准备模型时，会从 Hugging Face 下载权重并固定到其不可变版本。此过程不会读取或发送聊天记录。索引编制和后续查询只会加载本地文件，并禁用远程代码。

快速开始

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

若要进行首次合成运行，请使用单独的数据目录：

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"

请将私有导入数据和自定义数据目录放在代码库之外。附带的 .gitignore 会涵盖常见的私有文件夹，但无法保护所有名称任意的路径。

身份必须与导出内容中的发送者名称或发送者 ID 完全匹配。在某个平台上，平台别名优先于全局名称。系统不会根据消息数量猜测参与者。如果导入内容中没有匹配的所有者消息，会在写入任何内容前失败。更改名称／别名后，系统会重新计算所有权和交互，并使档案／向量失效；请再次运行 analyze 和 index。

支持的导入格式

平台	支持的输入	说明
Instagram	message_N.json 或当前 Meta 的 message_N.html 文件夹	会合并分页内容。会修复常见的损坏 JSON Unicode。绝不会执行 HTML 脚本、链接或媒体。
Snapchat	chat_history.json、支持的聊天卡片 HTML 子页面或原始 ZIP 导出文件	支持以接收者为键的直接布局和嵌套 JSON 布局。读取 ZIP 时无需解压；遇到重复 HTML 时优先使用 JSON。
WhatsApp	UTF-8 TXT、Android 和带方括号的 iOS 时间戳	日期以斜杠分隔；默认按日/月解析，美国格式的导出文件使用 --month-first。保留多行文本；系统和媒体通知不会纳入风格分析。
Generic	JSON 对话对象、conversations 对象、消息数组或 JSONL	参见下方的架构。

仅导入聊天文件。不会打开、转录、下载或分析媒体。遇到不支持的格式变体时会明确报错。文件格式错误会导致整个导入回滚。原始文件不会更改。内容哈希和稳定的消息 ID 可防止重复导入时产生重复记录。

WhatsApp 没有稳定的导出会话 ID。默认情况下，文件名用于标识对话；导入已重命名或更新的导出文件时，请使用 --conversation-id "stable-chat-name"。 不带时区偏移的时间戳遵循有据可查的 UTC 约定，以便按墙上时钟顺序排序；但这并不表示这些时间戳是在 UTC 时区记录的。Instagram/Snapchat HTML 支持英语导出日期。

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"}
  ]
}

对于 JSONL，每一行都是一条消息，包含 sender、text、timestamp 和可选的 conversation_id。可选的外部 ID 和 reply_to 会予以保留。Generic 身份信息来自已配置的别名，而不是导入的 is_user 声明。导入不同数据集时，请使用明确的对话 ID；未提供 ID 时，会使用有据可查的 default 对话。

测量内容

persona analyze 会在私有数据目录中写入 persona.md 和 persona-profile.json，并将结构化档案存储在 SQLite 中。只有发出的文本会用于分析器。收到的文本会作为有界检索上下文保留。

测量内容包括字符/单词/句子的长度、短消息突发、大小写、标点、emoji 码点、重复字符、常用单词和短语、重复俚语/缩写形式、问候语、结束语、罗马尼亚语变音符号，以及罗马尼亚语/英语单词标记。 语言标记是启发式规则，并非语言分类器。emoji 计数统计的是码点，而不是完整的字素簇。重复短语/形式至少需要出现三次；不会将孤立的拼写错误视为需要添加错别字的指示。

上下文标签明确且可扩展：

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

全局档案始终使用可用的发出文本。单独的上下文/人物档案默认至少需要 20 条消息。按需生成的人物统计会报告证据数量。系统不会推断家庭关系、约会关系、人格、讽刺或心理分类。确切姓名可能出现在多个平台上；在这种区别很重要时，请在检索/写作上下文中传入平台。

搜索与语义检索

SQLite FTS5 会搜索发出的消息和收到的交互上下文。每次交互最多保留三条收到的消息，以及一组最多包含八条发出回复的消息。间隔两小时或出现媒体记录时会中断配对；一组发出消息中相邻消息的间隔最多为五分钟。

本地语义提供程序使用 sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2。 它会为收到的上下文生成嵌入，并将 float32 向量存储在 SQLite 中。查询会对符合条件的向量进行精确余弦扫描；这种方式优先采用简单的本地架构，而非外部向量服务。索引会在中断后恢复。排序前会应用收件人／上下文／平台筛选条件。

如果没有符合条件的向量，检索结果会明确报告为 lexical。如果索引仅部分构建，则会报告其覆盖范围。低于 0.25 的语义分数会被省略；这些分数并非概率，也不能保证相关性。不会静默回退到其他收件人的数据。未来的提供程序可实现 EmbeddingProvider 协议，而无需更改导入或写入接口。

MCP 设置

服务器使用官方 Python MCP SDK 和 stdio 传输。标准输出仅承载协议消息；诊断输出会发送到标准错误。

persona serve

如果数据目录尚未初始化，serve 会像 persona init 一样创建该目录，并在标准错误中报告此操作；导入数据导出文件前，工具会返回空结果。通常由客户端为你启动此命令。请使用绝对路径，因为客户端的工作目录可能与终端不同。以下是接受常见 mcpServers 结构的客户端配置示例：

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

安装 uv 后，客户端可以直接运行已发布的软件包：

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

在 Windows 上，命令为 C:\\absolute\\path\\.venv\\Scripts\\persona.exe。Codex 配置示例：

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

请参阅 Codex MCP 设置。其他客户端可能使用不同的配置位置，但所需的可执行文件和参数相同。仅支持远程 HTTP MCP 的托管客户端无法直接启动此本地 stdio 服务器。PersonaMCP 不包含隧道／HTTP 桥接；要远程公开敏感的本地数据，需要单独作出明确的部署决策。

如果语义模型已准备就绪，在较慢的机器上，启动最多可能需要 90 秒，工具最多可能需要 120 秒。为避免 Windows BLAS 加载器死锁，会在启动 stdio 读取器线程前加载原生数值运行时。权重会在首次语义查询时加载并缓存。对于 Codex，这些设置应放在服务器的配置表中：

[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

工具：

工具	结果
get_style_profile(context?)	全局或指定上下文的风格测量档案
get_person_style(person)	精确匹配指定人员的沟通统计信息和证据数量
search_messages(query, person?, platform?, limit?)	数量受限的发出文本匹配结果
find_similar_interactions(message, person?, context?, platform?, limit?)	相似的真实收到／回复消息对
get_writing_context(message, person?, context?, platform?)	合适的风格及最多三条引用示例
get_persona_summary()	精简档案和数据库统计信息

历史内容会放在 historical_quote 中返回，并附有明确的非可信数据提示。 工具提供证据。你的 Agent 负责生成最终回复，并负责将历史指令视为数据，以及决定向其模型提供商发送哪些内容。

技能设置

可复用技能位于 skills/write-like-me/SKILL.md。它也包含在 wheel 中；persona skill-path 会打印其安装位置。将其文件夹复制到 Agent 可发现的技能目录中。对于当前的 Codex 仓库发现：

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

Windows PowerShell：先运行 New-Item -ItemType Directory -Force .agents/skills，再运行 Copy-Item -Recurse skills/write-like-me .agents/skills/。请参阅 Codex 技能发现。

然后让已连接的 Agent 使用 write-like-me，例如：

像我一样给 Alex 写一条简短回复，内容是“mai vii azi la cafea?”。使用 PersonaMCP 证据。

该技能会保留受支持的大小写、拼写、词汇和长度，但不会强行制造错别字或照搬旧信息。它也可以通过本地 shell 使用 persona writing-context，或者在 MCP 不可用时使用明确提供的个人资料。安装不会更改任何全局客户端配置。

隐私与数据控制

默认数据目录取自操作系统的应用数据位置。--home /private/path 或 PERSONAMCP_HOME 可指定其他位置。配置是本地的 config.json；数据库使用 SQLite 外键、版本化架构和事务式导入。

persona stats --json
persona export-profile ./my-style.md
persona export-profile ./my-style.json --json
persona delete-person "Name"
persona delete-conversation CONVERSATION_ID
persona reset

删除／重置操作会请求确认；有意用于脚本时可使用 --yes。删除某个人会移除完整对话，包括包含该人员的群组对话，以免保留与其相关的上下文。个人资料、FTS 行和向量会失效／清除，并对 SQLite 执行 vacuum。 reset 还会清除已配置的所有者身份，但会保留已下载的非个人模型资源。原始导出文件和任何已复制的个人资料仍由你掌控，不会被删除。

SQLite 未加密。请使用私有数据目录和磁盘加密。生成的词汇和示例也属于敏感信息。如果你的 Agent 使用外部大模型，工具结果可能会传给该服务提供商；“本地优先”描述的是存储和计算方式，而非已连接客户端的行为。请阅读 SECURITY.md，了解删除和提示词注入方面的限制。

离线基准测试

persona benchmark --limit 30

按时间戳排序后，最后 20% 的交互构成留出集。检索和风格个人资料仅使用更早的数据。留出集中的实际回复仅用于评分。默认候选内容是检索到的历史回复，不是大模型生成的答案。

报告包含检索覆盖率、回复长度相似度、词汇重合度、标点相似度、大小写相似度，以及它们的平均值——风格相似度评分。 当本地模型可用时，会单独报告嵌入相似度。不会打印基准测试中的原始回复。CandidateResponseProvider 是未来显式配置生成器的扩展点。评分不能证明身份仿真、作者身份、相关性或生成质量。数据集规模较小或时间分布较均匀时，无法支持此项评估。

架构

exports → platform adapters → normalized conversations/messages
                                  ↓
                      SQLite + participants + FTS5
                                  ↓
                   bounded incoming/outgoing interactions
                         ↙                    ↘
              deterministic profiles      local embedding vectors
                         ↘                    ↙
                        retrieval/service layer
                            ↙           ↘
                         CLI          MCP stdio → writing skill → agent

该软件包采用 src/personamcp 布局，包含导入器、模型、配置、存储、分析、嵌入、检索、共享服务、MCP 服务、CLI 和基准测试。无需外部数据库或大模型服务提供商。架构兼容性通过 PRAGMA user_version 跟踪；如果数据库版本较新，较旧版本会拒绝读取，而不会猜测读取方式。

开发、路线图和限制

运行 uv sync --locked，然后依次运行 uv run pytest、uv run ruff check src tests、 uv run ruff format --check src tests 和 uv run mypy src。CI 会在 Windows/Linux 和 Python 3.11–3.13 上进行检查，不使用个人数据，也不下载模型。公开样例数据均为合成数据。请参阅 CONTRIBUTING.md、CODE_OF_CONDUCT.md 和 实现决策。

后续计划包括增加导出适配器（Discord、Telegram、Messenger、iMessage、Signal），制定明确的脱敏规则，为超大型存档提供更快的本地向量索引，丰富语言信号，以及可选的基于生成的评估。这些功能尚未在此 MVP 中实现。

此版本是一个 CLI/MCP 引擎。导出模式可能会变更；群组收件人推断、心理画像分析、自动纠正拼写错误、语音/媒体分析、静态数据加密、云端嵌入服务提供商、HTTP 托管和前端均不在当前支持范围内。

基于 MIT 许可 © Robert Vind-Gardoș (@robyroro)。模型权重和依赖项各自遵循其许可；请参阅 多语言 MiniLM 模型卡 和 Sentence Transformers 文档。