magic-context

让AI智能体拥有无限记忆，一个会话干到底

magic-context 是一个面向编码智能体的上下文管理工具，旨在解决 AI 智能体在长会话中上下文有限、记忆混乱的问题。它提供无界上下文和自管理记忆，让智能体在一个会话中持续工作，无需频繁重置。核心能力包括自动记忆分层、缓存感知的上下文压缩、以及与主流智能体框架（如 LangChain）的集成。通过模拟海马体的功能，它帮助智能体记住关键信息，遗忘冗余内容，从而提升长任务的稳定性和效率。项目采用 TypeScript 编写，属于 CortexKit 生态，目前处于成长阶段，适合需要长期记忆和复杂任务处理的 AI 应用开发者。

开源 free 智能体

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 2189

维护状态活跃

是否开源是

定价模式 free

项目数据

分类智能体

开发团队cortexkit

所属国家

官网地址

GitHubhttps://github.com/cortexkit/magic-context

定价模式free

价格说明开源项目，MIT许可证，完全免费，可自行部署使用。

访问状态

是否开源是

开源协议MIT

主要语言TypeScript

技术栈/模型agent-framework,agent-memory,ai,ai-agents,ai-context,ai-memory,cache-aware,context-engineering,context-management,langchain,memory,opencode,pi-coding-agent

GitHub 星标★ 2189

30天Star增速

HF 下载量

上线时间2026-03-26 00:00:00

最近更新2026-09-23 00:00:00

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-08-09

浏览次数3

使用教程

难度：入门约 10 分钟部署方式：命令行工具 6 步

环境要求

Node.js 环境（能执行 npx 命令）
已安装至少一个受支持的 harness：OpenCode、Pi 或 OMP
一个真实可用的模型标识 provider/model-id
网络可访问 npm registry 与 GitHub raw 资源

安装与启动步骤

1macOS/Linux 运行向导

一键运行交互式安装向导，自动检测已装的 harness、添加插件并关闭内置压缩。
```
curl -fsSL https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.sh | bash
```
2Windows 运行向导

在 PowerShell 中执行安装脚本，效果与 macOS/Linux 脚本一致。
```
irm https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.ps1 | iex
```
3任意系统直接运行

不执行安装脚本时，可用 npx 直接启动同款交互式安装向导。
```
npx @cortexkit/magic-context@latest setup
```
4指定目标 harness

同时装了多个 harness 时，用 --harness 指定要配置哪一个（opencode、pi 或 omp）。
```
npx @cortexkit/magic-context@latest setup --harness opencode
```
5手动配置 OpenCode

无法跑向导时，在 opencode.jsonc 中加入 plugin 条目，并把 compaction 的 auto 与 prune 设为 false。
6配置 historian 模型

创建 magic-context.jsonc，填入 historian.opencode.model，取值必须是真实的 provider/model-id。

关键配置

配置项	必填	说明	示例
`plugin`	是	在 opencode.jsonc 中注册 magic-context 插件	`["@cortexkit/opencode-magic-context@latest"]`
`compaction.auto`	是	关闭宿主自动压缩，避免与 Magic Context 冲突	`false`
`compaction.prune`	是	关闭宿主压缩裁剪	`false`
`historian.opencode.model`	是	指定 historian 使用的模型，缺失会导致历史摘要失败	`provider/model-id`
`embedding`	否	省略则用本地 Xenova/all-MiniLM-L6-v2；关闭会失去语义检索	`false`
`dreamer`	否	控制周期性记忆整合，省略即关闭该功能	`provider/model-id`

如何确认成功

启动 OpenCode 会话，插件正常加载且 historian 能摘要历史，不再反复出现 “history compacting needs attention” 提示。

常见问题

Q：为什么必须关闭内置 compaction？

A：Magic Context 自行管理上下文，宿主的压缩会干扰其缓存感知的延迟操作并造成重复压缩，所以要把 auto 和 prune 都关掉。

Q：不填 historian 模型会怎样？

A：插件仍能加载，但 historian 运行失败，较早的历史不会被摘要，并会反复弹出 Magic Context — history compacting needs attention 提示。

Q：配置文件应放在哪里？

A：项目根目录 .cortexkit/magic-context.jsonc，或用户级 ~/.config/cortexkit/magic-context.jsonc，项目配置会覆盖用户级设置。

Q：旧版本的配置会丢吗？

A：不会。首次运行时旧配置会自动迁移到新的 CortexKit 位置，并在原路径留下 .MOVED_READPLEASE 标记。

Q：可以完全不用 embedding 吗？

A：可以。省略 embedding 默认使用本地 Xenova/all-MiniLM-L6-v2；显式关闭后失去语义搜索，关键词搜索与上下文管理仍正常。

注意事项

插件条目会在重启前固定到已下载的精确版本；若要特意保持不固定，需显式写 @latest。
按模型生效的设置（如 prompt_surface.models）目前只作用于注入的引导块，工具描述需等 OpenCode v2 插件 API。
完整配置参考见仓库 CONFIGURATION.md 或 docs.cortexkit.io 的配置文档。

核心亮点

自动管理上下文，无需手动清理或摘要，减少开发负担
缓存感知压缩，显著降低 token 消耗，节省成本
与 LangChain 等框架集成，接入简单，生态兼容性好

不足之处

项目较新，文档和社区支持尚待完善
依赖特定框架，对非标准智能体环境适配有限

适用场景

长对话型AI助手，需持续记忆用户偏好
复杂编码任务，需跨文件、跨步骤的上下文保持
多轮自动化工作流，需减少 token 开销的场景

替代项目

MemGPT、Letta、LangMem

项目介绍

magic-context 是智能体领域的开源项目，由 cortexkit 开发，是 2026 年新上线的项目。

在全站 13,090 个收录项目中，它的 GitHub 星标数（2,189）位列前 30%，在智能体分类中处于中上游。

近 42 天，它的 GitHub 星标从 1,729 增加到 2,189，净增 460。

项目目前处于活跃维护状态，最近一次代码更新于 2026-09-23。MIT许可证，完全免费，可自行部署使用。

它主要面向的使用场景是：长对话型AI助手，需持续记忆用户偏好。同类可对比的替代方案包括 MemGPT、Letta、LangMem。

上一篇：full-stack-ai-agent-template

下一篇：botpress