1. 项目定位与核心价值

piia-engram（以下简称 Engram）是一个面向 AI Agent 与编码助手的"记忆"中间件，以本地优先（local-first）的存储为底座，把跨工具、跨会话的经验沉淀为可治理的知识资产。Engram 不是一个普通的笔记系统，它把"经验"分为两条线：lesson（可复用的教训）与 decision（关键决策），并通过 staging → verified 的层级晋升机制，让知识在反复使用与人工/自动确认后逐步进入可信层。

Engram 的设计始终围绕三条边界：

• 本地优先：默认数据落盘于 ~/.engram/，通过 ENGRAM_DIR 环境变量可重定向。资料来源：src/piia_engram/beta_tracker.py:21-29
• 隐私敏感：导出到 AGENTS.md / CLAUDE.md 的内容仅包含 verified、active、且不超过调用方 sensitivity 上限的条目，且只输出 metadata/summary，不暴露内部 bookkeeping 字段。资料来源：src/piia_engram/agents_md_export.py:1-32
• 匿名遥测：使用轮换的"匿名日 ID"（daily_id）作为唯一标识，配合 ENGRAM_BETA_TRACKING=0 可完全关闭遥测。资料来源：src/piia_engram/beta_tracker.py:42-49

2. 系统组成与数据流

Engram 由四个相互协作的子系统组成：本地存储、Claude Code Hooks、AGENTS.md 导出器、以及可选的 Cloudflare Workers 匿名遥测后端。下面用一张 Mermaid 图描述其协作关系：

flowchart LR
    A[Claude Code / Agent] -->|SessionStart| B(auto_inject_resume_brief)
    A -->|PostCompact| C(auto_absorb_compact)
    A -->|工具调用| D[Engram Core]
    D -->|读写| E[(~/.engram/<br/>JSONL + SQLite)]
    D -->|metadata-only| F[AGENTS.md / CLAUDE.md]
    D -->|beta_events.jsonl| G[Telemetry Worker]
    G -->|D1| H[(Cloudflare D1)]
    G -->|/v1/stats| I[仪表盘 + JSON API]

• Hooks 层：auto_inject_resume_brief 在会话开始时把"恢复简报"注入到 additionalContext；auto_absorb_compact 在上下文被压缩（compact）后吸收内容，并明确不再做语义抽取（避免双写）。资料来源：src/piia_engram/hooks/auto_inject_resume_brief.py:1-36、src/piia_engram/hooks/auto_absorb_compact.py:1-40
• 遥测后端：POST /v1/events 接收匿名事件，GET / 返回带口令的仪表盘，GET /v1/stats 输出 JSON，GET /v1/health 公开健康检查；写入采用"分列回退（tiered insert）"以兼容未完成 schema 迁移的部署。资料来源：worker/src/index.js:1-120

3. 快速上手（Quick Start）

3.1 启用 Beta 遥测（可选）

遥测在 beta 构建中默认开启，仅采集事件元数据（如 knowledge_created、knowledge_promoted、cold_start），绝不包含知识正文。事件落盘于 ~/.engram/beta_events.jsonl，每行形如 {"event": "...", "ts": "ISO8601", "d": {...}}。如需关闭，设置环境变量即可。资料来源：src/piia_engram/beta_tracker.py:33-65

# 关闭遥测
export ENGRAM_BETA_TRACKING=0

# 自定义数据目录
export ENGRAM_DIR=~/my-engram-data

3.2 接入 Claude Code Hooks

将仓库 examples/ 中的示例 hook 接入 claude_mcp 配置即可。在 SessionStart 时，hook 会调用 engram.get_resume_brief() 生成恢复简报；在 PostCompact 时，hook 会吸收被压缩的会话内容到本地存储。两个 hook 都遵循"绝不阻塞 Claude Code"的容错约定。资料来源：src/piia_engram/hooks/auto_inject_resume_brief.py:31-36、src/piia_engram/hooks/auto_absorb_compact.py:32-40

3.3 导出可信知识到 AGENTS.md / CLAUDE.md

通过 agents_md_export.build_agents_md_export() 即可生成一段可直接粘贴的 Markdown 块。该函数是纯函数，不会对存储做读写，也不会自动注册新的 MCP 工具——所有 agent 表面必须经过独立审阅。资料来源：src/piia_engram/agents_md_export.py:50-92

from piia_engram.agents_md_export import build_agents_md_export

md = build_agents_md_export(
    lessons=lessons,
    decisions=decisions,
    scope="global",          # 或 "project"
    project="my-app",
    max_sensitivity="work",  # 排除更敏感的条目
)
print(md)

输出严格遵守"verified + active + 低于 sensitivity 上限 + 作用域匹配"四重过滤，未命中时返回一段 No verified, non-sensitive knowledge to export 的占位说明。资料来源：src/piia_engram/agents_md_export.py:60-78

3.4 真实客户端验证

在进行 Hermes CLI、OpenClaw 文件桥等真实客户端的回归验证时，可使用 client_validation.py 提供的证据脚手架。它定义了 run_meta.json、tool_locations.json、zero_pollution.txt、REPORT.md 等必备产物，并要求 client_id / client_version / workspace_isolated / home_isolated 等关键键全部存在，以保证跨次运行的"零污染"对比。资料来源：src/piia_engram/client_validation.py:1-58

4. 社区与生态

Engram 现已发布 v3.49.0，正式将"跨工具连续性"能力落地为可发布的本地检查点，包括 engram import --materialize-version-chain 选项（默认保守策略下可保留被审阅的同键 lesson/decision 冲突为版本链条目），以及 MCIC v1 等面向多客户端互操作的协议层。社区方面，issue #8 中已有国内 Claude / CodeX API 中转站主动接洽合作，希望在 README 中展示其服务——这与项目"本地优先、隐私敏感"的设计并不冲突，未来可能以"可选生态服务"形式独立呈现，而不会进入 Engram 核心分发。资料来源：worker/src/index.js:1-40

See Also

• hooks/auto_inject_resume_brief.py — 会话恢复简报注入
• hooks/auto_absorb_compact.py — Compact 后内容吸收
• beta_tracker.py — Beta 事件追踪与治理埋点
• agents_md_export.py — AGENTS.md / CLAUDE.md 兼容导出
• client_validation.py — 真实客户端验证证据契约
• worker/src/index.js — 匿名遥测后端（Cloudflare Workers + D1）

1. 概览

Engram 是一个面向 AI 编程代理的本地记忆治理中间层。它以 MCP（Model Context Protocol）工具的形式向代理暴露"知识生命周期"操作（创建、回顾、提升、导出），同时通过 Claude Code 钩子把会话事件自动接入本地存储，并把脱敏遥测上报到 Cloudflare Workers + D1 仪表盘。

整个系统围绕三条主线设计：

1. 本地优先：所有用户身份与知识条目默认落盘在 ~/.engram/，通过 ENGRAM_DIR 环境变量可重定向。
2. 分级 + 敏感度门禁：知识条目分 staging 与 verified 两层；导出时再叠加 sensitivity 等级过滤。
3. 可观测性：审计、β 事件追踪、遥测三者分通道落盘，避免敏感内容泄露。

资料来源：src/piia_engram/beta_tracker.py:1-30

2. 核心子系统

2.1 Claude Code 钩子集成

Engram 通过三段式钩子把"会话生命周期"映射为"知识生命周期"：

三段钩子共享一个设计契约：永不抛出阻塞异常，所有失败都被 try/except Exception: pass 吞掉，只输出 {"continue": true}。

资料来源：src/piia_engram/hooks/auto_inject_resume_brief.py:1-40, src/piia_engram/hooks/auto_absorb_compact.py:1-40, src/piia_engram/hooks/auto_save_on_stop.py:1-40

2.2 知识治理与导出

agents_md_export.py 实现了一个纯函数式的"AGENTS.md / CLAUDE.md 兼容导出器"，它不读写存储，仅接收已加载的 lessons / decisions 集合并按以下约束过滤：

• 只导出 tier == "verified" 且 status == "active" 的条目；
• 通过 sensitivity.classify_item 比对调用方传入的 max_sensitivity（默认 work），超过阈值的条目被静默排除；
• 区分 scope="global"（仅可泛化知识）与 scope="project"（单项目知识），由 _entry_project 决定归属；
• 输出只包含人类可读的 summary / choice 字段，绝不暴露 id、access_count、风险标志或来源细节。

该模块刻意保持为"纯函数 + 分离接线"模式：即只生成 Markdown 块，MCP 工具注册与权限审批是独立的、可评审的步骤——"wiring is a separate, reviewed step so no new agent-facing surface ships unreviewed"。

资料来源：src/piia_engram/agents_md_export.py:1-60

2.3 β 事件追踪与审计

beta_tracker.py 在治理节点记录元数据级事件（不包含知识正文），写入 ~/.engram/beta_events.jsonl，每行形如 {"event": "...", "ts": "ISO8601", "d": {...}}。追踪的事件包括：knowledge_created、knowledge_promoted、knowledge_reviewed、knowledge_rejected、cold_start、session_end、reconcile。默认开启，可通过 ENGRAM_BETA_TRACKING=0 关闭。

audit.py 提供 AuditLogger，对所有身份与知识的读/写/删除/导出/导入操作落盘 ~/.engram/audit.log（JSON Lines）。read 操作额外受 governance_runtime.caller_is_owner(root) 闸门保护，非属主调用被静默丢弃。

资料来源：src/piia_engram/beta_tracker.py:30-80, src/piia_engram/audit.py:1-40

2.4 遥测仪表盘（Worker 侧）

worker/src/index.js 是一个 Cloudflare Workers + D1 应用，对外暴露事件接收、反馈接收、仪表盘 HTML 与 JSON API。它实现了分层 INSERT + 优雅降级：

1. 尝试写入 v1.1 完整列（P0 + P1）；
2. 若 v1.1 列不存在则回退到 v1（P0 列）；
3. 任何写入都保证不丢事件（"no event is ever dropped"）。

接收端 validatePayload 使用白名单字段 + JSON.stringify 把未知字段塞入 raw_json；validateFeedback 仅强制 daily_id 存在且长度 ≤ 64。仪表盘渲染包含版本分布、操作系统分布、Python 版本分布、近期事件表、用户反馈报告（含平均促进率）等模块。

资料来源：worker/src/index.js:1-80

3. 数据流

flowchart LR
    A[Claude Code 会话] -->|SessionStart| B(hook: auto_inject_resume_brief)
    A -->|PreCompact / PostCompact| C(hook: auto_absorb_compact)
    A -->|Stop| D(hook: auto_save_on_stop)
    B --> E[Engram Core / 存储 ~/.engram/]
    C --> E
    D --> E
    E -->|读| F[agents_md_export 纯函数]
    F -->|粘贴| G[AGENTS.md / CLAUDE.md]
    E -->|元数据事件| H[beta_events.jsonl]
    E -->|审计记录| I[audit.log]
    E -->|脱敏遥测| J[Worker /v1/events]
    J --> K[(Cloudflare D1)]
    K --> L[/v1/stats JSON & 仪表盘/]

4. 客户端验证与零污染契约

client_validation.py 定义了真实 AI 客户端（如 Hermes CLI、OpenClaw 文件桥）验证运行的证据骨架。EVIDENCE_FILES 列出了 12 项必交产物（含 REPORT.md、OPTIMIZATION_NOTES.md、zero_pollution.txt），REQUIRED_RUN_META_KEYS 强制 10 个运行元数据字段（含 workspace_isolated、home_isolated、write_tools_allowed），FileSnapshot 数据类为 zero_pollution.txt 提供 path / sha256 / size_bytes / mtime_ns 的最小对比单元。该模块与 continuity_harness（纯模拟记忆循环）刻意分离，用于把"模拟"与"真实客户端运行"两套证据契约区分开。

资料来源：src/piia_engram/client_validation.py:1-40

5. 常见失败模式

• 钩子阻塞 Claude Code：所有钩子必须用 try/except 包裹并回退 {"continue": true}，否则会卡死会话。
• β 追踪误开启：在受限环境部署时务必显式设 ENGRAM_BETA_TRACKING=0，避免 JSONL 持续增长。
• 导出泄露敏感条目：调用方必须显式传 max_sensitivity，默认值 work 不一定适合所有场景。
• 遥测字段漂移：Worker 端 validatePayload 使用白名单，未知字段会被序列化进 raw_json；客户端升级前应先确认目标 D1 schema 处于 v1 还是 v1.1 阶段。

参见

• README 与安装指引（待生成）
• CLI 命令参考（待生成）
• 遥测与隐私（待生成）

概述

Engram 是面向 AI 开发者代理的持久化记忆层（Memory MCP），核心职责是在多次会话、多个工具之间维护"经验沉淀"与"上下文恢复"。本主题聚焦两类能力：一是将短期交互提炼为可复用的知识条目（lesson / decision），二是让 Claude Code、Cursor、Codex 等不同工具在切换时共享同一份经过治理的记忆。社区 issue #8（呆呆兽中转站合作申请）也证实了 Memory MCP 在跨工具状态查看场景中的实际价值。资料来源：src/piia_engram/agents_md_export.py:1-15

知识生命周期与分层

Engram 将知识划分为 staging（暂存）与 verified（已验证）两层。staging 条目由 PostCompact 钩子自动从会话摘录生成；verified 需经过用户审阅或自动晋升，且 AGENTS.md 导出只挑选 tier == "verified" 且 status == "active" 的条目。资料来源：src/piia_engram/agents_md_export.py:23-58、资料来源：src/piia_engram/hooks/auto_absorb_compact.py:1-12

graph LR
  A[SessionStart] --> B[auto_inject_resume_brief]
  C[PreCompact] --> D[auto_absorb_compact]
  E[Stop] --> F[auto_save_on_stop]
  G[PostCompact Agent] --> H[extract_session_insights]
  D --> H
  H --> I[staging 层]
  I --> J[用户审阅 / 自动晋升]
  J --> K[verified 层]
  K --> L[AGENTS.md / CLAUDE.md 导出]

会话开始时 auto_inject_resume_brief 读取既往摘要并以 hookSpecificOutput.additionalContext 形式注入。资料来源：src/piia_engram/hooks/auto_inject_resume_brief.py:1-30。Stop 钩子在消息数低于 max(4, _flush_threshold() // 2) 时跳过落盘，避免噪音。资料来源：src/piia_engram/hooks/auto_save_on_stop.py:1-30

跨工具连续性

跨工具同步由 reconcile.py 与 reconcile_apply.py 协调，事件 reconcile 同时被 beta_tracker 记录。v3.49.0 引入了"版本链物化"（version-chain materialization）：engram import <backup.json> --apply --yes --materialize-version-chain 可将同键冲突保留为版本链条目，而默认路径仍保持保守。资料来源：src/piia_engram/import_export.py:1-20

冲突解决不只覆盖 lesson/decision：decision_thread.py 与 merge_apply.py 提供线程式合并，相同键的差异在导入端可由用户审阅。client_validation.py 定义了真实客户端的证据契约，列出 12 个必备产物（run_meta.json、zero_pollution.txt、REPORT.md 等），用于在 Hermes CLI、OpenClaw 等客户端验证连续性不污染工作区。资料来源：src/piia_engram/client_validation.py:1-30

治理、审计与遥测

AuditLogger.log 对 read 路径额外校验 caller_is_owner，治理开启时非属主读取会被静默丢弃。资料来源：src/piia_engram/audit.py:1-50

beta_tracker.py 默认开启，事件包括 knowledge_created/promoted/reviewed/rejected、cold_start、session_end、reconcile 等。资料来源：src/piia_engram/beta_tracker.py:1-40

遥测端由 worker/src/index.js 实现：Cloudflare Workers + D1 接收事件与反馈，对 P1/P0/Legacy 列做分层 INSERT 保证不丢事件，仪表盘聚合版本采纳、激活状态、回访分桶、错误趋势等。资料来源：worker/src/index.js:1-60

常见失败模式

• AGENTS.md 导出为空：所有 verified 知识均被 classify_item 判定为高于 max_sensitivity（默认 work）。资料来源：src/piia_engram/agents_md_export.py:18-30
• Stop 钩子未触发：消息数低于 max(4, _flush_threshold() // 2) 阈值。资料来源：src/piia_engram/hooks/auto_save_on_stop.py:1-25
• 导入冲突被覆盖：未传 --materialize-version-chain 时默认保守路径会丢弃同键差异。资料来源：src/piia_engram/import_export.py:1-20
• 审计 read 静默：属主未通过 governance_runtime.caller_is_owner 校验。资料来源：src/piia_engram/audit.py:30-50

另请参阅

• MCIC v1 跨工具导入协议
• 知识晋升与自动审阅
• 遥测 Contract v1.1 派生分桶

一、遥测采集：边界、最小化与远程写入的容错

Engram 的遥测面只暴露匿名日 ID和派生的统计分桶，不写入任何用户原话、知识内容或个人身份信息。worker/src/index.js 通过 validatePayload 显式拒绝缺 daily_id、长度越界或字段类型错误的请求，并以 413/422/400 三个状态码区分载荷过大、字段非法和 JSON 损坏，从而在入口处把所有不可信数据挡掉 (worker/src/index.js:validatePayload, handleEvent)。

遥测写入采用分层 INSERT（P0 + P1 全部列 → 仅 P0 列 → 全失败回退），目的是在 D1 迁移尚未对齐时单条事件也不丢 (worker/src/index.js:handleEvent)。所有公开端点（/v1/events、/v1/feedback、/v1/stats）共用 CORS_HEADERS 统一响应头，根路由 OPTIONS 直接返回 204，便于从浏览器或桌面代理侧发起跨域探活 (worker/src/index.js:CORS_HEADERS, OPTIONS)。

flowchart LR
    Client[Engram CLI / Hook] -->|POST /v1/events| Edge[Cloudflare Worker]
    Edge -->|validatePayload| Reject{字段合法?}
    Reject -- 否 --> R4xx[413/422/400]
    Reject -- 是 --> Tier{Tiered INSERT}
    Tier -->|v1.1 列就绪| D1v11[(D1 events v1.1)]
    Tier -->|仅 P0 列| D1v1[(D1 events v1)]
    Tier -->|都不匹配| D1raw[(raw_json 兜底)]
    D1v11 --> Stats[/v1/stats JSON/]
    D1v1 --> Stats
    D1raw --> Stats

二、本地数据生命周期与退出控制

所有事件型元数据（治理节点的状态转移）默认落盘到 ~/.engram/beta_events.jsonl，每行一条 JSON，不包含任何知识原文，仅含 event/ts/d{...} 三类字段 (src/piia_engram/beta_tracker.py:_engram_root, _events_path, _is_beta_tracking_enabled)。这一行为是默认开启的；只要设置 ENGRAM_BETA_TRACKING=0|false|off|no 即可整体关闭遥测写入 (src/piia_engram/beta_tracker.py:_is_beta_tracking_enabled)。同时支持 ENGRAM_DIR 自定义根目录，便于多用户机器或容器里做隔离 (src/piia_engram/beta_tracker.py:_engram_root)。

Hook 链路上每个文件都遵循"绝不阻塞宿主"原则：auto_inject_resume_brief.py、auto_absorb_compact.py、auto_save_on_stop.py 都在最外层用 try/except 吃掉异常，并以 json.dumps({"continue": True}) 退出 (src/piia_engram/hooks/auto_inject_resume_brief.py:main, src/piia_engram/hooks/auto_absorb_compact.py:__main__, src/piia_engram/hooks/auto_save_on_stop.py)。这意味着即便 Engram 后端故障或磁盘满，Claude Code 的 SessionStart、Stop、Compact 流程也不会被卡住。

三、知识导出：verified-only + 敏感度闸门

agents_md_export.py 是把 Engram 知识沉淀到 AGENTS.md / CLAUDE.md 的唯一受审出口。它对每条 entry 做了三层硬约束：

1. Tier 与状态显式匹配：tier == "verified" 且 status == "active" 才可导出；缺失字段按"未经验证"处理，失败关闭 (src/piia_engram/agents_md_export.py:_is_verified_active)。
2. 敏感度上限：调用 sensitivity.classify_item 取得分级，再与调用方传入的 max_sensitivity（默认 work）比较；超出上限直接丢弃 (src/piia_engram/agents_md_export.py:_within_sensitivity, _rank)。
3. 作用域隔离：scope="global" 只导出可泛化知识（无 project 字段），scope="project" 只导出该项目的条目 (src/piia_engram/agents_md_export.py:_scope_match, _entry_project)。

最终输出只含 summary/choice/domain 这些人读字段，绝不携带 id/access_count/risk/内部 provenance 字段 (src/piia_engram/agents_md_export.py:build_agents_md_export)。

四、客户端校验与零污染证据链

client_validation.py 定义了真实 AI 客户端（Hermes CLI、OpenClaw file bridge 等）跑通时必须落盘的证据清单 EVIDENCE_FILES（含 run_meta.json、tool_locations.json、test-materials/、prompts/、raw/、parsed/、timings.json、zero_pollution.txt、REPORT.md 等）(src/piia_engram/client_validation.py:EVIDENCE_FILES, REQUIRED_RUN_META_KEYS)。FileSnapshot 把路径、是否存在、SHA-256、大小、纳秒级 mtime 打包成可比对快照，用于验证"无污染"(src/piia_engram/client_validation.py:FileSnapshot)。

REQUIRED_RUN_META_KEYS 强制声明客户端版本、运行面、模型、Engram 模式、环境臂、工作区是否隔离、家目录是否隔离、是否允许写工具、已知限制——任何缺项都会使该次验证报告不被视为可采信证据 (src/piia_engram/client_validation.py:REQUIRED_RUN_META_KEYS)。结合 _LEVEL_ORDER（L0–L5）的层级标识，最终形成"可审计、可回放、可判定"的多客户端证据体系，避免外部客户端在未受控环境下污染主仓库状态。

See Also

• 知识生命周期与治理节点定义：docs/governance.md
• 遥测口径与隐私白皮书：docs/telemetry-privacy.md
• 遥测 Contract 远程收尾 Runbook：docs/runbooks/telemetry-contract-remote-closeout.md
• 用户信任模型与披露承诺：docs/trust.md
• 公开安全策略：SECURITY.md
• 公开隐私策略：PRIVACY.md

Pitfall Log / 踩坑日志

项目：Patdolitse/piia-engram

摘要：发现 20 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[Bug] 'engram setup' deletes users existing configs without backups.。

1. 安全/权限坑 · 来源证据：[Bug] 'engram setup' deletes users existing configs without backups.

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] 'engram setup' deletes users existing configs without backups.
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/Patdolitse/piia-engram/issues/23 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 失败模式：installation: [Bug] 'engram setup' deletes users existing configs without backups.

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: [Bug] 'engram setup' deletes users existing configs without backups.
• 对用户的影响：Developers may fail before the first successful local run: [Bug] 'engram setup' deletes users existing configs without backups.
• 证据：failure_mode_cluster:github_issue | https://github.com/Patdolitse/piia-engram/issues/23 | [Bug] 'engram setup' deletes users existing configs without backups.

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

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

4. 配置坑 · 失败模式：configuration: v3.45.2 - CI entry-point patch

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v3.45.2 - CI entry-point patch
• 对用户的影响：Upgrade or migration may change expected behavior: v3.45.2 - CI entry-point patch
• 证据：failure_mode_cluster:github_release | https://github.com/Patdolitse/piia-engram/releases/tag/v3.45.2 | v3.45.2 - CI entry-point patch

5. 能力坑 · 能力判断依赖假设

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

6. 维护坑 · 失败模式：migration: Engram v3.47.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: Engram v3.47.0
• 对用户的影响：Upgrade or migration may change expected behavior: Engram v3.47.0
• 证据：failure_mode_cluster:github_release | https://github.com/Patdolitse/piia-engram/releases/tag/v3.47.0 | Engram v3.47.0

7. 维护坑 · 失败模式：migration: v3.45.1 - CI packaging patch

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v3.45.1 - CI packaging patch
• 对用户的影响：Upgrade or migration may change expected behavior: v3.45.1 - CI packaging patch
• 证据：failure_mode_cluster:github_release | https://github.com/Patdolitse/piia-engram/releases/tag/v3.45.1 | v3.45.1 - CI packaging patch

8. 维护坑 · 失败模式：migration: v3.46.0

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

9. 维护坑 · 失败模式：migration: v3.47.1 - Public Truth Sync

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v3.47.1 - Public Truth Sync
• 对用户的影响：Upgrade or migration may change expected behavior: v3.47.1 - Public Truth Sync
• 证据：failure_mode_cluster:github_release | https://github.com/Patdolitse/piia-engram/releases/tag/v3.47.1 | v3.47.1 - Public Truth Sync

10. 维护坑 · 失败模式：migration: v3.48.0

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

11. 维护坑 · 失败模式：migration: v3.48.1 — perf(retrieval): memoize tokenization

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v3.48.1 — perf(retrieval): memoize tokenization
• 对用户的影响：Upgrade or migration may change expected behavior: v3.48.1 — perf(retrieval): memoize tokenization
• 证据：failure_mode_cluster:github_release | https://github.com/Patdolitse/piia-engram/releases/tag/v3.48.1 | v3.48.1 — perf(retrieval): memoize tokenization

12. 维护坑 · 失败模式：migration: v3.48.2

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

13. 维护坑 · 维护活跃度未知

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:1242620513 | https://github.com/Patdolitse/piia-engram | no_demo; severity=medium

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

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

16. 能力坑 · 失败模式：capability: Piia Engram工具合作申请

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Piia Engram工具合作申请
• 对用户的影响：Developers may hit a documented source-backed failure mode: Piia Engram工具合作申请
• 证据：failure_mode_cluster:github_issue | https://github.com/Patdolitse/piia-engram/issues/8 | Piia Engram工具合作申请

17. 运行坑 · 失败模式：performance: piia-engram v3.49.0

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: piia-engram v3.49.0
• 对用户的影响：Upgrade or migration may change expected behavior: piia-engram v3.49.0
• 证据：failure_mode_cluster:github_release | https://github.com/Patdolitse/piia-engram/releases/tag/v3.49.0 | piia-engram v3.49.0

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

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

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

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

20. 维护坑 · 失败模式：maintenance: v3.45.3 - Publication boundary correction

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v3.45.3 - Publication boundary correction
• 对用户的影响：Upgrade or migration may change expected behavior: v3.45.3 - Publication boundary correction
• 证据：failure_mode_cluster:github_release | https://github.com/Patdolitse/piia-engram/releases/tag/v3.45.3 | v3.45.3 - Publication boundary correction