Magic Context
为 OpenCode 和 Pi 编程代理持续管理上下文，并沉淀跨会话项目记忆。
- Star 数
- ★ 2.5k
- 最近更新
- 4 天前
- License
- MIT
- 主语言
- TypeScript
- FA 评分
- 54/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 平台专用
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 中 · 需要几步配置
- 开始前需要
- 典型场景
- 使用 OpenCode 长期维护同一代码库的开发者，希望跨数周或数月的会话保留架构决策和项目约束。
- 不适合
- 只使用 ChatGPT、Codex 或 Claude Code 的团队，官方未提供这些宿主集成
- 在 Docker、CI 或一次性容器中运行却不挂载持久卷的用户，记忆不会累积
- 源码审查
- 54/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
Magic Context 是 CortexKit 的上下文与长期记忆插件，面向 OpenCode 和 Pi 编程代理。它用后台 historian 将旧对话压缩为带重要性分级的 compartments，并以确定性规则按上下文窗口渲染，从而避免宿主的常规 compaction 流程。它会把决策、约束和命名约定等信息写入项目记忆，并可通过可选的 dreamer 在空闲时验证、整理和更新记忆及文档。代理可借助 ctx_search、ctx_expand、ctx_memory、ctx_note 和 ctx_reduce 操作历史、记忆与延后事项。所有持久状态保存在本地 SQLite 数据库中，桌面应用直接读取该数据库进行浏览和管理。
每轮中，插件将活跃项目记忆和压缩后的会话历史以缓存稳定的方式注入上下文；可选的自动搜索会执行后台 ctx_search 并附加简短的相关提示。后台 historian 读取旧历史，生成按时间排列、带重要性评分的 compartments，同时提取 PROJECT_RULES、ARCHITECTURE、CONSTRAINTS、CONFIG_VALUES 和 NAMING 类记忆。代理可调用 ctx_reduce 排队删除陈旧内容、调用 ctx_memory 写入或删除记忆、调用 ctx_expand 还原压缩区间原文，并通过 ctx_search 搜索记忆、对话历史、可选索引的 Git 提交、notes 与 primers。可选 dreamer 会在空闲时创建临时子会话，执行 map、verify、curate、classify、retrospective、文档维护和 smart notes 处理；/ctx-dream 可按需触发。状态写入共享 CortexKit 存储中的 context.db，桌面应用从该 SQLite 库显示记忆、会话、缓存诊断、dreamer 记录、配置和日志。
- 使用 OpenCode 长期维护同一代码库的开发者，希望跨数周或数月的会话保留架构决策和项目约束。
- 在 Pi 与 OpenCode 之间切换的团队，希望两个宿主共享项目记忆和嵌入数据。
- 经常遇到长对话上下文压缩中断的开发者，希望由 historian 在后台维护历史，而不是依赖宿主 compaction。
- 代码库持续变化、担心记忆过期的维护者，希望在空闲时用 dreamer 将记忆映射到文件并增量验证。
- 需要追溯“为何这样设计”的工程师，希望用 ctx_search 在项目记忆、对话历史和可选 Git 提交索引中查询。
如何安装或部署这个 Agent？
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或任意系统运行：npx @cortexkit/magic-context@latest setup
安装向导会检测 OpenCode 和 Pi、添加插件、关闭内置 compaction，并协助选择 historian、dreamer 和 sidekick 模型。可用 --harness opencode 或 --harness pi 指定宿主；Pi 需要 >= 0.74.0。README 未说明需要单独的凭据。手动配置 OpenCode 时，在 opencode.json 添加 "@cortexkit/opencode-magic-context" 插件，并将 compaction.auto 与 compaction.prune 设为 false。
如何使用这个 Agent？
完成安装后重启 OpenCode 或 Pi；Magic Context 会从安装后的对话开始捕获上下文，不会回填此前会话。运行 npx @cortexkit/magic-context@latest doctor 可检查插件、冲突、TUI 侧栏与数据库完整性，并尝试修复可修复的问题。在会话中使用 /ctx-status 查看上下文状态，/ctx-dream 执行按需记忆维护，/ctx-recomp 重建历史 compartments，/ctx-wrapup [messages_to_keep] 压缩较旧的实时历史。项目级配置放在 <project-root>/.cortexkit/magic-context.jsonc，用户级配置放在 ~/.config/cortexkit/magic-context.jsonc。
这个 Agent 有哪些优点和局限？
- 以 historian compartments、确定性 decay rendering 和缓存安全的延迟操作管理上下文，目标是避免常规 compaction 暂停。
- 自动从历史压缩中提取项目记忆，并提供 ctx_memory、ctx_search、ctx_expand、ctx_note 与 ctx_reduce 等明确工具接口。
- OpenCode 与 Pi 共用数据库，因此项目记忆和嵌入可跨两个宿主复用。
- 可选 dreamer 可在空闲时验证、去重、分类记忆，并维护 ARCHITECTURE.md 与 STRUCTURE.md。
- 提供桌面应用，直接读取本地 SQLite 数据库以管理记忆、会话和缓存诊断，无需额外服务器或 API。
- 文档明确支持的宿主仅为 OpenCode 和 Pi，未提供 ChatGPT、Codex、Claude Code 或其 API 的原生集成证据。
- 它与 OpenCode 内置 compaction、opencode-dcp 及部分 oh-my-opencode hooks 冲突；冲突未解决时会以 fail-safe 方式自行禁用。
- 长期记忆与历史依赖本地 context.db 持久化；在 Docker、CI 或一次性容器中必须挂载持久卷，否则记忆不会累积。
- 默认本地嵌入首次使用时会下载约 90 MB 的 Xenova/all-MiniLM-L6-v2 ONNX 模型；也可关闭记忆或配置远程 embedding 后端。
- dreamer 的执行需要运行中的 OpenCode server，因为它会创建临时子会话。
这个 Agent 与同类方案有什么区别？
Magic Context 取代 OpenCode 的内置 compaction，并要求关闭 compaction.auto 与 compaction.prune。它不能与 opencode-dcp 同时运行；对于 oh-my-opencode，安装流程可关闭与其重叠的 preemptive-compaction、context-window-monitor 和 anthropic-context-window-limit-recovery hooks。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Magic Context 当前 | 54 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 2.5k | 4 天前 | TypeScript | — |
| Mnemo Cortex | 75 · 表现良好 | 自托管服务免费 | ★ 159 | 2 天前 | Python | Codex · Claude Code · Claude.ai |
| myc 本地代理记忆与任务层 | 87 · 表现良好 | 命令行工具免费 | ★ 14 | 18 天前 | TypeScript | Codex · Claude Code |
| Remnic 智能体记忆 | 85 · 表现良好 | 命令行工具免费 + 模型费 | ★ 231 | 今天 | TypeScript | ChatGPT · Codex · Claude Code · OpenAI API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示：插件需要访问项目文件、git历史、SQLite数据库，并可能调用外部模型API。README中说明了数据存储位置和用途，但未明确权限最小化原则。用户确认方面，安装和配置需要用户操作，但未提及关键操作（如删除记忆）的确认机制。数据流透明度较好，README详细描述了数据流向和存储。敏感数据处理方面，未明确说明如何处理API密钥或用户数据。依赖安全性方面，使用npm包和Rust crate，但未提供依赖审计或漏洞扫描证据。外部影响方面，插件会修改配置文件、禁用compaction，并可能运行后台进程，但README有说明。回滚方面，提供了`/ctx-recomp`和`/ctx-session-upgrade`命令，但未明确回滚机制。来源归属方面，MIT许可证和版权声明存在，但发布者未验证。
证据显示：README和测试文件描述了一致的架构和行为，但未提供完整的错误处理文档。依赖可用性方面，依赖外部服务（如模型API）和本地数据库，但未说明依赖故障时的降级策略。失败消息方面，README提到`doctor`命令和fail-safe机制，但未提供详细的错误消息示例。
证据显示：README面向编程代理用户，提供了多种使用场景（OpenCode、Pi、桌面应用）。能力边界方面，明确说明了与其他插件（如DCP、OMO）的冲突和禁用机制。触发精度方面，描述了`ctx_reduce`、`ctx_memory`等工具的触发条件。环境适配方面，支持macOS、Linux、Windows，并提供了Docker和CI环境的使用说明。
证据显示：README结构清晰，提供了安装、配置、使用和开发指南。安装说明详细，包括curl、PowerShell和npx方式。命名稳定性方面，工具和命令名称在README中一致。示例和FAQ方面，提供了工具使用示例，但未提供FAQ。已知限制方面，未明确列出所有限制，但提到了与其他插件的冲突。许可证为MIT，版权声明存在。版本变更日志方面，未提供CHANGELOG文件，但README提到迁移说明。维护责任方面，未明确说明维护者或贡献指南，但提供了Discord和GitHub链接。
证据显示：输出可用性方面，插件提供工具和命令，输出格式清晰。边际价值方面，解决了上下文管理和记忆问题，具有明确价值。成本效益方面，README提到使用缓存和本地模型降低成本，但未提供具体数据。
证据显示：README中的声明部分有测试支持（如缓存稳定性测试），但未提供所有声明的可追溯性。跨来源验证方面，未提供独立验证。事实与推断分离方面，README中区分了功能描述和性能声明，但未明确标注。
- 发布者身份未验证，需谨慎对待。
- 插件会修改配置文件并禁用compaction，可能影响其他工具。
- 依赖外部模型API和本地数据库，需确保数据安全。
- 未提供完整的错误处理文档和回滚机制。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
发布说明摘录
v0.49.35 This patch makes long OpenCode 2 sessions faster by letting OpenCode fold its own stored history while the session is idle, starts emergency recovery when OpenCode 2 reports an overflow as a failed step, keeps the context limit steady across a plugin reload, moves more ctx_expand work off OpenCode 2's main thread, fixes Oh My Pi turns refused after tag renumbering, and lets subagent sessions reclaim more context. Upgrading - Restart OpenCode or Pi after updating. No database migration is needed. Fixed …在 GitHub 查看 ↗ -
dashboard-v0.20.23 Dashboard dashboard-v0.20.23
发布说明摘录
Dashboard v0.20.23 The Cache page keeps reading Broca runs once Broca starts recording how a run and Magic Context agreed on the shape of history edits. Without this update, those runs would stop showing their steps and usage. Works with Magic Context 0.49.x.在 GitHub 查看 ↗ -
发布说明摘录
v0.49.34 This patch stops OpenCode 1 sessions from ending up with two summary markers after a failed save. Upgrading - Restart OpenCode after updating. No database migration is needed. Fixed - A failed save could leave a second summary marker on OpenCode 1: when Magic Context moves the point OpenCode loads history from, it writes a marker into OpenCode's database and then records that marker in its own database. If the second write failed, the next history update didn't know the first marker was its own and added another. Magic Context now records the marker it intends to writ …在 GitHub 查看 ↗