cortexkit/magic-context

Magic Context – 为编码代理提供自我管理的长期记忆

简介 – 这是CortexKit套件的一个插件，为AI驱动的编码代理赋予“海马体”。它能自动从项目的聊天记录中提取有用知识，在后台整合，并使其跨会话和工具（OpenCode、Pi、Oh‑My‑Pi）可搜索。目标是消除传统的压缩中断——那种让代理在任务中途忘记所学内容的机制。

主要功能

• 捕获 – 代理工作时，历史记录器会扫描对话，提取持久性事实（设计决策、约束、配置值、命名约定），并将其存储为项目记忆。
• 整合 – 可选的梦想家（通常在夜间）运行，对照当前代码库验证记忆，合并重复项，清理过时条目，并保持文档最新。
• 召回 – 每一轮系统都会将最相关的记忆注入提示词。开发者还可以调用ctx_search、ctx_expand、ctx_note等来检索或编辑记忆、搜索git提交或推迟笔记。
• 上下文窗口管理 – 历史记录器创建分层隔间，用重要性分数总结较旧消息，从而在保持完整线程的同时让活动提示词保持小巧。缓存感知的缩减确保模型的提示词缓存不会被失效。
• 跨框架支持 – 支持三大CortexKit框架（OpenCode、Pi、Oh‑My‑Pi），并自动禁用任何竞争的上下文管理插件。

安装与设置

# 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在任何操作系统上
npx @cortexkit/magic-context@latest setup

向导会检测你使用的框架，添加相应的插件（@cortexkit/opencode-magic-context、@cortexkit/pi-magic-context等），禁用宿主的内置压缩，并帮助你为历史记录器、梦想家和副驾选择模型。

配置 – JSONC文件（magic-context.jsonc）允许你按框架指定历史记录器（必需）以及可选的梦想家和副驾的模型ID。你还可以启用/禁用嵌入、时间感知和自动搜索提示。

典型工作流程

1. 运行设置向导（或手动将插件添加到框架配置中）。
2. 历史记录器开始总结聊天记录，并将持久性事实提升到项目记忆。
3. 可选地启用梦想家（/ctx-dream）以运行夜间维护。
4. 在会话期间，代理会自动接收相关记忆；你也可以用ctx_search查询或用ctx_memory编辑。

你将使用的命令

命令	作用
/ctx-status	显示当前记忆统计、待处理丢弃项、历史记录器进度等。
/ctx-flush	强制立即运行所有排队的缩减/压缩。
/ctx-recomp	从原始历史重建隔间（在状态损坏时有用）。
/ctx-dream	按需触发梦想家的维护周期。
/ctx-search（工具）	跨记忆、聊天、git提交和笔记进行语义/关键词搜索。
/ctx-note	创建一条延迟笔记，供梦想家稍后呈现。

重要性 – 没有Magic Context，每个编码代理会话都从空白状态开始，并遭受周期性“压缩”导致的上下文中断。有了Magic Context，单个会话可以持续数周甚至数月，在保留项目知识的同时降低令牌成本，并保持代理的提示词缓存稳定。

了解更多 – 完整文档位于 https://docs.cortexkit.io/magic-context ，Discord社区链接在README中。