Description

n8n-nodes-engram

Knowledge graph memory for n8n AI agents
Persistent memory with entity extraction, temporal fact tracking, community detection, graph traversal, and hybrid search.

Installation ·
Upgrade ·
Nodes ·
Storage ·
Extraction ·
Search ·
Security ·
Development

—

> Note: This is a community node. It is not officially supported by n8n. Use at your own discretion.

—

Overview

Engram gives your n8n AI agents a knowledge graph memory. Instead of losing context between conversations, agents build and query a persistent graph of entities (people, organizations, concepts) and the relationships between them.

Every conversation is stored as an episode. An optional LLM extraction pipeline identifies entities and facts from dialogue, building a growing knowledge graph. When the agent receives a new message, Engram searches the graph for relevant facts and injects them as context—giving the agent long-term memory that goes beyond simple chat history.

Highlights

| | Feature | Description |
| — | — | — |
| 4 | n8n Nodes | Memory, Explorer, Admin, Trigger |
| 2 | Storage Backends | Embedded (zero-setup) or Neo4j (production) |
| 5 | Extraction Stages | Entity, dedup, relationships, contradictions, embeddings |
| 3 | Search Modes | Full-text, vector, hybrid RRF fusion |
| 350 | Tests | Unit + integration across 35 test suites |

—

Architecture

—

Product Screenshots

Engram provides dedicated n8n nodes for AI memory, graph exploration, administration, diagnostics, and event-driven workflows.

| Installed nodes | AI Memory node |
| — | — |
| | |

| Explorer actions | Admin operations |
| — | — |
| | |

| Admin diagnostics output | Graph event trigger |
| — | — |
| | |

—

Installation

Via n8n Community Nodes

1. Go to Settings > Community Nodes in your n8n instance
2. Enter n8n-nodes-engram
3. Click Install

Manual

cd ~/.n8n
npm install n8n-nodes-engram

—

Upgrading from v0.4.x

Version 0.5.0 adds episode provenance and governance fields. Storage migration and n8n node-version upgrades are separate steps.

1. Create a current Engram export or storage/database backup before upgrading the package.
2. Upgrade n8n-nodes-engram, restart n8n, and confirm the installed package version.
3. Complete the storage-backend steps below.
4. Run Engram Admin > Monitoring > Diagnostics and confirm that no storage migration remains.
5. Upgrade selected Engram Memory nodes to v2 in an inactive workflow copy before changing production workflows.

Embedded Storage

No migration node is required. On first initialization after the package upgrade, Engram:

• migrates the embedded graph before opening it;
• creates and verifies a backup ending in .pre-schema-2.0.backup.json;
• replaces the graph atomically; and
• leaves the original graph unchanged if backup verification or migration fails.

After initialization, use Engram Admin > Monitoring > Diagnostics to verify the migration and backup status.

Neo4j Storage

Neo4j migration is intentionally operator-controlled so Engram does not perform an unbounded database rewrite during startup.

1. Add an Engram Admin node configured with the same Neo4j credentials as the production memory workflow.
2. Select Lifecycle > Migrate Storage Schema and run Dry Run.
3. Review the matched legacy episode count.
4. Select Migrate, set Confirm Migration to Confirmed, and execute a bounded batch.
5. Repeat until remaining_count is 0, then confirm the result with Monitoring > Diagnostics.

The Neo4j migration is additive and only fills missing governance fields with conservative defaults.

Engram Memory v2

Installing 0.5.0 does not silently change saved Engram Memory nodes. Existing v1 nodes retain their previous behavior until explicitly upgraded through n8n’s node upgrade action.

• Keep Human Episode Kind > Active Human for direct agent conversations.
• Select Passive Human for observed or curated human messages stored by passive ingestion workflows.
• Validate the upgraded node in an inactive workflow copy before replacing the production workflow.

—

Quick Start

Minimal Setup (No LLM Required)

1. Add an Engram Memory node to your AI Agent workflow
2. Connect it to the agent’s Memory input
3. Set Storage Backend to Embedded (Graphology)
4. Leave Knowledge Extraction as Disabled

Your agent now has persistent conversation history stored as episodic memory.

Full Setup (With Extraction)

1. Create an Engram Extraction LLM credential:
– Base URL: OpenAI-compatible endpoint (e.g. https://api.openai.com/v1)
– API Key: Your API key
2. Add an Engram Memory node, enable Knowledge Extraction
3. Select an extraction model (e.g. gpt-4o-mini)
4. Optionally enable Semantic Search (Embeddings) with an embedding model
5. Optionally enable Graph Traversal (BFS) for context enrichment

The extraction pipeline automatically identifies entities and relationships from conversations and builds a queryable knowledge graph.

—

Node Reference

Engram Memory

> AI Memory node—connects to the AI Agent memory input.

On each conversation turn, Engram Memory:

• Loads relevant facts from the knowledge graph as system context, plus recent chat history
• Saves messages as episodes, optionally running the full extraction pipeline

| Setting | Description | Default |
| — | — | — |
| Storage Backend | Embedded (Graphology) or Neo4j | Embedded |
| Knowledge Extraction | LLM-powered entity extraction | Disabled |
| Store Human Episodes | Persist human messages as episodes (v2) | Enabled |
| Human Episode Kind | Classify human input as active or passive provenance (v2) | Active Human |
| Store AI Episodes | Persist assistant replies as episodes (v2) | Enabled |
| Extract from Human Messages | Allow human content to produce facts (v2) | Enabled |
| Extract from AI Messages | Allow assistant content to produce facts (v2) | Disabled |
| Semantic Search | Vector embeddings for hybrid search | Disabled |
| Graph Traversal | BFS enrichment from matched entities | Disabled |
| Context Window | Recent turns to include | 10 |
| Max Facts per Query | Facts injected as context | 10 |
| Min Relevance Score | Threshold for inclusion (0–1) | 0.5 |
| Retention Policy | Episode lifecycle management | Forever |

Existing saved Engram Memory nodes retain their original node version and behavior when the package is upgraded. Use n8n’s node upgrade action on a workflow copy to adopt v2 controls. Passive ingestion workflows should select Human Episode Kind > Passive Human, while direct agent conversations should keep the default Active Human classification.

Engram Explorer

> Regular node—CRUD operations on the knowledge graph.

| Resource | Operations |
| — | — |
| Entity | Create, Get, Get by Name, List, Search, Update, Delete |
| Relationship | Create, Get, Get Between, Get for Entity, Search, Review, Update, Delete, Get Changelog |
| Episode | Get, Get Recent, Get by Date Range, Get Count, List, Update, Delete |
| Traversal | BFS from Entity, BFS from Episodes |

Engram Admin

> Regular node—administration and analysis.

| Resource | Operations |
| — | — |
| Monitoring | Stats, List Groups, Group Stats, Embedding Coverage, Diagnostics |
| Lifecycle | Apply Retention, Purge Episodes, Migrate Storage Schema, Clear Group, Bulk Clear Groups, Clear All |
| Hygiene | Orphaned Entities, Duplicate Entities, Expire Stale Edges, Rebuild Search Index, Backfill Embeddings |
| Portability | Export, Import |
| Analysis | Detect Communities |

Engram Trigger

> Polling trigger—fires when new entities, relationships, or episodes appear in the graph.

Operational Diagnostics

Engram Admin includes a read-only Monitoring > Diagnostics operation for production checks. By default it returns quick storage and graph counts only. Optional deep checks scan the full graph to report embedding coverage, expired/invalidated edges, dangling edges, and duplicate entity-name groups.

Use Monitoring > Embedding Coverage to check whether entities and facts have vectors before enabling hybrid search broadly. Use Hygiene > Rebuild Search Index to rebuild the embedded full-text index from stored graph data. Use Hygiene > Backfill Embeddings in dry-run mode first, then disable dry-run to fill missing embeddings with the configured embedding model.

Explorer entity and relationship searches can optionally return retrieval diagnostics. The aggregate trace shows active filters, bounded candidate scores and decisions, rejection reasons, and which complete items fit the context preview budget. Diagnostics are disabled by default.

Import, Export, and Backups

Engram exports use graph format 2.0 and include count metadata and a SHA-256 checksum. Imports support Dry Run mode, optional maximum item limits, checksum verification before migration, migration reporting, and reference-integrity warnings before writing data. Existing 1.0 backups remain importable; episodes without provenance are classified as legacy, unverified, and proposed rather than being accepted automatically.

Embedded storage upgrades automatically before the graph is opened. Engram creates and verifies an owner-readable backup beside the storage file, writes the migrated graph with atomic replacement, and stops without changing the source if backup verification or migration fails. The backup name ends with .pre-schema-2.0.backup.json, and Monitoring > Diagnostics reports its path and verification state.

Neo4j remains available during an upgrade and does not perform an unbounded startup rewrite. Use Lifecycle > Migrate Storage Schema in Dry Run mode to inspect the remaining legacy episode count, then apply confirmed bounded batches until the remaining count reaches zero. The migration is additive: it only fills missing governance fields with conservative legacy defaults.

For a staged restore, first run the import in Dry Run mode and review the source/target versions, default counts, and warnings. Keep the original export unchanged, then perform the write import only after the report matches expectations. Export the restored graph again to create a checksummed 2.0 backup.

To remove historical monitor or tool pollution, use Explorer episode filters to inspect the affected source, kind, trust level, or date range. Then run Admin Lifecycle > Purge Episodes in dry-run mode before confirming the bounded purge.

For production Neo4j deployments, see docs/production-neo4j.md. Ready-to-import starter workflows are available in docs/workflows/.

—

Storage Backends

| | Embedded (Graphology) | Neo4j |
| — | — | — |
| Setup | Zero configuration | Requires Neo4j instance |
| Persistence | JSON file on disk | Neo4j database |
| Vector search | Brute-force cosine similarity | Brute-force cosine similarity |
| Best for | Development, single-instance | Production, multi-instance |
| Scaling | Single n8n instance | Independent of n8n lifecycle |

Both backends implement the same IGraphStorage interface. All features work identically on either backend.

—

Knowledge Extraction

When enabled, the extraction pipeline processes each conversation turn:

User message + AI response
        |
   Entity Extractor ── identifies people, orgs, locations, concepts
        |
   Entity Deduplicator ── merges "Bob Smith" with "Bob"
        |
   Relationship Extractor ── extracts facts ("Alice works at Acme")
        |
   Contradiction Detector ── flags conflicting facts
        |
   Embedding Generator ── (optional) vectors for semantic search

Supported providers: Any OpenAI-compatible API—OpenAI, OpenRouter, Ollama, LM Studio, Together AI, and others.

Configurable entity types: person, organization, location, concept, event, or custom types.

Extracted entities and relationships include attributes.engram_extraction provenance metadata with source, extraction timestamp, confidence placeholder, review status, and related episode UUIDs where available.

—

Search

| Mode | Description | Requirements |
| — | — | — |
| Full-text | Keyword search on names, summaries, and facts | None |
| Vector | Cosine similarity on embedding vectors | Embeddings enabled |
| Hybrid RRF | Reciprocal Rank Fusion combining text + vector | Embeddings enabled |

Hybrid search automatically activates when both text and vector search are available.

All search operations support optional temporal filters (validafter, validbefore, createdafter, createdbefore) to scope results by time.

—

Temporal Queries

Engram tracks when facts are valid (validat, invalidat) and when they were superseded (expired_at). You can query the graph by time:

| Operation | Node | Description |
| — | — | — |
| Get by Date Range | Explorer > Episode | Retrieve episodes within a time window by reference_time |
| Get Changelog | Explorer > Relationship | Get recently created, expired, or invalidated relationships since a given date |
| Search with date filters | Explorer > Entity/Relationship Search | Filter search results by validafter, validbefore, or created_after |

Date parameters use ISO 8601 format (e.g. 2026-01-15T00:00:00.000Z). The LLM agent can convert natural language like “last week” into concrete dates before calling these operations.

—

Community Detection

Clusters related entities using label propagation. Communities are computed on demand via Engram Admin > Detect Communities and include member entities, key entities ranked by connectivity, and optional LLM-generated summaries.

—

Graph Traversal

BFS (breadth-first search) walks the knowledge graph outward from seed entities, collecting connected entities and relationships within a configurable hop limit.

• BFS from Entity: Start from specific entity UUIDs
• BFS from Episodes: Start from entities referenced in recent episodes
• Automatic enrichment: When enabled on the Memory node, a shallow BFS (default: 1 hop) runs after each search to enrich agent context

—

Data Storage & Security

Engram stores conversation data and extracted knowledge. You should understand where this data lives before deploying to production.

Embedded backend:

• Data is stored as a JSON file at ~/.n8n/storage/n8n-nodes-engram/{workflowId}-engram.json by default
• You can override the default with Custom Storage Path when using embedded storage
• The file contains all entities, relationships, episodes, and embeddings in plain text
• Backups: copy the JSON file

Neo4j backend:

• Data is stored in your Neo4j database instance
• Engram does not manage Neo4j authentication, encryption, or access control—configure these in Neo4j directly
• Credentials (URI, username, password) are stored in n8n’s encrypted credential store

LLM API calls:

• When extraction is enabled, conversation content is sent to the configured LLM provider for entity/relationship extraction
• Embedding generation sends entity names and facts to the configured embedding model
• No data is sent to any external service unless you explicitly enable extraction and configure an API credential

General:

• Engram does not phone home, collect telemetry, or make network calls beyond the LLM API you configure
• All data stays on your infrastructure
• Group IDs isolate data between different conversations/users

—

Credentials

Engram Extraction LLM

| Field | Description |
| — | — |
| Base URL | OpenAI-compatible API base URL |
| API Key | API key for the LLM provider |

Used for entity extraction, community summaries, and embedding generation.

Engram Neo4j Connection

| Field | Description |
| — | — |
| URI | Neo4j connection URI (e.g. bolt://localhost:7687) |
| Username | Neo4j username |
| Password | Neo4j password |
| Database | Database name (default: neo4j) |

Required only with the Neo4j storage backend.

—

Development

Prerequisites

• Node.js >= 18.10
• npm

Setup

git clone https://github.com/casistack/n8n-nodes-engram.git
cd n8n-nodes-engram
npm install

Commands

| Command | Description |
| — | — |
| npm run build | TypeScript compilation + icon build |
| npm run lint | ESLint |
| npm run format | Prettier (write) |
| npm run format:check | Prettier (check) |
| npm run type-check | TypeScript type checking |
| npm test | Run all tests |
| npm run test:coverage | Coverage report |

Git Hooks (Husky)

| Hook | Checks |
| — | — |
| pre-commit | ESLint, Prettier, TypeScript type-check |
| pre-push | Build, full test suite |

CI/CD

• Pull requests: Lint, type-check, test across Node 18/20/22
• Releases: Automated npm publish on GitHub Release

—

Support

If you find Engram useful, consider supporting the project:

—

License

AGPL-3.0