内容
# 好记忆
语言: 简体中文
好记忆是人工智能产品和编码代理的记忆层。
它为聊天应用程序、副驾驶和代理主机提供了一个持久的用户/项目记忆循环：
写入选定的事实，检索正确的上下文，将其注入下一轮，
审计发生的事情，并在错误时删除它。
好记忆不是一个大型语言模型、代理框架、向量数据库或通用RAG
系统。它是应用程序或安装的代理主机与模型运行时之间的产品记忆层。
## 您将获得
- 持久记忆API：`remember`、`recall`、`buildContext`、`feedback`、`forget`、
`exportMemory`和`deleteAllMemory`。
- 通过`goodmemory setup`为Codex和Claude Code安装代理记忆，
通过托管钩子、安装的Codex预动作、`goodmemory status`、只读
MCP和选择性写入。
- 使用`GoodMemoryConfig.remember`、`RememberProfile`、`rememberRules`、
`RememberInput.annotations`和命名提取器ID进行公共写入自定义。
- 通过编译的`dist`工件和TypeScript声明为`goodmemory`、`goodmemory/ai-sdk`、
`goodmemory/host`和`goodmemory/http`导出包。
- 本地优先存储：Bun默认使用持久化SQLite；可以添加显式Postgres、
注入适配器和嵌入提供程序。
## 基准测试结果
好记忆将经过门控验证的公共声明与内部研究证据分开。 一个数字
只有在`gate:public-benchmark-claim --strict`通过其提交声明后，才能出现在公共声明表中：
完整的覆盖率、`executionFailures: 0`、无记忆基线、确定性
评分或独立裁判、经过验证的数据集来源和许可证，以及可复制的运行（提交 + 命令 + 包版本）。
### 公共声明（门控验证）
<!-- public-claims-table:start -->
| 基准测试 | 主要指标 | 好记忆结果 | 基线/参考 | 声明声明 |
|---|---|---:|---:|---|
| LongMemEval全量500 | 严格：无裁判确定性子集 · 可比较：官方LongMemEval裁判协议 | 严格 **0.720** (360/500) · 官方协议 **0.888** (444/500)，`goodmemory-rules-only` | 无记忆0.068；当前Mem0框架：94.4 Top200 / 94.8 Top50（不同堆栈和预算） | [longmemeval.json](./benchmark-claims/longmemeval.json) |
| MemoryAgentBench（CR，TTL） | 答案准确性 — 确定性，无裁判 | **CR 0.959，TTL 0.767** | 无记忆消融0.000；已发布单跳CR上限~0.60 | [memoryagentbench.json](./benchmark-claims/memoryagentbench.json) |
| LoCoMo（完整10次对话） | 严格：确定性token-F1 · 可比较：行业LLM裁判协议（非对抗性1540） | 严格 **0.6117** (942/1540) · 裁判协议 **0.837** (1289/1540) | 无记忆0.0045非对抗性；当前Mem0框架：92.5 Top200 / 91.8 Top50（不同堆栈和预算） | [locomo.json](./benchmark-claims/locomo.json) |
| ImplicitMemBench Full-300 | 存储答案跨版本裁判重评分 | **0.691** (207.35/300)，gpt-5.4裁判超过gpt-5.5答案，sourceAnswersUnchanged | 上游聊天基线 **0.400** (120/300); 参考线0.66 | [implicitmembench.json](./benchmark-claims/implicitmembench.json) |
<!-- public-claims-table:end -->
每行报告两个跟踪。 **严格** 跟踪是确定性或无裁判 —
一个硬下限，没有LLM裁判可以膨胀。 **可比较** 跟踪在每个基准测试的官方或行业标准裁判协议下重新裁判*相同的存储答案*（不是重新生成），原样， 因此数字位于与已发布的竞争对手结果相同的尺度上。 跟踪之间的差距是量化的裁判宽容度，公开披露而不是隐藏。 可比较跟踪裁判使用gpt-5.4 — 与gpt-5.5答案者不同的模型，但相同的家族；每个协议的详细信息都记录在链接的声明声明中。
LongMemEval声明是无裁判的，取代了早期的内部有裁判数字（0.908），该数字被取代且不可申诉。 一个案例仅在确定性方法得分时才被视为正确
（放弃/精确/包含/预期替代/数字计数）；评估管道的同模型语义裁判（gpt-5.5裁判gpt-5.5）被排除在构造之外 — 使用它，诊断整体准确率为0.896，报告用于透明度但不声明。 声明的0.720（360/500，`executionFailures: 0`，v0.3.5）使用无嵌入的`goodmemory-rules-only`配置文件；放弃仅贡献了360个正确答案中的28个，而无记忆基线的0.068主要是裸放弃（其34个正确中的30个），因此+65.2点的提升是记忆系统的贡献。 无裁判指的是评分 — 答案仍然由gpt-5.5生成。 完整的出处在
[声明声明](./benchmark-claims/longmemeval.json).
MemoryAgentBench声明是好记忆的第一个公共基准声明，并且是有意范围的。 只有冲突解决（CR 0.959）和测试时间学习（TTL 0.767）被声明：无记忆消融两者都得分为`0.000`（问题在没有好记忆的检索巩固事实/上下文演示的情况下是无法回答的），因此这些是真正的记忆贡献，通过确定性方式评分，无LLM裁判（`executionFailures: 0`，259个问题）。 准确检索和长距离理解被排除：无记忆消融得分*更高* （AR 0.926 vs 0.890; LRU 0.632 vs 0.518），因此它们是多选题漏洞，模型从候选项中回答问题，而不是记忆获胜。 CR/TTL衡量答案时间当前值解析和上下文检索，而不是一般检索召回。
LoCoMo声明通过确定性token-F1（无裁判，`executionFailures: 0`跨所有1986个问题，全套10次对话，v0.3.5）进行评分。 配置文件被披露并且选择加入 — 提供商嵌入语义候选联盟（`retrieval.semanticCandidates`, topK 16）加上对话式写入时间提取加上放弃格式答案提示；无嵌入默认配置文件在代表性conv-1切片上得分0.020（银行检索边界），因此此声明专门关于嵌入+提取配置文件，而不是零依赖默认配置文件。 读取非对抗性分割上的记忆提升（0.6117 vs 0.0045 — 1540中942 vs 7个正确）：对抗性类别（446个问题，其黄金答案是字面放弃字符串）被无记忆臂始终放弃（0.998 vs 0.648）轻易掌握，因此整体与整体比较（0.6198 vs 0.2276）低估了可回答问题上的记忆贡献。 答案由gpt-5.5生成 — 无裁判指评分。 LoCoMo数据集是CC BY-NC 4.0（非商业范围），在评估时获取，从不分发。 完整的出处在
[声明声明](./benchmark-claims/locomo.json).
历史上的BEAM 100K结果作为版本证据保留，但不是当前公共声明行，因为其召回路径使用了仅限存储库的`legacy-fitted`配置文件。 它在基准测试的官方统一评分标准裁判下进行评分； 每个项目都评分1.0/0.5/0.0，问题的得分为其项目的平均值（所有400个问题，`judgeFailures: 0`）。 唯一公开的端到端BEAM 100K数字以相同方式评分的是0.49； 好记忆得分0.802（+31分），每个类别的详细信息在声明中 —
包括低于参考类别（instruction_following 0.394 vs 0.66），公开披露而不是平均消除。 严格的内部二进制裁判跟踪是0.7225 vs 0.5725无证据包消融（答案时间证据包贡献+15分）。 召回是双指标根据
[ADR-005](./adr/ADR-005-scenario-fitted-recall-boundary.txt): 规则仅限拟合0.9621 vs泛化底线0.6822禁用所有148个场景拟合门控（已发货选择加入语义候选联盟将该底线提升至0.8529）。 一个协议偏差被披露：论文管道使用排名相关性指标对event_ordering进行评分；此运行和公共参考都使用它。 数据集CC BY-SA 4.0，在评估时获取，从不分发。
ImplicitMemBench Full-300声明使用规范的零故障`run-phase61-full300-rerun-20260706-codex-current`答案，然后用gpt-5.4重新评分相同的存储答案（`sourceAnswersUnchanged: true`）。 裁判是跨版本但属于与gpt-5.5答案模型相同的GPT家族，而不是跨家族裁判。 公共得分是 **0.691** （207.35/300），而上游聊天基线是 **0.400** （120/300），在基线和好记忆臂之间有530个裁判所需的行决策；确定性`structured_first_action`行被继续而不是裁判。 较旧的同模型诊断得分为0.708，不作为公共声明。 最近的代码更改后的最新干净答案再生漂移检查得分0.6895，`executionFailures: 0`; 它显示当前检查点漂移，而不是存储答案可比性工件的替代品。 数据集CC BY 4.0，在评估时获取，从不分发。
### 内部诊断（非公共声明）
被阻止的基准测试数字在它们的声明表示可申诉且`gate:public-benchmark-claim --strict`通过之前不会出现在公共声明表中。 底层运行报告在gitignored `reports/`下，可以从声明中记录的运行命令中复制。
使用 [task-board/00-README.txt](./task-board/00-README.txt)获取执行顺序，
使用 [docs/GoodMemory-Current-Status-and-Evidence.md](./docs/GoodMemory-Current-Status-and-Evidence.md)获取声明边界。
## 选择您的集成路径
好记忆有三个主要的入口。 它们不是唯一的API：
较低级别的表面，如`goodmemory/host`、自定义存储、评估工具和
运行时帮助程序支持这些路径。 它们是从README级别的方式来决定
如何开始。
### 自主代理？ 从这里开始
如果您是一个想要给*自己*持久记忆的代理，请匹配一个路径
并运行它。 机器可读版本的此树生活在
[llms.txt](./llms.txt)和
[.well-known/goodmemory.json](./.well-known/goodmemory.json)（部署的桥
也提供描述符`/.well-known/goodmemory.json`）。
- **您是或运行在Claude Code或Codex中** →
`npm install -g goodmemory@0.5.1 && goodmemory setup`。 不确定已经
配置了什么？ 运行`goodmemory adopt`（添加`--json`获取机器可读计划）：
它检查`.claude/`、`.codex/`和现有的MCP配置，然后打印确切
的下一个命令用于您的环境。
- **您使用MCP** （Cursor、Windsurf、Cline、Claude Desktop、Gemini CLI、
OpenCode或自定义客户端）→ 添加
[独立MCP服务器](#standalone-mcp-for-any-client)；您需要的两个工具
是`goodmemory_get_context`（召回）和`goodmemory_remember`（选择加入写入）。
- **您是框架代理或后端** → 调用
[HTTP桥](#pythonfastapi-http-bridge)：托管在`goodmemory.vibenest.net`
或使用`goodmemory-http-bridge --recommended`（或
`GOODMEMORY_PROFILE=agent-recommended goodmemory-http-bridge`）自托管；
Python调用者使用`pip install goodmemory-client`。
以下文本路径扩展每个选项。
### 1. 将记忆构建到代理、聊天框或副驾驶中
当您拥有产品服务器和模型调用时，请使用此选项。 在您的
Node/Bun服务中安装`goodmemory`，创建一个`memory`实例，并传递一个
稳定的`scope`，例如`userId`、`workspaceId`、`sessionId`，可选
`agentId`。
请求流程是：
1. 在模型调用之前，为当前范围和查询运行`recall()`。
2. 运行`buildContext()`将召回命中转换为提示片段。
3. 使用该记忆上下文调用您的模型。
4. 在响应后，使用`memory.jobs.enqueueRemember()`或`remember()`写入选定的信号。
5. 使用`feedback()`、`reviseMemory()`、`forget()`和`exportMemory()`
进行纠正、删除和用户审计。
如果您的服务器已经使用Vercel AI SDK，请使用`goodmemory/ai-sdk`包装
`generateText()`或`streamText()`而不是整个循环。 从
[应用快速入门](#app-quickstart)开始，然后阅读
[AI SDK适配器](#ai-sdk-adapter)，如果您使用AI SDK。
### 2. 将记忆添加到Codex或Claude Code
当您希望安装的编码代理记住项目和用户上下文而不更改代理本身时，请使用此选项。 安装全局CLI并运行
`goodmemory setup`。
安装主机流程：
1. `session-start`注入会话简报；`user-prompt-submit`注入每个提示的上下文
（在新安装上对新鲜安装进行相关性检查以保持低信号提示清洁）。
2. Claude Code的`Stop`钩子捕获会话记录中的每个回合（`transcript_path`）
进入受控写入候选者 — 有界、编辑、绝不使用原始记录；对于Codex，
`goodmemory codex writeback --from-rollout`
将最新的会话推出通过相同的管道馈送。
3. Codex的`pre-tool-use`可以拒绝或重定向有风险的Bash通过
`goodmemory codex action`在相同的已安装配置和存储路径上。
4. MCP提供跟踪、上下文、统计数据和工件检查；
`goodmemory_remember`写入工具通过`mcp.allowWrite`（或
`goodmemory enable <host> --mcp-allow-write`）选择加入。
5. 写入对于脚本安装保持`off`；交互式安装和
`goodmemory setup --recommended`（一个同意提示）启用`selective`
持久写入 — 可通过`writeback inspect`审计，通过`writeback forget --event-id`可逆。
6. 新安装程序从测量的BM25混合检索层开始，带有
1024令牌会话简报和512令牌门控提示注入；`goodmemory
status`显示检索层、生命周期证明和注入
遥测。可选的`sharedAgents`配置允许一个主机读取另一个
主机的记录（写入仍然归属）。
从[快速入门：Codex 或 Claude Code 内存](#quickstart-codex-or-claude-code-memory)开始。
使用[安装主机写入](#installed-host-writeback)时，请准备好
审查或启用写入。
### 3. 将GoodMemory部署为后端内存层服务
当另一个后端应该将GoodMemory作为服务调用时，请使用此选项，
尤其是在产品后端是Python/FastAPI或产品（如OneLife）将GoodMemory
保持在服务器端而不是将GoodMemory捆绑到移动或浏览器客户端时。
部署打包的`goodmemory-http-bridge`在Node/Bun边车中。 您的后端
然后调用：
- `/memory/recall-context`在其自身的模型调用之前
- `/memory/remember`在用户确认或产品批准的信号后
- `/memory/feedback`用于程序纠正
- `/memory/export`和`/memory/forget`用于审计和删除
- `/memory/revise`用于通过显式记忆ID进行有针对性的纠正
您的服务仍然拥有身份验证、产品策略、UI和模型编排。
GoodMemory拥有内存存储、召回、上下文组装、写入治理和
审计/导出/删除行为。 从
[Python/FastAPI HTTP Bridge](#pythonfastapi-http-bridge) — 官方Python
客户端（`pip install goodmemory-client`）和托管桥实例
`goodmemory.vibenest.net`在那里记录 — 然后检查
[运行时和存储](#runtime-and-storage)以获取SQLite/Postgres选择。
在模型回合期间，GoodMemory执行四个作业：
1. 为当前范围解析内存。
2. 构建一个提示准备好的上下文片段。
3. 在您的应用程序或主机允许时，记录选定的后响应信号。
4. 提供审计、纠正、导出和删除路径以供用户控制。
您的应用程序或安装的代理仍然拥有身份验证、UI、模型调用和
产品策略。 GoodMemory拥有内存循环和存储边界。
## 安装
GoodMemory `0.5.1`有两个正常的安装路径。
使用全局CLI时，您希望在已安装的编码代理中增强内存：
```bash
npm install -g goodmemory@0.5.1
goodmemory setup
goodmemory status
```
使用包依赖时，您正在构建应用程序：
```bash
npm install goodmemory@0.5.1
```
如果您想直接输入`goodmemory`，请安装全局CLI。
项目本地`npm install goodmemory@0.5.1` 不会将`goodmemory`添加到您的shell `PATH`中。
改用`npx goodmemory`、`npm exec -- goodmemory`或`./node_modules/.bin/goodmemory`
从该项目开始。
```bash
npx goodmemory -V
```
Bun 消费者可以直接安装：
```bash
bun add goodmemory@0.5.1
```
发布彩排的tarball验证：
```bash
npm install ./goodmemory-0.5.1.tgz
```
已安装的CLI对于非版本命令使用Bun支持。对于`goodmemory -V`和`goodmemory --version`，软件包二进制文件是Node安全的；其他命令
委托给Bun。
## 快速入门：Codex 或 Claude 代码内存
对于大多数用户来说，第一个有用的路径是安装主机内存。
```bash
npm install -g goodmemory@0.5.1
goodmemory setup
goodmemory status
```
`goodmemory setup` 检测 Codex 和 Claude Code，安装托管主机线路，
并询问：
- 主机：`codex`、`claude` 或两者
- 激活：全局、当前工作区或手动选择
- GoodMemory 用户 ID
- 可选 Postgres 存储
- 可选嵌入提供商
- 可选 LLM 提取提供商
- 回写模式：`off`、`observe`、`review` 或 `selective`
交互式设置默认为全局激活，并使用工作区派生的隔离，
并建议 `selective` 以便新主机配置能够立即生效，
并具有审计和撤销功能。选择 `review` 时，您需要
检查员批准后才能进行持久写入。现有主机配置在其当前回写模式下保持不变，
除非接受交互式提示的默认值。脚本安装通过 `--json` 或 `--no-interactive` 保持安全。
跳过提供商设置是有效的：GoodMemory 仍然适用于本地 SQLite 和仅规则提取。
有用命令：
```bash
goodmemory setup --host codex
goodmemory status codex --workspace-root .
goodmemory enable codex --workspace-root . --writeback observe
goodmemory enable codex --workspace-root . --writeback selective
goodmemory disable codex --workspace-root .
goodmemory uninstall codex
```
已安装的主机路径有四个部分：
- Codex 的托管预动作：`pre-tool-use` 可以拒绝或重定向风险 Bash
命令，而 `goodmemory codex action` 在相同的安装配置、存储、提供商和作用域路径上执行经过审查的第一个步骤。
- 回忆注入：`session-start` 和 `user-prompt-submit` 钩子调用
`recall()` 加上 `buildContext()`，如果配置、解析或存储不可用，则失败并打开。
- 深度检查：`goodmemory mcp serve --host codex` 和 `goodmemory-mcp
--host codex` 暴露只读上下文、跟踪、统计数据和工件工具。
- 可选回写：`session-stop` 和显式回写命令可以将选定的响应信号转换为持久内存。
## 独立 MCP，适用于任何客户端
没有托管安装路径的主机（Cursor、Windsurf、Cline、Claude Desktop、
Gemini CLI、OpenCode 或您自己的 MCP 客户端）可以在独立模式下运行相同的 MCP 服务器 -
无需 `goodmemory setup`，无需主机配置文件。作用域和存储来自标志/环境变量；
提供的服务是相同的 8 个只读工具，以及一个可选的受管辖写入工具：
```json
{
"mcpServers": {
"goodmemory": {
"command": "goodmemory-mcp",
"args": ["--standalone", "--user-id", "YOUR_USER_ID"]
}
}
}
```
等效调用：`goodmemory-mcp --standalone --user-id <id>`（需要
Bun 在 PATH 上；`GOODMEMORY_USER_ID` 作为标志的环境变量备用）。
`--allow-write`（或 `GOODMEMORY_MCP_ALLOW_WRITE=1`）注册
`goodmemory_remember`，它通过正常的受管辖记住管道写入。
由已安装主机写入的带有代理标签的内存对其代理保持私密；
添加 `--agent-id codex` 和共享的 `--storage-url` 以选择加入
读取已安装主机的存储。完整的标志/环境变量矩阵、作用域注释和每个主机配方：
[docs/GoodMemory-Standalone-MCP-Setup-Guide.md](./docs/GoodMemory-Standalone-MCP-Setup-Guide.md)
([Cursor](./docs/GoodMemory-Cursor-Setup-Guide.md) ·
[Gemini CLI](./docs/GoodMemory-Gemini-CLI-Setup-Guide.md) ·
[OpenCode](./docs/GoodMemory-OpenCode-Setup-Guide.md)).
## 已安装主机回写
已安装主机回写是可选的。运行时配置默认值和新的脚本安装保持
`off`，除非用户明确选择回写模式。现有配置在其当前回写模式下保持不变，
除非提供明确的覆盖。新的交互式安装建议 `selective` 以便高信号写入
立即生效，并具有审计和撤销功能；选择 `review` 时，您需要
检查员批准后才能进行持久写入。
在 `selective` 之前使用 `observe`:
```bash
goodmemory enable codex --writeback observe
goodmemory codex writeback --json
goodmemory enable codex --writeback review
goodmemory inspector serve
goodmemory enable codex --writeback selective
goodmemory codex writeback --json
```
`goodmemory inspector serve` 为用户和作用域打开内置的本地 React 控制台，
分类内存和超会话历史、候选决策、回忆证据跟踪和审计事件。
启动令牌在 URL 片段中传递，立即清除到会话存储中，
仅作为持有者头部发送。修订和破坏性操作需要确认、ETag 和幂等键。
参见
[Inspector And Admin API](./docs/GoodMemory-Inspector-and-Admin-API.md).
回写规则：
- `off`：无响应后内存提取。
- `observe`：存储本地有界/编辑的候选预览以供审查，无原始转录或持久内存写入。
- `review`：队列有界/编辑的候选者等待检查员批准；无持久内存写入，直到操作员批准候选者。
- `selective`：通过公共 `remember` 接口写入选定的候选者。
- 原始转录不作为内存持久化。
- 助手源的持久内存被阻止，除非主机确认或验证它，并且活动配置文件允许它。
- `remember: "never"` 在确定性、自定义或辅助提取之前屏蔽注释内容。
审计和撤销：
```bash
goodmemory codex writeback inspect --json
goodmemory codex writeback forget --event-id <event-id> --review-outcome false_write
```
审计账本存储有界的编辑候选预览、候选键、键控链接记录 ID、状态、原因、主机、模式、时间戳、
作用域/会话摘要和可选的手动审查元数据。它不存储原始主机有效载荷。
`forget --event-id` 通过公共 `forget()` 删除链接的内存/证据记录，
然后在标记持久审计事件被遗忘之前；对于仅观察事件，它在不调用 `forget()` 的情况下标记候选被忽略。
Claude Code 具有确定性的 CLI 奇偶校验，用于钩子和回写命令；
Codex 是规范的实时证据路径。
## 脚本主机安装
使用 `goodmemory install <host>` 时，您想要一个完全非交互式的设置：
```bash
goodmemory install codex \
--user-id <user-id> \
--activation-mode global \
--writeback observe \
--storage-provider postgres \
--storage-url "postgres://user:pass@host:5432/goodmemory" \
--embedding-provider openai \
--embedding-model text-embedding-3-small \
--embedding-api-key <key> \
--llm-provider openai \
--llm-model gpt-4o-mini \
--llm-api-key <key> \
--no-interactive
```
托管配置位于 `~/.goodmemory/<host>.json` 下。重新运行安装并使用
提供商标志更新相同的配置，并保持 MCP/钩子注册不变。
包卸载不会删除 `~/.goodmemory`、`repo-local` `.goodmemory`、本地 SQLite 文件或远程 Postgres 数据。
使用 `goodmemory uninstall <host>` 删除托管主机线路，
并使用 `goodmemory forget ...` 或显式存储删除来删除内存数据。
## 应用快速入门
当您构建聊天框、副驾驶或产品代理时，请使用根包。
推荐的 Node 服务路径与 Express 和 Fastify 示例使用的相同薄循环。
更详细的演练位于
[docs/GoodMemory-15-Minute-App-Integration.md](./docs/GoodMemory-15-Minute-App-Integration.md).
```ts
import type { GoodMemoryTraceSpan } from "goodmemory";
import { createGoodMemory } from "goodmemory";
const traceSpans: GoodMemoryTraceSpan[] = [];
const memory = createGoodMemory({
observability: {
traceSink: {
emit(span) {
traceSpans.push(span);
},
},
},
});
const scope = {
userId: "u-1",
workspaceId: "workspace-a",
sessionId: "s-1",
};
const userMessage = "记住迁移 rollout 在 QA 签收后被阻止。";
// 调用 startSession 一次，当产品打开新会话时。对于稍后的回合，
// 使用相同的 sessionId，附加到现有的运行时状态。
await memory.runtime.startSession({ scope });
await memory.runtime.appendMessage({
scope,
message: {
role: "user",
content: userMessage,
},
});
const recall = await memory.recall({
scope,
query: "助手在回复前应该知道什么？",
retrievalProfile: "general_chat",
});
const context = await memory.buildContext({
recall,
output: "system_prompt_fragment",
});
const assistantText = await callYourModel({
memoryContext: context.content,
userMessage,
});
await memory.runtime.appendMessage({
scope,
message: {
role: "assistant",
content: assistantText,
},
});
const writeJob = await memory.jobs.enqueueRemember({
scope,
messages: [
{
role: "user",
content: userMessage,
},
{
role: "assistant",
content: assistantText,
},
],
idempotencyKey: "turn-1",
reason: "post_response_memory_write",
});
const drained = await memory.jobs.drain({ maxJobs: 1 });
const committedJob =
drained.jobs.find((job) => job.jobId === writeJob.jobId) ?? writeJob;
console.log({
traceCount: traceSpans.length,
writeJobId: writeJob.jobId,
writeJobStatus: committedJob.status,
});
async function callYourModel(input: {
memoryContext: string;
userMessage: string;
}): Promise<string> {
void input.memoryContext;
return `Got it. I will keep that in mind: ${input.userMessage}`;
}
```
核心内存循环故意保持较小：
- `remember()` 写入选定的用户、应用或主机信号。
- `recall()` 检索查询的作用域内存。
- `buildContext()` 将回忆命中转换为提示片段或 JSON 有效载荷。
- `feedback()` 记录显式更正和过程偏好。
- `forget()` 删除错误或过时的内存。
对于生产应用集成，推荐的回合循环添加了受管辖的运行时层围绕核心：
- `memory.runtime.startSession()` 和 `memory.runtime.appendMessage()` 跟踪
当前会话状态，无需将原始转录作为持久内存。
- `memory.jobs.enqueueRemember()` 调度响应后内存写入，并具有幂等性和可见的作业状态。
- `memory.jobs.drain()` 提交队列中的写入，在此内存调度程序中。
- `GoodMemoryConfig.observability.traceSink` 接收减污安全的回忆、回忆、
修订、忘记、导出和作业事件的跟踪。
- `memory.reviseMemory({ target: { memoryId } })` 通过显式 ID 更正已知的内存，而不是模糊文本选择。
- `exportMemory()` 为用户提供审计/导出路径。
运行时存档持久性默认为关闭。如果您调用
`memory.runtime.endSession({ scope, archive: "off" })`，会话状态将被清除，
无需写入存档。如果您选择加入存档持久性，请保持仅限摘要，并永远不要将原始转录作为默认内存源。
对于服务器集成，请从薄示例开始：
[examples/express-chat-server.ts](./examples/express-chat-server.ts) 或
[examples/fastify-chat-server.ts](./examples/fastify-chat-server.ts)。
对于 Python/FastAPI 后端，请使用下面的打包 `goodmemory-http-bridge` 路径。
## 可选回忆调优：广义融合、多跳、可选嵌入和对话式提取
以下控件是可选的，并且设计为保守。默认回忆是单次传递和仅规则的，
默认提取保持不变；除非您选择加入，否则不会发生任何变化。推荐的预设具有无提供商的本地路径；
嵌入和提取提供商添加可选通道，但不是必需的。
### 一个标志推荐的检索预设
`retrieval.preset: "recommended"` 通过一个标志启用广义检索和条件对话式提取：
```ts
const memory = createGoodMemory({
retrieval: { preset: "recommended" },
});
```
当激活时，它（a）索引内存、字段和句子粒度回忆文档，（b）融合 BM25、直接实体邻接和任何可用的神经密集候选与 RRF，（c）应用有界动态候选预算，和（d）偏置 `auto` 回忆路由到混合。一个明确的每次调用策略仍然赢，包括 `strategy: "rules-only"`，它绕过广义融合。
当神经嵌入解决时，它贡献了一个密集的 `topK: 16` 通道；
没有一个，检索保持本地、确定性和零网络。预设还将辅助提取翻转为 `mode: "conversational"`，前提是提取模型已经解决并且没有设置明确的模式。它从不注入提供商。留下 `preset` 未设置保留现有的仅规则默认。
要求和边界：
- 无提供商是必需的。神经嵌入端点
(`GOODMEMORY_EMBEDDING_*`、`providers.embedding` 或
`adapters.embeddingAdapter`) 添加可选的密集通道。零出口神经路径是下面的 Ollama 配方。
- `createLocalEmbeddingAdapter()` 在与预设配对时被拒绝：
哈希词典向量将复制词典证据，同时假装是密集的语义通道。
- 检查 `inspectGoodMemoryRuntime(memory).retrievalPreset` - 其 `extraction`
字段报告写入时间的一半是否参与（ `"conversational"`）或提取器不可用/保持原样。
- 预设仅涵盖内存检索和条件提取。答案侧的提示和拒绝政策仍然是应用程序关注的问题。
- 不要将其与 `bm25Ranking: true` 配对，除非您故意想要单独的旧版附加 BM25 槽；广义融合已经有一个 BM25 通道。
- 如果您使用环境解析提取并采用预设，则写入输出变为对话式原子声明；退出通道是一个显式
`providers.extraction` 对象，模式为 `"default"`。
### 可选逐点重新排序器
添加一个第一方 OpenAI 兼容的逐点重新排序器，当融合的候选集有用但其最终顺序是嘈杂的：
```ts
const memory = createGoodMemory({
retrieval: { preset: "recommended" },
providers: {
reranking: {
provider: "openai",
model: process.env.RERANKING_MODEL!,
apiKey: process.env.RERANKING_API_KEY!,
baseURL: process.env.RERANKING_BASE_URL,
},
},
});
const result = await memory.recall({ scope, query });
console.log(result.metadata.retrievalTrace?.reranker);
```
每个选定的事实都在一个独立的查询文档调用中得分；不会将 sibling 候选放入同一个重新排序提示中。重新排序器仅重新排序已经由确定性回忆允许的事实，因此它不能扩大成员资格或放松接地拒绝。提供商超时、模式或网关失败返回原始确定性顺序，并记录
`status: "fallback"` 加上 `retrievalTrace` 中的稳定原因。设置
`rerank: false` 在一次回忆中跳过它。显式 `adapters.reranker` 仍然对 `providers.reranking` 具有权威。基于提供商的重新排序默认为 15 秒请求超时；在选择的网关需要不同的延迟预算时，设置可选的正整数
`requestTimeoutMs`。
跟踪包括有界通道/RRF 属性、模型角色、清理的网关、延迟、分数和之前/之后的排名。它不包括 API 密钥、查询文本或内存内容。这是可选的，并为此添加一个模型调用每个事实；在有界重新排序窗口中，推荐的无提供商路径保持不变。
### 可选本地嵌入端点（Ollama）
推荐的预设不使用嵌入。要添加零出口神经密集通道，
`GOODMEMORY_EMBEDDING_BASE_URL` 接受任何 OpenAI 兼容的 `/v1/embeddings` 端点，
包括本地 Ollama 服务器。
```bash
ollama pull nomic-embed-text # 或 bge-m3 以获得更强的多语言召回
export GOODMEMORY_EMBEDDING_PROVIDER=openai
export GOODMEMORY_EMBEDDING_BASE_URL=http://localhost:11434/v1
export GOODMEMORY_EMBEDDING_MODEL=nomic-embed-text
export GOODMEMORY_EMBEDDING_API_KEY=ollama # 任意占位符；Ollama 忽略它，该变量仍然是必需的
# 在启动您的应用程序之前检查端点
curl http://localhost:11434/v1/embeddings \
-H "Content-Type: application/json" \
-d '{"model": "nomic-embed-text", "input": "hello"}'
```
- `provider` 保持 `openai`：它选择 OpenAI 兼容的线协议，
不是供应商。
- 每个存储保留一个嵌入模型：不同模型或
尺寸的向量不可比较，并且切换模型意味着重新回忆（重新嵌入）语料库。
- 本地嵌入质量与 `text-embedding-3-small` 不同；公开的
LoCoMo 数字是在 OpenAI 端点测量的。该配方
重现了该机制，而零出口，不确切的数字。
- 这不是 `createLocalEmbeddingAdapter()`（下面），它是
哈希词典，不是语义的，被推荐的预设拒绝。
### 可选的多跳召回
`recall()` 默认情况下是单次通过的。传入 `multiHop: true` 以选择双次检索：GoodMemory 运行查询，提取第一跳证据中命名的桥接实体，用它们扩展查询，并运行第二跳。
```ts
const recall = await memory.recall({
scope,
query: "谁管理了爱丽丝启动的项目？",
multiHop: true,
});
```
在答案需要只有第一跳命名的实体时使用（跳 1 找到“爱丽丝启动了 Atlas 项目”；跳 2 需要“谁管理 Atlas 项目”）。
- 它是可选的。默认召回仍然是单次通过；不设置 `multiHop` 不会改变任何内容。
- 它 **不是** 通用语义检索器。它通过词典桥接命名实体；它不按含义排名。
- 当第一跳召回较弱时，它 **可能会增加噪音**：如果跳 1 出现错误的证据，则提取的桥接实体是错误的，扩展的查询会稀释召回。在 LoCoMo 上测量（基础检索非常低）`multiHop` *伤害* 召回，因此不要用它来修复对话/短语差距检索 — 那需要真正的语义检索，而不是多跳桥接。
### 离线本地嵌入适配器
`createLocalEmbeddingAdapter()` 是一个确定性、离线、无依赖的嵌入适配器（哈希字符 n-gram 矢量）。注入它以进行词汇/形态打破 tie，无需配置嵌入提供程序：
```ts
import { createGoodMemory, createLocalEmbeddingAdapter } from "goodmemory";
const memory = createGoodMemory({
adapters: { embeddingAdapter: createLocalEmbeddingAdapter() },
});
```
- 它 **不是** 神经语义检索。矢量是哈希词汇特征，因此它们打破词汇相似候选之间的 tie；它们不理解含义。
- 不要 **使用它来声称语义基准改进**。它无法桥接问题到文本的短语差距，而这些差距已经忽略词汇重叠。
- 对于真正的语义排名，通过 `GOODMEMORY_EMBEDDING_*` 配置神经嵌入提供程序。
### 可选的对话事实提取
默认情况下，辅助提取（当配置了 `providers.extraction` 模型时）会提取持久的产品记忆 — 个人资料、偏好、参考和事实。设置 `providers.extraction.mode: "conversational"` 以在写入时将对话分解为自包含的、经过核心参考解析的、以实体和日期规范化的原子声明，以便后续检索与规范化的事实相匹配，而不是原始的对话回合。
```ts
const memory = createGoodMemory({
providers: {
extraction: {
provider: "openai",
model: "gpt-5.6-terra",
apiKey: process.env.GOODMEMORY_ASSISTED_EXTRACTOR_API_KEY!,
baseURL: process.env.GOODMEMORY_ASSISTED_EXTRACTOR_BASE_URL,
mode: "conversational",
},
},
});
```
在聊天/代理产品中使用它，其中记忆来自多轮对话，问题以与事物被提及的方式不同的方式表达（“谁是用户的经理？” vs. “是的，我的老板 Dana 签字了”）。
- 它是可选的。留下 `mode` 未设置（或省略 `providers.extraction`）保持默认提取行为；召回排名路径不受影响。
- 它是 **写入时 LLM 传递**：它使用您配置的聊天模型，因此它增加了提取延迟和令牌成本，并且像任何 LLM 步骤一样，它可能会删除或误传声明。原始回合仍然是真相。
- 它 **不是** 语义检索。它规范存储的文本，以便词汇检索有更好的表面来匹配；它不按含义排名。它是无嵌入的杠杆，用于对话短语差距，而不是神经嵌入提供程序的替代品。
- 不要 **引用它的基准数字**，而没有保留验证，并且不要调整提取提示到特定基准的短语。
## 运行时和存储
`createGoodMemory({})` 遵循本地优先的自动存储合约：
- 显式 `storage.provider` 优先。
- 没有显式存储，GoodMemory 仅在配置的目标可以启动 GoodMemory 后端时使用 Postgres。
- 在 Bun 上，零配置持久存储是本地 SQLite，位于 `./.goodmemory/memory.sqlite`。
- 在没有内置本地 SQLite 适配器的 Node 运行时上，零配置存储回落到内存中。
- 不受支持的显式内置 `sqlite` 或 `postgres` 选择被报告为不可用，而不是错误标记为持久存储。
- 注入的 `documentStore`、`sessionStore` 或 `vectorStore` 适配器被报告为适配器定义的存储。
- 没有检索预设，运行时行为保持 `rules-only`，与嵌入配置无关。`recommended` 预设将 `auto` 路由到其提供者免费的混合融合路径，并在配置时添加密集证据。
- 支持的本地运行时可以使用 `sqlite-vss` 进行 SQLite 语义索引；不支持的运行时保持持久的非加速回落行为。
检查已解析的运行时而不是猜测：
```ts
import { createGoodMemory, inspectGoodMemoryRuntime } from "goodmemory";
const memory = createGoodMemory({});
const runtime = inspectGoodMemoryRuntime(memory);
console.log(runtime.storage);
```
SQLite 矢量控制：
- `GOODMEMORY_SQLITE_VECTOR_MODE=off|prefer|require`
- `GOODMEMORY_SQLITE_CUSTOM_LIBRARY_PATH`
- `GOODMEMORY_SQLITE_VECTOR_EXTENSION_PATH`
- `GOODMEMORY_SQLITE_VECTOR_EXTENSION_ENTRYPOINT`
- `GOODMEMORY_SQLITE_VECTOR_SEARCH_FUNCTION`
## 公共记忆自定义
产品集成应通过公共 `remember` 接口自定义写入。不要为产品行为使用仅限测试的提取器缝隙。
```ts
import { createGoodMemory, rememberRules } from "goodmemory";
const memory = createGoodMemory({
remember: {
preset: "default",
profiles: [
{
id: "life-coach",
when: { agentId: "life-coach" },
rules: [
rememberRules.fact(/my top priority this quarter is (.+)/i, {
id: "life-goal-priority",
category: "goal",
tags: ["life_coach", "long_term_goal"],
attributes: { horizon: "quarter" },
content: ({ match }) => match[1] ?? "",
}),
rememberRules.preference(/please coach me with (.+)/i, {
id: "life-coaching-style",
category: "coaching_style",
value: ({ match }) => match[1] ?? "",
}),
],
assistantOutputs: { mode: "confirmed_or_verified_only" },
},
],
},
});
await memory.remember({
scope: { userId: "u-1", agentId: "life-coach" },
messages: [
{
role: "user",
content: "这个季度我的首要任务是重建我的睡眠习惯。",
},
],
annotations: [
{
messageIndex: 0,
remember: "always",
metadataPatch: { tags: ["confirmed_by_host"] },
},
],
});
```
配置文件 `extractors` 可以是原始 `MemoryExtractor` 对象或命名 `{ id, extractor }` 条目。对于真正的集成，请使用命名提取器，以便记住事件和评估报告携带稳定的 `extractorIds`，即使配置文件组成发生变化。记住事件还携带解析的 `profileId` 和 `presetId` 元数据。
## AI SDK 适配器
GoodMemory 的 Node 兼容 AI SDK 路径是一个普通的 `Request -> Response` 服务器处理程序，由 `createGoodMemory()` 和 `createGoodMemoryAISDK()` 构建。
```ts
import { createGoodMemory } from "goodmemory";
import type { GoodMemoryStreamTextInput } from "goodmemory/ai-sdk";
import { createGoodMemoryAISDK } from "goodmemory/ai-sdk";
const memory = createGoodMemory({});
const aiSDK = createGoodMemoryAISDK({
memory,
});
type MemoryChatRequest = Pick<
GoodMemoryStreamTextInput,
"messages" | "query" | "scope" | "system"
>;
function isMemoryChatRequest(value: unknown): value is MemoryChatRequest {
if (!value || typeof value !== "object" || Array.isArray(value)) {
return false;
}
const candidate = value as Record<string, unknown>;
const scope = candidate.scope;
return Array.isArray(candidate.messages)
&& !!scope
&& typeof scope === "object"
&& !Array.isArray(scope)
&& typeof (scope as { userId?: unknown }).userId === "string"
&& (scope as { userId: string }).userId.trim().length > 0;
}
export async function handleMemoryChat(request: Request): Promise<Response> {
const body: unknown = await request.json();
if (!isMemoryChatRequest(body)) {
return new Response(
JSON.stringify({
error: "Expected a request body with a messages array and scope.userId.",
}),
{
headers: { "content-type": "application/json; charset=utf-8" },
status: 400,
},
);
}
const result = aiSDK.streamText({
messages: body.messages,
query: body.query,
scope: body.scope,
system: body.system,
model: {} as never,
});
return result.toTextStreamResponse();
}
```
注意：
- 规范的服务器示例是 [examples/plain-ai-sdk-server.ts](./examples/plain-ai-sdk-server.ts)。
- 精简的 Express 和 Fastify 示例分别是 [examples/express-chat-server.ts](./examples/express-chat-server.ts) 和 [examples/fastify-chat-server.ts](./examples/fastify-chat-server.ts)。
- [examples/vercel-ai-chat.ts](./examples/vercel-ai-chat.ts) 仍然是一个较低级别的包装器/API 示例。
- Next.js App Router 可以将 `export async function POST(request: Request)` 映射到相同的处理程序正文。
- 第一个公共服务器路径是 `ModelMessage`-first。
- 包装器通过 `recall()` 和 `buildContext()` 增强 `system`，如果内存层出错，则软失败。
## Python/FastAPI HTTP 桥接
当 Python 后端应将 GoodMemory 调用为服务器端内存服务时，请使用打包的 HTTP 桥接。
```bash
GOODMEMORY_HTTP_BRIDGE_TOKEN="replace-with-service-token" \
GOODMEMORY_STORAGE_PROVIDER=postgres \
GOODMEMORY_STORAGE_URL="postgres://user:pass@host:5432/goodmemory" \
./node_modules/.bin/goodmemory-http-bridge --profile life-coach
```
Python 调用者发送 `Authorization: Bearer <token>` 以及 `x-goodmemory-*` 范围标头到 `POST /memory/recall-context`、`/memory/remember`、`/memory/feedback`、`/memory/export`、`/memory/forget` 和有针对性的 `/memory/revise`。TypeScript 桥接 API 可从 `goodmemory/http` 获得。
要通过桥接器提供推荐的检索预设（多粒度 BM25 + 实体 + RRF，可选的密集通道），请使用一个开关 `--recommended`（或 `GOODMEMORY_PROFILE=agent-recommended` 或 `GOODMEMORY_HTTP_BRIDGE_RECOMMENDED=1`）。不需要嵌入端点；`GOODMEMORY_EMBEDDING_*` 在配置时添加密集通道。`GET /healthz` 报告 `retrievalTier` 和 `embeddingEnabled`，召回请求默认为 `strategy: "auto"`，预设将其路由到 `hybrid`。显式 `strategy: "rules-only"` 请求仍然选择严格的地板。
或使用 Docker 一键部署（包括 SQLite 卷；添加 compose `postgres` 配置文件以支持 pgvector）：
```bash
GOODMEMORY_HTTP_BRIDGE_TOKEN="replace-with-service-token" docker compose up -d
curl -fsS http://127.0.0.1:8739/healthz
```
`GET /healthz` 是容器、负载均衡器和客户端就绪等待的身份验证免费的活动端点。Python 后端应使用官方客户端 — `pip install goodmemory-client` ([PyPI](https://pypi.org/project/goodmemory-client/)) — 它从一个 `Scope` 对象派生调用者头部，镜像每个端点的幂等规则，并显示召回 `routing`（以便 Silent 策略降级是可见的）。详细信息： [docs/GoodMemory-Python-HTTP-Integration-Bridge.md](./docs/GoodMemory-Python-HTTP-Integration-Bridge.md).
**托管实例。** 一个实时 GoodMemory 桥接器运行在 `https://goodmemory.vibenest.net`（活动： [`/healthz`](https://goodmemory.vibenest.net/healthz））。通过 `GOODMEMORY_BRIDGE_HOST` / `--goodmemory-host`（或 `GoodMemoryClient` 主机参数）将任何客户端指向它，而不是本地 URL；它强制执行 bearer-token 身份验证，因此请携带您自己的服务令牌。它是一个单进程、可写入的 API — 在公开暴露之前，请添加速率限制和一次性作用域数据，并且永远不要发布共享的写入令牌。
## 主机适配器 API
当外部主机需要工件或主机特定合约时，请使用 `goodmemory/host`。
```ts
import { createGoodMemory } from "goodmemory";
import { createHostAdapter } from "goodmemory/host";
const memory = createGoodMemory({});
const adapter = createHostAdapter({
id: "codex-handoff",
hostKind: "codex",
memory,
readableArtifactTypes: ["session_memory"],
});
const result = await adapter.readArtifacts({
scope: {
userId: "u-1",
workspaceId: "workspace-a",
sessionId: "s-1",
},
includeRuntime: true,
});
```
模式：
- `file-assisted`：读取编译后的工件，如 `MEMORY.md`、`user.md`、`session-memory/<sessionId>.md` 和 `playbooks/*.md`，而不将文件视为规范存储。
- `file-authoritative`：适用于最小的可写子集。今天，该子集是规范的 `playbooks/*.md` 文件形状，写入结构化增量以回馈有效的验证模式记录。
可写防护措施：
- 提示和技能片段文件保持派生只读输出。
- 风险高的指导编辑需要显式 `verifyWrite` 批准。
- 低风险的元数据编辑，如 `appliesTo` 和 `Why`，可以在无需额外批准步骤的情况下写入。
- 失败的可写操作返回带有回滚指导的诊断信息。
当前的 Claude/Codex 示例默认情况下处于 `file-assisted` 模式。
## CLI 参考
shell `PATH` 上的 `goodmemory` 命令是使用 `npm install -g goodmemory@0.5.1` 安装的全局 CLI。在本地依赖安装中，通过 `npx goodmemory`、`npm exec -- goodmemory` 或 `./node_modules/.bin/goodmemory` 调用包二进制文件。存储库本地的 `bun run goodmemory` 脚本仅用于开发。
内存优先的命令：
```bash
./node_modules/.bin/goodmemory inspect --user-id <user-id> --workspace-id <workspace-id>
./node_modules/.bin/goodmemory trace --user-id <user-id> --workspace-id <workspace-id> --query "Which runbook is the source of truth?"
./node_modules/.bin/goodmemory export-memory --user-id <user-id> --workspace-id <workspace-id> --output ./tmp/export
./node_modules/.bin/goodmemory stats --user-id <user-id> --workspace-id <workspace-id>
./node_modules/.bin/goodmemory remember --user-id <user-id> --workspace-id <workspace-id> --session-id <session-id> --message "Remember that the deploy is blocked on smoke verification."
./node_modules/.bin/goodmemory feedback --host codex --workspace-root . --session-id <session-id> --signal "Keep coding summaries short and list explicit next steps."
./node_modules/.bin/goodmemory forget --host codex --workspace-root . --session-id <session-id> --memory-id <memory-id>
```
已安装主机命令：
```bash
goodmemory -V
goodmemory --version
goodmemory setup --host codex
goodmemory status codex --workspace-root .
goodmemory install codex --activation-mode global --writeback observe --user-id <user-id>
goodmemory enable codex --workspace-root . --writeback selective
goodmemory mcp serve --host codex
goodmemory-mcp --host codex
goodmemory codex bootstrap --user-id <user-id> --workspace-id <workspace-id>
goodmemory claude bootstrap --user-id <user-id> --workspace-id <workspace-id>
```
钩子和写回示例：
```bash
printf '%s' '{"cwd":".","session_id":"s-1","hook_event_name":"SessionStart","source":"startup"}' \
| goodmemory codex hook session-start
printf '%s' '{"cwd":".","session_id":"s-1","tool_name":"Bash","tool_input":{"command":"./tools/DeepAnalyzer --detailed"}}' \
| goodmemory codex hook pre-tool-use
goodmemory codex action -- ./tools/DeepAnalyzer --detailed
printf '%s' '{"cwd":".","session_id":"s-1","messages":[{"role":"user","content":"Next step is to finish the release smoke."}]}' \
| goodmemory codex writeback --json
printf '%s' '{"cwd":".","session_id":"s-1","event_id":"stop-1","summary":"Keep coding summaries short."}' \
| goodmemory codex hook session-stop```
评估工件检查：
```bash
./node_modules/.bin/goodmemory eval inspect --run-dir reports/eval/live/<run-id> --case-id <case-id>
./node_modules/.bin/goodmemory eval trace --run-dir reports/eval/live/<run-id> --case-id <case-id>
./node_modules/.bin/goodmemory eval export-case --run-dir reports/eval/live/<run-id> --case-id <case-id> --json
./node_modules/.bin/goodmemory eval export-case --run-dir reports/eval/live/<run-id> --case-id <case-id> --output /tmp/case.json
```
CLI 界面：
- `goodmemory -V`
- `goodmemory --version`
- `goodmemory setup`
- `goodmemory status`
- `goodmemory install`
- `goodmemory uninstall`
- `goodmemory enable`
- `goodmemory disable`
- `goodmemory inspect`
- `goodmemory trace`
- `goodmemory export-memory`
- `goodmemory stats`
- `goodmemory remember`
- `goodmemory feedback`
- `goodmemory forget`
- `goodmemory mcp serve`
- `goodmemory-mcp`
- `goodmemory codex hook`
- `goodmemory codex writeback`
- `goodmemory claude hook`
- `goodmemory claude writeback`
- `goodmemory codex bootstrap`
- `goodmemory claude bootstrap`
- `goodmemory eval inspect`
- `goodmemory eval trace`
- `goodmemory eval export-case`
## 示例
安装包指南：
- 15分钟应用集成指南：
[docs/GoodMemory-15-Minute-App-Integration.md](./docs/GoodMemory-15-Minute-App-Integration.md)
- 参考集成指南：
[docs/GoodMemory-Reference-Integration-Guide.md](./docs/GoodMemory-Reference-Integration-Guide.md)
- Codex 交接设置指南：
[docs/GoodMemory-Codex-Handoff-Setup-Guide.md](./docs/GoodMemory-Codex-Handoff-Setup-Guide.md)
- Claude Code 设置指南：
[docs/GoodMemory-Claude-Code-Setup-Guide.md](./docs/GoodMemory-Claude-Code-Setup-Guide.md)
仓库本地示例：
- 基本聊天集成： [examples/basic-chat.ts](./examples/basic-chat.ts)
- Coding-agent风格集成：
[examples/coding-agent.ts](./examples/coding-agent.ts)
- 普通AI SDK服务器集成：
[examples/plain-ai-sdk-server.ts](./examples/plain-ai-sdk-server.ts)
- Express聊天服务器集成：
[examples/express-chat-server.ts](./examples/express-chat-server.ts)
- Fastify聊天服务器集成：
[examples/fastify-chat-server.ts](./examples/fastify-chat-server.ts)
- AI SDK包装集成：
[examples/vercel-ai-chat.ts](./examples/vercel-ai-chat.ts)
- 生活教练公共记忆配置文件：
[examples/life-coach-remember-profile.ts](./examples/life-coach-remember-profile.ts)
- Claude风格主机工件消耗：
[examples/host-claude-artifacts.ts](./examples/host-claude-artifacts.ts)
- Codex风格会话交接消耗：
[examples/host-codex-handoff.ts](./examples/host-codex-handoff.ts)
从此仓库运行示例：
```bash
bun run example:chat
bun run example:coding-agent
bun run example:ai-sdk-server
bun run example:express-chat
bun run example:fastify-chat
bun run example:vercel-ai
bun run example:life-coach-profile
bun run example:host-claude
bun run example:host-codex
```
## 测试和评估
默认本地网关：
```bash
bun test
bun run typecheck
bun run test:coverage
```
仅在您故意需要更广泛的扫荡时使用`bun run test:all`通过供应商或第三方测试树。
评估命令：
```bash
bun run eval:smoke
bun run eval:fallback
bun run eval:live
bun run eval:live-memory
bun run eval:live-auto-memory
bun run eval:live-provider-memory
bun run eval:summary
```
含义：
- `eval:smoke`：自我检查。
- `eval:fallback`：无需实时模型调用的确定性验证。
- `eval:live`：实时生成器加实时评判器，内存后端。
- `eval:live-memory`：实时生成器加实时评判器，使用自动存储语义；默认存储为本地SQLite，除非提供商存储解析。
- `eval:live-auto-memory`：当脚本需要显式自动存储时的`eval:live-memory`别名。
- `eval:live-provider-memory`：需要Postgres、嵌入和辅助提取的提供商支持的证据路径；它不会静默回退到SQLite。
- `eval:summary`：总结现有的评估输出目录。
实时评估环境：
- `GOODMEMORY_EVAL_PROVIDER`
- `GOODMEMORY_EVAL_BASE_URL`，适用于OpenAI兼容网关
- `GOODMEMORY_EVAL_MODEL`
- `GOODMEMORY_EVAL_API_KEY`
- `GOODMEMORY_EVAL_MAX_CONCURRENCY`可选并行上限
- `GOODMEMORY_JUDGE_PROVIDER`
- `GOODMEMORY_JUDGE_BASE_URL`，适用于OpenAI兼容网关
- `GOODMEMORY_JUDGE_MODEL`
- `GOODMEMORY_JUDGE_API_KEY`
`eval:live-memory`和`eval:live-auto-memory`还需要嵌入和辅助提取器配置：
- `GOODMEMORY_EMBEDDING_PROVIDER`
- `GOODMEMORY_EMBEDDING_BASE_URL`，适用于OpenAI兼容网关
- `GOODMEMORY_EMBEDDING_MODEL`
- `GOODMEMORY_EMBEDDING_API_KEY`
- `GOODMEMORY_ASSISTED_EXTRACTOR_PROVIDER`
- `GOODMEMORY_ASSISTED_EXTRACTOR_BASE_URL`，适用于OpenAI兼容网关
- `GOODMEMORY_ASSISTED_EXTRACTOR_MODEL`
- `GOODMEMORY_ASSISTED_EXTRACTOR_API_KEY`
`eval:live-provider-memory`还需要：
- `GOODMEMORY_TEST_POSTGRES_URL`
输出目录：
- 实时运行：`reports/eval/live/run-*`
- 自动存储实时内存运行：`reports/eval/live-memory/run-*`
- 提供商支持的实时内存运行：`reports/eval/live-provider-memory/run-*`
- 回退运行：`reports/eval/fallback/run-*`
## 策略推出
GoodMemory将`rules-only`作为支持的基线。新的检索行为通过`observe -> assist -> promote`进行。
操作员指南：
- `observe`：收集孤立的影子证据，而不改变执行的路径。
- `assist`：在受控评估运行中允许候选执行。
- `promote`：需要`strategy-promotion-gate.json`、`regression-dashboard.json`和`strategy-promotion-authorization.json`。
- 当评估证据不完整、提供商支持的依赖不可用或回滚条件存在时，请保持`rules-only`。
## 当前状态
当前稳定的公共界面：
- 通过`goodmemory`的根内存API
- 通过`goodmemory/ai-sdk`的AI SDK适配器
- 通过`goodmemory/host`的主机适配器和主机合约
- 通过`goodmemory/http`和打包的`goodmemory-http-bridge`的HTTP桥接API
- 通过`goodmemory setup`安装的CLI和管理主机设置
- 用于回忆的Codex和Claude Code钩子
- 用于检查和调试的只读MCP
- 带有审计和撤销的安装主机写回（需选择加入）
- Bun上的本地SQLite持久回退
- 配置后，提供商支持的评估，包括Postgres、嵌入、辅助提取等
仍在公共声明范围之外：
- 默认开启的自动写回
- 原始转录存档
- 仪表板或托管云
- 将导出的工件文件视为规范存储
- 通过内部提案或推广内部件，扩大根导出
有关详细的当前状态和证据映射，请使用[docs/GoodMemory-Current-Status-and-Evidence.md](./docs/GoodMemory-Current-Status-and-Evidence.md)。
## 文档
- 文档映射和存档策略：
[docs/README.md](./docs/README.md)
- 当前状态和证据：
[docs/GoodMemory-Current-Status-and-Evidence.md](./docs/GoodMemory-Current-Status-and-Evidence.md)
- 产品比较：
[docs/GoodMemory-Product-Comparison.md](./docs/GoodMemory-Product-Comparison.md)
- 规范设计：
[docs/GoodMemory-First-Principles-and-Reference-Architecture.md](./docs/GoodMemory-First-Principles-and-Reference-Architecture.md)
- v1实现架构：
[docs/GoodMemory-OSS-Architecture-v1.md](./docs/GoodMemory-OSS-Architecture-v1.md)
- PRD：
[docs/GoodMemory-PRD.md](./docs/GoodMemory-PRD.md)
- TDD和评估策略：
[docs/GoodMemory-TDD-and-Evaluation-Strategy.md](./docs/GoodMemory-TDD-and-Evaluation-Strategy.md)
- 策略推出指南：
[docs/GoodMemory-Strategy-Rollout-Guide.md](./docs/GoodMemory-Strategy-Rollout-Guide.md)
- 发布检查清单：
[docs/GoodMemory-v1-Release-Checklist.md](./docs/GoodMemory-v1-Release-Checklist.md)
- 历史质量门控存档：
[docs/archive/quality-gates/README.md](./docs/archive/quality-gates/README.md)
- 历史v1快照：
[docs/GoodMemory-v1-Quality-Gate.md](./docs/GoodMemory-v1-Quality-Gate.md)
- 框架食谱 — 代理框架中的持久内存：
[LangGraph](./docs/cookbooks/langgraph.md) ·
[CrewAI](./docs/cookbooks/crewai.md) ·
[OpenAI Agents SDK](./docs/cookbooks/openai-agents-sdk.md)
使用 [task-board/00-README.txt](./task-board/00-README.txt) 获取执行顺序、开放后续工作和特定阶段的验收边界。存档的设计输入不是当前事实，而是通过`docs/README.md`路由。
连接信息
猜你喜欢
暂无推荐服务器