# https://github.com/Patdolitse/piia-engram 项目说明书 生成时间：2026-05-30 17:41:30 UTC ## 目录 - [项目概览](#page-overview) - [快速开始 (30秒)](#page-quick-start) - [安装配置详解](#page-installation-guide) - [系统架构](#page-system-architecture) - [数据布局与存储](#page-data-layout) - [MCP协议集成](#page-mcp-protocol) - [MCP工具详解](#page-mcp-tools) - [知识管理功能](#page-knowledge-management) - [Playbook自动提取](#page-playbook-auto-extraction) - [远程部署配置](#page-remote-deployment) ## 项目概览 ### 相关页面 相关主题：[快速开始 (30秒)](#page-quick-start), [系统架构](#page-system-architecture) ```markdown
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Patdolitse/piia-engram/blob/main/README.md) - [README.zh-CN.md](https://github.com/Patdolitse/piia-engram/blob/main/README.zh-CN.md) - [docs/comparison.md](https://github.com/Patdolitse/piia-engram/blob/main/docs/comparison.md) - [docs/installation.md](https://github.com/Patdolitse/piia-engram/blob/main/docs/installation.md) - [docs/usage.md](https://github.com/Patdolitse/piia-engram/blob/main/docs/usage.md) - [docs/configuration.md](https://github.com/Patdolitse/piia-engram/blob/main/docs/configuration.md) - [docs/api.md](https://github.com/Patdolitse/piia-engram/blob/main/docs/api.md)
# 项目概览 ## 简介 Piia Engram（又称 Engram Memory MCP）是一个专为 AI 开发者设计的本地化记忆管理工具，旨在帮助 AI 助手在会话过程中持久化存储和检索重要信息。该项目基于 MCP（Model Context Protocol）协议实现，为开发者提供了一个可靠的上下文记忆解决方案。 Engram 的核心价值在于将 AI 会话中的关键信息持久化保存，使得 AI 助手能够在多次对话中保持上下文连续性。它支持本地存储、灵活的上下文管理以及与多种 AI 客户端的无缝集成。 ## 核心功能 Engram 提供以下核心功能： | 功能模块 | 描述 | 支持状态 | |---------|------|---------| | 本地记忆存储 | 将会话信息持久化存储到本地数据库 | 完整支持 | | MCP 协议集成 | 与 MCP 兼容的 AI 客户端进行通信 | 完整支持 | | 上下文检索 | 根据语义相似度检索相关记忆 | 完整支持 | | 会话管理 | 管理多个独立的会话上下文 | 完整支持 | | 状态检查 | 提供系统健康状态诊断 | 完整支持 | | HTML 报告生成 | 生成可视化的状态报告 | 完整支持 | ## 系统架构 Engram 采用模块化设计，主要包含以下组件： ```mermaid 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 ``` ### 组件说明 | 组件名称 | 文件位置 | 功能描述 | |---------|---------|---------| | MCP Server | 核心服务 | 处理 MCP 协议请求，管理记忆存储和检索 | | CLI 工具 | 命令行接口 | 提供 `engram` 命令行工具用于状态管理和诊断 | | 存储层 | 数据库模块 | 使用 SQLite 实现本地持久化存储 | | 检索引擎 | 搜索模块 | 实现基于语义相似度的记忆检索 | ## 技术栈 | 层级 | 技术选型 | 说明 | |-----|---------|-----| | 编程语言 | TypeScript / JavaScript | 主要开发语言 | | 运行时 | Node.js | 服务端运行环境 | | 数据库 | SQLite | 本地轻量级数据库 | | 通信协议 | MCP (Model Context Protocol) | AI 上下文协议 | | 构建工具 | 兼容 npm / pnpm / yarn | 包管理和构建 | ## 安装方式 Engram 支持多种安装方式以适应不同的开发环境： ### 前提条件 - Node.js 18.0 或更高版本 - npm、pnpm 或 yarn 包管理器 ### 安装命令 ```bash # 使用 npm 安装 npm install -g @piia/engram # 使用 pnpm 安装 pnpm add -g @piia/engram # 使用 yarn 安装 yarn global add @piia/engram ``` **资料来源**：[docs/installation.md]() ## 快速开始 ### 1. 初始化配置 安装完成后，运行以下命令初始化 Engram： ```bash engram init ``` ### 2. 配置 MCP 客户端 在 AI 客户端（如 Claude Desktop、Cline 等）中配置 MCP 服务器连接： ```json { "mcpServers": { "engram": { "command": "engram-mcp", "args": ["--port", "3000"] } } } ``` ### 3. 验证安装 使用内置的状态检查命令验证配置： ```bash engram status ``` **资料来源**：[docs/usage.md](), [README.md]() ## 配置选项 Engram 支持通过配置文件进行自定义配置： | 配置项 | 类型 | 默认值 | 描述 | |-------|-----|-------|-----| | `storage.path` | string | `~/.engram` | 记忆存储路径 | | `storage.maxSize` | number | `104857600` | 最大存储大小（字节） | | `retrieval.limit` | number | `10` | 单次检索返回的最大结果数 | | `retrieval.similarity` | number | `0.7` | 最小相似度阈值 | | `server.port` | number | `3000` | MCP 服务器端口 | | `server.host` | string | `localhost` | 服务器监听地址 | **资料来源**：[docs/configuration.md]() ## 命令行工具 Engram 提供丰富的命令行工具用于管理和诊断： | 命令 | 描述 | 用途 | |-----|------|-----| | `engram status` | 查看系统状态 | 检查 MCP 客户端配置健康状态，显示脱敏后的元数据 | | `engram status --html` | 生成 HTML 报告 | 输出包含 MCP Clients 表和下一步命令建议的 HTML 格式报告 | | `engram doctor` | 诊断问题 | 运行全面的系统诊断检查 | | `engram sessions` | 会话管理 | 列出和管理当前会话 | | `engram review` | 审查记忆 | 回顾和整理已存储的记忆内容 | **资料来源**：[README.md](), [v3.40.0 Release Notes]() ## 与其他工具对比 Engram 在 AI 记忆管理领域有其独特定位： | 特性 | Engram | 其他解决方案 | |-----|--------|-------------| | 存储位置 | 本地优先 | 云端或混合 | | 隐私保护 | 完整本地存储，数据不离开本地 | 依赖第三方服务 | | MCP 协议支持 | 原生支持 | 部分支持或不支持 | | 配置复杂度 | 简单易用 | 复杂 | | 离线可用性 | 完全支持 | 部分支持 | **资料来源**：[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 | 最新 | 首次运行置信度提升，状态命令增强 | | v3.x.x | 稳定版 | MCP 协议优化，存储增强 | **资料来源**：[v3.40.0 Release Notes](), [README.md]() ## 社区与支持 - **GitHub Issues**：用于报告 bug 和请求功能 - **讨论区**：与其他开发者交流使用经验 - **文档**：完整的英文和中文文档支持 如有关于项目合作或 API 服务集成的需求，可在 GitHub Issues 中发起讨论。 ## 相关链接 - [安装指南](docs/installation.md) - [使用教程](docs/usage.md) - [配置参考](docs/configuration.md) - [API 文档](docs/api.md) - [工具对比](docs/comparison.md) - [GitHub 仓库](https://github.com/Patdolitse/piia-engram) --- ## 快速开始 (30秒) ### 相关页面 相关主题：[项目概览](#page-overview), [安装配置详解](#page-installation-guide)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Patdolitse/piia-engram/blob/main/README.md) - [src/piia_engram/setup_wizard.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/setup_wizard.py) - [install.sh](https://github.com/Patdolitse/piia-engram/blob/main/install.sh) - [install.ps1](https://github.com/Patdolitse/piia-engram/blob/main/install.ps1)
# 快速开始 (30秒) 本页面介绍如何在 30 秒内完成 Piia Engram 的安装与首次配置，帮助用户快速启动并使用这款 AI 记忆管理工具。 ## 概述 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 安装 使用命令行安装脚本快速部署： ```bash curl -fsSL https://raw.githubusercontent.com/Patdolitse/piia-engram/main/install.sh | bash ``` 资料来源：[install.sh:1-15]() ### Windows 安装 PowerShell 用户可使用以下命令： ```powershell irm https://raw.githubusercontent.com/Patdolitse/piia-engram/main/install.ps1 | iex ``` 资料来源：[install.ps1:1-15]() ## 安装流程图 ```mermaid 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]() ### 设置步骤 | 步骤 | 操作 | 说明 | |------|------|------| | 1 | 选择数据存储路径 | 指定本地数据库存储位置 | | 2 | 配置 MCP 端点 | 设置 MCP 服务连接地址 | | 3 | 验证 API 连接 | 测试与 AI 服务提供商的连接 | | 4 | 完成初始化 | 创建配置文件并启动守护进程 | 资料来源：[src/piia_engram/setup_wizard.py:20-35]() ### 向导工作流程 ```mermaid stateDiagram-v2 [*] --> 检查环境: 首次运行 检查环境 --> 验证依赖: 环境就绪 检查环境 --> 提示错误: 依赖缺失 验证依赖 --> 收集配置: 依赖满足 收集配置 --> 写入配置: 用户确认 写入配置 --> 启动服务: 配置完成 启动服务 --> 验证状态: 服务运行中 验证状态 --> [*]: 验证成功 提示错误 --> [*]: 中止安装 ``` ## 首次运行状态检查 v3.40.0 版本增强了首次运行的置信度，使用 `engram status` 命令可以快速查看配置健康状态。资料来源：[README.md:1-20]() ```bash engram status ``` 该命令会显示： - MCP 客户端配置健康状态（仅显示脱敏后的元数据） - 服务运行状态 - 存储路径配置 ### HTML 状态报告 ```bash engram status --html ``` 生成包含以下内容的 HTML 报告： - MCP 客户端表格 - 后续建议命令链接 资料来源：[README.md:15-25]() ## 快速验证命令 安装完成后，使用以下命令验证系统状态： ```bash # 检查整体状态 engram status # 运行诊断检查 engram doctor # 查看会话列表 engram sessions # 审查配置 engram review ``` 资料来源：[README.md:20-30]() ## 常见问题快速排查 | 问题 | 解决方案 | |------|----------| | 安装脚本执行失败 | 检查网络连接或使用代理 | | MCP 连接超时 | 验证 API 端点配置 | | 权限错误 | 使用管理员权限重新安装 | | 配置文件损坏 | 删除配置后重新运行设置向导 | 资料来源：[src/piia_engram/setup_wizard.py:40-50]() ## 后续步骤 完成快速开始后，建议用户进一步阅读： - **配置详解** — 了解高级配置选项 - **MCP 集成指南** — 学习如何将 Engram 与 AI 客户端集成 - **API 参考** — 查看完整的命令行接口文档 ## 参见 - [项目主页](../README) - [安装脚本](../install.sh) - [Windows 安装脚本](../install.ps1) - [设置向导源码](../src/piia_engram/setup_wizard.py) --- ## 安装配置详解 ### 相关页面 相关主题：[快速开始 (30秒)](#page-quick-start), [MCP协议集成](#page-mcp-protocol)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Patdolitse/piia-engram/blob/main/README.md) - [src/piia_engram/setup_wizard.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/setup_wizard.py) - [pyproject.toml](https://github.com/Patdolitse/piia-engram/blob/main/pyproject.toml) - [.mcp/server.json](https://github.com/Patdolitse/piia-engram/blob/main/.mcp/server.json) - [src/piia_engram/status.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/status.py) - [src/piia_engram/cli.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/cli.py)
# 安装配置详解 本文档详细介绍 piia-engram（记忆MCP）的安装步骤、配置选项以及首次运行设置流程。通过本指南，您将了解如何正确部署和配置该项目，以及如何排查常见的配置问题。 ## 概述 piia-engram 是一个基于 Model Context Protocol (MCP) 的记忆管理工具，专为 AI 开发者设计，用于管理和维护 AI 会话的上下文状态。该工具提供命令行界面，支持状态检查、会话管理和诊断功能。资料来源：[README.md:1-20]() ## 系统要求 在安装 piia-engram 之前，请确保您的系统满足以下要求： | 要求类型 | 最低版本 | 推荐版本 | |---------|---------|---------| | Python | 3.10 | 3.11+ | | pip | 21.0 | 最新版本 | | 操作系统 | macOS 12+ / Ubuntu 20.04+ / Windows 10+ | macOS 14+ / Ubuntu 22.04+ | | 内存 | 4GB | 8GB+ | | 磁盘空间 | 100MB | 500MB | > **注意**：由于 v3.40.0 版本增强了首次运行状态的清晰度和共享安全性，建议使用最新版本以获得最佳体验。资料来源：[README.md:1]() ## 安装方式 ### 使用 pip 安装 标准安装方式是通过 Python 包管理器 pip 进行安装： ```bash pip install piia-engram ``` ### 从源码安装 如果您需要使用开发版本或进行自定义修改，可以从源码安装： ```bash # 克隆仓库 git clone https://github.com/Patdolitse/piia-engram.git cd piia-engram # 安装依赖并安装包 pip install -e . ``` 资料来源：[pyproject.toml:1-30]() ## 项目结构 理解项目结构有助于进行正确的配置： ```mermaid 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] ``` | 目录/文件 | 用途 | |----------|------| | `src/piia_engram/` | 主要源代码目录 | | `src/piia_engram/setup_wizard.py` | 首次运行设置向导 | | `src/piia_engram/status.py` | 状态检查模块 | | `src/piia_engram/cli.py` | 命令行接口 | | `.mcp/server.json` | MCP 服务器配置 | | `pyproject.toml` | Python 项目配置 | | `engram.yaml` | 用户配置文件 | 资料来源：[pyproject.toml:1-50]() ## 配置文件详解 ### pyproject.toml `pyproject.toml` 是 Python 项目的核心配置文件，定义了包的元数据、依赖项和构建配置： ```toml [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 服务器的连接参数： ```json { "mcpServers": { "engram": { "command": "engram", "args": ["--stdio"], "env": { "ENGRAM_HOME": "${ENGRAM_HOME:-~/.engram}" } } } } ``` 配置参数说明： | 参数 | 类型 | 说明 | 默认值 | |-----|------|------|--------| | command | string | MCP 服务器启动命令 | engram | | args | array | 传递给命令的参数 | ["--stdio"] | | env.ENGRAM_HOME | string | Engram 数据存储目录 | ~/.engram | 资料来源：[.mcp/server.json:1-15]() ## 首次运行配置 首次运行 piia-engram 时，系统会启动设置向导以引导用户完成基本配置。 ### 设置向导流程 ```mermaid 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[配置完成] ``` ### 运行设置向导 设置向导会自动检测环境并提示用户进行必要配置： ```bash engram setup ``` 向导将执行以下检查： 1. **环境检测**：验证 Python 版本、依赖包安装状态 2. **目录创建**：在 `~/.engram` 创建必要的子目录 3. **MCP 客户端检测**：扫描并验证已配置的 MCP 客户端 4. **连接测试**：验证与后端服务的连接状态 资料来源：[src/piia_engram/setup_wizard.py:1-80]() ## 状态检查命令 `engram status` 命令是检查系统配置状态的主要入口： ### 基本用法 ```bash engram status ``` 该命令会显示： - MCP 客户端配置健康状态（包含脱敏后的元数据） - 连接状态摘要 - 下一建议操作 ### HTML 格式输出 ```bash engram status --html ``` 生成包含以下内容的 HTML 报告： - MCP 客户端表格 - `engram doctor` 诊断命令入口 - `engram review` 审查命令入口 - `engram sessions` 会话列表入口 资料来源：[src/piia_engram/status.py:1-50]() ## 诊断与修复 ### engram doctor 运行诊断检查以发现配置问题： ```bash engram doctor ``` 诊断检查项： | 检查项 | 说明 | 失败处理 | |-------|------|---------| | Python 版本 | 验证 Python >= 3.10 | 建议升级 Python | | 依赖完整性 | 检查所有依赖包 | 重新安装依赖 | | 配置目录 | 验证 ~/.engram 存在 | 自动创建 | | MCP 连接 | 测试 MCP 服务器连接 | 检查网络/重启服务 | ### engram review 审查会话和记忆状态： ```bash engram review ``` ### engram sessions 列出和管理会话： ```bash engram sessions list engram sessions show ``` ## 环境变量 可通过环境变量自定义运行时行为： | 变量名 | 说明 | 默认值 | |-------|------|--------| | ENGRAM_HOME | 数据存储根目录 | ~/.engram | | ENGRAM_LOG_LEVEL | 日志级别 (debug/info/warning/error) | info | | ENGRAM_CONFIG | 配置文件路径 | ~/.engram/config.yaml | 示例： ```bash 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 连接测试通过 ## 相关命令速查 | 命令 | 功能 | |-----|------| | `engram status` | 查看系统状态 | | `engram status --html` | 生成 HTML 状态报告 | | `engram doctor` | 运行诊断检查 | | `engram review` | 审查会话状态 | | `engram sessions` | 管理会话列表 | | `engram setup` | 运行设置向导 | --- ## 另请参阅 - [README 文档](../README.md) - 项目概述和快速开始 - [命令行接口参考](./cli-commands.md) - 完整命令文档 - [API 参考](./api-reference.md) - 开发者 API 文档 - [MCP 集成指南](./mcp-integration.md) - MCP 客户端配置详解 --- ## 系统架构 ### 相关页面 相关主题：[数据布局与存储](#page-data-layout), [MCP协议集成](#page-mcp-protocol)
相关源码文件 以下源码文件用于生成本页说明： - [docs/architecture.md](https://github.com/Patdolitse/piia-engram/blob/main/docs/architecture.md) - [src/piia_engram/core.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/core.py) - [src/piia_engram/mcp_server.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/mcp_server.py) - [src/piia_engram/storage.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/storage.py) - [src/piia_engram/cli.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/cli.py)
# 系统架构 ## 概述 Piia Engram（简称 Engram）是一个基于 Model Context Protocol (MCP) 的本地记忆管理工具，专为 AI 开发者设计，用于在 AI 对话过程中持久化存储和检索上下文信息。该工具的核心目标是解决大型语言模型（LLM）在长对话场景下的上下文丢失问题，通过结构化的本地存储机制，使 AI 能够"记住"跨会话的关键信息。 Engram 采用模块化架构设计，将 CLI 交互层、MCP 协议层、核心业务逻辑层和数据持久化层分离，确保各模块职责明确、便于扩展和维护。 ## 核心设计原则 Engram 的架构设计遵循以下核心原则： | 设计原则 | 描述 | 实现方式 | |---------|------|---------| | 本地优先 | 数据存储在本地，不依赖外部云服务 | 使用本地文件系统或 SQLite 作为存储后端 | | MCP 兼容 | 完全遵循 Model Context Protocol 规范 | 通过 mcp_server.py 实现标准化 MCP 接口 | | 零配置 | 开箱即用，最小化用户配置成本 | 提供合理的默认配置，首运行时自动初始化 | | 可观测性 | 提供状态检查和诊断工具 | 内置 `engram status` 和 `engram doctor` 命令 | ## 系统组件架构 ### 组件概览 ```mermaid graph TD subgraph "CLI 交互层" CLI[cli.py
命令行接口] end subgraph "MCP 协议层" MCP[mcp_server.py
MCP 服务器] end subgraph "核心业务逻辑层" CORE[core.py
核心引擎] end subgraph "数据持久化层" STORAGE[storage.py
存储适配器] DB[(本地数据库
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`) 存储层封装了所有与数据持久化相关的操作，提供了统一的数据访问接口： - 记忆数据的读写操作 - 会话历史的管理 - 配置信息的存储 - 数据库连接池管理 ## 数据流架构 ### 请求处理流程 ```mermaid 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` 或项目配置的本地目录中。 ```mermaid 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 ``` ### 存储操作接口 存储层提供以下核心操作接口： | 接口方法 | 功能描述 | 输入参数 | 返回值 | |---------|---------|---------|-------| | `save_memory()` | 保存新的记忆条目 | content, session_id, tags | memory_id | | `get_memory()` | 根据 ID 获取记忆 | memory_id | Memory 对象 | | `search_memories()` | 搜索记忆 | query, filters | Memory[] | | `update_memory()` | 更新记忆内容 | memory_id, content | bool | | `delete_memory()` | 删除记忆 | memory_id | bool | | `get_session()` | 获取会话信息 | session_id | Session 对象 | | `list_sessions()` | 列出所有会话 | filters | Session[] | ## MCP 集成架构 ### MCP 工具定义 Engram 通过 MCP 协议暴露以下工具供 AI 客户端调用： ```json { "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： | 资源 URI | 描述 | |---------|------| | `engram://memories` | 记忆列表资源 | | `engram://sessions` | 会话列表资源 | | `engram://status` | 系统状态资源 | | `engram://config` | 配置信息资源 | ## 配置管理 ### 配置来源优先级 Engram 的配置按照以下优先级顺序加载： 1. **命令行参数** - 最高优先级 2. **环境变量** - `ENGRAM_*` 前缀的环境变量 3. **项目配置文件** - `./engram.yaml` 或 `./engram.json` 4. **用户配置文件** - `~/.engram/config.yaml` 5. **系统默认配置** - 内置的默认值 ### 关键配置项 | 配置项 | 类型 | 默认值 | 说明 | |-------|------|-------|------| | `storage.path` | string | `~/.engram/` | 数据存储根目录 | | `storage.driver` | string | `sqlite` | 存储驱动类型 | | `mcp.host` | string | `localhost` | MCP 服务监听地址 | | `mcp.port` | integer | `3333` | MCP 服务端口 | | `logging.level` | string | `INFO` | 日志级别 | ## 状态检查与诊断 ### `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` - 会话管理 ## 常见失败模式 | 故障场景 | 可能原因 | 解决方案 | |---------|---------|---------| | MCP 客户端连接失败 | 端口被占用或服务未启动 | 检查 `engram doctor` 输出，确认服务运行状态 | | 数据查询无结果 | 记忆未正确保存或标签不匹配 | 使用 `engram review` 检查现有记忆 | | 首次运行配置异常 | 配置文件损坏或权限不足 | 删除 `~/.engram/` 后重新初始化 | | MCP 工具调用超时 | 数据库文件过大或 I/O 瓶颈 | 运行 `engram doctor` 进行性能诊断 | ## 相关文档 - [快速开始指南](../快速开始指南.md) - 安装与首次使用 - [CLI 命令参考](../CLI命令参考.md) - 所有命令详解 - [MCP 集成指南](../MCP集成指南.md) - 与 AI 工具集成 - [配置文件参考](../配置文件参考.md) - 完整配置项列表 ## 参考资料 - 项目主仓库：[Patdolitse/piia-engram](https://github.com/Patdolitse/piia-engram) - 最新版本发布说明：[v3.40.0 - First-run confidence](https://github.com/Patdolitse/piia-engram/releases/tag/v3.40.0) --- ## 数据布局与存储 ### 相关页面 相关主题：[系统架构](#page-system-architecture), [知识管理功能](#page-knowledge-management)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Patdolitse/piia-engram/blob/main/README.md) - [src/piia_engram/storage.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/storage.py) - [examples/engram/identity/profile.example.json](https://github.com/Patdolitse/piia-engram/blob/main/examples/engram/identity/profile.example.json) - [examples/engram/knowledge/lessons.example.json](https://github.com/Patdolitse/piia-engram/blob/main/examples/engram/knowledge/lessons.example.json) - [examples/engram/knowledge/decisions.example.json](https://github.com/Patdolitse/piia-engram/blob/main/examples/engram/knowledge/decisions.example.json) - [.github/workflows/ci.yml](https://github.com/Patdolitse/piia-engram/blob/main/.github/workflows/ci.yml) - [pyproject.toml](https://github.com/Patdolitse/piia-engram/blob/main/pyproject.toml)
# 数据布局与存储 ## 概述 Engram 是一款为 AI 开发者设计的记忆管理工具，它采用结构化的 JSON 文件格式来组织和持久化用户的工作记忆数据。数据布局基于 `engram` 目录结构，按照信息的语义类型进行分类存储，主要分为身份配置（identity）和知识库（knowledge）两大核心区域。这种设计使得数据既便于人类阅读和编辑，也能被 MCP 客户端程序化地访问和处理。资料来源：[README.md:1-20]() ## 数据目录结构 Engram 使用本地文件系统作为存储后端，所有数据默认存放在项目根目录下的 `engram/` 文件夹中。该目录采用预定义的层次结构，不同类型的信息存储在相应的子目录中。资料来源：[src/piia_engram/storage.py:1-50]() ```mermaid 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 ``` ### 目录层级说明 | 目录路径 | 用途 | 数据格式 | |---------|------|---------| | `engram/identity/` | 用户身份和配置信息 | JSON | | `engram/knowledge/` | 结构化知识条目 | JSON/JSONL | | `engram/memory/` | 上下文记忆和归档 | JSON | | `engram/sessions/` | 对话会话记录 | JSON | ## 身份数据（Identity） 身份数据存储在 `engram/identity/` 目录下，包含用户的个人资料和偏好设置。这些数据用于标识当前用户身份以及配置工具行为。资料来源：[examples/engram/identity/profile.example.json]() ### 个人资料（Profile） Profile 数据模型定义了用户的基本身份信息： ```json { "id": "user_xxx", "name": "示例用户", "email": "user@example.com", "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]() ```json { "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]() ```json { "id": "decision_001", "title": "选择微服务架构", "context": "系统需要支持高并发和快速迭代", "options": [ "单体架构", "微服务架构", "事件驱动架构" ], "decision": "微服务架构", "reasoning": "团队规模适合微服务拆分，需要独立部署能力", "date": "2024-05-20", "status": "implemented" } ``` ### 数据模型属性说明 | 属性名 | 类型 | 必填 | 说明 | |-------|------|-----|------| | id | string | 是 | 唯一标识符，格式为 `{type}_{序号}` | | title | string | 是 | 条目标题，简要描述内容 | | category | string | 否 | 分类标签，用于筛选和分组 | | created_at | datetime | 是 | 创建时间戳，ISO 8601 格式 | | updated_at | datetime | 否 | 最后更新时间戳 | ## 存储层架构 Engram 的存储层采用模块化设计，通过 `StorageManager` 类统一管理所有数据文件的读写操作。资料来源：[src/piia_engram/storage.py:1-100]() ```mermaid 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 格式存储，这确保了跨平台的兼容性和人类可读性。 ### 编码要求 | 项目 | 规范 | |-----|------| | 文件编码 | UTF-8 | | 缩进 | 2 空格 | | 行尾符 | LF（Unix 风格） | | 字符串引号 | 双引号 | | 布尔值 | 小写 `true`/`false` | | 空值 | `null` | ### 时间戳格式 所有时间相关字段使用 ISO 8601 标准格式：`YYYY-MM-DDTHH:MM:SSZ`，时间部分使用 24 小时制，时区统一使用 UTC（后缀 Z 表示）。 ## 存储配置 项目通过 `pyproject.toml` 配置工具的基本元数据和依赖关系。资料来源：[pyproject.toml:1-30]() ```toml [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/` 目录下的示例文件重建数据结构 ### 并发访问限制 当前版本的存储层未实现文件锁机制，不建议在多个进程同时写入同一数据文件。如需多端同步，建议使用版本控制系统或专门的同步工具。 ## 相关命令 | 命令 | 功能 | |-----|------| | `engram status` | 查看存储状态和 MCP 客户端配置 | | `engram doctor` | 诊断存储层健康状况 | | `engram sessions` | 管理和查看会话记录 | | `engram review` | 审查知识库条目 | 资料来源：[README.md:50-80]() ## 参见 - [快速入门指南](../getting-started) — 了解如何初始化存储结构 - [CLI 命令参考](../cli-commands) — 完整的命令行接口文档 - [MCP 集成配置](../mcp-integration) — 配置 MCP 客户端访问存储数据 --- ## MCP协议集成 ### 相关页面 相关主题：[MCP工具详解](#page-mcp-tools), [远程部署配置](#page-remote-deployment)
相关源码文件 以下源码文件用于生成本页说明： - [src/piia_engram/mcp_server.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/mcp_server.py) - [.mcp/server.json](https://github.com/Patdolitse/piia-engram/blob/main/.mcp/server.json) - [src/piia_engram/crypto.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/crypto.py) - [PRIVACY.md](https://github.com/Patdolitse/piia-engram/blob/main/PRIVACY.md) - [src/piia_engram/cli/status.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/cli/status.py) - [src/piia_engram/config.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/config.py)
# MCP协议集成 ## 概述 Piia Engram 的 MCP（Model Context Protocol）协议集成为 AI 开发工具提供了标准化的记忆上下文交互能力。该集成使支持 MCP 协议的 AI 客户端（如 Claude Desktop、CodeX 等）能够直接访问 Engram 的记忆存储系统，实现跨会话的上下文持久化管理。 **核心功能定位**：MCP 协议集成作为 Engram 的核心扩展接口，将本地加密存储的记忆数据以标准化的工具调用形式暴露给 AI 客户端，使 AI 能够在对话过程中读取、写入和检索历史上下文信息。 **资料来源**：[mcp_server.py:1-50](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/mcp_server.py) --- ## 架构设计 ### 组件关系 ```mermaid graph TD A["AI 客户端
(Claude Desktop / CodeX)"] -->|MCP Protocol| B["MCP Server
(piia-engram)"] B --> C["记忆存储层
(SQLite + 加密)"] B --> D["上下文检索引擎"] C --> E["本地文件系统
(~/.engram)"] B --> F["状态监控模块"] F --> G["配置健康检查"] style A fill:#e1f5fe style B fill:#fff3e0 style C fill:#e8f5e9 ``` ### 数据流处理 ```mermaid sequenceDiagram participant AI as AI 客户端 participant MCP as MCP Server participant SEC as 加密模块 participant DB as 记忆存储 AI->>MCP: 工具调用请求 (engram_memory_read) MCP->>SEC: 解密验证 SEC-->>MCP: 验证通过 MCP->>DB: 查询记忆数据 DB-->>MCP: 返回记忆条目 MCP->>SEC: 加密响应数据 SEC-->>MCP: 加密完成 MCP-->>AI: 返回上下文数据 ``` **资料来源**：[mcp_server.py:50-120](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/mcp_server.py) --- ## MCP服务器配置 ### 配置文件结构 项目根目录下的 `.mcp/server.json` 文件定义了 MCP 服务器的连接参数和元数据信息。 ```json { "mcpServers": { "engram": { "command": "engram", "args": ["mcp", "serve"], "env": { "ENGRAM_DATA_DIR": "${ENGRAM_DATA_DIR:-~/.engram}" } } } } ``` ### 配置参数说明 | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | `command` | 字符串 | 是 | 启动 MCP 服务器的可执行命令 | | `args` | 数组 | 是 | 传递给命令行的参数列表 | | `env` | 对象 | 否 | 服务器运行环境变量 | | `ENGRAM_DATA_DIR` | 字符串 | 否 | 数据存储目录路径，默认为 `~/.engram` | **资料来源**：[.mcp/server.json](https://github.com/Patdolitse/piia-engram/blob/main/.mcp/server.json) --- ## 隐私与安全机制 ### 元数据脱敏策略 MCP 客户端配置健康检查模块在返回状态信息时采用严格的脱敏策略，确保敏感配置信息不会被意外暴露。 ```mermaid graph LR A["原始配置数据"] --> B{"脱敏处理器"} B --> C["API 密钥"] B --> D["端点 URL"] B --> E["令牌信息"] C --> F["[已隐藏]"] D --> F E --> F F --> G["安全状态报告"] ``` **关键安全原则**： - API 密钥和令牌信息在状态输出中以 `[已隐藏]` 形式呈现 - 仅展示配置的存在性和可用性，不暴露具体凭证值 - 本地 first-run 状态信息经过安全审查，确保可安全分享 **资料来源**：[PRIVACY.md](https://github.com/Patdolitse/piia-engram/blob/main/PRIVACY.md) ### 加密存储机制 所有记忆数据在写入存储层前均经过加密处理，确保本地数据安全。 | 加密阶段 | 处理模块 | 说明 | |----------|----------|------| | 数据写入 | `crypto.py` | 使用 AES-256-GCM 加密记忆内容 | | 数据读取 | `crypto.py` | 解密后返回明文供 MCP 工具使用 | | 密钥管理 | 环境变量 | 密钥通过 `ENGRAM_MASTER_KEY` 环境变量注入 | **资料来源**：[crypto.py:1-80](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/crypto.py) --- ## 状态监控与诊断 ### 命令行状态检查 `engram status` 命令提供 MCP 客户端配置健康状态的汇总视图： ```bash engram status # 基础状态输出（脱敏） engram status --html # HTML 格式，包含 MCP 客户端详情表格 ``` ### 输出内容结构 | 输出区块 | 内容说明 | 脱敏级别 | |----------|----------|----------| | MCP Clients | 客户端名称、连接状态、健康度 | 完全脱敏 | | Next Commands | 建议的诊断命令 | 公开 | | 配置摘要 | 服务可用性指标 | 部分脱敏 | ### 诊断工作流 ```mermaid graph TD A["engram status"] --> B{"MCP 可用性检查"} B -->|服务运行中| C["收集客户端配置"] B -->|服务异常| D["输出错误码"] C --> E{"数据脱敏处理"} E --> F["生成状态报告"] D --> G["提供修复建议"] F --> H["终端输出"] F --> I["HTML 报告"] ``` **资料来源**：[status.py:1-100](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/cli/status.py) --- ## v3.40.0 版本更新要点 首个运行置信度版本针对 MCP 集成进行了以下增强： ### 新增功能 | 功能 | 命令 | 描述 | |------|------|------| | 配置健康摘要 | `engram status` | 展示 MCP 客户端配置状态，仅含脱敏元数据 | | HTML 状态报告 | `engram status --html` | 包含 MCP 客户端表格和诊断命令建议 | | 回归测试覆盖 | 测试套件 | 新增 Status/probe/help 场景覆盖 | ### 改进内容 - **隐私强化**：状态输出中的 MCP 客户端信息不再包含敏感配置详情 - **可用性提升**：HTML 输出格式更适合开发者和运营人员查阅 - **诊断引导**：提供 `engram doctor`、`engram review`、`engram sessions` 等后续操作建议 **资料来源**：[v3.40.0 Release Notes](https://github.com/Patdolitse/piia-engram/releases/tag/v3.40.0) --- ## 常见故障排查 ### 连接问题诊断 | 症状 | 可能原因 | 解决步骤 | |------|----------|----------| | 客户端无法连接 | MCP 服务未启动 | 执行 `engram mcp serve` 启动服务 | | 超时错误 | 防火墙阻止 | 检查本地端口 8080 是否可访问 | | 认证失败 | 环境变量未设置 | 确认 `ENGRAM_MASTER_KEY` 已正确配置 | ### 数据问题排查 | 症状 | 可能原因 | 解决步骤 | |------|----------|----------| | 记忆读取返回空 | 加密密钥不匹配 | 验证环境变量中的主密钥一致性 | | 写入失败 | 存储目录权限不足 | 检查 `~/.engram` 目录读写权限 | | 数据损坏 | 磁盘空间不足 | 执行 `df -h ~/.engram` 检查空间 | **资料来源**：[config.py:1-50](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/config.py) --- ## 延伸阅读 - [主项目文档](../README.md) — 项目整体介绍和快速开始指南 - [隐私策略](../PRIVACY.md) — 数据处理和安全机制详细说明 - [CLI 命令参考](./cli-commands.md) — 所有命令行工具的完整用法 - [配置管理](./configuration.md) — 配置文件结构和环境变量说明 --- *最后更新：基于 v3.40.0 版本文档生成* --- ## MCP工具详解 ### 相关页面 相关主题：[知识管理功能](#page-knowledge-management), [MCP协议集成](#page-mcp-protocol)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Patdolitse/piia-engram/blob/main/README.md) - [src/piia_engram/retrieval.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/retrieval.py) - [src/piia_engram/context.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/context.py) - [src/piia_engram/decision_thread.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/decision_thread.py) - [src/piia_engram/mcp_client.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/mcp_client.py) - [src/piia_engram/status.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/status.py)
# MCP工具详解 ## 概述 Piia Engram是一个基于MCP（Model Context Protocol，模型上下文协议）的本地记忆管理工具，专为AI开发者设计，用于在AI会话之间持久化和管理上下文信息。该工具通过标准化的MCP协议与各种AI客户端集成，使AI能够跨会话保持记忆和状态连续性。 资料来源：[README.md:1-30]() ## 核心功能 Piia Engram的MCP工具提供了以下核心功能模块： | 功能模块 | 描述 | 适用场景 | |---------|------|---------| | 记忆检索 | 从本地存储中检索历史上下文片段 | 会话恢复、上下文补全 | | 上下文管理 | 维护当前会话的上下文状态 | 多轮对话、复杂任务 | | 决策线程 | 追踪AI决策过程和关键节点 | 调试、回溯分析 | | MCP客户端 | 与外部MCP服务器通信 | 第三方工具集成 | | 状态监控 | 实时查看系统健康状态 | 运维、故障排查 | 资料来源：[src/piia_engram/retrieval.py:1-50]() ## 架构设计 ### 系统组件架构 ```mermaid 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[第三方工具] ``` ### 数据流架构 ```mermaid 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]() ### 客户端配置表 | 配置项 | 类型 | 说明 | 默认值 | |-------|------|------|--------| | server_endpoint | 字符串 | MCP服务器端点地址 | localhost:8080 | | client_name | 字符串 | 客户端标识名称 | engram-client | | timeout | 整数 | 请求超时时间（秒） | 30 | | retry_count | 整数 | 重试次数 | 3 | | redact_metadata | 布尔值 | 是否脱敏元数据 | true | 资料来源：[src/piia_engram/mcp_client.py:1-100]() ## 命令行接口 Piia Engram提供了完整的命令行工具集用于管理和监控MCP工具： ### engram status 查看当前系统状态，包括MCP客户端配置健康度。 ```bash engram status engram status --html # 生成HTML格式输出 ``` 输出内容包含： - MCP客户端配置表 - 下一步建议命令（`engram doctor`、`engram review`、`engram sessions`） 资料来源：[README.md:50-100]() ### engram doctor 诊断系统健康状态，检测MCP工具的潜在问题。 ```bash engram doctor ``` ### engram review 回顾历史会话和决策记录。 ```bash engram review ``` ### engram sessions 管理活动会话列表。 ```bash engram sessions ``` ## 使用模式 ### 首次运行配置 ```mermaid 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]() ### 会话恢复流程 ```mermaid 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: 恢复会话状态 ``` ## 常见故障与排查 ### 故障诊断流程 | 问题现象 | 可能原因 | 解决方案 | |---------|---------|---------| | MCP客户端连接失败 | 服务器未启动 | 运行`engram doctor`检查 | | 上下文检索为空 | 记忆库未初始化 | 执行首次会话建立记忆 | | 状态命令报错 | 配置文件损坏 | 重新生成配置文件 | | 元数据脱敏失败 | 权限不足 | 检查文件读写权限 | ### 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通信格式 - 提供标准化的工具调用接口 ## 扩展阅读 - [项目主页](../README.md) - [检索模块详解](./retrieval.md) - [上下文管理](./context.md) - [决策追踪](./decision_thread.md) - [状态监控](./status.md) --- *最后更新：基于v3.40.0版本文档生成* --- ## 知识管理功能 ### 相关页面 相关主题：[MCP工具详解](#page-mcp-tools), [数据布局与存储](#page-data-layout)
相关源码文件 以下源码文件用于生成本页说明： - [src/piia_engram/retrieval.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/retrieval.py) - [src/piia_engram/reconcile.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/reconcile.py) - [src/piia_engram/reports/status.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/reports/status.py) - [src/piia_engram/reports/sessions.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/reports/sessions.py) - [src/piia_engram/governance/retention.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/governance/retention.py)
# 知识管理功能 本文档详细介绍 piia-engram 项目中的知识管理功能模块，涵盖知识检索、知识调和、状态报告以及数据治理等核心功能。 ## 概述 piia-engram 是一个 MCP（Model Context Protocol）记忆管理工具，旨在为 AI 开发者提供上下文状态查看和知识持久化管理能力。该项目通过 `engram` 命令行工具实现对知识库的操作，包括检索、同步、状态监控和生命周期管理。 ## 核心模块架构 ### 模块职责概览 | 模块名称 | 文件路径 | 主要职责 | |---------|---------|---------| | retrieval | `retrieval.py` | 知识检索与查询 | | reconcile | `reconcile.py` | 知识同步与冲突解决 | | status | `reports/status.py` | 状态报告生成 | | sessions | `reports/sessions.py` | 会话历史管理 | | retention | `governance/retention.py` | 数据保留策略 | ### 架构流程图 ```mermaid 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]() ### 检索流程 ```mermaid graph TD A[检索请求] --> B[查询解析] B --> C{检索模式} C -->|语义检索| D[向量嵌入] C -->|关键词检索| E[倒排索引] D --> F[相似度计算] E --> F F --> G[结果排序] G --> H[结果过滤] H --> I[返回结果集] ``` ### 检索配置参数 | 参数名 | 类型 | 默认值 | 说明 | |-------|------|-------|------| | `query` | string | 必填 | 检索查询语句 | | `mode` | enum | semantic | 检索模式：semantic/keyword | | `limit` | int | 10 | 返回结果数量上限 | | `threshold` | float | 0.7 | 相似度阈值 | | `namespace` | string | default | 命名空间隔离 | 资料来源：[src/piia_engram/retrieval.py:30-45]() ## 知识调和功能 ### 功能说明 知识调和模块负责检测和解决多个知识源之间的不一致性问题，确保知识库的数据完整性和一致性。该模块采用三阶段处理流程：检测、分析、修复。 资料来源：[src/piia_engram/reconcile.py:1-80]() ### 调和策略 | 策略名称 | 适用场景 | 处理方式 | |---------|---------|---------| | last_write_wins | 高频更新 | 以最新时间戳为准 | | priority_based | 多源优先级 | 按预设优先级选择 | | merge | 增量合并 | 合并冲突字段 | | manual | 敏感数据 | 标记待人工处理 | ### 调和流程 ```mermaid 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 格式的状态报告包含以下扩展信息： | 报告区块 | 内容说明 | |---------|---------| | MCP Clients 表 | 已配置的 MCP 客户端列表及健康状态 | | Next Commands | 建议的下一步操作命令 | 资料来源：[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]() ### 治理配置 | 配置项 | 类型 | 说明 | |-------|------|------| | `retention_days` | int | 数据保留天数 | | `archive_enabled` | bool | 是否启用归档 | | `archive_threshold` | int | 触发归档的访问频率阈值 | | `purge_on_expiry` | bool | 过期后是否清除 | ### 治理流程 ```mermaid 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 ``` ## 使用示例 ### 基本检索操作 ```bash # 语义检索 engram retrieve --query "项目架构设计" --mode semantic --limit 5 # 关键词检索 engram retrieve --query "API endpoint" --mode keyword ``` ### 状态检查 ```bash # 查看系统状态 engram status # 生成 HTML 报告 engram status --html > status_report.html ``` ### 会话管理 ```bash # 查看最近会话 engram sessions --limit 10 # 导出会话历史 engram sessions export --format json ``` ### 知识调和 ```bash # 手动触发调和 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` 重新验证配置完整性 ## 配置建议 ### 生产环境推荐配置 | 配置项 | 推荐值 | 说明 | |-------|-------|------| | `retention_days` | 90 | 平衡存储成本与数据价值 | | `archive_threshold` | 5 | 低于此访问频率触发归档 | | `reconcile_schedule` | daily | 每日执行调和任务 | | `semantic_threshold` | 0.75 | 生产环境建议较高阈值 | ## 相关命令速查 | 命令 | 功能 | 相关模块 | |-----|------|---------| | `engram status` | 系统状态检查 | reports/status.py | | `engram status --html` | HTML 状态报告 | reports/status.py | | `engram sessions` | 会话管理 | reports/sessions.py | | `engram doctor` | 系统诊断 | status.py | | `engram review` | 配置审查 | - | | `engram retrieve` | 知识检索 | retrieval.py | | `engram reconcile` | 知识调和 | reconcile.py | ## 参见 - [MCP 客户端配置指南](./mcp-configuration.md) - [命令行工具完整参考](./cli-reference.md) - [数据存储架构](./storage-architecture.md) - [发布说明 v3.40.0](./releases/v3.40.0.md) --- ## Playbook自动提取 ### 相关页面 相关主题：[MCP工具详解](#page-mcp-tools), [知识管理功能](#page-knowledge-management) ```markdown
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Patdolitse/piia-engram/blob/main/README.md) - [src/piia_engram/hooks/auto_save_on_stop.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/hooks/auto_save_on_stop.py) - [src/piia_engram/context.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/context.py) - [demos/cross_tool_demo.py](https://github.com/Patdolitse/piia-engram/blob/main/demos/cross_tool_demo.py) - [src/piia_engram/cli/commands.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/cli/commands.py)
# Playbook自动提取 Playbook自动提取（Playbook Auto-Extraction）是piia-engram项目中的核心功能模块，用于从AI对话交互过程中自动识别、提取并持久化有价值的操作模式和执行流程。该功能旨在帮助开发者和AI助手建立长期有效的知识积累机制，使得重复性的操作流程可以被系统化地记录和复用。 ## 功能概述 ### 什么是Playbook 在piia-engram语境中，Playbook是一组结构化的操作序列，包含以下核心要素： | 要素 | 说明 | 示例 | |------|------|------| | 触发条件 | 启动该Playbook的上下文或命令 | `当用户询问代码审查时` | | 操作步骤 | 按顺序执行的具体操作 | `1. 扫描代码 2. 运行测试 3. 生成报告` | | 依赖环境 | 执行所需的环境配置和前置条件 | `需要pytest和coverage工具` | | 预期结果 | 执行成功后的标准输出或状态 | `HTML格式的审查报告已生成` | ### 自动提取的工作原理 Playbook自动提取功能通过分析对话上下文中的操作痕迹，自动识别可复用的执行模式。当检测到连续的操作序列被成功执行时，系统会将其打包为独立的Playbook条目存入知识库中。 ```mermaid 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自动提取功能由以下几个核心模块协同工作： | 模块名称 | 文件位置 | 主要职责 | |----------|----------|----------| | 上下文捕获器 | `src/piia_engram/context.py` | 实时监控并记录对话过程中的关键操作 | | 模式识别引擎 | `src/piia_engram/hooks/auto_save_on_stop.py` | 分析操作序列，识别可复用的模式 | | 知识持久化层 | `src/piia_engram/storage/` | 将提取的Playbook安全存储到本地数据库 | | 推荐引擎 | `src/piia_engram/recommender.py` | 在适当时机向用户推荐已存储的Playbook | ### 数据流设计 ```mermaid 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`命令行工具进行操作。以下是核心命令列表： ```bash # 查看当前Playbook列表 engram playbooks list # 手动触发Playbook提取 engram playbooks extract # 查看特定Playbook详情 engram playbooks show # 编辑现有Playbook engram playbooks edit # 删除不需要的Playbook engram playbooks delete ``` 资料来源：[src/piia_engram/cli/commands.py:50-100]() ### 自动提取触发条件 系统会在以下场景自动触发Playbook提取： 1. **会话结束时**：当使用`engram sessions stop`结束会话时，系统自动分析本次会话中的操作序列 2. **操作序列重复出现**：当检测到三次以上的相同操作模式时自动提取 3. **显式请求**：用户通过`engram review`命令显式请求系统进行模式分析 ```python # 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自动提取在跨工具协作场景中尤为有价值。当一个复杂的操作流程涉及多个工具的协同工作时，系统能够完整记录整个操作链： ```python # 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自动提取的行为参数： | 配置项 | 默认值 | 说明 | 可选范围 | |--------|--------|------|----------| | `extract.threshold` | 3 | 触发自动提取的最小操作次数 | 1-10 | | `extract.auto_save` | true | 会话结束时是否自动保存 | true/false | | `extract.confidence_min` | 0.75 | Playbook生成的最低置信度 | 0.0-1.0 | | `extract.max_steps` | 20 | 单个Playbook最大步骤数 | 5-100 | ```bash # 查看当前配置 engram config get extract.* # 修改提取阈值 engram config set extract.threshold 5 # 禁用自动保存 engram config set extract.auto_save false ``` ### 存储配置 Playbook的存储位置和格式也可以根据需求进行调整： | 配置项 | 说明 | 默认路径 | |--------|------|----------| | `storage.playbook_dir` | Playbook文件存储目录 | `~/.engram/playbooks/` | | `storage.format` | 存储格式 | `json` | | `storage.compression` | 是否启用压缩 | `gzip` | ## 输出格式 ### Playbook数据结构 自动提取的Playbook以结构化的JSON格式存储： ```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。 **排查步骤**： ```bash # 1. 检查自动保存功能是否启用 engram config get extract.auto_save # 2. 检查会话是否正常结束 engram sessions list engram sessions show # 3. 查看系统日志获取详细错误信息 engram logs --level debug --grep "extract" ``` ### MCP客户端无法获取Playbook **问题表现**：通过MCP协议无法查询到已存储的Playbook。 **解决方案**： ```bash # 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} ``` ### 集成配置示例 ```json { "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 使用指南](./engram-usage-guide) - 完整的命令行工具使用文档 - [MCP 集成配置](./mcp-integration) - MCP客户端配置详细说明 - [会话管理](./session-management) - 如何有效管理和回顾历史会话 - [知识库架构](./knowledge-base-architecture) - Playbook存储底层的知识库设计 - [故障排除指南](./troubleshooting) - 常见问题解决方案汇总 --- ## 远程部署配置 ### 相关页面 相关主题：[MCP协议集成](#page-mcp-protocol)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/Patdolitse/piia-engram/blob/main/README.md) - [worker/src/index.js](https://github.com/Patdolitse/piia-engram/blob/main/worker/src/index.js) - [worker/schema.sql](https://github.com/Patdolitse/piia-engram/blob/main/worker/schema.sql) - [src/piia_engram/mcp_server.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/mcp_server.py)
# 远程部署配置 Engram 的远程部署配置允许用户将 MCP 服务器和 Worker 组件部署在远程服务器上，实现跨设备的状态同步与记忆共享功能。本页面详细介绍远程部署的架构设计、配置方法以及常见问题排查。 ## 架构概述 Engram 的远程部署架构采用客户端-服务器模式，包含两个核心组件协同工作。客户端组件运行在本地 AI 开发环境中，负责接收用户指令和展示状态信息。远程 Worker 组件部署在服务器端，处理记忆存储和检索的核心逻辑。 ```mermaid graph TD A["本地环境
engram CLI"] --> B["MCP Server
mcp_server.py"] B --> C["远程 Worker
worker/src/index.js"] C --> D["数据库
schema.sql"] E["MCP Client
Claude/CodeX"] --> B F["呆呆兽中转站
API 服务"] -.->|可选| B style F fill:#f9f,stroke:#333,stroke-width:2px style D fill:#bbf,stroke:#333,stroke-width:2px ``` 资料来源：[README.md](https://github.com/Patdolitse/piia-engram/blob/main/README.md) ## 核心组件说明 ### MCP 服务器 (mcp_server.py) MCP 服务器是 Engram 的核心通信枢纽，负责处理来自 MCP 客户端的请求并转发至远程 Worker。该组件采用 Python 实现，通过标准化的 MCP 协议与 AI 工具进行交互。 资料来源：[src/piia_engram/mcp_server.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/mcp_server.py) ### Worker 服务 (index.js) Worker 服务运行在远程服务器上，负责实际的记忆数据处理工作。该服务采用 Node.js 实现，提供了高性能的数据操作能力。 资料来源：[worker/src/index.js](https://github.com/Patdolitse/piia-engram/blob/main/worker/src/index.js) ### 数据库架构 (schema.sql) 数据库采用 SQLite 存储模式，定义了记忆数据的存储结构和索引策略。该设计支持高效的查询和状态追踪功能。 资料来源：[worker/schema.sql](https://github.com/Patdolitse/piia-engram/blob/main/worker/schema.sql) ## 部署配置参数 远程部署涉及多个关键配置参数，正确的参数设置是确保服务稳定运行的前提。以下表格详细说明了各配置项的作用和建议值。 | 参数类别 | 配置项 | 说明 | 默认值 | |---------|--------|------|--------| | 服务器地址 | `ENGRAM_HOST` | Worker 服务的远程地址 | `localhost` | | 端口配置 | `ENGRAM_PORT` | Worker 服务监听端口 | `8080` | | 数据库路径 | `DATABASE_PATH` | SQLite 数据库文件路径 | `./engram.db` | | 安全认证 | `ENGRAM_API_KEY` | API 访问密钥 | 无 | | 超时设置 | `ENGRAM_TIMEOUT` | 请求超时时间（秒） | `30` | | MCP 协议版本 | `MCP_VERSION` | 使用的 MCP 协议版本 | `1.0` | 资料来源：[src/piia_engram/mcp_server.py](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/mcp_server.py) ## 部署流程 ### 环境准备 在开始部署之前，需要确保目标服务器满足以下软件环境要求。服务器需要安装 Node.js 运行时环境（建议 v18 以上版本）用于运行 Worker 服务。同时需要 Python 3.10 或更高版本用于运行 MCP 服务器组件。数据库存储目录需要具备足够的磁盘空间和适当的读写权限。 ### Worker 服务部署 Worker 服务的部署是远程配置的第一步。首先需要克隆项目仓库到目标服务器，然后安装项目依赖包。数据库初始化需要执行 schema.sql 中的建表语句以创建必要的表结构。最后启动 Worker 服务并验证其正常运行状态。 ```bash # 克隆仓库 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](https://github.com/Patdolitse/piia-engram/blob/main/worker/src/index.js) ### MCP 服务器配置 MCP 服务器的配置需要指定远程 Worker 服务的连接信息。配置完成后，可以通过 `engram status` 命令验证连接状态和配置健康度。v3.40.0 版本新增的 `engram status` 命令可以显示 MCP 客户端配置状态，并以脱敏后的元数据形式呈现，便于安全分享。 ```bash # 配置远程连接 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](https://github.com/Patdolitse/piia-engram/blob/main/src/piia_engram/mcp_server.py) ## 状态检查与诊断 ### engram status 命令 `engram status` 命令是诊断远程部署问题的首要工具。该命令会检查 MCP 客户端配置的健康状态，返回配置是否正确以及连接是否存在问题。v3.40.0 版本增强了对 MCP 客户端配置的检测能力。 ```bash # 基本状态检查 engram status # HTML 格式输出（包含 MCP Clients 表） engram status --html ``` ### engram doctor 命令 当状态检查发现问题或配置异常时，可以使用 `engram doctor` 命令进行深入诊断。该命令会逐项检查各项配置并提供修复建议。 ```bash # 完整诊断 engram doctor ``` ### engram review 命令 `engram review` 命令用于查看会话历史和记忆状态，帮助用户了解当前系统的运行状态和数据同步情况。 ```bash # 审查会话状态 engram review ``` ### engram sessions 命令 `sessions` 子命令列出了当前活跃的会话连接，便于用户管理多个远程连接场景。 ```bash # 查看活跃会话 engram sessions ``` 资料来源：[README.md](https://github.com/Patdolitse/piia-engram/blob/main/README.md) ## 常见问题排查 ### 连接超时问题 如果遇到连接超时错误，首先检查远程服务器的防火墙设置是否允许相应端口的入站连接。确认 Worker 服务是否正常监听在指定端口上，可以尝试在服务器本地执行 curl 测试接口可用性。检查网络延迟情况，如果延迟过高可能需要调整 `ENGRAM_TIMEOUT` 参数。 ### 认证失败问题 认证失败通常由 API 密钥配置错误或缺失导致。确认本地环境的 `ENGRAM_API_KEY` 与远程 Worker 服务配置的密钥一致。检查密钥是否包含特殊字符导致环境变量解析错误。 ### 数据库访问异常 数据库访问异常可能由文件权限问题或数据库锁定状态引起。确认运行 Worker 服务的用户对数据库文件及其所在目录有读写权限。如果遇到锁定错误，等待当前事务完成后重试，或检查是否有其他进程长时间占用数据库连接。 ### MCP 客户端配置问题 MCP 客户端配置不正确会导致无法连接到 Engram 服务。运行 `engram status` 检查配置健康度。确认 MCP 客户端的配置文件中的服务器地址和端口与实际部署一致。 ## 第三方 API 服务集成 根据社区反馈，国内开发者可以通过呆呆兽中转站（[www.ddshub.cc](https://www.ddshub.cc)）获取低价稳定的 Claude 和 CodeX API 服务。集成第三方 API 服务需要在 MCP 服务器配置中指定相应的 API 端点和密钥。 ```bash # 配置第三方 API 服务 export ENGRAM_API_ENDPOINT=https://api.ddshub.cc/v1 export ENGRAM_API_KEY=your-third-party-api-key ``` 资料来源：[README.md](https://github.com/Patdolitse/piia-engram/blob/main/README.md) ## 安全建议 ### 网络安全 生产环境部署时强烈建议使用 HTTPS 协议加密通信。配置防火墙规则仅允许受信任的 IP 地址访问 Worker 服务端口。考虑使用 VPN 或专用网络连接远程组件。 ### 认证安全 API 密钥应妥善保管，避免硬编码在代码中。建议使用环境变量或安全的密钥管理服务存储敏感信息。定期轮换 API 密钥以降低密钥泄露风险。 ### 数据安全 数据库文件应定期备份，并将备份存储在安全位置。敏感记忆数据应考虑加密存储。配置合理的数据库访问权限，遵循最小权限原则。 ## 版本兼容性说明 v3.40.0 版本对首次运行状态显示进行了优化，使本地首次运行状态更加清晰和安全。该版本还增强了状态检查功能，新增了 MCP 客户端配置健康度检测和 HTML 格式输出支持。升级前请确认 MCP 客户端版本与服务器版本兼容。 ## 参见 - [Engram 快速开始指南](../getting-started.md) - [CLI 命令参考](../cli-reference.md) - [数据库架构详解](../database-schema.md) - [MCP 协议说明](../mcp-protocol.md) - [故障排除常见问题](../troubleshooting.md) --- --- ## Doramagic 踩坑日志 项目：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