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. Explore a galeria de provas ou leia o guia da campanha.

Limite do núcleo aberto: 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 3 dias ou assine o Pro.

Economia medida de tokens e contexto

Estimador em tempo de execução

As visualizações 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 workspaces visíveis por padrão, ou aceitam um workspace explícito mais filtros opcionais de 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, o servidor Smart MCP, documentos, o 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. A 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 precisar 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 por padrão o 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 34 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 v7-para-v8 existentes já contêm confidence e pinned_at/unpinned_at; v9 adiciona a coluna/tabela memory_tombstones de escopo de repositório e executa 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 faz o backfill de 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 a coleção Obsidian e manifestos de importação; 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 limitados e sem conteúdo de formato/resultado por trabalho. 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 deveria ter que reconstruir um projeto a partir de histórico de chat disperso em cada tarefa. O Engraphis transforma conhecimento local de 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 resumida de quanto menos histórico um agente precisa carregar.

Dashboard e UI local

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

Ledger é a interface local principal para recall, memórias, exploração de grafo, 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 de 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 de navegador e ciclo de vida do processo ao mesmo entrypoint engraphis-dashboard, em vez de manter um segundo caminho de comportamento.

Inspeção acessível em primeiro lugar, integrada

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

Como funciona

Engraphis fornece aos agentes conhecimento de projeto durável, com escopo e explicável. O mecanismo local combina decadência de Ebbinghaus, fatos bi-temporais e recall híbrido vetorial/lexical/de gráfico; ele funciona 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, transferências e recuperação ciente de código.
• Auditável: cadeias de recebimento sem conteúdo, proveniência e relacionamentos 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 recall permanecem locais sem um LLM. Um provedor configurado explicitamente adiciona extração estruturada, síntese citada, consolidação e supervisão de retenção. Configure-o em Configurações → Conectar um 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 selecionado explicitamente 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 Tesseract local para OCR de imagens. Fora do Docker, o extra documents instala seus bindings Python; instale o Tesseract também através do seu sistema operacional 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, analisador 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 executa 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 recall. Meça sua máquina com python -m eval.vector_scale --backend numpy e depois execute python -m eval.performance em um corpus representativo. Se as varreduras exatas não atingirem sua meta 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 de Dashboard, REST e MCP usam por padrão ENGRAPHIS_VECTOR_BACKEND=auto: eles usam sqlite-vec quando o extra vector está instalado e é compatível, e 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, o recall de vetor persistente permanece bloqueado 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 execute offline. Esse fallback captura sobreposição lexical, não significado: recall 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, 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

Docker

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

Para persistência do Docker Compose e configuração de porta de 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 recall 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 plano hospedado 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

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 é MCP Inteligente de configuração zero: agentes começam com nove ferramentas compactas para sessões, recall pronto para prompt, memória durável, leitura/atualização de registro governada, revisão de conflitos, descoberta de ações e execução segura. Para gráficos 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 fixam as 34 ferramentas nomeadas históricas 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.

Extensão Pi

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

Provedor Hermes

Engraphis também inclui um plugin nativo de provedor de memória Hermes com pré-busca local, captura de turno limitada, recall com escopo e apagamento seguro explícito. Instale Engraphis no ambiente Python Hermes, copie o provedor e selecione-o com hermes memory setup. Veja o guia de integração Hermes. O provedor nunca se instala ou baixa um modelo de embedding.

Início rápido: gráfico 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 regex sem dependências permanece 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 arquivo 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 gráfico limitado e une nós e arestas deterministicamente em vez de escolher um lado da exportação.

Para uma API de recall e gráfico somente leitura 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

Um bind não-loopback falha fechado a menos que ENGRAPHIS_GRAPH_TOKEN (ou ENGRAPHIS_API_TOKEN) esteja definido. Veja 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 dá suporte ao painel e ao servidor MCP.

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

Após uma atualização, stats() relata contagens de elegibilidade de prompt e cobertura ativa de espaço de embedding. Recall de zero resultados identifica um escopo com revisão obrigatória em vez de parecer vazio silenciosamente, e engraphis-cli review list|approve fornece um fluxo de trabalho local em massa com teste seco primeiro. Mudanças de modelo de embedding disparam uma reconstrução protegida; o recall de vetor permanece desabilitado até que cada vetor armazenado corresponda à nova impressão digital. Veja recuperação de recall.

Hosts de agentes podem evitar 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 evidência compacta é forte, e history_fallback quando recuperação fraca deve ampliar de volta para 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 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 a superfície compatível de recall completo; 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.

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 somente quando eles coincidem.

Para uma afirmaçã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 offline de conflitos 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 afirmaçã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 explícita de correct.

Governar memórias sem perder 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 as linhas locais de FTS/índice vetorial e de grafo/links derivados, 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 de sistema de arquivos, peers remotos, backups desconhecidos ou informações que um agente em execução/comprometido já leu; rotacione a credencial. Consulte limites de exclusão segura. 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 estrita, permanece não confiável se qualquer fonte era não confiável e permanece fixado se qualquer fonte era 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 Team vivem em um repositório privado. Eles não limitam o núcleo local. Consulte 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 34 ferramentas em memória, recall, grafos de código, governança, sessões e recibos de auditoria seguros para privacidade. A referência de ferramentas MCP é a fonte para o inventário completo e os parâmetros.

Grafos e recibos seguros para privacidade

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. Consulte a arquitetura, a referência de ferramentas MCP e a 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 do cliente e a implementação de mesclagem determinística; relay hospedado e operações de conta são separados. Consulte Cloud Sync para configuração, 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ças 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. A autenticação do cliente e o 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 para 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 somente pela identidade do serviço. A Engraphis rejeita links, reparse points, 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). Consulte .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é-visualização de zero gravação e 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 degradado lexical.

O fluxo Importar documentos locais do dashboard oferece a mesma pré-visualização, 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. O 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

Consulte o guia de importação de documentos para formatos suportados, segurança de fonte, comportamento de retomada e conflito, adaptadores opcionais e limitações; consulte 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. Consulte 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.

Consulte .env.example para o inventário completo de variáveis. Forneça esses valores por meio 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.

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 + 34-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 módulos comerciais futuros entregues separadamente estão fora da concessão de código-fonte público. Consulte docs/LICENSING.md para o limite completo.