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:
- Sumarização em Prosa Destrói Restrições Negativas: A compactação otimiza para continuidade narrativa ("o que estamos construindo agora"), podando agressivamente "o que rejeitamos e por quê". Sem restrições negativas explícitas, a distribuição a priori do modelo o puxa de volta para o padrão rejeitado.
- Arquivos Markdown Planos Sofrem Deriva Temporal: Despejar notas em
CLAUDE.mdou scratchpads planos não possui validade temporal. Um invariante do protótipo de terça-feira convive lado a lado com a regra de produção de quinta-feira sem distinção entre verdade ativa e histórico superado. - Zero Verificação Estrutural na Fronteira do Turno: Mesmo quando uma restrição sobrevive no prompt de sistema, nada valida o código gravado em disco contra o contrato arquitetural antes de o turno ser concluído.
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.
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:
valid_from: O commit lógico, migração ou timestamp em que uma restrição passou a valer no repositório.valid_until:NULLenquanto a restrição está ativa; preenchido no instante em que uma nova decisão a substitui (nunca apagado).recorded_at: O timestamp imutável de transação de quando o agente gravou o fato, permitindo auditorias com viagem no tempo ("no que o agente acreditava às 14:20?").
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
/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.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.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.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.