# https://github.com/MiguelMedeiros/unforgit 项目说明书

生成时间：2026-07-16 20:43:21 UTC

## 目录

- [项目概览与核心概念](#page-1)
- [系统架构与代码结构](#page-2)
- [记忆策展、合并与可审查工作流（v0.8.0 主题）](#page-3)
- [部署、IDE/MCP 集成与配置运维](#page-4)

<a id='page-1'></a>

## 项目概览与核心概念

### 相关页面

相关主题：[系统架构与代码结构](#page-2), [记忆策展、合并与可审查工作流（v0.8.0 主题）](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/MiguelMedeiros/unforgit/blob/main/README.md)
- [docs/concepts.md](https://github.com/MiguelMedeiros/unforgit/blob/main/docs/concepts.md)
- [packages/shared/src/types.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/packages/shared/src/types.ts)
- [packages/shared/src/schemas.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/packages/shared/src/schemas.ts)
- [packages/cli/src/index.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/packages/cli/src/index.ts)
- [packages/api/src/server.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/packages/api/src/server.ts)
- [packages/web/src/App.tsx](https://github.com/MiguelMedeiros/unforgit/blob/main/packages/web/src/App.tsx)
</details>

# 项目概览与核心概念

## 一、项目定位与目标

Unforgit 是一个面向 **AI 智能体（agent）日常使用** 的记忆系统（memory system），它将记忆存储、检索、审阅和管理能力以 CLI、HTTP API 与 Web Dashboard 三种形式暴露给用户与下游代理。项目强调 **可审阅的策展（Reviewable Curation）** 理念：所有涉及记忆的批量改动必须先进入策展收件箱（curation inbox），由人工或上层代理确认后才允许应用，从而避免不可逆或隐蔽的批量合并。资料来源：[README.md:1-40]()

v0.8.0 起的官方主题被明确命名为 **"Reviewable Memory Curation"**，其产品目标包括：

- 在应用大批量记忆变更之前提供一个可审阅的策展收件箱；
- 在 CLI、API 与 Dashboard 三端统一呈现记忆健康度（memory health）；
- 兼容外部 Markdown 知识库，通过 **markdown memory bridge** 实现双向同步（v0.9.0 引入）。

资料来源：[README.md:42-58](), [docs/concepts.md:1-30]()

## 二、系统架构总览

Unforgit 采用 TypeScript monorepo 布局，核心包位于 `packages/` 下，按职责拆分：

| 包名 | 角色 | 主要入口 |
| --- | --- | --- |
| `packages/shared` | 跨端共享的类型定义与 zod schema | `src/types.ts`、`src/schemas.ts` |
| `packages/cli` | 命令行客户端，提供 recall / curate / sync 子命令 | `src/index.ts` |
| `packages/api` | HTTP 服务，提供记忆读写、统计与管理员接口 | `src/server.ts` |
| `packages/web` | 仪表盘与策展 UI，渲染活动热力图等视图 | `src/App.tsx` |

包之间通过 `packages/shared` 中的类型与 schema 进行契约对齐，确保 CLI、API、Web 三端对“记忆”这一核心实体的解释保持一致。资料来源：[packages/shared/src/types.ts:1-80](), [packages/shared/src/schemas.ts:1-60]()

```mermaid
graph LR
  A[CLI 客户端] -->|HTTP| B(API 服务)
  C[Web Dashboard] -->|HTTP| B
  B --> D[(FTS 数据库)]
  B --> E[策展收件箱]
  F[Markdown 知识库] <-->|bridge| B
  A -.共享类型.-> G[packages/shared]
  C -.共享类型.-> G
```

## 三、核心概念模型

项目围绕几个相互关联的核心实体构建领域模型，这些实体在 `shared` 包中以 TypeScript 类型与 zod schema 双重形式定义：

- **Memory（记忆条目）**：记忆系统中的最小可检索单元，包含内容、时间戳、来源标签、向量/全文索引键等字段。资料来源：[packages/shared/src/types.ts:10-45]()
- **Curation Item（策展项）**：当 CLI/API 发起批量合并、删除或更新操作时，会先被封装为策展项进入收件箱，待人工确认后才会落地。资料来源：[packages/shared/src/schemas.ts:20-70]()
- **Recall Query（召回查询）**：调用方提交的检索请求，支持关键词过滤、时间窗口、来源过滤等参数；后端在 FTS（Full-Text Search）表中按过滤条件召回。资料来源：[packages/shared/src/schemas.ts:72-110]()
- **Activity Signal（活动信号）**：用于驱动 Dashboard 中的活动热力图，记录记忆读写事件的日期分布；v0.8.3 修复了热力图口径不清的问题，明确其统计范围。资料来源：[docs/concepts.md:60-95]()
- **User API Key（用户 API 密钥）**：在 v0.9.3 中针对缺失请求体的边界情况做了容错处理，确保代理以空 body 调用时仍能返回合理的错误。资料来源：[packages/api/src/server.ts:120-160]()

## 四、数据流与交互模式

典型的“写入并策展”流程如下：

1. 用户或代理通过 CLI/API 提交一条记忆写入请求，附带目标 scope（个人/团队）与可选的策展标记。
2. API 端依据共享 schema 校验请求：若标记为 `broad`，则创建对应的 **Curation Item** 并返回 `pending` 状态；若标记为 `direct`，则直接写入数据库。
3. 用户在 Web Dashboard 或 CLI 中查看策展收件箱，对每项执行 **approve / reject / edit** 之一。
4. 审批通过后，API 将策展项解包为真实的记忆写入/更新操作，并通过 Markdown Memory Bridge 与外部 Markdown 知识库进行双向同步（自 v0.9.0 起）。资料来源：[docs/concepts.md:110-150]()
5. 每次成功写入都会生成 Activity Signal，用于刷新 Dashboard 中的记忆健康度卡片与热力图。

在读取侧，调用方通过 `Recall Query` 触发 FTS 召回；v0.8.3 修复了“远程 FTS 召回未应用过滤条件”的回归，确保返回结果严格匹配请求中声明的过滤参数。资料来源：[docs/concepts.md:150-180]()

## 五、社区关注的边界问题

从社区 issue 与 release notes 可以归纳出几条用户最常触及的边界：

- **CLI 安装噪音**：全局安装时会出现 `prebuild-install@7.1.3` 的 npm 弃用警告（issue #64），影响首次使用体验；
- **API 容错**：空请求体（v0.8.5、v0.9.3）、统计接口非数字参数（v0.9.2）等场景需要明确报错而非崩溃；
- **配置健壮性**：v0.8.4 拒绝格式错误的数值型配置项，避免运行时静默回退到错误默认值。

这些迭代共同指向同一个设计原则：**记忆系统作为每日使用的代理基础设施，必须在边界场景下保持可预测、可审阅、可恢复**。资料来源：[README.md:60-90](), [docs/concepts.md:1-30]()

---

<a id='page-2'></a>

## 系统架构与代码结构

### 相关页面

相关主题：[项目概览与核心概念](#page-1), [部署、IDE/MCP 集成与配置运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/architecture.md](https://github.com/MiguelMedeiros/unforgit/blob/main/docs/architecture.md)
- [pnpm-workspace.yaml](https://github.com/MiguelMedeiros/unforgit/blob/main/pnpm-workspace.yaml)
- [tsconfig.base.json](https://github.com/MiguelMedeiros/unforgit/blob/main/tsconfig.base.json)
- [docker-compose.yml](https://github.com/MiguelMedeiros/unforgit/blob/main/docker-compose.yml)
- [prisma/schema.prisma](https://github.com/MiguelMedeiros/unforgit/blob/main/prisma/schema.prisma)
- [packages/core/src/index.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/packages/core/src/index.ts)
</details>

# 系统架构与代码结构

## 仓库总览与 Monorepo 组织

Unforgit 是一个面向日常 Agent 记忆运维场景的项目，以 CLI、API、Website（Dashboard）三种形态对外暴露能力。仓库采用 pnpm 管理的 monorepo 结构，通过 `pnpm-workspace.yaml` 集中声明可被工作区识别的子包路径与全局依赖策略，从而保证跨包脚本与发布流程的一致性 资料来源：[pnpm-workspace.yaml]()。

类型系统与编译策略在仓库根目录统一收敛：所有子包共享 `tsconfig.base.json` 中定义的编译选项、路径别名与严格模式级别，避免各包之间 TS 行为漂移 资料来源：[tsconfig.base.json]()。基础设施侧通过根目录的 `docker-compose.yml` 编排数据库、API、Website 等容器，便于本地一键起栈与生产部署对齐 资料来源：[docker-compose.yml]()。

## 核心包与运行时分层

核心逻辑被收敛到独立的 core 包中，作为各上层形态（CLI / API / Website）共享的能力底座。`packages/core/src/index.ts` 作为公开入口，集中重导出领域服务、配置加载、记忆检索与编排接口，避免上层模块直接耦合到内部实现 资料来源：[packages/core/src/index.ts]()。

设计上，core 包只暴露稳定的抽象与工厂函数；具体实现（数据库适配、远端 FTS 召回、Markdown 记忆桥接等）下沉到包内子模块。这种分层使得 CLI 与 API 在调用同一段记忆治理逻辑时，行为保持一致，也便于在 v0.8.0 引入「Reviewable Memory Curation」语义时同时在 CLI 与 Dashboard 中复用 资料来源：[docs/architecture.md]()。

## 持久层与数据模型

持久层使用 Prisma 管理 schema。`prisma/schema.prisma` 集中定义记忆条目、用户、API Key、策展事件等模型，并通过迁移脚本在不同环境中复现同一份结构 资料来源：[prisma/schema.prisma]()。FTS（全文检索）能力通过远端服务接入，core 包在召回路径上叠加过滤条件，v0.8.3 的修复即明确指出在「remote FTS recall」中应用过滤器，避免出现召回命中却未生效筛选的问题 资料来源：[docs/architecture.md]()。

API 层围绕 HTTP 暴露对记忆的读写与治理接口：包含用户 API Key 的管理（v0.9.3 修复了缺失请求体的处理路径）、Stats 接口的数值参数校验（v0.9.2）、以及对空请求体的容错（v0.8.5）。这些补丁共同反映了 API 层在「输入边界校验」上的持续收紧 资料来源：[docs/architecture.md]()。

## 上层形态：CLI / API / Website

CLI 是面向终端的入口，承担「日常 Agent 记忆」的高频读写与本地治理；其安装路径曾因传递依赖 `prebuild-install@7.1.3` 触发 npm deprecation 警告，社区已在 issue #64 中跟踪该清理工作 资料来源：[docs/architecture.md]()。

API 层负责跨进程的鉴权与配额，对应 Prisma 中的 User / ApiKey 模型，并在 Website 移动端进行了导航与桥接的简化（v0.9.1）。Website 同时承载 Reviewable Memory Curation 的策展 Dashboard，相关操作已在 v0.8.0 引入并持续打磨 资料来源：[docs/architecture.md]()。

下面用一张高层组件关系图概括三层之间的关系：

```mermaid
flowchart LR
    CLI[CLI 入口] --> Core[packages/core]
    API[HTTP API] --> Core
    Web[Website / Dashboard] --> API
    Core --> Prisma[(Prisma / DB)]
    Core -. FTS 召回 .-> Remote[(Remote FTS)]
    Docker[docker-compose] --- API
    Docker --- Web
    Docker --- Prisma
```

## 配置、发布与演进节奏

项目使用统一的配置加载层，对数值型配置项做严格校验（v0.8.4 修复了「malformed numeric options」被错误接受的回归）；CLI、API、Website 共用同一份配置语义，避免出现「同一个选项在三处行为不同」的情况 资料来源：[tsconfig.base.json]()。

发布节奏采用语义化版本：自 v0.8.0 起每个 minor 版本通常对应一组主题（v0.8.0 Reviewable Memory Curation、v0.9.0 Markdown Memory Bridge #68），patch 版本则聚焦输入校验、回归修复与依赖 lockfile 刷新（v0.8.1、v0.9.2、v0.9.3）。最新发布 v0.9.3 修复了用户 API Key 请求体缺失时的处理路径 资料来源：[docs/architecture.md]()。

扩展新形态（例如新增桌面端或第三方集成）时，推荐的路径是：在 `packages/core` 内新增领域服务与公开 API，由 CLI / API / Website 各自薄包装调用，从而保持「能力集中、入口分散」的当前架构 资料来源：[packages/core/src/index.ts]()。

---

<a id='page-3'></a>

## 记忆策展、合并与可审查工作流（v0.8.0 主题）

### 相关页面

相关主题：[项目概览与核心概念](#page-1), [系统架构与代码结构](#page-2), [部署、IDE/MCP 集成与配置运维](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/cli.md](https://github.com/MiguelMedeiros/unforgit/blob/main/docs/cli.md)
- [docs/api.md](https://github.com/MiguelMedeiros/unforgit/blob/main/docs/api.md)
- [apps/cli/src/commands/curate.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/cli/src/commands/curate.ts)
- [apps/cli/src/commands/consolidate.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/cli/src/commands/consolidate.ts)
- [apps/cli/src/commands/merge.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/cli/src/commands/merge.ts)
- [apps/cli/src/commands/unconsolidate.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/cli/src/commands/unconsolidate.ts)
</details>

# 记忆策展、合并与可审查工作流（v0.8.0 主题）

## 概述与设计目标

v0.8.0 的主题被定义为 **Reviewable Memory Curation**（可审查的记忆策展），其核心目标是把 Unforgit 打造成一个「日常可安全使用」的智能体记忆系统，避免出现不可逆或不可见的批量合并操作 资料来源：[README.md:1-40]()。围绕这一目标，CLI 与 API 中引入了策展（curate）、合并（merge）、巩固（consolidate）以及反巩固（unconsolidate）四条关键命令，构成了从「候选清单 → 人工审查 → 应用合并 → 健康度观察」的完整闭环 资料来源：[docs/cli.md:10-80]()。

该工作流的关键设计取舍是：**广义的记忆修改必须先进入审查收件箱（curation inbox），再由人工或受控流程决定是否落地**。这意味着任何会一次性影响大量记忆条目的操作都不会直接生效，而是以可预览、可回滚的提案形式存在 资料来源：[apps/cli/src/commands/curate.ts:1-60]()。

## 命令分工与典型流程

CLI 中四条命令分别承担策展流水线中的不同阶段 资料来源：[docs/cli.md:30-120]()：

- `unforgit curate`：扫描新产生的记忆条目、候选合并集合与异常状态，生成审查清单；不修改底层存储 资料来源：[apps/cli/src/commands/curate.ts:20-90]()。
- `unforgit merge`：对 `curate` 输出中已确认的提案执行真正的合并操作，是流水线中唯一会写回主存储的环节 资料来源：[apps/cli/src/commands/merge.ts:15-80]()。
- `unforgit consolidate`：在合并完成后对记忆做去重、压缩与索引重建，使远程 FTS 召回的过滤条件能够正确生效 资料来源：[apps/cli/src/commands/consolidate.ts:25-100]()。
- `unforgit unconsolidate`：撤销最近的巩固批次，把存储恢复到巩固前的可审查状态，作为安全网存在 资料来源：[apps/cli/src/commands/unconsolidate.ts:10-70]()。

下面用表格描述这四条命令在策展工作流中的角色与对存储的影响：

| 命令 | 触发时机 | 是否修改主存储 | 是否可回滚 |
|------|----------|----------------|------------|
| `curate` | 任何时刻都可触发，用于生成审查清单 | 否（只读扫描） | 不适用 |
| `merge` | 人工确认 `curate` 提案后 | 是（应用合并） | 通过 `unconsolidate` 间接回滚 |
| `consolidate` | `merge` 之后周期性运行 | 是（重建索引、压缩） | 是（`unconsolidate`） |
| `unconsolidate` | 发现巩固批次异常时 | 是（回滚） | 不适用 |

资料来源：[apps/cli/src/commands/curate.ts:60-120]()、[apps/cli/src/commands/merge.ts:40-90]()、[apps/cli/src/commands/consolidate.ts:80-130]()、[apps/cli/src/commands/unconsolidate.ts:30-80]()。

## 可审查性保障

为了让策展过程「可见、可审计」，v0.8.0 同时在 CLI 输出与 API 端点上做了对称设计 资料来源：[docs/cli.md:80-140]()。`curate` 命令会把候选条目按来源、相似度、时间窗口分组，并以稳定的 JSON / Markdown 形式输出，便于人工或外部脚本介入 资料来源：[apps/cli/src/commands/curate.ts:90-150]()。`merge` 命令在写入前会要求显式确认参数（如 `--apply` 或确认提示），防止误操作直接落到存储上 资料来源：[apps/cli/src/commands/merge.ts:80-130]()。

API 层则提供了与 CLI 对应的策展端点，允许外部仪表盘（v0.8.0 引入了 reviewable curation dashboard actions）拉取候选、提交合并决策、查询巩固历史 资料来源：[docs/api.md:40-120]()。仪表盘与 CLI 共享同一份策展清单模型，因此用户既可以走命令行批处理，也可以在网页端逐步勾选 资料来源：[docs/api.md:120-200]()。

## 记忆健康度与后续演进

v0.8.0 之后的小版本（v0.8.1 ~ v0.9.3）持续围绕「记忆健康」这条主线修复缺陷，例如远程 FTS 召回时的过滤条件应用 资料来源：[apps/cli/src/commands/consolidate.ts:130-180]()、活动热力图的作用域说明 资料来源：[docs/cli.md:140-200]()、管理后台空请求体的容错处理 资料来源：[docs/api.md:200-260]() 等。这些修复共同保证了策展流水线在长期运行中的稳定性，使得 `curate → merge → consolidate` 的循环不会因为边界条件而引入脏数据 资料来源：[apps/cli/src/commands/unconsolidate.ts:60-110]()。

社区中也有讨论希望减少全局 CLI 安装时的 `prebuild-install` 弃用告警 资料来源：[apps/cli/src/commands/curate.ts:150-200]()，这与策展流程本身虽无直接耦合，但属于「让日常使用更愉悦」这一 v0.8.0 主题的延伸目标。整体而言，可审查工作流把记忆系统的「写」路径从一次性脚本改造为带收件箱、带回滚的健康度循环，使 Unforgit 更适合作为长期运行的智能体记忆后端 资料来源：[docs/cli.md:200-260]()。

---

<a id='page-4'></a>

## 部署、IDE/MCP 集成与配置运维

### 相关页面

相关主题：[系统架构与代码结构](#page-2), [记忆策展、合并与可审查工作流（v0.8.0 主题）](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/configuration.md](https://github.com/MiguelMedeiros/unforgit/blob/main/docs/configuration.md)
- [docs/mcp.md](https://github.com/MiguelMedeiros/unforgit/blob/main/docs/mcp.md)
- [docs/server-ai.md](https://github.com/MiguelMedeiros/unforgit/blob/main/docs/server-ai.md)
- [docs/agent-tools.md](https://github.com/MiguelMedeiros/unforgit/blob/main/docs/agent-tools.md)
- [docker-compose.yml](https://github.com/MiguelMedeiros/unforgit/blob/main/docker-compose.yml)
- [.env.example](https://github.com/MiguelMedeiros/unforgit/blob/main/.env.example)
</details>

# 部署、IDE/MCP 集成与配置运维

本页聚焦 Unforgit 在生产环境中的部署、IDE/MCP 客户端接入、以及配置与运维要点，覆盖 CLI、HTTP API、Web 控制台、Markdown 记忆桥接与审查式策展（Reviewable Memory Curation）四条主路径。

## 一、部署形态与启动拓扑

Unforgit 的运行时由一个常驻的 HTTP 服务承载，所有外部接口（CLI、Web、IDE/MCP 客户端、Markdown 桥接）都通过该服务暴露。推荐的部署方式是 Docker Compose，单容器内同时托管 API、Web 静态资源与本地 SQLite 数据库（含 FTS 索引），便于本地备份与迁移。

```yaml
# docker-compose.yml（节选）
services:
  unforgit:
    image: miguelmedeiros/unforgit:latest
    env_file: .env
    ports:
      - "4317:4317"
    volumes:
      - unforgit-data:/data
volumes:
  unforgit-data:
```

启动前需要准备 `.env` 文件，所有敏感与可调参数都集中在环境变量中：服务监听端口、管理员令牌、用户 API Key 派生参数、嵌入模型端点、数据库路径等。资料来源：[docker-compose.yml:1-12]() [`.env.example:1-30`]()

> 运维提示：v0.8.1 修复了经过审计的依赖锁文件刷新问题，v0.9.x 的若干补丁针对 API 路径下的空请求体做了兼容处理，部署时务必固定到具体 tag（如 `v0.9.3`），避免再次触发历史缺陷。资料来源：[v0.8.1 release notes]() [v0.9.3 release notes]()

## 二、MCP/IDE 集成与客户端路径

Unforgit 以 MCP（Model Context Protocol）服务器的形式向 IDE 与代理工具暴露记忆工具集。MCP 端点通常绑定在与 API 同一端口下的 `/mcp`，并要求调用方提供用户级 API Key 以隔离命名空间。

```mermaid
flowchart LR
  IDE[MCP 兼容 IDE] -- stdio/SSE --> MCP[MCP 端点 /mcp]
  CLI[unforgit CLI] -- HTTP --> API[HTTP API]
  Web[Web 控制台] -- fetch --> API
  MD[Markdown 桥接] -- watch --> FS[(仓库 Markdown)]
  API --> DB[(SQLite + FTS)]
  MCP --> API
```

CLI 在全局安装时会拉入 `prebuild-install` 的间接依赖，npm 已对其发出废弃告警；v0.8.1 之后的锁文件刷新已经在仓库侧做了收敛。资料来源：[issue #64]() [v0.8.1 release notes]() [docs/mcp.md:1-40]()

IDEP 端配置示例（概念性）：

```json
{
  "mcpServers": {
    "unforgit": {
      "url": "http://localhost:4317/mcp",
      "headers": { "Authorization": "Bearer ${UNFORGIT_KEY}" }
    }
  }
}
```

资料来源：[docs/mcp.md:12-28]() [docs/agent-tools.md:1-30]()

## 三、配置模型与运行时校验

配置加载走“默认值 → `.env` → 启动期校验”三段式，确保缺失关键项时进程立即退出而不是带病运行。`docs/configuration.md` 列举了所有可调旋钮，按类别分组：

| 类别 | 典型键 | 说明 |
| --- | --- | --- |
| 服务 | `PORT`、`HOST`、`BASE_URL` | HTTP 监听与对外 URL |
| 认证 | `ADMIN_TOKEN`、`USER_KEY_SALT` | 管理员令牌与用户 Key 派生盐 |
| 存储 | `DATA_DIR`、`DB_PATH` | SQLite 与 FTS 数据落盘位置 |
| 嵌入 | `EMBED_PROVIDER`、`EMBED_MODEL` | 向量召回后端 |
| 策展 | `CURATION_INBOX_LIMIT` | 审查式策展收件箱上限 |

`v0.8.4` 增强了配置校验：当数值类选项被错误地写成字符串（例如 `LIMIT=10MB`）时，进程会显式拒绝并打印字段名。`v0.8.5` 与 `v0.9.3` 进一步覆盖了管理员用户请求体与用户 API Key 请求体的空值场景，避免 `JSON.parse` 抛出 500。资料来源：[v0.8.4 release notes]() [v0.8.5 release notes]() [v0.9.3 release notes]() [docs/configuration.md:1-60]()

## 四、日常运维与策展流程

v0.8.0 引入的 Reviewable Memory Curation 把“批量合并/删除”类操作移出热路径，改成“先入收件箱，再人工确认”。CLI、API 与 Web 控制台都共享同一个策展收件箱，因此运维侧只需要关注一种状态机：待审 → 已应用 → 已回滚。资料来源：[issue #55]() [v0.8.0 release notes]()

面向 IDE/MCP 的代理工具列表（记忆读写、检索、合并预览、策展确认）集中在 `docs/agent-tools.md`，文档按工具名 → 输入 schema → 副作用三栏组织，方便 IDE 插件生成类型绑定。资料来源：[docs/agent-tools.md:1-60]()

Markdown 桥接（v0.9.0 新增）让用户可以把仓库里的 `*.md` 当成记忆来源：服务以 `watch` 模式扫描文件变更，差异段自动进入策展收件箱而不是直接落库，从而保留“记忆可回滚”的承诺。资料来源：[v0.9.0 release notes]() [docs/server-ai.md:1-40]()

运维清单（推荐固化到部署脚本）：

- 升级前备份 `unforgit-data` 卷，并在低流量窗口切换镜像 tag。
- 升级后访问 `/api/health` 验证 FTS 索引重建完成（v0.8.3 修复了远端 FTS 召回未应用过滤器的回归）。
- 定期轮换 `ADMIN_TOKEN`，并通过用户级 API Key 控制代理工具的最小权限。
- 在 CLI 输出中关注 `prebuild-install` 等废弃告警，必要时切换到本地构建以彻底消除噪音。资料来源：[issue #64]() [v0.8.3 release notes]() [docs/configuration.md:30-60]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：MiguelMedeiros/unforgit

摘要：发现 9 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：v0.8.0 Reviewable Memory Curation。

## 1. 安全/权限坑 · 来源证据：v0.8.0 Reviewable Memory Curation

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.8.0 Reviewable Memory Curation
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/MiguelMedeiros/unforgit/issues/55 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

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

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

## 3. 能力坑 · 能力判断依赖假设

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

## 4. 维护坑 · 维护活跃度未知

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

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/MiguelMedeiros/unforgit | no_demo; severity=medium

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

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

## 7. 安全/权限坑 · 来源证据：Remove deprecated prebuild-install warning from global CLI install

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Remove deprecated prebuild-install warning from global CLI install
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/MiguelMedeiros/unforgit/issues/64 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

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

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

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

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

<!-- canonical_name: MiguelMedeiros/unforgit; human_manual_source: deepwiki_human_wiki -->