n8n-nodes-keyvalue

A filesystem-based key-value store and trigger node for n8n. Store, retrieve, list, and delete key-value pairs using plain directories and text files. Includes full-text search, vault navigation, tag management, and YAML frontmatter metadata. Also includes a trigger node that watches directories for new or changed records.

~/.n8n-keyvalue/          ← your store root
├── customers/            ← a directory
│   ├── alice             ← a record (text file)
│   └── bob
└── orders/
    ├── order_001
    └── order_002

Installation

Install from the n8n community nodes panel, or:

npm install n8n-nodes-keyvalue

No external dependencies — uses only Node.js built-in modules (fs, path, os).

Note: This node operates on the local filesystem and cannot run on n8n Cloud.

Quick Start

1. Add a KeyValue node to your workflow.
2. Select Directory → Create, enter my_dir.
3. Add another KeyValue node, select Record → Write, enter directory my_dir, key greeting, value Hello n8n!.
4. Add a third node, Record → Read, same directory and key — outputs Hello n8n!.

Operations Reference

Counter Resource

| Operation | Fields | Description | Output | |-----------|--------|-------------|--------| | Get | Counter Name (required) | Reads the current counter value | { "counter": "name", "value": 42 } | | Increment | Counter Name, Increment By, Start At | Increments a counter and returns the new value. Creates it at startAt on first call | { "counter": "name", "value": 43 } | | Reset | Counter Name, Reset To | Resets a counter to a target value | { "counter": "name", "value": 0 } |

• Increment By (default 1) — amount to add each call.
• Start At (default 0) — value to create the counter at if it doesn't exist yet. Ignored once the counter exists.
• Reset To (default 0) — value to set the counter to on reset.
• Counters are stored as plain text files under counters/ in the base directory.
• Get and Reset on a non-existent counter throw an error.

Directory Resource

| Operation | Field | Description | Output | |-----------|-------|-------------|--------| | Create | Directory Name (required) | Creates a new directory | { "directory": "name", "created": true } | | Delete | Directory Name (required) | Deletes a directory and all its records | { "directory": "name", "deleted": true } | | List | — | Lists all directories | [{ "directory": "name1" }, { "directory": "name2" }] |

Record Resource

| Operation | Fields | Description | Output | |-----------|--------|-------------|--------| | Append | Directory Name, Key, Value, Separator | Appends value to a record (creates if missing) | { "directory": "name", "key": "k", "value": "...", "appended": true } | | Count | Directory Name, Key Filter, Tag Filter | Counts records with optional glob and tag filters | { "directory": "name", "count": 5 } | | Delete | Directory Name, Key Filter, Value Filter, Tag Filter | Deletes records matching filters. At least one filter required. Use "*" for all records | [{ "directory": "name", "key": "k", "deleted": true }] | | Exists | Directory Name, Key | Checks if a record exists without throwing an error | { "directory": "name", "key": "k", "exists": true } | | List | Directory Name, Key Filter, Value Filter, Tag Filter, Include Frontmatter | Lists records with optional glob, content, and tag filters | [{ "directory": "name", "key": "k", "value": "..." }] | | Read | Directory Name, Key, Mode | Reads a record. Mode: Full (default) / Frontmatter Only / Body Only. JSON auto-parsed | { "directory": "name", "key": "k", "value": "...", "frontmatter": {...}, "body": "..." } | | Touch | Directory Name, Key | Updates mtime. Creates empty record if key does not exist | { "directory": "name", "key": "k", "touched": true, "created": false } | | Write | Directory Name, Key, Value, Frontmatter (collection) | Creates/overwrites. Optional YAML frontmatter metadata | { "directory": "name", "key": "k", "value": "...", "written": true } |

List Filters

• Directory Filter (Directory → List) — glob pattern on directory names. * matches any characters, ? matches one. Example: prod_* matches prod_eu, prod_us.
• Key Filter (Record → List, Count, Delete) — glob pattern on filename. * matches any characters, ? matches one. Example: user_* matches user_alice, user_bob.
• Value Filter (Record → List, Delete) — substring match inside file content. Example: active returns only records containing "active".
• Tag Filter (Record → List, Count, Delete) — exact match on a frontmatter tag. Only matches records whose tags array contains this value. Reads file content when enabled.
• All filters combined use AND logic. Empty = match all.

Frontmatter (YAML Metadata)

Records can optionally include YAML frontmatter — structured metadata stored as --- delimited blocks at the top of the file:

---
tags: [n8n, error-handling, critical]
description: Error format rules for n8n nodes
updated: "2026-06-29T14:30:00Z"
---
Error must be at top level of INodeExecutionData.

Write with frontmatter: expand the Frontmatter collection on Record → Write. Fields: Tags (comma-separated), Description, Updated (ISO timestamp — auto-filled if empty).

Read modes: Record → Read offers three modes via the Mode dropdown:

• Full (default) — returns value, frontmatter, and body
• Frontmatter Only — returns only frontmatter metadata (no content I/O for body)
• Body Only — returns only value (backward compatible)

List with frontmatter: enable Include Frontmatter to return frontmatter per item. Use values via {{ $json.frontmatter.tags }}.

The value field is always the clean content (body), never polluted by YAML metadata. Files without frontmatter return frontmatter: null — fully backward compatible.

Append Separator

The Separator field on Record → Append defaults to a newline. You can type \\n for a newline, use , for CSV-style, or leave empty for direct concatenation.

KeyValue Trigger Node

The KeyValue Trigger node watches a directory for new or changed records and triggers your workflow when changes are detected. Place it at the start of a workflow — it requires no upstream input.

Trigger Operations

| Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | Directory Name | string | ✅ | '' | Directory to watch for changes | | Poll Time | number | ❌ | 30 | Interval in seconds between each scan. Minimum: 5 seconds | | Watch Events | multiOptions | ✅ | ['add', 'change'] | File Created — new record files ; File Changed — modified record files | | Key Filter | string | ❌ | '' | Glob pattern to filter records by filename. Leave empty to match all | | Include Content | boolean | ❌ | true | Read and return the content of detected records. Disable for faster scanning |

Trigger Output

Each detected file produces one item:

{
  "directory": "incoming",
  "key": "order_001.json",
  "event": "add",
  "value": { "id": 1, "total": 99.99 },
  "mtimeMs": 1719403200000
}

When no changes are detected, the scan is silent (no execution).

Trigger Quick Start

1. Add a KeyValue Trigger node to a new workflow.
2. Set Directory Name to my_queue, Poll Time to 15.
3. Execute the workflow — it activates and waits.
4. In a separate workflow, use KeyValue (Record → Write) to create a file in my_queue/.
5. Within 15 seconds, the trigger workflow fires with event: "add".

Trigger Examples

KeyValue Trigger (directory: "orders", Poll Time: 10, events: add + change)
  → IF ({{ $json.event }} = "add")
    → HTTP Request (POST to fulfillment API)

KeyValue Trigger (directory: "logs", Key Filter: "error_*", Include Content: true)
  → Email (send alert with file content)

Polling Limitation

The trigger uses time-based polling (setInterval). It compares file modification timestamps (mtime) between scans, not individual write operations:

• Rapid updates (multiple writes to the same file between two scans) are collapsed into a single change event.
• Example: 10 writes in 3 seconds with Poll Time: 15 → at most 1-2 events captured.
• Solution: reduce Poll Time (minimum 5s) for high-frequency use cases.
• No event history: the trigger only sees "the file changed since last scan", not "how many times".

State File

The trigger stores its state in .keyvalue-watch-state.json inside the watched directory:

{ "filename": 1719403200000, ... }

It tracks mtimeMs for each file. This file is overwritten on every scan and visible in Record → List. Deleting it resets the trigger to a clean baseline (no existing files will fire events on restart).

Examples

Counter: basic counting

KeyValue (Counter → Increment, name: "page_visits")
  → first call returns { "counter": "page_visits", "value": 1 }
  → second call returns { "counter": "page_visits", "value": 2 }

KeyValue (Counter → Reset, name: "page_visits")
  → returns { "counter": "page_visits", "value": 0 }

Counter: starting at a custom value

KeyValue (Counter → Increment, name: "invoice", Start At: 1000)
  → first call returns { "counter": "invoice", "value": 1001 }
  → second call returns { "counter": "invoice", "value": 1002 }

Create a directory and write a record

KeyValue (Directory → Create, name: "config")
  → KeyValue (Record → Write, directory: "config", key: "api_url", value: "https://api.example.com")

List all directories, then delete one

KeyValue (Directory → List)
  → KeyValue (Directory → Delete, name: "old_dir")

Filter records by pattern

KeyValue (Record → List, directory: "users", Key Filter: "admin_*")
  → returns only keys starting with "admin_"

Count records in a directory

KeyValue (Record → Count, directory: "users", Key Filter: "admin_*")
  → returns { "directory": "users", "count": 3 }

Delete records by filter

# Delete a single record by exact key
KeyValue (Record → Delete, directory: "cache", Key Filter: "old_report")

# Delete all records matching a pattern
KeyValue (Record → Delete, directory: "cache", Key Filter: "temp_*")

# Delete all records (explicit — must type "*")
KeyValue (Record → Delete, directory: "cache", Key Filter: "*")

# Delete records containing "expired" in content
KeyValue (Record → Delete, directory: "cache", Value Filter: "expired")

At least one filter is required. Leaving both empty throws an error — this is a safety guard.

Conditional branching with Exists

KeyValue (Record → Exists, directory: "cache", key: "latest_report")
  → returns { "directory": "cache", "key": "latest_report", "exists": true }
  → use {{ $json.exists }} in an IF node to branch

Heartbeat / liveness check with Touch

Cron (every 5 min) → KeyValue (Record → Touch, directory: "health", key: "worker_alive")
  → returns { "directory": "health", "key": "worker_alive", "touched": true }

Monitor workflow → KeyValue (Record → Stat / Read, directory: "health", key: "worker_alive")
  → check mtime or use a KeyValue Trigger on "health/" with Event: File Changed
  → if no touch in 10 minutes → alert

Touch creates the record on first call (created: true), then only updates timestamps on subsequent calls (touched: true). The KeyValue Trigger treats Touch as a change event.

JSON auto-detection

When you write a record whose value is a valid JSON object or array ({...} / [...]), it is stored as structured JSON and automatically parsed back on Read and List:

KeyValue (Record → Write, directory: "contacts", key: "jean",
  value: {"prenom": "Jean", "nom": "Dupont", "telephone": "+33 6 12 34 56 78"})
  → stored as formatted JSON on disk

KeyValue (Record → Read, directory: "contacts", key: "jean")
  → returns { "prenom": "Jean", "nom": "Dupont", ... }
  → use {{ $json.value.prenom }} in downstream nodes

KeyValue (Record → Write, directory: "contacts", key: "jean_copy",
  value: {{ $json.value }})
  → the parsed array/object is passed directly and stored as JSON

Plain text, numbers, and booleans are stored as-is (strings). Only {...} and [...] trigger JSON mode. The Append operation always treats values as plain text.

Search Resource

| Operation | Fields | Description | Output | |-----------|--------|-------------|--------| | Query | Query (required), Directory Filter, Tag Filter, Limit, Include Snippets | Full-text search across all files (key + body). AND logic, case-insensitive, scored | [{ "directory": "d", "key": "k", "score": 4, "tags": [...], "snippet": "..." }] |

• Query — list of words, separated by spaces. All words must match (AND logic).
• Scoring — number of occurrences summed across all terms. Sorted by score descending.
• Search scope — both the filename (key) and content (body) are searched.
• Snippets — ±60 characters of context around the first match. Shows key: <filename> when the match is in the key. Disable with Include Snippets: false for faster queries.

Vault Resource

| Operation | Fields | Description | Output | |-----------|--------|-------------|--------| | Backlinks | Target Path (required), Directory Filter | Finds files that reference a target file (exact path, wiki link [[...]], or bare filename) | [{ "source_directory": "...", "source_key": "...", "matched_pattern": "[[...]]", "line": N, "context": "..." }] | | Recent | Limit, Directory Filter, Tag Filter | Lists recently modified files sorted by mtime | [{ "directory": "d", "key": "k", "updated": "ISO", "size": N }] | | Stats | — | Aggregate vault statistics | { "files": N, "directories": N, "total_size_kb": N, "unique_tags": N, "last_modified": "...", "last_modified_at": "ISO" } | | Tree | Path, Max Depth | Displays the vault directory structure as an ASCII tree | { "tree": "db1/\n├── file1\n└── file2", "directories": [...], "files": [...] } |

Tag Resource

| Operation | Fields | Description | Output | |-----------|--------|-------------|--------| | List | Directory Filter | Lists all unique tags across the vault with file counts | [{ "tag": "n8n", "count": 12, "files": ["dir1/file1", ...] }] |

Data Model

| n8n concept | Filesystem | |-------------|------------| | Counter | Plain text file under counters/ containing a number | | Directory | Subdirectory under ~/.n8n-keyvalue/ | | Record (key-value pair) | File whose name is the key, contents are the value | | Delete (filter-based) | Scans directory, applies Key Filter (glob), Value Filter (substring), and/or Tag Filter (exact tag). At least one filter required | | Value | Plain UTF-8 text stored in the file. JSON objects/arrays ({...} / [...]) are auto-detected on Write and auto-parsed on Read | | Count | Lightweight tally of records — reads file contents only when Tag Filter is enabled | | Exists | fs.existsSync check — no file contents read, never throws | | Touch | Updates record mtime only — no content I/O on existing records. Creates an empty record if the key does not exist | | Frontmatter | YAML metadata block at the top of the file (--- delimited). Contains tags, description, updated. Stripped from value on read. | | Search | Full-text scan of all files (key + body). Tokenized AND search with occurrence scoring and optional snippet extraction | | Vault | Cross-directory navigation: Tree (ASCII), Stats (aggregates), Recent (by mtime), Backlinks (cross-references) | | Tag | Index of all unique frontmatter tags with per-file counts | | Trigger | Polling-based watcher on a directory. Detects add/change via mtime comparison between scans |

KeyValue Use Cases

When building robust automation in n8n, certain heavy lifting, like initializing an environment or creating a specific SQL table, should only happen exactly once. By pairing the n8n-nodes-keyvalue community node with the built-in $workflow.id variable, you can seamlessly track initialization states across executions without complex error-handling.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | N8N_KEYVALUE_DIR | ~/.n8n-keyvalue | Override the base directory. Useful for Docker / persistent volume mounts. |

Setting up a persistent directory (Docker)

If your n8n container has a persistent volume at /home/node/.n8n, set up KeyValue inside it:

# Inside the container (or add to your Dockerfile/entrypoint)
mkdir -p /home/node/.n8n/keyvalue

Then set the environment variable on your n8n container:

N8N_KEYVALUE_DIR=/home/node/.n8n/keyvalue

All directories and records will now be stored under /home/node/.n8n/keyvalue/ and survive container restarts.

Security note: If your n8n instance has N8N_RESTRICT_FILE_ACCESS_TO set, include the KeyValue directory in its semicolon-separated list:

N8N_KEYVALUE_DIR=/home/node/.n8n/keyvalue
N8N_RESTRICT_FILE_ACCESS_TO=/home/node/.n8n

Limitations

• No input validation: Directory names and record keys are passed directly to the filesystem. Invalid characters (/, <, >, :, ", \, |, ?, *) will cause OS-level errors. Stick to alphanumeric names, hyphens, and underscores for now.

Development

git clone https://github.com/stephaneheckel/n8n-nodes-keyvalue.git
cd n8n-nodes-keyvalue
npm install --legacy-peer-deps
npm run build
npm run dev        # starts n8n with hot-reload at localhost:5678

Hermes Agent External Memory

This node powers an external memory system for Hermes Agent. The KeyValue store at ~/.n8n-keyvalue/ holds structured markdown files with YAML frontmatter in a single reserved directory:

| Directory | Purpose | |-----------|---------| | memory/ | Hermes external memory — conventions, pitfalls, projects, user context |

Taxonomy is encoded in YAML tags, not subdirectories. A single search finds everything: search_files("n8n", path="~/.n8n-keyvalue/memory/").

Hermes accesses these files via read_file/search_files, and n8n workflows can navigate them via Search, Record, Vault, and Tag resources. Full documentation: EXTERNAL-MEMORY-SYSTEM.md

License

MIT