这篇实践把 OpenCode 的长期开发记忆拆成三个层次：claude-mem 保存跨会话的细粒度操作历史，magic-context 管理当前会话的上下文裁剪与近期记忆，StrictDoc 则把项目决策、进度和长期文档固化成开发者可阅读、可版本管理的事实来源。原作者发布于 2026 年 8 月 29 日；下面按可复用的工程结构整理配置、验证方法和边界。

一、三层职责不要混在一起

  • 操作历史层：claude-mem。通过 OpenCode 插件 hook 记录工具活动，并提供语义搜索，适合回答“之前实际做过什么”。这类记录只能作为线索，最终状态仍要用代码、配置和 Git 验证。
  • 会话上下文层：magic-context。由 historian/dreamer 等后台角色处理旧对话、近期记忆和上下文裁剪，目标是在长会话中保留任务主线，并允许检索被压缩的历史。
  • 项目事实层：StrictDoc。把当前有效的决策、进度、规范和研究文档放进 docs/，供人和 Agent 一起审阅。作者把这一层当作 source of truth，避免记忆随工程演化后互相冲突。

这个分工很重要：自动记忆擅长覆盖细节，却不保证事实仍然有效；人工可审阅文档更可靠，却需要明确的更新纪律。

二、安装与基础配置

claude-mem 的 OpenCode 安装命令是：

npx claude-mem install --ide opencode

安装后，OpenCode 插件通常位于用户配置目录。若需要插件默认 search 之外的 MCP 工具，原作者还在 opencode.jsonc 中注册本地 MCP 服务：

{
  "mcp": {
    "claude-mem": {
      "type": "local",
      "command": ["~/.bun/bin/bun", "<claude-mem>/scripts/mcp-server.cjs"],
      "enabled": true
    }
  }
}

<claude-mem> 必须替换成实际安装目录，不应照抄某台机器的缓存路径。~/.claude-mem/settings.json 中可配置 runtime、provider、OpenAI-compatible endpoint、模型和观察数量；API Key 应使用真实密钥管理方式，并限制配置文件权限，不要提交到仓库。

magic-context 的原帖安装命令为：

curl -fsSL https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.sh | bash

这是远程脚本直接进入 shell 的供应链风险点。更稳妥的做法是先下载并审查脚本、固定提交或版本，再执行。其用户级配置位于 ~/.config/cortexkit/magic-context.jsonc，核心形态如下：

{
  "historian": { "opencode": { "model": "提供商/模型" } },
  "execute_threshold_percentage": 65,
  "embedding": {
    "provider": "openai-compatible",
    "model": "text-embedding-3-large",
    "endpoint": "BASE URL",
    "api_key": "API KEY"
  },
  "dreamer": { "opencode": { "model": "提供商/模型" } },
  "sidekick": { "disable": true }
}

原作者把触发阈值设为模型输入窗口的 65%。这是个人配置，不是通用最优值；不同模型窗口、缓存策略、后台调用成本和响应延迟都需要重新测量。

三、避免双重压缩

magic-context 官方说明与原帖都要求关闭 OpenCode 内置 compaction，否则两个机制可能重复裁剪并相互干扰：

{
  "compaction": { "auto": false, "prune": false },
  "plugin": ["@cortexkit/opencode-magic-context@latest"]
}

正式项目不宜长期使用 latest。建议固定已验证版本，并在升级后重新检查配置 Schema、数据库兼容性和与其他上下文插件的冲突。magic-context 官方还提供 doctor 检查，可用于发现内置 compaction、DCP 或其他重叠 hook；原帖没有给出完整的升级回滚流程。

四、把可审阅事实固化到 StrictDoc

作者将 docs/ 分成两棵树：

docs/
├── project_memory/   # 决策与进度
└── handbook/         # 规范、研究、评估、设计文档

决策节点记录稳定 UID、状态、结论和理由；只有 Active 被视为当前规范，旧结论通过 Deprecated 或 Superseded 保留历史，而不是直接覆盖。进度写入 journal，长期文档进入 handbook。这样既保留演化过程，也能让下一次会话找到当前有效口径。

原帖的自定义 load-mem、save-mem、migrate-mem skills 负责把信息路由到三层：持久配置和约束进入注入式记忆，决策与进度进入 StrictDoc，操作细节留给 claude-mem。迁移旧文档时先盘点、分类并由人确认，再写入新结构，避免 Agent 自行判断冲突。

StrictDoc 版本必须固定并跨机器一致。原作者的迁移脚本举例固定到 0.28.1，同时提醒 0.28.3 已移除单括号 [SECTION] 写法；当前稳定文档也包含对应迁移说明。每次编辑后应运行：

strictdoc export .

只有导出成功，才说明语法和文档树仍可解析。

五、如何验证这套方案

原帖给出了作者的长期使用感受，但没有公开对照实验、成本统计、丢失率或故障注入结果。因此“不会失忆”“不失真”应视为作者观点，不能当作已证实结论。可以用以下验收清单自行复现：

  1. 新建测试项目，记录三项可核对的约束、一项架构决策和一个已知坑。
  2. 让会话超过配置阈值，确认 magic-context 触发后仍能准确复述约束，并能展开或检索被裁剪的原始历史。
  3. 结束会话后重新打开项目，检查 claude-mem 能否找到上次操作，同时用代码和 Git 核对结果。
  4. 修改一项决策并标记旧节点为 Superseded，验证 Agent 只采用当前 Active 版本。
  5. 暂停其中一个插件，确认系统能明确降级，而不是静默使用过期记忆。
  6. 记录后台模型调用量、embedding 成本、延迟和存储增长，再决定 65% 阈值是否合适。

适用边界与风险

这套组合适合长周期、跨会话、需要追踪决策缘由的代码项目；短任务或敏感环境可能不值得承担额外复杂度。两个记忆插件会接触对话、工具输出和项目上下文，使用前要审查权限、数据落点、联网行为与第三方模型端点。不要把凭据、生产数据或个人信息写进可被自动采集的上下文。

它也不是代码事实的替代品：记忆命中后仍要检查当前文件、测试和版本控制；StrictDoc 只有在团队持续维护状态和理由时才是真实来源。若插件版本、OpenCode hook 或模型接口变化，原帖中的路径和配置可能立即失效。

相关核对： claude-mem OpenCode 集成 · magic-context 官方说明 · StrictDoc 用户指南

原作者：brilliantrough
原帖：https://linux.do/t/topic/2829071