# https://github.com/memorycrystal/memorycrystal 项目说明书

生成时间：2026-06-25 17:19:46 UTC

## 目录

- [项目概述与系统架构](#page-overview)
- [上下文引擎与记忆系统](#page-context-engine)
- [集成与部署](#page-integration-deployment)
- [安全、提示注入防护与运维](#page-security-operations)

<a id='page-overview'></a>

## 项目概述与系统架构

### 相关页面

相关主题：[上下文引擎与记忆系统](#page-context-engine), [集成与部署](#page-integration-deployment), [安全、提示注入防护与运维](#page-security-operations)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/memorycrystal/memorycrystal/blob/main/README.md)
- [plugin/README.md](https://github.com/memorycrystal/memorycrystal/blob/main/plugin/README.md)
- [plugin/package.json](https://github.com/memorycrystal/memorycrystal/blob/main/plugin/package.json)
- [mcp-server/README.md](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/README.md)
- [mcp-server/src/index.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/index.ts)
- [mcp-server/src/tools/import-knowledge.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/tools/import-knowledge.ts)
- [mcp-server/src/lib/obsidian.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/lib/obsidian.ts)
- [package.json](https://github.com/memorycrystal/memorycrystal/blob/main/package.json)
</details>

# 项目概述与系统架构

## 项目定位与目标

Memory Crystal 是一个面向 AI 智能体（AI agent）的持久化记忆中间件，官方定位为"Persistent memory for AI agents"——让每一次会话都被记住、每一项决策可被回溯、每一个新会话都获得历史上下文支持。资料来源：[README.md:1-15]()

项目以 MIT 协议开源，主仓库同时承载自托管（self-hosted）形态与 [memorycrystal.ai](https://memorycrystal.ai) 云端 SaaS 形态两套部署目标。资料来源：[README.md:160-180]() 用户既可 `git clone` 后通过 `npx convex deploy` 与本地 Convex 跑通完整栈，也能直接接入托管 API（`https://convex.memorycrystal.ai`）获得零运维体验。

## 高层系统架构

系统由三块相互解耦的运行时构成：OpenClaw 原生插件、共享 hook 脚本、MCP 协议兼容层。三者共享同一套 Convex 后端与 HTTP/MCP 双协议 API。

```mermaid
flowchart TB
    subgraph Client["客户端运行时"]
        OC[OpenClaw Plugin<br/>plugin/index.js]
        CC[Claude Code / Codex / Factory]
        MCP[MCP Host]
    end

    subgraph Shared["共享层"]
        Hook[plugins/shared/ Hook 脚本]
        McpSrv[mcp-server/<br/>stdio + HTTP 双协议]
    end

    subgraph Backend["Convex 后端"]
        Convex[(Convex Functions<br/>convex/)]
        KB[(Knowledge Bases<br/>+ Convex Storage)]
    end

    OC --> Hook
    CC --> Hook
    MCP --> McpSrv
    Hook --> Convex
    McpSrv --> Convex
    Convex --> KB
```

资料来源：[README.md:95-130]() 插件入口 `plugin/index.js` 负责注册 OpenClaw 生命周期 hook，共享脚本被 Claude Code、Codex、Factory 等外部代理复用，MCP 服务器则把工具以标准 MCP 协议暴露给任意兼容 host。Convex 既提供事务型函数运行时，也托管知识库与多模态资产存储（v0.8.6 引入 Convex Storage 后端支持）。

## 核心组件与职责

| 组件 | 路径 | 职责 |
|---|---|---|
| OpenClaw 插件 | `plugin/index.js` | 注册 hook 与 24 个 MCP 工具，承载会话生命周期 |
| Compaction 模块 | `plugin/compaction/` | 上下文压缩与摘要，跨压缩边界保留记忆 |
| Tools 模块 | `plugin/tools/` | 插件直接注册的工具实现 |
| Store 模块 | `plugin/store/` | 本地 SQLite 备份存储（可选） |
| 共享 hook 脚本 | `plugins/shared/` | 为 Claude Code / Codex / Factory 提供等价 hook |
| MCP 服务器 | `mcp-server/` | stdio + HTTP 双协议兼容层，转发至 Convex |
| Obsidian 导出 | `mcp-server/src/lib/obsidian.ts` | 将记忆以 YAML frontmatter + Markdown 落盘 |

资料来源：[plugin/README.md:1-40]() 与 [plugin/package.json:1-20]() 表明插件以 ESM 模块形式发布，`@memorycrystal/crystal-memory` 作为 npm 包名对外分发，`openclaw.extensions` 字段指向 `index.js` 作为加载入口。`mcp-server` 包则提供 `crystal-mcp` 可执行命令，供 Claude Code、Codex 等通过 stdio 启动。

## 关键能力与运行时契约

### 1. 多类记忆存储

系统区分五大记忆类型（sensory / episodic / semantic / procedural / prospective）与八类记忆类别（decision / lesson / person / rule / event / fact / goal / workflow / conversation），并以 `crystal_remember`、`crystal_recall` 等工具对外暴露 CRUD。资料来源：[mcp-server/README.md:50-75]()

### 2. 知识库一等公民

知识库（Knowledge Base）是不可变、可作用域隔离的参考集合，与会话记忆并列存在。`crystal_create_knowledge_base` / `crystal_import_knowledge` / `crystal_query_knowledge_base` 构成完整生命周期。资料来源：[mcp-server/src/tools/import-knowledge.ts:1-50]() 该工具接受结构化的 `chunks` 数组，并对 `metadata.sourceUrl` 做 `URL` 构造校验，失败时自动剔除该字段以保证导入鲁棒性。

### 3. 安全与多租户

所有 HTTP 端点需 `Authorization: Bearer <api-key>`，API key 在数据库中以 SHA-256 哈希形式存储，明文永不落盘；每次读取都执行 owner 校验，租户隔离在数据库层面强制生效。资料来源：[mcp-server/src/index.ts:20-70]() 服务端还提供 `sanitizeErrorForLog` 与 `redactToolErrorResult` 防止密钥经错误信息泄露，`redactSecrets` 用于在工具输出前对敏感串进行遮蔽。

### 4. Hook 生命周期

OpenClaw 插件订阅 `before_agent_start`、`before_tool_call`、`before_dispatch`、`message_received`、`llm_output`、`message_sending`、`message_sent`、`session_end` 等事件，并在 `before_compaction` / `after_compaction` 时分别执行快照与本地状态刷新，从而让记忆在上下文压缩后仍可被 recall。资料来源：[plugin/README.md:25-55]()

### 5. 观测与诊断

v0.8.8 引入 `crystal_doctor` 工具，可输出 backend / mode / queue / tool-surface / scoping 等可读诊断；v0.8.12 进一步暴露 hook 注册 API、注册名、最近事件、最近解析的 session/channel 与跳过原因；当 hook 已注册但无回调触发时发出告警，便于定位 provider disconnect。资料来源：[README.md:120-150]()

## 部署形态

仓库根目录的 `package.json` 暴露 `convex:dev`、`web:backend:local`、`web:backend:remote`、`test:local`、`test:remote`、`chaos`、`e2e` 等脚本，对应本地开发、远端部署、混沌测试与端到端验证。资料来源：[package.json:1-30]() 本地栈使用 `127.0.0.1:3210`（Convex RPC）、`127.0.0.1:3211`（HTTP actions）、`127.0.0.1:6791`（仪表盘）三个端口；自托管栈则通过 `CONVEX_DEPLOY=prod:your-project-123 npx convex deploy` 与配套 `.env` 切到生产环境。

## 已知风险与社区关注

社区 issue #4 报告 `crystal_recall` 在传入 `channel: '__management__'` 时存在访问控制绕过——普通用户可借此读取管理层 KB 范围。官方建议在服务端对 `MANAGEMENT_CHANNEL_SENTINEL` 走角色校验而非默认放行。资料来源：[README.md:175-195]()（社区上下文）这是当前架构在多租户边界上最受关注的隐患之一，运维侧应在启用 KB recall 时显式禁用该 sentinel 或叠加角色网关。

## See Also

- [plugin/README.md](https://github.com/memorycrystal/memorycrystal/blob/main/plugin/README.md) — OpenClaw 插件 hook 与工具细节
- [mcp-server/README.md](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/README.md) — MCP 工具清单与本地栈说明
- [package.json](https://github.com/memorycrystal/memorycrystal/blob/main/package.json) — 根级脚本与引擎要求

---

<a id='page-context-engine'></a>

## 上下文引擎与记忆系统

### 相关页面

相关主题：[项目概述与系统架构](#page-overview), [安全、提示注入防护与运维](#page-security-operations)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [plugin/README.md](https://github.com/memorycrystal/memorycrystal/blob/main/plugin/README.md)
- [README.md](https://github.com/memorycrystal/memorycrystal/blob/main/README.md)
- [mcp-server/README.md](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/README.md)
- [mcp-server/src/tools/import-knowledge.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/tools/import-knowledge.ts)
- [mcp-server/src/tools/list-knowledge-bases.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/tools/list-knowledge-bases.ts)
- [mcp-server/src/lib/obsidian.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/lib/obsidian.ts)
- [mcp-server/src/index.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/index.ts)
- [package.json](https://github.com/memorycrystal/memorycrystal/blob/main/package.json)
</details>

# 上下文引擎与记忆系统

## 概述

Memory Crystal 的"上下文引擎与记忆系统"是一套面向 AI Agent 的持久化记忆与上下文装配框架。它把对话、决策、流程、人物、知识库等多种信息，按五种记忆存储（sensory / episodic / semantic / procedural / prospective）和九种类别（decision、lesson、person、rule、event、fact、goal、workflow、conversation）分层组织，在 Agent 启动、调用工具、派发请求、压缩上下文等关键生命周期节点自动注入相关记忆，使每个新会话都能复用历史上下文。资料来源：[README.md:context-engine]() 与 [plugin/README.md:hooks]()。

整套系统由三个核心组件协同：OpenClaw 插件负责在 Agent 生命周期中捕获与注入记忆（`plugin/index.js`），MCP 服务器暴露 24 个工具与 HTTP API 给任何 MCP 主机调用（`mcp-server/src/index.ts`），后端 Convex 数据库承担向量与文档的存储与检索。资料来源：[README.md:architecture]()。

```mermaid
flowchart LR
  Agent[AI Agent / MCP Host] -->|hooks / tool calls| Plugin[OpenClaw Plugin]
  Plugin -->|capture / recall| MCP[MCP Server]
  MCP -->|Convex RPC| Convex[(Convex Backend)]
  Convex -->|memories + KB chunks| MCP
  MCP -->|context bundle| Plugin
  Plugin -->|prompt injection| Agent
  Convex -->|embeddings async| Convex
```

## 记忆分层与上下文模式

记忆系统按"存储类型 + 类别"双维度组织。存储层定义记忆的认知阶段：sensory 用于短期观察、episodic 用于事件对话、semantic 用于事实知识、procedural 用于操作流程、prospective 用于目标意图。类别层定义业务语义，二者交叉形成可检索的标签矩阵。资料来源：[mcp-server/README.md:memory-stores]()。

上下文引擎在此之上暴露六种召回模式，由引擎根据当前请求自动选择，无需用户配置：

| 模式 | 召回重点 |
|---|---|
| General | STM + LTM 广度检索 |
| Decision | 决策、教训、规则 |
| Project | 目标、流程、实现上下文 |
| People | 所有权、协作者、关系 |
| Workflow | 程序、规则、操作记忆 |
| Conversation | 最近会话上下文与连续性 |

资料来源：[README.md:context-engine-modes]()。

## 知识库与短期消息处理

知识库（Knowledge Base）是一类**不可变**的参考集合，与对话记忆并行存在，适合放置 runbook、策略、文档与导入资料。其特点包括：导入后内容保持稳定、租户与通道作用域隔离、支持标准导入与高吞吐 bulk-insert、embedding 与图谱回填在后台异步进行。知识库的增删改查通过 `crystal_create_knowledge_base`、`crystal_list_knowledge_bases`、`crystal_import_knowledge`、`crystal_query_knowledge_base` 工具以及对应的 HTTP 端点暴露。资料来源：[README.md:knowledge-bases]() 与 [mcp-server/src/tools/list-knowledge-bases.ts:tool-definition]()。

导入工具会严格校验入参结构：`chunks` 数组中每项必须包含非空 `content` 字符串，`metadata.sourceUrl` 必须是合法 URL，否则会被丢弃 `sourceUrl` 字段后保留其余元数据，避免无效元数据污染向量索引。资料来源：[mcp-server/src/tools/import-knowledge.ts:parseInput]()。

短期消息工具（`crystal_search_messages`、`crystal_recent`、召回匹配项、wake 摘要）在返回结果前会调用 `redactSecrets` 进行敏感信息脱敏；同一条消息只有在当前 turn 结束后才可被检索到，turn 内部不应预期自己刚发出的内容已可见。资料来源：[mcp-server/src/index.ts:redactSecrets]() 与 [mcp-server/README.md:short-term-tools]()。

## 压缩、插件集成与安全

Memory Crystal 拥有 OpenClaw 上下文压缩路径，`before_compaction` 在原始 turn 被压缩前对源对话做快照与 checkpoint，`after_compaction` 刷新本地摘要状态以保证压缩后仍可召回。插件在 Agent 生命周期注册多个 hook：`before_agent_start` 注入精简上下文、`before_tool_call` 提示风险操作、`message_received`/`llm_output` 双向捕获对话。资料来源：[plugin/README.md:compaction]() 与 [plugin/README.md:hooks]()。

记忆与 KB 的导出可走 Obsidian 兼容的 Markdown + YAML frontmatter 格式，frontmatter 包含 valence、arousal、confidence、source、tags、channel、createdAt 等字段，便于本地检索。资料来源：[mcp-server/src/lib/obsidian.ts:frontmatter]()。

API 鉴权采用 Bearer Token 形式，API Key 在存储前以 SHA-256 哈希，明文永不落盘。旧版 `CRYSTAL_API_KEY` 环境变量已被移除，统一使用 `MEMORY_CRYSTAL_API_KEY`，启动时若检测到旧变量会返回升级提示。资料来源：[mcp-server/src/index.ts:legacy-key]()。社区曾报告 `__management__` 通道存在越权风险（Issue #4），建议在调用层面对管理通道做角色校验以保护 KB 可见性边界。资料来源：[community-context:issue-4]()。

本地开发栈的默认端点为：Convex RPC `http://127.0.0.1:3210`、HTTP actions `http://127.0.0.1:3211`、仪表盘 `http://127.0.0.1:6791`，Node 引擎要求 `>=22.13.0`。资料来源：[package.json:engines]() 与 [README.md:local-first]()。

## See Also

- 插件与 Hook 生命周期：[plugin/README.md](https://github.com/memorycrystal/memorycrystal/blob/main/plugin/README.md)
- MCP 工具与 HTTP API：[mcp-server/README.md](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/README.md)
- 知识库导入参考实现：[mcp-server/src/tools/import-knowledge.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/tools/import-knowledge.ts)
- Obsidian 导出格式：[mcp-server/src/lib/obsidian.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/lib/obsidian.ts)

---

<a id='page-integration-deployment'></a>

## 集成与部署

### 相关页面

相关主题：[项目概述与系统架构](#page-overview), [安全、提示注入防护与运维](#page-security-operations)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/memorycrystal/memorycrystal/blob/main/README.md)
- [plugin/README.md](https://github.com/memorycrystal/memorycrystal/blob/main/plugin/README.md)
- [plugin/package.json](https://github.com/memorycrystal/memorycrystal/blob/main/plugin/package.json)
- [mcp-server/README.md](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/README.md)
- [mcp-server/src/index.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/index.ts)
- [mcp-server/src/tools/ideas.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/tools/ideas.ts)
- [mcp-server/src/lib/obsidian.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/lib/obsidian.ts)
- [package.json](https://github.com/memorycrystal/memorycrystal/blob/main/package.json)
</details>

# 集成与部署

## 概述

Memory Crystal 提供多种集成与部署形态，以适配不同的宿主环境与运维诉求。核心目标是让 AI 智能体在任意会话通道中都能获得持久化记忆、跨会话上下文召回以及结构化知识库支持。仓库本身是托管服务 [memorycrystal.ai](https://memorycrystal.ai) 的开源镜像，仓库顶层 `README.md` 顶部明确声明 web 应用与托管服务单独维护，开源部分聚焦本地与自托管栈。

项目暴露三层集成面：

1. **OpenClaw 插件**（[plugin/README.md](https://github.com/memorycrystal/memorycrystal/blob/main/plugin/README.md)）—— 嵌入对话生命周期。
2. **MCP 服务器**（[mcp-server/README.md](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/README.md)）—— 标准协议层，供任意 MCP 宿主调用 24 个记忆工具。
3. **HTTP API**（[README.md](https://github.com/memorycrystal/memorycrystal/blob/main/README.md)）—— 直接面向集成方的 REST 端点。

部署侧则提供云托管、本地优先（local-first）以及完全自托管三档方案，三者共用同一套 Convex 后端与记忆语义。

## OpenClaw 插件集成

OpenClaw 插件是当前主推的集成入口，安装要求为 OpenClaw 2026.6.1 或更新版本（[plugin/README.md](https://github.com/memorycrystal/memorycrystal/blob/main/plugin/README.md)）。官方安装脚本 `curl -fsSL https://memorycrystal.ai/crystal | bash` 在宿主机上写入插件目录与 npm 依赖；手动安装则通过 `rsync` 同步 `plugin/` 目录到 `~/.openclaw/extensions/crystal-memory/` 并执行 `npm install`。

插件以 npm 包 `@memorycrystal/crystal-memory` 形式发布，当前版本 `0.8.15`（[plugin/package.json](https://github.com/memorycrystal/memorycrystal/blob/main/plugin/package.json)）。`files` 字段显式排除了 `*.test.js` 与 `__tests__/**`，确保发布产物只携带运行时代码。

`openclaw.plugin.json` 中的 `configSchema.properties` 定义了配置契约，常见键包括 `apiKey`、`convexUrl`、`defaultRecallMode`、`defaultRecallLimit` 与 `debugRecallOutput`（[plugin/README.md](https://github.com/memorycrystal/memorycrystal/blob/main/plugin/README.md)）。召回模式可选 `general`、`decision`、`project`、`people`、`workflow`、`conversation`，由 Context Engine 自动选择。

插件通过 OpenClaw 生命周期钩子挂入对话，覆盖 `before_agent_start`、`before_tool_call`、`before_dispatch`、`message_received`、`llm_output`、`message_sending`、`message_sent`、`session_end` 等事件，并在 OpenClaw 上下文压缩期间通过 `before_compaction` / `after_compaction` 维持记忆一致（[plugin/README.md](https://github.com/memorycrystal/memorycrystal/blob/main/plugin/README.md)）。

## MCP 服务器与 HTTP API

MCP 服务器在 stdio 与 HTTP 两种传输间复用同一份工具实现（[mcp-server/src/index.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/index.ts)）。入口处通过 `redactToolErrorResult` 与 `sanitizeErrorForLog` 防止 API Key 或令牌泄漏到日志中。`readBearerToken` 调用 `extractBearer`，再由 Bearer 中间件完成鉴权，旧版 `CRYSTAL_API_KEY` 已被弃用，统一使用 `MEMORY_CRYSTAL_API_KEY`。

工具层按记忆系统与知识库系统分组。`ideas.ts` 中的 `handleIdeasTool` 接收 `status` 与 `limit` 参数并通过 `ConvexClient` 与后端交互（[mcp-server/src/tools/ideas.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/tools/ideas.ts)）。`obsidian.ts` 提供把记忆导出为带 YAML frontmatter 的 Markdown 文件的能力（[mcp-server/src/lib/obsidian.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/lib/obsidian.ts)）。

HTTP API 端点位于 `/api/mcp/*` 与 `/api/knowledge-bases/*`（[README.md](https://github.com/memorycrystal/memorycrystal/blob/main/README.md)）。所有请求需要 `Authorization: Bearer <api-key>`，并对单 key 实施速率限制。

### 关键端点速览

| 端点 | 方法 | 用途 |
|---|---|---|
| `/api/mcp/capture` | POST | 创建一条记忆 |
| `/api/mcp/recall` | POST | 在长期记忆上做混合召回 |
| `/api/mcp/search-messages` | POST | 检索短期会话历史 |
| `/api/knowledge-bases` | GET/POST | 列出或创建知识库 |
| `/api/knowledge-bases/:id/import` | POST | 导入参考文本块 |
| `/api/knowledge-bases/:id/bulk-insert` | POST | 高吞吐迁移导入 |
| `/api/knowledge-bases/:id/query` | POST | 在知识库内检索 |

## 部署模式

### 云托管

v0.8.4 引入了登录式引导、租户启动页、引导恢复、API Key 管理与部署目标门禁（[README.md](https://github.com/memorycrystal/memorycrystal/blob/main/README.md)）。云端路由受保护，自托管构建默认关闭该面板，便于在同一代码库下分离 SaaS 与自托管发布。

### 本地优先（local-first）

本地栈绑定三组端口：Convex RPC `http://127.0.0.1:3210`、HTTP Actions `http://127.0.0.1:3211`、仪表盘 `http://127.0.0.1:6791`（[README.md](https://github.com/memorycrystal/memorycrystal/blob/main/README.md)）。`scripts/convex-local-write-env.ts` 与 `scripts/web-backend-env.ts` 在 `package.json` 中以 `--experimental-strip-types` 形式提供本地与远端环境生成脚本（[package.json](https://github.com/memorycrystal/memorycrystal/blob/main/package.json)）。

### 完全自托管

完全自托管流程是：克隆仓库 → `npm install` → 用自有 Convex 项目执行 `npx convex deploy` → 在 `mcp-server/.env` 中写入 `CONVEX_URL` 与 `GEMINI_API_KEY` → 运行 `npm run crystal:enable` 与 `npm run crystal:doctor` 启用并自检（[README.md](https://github.com/memorycrystal/memorycrystal/blob/main/README.md)）。该流程对 OpenClaw 安装脚本用户也适用，安装后可通过 `openclaw plugins info crystal-memory` 与 `openclaw crystal_status` 直接确认插件已加载。

## 运维与诊断

`crystal_doctor` 在
Error with Openai API: peer closed connection without sending complete message body (incomplete chunked read)

Please check that you have set the OPENAI_API_KEY environment variable with a valid API key.

---

<a id='page-security-operations'></a>

## 安全、提示注入防护与运维

### 相关页面

相关主题：[项目概述与系统架构](#page-overview), [上下文引擎与记忆系统](#page-context-engine)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mcp-server/src/lib/sanitize.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/lib/sanitize.ts)
- [mcp-server/src/index.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/index.ts)
- [mcp-server/src/lib/convexClient.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/lib/convexClient.ts)
- [mcp-server/src/lib/obsidian.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/lib/obsidian.ts)
- [mcp-server/src/tools/ideas.ts](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/src/tools/ideas.ts)
- [mcp-server/README.md](https://github.com/memorycrystal/memorycrystal/blob/main/mcp-server/README.md)
- [plugin/README.md](https://github.com/memorycrystal/memorycrystal/blob/main/plugin/README.md)
- [README.md](https://github.com/memorycrystal/memorycrystal/blob/main/README.md)
- [package.json](https://github.com/memorycrystal/memorycrystal/blob/main/package.json)
</details>

# 安全、提示注入防护与运维

## 概览

Memory Crystal 作为面向 AI Agent 的持久化记忆层，在 OpenClaw、Claude Code、Codex、Factory 等宿主中以插件或 MCP 服务器形态运行。其安全姿态由三层组成：内容层（提示词回显清洗与机密脱敏）、传输层（Bearer 令牌与 API Key 校验）、运维层（`crystal_doctor` 自检与 Convex 成本熔断）。每一层都对应具体源码实现，并通过自 v0.8.7 以来的多个版本持续硬化。

## 提示注入防护

提示词回显注入是 Agent 记忆系统最常见的一类风险——当用户原始消息被原样回写到模型上下文时，攻击者可借此伪造系统提示。`mcp-server/src/lib/sanitize.ts` 在文件顶部即声明了多组清洗规则，覆盖 XML 风格标签（`<system>...</system>`）、ChatML 风格 token（`<|im_start|>`、`<|im_end|>`）以及指令包络（`[INST]...[/INST]`）等典型注入载体。资料来源：[mcp-server/src/lib/sanitize.ts:1-20]()

`INJECTION_LINE_PATTERNS` 进一步匹配行首的伪装指令，例如 `^system:`、`^you are now`、`^ignore previous` 等；`WRAPPED_INJECTION_PATTERNS` 则用于捕获跨行的完整伪造块。资料来源：[mcp-server/src/lib/sanitize.ts:9-25]()。`MAX_MEMORY_CONTENT_LENGTH = 2000` 在写入模型上下文前限制单条记忆的最大长度，避免巨型负载挤占上下文窗口或携带隐藏指令。资料来源：[mcp-server/src/lib/sanitize.ts:27]()

服务器侧额外提供 `sanitizeErrorForLog` 与 `redactToolErrorResult` 两个包装函数，把异常文本与工具错误结果在写入日志或返回客户端之前统一经过 `redactSecrets`，防止 API Key 随错误信息泄露。资料来源：[mcp-server/src/index.ts:31-48]()。v0.8.13 发布说明指出，压缩回显证据、Workflow 技能注入与最近消息匹配头部现已复用同一套回显清洗器，避免不同代码路径出现行为漂移。

## 密钥管理与身份认证

所有 MCP 端点统一要求 `Authorization: Bearer <api-key>` 请求头。`mcp-server/src/lib/convexClient.ts` 在客户端构造时即强制校验 `MEMORY_CRYSTAL_API_URL` 与 `MEMORY_CRYSTAL_API_KEY`：任一缺失、或者误用旧版 `CRYSTAL_API_KEY`，都会立即抛出明确错误提示用户升级。资料来源：[mcp-server/src/lib/convexClient.ts:18-45]()

密钥清洗使用反向否定前瞻（`SECRET_KEY_NAME`）排除 `tokenCount` 等无关变量，再对 `api_key`、`accessToken`、`refreshToken`、`clientSecret`、`privateKey` 等 16 类敏感字段统一打码。资料来源：[mcp-server/src/lib/sanitize.ts:29-50]()。这种字段命名白名单 + 正则匹配的组合，是 `crystal_search_messages`、`crystal_recent`、回显匹配等短时记忆工具在返回前默认执行的脱敏管线。资料来源：[mcp-server/README.md:25-30]()

知识库访问遵循租户与通道（channel）边界。社区曾报告 `__management__` 哨兵导致普通用户越权读取管理级 KB 的问题（Issue #4），自 v0.8.14 起，KB 查询会按调用方 agent id 重新鉴权，而非将 peer channel 视为硬性内容过滤器。资料来源：[plugin/README.md:38-46]()

## 运维诊断与成本控制

`crystal_doctor` 是面向运维的人工可读诊断命令，v0.8.8 首次为 Hermes 引入，v0.8.12 进一步扩展，可报告钩子注册 API、已注册钩子名称、注册时间、最近一次事件、最近解析的 session/channel，以及最近一次 skip 原因。当钩子已注册但自插件加载以来无任何回调触发时，会主动给出告警。`mcp-server/src/tools/ideas.ts` 中的工具结果构造与错误降级模式可作为该诊断面返回结构化文本的参考实现。资料来源：[mcp-server/src/tools/ideas.ts:1-30]()

成本侧由 Convex 端运行时代码与 `scripts/convex-cost-smoke.mjs` 共同保障：v0.8.7 引入了带 per-user 与全局紧急阈值的成本熔断账本，覆盖 recall、message search、knowledge-base search 三个表面；smoke 脚本消费生产环境 Convex JSONL 日志以提供压测证据。`package.json` 中的 `web:backend:*` 与 `convex-local-write-env` 脚本则为本地 / 远程部署的密钥注入提供受控通道。资料来源：[package.json:30-50]()

`obsidian.ts` 把记忆导出为带 YAML frontmatter 的 Markdown 时，会显式写入 `confidence`、`valence`、`arousal`、`source`、`channel` 等元数据，便于离线审计与回溯取证。资料来源：[mcp-server/src/lib/obsidian.ts:1-20]()

## 常见故障与最佳实践

| 场景 | 现象 | 建议 |
|---|---|---|
| 钩子注册但无回调 | 插件加载后无事件触发 | 运行 `crystal_doctor` 检查 `lastHookEvent` 与 `lastHookSkipReason` |
| 直接会话捕获失败 | Telegram 等 peer 渠道未入库 | 确认 hook 上下文是否匹配显式 peer 策略（v0.8.11） |
| KB 召回结果过少 | 共享训练 KB 未返回 | 检查调用方 agent id 鉴权（v0.8.14） |
| 同一记忆反复出现 | 迁移副本挤占结果上限 | 升级至 v0.8.15，recall 端将自动去重 |
| 错误日志中疑似 Key 泄漏 | 异常文本含 `Bearer ...` | 确认使用 `sanitizeErrorForLog` 包装的日志通道 |

## See Also

- [架构概览](architecture.md)
- [MCP 工具清单](mcp-tools.md)
- [OpenClaw 插件钩子](plugin-hooks.md)
- [知识库与召回](knowledge-bases.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：memorycrystal/memorycrystal

摘要：发现 18 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

## 1. 身份坑 · 仓库名和安装名不一致

- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `memorycrystal` 与安装入口 `@memorycrystal/crystal-memory` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 复现命令：`npm install @memorycrystal/crystal-memory`
- 证据：identity.distribution | https://github.com/memorycrystal/memorycrystal | repo=memorycrystal; install=@memorycrystal/crystal-memory

## 2. 安装坑 · 失败模式：installation: Memory Crystal v0.8.11

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Memory Crystal v0.8.11
- 对用户的影响：Upgrade or migration may change expected behavior: Memory Crystal v0.8.11
- 证据：failure_mode_cluster:github_release | https://github.com/memorycrystal/memorycrystal/releases/tag/v0.8.11 | Memory Crystal v0.8.11

## 3. 安装坑 · 失败模式：installation: Memory Crystal v0.8.12

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Memory Crystal v0.8.12
- 对用户的影响：Upgrade or migration may change expected behavior: Memory Crystal v0.8.12
- 证据：failure_mode_cluster:github_release | https://github.com/memorycrystal/memorycrystal/releases/tag/v0.8.12 | Memory Crystal v0.8.12

## 4. 安装坑 · 失败模式：installation: Memory Crystal v0.8.13

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Memory Crystal v0.8.13
- 对用户的影响：Upgrade or migration may change expected behavior: Memory Crystal v0.8.13
- 证据：failure_mode_cluster:github_release | https://github.com/memorycrystal/memorycrystal/releases/tag/v0.8.13 | Memory Crystal v0.8.13

## 5. 安装坑 · 失败模式：installation: Memory Crystal v0.8.14

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Memory Crystal v0.8.14
- 对用户的影响：Upgrade or migration may change expected behavior: Memory Crystal v0.8.14
- 证据：failure_mode_cluster:github_release | https://github.com/memorycrystal/memorycrystal/releases/tag/v0.8.14 | Memory Crystal v0.8.14

## 6. 安装坑 · 失败模式：installation: Memory Crystal v0.8.4

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Memory Crystal v0.8.4
- 对用户的影响：Upgrade or migration may change expected behavior: Memory Crystal v0.8.4
- 证据：failure_mode_cluster:github_release | https://github.com/memorycrystal/memorycrystal/releases/tag/v0.8.4 | Memory Crystal v0.8.4

## 7. 安装坑 · 失败模式：installation: Memory Crystal v0.8.5

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Memory Crystal v0.8.5
- 对用户的影响：Upgrade or migration may change expected behavior: Memory Crystal v0.8.5
- 证据：failure_mode_cluster:github_release | https://github.com/memorycrystal/memorycrystal/releases/tag/v0.8.5 | Memory Crystal v0.8.5

## 8. 安装坑 · 失败模式：installation: Memory Crystal v0.8.6

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Memory Crystal v0.8.6
- 对用户的影响：Upgrade or migration may change expected behavior: Memory Crystal v0.8.6
- 证据：failure_mode_cluster:github_release | https://github.com/memorycrystal/memorycrystal/releases/tag/v0.8.6 | Memory Crystal v0.8.6

## 9. 安装坑 · 失败模式：installation: Memory Crystal v0.8.7

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Memory Crystal v0.8.7
- 对用户的影响：Upgrade or migration may change expected behavior: Memory Crystal v0.8.7
- 证据：failure_mode_cluster:github_release | https://github.com/memorycrystal/memorycrystal/releases/tag/v0.8.7 | Memory Crystal v0.8.7

## 10. 安装坑 · 失败模式：installation: Memory Crystal v0.8.8

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: Memory Crystal v0.8.8
- 对用户的影响：Upgrade or migration may change expected behavior: Memory Crystal v0.8.8
- 证据：failure_mode_cluster:github_release | https://github.com/memorycrystal/memorycrystal/releases/tag/v0.8.8 | Memory Crystal v0.8.8

## 11. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/memorycrystal/memorycrystal | host_targets=openclaw, mcp_host, claude, claude_code, codex

## 12. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/memorycrystal/memorycrystal | README/documentation is current enough for a first validation pass.

## 13. 维护坑 · 失败模式：migration: Memory Crystal v0.8.15

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: Memory Crystal v0.8.15
- 对用户的影响：Upgrade or migration may change expected behavior: Memory Crystal v0.8.15
- 证据：failure_mode_cluster:github_release | https://github.com/memorycrystal/memorycrystal/releases/tag/v0.8.15 | Memory Crystal v0.8.15

## 14. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/memorycrystal/memorycrystal | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/memorycrystal/memorycrystal | no_demo; severity=medium

## 16. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/memorycrystal/memorycrystal | no_demo; severity=medium

## 17. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/memorycrystal/memorycrystal | issue_or_pr_quality=unknown

## 18. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/memorycrystal/memorycrystal | release_recency=unknown

<!-- canonical_name: memorycrystal/memorycrystal; human_manual_source: deepwiki_human_wiki -->