项目定位与目标

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

项目以 MIT 协议开源，主仓库同时承载自托管（self-hosted）形态与 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。

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 后端支持）。

核心组件与职责

资料来源：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 — OpenClaw 插件 hook 与工具细节
• mcp-server/README.md — MCP 工具清单与本地栈说明
• package.json — 根级脚本与引擎要求

概述

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。

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。

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

资料来源：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
• MCP 工具与 HTTP API：mcp-server/README.md
• 知识库导入参考实现：mcp-server/src/tools/import-knowledge.ts
• Obsidian 导出格式：mcp-server/src/lib/obsidian.ts

概述

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

项目暴露三层集成面：

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

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

OpenClaw 插件集成

OpenClaw 插件是当前主推的集成入口，安装要求为 OpenClaw 2026.6.1 或更新版本（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）。files 字段显式排除了 *.test.js 与 __tests__/**，确保发布产物只携带运行时代码。

openclaw.plugin.json 中的 configSchema.properties 定义了配置契约，常见键包括 apiKey、convexUrl、defaultRecallMode、defaultRecallLimit 与 debugRecallOutput（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）。

MCP 服务器与 HTTP API

MCP 服务器在 stdio 与 HTTP 两种传输间复用同一份工具实现（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）。obsidian.ts 提供把记忆导出为带 YAML frontmatter 的 Markdown 文件的能力（mcp-server/src/lib/obsidian.ts）。

HTTP API 端点位于 /api/mcp/* 与 /api/knowledge-bases/*（README.md）。所有请求需要 Authorization: Bearer <api-key>，并对单 key 实施速率限制。

关键端点速览

部署模式

云托管

v0.8.4 引入了登录式引导、租户启动页、引导恢复、API Key 管理与部署目标门禁（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）。scripts/convex-local-write-env.ts 与 scripts/web-backend-env.ts 在 package.json 中以 --experimental-strip-types 形式提供本地与远端环境生成脚本（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）。该流程对 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.

概览

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

常见故障与最佳实践

See Also

• 架构概览
• MCP 工具清单
• OpenClaw 插件钩子
• 知识库与召回

Pitfall Log / 踩坑日志

项目：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