# piia-engram - Doramagic AI Context Pack

> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。

## 充分原则

- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。
- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。

## 给宿主 AI 的使用方式

你正在读取 Doramagic 为 piia-engram 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。

## Claim 消费规则

- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。
- **事实最低状态**：`supported`
- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。
- `weak`：只能作为低置信度线索，必须要求用户继续核实。
- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。
- `unverified`：不得作为事实使用，应明确说证据不足。
- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。

## 它最适合谁

- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0021` supported 0.86

## 它能做什么

- **MCP Server Interface**（需要安装后验证）：Exposes 72 MCP tools (Tier-1 by default) for AI clients including Claude Code, Cursor, Codex, and any MCP-compatible tool. Supports stdio transport. 证据：`docs/architecture.md`, `src/piia_engram/mcp_server.py`, `README.md` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等
- **Identity & Profile Management**（可做安装前预览）：Stores user's identity, role, preferences, technical level, and quality standards as local JSON. AI tools read this to understand who they are working with. 证据：`src/piia_engram/core.py`, `docs/architecture.md`, `PRIVACY.md`, `examples/engram/identity/profile.example.json` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等
- **Knowledge Management (Lessons & Decisions)**（可做安装前预览）：CRUD operations for lessons learned and key decisions. Knowledge has staging/verified workflow where AI-proposed content goes to staging until user approves it. 证据：`src/piia_engram/core.py`, `docs/architecture.md`, `README.md`, `docs/cross-tool-guide.md` 等 Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等
- **Keyword Search & Retrieval**（可做安装前预览）：Tokenization-based keyword search with bigram similarity scoring, CJK support, and alias expansion for knowledge retrieval. 证据：`src/piia_engram/retrieval.py`, `docs/architecture.md`, `docs/hybrid-search.md` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等
- **Hybrid Search (Optional)**（可做安装前预览）：Opt-in fusion search combining keyword, SQLite FTS5 full-text, and vector embeddings via Reciprocal Rank Fusion. Enables cross-lingual retrieval. 证据：`docs/hybrid-search.md`, `docs/hybrid-search.md`, `docs/hybrid-search.md` Claim：`clm_0004` supported 0.86, `clm_0005` supported 0.86
- **Setup Wizard & Auto-Configuration**（可做安装前预览）：Interactive CLI wizard that auto-detects AI tools (Claude Code, Cursor, Codex, Claude Desktop), configures MCP connections, and injects AI instructions. 证据：`src/piia_engram/setup_wizard.py`, `README.md`, `README.zh-CN.md` Claim：`clm_0001` supported 0.86, `clm_0003` supported 0.86, `clm_0006` supported 0.86, `clm_0007` supported 0.86 等
- **Doctor Diagnostics**（可做安装前预览）：CLI command that validates MCP configurations, checks entry point styles, probes launch capability, and can auto-fix stale configurations. 证据：`src/piia_engram/setup_wizard.py`, `docs/superpowers/specs/2026-05-30-gui-entry-doctor-probe-design.md`, `docs/superpowers/specs/2026-05-30-v340-first-run-confidence-design.md` Claim：`clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86
- **Status Command (v3.40.0)**（可做安装前预览）：Concise status summary showing CLI version, MCP entry health, storage root, terminal encoding, knowledge counts, and telemetry state. 证据：`docs/superpowers/plans/2026-05-30-v340-first-run-confidence.md`, `release-evidence/README.md`, `docs/superpowers/specs/2026-05-30-v340-first-run-confidence-design.md` Claim：`clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0019` supported 0.86
- **Governance & Access Control**（可做安装前预览）：Optional trust-level system that filters what AI clients can read/write based on client type (private-self, trusted-local, read-only-external). Disclosure ledger with SHA-256 chain. 证据：`docs/governance.md`, `docs/governance.md`, `docs/governance.md`, `src/piia_engram/mcp_server.py` Claim：`clm_0001` supported 0.86, `clm_0009` supported 0.86
- **Field-Level Encryption**（可做安装前预览）：Optional AES-256-GCM encryption for sensitive profile fields using PBKDF2 with 600,000 iterations. Encrypted values stored as enc:v2:... format. 证据：`PRIVACY.md`, `PRIVACY.md`, `src/piia_engram/crypto.py` Claim：`clm_0002` supported 0.86, `clm_0010` supported 0.86, `clm_0014` supported 0.86, `clm_0016` supported 0.86
- **Cross-Tool Memory Reconciliation**（可做安装前预览）：Silent import of memories and configurations from other AI tools: scans Claude projects memory/, CLAUDE.md, .cursorrules, AGENTS.md with similarity-based deduplication. 证据：`src/piia_engram/reconcile.py`, `docs/architecture.md` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等
- **Session Management & Wrap-up**（可做安装前预览）：Save agent context per conversation, automatic session wrap-up that extracts lessons/decisions and updates quick_context.md. 证据：`src/piia_engram/context.py`, `docs/cross-tool-guide.md`, `docs/cross-tool-guide.md` Claim：`clm_0003` supported 0.86, `clm_0012` supported 0.86
- **Review & Reports Generation**（可做安装前预览）：Interactive HTML audit page for reviewing staged knowledge, identity card export, knowledge health overview with 0-100 scores, and analytics. 证据：`src/piia_engram/reports.py`, `docs/architecture.md`, `README.zh-CN.md` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等
- **Playbook Management**（可做安装前预览）：Store and execute reusable multi-step procedures (playbooks) with steps, gotchas, and trigger keywords. Auto-extracted from session wrap-up. 证据：`PRIVACY.md`, `README.zh-CN.md`, `docs/comparison.md` Claim：`clm_0002` supported 0.86, `clm_0006` supported 0.86, `clm_0010` supported 0.86, `clm_0013` supported 0.86 等
- **Tool Registry**（可做安装前预览）：Register and discover locally installed development tools and runtimes. Maintains environment graph across tools and sessions. 证据：`README.zh-CN.md`, `src/piia_engram/core.py` Claim：`clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0006` supported 0.86, `clm_0013` supported 0.86 等
- **Opt-in Telemetry**（可做安装前预览）：Anonymous usage statistics written to local telemetry.log only. Collects tool call counts, knowledge totals, version — never content or paths. 证据：`PRIVACY.md`, `PRIVACY.md`, `src/piia_engram/telemetry.py` Claim：`clm_0002` supported 0.86, `clm_0010` supported 0.86, `clm_0014` supported 0.86, `clm_0016` supported 0.86
- **Knowledge Inheritance**（可做安装前预览）：Cross-project knowledge inheritance that提炼 relevant lessons and decisions from all past work when describing a new project. 证据：`src/piia_engram/retrieval.py`, `README.zh-CN.md` Claim：`clm_0004` supported 0.86, `clm_0006` supported 0.86, `clm_0013` supported 0.86, `clm_0014` supported 0.86 等
- **Conflict Detection**（可做安装前预览）：Detects conflicting decisions and lessons across the knowledge base to prevent contradictory information. 证据：`src/piia_engram/retrieval.py`, `docs/architecture.md` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等
- **Sessions List & Management**（可做安装前预览）：Track and list recent AI conversation sessions with metadata for cross-session continuity. 证据：`docs/superpowers/plans/2026-05-30-v340-first-run-confidence.md`, `release-evidence/README.md` Claim：`clm_0008` supported 0.86, `clm_0019` supported 0.86
- **Export/Import All Data**（可做安装前预览）：Export all Engram data as portable JSON for backup or migration. Import restores from backup. 证据：`src/piia_engram/core.py`, `docs/architecture.md` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等

## 怎么开始

- `pip install piia-engram && engram setup` 证据：`README.md` Claim：`clm_0022` supported 0.86
- `pip install piia-engram` 证据：`README.md` Claim：`clm_0022` supported 0.86, `clm_0023` supported 0.86, `clm_0026` supported 0.86, `clm_0027` supported 0.86
- `claude mcp add piia-engram -- piia-engram-mcp` 证据：`README.md` Claim：`clm_0024` supported 0.86
- `pip install --upgrade piia-engram` 证据：`README.md` Claim：`clm_0025` supported 0.86
- `pip install piia-engram[remote]` 证据：`README.md` Claim：`clm_0026` supported 0.86
- `pip install piia-engram[secure]` 证据：`README.md` Claim：`clm_0027` supported 0.86

## 继续前判断卡

- **当前建议**：需要管理员/安全审批
- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。

### 30 秒判断

- **现在怎么做**：需要管理员/安全审批
- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装
- **先别相信**：角色质量和任务匹配不能直接相信。
- **继续会触碰**：角色选择偏差、命令执行、宿主 AI 配置

### 现在可以相信

- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0021` supported 0.86
- **能力存在：MCP Server Interface**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`docs/architecture.md`, `src/piia_engram/mcp_server.py`, `README.md` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86
- **能力存在：Identity & Profile Management**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`src/piia_engram/core.py`, `docs/architecture.md`, `PRIVACY.md`, `examples/engram/identity/profile.example.json` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86
- **能力存在：Knowledge Management (Lessons & Decisions)**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`src/piia_engram/core.py`, `docs/architecture.md`, `README.md`, `docs/cross-tool-guide.md` 等 Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86
- **能力存在：Keyword Search & Retrieval**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`src/piia_engram/retrieval.py`, `docs/architecture.md`, `docs/hybrid-search.md` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86
- **能力存在：Hybrid Search (Optional)**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`docs/hybrid-search.md`, `docs/hybrid-search.md`, `docs/hybrid-search.md` Claim：`clm_0004` supported 0.86, `clm_0005` supported 0.86

### 现在还不能相信

- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。
- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。
- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。
- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。
- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.claude-plugin/plugin.json`
- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。
- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`.claude-plugin/plugin.json`
- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。

### 继续会触碰什么

- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。
- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`
- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.claude-plugin/plugin.json`
- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `docs/architecture.md`, `src/piia_engram/mcp_server.py`
- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`CHANGELOG.md`, `CHANGELOG.zh-CN.md`, `PRIVACY.md`, `README.md` 等
- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。

### 最小安全下一步

- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）
- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）
- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）
- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）
- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）

### 退出方式

- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。
- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。
- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。
- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。
- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。
- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。

## 哪些只能预览

- 解释项目适合谁和能做什么
- 基于项目文档演示典型对话流程
- 帮助用户判断是否值得安装或继续研究

## 哪些必须安装后验证

- 真实安装 Skill、插件或 CLI
- 执行脚本、修改本地文件或访问外部服务
- 验证真实输出质量、性能和兼容性

## 边界与风险判断卡

- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0028` inferred 0.45
- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`.claude-plugin/plugin.json` Claim：`clm_0029` supported 0.86
- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0030` supported 0.86
- **风险**： 处理方式：
- **风险**： 处理方式：
- **风险**： 处理方式：
- **风险**： 处理方式：
- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。
- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。
- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。

## 开工前工作上下文

### 加载顺序

- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。
- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。
- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。
- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。
- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。

### 任务路由

- **MCP Server Interface**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`docs/architecture.md`, `src/piia_engram/mcp_server.py`, `README.md` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等
- **Identity & Profile Management**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`src/piia_engram/core.py`, `docs/architecture.md`, `PRIVACY.md`, `examples/engram/identity/profile.example.json` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等
- **Knowledge Management (Lessons & Decisions)**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`src/piia_engram/core.py`, `docs/architecture.md`, `README.md`, `docs/cross-tool-guide.md` 等 Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等
- **Keyword Search & Retrieval**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`src/piia_engram/retrieval.py`, `docs/architecture.md`, `docs/hybrid-search.md` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等
- **Hybrid Search (Optional)**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`docs/hybrid-search.md`, `docs/hybrid-search.md`, `docs/hybrid-search.md` Claim：`clm_0004` supported 0.86, `clm_0005` supported 0.86
- **Setup Wizard & Auto-Configuration**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`src/piia_engram/setup_wizard.py`, `README.md`, `README.zh-CN.md` Claim：`clm_0001` supported 0.86, `clm_0003` supported 0.86, `clm_0006` supported 0.86, `clm_0007` supported 0.86 等
- **Doctor Diagnostics**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`src/piia_engram/setup_wizard.py`, `docs/superpowers/specs/2026-05-30-gui-entry-doctor-probe-design.md`, `docs/superpowers/specs/2026-05-30-v340-first-run-confidence-design.md` Claim：`clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86
- **Status Command (v3.40.0)**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`docs/superpowers/plans/2026-05-30-v340-first-run-confidence.md`, `release-evidence/README.md`, `docs/superpowers/specs/2026-05-30-v340-first-run-confidence-design.md` Claim：`clm_0007` supported 0.86, `clm_0008` supported 0.86, `clm_0019` supported 0.86
- **Governance & Access Control**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`docs/governance.md`, `docs/governance.md`, `docs/governance.md`, `src/piia_engram/mcp_server.py` Claim：`clm_0001` supported 0.86, `clm_0009` supported 0.86
- **Field-Level Encryption**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`PRIVACY.md`, `PRIVACY.md`, `src/piia_engram/crypto.py` Claim：`clm_0002` supported 0.86, `clm_0010` supported 0.86, `clm_0014` supported 0.86, `clm_0016` supported 0.86
- **Cross-Tool Memory Reconciliation**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`src/piia_engram/reconcile.py`, `docs/architecture.md` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等
- **Session Management & Wrap-up**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`src/piia_engram/context.py`, `docs/cross-tool-guide.md`, `docs/cross-tool-guide.md` Claim：`clm_0003` supported 0.86, `clm_0012` supported 0.86
- **Review & Reports Generation**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`src/piia_engram/reports.py`, `docs/architecture.md`, `README.zh-CN.md` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等
- **Playbook Management**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`PRIVACY.md`, `README.zh-CN.md`, `docs/comparison.md` Claim：`clm_0002` supported 0.86, `clm_0006` supported 0.86, `clm_0010` supported 0.86, `clm_0013` supported 0.86 等
- **Tool Registry**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`README.zh-CN.md`, `src/piia_engram/core.py` Claim：`clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0006` supported 0.86, `clm_0013` supported 0.86 等
- **Opt-in Telemetry**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`PRIVACY.md`, `PRIVACY.md`, `src/piia_engram/telemetry.py` Claim：`clm_0002` supported 0.86, `clm_0010` supported 0.86, `clm_0014` supported 0.86, `clm_0016` supported 0.86
- **Knowledge Inheritance**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`src/piia_engram/retrieval.py`, `README.zh-CN.md` Claim：`clm_0004` supported 0.86, `clm_0006` supported 0.86, `clm_0013` supported 0.86, `clm_0014` supported 0.86 等
- **Conflict Detection**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`src/piia_engram/retrieval.py`, `docs/architecture.md` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等
- **Sessions List & Management**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`docs/superpowers/plans/2026-05-30-v340-first-run-confidence.md`, `release-evidence/README.md` Claim：`clm_0008` supported 0.86, `clm_0019` supported 0.86
- **Export/Import All Data**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`src/piia_engram/core.py`, `docs/architecture.md` Claim：`clm_0001` supported 0.86, `clm_0002` supported 0.86, `clm_0003` supported 0.86, `clm_0004` supported 0.86 等

### 上下文规模

- 文件总数：98
- 重要文件覆盖：40/98
- 证据索引条目：73
- 角色 / Skill 条目：26

### 证据不足时的处理

- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。
- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。
- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。
- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。

## Prompt Recipes

### 适配判断

- 目标：判断这个项目是否适合用户当前任务。
- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。

```text
请基于 piia-engram 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。
```

### 安装前体验

- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。
- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。

```text
请把 piia-engram 当作安装前体验资产，而不是已安装工具或真实运行环境。

请严格输出四段：
1. 先问我 3 个必要问题。
2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。
3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。
4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。

硬性边界：
- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。
- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。
- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。
- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。
- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。
- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。

```

### 角色 / Skill 选择

- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。
- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。

```text
请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。
```

### 风险预检

- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。
- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。

```text
请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。
```

### 宿主 AI 开工指令

- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。
- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。

```text
请基于 piia-engram 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。
```


## 角色 / Skill 索引

- 共索引 26 个角色 / Skill / 项目文档条目。

- **piia-engram**（project_doc）：One memory. Every AI tool. Yours to keep. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`
- **Release evidence**（project_doc）：Each release must have a v .md file here recording that the mandatory pre-release gates passed. The publish workflow runs scripts/check release gate.py , which fails the publish job unless the matching file exists and is complete — so the gate cannot be skipped, even if someone forgets the process. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`release-evidence/README.md`
- **piia-engram — Architecture**（project_doc）：This document describes how piia-engram is structured internally, why the structure exists, and where each piece lives. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/architecture.md`
- **Engram vs. other memory / identity tools**（project_doc）：Engram vs. other memory / identity tools 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/comparison.md`
- **Contributing to piia-engram**（project_doc）：Thanks for considering a contribution to piia-engram — the AI identity layer that stores who you are, not just what you did. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`
- **Privacy & Data Practices**（project_doc）：piia-engram is a local-first tool. Your identity, preferences, lessons, and decisions are stored as plain JSON files on your machine. This document describes exactly what data piia-engram handles and how. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`PRIVACY.md`
- **piia-engram**（project_doc）：告诉 AI 一次——你的偏好、标准和经验会跟随你到 Claude Code、Cursor、Codex 等所有 MCP 工具。AI 提议知识，你决定什么留下。本地存储，无云端，无账号。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.zh-CN.md`
- **Engram Cross-Tool & Cross-Session Usage Guide**（project_doc）：Engram Cross-Tool & Cross-Session Usage Guide 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/cross-tool-guide.md`
- **Agent Governance**（project_doc）：Engram is local-first memory for AI tools. The governance layer is an optional runtime boundary for deciding what a calling agent may read, which write-like operations it may perform, and what disclosures were made. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/governance.md`
- **Hybrid Search optional**（project_doc）：Status: opt-in, off by default. The default search behavior is unchanged keyword . Turn this on only if you want it. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/hybrid-search.md`
- **GUI Entry Doctor Probe Implementation Plan**（project_doc）：GUI Entry Doctor Probe Implementation Plan 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/superpowers/plans/2026-05-30-gui-entry-doctor-probe.md`
- **v3.40 First-Run Confidence Implementation Plan**（project_doc）：v3.40 First-Run Confidence Implementation Plan 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/superpowers/plans/2026-05-30-v340-first-run-confidence.md`
- **GUI Entry Doctor Probe Design**（project_doc）：Goal: Make engram doctor verify whether GUI MCP client entries can launch the new piia-engram-mcp entry point, without turning setup into a broad rewrite. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/superpowers/specs/2026-05-30-gui-entry-doctor-probe-design.md`
- **v3.40 First-Run Confidence And Visual Trust Design**（project_doc）：v3.40 First-Run Confidence And Visual Trust Design 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/superpowers/specs/2026-05-30-v340-first-run-confidence-design.md`
- **Changelog**（project_doc）：English CHANGELOG.md 中文 CHANGELOG.zh-CN.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`
- **更新日志**（project_doc）：English CHANGELOG.md 中文 CHANGELOG.zh-CN.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.zh-CN.md`
- **Security Policy**（project_doc）：Version Supported --------- ----------- 3.x Yes < 3.0 No 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md`
- **Release evidence — v3.33.2**（project_doc）：- self-review: passed - codex-review: passed round-2, commit dcd8621 — all 6 round-1 findings verified fixed, no regressions - tests: pass full suite 1022 passed - eval-gate: pass round11 keyword-vs-hybrid: G1/G2/G3 all PASS REG recall 1.00- 1.00, XLING 0.50- 0.875 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`release-evidence/v3.33.2.md`
- **Release evidence — v3.34.0**（project_doc）：- self-review: passed - codex-review: passed R20 PASS — a0 read-path full cutover verified, universal harness covers all 41 governed tools - tests: pass full suite 1385 passed, governance matrix 215 passed - eval-gate: n/a no retrieval algorithm change in this release 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`release-evidence/v3.34.0.md`
- **Release Evidence — v3.35.0**（project_doc）：- self-review: passed - codex-review: passed additive features only c1+c2+a0 , self-reviewed, no security-critical changes - tests: pass full suite 1439 passed, governance matrix 220 passed - eval-gate: n/a no retrieval algorithm change - negative-control: n/a R1: no security-sensitive change in this release - field-assertion-audit: n/a R5: no security-sensitive module touched 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`release-evidence/v3.35.0.md`
- **Release Evidence — v3.36.0**（project_doc）：- self-review: passed - codex-review: passed independent Codex audits across the release scope: a5 corpus encryption 3 rounds, all FAIL findings closed , governance read-path Round 8 side-effect sweep + Round 9 structural closure — all returned PASS / PASS-WITH-FIXES, fixes strong-verified - tests: pass full suite 1718 passed, governance write-gate matrix 166 passed - eval-gate: n/a no retrieval/quality algorithm ch… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`release-evidence/v3.36.0.md`
- **Release Evidence — v3.37.0**（project_doc）：- self-review: passed - codex-review: passed Codex reviewed the distribution/onboarding entry-point change; no security-sensitive or retrieval-quality logic changed - tests: pass full suite 1720 passed; packaging/setup wizard targeted suite 169 passed; local wheel smoke verified piia-engram-mcp entry point - sanitize: passed working-tree internal strict scan high=0 warn=0; commit-message internal strict has 16 histo… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`release-evidence/v3.37.0.md`
- **Release Evidence - v3.38.0**（project_doc）：- self-review: passed - codex-review: passed Claude independent review passed; see Engram v3.38.0 EncodingHardening Claude Independent Review Report.md. - tests: pass Full suite 1742 passed, 4 expected engram core deprecation warnings; targeted encoding/setup/MCP stdio/package/release-gate suite 205 passed; local wheel built as piia engram-3.38.0-py3-none-any.whl. - sanitize: passed scripts/release sanitize check.py… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`release-evidence/v3.38.0.md`
- **Release Evidence - v3.39.0**（project_doc）：- self-review: passed Codex local release-prep sweep: version/docs/evidence consistency, publish allowlist, sanitize, package build, and full pytest. - codex-review: passed Claude read-only independent reviews passed for sessions continuity CLI, staging review CLI, docs/tool-count consistency, and privacy layout examples. - tests: pass Full suite 1762 passed, 4 expected engram core deprecation warnings; targeted pac… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`release-evidence/v3.39.0.md`
- **Release Evidence - v3.39.1**（project_doc）：- self-review: passed Codex reviewed the diff, verified doctor failure semantics stay informational, and confirmed docs/version/evidence consistency. - codex-review: passed Claude Code read-only independent review PASS for terminal encoding diagnostics, cp65001 handling, tests, and docs. - tests: pass Full suite 1767 passed, 4 expected engram core deprecation warnings; targeted setup/encoding/packaging/release suite… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`release-evidence/v3.39.1.md`
- **Release Evidence - v3.40.0**（project_doc）：- self-review: passed Codex implemented and reviewed the first-run status completion diff, HTML redaction fix, sanitize ASCII output, version/docs/evidence consistency, and release gates. - codex-review: passed Codex subagent Turing independently reviewed the status client summary and found the HTML storage-path disclosure edge; Codex fixed it before release. - claude-review: passed Claude Code Opus 4.8 high read-on… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`release-evidence/v3.40.0.md`

## 证据索引

- 共索引 73 条证据。

- **piia-engram**（documentation）：One memory. Every AI tool. Yours to keep. 证据：`README.md`
- **Release evidence**（documentation）：Each release must have a v .md file here recording that the mandatory pre-release gates passed. The publish workflow runs scripts/check release gate.py , which fails the publish job unless the matching file exists and is complete — so the gate cannot be skipped, even if someone forgets the process. 证据：`release-evidence/README.md`
- **piia-engram — Architecture**（documentation）：This document describes how piia-engram is structured internally, why the structure exists, and where each piece lives. 证据：`docs/architecture.md`
- **Engram vs. other memory / identity tools**（documentation）：Engram vs. other memory / identity tools 证据：`docs/comparison.md`
- **Contributing to piia-engram**（documentation）：Thanks for considering a contribution to piia-engram — the AI identity layer that stores who you are, not just what you did. 证据：`CONTRIBUTING.md`
- **Plugin**（structured_config）：{ "name": "piia-engram", "version": "3.40.0", "description": "Cross-tool personal identity layer. Stores your profile, preferences, lessons, and decisions as local JSON — every AI tool Claude Code, Cursor, Codex, Windsurf, any MCP client reads the same memory. AI proposes knowledge; you approve what becomes permanent. Local-first, no cloud, no account.", "author": { "name": "Engram Contributors", "url": "https://github.com/Patdolitse/piia-engram" }, "homepage": "https://github.com/Patdolitse/piia-engram", "license": "Apache-2.0", "keywords": "memory", "identity", "cross-tool", "local-first", "mcp", "knowledge-management", "claude-code", "cursor", "codex" } 证据：`.claude-plugin/plugin.json`
- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`
- **Privacy & Data Practices**（documentation）：piia-engram is a local-first tool. Your identity, preferences, lessons, and decisions are stored as plain JSON files on your machine. This document describes exactly what data piia-engram handles and how. 证据：`PRIVACY.md`
- **piia-engram**（documentation）：告诉 AI 一次——你的偏好、标准和经验会跟随你到 Claude Code、Cursor、Codex 等所有 MCP 工具。AI 提议知识，你决定什么留下。本地存储，无云端，无账号。 证据：`README.zh-CN.md`
- **Engram Cross-Tool & Cross-Session Usage Guide**（documentation）：Engram Cross-Tool & Cross-Session Usage Guide 证据：`docs/cross-tool-guide.md`
- **Agent Governance**（documentation）：Engram is local-first memory for AI tools. The governance layer is an optional runtime boundary for deciding what a calling agent may read, which write-like operations it may perform, and what disclosures were made. 证据：`docs/governance.md`
- **Hybrid Search optional**（documentation）：Status: opt-in, off by default. The default search behavior is unchanged keyword . Turn this on only if you want it. 证据：`docs/hybrid-search.md`
- **GUI Entry Doctor Probe Implementation Plan**（documentation）：GUI Entry Doctor Probe Implementation Plan 证据：`docs/superpowers/plans/2026-05-30-gui-entry-doctor-probe.md`
- **v3.40 First-Run Confidence Implementation Plan**（documentation）：v3.40 First-Run Confidence Implementation Plan 证据：`docs/superpowers/plans/2026-05-30-v340-first-run-confidence.md`
- **GUI Entry Doctor Probe Design**（documentation）：Goal: Make engram doctor verify whether GUI MCP client entries can launch the new piia-engram-mcp entry point, without turning setup into a broad rewrite. 证据：`docs/superpowers/specs/2026-05-30-gui-entry-doctor-probe-design.md`
- **v3.40 First-Run Confidence And Visual Trust Design**（documentation）：v3.40 First-Run Confidence And Visual Trust Design 证据：`docs/superpowers/specs/2026-05-30-v340-first-run-confidence-design.md`
- **Server**（structured_config）：{ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.Patdolitse/piia-engram", "description": "One memory, every AI tool, yours to keep. Local-first, cross-tool, MCP-native.", "repository": { "url": "https://github.com/Patdolitse/piia-engram", "source": "github" }, "version": "3.40.0", "packages": { "registryType": "pypi", "identifier": "piia-engram", "version": "3.40.0", "transport": { "type": "stdio" } } } 证据：`.mcp/server.json`
- **Profile.Example**（structured_config）：{ "role": "软件工程师", "language": "中文", "technical level": "中级，3年Python经验", "description": "全栈开发者，专注后端和DevOps。", "updated at": "2026-01-01T00:00:00" } 证据：`examples/engram/identity/profile.example.json`
- **Decisions.Example**（structured_config）：{ "question": "Engram用什么协议暴露给外部", "choice": "MCP Model Context Protocol ", "reasoning": "MCP已成为行业标准，所有主流AI工具都支持", "source tool": "claude code", "timestamp": "2026-01-01T00:00:00" } 证据：`examples/engram/knowledge/decisions.example.json`
- **Lessons.Example**（structured_config）：{ "summary": "Windows上python命令可能是商店stub，用完整路径更可靠", "detail": "", "domain": "python", "source tool": "claude code", "timestamp": "2026-01-01T00:00:00" } 证据：`examples/engram/knowledge/lessons.example.json`
- **只显示前30行**（source_file）：TOOLS DIR = Path file .resolve .parent.parent / "src" / "piia engram" ⋮---- def print section title: str ⋮---- def demo without engram ⋮---- def demo with engram ⋮---- engram = Engram context = engram.generate context ⋮---- def demo cross tool knowledge ⋮---- stats = engram.get stats lessons = engram.get lessons limit=5 decisions = engram.get decisions limit=3 ⋮---- tool = l.get "source tool", "未标记" ⋮---- tool = d.get "source tool", "未标记" ⋮---- def demo identity card ⋮---- """展示可携带身份卡。""" ⋮---- card = engram.export identity card ⋮---- 只显示前30行 lines = card.split "\n" :30 ⋮---- def demo schema v2 ⋮---- """展示 v2.0 新功能。""" ⋮---- prefs = engram.get preferences tool prefs = prefs.get "tool prefer… 证据：`demos/cross_tool_demo.py`
- **piia-engram 一键安装脚本 Windows PowerShell**（source_file）：piia-engram 一键安装脚本 Windows PowerShell 用法: irm https://raw.githubusercontent.com/Patdolitse/piia-engram/main/install.ps1 iex 证据：`install.ps1`
- **检测 Python 3.10+**（source_file）：set -e echo "" echo "========================================" echo " piia-engram 安装程序 Mac/Linux " echo "========================================" echo "" 检测 Python 3.10+ PYTHON="" for cmd in python3 python; do if command -v "$cmd" & /dev/null; then version=$ "$cmd" -c "import sys; print sys.version info = 3,10 " 2 /dev/null true if "$version" = "True" ; then PYTHON="$cmd" break fi fi done if -z "$PYTHON" ; then echo "❌ 未找到 Python 3.10+。" echo "" if command -v brew & /dev/null; then echo " 请运行: brew install python" else echo " 请访问: https://python.org/downloads/" fi exit 1 fi echo "✅ Python: $ $PYTHON --version " echo "" echo "正在安装 Engram..." $PYTHON -m pip install --upgrade piia-engram echo… 证据：`install.sh`
- **MCP server entry point — lets any client launch via piia-engram-mcp or**（source_file）：project name = "piia-engram" version = "3.40.0" description = "One memory, every AI tool, yours to keep — your preferences, standards, and lessons follow you across Claude Code, Cursor, Codex, and any MCP tool. Local-first, no cloud, no account." readme = "README.md" license = "Apache-2.0" requires-python = " =3.10" authors = {name = "Engram Contributors"}, keywords = "ai", "identity", "mcp", "memory", "persistent-memory", "personal-knowledge", "llm", "context", "claude-code", "cursor", "codex", "mcp-server", "ai-agent", "local-first", "cross-tool", "cross-session", "developer-preferences", "user-profile", "knowledge-management", "vibe-coding" classifiers = "Development Status :: 4 - Beta",… 证据：`pyproject.toml`
- **Auto Save On Stop**（source_file）：engram src = Path file .resolve .parent.parent / "src" 证据：`scripts/auto_save_on_stop.py`
- **Schema**（source_file）：CREATE TABLE IF NOT EXISTS events id INTEGER PRIMARY KEY AUTOINCREMENT, received TEXT NOT NULL DEFAULT datetime 'now' , daily id TEXT NOT NULL, version TEXT NOT NULL DEFAULT '', -- engram version e.g. "3.23.0" tool calls TEXT NOT NULL DEFAULT '{}', -- JSON {tool: {success:N, error:N}} knowledge TEXT NOT NULL DEFAULT '{}', -- JSON {lessons:N, decisions:N, domains:N} os TEXT NOT NULL DEFAULT '', -- win32 / darwin / linux py TEXT NOT NULL DEFAULT '', -- "3.12" major.minor only tier TEXT NOT NULL DEFAULT 'core', schema v INTEGER NOT NULL DEFAULT 1 ; CREATE INDEX IF NOT EXISTS idx received ON events received ; CREATE INDEX IF NOT EXISTS idx daily id ON events daily id ; CREATE INDEX IF NOT EXIST… 证据：`worker/schema.sql`
- **------------------------------------------------------------------**（source_file）：logger = logging.getLogger name ⋮---- class ContextMixin ⋮---- @staticmethod def estimate tokens text: str - int ⋮---- cjk = sum 1 for c in text if "\u4e00" str ⋮---- """Infer domain s from text. Returns comma-separated if multiple match.""" text lower = text.lower matched = ⋮---- def has content chars self, text: str - bool ⋮---- ------------------------------------------------------------------ Free-form ingestion ⋮---- def ingest notes self, text: str, source tool: str = "", domain: str = "" - dict ⋮---- """Parse free-form notes and extract lesson/decision candidates.""" lines = text.splitlines saved lessons = saved decisions = duplicates = skipped = 0 results = ⋮---- line = raw line.str… 证据：`src/piia_engram/context.py`
- **Corpus encryption key derived once, reused for all entry I/O**（source_file）：logger = logging.getLogger name ⋮---- class Engram RetrievalMixin, ContextMixin, ReconcileMixin, ReportsMixin, ContextStoreMixin ⋮---- def init self, root: Path None = None ⋮---- secret = os.environ.get "ENGRAM SECRET", "" .strip ⋮---- Corpus encryption key derived once, reused for all entry I/O ⋮---- salt path = self.root / ".corpus salt" ⋮---- salt = salt path.read bytes ⋮---- salt = os.urandom 16 ⋮---- A plaintext hybrid search index left over from a pre-encryption run would keep the decrypted bodies readable on disk even though all new writes are encrypted. Purge it on init so enabling encryption can't be silently undermined by a stale index Codex a5 round-2 P1-2 . purge search index is… 证据：`src/piia_engram/core.py`
- **Corpus key cache derived once, reused for all entry encrypt/decrypt**（source_file）：logger = logging.getLogger name ⋮---- class DecryptionError Exception ⋮---- ENC PREFIX V1 = "enc:v1:" ENC PREFIX V2 = "enc:v2:" ENC PREFIX V2C = "enc:v2c:" ENC PREFIX = ENC PREFIX V2 ENC PREFIXES = ENC PREFIX V2C, ENC PREFIX V2, ENC PREFIX V1 ⋮---- PBKDF2 ITERATIONS V1 = 100 000 PBKDF2 ITERATIONS V2 = 600 000 ⋮---- HAS CRYPTO = True ⋮---- HAS CRYPTO = False ⋮---- def derive key secret: str, salt: bytes, iterations: int = PBKDF2 ITERATIONS V2 - bytes ⋮---- def starts with enc prefix value: str - bool ⋮---- class EncryptionEngine ⋮---- def init self, secret: str None = None ⋮---- Corpus key cache derived once, reused for all entry encrypt/decrypt ⋮---- def encrypt self, value: str - str ⋮----… 证据：`src/piia_engram/crypto.py`
- **Decision Thread**（source_file）：RELATION TYPES = "led to", "supersedes", "implemented by" ⋮---- FORWARD = frozenset {"led to", "implemented by"} ⋮---- def validate edges edges: Iterable dict - list dict ⋮---- out: list dict = ⋮---- rel = str e.get "rel", "" .strip src = e.get "src" dst = e.get "dst" ⋮---- def forward pairs node ids: set str , edges: list dict - set tuple str, str ⋮---- nodes = set node ids pairs: set tuple str, str = set ⋮---- def undirected adj edges: list dict - dict str, set str ⋮---- adj: dict str, set str = defaultdict set ⋮---- def connected component seed id: str, edges: list dict - set str ⋮---- seed id = str seed id adj = undirected adj edges ⋮---- seen = {seed id} q = deque seed id ⋮---- n = q.p… 证据：`src/piia_engram/decision_thread.py`
- **Skip trivially short sessions. Threshold is env-configurable so**（source_file）：def apply argv env argv: list str - None ⋮---- i = 0 ⋮---- pair = argv i + 1 ⋮---- key = key.strip ⋮---- def flush threshold - int ⋮---- raw = os.environ.get "ENGRAM MIN TURNS TO FLUSH", "10" ⋮---- def main - None ⋮---- raw = sys.stdin.read ⋮---- hook input = json.loads raw ⋮---- cwd = hook input.get "cwd", "" transcript path = hook input.get "transcript path", "" session id raw = hook input.get "session id", "" ⋮---- msg count = 0 tool calls: list str = first ts = "" last ts = "" ⋮---- line = line.strip ⋮---- entry = json.loads line ⋮---- ts = entry.get "timestamp", "" ⋮---- first ts = ts ⋮---- last ts = ts ⋮---- name = entry.get "name", "" ⋮---- name = block.get "name", "" ⋮---- Skip triv… 证据：`src/piia_engram/hooks/auto_save_on_stop.py`
- **Time-based heartbeat v3.30 mechanism 2 :**（source_file）：logger = logging.getLogger name ⋮---- def configure utf8 stdio - None ⋮---- stream = getattr sys, stream name, None reconfigure = getattr stream, "reconfigure", None ⋮---- HAS STARLETTE = True ⋮---- HAS STARLETTE = False ⋮---- TOOLS DIR = Path file .resolve .parent ⋮---- engram = Engram ⋮---- ToolCallTracker = None ⋮---- tracker = ToolCallTracker if ToolCallTracker else None track count = 0 FLUSH EVERY = 10 ⋮---- def flush telemetry force: bool = False - None ⋮---- ver = pkg version "piia-engram" ⋮---- ver = "dev" tier = os.environ.get "ENGRAM TOOLS", "core" ⋮---- class SessionTracker ⋮---- COLD START TOOLS = frozenset { ⋮---- MIN CALLS = 2 ⋮---- CHECKPOINT EVERY = 20 DEFAULT HEARTBEAT INTE… 证据：`src/piia_engram/mcp_server.py`
- **Also include decision texts for dedup**（source_file）：class ReconcileMixin ⋮---- CLAUDE MEMORY GLOBS = ⋮---- RECONCILE MAX FILE SIZE = 10 240 ⋮---- AI CONFIG FILENAMES = ⋮---- AI GLOBAL CONFIGS = ⋮---- @staticmethod def reconcile authorized - bool ⋮---- env = os.environ.get "ENGRAM RECONCILE", "" .strip .lower ⋮---- cfg path = Path os.environ.get "ENGRAM DIR", "" .strip or ⋮---- cfg = json.loads cfg path.read text encoding="utf-8" ⋮---- def reconcile memories self - dict ⋮---- imported = 0 duplicates = 0 scanned files = 0 skipped large = 0 sources: list str = ⋮---- existing lessons = self.get lessons limit=None, update access=False existing decisions = self.get decisions limit=None, update access=False existing summaries = { Also include decis… 证据：`src/piia_engram/reconcile.py`
- **------------------------------------------------------------------**（source_file）：class RetrievalMixin ⋮---- PROMOTE ACCESS COUNT = 3 ⋮---- def evaluate tiers self - dict ⋮---- promoted = 0 ⋮---- path = self. knowledge dir / path name entries = self. read entries path, entry type ⋮---- changed = False ⋮---- tier = entry.get "tier", "verified" ⋮---- access = entry.get "access count", 0 ⋮---- changed = True ⋮---- def get staging summary self - dict ⋮---- lessons = self. read entries self. knowledge dir / "lessons.json", "lesson" decisions = self. read entries self. knowledge dir / "decisions.json", "decision" staging lessons = staging decisions = staging playbooks = ⋮---- pb = self. read playbook by id idx entry.get "id", "" ⋮---- all staging = staging lessons + staging de… 证据：`src/piia_engram/retrieval.py`
- **---------------------------------------------------------------------------**（source_file）：logger = logging.getLogger name ⋮---- LEGACY SERVER NAMES = "piia-pkc", "piia pkc", "piia-pkc-mcp" ⋮---- lang = "zh" ⋮---- def safe print text: str - None ⋮---- enc = sys.stdout.encoding or "ascii" safe = text.encode enc, errors="ignore" .decode enc ⋮---- def is utf8 encoding encoding: str None - bool ⋮---- name = encoding or "" .strip .lower .replace " ", "-" ⋮---- stdout encoding = stdout encoding if stdout encoding is not None else sys.stdout.encoding stderr encoding = stderr encoding if stderr encoding is not None else sys.stderr.encoding preferred encoding = filesystem encoding = pythonioencoding = ⋮---- stdout label = stdout encoding or "unknown" stderr label = stderr encoding or "unk… 证据：`src/piia_engram/setup_wizard.py`
- **---------------------------------------------------------------------------**（source_file）：logger = logging.getLogger name ⋮---- SCHEMA VERSION = "2.0" ENGRAM DIR NAME = ".engram" LEGACY DIR NAME = ".piia" SIMILARITY THRESHOLD = 0.55 SIMILARITY DUPLICATE THRESHOLD = 0.95 ⋮---- SUPPLEMENT MARKERS = frozenset { SEARCH RELEVANCE THRESHOLD = 0.3 ⋮---- HYBRID RELEVANCE THRESHOLD = 0.0 STALE KNOWLEDGE DAYS = 30 ⋮---- STALE DECAY MULTIPLIERS: dict str, float = { MAX KNOWLEDGE ENTRIES = 200 CONFLICT Q THRESHOLD = 0.25 CONFLICT C CEILING = 0.80 ⋮---- NEGATION MARKERS = frozenset { AFFIRMATION MARKERS = frozenset { ⋮---- ENCRYPTED PROFILE FIELDS: set str = { ⋮---- ALLOWED PROFILE FIELDS: frozenset = frozenset { ALLOWED PREFERENCES FIELDS: frozenset = frozenset { ALLOWED TRUST FIELDS: froze… 证据：`src/piia_engram/storage.py`
- **Index**（source_file）：async function hashPassword password, salt ⋮---- function getSessionFromCookie request ⋮---- async function isAuthenticated request, env ⋮---- function renderLogin error = '' ⋮---- // --- 校验 --- ⋮---- function validatePayload data ⋮---- function validateFeedback data ⋮---- async function handleFeedback request, env ⋮---- async function handleEvent request, env ⋮---- async function fetchPypiStats ⋮---- async function getStatsData env ⋮---- function aggregateTools rows ⋮---- function renderDashboard stats ⋮---- const label = d.date.slice 5 ; // MM-DD ⋮---- // 每月汇总表 ⋮---- // 工具使用表生成器 function toolTable tools, emptyMsg ⋮---- // 版本标签 ⋮---- // 操作系统标签 ⋮---- // --- 路由 --- ⋮---- async fetch request,… 证据：`worker/src/index.js`
- **Changelog**（documentation）：English CHANGELOG.md 中文 CHANGELOG.zh-CN.md 证据：`CHANGELOG.md`
- **更新日志**（documentation）：English CHANGELOG.md 中文 CHANGELOG.zh-CN.md 证据：`CHANGELOG.zh-CN.md`
- **Security Policy**（documentation）：Version Supported --------- ----------- 3.x Yes < 3.0 No 证据：`SECURITY.md`
- **Release evidence — v3.33.2**（documentation）：- self-review: passed - codex-review: passed round-2, commit dcd8621 — all 6 round-1 findings verified fixed, no regressions - tests: pass full suite 1022 passed - eval-gate: pass round11 keyword-vs-hybrid: G1/G2/G3 all PASS REG recall 1.00- 1.00, XLING 0.50- 0.875 证据：`release-evidence/v3.33.2.md`
- **Release evidence — v3.34.0**（documentation）：- self-review: passed - codex-review: passed R20 PASS — a0 read-path full cutover verified, universal harness covers all 41 governed tools - tests: pass full suite 1385 passed, governance matrix 215 passed - eval-gate: n/a no retrieval algorithm change in this release 证据：`release-evidence/v3.34.0.md`
- **Release Evidence — v3.35.0**（documentation）：- self-review: passed - codex-review: passed additive features only c1+c2+a0 , self-reviewed, no security-critical changes - tests: pass full suite 1439 passed, governance matrix 220 passed - eval-gate: n/a no retrieval algorithm change - negative-control: n/a R1: no security-sensitive change in this release - field-assertion-audit: n/a R5: no security-sensitive module touched 证据：`release-evidence/v3.35.0.md`
- **Release Evidence — v3.36.0**（documentation）：- self-review: passed - codex-review: passed independent Codex audits across the release scope: a5 corpus encryption 3 rounds, all FAIL findings closed , governance read-path Round 8 side-effect sweep + Round 9 structural closure — all returned PASS / PASS-WITH-FIXES, fixes strong-verified - tests: pass full suite 1718 passed, governance write-gate matrix 166 passed - eval-gate: n/a no retrieval/quality algorithm change hybrid index suppressed under corpus encryption, not re-ranked - negative-control: passed R1: read-path closure — 3 revert-to-RED proofs independently reproduced audit fail-open writes audit.log; track fail-open writes contexts+telemetry.log; track gate removed fails 28/30 s… 证据：`release-evidence/v3.36.0.md`
- **Release Evidence — v3.37.0**（documentation）：- self-review: passed - codex-review: passed Codex reviewed the distribution/onboarding entry-point change; no security-sensitive or retrieval-quality logic changed - tests: pass full suite 1720 passed; packaging/setup wizard targeted suite 169 passed; local wheel smoke verified piia-engram-mcp entry point - sanitize: passed working-tree internal strict scan high=0 warn=0; commit-message internal strict has 16 historical warn-level hits from old messages, high=0 and no current release artifact hit, so no filter-repo rewrite for v3.37.0 - eval-gate: n/a no retrieval/quality algorithm change - negative-control: n/a R1: not a security-sensitive behavior change; entry-point/config tests were st… 证据：`release-evidence/v3.37.0.md`
- **Release Evidence - v3.38.0**（documentation）：- self-review: passed - codex-review: passed Claude independent review passed; see Engram v3.38.0 EncodingHardening Claude Independent Review Report.md. - tests: pass Full suite 1742 passed, 4 expected engram core deprecation warnings; targeted encoding/setup/MCP stdio/package/release-gate suite 205 passed; local wheel built as piia engram-3.38.0-py3-none-any.whl. - sanitize: passed scripts/release sanitize check.py returned high=0 warn=0. - eval-gate: n/a No retrieval or quality-ranking algorithm changed. - negative-control: passed R1: pre-fix behavior failed the new encoding repair, write-boundary normalization, and MCP stdio UTF-8 tests. - field-assertion-audit: n/a No security-sensitive… 证据：`release-evidence/v3.38.0.md`
- **Release Evidence - v3.39.0**（documentation）：- self-review: passed Codex local release-prep sweep: version/docs/evidence consistency, publish allowlist, sanitize, package build, and full pytest. - codex-review: passed Claude read-only independent reviews passed for sessions continuity CLI, staging review CLI, docs/tool-count consistency, and privacy layout examples. - tests: pass Full suite 1762 passed, 4 expected engram core deprecation warnings; targeted packaging/review/setup suites passed; local wheel/sdist build passed. - sanitize: passed scripts/release sanitize check.py --internal --strict returned high=0 warn=0. - eval-gate: n/a No retrieval, ranking, or quality-evaluation algorithm changed. - negative-control: n/a No security… 证据：`release-evidence/v3.39.0.md`
- **Release Evidence - v3.39.1**（documentation）：- self-review: passed Codex reviewed the diff, verified doctor failure semantics stay informational, and confirmed docs/version/evidence consistency. - codex-review: passed Claude Code read-only independent review PASS for terminal encoding diagnostics, cp65001 handling, tests, and docs. - tests: pass Full suite 1767 passed, 4 expected engram core deprecation warnings; targeted setup/encoding/packaging/release suites passed. - sanitize: passed scripts/release sanitize check.py --internal --strict returned high=0 warn=0. - eval-gate: n/a No retrieval, ranking, search, or quality-evaluation algorithm changed. - negative-control: n/a No security-sensitive governance/encryption behavior changed… 证据：`release-evidence/v3.39.1.md`
- **Release Evidence - v3.40.0**（documentation）：- self-review: passed Codex implemented and reviewed the first-run status completion diff, HTML redaction fix, sanitize ASCII output, version/docs/evidence consistency, and release gates. - codex-review: passed Codex subagent Turing independently reviewed the status client summary and found the HTML storage-path disclosure edge; Codex fixed it before release. - claude-review: passed Claude Code Opus 4.8 high read-only acceptance review PASS for MCP client summary redaction, HTML path redaction, sanitize ASCII output, tests, and publish risk. - tests: passed Full suite 1781 passed, 4 expected engram core deprecation warnings; targeted setup/packaging/sanitize/release-gate suites 243 passed.… 证据：`release-evidence/v3.40.0.md`
- **.Mcp**（structured_config）：{ "engram": { "command": "uvx", "args": "--from", "piia-engram", "python", "-m", "piia engram.mcp server" } } 证据：`.mcp.json`
- **Claude Mcp.Example**（structured_config）：{ "mcpServers": { "engram": { "command": " ", "args": " /engram/src/piia engram/mcp server.py" } } } 证据：`examples/claude_mcp.example.json`
- **Glama**（structured_config）：{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": "Patdolitse" } 证据：`glama.json`
- **Preferences.Example**（structured_config）：{ "work patterns": { "语言": "所有沟通使用中文", "代码风格": "实用为主", "开发节奏": "快速迭代" }, "communication": "直接简洁", "tool preferences": { "编码": "Claude Code", "设计": "Figma" }, "updated at": "2026-01-01T00:00:00" } 证据：`examples/engram/identity/preferences.example.json`
- **Quality Standards.Example**（structured_config）：{ "acceptance threshold": 3, "rules": "编译必须通过", "测试必须通过", "功能必须可运行" , "updated at": "2026-01-01T00:00:00" } 证据：`examples/engram/identity/quality_standards.example.json`
- **Trust Boundaries.Example**（structured_config）：{ "default sharing": "full", "tool access": {}, "private fields": , "notes": "默认所有工具可访问全部Engram数据。可按工具或字段限制。", "updated at": "2026-01-01T00:00:00" } 证据：`examples/engram/identity/trust_boundaries.example.json`
- **Domains.Example**（structured_config）：{"python": 5, "frontend": 2, "devops": 1} 证据：`examples/engram/knowledge/domains.example.json`
- **Example Project**（structured_config）：{ "title": "示例项目", "tech stack": "python", "fastapi" , "known issues": "部署脚本需要更新" , "notes": "MVP阶段", "updated at": "2026-01-01T00:00:00" } 证据：`examples/engram/projects/example_project.json`
- **Schema Version.Example**（structured_config）：{"schema version": "2.0", "migrated at": "2026-01-01T00:00:00"} 证据：`examples/engram/schema_version.example.json`
- **Pragmas / lines to exclude from coverage**（source_file）：run source = src/piia engram branch = false 证据：`.coveragerc`
- **Python**（source_file）：Python pycache / .pytest cache/ .py cod .egg-info/ dist/ build/ .eggs/ 证据：`.gitignore`
- 其余 13 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。

## 宿主 AI 必须遵守的规则

- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `release-evidence/README.md`, `docs/architecture.md`
- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `release-evidence/README.md`, `docs/architecture.md`

## 用户开工前应该回答的问题

- 你准备在哪个宿主 AI 或本地环境中使用它？
- 你只是想先体验工作流，还是准备真实安装？
- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？

## 验收标准

- 所有能力声明都能回指到 evidence_refs 中的文件路径。
- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。
- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。

---

## Doramagic Context Augmentation

下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。

## Human Manual 骨架

使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。

宿主 AI 硬性规则：
- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。
- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。
- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。

- **项目概览**：importance `high`
  - source_paths: README.md, README.zh-CN.md, docs/comparison.md
- **快速开始 (30秒)**：importance `high`
  - source_paths: README.md, src/piia_engram/setup_wizard.py, install.sh, install.ps1
- **安装配置详解**：importance `high`
  - source_paths: README.md, src/piia_engram/setup_wizard.py, pyproject.toml, .mcp/server.json
- **系统架构**：importance `high`
  - source_paths: docs/architecture.md, src/piia_engram/core.py, src/piia_engram/mcp_server.py, src/piia_engram/storage.py
- **数据布局与存储**：importance `high`
  - source_paths: README.md, src/piia_engram/storage.py, examples/engram/identity/profile.example.json, examples/engram/knowledge/lessons.example.json, examples/engram/knowledge/decisions.example.json
- **MCP协议集成**：importance `high`
  - source_paths: src/piia_engram/mcp_server.py, .mcp/server.json, src/piia_engram/crypto.py, PRIVACY.md
- **MCP工具详解**：importance `high`
  - source_paths: README.md, src/piia_engram/retrieval.py, src/piia_engram/context.py, src/piia_engram/decision_thread.py
- **知识管理功能**：importance `medium`
  - source_paths: src/piia_engram/retrieval.py, src/piia_engram/reconcile.py, src/piia_engram/reports*.py, src/piia_engram/governance*.py

## Repo Inspection Evidence / 源码检查证据

- repo_clone_verified: true
- repo_inspection_verified: true
- repo_commit: `0753eaaf7e8bb4d6dc7e2f3a84415e098903522b`
- inspected_files: `pyproject.toml`, `Dockerfile`, `README.md`, `docs/architecture.md`, `docs/governance.md`, `docs/cross-tool-guide.md`, `docs/comparison.md`, `docs/hybrid-search.md`, `docs/superpowers/specs/2026-05-30-gui-entry-doctor-probe-design.md`, `docs/superpowers/specs/2026-05-30-v340-first-run-confidence-design.md`, `docs/superpowers/plans/2026-05-30-gui-entry-doctor-probe.md`, `docs/superpowers/plans/2026-05-30-v340-first-run-confidence.md`, `examples/claude_mcp.example.json`, `examples/engram/schema_version.example.json`, `examples/engram/identity/trust_boundaries.example.json`, `examples/engram/identity/preferences.example.json`, `examples/engram/identity/quality_standards.example.json`, `examples/engram/identity/profile.example.json`, `examples/engram/projects/example_project.json`, `examples/engram/knowledge/domains.example.json`

宿主 AI 硬性规则：
- 没有 repo_clone_verified=true 时，不得声称已经读过源码。
- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。
- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。

## Doramagic Pitfall Constraints / 踩坑约束

这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。

### Constraint 1: 失败模式：installation: v3.34.0 — Governance cutover + Universal harness + Playbook policy

- Trigger: Developers should check this installation risk before relying on the project: v3.34.0 — Governance cutover + Universal harness + Playbook policy
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v3.34.0 — Governance cutover + Universal harness + Playbook policy. Context: Observed when using python
- Why it matters: Upgrade or migration may change expected behavior: v3.34.0 — Governance cutover + Universal harness + Playbook policy
- Evidence: failure_mode_cluster:github_release | fmev_76925401e068c1b5f3b688fe03df685f | https://github.com/Patdolitse/piia-engram/releases/tag/v3.34.0 | v3.34.0 — Governance cutover + Universal harness + Playbook policy
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 2: 失败模式：installation: v3.35.0 — Decision Threads & Permission Profile

- Trigger: Developers should check this installation risk before relying on the project: v3.35.0 — Decision Threads & Permission Profile
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v3.35.0 — Decision Threads & Permission Profile. Context: Observed when using python
- Why it matters: Upgrade or migration may change expected behavior: v3.35.0 — Decision Threads & Permission Profile
- Evidence: failure_mode_cluster:github_release | fmev_77e4f97aad82e83fe9ef3312294eec6b | https://github.com/Patdolitse/piia-engram/releases/tag/v3.35.0 | v3.35.0 — Decision Threads & Permission Profile
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 3: 失败模式：installation: v3.37.0 - GUI entry adoption: piia-engram-mcp + uvx

- Trigger: Developers should check this installation risk before relying on the project: v3.37.0 - GUI entry adoption: piia-engram-mcp + uvx
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v3.37.0 - GUI entry adoption: piia-engram-mcp + uvx. Context: Observed during installation or first-run setup.
- Why it matters: Upgrade or migration may change expected behavior: v3.37.0 - GUI entry adoption: piia-engram-mcp + uvx
- Evidence: failure_mode_cluster:github_release | fmev_75eede3829cc5d9e70aae6672a96605c | https://github.com/Patdolitse/piia-engram/releases/tag/v3.37.0 | v3.37.0 - GUI entry adoption: piia-engram-mcp + uvx
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 4: 失败模式：installation: v3.39.0 - Local Workflow Visibility

- Trigger: Developers should check this installation risk before relying on the project: v3.39.0 - Local Workflow Visibility
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v3.39.0 - Local Workflow Visibility. Context: Observed during installation or first-run setup.
- Why it matters: Upgrade or migration may change expected behavior: v3.39.0 - Local Workflow Visibility
- Evidence: failure_mode_cluster:github_release | fmev_500227db57a8529c37cfce701ae84bdc | https://github.com/Patdolitse/piia-engram/releases/tag/v3.39.0 | v3.39.0 - Local Workflow Visibility
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 5: 可能修改宿主 AI 配置

- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。
- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- Evidence: capability.host_targets | github_repo:1242620513 | https://github.com/Patdolitse/piia-engram | host_targets=mcp_host, claude, claude_code
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 6: 失败模式：configuration: v3.38.0 - Encoding repair guardrails

- Trigger: Developers should check this configuration risk before relying on the project: v3.38.0 - Encoding repair guardrails
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v3.38.0 - Encoding repair guardrails. Context: Observed when using windows
- Why it matters: Upgrade or migration may change expected behavior: v3.38.0 - Encoding repair guardrails
- Evidence: failure_mode_cluster:github_release | fmev_42be567d8e4b76432faa58f51baccf59 | https://github.com/Patdolitse/piia-engram/releases/tag/v3.38.0 | v3.38.0 - Encoding repair guardrails
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 7: 失败模式：configuration: v3.40.0 - First-run confidence

- Trigger: Developers should check this configuration risk before relying on the project: v3.40.0 - First-run confidence
- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v3.40.0 - First-run confidence. Context: Observed during installation or first-run setup.
- Why it matters: Upgrade or migration may change expected behavior: v3.40.0 - First-run confidence
- Evidence: failure_mode_cluster:github_release | fmev_e8bb2627f41868837723a394026965a3 | https://github.com/Patdolitse/piia-engram/releases/tag/v3.40.0 | v3.40.0 - First-run confidence
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 8: 能力判断依赖假设

- Trigger: README/documentation is current enough for a first validation pass.
- Host AI rule: 将假设转成下游验证清单。
- Why it matters: 假设不成立时，用户拿不到承诺的能力。
- Evidence: capability.assumptions | github_repo:1242620513 | https://github.com/Patdolitse/piia-engram | README/documentation is current enough for a first validation pass.
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 9: 维护活跃度未知

- Trigger: 未记录 last_activity_observed。
- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。
- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- Evidence: evidence.maintainer_signals | github_repo:1242620513 | https://github.com/Patdolitse/piia-engram | last_activity_observed missing
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。

### Constraint 10: 下游验证发现风险项

- Trigger: no_demo
- Host AI rule: 进入安全/权限治理复核队列。
- Why it matters: 下游已经要求复核，不能在页面中弱化。
- Evidence: downstream_validation.risk_items | github_repo:1242620513 | https://github.com/Patdolitse/piia-engram | no_demo; severity=medium
- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。