Question 1

如何修复首次运行时出现的 AgentMemory 错误 "Failed to load persisted index: Cannot read properties of undefined (reading v)"？

Accepted Answer

将 AgentMemory 升级到 v0.9.26 或更高版本，该版本修复了分片索引清单（sharded index manifest）的加载问题，此问题会影响那些在键缺失时返回 `undefined` 的适配器：

```bash
npm install -g @agentmemory/agentmemory@0.9.26
```

然后重新运行 AgentMemory。在 v0.9.25 中，该错误仅在首次运行时造成表象上的影响：启动后不久，带防抖（debounced）的保存过程会自动重建索引，因此如果您无法立即升级，可以安全地忽略该错误。

Question 2

如何修复 agentmemory 因已安装 iii-engine v0.16.1 但 v0.11.2 被硬性固定而拒绝启动的问题？

Accepted Answer

在全新全局安装的 agentmemory v0.9.24 上，覆盖运行时版本检查，以使用已安装的、版本一致的 v0.16.1 引擎和 worker 组件：

```bash
AGENTMEMORY_III_VERSION=0.16.1 agentmemory
```

对于 `npx`，运行：

```bash
AGENTMEMORY_III_VERSION=0.16.1 npx @agentmemory/agentmemory@latest
```

要使其在当前 shell 中持久生效：

```bash
export AGENTMEMORY_III_VERSION=0.16.1
agentmemory
```

在 Ubuntu 24.04 aarch64 上，此操作可成功启动 iii-engine v0.16.1，并报告 worker/REST 服务运行正常。请勿盲目按照建议降级到 v0.11.2 的 tarball：其 `iii-aarch64-unknown-linux-gnu.tar.gz` 仅包含 `iii` 二进制文件，这会导致 v0.11.2 的 `iii` 与 v0.16.1 的 `iii-worker` 搭配使用，从而产生另一种版本不匹配问题。永久修复方案是让安装程序获取锁定（pinned）的引擎版本，或者由 agentmemory 将其锁定版本更新至 v0.16.1。

Question 3

为什么 ~/.agentmemory/.env 中的 AGENTMEMORY_TOOLS=core 被忽略，该如何修复？

Accepted Answer

在 `@agentmemory/agentmemory@0.9.27` 中，`src/mcp/tools-registry.ts` 里的 `getVisibleTools()` 直接读取 `process.env.AGENTMEMORY_TOOLS`，而不是读取合并后的环境变量（`loadEnvFile()` + `process.env`），因此仅在 `~/.agentmemory/.env` 中设置的值会被静默忽略，导致暴露全部 53 个工具，而非 8 个核心工具。在补丁发布前的临时解决方案：(1) 使用 CLI 标志启动，即 `agentmemory --tools core`；或 (2) 在启动 shell 中导出该变量，例如 `AGENTMEMORY_TOOLS=core agentmemory`，或在 pm2 ecosystem 文件的 `env` 块中进行配置，然后执行 `pm2 restart agentmemory`。使用 `(Invoke-RestMethod 'http://127.0.0.1:3111/agentmemory/mcp/tools').tools.Count` 进行验证——它应返回 8。永久修复方法是将 `getVisibleTools()` 以及 `src/mcp/standalone.ts` 中的 `process.env["AGENTMEMORY_TOOLS"]` 改为 `getEnvVar("AGENTMEMORY_TOOLS")`。

Question 4

如何修复在使用 agent-sdk provider 汇总大型 AgentMemory 会话时出现的 "too_many_chunks_skipped: chunks failed to parse after retry" 错误？

Accepted Answer

该问题影响 `@agentmemory/agentmemory` 0.9.22 至 0.9.24 版本（当 `AGENTMEMORY_ALLOW_AGENT_SDK=true` 时）。agent-sdk 的递归防护机制会设置全局的 `process.env.AGENTMEMORY_SDK_CHILD`，因此并发的摘要分块会检测到该标志并返回空响应，从而被计为解析失败。作为临时解决方案，可在 `~/.agentmemory/.env` 中添加 `SUMMARIZE_CHUNK_CONCURRENCY=1`，强制分块摘要串行运行，然后重启 worker：

```bash
echo 'SUMMARIZE_CHUNK_CONCURRENCY=1' >> ~/.agentmemory/.env
```

如需在 shell 中临时运行：

```bash
SUMMARIZE_CHUNK_CONCURRENCY=1 AGENTMEMORY_ALLOW_AGENT_SDK=true node your-worker.js
```

然后重试摘要操作。永久性的代码修复方案是：用进程内机制（例如 `AsyncLocalStorage` 或每次调用的标志）替换进程级全局环境变量递归防护，同时仅在真正的子进程边界处保留环境变量防护。

Question 5

为什么我复现的 agentmemory coding-agent-life-v1 的 P@5 只有 0.240，而不是已公布的基准分数？

Accepted Answer

你复现的数字是正确的；已发布的评分卡是错误的。在 `eval/runner/score.ts` 中，Precision@5 按每个查询计算如下：

```ts
const topK = ranked.slice(0, k).map((r) => r.sessionId);
const gold = new Set(q.goldSessionIds);
const hits = topK.filter((id) => gold.has(id)).length;
const precisionAtK = k > 0 ? hits / k : 0;
const recallAtK = gold.size === 0 ? 0 : hits / gold.size;
```

适配器得分是所有 15 个问题的算术平均值。

`coding-agent-life-v1` 数据集包含 12 个只有一个 gold session 的问题和 3 个有两个 gold session 的问题。因此，P@5 的最大可能值为：

```text
(12 × (1/5) + 3 × (2/5)) / 15 = 18/75 = 0.240
```

所以：
- `agentmemory-hybrid P@5=0.240, R@5=1.000` 表示每个 gold session 都在前 5 名中被检索到。
- `grep P@5=0.227, R@5=0.967` 对应于最多 18 次前 5 名命中中的 17 次成功命中；有一个含两个 gold session 的问题只返回了一个相关会话。其宏平均召回率为 `(14 + 0.5) / 15 = 0.9667`。

解决方法：使用当前公式重新计算或重新生成基准测试报告，并替换已发布的错误 P@5 值；在此指标定义下，该数据集上任何高于 `0.240` 的得分都是不可能的。

agentmemory

项目简介

README 预览

常见问题 (5)

同类型项目

browser-use

puppeteer

manim

PaddleOCR