muri-saver

Português  ·  English

Instalar  ·  Arquitetura  ·  Cadeia de LLMs  ·  Nota viva  ·  Referência  ·  Versões

Kit de governança, memória e registro para agentes de código. Gasta menos cota, não deixa o contexto evaporar entre sessões e transforma cada sessão numa nota legível no Obsidian. Funciona no Claude Code, no Codex e no Antigravity, em macOS, Linux e Windows, com um instalador em Node e nenhuma dependência.

[!NOTE]
Os números deste README vêm do uso real do autor e servem de diagnóstico, não de benchmark. Meça a sua rotina com muri-saver report e muri-saver audit. As capturas do vault usam dados fictícios de examples/vault/.

Por que existe

Quem usa agente de código todo dia esbarra em três problemas: a cota acaba sem você entender por quê, o contexto evapora entre sessões e não sobra nenhum registro legível do que foi feito.

O muri-saver nasceu de auditar transcripts reais. Uma sessão sozinha gastou 2,1 bilhões de tokens de cache em 42 horas; um arquivo foi relido 54 vezes na mesma sessão; a automação de navegador tirou 501 screenshots onde 3 leituras de texto bastavam. Cada regra do kit responde a um desses achados, e o resto roda sozinho em hooks, sem você precisar lembrar.

Em 90 segundos

https://github.com/user-attachments/assets/c69dbadb-41bb-4152-825b-ace8e280813f

_{Sem narração. Se o player não carregar, abra o vídeo. Telas de terminal marcadas como simulação usam as cores, os limites e os textos dos scripts reais.}

Status line: contexto, cache e cotas num relance	Guarda de contexto: segura a retomada cara	/compact na hora certa: 218k → 34k
Memória: a sessão nova sabe de onde parou	Skills e conectores sob demanda	Onde a cota vai: 71% acima de 250k

O que você vê no terminal

• Status line: o contexto muda de cor pelos tokens (amarelo em 120k, vermelho em 200k), mostra quanto falta para o cache esfriar e as cotas de 5 horas e 7 dias com contagem regressiva.
• Guarda de contexto: depois de 55 minutos parado com mais de 80k de contexto, segura uma vez o próximo prompt, porque a retomada regravaria o cache inteiro. Em 120k, 160k e 200k, lembra a hora de abrir sessão nova. MURI_GUARDA=0 desliga.
• Notificação: alerta no desktop quando o Claude está esperando você (macOS e Linux). MURI_NOTIFY=0 desliga.
• Skill muri-saver: diga "muri saver" e o agente entra no modo de economia agressiva: não reler, paralelizar, perfil por tarefa e sessões curtas.

O que fica registrado

1. Cada turno grava um dump local da sessão no seu vault, na hora, sem esperar modelo nenhum.
2. A cada 15 minutos, um processo à parte escreve a narrativa: síntese, decisões, ações e arquivos.
3. No fim da sessão, a narrativa ganha a versão final e entra no Daily do dia, junto com as sessões dos outros agentes.
4. O ai-memory consolida a sessão em páginas pesquisáveis, e a próxima sessão começa sabendo de onde parou.
5. Segredos são mascarados antes de qualquer gravação e antes de o texto ir para o modelo: uma chave colada vira [REDACTED:ANTHROPIC_KEY].

A narrativa e a consolidação usam uma cadeia de modelos que troca sozinha quando um bate no limite. Nenhum padrão usa a cota do Claude.

A nota viva em detalhe →

Onde a cota vai

Trinta dias de uso medidos turno a turno mostraram que o problema não é a escolha de modelo, é o tamanho do contexto. Os turnos acima de 250k foram metade dos turnos e 71% do gasto, porque cada um custa cerca de 2,5 vezes um turno de 100 a 150k. Na mesma análise, 64 retomadas com o cache já frio custaram 33,5 milhões de tokens-eq, perto de 11 pontos da cota semanal no mês.

Daí a status line colorida por tokens, o guarda de contexto e o autoCompactWindow de 250k recomendado no settings.snippet.json.

Os achados

Cada número virou uma regra curta na governança: memória antes de reler, texto antes de screenshot, confirmação antes de loop, sessão nova antes de maratona.

[!IMPORTANT]
Os hooks rodam em todo turno, então precisam ser baratos: nenhum passa de 150 ms. O Stop nunca espera um modelo; a narrativa roda num processo destacado.

Instalar

git clone https://github.com/murilolol/muri-saver.git
cd muri-saver
node bin/install.mjs --dry-run      # mostra o que faria, não escreve nada
node bin/install.mjs --with-all     # Claude Code + Codex + Antigravity
node bin/doctor.mjs                 # confere tudo, só leitura

Sem clonar: npx github:murilolol/muri-saver install --with-all. Depois, ligue o que quiser:

node bin/install.mjs --update --vault "/caminho/do/seu/vault"   # toda sessão vira nota no Obsidian
npx muri-saver llm chain && npx muri-saver llm tune              # ai-memory pela cadeia de modelos
node bin/install.mjs --update --with-jobs                         # jobs de fundo

Abra uma sessão nova e diga muri-saver: revise este projeto gastando menos contexto. O ai-memory é um programa à parte (como instalar); o Obsidian é opcional. Vai instalar com ajuda de uma IA? Mande o link deste repositório e peça para seguir o INSTALL-AI.md.

Configurações existentes são mescladas, nunca substituídas; o que o instalador sobrescreve ganha backup, e o --uninstall remove só o que você não editou. Passo a passo →  ·  Todas as opções →

O que vem junto

Como funciona

Os três agentes carregam a mesma governança. Os hooks de ciclo de vida (SessionStart, UserPromptSubmit, Stop, SessionEnd) alimentam o ai-memory e o vault a cada turno; o ingestor importa o histórico antigo de cada agente sem gastar modelo.

sequenceDiagram
    participant U as Voce
    participant A as Agente
    participant H as Hooks
    participant W as Worker
    participant L as Cadeia de LLMs
    participant M as ai-memory
    participant V as Obsidian

    U->>A: abre a sessao
    A->>H: SessionStart
    H->>M: sobe o servidor e o shim, entrega o handoff
    U->>A: trabalha
    A->>H: Stop (a cada turno)
    H->>V: dump local da nota e linha no Daily
    H-->>W: a cada 15 min de sessao, dispara o worker
    W->>L: transcript sem segredos
    L-->>W: narrativa (agy, Gemini API...)
    W->>V: bloco de narrativa, taxonomia, canvas
    A->>H: SessionEnd
    H-->>W: versao final da narrativa
    M->>L: consolida a sessao em paginas (via shim)

Se a cadeia inteira estiver em cooldown, a nota fica com o dump e ganha a narrativa depois: no próximo intervalo, no SessionEnd ou no job de backfill.

A arquitetura em detalhe →

Versões

Do kit de regras soltas à guarda de contexto. O detalhe de cada uma está no histórico de versões.

Tecnologia

Node.js 18 ou mais novo, só com a biblioteca padrão, e scripts auxiliares em Python e shell. Memória no ai-memory (SQLite com busca FTS5 e servidor MCP local). Jobs no launchd, no systemd --user ou crontab e no Agendador de Tarefas do Windows. 93 testes com node:test, rodando numa home temporária com binários falsos: nenhum teste toca a sua configuração nem chama um modelo.

Documentação

Contribuindo e créditos

Contribuições são bem-vindas: veja o CONTRIBUTING.md e as issues. Licença MIT (LICENSE). Feito por @murilolol a partir do uso diário real; muri-saver e grill-me são conteúdo original. O ai-memory é de Fabio Akita, e as skills companheiras são dos respectivos autores.

_{O banner, o gráfico e o cartão dos achados são gerados a partir de assets/readme/dados.json com tools/build-readme.mjs. O mascote é o Pavio, do vídeo de apresentação. Se isso te economizou cota ou uma tarde de contexto perdido, uma ⭐ ajuda outra pessoa a achar.}