---
## O que é Magic Context?
Você não contrata um desenvolvedor para corrigir um único bug e o demite no momento em que a correção é publicada. Os bons você mantém. Eles aprendem a base de código, lembram por que as decisões foram tomadas e ficam mais afiados toda semana.
Agentes de programação funcionam do jeito oposto. Cada tarefa é uma nova contratação sem memória do seu projeto, e no fim de cada sessão você a demite e começa do zero. No meio da tarefa eles ainda encontram pausas de "compaction" que quebram o fluxo e deixam cair silenciosamente o que sabiam. É amnésia anterógrada, a mesma coisa que acontece quando o hipocampo é danificado.
Magic Context dá um a eles. É o **hipocampo** para agentes de programação, a parte do cérebro que forma memórias, as consolida e as recupera, inteiramente em segundo plano. Uma sessão deixa de ser um contratado descartável e vira um colega de equipe de longo prazo que esteve presente durante todo o projeto:
- **Captura.** Enquanto o historian comprime seu histórico, ele eleva o conhecimento durável (decisões, restrições, convenções) para a memória do projeto. Você ganha um sistema de memória de graça, a partir do trabalho que já está fazendo.
- **Consolidação.** Durante a noite, agentes dreamer fazem o que o sono faz por você: verificam memórias contra a base de código, organizam duplicatas e entradas obsoletas, e promovem o que se repete.
- **Recuperação.** As memórias certas aparecem automaticamente a cada turno, e o agente pode procurar em memórias, conversas passadas e histórico git sob demanda. Entre sessões, e entre OpenCode e Pi.
Duas promessas: seu agente **nunca para para gerenciar seu contexto** (sem pausas de compaction, sem fluxo quebrado) e **nunca esquece**.
Execute uma sessão por projeto e mantenha-a por semanas, meses ou anos. Ela lembra tudo que vocês construíram juntos.
---
## Início rápido
Execute o assistente interativo de configuração. Ele detecta seus modelos, configura tudo e cuida da compatibilidade.
**macOS / Linux:**
```bash
curl -fsSL https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.sh | bash
```
**Windows (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/cortexkit/magic-context/master/scripts/install.ps1 | iex
```
**Ou execute diretamente (qualquer OS):**
```bash
npx @cortexkit/magic-context@latest setup
```
O assistente detecta automaticamente quais harnesses você tem (OpenCode, Pi ou ambos), adiciona o plugin, desativa a compaction integrada, ajuda você a escolher modelos para historian e dreamer, e resolve conflitos com outros plugins de gerenciamento de contexto. Aponte para um harness específico com `--harness opencode` ou `--harness pi`.
> **Por que desativar a compaction integrada?** Magic Context gerencia o contexto por conta própria. A compaction do host interferiria nas operações adiadas conscientes de cache e comprimiria duas vezes.
**Configuração manual** (OpenCode): adicione o plugin e desligue a compaction em `opencode.json`, depois coloque um `magic-context.jsonc` em `/.cortexkit/` (ou `~/.config/cortexkit/` para padrões de usuário). Veja a [referência de configuração](./CONFIGURATION.md).
```jsonc
{
"plugin": ["@cortexkit/opencode-magic-context"],
"compaction": { "auto": false, "prune": false }
}
```
**Pi:** `npx @cortexkit/magic-context@latest setup --harness pi` (requer Pi `>= 0.74.0`). A extensão Pi compartilha o mesmo banco de dados que o OpenCode; memórias do projeto e embeddings se agrupam entre ambos.
**Solução de problemas:** `npx @cortexkit/magic-context@latest doctor` detecta seus harnesses automaticamente, verifica conflitos (compaction, OMO hooks, DCP), valida o plugin e a barra lateral TUI, executa uma checagem de integridade no banco de dados e corrige o que puder. Adicione `--issue` para criar um relatório de bug pronto para enviar.
Funciona igual em um projeto novo ou antigo: instale, reinicie o harness, e o Magic Context captura contexto a partir desse ponto. Ele não preenche sessões OpenCode ou Pi anteriores à instalação.
Compatibilidade com outros plugins de gerenciamento de contexto
Magic Context possui o gerenciamento de contexto de ponta a ponta, então **se desativa** se outro plugin já estiver fazendo esse trabalho. Dois gerenciadores de contexto ao mesmo tempo comprimiriam seu histórico duas vezes e bagunçariam o prompt cache. Na inicialização ele verifica o seguinte; setup e `doctor` ajudam a resolver cada item, e até que sejam resolvidos Magic Context fica desligado (fail-safe) e explica por quê:
- **OpenCode built-in compaction** (`compaction.auto` / `compaction.prune`): Magic Context a substitui. Setup a desliga.
- **DCP** (`opencode-dcp`): um plugin separado de poda de contexto. Os dois não podem rodar juntos; remova-o da sua lista `plugin`.
- **oh-my-opencode (OMO)**: setup oferece desativar os três hooks que se sobrepõem:
- `preemptive-compaction`: dispara compaction que conflita com historian.
- `context-window-monitor`: injeta avisos de uso que se sobrepõem aos nudges do Magic Context.
- `anthropic-context-window-limit-recovery`: dispara compaction de emergência que ignora historian.
Execute `npx @cortexkit/magic-context@latest doctor` a qualquer momento para verificar de novo e corrigir automaticamente.
---
## Parte do CortexKit
Um cérebro não é um único órgão. Um agente de programação capaz também não.
**CortexKit** é uma família de plugins, cada um modelado em uma região diferente do cérebro. Instale um e seu agente fica mais afiado. Instale os três e ele tem um cérebro.
| Plugin | Região | O que faz |
|---|---|---|
| **Magic Context** *(você está aqui)* | Hipocampo e lobo temporal medial | Contexto autogerenciado e memória de longo prazo. Mantém sessões em execução sem pausas de compaction enquanto forma, consolida e recupera conhecimento do projeto entre elas. |
| **[AFT](https://github.com/cortexkit/aft)** | Córtex sensório-motor | Percebe a estrutura do código e age sobre ela com precisão. Um IDE e OS de verdade para seu agente. |
| **Alfonso** *(em breve)* | Córtex pré-frontal | Controle executivo. Planeja, decompõe trabalho, escolhe agentes e modelos, e decide quando perguntar, verificar e commitar. |
Magic Context é **1 dos 3 plugins de que você vai precisar.** Ele lembra; AFT percebe e age; Alfonso decide. Eles compartilham um único armazenamento CortexKit, então a memória se agrupa entre harnesses e ferramentas.
---
## ⚡ Gerenciamento de contexto
*Uma sessão sem limites que se gerencia sozinha.* A janela de contexto se enche enquanto você trabalha, e a solução comum, compaction, para o agente para reler tudo. Magic Context cuida disso continuamente em segundo plano, então a sessão continua.
- **Compartimentalização historian**: um historian em segundo plano comprime histórico bruto antigo em **compartimentos em camadas**, resumos cronológicos que representam mensagens mais antigas. Cada um carrega uma pontuação de importância, então a janela ativa fica pequena sem perder o fio. Resumir não precisa da força de programação do agente principal, então você pode rodar historian em um modelo barato ou totalmente local enquanto o agente principal fica no topo.
- **Renderização por decaimento**: compartimentos são renderizados com a fidelidade certa para o momento, por uma regra determinística sem LLM que se ajusta à janela de contexto do modelo. O histórico antigo desaparece de forma suave em vez de cair de um penhasco, e como é determinístico, o mesmo histórico sempre renderiza igual.
- **O agente sugere o que descartar, ou não**: com redução guiada pelo agente ligada, o agente chama `ctx_reduce` para marcar saídas de ferramentas obsoletas ou mensagens longas para remoção. Os descartes são **enfileirados e conscientes de cache**, aplicados apenas em momentos seguros para cache, então a redução nunca desestabiliza o cache. Desligue isso e o agente fica totalmente fora do gerenciamento de contexto: saída obsoleta é removida automaticamente por idade, com compressão caveman opcional do texto mais antigo.
- **Layout estável para cache**: tudo isso é estruturado para que trabalho em segundo plano nunca invalide o prefixo cacheado do seu prompt. Seu cache sobrevive à sessão inteira.
O resultado: uma sessão roda por meses, sem pausas de compaction e com baixo custo em provedores com preço por cache. Você pode ver isso na TUI do OpenCode, onde uma barra lateral ao vivo mostra a divisão do contexto por fonte, status do historian e contagens de memória, atualizando após cada mensagem.
> *Opcional (desligado por padrão):* **caveman text compression** comprime progressivamente o texto mais antigo de user e assistant por uma regra determinística por idade, para sessões que rodam com redução guiada pelo agente desligada.
---
## 🧠 Captura
*Memória, de graça.* Para comprimir seu histórico, historian precisa ler tudo. Então, na mesma passagem, ele extrai o conhecimento que vale guardar para sempre, decisões, restrições, convenções, valores de configuração, e o promove para **memória do projeto**, categorizada e levada a cada sessão futura. Sua memória se constrói sozinha a partir do trabalho que você já faz.
O agente também pode registrar memórias explicitamente, embora a maioria seja capturada automaticamente para ele:
- **`ctx_memory`**: escreva ou apague conhecimento entre sessões diretamente, em uma pequena taxonomia de categorias (`PROJECT_RULES`, `ARCHITECTURE`, `CONSTRAINTS`, `CONFIG_VALUES`, `NAMING`).
```
ctx_memory(action="write", category="ARCHITECTURE", content="Event sourcing for orders.")
```
> **Consciência temporal** *(ligada por padrão)* dá ao agente uma noção de tempo, com marcadores de intervalo como `+2h 15m` entre mensagens e compartimentos datados, para que ele raciocine sobre há quanto tempo algo aconteceu. Defina `temporal_awareness: false` para desligar.
---
## 🌙 Consolidação
*O que o sono faz pela memória.* Um agente **dreamer** opcional roda durante a noite para manter a qualidade da memória alta, criando sessões filhas efêmeras para cada tarefa:
- **Verificar**: checar memórias incrementalmente contra a codebase atual (caminhos, configs, padrões) e corrigir ou remover fatos obsoletos.
- **Curar**: varrer todo o pool de memória para mesclar duplicatas, apertar redação e arquivar entradas de baixo valor ou redundantes.
- **Classificar**: pontuar a importância, escopo e compartilhamento seguro de cada memória sem perturbar o prompt cache ativo.
- **Manter docs**: manter `ARCHITECTURE.md` e `STRUCTURE.md` atualizados a partir de mudanças na codebase.
- **Memórias de usuário**: promover observações recorrentes sobre como você trabalha (estilo de comunicação, foco de review, padrões de trabalho) para um `` que viaja com cada sessão.
- **Smart notes**: avaliar notas adiadas cujo `surface_condition` se tornou verdadeiro e mostrar as prontas.
Como roda em tempo ocioso, dreamer combina bem com modelos locais, mesmo lentos. Ninguém fica esperando. Dispare uma execução a qualquer momento com `/ctx-dream`.
---
## 🔎 Recuperação
*A memória certa no momento certo.* A cada turno, memórias ativas do projeto e histórico de sessão compactado são injetados automaticamente e de forma estável para cache. Sob demanda, o agente usa:
- **`ctx_search`**: uma consulta em três camadas ao mesmo tempo: **memories** do projeto, histórico bruto de **conversation** e **git commits** indexados. Semantic embeddings com fallback de texto completo.
```
ctx_search(query="why did we pick event sourcing for orders")
```
- **`ctx_expand`**: trazer um intervalo de histórico comprimido de volta ao transcript original `U:`/`A:` quando o agente precisa dos detalhes exatos.
- **`ctx_note`**: um scratchpad para intenções adiadas. Notas reaparecem em limites naturais (depois de commits, depois de execuções de historian, quando todos terminam). **Smart notes** carregam uma condição em aberto que dreamer observa.
A recuperação funciona **entre sessões** (uma nova sessão herda tudo) e **entre harnesses** (escreva uma memória no OpenCode, recupere-a no Pi).
> **Dicas de busca automática** *(ligadas por padrão)* rodam um `ctx_search` em segundo plano a cada turno e sussurram uma "lembrança vaga" quando algo relevante existe, como quase lembrar uma nota que você fez. Só adiciona fragmentos compactos, nunca conteúdo completo; defina `memory.auto_search.enabled: false` para desligar. **Indexação de git commits** *(opt-in)* torna o histórico do projeto semanticamente pesquisável como uma quarta fonte de `ctx_search`, habilite com `memory.git_commit_indexing.enabled: true`.
### Ferramentas do agente em resumo
| Ferramenta | Seção | O que faz |
|------|-------|-------------|
| `ctx_reduce` | Contexto | Enfileira conteúdo marcado obsoleto para remoção, consciente de cache |
| `ctx_memory` | Captura | Escreve ou apaga memórias duráveis entre sessões |
| `ctx_search` | Recuperação | Pesquisa memórias, histórico de conversa e git commits |
| `ctx_expand` | Recuperação | Descomprime um intervalo de histórico de volta ao transcript |
| `ctx_note` | Recuperação | Intenções adiadas e smart notes avaliadas por dreamer |
---
## Comandos
| Comando | Descrição |
|---------|-------------|
| `/ctx-status` | Visão de debug: tags, pending drops, cache TTL, estado de nudge, progresso do historian, cobertura de compartimentos, orçamento de histórico |
| `/ctx-flush` | Forçar todas as operações enfileiradas imediatamente, ignorando cache TTL |
| `/ctx-recomp` | Reconstruir compartimentos a partir do histórico bruto (aceita um intervalo `start-end`). Use quando o estado armazenado parecer errado |
| `/ctx-dream` | Executar manutenção dreamer sob demanda: manter memória, docs, smart notes e revisão de user-profile |
---
## Aplicativo desktop
Um aplicativo desktop companheiro para navegar e gerenciar o estado do Magic Context fora do terminal.
- **Navegador de memória**: pesquise, filtre e edite memórias do projeto por categoria e projeto.
- **Histórico de sessão**: navegue por compartimentos e notas de qualquer sessão com navegação em linha do tempo.
- **Diagnóstico de cache**: linha do tempo em tempo real de cache hit/miss e detecção de causas de bust.
- **Gerenciamento dreamer**: veja histórico de dream-run, dispare execuções, inspecione resultados de tarefas.
- **Editor de configuração**: edição por formulário para cada configuração, incluindo cadeias de fallback de modelos.
- **Visualizador de logs**: live-tailing logs com busca.
Ele lê diretamente do banco SQLite do Magic Context. Sem servidor extra, sem API. Autoatualizações integradas.
---
## Configuração
As configurações ficam em `magic-context.jsonc`. Tudo tem padrões sensatos; a configuração do projeto é mesclada sobre as configurações de usuário. Para a referência completa, ajuste de cache TTL, limites execute por modelo, seleção de modelos historian e dreamer, provedores de embeddings e configurações de memória, veja **[CONFIGURATION.md](./CONFIGURATION.md)** ou a **[referência de configuração em docs.cortexkit.io](https://docs.cortexkit.io/magic-context/reference/configuration/)**.
**Locais de configuração** (um local CortexKit compartilhado, projeto sobrescreve usuário):
1. `/.cortexkit/magic-context.jsonc`
2. `~/.config/cortexkit/magic-context.jsonc`
Atualizando de uma versão anterior? Sua configuração existente é movida para cá automaticamente na primeira execução (um rastro `.MOVED_READPLEASE` fica no caminho antigo).
---
## Armazenamento
Todo estado durável vive em um banco SQLite local sob o armazenamento CortexKit compartilhado (`~/.local/share/cortexkit/magic-context/context.db`, equivalente XDG no Windows; bancos legados em pastas OpenCode são migrados no primeiro boot). Se o banco não puder ser aberto, Magic Context se desativa e avisa você. Memórias são chaveadas para uma **identidade estável de projeto** derivada do repo, então acompanham um projeto entre worktrees, clones e forks em vez de ficarem presas a um caminho de diretório.
Magic Context também escreve em alguns outros locais:
| Caminho | O quê | Persistência |
|---|---|---|
| `~/.local/share/cortexkit/magic-context/context.db` | Banco SQLite, tags, compartimentos, memórias, todo estado durável (equivalente XDG no Windows) | **Deve persistir.** Perdê-lo perde sua memória/histórico. |
| `~/.local/share/cortexkit/magic-context/models/` | Cache local do modelo de embeddings (~90 MB `Xenova/all-MiniLM-L6-v2` ONNX), baixado no primeiro uso quando embeddings locais estão habilitados | Deve persistir, senão será baixado de novo a cada execução. Não é usado quando `memory.enabled: false` ou um backend de embeddings `openai_compatible`/`ollama` está configurado. |
| `${TMPDIR}/opencode/magic-context/magic-context.log` (`pi/` for Pi) | Log de diagnóstico | Descartável. |
**Ambientes sandbox / efêmeros (Docker, CI, contêineres descartáveis):** monte o diretório `~/.local/share/cortexkit/magic-context/` em um volume persistente para que o banco e o cache do modelo sobrevivam entre execuções. Se só o cache do modelo for efêmero, o modelo apenas será baixado de novo; se o banco for efêmero, memória e histórico não se acumulam. Para evitar completamente o download do modelo de ~90 MB, defina `memory.enabled: false` ou aponte `embedding` para um backend remoto `openai_compatible`/`ollama`.
---
## Histórico de estrelas
---
## Desenvolvimento
**Requisitos:** [Bun](https://bun.sh) ≥ 1.0
```sh
bun install # Install dependencies
bun run build # Build the plugin
bun run typecheck # Type-check without emitting
bun test # Run tests
bun run lint # Lint (Biome)
bun run format # Format (Biome)
```
A execução de Dream requer um servidor OpenCode ativo (dreamer cria sessões filhas efêmeras). Use `/ctx-dream` dentro do OpenCode para manutenção sob demanda.
---
## Contribuição
Bug reports e pull requests são bem-vindos. Para mudanças maiores, abra primeiro uma issue para discutir a abordagem. Execute `bun run format` antes de enviar; CI rejeita código sem formatação.
---
## Licença
[MIT](LICENSE)
