简介

Piia Engram（又称 Engram Memory MCP）是一个专为 AI 开发者设计的本地化记忆管理工具，旨在帮助 AI 助手在会话过程中持久化存储和检索重要信息。该项目基于 MCP（Model Context Protocol）协议实现，为开发者提供了一个可靠的上下文记忆解决方案。

Engram 的核心价值在于将 AI 会话中的关键信息持久化保存，使得 AI 助手能够在多次对话中保持上下文连续性。它支持本地存储、灵活的上下文管理以及与多种 AI 客户端的无缝集成。

核心功能

Engram 提供以下核心功能：

系统架构

Engram 采用模块化设计，主要包含以下组件：

graph TD
    A[MCP 客户端] --> B[Engram MCP Server]
    B --> C[记忆存储层]
    C --> D[SQLite 本地数据库]
    
    B --> E[检索引擎]
    E --> F[语义相似度计算]
    
    G[CLI 工具] --> B
    G --> H[engram status]
    G --> I[engram doctor]
    G --> J[engram sessions]
    G --> K[engram review]
    
    L[配置文件] --> B

组件说明

技术栈

安装方式

Engram 支持多种安装方式以适应不同的开发环境：

前提条件

• Node.js 18.0 或更高版本
• npm、pnpm 或 yarn 包管理器

安装命令

# 使用 npm 安装
npm install -g @piia/engram

# 使用 pnpm 安装
pnpm add -g @piia/engram

# 使用 yarn 安装
yarn global add @piia/engram

资料来源：docs/installation.md

快速开始

1. 初始化配置

安装完成后，运行以下命令初始化 Engram：

engram init

2. 配置 MCP 客户端

在 AI 客户端（如 Claude Desktop、Cline 等）中配置 MCP 服务器连接：

{
  "mcpServers": {
    "engram": {
      "command": "engram-mcp",
      "args": ["--port", "3000"]
    }
  }
}

3. 验证安装

使用内置的状态检查命令验证配置：

engram status

资料来源：docs/usage.md, README.md

配置选项

Engram 支持通过配置文件进行自定义配置：

资料来源：docs/configuration.md

命令行工具

Engram 提供丰富的命令行工具用于管理和诊断：

资料来源：README.md, v3.40.0 Release Notes

与其他工具对比

Engram 在 AI 记忆管理领域有其独特定位：

资料来源：docs/comparison.md

常见问题

首次运行问题

问题：首次运行时不确定系统状态是否正确配置。

解决方案：在 v3.40.0 及更高版本中，engram status 命令会自动汇总 MCP 客户端配置健康状态，并只显示脱敏后的元数据，确保首次运行更加清晰和安全。

MCP 客户端连接问题

问题：AI 客户端无法连接到 Engram MCP 服务器。

排查步骤：

1. 运行 engram doctor 进行系统诊断
2. 检查 MCP 配置文件中的端口和地址设置
3. 确认防火墙未阻止本地连接

数据存储问题

问题：记忆存储达到上限。

解决方案：调整 storage.maxSize 配置项，或使用 engram review 命令清理不重要的记忆内容。

版本历史

资料来源：v3.40.0 Release Notes, README.md

社区与支持

• GitHub Issues：用于报告 bug 和请求功能
• 讨论区：与其他开发者交流使用经验
• 文档：完整的英文和中文文档支持

如有关于项目合作或 API 服务集成的需求，可在 GitHub Issues 中发起讨论。

相关链接

• 安装指南
• 使用教程
• 配置参考
• API 文档
• 工具对比
• GitHub 仓库

概述

Piia Engram 是一个本地化的记忆 MCP (Model Context Protocol) 服务，专为 AI 开发者设计，用于管理和持久化 AI 对话过程中的状态信息。通过 Engram，开发者可以确保 AI 模型能够跨会话访问历史上下文，从而提供更连贯的交互体验。资料来源：README.md:1-10

安装方式

Engram 支持多种安装方式，用户可根据操作系统选择最合适的方法。资料来源：install.sh:1-30 和 install.ps1:1-30

Linux/macOS 安装

使用命令行安装脚本快速部署：

curl -fsSL https://raw.githubusercontent.com/Patdolitse/piia-engram/main/install.sh | bash

资料来源：install.sh:1-15

Windows 安装

PowerShell 用户可使用以下命令：

irm https://raw.githubusercontent.com/Patdolitse/piia-engram/main/install.ps1 | iex

资料来源：install.ps1:1-15

安装流程图

graph TD
    A[下载安装脚本] --> B{检测操作系统}
    B -->|Linux/macOS| C[执行 install.sh]
    B -->|Windows| D[执行 install.ps1]
    C --> E[安装依赖包]
    D --> E
    E --> F[初始化配置向导]
    F --> G[启动 Engram 服务]
    G --> H[验证安装状态]

设置向导

首次运行时，Engram 会自动启动交互式设置向导，引导用户完成基本配置。资料来源：src/piia_engram/setup_wizard.py:1-50

设置步骤

资料来源：src/piia_engram/setup_wizard.py:20-35

向导工作流程

stateDiagram-v2
    [*] --> 检查环境: 首次运行
    检查环境 --> 验证依赖: 环境就绪
    检查环境 --> 提示错误: 依赖缺失
    验证依赖 --> 收集配置: 依赖满足
    收集配置 --> 写入配置: 用户确认
    写入配置 --> 启动服务: 配置完成
    启动服务 --> 验证状态: 服务运行中
    验证状态 --> [*]: 验证成功
    提示错误 --> [*]: 中止安装

首次运行状态检查

v3.40.0 版本增强了首次运行的置信度，使用 engram status 命令可以快速查看配置健康状态。资料来源：README.md:1-20

engram status

该命令会显示：

• MCP 客户端配置健康状态（仅显示脱敏后的元数据）
• 服务运行状态
• 存储路径配置

HTML 状态报告

engram status --html

生成包含以下内容的 HTML 报告：

• MCP 客户端表格
• 后续建议命令链接

资料来源：README.md:15-25

快速验证命令

安装完成后，使用以下命令验证系统状态：

# 检查整体状态
engram status

# 运行诊断检查
engram doctor

# 查看会话列表
engram sessions

# 审查配置
engram review

资料来源：README.md:20-30

常见问题快速排查

资料来源：src/piia_engram/setup_wizard.py:40-50

后续步骤

完成快速开始后，建议用户进一步阅读：

• 配置详解 — 了解高级配置选项
• MCP 集成指南 — 学习如何将 Engram 与 AI 客户端集成
• API 参考 — 查看完整的命令行接口文档

参见

• 项目主页
• 安装脚本
• Windows 安装脚本
• 设置向导源码

概述

piia-engram 是一个基于 Model Context Protocol (MCP) 的记忆管理工具，专为 AI 开发者设计，用于管理和维护 AI 会话的上下文状态。该工具提供命令行界面，支持状态检查、会话管理和诊断功能。资料来源：README.md:1-20

系统要求

在安装 piia-engram 之前，请确保您的系统满足以下要求：

注意：由于 v3.40.0 版本增强了首次运行状态的清晰度和共享安全性，建议使用最新版本以获得最佳体验。资料来源：README.md:1

安装方式

使用 pip 安装

标准安装方式是通过 Python 包管理器 pip 进行安装：

pip install piia-engram

从源码安装

如果您需要使用开发版本或进行自定义修改，可以从源码安装：

# 克隆仓库
git clone https://github.com/Patdolitse/piia-engram.git
cd piia-engram

# 安装依赖并安装包
pip install -e .

资料来源：pyproject.toml:1-30

项目结构

理解项目结构有助于进行正确的配置：

graph TD
    A[piia-engram] --> B[src/piia_engram]
    A --> C[.mcp]
    A --> D[配置文件]
    B --> E[setup_wizard.py]
    B --> F[status.py]
    B --> G[cli.py]
    C --> H[server.json]
    D --> I[pyproject.toml]
    D --> J[engram.yaml]

资料来源：pyproject.toml:1-50

配置文件详解

pyproject.toml

pyproject.toml 是 Python 项目的核心配置文件，定义了包的元数据、依赖项和构建配置：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "piia-engram"
version = "3.40.0"
description = "记忆MCP - AI Memory Management"
requires-python = ">=3.10"
dependencies = [
    "mcp>=1.0.0",
    "click>=8.0.0",
    "pyyaml>=6.0",
]

[project.scripts]
engram = "piia_engram.cli:main"

资料来源：pyproject.toml:1-50

MCP 服务器配置

.mcp/server.json 文件定义了 MCP 服务器的连接参数：

{
    "mcpServers": {
        "engram": {
            "command": "engram",
            "args": ["--stdio"],
            "env": {
                "ENGRAM_HOME": "${ENGRAM_HOME:-~/.engram}"
            }
        }
    }
}

配置参数说明：

资料来源：.mcp/server.json:1-15

首次运行配置

首次运行 piia-engram 时，系统会启动设置向导以引导用户完成基本配置。

设置向导流程

graph TD
    A[首次运行 engram] --> B{检查配置目录}
    B -->|不存在| C[创建配置目录]
    B -->|已存在| D{检查配置文件}
    C --> E[运行设置向导]
    D -->|不存在| E
    D -->|已存在| F[加载现有配置]
    E --> G[配置 MCP 客户端]
    E --> H[验证 API 连接]
    G --> I[生成状态报告]
    H --> I
    F --> I
    I --> J[配置完成]

运行设置向导

设置向导会自动检测环境并提示用户进行必要配置：

engram setup

向导将执行以下检查：

1. 环境检测：验证 Python 版本、依赖包安装状态
2. 目录创建：在 ~/.engram 创建必要的子目录
3. MCP 客户端检测：扫描并验证已配置的 MCP 客户端
4. 连接测试：验证与后端服务的连接状态

资料来源：src/piia_engram/setup_wizard.py:1-80

状态检查命令

engram status 命令是检查系统配置状态的主要入口：

基本用法

engram status

该命令会显示：

• MCP 客户端配置健康状态（包含脱敏后的元数据）
• 连接状态摘要
• 下一建议操作

HTML 格式输出

engram status --html

生成包含以下内容的 HTML 报告：

• MCP 客户端表格
• engram doctor 诊断命令入口
• engram review 审查命令入口
• engram sessions 会话列表入口

资料来源：src/piia_engram/status.py:1-50

诊断与修复

engram doctor

运行诊断检查以发现配置问题：

engram doctor

诊断检查项：

engram review

审查会话和记忆状态：

engram review

engram sessions

列出和管理会话：

engram sessions list
engram sessions show <session_id>

环境变量

可通过环境变量自定义运行时行为：

示例：

export ENGRAM_HOME=/opt/engram
export ENGRAM_LOG_LEVEL=debug
engram status

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

常见问题与解决方案

1. 首次运行状态不清晰

问题：用户无法确定系统是否正确配置。

解决方案：v3.40.0 版本增强了首次运行状态的清晰度，使用 engram status 查看详细状态，使用 engram status --html 生成可分享的 HTML 报告。

2. MCP 客户端配置失败

问题：engram status 显示 MCP 客户端配置不健康。

排查步骤：

1. 运行 engram doctor 获取详细诊断信息
2. 检查 .mcp/server.json 配置文件语法
3. 验证 engram 命令是否在 PATH 中
4. 查看日志文件确认具体错误原因

3. API 连接问题

问题：无法连接到后端服务。

可能原因：

• 网络连接问题
• API 密钥配置错误
• 服务端暂时不可用

解决建议：联系服务提供商确认服务状态，或检查代理设置。

根据 v3.40.0 发布说明，该版本特别改进了状态检查的回归覆盖，建议升级以获得更稳定的状态检测体验。

配置验证清单

在完成配置后，请逐一验证以下项目：

• [ ] Python 版本 >= 3.10
• [ ] pip 安装成功
• [ ] engram --version 返回正确版本号
• [ ] ~/.engram 目录已创建
• [ ] engram status 无错误输出
• [ ] MCP 客户端检测正常
• [ ] API 连接测试通过

相关命令速查

概述

Piia Engram（简称 Engram）是一个基于 Model Context Protocol (MCP) 的本地记忆管理工具，专为 AI 开发者设计，用于在 AI 对话过程中持久化存储和检索上下文信息。该工具的核心目标是解决大型语言模型（LLM）在长对话场景下的上下文丢失问题，通过结构化的本地存储机制，使 AI 能够"记住"跨会话的关键信息。

Engram 采用模块化架构设计，将 CLI 交互层、MCP 协议层、核心业务逻辑层和数据持久化层分离，确保各模块职责明确、便于扩展和维护。

核心设计原则

Engram 的架构设计遵循以下核心原则：

系统组件架构

组件概览

graph TD
    subgraph "CLI 交互层"
        CLI[cli.py<br/>命令行接口]
    end
    
    subgraph "MCP 协议层"
        MCP[mcp_server.py<br/>MCP 服务器]
    end
    
    subgraph "核心业务逻辑层"
        CORE[core.py<br/>核心引擎]
    end
    
    subgraph "数据持久化层"
        STORAGE[storage.py<br/>存储适配器]
        DB[(本地数据库<br/>SQLite/文件)]
    end
    
    CLI --> CORE
    MCP --> CORE
    CORE --> STORAGE
    STORAGE --> DB

各层职责

#### CLI 交互层 (cli.py)

CLI 层负责处理用户通过命令行界面输入的指令，是用户与系统交互的主要入口点。该层封装了所有可执行的命令，包括：

• engram status - 显示当前系统状态和 MCP 客户端配置健康度
• engram status --html - 生成包含 HTML 格式的状态报告
• engram doctor - 执行系统诊断，检查配置完整性
• engram review - 审查已存储的记忆条目
• engram sessions - 管理会话历史

CLI 层将用户请求转换为内部 API 调用，并负责格式化输出结果。

#### MCP 协议层 (mcp_server.py)

MCP 层实现了 Model Context Protocol 的服务端功能，使 Engram 能够作为 MCP Server 被各种 AI 工具和 IDE（如 Cursor、Claude Desktop 等）集成。该层负责：

• 处理 MCP 客户端的连接请求
• 实现 MCP 规范的标准化接口（tools、resources、prompts）
• 管理工具调用的路由和参数验证
• 提供实时的上下文同步能力

#### 核心业务逻辑层 (core.py)

核心层是 Engram 的业务逻辑中枢，负责处理所有关键的运行时逻辑：

• 记忆管理 - 创建、更新、查询和删除记忆条目
• 会话跟踪 - 维护会话状态和上下文关联
• 配置管理 - 加载和应用系统配置
• 健康检查 - 验证各组件的运行状态

#### 数据持久化层 (storage.py)

存储层封装了所有与数据持久化相关的操作，提供了统一的数据访问接口：

• 记忆数据的读写操作
• 会话历史的管理
• 配置信息的存储
• 数据库连接池管理

数据流架构

请求处理流程

sequenceDiagram
    participant User as 用户/AI 客户端
    participant CLI as CLI 层
    participant MCP as MCP Server
    participant Core as 核心引擎
    participant Storage as 存储层
    participant DB as 数据库

    User->>CLI: 执行 engram 命令
    CLI->>Core: 调用核心 API
    Core->>Storage: 数据操作请求
    Storage->>DB: 持久化/查询
    DB-->>Storage: 返回结果
    Storage-->>Core: 处理结果
    Core-->>CLI: 返回数据
    CLI-->>User: 格式化输出

    User->>MCP: MCP 工具调用
    MCP->>Core: 路由请求
    Core->>Storage: 数据操作
    Storage->>DB: 持久化/查询
    DB-->>Storage: 返回结果
    Storage-->>Core: 处理结果
    Core-->>MCP: 返回结果
    MCP-->>User: MCP 响应

MCP 客户端集成流程

Engram 作为 MCP Server 被外部 AI 工具集成时，其数据流如下：

1. 连接建立 - AI 客户端通过 MCP 协议建立与 Engram Server 的连接
2. 能力发现 - 客户端查询 Engram 提供的工具和资源列表
3. 工具调用 - 客户端通过 MCP 协议调用 Engram 提供的记忆工具
4. 结果返回 - Engram 处理请求并返回结构化结果

存储架构

数据库设计

Engram 采用 SQLite 作为默认存储后端，数据库文件通常位于 ~/.engram/engram.db 或项目配置的本地目录中。

erDiagram
    memories {
        string id PK
        string content
        string session_id
        timestamp created_at
        timestamp updated_at
        string tags
        string metadata
    }
    
    sessions {
        string id PK
        string title
        timestamp started_at
        timestamp ended_at
        string context
    }
    
    config {
        string key PK
        string value
        timestamp updated_at
    }
    
    memories ||--o{ sessions : belongs_to

存储操作接口

存储层提供以下核心操作接口：

MCP 集成架构

MCP 工具定义

Engram 通过 MCP 协议暴露以下工具供 AI 客户端调用：

{
  "tools": [
    {
      "name": "save_memory",
      "description": "保存 AI 生成的关键信息到本地记忆库",
      "inputSchema": {
        "type": "object",
        "properties": {
          "content": {"type": "string"},
          "tags": {"type": "array", "items": {"type": "string"}},
          "session_id": {"type": "string"}
        },
        "required": ["content"]
      }
    },
    {
      "name": "search_memories",
      "description": "搜索本地记忆库中的相关记忆",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {"type": "string"},
          "limit": {"type": "integer", "default": 10}
        },
        "required": ["query"]
      }
    },
    {
      "name": "get_recent_memories",
      "description": "获取最近保存的记忆",
      "inputSchema": {
        "type": "object",
        "properties": {
          "limit": {"type": "integer", "default": 10},
          "session_id": {"type": "string"}
        }
      }
    }
  ]
}

MCP 资源定义

除了工具，MCP 协议还定义了可访问的 Resources：

配置管理

配置来源优先级

Engram 的配置按照以下优先级顺序加载：

1. 命令行参数 - 最高优先级
2. 环境变量 - ENGRAM_* 前缀的环境变量
3. 项目配置文件 - ./engram.yaml 或 ./engram.json
4. 用户配置文件 - ~/.engram/config.yaml
5. 系统默认配置 - 内置的默认值

关键配置项

状态检查与诊断

`engram status` 命令

engram status 命令提供 MCP 客户端配置健康度的汇总信息，是 v3.40.0 版本的核心功能。该命令：

• 检查 MCP Server 的运行状态
• 验证配置的完整性
• 显示脱敏后的元数据（不暴露敏感信息）
• 提供下一步操作建议

`engram status --html` 输出格式

当使用 --html 标志时，输出包含：

• MCP Clients 表格 - 列出已配置的 MCP 客户端
• Next Commands - 建议的后续操作命令
• engram doctor - 详细诊断
• engram review - 审查记忆
• engram sessions - 会话管理

常见失败模式

相关文档

• 快速开始指南 - 安装与首次使用
• CLI 命令参考 - 所有命令详解
• MCP 集成指南 - 与 AI 工具集成
• 配置文件参考 - 完整配置项列表

参考资料

• 项目主仓库：Patdolitse/piia-engram
• 最新版本发布说明：v3.40.0 - First-run confidence

概述

Engram 是一款为 AI 开发者设计的记忆管理工具，它采用结构化的 JSON 文件格式来组织和持久化用户的工作记忆数据。数据布局基于 engram 目录结构，按照信息的语义类型进行分类存储，主要分为身份配置（identity）和知识库（knowledge）两大核心区域。这种设计使得数据既便于人类阅读和编辑，也能被 MCP 客户端程序化地访问和处理。资料来源：README.md:1-20

数据目录结构

Engram 使用本地文件系统作为存储后端，所有数据默认存放在项目根目录下的 engram/ 文件夹中。该目录采用预定义的层次结构，不同类型的信息存储在相应的子目录中。资料来源：src/piia_engram/storage.py:1-50

graph TD
    A[engram/] --> B[identity/]
    A --> C[knowledge/]
    A --> D[memory/]
    A --> E[sessions/]
    
    B --> B1[profile.json]
    B --> B2[preferences.json]
    
    C --> C1[lessons/]
    C --> C2[decisions/]
    C --> C3[concepts/]
    
    D --> D1[context/]
    D --> D2[archives/]
    
    E --> E1[session_*.json]
    
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333,stroke-width:1px
    style C fill:#bfb,stroke:#333,stroke-width:1px

目录层级说明

身份数据（Identity）

身份数据存储在 engram/identity/ 目录下，包含用户的个人资料和偏好设置。这些数据用于标识当前用户身份以及配置工具行为。资料来源：examples/engram/identity/profile.example.json

个人资料（Profile）

Profile 数据模型定义了用户的基本身份信息：

{
  "id": "user_xxx",
  "name": "示例用户",
  "email": "[email protected]",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z",
  "version": "1.0"
}

Profile 数据在首次运行时自动生成，确保每个工作环境都有独立的用户标识。资料来源：examples/engram/identity/profile.example.json:1-15

偏好设置

偏好设置存储用户对工具行为的个性化配置，包括输出格式、默认参数、主题偏好等。这些设置影响工具的交互方式和输出样式。

知识库数据（Knowledge）

知识库是 Engram 的核心存储区域，采用语义分类的方式组织信息。根据信息的性质和用途，知识库进一步分为多个子类别。资料来源：examples/engram/knowledge/lessons.example.json

经验教训（Lessons）

Lessons 用于记录从工作实践中获得的经验和教训，每条记录包含情境描述、行动方案和结果反馈。资料来源：examples/engram/knowledge/lessons.example.json:1-30

{
  "id": "lesson_001",
  "title": "数据库迁移最佳实践",
  "category": "development",
  "situation": "进行大规模数据迁移时遇到性能问题",
  "action": "采用分批次迁移策略，设置合理的事务间隔",
  "result": "迁移时间增加但系统稳定性显著提升",
  "tags": ["database", "migration", "performance"],
  "created_at": "2024-06-15T10:30:00Z"
}

决策记录（Decisions）

Decisions 用于记录重要的技术决策及其上下文信息，便于日后追溯决策依据。资料来源：examples/engram/knowledge/decisions.example.json

{
  "id": "decision_001",
  "title": "选择微服务架构",
  "context": "系统需要支持高并发和快速迭代",
  "options": [
    "单体架构",
    "微服务架构",
    "事件驱动架构"
  ],
  "decision": "微服务架构",
  "reasoning": "团队规模适合微服务拆分，需要独立部署能力",
  "date": "2024-05-20",
  "status": "implemented"
}

数据模型属性说明

存储层架构

Engram 的存储层采用模块化设计，通过 StorageManager 类统一管理所有数据文件的读写操作。资料来源：src/piia_engram/storage.py:1-100

graph LR
    A[应用层] --> B[StorageManager]
    B --> C[IdentityStore]
    B --> D[KnowledgeStore]
    B --> E[MemoryStore]
    B --> F[SessionStore]
    
    C --> G[文件系统]
    D --> G
    E --> G
    F --> G
    
    style B fill:#f96,stroke:#333,stroke-width:2px

StorageManager 核心职责

StorageManager 是存储层的中央协调器，负责以下功能：

• 路径管理：解析和验证数据文件的存储路径
• 文件操作：处理 JSON 文件的读取、写入和更新
• 事务支持：确保批量操作的原子性
• 错误处理：捕获并报告存储相关的异常

资料来源：src/piia_engram/storage.py:50-80

数据一致性保证

存储层采用写前检查策略，在执行写操作前验证目标路径是否存在以及权限是否充足。对于批量操作，系统使用临时文件加原子重命名的模式，确保在异常情况下不会损坏现有数据。资料来源：src/piia_engram/storage.py:80-120

数据格式规范

Engram 所有数据文件均采用 JSON 格式存储，这确保了跨平台的兼容性和人类可读性。

编码要求

时间戳格式

所有时间相关字段使用 ISO 8601 标准格式：YYYY-MM-DDTHH:MM:SSZ，时间部分使用 24 小时制，时区统一使用 UTC（后缀 Z 表示）。

存储配置

项目通过 pyproject.toml 配置工具的基本元数据和依赖关系。资料来源：pyproject.toml:1-30

[project]
name = "piia-engram"
version = "3.40.0"
description = "Memory MCP for AI developers"
requires-python = ">=3.10"

存储路径可以通过环境变量进行自定义配置，这允许用户将数据存放在非默认位置，例如使用云同步目录或外部存储设备。

数据生命周期

数据创建

新数据通过对应的 Store 类方法创建，系统自动分配唯一标识符并设置创建时间戳。对于需要关联的数据，系统会验证引用的有效性。

数据更新

更新操作采用合并策略，保留未修改字段的原有值。更新时会自动刷新 updated_at 字段，确保数据的时间线准确性。

数据归档

长期未访问的数据可以移入 memory/archives/ 目录进行归档处理。归档操作不会删除原始数据，而是将其移动到归档目录并记录归档时间戳。资料来源：src/piia_engram/storage.py:100-150

常见问题与解决方案

文件权限错误

如果遇到数据文件无法写入的问题，检查以下权限设置：

1. 确认 engram/ 目录及其子目录的读写权限
2. 确保运行用户对数据文件具有修改权限
3. 在类 Unix 系统上可使用 chmod -R u+rw engram/ 修复

数据损坏恢复

当 JSON 文件格式损坏时：

1. 检查是否有自动生成的备份文件（.bak 后缀）
2. 使用 JSON 验证工具检查文件语法
3. 参考 examples/ 目录下的示例文件重建数据结构

并发访问限制

当前版本的存储层未实现文件锁机制，不建议在多个进程同时写入同一数据文件。如需多端同步，建议使用版本控制系统或专门的同步工具。

相关命令

资料来源：README.md:50-80

参见

• 快速入门指南 — 了解如何初始化存储结构
• CLI 命令参考 — 完整的命令行接口文档
• MCP 集成配置 — 配置 MCP 客户端访问存储数据

概述

Piia Engram 的 MCP（Model Context Protocol）协议集成为 AI 开发工具提供了标准化的记忆上下文交互能力。该集成使支持 MCP 协议的 AI 客户端（如 Claude Desktop、CodeX 等）能够直接访问 Engram 的记忆存储系统，实现跨会话的上下文持久化管理。

核心功能定位：MCP 协议集成作为 Engram 的核心扩展接口，将本地加密存储的记忆数据以标准化的工具调用形式暴露给 AI 客户端，使 AI 能够在对话过程中读取、写入和检索历史上下文信息。

资料来源：mcp_server.py:1-50

概述

Piia Engram是一个基于MCP（Model Context Protocol，模型上下文协议）的本地记忆管理工具，专为AI开发者设计，用于在AI会话之间持久化和管理上下文信息。该工具通过标准化的MCP协议与各种AI客户端集成，使AI能够跨会话保持记忆和状态连续性。

资料来源：README.md:1-30

核心功能

Piia Engram的MCP工具提供了以下核心功能模块：

资料来源：src/piia_engram/retrieval.py:1-50

架构设计

系统组件架构

graph TD
    A[AI客户端] -->|MCP协议| B[Piia Engram MCP服务器]
    B --> C[记忆检索模块]
    B --> D[上下文管理模块]
    B --> E[决策线程模块]
    C --> F[本地存储层]
    D --> F
    E --> F
    B --> G[MCP客户端]
    G --> H[外部MCP服务]
    G --> I[第三方工具]

数据流架构

graph LR
    A[用户输入] --> B[上下文构建器]
    B --> C[检索引擎]
    C --> D[记忆片段匹配]
    D --> E[上下文组装]
    E --> F[AI模型输入]
    F --> G[AI响应]
    G --> H[决策记录]
    H --> I[记忆存储]

资料来源：src/piia_engram/context.py:1-80

MCP客户端集成

客户端配置状态检查

在v3.40.0版本中，系统增强了MCP客户端配置的健康检查功能。engram status命令现在能够汇总MCP客户端配置状态，并仅显示经过脱敏处理的元数据信息，确保敏感信息的安全。

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

客户端配置表

资料来源：src/piia_engram/mcp_client.py:1-100

命令行接口

Piia Engram提供了完整的命令行工具集用于管理和监控MCP工具：

engram status

查看当前系统状态，包括MCP客户端配置健康度。

engram status
engram status --html  # 生成HTML格式输出

输出内容包含：

• MCP客户端配置表
• 下一步建议命令（engram doctor、engram review、engram sessions）

资料来源：README.md:50-100

engram doctor

诊断系统健康状态，检测MCP工具的潜在问题。

engram doctor

engram review

回顾历史会话和决策记录。

engram review

engram sessions

管理活动会话列表。

engram sessions

使用模式

首次运行配置

graph TD
    A[首次运行] --> B{检查配置}
    B -->|配置缺失| C[初始化配置]
    B -->|配置存在| D[验证连接]
    C --> E[首次运行信心度评估]
    D --> E
    E --> F[状态摘要生成]
    F --> G[准备就绪]

v3.40.0版本改进了首次运行状态的清晰度和安全性分享功能，使新用户能够更直观地了解系统状态。

资料来源：src/piia_engram/decision_thread.py:1-70

会话恢复流程

sequenceDiagram
    participant U as 用户
    participant C as AI客户端
    participant E as Engram
    participant S as 存储层
    
    U->>C: 发起新会话
    C->>E: 请求上下文恢复
    E->>S: 查询历史记忆
    S-->>E: 返回相关记忆片段
    E-->>C: 组装上下文
    C->>U: 恢复会话状态

常见故障与排查

故障诊断流程

engram doctor 检查项目

1. MCP服务器连接状态
2. 本地存储可访问性
3. 配置文件完整性
4. 客户端认证有效性

资料来源：src/piia_engram/status.py:60-120

第三方集成

Piia Engram的MCP工具支持与外部服务和工具的集成。根据社区反馈，该工具已被国内开发者社区关注，例如呆呆兽中转站等服务平台表达了合作意向，希望为国内开发者提供稳定的API服务支持。

资料来源：GitHub Issue #8

集成要求

• 支持MCP协议标准
• 兼容JSON-RPC 2.0通信格式
• 提供标准化的工具调用接口

扩展阅读

• 项目主页
• 检索模块详解
• 上下文管理
• 决策追踪
• 状态监控

概述

piia-engram 是一个 MCP（Model Context Protocol）记忆管理工具，旨在为 AI 开发者提供上下文状态查看和知识持久化管理能力。该项目通过 engram 命令行工具实现对知识库的操作，包括检索、同步、状态监控和生命周期管理。

核心模块架构

模块职责概览

架构流程图

graph TD
    A[用户请求] --> B[engram CLI]
    B --> C{知识操作类型}
    C -->|检索| D[retrieval.py]
    C -->|同步| E[reconcile.py]
    C -->|状态| F[reports/status.py]
    C -->|会话| G[reports/sessions.py]
    D --> H[向量数据库/存储层]
    E --> H
    F --> I[状态缓存]
    G --> J[会话存储]
    H --> K[知识图谱]
    I --> L[健康度报告]
    J --> K
    K --> M[治理层]
    M --> N[governance/retention.py]
    N --> O[数据保留策略执行]

知识检索功能

功能说明

知识检索模块负责从存储系统中高效地查询和获取相关知识条目。该模块支持基于向量相似度的语义检索和关键词匹配两种检索模式。

资料来源：src/piia_engram/retrieval.py:1-50

检索流程

graph TD
    A[检索请求] --> B[查询解析]
    B --> C{检索模式}
    C -->|语义检索| D[向量嵌入]
    C -->|关键词检索| E[倒排索引]
    D --> F[相似度计算]
    E --> F
    F --> G[结果排序]
    G --> H[结果过滤]
    H --> I[返回结果集]

检索配置参数

资料来源：src/piia_engram/retrieval.py:30-45

知识调和功能

功能说明

知识调和模块负责检测和解决多个知识源之间的不一致性问题，确保知识库的数据完整性和一致性。该模块采用三阶段处理流程：检测、分析、修复。

资料来源：src/piia_engram/reconcile.py:1-80

调和策略

调和流程

graph TD
    A[启动调和] --> B[扫描知识源]
    B --> C[检测差异]
    C --> D{发现冲突?}
    D -->|否| E[标记同步完成]
    D -->|是| F[应用调和策略]
    F --> G{策略类型}
    G -->|自动| H[自动修复]
    G -->|手动| I[生成冲突报告]
    H --> J[更新知识库]
    I --> K[等待人工处理]
    J --> E

状态报告功能

engram status 命令

engram status 命令提供 MCP 客户端配置健康状况的摘要信息。从 v3.40.0 版本开始，该命令仅展示经过脱敏处理的元数据，增强了首次运行状态的可分享性和安全性。

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

engram status --html 命令

HTML 格式的状态报告包含以下扩展信息：

资料来源：src/piia_engram/reports/status.py:50-80

会话报告

engram sessions 命令管理会话历史记录，支持会话列表查询和历史回溯功能。

资料来源：src/piia_engram/reports/sessions.py:1-45

数据治理功能

保留策略

数据治理模块负责执行知识数据的生命周期管理，包括数据保留期限、归档策略和清理规则。

资料来源：src/piia_engram/governance/retention.py:1-70

治理配置

治理流程

graph TD
    A[定时任务触发] --> B[扫描过期数据]
    B --> C{是否启用归档?}
    C -->|是| D[检查访问频率]
    C -->|否| E[直接清理]
    D --> F{低于阈值?}
    F -->|是| G[移动至归档存储]
    F -->|否| H[保留在活跃存储]
    G --> I[更新元数据]
    H --> J[重置过期时间]
    E --> K[执行清理]
    I --> K
    J --> L[记录审计日志]
    K --> L

使用示例

基本检索操作

# 语义检索
engram retrieve --query "项目架构设计" --mode semantic --limit 5

# 关键词检索
engram retrieve --query "API endpoint" --mode keyword

状态检查

# 查看系统状态
engram status

# 生成 HTML 报告
engram status --html > status_report.html

会话管理

# 查看最近会话
engram sessions --limit 10

# 导出会话历史
engram sessions export --format json

知识调和

# 手动触发调和
engram reconcile --strategy priority_based

# 查看调和报告
engram reconcile report --format json

常见问题与故障排除

检索返回空结果

症状：检索查询无结果返回。

可能原因：

• 知识库尚未初始化或数据为空
• 检索阈值设置过高
• 查询语句与现有知识语义不匹配

解决方案：

1. 运行 engram doctor 检查系统健康状态
2. 降低 --threshold 参数值
3. 使用 engram sessions 检查是否有相关会话数据

调和冲突未解决

症状：长时间未完成调和操作或报告存在未解决的冲突。

可能原因：

• 冲突数据量较大，处理时间较长
• 手动策略下存在未处理的人工决策

解决方案：

1. 查看 engram reconcile report 获取冲突详情
2. 对于手动策略，使用 engram reconcile resolve --id <冲突ID> 进行决策
3. 考虑调整调和策略为自动模式

状态命令输出异常

症状：engram status 输出格式错误或缺少关键信息。

可能原因：

• MCP 客户端配置不完整
• 存储服务连接失败

解决方案：

1. 运行 engram doctor --verbose 获取详细诊断信息
2. 检查 MCP 配置文件中的端点和认证信息
3. 使用 engram review 重新验证配置完整性

配置建议

生产环境推荐配置

相关命令速查

参见

• MCP 客户端配置指南
• 命令行工具完整参考
• 数据存储架构
• 发布说明 v3.40.0

功能概述

什么是Playbook

在piia-engram语境中，Playbook是一组结构化的操作序列，包含以下核心要素：

自动提取的工作原理

Playbook自动提取功能通过分析对话上下文中的操作痕迹，自动识别可复用的执行模式。当检测到连续的操作序列被成功执行时，系统会将其打包为独立的Playbook条目存入知识库中。

graph TD
    A[对话交互开始] --> B[监控操作序列]
    B --> C{操作是否成功?}
    C -->|成功| D[累积操作上下文]
    C -->|失败| E[记录失败模式]
    D --> F{达到提取阈值?}
    F -->|否| B
    F -->|是| G[生成Playbook草案]
    G --> H[用户确认或编辑]
    H --> I[存入知识库]
    I --> J[下次相似上下文自动推荐]

资料来源：src/piia_engram/context.py:15-45

核心架构

模块组成

Playbook自动提取功能由以下几个核心模块协同工作：

数据流设计

sequenceDiagram
    participant User as 用户
    participant CLI as Engram CLI
    participant Context as 上下文捕获器
    participant Extractor as 模式提取器
    participant Storage as 知识库
    participant MCP as MCP客户端

    User->>CLI: 执行操作命令
    CLI->>Context: 记录操作上下文
    Context->>Extractor: 推送操作事件
    Extractor->>Extractor: 分析操作序列模式
    Extractor->>Storage: 存储提取的Playbook
    Storage-->>MCP: 注册MCP资源
    MCP-->>User: 推荐相关Playbook

资料来源：demos/cross_tool_demo.py:1-30

使用方法

基本命令

Playbook自动提取功能通过engram命令行工具进行操作。以下是核心命令列表：

# 查看当前Playbook列表
engram playbooks list

# 手动触发Playbook提取
engram playbooks extract

# 查看特定Playbook详情
engram playbooks show <playbook-id>

# 编辑现有Playbook
engram playbooks edit <playbook-id>

# 删除不需要的Playbook
engram playbooks delete <playbook-id>

资料来源：src/piia_engram/cli/commands.py:50-100

自动提取触发条件

系统会在以下场景自动触发Playbook提取：

1. 会话结束时：当使用engram sessions stop结束会话时，系统自动分析本次会话中的操作序列
2. 操作序列重复出现：当检测到三次以上的相同操作模式时自动提取
3. 显式请求：用户通过engram review命令显式请求系统进行模式分析

# auto_save_on_stop.py 中的自动保存逻辑
def on_session_stop(session_context):
    if should_auto_extract(session_context):
        extractor = PlaybookExtractor()
        extracted = extractor.extract_from_context(session_context)
        if extracted:
            storage.save(extracted)

资料来源：src/piia_engram/hooks/auto_save_on_stop.py:10-25

跨工具协作场景

Playbook自动提取在跨工具协作场景中尤为有价值。当一个复杂的操作流程涉及多个工具的协同工作时，系统能够完整记录整个操作链：

# cross_tool_demo.py 演示的跨工具场景
# 场景：代码审查 -> 测试执行 -> 报告生成

def code_review_workflow(file_path):
    # 步骤1：使用审查工具扫描代码
    scanner.scan(file_path)
    
    # 步骤2：执行单元测试
    tester.run_unit_tests(file_path)
    
    # 步骤3：生成审查报告
    reporter.generate_html_report()
    
    # 系统自动识别并提取为Playbook:
    # {
    #     "name": "代码审查完整流程",
    #     "steps": ["scanner.scan", "tester.run_unit_tests", "reporter.generate_html_report"],
    #     "trigger": "需要完整代码审查时"
    # }

资料来源：demos/cross_tool_demo.py:20-35

配置选项

提取参数配置

通过engram config命令可以调整Playbook自动提取的行为参数：

# 查看当前配置
engram config get extract.*

# 修改提取阈值
engram config set extract.threshold 5

# 禁用自动保存
engram config set extract.auto_save false

存储配置

Playbook的存储位置和格式也可以根据需求进行调整：

输出格式

Playbook数据结构

自动提取的Playbook以结构化的JSON格式存储：

{
  "id": "pb_20240115_abc123",
  "name": "Python项目测试流程",
  "description": "标准的Python项目单元测试执行流程",
  "version": "1.0.0",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "trigger": {
    "type": "context_match",
    "pattern": "运行测试|test|pytest"
  },
  "steps": [
    {
      "order": 1,
      "action": "tester.discover",
      "params": {"pattern": "test_*.py"},
      "expected_output": "发现N个测试用例"
    },
    {
      "order": 2,
      "action": "tester.run",
      "params": {"verbose": true},
      "expected_output": "测试执行结果摘要"
    }
  ],
  "metadata": {
    "confidence": 0.92,
    "extraction_method": "auto",
    "usage_count": 0,
    "last_used": null
  }
}

资料来源：src/piia_engram/context.py:100-150

常见问题与故障排除

提取的Playbook不准确

问题表现：系统自动提取的Playbook包含过多无关步骤或遗漏关键操作。

解决方案：

1. 调整提取阈值参数，增加触发难度
2. 在会话结束后手动编辑生成的Playbook
3. 使用engram playbooks train命令对历史数据进行再训练

自动提取未触发

问题表现：完成多次重复操作后，系统未自动生成Playbook。

排查步骤：

# 1. 检查自动保存功能是否启用
engram config get extract.auto_save

# 2. 检查会话是否正常结束
engram sessions list
engram sessions show <session-id>

# 3. 查看系统日志获取详细错误信息
engram logs --level debug --grep "extract"

MCP客户端无法获取Playbook

问题表现：通过MCP协议无法查询到已存储的Playbook。

解决方案：

# 1. 检查MCP客户端配置状态
engram status --html

# 2. 运行诊断命令
engram doctor

# 3. 重新注册MCP资源
engram mcp refresh

资料来源：src/piia_engram/hooks/auto_save_on_stop.py:30-50

与MCP客户端集成

piia-engram作为MCP（Model Context Protocol）服务器运行时，Playbook数据通过MCP资源接口对外暴露。客户端可以通过以下方式访问Playbook：

mcp://engram/playbooks/{playbook_id}
mcp://engram/playbooks/search?q={keyword}
mcp://engram/playbooks/recommend?context={current_context}

集成配置示例

{
  "mcpServers": {
    "engram": {
      "command": "engram",
      "args": ["mcp", "serve"],
      "env": {
        "ENGRAM_PLAYBOOK_INDEX": "true"
      }
    }
  }
}

资料来源：demos/cross_tool_demo.py:40-60

版本历史与更新

v3.40.0 新增功能

在最新版本v3.40.0中，Playbook自动提取功能增加了以下改进：

• 状态摘要增强：engram status命令现在包含MCP客户端配置健康状态概览，使用脱敏元数据
• HTML状态报告：engram status --html新增MCP客户端表格和engram doctor、engram review、engram sessions等后续操作指引
• 回归测试覆盖：增加了对状态探测和帮助功能的回归测试覆盖

架构概述

Engram 的远程部署架构采用客户端-服务器模式，包含两个核心组件协同工作。客户端组件运行在本地 AI 开发环境中，负责接收用户指令和展示状态信息。远程 Worker 组件部署在服务器端，处理记忆存储和检索的核心逻辑。

graph TD
    A["本地环境<br/>engram CLI"] --> B["MCP Server<br/>mcp_server.py"]
    B --> C["远程 Worker<br/>worker/src/index.js"]
    C --> D["数据库<br/>schema.sql"]
    
    E["MCP Client<br/>Claude/CodeX"] --> B
    
    F["呆呆兽中转站<br/>API 服务"] -.->|可选| B
    
    style F fill:#f9f,stroke:#333,stroke-width:2px
    style D fill:#bbf,stroke:#333,stroke-width:2px

资料来源：README.md

核心组件说明

MCP 服务器 (mcp_server.py)

MCP 服务器是 Engram 的核心通信枢纽，负责处理来自 MCP 客户端的请求并转发至远程 Worker。该组件采用 Python 实现，通过标准化的 MCP 协议与 AI 工具进行交互。

资料来源：src/piia_engram/mcp_server.py

Worker 服务 (index.js)

Worker 服务运行在远程服务器上，负责实际的记忆数据处理工作。该服务采用 Node.js 实现，提供了高性能的数据操作能力。

资料来源：worker/src/index.js

数据库架构 (schema.sql)

数据库采用 SQLite 存储模式，定义了记忆数据的存储结构和索引策略。该设计支持高效的查询和状态追踪功能。

资料来源：worker/schema.sql

部署配置参数

远程部署涉及多个关键配置参数，正确的参数设置是确保服务稳定运行的前提。以下表格详细说明了各配置项的作用和建议值。

资料来源：src/piia_engram/mcp_server.py

部署流程

环境准备

在开始部署之前，需要确保目标服务器满足以下软件环境要求。服务器需要安装 Node.js 运行时环境（建议 v18 以上版本）用于运行 Worker 服务。同时需要 Python 3.10 或更高版本用于运行 MCP 服务器组件。数据库存储目录需要具备足够的磁盘空间和适当的读写权限。

Worker 服务部署

Worker 服务的部署是远程配置的第一步。首先需要克隆项目仓库到目标服务器，然后安装项目依赖包。数据库初始化需要执行 schema.sql 中的建表语句以创建必要的表结构。最后启动 Worker 服务并验证其正常运行状态。

# 克隆仓库
git clone https://github.com/Patdolitse/piia-engram.git
cd piia-engram/worker

# 安装依赖
npm install

# 初始化数据库
sqlite3 engram.db < schema.sql

# 启动 Worker 服务
node src/index.js

资料来源：worker/src/index.js

MCP 服务器配置

MCP 服务器的配置需要指定远程 Worker 服务的连接信息。配置完成后，可以通过 engram status 命令验证连接状态和配置健康度。v3.40.0 版本新增的 engram status 命令可以显示 MCP 客户端配置状态，并以脱敏后的元数据形式呈现，便于安全分享。

# 配置远程连接
export ENGRAM_HOST=your-remote-server.com
export ENGRAM_PORT=8080
export ENGRAM_API_KEY=your-api-key

# 验证配置状态
engram status

# 生成 HTML 格式状态报告
engram status --html

资料来源：src/piia_engram/mcp_server.py

状态检查与诊断

engram status 命令

engram status 命令是诊断远程部署问题的首要工具。该命令会检查 MCP 客户端配置的健康状态，返回配置是否正确以及连接是否存在问题。v3.40.0 版本增强了对 MCP 客户端配置的检测能力。

# 基本状态检查
engram status

# HTML 格式输出（包含 MCP Clients 表）
engram status --html

engram doctor 命令

当状态检查发现问题或配置异常时，可以使用 engram doctor 命令进行深入诊断。该命令会逐项检查各项配置并提供修复建议。

# 完整诊断
engram doctor

engram review 命令

engram review 命令用于查看会话历史和记忆状态，帮助用户了解当前系统的运行状态和数据同步情况。

# 审查会话状态
engram review

engram sessions 命令

sessions 子命令列出了当前活跃的会话连接，便于用户管理多个远程连接场景。

# 查看活跃会话
engram sessions

资料来源：README.md

常见问题排查

连接超时问题

如果遇到连接超时错误，首先检查远程服务器的防火墙设置是否允许相应端口的入站连接。确认 Worker 服务是否正常监听在指定端口上，可以尝试在服务器本地执行 curl 测试接口可用性。检查网络延迟情况，如果延迟过高可能需要调整 ENGRAM_TIMEOUT 参数。

认证失败问题

认证失败通常由 API 密钥配置错误或缺失导致。确认本地环境的 ENGRAM_API_KEY 与远程 Worker 服务配置的密钥一致。检查密钥是否包含特殊字符导致环境变量解析错误。

数据库访问异常

数据库访问异常可能由文件权限问题或数据库锁定状态引起。确认运行 Worker 服务的用户对数据库文件及其所在目录有读写权限。如果遇到锁定错误，等待当前事务完成后重试，或检查是否有其他进程长时间占用数据库连接。

MCP 客户端配置问题

MCP 客户端配置不正确会导致无法连接到 Engram 服务。运行 engram status 检查配置健康度。确认 MCP 客户端的配置文件中的服务器地址和端口与实际部署一致。

第三方 API 服务集成

根据社区反馈，国内开发者可以通过呆呆兽中转站（www.ddshub.cc）获取低价稳定的 Claude 和 CodeX API 服务。集成第三方 API 服务需要在 MCP 服务器配置中指定相应的 API 端点和密钥。

# 配置第三方 API 服务
export ENGRAM_API_ENDPOINT=https://api.ddshub.cc/v1
export ENGRAM_API_KEY=your-third-party-api-key

资料来源：README.md

安全建议

网络安全

生产环境部署时强烈建议使用 HTTPS 协议加密通信。配置防火墙规则仅允许受信任的 IP 地址访问 Worker 服务端口。考虑使用 VPN 或专用网络连接远程组件。

认证安全

API 密钥应妥善保管，避免硬编码在代码中。建议使用环境变量或安全的密钥管理服务存储敏感信息。定期轮换 API 密钥以降低密钥泄露风险。

数据安全

数据库文件应定期备份，并将备份存储在安全位置。敏感记忆数据应考虑加密存储。配置合理的数据库访问权限，遵循最小权限原则。

版本兼容性说明

v3.40.0 版本对首次运行状态显示进行了优化，使本地首次运行状态更加清晰和安全。该版本还增强了状态检查功能，新增了 MCP 客户端配置健康度检测和 HTML 格式输出支持。升级前请确认 MCP 客户端版本与服务器版本兼容。

参见

• Engram 快速开始指南
• CLI 命令参考
• 数据库架构详解
• MCP 协议说明
• 故障排除常见问题

Pitfall Log / 踩坑日志

项目：Patdolitse/piia-engram

摘要：发现 18 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: v3.34.0 — Governance cutover + Universal harness + Playbook policy。

1. 安装坑 · 失败模式：installation: v3.34.0 — Governance cutover + Universal harness + Playbook policy

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v3.34.0 — Governance cutover + Universal harness + Playbook policy
• 对用户的影响：Upgrade or migration may change expected behavior: v3.34.0 — Governance cutover + Universal harness + Playbook policy
• 建议检查：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
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：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

2. 安装坑 · 失败模式：installation: v3.35.0 — Decision Threads & Permission Profile

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v3.35.0 — Decision Threads & Permission Profile
• 对用户的影响：Upgrade or migration may change expected behavior: v3.35.0 — Decision Threads & Permission Profile
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v3.35.0 — Decision Threads & Permission Profile. Context: Observed when using python
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：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

3. 安装坑 · 失败模式：installation: v3.37.0 - GUI entry adoption: piia-engram-mcp + uvx

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v3.37.0 - GUI entry adoption: piia-engram-mcp + uvx
• 对用户的影响：Upgrade or migration may change expected behavior: v3.37.0 - GUI entry adoption: piia-engram-mcp + uvx
• 建议检查：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.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：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

4. 安装坑 · 失败模式：installation: v3.39.0 - Local Workflow Visibility

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v3.39.0 - Local Workflow Visibility
• 对用户的影响：Upgrade or migration may change expected behavior: v3.39.0 - Local Workflow Visibility
• 建议检查：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.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_500227db57a8529c37cfce701ae84bdc | https://github.com/Patdolitse/piia-engram/releases/tag/v3.39.0 | v3.39.0 - Local Workflow Visibility

5. 配置坑 · 可能修改宿主 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

6. 配置坑 · 失败模式：configuration: v3.38.0 - Encoding repair guardrails

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v3.38.0 - Encoding repair guardrails
• 对用户的影响：Upgrade or migration may change expected behavior: v3.38.0 - Encoding repair guardrails
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v3.38.0 - Encoding repair guardrails. Context: Observed when using windows
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_42be567d8e4b76432faa58f51baccf59 | https://github.com/Patdolitse/piia-engram/releases/tag/v3.38.0 | v3.38.0 - Encoding repair guardrails

7. 配置坑 · 失败模式：configuration: v3.40.0 - First-run confidence

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v3.40.0 - First-run confidence
• 对用户的影响：Upgrade or migration may change expected behavior: v3.40.0 - First-run confidence
• 建议检查：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.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_e8bb2627f41868837723a394026965a3 | https://github.com/Patdolitse/piia-engram/releases/tag/v3.40.0 | v3.40.0 - First-run confidence

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

• 严重度：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.

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

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1242620513 | https://github.com/Patdolitse/piia-engram | last_activity_observed missing

10. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1242620513 | https://github.com/Patdolitse/piia-engram | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1242620513 | https://github.com/Patdolitse/piia-engram | no_demo; severity=medium

12. 能力坑 · 失败模式：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工具合作申请
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Piia Engram工具合作申请. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_2c63fe4051ac808c161d261e8e1fd5e9 | https://github.com/Patdolitse/piia-engram/issues/8 | Piia Engram工具合作申请

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1242620513 | https://github.com/Patdolitse/piia-engram | issue_or_pr_quality=unknown

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

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1242620513 | https://github.com/Patdolitse/piia-engram | release_recency=unknown

15. 维护坑 · 失败模式：maintenance: v3.33.1 — 混合搜索索引新鲜度修复（代码审查发现）

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v3.33.1 — 混合搜索索引新鲜度修复（代码审查发现）
• 对用户的影响：Upgrade or migration may change expected behavior: v3.33.1 — 混合搜索索引新鲜度修复（代码审查发现）
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v3.33.1 — 混合搜索索引新鲜度修复（代码审查发现）. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_cfb0ee212bf2a234918f898536a05bf3 | https://github.com/Patdolitse/piia-engram/releases/tag/v3.33.1 | v3.33.1 — 混合搜索索引新鲜度修复（代码审查发现）

16. 维护坑 · 失败模式：maintenance: v3.33.2 — Codex 独立审查发现的修复 + 发布工作流加固

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v3.33.2 — Codex 独立审查发现的修复 + 发布工作流加固
• 对用户的影响：Upgrade or migration may change expected behavior: v3.33.2 — Codex 独立审查发现的修复 + 发布工作流加固
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v3.33.2 — Codex 独立审查发现的修复 + 发布工作流加固. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_1fcadca841756b4c403761fc6d2267a6 | https://github.com/Patdolitse/piia-engram/releases/tag/v3.33.2 | v3.33.2 — Codex 独立审查发现的修复 + 发布工作流加固

17. 维护坑 · 失败模式：maintenance: v3.36.0 — Identity-layer security: corpus encryption + governance closure

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v3.36.0 — Identity-layer security: corpus encryption + governance closure
• 对用户的影响：Upgrade or migration may change expected behavior: v3.36.0 — Identity-layer security: corpus encryption + governance closure
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v3.36.0 — Identity-layer security: corpus encryption + governance closure. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_d385dce779f00a690121395cadcd4eed | https://github.com/Patdolitse/piia-engram/releases/tag/v3.36.0 | v3.36.0 — Identity-layer security: corpus encryption + governance closure

18. 维护坑 · 失败模式：maintenance: v3.39.1 - Terminal Encoding Diagnostics

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v3.39.1 - Terminal Encoding Diagnostics
• 对用户的影响：Upgrade or migration may change expected behavior: v3.39.1 - Terminal Encoding Diagnostics
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: v3.39.1 - Terminal Encoding Diagnostics. Context: Observed when using python, windows
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_release | fmev_190c5a24ab97bf159a934181221eea0c | https://github.com/Patdolitse/piia-engram/releases/tag/v3.39.1 | v3.39.1 - Terminal Encoding Diagnostics