piia-engram

Piia Engram

Identidade de trabalho de IA local-first que você pode ver, editar e substituir — portátil entre suas ferramentas de codificação MCP.

Diga à IA uma única vez quem você é, como você trabalha e o que significa "bom". Claude Code, Codex, Cursor, Windsurf e outras ferramentas compatíveis com MCP podem começar a partir da mesma camada de identidade de trabalho de IA — arquivos locais que você possui, sem conta na nuvem, sem memória oculta que você não possa inspecionar.

Instalar · Veja em Ação · Ferramentas Suportadas · Ferramentas MCP · FAQ

ENGLISH | 中文

Listado em:

Também listado em: awesome-agents · Awesome-MCP-ZH · mcpservers.org · Cursor Directory · ModelScope · PulseMCP

Resumo: piia-engram é uma camada de identidade de IA pessoal local-first. Ela ajuda vários agentes de codificação a começar a partir do mesmo entendimento sobre você: suas preferências, padrão de qualidade, lições aprendidas, decisões e contexto de projeto. Não é um banco de dados de memória de agente; é a camada de propriedade do usuário acima de suas ferramentas.

Por que não usar apenas a memória nativa? Claude Code, Codex, Cursor e Windsurf estão adicionando suas próprias memórias e regras. Elas são úteis, mas estão limitadas a uma ferramenta ou espaço de trabalho. piia-engram oferece uma camada de identidade portátil acima delas: arquivos locais que você possui, conhecimento proposto por IA que você revisa e contexto que pode acompanhá-lo entre ferramentas.

Modelo de confiança em quatro linhas:

• Sem conta na nuvem: instale com pip, mantenha o armazenamento principal na sua máquina.
• Arquivos locais: identidade e conhecimento vivem em ~/.engram/ como JSON/Markdown.
• Aprovação do usuário: a IA escreve localmente; itens de alto risco (credenciais, comandos de shell, configuração MCP, regras de permissão) aguardam sua revisão, enquanto gravações de baixo/médio risco são absorvidas automaticamente, mas totalmente auditáveis e reversíveis. Defina ENGRAM_APPROVAL=strict para controlar cada gravação.
• Limites documentados: veja Modelo de confiança, Privacidade e Segurança.

Quer prova? Veja a prova de continuidade entre ferramentas ao vivo — uma memória escrita pelo Claude Code, lida de volta pelo Codex através de um único armazenamento local — ou a demonstração de código reproduzível com um comando.

Veja em Ação

You  → "Help me refactor this auth module"

# WITHOUT piia-engram: AI starts from scratch
AI   → "What language? What framework? What's your testing preference?"

# WITH piia-engram: AI can load your approved context
AI   → "Based on your preference for pytest + 90% coverage, and your
        lesson about always separating auth middleware from business
        logic (from the March incident), here's my approach..."

E você nunca precisa aceitar isso por fé — Memory Lens (engram preview --html) mostra exatamente o que qualquer chamador de IA receberia, e o que a governança reteve, antes de qualquer coisa ser enviada:

Acima: um relatório real de um armazenamento de demonstração — 4 itens expostos; uma nota de staging não revisada e uma lição contendo uma credencial foram retidas, com o segredo mostrado como [REDACTED].

Instalar

pip install piia-engram && engram setup

O assistente detecta automaticamente suas ferramentas de IA — Claude Code, Cursor, Codex, Claude Desktop — lista os arquivos de configuração exatos que tocará e grava a conexão MCP após uma confirmação de uma tecla (toda gravação é copiada primeiro; recuse e nada muda). Ele pré-visualiza seu cartão de identidade, então você reinicia sua ferramenta configurada; a primeira conversa pode carregar seu contexto aprovado através de ferramentas de inicialização ou pesquisa. (passo a passo completo ↓)

Ferramentas Suportadas

Os níveis de evidência seguem o runbook de validação de cliente de agente: L0 = não testado, L1 = instalado, L2 = leitura/pesquisa observada, L3 = ponte de arquivo estático, L4 = continuidade entre clientes.

Pelos números

Estes são fatos atuais do repositório de docs/public-facts.json. Registros públicos e selos de pacotes são atualizados apenas durante lançamento/publicação.

Sua IA esquece você toda vez que você troca de ferramenta ou inicia um novo chat. piia-engram corrige a transferência.

Toda vez que você abre uma nova janela de chat, troca de Claude Code para Codex, atualiza sua ferramenta de IA ou muda para um projeto diferente, você volta ao zero:

• suas preferências de comunicação — perdidas
• seus padrões de código e padrão de qualidade — esquecidos
• quais erros você já aprendeu — perdidos
• por que você tomou aquela decisão de arquitetura no mês passado — apagado

Isso acontece porque a memória de IA hoje está bloqueada dentro de cada plataforma. Ela pertence à ferramenta, não a você. A ferramenta atualiza, redefine ou é substituída — e seu contexto desaparece com ela.

piia-engram oferece uma camada de identidade pessoal que vive na sua máquina, independente de qualquer ferramenta de IA. Você diz uma vez quem você é, como trabalha e o que aprendeu. Ferramentas compatíveis com MCP podem ler o mesmo contexto aprovado. Novo chat, nova ferramenta, nova versão — sua identidade permanece portátil.

piia-engram não é um banco de dados de memória de agente. Ferramentas como Mem0, Zep e Letta armazenam contexto de tarefa e histórico de sessão para agentes de IA. piia-engram armazena quem você é como pessoa — sua identidade, preferências, lições difíceis e decisões-chave. É uma camada diferente: não o que aconteceu em uma tarefa, mas quem está por trás de cada tarefa.

Por que piia-engram?

Quem Usa piia-engram

piia-engram é construído para desenvolvedores que usam múltiplas ferramentas de codificação de IA e estão cansados de se reexplicar.

Se você alterna entre Claude Code, Codex e Cursor — seus padrões de código, decisões de arquitetura e lições difíceis são redefinidos toda vez. piia-engram faz cada ferramenta começar a partir do mesmo entendimento sobre quem você é.

Se você abre 10+ janelas de chat de IA por semana — cada uma começa do zero. piia-engram permite que cada conversa comece a partir do mesmo contexto de identidade e conhecimento aprovado.

Se você perdeu preferências após uma atualização de ferramenta — sua identidade vive na sua máquina, não dentro de qualquer plataforma. Atualizações, redefinições e migrações não tocam sua memória.

O que piia-engram Armazena

Todos os dados vivem em ~/.engram/ como arquivos JSON e Markdown em texto simples que você pode abrir, editar, fazer backup ou migrar você mesmo.

• Identidade: quem você é, como você se comunica, quais idiomas você prefere
• Padrões de qualidade: seu padrão de revisão de código, expectativas de cobertura de teste, o que você se recusa a enviar
• Preferências: estilo de codificação, comportamento de IA, como você gosta de explicações
• Limites de confiança: quais campos manter privados, o que as ferramentas podem acessar
• Instantâneos de projeto: contexto para trabalho em andamento, capturado e recarregável
• Lições aprendidas: erros, surpresas, coisas que funcionaram e não funcionaram
• Decisões-chave: o que você escolheu, o que descartou e por quê
• Conhecimento de domínio: insights reutilizáveis entre projetos e ferramentas

O que piia-engram Faz (Além do Armazenamento)

A maioria das ferramentas de memória são passivas — você coloca coisas, elas devolvem. piia-engram também é ativa.

Herança de conhecimento entre projetos
Descreva um novo projeto em texto simples. get_knowledge_inheritance retorna um pacote inicial curado das lições e decisões mais relevantes de tudo que você já trabalhou. Seu décimo projeto se beneficia de todos os nove anteriores — a uma chamada de ferramenta de distância.

Captura passiva de conhecimento
Cole um resumo de sessão em extract_session_insights e piia-engram extrai e armazena as lições e decisões. Sem anotações manuais. O conhecimento se acumula através de conversas normais de IA.

Funciona com ferramentas que não suportam MCP
ChatGPT, Gemini, Kimi — get_identity_card exporta um cartão de identidade Markdown pronto para colar. Seu contexto viaja até para ferramentas que não podem se conectar diretamente. Extração automática de playbooks
Conclua um fluxo de trabalho de várias etapas — publicação no PyPI, implantação no Cloudflare, publicação no MCP Registry — e o piia-engram detecta isso ao final da sessão. Ele gera um rascunho estruturado de playbook (etapas, armadilhas, palavras-chave de gatilho) e o salva em uma área de preparação. Na próxima vez que você fizer a mesma tarefa, a IA poderá recuperar o playbook confirmado como referência passiva, percorrer as etapas com você e registrar o resultado. Nenhum registro manual é necessário — o Engram inicia o rascunho, você confirma, e a IA anfitriã permanece responsável. Veja Extração Automática de Playbooks abaixo.

Registro de ferramentas locais
As ferramentas de IA procuram constantemente por programas locais, runtimes e CLIs. O register_tool registra o que está instalado e onde; o find_tool recupera isso instantaneamente. Chega de which python a cada sessão — o mapa de ambiente persiste entre ferramentas e conversas.

Saúde e descoberta do conhecimento
O get_knowledge_overview destaca lições desatualizadas (não revisadas há mais de 30 dias), calcula uma pontuação de saúde de 0 a 100 em quatro dimensões (atualidade, qualidade, cobertura, limpeza) e sinaliza lacunas que valem a pena revisitar. O explore_knowledge verifica se há quase duplicatas na sua base de conhecimento (e examina itens relacionados/semelhantes) com comandos de mesclagem acionáveis. O manage_relation conecta lições e decisões relacionadas em um grafo de conhecimento navegável.

Busca híbrida (opcional, desativada por padrão)
A busca por palavra-chave padrão permanece inalterada. Opte pela recuperação híbrida — texto completo FTS5 mais uma camada vetorial semântica — para recuperação entre idiomas, por exemplo, uma consulta em inglês encontrando uma nota em chinês: pip install "piia-engram[vector]" e defina ENGRAM_SEARCH=hybrid, ou deixe o engram setup ativá-lo com um único toque de tecla. O índice é um arquivo SQLite reconstruível; seu armazenamento JSON permanece como a única fonte de verdade. Veja docs/hybrid-search.md.

Início Rápido

pip install piia-engram
engram setup

Novo no piia-engram? Veja o quickstart de primeiro valor mais completo para o caminho instalação -> primeira memória -> recuperação em nova sessão usando apenas as 19 ferramentas principais padrão, ou o Guia do Usuário completo cobrindo instalação -> primeiro valor -> continuidade entre ferramentas -> governança -> privacidade -> FAQ. Cartões de configuração específicos para cada host estão disponíveis para Claude Code, Codex e Cursor. Para rascunhos de contexto seguro somente para proposta, reprodução, atualidade/conflito e evidências, veja Governança de contexto.

O assistente de configuração irá:

1. Detectar seu ambiente Python
2. Permitir que você escolha a pasta de dados do Engram (~/.engram, outra unidade ou um caminho personalizado)
3. Detectar suas ferramentas de IA, listar os arquivos de configuração exatos que serão alterados e gravar a conexão MCP após uma confirmação com um toque de tecla (com backup prévio; recusar deixa tudo intacto)
4. Orientá-lo pelo conhecimento inicial (função, stack de tecnologia, idioma)
5. Importar regras de forma inteligente dos seus arquivos CLAUDE.md / .cursorrules existentes
6. No modo avançado (engram setup --advanced), mostrar suas preferências opcionais de privacidade (sincronização entre ferramentas, estatísticas anônimas)
7. Pré-visualizar seu cartão de identidade de IA — prova imediata de valor

Após a configuração gravar a conexão MCP (você confirma no prompt primeiro), reinicie sua ferramenta de IA. Muitos clientes podem chamar get_user_context na inicialização; quando um host não faz isso proativamente, uma chamada explícita de search_knowledge ou get_resume_brief ainda é o caminho L2 esperado.

Para execuções não interativas ou de CI, pule o prompt de confirmação e grave diretamente:

engram setup --apply-external-config

De qualquer forma, toda gravação de configuração externa é copiada para a pasta de dados do Engram selecionada, e recusar o prompt deixa toda configuração externa intacta.

Verifique a saúde a qualquer momento:

engram status        # redacted install + memory health summary
engram status --html # write a local redacted status page
engram preview --as automation  # see exactly what a given AI caller would receive (read-only)
engram continuity    # metadata-only proof that cross-tool handoff is ready
engram management    # metadata-only review/playbook management view
engram doctor        # diagnose all tools
engram doctor --fix  # auto-repair issues + inject missing instructions
engram repair-encoding        # dry-run scan for garbled / mojibake text
engram repair-encoding --apply  # repair reversible cases with a backup

O engram continuity é somente metadados: ele relata contagens de sessões salvas, ferramentas contribuintes, prontidão do resumo de retomada e sinais agregados de carregamento de contexto / encerramento sem imprimir corpos de memória, eventos brutos de telemetria, IDs de sessão ou caminhos locais.

Para uma prova de loop sintético legível por máquina, execute:

python demos/cross_tool_continuity_demo.py --json

O engram continuity relata metadados de prontidão. O JSON de demonstração prova um loop isolado de gravação -> retomada -> busca -> proveniência usando apenas dados sintéticos.

Para evidências de lançamento mais amplas, execute o benchmark sintético MCIC:

python demos/mcic_benchmark.py --json

O MCIC v1 contém 10 cenários de continuidade com rótulos de propósito cobrindo recuperação explícita, sinais implícitos de personalização, sinais de proteção contra premissas falsas, limites de ações públicas, seleção de HEAD em cadeia de versões, controle negativo e proveniência. Sua afirmação é restrita: o Engram disponibiliza o sinal certo para o próximo cliente; a conformidade do modelo ao vivo ainda precisa de testes A/B separados.

Confiança e Evidências

O piia-engram trata as afirmações de confiança como artefatos de lançamento, não como texto de marketing:

Verifique você mesmo (5 minutos)

Não aceite a tabela acima por fé — execute as verificações na sua própria máquina:

1. Verifique sua configuração — o engram doctor relata ferramentas detectadas, saúde do armazenamento e o modo de capacidade ativo.
2. Veja o que a IA vê — o engram preview --as automation renderiza o contexto exato que um chamador receberia (somente leitura, nada é enviado).
3. Controle a superfície — defina ENGRAM_TOOLS=core (ou componha grupos) e execute novamente o engram doctor para confirmar que ele relata a superfície principal esperada. Veja modos de capacidade.
4. Audite seus dados — siga o runbook de auditoria de soberania de dados para confirmar que os dados de identidade e conhecimento permanecem sob sua raiz do Engram, com gravações externas explícitas e auditadas.
5. Verifique as afirmações — cada afirmação de confiança em evidências de confiança mapeia para uma verificação determinística ou caminho de inspeção que você pode executar localmente.

Configure para Sua Ferramenta de IA

# Guided setup; confirms before writing external client configs (backed up first)
engram setup
# Skip the confirmation prompt for non-interactive/CI runs
engram setup --apply-external-config
# Or manual:
claude mcp add piia-engram -- piia-engram-mcp

{
  "mcpServers": {
    "piia-engram": {
      "command": "piia-engram-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

{
  "command": "python",
  "args": ["-m", "piia_engram.mcp_server"]
}

{
  "mcpServers": {
    "piia-engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"]
    }
  }
}

{
  "mcpServers": {
    "piia-engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"]
    }
  }
}

{
  "mcpServers": {
    "piia-engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"]
    }
  }
}

{
  "mcpServers": {
    "piia-engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"]
    }
  }
}

Verifique sua configuração

Após a configuração, execute o engram doctor para verificar se tudo está conectado:

$ engram doctor

  Detected 3 AI tool(s):
    [ok] Claude Code — Engram configured
    [ok] Cursor — Engram configured
    [ok] Codex — Engram configured

  [ok] All configured tools look healthy.

  ── Functional Checks ──
    [ok] piia_engram.core importable
    [ok] Engram initialized (~/.engram)
    [ok] Identity loaded (role: Senior Backend Developer)
    [ok] quick_context.md ready (4096 bytes)
    [ok] MCP server: 18 tools registered

  -- Terminal encoding --

    [ok] stdout/stderr: utf-8 / utf-8
    [ok] PYTHONIOENCODING not set (stdout/stderr already UTF-8)
    [ok] Runtime encodings: preferred=UTF-8, filesystem=utf-8

  -- Config Integrity --

    [ok] MCP configs: 3/13 files found, 3 configured
    [ok] Instruction files: 3/4 found, 3 fresh
    [ok] Project rule files: 1 found
    [ok] Shared instructions: 1 found
    [ok] Claude hooks: 4/4 registered
    [ok] Report is metadata-only (hashes + counts; no rule bodies)

  -- Continuity --

    [--] No saved agent sessions yet
         Run an AI session, then wrap up or stop the tool to create one.
    [ok] Resume brief builds (2 section(s))

Para verificações de compatibilidade legíveis por máquina, execute o engram capabilities --json. Ele relata códigos de capacidade estáveis e versões de contrato sem ler a memória do usuário ou o conteúdo do projeto; o MCP doctor(output_format="json") inclui a mesma impressão digital.

Atualização

pip install --upgrade piia-engram

Após a atualização, o piia-engram migra automaticamente quaisquer configurações MCP desatualizadas na próxima vez que o servidor iniciar (modo stdio). Se sua ferramenta de IA ainda mostrar um erro "MCP desconectado" após reiniciar, execute:

piia-engram doctor        # show what's wrong
piia-engram doctor --fix  # auto-repair and fix in one step

Em seguida, reinicie a ferramenta de IA afetada. O comando doctor verifica os locais de configuração MCP do Claude Code, Cursor, Codex, Windsurf, Claude Desktop e os suportados pela comunidade, remove entradas de servidor desatualizadas e imprime um resumo de integridade de configuração somente com metadados.

Implantação Remota

Execute o piia-engram no seu próprio servidor e conecte-se de qualquer lugar.

Configuração do Servidor

# Install with remote support
pip install piia-engram[remote]

# Generate an auth token
python -c "import secrets; print(secrets.token_urlsafe(32))"
# Save the output, e.g. "abc123..."

# Start in SSE mode
ENGRAM_AUTH_TOKEN=abc123... python -m piia_engram.mcp_server --transport sse --host 0.0.0.0 --port 8767

Configuração do Cliente (Claude Code)

{
  "mcpServers": {
    "piia-engram": {
      "url": "http://your-server:8767/sse",
      "headers": {
        "Authorization": "Bearer abc123..."
      }
    }
  }
}

Configuração do Cliente (Cursor)

{
  "mcpServers": {
    "piia-engram": {
      "url": "http://your-server:8767/sse",
      "headers": {
        "Authorization": "Bearer abc123..."
      }
    }
  }
}

Notas de segurança:

• Sempre use HTTPS em produção, atrás de nginx ou caddy com TLS.
• O token de autenticação protege seus dados de identidade. Mantenha-o em segredo.
• O bind padrão é 127.0.0.1 apenas para localhost. Use 0.0.0.0 somente atrás de um proxy reverso.
• Defina ENGRAM_CORS_ORIGINS para restringir o acesso entre origens (por exemplo, https://your-domain.com).
• Os dados permanecem no seu servidor e nunca tocam nuvens de terceiros.

Ferramentas MCP

O piia-engram inclui 59 ferramentas MCP. Por padrão, apenas as 19 ferramentas Tier-1 Core são carregadas para manter o contexto da IA limpo. "Core" significa "usado na maioria das sessões", não "somente leitura": algumas ferramentas principais gravam memória local ou arquivos de exportação protegidos pelo proprietário, e a camada de governança ainda controla esses efeitos colaterais. Para a visão curta do operador, veja a folha de referência MCP. Para desbloquear todas as 59 ferramentas, adicione ENGRAM_TOOLS=all à sua configuração MCP:

Você também pode expor modos de capacidade combináveis, como gerenciamento de conhecimento, governança, administração ou integrações; veja o guia de modos de capacidade.

{
  "mcpServers": {
    "piia-engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"],
      "env": { "ENGRAM_TOOLS": "all" }
    }
  }
}

Sincronização na inicialização: o Engram reconcilia memórias/trechos de configuração das ferramentas de IA locais quando um servidor MCP inicia. Por padrão, isso é executado em segundo plano para que os clientes stdio possam inicializar rapidamente. Defina ENGRAM_MCP_STARTUP_SYNC=eager para restaurar a sincronização síncrona na inicialização, ou ENGRAM_MCP_STARTUP_SYNC=off para pular a sincronização na inicialização em braços de teste sensíveis à latência. O ENGRAM_EPHEMERAL=1 também pula a sincronização na inicialização e o trabalho de migração em clientes de contêiner/efêmeros.

Tier-1 Core (18 ferramentas — fluxo de trabalho diário)

Nível 2 — Avançado (40 ferramentas — gestão de conhecimento, revisão, governança, importação/exportação)

As ferramentas avançadas incluem integrações locais opcionais, superfícies de proprietário/admin e utilitários de manutenção. Ferramentas que exportam arquivos, importam armazenamentos completos, geram páginas de revisão ou alteram a confiança do chamador são superfícies de proprietário/admin/exportação, mesmo quando são capacidades de produto amplamente úteis. Operações relacionadas são consolidadas em ferramentas únicas com um seletor mode/action (v4.0).

A migração do escopo do Playbook legado (classificar / aplicar / reverter / fila de revisão) foi movida da superfície MCP para o CLI local exclusivo do proprietário: engram playbook scope classify|apply|rollback|queue|resolve (pré-visualiza por padrão; gravações exigem --apply --yes).

Extração Automática de Playbook

O piia-engram pode detectar fluxos de trabalho de múltiplas etapas que você conclui durante uma sessão e redigir automaticamente playbooks estruturados — sem necessidade de registro manual.

Como Funciona

1. Detecção — Quando você chama wrap_up_session ou save_agent_context, o piia-engram verifica sinais de fluxo de trabalho processual: etapas de checkpoint, verbos de ação e palavras-chave de gatilho.
2. Geração de rascunho — Se um fluxo de trabalho for detectado, um rascunho de playbook é criado com etapas, armadilhas, palavras-chave de gatilho e pré-condições. Informações sensíveis (chaves de API, tokens, caminhos absolutos) são automaticamente redigidas antes do armazenamento.
3. Staging — O rascunho é salvo em uma área de staging, nunca promovido automaticamente para verificado. Você revisa e confirma antes que ele se torne um playbook confiável.
4. Contrato de esquema — Playbooks armazenados são normalizados em um contrato versionado: palavras-chave de gatilho, pré-condições, armadilhas, etapas estruturadas e declarações opcionais de required_tools. Rascunhos simples permanecem revisáveis, mas carregam avisos de qualidade legíveis por máquina.
5. Resolução de ferramentas — Playbooks declaram necessidades de ferramentas por nome ou finalidade, enquanto caminhos locais permanecem no registro de ferramentas. playbook_execution (ação prepare) retorna resolved_tools, tools_ready e missing_tools em tempo de execução para que a IA do host possa ver quais ferramentas locais estão disponíveis sem armazenar caminhos resolvidos no Playbook.
6. Reutilização e resultado — Na próxima vez que uma ferramenta de IA encontrar uma tarefa semelhante, search_knowledge corresponde às palavras-chave de gatilho e retorna o playbook como referência passiva. A IA do host percorre as etapas com você e playbook_execution (ação status) relata um resumo de resultado (pending, partial, succeeded ou failed) em vez de tratar etapas ignoradas como sucesso silencioso.

Filosofia de Design: Engram Inicia, Você Confirma, IA Aplica

A extração automática de playbook não é totalmente automática. O piia-engram detecta o fluxo de trabalho e gera um rascunho aproximado — mas o rascunho permanece em staging até que você o confirme explicitamente. Uma vez confirmado, as ferramentas de IA podem usar o playbook como referência passiva governada e registrar resultados de etapas; o Engram não executa silenciosamente o fluxo de trabalho por elas. Isso mantém os humanos no controle de qualidade enquanto elimina o trabalho manual de escrever procedimentos operacionais.

Níveis de Confiança

Redação de Informações Sensíveis

Antes de qualquer rascunho ser armazenado, o piia-engram redige automaticamente:

• Chaves de API e tokens (Bearer, sk-, ghp_, etc.)
• Caminhos de arquivo absolutos (Windows e Unix)
• Endereços de e-mail
• Segredos de variáveis de ambiente

Interruptor de Desativação

Os usuários podem desativar ou reativar a extração automática de playbook a qualquer momento:

• Desativar: Diga à sua IA "关闭 playbook" / "stop playbook" / "disable playbook auto-extraction"
• Ativar: Diga à sua IA "开启 playbook" / "start playbook" / "enable playbook auto-extraction"

A IA chama update_identity(field="preferences", ...) para alternar playbook_auto_extract. O padrão é ativado.

Criação Manual de Playbook

Você sempre pode criar playbooks manualmente com add_playbook, independentemente da configuração de extração automática. O interruptor de desativação afeta apenas a detecção automática durante wrap_up_session.

Layout de Dados

~/.engram/
|-- schema_version.json
|-- identity/
|   |-- profile.json
|   |-- preferences.json
|   |-- quality_standards.json
|   `-- trust_boundaries.json
|-- knowledge/
|   |-- lessons.json
|   |-- decisions.json
|   `-- domains.json
|-- playbooks/
|   |-- _index.json
|   `-- {playbook_id}.json
|-- tools/
|   `-- registry.json
|-- projects/
|   `-- {project_id}.json
|-- contexts/
|   `-- {tool_name}/
|       `-- {session_id}.md
|-- exports/
`-- compat/
    `-- openclaw/

Possua e exporte seus dados

Tudo vive em JSON local que você possui — inspecione, edite, faça backup ou exclua diretamente. Três caminhos explícitos de exportação, cada um com um limite diferente:

As exportações são restritas ao proprietário quando ENGRAM_GOVERNANCE=1 (veja docs/governance.md). Não há cópia em nuvem nem memória oculta: o que você exporta é exatamente o que está no seu disco.

Soberania local de dados. Backup e restauração cobrem apenas o diretório do Engram — engram backup-plan imprime uma lista somente de metadados do que copiar antes de uma atualização (não lê corpos de conhecimento armazenados e nunca acessa fora da raiz do Engram). Para backups JSON, import_engram(..., dry_run=True) ou engram import <backup.json> retorna um plano de mesclagem somente de metadados com contagens de adição/ignoração/conflito antes de qualquer gravação; --apply --yes é necessário para mutar o armazenamento local. Lições com o mesmo resumo e decisões com a mesma pergunta com campos semânticos divergentes são pré-visualizadas como candidatas a cadeia de versões; elas são materializadas apenas quando o proprietário executa explicitamente engram import <backup.json> --apply --yes --materialize-version-chain. O Engram nunca faz backup, modifica ou exclui arquivos nas suas pastas de projeto. Veja docs/runbooks/setup-upgrade-safety.md.

Comparação

📊 Para a comparação completa lado a lado, incluindo quando escolher um concorrente em vez do piia-engram, veja docs/comparison.md.

Construído Com

piia-engram é um projeto open-source dirigido por humanos e assistido por IA.

FAQ

Qual servidor MCP me permite compartilhar memória entre Claude Code e Cursor? piia-engram. Instale com pip install piia-engram && engram setup, e ambas as ferramentas leem a mesma identidade, preferências e lições de ~/.engram/. Sem nuvem, sem serviço de sincronização — ambas leem arquivos JSON locais via MCP.

O que é piia-engram? piia-engram é uma camada de identidade de trabalho de IA local-first para ferramentas de codificação compatíveis com MCP. Ela armazena sua identidade, preferências, padrões de código, lições aprendidas e decisões-chave como arquivos JSON locais na sua máquina. Ferramentas configuradas (Claude Code, Codex, Cursor, Windsurf, Claude Desktop) podem ler o mesmo contexto de propriedade do usuário, para que novos chats e trocas de ferramentas possam começar a partir da mesma base de memória e identidade governada.

Como o piia-engram é diferente do servidor de memória MCP oficial? O @modelcontextprotocol/server-memory oficial armazena um grafo de conhecimento genérico de entidades e relações. O piia-engram é especializado para identidade de desenvolvedor: possui campos estruturados para seu perfil, padrões de código, nível de qualidade, lições aprendidas e decisões-chave — além de 59 ferramentas para gerenciamento do ciclo de vida do conhecimento (busca, revisão, mesclagem, herança entre projetos). Se você precisa de memória de entidades de propósito geral, use o servidor oficial. Se você quer que ferramentas de codificação compatíveis com MCP comecem a partir do mesmo entendimento aprovado de suas preferências e erros passados, use o piia-engram.

Como o piia-engram é diferente de ferramentas de memória de agentes como Mem0, Zep ou Letta? Essas ferramentas armazenam contexto de tarefa e histórico de sessão para agentes de IA — o que aconteceu durante um fluxo de trabalho. O piia-engram armazena quem você é como pessoa — sua identidade, preferências, lições difíceis e decisões-chave. É uma camada diferente: a identidade persiste entre ferramentas, sessões e projetos, enquanto a memória de tarefa é limitada a uma única execução de agente. Seus dados são arquivos JSON locais que você possui e pode editar diretamente.

Por que não usar apenas AGENTS.md / CLAUDE.md / .cursorrules? Esses arquivos de configuração são ótimos para regras específicas de repositório (etapas de build, convenções de codificação). O piia-engram é para você — suas preferências, lições e decisões que podem acompanhá-lo entre repositórios e ferramentas compatíveis com MCP configuradas. Eles se complementam: use AGENTS.md para o projeto, piia-engram para a pessoa. Veja a comparação completa em docs/comparison.md.

Posso usar o piia-engram com várias ferramentas de IA ao mesmo tempo? Sim. Esse é o caso de uso principal. O piia-engram usa armazenamento de arquivos local (~/.engram/) com gravações atômicas e bloqueio de arquivo. Claude Code, Cursor, Codex e qualquer outro cliente MCP podem se conectar simultaneamente. Uma lição registrada no Claude Code fica imediatamente disponível no Cursor.

Quais ferramentas de IA o piia-engram suporta? Qualquer ferramenta compatível com MCP: Claude Code, OpenAI Codex, Cursor, Claude Desktop, Windsurf, GitHub Copilot, Cline, Roo Code, Amazon Q, Augment, Zed e outras. Para ferramentas sem suporte a MCP (ChatGPT, Gemini, Kimi), exporte um cartão de identidade em Markdown com get_identity_card e cole-o.

Onde meus dados são armazenados? Todos os dados ficam em ~/.engram/ na sua máquina local como arquivos JSON e Markdown simples. Sem nuvem, sem conta, sem assinatura. Você pode abrir, editar, fazer backup ou migrar os arquivos você mesmo. Criptografia opcional AES-256-GCM está disponível via pip install piia-engram[secure].

Como instalo o piia-engram?

pip install piia-engram
engram setup

O assistente de configuração detecta suas ferramentas de IA sem alterar os arquivos de configuração por padrão. Para configurar automaticamente as entradas MCP com backups, execute engram setup --apply-external-config e reinicie sua ferramenta de IA. A IA chamará get_user_context no início de cada sessão.

Após atualizar, minha ferramenta de IA mostra "servidor MCP desconectado". Como corrijo? Execute engram doctor --fix em um terminal e reinicie sua ferramenta de IA. Este comando verifica todos os arquivos de configuração MCP conhecidos, remove entradas de servidor desatualizadas e corrige caminhos quebrados em uma única etapa.

O piia-engram envia dados para a nuvem? Não por padrão. As ferramentas de identidade e conhecimento usam arquivos locais, e a telemetria está desativada por padrão. Estatísticas anônimas de uso opcionais podem ser habilitadas como um log local; telemetria remota e relatórios semanais de feedback exigem aceite explícito separado e enviam apenas contagens, nunca conteúdo de conhecimento. Você pode inspecionar o próximo payload com engram telemetry preview, desativar a qualquer momento com engram telemetry off e desligar o envio remoto com engram telemetry remote off. Veja PRIVACY.md para o diagrama completo do fluxo de dados, o que é e o que não é coletado, e seus direitos de dados.

Quantas ferramentas MCP o piia-engram fornece? Dois níveis, projetados para que a maioria dos usuários veja apenas 18 ferramentas:

A maioria dos usuários nunca precisa habilitar as ferramentas Avançadas — o Principal cobre o uso diário.

O piia-engram é gratuito? Sim. O núcleo open-source é software livre sob AGPL-3.0. O uso pessoal/local não tem assinatura, nível de nuvem ou dependência de fornecedor. Se você planeja incorporação de código fechado, redistribuição hospedada ou empacotamento empresarial, revise as obrigações da AGPL primeiro; o piia-engram atualmente não oferece uma licença comercial separada.

Limitações

O piia-engram é funcional e ativamente usado, mas algumas coisas que ele intencionalmente ainda não faz:

O que isso significa na prática:

• Não armazene senhas, chaves de API ou PII de clientes no piia-engram
• Qualquer processo com acesso de leitura a ~/.engram/ pode ler seus dados
• restricted_fields reduz o que o piia-engram emite no contexto de inicialização a frio, mas não é criptografia nem uma ACL verdadeira

Este não é um aviso para evitar o piia-engram — é uma descrição honesta do que ele é: uma camada de memória local para contexto pessoal de IA. Para uso pessoal, funciona bem hoje.

Configuração de Segurança

Criptografia em nível de campo (opcional)

Criptografe campos sensíveis do perfil (e-mail, telefone, localização, etc.) em repouso:

pip install piia-engram[secure]
export ENGRAM_SECRET="your-strong-passphrase"

Campos criptografados são armazenados como enc:v2:... em arquivos JSON; valores legados enc:v1:... ainda são descriptografados. Sem ENGRAM_SECRET, o piia-engram funciona normalmente com texto simples (compatível com versões anteriores).

Registro de auditoria (ativado por padrão)

Um log de auditoria local registra todas as operações de leitura/escrita em ~/.engram/audit.log no formato JSON-lines. É apenas um arquivo local — nunca enviado a lugar algum. Consulte-o com a ferramenta get_audit_log ou grep.

Para desativar:

export ENGRAM_AUDIT=0

Governança de agentes (avançado, opcional)

Habilite níveis de confiança por chamador e recibos de divulgação:

export ENGRAM_GOVERNANCE=1
export ENGRAM_CLIENT_TYPE=claude_code

A governança está desativada por padrão. Quando habilitada, agentes de codificação locais conhecidos são filtrados para conhecimento público/de trabalho, chamadores desconhecidos falham fechados para somente público, e exportações/importações/concessões somente do proprietário exigem private-self. Veja docs/governance.md para os níveis de confiança exatos, portões, limites honestos e comandos do livro-razão.

Roteiro recomendado: mantenha o padrão global compatível, mas habilite a governança no ambiente de cada cliente MCP quando você usar o Engram em várias ferramentas de IA, automação, ou qualquer ponte voltada para remoto. engram status e engram doctor relatam se esta camada está ativa. A identidade do chamador ainda é fornecida por variáveis de ambiente MCP, não por autenticação criptográfica, então a governança é um limite de política local prático em vez de um sandbox endurecido.

Comandos CLI

engram setup            # Interactive install wizard (confirms before writing client configs)
engram setup --apply-external-config  # Skip the confirm prompt (non-interactive/CI); writes with backups
piia-engram doctor           # Check config health + governance state
piia-engram status           # Redacted install + memory/governance summary
piia-engram status --html    # Write a local redacted status page
piia-engram preview          # Show what a simulated AI caller would receive (--as ROLE, --level, --html)
piia-engram continuity       # Prove cross-tool handoff readiness (metadata only)
piia-engram management       # Show a metadata-only review/playbook management view
piia-engram doctor --fix     # Auto-repair any issues found
piia-engram sessions         # List saved cross-tool agent sessions
piia-engram sessions show <id>  # Print one saved session
piia-engram review           # List staging knowledge awaiting review
piia-engram review show <id> # Inspect one review item
piia-engram review approve <id> --yes  # Promote a staging item
piia-engram review archive <id> --yes  # Archive a review item
piia-engram management action review approve <id> --yes --json  # Structured metadata-only action receipt
piia-engram management action playbook delete <id> --yes --json # Soft-delete a Playbook without body echo
piia-engram management action playbook_scope accept_project <id> --project . --yes --json # Resolve ambiguous Playbook scope
piia-engram management action playbook_scope accept_shared <id> --project ./app-a --project ./app-b --yes --json # Share one Playbook with selected projects
piia-engram dock-status      # Zero-write Dock owner-console status (--json)
piia-engram repair-encoding  # Dry-run scan for garbled / mojibake text
piia-engram repair-encoding --apply  # Repair reversible cases with a backup
piia-engram backup-plan      # Metadata-only plan of what to copy before upgrading (local-only)
piia-engram export-agents-md # Export verified, non-sensitive knowledge as an AGENTS.md/CLAUDE.md block
piia-engram stats            # Show project growth metrics (GitHub + PyPI)
piia-engram stats --log      # Append stats snapshot to local log
engram telemetry        # Manage anonymous usage statistics
engram privacy          # Show what data piia-engram stores and where

Contribuindo

Contribuições, problemas e feedback são bem-vindos.

Veja CONTRIBUTING.md.

Licença

AGPL-3.0. O piia-engram é software livre. Sua identidade de trabalho de IA e memória pertencem a você.