Por que o Claude Code Perde Contexto Após /compact (E Como Memória em Grafo Bitemporal + AST Drift Locks Resolvem Isso)

Um mergulho arquitetural profundo sobre por que sessões longas de agentes de código sofrem amnésia de contexto após /compact ou /clear, e como o Benni-OS/claude-code-sovereign injeta um grafo de conhecimento bitemporal local via MCP somado a um AST Reality Lock no hook Stop para que invariantes sobrevivam a toda compactação.

Por que o Claude Code Perde Contexto Após /compact: Memória em Grafo Bitemporal e AST Drift Locks

1. O Penhasco da Amnésia Pós-Compactação

Todo engenheiro que conduz sessões longas de refatoração ou construção de features no Claude Code bate exatamente no mesmo penhasco por volta do turno 40. O medidor de contexto passa de 85%, você executa /compact (ou a autocompactação dispara), e nos três turnos seguintes tudo parece normal — até que o agente reintroduz silenciosamente um padrão de ORM que você baniu explicitamente há 25 minutos, altera um schema de resposta congelado da API ou tenta novamente uma estratégia de lock no Redis que já provou causar deadlock sob carga.

Isso não é um problema de inteligência do modelo. É um problema de compressão com perdas e representação de estado:

Tese Central: A compactação deve comprimir prosa conversacional, nunca verdade arquitetural. O Benni-OS/claude-code-sovereign desacopla a memória de trabalho da memória estrutural ao armazenar invariantes, contratos de schema e alternativas rejeitadas em um grafo de conhecimento bitemporal local exposto via MCP, pareado com um AST Reality Lock determinístico no hook Stop.

2. Arquitetura: Grafo MCP Bitemporal + AST Reality Lock no Hook Stop

Para sobreviver tanto a /compact quanto a /clear sem inflar o consumo de tokens, o claude-code-sovereign separa o que é verdadeiro hoje no repositório de quando o agente observou ou substituiu essa verdade. Cada decisão arquitetural é gravada como uma aresta ou nó tipado com três timestamps: valid_from, valid_until e recorded_at.

flowchart LR A["Turno no Claude Code\n(/compact ou /clear)"] -->|"Hook PreCompact / SessionStart"| B["Servidor MCP de Memória\n(Grafo Bitemporal SQLite)"] B -->|"Query: valid_until IS NULL\n(< 1.2ms local)"| C["Invariantes Ativos + Alts Rejeitadas\nInjetados como Contexto Compacto"] C --> D["Geração de Código\n(Edições e Tool Calls)"] D -->|"Fim do Turno"| E["Hook Stop: AST Reality Lock\n(Tree-sitter / Python ast)"] E -->|"0 Violações de Deriva"| F["Turno Aceito\n(Commit / Próximo Passo)"] E -->|"Violação de Contrato"| G["Bloqueia Stop e Devolve\nDiff AST Exato ao Agente"]

Observe o ciclo fechado de feedback. Mesmo após um /clear completo, o servidor MCP reidrata apenas o subgrafo atualmente válido (valid_until IS NULL) em menos de 1.2 ms — cerca de 350 a 600 tokens de fatos estruturais de alta densidade em vez de 40.000 tokens de histórico obsoleto. Em seguida, antes de o Claude Code devolver o controle a você, o hook Stop executa o AST Reality Lock sobre cada arquivo modificado.


3. O Schema Bitemporal: Por Que Três Timestamps Vencem Notas Planas

A maioria dos plugins de "memória para agentes" usa busca por similaridade vetorial sobre trechos de texto não estruturados. Busca vetorial é fundamentalmente inadequada para restrições de engenharia: se você busca "middleware de autenticação", a similaridade de cosseno recupera tanto a regra obsoleta de JWT em cookie quanto a regra atual de mTLS, deixando o LLM adivinhar qual ainda vale.

Um schema bitemporal resolve isso deterministicamente:

import sqlite3
from dataclasses import dataclass
from datetime import datetime, timezone
from typing import List, Optional


@dataclass(frozen=True)
class TemporalFact:
    subject: str
    predicate: str  # ex.: "MUST_USE", "FORBIDS", "REJECTED_ALT", "SCHEMA_LOCK"
    object_val: str
    rationale: str
    valid_from: str
    valid_until: Optional[str]
    recorded_at: str


class BiTemporalGraphStore:
    """Grafo bitemporal local em SQLite exposto ao Claude Code via stdio MCP."""

    def __init__(self, db_path: str = ".sovereign/memory.db"):
        self.conn = sqlite3.connect(db_path)
        self.conn.execute("""
            CREATE TABLE IF NOT EXISTS graph_facts (
                id INTEGER PRIMARY KEY AUTOINCREMENT,
                subject TEXT NOT NULL,
                predicate TEXT NOT NULL,
                object_val TEXT NOT NULL,
                rationale TEXT NOT NULL,
                valid_from TEXT NOT NULL,
                valid_until TEXT DEFAULT NULL,
                recorded_at TEXT NOT NULL
            )
        """)
        self.conn.execute(
            "CREATE INDEX IF NOT EXISTS idx_active ON graph_facts(subject, valid_until)"
        )
        self.conn.commit()

    def assert_fact(
        self,
        subject: str,
        predicate: str,
        object_val: str,
        rationale: str,
        supersedes_predicate: Optional[str] = None,
    ) -> None:
        now = datetime.now(timezone.utc).isoformat()
        with self.conn:
            if supersedes_predicate:
                self.conn.execute(
                    """
                    UPDATE graph_facts
                    SET valid_until = ?
                    WHERE subject = ? AND predicate = ? AND valid_until IS NULL
                    """,
                    (now, subject, supersedes_predicate),
                )
            self.conn.execute(
                """
                INSERT INTO graph_facts
                (subject, predicate, object_val, rationale, valid_from, valid_until, recorded_at)
                VALUES (?, ?, ?, ?, ?, NULL, ?)
                """,
                (subject, predicate, object_val, rationale, now, now),
            )

    def query_active_invariants(self, subject_prefix: str = "") -> List[TemporalFact]:
        """Retorna apenas restrições válidas (< 1.2ms) para injeção pós-/compact."""
        cur = self.conn.execute(
            """
            SELECT subject, predicate, object_val, rationale,
                   valid_from, valid_until, recorded_at
            FROM graph_facts
            WHERE valid_until IS NULL AND subject LIKE ?
            ORDER BY recorded_at ASC
            """,
            (f"{subject_prefix}%",),
        )
        return [TemporalFact(*row) for row in cur.fetchall()]

Repare como fatos REJECTED_ALT permanecem ativos (valid_until IS NULL) durante todo o ciclo de vida da feature. Quando o Claude Code executa /compact, o hook PreCompact ou SessionStart consulta query_active_invariants() e fixa todas as arestas FORBIDS e REJECTED_ALT na nova janela — impedindo que o agente desperdice 10 turnos redescobrindo por que um caminho foi descartado.


4. AST Reality Lock no Hook Stop: Deriva Silenciosa Zero

Injeção de memória sozinha é apenas consultiva; modelos ainda podem ignorar uma restrição durante edições complexas em múltiplos arquivos. Por isso o claude-code-sovereign combina o grafo MCP com um hook Stop determinístico que inspeciona a Árvore Sintática Abstrata (AST) real dos arquivos modificados antes de liberar a conclusão do turno.

Diferente de linters baseados em regex, um AST Reality Lock compreende imports, assinaturas de função, herança de classes e campos de schema. Abaixo está um AST Reality Lock mínimo em Python aplicado ao evento Stop do Claude Code:

import ast
import json
import subprocess
import sys
from pathlib import Path
from typing import Dict, List


def get_modified_python_files() -> List[Path]:
    res = subprocess.run(
        ["git", "diff", "--name-only", "HEAD"],
        capture_output=True,
        text=True,
        check=False,
    )
    return [Path(p) for p in res.stdout.splitlines() if p.endswith(".py") and Path(p).exists()]


def verify_ast_contracts(files: List[Path], forbidden_imports: Dict[str, str]) -> List[str]:
    violations: List[str] = []
    for path in files:
        tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
        for node in ast.walk(tree):
            if isinstance(node, ast.Import):
                for alias in node.names:
                    if alias.name in forbidden_imports:
                        violations.append(
                            f"{path}:{node.lineno} importa módulo proibido '{alias.name}' "
                            f"({forbidden_imports[alias.name]})"
                        )
            elif isinstance(node, ast.ImportFrom) and node.module:
                root_mod = node.module.split(".")[0]
                if root_mod in forbidden_imports:
                    violations.append(
                        f"{path}:{node.lineno} importa do módulo proibido '{root_mod}' "
                        f"({forbidden_imports[root_mod]})"
                    )
    return violations


if __name__ == "__main__":
    # Em produção, carregado dinamicamente do BiTemporalGraphStore (predicate='FORBIDS')
    active_bans = {
        "sqlalchemy": "REJECTED_ALT #12: O projeto usa asyncpg puro + contratos SQL tipados.",
        "pickle": "SECURITY_LOCK #04: Desserialização não confiável banida em todos os serviços.",
    }
    drift = verify_ast_contracts(get_modified_python_files(), active_bans)
    if drift:
        # Contrato do hook Stop do Claude Code: exit code 2 bloqueia a parada e devolve stderr ao modelo
        print(json.dumps({"decision": "block", "reason": "\n".join(drift)}), file=sys.stderr)
        sys.exit(2)

Quando o Claude Code tenta encerrar um turno após importar sqlalchemy acidentalmente depois de uma compactação, o hook Stop retorna código de saída 2, expõe o arquivo exato, a linha e a justificativa bitemporal (REJECTED_ALT #12), e força o agente a se autocorrigir antes mesmo que o operador humano veja o diff.


5. Comparação Arquitetural: /compact Padrão vs. CLAUDE.md Plano vs. claude-code-sovereign

Dimensão /compact Padrão CLAUDE.md Plano + RAG Vetorial Benni-OS/claude-code-sovereign
Restrições Negativas & Alts Rejeitadas Podadas na sumarização em prosa Perdidas em ruído de chunks / ranking Fixadas via Arestas Tipadas (REJECTED_ALT)
Substituição Temporal Nenhuma (névoa cronológica) Edição manual; chunks antigos e novos colidem Bitemporal (valid_from, valid_until, recorded_at)
Recuperação Pós-/clear 0% da memória de sessão mantida Exige re-injeção manual no prompt Reidratação Automática via MCP (< 2 ms)
Imposição Contra Deriva Apenas prompt (consultivo) Apenas prompt (consultivo) AST Reality Lock Determinístico no Hook Stop
Infraestrutura & Privacidade Estado de sessão na nuvem Frequentemente exige embeddings/vector DB em nuvem 100% SQLite Local + stdio MCP (Custo Zero de Nuvem)

6. Conectando o Ciclo Soberano em .claude/settings.json

Integrar o servidor MCP bitemporal e o AST Reality Lock no hook Stop exige zero alterações no binário do Claude Code. Basta conectar ambos no arquivo .claude/settings.json do repositório:

{
  "mcpServers": {
    "sovereign-memory": {
      "command": "python",
      "args": ["-m", "claude_code_sovereign.mcp_server", "--db", ".sovereign/memory.db"]
    }
  },
  "hooks": {
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python -m claude_code_sovereign.hooks.snapshot_invariants"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python -m claude_code_sovereign.hooks.ast_reality_lock"
          }
        ]
      }
    ]
  }
}

Com essa configuração ativa, cada /compact tira um snapshot das decisões vigentes, cada nova sessão consulta exclusivamente os invariantes não superados e cada turno concluído é verificado estruturalmente contra os contratos AST do repositório.

Torne o Claude Code Imune a Amnésia Pós-/compact

Clone o Benni-OS/claude-code-sovereign, conecte o servidor MCP bitemporal em SQLite local e imponha travas determinísticas de AST Reality Lock a cada turno.

Explorar Benni-OS/claude-code-sovereign no GitHub →

Perguntas Frequentes

Por que o Claude Code esquece decisões arquiteturais logo após o comando /compact?
O comando /compact substitui turnos brutos da conversa por um resumo em prosa com perdas para recuperar espaço na janela de contexto. Embora objetivos gerais sobrevivam, restrições negativas, alternativas rejeitadas e contratos exatos de schema são comprimidos, fazendo o modelo repropor designs descartados ou violar invariantes silenciosamente.
O que torna um grafo de conhecimento bitemporal (valid_from, valid_until, recorded_at)?
Um grafo bitemporal rastreia duas linhas do tempo independentes: tempo válido (valid_from e valid_until, indicando quando um fato ou restrição é verdadeiro no código) e tempo de transação (recorded_at, indicando quando o agente registrou ou substituiu o fato). Isso impede que regras obsoletas vazem para prompts atuais mantendo uma trilha de auditoria completa.
Como o AST Reality Lock no hook Stop evita a deriva arquitetural?
Antes de o Claude Code encerrar um turno, o hook Stop analisa os arquivos modificados em uma Árvore Sintática Abstrata (AST) e compara símbolos exportados, assinaturas de tipo e imports proibidos contra as restrições ativas no grafo bitemporal. Se detectar deriva, o hook bloqueia a conclusão e devolve a violação estrutural exata ao agente.
O claude-code-sovereign exige um banco vetorial externo na nuvem?
Não. O Benni-OS/claude-code-sovereign roda 100% localmente sobre SQLite e MCP via stdio, sem chamadas externas de API, sem vendor lock-in e com consultas em sub-milissegundos através de fronteiras de /compact e /clear.