Magic Context
Persistent context management and cross-session project memory for OpenCode and Pi coding agents.
- Source repo
- cortexkit/magic-context
- Stars
- ★ 2.5k
- Last updated
- today
- License
- MIT
- Primary language
- TypeScript
- FA score
- 54/100 · Major gaps
At a glance
- How it runs
- Works with
- Platform-specific
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- An OpenCode developer maintaining one codebase over weeks or months who wants architectural decisions and project constraints to persist between sessions.
- Not a fit if
- Teams on ChatGPT, Codex, or Claude Code only; no native integration is documented
- Docker, CI, or disposable-container users without a mounted persistent volume; memory won't accumulate
- Source review
- 54/100 · Major gaps
What does this agent do, and when should you use it?
Magic Context is CortexKit's context-management and long-term-memory plugin for OpenCode and Pi coding agents. A background historian compresses older conversation into importance-tiered compartments and renders them deterministically for the available context window, instead of relying on host compaction. It promotes decisions, constraints, and conventions into project memory, while an optional dreamer can verify, curate, and maintain memories and documentation during idle time. Agents can operate on history, memory, and deferred work through ctx_search, ctx_expand, ctx_memory, ctx_note, and ctx_reduce. Durable state is stored in a local SQLite database, which the companion desktop app reads directly for browsing and management.
On each turn, the plugin injects active project memories and compacted session history in a cache-stable layout; optional automatic search runs a background ctx_search and appends compact relevance hints. Its background historian reads older history, creates chronological compartments with importance scores, and extracts PROJECT_RULES, ARCHITECTURE, CONSTRAINTS, CONFIG_VALUES, and NAMING memories. An agent can use ctx_reduce to queue stale content for removal, ctx_memory to write or delete memories, ctx_expand to restore compressed transcript ranges, and ctx_search across memories, conversation history, optionally indexed Git commits, notes, and primers. The optional dreamer creates ephemeral child sessions during idle time for mapping, verification, curation, classification, retrospectives, documentation maintenance, and smart-note processing; /ctx-dream triggers it on demand. State is written to context.db in the shared CortexKit store, while the desktop app exposes memories, sessions, cache diagnostics, dreamer runs, configuration, and logs from that SQLite database.
- An OpenCode developer maintaining one codebase over weeks or months who wants architectural decisions and project constraints to persist between sessions.
- A team moving between Pi and OpenCode that wants project memories and embeddings shared by both harnesses.
- A developer whose long coding conversations are disrupted by context compaction and who wants the historian to manage history in the background.
- A maintainer of a changing codebase who wants the dreamer to map memories to files and incrementally verify them during idle time.
- An engineer investigating why a design choice was made who wants ctx_search across project memories, conversation history, and optional Git-commit indexing.
How do you install or deploy this 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
Any OS: npx @cortexkit/magic-context@latest setupThe setup wizard detects OpenCode and Pi, adds the plugin, disables built-in compaction, and helps select historian, dreamer, and sidekick models. Use --harness opencode or --harness pi to target one harness; Pi requires >= 0.74.0. No separate credentials are documented. For manual OpenCode setup, add "@cortexkit/opencode-magic-context" to opencode.json and set compaction.auto and compaction.prune to false.
How do you use this agent?
Restart OpenCode or Pi after setup. Magic Context captures context from that point onward and does not backfill prior sessions. Run npx @cortexkit/magic-context@latest doctor to check the plugin, conflicts, TUI sidebar, and database integrity, and to fix issues it can fix. In a session, use /ctx-status for context diagnostics, /ctx-dream for on-demand memory maintenance, /ctx-recomp to rebuild history compartments, and /ctx-wrapup [messages_to_keep] to compact older live history. Put project configuration in <project-root>/.cortexkit/magic-context.jsonc, with user-wide defaults in ~/.config/cortexkit/magic-context.jsonc.
What are this agent's strengths and limitations?
- Combines historian compartments, deterministic decay rendering, and cache-aware deferred operations to manage context without ordinary compaction pauses.
- Extracts project memory from history compression and provides explicit ctx_memory, ctx_search, ctx_expand, ctx_note, and ctx_reduce interfaces.
- OpenCode and Pi share one database, allowing project memories and embeddings to be reused across both harnesses.
- The optional dreamer can verify, deduplicate, and classify memories during idle time, and maintain ARCHITECTURE.md and STRUCTURE.md.
- A desktop app reads the local SQLite database directly to manage memories, sessions, and cache diagnostics without an additional server or API.
- The documented harnesses are OpenCode and Pi only; the source provides no native integration evidence for ChatGPT, Codex, Claude Code, or their APIs.
- It conflicts with OpenCode built-in compaction, opencode-dcp, and certain oh-my-opencode hooks; it disables itself fail-safe until conflicts are resolved.
- Long-term memory and history depend on a persistent local context.db; Docker, CI, and disposable containers need a mounted persistent volume or memory will not accumulate.
- The default local embedding path downloads an approximately 90 MB Xenova/all-MiniLM-L6-v2 ONNX model on first use; memory can instead be disabled or configured with a remote embedding backend.
- Dream execution requires a live OpenCode server because the dreamer creates ephemeral child sessions.
How does this agent compare with similar options?
Magic Context replaces OpenCode's built-in compaction and requires compaction.auto and compaction.prune to be disabled. It cannot run alongside opencode-dcp; for oh-my-opencode, setup can disable the overlapping preemptive-compaction, context-window-monitor, and anthropic-context-window-limit-recovery hooks.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Magic Context This agent | 54 · Major gaps | CLIFree + model costs | ★ 2.5k | today | TypeScript | — |
| Mnemo Cortex | 75 · Good | Self-hosted serviceFree | ★ 159 | 1d ago | Python | Codex · Claude Code · Claude.ai |
| myc Local Agent Memory | 87 · Good | CLIFree | ★ 14 | 19d ago | TypeScript | Codex · Claude Code |
| Remnic Agent Memory | 85 · Good | CLIFree + model costs | ★ 233 | 1d ago | TypeScript | ChatGPT · Codex · Claude Code · OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: The plugin requires access to project files, git history, SQLite database, and may call external model APIs. README explains data storage locations and purposes, but does not explicitly state least-privilege principles. User confirmation: installation and configuration require user action, but no confirmation mechanism for critical operations (e.g., memory deletion) is mentioned. Data flow transparency is good; README details data flow and storage. Sensitive data handling: no explicit statement on handling API keys or user data. Dependency security: uses npm packages and Rust crates, but no dependency audit or vulnerability scanning evidence. External effects: plugin modifies config files, disables compaction, and may run background processes, but README explains. Rollback: provides `/ctx-recomp` and `/ctx-session-upgrade` commands, but no explicit rollback mechanism. Source attribution: MIT license and copyright notice exist, but publisher is unverified.
Evidence shows: README and test files describe a consistent architecture and behavior, but no complete error handling documentation. Dependency availability: depends on external services (e.g., model APIs) and local database, but no degradation strategy for dependency failures. Failure messages: README mentions `doctor` command and fail-safe mechanism, but no detailed error message examples.
Evidence shows: README targets coding agent users, provides multiple usage scenarios (OpenCode, Pi, desktop app). Capability boundaries: clearly explains conflicts with other plugins (e.g., DCP, OMO) and disabling mechanisms. Trigger precision: describes trigger conditions for tools like `ctx_reduce`, `ctx_memory`. Environment fit: supports macOS, Linux, Windows, and provides usage instructions for Docker and CI environments.
Evidence shows: README is well-structured, providing installation, configuration, usage, and development guides. Install notes are detailed, including curl, PowerShell, and npx methods. Naming stability: tool and command names are consistent in README. Examples and FAQ: provides tool usage examples, but no FAQ. Known limitations: not all limitations are explicitly listed, but conflicts with other plugins are mentioned. License is MIT, copyright notice exists. Versioning/changelog: no CHANGELOG file, but README mentions migration notes. Maintenance responsibility: no explicit maintainer or contribution guide, but Discord and GitHub links are provided.
Evidence shows: Output usability: plugin provides tools and commands with clear output formats. Marginal value: solves context management and memory issues, providing clear value. Cost-benefit: README mentions using cache and local models to reduce costs, but no specific data.
Evidence shows: Some claims in README are supported by tests (e.g., cache stability tests), but not all claims are traceable. Cross-source corroboration: no independent verification. Fact-inference separation: README distinguishes feature descriptions and performance claims, but not explicitly labeled.
- Publisher identity is unverified; proceed with caution.
- Plugin modifies config files and disables compaction, which may affect other tools.
- Depends on external model APIs and local database; ensure data security.
- No complete error handling documentation or rollback mechanism provided.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/magic-context)<a href="https://followagents.com/en/agents/magic-context"><img src="https://followagents.com/badge/magic-context.svg" alt="FARS review"></a>Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
v0.49.36 This patch fixes a set of OpenCode 2 compaction problems (empty and missed folds, a manual /compact that reclaimed nothing, per-pass work that grew with the session), unblocks long OpenCode sessions that refused every turn on compaction markers, lets emergency recovery work after provider overflows it didn't recognize, keeps the prompt cache intact after a restart and around replies with signed thinking, and fixes several Pi, Oh My Pi and dreamer issues. Upgrading - Restart OpenCode or Pi after updating. No database migration is needed. Fixed OpenCode 2 …View on GitHub ↗ -
Release notes excerpt
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 …View on GitHub ↗ -
dashboard-v0.20.23 Dashboard dashboard-v0.20.23
Release notes excerpt
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.View on GitHub ↗