为编码代理提供后台自动记忆捕获、整合与召回，实现单会话长期运行

方案简介

Magic Context 是 CortexKit 旗下的编码代理“海马体”——一套完全在后台运行的上下文与记忆管理方案。它把一次性会话变成可延续数周、数月甚至数年的长期会话：代理不再每次任务都“从零入职”，而是持续积累项目记忆。

方案解决两个核心问题：一是代理中途的 compaction（压缩）暂停会打断工作流并悄悄丢失上下文；二是会话结束后知识全部丢失。Magic Context 通过三个环节应对：

• Capture（捕获）：historian 在压缩历史时把持久知识（决策、约束、约定）提升进项目记忆，等于“免费”获得记忆系统。
• Consolidate（整合）：夜间由 dreamer 代理校验记忆与代码库一致性、清理重复与过期条目、提升反复出现的记忆。
• Recall（召回）：每轮自动浮现相关记忆，代理也可按需搜索记忆、历史对话与 git 历史，并跨 OpenCode、Pi、OMP 使用。

适合使用 OpenCode、Pi 或 OMP 等 harness、希望代理具备长期项目记忆的开发者。

亮点与能力

• 后台自动捕获持久知识（决策、约束、约定）进项目记忆
• 夜间 dreamer 代理自动校验、去重、清理过期记忆
• 每轮自动召回正确记忆，无需手动触发
• 支持跨记忆、历史对话与 git 历史的按需搜索
• 无 compaction 暂停，缓存感知的延迟操作不破坏流程
• 跨会话、跨 OpenCode/Pi/OMP 共享记忆
• 交互式安装向导自动检测 harness、选模型、处理插件冲突
• 可选本地嵌入模型支持语义搜索

组成与分工

• OpenCode / Pi / OMP：宿主 harness，Magic Context 以插件形式接入其中，可任意组合
• @cortexkit/magic-context：npm 主包，提供交互式安装向导
• @cortexkit/opencode-magic-context：OpenCode 专用插件包
• historian（模型）：压缩历史并把持久知识提升为项目记忆
• dreamer（模型）：夜间定期整合记忆，验证与代码库一致性、去重
• sidekick（模型）：支撑 /ctx-aug 能力（可选）
• Xenova/all-MiniLM-L6-v2：默认本地嵌入模型，支持语义搜索（可选配置）
• git：被召回搜索覆盖的历史来源之一

前置要求

需要具备 OpenCode、Pi 或 OMP 之一（或任意组合）作为宿主 harness，并通过 npm/npx 运行安装向导。安装命令：

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

Windows (PowerShell)：
powershell
irm https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.ps1 | iex

或任意系统直接运行：
bash
npx @cortexkit/magic-context@latest setup

使用与配置要点

• 每个项目保持一个会话长期运行，可延续数周、数月甚至数年
• 必须设置 historian.opencode.model 为真实的 provider/model-id，否则插件虽加载但 historian 运行失败，旧历史不被摘要，并出现 Magic Context — history comparting needs attention 提示
• 必须禁用宿主内置 compaction，否则会干扰缓存感知的延迟操作并造成双重压缩
• 裸插件条目在重启前会被固定到下载的确切版本，避免 OpenCode 在会话中途移除活跃包；如需保持 unpinned，需显式写 @latest
• 旧的扁平模型配置会在首次读取时自动迁移到 per-harness 形式

注意事项与常见问题

• 必须禁用内置压缩：Magic Context 自行管理上下文，宿主的压缩会干扰其缓存感知的延迟操作并双重压缩。
• historian 模型必填：缺少时插件加载但 historian 运行失败，旧历史不摘要，重复失败会显示 Magic Context — history comparting needs attention 通知。
• 关闭 embedding 的代价：会移除语义/嵌入支持的搜索，但关键词搜索与上下文管理继续可用。
• 插件版本固定：裸条目会被固定到确切版本；移除版本后若想保持 unpinned 需显式写 @latest。
• 配置形状迁移：新配置应使用 per-harness 形状，扁平形状仅作为迁移前的 before 示例。

优缺点

• ✓ 无需手动压缩，上下文不打断
• ✓ 跨会话跨工具记忆共享
• ✕ 必须禁用宿主内置压缩
• ✕ historian 模型必配否则失败

出处

本方案挖掘自开源项目 cortexkit/magic-context，方案内容与实施命令均来自其 README 原文。