# https://github.com/salishforge/memforge 项目说明书
生成时间：2026-07-28 03:50:56 UTC
## 目录
- [MemForge 概述与系统架构](#page-1)
- [核心记忆系统与数据流](#page-2)
- [SDK、平台集成与部署方式](#page-3)
- [运维、安全与社区关注问题](#page-4)
## MemForge 概述与系统架构
### 相关页面
相关主题：[核心记忆系统与数据流](#page-2), [SDK、平台集成与部署方式](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/salishforge/memforge/blob/main/README.md)
- [ARCHITECTURE.md](https://github.com/salishforge/memforge/blob/main/ARCHITECTURE.md)
- [SPECIFICATION.md](https://github.com/salishforge/memforge/blob/main/SPECIFICATION.md)
- [src/server.ts](https://github.com/salishforge/memforge/blob/main/src/server.ts)
- [src/sleep-cycle.ts](https://github.com/salishforge/memforge/blob/main/src/sleep-cycle.ts)
- [src/consolidation.ts](https://github.com/salishforge/memforge/blob/main/src/consolidation.ts)
- [python/memforge/client.py](https://github.com/salishforge/memforge/blob/main/python/memforge/client.py)
- [python/memforge/types.py](https://github.com/salishforge/memforge/blob/main/python/memforge/types.py)
# MemForge 概述与系统架构
MemForge 是由 Salish Forge 维护、面向 AI Agent 的多租户记忆合并（memory consolidation）服务。其设计灵感来自神经科学中的"睡眠记忆巩固"机制：当 Agent 空闲或显式触发时，系统会主动对已存储的知识进行重写、强化与降级，从而在持久化、可语义检索的记忆层之上模拟睡眠周期 资料来源：[README.md:1-30]()。
## 核心定位与设计目标
MemForge 通过分层存储（hot / warm / cold）解决 AI Agent 在长会话中常见的上下文窗口有限、检索精度衰减与跨会话知识复用困难等问题。它对外暴露 REST API，并同时提供 Node.js 与 Python 双语言 SDK，使 Agent 可以以低耦合方式接入持久化记忆 资料来源：[SPECIFICATION.md:1-50]()。
设计目标可归纳为三点：
- **多租户隔离**：通过 PostgreSQL 行级安全（RLS）策略，按 `agent_id` 进行数据隔离，确保不同 Agent 之间互不可见 资料来源：[README.md:40-60]()。
- **混合检索**：结合 PostgreSQL 全文检索（keyword FTS）、pgvector 语义向量检索以及倒数排序融合（RRF），在 Recall@k 上取得稳定表现 资料来源：[ARCHITECTURE.md:60-90]()。
- **自动分层与巩固**：通过 sleep-cycle 在 hot/warm/cold 层之间批量迁移并压缩记忆，模拟人脑在睡眠中对记忆的整理过程 资料来源：[src/sleep-cycle.ts:1-40]()。
## 系统架构与数据流
MemForge 运行时由 HTTP 接口层、合并调度层与多层级存储后端组成。下图展示了请求在系统内的主要流向：
```mermaid
flowchart LR
Client[Agent / SDK] -->|REST /memory/:agentId/*| API[Express Router
src/server.ts]
API --> Query[Query Engine]
API --> Add[Add Path]
Query --> Hybrid[Hybrid Search
FTS + Vector + RRF]
Hybrid --> PG[(PostgreSQL + pgvector)]
Add --> Hot[Hot Tier]
Hot -->|sleep-cycle| Warm[Warm Tier]
Warm -->|age out| Cold[Cold Tier]
Cycle[sleep-cycle.ts] --> PG
Cycle --> Redis[(Redis Cache)]
```
HTTP 入口位于 `src/server.ts`，将请求分发至查询引擎或写入路径。写入路径将新记忆落入 hot 层；当 sleep-cycle 触发时，hot 层中最多 50 条记录会被批量合并为 warm 层中的一条，这一合并粒度也是 LongMemEval 基准上出现平坦 Recall@k 曲线（R@1 = R@3 = R@5 = R@10）的根因 资料来源：[src/sleep-cycle.ts:60-120]() 资料来源：[issues/47]()。合并后的 warm 条目经冷淘汰进入 cold 层，并可通过 cold-tier recovery 重新激活 资料来源：[src/consolidation.ts:30-80]()。
## 多租户、命名空间与记忆预算
v3.0.0-beta.4 引入了**记忆命名空间（namespace）**，允许在同一 `agent_id` 内进一步按域（domain）分区，例如区分用户偏好、工具调用日志与对话上下文。`add`、`query`、`consolidate`、`timeline`、`stats`、`resume`、`export` 等接口均接受可选的 `namespace` 参数 资料来源：[releases/v3.0.0-beta.4]()。
与此同时，系统引入**硬性记忆预算（hard memory budgets）** 与**自适应调度提示（adaptive scheduling hints）**：当某命名空间接近上限时，sleep-cycle 优先回收评分最低的 cold 条目；调度提示则会告知调用方何时适合主动调用 `consolidate` 资料来源：[releases/v3.0.0-beta.4]()。RLS 策略与审计删除触发器确保即便共享底层数据库实例，租户之间也无法互相窥探 资料来源：[releases/v3.0.0-beta.3]()。
## SDK、API 表面与已知问题
Node.js 与 Python SDK 在结构上保持一致：`client` 类封装 HTTP 调用，`types` 定义返回数据结构。需注意，Python SDK 的 `QueryResult` 数据类目前采用固定字段构造，服务端新增字段（如 `context_signals`）会在 v3.8+ 上抛出 `TypeError`，升级前后应查阅兼容性说明 资料来源：[python/memforge/types.py:1-60]() 资料来源：[issues/161]()。
REST 路由方面，`GET /memory/:agentId/entities` 与 `GET /memory/:agentId/graph` 在传入非法 `agentId` 时，`getAgentId()` 抛出的 `TypeError` 会被通用 500 分支吞没，客户端仅看到"服务器错误"而非参数校验提示；`/query` 的 OpenAPI 描述中也缺少 `epistemic` 参数。这些问题已在 #162 中记录，建议调用方在客户端先做格式校验以获得更准确的错误信息 资料来源：[issues/162]()。Node.js 端的 REST 处理同样位于 `src/server.ts` 中，处理顺序决定了哪些错误会进入 500 分支 资料来源：[src/server.ts:120-180]()。
---
## 核心记忆系统与数据流
### 相关页面
相关主题：[MemForge 概述与系统架构](#page-1), [SDK、平台集成与部署方式](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [src/memory-manager.ts](https://github.com/salishforge/memforge/blob/main/src/memory-manager.ts)
- [src/db.ts](https://github.com/salishforge/memforge/blob/main/src/db.ts)
- [src/schemas.ts](https://github.com/salishforge/memforge/blob/main/src/schemas.ts)
- [src/embedding.ts](https://github.com/salishforge/memforge/blob/main/src/embedding.ts)
- [src/classifier.ts](https://github.com/salishforge/memforge/blob/main/src/classifier.ts)
- [src/consolidation.ts](https://github.com/salishforge/memforge/blob/main/src/consolidation.ts)
- [schema/schema.sql](https://github.com/salishforge/memforge/blob/main/schema/schema.sql)
- [src/routes/memory.ts](https://github.com/salishforge/memforge/blob/main/src/routes/memory.ts)
# 核心记忆系统与数据流
MemForge 的核心记忆系统是一套面向 AI Agent 的多租户记忆持久化与检索基础设施，承担"接收写入、跨层编排、按需检索、周期性整合"四大职责。其设计灵感源自神经科学中的"睡眠周期"，通过 PostgreSQL（搭配 pgvector）、Redis 与 Node.js 运行时形成 tiered memory 架构（hot → warm → cold） 资料来源：[schema/schema.sql:1-120]()。
## 1. 目的与适用范围
该系统的核心目标是为长时间运行的 Agent 提供可扩展、可语义搜索、并能够自我整合的记忆存储能力。它通过 agent_id 级别的行级安全（RLS）策略实现多租户隔离 资料来源：[schema/schema.sql:200-310]()，并对外暴露统一的 REST 接口（`/memory/:agentId/...`），供 SDK（含 Python / TypeScript 客户端）以及上游 Agent 调用 资料来源：[src/routes/memory.ts:1-80]()。自 v3.0.0-beta.4 起，系统引入 memory namespaces 与 domain partitioning，允许同一 agent 在不同命名空间或领域中独立管理记忆 资料来源：[CHANGELOG.md:1-40]()。
## 2. 分层存储架构（Hot / Warm / Cold）
记忆按访问频率与生命周期分入三个物理层级：
| 层级 | 存储后端 | 典型用途 | 主要约束 |
|------|----------|----------|----------|
| Hot | Redis | 最近写入与高频查询的短期记录 | 容量最小，TTL 短 |
| Warm | PostgreSQL + pgvector | 周期性整合后的语义化记忆 | 批量化（每批最多 50 条 hot → 1 条 warm） |
| Cold | 对象/归档存储 | 历史与低频召回数据 | 冷层恢复（cold-tier recovery）流程接管 |
资料来源：[src/db.ts:1-90](), [src/consolidation.ts:30-120](), [schema/schema.sql:1-120]()。
Hot 层提供亚毫秒级缓存命中；Warm 层在 PostgreSQL 中以 pgvector 形式持久存储向量并配以全文检索索引；Cold 层由冷层恢复流程定期重建可被重新激活的批次 资料来源：[src/consolidation.ts:140-260]()。
## 3. 写入、检索与整合数据流
```mermaid
flowchart LR
Client["SDK / REST 客户端"] -->|POST /memory/:id/add| Router["memory 路由\nsrc/routes/memory.ts"]
Router --> Validate["schemas 校验\nsrc/schemas.ts"]
Validate --> Embed["向量化\nsrc/embedding.ts"]
Embed --> Hot["写入 Redis 热层\nsrc/db.ts"]
Embed --> Warm["异步写入 PG + pgvector\nsrc/db.ts"]
Warm --> Classify["分类与置信度\nsrc/classifier.ts"]
Warm -->|周期触发| Consol["consolidation\nsrc/consolidation.ts"]
Consol --> Warm
Client -->|GET /memory/:id/query| Search["混合检索\nBM25 + 向量 + RRF"]
Search --> Warm
Search --> Client
```
写入路径首先在 `schemas.ts` 中通过 Zod 完成严格校验，避免非法字段进入下游 资料来源：[src/schemas.ts:1-60]()。校验后由 `embedding.ts` 生成向量嵌入，并经由 `db.ts` 同时落到 Redis 与 PostgreSQL 双写通道 资料来源：[src/db.ts:90-210]()。`classifier.ts` 为每条记忆打上分类标签与认知状态（epistemic）以支持后续的置信度评估 资料来源：[src/classifier.ts:1-90]()。
检索路径执行 hybrid search：先将 query 关键词经 BM25/全文索引召回，再以向量余弦相似度召回，最后通过 reciprocal rank fusion（RRF）融合排名，从而兼顾字面与语义匹配 资料来源：[src/db.ts:210-340]()。
`consolidation.ts` 周期性以"批处理（≤50 条 hot 折叠为 1 条 warm）"的方式把冗余热层记忆压缩为更高质量的语义记忆；LongMemEval 基准中曾观察到"R@1 = R@3 = R@5 = R@10"的现象，根源之一正是该分批粒度导致评分粒度不足 资料来源：[issue #47]()。
## 4. 已知边界与社区关注点
社区多次反馈 REST 接口的健壮性问题：`GET /memory/:agentId/entities` 与 `/graph` 端点对非法 agentId 抛出的 `TypeError` 会被外层捕获为 500，而非受控的 400；同时 OpenAPI 中 query 路径缺少 epistemic 参数声明 资料来源：[issue #162]()。Python SDK 中的 `QueryResult` 数据类使用固定字段构造，服务器响应自 v3.8 起新增的字段（如 `context_signals`）会使 SDK 抛错 资料来源：[issue #161]()。这些都属于核心数据流上下游契约需要持续维护的范围，建议在引入新字段时同步更新 `schemas.ts`、Python `types.py` 与 OpenAPI 文档。
---
## SDK、平台集成与部署方式
### 相关页面
相关主题：[MemForge 概述与系统架构](#page-1), [运维、安全与社区关注问题](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [src/client.ts](https://github.com/salishforge/memforge/blob/main/src/client.ts)
- [src/mcp.ts](https://github.com/salishforge/memforge/blob/main/src/mcp.ts)
- [src/tool-definitions.ts](https://github.com/salishforge/memforge/blob/main/src/tool-definitions.ts)
- [python/memforge/client.py](https://github.com/salishforge/memforge/blob/main/python/memforge/client.py)
- [python/memforge/resilient.py](https://github.com/salishforge/memforge/blob/main/python/memforge/resilient.py)
- [python/memforge/conversation.py](https://github.com/salishforge/memforge/blob/main/python/memforge/conversation.py)
# SDK、平台集成与部署方式
MemForge 是一个面向 AI 智能体的多租户记忆整合服务，提供分层记忆（hot/warm/cold）、混合检索与自动整合能力。围绕核心服务，仓库同时提供 **TypeScript SDK**、**Python SDK**、**MCP 协议服务器** 以及 **OpenAPI/HTTP REST 接口**，并通过 npm 与容器镜像对外分发。本页面向希望把 MemForge 集成进现有智能体框架或自行托管的开发者，梳理 SDK 形态、协议集成点以及部署/发布方式。
## 客户端 SDK
### TypeScript / Node.js SDK
`src/client.ts` 是 Node 侧的主入口，封装 REST 调用并暴露面向业务的方法（如 `add`、`query`、`consolidate`、`timeline`、`stats`、`export` 等），便于在 Node 智能体运行时直接复用。`资料来源：[src/client.ts:1-80]()`
在 v3.0.0-beta.4 之后，所有读写操作都接受可选的 `namespace` 参数以支持命名空间隔离，使得同一进程内多个业务域可共享同一个 MemForge 实例而互不污染。`资料来源：[src/client.ts:120-180]()`
CLI 工具复用同一客户端实现，使得 `memforge add`、`memforge query` 等命令既可独立调试，也可被脚本串联使用。
### Python SDK
`python/memforge/client.py` 提供同步/异步客户端，`python/memforge/conversation.py` 将多次 `add`/`query` 组合成面向对话的高级 API，`python/memforge/resilient.py` 在此之上叠加重试、熔断与退避策略，便于在长时运行的智能体进程中提高可用性。`资料来源：[python/memforge/client.py:1-60]()`
社区已记录 Python SDK 的一个前置隐患：`types.py` 中的 `QueryResult` 是固定字段的 dataclass，而 `client.py` 通过 `QueryResult(**r)` 直接展开服务端响应；服务端自 v3.8 起新增了 `context_signals` 等字段，导致旧版本 SDK 在反序列化时抛错。`资料来源：[python/memforge/types.py:30-90]()`、`资料来源：[python/memforge/client.py:200-240]()` 升级到对应版本或采用 `resilient.py` 中的兼容层可绕过此问题。
## MCP 协议集成
`src/mcp.ts` 将 MemForge 暴露为 **Model Context Protocol (MCP)** 服务器，使支持 MCP 的客户端（如 Claude Desktop、IDE 插件等）能直接把记忆工具暴露给 LLM。`资料来源：[src/mcp.ts:1-50]()`
工具的元信息集中在 `src/tool-definitions.ts`，统一维护名称、输入 schema 与描述，便于：
- 在不同 MCP 传输（stdio / SSE）之间复用同一份契约；
- 与 OpenAPI 文档保持一致（已知 OpenAPI 在 `query` 路径上漏掉了 `epistemic` 参数，对照 `tool-definitions.ts` 可补齐）。`资料来源：[src/tool-definitions.ts:40-120]()`
```mermaid
flowchart LR
Agent[LLM Agent / MCP Client] -->|stdio or SSE| MCP[src/mcp.ts]
MCP --> TD[src/tool-definitions.ts]
MCP --> REST[REST API Server]
REST --> PG[(PostgreSQL + pgvector)]
REST --> RD[(Redis)]
```
## 部署与发布方式
### 运行时依赖
完整功能依赖三类外部服务：
| 组件 | 用途 |
|------|------|
| PostgreSQL + pgvector | 持久化分层记忆与向量召回 |
| Redis | 缓存、短期热数据与速率控制 |
| OpenAI 兼容 Embeddings | 语义向量化（可自托管替换） |
社区常见的本地起栈方式是通过 `docker compose` 拉起上述依赖，再启动 API 服务。
### npm Trusted Publishing (OIDC)
v3.0.0-beta.4 起，TypeScript 包改为通过 **npm Trusted Publishing (OIDC)** 发布，不再使用长期 token。CI 配置需在 GitHub Actions 中声明 `id-token: write` 权限并关联 npm 的可信发布者，从而避免 token 泄露风险。`资料来源：[.github/workflows/publish.yml:1-40]()`
### OpenAPI / REST 契约
REST 端点遵循 `/memory/:agentId/...` 的命名空间前缀。社区已识别出两处需要特别注意：
- `GET /memory/:agentId/entities` 与 `GET /memory/:agentId/graph` 在校验失败时会被通用 500 分支捕获，返回不友好的错误码；建议在调用前校验 `agentId`。`资料来源：[src/server/routes/entities.ts:1-60]()`
- OpenAPI 文档中 `query` 路径缺少 `epistemic` 参数，需对照实际路由补齐。`资料来源：[openapi.yaml:1-120]()`
综合来看，MemForge 通过 **多语言 SDK + MCP 协议 + REST/OpenAPI** 三层接入面，以及 **容器化依赖 + OIDC 发布** 的现代交付链路，既适合嵌入既有智能体框架，也便于作为独立服务托管。
---
## 运维、安全与社区关注问题
### 相关页面
相关主题：[核心记忆系统与数据流](#page-2), [SDK、平台集成与部署方式](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [src/routes/entities.ts](https://github.com/salishforge/memforge/blob/main/src/routes/entities.ts)
- [src/routes/graph.ts](https://github.com/salishforge/memforge/blob/main/src/routes/graph.ts)
- [src/routes/query.ts](https://github.com/salishforge/memforge/blob/main/src/routes/query.ts)
- [src/openapi/schema.ts](https://github.com/salishforge/memforge/blob/main/src/openapi/schema.ts)
- [python/memforge/types.py](https://github.com/salishforge/memforge/blob/main/python/memforge/types.py)
- [python/memforge/client.py](https://github.com/salishforge/memforge/blob/main/python/memforge/client.py)
- [sql/migrations/0007_rls_policies.sql](https://github.com/salishforge/memforge/blob/main/sql/migrations/0007_rls_policies.sql)
- [sql/migrations/0008_audit_delete_trigger.sql](https://github.com/salishforge/memforge/blob/main/sql/migrations/0008_audit_delete_trigger.sql)
- [.github/workflows/ci.yml](https://github.com/salishforge/memforge/blob/main/.github/workflows/ci.yml)
- [package.json](https://github.com/salishforge/memforge/blob/main/package.json)
- [.npmrc](https://github.com/salishforge/memforge/blob/main/.npmrc)
# 运维、安全与社区关注问题
本页汇总 MemForge 在运维、安全与社区反馈三个维度上值得关注的设计点与已知问题。这些议题直接影响部署可靠性、租户数据隔离以及上下游 SDK 与 CI 工具链的协同。
## 1. 多租户隔离与行级安全（RLS）
MemForge 自 v0.1.0-alpha 起即按 `agent_id` 进行多租户隔离，并在 v3.0.0-beta.3 中将 RLS 策略与审计删除触发器收口到规范化迁移中 资料来源：[sql/migrations/0007_rls_policies.sql:1-120]() 资料来源：[sql/migrations/0008_audit_delete_trigger.sql:1-60]()。
- 每次写入会强制携带 `agent_id`，数据库侧通过策略校验，禁止跨代理读取 资料来源：[sql/migrations/0007_rls_policies.sql:10-45]()。
- 删除操作触发审计写入，旧行被写入审计表，供事后追溯 资料来源：[sql/migrations/0008_audit_delete_trigger.sql:5-35]()。
- v3.0.0-beta.4 引入的 `namespace` 参数（#16）扩展了隔离维度，允许在同一 `agent_id` 下按命名空间分区 资料来源：[CHANGELOG.md:30-60]()。
## 2. REST 错误处理与 OpenAPI 同步
社区在 #162 中发现，`GET /memory/:agentId/entities` 与 `GET /memory/:agentId/graph` 在收到无效 `agentId` 时会抛出 `TypeError`，由于 `getAgentId()` 校验位于主 `try` 内部，异常被通用 500 分支吞掉，掩盖了真正的校验失败 资料来源：[src/routes/entities.ts:20-55]() 资料来源：[src/routes/graph.ts:18-50]()。
| 问题 | 现象 | 建议修复 |
|---|---|---|
| 错误码被遮蔽 | 无效 `agentId` 返回 500 而非 4xx | 将 `getAgentId()` 调用移至 `try` 之前或拆出独立 catch |
| OpenAPI 文档缺失 | `/query` 端点未声明 `epistemic` 查询参数 | 在 OpenAPI schema 中补充该参数定义 |
此外，`/query` 的 OpenAPI 定义缺失 `epistemic` 查询参数，与服务端实际行为不一致，需同步到 资料来源：[src/openapi/schema.ts:80-120]() 资料来源：[src/routes/query.ts:15-40]()。
## 3. SDK 兼容性：Python `QueryResult` 字段演进
Python SDK 的 `QueryResult` 在 `types.py` 中以 dataclass 声明固定字段集，并在 `client.py` 中通过 `QueryResult(**r)` 直接展开服务端响应 资料来源：[python/memforge/types.py:1-40]() 资料来源：[python/memforge/client.py:120-160]()。自 v3.8 起，服务器响应新增了 `context_signals` 等字段，旧版 dataclass 会在反序列化阶段抛 `TypeError`，导致 SDK 调用方静默失败——这正是 #161 报告的问题。
该问题揭示了 SDK 与服务端"开放 vs 封闭"响应契约的权衡：服务端持续演进字段（这是必要的，例如新增上下文信号），而 SDK 仍按封闭 dataclass 反序列化。短期可在 `__init__` 中忽略多余键，长期可切换到 `pydantic.BaseModel` 或显式 `extra="ignore"`。
## 4. CI/CD 与发布供应链
v3.0.0-beta.2 完成了 CI 全绿，6 个作业（typecheck-lint、integration-tests、cache-tests × Node 20 + 22）均通过，并修复了 Redis/DB 连接未关闭导致的测试挂起、10+ 处 SQL 参数化错误以及异步触发器中的竞态条件 资料来源：[.github/workflows/ci.yml:1-80]()。
v3.0.0-beta.4 是首次采用 npm Trusted Publishing（OIDC）发布的版本，弃用了长期 token 资料来源：[package.json:40-70]() 资料来源：[.npmrc:1-10]()。这降低了 npm 凭据泄露风险，但要求发布环境具备 OIDC 颁发者配置，运维需在 CI 中预先设置 `id-token: write` 权限。
## 5. 已知质量与评分粒度问题
社区在 #47 中指出 LongMemEval 上 R@1=R@3=R@5=R@10 全部为 88.0%，曲线平直，原因是合并批次将至多 50 条热层行打包为单条温层行，导致每题仅命中同一聚合行、缺乏排序粒度 资料来源：[src/consolidation/merger.ts:30-90]()。此问题虽非"安全/运维"严格范畴，但属于社区高度关注的召回质量议题，建议作为 wiki 交叉链接。
## 总结
MemForge 在安全（RLS + 审计触发器）、错误码语义（#162 修复方向）以及发布供应链（OIDC）三方面已建立清晰基线。下一步社区关注重点包括：Python SDK 字段兼容（#161）、OpenAPI 同步（`epistemic` 参数）以及评分粒度（#47）。建议运维在升级到 v3.0.0-beta.4 后审计 OIDC 信任链，并将 REST 4xx 错误语义作为优先修复项。
---
---
## Doramagic 踩坑日志
项目：salishforge/memforge
摘要：发现 15 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: v3.0.0-beta.3。
## 1. 安装坑 · 失败模式：installation: v3.0.0-beta.3
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v3.0.0-beta.3
- 对用户的影响：Upgrade or migration may change expected behavior: v3.0.0-beta.3
- 证据：failure_mode_cluster:github_release | https://github.com/salishforge/memforge/releases/tag/v3.0.0-beta.3 | v3.0.0-beta.3
## 2. 安装坑 · 失败模式：installation: v3.0.0-beta.4
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v3.0.0-beta.4
- 对用户的影响：Upgrade or migration may change expected behavior: v3.0.0-beta.4
- 证据：failure_mode_cluster:github_release | https://github.com/salishforge/memforge/releases/tag/v3.0.0-beta.4 | v3.0.0-beta.4
## 3. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/salishforge/memforge | host_targets=mcp_host, claude
## 4. 配置坑 · 失败模式：configuration: MemForge v0.1.0-alpha
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: MemForge v0.1.0-alpha
- 对用户的影响：Upgrade or migration may change expected behavior: MemForge v0.1.0-alpha
- 证据：failure_mode_cluster:github_release | https://github.com/salishforge/memforge/releases/tag/v0.1.0-alpha | MemForge v0.1.0-alpha
## 5. 配置坑 · 失败模式：configuration: v3.0.0-beta.2 — CI Green, Shared Memory, Full Test Coverage
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v3.0.0-beta.2 — CI Green, Shared Memory, Full Test Coverage
- 对用户的影响：Upgrade or migration may change expected behavior: v3.0.0-beta.2 — CI Green, Shared Memory, Full Test Coverage
- 证据：failure_mode_cluster:github_release | https://github.com/salishforge/memforge/releases/tag/v3.0.0-beta.2 | v3.0.0-beta.2 — CI Green, Shared Memory, Full Test Coverage
## 6. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/salishforge/memforge | README/documentation is current enough for a first validation pass.
## 7. 运行坑 · 来源证据：Python SDK: QueryResult dataclass rejects unknown response keys (breaks on v3.8+ fields)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Python SDK: QueryResult dataclass rejects unknown response keys (breaks on v3.8+ fields)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/salishforge/memforge/issues/161 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 8. 运行坑 · 来源证据：REST: /entities and /graph return 500 for invalid agent ids; OpenAPI query path missing epistemic param
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：REST: /entities and /graph return 500 for invalid agent ids; OpenAPI query path missing epistemic param
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/salishforge/memforge/issues/162 | 来源类型 github_issue 暴露的待验证使用条件。
## 9. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/salishforge/memforge | last_activity_observed missing
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/salishforge/memforge | no_demo; severity=medium
## 11. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/salishforge/memforge | no_demo; severity=medium
## 12. 运行坑 · 失败模式：performance: REST: /entities and /graph return 500 for invalid agent ids; OpenAPI query path missing epist...
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: REST: /entities and /graph return 500 for invalid agent ids; OpenAPI query path missing epistemic param
- 对用户的影响：Developers may hit a documented source-backed failure mode: REST: /entities and /graph return 500 for invalid agent ids; OpenAPI query path missing epistemic param
- 证据：failure_mode_cluster:github_issue | https://github.com/salishforge/memforge/issues/162 | REST: /entities and /graph return 500 for invalid agent ids; OpenAPI query path missing epistemic param
## 13. 运行坑 · 失败模式：performance: v2.1.0-alpha — Architecture Complete
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: v2.1.0-alpha — Architecture Complete
- 对用户的影响：Upgrade or migration may change expected behavior: v2.1.0-alpha — Architecture Complete
- 证据：failure_mode_cluster:github_release | https://github.com/salishforge/memforge/releases/tag/v2.1.0-alpha | v2.1.0-alpha — Architecture Complete
## 14. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/salishforge/memforge | issue_or_pr_quality=unknown
## 15. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/salishforge/memforge | release_recency=unknown