核心定位与设计目标

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 接口层、合并调度层与多层级存储后端组成。下图展示了请求在系统内的主要流向：

flowchart LR
    Client[Agent / SDK] -->|REST /memory/:agentId/*| API[Express Router<br/>src/server.ts]
    API --> Query[Query Engine]
    API --> Add[Add Path]
    Query --> Hybrid[Hybrid Search<br/>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 的核心记忆系统是一套面向 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）

记忆按访问频率与生命周期分入三个物理层级：

资料来源：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. 写入、检索与整合数据流

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 文档。

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

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)]

部署与发布方式

运行时依赖

完整功能依赖三类外部服务：

社区常见的本地起栈方式是通过 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 发布 的现代交付链路，既适合嵌入既有智能体框架，也便于作为独立服务托管。

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。

此外，/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 错误语义作为优先修复项。

Pitfall Log / 踩坑日志

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