内容
# 风格记忆微服务
[English](README.md) | [简体中文](README.zh-CN.md)
一个轻量级的本地MCP服务器，学习用户的对话风格、口头禅、方言标记、表情符号习惯、语气偏好和具体合作偏好，而不存储私人记忆。
它的目的是记住某人说话的“味道”，而不是他们生活的私人事实。
## 为什么
大多数代理记忆工具都记住事实：
- “用户住在...”
- “用户从事...”
- “用户更喜欢...”
`style-memory-mcp` 记得的是语调：
- “用户通常说‘lol’或‘哈哈哈’。”
- “用户喜欢温暖、活泼的回复。”
- “用户有时会使用四川口语，如‘锤子’或‘巴适’。”
- “用户使用类似（｡･ω･｡）的颜文字。”
小事，大氛围。（｡･ω･｡）ﾉ
## 功能
- 仅限本地JSON存储 — 您的数据保留在您的机器上
- 无云服务，无遥测，无外部API调用
- **MCP服务器本身从不调用LLM。** 字典路径是纯粹的正则表达式。您可以**可选地**让宿主代理通过`hints`转发其自己的观察结果 — 请参见下面的[LLM辅助学习](#llm-assisted-learning)。
- 无完整对话日志存储 — 仅存储风格信号（每个习惯的短示例，长度≤60字符，存储前会进行清理）
- 先学习候选项，再推广重复的习惯
- 推广现在还需要习惯在**≥2个不同的上下文标签**下出现（跨上下文检查，灵感来自nuwa-skill）
- 自动清理过时的习惯（候选项 → 存档 → 删除）
- 支持中文、英文、表情符号、颜文字和方言标记 — 以及主机LLM注意到的任意`idiolect`
- 内置词典涵盖四川、粤语、东北（东 北）、上海话和闽南/台语标记，以及当前的（2024-2026）中英文网络流行语。按地域标签，智能体可以区分通用安全短语和必须避免在法律/医疗/严肃回复中使用的俚语。
- 返回可操作的风格简介：如何应用风格，然后是上下文相关的习惯
- 支持`interaction profile`：用户更喜欢智能体如何合作，无需个性标签
- 交互配置文件偏好可以像风格习惯一样被审查、固定或遗忘
- 包括一个轻量级的`get_style_memory_score`健康检查，用于准备就绪、漂移风险、过度模仿风险和简短的刷新建议
- 与任何支持MCP的智能体配合使用
- 固定习惯以保护它们免受自动清理
- 随时使用`set_learning_enabled`暂停学习
## 安装
### 本地安装
```bash
git clone https://github.com/hexingyuofficial/style-memory-mcp.git
cd style-memory-mcp
npm install
npm run build
```
### 全局安装（可选）
```bash
npm install -g style-memory-mcp
# 然后使用：style-memory-mcp
```
对于本地开发：
```bash
npm run dev
```
## MCP客户端配置
将以下内容添加到您的MCP客户端配置中（例如Claude Desktop、Cursor等）：
```json
{
"mcpServers": {
"style-memory": {
"command": "node",
"args": ["/绝对路径/to/style-memory-mcp/dist/server.js"]
}
}
}
```
您可以自定义JSON存储位置：
```json
{
"mcpServers": {
"style-memory": {
"command": "node",
"args": ["/绝对路径/to/style-memory-mcp/dist/server.js"],
"env": {
"STYLE_MEMORY_PATH": "/绝对路径/to/style-memory.json"
}
}
}
}
```
参见[docs/INTEGRATION.zh-CN.md](docs/INTEGRATION.zh-CN.md)以获取实用的中文集成指南，包括类似Doubao的设置说明和推荐的自动简介刷新协议。
### 环境变量
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `STYLE_MEMORY_PATH` | `~/.style-memory-mcp/style-memory.json` | JSON存储路径 |
| `STYLE_MEMORY_MIN_PROMOTE_COUNT` | `3` | 习惯在成为活跃之前必须被看到的次数 |
| `STYLE_MEMORY_CANDIDATE_TTL_DAYS` | `30` | 未使用的候选习惯被删除前的天数 |
| `STYLE_MEMORY_INACTIVE_TTL_DAYS` | `180` | 活跃习惯被存档前的天数 |
| `STYLE_MEMORY_MAX_BRIEF_ITEMS` | `8` | 风格简介中返回的最大习惯数 |
| `STYLE_MEMORY_MAX_EXAMPLE_LEN` | `60` | 存储的用法示例的最大字符数 |
| `STYLE_MEMORY_LEARNING` | `on` | 设置为`off`以禁用学习 |
## 工具
### `observe_user_message`
从最新的用户消息中学习轻量级的风格信号。
代理应在用户消息后调用此函数，但**不应**发送秘密、私人记忆转储或完整的聊天日志。
可以可选地包含一个`hints`数组 — 请参见下面的[LLM辅助学习](#llm-assisted-learning) — 和一个`profileHints`数组，用于具体的合作偏好。
### `get_style_brief`
返回一个简短的风格简介，供代理轻量使用。
代理应在对话开始时或在起草友好回复之前调用此函数。
### `distill_recent_style`
批处理，用户认可的种子。主机LLM提交3-8个从最近消息中提取的高置信度观察结果。每个习惯立即成为`active`。适用于热启动一个全新的存储，或当用户明确要求代理“真正学习我如何说话”。
### `distill_interaction_profile`
批处理，用户认可的种子，用于具体的合作偏好，例如“更喜欢价值判断，然后是步骤”或“喜欢计划→实施→验证用于技术工作”。不要提交人格标签，心理状态，诊断或私人事实。
### `list_style_habits`
列出候选项，活跃习惯和存档习惯。
### `list_interaction_profile`
列出存储的合作和响应结构偏好。
### `review_style_habits`
返回一个简短的审查队列，包含建议的操作：`keep`，`pin`，`forget`或`observe`。当用户想要检查MCP学习的内容时很有用。
### `review_interaction_profile`
返回一个简短的审查队列，用于合作偏好，包含建议的操作：`keep`，`pin`，`forget`或`observe`。
### `forget_style_habit`
通过ID或确切文本删除习惯。
### `forget_interaction_preference`
通过ID或确切文本删除合作偏好。
### `pin_style_habit`
固定习惯以防止自动清理删除它。
### `pin_interaction_preference`
固定合作偏好以防止自动清理删除它。
### `set_learning_enabled`
打开或关闭学习。
### `get_style_memory_score`
评估本地风格记忆是否可用和稳定。返回准备就绪、稳定性、新鲜度、漂移风险、过度模仿风险、`get_style_brief`是否应刷新以及简短的建议。
### `get_style_memory_status`
显示JSON路径和习惯计数。
## 代理指令
在您的代理或技能中添加类似的内容：
```text
仅将style-memory-mcp用于轻量级对话风格。
在对话开始时，调用get_style_brief。
在每个用户消息后，使用最新的用户消息调用observe_user_message。
在长聊天中，静默调用get_style_brief，每12-20个用户回合，
在重大上下文切换后，在重要答案之前，或当用户说
类似“感觉飘了”或“重新对齐一下”的话时。
如果您发现内置词典可能无法捕捉到的个人习惯
（例如，自创的句末助词，不常见的结构奇特之处），
请将其作为hints[]条目添加到同一个observe_user_message调用中。
三个不同上下文中的重复需要两个不同的上下文标签，
习惯才会稳定，因此您不必在第一次尝试时就正确。
不要发送秘密、私人记忆、文件或完整的对话日志。
轻度使用返回的风格提示。塑造助理自己的稳定
合作风格；永远不要机械地复制用户。
```
更长的模板位于`examples/agent-instruction.md`。
## 交互配置文件
`style-memory-mcp`不建立人格配置文件。它可以学习具体、行为性的合作偏好，这些偏好更安全、更有用：
- “用户更喜欢结论在细节之前。”
- “对于技术工作，用户喜欢计划→实施→验证。”
- “用户更喜欢价值判断，然后是分步指令。”
- “用户不喜欢模糊的赞扬，想要具体的建议。”
不要存储：
- “用户焦虑。”
- “用户是内向的。”
- 心理标签、诊断或人格类型。
- 现实身份、地址、工作或其他私人事实。
主机代理可以在`observe_user_message`上提交`profileHints`：
```jsonc
{
"text": "首先告诉我这是否值得做，然后给出步骤。",
"context": "planning",
"profileHints": [
{
"category": "response_structure",
"text": "更喜欢价值判断，然后是逐步实施",
"example": "首先告诉我这是否值得做，然后给出步骤。",
"useWhen": ["planning", "technical_chat"],
"confidence": 0.7
}
]
}
```
对于一次性种子，请使用`distill_interaction_profile`，包含1-8个高置信度的偏好。活跃的配置文件偏好在`get_style_brief`中与风格习惯一起显示，但简介保持简短并根据上下文过滤。
如果配置文件偏好不正确，请使用`forget_interaction_preference`。如果它很重要，应该在清理后保留，请使用`pin_interaction_preference`。使用`review_interaction_profile`获取简短的修正队列。
## 漂移和刷新
MCP服务器本身无法将上下文推入主机代理。主机代理应刷新其对齐简介：
- 在新聊天开始时，
- 在长聊天中每12-20个用户回合，
- 在重大话题或上下文切换后，
- 在长或重要答案之前，
- 当用户说“感觉飘了”，“重新对齐一下”，“不像我”或类似的话时。
对于快速健康检查，调用`get_style_memory_score`。如果`briefRefreshRecommended`为`true`，请在下一个重要回复之前调用`get_style_brief`。
## 只读重用和重启
MCP进程通常由主机代理启动和重启。`style-memory-mcp`不需要自行重启。持久的部分是JSON存储：如果多个对话使用相同的`STYLE_MEMORY_PATH`，它们在重启后会读取相同的风格记忆。
如果存储已经学到了足够多的内容，您希望它在不继续学习的情况下指导风格，请使用此模式：
1. 保持相同的`STYLE_MEMORY_PATH`。
2. 在新对话开始时调用`get_style_brief`。
3. 调用`set_learning_enabled(false)`或设置`STYLE_MEMORY_LEARNING=off`。
4. 仅在需要刷新样式时再打开学习。
这为您提供了持久的样式延续，而无需在每个消息上编写新的习惯。
## LLM辅助学习
词典路径只知道硬编码的内容（四川方言、常见的中英文口头禅、颜文字等）。它会错过作者没想到的事情 — 包括使某人听起来像他们自己的**个人**习惯。
`style-memory-mcp`在不依赖LLM的情况下解决了这个问题：**主机代理已经读取每个用户消息以生成其回复，因此让它传递它注意到的任何内容。** MCP服务器仍然是一个薄的“计数器+生命周期+安全”层位于本地JSON之上。无需API密钥。无需网络。无需模型注册。零额外成本。
```jsonc
// observe_user_message 输入
{
"text": "今天天气好巴适莫",
"context": "casual_chat",
"hints": [
{
"kind": "sentence_final_particle",
"text": "莫",
"example": "今天天气好巴适莫",
"confidence": 0.6
}
]
}
```
在两个不同的`context`标签中观察三次后，`莫`被提升为`active`，并出现在未来的`get_style_brief`调用中，示例包括在内。高置信度的提示（≥ ~0.71）跳过跨上下文门槛。
对于批处理，用户认可的种子，请调用`distill_recent_style`一次，包含3-8个从最近消息中提取的观察结果。
安全防护措施使此功能安全：
- MCP服务器本身从不调用LLM — 它只是记录主机报告的内容。“无网络”仍然成立。
- 具有不良`kind`或空`text`的提示会被丢弃，不会学习。
- 示例会被清理（`sanitizeExample`）：空格折叠、长度上限、敏感内容（凭证/令牌）被静默丢弃。
- 三次打击+跨上下文推广规则保留单个幻觉提示不会污染活跃习惯集。
- 所有现有的控件（`forget_style_habit`、`pin_style_habit`、`set_learning_enabled`）保持不变。
## 清理规则
服务器不需要后台守护进程。清理发生在MCP启动和调用工具时。
默认行为：
- 候选习惯在30天不活动后消失。
- 活跃习惯在180天不活动后存档。
- 存档习惯在另外180天不活动后删除。
- 固定的习惯永远不会自动删除。
重要：只有当用户再次说出某个习惯时，该习惯才会被刷新。代理的使用不会使其保持活跃，因此系统不会陷入自我模仿的循环。
## 示例JSON
```json
{
"id": "zh-cn-sichuan-dialect_marker-锤子",
"kind": "dialect_marker",
"text": "锤子",
"locale": "zh-CN-sichuan",
"confidence": 0.64,
"seenCount": 4,
"status": "active",
"pinned": false,
"useWhen": ["casual_chat", "joking", "warm_chat"],
"avoidWhen": ["serious_debugging", "legal", "medical", "user_upset"]
}
```
## 开发
```bash
# 安装依赖
npm install
# 类型检查
npm run check
# 构建
npm run build
# 运行测试
npm test
# 开发模式（使用tsx自动重载）
npm run dev
```
## 词典大小和令牌成本
内置词典（方言标记、口头禅、网络俚语）位于`src/extract.ts`中，**永远**不会发送到LLM。它只参与本地`text.includes()`/正则表达式扫描。增加词典的成本为每个回合增加零令牌。
唯一达到主机LLM的负载是：
1. `get_style_brief`输出 — 受`STYLE_MEMORY_MAX_BRIEF_ITEMS`限制（默认为8）。简介仅显示**用户实际表现出的、被提升为活跃的习惯**，而是词典中存在的任何内容。
2. 工具描述 — 固定在`server.ts`中，与词典大小无关。
因此，如果您的方言或俚语未被覆盖，请提交一个PR添加新条目 — 它只会提高召回率，不会增加任何人的提示负担。
## 隐私
该项目故意对数据保持谨慎：
- 它存储风格信号，而不是原始消息。
- 它避免从明显的秘密上下文中学习（类似凭证的模式被过滤）。
- 它保留自己的JSON存储，独立于任何用户内存数据库。
- 用户可以随时列出、忘记、固定或禁用学习。
- 无网络调用。所有操作都在本地运行。
## 贡献
欢迎贡献！尤其是：
- 新的方言标记（粤语、上海话、东北话等）
- 任何语言的新口头禅模式
- 更好的敏感度检测启发式
- 性能改进
请为新的提取规则添加测试。参见`src/extract.test.ts`中的示例。
## 许可证
MIT
