MemoryGuard

Governança de memória MCP local-first para agentes de codificação com regras compartilhadas, deduplicação, auditoria, rollback e insights de tokens.

GitHub

Experimente este MCPPatrocinado

Documentação

MemoryGuard

Memória compartilhada governada para agentes de codificação.
Memória MCP local-first com organização automática, regras com escopo, evidências e rollback.

中文文档

Deixe os agentes escreverem sem transformar a memória compartilhada em uma pilha não revisada. O MemoryGuard organiza cada escrita, preserva as evidências por trás das mudanças e mantém as decisões de governança reversíveis.

Sem conta. Sem servidor remoto. Sem telemetria remota. A telemetria de uso local é opcional e armazena agregados limitados e que preservam a privacidade localmente.

Início rápido · Atualização · Biblioteca de Conhecimento · Arquitetura · Hosts suportados · Privacidade e segurança

Animated MemoryGuard neuron graph with governed memory categories and signals moving through the local projection

_{Uma projeção governada sintética: sinais se movem pelas categorias de memória enquanto o texto bruto da conversa permanece fora do grafo.}

Novidades na v0.7.8

A v0.7.8 consolida as correções de governança, observabilidade e runtime do host preparadas após a v0.7.7:

Governança canônica de memória e regras: regras, hábitos e memórias relacionados convergem por um caminho canônico de leitura/escrita, enquanto evidências, links de origem, ramificações do grafo, histórico de substituição, revisão de conflitos e resolução permanecem auditáveis e reversíveis.
Governança multiagente legível: identidades de programa verificadas, rótulos legíveis, ícones de família seguros, escopo de grupo compartilhado, explicações de risco, encerramento de conflitos obsoletos e o shell de GUI de sete páginas mantêm a governança diária compreensível.
Visualização de uso e economia locais: a página de Tokens mostra eventos locais de conversão MCP e unidades estimadas de linha de base versus entregues em sete/trinta dias. As medições de tokens do provedor são usadas apenas quando relatadas (atualmente Codex e Grok); Claude, Cursor e Trae permanecem explicitamente sem suporte. Nenhum corpo de conversa, conta, caminho ou identificador de instância é armazenado.
Alinhamento de ciclo de vida e runtime do Codex: evidências de thread de terminal controlam a recuperação de coortes vazadas de propriedade do Codex; turnos comuns permanecem retomáveis. O reparo instalado alinha os Hooks MCP e de ciclo de vida ao interpretador atual, preservando a identidade do Agent/grupo compartilhado e os limites de falha fechada.

Consulte o registro de lançamento da v0.7.8.

Detalhes de lançamentos anteriores são mantidos no Changelog e registros de lançamento do GitHub.

Grande refatoração V2 na v0.6.0

A v0.6.0 foi uma refatoração do plano de dados de produção, não apenas uma atualização de armazenamento:

Domínios V2 autoritativos: Memória, Regras, Evidências, Conteúdo, Runtime, Projeção, Ativos, CodeGraph, Habilidades e estado do Sistema são separados em domínios SQLite explícitos com limites governados.
Transição explícita: V1_ACTIVE → V2_BUILDING → V2_READY → V2_ACTIVE é de falha fechada; o V2 nunca recorre silenciosamente a armazenamentos legados ou gravações duplas após READY/ACTIVE.
Migração sem perdas: a preparação de fonte congelada usa backups online coerentes do SQLite, valida evidências de origem/destino, reverifica a derivação da fonte ativa e preserva dados V1 mais backups de migração para rollback.
Roteamento nativo: as superfícies MCP, CLI, GUI e Hook são classificadas explicitamente; o lançamento fechou a transição de 233 superfícies com 138 rotas implementadas, 95 rotas aposentadas e zero rotas neutras/bloqueadoras.
Inteligência governada: ciclo de vida de Regras e RuleMerge, extração/enriquecimento, importação MCP externa, plano de controle do provedor, histórico de conversas, Biblioteca de Conhecimento e governança da GUI usam os caminhos de evidência e decisão V2.
Evidência operacional: Auditoria de Referência, saúde SQLite por domínio, manutenção protegida, evidência de rollback e diagnósticos não vinculados seguros fazem parte da prontidão e das operações.

Por que MemoryGuard

A memória persistente resolve o armazenamento. Ela não resolve a governança.

Quando vários agentes de codificação escrevem no mesmo contexto, os registros se tornam duplicados, obsoletos, contraditórios, excessivamente amplos ou inseguros para reutilização. O MemoryGuard fica entre os agentes de codificação e sua memória compartilhada para manter esse contexto utilizável.

Sem governança	Com MemoryGuard
As notas se acumulam sem um estado canônico	As escritas são classificadas, deduplicadas, substituídas ou exibidas como conflitos
Uma correção destrói silenciosamente o valor antigo	Evidências e cadeias de substituição preservam o que mudou e por quê
Tokens e credenciais podem permanecer ativos	Conteúdo de aparência sensível é colocado em quarentena da memória ativa
Cada escrita precisa de aprovação manual	Os agentes escrevem normalmente; as pessoas revisam exceções e resultados
Logs de chat brutos vazam para o contexto futuro	O histórico de conversas permanece um arquivo de evidências separado e explicitamente lido

Arquitetura do sistema

%%{init: {"theme":"base","themeVariables":{"background":"#071521","fontFamily":"Arial, sans-serif","fontSize":"14px","primaryTextColor":"#EEF4F8","lineColor":"#557287","edgeLabelBackground":"#071521","clusterBkg":"#0A1A29","clusterBorder":"#27445A"},"flowchart":{"htmlLabels":true,"curve":"basis","nodeSpacing":32,"rankSpacing":48,"padding":14}}}%%
flowchart TB
    Hosts["CODING-AGENT HOSTS<br/>Claude Code · Codex · Cursor · TRAE&nbsp;&nbsp;&nbsp;&nbsp;"]:::host
    Gateway["LOCAL INTEGRATION<br/>MCP stdio · redirect rules · lifecycle hooks&nbsp;&nbsp;&nbsp;&nbsp;"]:::gateway

    subgraph Core["GOVERNANCE CORE&nbsp;&nbsp;&nbsp;&nbsp;"]
        direction LR
        Identity["TRUST<br/>identity · scope&nbsp;&nbsp;&nbsp;&nbsp;"]:::core
        MemoryAPI["MEMORY<br/>governed I/O&nbsp;&nbsp;&nbsp;&nbsp;"]:::active
        Rules["RULES<br/>scope · assignment&nbsp;&nbsp;&nbsp;&nbsp;"]:::rule
        HistoryAPI["HISTORY<br/>search · timeline&nbsp;&nbsp;&nbsp;&nbsp;"]:::history
        Security["SAFETY<br/>validate · quarantine&nbsp;&nbsp;&nbsp;&nbsp;"]:::danger

        Identity --> MemoryAPI
        Identity --> Rules
        Identity --> HistoryAPI
        MemoryAPI --> Security
    end

    subgraph Stores["LOCAL GOVERNED STORES&nbsp;&nbsp;&nbsp;&nbsp;"]
        direction LR
        SharedDB[("V2 DOMAIN STORES<br/>Memory · Rules · Evidence · Content&nbsp;&nbsp;&nbsp;&nbsp;")]:::store
        HistoryDB[("HISTORY STORE<br/>isolated conversations&nbsp;&nbsp;&nbsp;&nbsp;")]:::historyStore
        AuditDB[("RECOVERY STORE<br/>versions · receipts · backups&nbsp;&nbsp;&nbsp;&nbsp;")]:::store
    end

    Bootstrap["BOUNDED CONTEXT BOOTSTRAP<br/>mandatory rule pack · relevant recall&nbsp;&nbsp;&nbsp;&nbsp;"]:::bootstrap
    Control["HUMAN CONTROL<br/>CLI · desktop governance console&nbsp;&nbsp;&nbsp;&nbsp;"]:::surface

    Hosts --> Gateway --> Identity
    MemoryAPI --> SharedDB
    Rules --> SharedDB
    HistoryAPI --> HistoryDB
    Security --> AuditDB
    SharedDB --> Bootstrap
    Control --> Identity

    classDef host fill:#12243A,stroke:#38D5C8,color:#EEF4F8,stroke-width:1.4px;
    classDef gateway fill:#0D3338,stroke:#38D5C8,color:#EEF4F8,stroke-width:2.4px;
    classDef core fill:#12243A,stroke:#557287,color:#EEF4F8,stroke-width:1.4px;
    classDef active fill:#0D383A,stroke:#38D5C8,color:#EEF4F8,stroke-width:2px;
    classDef rule fill:#3B2C18,stroke:#F3B562,color:#EEF4F8,stroke-width:1.8px;
    classDef history fill:#102F45,stroke:#73C7F5,color:#EEF4F8,stroke-width:1.8px;
    classDef danger fill:#3A2028,stroke:#EA6A6A,color:#EEF4F8,stroke-width:1.8px;
    classDef bootstrap fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2.4px;
    classDef store fill:#0B1624,stroke:#7F96A8,color:#EEF4F8,stroke-width:1.4px;
    classDef historyStore fill:#102436,stroke:#73C7F5,color:#EEF4F8,stroke-width:1.4px;
    classDef surface fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2px;

    style Core fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
    style Stores fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
    linkStyle default stroke:#557287,stroke-width:1.4px;

Início rápido

Metadados do registro MCP

Este pacote expõe um servidor MCP stdio local como io.github.irisxc4/memoryguard. Os metadados do registro são mantidos em server.json. O marcador acima é obrigatório no README do pacote PyPI. O artefato PyPI atual de agent-memguard 0.7.8 não tem marcador, então 0.7.8 ainda não pode ser publicado no Registro MCP. Para o próximo lançamento, primeiro aumente ambas as versões de server.json para a nova versão do pacote, publique um artefato PyPI com marcador, confirme que sua versão e marcador estão visíveis e então execute mcp-publisher publish.

1. Instalar

python -m pip install agent-memguard

Para o console de governança de desktop:

python -m pip install "agent-memguard[gui]"

2. Autorizar o projeto atual

memoryguard source add .

3. Conectar ou reparar seu agente de codificação

A configuração global do provedor é reconstruída a partir da vinculação real no diretório inicial de dados do usuário canônico. O comando é idempotente e remove substituições de nível de projeto do MemoryGuard obsoletas após uma tomada global bem-sucedida.

# Repair one provider
memoryguard provider repair claude
memoryguard provider repair codex
memoryguard provider repair cursor
memoryguard provider repair trae

# Repair every detected provider
memoryguard provider repair all

Reinicie o host após a instalação e verifique a integração:

memoryguard doctor
memoryguard mcp-status
memoryguard hooks status --provider all

Inicie o console de desktop:

memoryguard gui

memoryguard-gui . permanece disponível para atalhos de desktop. Um memoryguard gui simples sempre abre o diretório de controle de nível de usuário canônico (padrão %LOCALAPPDATA%\MemoryGuard no Windows), então executá-lo a partir de um projeto ou de C:\Windows\System32 não pode alternar bancos de dados silenciosamente. MEMORYGUARD_WORKSPACE é uma substituição explícita do operador; um memoryguard gui <project-path> ou memoryguard gui --workspace <project-path> explícito seleciona um workspace específico. Ele não lembra de um projeto selecionado anteriormente nem abre um seletor de pastas. No Windows, memoryguard gui desanexa a janela nativa do terminal, então fechar o PowerShell não fecha a GUI.

Configuração e comportamento específicos do provedor:

Vinculação estável Codex / Router

O Codex/Router vincula o MemoryGuard ao programa Codex local estável e à instalação de controle. Um perfil de conta é um endpoint/alias, não um novo proprietário de memória: alternar perfis descobre ou repara automaticamente o perfil e reutiliza a vinculação verificada do Agent e o grupo ativo. A identidade da solicitação permanece de falha fechada; isso não compartilha registros entre máquinas ou com contas arbitrárias.

Atualização

O MemoryGuard atualmente atualiza pelo gerenciador de pacotes do Python:

python -m pip install --upgrade agent-memguard
memoryguard --version
memoryguard doctor

Se você instalou o extra da GUI, mantenha-o durante a atualização:

python -m pip install --upgrade "agent-memguard[gui]"

Não há comando de auto-atualização do pacote. O gerenciador de pacotes é o caminho autoritativo de atualização de pacotes; memoryguard upgrade abaixo é o fluxo explícito de migração de workspace, não um atualizador de pacotes.

Atualizar um diretório inicial de dados V1 existente

Atualize o pacote e execute a migração verificada. Nenhum argumento de workspace, diretório inicial de dados, aplicação ou confirmação é necessário para o diretório inicial de dados de nível de usuário normal:

python -m pip install --upgrade agent-memguard
memoryguard --version                    # 0.7.8
memoryguard upgrade
memoryguard doctor

O comando prepara o V2, valida as evidências de origem congelada e ativa, migra o controle de Agent/Grupo, ativa somente após todas as portas passarem e remove apenas o lote de backup pertencente a essa migração bem-sucedida. Executá-lo novamente em V2_ACTIVE é idempotente. Para um relatório sem gravação, use:

memoryguard upgrade --preview

Opções avançadas explícitas de workspace/diretório inicial de dados permanecem disponíveis para operadores que gerenciam uma instalação isolada. Uma porta falhada permanece não ativa e preserva suas evidências; a ativação bem-sucedida não mantém um backup de migração redundante.

Workspaces pré-V2 existentes: transição V2 explícita

A v0.6.0 nunca ativa automaticamente um workspace existente. Atualize o pacote primeiro e use o CLI de operador empacotado:

# Read-only manifest status
memoryguard-v2 status -w .

# Build a frozen-source V2 shadow and stop at V2_READY
memoryguard-v2 prepare -w . --apply

# Activate only after the prepare result is V2_READY / ready=true
memoryguard-v2 activate -w . --confirm V2_ACTIVE

A etapa de preparação usa backups online coerentes do SQLite, preserva V1 e migration-backups e reverifica a derivação da fonte ativa antes de READY. A ativação realiza outra verificação de derivação fresca antes de alterar o manifesto. Não exclua dados V1 legados ou backups de migração como parte da atualização.

Biblioteca de Conhecimento

O console de desktop pode transformar uma pasta selecionada ou conjunto de arquivos em uma biblioteca de conhecimento local governada. Os arquivos de origem permanecem onde estão; o MemoryGuard armazena o índice pesquisável em seu diretório inicial de dados do usuário em vez de copiar um banco de dados de runtime em cada projeto de origem. Os metadados de conhecimento nunca se tornam um segundo armazenamento de corpo de origem.

Capacidade	Comportamento atual
Ingestão de arquivo/pasta	Adicionar uma pasta como livro ou arquivos selecionados como documentos
Estrutura	Analisar documentos, preservar contexto de capítulo/seção e criar blocos rastreáveis
Recuperação	Pesquisa de texto completo, embeddings opcionais e um grafo de conhecimento em camadas
Sincronização natural	Re-ingestão de arquivos alterados; uma varredura parcial ou falha não remove silenciosamente conteúdo indexado anteriormente
Ciclo de vida	Mover um livro para a lixeira da biblioteca, restaurá-lo ou limpar explicitamente seu snapshot de recuperação
Candidatos de memória	Visualizar candidatos com evidências antes de aceitá-los na memória de longo prazo governada

Abra o console de desktop e escolha Biblioteca de Conhecimento. Indexação remota por embeddings ou modelo é opcional e requer autorização explícita; a recuperação local de texto completo permanece disponível sem enviar texto de origem a um provedor remoto.

Atualização do CodeGraph

A primeira compilação do CodeGraph é uma compilação completa explícita e confirmada. Após um escopo ser compilado, cada escrita de arquivo confiável bem-sucedida pode acionar uma atualização incremental para esse escopo, sujeita à validação estrita de caminho de origem e vinculação ativa. Hashes de conteúdo inalterados são no-op; arquivos excluídos são aposentados; o próximo contexto recebe um recibo affected limitado. O MemoryGuard não executa um daemon ou observador para esse caminho e não infere caminhos de shell ou texto de forma livre.

Superfícies do console de desktop

A GUI segue uma arquitetura de informação de sete páginas:

Visão Geral de Governança
Fontes de Dados e Agentes
Núcleo de Memória
CodeGraph
Regras e Hábitos
Histórico de Conversas
Sinais de Risco e Console de Governança

As listas de agentes usam nomes legíveis de programa/provedor; o ID subjacente permanece disponível na visualização de detalhes. Dados vazios são mostrados como um estado vazio explícito.

Ciclo de vida de escrita e governança

%%{init: {"theme":"base","themeVariables":{"background":"#071521","fontFamily":"Arial, sans-serif","fontSize":"14px","primaryTextColor":"#EEF4F8","lineColor":"#557287","edgeLabelBackground":"#071521","clusterBkg":"#0A1A29","clusterBorder":"#27445A"},"flowchart":{"htmlLabels":true,"curve":"basis","nodeSpacing":30,"rankSpacing":42,"padding":14}}}%%
flowchart TD
    subgraph Intake["01 · INTAKE&nbsp;&nbsp;&nbsp;&nbsp;"]
        direction LR
        Write(["Memory write&nbsp;&nbsp;&nbsp;&nbsp;"]):::entry
        Scope["Resolve identity<br/>scope · audience&nbsp;&nbsp;&nbsp;&nbsp;"]:::core
        Validate{"Authorized?&nbsp;&nbsp;&nbsp;&nbsp;"}:::decision
        Reject["Reject<br/>no persistence&nbsp;&nbsp;&nbsp;&nbsp;"]:::danger
        Write --> Scope --> Validate
        Validate -- NO --> Reject
    end

    subgraph Organize["02 · ORGANIZE&nbsp;&nbsp;&nbsp;&nbsp;"]
        direction TB
        Secret{"Sensitive?&nbsp;&nbsp;&nbsp;&nbsp;"}:::decision
        Quarantine["Quarantine<br/>outside active set&nbsp;&nbsp;&nbsp;&nbsp;"]:::danger
        Compare["Classify · compare<br/>governed records&nbsp;&nbsp;&nbsp;&nbsp;"]:::active
        Relation{"Relationship&nbsp;&nbsp;&nbsp;&nbsp;"}:::decision
        New["NEW<br/>create active record&nbsp;&nbsp;&nbsp;&nbsp;"]:::result
        Duplicate["DUPLICATE<br/>merge provenance&nbsp;&nbsp;&nbsp;&nbsp;"]:::result
        Correction["CORRECTION<br/>supersede old record&nbsp;&nbsp;&nbsp;&nbsp;"]:::rule
        Conflict["CONFLICT<br/>preserve both sides&nbsp;&nbsp;&nbsp;&nbsp;"]:::danger

        Secret -- YES --> Quarantine
        Secret -- NO --> Compare --> Relation
        Relation --> New
        Relation --> Duplicate
        Relation --> Correction
        Relation --> Conflict
    end

    subgraph Govern["03 · GOVERN&nbsp;&nbsp;&nbsp;&nbsp;"]
        direction LR
        Receipt[("Evidence event<br/>version receipt&nbsp;&nbsp;&nbsp;&nbsp;")]:::store
        Review["CLI or desktop review&nbsp;&nbsp;&nbsp;&nbsp;"]:::surface
        Action["Correct · merge<br/>restore · delete&nbsp;&nbsp;&nbsp;&nbsp;"]:::rule
        Snapshot["Reversible<br/>snapshot&nbsp;&nbsp;&nbsp;&nbsp;"]:::active
        Receipt --> Review --> Action --> Snapshot
    end

    Validate -- YES --> Secret
    Quarantine --> Receipt
    New --> Receipt
    Duplicate --> Receipt
    Correction --> Receipt
    Conflict --> Receipt

    classDef entry fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2.4px;
    classDef core fill:#12243A,stroke:#557287,color:#EEF4F8,stroke-width:1.5px;
    classDef decision fill:#0D3338,stroke:#38D5C8,color:#EEF4F8,stroke-width:2px;
    classDef active fill:#0D383A,stroke:#38D5C8,color:#EEF4F8,stroke-width:2px;
    classDef result fill:#12243A,stroke:#38D5C8,color:#EEF4F8,stroke-width:1.6px;
    classDef rule fill:#3B2C18,stroke:#F3B562,color:#EEF4F8,stroke-width:1.8px;
    classDef danger fill:#3A2028,stroke:#EA6A6A,color:#EEF4F8,stroke-width:1.8px;
    classDef store fill:#0B1624,stroke:#7F96A8,color:#EEF4F8,stroke-width:1.4px;
    classDef surface fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2px;

    style Intake fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
    style Organize fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
    style Govern fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
    linkStyle default stroke:#557287,stroke-width:1.4px;

O console não é uma fila de aprovação. Os agentes continuam se movendo. O MemoryGuard registra o resultado e expõe as evidências necessárias para corrigi-lo posteriormente.

O que você pode governar

Sinal	Ação de governança
Memória duplicada ou desatualizada	Inspecione o registro canônico e a cadeia de substituição; restaure uma versão anterior quando necessário
Memórias conflitantes	Mantenha ambas visíveis até que o conflito seja resolvido deliberadamente
Segredos, tokens ou credenciais	Coloque o registro em quarentena para que não entre na memória compartilhada ativa
Organização automática incorreta	Corrija, mescle, bloqueie, restaure ou reverta com evidências
Múltiplos agentes de codificação	Vincule agentes a um único grupo compartilhado preservando a identidade e o escopo da fonte
Regras obrigatórias	Atribua regras a um Agente, projeto, provedor, função de runtime ou grupo compartilhado

Regras e histórico permanecem separados

O MemoryGuard mantém deliberadamente a memória governada de longo prazo e o histórico bruto de conversas em caminhos diferentes.

Superfície	Propósito	Comportamento de contexto
Regras e hábitos	Preferências, procedimentos, correções, fatos, projetos e regras obrigatórias com escopo	Regras obrigatórias usam um orçamento independente de caracteres/tokens após escopo, exclusão, conflito e deduplicação semântica. Contagem efetiva acima de 20 é um aviso de saúde, não um bloqueio rígido; o armazenamento não é limitado por contagem. Registros sensíveis, corrompidos, com tamanho excessivo por item e estouro agregado ainda falham de forma fechada, sem truncamento silencioso. Registros comuns são recuperados quando relevantes
Histórico de conversas	Arquivo local de evidência bruta com controles de acesso do proprietário e de grupo compartilhado	Nunca entra no bootstrap automaticamente; texto bruto é lido somente por meio de ferramentas explícitas de histórico
Grafo de neurônios	Navegação e governança sobre memória, regras, projetos, agentes e sessões	Nós de histórico contêm metadados seguros e resumos, não conteúdo bruto de chat

A recuperação de histórico é progressiva: resultados de pesquisa, depois uma linha do tempo limitada e, em seguida, um turno ou sessão explicitamente selecionado. Extrair do histórico cria uma prévia primeiro; não grava silenciosamente uma memória de longo prazo.

%%{init: {"theme":"base","themeVariables":{"background":"#071521","fontFamily":"Arial, sans-serif","fontSize":"14px","primaryTextColor":"#EEF4F8","lineColor":"#557287","edgeLabelBackground":"#071521","clusterBkg":"#0A1A29","clusterBorder":"#27445A"},"flowchart":{"htmlLabels":true,"curve":"basis","nodeSpacing":30,"rankSpacing":42,"padding":14}}}%%
flowchart LR
    subgraph HistoryPath["CONVERSATION EVIDENCE&nbsp;&nbsp;&nbsp;&nbsp;"]
        direction TB
        Archive[("Raw local history&nbsp;&nbsp;&nbsp;&nbsp;")]:::historyStore
        Search["Search summaries&nbsp;&nbsp;&nbsp;&nbsp;"]:::history
        Timeline["Bounded timeline&nbsp;&nbsp;&nbsp;&nbsp;"]:::history
        Read["Explicit turn or session&nbsp;&nbsp;&nbsp;&nbsp;"]:::history
        Preview["Evidence-backed<br/>extraction preview&nbsp;&nbsp;&nbsp;&nbsp;"]:::history
        Confirm["Explicit acceptance&nbsp;&nbsp;&nbsp;&nbsp;"]:::surface
        Isolation["NO AUTOMATIC<br/>BOOTSTRAP PATH&nbsp;&nbsp;&nbsp;&nbsp;"]:::barrier

        Archive --> Search --> Timeline --> Read --> Preview --> Confirm
        Archive -.-> Isolation
    end

    subgraph GovernedMemory["GOVERNED LONG-TERM MEMORY&nbsp;&nbsp;&nbsp;&nbsp;"]
        direction TB
        Mandatory["Scoped mandatory rules&nbsp;&nbsp;&nbsp;&nbsp;"]:::rule
        Assignments["Agent · project<br/>role · group scope&nbsp;&nbsp;&nbsp;&nbsp;"]:::core
        RulePack["Mandatory-rule<br/>budget&nbsp;&nbsp;&nbsp;&nbsp;"]:::budget
        Ordinary["Facts · preferences<br/>projects · procedures&nbsp;&nbsp;&nbsp;&nbsp;"]:::memory
        Recall["Task-relevant<br/>recall budget&nbsp;&nbsp;&nbsp;&nbsp;"]:::budget
        Context["BOUNDED CONTEXT PACKET&nbsp;&nbsp;&nbsp;&nbsp;"]:::context

        Mandatory --> Assignments --> RulePack --> Context
        Ordinary --> Recall --> Context
    end

    HistoryPath ==>|GOVERNED WRITE&nbsp;&nbsp;&nbsp;&nbsp;| GovernedMemory

    classDef rule fill:#3B2C18,stroke:#F3B562,color:#EEF4F8,stroke-width:1.8px;
    classDef core fill:#12243A,stroke:#557287,color:#EEF4F8,stroke-width:1.4px;
    classDef memory fill:#0D383A,stroke:#38D5C8,color:#EEF4F8,stroke-width:1.8px;
    classDef budget fill:#12243A,stroke:#38D5C8,color:#EEF4F8,stroke-width:1.6px;
    classDef context fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2.4px;
    classDef history fill:#102F45,stroke:#73C7F5,color:#EEF4F8,stroke-width:1.6px;
    classDef historyStore fill:#102436,stroke:#73C7F5,color:#EEF4F8,stroke-width:1.6px;
    classDef surface fill:#EEF4F8,stroke:#73C7F5,color:#071521,stroke-width:2px;
    classDef barrier fill:#3A2028,stroke:#EA6A6A,color:#EEF4F8,stroke-width:2px;

    style GovernedMemory fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
    style HistoryPath fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
    linkStyle default stroke:#557287,stroke-width:1.4px;

Hosts suportados

Host	Integração	Limite atual
Claude Code	Vínculo MCP global, regras de redirecionamento, Hook de ciclo de vida em nível de usuário	Caminho de substituição verificado
Codex	Vínculo MCP global, regras de redirecionamento, Hook de ciclo de vida em nível de usuário	Caminho de substituição verificado
Cursor	Vínculo MCP global, regras de redirecionamento, Hook de ciclo de vida em nível de usuário	Caminho de substituição verificado
TRAE	Vínculo MCP e regras de redirecionamento	Nenhum ponto de Hook verificado; relatado como fallback em vez de substituição completa

O status do provedor é relatado honestamente como redirecionado, observado, operacional ou não suportado. O MemoryGuard não afirma que pode desativar a memória nativa de todos os hosts quando o host não expõe um ponto de integração confiável.

Arquitetura

Camada	Responsabilidade
Evidência e Conteúdo	Fontes autorizadas, evidência imutável, blobs/ocorrências endereçados por conteúdo, manifestos de fonte e arquivos de conversa
Memória e Regras	Átomos de memória com escopo, revisões, vínculos, definições de regras, decisões, links de evidência e operações de governança compensatórias
Runtime e Projeção	Contexto de trabalho limitado, projeções de cenário/perfil, CodeGraph, Assets e metadados de Skills
Cutover e Governança	Manifesto de quatro estados, roteamento nativo MCP/CLI/GUI/Hook, Auditoria de Referência, manutenção, adaptadores de provedor e evidências de rollback

O V2 usa domínios SQLite autoritativos separados em vez de um único banco de memória compartilhada. O runtime lê e grava no V2 somente após o manifesto atingir V2_ACTIVE; V2_BUILDING e V2_READY nunca fazem fallback silencioso ou gravação dupla. A evidência permanece rastreável sem ser tratada como memória automaticamente confiável.

Privacidade e segurança

O MemoryGuard executa como um servidor MCP stdio local.
Todos os dados governados permanecem locais, a menos que você autorize explicitamente um modelo remoto ou operação de incorporação. A telemetria opcional de uso é apenas local: seus eventos medidos de tokens do host e eventos de conversão determinísticos são armazenados em .memoryguard/usage_telemetry.sqlite; ela não envia dados. As economias de tokens são estimativas baseadas em unidades determinísticas do MemoryGuard, não uma declaração de cobrança do provedor. Hosts sem relatório de tokens permanecem não suportados nas colunas medidas.
O banco de dados da Biblioteca de Conhecimento usa MEMORYGUARD_HOME ou o diretório de dados do usuário da plataforma, para que uma pasta de origem selecionada não receba seu próprio banco de dados de conhecimento.
O estado autoritativo do espaço de trabalho V2 é separado em .memoryguard/ em domínios explícitos de Memória, Regras, Evidência, Conteúdo, Runtime, Projeção, Assets, CodeGraph, Skills e Sistema; controle de Histórico, Fonte, Vínculo e Grupo são superfícies nativas do V2. Artefatos legados do V1 são preservados como evidência local de rollback/auditoria após o cutover e não são mais o caminho de gravação ativo do runtime V2; somente memoryguard.migration pode lê-los.
A varredura de fontes é somente leitura por padrão.
Caminhos de governança mutáveis usam validação, escopo explícito, proveniência e estado reversível.
Registros em quarentena permanecem fora da memória compartilhada ativa.
O histórico bruto de conversas nunca é injetado no bootstrap automaticamente.
O acesso ao histórico de grupo compartilhado segue a associação ativa atual e não concede direitos de exclusão sobre a fonte de outro Agente.

CLI

O comando memoryguard instalado expõe estas operações de nível superior:

Comando	Propósito
`audit [path]`	Executa uma auditoria somente leitura e gera um relatório
`open [path]`	Abre o relatório interativo mais recente
`explain <finding_id>`	Explica evidências e riscos para uma descoberta
`source <action>`	Lista, adiciona, remove ou pré-visualiza fontes autorizadas
`scan`	Varre fontes autorizadas e constrói o registro de cobertura
`doctor`	Diagnostica o manifesto V2, disponibilidade de domínio e cobertura nativa
`mcp-status`	Inspeciona a saúde do backend MCP V2; contagens de locatários exigem um escopo de Agente vinculado
`hooks <action>`	Instala, inspeciona, pausa, repara ou remove Hooks de host
`provider <action>`	Inspeciona ou repara integrações globais de provedor
`storage audit	report`
`storage sweep	compact`
`groups <action>`	Inspeciona o estado do grupo governado
`gui [path]`	Inicia o console de governança interativo
`desktop`	Inicia o executor de desktop confiável

Os fluxos de trabalho legados V1 plan, apply, verify, undo, import e gc podem permanecer analisáveis como superfícies de compatibilidade aposentadas explícitas, mas não são um caminho de runtime V1. Sob V2_ACTIVE, eles retornam um resultado aposentado estável em vez de gravar por meio de um armazenamento legado. A entrada de dados legados é aceita somente pelo fluxo de atualização explícito memoryguard.migration.

Execute memoryguard --help ou memoryguard <command> --help para a referência de comandos ao vivo.

API MCP

O servidor MCP expõe ferramentas para:

leitura, pesquisa, gravação, atualização, exclusão e status de memória governada;
bootstrap de contexto limitado com isolamento de regras obrigatórias;
criação de regras, feedback, governança de mesclagem, desfazer e estatísticas de escopo;
inspeção de vínculo de Agente e grupo compartilhado;
varredura de fontes, projeção de grafo, prévias de importação e planejamento de construção;
descoberta e importação de MCP externo;
prévias de extração de documentos e aceitação de candidatos;
pesquisa de histórico de conversas, linha do tempo, leitura explícita, exportação, exclusão e prévia de extração;
instalação de provedor e enriquecimento de agente host.

Use o MCP tools/list como fonte de verdade para o conjunto exato de ferramentas suportado pela versão instalada.

Links do projeto

Roadmap

Linha de lançamento atual: v0.7.8 consolida governança canônica, governança GUI legível para múltiplos agentes, telemetria de uso apenas local e alinhamento de ciclo de vida/runtime do Codex. v0.7.7 torna o reparo de provedor simples seguro em um lar de controle verificado e exclusivamente vinculado e alinha os reparos instalados do Codex MCP/Hook ao interpretador atual, preservando a identidade do Agente e do grupo compartilhado. v0.7.6 torna a seleção de runtime do Codex Hook/MCP consistente por meio de um único snapshot imutável, encurta as janelas de bloqueio de estado do Hook e mantém o estado de sucesso/fracasso do bootstrap honesto com tratamento explícito de estouro obrigatório com falha fechada. Registros de lançamentos anteriores retêm as mudanças detalhadas de revisão de conflito v0.7.5, governança canônica v0.7.4, histórico compartilhado v0.7.3 e gravação/leitura e ciclo de vida do Codex v0.7.2. O trabalho de migração somente V2 v0.7.1 e ciclo de vida de desktop permanece documentado como contexto histórico de lançamento.
Limite de aceitação: a evidência Graphify é o resultado focado 3 / 3 mais a exportação/projeção real do repositório completo descrita acima. Não afirma que a suíte de testes de repositório completo do Graphify upstream passou.
Próximo após o lançamento: ingestão mais ampla de CodeGraph/Skills, relatórios de manutenção mais amigáveis ao operador e observabilidade adicional de migração. Registros de longo prazo não são aposentados apenas por serem antigos.
Depois: capacidades de equipe e empresa somente após demanda validada.

Contribuindo

Issues e pull requests são bem-vindos. Leia CONTRIBUTING.md antes de enviar uma alteração. Pull requests exigem concordância com o CLA.

Licença

MIT