n8n-nodes-engram 0.2.0

package/README.md

@@ -0,0 +1,334 @@
+<p align="center">
+  <img src="docs/images/logo.png" alt="Engram" width="120" />
+</p>
+
+<h1 align="center">n8n-nodes-engram</h1>
+
+<p align="center">
+  <strong>Knowledge graph memory for n8n AI agents</strong><br/>
+  Persistent memory with entity extraction, temporal fact tracking, community detection, graph traversal, and hybrid search.
+</p>
+
+<p align="center">
+  <a href="https://github.com/casistack/n8n-nodes-engram/actions/workflows/ci.yml">
+    <img src="https://github.com/casistack/n8n-nodes-engram/actions/workflows/ci.yml/badge.svg" alt="CI" />
+  </a>
+  <a href="https://www.npmjs.com/package/n8n-nodes-engram">
+    <img src="https://img.shields.io/npm/v/n8n-nodes-engram.svg" alt="npm version" />
+  </a>
+  <a href="https://github.com/casistack/n8n-nodes-engram/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/license-AGPL--3.0-blue.svg" alt="License: AGPL-3.0" />
+  </a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18.10-brightgreen.svg" alt="Node.js" />
+  <img src="https://img.shields.io/badge/n8n-community%20node-ff6d5a.svg" alt="n8n community node" />
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> &middot;
+  <a href="#node-reference">Nodes</a> &middot;
+  <a href="#storage-backends">Storage</a> &middot;
+  <a href="#knowledge-extraction">Extraction</a> &middot;
+  <a href="#search">Search</a> &middot;
+  <a href="#data-storage--security">Security</a> &middot;
+  <a href="#development">Development</a>
+</p>
+
+---
+
+> **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&mdash;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 |
+| **169** | Tests | Unit + integration across 17 test suites |
+
+---
+
+## Architecture
+
+<p align="center">
+  <img src="docs/images/architecture.svg" alt="Engram Architecture" width="780" />
+</p>
+
+---
+
+## Installation
+
+### Via n8n Community Nodes
+
+1. Go to **Settings > Community Nodes** in your n8n instance
+2. Enter `n8n-nodes-engram`
+3. Click **Install**
+
+### Manual
+
+```bash
+cd ~/.n8n
+npm install n8n-nodes-engram
+```
+
+---
+
+## 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&mdash;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 |
+| 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&ndash;1) | 0.5 |
+| Retention Policy | Episode lifecycle management | Forever |
+
+### Engram Explorer
+
+> Regular node&mdash;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, Update, Delete |
+| **Episode** | Get, Get Recent, Get Count |
+| **Traversal** | BFS from Entity, BFS from Episodes |
+
+### Engram Admin
+
+> Regular node&mdash;administration and analysis.
+
+| Category | Operations |
+| --- | --- |
+| **Monitoring** | Stats, List Groups, Group Stats |
+| **Lifecycle** | Apply Retention, Clear Group, Bulk Clear, Clear All |
+| **Hygiene** | Orphaned Entities, Duplicate Entities, Expire Stale Edges |
+| **Analysis** | Detect Communities |
+| **Portability** | Export (JSON), Import (JSON) |
+
+### Engram Trigger
+
+> Polling trigger&mdash;fires when new entities, relationships, or episodes appear in the graph.
+
+---
+
+## 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:
+
+```text
+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&mdash;OpenAI, OpenRouter, Ollama, LM Studio, Together AI, and others.
+
+**Configurable entity types**: `person`, `organization`, `location`, `concept`, `event`, or custom types.
+
+---
+
+## 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.
+
+---
+
+## 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 `engram-data/{workflowId}-engram.json` inside your n8n data directory
+- 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&mdash;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
+
+```bash
+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:
+
+<a href="https://www.buymeacoffee.com/cassistack" target="_blank">
+  <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="40" />
+</a>
+
+---
+
+## License
+
+[AGPL-3.0](LICENSE)

package/dist/community/CommunityDetector.d.ts

@@ -0,0 +1,11 @@
+import type { IGraphStorage } from '../storage/IGraphStorage';
+import type { CommunityDetectionResult } from '../schemas/Community.schema';
+export interface CommunityDetectionOptions {
+    minCommunitySize?: number;
+    maxIterations?: number;
+}
+export declare class CommunityDetector {
+    private storage;
+    constructor(storage: IGraphStorage);
+    detect(groupId: string, options?: CommunityDetectionOptions): Promise<CommunityDetectionResult>;
+}

package/dist/community/CommunityDetector.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommunityDetector = void 0;
+class CommunityDetector {
+    constructor(storage) {
+        this.storage = storage;
+    }
+    async detect(groupId, options) {
+        var _a, _b, _c, _d;
+        const minSize = (_a = options === null || options === void 0 ? void 0 : options.minCommunitySize) !== null && _a !== void 0 ? _a : 2;
+        const maxIter = (_b = options === null || options === void 0 ? void 0 : options.maxIterations) !== null && _b !== void 0 ? _b : 10;
+        const entities = await this.storage.listEntities(groupId);
+        if (entities.length === 0) {
+            return {
+                communities: [],
+                total_entities: 0,
+                unclustered_entities: 0,
+                detection_method: 'label_propagation',
+            };
+        }
+        const adjacency = new Map();
+        const edgeMap = new Map();
+        for (const entity of entities) {
+            adjacency.set(entity.uuid, new Set());
+            edgeMap.set(entity.uuid, []);
+        }
+        for (const entity of entities) {
+            const edges = await this.storage.getEdgesForEntity(entity.uuid);
+            edgeMap.set(entity.uuid, edges);
+            for (const edge of edges) {
+                if (edge.expired_at)
+                    continue;
+                const neighbor = edge.source_node_uuid === entity.uuid ? edge.target_node_uuid : edge.source_node_uuid;
+                if (adjacency.has(neighbor)) {
+                    adjacency.get(entity.uuid).add(neighbor);
+                    adjacency.get(neighbor).add(entity.uuid);
+                }
+            }
+        }
+        const labels = new Map();
+        for (const entity of entities) {
+            labels.set(entity.uuid, entity.uuid);
+        }
+        const entityUuids = entities.map((e) => e.uuid);
+        for (let iter = 0; iter < maxIter; iter++) {
+            let changed = false;
+            const sorted = [...entityUuids].sort();
+            for (const uuid of sorted) {
+                const neighbors = adjacency.get(uuid);
+                if (!neighbors || neighbors.size === 0)
+                    continue;
+                const labelCounts = new Map();
+                for (const neighbor of neighbors) {
+                    const nLabel = labels.get(neighbor);
+                    labelCounts.set(nLabel, ((_c = labelCounts.get(nLabel)) !== null && _c !== void 0 ? _c : 0) + 1);
+                }
+                let bestLabel = labels.get(uuid);
+                let bestCount = 0;
+                for (const [label, count] of labelCounts) {
+                    if (count > bestCount || (count === bestCount && label < bestLabel)) {
+                        bestLabel = label;
+                        bestCount = count;
+                    }
+                }
+                if (bestLabel !== labels.get(uuid)) {
+                    labels.set(uuid, bestLabel);
+                    changed = true;
+                }
+            }
+            if (!changed)
+                break;
+        }
+        const groups = new Map();
+        const entityMap = new Map();
+        for (const entity of entities) {
+            entityMap.set(entity.uuid, entity);
+            const label = labels.get(entity.uuid);
+            if (!groups.has(label))
+                groups.set(label, []);
+            groups.get(label).push(entity);
+        }
+        const communities = [];
+        let unclustered = 0;
+        for (const [, groupEntities] of groups) {
+            if (groupEntities.length < minSize) {
+                unclustered += groupEntities.length;
+                continue;
+            }
+            const memberUuids = new Set(groupEntities.map((e) => e.uuid));
+            const members = [];
+            const internalEdges = new Set();
+            for (const entity of groupEntities) {
+                const entityEdges = (_d = edgeMap.get(entity.uuid)) !== null && _d !== void 0 ? _d : [];
+                const communityEdges = entityEdges.filter((e) => !e.expired_at &&
+                    memberUuids.has(e.source_node_uuid) &&
+                    memberUuids.has(e.target_node_uuid));
+                for (const e of communityEdges) {
+                    internalEdges.add(e.uuid);
+                }
+                members.push({ entity, edges: communityEdges });
+            }
+            const byConnectivity = [...members].sort((a, b) => b.edges.length - a.edges.length);
+            const keyEntities = byConnectivity.slice(0, 3).map((m) => m.entity.name);
+            const sortedUuids = groupEntities.map((e) => e.uuid).sort();
+            const id = sortedUuids.join(':').slice(0, 64);
+            communities.push({
+                id,
+                label: keyEntities.join(', '),
+                members,
+                summary: null,
+                entity_count: groupEntities.length,
+                edge_count: internalEdges.size,
+                key_entities: keyEntities,
+            });
+        }
+        communities.sort((a, b) => b.entity_count - a.entity_count);
+        return {
+            communities,
+            total_entities: entities.length,
+            unclustered_entities: unclustered,
+            detection_method: 'label_propagation',
+        };
+    }
+}
+exports.CommunityDetector = CommunityDetector;
+//# sourceMappingURL=CommunityDetector.js.map

package/dist/community/CommunityDetector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommunityDetector.js","sourceRoot":"","sources":["../../src/community/CommunityDetector.ts"],"names":[],"mappings":"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"}

package/dist/community/CommunitySummarizer.d.ts

@@ -0,0 +1,8 @@
+import type { LlmClient } from '../extraction/LlmClient';
+import type { Community, CommunityDetectionResult } from '../schemas/Community.schema';
+export declare class CommunitySummarizer {
+    private llm;
+    constructor(llm: LlmClient);
+    summarize(community: Community): Promise<string>;
+    summarizeAll(result: CommunityDetectionResult, concurrency?: number): Promise<CommunityDetectionResult>;
+}

package/dist/community/CommunitySummarizer.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommunitySummarizer = void 0;
+const COMMUNITY_SUMMARY_SYSTEM = `You are analyzing a knowledge graph community (a cluster of related entities).
+Summarize the following cluster of entities and their relationships in 2-3 concise sentences.
+Focus on the key theme or connection that binds these entities together.
+Return only the summary text, no JSON or formatting.`;
+function buildCommunityPrompt(community) {
+    const entityLines = community.members.map((m) => `- ${m.entity.name} (${m.entity.entity_type}): ${m.entity.summary || 'No summary'}`);
+    const factSet = new Set();
+    for (const m of community.members) {
+        for (const e of m.edges) {
+            factSet.add(`- ${e.fact}`);
+        }
+    }
+    const parts = ['Entities:', ...entityLines];
+    if (factSet.size > 0) {
+        parts.push('', 'Relationships:', ...factSet);
+    }
+    return parts.join('\n');
+}
+class CommunitySummarizer {
+    constructor(llm) {
+        this.llm = llm;
+    }
+    async summarize(community) {
+        const response = await this.llm.chat([
+            { role: 'system', content: COMMUNITY_SUMMARY_SYSTEM },
+            { role: 'user', content: buildCommunityPrompt(community) },
+        ]);
+        return response.content.trim();
+    }
+    async summarizeAll(result, concurrency = 3) {
+        var _a, _b;
+        const communities = [...result.communities];
+        for (let i = 0; i < communities.length; i += concurrency) {
+            const batch = communities.slice(i, i + concurrency);
+            const summaries = await Promise.allSettled(batch.map((c) => this.summarize(c)));
+            for (let j = 0; j < batch.length; j++) {
+                const outcome = summaries[j];
+                if (outcome.status === 'fulfilled') {
+                    batch[j] = { ...batch[j], summary: outcome.value };
+                }
+                else {
+                    console.warn(`Engram: Failed to summarize community "${batch[j].label}":`, (_b = (_a = outcome.reason) === null || _a === void 0 ? void 0 : _a.message) !== null && _b !== void 0 ? _b : 'Unknown error');
+                }
+            }
+            for (let j = 0; j < batch.length; j++) {
+                communities[i + j] = batch[j];
+            }
+        }
+        return { ...result, communities };
+    }
+}
+exports.CommunitySummarizer = CommunitySummarizer;
+//# sourceMappingURL=CommunitySummarizer.js.map

package/dist/community/CommunitySummarizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommunitySummarizer.js","sourceRoot":"","sources":["../../src/community/CommunitySummarizer.ts"],"names":[],"mappings":"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"}

package/dist/community/index.d.ts

@@ -0,0 +1,2 @@
+export { CommunityDetector, type CommunityDetectionOptions } from './CommunityDetector';
+export { CommunitySummarizer } from './CommunitySummarizer';

package/dist/community/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommunitySummarizer = exports.CommunityDetector = void 0;
+var CommunityDetector_1 = require("./CommunityDetector");
+Object.defineProperty(exports, "CommunityDetector", { enumerable: true, get: function () { return CommunityDetector_1.CommunityDetector; } });
+var CommunitySummarizer_1 = require("./CommunitySummarizer");
+Object.defineProperty(exports, "CommunitySummarizer", { enumerable: true, get: function () { return CommunitySummarizer_1.CommunitySummarizer; } });
+//# sourceMappingURL=index.js.map

package/dist/community/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/community/index.ts"],"names":[],"mappings":";;;AAAA,yDAAwF;AAA/E,sHAAA,iBAAiB,OAAA;AAC1B,6DAA4D;AAAnD,0HAAA,mBAAmB,OAAA"}

package/dist/credentials/EngramExtractionApi.credentials.d.ts

@@ -0,0 +1,8 @@
+import type { ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class EngramExtractionApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    test: ICredentialTestRequest;
+}

package/dist/credentials/EngramExtractionApi.credentials.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EngramExtractionApi = void 0;
+class EngramExtractionApi {
+    constructor() {
+        this.name = 'engramExtractionApi';
+        this.displayName = 'Engram Extraction LLM';
+        this.documentationUrl = 'https://github.com/casistack/n8n-nodes-engram';
+        this.properties = [
+            {
+                displayName: 'API Key',
+                name: 'apiKey',
+                type: 'string',
+                typeOptions: { password: true },
+                required: true,
+                default: '',
+                description: 'API key for the LLM provider (OpenAI, OpenRouter, or any OpenAI-compatible service)',
+            },
+            {
+                displayName: 'Base URL',
+                name: 'baseUrl',
+                type: 'string',
+                default: 'https://api.openai.com/v1',
+                hint: 'OpenAI: https://api.openai.com/v1 | OpenRouter: https://openrouter.ai/api/v1 | Ollama: http://localhost:11434/v1',
+                description: 'Base URL for the OpenAI-compatible API endpoint. The model list is fetched from this URL.',
+            },
+        ];
+        this.test = {
+            request: {
+                baseURL: '={{$credentials.baseUrl}}',
+                url: '/models',
+                method: 'GET',
+                headers: {
+                    Authorization: '=Bearer {{$credentials.apiKey}}',
+                },
+            },
+        };
+    }
+}
+exports.EngramExtractionApi = EngramExtractionApi;
+//# sourceMappingURL=EngramExtractionApi.credentials.js.map

package/dist/credentials/EngramExtractionApi.credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EngramExtractionApi.credentials.js","sourceRoot":"","sources":["../../src/credentials/EngramExtractionApi.credentials.ts"],"names":[],"mappings":";;;AAEA,MAAa,mBAAmB;IAAhC;QACE,SAAI,GAAG,qBAAqB,CAAC;QAE7B,gBAAW,GAAG,uBAAuB,CAAC;QAEtC,qBAAgB,GAAG,+CAA+C,CAAC;QAEnE,eAAU,GAAsB;YAC9B;gBACE,WAAW,EAAE,SAAS;gBACtB,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;gBAC/B,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE,EAAE;gBACX,WAAW,EACT,qFAAqF;aACxF;YACD;gBACE,WAAW,EAAE,UAAU;gBACvB,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,2BAA2B;gBACpC,IAAI,EAAE,kHAAkH;gBACxH,WAAW,EACT,2FAA2F;aAC9F;SACF,CAAC;QAEF,SAAI,GAA2B;YAC7B,OAAO,EAAE;gBACP,OAAO,EAAE,2BAA2B;gBACpC,GAAG,EAAE,SAAS;gBACd,MAAM,EAAE,KAAK;gBACb,OAAO,EAAE;oBACP,aAAa,EAAE,iCAAiC;iBACjD;aACF;SACF,CAAC;IACJ,CAAC;CAAA;AAvCD,kDAuCC"}

package/dist/credentials/EngramNeo4jApi.credentials.d.ts

@@ -0,0 +1,8 @@
+import type { ICredentialTestRequest, ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class EngramNeo4jApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    test: ICredentialTestRequest;
+}