convez.ai
MCP ServerAutomaçãoIntermediário
scops

Engrama

scops/engrama

Memória estruturada em grafo para agentes IA, com SQLite ou Neo4j

Ver no GitHub
BomPluginScore · de 0 a 100

Framework de memória de longo prazo baseado em grafo de conhecimento para agentes de IA. Armazena entidades, observações e relacionamentos, permitindo que agentes atravessem o grafo para raciocinar sobre conhecimento acumulado. Suporta SQLite (padrão, sem dependências externas) e Neo4j para cenários multi-processo em produção.

Instalação

$npx convez-ai scops/engrama

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
9
Forks
0
Acompanhando
1
Saúde
85%
Último commit
há 1 semana
Versão
v0.18.1
Issues abertas
2
Contribuidores
3

Casos de uso

  • Agentes com memória persistente e contextual
  • Raciocínio sobre relacionamentos entre entidades
  • Sistemas multi-agente ou multi-tenant com isolamento de dados
  • Busca semântica opcional sem dependência de serviços externos

Veredito

Solução técnica madura (alpha) que resolve um problema real: reconstruir contexto via graph traversal em vez de sobrecarregar o prompt. SQLite zero-dep é excelente para prototipagem; Neo4j adiciona escala. Implementação clara de multi-tenancy e GDPR é destaque.

README

A tradução para o português deste README ainda está na fila.

Engrama

Graph-based long-term memory framework for AI agents.

PyPI Python Backend License Status

Engrama gives any AI agent persistent, structured memory backed by a knowledge graph. Instead of flat key-value stores or opaque vector databases, Engrama stores entities, observations, and relationships — and lets agents traverse that graph to reason about their accumulated knowledge.

Two backends are first-class:

  • SQLite + sqlite-vec (default since 0.9) — single file, zero external services, pip install engrama and you're running.
  • Neo4j 5.26 LTS (opt-in) — for multi-process production setups, large-scale vector search, or teams that already use Cypher.

The data model is identical on both. See docs/backends.md for a full decision guide; the rest of this README assumes the SQLite default.

Since 0.13.0, every node and relation is owned by an (org_id, user_id) identity and reads are fail-closed: a missing or partial scope matches nothing rather than falling back to "see all". A single-process install runs as one stable standalone identity and needs no configuration; a multi-tenant deployment supplies the identity per request from an authenticating gateway. Each identity can permanently erase its own memory through the engrama_gdpr_forget tool (GDPR right-to-erasure). See docs/security.md.

Inspired by Karpathy's second-brain concept, but built for agents instead of humans — and with graphs instead of wikis.


Why graphs?

Flat JSON / KVVector DBEngrama (Graph)
Relationship queries❌❌✅ native
Scales to 10k+ memories❌ slow✅✅
Works without embeddings✅❌✅ (optional)
Local-first / private✅depends✅
Zero external services✅❌✅ (SQLite)
"What projects use FastMCP?"full scanapproximate1-hop traversal

Prerequisites

You need two things to run on the default SQLite backend. Docker is not required unless you opt into Neo4j.

RequirementVersionHow to checkInstall guide
Python3.11 or newerpython --versionpython.org/downloads
uv (Python package manager)any recentuv --versiondocs.astral.sh/uv

Windows users: after installing Python, make sure "Add Python to PATH" is checked. After installing uv, you may need to restart your terminal.

Optional:

  • Obsidian — for vault sync features.
  • A local embedder for semantic search.
  • Docker Desktop — only if you opt into the Neo4j backend.

Quick start (SQLite, zero-dep)

Step 1: Install

From PyPI (recommended):

pip install engrama          # or: uv add engrama

Or from source, for development:

git clone https://github.com/scops/engrama
cd engrama
uv sync

The commands below assume a PyPI install (engrama ...). From a source checkout, prefix each one with uv run (uv run engrama ...).

Step 2: Initialise the schema

engrama init --profile developer

Step 3: Verify

engrama verify

Step 4: Use it

A) From Python:

from engrama import Engrama

with Engrama() as eng:
    eng.remember("Technology", "FastAPI", "High-performance async framework")
    eng.associate("MyProject", "Project", "USES", "FastAPI", "Technology")
    results = eng.search("microservices")

B) From the command line:

engrama search "FastAPI"
engrama reflect

Quick start (Neo4j, opt-in)

If you need multi-process writes, very large vector indexes, or an existing Cypher toolchain, install with the Neo4j extra:

pip install "engrama[neo4j]"     # or, from source: uv sync --extra neo4j

Configure your credentials by copying .env.example to .env and setting GRAPH_BACKEND=neo4j. Start Neo4j with docker compose up -d, and then initialize the schema:

engrama init --profile developer
engrama verify

Hosted (beta)

Engrama is built to be self-hosted: pip install, and it runs on your machine with your data in a local file. If you would rather not operate and secure a remote instance yourself, engrama.sinensia.com is a managed deployment of this same server — EU-hosted, OAuth 2.1 in front of /mcp, per-identity isolation and GDPR erasure already wired, with setup guides for Claude, ChatGPT, Gemini, Cursor, VS Code, Windsurf, Zed and Codex.

It is invitation-only during the beta: request access. The open-source server in this repository is not a cut-down edition of it — same tools, same graph model, same code.


Security considerations

Engrama stores everything an agent learns, so treat the memory graph as sensitive data. The full policy lives in docs/security.md; the essentials:

  • Data residency. On the default SQLite backend all data lives in a single local file (~/.engrama/engrama.db by default) — nothing leaves your machine. It is plain SQLite: keep it off shared filesystems, back it up, and rely on filesystem permissions for at-rest protection. On the Neo4j backend, data resides wherever you host Neo4j; you own that deployment and its region.
  • Neo4j authentication. Supply credentials through .env / environment variables (NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD) — never commit them. The shipped docker-compose.yml is for local dev; change the default password and enable TLS before any networked use.
  • Embedding providers. Endpoints reached via OPENAI_BASE_URL should use HTTPS unless they are on localhost or a trusted network. With EMBEDDING_PROVIDER=none no text is sent anywhere; search degrades to fulltext-only.
  • Tenant isolation. Since 0.13.0 every node and relation is owned by an (org_id, user_id) identity and reads are fail-closed. A single install runs as one stable standalone identity; a multi-tenant deployment must inject the identity per request from an authenticating gateway (set ENGRAMA_REQUIRE_IDENTITY=1 to fail closed on missing headers). See docs/security.md.
  • Right to erasure. Each identity can permanently erase its own memory via the engrama_gdpr_forget tool (GDPR). There is no undo and no server-side backup.
  • Network exposure. The MCP server is meant for a local client. The optional Streamable HTTP transport ships without authentication — keep it on loopback or behind your own authenticated gateway, or use the hosted service, which puts OAuth 2.1 in front of it.

📚 Full Documentation

All further details, including MCP integration (Claude Desktop), Obsidian sync, Architecture, and the complete API Reference, are available in the official documentation.

👉 Read the Full Documentation

Ver o original no GitHub

Bom para