一、项目定位与目标

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 中的类型与 schema 进行契约对齐，确保 CLI、API、Web 三端对“记忆”这一核心实体的解释保持一致。资料来源：packages/shared/src/types.ts:1-80, packages/shared/src/schemas.ts:1-60

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 安装噪音：全局安装时会出现 [email protected] 的 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

仓库总览与 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 记忆」的高频读写与本地治理；其安装路径曾因传递依赖 [email protected] 触发 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。

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

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。

概述与设计目标

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。

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

资料来源：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。

一、部署形态与启动拓扑

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

# 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 以隔离命名空间。

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 端配置示例（概念性）：

{
  "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 列举了所有可调旋钮，按类别分组：

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

Pitfall Log / 踩坑日志

项目：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