Engraphis

Engraphis

https://engraphis.com/

https://discord.com/invite/Wfr2ejBmY

Dê aos seus agentes de IA uma memória. Veja-a, pesquise-a e mantenha-a, tudo em uma bela WebUI na sua própria máquina.

^{Knowledge Graph · execute engraphis-dashboard para vê-lo ao vivo}

Fundamentado, não adivinhado. Memória com comprovantes. Local por padrão.

Limite do open-core: este repositório contém o mecanismo local gratuito, o dashboard, o servidor MCP, e os clientes do lado do cliente. Sincronização hospedada, análises, automação e serviços de equipe rodam no serviço hospedado oficial; suas implementações de servidor não são distribuídas aqui.

Apoie o desenvolvimento contínuo do Engraphis com o Pro. Inicie um teste Pro de 7 dias ou assine o Pro.

Economia medida de tokens e contexto

Estimador em tempo de execução

As visualizações de Visão Geral e Auditoria/Comprovantes do dashboard também mostram uma estimativa baseada em comprovantes de entregas reais de contexto. Ela compara o histórico do host ou a linha de base da fonte recuperada com o contexto que o Engraphis realmente emitiu, mantém contadores de tokens e versões de lançamento separados, e rotula reduções adaptativas de histórico separadamente das economias de empacotamento. Comprovantes sem metadados de estimador permanecem históricos/não classificados. Isso mede a redução estimada do contexto do prompt; não mede a cobrança do provedor. A API /context-savings e a ferramenta MCP engraphis_context_savings agregam o histórico completo em todos os espaços de trabalho visíveis por padrão, ou aceitam um espaço de trabalho explícito mais filtros opcionais from_ts, to_ts e release_version.

^{Menos histórico repetido significa mais espaço para a tarefa, ferramentas e evidências úteis.}

python -m eval.grounded
python -m eval.chunking_eval --dataset eval/datasets/longdoc.jsonl --k 5
python -m eval.performance --dataset eval/datasets/codemem.jsonl --k 5 --iterations 10 --json

Instalação completa do Engraphis: pip install "engraphis[all]"

A instalação completa do engraphis[all] é a maneira padrão de usar o Engraphis: ela inclui o dashboard local, servidor Smart MCP, documentos, cliente Cloud Sync e integrações opcionais suportadas. Python 3.10+ é necessário.

pip install "engraphis[all]"
engraphis-dashboard

O dashboard abre em http://127.0.0.1:8700. Memória local não precisa de conta ou chave de API.

Opções de instalação menores

Use um pacote menor apenas quando você intencionalmente precisa de uma superfície limitada. O núcleo somente NumPy continua suportando Python 3.9+.

Para clientes MCP diferentes do Codex, configure um servidor stdio cujo comando seja engraphis-mcp; veja o guia de conexão de agentes.

Atualização

Use engraphis-update para atualizar a instalação usando seu método de instalação detectado. Os metadados do pacote não registram quais extras foram selecionados, então o atualizador usa o padrão do superconjunto seguro engraphis[all] em vez de descartar silenciosamente uma superfície opcional. Para uma seleção deliberada, defina ENGRAPHIS_UPDATE_EXTRAS para uma lista separada por vírgulas (por exemplo, server,mcp), ou defina-o para none apenas para o pacote base.

Atualizando para 1.4: engraphis-mcp agora expõe o gateway Smart de nove ferramentas. Integrações que exigem os antigos 35 nomes diretos de ferramentas devem executar engraphis-mcp-classic. O esquema SQLite na versão 1.4.0 era a versão 9. Bancos de dados existentes v7-para-v8 já contêm confidence e pinned_at/unpinned_at; v9 adiciona a coluna/tabela de escopo de repositório memory_tombstones e realiza um reparo único de canonicalização de entidades, depois migra automaticamente na primeira abertura. Um tombstone com um repo_id conhecido é terminal apenas naquele repositório; tombstones legados sem repositório permanecem globais. Veja as notas de lançamento 1.4.0.

Atualizando para 1.5: o esquema 10 limita o estado de retenção legado e o esquema 11 preenche aprovação explícita apenas para memórias locais elegíveis de pré-revisão. Evidências pendentes e em quarentena permanecem bloqueadas. Bancos de dados 1.4.x existentes migram automaticamente quando o Engraphis 1.5 os abre; veja as notas de lançamento 1.5.

Atualizando para 1.6: bancos de dados 1.5 existentes migram automaticamente através do esquema 12, que classifica marcadores de apagamento sem conteúdo antes da sincronização: marcadores existentes tornam-se never_export somente locais, enquanto novos apagamentos seguros tornam-se remote_erasure apenas para registros workspace/repo não secretos já elegíveis para compartilhamento. O esquema 13 adiciona relógios lógicos híbridos por memória para sincronização determinística de estado descritivo e prova durável e sem conteúdo de que uma memória cruzou um limite de sincronização. O esquema 14 adiciona o manifesto de coleção e importação do Obsidian; o esquema 15 os generaliza para documentos locais neutros em fonte, preserva a linhagem temporal da fonte em reimportações, vincula adaptadores e escopos de destino, e retém apenas metadados de formato/resultado por trabalho limitados e sem conteúdo. A migração do esquema 16 persiste o destino de sessão opcional de cada trabalho de importação e exige que a linhagem da fonte e os anexos de itens do trabalho permaneçam nessa sessão exata. Veja as notas de lançamento 1.6.

O que o Engraphis dá a um agente

Um agente não deve ter que reconstruir um projeto a partir de histórico de chat disperso em cada tarefa. O Engraphis transforma conhecimento local do projeto em memória com escopo e ciente do tempo; recupera a evidência que suporta a pergunta atual; e retorna um pacote de contexto limitado e atribuível.

A tarefa central é continuidade: recuperar a decisão atual e suportada do projeto sem arrastar todo o histórico para o próximo prompt. Veja economia medida de tokens e contexto para a versão curta de quanto menos histórico um agente precisa carregar.

Painel e interface local

O painel do Engraphis abre http://127.0.0.1:8700. A memória local não precisa de conta na nuvem, cadastro ou chave de API e permanece em um arquivo SQLite na sua máquina.

Ledger é a principal interface local para recordação, memórias, exploração de grafos, proveniência, workspaces e consolidação manual. Classic preserva o antigo conjunto completo de ferramentas; ambos usam os mesmos dados locais. Alterne em Manage → Settings → Interface (Ledger) ou Settings → Appearance & Engine (Classic).

Inicie em todas as plataformas

Em um checkout do código-fonte, scripts/launch_dashboard.ps1 é apenas um wrapper de conveniência para Windows. Ele delega configuração, verificação de saúde na inicialização, abertura do navegador e ciclo de vida do processo ao mesmo entrypoint engraphis-dashboard em vez de manter um segundo caminho de comportamento.

Inspeção com acessibilidade em primeiro lugar, integrada

Inspecione memórias, diffs de substituição, pontuações de recordação, linhas do tempo, links, consolidação e registros de auditoria no painel. O renderizador de grafos offline é fornecido, e a interface é navegável por teclado com temas claro e escuro. A exploração de grafos oferece uma visão focada em Alta qualidade e uma visão explícita Cada nó com suporte de worker para projeções completas de entidades de até 20.000 nós e 200.000 relacionamentos; veja os perfis de desempenho de grafos.

Como funciona

O Engraphis dá aos agentes conhecimento de projeto durável, com escopo e explicável. O mecanismo local combina decadência de Ebbinghaus, fatos bi-temporais e recordação híbrida vetorial/lexical/grafo; ele roda offline com SQLite, embeddings locais e apenas numpy.

• Fundamentado e governado: resolução determinística de conflitos, respostas citadas ou abstenção, correção/promoção/esquecimento explícitos e um histórico completo.
• Pronto para agentes: ferramentas MCP, pacotes de contexto com orçamento rígido, handoffs e recuperação ciente de código.
• Auditável: cadeias de recibos sem conteúdo, proveniência e relações temporais/entidade/código.
• Prático: ingestão local de arquivos e código, PDF/OCR/transcrição opcionais e SQLCipher em repouso.

Provedores de LLM opcionais

O mecanismo de memória, embeddings, resolução de conflitos e recordação permanecem locais sem um LLM. Um provedor explicitamente configurado adiciona extração estruturada, síntese citada, consolidação e supervisão de retenção. Configure em Settings → Connect an LLM. A visualização de atividade registra resultados, nunca chaves, prompts ou respostas brutas do provedor. Veja o guia de provedores de LLM para configuração e opções de privacidade.

Limite de privacidade: texto enviado a um provedor explicitamente selecionado sai do processo local sob os termos desse provedor. Use ENGRAPHIS_RETENTION_SUPERVISOR=none (o padrão) e o extrator offline chunk quando a ingestão precisar permanecer totalmente local.

Escolha e configure um LLM externo com o guia de provedores de LLM, incluindo OpenAI, Anthropic, Google, OpenRouter, Ollama, Cohere Command, Command Code Provider, e outros endpoints compatíveis. O guia também cobre conexões MCP de assinatura Codex.

Instalação

pip install "engraphis[all]"        # self-hosted dashboard, MCP, code graph, documents, transcription, PostgreSQL, and Cloud Sync
pip install "engraphis[server]"     # dashboard + REST API
pip install "engraphis[mcp]"        # MCP server only
pip install "engraphis[documents]"  # PDF + image OCR bindings
pip install "engraphis[transcription]" # faster-whisper audio/video
pip install "engraphis[postgres]"   # PostgreSQL schema introspection
pip install "engraphis[code]"       # tree-sitter code graph indexing
pip install "engraphis[vector]"     # native sqlite-vec exact-KNN acceleration
pip install "engraphis[cloud-sync]" # Cloud Sync client crypto/runtime
pip install "engraphis[encryption]" # SQLCipher encryption-at-rest extra
pip install engraphis               # core library: numpy only, fully offline

A imagem Docker oficial inclui o executável local Tesseract para OCR de imagens. Fora do Docker, o extra documents instala seus bindings Python; instale o Tesseract através do seu sistema operacional também se você habilitar OCR de imagens.

A biblioteca principal somente NumPy suporta Python 3.9+. As versões corrigidas atuais da pilha WebUI, SDK MCP, parser de imagens e cliente Cloud Sync exigem Python 3.10+, então use Python 3.10 ou mais recente para os caminhos de instalação server, mcp, documents, cloud-sync ou all.

O NumpyVectorIndex padrão realiza uma varredura completa exata. Não há um limite universal de contagem de memória porque a latência depende do tamanho do vetor, hardware, filtros e o restante do pipeline de recordação. Meça sua máquina com python -m eval.vector_scale --backend numpy, depois execute python -m eval.performance em um corpus representativo. Se as varreduras exatas perderem seu alvo de latência, instale engraphis[vector], crie o mecanismo com vector_backend="sqlite-vec" e meça novamente. O backend estável sqlite-vec vec0 executa KNN exato em código nativo; é aceleração, não uma afirmação de escalonamento ANN sublinear. Veja BENCHMARKS.md para os comandos reproduzíveis e limites de relatório.

Os entrypoints do painel, REST e MCP usam por padrão ENGRAPHIS_VECTOR_BACKEND=auto: eles usam sqlite-vec quando o extra vector está instalado e é compatível, então caem com segurança para NumPy. Os MemoryEngine.create() e MemoryService.create() programáticos mantêm o padrão determinístico numpy a menos que um backend seja solicitado explicitamente. Use python -m eval.vector_scale --backend sqlite-vec para uma comparação de busca direta com entrada idêntica; o tempo de configuração/construção do índice é explicitamente excluído do envelope de busca cronometrado.

Vetores persistentes falham fechados, a menos que o embedder possa publicar uma impressão digital de espaço durável e sem segredos. Sentence Transformers usam o commit do Hub carregado ou um manifesto de artefatos locais; quando a identidade imutável de um modelo remoto não pode ser resolvida, a recordação de vetores persistentes permanece bloqueada em vez de misturar espaços. Para embeddings programáticos compatíveis com OpenAI, construa ApiEmbedder com um space_version de operador/provedor; sem ele, o adaptador permanece utilizável apenas para embedding efêmero. Seu base_url pode ser uma raiz de provedor ou uma raiz /v1 e é normalizado para exatamente um endpoint /v1/embeddings.

sqlcipher3-binary publica wheels CPython manylinux x86-64. Nesse alvo, engraphis[encryption] instala o driver. O extra multiplataforma all deliberadamente o omite para que all permaneça resolvível em macOS, Windows, Linux ARM e musl; nesses alvos, provisione um driver SQLCipher compatível separadamente antes de habilitar uma chave de banco de dados. O núcleo programático permanece em texto simples, a menos que uma chave de banco de dados seja configurada. Para um banco de dados novo, engraphis-init habilita SQLCipher automaticamente quando um driver compatível está disponível, cria um sidecar de chave privada e pode ser substituído com --no-encryption.

Linux / macOS: se pip install falhar com error: externally-managed-environment, seu Python do sistema está marcado como somente leitura (PEP 668). Instale em um ambiente virtual em vez disso. Execute python3 -m venv venv && source venv/bin/activate && pip install "engraphis[server]" Alternativamente, use Docker (docker compose up). pipx install "engraphis[server]" também funciona.

A primeira execução baixa all-MiniLM-L6-v2 (~80 MB). Sem ele, o mecanismo cai para hashing de características determinístico para que sempre rode offline. Esse fallback captura sobreposição lexical, não significado: recordação e respostas MCP fundamentadas definem degraded_mode=true e semantic_support=false, e desabilitam recuperação vetorial mais evidência de cosseno semântico. Instale um modelo de embedding declarado para recuperação semântica.

Para exigir um modelo que já está local, defina ENGRAPHIS_EMBED_MODEL=local:/absolute/model/path ou local:<cached-model-id>. Este caminho nunca baixa um modelo. Se ele estiver indisponível, o Engraphis entra explicitamente em modo degradado lexical em vez de apresentar pontuações de vetor hash como semânticas.

Início rápido: painel

pip install "engraphis[server]"
engraphis-dashboard                   # → http://127.0.0.1:8700
engraphis-dashboard --install-shortcuts   # → Desktop + Start Menu icons

Primeira execução offline: o primeiro lançamento baixa o modelo de embedding all-MiniLM-L6-v2 (~80 MB), então roda totalmente offline. Para permanecer somente offline, defina ENGRAPHIS_EMBED_MODEL=local:/absolute/model/path (nunca baixa; modelos locais desconhecidos entram em modo degradado lexical em vez de fingir pontuações semânticas). A extração usa por padrão ENGRAPHIS_EXTRACTOR=none (escritas verbatim), o backend de vetores usa por padrão auto (aceleração nativa quando instalada, caso contrário NumPy), e recordação sem um espaço semântico utilizável relata degraded_mode=true com recordação lexical/grafo. Execute engraphis-init --check para verificar a instalação, extras e capacidade de escrita do banco de dados.

Docker

docker compose up                     # → http://127.0.0.1:8700

Para persistência do Docker Compose e configuração de porta loopback, veja o guia de implantação Docker. engraphis-server e engraphis server são aliases de compatibilidade headless para este mesmo serviço v2, então toda superfície pública tem o mesmo modelo de recordação e retenção com escopo.

Para exposição opcional em LAN, configuração de token e configuração MCP HTTP, veja o guia de implantação Docker.

Defina ENGRAPHIS_API_TOKEN para exigir autenticação de API e ENGRAPHIS_DB_KEY para criptografar o banco de dados local em repouso. Credenciais de planos hospedados configuram clientes de clientes; elas não instalam implementações de servidor premium nesta imagem. Veja docker-compose.yml para opções.

Início rápido: servidor MCP (para agentes de codificação)

pip install "engraphis[mcp]"
engraphis-init                     # writes ~/.engraphis/config.env + prints config snippets
claude mcp add engraphis -- engraphis-mcp
codex mcp add engraphis -- engraphis-mcp  # Codex subscription

Primeira execução offline: a primeira chamada de ferramenta carrega lentamente o modelo de embedding all-MiniLM-L6-v2 (~80 MB, mesmo download do painel), então a memória roda totalmente offline sem chave de API. Para permanecer somente offline, defina ENGRAPHIS_EMBED_MODEL=local:/absolute/model/path (nunca baixa); a extração usa por padrão ENGRAPHIS_EXTRACTOR=none, o backend de vetores auto cai para NumPy sem o extra vector, e recordação sem um espaço semântico utilizável relata degraded_mode=true com recordação lexical/grafo. Execute engraphis-init --check para verificar a instalação e o caminho do banco de dados antes de registrar o servidor.

Para configuração e verificação de assinatura Codex, veja o guia de conexão de agente e o guia de provedores de LLM.

engraphis-mcp é Smart MCP de configuração zero: agentes começam com nove ferramentas compactas para sessões, recordação pronta para prompt, memória durável, leitura/atualização de registros governados, revisão de conflitos, descoberta de ações e execução segura. Para grafos de código, governança, auditoria ou outro trabalho avançado, o agente chama engraphis_discover_actions e depois o executor de leitura ou ação indicado; nenhuma seleção de perfil é necessária. O gateway valida a capacidade descoberta novamente antes de executá-la, e os clientes permanecem responsáveis por seu limite normal de aprovação de ações destrutivas.

Clientes existentes que usam ferramentas nomeadas podem usar engraphis-mcp-classic (ou engraphis-mcp-http --classic). O inventário clássico completo, incluindo engraphis_check_update, está na referência de ferramentas MCP.

Escolha onde as memórias do agente pertencem

Use a configuração de conexão do agente no dashboard para escolher um workspace, salvar um mapeamento de repositório para workspace e copiar instruções específicas do agente para o projeto. Chamadas MCP rotineiras com um workspace omitido podem herdar a sessão fornecida ou o mapeamento de repositório salvo. Valores explícitos de workspace, incluindo "default", têm precedência; atualize instruções ou hooks mais antigos que os codifiquem. Os tipos de memória descrevem o tipo de memória, não seu destino. Consulte organização do workspace para configuração, precedência de roteamento e pré-visualização de movimentações de memórias existentes.

Extensão Pi

Para instalação, configuração, comandos de ciclo de vida e o limite de confiança local, consulte o guia da extensão Pi.

Hook Command Code SessionStart

integrations/commandcode/ inclui um hook SessionStart que aquece uma nova sessão com contexto limitado e recuperado do gateway Engraphis local. Falha aberta em timeout e é instalado via python scripts/install_cc_hook.py. O hook envia o nome da raiz Git mais próxima como repo e permite que o servidor aplique um mapeamento de workspace salvo. Defina ENGRAPHIS_HOOK_WORKSPACE apenas para uma substituição explícita; uma substituição anterior de default deve ser limpa para usar o mapeamento. Seu cabeçalho de contexto mostra o workspace resolvido. Versões anteriores usavam como padrão um workspace nomeado após a pasta do projeto; salve esse mapeamento para continuar recuperando essas memórias no início da sessão.

frota prime-agent

integrations/prime_agent/ inclui um pacote Python de primeira parte para PrimeIntellect prime-agent que expõe as mesmas nove ferramentas Smart MCP, com um PrimeAgentFleet de oito subagentes nomeados (researcher, planner, coder, reviewer, tester, documenter, monitor, integrator) compartilhando um engraphis-mcp stdio subprocesso. Instale via pip install ./integrations/prime_agent e registre com python scripts/install_prime_agent.py. Consulte o guia de integração prime-agent.

O que é a integração. Um PrimeAgentFleet é uma camada Python fina em torno do mesmo gateway Smart engraphis-mcp que todos os outros hosts usam. Em tempo de execução, a frota mantém um EngraphisMcpClient compartilhado, que possui um subprocesso engraphis-mcp via JSON-RPC stdio. Cada um dos oito subagentes nomeados recebe sua própria sessão Engraphis (iniciada lentamente no primeiro uso da ferramenta) e seu próprio escopo padrão de repo, para que a memória por função seja isolada enquanto o gateway local permanece em processo único. Os oito nomes de subagentes (researcher, planner, coder, reviewer, tester, documenter, monitor, integrator) são o padrão fixo; passe agent_names=[...] para PrimeAgentFleet(...) para um conjunto personalizado. Chamadas de ferramentas concorrentes são serializadas na camada de quadro JSON-RPC por meio de um asyncio.Lock, para que o paralelismo no nível do framework (oito subagentes raciocinando ao mesmo tempo) seja preservado enquanto o transporte MCP subjacente permanece como um fluxo ordenado. A única superfície de integração é EngraphisPrimeAgent.register() em integrations/prime_agent/src/engraphis_prime_agent/agent.py — esse é o único ponto de adaptação para substituir se a API de registro de ferramentas do prime-agent diferir do contrato assumido de target.register_tool(name, fn, schema=...).

O design — oito subagentes nomeados, um subprocesso stdio compartilhado, inicialização de sessão por agente e encaminhamento de ambiente somente com ENGRAPHIS_* para o gateway — está registrado em ~/.commandcode/plans/prime-agent-integration.md no host onde a integração foi desenvolvida. Quando esse plano de host não estiver disponível (outras máquinas de colaboradores, CI), o mesmo design é resumido na descrição do PR que introduziu a integração e no guia de integração prime-agent (seções "Arquitetura" e "Modelo de concorrência").

Início rápido: grafo de repositório

pip install "engraphis[code]"
engraphis-graph index -w acme -r api --root .
engraphis-graph search -w acme -r api "UserService"
# `query`/`explain` blend code search with your stored memories: query matches symbol
# and file NAMES (a full question sentence won't match anything), and explain's answer
# is drawn from memories recorded against the repo; both are empty on a fresh index.
engraphis-graph query -w acme -r api "UserService"
engraphis-graph explain -w acme -r api "why does deploy depend on approval?"
engraphis-graph path -w acme -r api UserService DatabasePool
engraphis-graph impact -w acme -r api --root . --git-range origin/main...HEAD
engraphis-graph prs -w acme -r api --base main --head HEAD
engraphis-graph export -w acme -r api -o engraphis-graph-out
engraphis-graph install-merge-driver --root .

A exportação contém graph.json, um graph.html autônomo e GRAPH_REPORT.md. A indexação suporta Python, JavaScript, TypeScript, Go, Rust, Java, C#, C, C++, SQL e Terraform. Tree-sitter é usado quando disponível; o backend de regex sem dependências permanece como um fallback funcional. Definições, métodos, chamadas, importações, propriedade, variáveis, herança/implementação e docstrings/comentários são indexados. A indexação é incremental por hash de conteúdo, respeita .engraphisignore e não segue symlinks de arquivos fora da raiz do repositório. As arestas de chamada são baseadas em nome e de melhor esforço, em vez de resolvidas por tipo. O driver de merge Git opcional valida JSON de grafo limitado e une deterministicamente nós e arestas em vez de escolher um lado da exportação.

Para uma API de recuperação somente leitura e de grafo que pode ser compartilhada sem expor operações de escrita:

pip install "engraphis[server]"
engraphis-graph-server                 # API at http://127.0.0.1:8720; schema at /openapi.json

Uma vinculação não-loopback falha fechada, a menos que ENGRAPHIS_GRAPH_TOKEN (ou ENGRAPHIS_API_TOKEN) esteja definido. Consulte o documento de arquitetura/design v3.

Início rápido: biblioteca Python

from engraphis.service import MemoryService

mem = MemoryService.create("engraphis.db")
mem.remember("Auth migrated from JWT to PASETO.", workspace="acme", repo="api")
hit = mem.recall("why did we change auth?", workspace="acme", repo="api")
print(hit["context"])

O mesmo MemoryService alimenta o dashboard e o servidor MCP. A raiz do pacote também expõe intencionalmente a fachada do mecanismo de baixo nível (MemoryEngine, create_memory_engine) para composição avançada, enquanto MemoryService permanece como a API de serviço de alto nível.

Novas gravações suportam visibilidade session, repo e workspace. scope="user" é reservado e rejeitado até que os registros carreguem uma identidade de proprietário imutável; não deve ser tratado como memória privada por pessoa. Linhas históricas de escopo do usuário permanecem vinculadas ao workspace para compatibilidade.

Após uma atualização, stats() relata contagens de elegibilidade de prompt e cobertura ativa do espaço de incorporação. Recuperação com zero resultados identifica um escopo revisado por gate em vez de parecer vazio silenciosamente, e engraphis-cli review list|approve fornece um fluxo de trabalho local em massa com simulação primeiro. Mudanças no modelo de incorporação disparam uma reconstrução protegida; a recuperação vetorial permanece desativada até que cada vetor armazenado corresponda à nova impressão digital. Consulte recuperação de recall.

Os hosts de agentes podem evitar a recuperação quando seu histórico existente já se encaixa:

decision = mem.adaptive_context(
    "what should the agent do next?",
    current_history,
    workspace="acme",
    repo="api",
    max_context_tokens=8_192,
    retrieval_token_budget=1_024,
)
prompt_context = decision["context"]

A decisão é history_bypass quando o histórico se encaixa, retrieval quando a evidência compacta é forte e history_fallback quando a recuperação fraca deve ampliar de volta para o histórico bruto recente.

Para um prompt de agente, prefira engraphis_recall_context: ele retorna um context compactado com orçamento rígido mais sources compacto, contabilidade determinística de usage (budget_tokens, context_tokens, source_tokens, saved_tokens, savings_ratio, packed_count, omitted_count e token_counter) e diagnósticos opcionais. A contabilidade é exata para o contador nomeado; injete o tokenizador do leitor quando a paridade de tokens do modelo do leitor for necessária. engraphis_recall permanece como a superfície de recuperação completa compatível; use response_mode="compact" quando o contexto compactado for suficiente e os corpos de memória completos o duplicariam. Para configuração avançada de planejamento de consultas, consulte o guia de arquitetura.

Alternativas orientadas por benchmark são opt-in: packing_mode="coverage" mantém unidades de evidência completas de mais memórias de origem, enquanto retrieval_recipe="conversation" e retrieval_recipe="long_session" selecionam os pontos de partida medidos de profundidade/orçamento. As configurações históricas de legacy/default permanecem inalteradas. Para um valor que deve sobreviver a uma edição de arquivo ou chamada de ferramenta exatamente, as APIs de gravação Smart e Classic engraphis_remember e Python/serviço aceitam exact_value vinculado à origem mais seu exact_value_type. O MCP remember exige uma ocorrência única; as gravações Python/serviço podem selecionar uma ocorrência repetida com exact_value_span. Os metadados de vinculação compactados exigem a fonte de memória completa, preservando condições em qualquer idioma. Espaço em branco de limite fora do valor vinculado pode ser removido. A cobertura retém um grupo vinculado que não cabe; o legado mantém seu texto selecionado, mas omite a vinculação incompleta. Correções e revisões de conteúdo limpam a vinculação antiga quando o conteúdo muda; passe exact_value para vincular explicitamente a substituição, com exact_value_span=[start,end] para uma ocorrência repetida, ou clear_exact_value=true para remover uma vinculação. Conteúdo inalterado e revisões apenas de título preservam vinculações válidas. O histórico preserva o registro original. A remoção de resposta MCP remove metadados de vinculação sempre que seu contexto de suporte é omitido. Para leituras bi-temporais, valid_at seleciona o que era verdadeiro em um timestamp Unix e known_at seleciona o que a Engraphis havia aprendido naquele momento. as_of permanece um alias de compatibilidade para valid_at; fornecer ambos é permitido apenas quando eles coincidem.

Para uma declaração mutável, passe um subject_key estável e um claim_kind opcional, como subject_key="api.rate_limit", claim_kind="configured_value". A resolução de conflitos offline adiciona, reforça, relaciona ou substitui registros de forma determinística, preservando o histórico temporal; ela não precisa de um LLM. Identidades de declaração correspondentes permitem que ela substitua fatos mutáveis substancialmente reformulados. Sem elas, o embedder lexical sem dependências não pode inferir de forma confiável que uma paráfrase é uma contradição, então mantenha ambos os registros ou use uma operação correct explícita.

Governar memórias sem perder o histórico

A Engraphis separa a resolução automática de gravação da governança humana explícita:

A mesclagem manual N→1 está disponível por meio de MemoryService.merge() e POST /api/merge:

a = mem.remember("Deploys happen Friday at 3pm.", workspace="acme")
b = mem.remember("We deploy Fridays around 15:00.", workspace="acme")

merged = mem.merge(
    [a["id"], b["id"]],
    "Deploys ship every Friday at approximately 15:00.",
    workspace="acme",
    reason="deduplicate the deployment schedule",
)
print(merged["compaction"])

retire intencionalmente não é exclusão: preserva o histórico temporal, FTS e evidência vetorial para leituras históricas. Se uma credencial foi capturada, novas gravações são bloqueadas antes do armazenamento; para um vazamento legado, use o MemoryService.secure_erase() explicitamente destrutivo ou POST /api/secure-erase/engraphis_secure_erase. Esse fluxo remove a memória e o índice FTS/vetorial local e as linhas derivadas de grafo/links, executa exclusão segura do SQLite, checkpoint WAL e VACUUM, e verifica backups de recuperação SQLite locais reconhecidos. Ele não pode apagar exportações, snapshots do sistema de arquivos, peers remotos, backups desconhecidos ou informações que um agente em execução/comprometido já leu; rotacione a credencial. Veja limites de apagamento seguro. forget permanece um alias de compatibilidade obsoleto para retire.

Todas as fontes devem pertencer ao workspace nomeado. O resultado herda a sensibilidade de fonte mais restrita, permanece não confiável se qualquer fonte não era confiável e permanece fixado se qualquer fonte estava fixada. A cadeia completa de múltiplos predecessores permanece visível por meio de inspeção, Why e Timeline.

Gratuito para sempre vs. planos hospedados

O mecanismo principal, o dashboard local, o servidor MCP e a consolidação manual são Apache-2.0 e gratuitos. Pro e Team são serviços que fornecem acesso opcional ao serviço hospedado oficial; seus módulos de plano de controle, cobrança, relay, computação e identidade de Team vivem em um repositório privado. Eles não limitam o núcleo local. Veja planos hospedados, licenciamento e Cloud Sync para limites de serviço, ciclo de vida e preços.

Assine o Pro para apoiar o projeto e adicionar serviços hospedados.

Compare planos hospedados quando estiver pronto para avaliar o limite de serviço e as opções de cobrança.

Ferramentas MCP

A Engraphis expõe um gateway Smart MCP de configuração zero além de um servidor de compatibilidade Classic de 39 ferramentas em memória, recuperação, grafos de código, governança, sessões e recibos de auditoria seguros para privacidade. A referência de ferramentas MCP focada é a fonte para o inventário completo e parâmetros.

engraphis_decide fornece decisões tipadas consultivas no Classic MCP; o Smart MCP expõe a mesma ação de decisão por meio de descoberta e engraphis_execute_action. As decisões permanecem locais por padrão. Para usar a franquia Pro ou Team incluída quando o serviço Cloud a ativa, conecte sua instalação por meio do fluxo de conta Cloud comum e defina ENGRAPHIS_DECISION_BACKEND=managed. O portal da conta relata disponibilidade e uso. Para uma chave TypeSafe pessoal, selecione explicitamente byok e forneça TYPESAFE_API_KEY por meio da configuração confiável abaixo; cobranças diretas do provedor podem ser aplicadas.

Toda chamada remota também exige os booleanos literais allow_remote=true e data_classification="public" ou "internal" para o texto fornecido. offline_mode=true impede solicitações remotas. Verificações de comando sempre retornam allow_auto=false, incluindo resultados remotos. As decisões permanecem consultivas e não autorizam execução ou alterações de memória. Veja os detalhes do plano Jev e consentimento.

Grafos e recibos seguros para privacidade

As relações de memória, entidade e código vivem em um único grafo local. A Engraphis também fornece recibos de operação sem conteúdo para evidência de auditoria inspecionável. Veja a arquitetura, referência de ferramentas MCP e política de segurança para o modelo de dados, ferramentas e garantias.

Cloud Sync

O Cloud Sync é um serviço hospedado opcional do Pro/Team. O pacote público inclui o cliente e a implementação de mesclagem determinística; relay hospedado e operações de conta são separados. Veja Cloud Sync para configuração, criptografia, comportamento de mesclagem e troca de pasta local.

O pacote público inclui o mesmo cliente de sincronização como script de console e verbo CLI: engraphis-sync (ponto de entrada instalado), engraphis sync ... e python -m scripts.sync --status para estado somente local sem atividade de rede. Veja Cloud Sync para flags, criptografia, comportamento de mesclagem e troca de pasta local.

Segurança e limites de confiança

A Engraphis é local-first e vincula-se ao loopback por padrão. Leia a política de segurança antes de implantação remota ou integração de recursos externos; ela cobre versões suportadas, proteções de dados, modelo de ameaça e relato de vulnerabilidades.

Criptografia em repouso

Defina ENGRAPHIS_DB_KEY (ou ENGRAPHIS_DB_KEY_FILE) e instale o extra:

pip install "engraphis[encryption]"

O arquivo inteiro do banco de dados de memória principal é criptografado de forma transparente com AES-256 via SQLCipher; a pesquisa de texto completo, o grafo e cada consulta continuam funcionando inalterados. Autenticação do cliente e estado do serviço gerenciado usam suas respectivas proteções de implantação. Quando uma chave é definida para o banco de dados principal, a Engraphis falha fechada com um erro em vez de cair silenciosamente em texto simples. Gere uma chave forte:

python -c "import secrets; print(secrets.token_hex(32))"

Ao usar ENGRAPHIS_DB_KEY_FILE, provisione um arquivo de segredo regular legível apenas pela identidade do serviço. A Engraphis rejeita links, pontos de reanálise, hard links, texto malformado e arquivos de chave superdimensionados em vez de seguir um objeto de sistema de arquivos inesperado.

Um banco de dados de texto simples existente não pode ser aberto com uma chave: migre-o (dump → import em um banco de dados novo com chave). Veja .env.example para todas as opções de criptografia.

Importar arquivos e pastas

O núcleo universal sem dependências verifica Markdown, texto simples, RST, HTML, JSON/JSONL, CSV/TSV, texto de configuração/XML, código-fonte, RTF, DOCX/ODT, XLSX/ODS, PPTX/ODP e EPUB no caminho normal de memória v2. Adaptadores de recursos locais instalados adicionam texto PDF, OCR de imagem e transcrição de áudio/vídeo explicitamente com modelo local. Comece com uma prévia de zero gravação, depois confirme a mesma coleção de fontes explicitamente:

engraphis import documents /path/to/collection --workspace acme --dry-run
engraphis import documents /path/to/collection --workspace acme --repo product --yes

O CLI nunca baixa um modelo de embedding durante a importação. Use um modelo que já esteja em cache, defina ENGRAPHIS_EMBED_MODEL=local:/absolute/model/path ou defina explicitamente ENGRAPHIS_EMBED_MODEL para um valor vazio para usar hashing determinístico sem dependências no modo lexical degradado.

O fluxo Importar documentos locais do dashboard oferece a mesma prévia, escopo de destino, rótulo de fonte, política de conflito, cancelamento e progresso retomável. Reimportações são idempotentes, preservam o histórico temporal e relatam remoções de fonte sem excluir memórias permanentemente. Obsidian permanece o adaptador Markdown rico para frontmatter, aliases, wikilinks e referências de anexos:

engraphis import obsidian /path/to/vault --workspace acme --dry-run

Veja o guia de importação de documentos para formatos suportados, segurança de fonte, comportamento de retomada e conflito, adaptadores opcionais e limitações; veja o guia do adaptador Obsidian para comportamento específico de Markdown.

Consolidação e automação

A consolidação manual é gratuita, local e dry-run por padrão; use o dashboard, SDK, CLI ou MCP. A automação hospedada Pro e Team é computação gerenciada opcional que produz propostas revisáveis em vez de alterar silenciosamente dados locais. Veja planos hospedados, licenciamento e a referência de ferramentas MCP para escopo e uso.

Configuração

Os valores vêm do ambiente do processo. A Engraphis também carrega o ~/.engraphis/config.env privado do proprietário; ENGRAPHIS_ENV_FILE pode selecionar outro arquivo regular privado do proprietário absoluto. Ela nunca pesquisa o diretório de trabalho por .env, e variáveis de processo explícitas vencem.

O reranker cross-encoder opcional depende do modelo e do hardware. Trate sua qualidade e latência como específicas da implantação até que uma identidade de modelo versionada, configuração exata e artefato de avaliação reproduzível estejam disponíveis para a comparação relatada.

Consulte .env.example para o inventário completo de variáveis. Forneça esses valores através do ambiente do processo ou do arquivo de configuração confiável acima; copiá-lo para um ./.env arbitrário não faz o Engraphis carregá-lo.

Fixture de ablação: python -m eval.ablation é uma verificação determinística offline que imprime comparações recall@5 para recuperação somente vetorial e híbrida, braços de grafo multi-hop e políticas de recuperação, além de verificações de idade de recall comum e confiança semântica. Não produz resultados de MRR, hit@5 ou ms/consulta. Use python -m eval.reinforcement para trajetórias de retenção e registre evidências antes de citar qualquer resultado de benchmark.

Estrutura do projeto

engraphis/
├── engraphis/
│   ├── core/                # v2 engine: interfaces, store, recall, scoring, schema, sync
│   ├── backends/            # pluggable embedder / vector index / reranker / codegraph / sync transports / encryption
│   ├── factory.py           # outer v2 composition root; selects and injects concrete backends
│   ├── service.py           # validated MemoryService facade
│   ├── mcp_server.py        # Smart MCP gateway + 39-tool Classic compatibility server
│   ├── dashboard_app.py     # dashboard WebUI (FastAPI)
│   ├── dashboard_assets/    # primary Ledger interface + graph engine
│   ├── classic_assets/      # selectable full operator dashboard backup
│   ├── read_only_api.py     # token-protected recall/repository-graph HTTP surface
│   ├── hosted_client.py     # hosted URLs, plan labels, and endpoint validation only
│   ├── licensing.py         # compatibility facade for hosted presentation metadata
│   ├── cloud_session.py     # rotating hosted customer-session client
│   ├── cloud_features.py    # consented managed-feature protocol client
│   ├── config.py / app.py   # env settings / REST server
│   └── static/              # compatibility dashboard asset paths
├── eval/                    # offline retrieval eval harness + datasets
├── tests/                   # offline-first pytest suite and release/security contracts
├── scripts/                 # dashboard, server, graph, CLI, connect, update, consolidation, sync
├── docs/                    # product, API, hosting, sync, and provider guides
├── Dockerfile / docker-compose.yml
└── pyproject.toml

Nova capacidade pertence ao caminho v2 (engraphis/core/, engraphis/backends/ e MemoryService) por trás das interfaces em core/interfaces.py. Módulos de algoritmo em core/ permanecem agnósticos de backend; engraphis/factory.py é a raiz de composição externa usada por engraphis.create_memory_engine() e o ponto de entrada de compatibilidade MemoryEngine.create(), então injeta os colaboradores selecionados em core/engine.py. O servidor v1 de namespace plano sob engraphis/app.py, routes/, stores/ e engines/ permanece uma superfície de compatibilidade/referência; engraphis-dashboard, o servidor MCP e o quickstart Python acima usam v2.

Licença

Apache-2.0. Consulte LICENSE e NOTICE. "Engraphis" é uma marca do projeto Engraphis; a licença não concede direitos de marca. Código já distribuído sob Apache-2.0 mantém essa concessão; versões posteriores não podem retirá-la retroativamente. O plano de controle hospedado oficial, suas credenciais e registros de produção, operações gerenciadas, suporte e futuros módulos comerciais entregues separadamente estão fora da concessão de código-fonte público. Consulte docs/LICENSING.md para o limite completo.

Candidato de implementação de confiabilidade

O código-fonte atual usa o schema 18 para reparo durável de índice vetorial sem conteúdo e recibos atômicos de comandos de memória. Atualizações usam o caminho de migração de backup verificado existente. O registro de execução de retrabalho registra as descobertas atuais, decisões de compatibilidade, evidências de aceitação, trabalho restante e procedimento de recuperação. Consulte o programa de confiabilidade para implementação exata, validação, migração e limites de lançamento. O processamento gerenciado agora exige aprovação explícita do workspace em Settings. Instalações existentes iniciam com uploads legíveis pausados até confirmação; conectar uma conta não concede aprovação.

Para diagnósticos de configuração, use engraphis-init --check --json. Novas configurações recebem um token de API local privado do proprietário. Configurações existentes são preservadas. Registre as capacidades de instalação selecionadas com engraphis-init --extras server,mcp ou --extras none; atualizações futuras preservam essa escolha. ENGRAPHIS_UPDATE_EXTRAS permanece uma substituição explícita.