mem-recall

Mem Recall

为 Claude Code、Codex CLI、Devin CLI、Grok、OpenCode、Pi 和 ZCode 提供跨平台对话记忆。trellis mem 命令会读取各平台的本地会话存储，清理对话内容（剔除系统提示词、工具噪声、钩子注入内容，并正确处理压缩摘要），并提供专注于回忆工作流的 5 命令 CLI。Devin CLI 对应 --platform devin，读取 ~/.local/share/devin/cli/sessions.db——不是 trellis init --devin（Desktop/Cascade），也不是 Factory Droid。

前提条件

全局安装 Trellis CLI 0.6.17 或更高版本：

npm install -g @mindfoldhq/trellis@latest
trellis --version

trellis mem 已随 CLI 捆绑，无需额外设置。0.6.17 新增了 Cognition Devin CLI 支持（--platform devin，~/.local/share/devin/cli/sessions.db）。 这不是 trellis init --devin（Desktop/Cascade），也不是 Factory Droid。 0.6.14 新增了 Grok 支持，并保留了压缩前的对话轮次；0.6.16 恢复了 OpenCode 支持。

OpenCode 于 0.6.16 通过零依赖 SQLite 读取器恢复支持。 --platform opencode 会读取 ~/.local/share/opencode/opencode.db。

何时使用此技能

每当用户提出以下任意请求时，主动使用：

• “我之前跟 Codex/Claude 讨论过 X，你了解下”
• “上次我们怎么解决 Y 的？”
• “翻一下历史看看”
• “我之前在 trellis 项目里聊过哪些 plugin 设计？”
• “find sessions about memory architecture”
• “what did I tell another AI about this last week”

设计理由类问题（优先使用 --phase brainstorm，见下文）：

• “我们当时怎么决定 X 的？”
• “之前讨论过 X 的 trade-off”
• “为什么我们选了 X 而不是 Y”
• “what was the design discussion about Y”
• “the rationale for choosing X”
• “find the brainstorm where we picked Z over alternatives”

不要质疑用户的意图。此技能正是为满足用户“将我过去的对话用作上下文”的需求而设计的。跨平台、跨项目回忆没有其他工具可用——git log 只能查看提交记录，你自己的记忆也没有记录用户在其他 CLI 中说过什么。

回忆工作流（记住此模式）

回忆分为两步逐步深入，而不是单次查询。第 1 步缩小到某个会话；第 2 步提取实际内容。

Step 1 (discover):  trellis mem search "<topic>" [--cwd <project>] [--since <date>]
Step 2 (drill):     trellis mem context <session-id> --grep <topic> --turns 3 --around 1

如果用户没有说明是哪个项目，先运行 trellis mem projects，列出最近活跃项目的 cwd，再选择最可能的项目。

命令

trellis mem projects — 列出活跃项目的 cwd

用户提到“那个项目”但没说是哪个时，先使用此命令。它会显示所有平台上不重复的 cwd，按最近活跃时间排序，并列出各平台的会话数。这是 AI 路由的入口。

trellis mem projects --since 2026-04-20 --limit 10

输出：

2026-05-04 03:42  sessions= 1 (claude:1)  ~/workspace/nb_project/mem-poc
2026-05-04 01:00  sessions=114 (claude:51 codex:63)  ~/workspace/.../Trellis
...

trellis mem search <keyword> — 查找候选会话

在清理后的对话中执行多词 AND 搜索。返回按相关性排序的会话，每个匹配项都附有片段摘录。默认搜索当前工作目录；使用 --global 可搜索所有项目。

trellis mem search "trellis memory" --cwd ~/workspace/.../Trellis --since 2026-04-13

每个会话的输出：

[claude  ] 2026-04-20 11:39  4cda3c7f-8f9  ~/.../Trellis  score=6.027  hits=169 (u=27,a=142)  turns=37
    [user] 是我们的用户想要搞类似记忆系统的东西…
    [assistant] ## Memory plugin 调研结论…

分数的含义：(3 × user_hits + asst_hits) / total_turns。分数越高，表示话题越集中，且由用户本人提出的可能性越大。用户对话轮次的命中权重乘以 3，因为用户的措辞是最强的话题信号——AI 可能反复使用同一个词进行展开，从而抬高原始计数。

摘录按段落对齐分块，而非按字符窗口截取。分块会遵循 Markdown 和代码块边界，并优先选择明显包含所有查询词的片段。如果多个查询词分散在较长的对话轮次中，片段会改为以最罕见的词为锚点（区分度更高）。

trellis mem context <session-id> — 深入查看会话

search 选出候选会话后，使用此命令提取特定命中轮次及其上下文。输出按 Token 预算控制，便于 AI 直接使用。

trellis mem context 4cda3c7f --grep memory --turns 3 --around 1
# top-3 hit turns + 1 turn before/after each, ≤6000 chars total

trellis mem context 4cda3c7f --turns 5 --around 0
# no grep: returns the first 5 turns (lets you see how the session opens)

默认预算为 6000 个字符（约 1500 个 Token）；每轮上限为预算的一半。使用 --max-chars N 可调整。

trellis mem extract <session-id> — 导出清理后的对话

导出经过平台专属清理的完整对话。适用于长篇检查，不适用于预算受限的回忆。

trellis mem extract 4cda3c7f --grep memory   # filter to turns matching keyword
trellis mem extract 4cda3c7f --json          # structured output

trellis mem extract --phase brainstorm — 切分讨论部分

Trellis 会话通常以头脑风暴开场（用户边想边说、AI 提出选项、否决替代方案、作出决定），用户运行 task.py start 后才开始实施工作。--phase 标志会沿着这个边界切分清理后的对话，以便提取讨论部分并去除实施过程中的噪声，反之亦然。

边界：头脑风暴窗口是同一会话中匹配的 task.py create ... 和 task.py start ... Bash 调用之间的所有内容。包含多个任务的会话会产生多个窗口。

三个取值：

--phase	提取内容
all（默认）	完整的清理后对话——与此标志出现前相同
brainstorm	仅包含 [create, start) 窗口——讨论 / 决策
implement	所有头脑风暴窗口以外的内容——实际工作

适合优先使用 --phase brainstorm 的情况：关于设计理由的问题（“我们当时为什么选了 X”、“关于 Y 的权衡讨论”、“我们否决了哪些替代方案”）在头脑风暴窗口中的信号密度，远高于整个会话。直接使用 extract --phase brainstorm，而不是 context --grep；后者可能会把你带到实施阶段的中间，这时话题只是被提及，并非作出决定的过程。

示例：

# Single session, brainstorm only
trellis mem extract 4cda3c7f --phase brainstorm

# Multi-task session — output is split with separators:
#   --- task: my-feature ---
#   ## Human ...
#   --- task: another-task ---
#   ## Human ...
trellis mem extract 4cda3c7f --phase brainstorm

# Filter inside the brainstorm window only (--phase runs first, then --grep)
trellis mem extract 4cda3c7f --phase brainstorm --grep "trade-off"

# Structured output: get window metadata for downstream scripts / AI
trellis mem extract 4cda3c7f --phase brainstorm --json
# JSON adds:
#   "phase": "brainstorm"
#   "windows": [{ "label": "my-feature", "startTurn": 1, "endTurn": 14 }, ...]
#   "groups":  [{ "label": "my-feature", "turns": [...] }, ...]
#   "turns":   [...]   // flat concatenation, legacy-compatible

# The inverse: just the implementation work
trellis mem extract 4cda3c7f --phase implement

平台支持：

平台	--phase brainstorm / implement
Claude	原生支持——在原始 JSONL tool_use Bash 块中检测边界
Codex	原生支持——在 function_call（exec_command）事件中检测边界
Devin	原生支持——沿 main_chain_id 遍历 exec tool_calls 并检测边界
Pi	原生支持——在活动分支会话条目中检测边界
OpenCode	支持有限——返回完整对话，并发出 opencode-phase-unsupported 警告

已妥善处理的边缘情况：

• 找到 create，但后面没有 start（任务仍在进行中）→ 窗口会一直延续到会话结束。
• 找到 start，但前面没有 create（任务在更早的会话中创建）→ 头脑风暴窗口为 [0, start)。
• 两者均未找到 → 返回完整对话，并向 stderr 输出警告。

trellis mem list — 列举会话

主要用于浏览 / 调试。默认限定当前项目；使用 --global 可扩大范围。

trellis mem list --since 2026-04-27

OpenCode 子会话会显示 ↳ child of <parent-id> 注释。

标志参考

--platform claude|codex|devin|grok|opencode|pi|zcode|all   default all
--since YYYY-MM-DD                     inclusive lower bound
--until YYYY-MM-DD                     inclusive upper bound
--global                               include all projects (default: cwd-scoped)
--cwd <path>                           override the project cwd
--limit N                              cap output (default 50)
--grep KW                              extract / context: filter turns by keyword
--turns N                              context: top-N hit turns (default 3)
--around N                             context: surrounding turns per hit (default 1)
--max-chars N                          context: char budget (default 6000)
--phase brainstorm|implement|all       extract: slice by [task.py create, start) (default all; Claude, Codex, Devin & Pi)
--include-children                     search / context: merge OpenCode sub-agent sessions into parent
--json                                 emit JSON
--help, -h                             show help

运行 trellis mem help 查看权威标志参考。

数据来源（各平台）

工具会直接读取以下位置。无需守护进程、索引或上传。

平台	存储位置	说明
Claude Code	~/.claude/projects/<sanitized-cwd>/*.jsonl	每个会话对应一个 JSONL；cwd 路径编码在目录名中（/ 和 _ → -）
Codex	~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl	每个会话对应一个 JSONL；cwd 位于首个事件的 session_meta 载荷中
Devin CLI	~/.local/share/devin/cli/sessions.db	Cognition Devin CLI（WAL SQLite）。使用 --platform devin。不是 trellis init --devin（Desktop/Cascade），也不是 Factory Droid
Grok	~/.grok/sessions/<url-encoded-cwd>/<session-id>/chat_history.jsonl	cwd 在目录名中经过 URL 编码；session_search.sqlite 仅作索引，不会被读取
Pi	默认路径 ~/.pi/agent/sessions/；环境变量覆盖项；全局配置 ~/.pi/agent/settings.json；项目范围配置 .pi/settings.json	每个会话对应一个 JSONL；相对 sessionDir 值会以设置文件所在目录为基准解析。项目本地设置会针对当前 cwd 或 --cwd 查找，不会通过不受限的 --global 扫描查找。仅提取活动的 id/parentId 分支。
OpenCode	~/.local/share/opencode/opencode.db	SQLite session/message/part 表（0.6.16+）

清理规则（从原始数据中剔除的内容）

该工具仅提取真实的人类与 AI 对话，并剔除：

• 系统／提示词注入：<system-reminder>、<workflow-state>、<INSTRUCTIONS>、<environment_context>、<permissions instructions>、<collaboration_mode> 等（不区分大小写）
• 引导轮次：Codex 会将 AGENTS.md 前言注入为首条用户消息——整个轮次都会被丢弃，而不只是标签
• 工具调用及其结果：仅保留 text 块 压缩前的轮次会保留，并标记压缩发生的位置（0.6.14 及更高版本；更早版本会丢弃这些轮次）。对于平台未以可读形式存储的内容，工具会报告，而不是静默省略——Codex 会加密 Agent 之间的消息，Grok 则会将压缩前的轮次以渲染后的 Markdown 形式保存在 <session>/compaction/ 下。

这意味着搜索命中结果能可靠地表明“实际对话讨论过这件事”，而不是“某个钩子注入中出现了这个关键词”。

跨平台子 Agent 语义

平台	子 Agent 存储方式	可恢复？
Claude	同一份 JSONL——主 Agent 的 Agent/Task tool_use 会记录提示词；tool_result 包含最终输出。不会记录子 Agent 的内部轮次	仅提示词 + 最终结果
Codex	每次 codex exec 启动都会生成新的 rollout JSONL，没有 parent_id 字段	视为独立会话
Devin	sessions.db 中的树结构（message_nodes）；沿 main_chain_id / parent_node_id 遍历。分叉和回退会被丢弃	当前主链
Pi	每个会话对应一份 JSONL；已放弃的分支会从活动分支中移除，但每个已放弃分支的 branch_summary 条目都会作为一条摘要轮次保留	活动分支 + 已放弃分支的摘要
OpenCode	session.parent_id 会关联子 Agent 链	--include-children 会将后代合并到父会话中

--include-children 只会显著改变 OpenCode 搜索的行为——其他平台没有原生的 parent_id 可供合并。

示例：“上周我在 Trellis 中讨论过哪些关于记忆的内容？”

# 1. Confirm the project name (skip if user already named it explicitly)
trellis mem projects --since 2026-04-27
# → finds "~/workspace/.../Trellis" with 114 sessions

# 2. Find candidate sessions
trellis mem search "memory" \
  --cwd ~/workspace/.../Trellis \
  --since 2026-04-27

# → top: codex 019dcc75 (score 2.43, Codex memory subagent + Trellis hook)
#   then: claude 12d26622 (user interview about "项目记忆 4 形态")

# 3. Drill into the most relevant
trellis mem context 12d26622 --grep memory --turns 3 --around 1
# → returns the actual interview question block listing 4 memory archetypes

# 4. Now answer the user with concrete content recovered from past sessions

除非用户明确要求查看完整会话，否则不要为了回忆而运行 extract——它会耗费大量 token 预算，而且通常没有必要。

引用回忆的内容

向用户呈现恢复的内容时，请引用会话 id + 实际引用的原文。不要只说“我记得我们讨论过 X”，却没有依据——用户无法核实，也可能指的是另一段对话。

格式：

From session 12d26622 (claude, 2026-04-20):
> 是我们的用户想要搞类似记忆系统的东西…

You proposed four memory archetypes that day: …

不应使用此技能的情况

• 用户想搜索代码（使用 Grep / Read）
• 用户想查看提交历史（使用 git log / gh）
• 用户想搜索当前项目中的文档／文件（使用 Read / Glob）

此技能专门用于恢复过去 AI 对话中的内容，而非文件内容。

性能说明

• 项目范围内搜索最近 3 周：在典型的 Mac 上约需 0.85 秒
• 不限时间的全局搜索：约需 3 秒（扫描整台机器上的会话语料）
• 每次调用都是无状态的——没有缓存，也没有守护进程。冷启动和热启动的性能相近，因为 macOS / Linux 的页缓存会吸收文件读取开销
• 交互使用时，建议使用 --cwd + --since 缩小语料范围