🎯 OpenCode插件系列: opencode-magic-context

类型: 上下文管理插件代码库: https://github.com/cortexkit/magic-context NPM包: @cortexkit/magic-context (CLI), @cortexkit/opencode-magic-context (OpenCode插件), @cortexkit/pi-magic-context (Pi插件) 星标: 500+ ⭐

1. 这是什么插件？

Magic Context 是一个用于AI编码代理的缓存感知无限上下文、跨会话内存和背景历史压缩插件。

核心思想是让代理专注于编码工作，而不是自己管理上下文和内存。所有上下文压缩和内存管理都在后台自动运行，代理完全无感知。

主要组件:

背景历史记录器 — 主代理继续工作时，一个单独的模型在后台压缩旧的对话。所有操作都是缓存感知的，避免浪费缓存的prefix。
跨会话项目内存 — 架构决策、约束和偏好在不同会话间持久化。
夜间梦想家代理 — 整合、去重、提升记忆到规范事实，并维护代码库文档。
按需助手 — 用相关的项目上下文增强提示。
TUI侧边栏 — 在终端内显示实时上下文分解、token使用、历史记录器状态和内存计数。

2. 有什么用？

在以下场景中使用它：

✅ 无限上下文窗口 — 可以在同一会话中工作数周、数月甚至数年
✅ 跨会话记忆 — 在OpenCode中写入记忆，在Pi中检索（反之亦然）
✅ 防止上下文过载 — 自动压缩旧对话，保持当前上下文精简
✅ 智能记忆管理 — 通过语义搜索检索相关记忆
✅ 实时监控 — 通过TUI侧边栏查看token分解和历史记录器状态
✅ 自动代码库文档 — 梦想家代理维护项目文档

技术特性:

缓存感知压缩 — 避免破坏缓存prefix，只在必要时压缩
分层压缩策略 — 不同年龄的文本采用不同的压缩强度
语义搜索 — 通过嵌入向量在记忆和会话历史中搜索
时间感知 — 显示消息间的时间间隔，帮助代理理解时间流逝
Git提交索引 — 索引项目提交记录，支持语义查询
子代理上下文管理 — 子代理自动清理旧工具调用和推理过程

3. 怎么用？

快速安装（推荐）

运行交互式设置向导 — 它会检测你的模型、配置所有内容并处理兼容性：

macOS / Linux:

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

Windows (PowerShell):

irm https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.ps1 | iex

或手动安装OpenCode插件:

opencode plugin @cortexkit/opencode-magic-context@latest --global

配置

关闭 ~/.config/opencode/opencode.jsonc 文件中的压缩:

  "compaction": {
    "auto": false,
    "prune": false
  },

如果使用了oh-my-openagent 或者oh-my-opencode , 需要做以下设置：


 "disabled_hooks": [
    "non-interactive-env",
    "context-window-monitor",
    "preemptive-compaction",
    "anthropic-context-window-limit-recovery",
    "agent-usage-reminder",
    "category-skill-reminder",
    "comment-checker",
    "directory-readme-injector",
    "keyword-detector",
    "todo-continuation-enforcer",
    "write-existing-file-guard"
  ]

创建 ~/.config/opencode/magic-context.jsonc 文件：

{
  "enabled": true,
  "debug": false,

  // 上下文管理设置
  "ctx_reduce_enabled": false,  // 禁用代理驱动的压缩（推荐使用背景压缩）
  "execute_threshold": 0.75,    // 触发压缩的上下文利用率阈值（百分比）

  // 历史记录器设置
  "historian": {
    "enabled": true,
    "model": "anthropic/claude-haiku-4.5"  // 用于压缩的模型
  },

  // 梦想家设置
  "dreamer": {
    "enabled": true,
    "schedule": "daily",        // 每天运行
    "user_memories": true,      // 提取用户行为观察
    "pin_key_files": false      // 实验性：自动固定关键文件
  },

  // 记忆设置
  "memories": {
    "enabled": true,
    "embedding_provider": "openai",  // 或 "anthropic", "cohere"
    "max_injected": 10               // 每次注入的最大记忆数
  }
}

可用的斜杠命令

命令	功能
`/ctx-status`	调试视图：标签、待处理删除、缓存TTL、历史记录器进度
`/ctx-flush`	强制立即执行所有排队操作，绕过缓存TTL
`/ctx-recomp`	从原始历史重新构建隔间和事实
`/ctx-aug`	对提示运行助手增强 — 通过单独模型检索相关记忆
`/ctx-dream`	按需运行梦想家维护 — 整合、验证、归档、改进记忆

对于不同的AI代理：

OpenCode: 使用 @cortexkit/opencode-magic-context 插件
Pi代理: 使用 @cortexkit/pi-magic-context 插件
独立CLI: 使用 @cortexkit/magic-context 包

4. 什么时候用？

在以下场景使用：

✅ 长期项目 — 在同一项目上工作数周或数月
✅ 大型代码库 — 需要跨多个文件保持上下文一致
✅ 团队协作 — 需要共享架构决策和项目知识
✅ 复杂重构 — 需要参考历史决策和约束
✅ 多个AI代理 — 在OpenCode和Pi之间共享记忆
✅ 按token付费 — 需要减少不必要的上下文重复

不要使用的场景：

❌ 简单短任务 — 一次性脚本或简单的bug修复
❌ 探索性工作 — 快速原型验证，不需要长期记忆
❌ 受限的系统资源 — SQLite数据库和后台模型需要额外资源
❌ 需要手动完全控制 — 想要100%手动管理所有上下文

⚠️ 重要注意事项

缓存权衡：

没有Magic Context: 缓存命中率约 90%
有Magic Context: 缓存感知操作，根据模型变化调整压缩时机，避免不必要的缓存破坏
背景压缩 使用单独模型，不影响主代理的缓存

兼容性问题：

与DCP插件冲突 — 不能同时启用Magic Context和DCP
OpenCode内置压缩 — 需要禁用以避免冲突
启动时冲突检测 — Magic Context会自动检测并警告配置问题

实验性功能：

用户记忆 — 提取用户行为模式并注入为 <user-profile>
关键文件固定 — 自动识别并固定经常读取的核心文件
Git提交索引 — 使提交历史可通过语义搜索访问
自动搜索提示 — 在提示前运行后台搜索，提供相关片段

许可证: MIT

🔗 有用链接

官方文档:
NPM包:
配置和架构文档:
相关项目和平台:
比较和迁移: