n8n-nodes-postgres-context

This is an n8n community node package that provides nodes for AI context management with PostgreSQL persistence.

Overview

This package contains two nodes for managing AI context in n8n workflows:

1. Context Manager Node: Used within AI agent flows to retrieve contexts by type, with filtering and limits.
2. External Context Node: Used to save or retrieve external contexts from any type and scope.

PostgreSQL Setup

Before using these nodes, you need to set up a PostgreSQL database with the following table:

CREATE TABLE IF NOT EXISTS ai_contexts (
  id SERIAL PRIMARY KEY,
  chat_id TEXT NOT NULL,
  user_id TEXT,
  agent_id TEXT,
  session_key TEXT NOT NULL,
  context_key TEXT NOT NULL,
  context_type TEXT DEFAULT 'session',
  context_value JSONB NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE (chat_id, context_key, context_type)
);

CREATE INDEX IF NOT EXISTS idx_context_chat_type ON ai_contexts (chat_id, context_type, updated_at DESC);

The nodes will automatically create this table if it doesn't exist, but it's recommended to set it up manually for better control.

Node Usage

Context Manager Node

This node allows AI agents to retrieve contexts by type with filtering and limits.

Parameters

| Parameter | Type | Description | |-----------|------|-------------| | chatId | string | Unique identifier for the conversation | | alwaysInclude | multiOptions | Context types that should always be included | | limitsPerType | fixedCollection | List of types with maximum number of records | | connectionString | string | PostgreSQL connection string |

Example

{
  "chatId": "chat-123",
  "alwaysInclude": ["api"],
  "limitsPerType": [
    {"type": "user", "limit": 20},
    {"type": "agent", "limit": 10}
  ]
}

External Context Node

This node allows saving or retrieving external contexts of any type and scope.

Parameters

| Parameter | Type | Description | |-----------|------|-------------| | mode | options | 'save' or 'get' | | chatId | string | Unique identifier for the conversation | | contextKey | string | Name of the context key | | contextType | string | Type of the context (api, user, etc.) | | contextValue | json | (save mode) JSON object to be saved as context | | userId | string | (save mode) Optional user identifier | | agentId | string | (save mode) Optional agent identifier | | sessionKey | string | (save mode) Session identifier | | connectionString | string | PostgreSQL connection string |

Example: Saving Context

{
  "mode": "save",
  "chatId": "chat-123",
  "contextKey": "weather-forecast",
  "contextType": "api",
  "contextValue": {
    "city": "Arraial do Cabo",
    "temperature": "27°C",
    "status": "Ensolarado"
  }
}

Example: Getting Context

{
  "mode": "get",
  "chatId": "chat-123",
  "contextKey": "weather-forecast",
  "contextType": "api"
}

Context Types

The following context types are supported:

• user
• agent
• api
• memory
• short_term
• long_term
• system
• custom

Best Practices

• Use context_type as a way to group logics: user, api, memory, etc.
• Use ExternalContextNode for programmatic populations (via Webhook, Workers, etc).
• Add TTL with periodic cleaning by updated_at.
• Index by chat_id and context_type for performance.

Examples

This package includes example workflows in the examples directory that demonstrate how to use the nodes in n8n. See the examples README for more information.

License

MIT