# https://github.com/joshuaswarren/remnic 项目说明书

生成时间：2026-06-26 19:42:37 UTC

## 目录

- [项目概览](#page-overview)
- [Lib 模块](#page-dashboard-lib)
- [Src 模块](#page-src)
- [Src 模块](#page-packages-bench-ui-src)
- [Src 模块](#page-packages-plugin-openclaw-src)

<a id='page-overview'></a>

## 项目概览

### 相关页面

相关主题：[Lib 模块](#page-dashboard-lib)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/plugin-openclaw/src/public-artifacts.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/plugin-openclaw/src/public-artifacts.ts)
- [packages/remnic-core/src/access-mcp.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/access-mcp.ts)
- [packages/remnic-core/src/access-service.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/access-service.ts)
- [packages/remnic-core/src/boxes.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/boxes.ts)
- [packages/remnic-core/src/shared-context/manager.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/shared-context/manager.ts)
- [packages/remnic-core/src/memory-extension/codex-publisher.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/memory-extension/codex-publisher.ts)
- [packages/remnic-core/src/connectors/live/github.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/connectors/live/github.ts)
- [packages/remnic-core/src/wearables/day-store.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/wearables/day-store.ts)
- [packages/remnic-core/src/native-knowledge.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/native-knowledge.ts)
- [packages/bench/src/registry.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/bench/src/registry.ts)
- [package.json](https://github.com/joshuaswarren/remnic/blob/main/package.json)
</details>

# 项目概览

## 项目定位

remnic 是一个面向 AI 代理（agent）的记忆与上下文管理框架，目标是在多种宿主（host）环境之间提供可移植、可检索、可治理的记忆层。最新发布版本为 v9.3.644（截至社区记录），仓库采用 monorepo 结构，通过多个子包分别承载核心能力与平台集成。资料来源：[package.json]()

项目的核心抽象是「以 Markdown + YAML 形式持久化的记忆文件」。在 `memory-extension/shared-instructions.ts` 中明确将记忆划分为 `fact`、`preference`、`decision`、`entity`、`skill`、`correction`、`question`、`observation`、`summary` 等类型，并规定通过 front-matter 的 `type` 字段决定其语义角色。资料来源：[packages/remnic-core/src/memory-extension/shared-instructions.ts]()

## 整体架构

remnic 由「核心包 + 平台插件 + 评测体系」三层组成。核心包 `@remnic/core` 提供存储、检索、共享上下文、可穿戴设备桥接、连接器（GitHub 等）等基础能力；上层通过 `plugin-openclaw`、`plugin-pi`、`memory-extension/codex-publisher` 等模块把同一份记忆层桥接到不同的宿主代理中；`@remnic/bench` 则为上述能力提供基准测试覆盖。资料来源：[packages/remnic-core/src/memory-extension/codex-publisher.ts]()、[packages/plugin-openclaw/src/public-artifacts.ts]()、[packages/bench/src/registry.ts]()

```mermaid
flowchart LR
  Hosts[宿主代理: OpenClaw / Pi / Codex]
  Ext[memory-extension publisher]
  Core[remnic-core]
  Stores[(facts/ entities/ skills/<br/>corrections/ observations/)]
  Wear[wearables/]
  Conn[connectors: GitHub]
  MCP[access-mcp tools]
  Bench[bench registry]
  Hosts --> Ext
  Ext --> Core
  Core --> Stores
  Core --> Wear
  Core --> Conn
  Core --> MCP
  Core --> Bench
```

## 主要功能模块

### 记忆存储与共享上下文

`remnic-core` 的 `storage.ts` 负责把 `EntityFile` 等结构化数据序列化为带 front-matter 的 Markdown，并保留与旧版 `summary` / `facts` 字段的解析兼容性。资料来源：[packages/remnic-core/src/storage.ts]()。`shared-context/manager.ts` 则承担多代理间的「交叉信号」汇总：分析多个 agent 的产出与反馈后产出 `Cross-Signals` 报告，并支持语义增强器（semantic enhancer）的失败开放（fail-open）降级。资料来源：[packages/remnic-core/src/shared-context/manager.ts]()

### 检索与召回路由

核心检索能力由若干互补模块组成：`explicit-cue-recall.ts` 基于显式关键词构建引用片段；`event-order-recall.ts` 维护按时间顺序的实体/事件索引；`response-guidance-recall.ts` 通过意图正则（如 `diy_shelf_summary`、`calculus_derivative_walkthrough` 等）匹配专项召回策略。MCP 层 `access-mcp.ts` 将这些召回能力以 `engram.recall`、`engram.recall_explain` 等工具形式暴露给宿主代理。资料来源：[packages/remnic-core/src/explicit-cue-recall.ts]()、[packages/remnic-core/src/event-order-recall.ts]()、[packages/remnic-core/src/response-guidance-recall.ts]()、[packages/remnic-core/src/access-mcp.ts]()

### Memory Boxes 与 Trace Weaver

`boxes.ts` 引入 REMem 风格的「记忆盒」与「Trace Weaver」机制：每当新记忆落入 open box 时记录目标与使用工具，当话题漂移（topic_shift）、时间间隔超过 `boxTimeGapMs` 或累积达到 `boxMaxMemories` 时触发 `SealReason` 封盒；同时通过 `TraceIndex` 在 `traceWeaverLookbackDays` 窗口内反向关联 trace。资料来源：[packages/remnic-core/src/boxes.ts]()

### 平台桥接与公共产物

`plugin-openclaw/src/public-artifacts.ts` 实现了「memory-wiki bridge mode」：仅枚举 `facts/`、`entities/`、`corrections/`、`artifacts/` 与 `profile.md` 等安全目录作为公共产物；显式排除 `state/`、`questions/`、`transcripts/`、`archive/`、`buffers/`、`tokens/` 等私有运行时状态，并在扫描时通过 `realpath` 阻断 symlink 越界以及「白名单目录被符号链接重定向到私有目录」的攻击面。资料来源：[packages/plugin-openclaw/src/public-artifacts.ts]()

### 可穿戴设备与外部连接器

`wearables/day-store.ts` 将每日对话转写为 `<memoryDir>/wearables/<source>/<YYYY-MM-DD>.md`，刻意放在记忆扫描根之外但位于 QMD 集合根之内，兼顾「不进入召回但仍可全文检索」的需求。资料来源：[packages/remnic-core/src/wearables/day-store.ts]()。`connectors/live/github.ts` 则把 issue 评论、discussion 等转换为 `ConnectorDocument`，并通过 `advancePageUrl` 处理 GitHub 1-based 的分页推进。资料来源：[packages/remnic-core/src/connectors/live/github.ts]()

## 近期社区关注点

社区近期的修复集中在四个方向：1) 记忆刷新与 LCM 摘要路由——修复了 `FallbackLlmClient` 在 OAuth 鉴权下拒绝 `openai` 等 provider 的问题（issue #1478）以及 LCM 摘要绕过 `taskModelChain` 回退到 gateway 默认模型链的问题（issue #1473）；2) 平台集成——修复 Windows 下 QMD 探测因 `spawn` 缺少 `shell:true` 全部失败的问题（issue #1476）以及 Pi 插件中 post-await 访问陈旧 `ctx` 导致的扩展崩溃（issue #1481）；3) 召回顺序——为兼容 DeepSeek V4 Flash 等前缀缓存，`plugin-pi` 的 `context` hook 改为 append 而非 prepend 注入召回内容（issue #1479）；4) 定时任务——`engram-day-summary` cron 增加了模型配置 reconcile（issue #1474）以及可配置时区（issue #1475）。资料来源：[community context issues #1473/#1474/#1475/#1476/#1478/#1479/#1481]()

## See Also

- 记忆类型与共享指令：[packages/remnic-core/src/memory-extension/shared-instructions.ts]()
- 公共产物白名单：[packages/plugin-openclaw/src/public-artifacts.ts]()
- MCP 工具接口：[packages/remnic-core/src/access-mcp.ts]()
- 基准测试注册表：[packages/bench/src/registry.ts]()

---

<a id='page-dashboard-lib'></a>

## Lib 模块

### 相关页面

相关主题：[项目概览](#page-overview), [Src 模块](#page-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/remnic-core/src/types.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/types.ts)
- [packages/remnic-core/src/storage.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/storage.ts)
- [packages/remnic-core/src/boxes.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/boxes.ts)
- [packages/remnic-core/src/explicit-cue-recall.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/explicit-cue-recall.ts)
- [packages/remnic-core/src/event-order-recall.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/event-order-recall.ts)
- [packages/remnic-core/src/response-guidance-recall.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/response-guidance-recall.ts)
- [packages/remnic-core/src/native-knowledge.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/native-knowledge.ts)
- [packages/remnic-core/src/access-mcp.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/access-mcp.ts)
- [packages/remnic-core/src/connectors/live/github.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/connectors/live/github.ts)
- [packages/remnic-core/src/shared-context/manager.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/shared-context/manager.ts)
- [packages/remnic-core/src/wearables/day-store.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/wearables/day-store.ts)
- [packages/remnic-core/src/taxonomy/resolver-doc-generator.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/taxonomy/resolver-doc-generator.ts)
- [packages/remnic-core/src/memory-extension/codex-publisher.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/memory-extension/codex-publisher.ts)
- [packages/plugin-openclaw/src/public-artifacts.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/plugin-openclaw/src/public-artifacts.ts)
</details>

# Lib 模块

## 1. 模块定位与总体架构

Remnic 项目是一个面向 AI Agent 的"记忆层"中间件。其代码主体位于 `packages/remnic-core/src/`（核心库）以及若干配套包（CLI、bench、plugin-*）之中。这里所称的 **Lib 模块** 泛指 `remnic-core` 包中那些以库函数形式对外提供能力、不直接绑定到某个 CLI 命令或 HTTP 路由的纯逻辑层模块：包括类型定义、存储序列化、多种召回（recall）策略、知识图谱、MCP 接入面、外部连接器、共享上下文协调以及可穿戴设备/记忆盒/分类法等子系统。它们被上层 plugin、CLI、dashboard 复用，共同支撑"事实提取 → 存储 → 检索 → 上下文注入"的主链路。

资料来源：[packages/remnic-core/src/types.ts:1-60]()
资料来源：[packages/remnic-core/src/storage.ts:1-40]()

```mermaid
flowchart LR
  A[Agent / Plugin] --> B[access-mcp.ts<br/>MCP 工具入口]
  A --> C[recall 策略<br/>explicit-cue / event-order / response-guidance]
  C --> D[storage.ts<br/>实体/事实序列化]
  C --> E[native-knowledge.ts<br/>Obsidian / 工作区]
  B --> F[connectors/live/github.ts]
  B --> G[plugin-openclaw public-artifacts]
  D --> H[(磁盘记忆库)]
  E --> H
  F --> I[(外部服务)]
  G --> J[(OpenClaw workspace)]
  C -.cross signals.-> K[shared-context/manager.ts]
  L[wearables/day-store.ts] --> H
  M[taxonomy/resolver-doc-generator.ts] --> H
  N[memory-extension/codex-publisher.ts] --> O[Codex 扩展]
```

## 2. 核心数据模型与配置

`types.ts` 集中维护了整个 Remnic 的运行时配置结构（`PluginConfig`）。它覆盖了从摘要重要性阈值、主题抽取、transcript 留存策略、检查点（checkpoint）、压缩重置（compaction reset）、到 OpenClaw 工具/命令开关等近百项开关。配置项按"功能子系统"分组（`summarization*`、`transcript*`、`checkpoint*`、`openclaw*`、`recall*` 等），并通过 `activeRecallAgents`、`respectBundledActiveMemoryToggle` 等布尔项控制是否真正启用。

关键设计点：
- **细粒度开关**：每个子系统都有独立的 enable flag 与若干调节参数（如 `summarizationImportanceThreshold`、`topicExtractionTopN`），便于在不动代码的前提下微调行为。
- **保留兼容字段**：`transcriptSkipChannelTypes` 等数组字段允许在保留 transcript 功能的同时排除某些 channel（如 `cron`）。
- **运行时生效**：这些字段在 plugin 启动时被读取并物化为内存中的行为参数，运行时修改需要重启或显式 reconcile（参见 [issue #1474](https://github.com/joshuaswarren/remnic/issues/1474) 中关于 day-summary cron 启动时未 reconcile 的讨论）。

资料来源：[packages/remnic-core/src/types.ts:1-60]()

## 3. 存储与序列化

`storage.ts` 提供实体（EntityFile）的 markdown 序列化/反序列化能力。其核心思想是"compiled-truth + timeline"：在写出时根据 `entitySchemas` 对 `structuredSections` 排序、对 `facts` 做归一化，并通过 digest 字段记录最近一次合成的内容指纹，从而在保留旧版 `summary`/`facts` 字段可解析性的同时支持增量更新。

`boxes.ts` 实现"记忆盒（Memory Box）"机制——一组与某个高层任务目标（`goal`）、所用工具（`toolsUsed`）和结局（`outcome`）绑定的内存条目集合，并维护 `TraceIndex` 用于跨盒的回溯关联。盒的封口（seal）可由主题切换、时间间隔、容量上限或外部 flush 触发。

资料来源：[packages/remnic-core/src/storage.ts:1-80]()
资料来源：[packages/remnic-core/src/boxes.ts:1-60]()

## 4. 召回（Recall）策略族

Lib 模块将召回拆成多个相互独立、可组合的策略：

| 模块 | 策略 |
|---|---|
| `explicit-cue-recall.ts` | 基于查询中显式线索词与停用词集合进行证据项检索 |
| `event-order-recall.ts` | 通过正则词典匹配事件时序意图，抑制不相关模式（如 therapy、collaboration） |
| `response-guidance-recall.ts` | 通过多组正则联合判别用户意图（数学导数、DIY 工程、户外运动等） |
| `native-knowledge.ts` | 将 Obsidian 笔记、OpenClaw 工作区同步状态按"块（chunk）"切片并建立别名/反向链接索引 |

这些策略并非互斥调用，而是按阶段拼接：先做 cue 检索得到证据项，再由 event-order 与 response-guidance 决定是否抑制或重排序，最后由 native-knowledge 提供底层语料。`access-mcp.ts` 暴露的工具（`engram.recall`、`engram.recall_explain`、`engram.set_coding_context` 等）即建立在这些策略之上，并支持按 `cwd`/`projectTag` 解析项目命名空间、按 `asOf` 做历史时间锁存、按 `tags` 做记忆过滤。

资料来源：[packages/remnic-core/src/explicit-cue-recall.ts:1-60]()
资料来源：[packages/remnic-core/src/event-order-recall.ts:1-40]()
资料来源：[packages/remnic-core/src/response-guidance-recall.ts:1-50]()
资料来源：[packages/remnic-core/src/access-mcp.ts:1-60]()
资料来源：[packages/remnic-core/src/native-knowledge.ts:1-60]()

## 5. 外部连接与共享上下文

- **GitHub 连接器**（`connectors/live/github.ts`）：把 discussions/comments 转成统一的 `ConnectorDocument`，并在分页失败时通过 `advancePageUrl` 安全地递增 `page` 参数（解析失败直接返回空串避免死循环）。
- **OpenClaw 公共产物**（`plugin-openclaw/src/public-artifacts.ts`）：枚举记忆目录中可对外暴露的"白名单"子目录（`facts/`、`entities/`、`corrections/`、`artifacts/`、`profile.md`），显式排除 `state/`、`questions/`、`transcripts/`、`archive/`、`buffers`、`tokens/` 等私有路径；并通过 `realpath` 校验防止符号链接逃逸到非白名单目录。
- **共享上下文管理器**（`shared-context/manager.ts`）：每日生成 Cross-Signals 报告，统计源输出、反馈条目、approved/rejected 决策、可选的语义增强器（semantic enhancer）状态，并写出 JSON + Markdown 两种产物。
- **可穿戴设备日存储**（`wearables/day-store.ts`）：把单源单日 transcript 写到 `<memoryDir>/wearables/<source>/<YYYY-MM-DD>.md`，刻意放在记忆扫描根目录之外（避免被当记忆召回），同时落在 QMD 收集根目录之内（保证全文检索可用），并用正文哈希做幂等。
- **Codex 记忆扩展发布器**（`memory-extension/codex-publisher.ts`）：渲染 `instructions.md`、原子写入（temp + rename），并在 Phase-2 沙箱中强制只读文件系统访问。
- **分类法决策树生成器**（`taxonomy/resolver-doc-generator.ts`）：根据 `Taxonomy.categories` 的优先级顺序生成 `RESOLVER.md`，引导用户把新知识分门别类归档。

资料来源：[packages/remnic-core/src/connectors/live/github.ts:1-50]()
资料来源：[packages/plugin-openclaw/src/public-artifacts.ts:1-80]()
资料来源：[packages/remnic-core/src/shared-context/manager.ts:1-60]()
资料来源：[packages/remnic-core/src/wearables/day-store.ts:1-40]()
资料来源：[packages/remnic-core/src/memory-extension/codex-publisher.ts:1-60]()
资料来源：[packages/remnic-core/src/taxonomy/resolver-doc-generator.ts:1-40]()

## 6. 常见失败模式与近期修复

围绕 Lib 模块，社区曾报告并已修复（含 [v9.3.639 – v9.3.644](https://github.com/joshuaswarren/remnic/releases)）：
- **LCM 摘要绕过 taskModelChain**（[#1473](https://github.com/joshuaswarren/remnic/issues/1473)）：`_fastGatewayLlm` 走 `FallbackLlmClient` 时未应用 `taskModelChain`，已在 [#1482](https://github.com/joshuaswarren/remnic/pull/1482) 中修正，让 LCM 路由经过插件级任务模型链。
- **OAuth-only provider 被拒绝**（[#1478](https://github.com/joshuaswarren/remnic/issues/1478)）：运行时未解析 OAuth 凭据即拒绝 `openai/gpt-5.4` 等模型；同期合并 [#1482](https://github.com/joshuaswarren/remnic/pull/1482)。
- **Day summary cron 启动未 reconcile**（[#1474](https://github.com/joshuaswarren/remnic/issues/1474)）：与 hourly summary cron 不一致，已通过 [#1482](https://github.com/joshuaswarren/remnic/pull/1482) 补齐。
- **flush-plan 幻觉路径**（[#1483](https://github.com/joshuaswarren/remnic/issues/1483)）：v9.3.641 修复生命周期处理、v9.3.640 收紧 prompt 约束。
- **Pi 插件 stale ctx**（[#1481](https://github.com/joshuaswarren/remnic/issues/1481)）：v9.3.640 (#1485) 强化上下文处理并改为 append recall，对 prefix-cached provider（如 DeepSeek）友好（[#1479](https://github.com/joshuaswarren/remnic/issues/1479)）。
- **Windows QMD probe 失败**（[#1476](https://github.com/joshuaswarren/remnic/issues/1476)）：`launchProcess()` 缺 `shell:true`，v9.3.640 (#1486) 已修复。
- **Day summary 时区硬编码**（[#1475](https://github.com/joshuaswarren/remnic/issues/1475)）：目前仍跟随服务器 `Intl.DateTimeFormat().resolvedOptions().timeZone`，未配置化。

## 7. See Also

- [Plugin 模块（plugin-openclaw、plugin-pi）](#)
- [Bench 模块（packages/bench/src/registry.ts）](#)
- [CLI 模块（packages/remnic-cli）](#)
- [共享上下文子系统](#)

---

<a id='page-src'></a>

## Src 模块

### 相关页面

相关主题：[Lib 模块](#page-dashboard-lib), [Src 模块](#page-packages-bench-ui-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/plugin-openclaw/src/public-artifacts.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/plugin-openclaw/src/public-artifacts.ts)
- [packages/remnic-core/src/explicit-cue-recall.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/explicit-cue-recall.ts)
- [packages/remnic-core/src/access-mcp.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/access-mcp.ts)
- [packages/remnic-core/src/native-knowledge.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/native-knowledge.ts)
- [packages/remnic-core/src/connectors/live/github.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/connectors/live/github.ts)
- [packages/remnic-core/src/storage.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/storage.ts)
- [packages/remnic-core/src/boxes.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/boxes.ts)
- [packages/remnic-core/src/types.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/types.ts)
- [packages/remnic-core/src/access-service.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/access-service.ts)
- [packages/remnic-core/src/shared-context/manager.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/shared-context/manager.ts)
- [packages/remnic-core/src/memory-extension/codex-publisher.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/memory-extension/codex-publisher.ts)
- [packages/remnic-core/src/memory-extension/shared-instructions.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/memory-extension/shared-instructions.ts)
- [packages/remnic-core/src/taxonomy/resolver-doc-generator.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/taxonomy/resolver-doc-generator.ts)
- [packages/remnic-core/src/event-order-recall.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/event-order-recall.ts)
- [packages/remnic-core/src/response-guidance-recall.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/response-guidance-recall.ts)
- [packages/remnic-cli/src/bench-args.test.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-cli/src/bench-args.test.ts)
- [packages/bench/src/registry.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/bench/src/registry.ts)
</details>

# Src 模块

## 概述与项目定位

`remnic` 是一个面向 AI 编程代理（agent）的分层记忆与上下文管理系统，其源码以 monorepo 形式组织在 `packages/` 目录下。核心代码位于 `packages/remnic-core/src/`，由多个职责单一、互相协作的子系统组成，分别负责记忆存取、检索、连接器集成、共享上下文与扩展发布等能力。

在 `packages/remnic-core/src/types.ts` 中定义了贯穿整个系统的配置与状态类型（如 `compactionResetEnabled`、`flushOnResetEnabled`、`sessionTogglesEnabled`、`activeRecallEnabled` 等），为各子系统提供统一的配置契约。资料来源：[packages/remnic-core/src/types.ts]()

社区近期讨论集中在若干热点：记忆刷新（flush plan）路径校验、LCM（无损上下文管理）模型路由、Windows 下的 QMD 启动、Pi 插件的会话上下文处理以及每日摘要 cron 任务的协调机制。这些问题均可在 `packages/remnic-core/src/` 与 `packages/plugin-openclaw/src/` 等源码中定位到对应实现。

## 核心子系统划分

`remnic-core/src` 按照职责划分为以下主要子系统：

### 1. 记忆存取层（Memory Storage & Public Artifacts）

记忆以 Markdown + YAML frontmatter 形式持久化。实体文件（entity）的序列化由 `storage.ts` 中的 `serializeEntityFile()` 负责，使用 compiled-truth + timeline 格式并兼容旧的 `summary`/`facts` 字段。资料来源：[packages/remnic-core/src/storage.ts]()

为避免私有运行时数据被错误暴露为公共工件，`public-artifacts.ts` 显式枚举了仅允许暴露的目录（`facts/`、`entities/`、`corrections/`、`artifacts/`、`profile.md`），并阻止通过符号链接将 `state/` 等私有目录伪装为公共目录。资料来源：[packages/plugin-openclaw/src/public-artifacts.ts]()

### 2. 检索与上下文层（Recall & Context Assembly）

系统提供多种召回路径：

| 召回路径 | 关键文件 | 用途 |
|---|---|---|
| Explicit Cue Recall | `explicit-cue-recall.ts` | 基于显式提示词与停用词过滤的内容词项召回 |
| Event Order Recall | `event-order-recall.ts` | 通过领域关键词正则匹配识别事件顺序意图 |
| Response Guidance Recall | `response-guidance-recall.ts` | 推断数学、技术项目等响应指导意图 |
| Native Knowledge | `native-knowledge.ts` | 加载 Obsidian 笔记、OpenClaw 工作区同步等原生知识 |

资料来源：[packages/remnic-core/src/explicit-cue-recall.ts]()、[packages/remnic-core/src/event-order-recall.ts]()、[packages/remnic-core/src/response-guidance-recall.ts]()、[packages/remnic-core/src/native-knowledge.ts]()

### 3. 访问接口层（Access Layer）

通过 `access-mcp.ts`（Model Context Protocol 工具）、`access-service.ts`（核心访问服务接口）与 HTTP/CLI 接入对外暴露能力。`engram.recall`、`engram.observe`、`engram.set_coding_context` 等工具支持 `cwd`/`projectTag` 字段以路由到项目级命名空间，并区分 `_SCOPED`（真正解析命名空间）与 `_IGNORED`（仅为兼容 MCP 客户端自动注入而接受）。资料来源：[packages/remnic-core/src/access-mcp.ts]()、[packages/remnic-core/src/access-service.ts]()

### 4. 连接器与共享上下文（Connectors & Shared Context）

GitHub 连接器（`connectors/live/github.ts`）将评论与讨论转化为 `ConnectorDocument`，使用分页 URL 推进函数 `advancePageUrl()` 抓取完整线程。资料来源：[packages/remnic-core/src/connectors/live/github.ts]()

`shared-context/manager.ts` 协调跨信号（cross-signals）整合，生成每日共享上下文报告（含主题、风险、潜在晋升项）并以原子写入方式落盘。资料来源：[packages/remnic-core/src/shared-context/manager.ts]()

### 5. 记忆盒与轨迹编织（Memory Boxes & Trace Weaver）

`boxes.ts` 实现了 REMem 启发的"记忆盒"机制，用于按主题/时间窗口聚类记忆条目，并维护 `TraceIndex` 索引以支持跨会话的轨迹回溯。盒的关闭由 `topic_shift`、`time_gap`、`max_memories`、`forced`、`flush` 等 `SealReason` 触发。资料来源：[packages/remnic-core/src/boxes.ts]()

### 6. 记忆扩展与基准测试（Memory Extension & Bench）

`memory-extension/codex-publisher.ts` 将 Remnic 记忆扩展发布到目标环境（含沙箱规则），`shared-instructions.ts` 提供跨主机的可复用 Markdown 片段（如 `REMNIC_SEMANTIC_OVERVIEW`）。`bench/src/registry.ts` 集中注册各类基准（如 `enrichmentFidelity`、`entityConsolidation`、`codingRecall` 等），`remnic-cli/src/bench-args.test.ts` 则覆盖 CLI 参数解析测试。资料来源：[packages/remnic-core/src/memory-extension/codex-publisher.ts]()、[packages/remnic-core/src/memory-extension/shared-instructions.ts]()、[packages/bench/src/registry.ts]()、[packages/remnic-cli/src/bench-args.test.ts]()

## 模块协作流程

下图展示了从外部请求到记忆召回与持久化协作的关键路径：

```mermaid
flowchart LR
    A[MCP/HTTP/CLI 客户端] --> B[access-mcp/access-service]
    B --> C{engram.recall}
    C --> D[explicit-cue-recall]
    C --> E[native-knowledge]
    C --> F[connectors/github]
    D --> G[boxes 索引]
    E --> G
    G --> H[storage 序列化]
    H --> I[(Markdown + YAML)]
    J[Codex/Pi/OpenClaw 插件] --> K[public-artifacts 过滤]
    K --> L[记忆写入]
```

## 近期热点与源码映射

社区报告的问题大多可在源码中定位：

- **#1483 flush plan 路径幻觉**：`public-artifacts.ts` 通过 `PUBLIC_DIRS` 显式枚举合法目录并校验符号链接，是缓解该类问题的核心防线。资料来源：[packages/plugin-openclaw/src/public-artifacts.ts]()
- **#1473/#1478 LCM 路由与 OAuth 提供方**：通过 `access-mcp.ts` 中的 `taskModelChain` 与 `FallbackLlmClient` 解析路径修复。
- **#1476 Windows QMD 启动**：`launchProcess()` 在 Windows 路径下需要 `shell:true`；与 `connectors/live/` 中的子进程调用相关。
- **#1475/#1474 每日摘要 cron**：`shared-context/manager.ts` 中的 `curateDaily()` 协调每日报告生成，与 `ensureDaySummaryCron()` 的协调机制密切相关。

## See Also

- [Remnic 召回系统](召回系统.md)
- [OpenClaw 插件集成](OpenClaw插件.md)
- [记忆盒与轨迹编织](记忆盒.md)
- [MCP 工具接口](MCP接口.md)

---

<a id='page-packages-bench-ui-src'></a>

## Src 模块

### 相关页面

相关主题：[Src 模块](#page-src), [Src 模块](#page-packages-plugin-openclaw-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/plugin-openclaw/src/public-artifacts.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/plugin-openclaw/src/public-artifacts.ts)
- [packages/remnic-core/src/explicit-cue-recall.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/explicit-cue-recall.ts)
- [packages/remnic-core/src/access-mcp.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/access-mcp.ts)
- [packages/remnic-core/src/native-knowledge.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/native-knowledge.ts)
- [packages/remnic-core/src/connectors/live/github.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/connectors/live/github.ts)
- [packages/remnic-core/src/storage.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/storage.ts)
- [packages/remnic-core/src/boxes.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/boxes.ts)
- [packages/remnic-core/src/types.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/types.ts)
- [packages/remnic-core/src/access-service.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/access-service.ts)
- [packages/remnic-core/src/taxonomy/resolver-doc-generator.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/taxonomy/resolver-doc-generator.ts)
- [packages/remnic-core/src/shared-context/manager.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/shared-context/manager.ts)
- [packages/remnic-core/src/memory-extension/codex-publisher.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/memory-extension/codex-publisher.ts)
- [packages/remnic-core/src/memory-extension/shared-instructions.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/memory-extension/shared-instructions.ts)
- [packages/remnic-core/src/event-order-recall.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/event-order-recall.ts)
- [packages/remnic-core/src/response-guidance-recall.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/response-guidance-recall.ts)
- [packages/remnic-cli/src/bench-args.test.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-cli/src/bench-args.test.ts)
- [packages/bench/src/registry.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/bench/src/registry.ts)

</details>

# Src 模块

## 模块定位与职责

Remnic 仓库的 `src/` 目录承载了整个记忆引擎的核心实现，按照多包 monorepo 组织成三层：基础设施层 (`remnic-core`)、主机插件层 (`plugin-openclaw`、`plugin-pi` 等) 以及基准测试与 CLI 层 (`bench`、`remnic-cli`)。`src` 模块并不是单一入口文件，而是一组按子系统拆分的 TypeScript 源文件集合，涵盖了从记忆摄取、检索、回放到外部主机集成的全部逻辑。

`remnic-core/src/types.ts` 中的 `PluginConfig` 类型集中描述了所有可调旋钮（如 `memoryBoxesEnabled`、`topicExtractionEnabled`、`transcriptEnabled`、`compactionResetEnabled` 等），是理解 `src` 模块配置面的入口。 资料来源：[packages/remnic-core/src/types.ts:1-100]()

`src` 模块的对外契约主要由两个面构成：(1) 通过 `access-mcp.ts` 暴露的 MCP 工具集（`engram.recall`、`engram.observe`、`engram.briefing` 等），供主机代理以 JSON-RPC 方式调用；(2) 通过 `plugin-openclaw/src/public-artifacts.ts` 暴露的"公共制品"枚举，用于将记忆内容桥接到外部 wiki 系统。 资料来源：[packages/remnic-core/src/access-mcp.ts:1-60](), [packages/plugin-openclaw/src/public-artifacts.ts:1-40]()

## 核心子系统

### 记忆存储与序列化

`storage.ts` 实现了实体文件的双向编解码：解析阶段将 Markdown 文件拆分为 `synthesis`、`timeline`、`structuredSections`、`relationships`、`activity`、`aliases` 等字段；序列化阶段重新编译为兼容旧版 `summary` 与 `facts` 字段的格式。 资料来源：[packages/remnic-core/src/storage.ts:1-80]()

`native-knowledge.ts` 负责将外部知识库（如 Obsidian Vault）按标题感知的切片方式（`chunkHeadingAware`）转换为 `NativeKnowledgeChunk`，每个块携带 `vaultId`、`notePath`、`namespace`、`privacyClass` 等元数据，以便后续检索时复用。 资料来源：[packages/remnic-core/src/native-knowledge.ts:1-60]()

### 检索与回放

`explicit-cue-recall.ts` 实现了基于显式线索词的回放逻辑：维护停用词表（`CONTENT_LEXICAL_CUE_STOPWORDS`）与"内容词"短语停用词表（`CONTENT_LEXICAL_PHRASE_STOPWORDS`），并依据 `maxChars`、`maxReferences` 等参数从查询中提取证据项。 资料来源：[packages/remnic-core/src/explicit-cue-recall.ts:1-80]()

`event-order-recall.ts` 与 `response-guidance-recall.ts` 提供事件顺序与意图感知的回放能力。前者通过正则匹配识别会议、协作、治疗等场景短语；后者基于关键词组合推断"技术项目总结""圆锥曲线总结""微积分求导"等意图，进而指导 LLM 的回应风格。 资料来源：[packages/remnic-core/src/event-order-recall.ts:1-60](), [packages/remnic-core/src/response-guidance-recall.ts:1-40]()

`boxes.ts` 引入了"记忆盒（Memory Boxes）"抽象，对应 REMem 风格的情景记忆单元：一个盒子聚合一段连续话题下的多条记忆，包含 `topics`、`memoryIds`、`goal`、`toolsUsed`、`outcome` 等字段，并由 `boxTopicShiftThreshold`、`boxTimeGapMs`、`boxMaxMemories` 三个参数控制封盒（seal）时机。 资料来源：[packages/remnic-core/src/boxes.ts:1-60]()

### 外部连接器与 MCP

`connectors/live/github.ts` 把 GitHub 的 issue、PR 评论、discussion 转写为统一的 `ConnectorDocument`，使用 `${repo}/${kind}/${comment.id}` 作为外部 ID，并通过 `advancePageUrl()` 在分页边界推进页码。 资料来源：[packages/remnic-core/src/connectors/live/github.ts:1-60]()

`access-mcp.ts` 将所有记忆操作以 JSON Schema 的形式声明为 MCP 工具，并按"作用域写入"与"兼容接受"两类复用同一组 `cwd` / `projectTag` 字段定义（`MCP_GIT_CONTEXT_SCHEMA_PROPS_SCOPED` 与 `_IGNORED`），避免多工具之间的描述漂移。 资料来源：[packages/remnic-core/src/access-mcp.ts:60-120]()

`plugin-openclaw/src/public-artifacts.ts` 仅枚举白名单目录（`facts/`、`entities/`、`corrections/`、`artifacts/`、`profile.md`）作为可公开暴露的制品，并通过 `realpath()` 校验避免符号链接穿越到 `state/`、`questions/`、`transcripts/`、`tokens/` 等私有路径。 资料来源：[packages/plugin-openclaw/src/public-artifacts.ts:40-80]()

### 共享上下文与扩展指令

`shared-context/manager.ts` 中的 `generateCrossSignals()` 输出每日跨信号报告，包含来源数量、反馈决策统计、语义增强器状态（启用/超时/失败开放）等元数据。 资料来源：[packages/remnic-core/src/shared-context/manager.ts:1-60]()

`memory-extension/codex-publisher.ts` 与 `shared-instructions.ts` 共同构成"主机扩展指令"管线：前者将 `REMINIC_SEMANTIC_OVERVIEW`、`REMINIC_MCP_TOOL_INVENTORY`、`REMINIC_RECALL_DECISION_RULES` 等共享片段拼装到 `instructions.md`，并通过原子写入（temp + rename）落地到主机扩展根目录。 资料来源：[packages/remnic-core/src/memory-extension/codex-publisher.ts:1-60](), [packages/remnic-core/src/memory-extension/shared-instructions.ts:1-60]()

## 数据流与架构

```mermaid
flowchart LR
  Host[主机代理<br/>OpenClaw / Pi / Codex] -->|MCP JSON-RPC| MCP[access-mcp.ts]
  MCP --> Recall[回放引擎<br/>explicit-cue-recall / event-order-recall]
  Recall --> Core[remnic-core 存储<br/>storage.ts + boxes.ts]
  Core -->|公共制品枚举| Wiki[外部 Wiki<br/>public-artifacts.ts]
  Connectors[外部连接器<br/>GitHub / Obsidian] -->|ConnectorDocument| Core
  Extension[主机扩展<br/>codex-publisher.ts] -->|instructions.md| Host
```

## 配置与故障模式

`types.ts` 中的字段（如 `transcriptEnabled`、`summarizationImportanceThreshold`、`topicExtractionEnabled`）通常对应功能开关，关闭后相关模块会被跳过——这是排查"功能不起作用"问题的第一站。 资料来源：[packages/remnic-core/src/types.ts:1-100]()

社区近期讨论的几个故障与 `src` 模块直接相关：

- **#1483 flush-plan 路径幻觉**：模型在记忆触发的压缩刷新中会尝试写入 `memory-candidates/` 等不存在的路径，导致 `flush-plan.md` 无限膨胀。修复由 v9.3.641 (#1487) 完成，属于 `src` 模块中提示约束逻辑的调整。
- **#1473 / #1478 LCM 与 OAuth 路由**：`FallbackLlmClient` 在 `modelSource: "gateway"` 下忽略 OAuth-only 提供商，LCM summarizer 也绕过 `taskModelChain`。修复在 v9.3.639 (#1482) 合并，影响 `src` 模块中模型路由相关文件。
- **#1481 / #1479 plugin-pi 上下文过期**：在事件与命令处理器中，`await` 之后访问 `ctx` 会触发"stale ctx"错误；同时回放内容以 prepend 方式注入，破坏 DeepSeek V4 Flash 等前缀缓存。修复在 v9.3.640 (#1485)。
- **#1476 Windows QMD 探测**：`launchProcess()` 缺少 `shell:true` 导致所有 qmd 启动形式失败，修复在 v9.3.640 (#1486)。

## 参见

- [remnic-core 类型定义](types.md)
- [MCP 工具契约](access-mcp.md)
- [公共制品与 Wiki 桥接](public-artifacts.md)
- [Release Notes v9.3.637 – v9.3.644](release-notes.md)

---

<a id='page-packages-plugin-openclaw-src'></a>

## Src 模块

### 相关页面

相关主题：[Src 模块](#page-packages-bench-ui-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [packages/plugin-openclaw/src/public-artifacts.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/plugin-openclaw/src/public-artifacts.ts)
- [packages/remnic-core/src/access-mcp.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/access-mcp.ts)
- [packages/remnic-core/src/native-knowledge.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/native-knowledge.ts)
- [packages/remnic-core/src/connectors/live/github.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/connectors/live/github.ts)
- [packages/remnic-core/src/storage.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/storage.ts)
- [packages/remnic-core/src/boxes.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/boxes.ts)
- [packages/remnic-core/src/taxonomy/resolver-doc-generator.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/taxonomy/resolver-doc-generator.ts)
- [packages/remnic-core/src/shared-context/manager.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/shared-context/manager.ts)
- [packages/remnic-core/src/memory-extension/codex-publisher.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/memory-extension/codex-publisher.ts)
- [packages/remnic-core/src/memory-extension/shared-instructions.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/memory-extension/shared-instructions.ts)
- [packages/remnic-cli/src/bench-args.test.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-cli/src/bench-args.test.ts)
- [packages/bench/src/registry.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/bench/src/registry.ts)
</details>

# Src 模块

## 一、定位与总体结构

Remnic 项目的源码采用 monorepo 形式组织，按照职责划分为多个独立包，每个包下都包含 `src/` 目录承载核心实现：

| 包名 | 角色 | 典型内容 |
|------|------|---------|
| `@remnic/core` (`packages/remnic-core/src`) | 记忆引擎、检索、存储、连接器与外部暴露 | 包含 `access-mcp.ts`、`boxes.ts`、`storage.ts` 等 |
| `@remnic/plugin-openclaw` (`packages/plugin-openclaw/src`) | OpenClaw 宿主桥接与公开制品导出 | 包含 `public-artifacts.ts` 等 |
| `@remnic/cli` (`packages/remnic-cli/src`) | 命令行入口与参数解析 | 包含 `bench-args.test.ts` 等 |
| `@remnic/bench` (`packages/bench/src`) | 基准测试注册表与运行器 | 包含 `registry.ts` 等 |

`@remnic/core` 是整个系统的事实来源，承载记忆的分块、检索、序列化、分类解析与外部连接器；上层包（plugin、cli、bench）只负责与宿主协议交互、调度入口或注册基准。资料来源：[packages/remnic-core/src/storage.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/storage.ts)、[packages/bench/src/registry.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/bench/src/registry.ts)

## 二、`@remnic/core` 内部子模块

`@remnic/core` 的 `src/` 进一步按功能切分：

- **检索与提示装配**：`explicit-cue-recall.ts`、`response-guidance-recall.ts`、`event-order-recall.ts` 负责把召回片段拼装成可注入提示，匹配不同用户意图（教学性总结、技术项目摘要、计算导数演练等）。资料来源：[packages/remnic-core/src/explicit-cue-recall.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/explicit-cue-recall.ts)、[packages/remnic-core/src/response-guidance-recall.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/response-guidance-recall.ts)
- **存储与序列化**：`storage.ts` 提供实体文件（`EntityFile`）的解析与回写，保留前向兼容旧版 `summary` / `facts` 字段。资料来源：[packages/remnic-core/src/storage.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/storage.ts)
- **原生知识整合**：`native-knowledge.ts` 处理 Obsidian 金库、OpenClaw 工作区同步等外部来源的分块、命名空间归属与隐私分级。资料来源：[packages/remnic-core/src/native-knowledge.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/native-knowledge.ts)
- **连接器**：`connectors/live/github.ts` 等负责拉取外部评论/讨论等文档对象并构造成 `ConnectorDocument`。资料来源：[packages/remnic-core/src/connectors/live/github.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/connectors/live/github.ts)
- **MCP 暴露**：`access-mcp.ts` 把记忆能力封装成 `engram.*` MCP 工具，附带 Git 上下文（`cwd`、`projectTag`）的标准化字段。资料来源：[packages/remnic-core/src/access-mcp.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/access-mcp.ts)
- **记忆盒与追踪编织**：`boxes.ts` 实现 REMem 风格的“记忆盒（memory box）”抽象，记录同一议题下的工具、目标与结局，并支持基于主题漂移或时间间隔的封口策略。资料来源：[packages/remnic-core/src/boxes.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/boxes.ts)
- **分类法与共享上下文**：`taxonomy/resolver-doc-generator.ts` 根据分类法生成 markdown 决策树文档；`shared-context/manager.ts` 跨会话汇总“跨信号（Cross-Signals）”日报。资料来源：[packages/remnic-core/src/taxonomy/resolver-doc-generator.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/taxonomy/resolver-doc-generator.ts)、[packages/remnic-core/src/shared-context/manager.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/shared-context/manager.ts)
- **宿主指令发布**：`memory-extension/codex-publisher.ts` 与 `shared-instructions.ts` 生成面向 Codex 等宿主代理的 `instructions.md`，集中声明沙箱规则、记忆类型与引用格式。资料来源：[packages/remnic-core/src/memory-extension/codex-publisher.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/memory-extension/codex-publisher.ts)、[packages/remnic-core/src/memory-extension/shared-instructions.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/memory-extension/shared-instructions.ts)

## 三、上层桥接包

`@remnic/plugin-openclaw` 的 `src/public-artifacts.ts` 定义了允许对外暴露的“公开制品”白名单（`facts/`、`entities/`、`corrections/`、`artifacts/`、`profile.md`），并显式排除 `state/`、`questions/`、`transcripts/`、`archive/`、`buffers/`、`tokens/` 等私有运行时目录，实现“记忆 → Wiki”的安全桥接；同时通过 `realpath` 校验阻止符号链接越界。资料来源：[packages/plugin-openclaw/src/public-artifacts.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/plugin-openclaw/src/public-artifacts.ts)

`@remnic/cli` 的 `src/bench-args.test.ts` 等模块负责把 CLI 选项（如 `--internal-codex-reasoning-effort`、`--ama-bench-judge-protocol`）解析并校验，再交给基准执行器。资料来源：[packages/remnic-cli/src/bench-args.test.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-cli/src/bench-args.test.ts)

`@remnic/bench` 的 `src/registry.ts` 集中登记全部基准（如 `enrichmentFidelity`、`entityConsolidation`、`retrievalPersonalization`、`retrievalTemporal`、`codingRecall`、`ingestionEntityRecall` 等），CLI 通过此表驱动运行。资料来源：[packages/bench/src/registry.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/bench/src/registry.ts)

## 四、近期修复与社区关注点

围绕 `src/` 模块，社区近期修复了一系列会影响上层宿主与基准的根因问题：

- v9.3.637 修复网关任务默认值未走 `taskModelChain` 的问题，源自 `FallbackLlmClient`。
- v9.3.639（#1482）合并三处修复：解析 OAuth 唯一提供方、把 LCM 摘要器接入 `taskModelChain`、让日终汇总 cron 在插件启动时重新对齐模型配置（[#1474](https://github.com/joshuaswarren/remnic/issues/1474)、[#1473](https://github.com/joshuaswarren/remnic/issues/1473)、[#1478](https://github.com/joshuaswarren/remnic/issues/1478)）。
- v9.3.640 修复 Windows 下 `launchProcess()` 缺 `shell:true` 导致 QMD 探测全失败（[#1476](https://github.com/joshuaswarren/remnic/issues/1476)）、加固 Pi 插件上下文处理并把召回片段改为追加（[#1481](https://github.com/joshuaswarren/remnic/issues/1481)、[#1479](https://github.com/joshuaswarren/remnic/issues/1479)），以及收窄 OpenClaw flush-plan 提示以抑制幻觉路径（[#1483](https://github.com/joshuaswarren/remnic/issues/1483)）。
- v9.3.641 修复 OpenClaw flush-plan 生命周期处理（[#1487](https://github.com/joshuaswarren/remnic/pull/1487)）。
- v9.3.643 修复记忆检视器中可选未验证预览的处理（[#1489](https://github.com/joshuaswarren/remnic/pull/1489)）。
- 最新 v9.3.644（#1490）放宽 OpenClaw 主机版本校验，接受 2026.6.11 beta 主机。

另外，日终汇总 cron（`engram-day-summary`）的时区不可配置问题（[#1475](https://github.com/joshuaswarren/remnic/issues/1475)）仍处于待修复状态，建议运维在多时区场景下临时使用定时任务前置偏移。

## 五、See Also

- 访问协议与 MCP 工具：[access-mcp.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/access-mcp.ts)
- 记忆盒与追踪编织：[boxes.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/boxes.ts)
- 实体存储与序列化：[storage.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/remnic-core/src/storage.ts)
- 公开制品（Wiki 桥接）:[public-artifacts.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/plugin-openclaw/src/public-artifacts.ts)
- 基准注册表：[registry.ts](https://github.com/joshuaswarren/remnic/blob/main/packages/bench/src/registry.ts)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：joshuaswarren/remnic

摘要：发现 29 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 失败模式：security_permissions: FallbackLlmClient rejects OAuth-only providers (openai) before runtime auth resolution。

## 1. 安全/权限坑 · 失败模式：security_permissions: FallbackLlmClient rejects OAuth-only providers (openai) before runtime auth resolution

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: FallbackLlmClient rejects OAuth-only providers (openai) before runtime auth resolution
- 对用户的影响：Developers may expose sensitive permissions or credentials: FallbackLlmClient rejects OAuth-only providers (openai) before runtime auth resolution
- 证据：failure_mode_cluster:github_issue | https://github.com/joshuaswarren/remnic/issues/1478 | FallbackLlmClient rejects OAuth-only providers (openai) before runtime auth resolution

## 2. 安全/权限坑 · 失败模式：security_permissions: [Windows] QMD probe fails: launchProcess() uses bare spawn() without shell:true — all qmd lau...

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: [Windows] QMD probe fails: launchProcess() uses bare spawn() without shell:true — all qmd launch forms (sh/.cmd/JS) error
- 对用户的影响：Developers may expose sensitive permissions or credentials: [Windows] QMD probe fails: launchProcess() uses bare spawn() without shell:true — all qmd launch forms (sh/.cmd/JS) error
- 证据：failure_mode_cluster:github_issue | https://github.com/joshuaswarren/remnic/issues/1476 | [Windows] QMD probe fails: launchProcess() uses bare spawn() without shell:true — all qmd launch forms (sh/.cmd/JS) error

## 3. 安装坑 · 失败模式：installation: plugin-pi: stale ctx error after session replacement/reload (post-await ctx access in event +...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: plugin-pi: stale ctx error after session replacement/reload (post-await ctx access in event + command handlers)
- 对用户的影响：Developers may fail before the first successful local run: plugin-pi: stale ctx error after session replacement/reload (post-await ctx access in event + command handlers)
- 证据：failure_mode_cluster:github_issue | https://github.com/joshuaswarren/remnic/issues/1481 | plugin-pi: stale ctx error after session replacement/reload (post-await ctx access in event + command handlers)

## 4. 安装坑 · 来源证据：Day Summary cron job does not reconcile model config on plugin startup

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Day Summary cron job does not reconcile model config on plugin startup
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/joshuaswarren/remnic/issues/1474 | 来源类型 github_issue 暴露的待验证使用条件。

## 5. 安装坑 · 来源证据：[Windows] QMD probe fails: launchProcess() uses bare spawn() without shell:true — all qmd launch forms (sh/.cmd/JS) err…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Windows] QMD probe fails: launchProcess() uses bare spawn() without shell:true — all qmd launch forms (sh/.cmd/JS) error
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/joshuaswarren/remnic/issues/1476 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 6. 安装坑 · 来源证据：plugin-pi: stale ctx error after session replacement/reload (post-await ctx access in event + command handlers)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：plugin-pi: stale ctx error after session replacement/reload (post-await ctx access in event + command handlers)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/joshuaswarren/remnic/issues/1481 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 7. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/joshuaswarren/remnic | host_targets=mcp_host, openclaw, claude_code, claude, codex, chatgpt

## 8. 配置坑 · 失败模式：configuration: Day Summary cron job does not reconcile model config on plugin startup

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Day Summary cron job does not reconcile model config on plugin startup
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Day Summary cron job does not reconcile model config on plugin startup
- 证据：failure_mode_cluster:github_issue | https://github.com/joshuaswarren/remnic/issues/1474 | Day Summary cron job does not reconcile model config on plugin startup

## 9. 配置坑 · 失败模式：configuration: Day Summary cron timezone is not configurable (uses server timezone)

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Day Summary cron timezone is not configurable (uses server timezone)
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Day Summary cron timezone is not configurable (uses server timezone)
- 证据：failure_mode_cluster:github_issue | https://github.com/joshuaswarren/remnic/issues/1475 | Day Summary cron timezone is not configurable (uses server timezone)

## 10. 配置坑 · 失败模式：configuration: Flush plan: models hallucinate 'memory-candidates/' paths and flush-plan.md grows indefinitely

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Flush plan: models hallucinate 'memory-candidates/' paths and flush-plan.md grows indefinitely
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Flush plan: models hallucinate 'memory-candidates/' paths and flush-plan.md grows indefinitely
- 证据：failure_mode_cluster:github_issue | https://github.com/joshuaswarren/remnic/issues/1483 | Flush plan: models hallucinate 'memory-candidates/' paths and flush-plan.md grows indefinitely

## 11. 配置坑 · 失败模式：configuration: LCM summarizer bypasses taskModelChain, falls back to gateway default model chain

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: LCM summarizer bypasses taskModelChain, falls back to gateway default model chain
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: LCM summarizer bypasses taskModelChain, falls back to gateway default model chain
- 证据：failure_mode_cluster:github_issue | https://github.com/joshuaswarren/remnic/issues/1473 | LCM summarizer bypasses taskModelChain, falls back to gateway default model chain

## 12. 配置坑 · 失败模式：configuration: v9.3.639

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v9.3.639
- 对用户的影响：Upgrade or migration may change expected behavior: v9.3.639
- 证据：failure_mode_cluster:github_release | https://github.com/joshuaswarren/remnic/releases/tag/v9.3.639 | v9.3.639

## 13. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/joshuaswarren/remnic | README/documentation is current enough for a first validation pass.

## 14. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/joshuaswarren/remnic | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/joshuaswarren/remnic | no_demo; severity=medium

## 16. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/joshuaswarren/remnic | no_demo; severity=medium

## 17. 安全/权限坑 · 来源证据：FallbackLlmClient rejects OAuth-only providers (openai) before runtime auth resolution

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：FallbackLlmClient rejects OAuth-only providers (openai) before runtime auth resolution
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/joshuaswarren/remnic/issues/1478 | 来源类型 github_issue 暴露的待验证使用条件。

## 18. 安全/权限坑 · 来源证据：Flush plan: models hallucinate 'memory-candidates/' paths and flush-plan.md grows indefinitely

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Flush plan: models hallucinate 'memory-candidates/' paths and flush-plan.md grows indefinitely
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/joshuaswarren/remnic/issues/1483 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 19. 安全/权限坑 · 来源证据：LCM summarizer bypasses taskModelChain, falls back to gateway default model chain

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：LCM summarizer bypasses taskModelChain, falls back to gateway default model chain
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/joshuaswarren/remnic/issues/1473 | 来源类型 github_issue 暴露的待验证使用条件。

## 20. 能力坑 · 失败模式：capability: Make context recall append instead of prepend

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Make context recall append instead of prepend
- 对用户的影响：Developers may hit a documented source-backed failure mode: Make context recall append instead of prepend
- 证据：failure_mode_cluster:github_issue | https://github.com/joshuaswarren/remnic/issues/1479 | Make context recall append instead of prepend

## 21. 运行坑 · 失败模式：performance: v9.3.643

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: v9.3.643
- 对用户的影响：Upgrade or migration may change expected behavior: v9.3.643
- 证据：failure_mode_cluster:github_release | https://github.com/joshuaswarren/remnic/releases/tag/v9.3.643 | v9.3.643

## 22. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/joshuaswarren/remnic | issue_or_pr_quality=unknown

## 23. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/joshuaswarren/remnic | release_recency=unknown

## 24. 维护坑 · 失败模式：maintenance: v9.3.636

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v9.3.636
- 对用户的影响：Upgrade or migration may change expected behavior: v9.3.636
- 证据：failure_mode_cluster:github_release | https://github.com/joshuaswarren/remnic/releases/tag/v9.3.636 | v9.3.636

## 25. 维护坑 · 失败模式：maintenance: v9.3.637

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v9.3.637
- 对用户的影响：Upgrade or migration may change expected behavior: v9.3.637
- 证据：failure_mode_cluster:github_release | https://github.com/joshuaswarren/remnic/releases/tag/v9.3.637 | v9.3.637

## 26. 维护坑 · 失败模式：maintenance: v9.3.638

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v9.3.638
- 对用户的影响：Upgrade or migration may change expected behavior: v9.3.638
- 证据：failure_mode_cluster:github_release | https://github.com/joshuaswarren/remnic/releases/tag/v9.3.638 | v9.3.638

## 27. 维护坑 · 失败模式：maintenance: v9.3.640

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v9.3.640
- 对用户的影响：Upgrade or migration may change expected behavior: v9.3.640
- 证据：failure_mode_cluster:github_release | https://github.com/joshuaswarren/remnic/releases/tag/v9.3.640 | v9.3.640

## 28. 维护坑 · 失败模式：maintenance: v9.3.641

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v9.3.641
- 对用户的影响：Upgrade or migration may change expected behavior: v9.3.641
- 证据：failure_mode_cluster:github_release | https://github.com/joshuaswarren/remnic/releases/tag/v9.3.641 | v9.3.641

## 29. 维护坑 · 失败模式：maintenance: v9.3.642

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v9.3.642
- 对用户的影响：Upgrade or migration may change expected behavior: v9.3.642
- 证据：failure_mode_cluster:github_release | https://github.com/joshuaswarren/remnic/releases/tag/v9.3.642 | v9.3.642

<!-- canonical_name: joshuaswarren/remnic; human_manual_source: deepwiki_human_wiki -->