n8n-nodes-supabase-memory

Community node for n8n — A powerful AI Agent memory node that connects to Supabase for persistent, structured data storage with full control over table selection, field mapping, SQL-like filters, and data modeling.

🎯 Features

• 🗄️ Custom Table Selection — Choose any Supabase table to store your AI agent's memory
• 📝 Flexible Data Mapping — Map fields manually, auto-map from input, or provide raw JSON
• 🔍 SQL-Like Filters — Filter data using 13+ operators (eq, neq, gt, like, ilike, in, contains, full-text search, etc.)
• 📊 Data Modeling — Transform and model data before saving using templates
• 🔄 Upsert Support — Insert or update on conflict with configurable conflict columns
• 📋 Pagination — Built-in limit and offset for large datasets
• 🔧 RPC Support — Execute custom Supabase SQL functions/stored procedures
• 🤖 AI Agent Compatible — Marked as usableAsTool for seamless integration with n8n's AI Agent node

📦 Installation

Community Nodes (Recommended)

1. Go to Settings > Community Nodes in your n8n instance
2. Click Install a community node
3. Enter n8n-nodes-supabase-memory
4. Click Install

Manual Installation

cd ~/.n8n/custom
npm install n8n-nodes-supabase-memory

🔑 Credentials Setup

1. Create a new credential of type Supabase Memory API
2. Enter your Supabase URL (e.g., https://xyzcompany.supabase.co)
3. Enter your Service Role Key (found in Supabase Dashboard > Project Settings > API)

⚠️ The service role key bypasses Row Level Security (RLS). Use it only in secure environments.

🛠️ Operations

1. Save Memory

Insert or upsert data into any Supabase table.

Data Mapping Modes:

• Manual — Define each column-value pair with explicit type casting
• Auto-Map — Automatically maps incoming JSON fields to table columns
• JSON — Provide a raw JSON object

Options:

• Upsert with conflict column detection
• Data transform templates for auto-map mode
• Return the inserted data

2. Load Memory

Read data from a Supabase table with optional filters.

• Select specific columns or use * for all
• Apply multiple SQL-like filters (AND logic)
• Order by any column(s)
• Limit and offset for pagination

3. Update Memory

Update existing records with filters.

• Same data mapping modes as Save
• Filters to target specific records
• Return updated data

4. Delete Memory

Delete records with mandatory filters (prevents accidental full table deletion).

• At least one filter is required
• Returns deleted records optionally

5. Search Memory

Advanced search with result count.

• All filter operators available
• Returns _totalCount with each record
• Full pagination support

6. Run SQL (RPC)

Execute Supabase remote procedure calls (stored functions).

• Call any SQL function by name
• Pass parameters as JSON
• Great for complex queries, vector search, or custom logic

🔍 Available Filter Operators

| Operator | Description | Example Value | |----------|------------|---------------| | eq | Equals | abc-123 | | neq | Not equals | old-session | | gt | Greater than | 100 | | gte | Greater or equal | 2024-01-01 | | lt | Less than | 50 | | lte | Less or equal | 2024-12-31 | | like | Pattern match | %search% | | ilike | Case-insensitive match | %Search% | | is | IS (null/true/false) | null | | in | List of values | val1, val2, val3 | | contains | JSON/Array contains | {"key": "value"} | | containedBy | Contained by JSON/Array | ["a", "b"] | | textSearch | Full-text search | search term |

🗃️ Supabase Setup

Recommended Table Schema for AI Memory

CREATE TABLE agent_memory (
    id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
    session_id TEXT NOT NULL,
    agent_id TEXT,
    memory_type TEXT DEFAULT 'conversation',
    content JSONB NOT NULL,
    metadata JSONB DEFAULT '{}',
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW(),
    expires_at TIMESTAMPTZ
);

-- Index for fast lookups
CREATE INDEX idx_agent_memory_session ON agent_memory(session_id);
CREATE INDEX idx_agent_memory_agent ON agent_memory(agent_id);
CREATE INDEX idx_agent_memory_type ON agent_memory(memory_type);
CREATE INDEX idx_agent_memory_created ON agent_memory(created_at DESC);

-- Optional: GIN index for JSONB search
CREATE INDEX idx_agent_memory_content ON agent_memory USING GIN (content);
CREATE INDEX idx_agent_memory_metadata ON agent_memory USING GIN (metadata);

Optional: Table Listing Function

To enable the auto-load table dropdown in n8n, create this RPC function in Supabase:

CREATE OR REPLACE FUNCTION get_tables_list()
RETURNS TABLE(table_name TEXT) AS $$
BEGIN
    RETURN QUERY
    SELECT t.table_name::TEXT
    FROM information_schema.tables t
    WHERE t.table_schema = 'public'
      AND t.table_type = 'BASE TABLE'
    ORDER BY t.table_name;
END;
$$ LANGUAGE plpgsql SECURITY DEFINER;

💡 Usage Examples

Example 1: Save conversation memory

Operation: Save Memory
Table: agent_memory
Data Mapping: Manual
Mappings:
  - session_id → {{$json.sessionId}}
  - content → {{$json.message}}  (type: JSON)
  - memory_type → "conversation"
  - agent_id → "agent-vittal-01"

Example 2: Load recent memories for a session

Operation: Load Memory
Table: agent_memory
Columns: content, created_at, memory_type
Filters:
  - session_id eq {{$json.sessionId}}
  - memory_type eq "conversation"
Order By: created_at DESC
Limit: 10

Example 3: Search across all sessions

Operation: Search Memory
Table: agent_memory
Filters:
  - content ilike "%payment%"
  - created_at gte "2024-01-01"
Order By: created_at DESC
Limit: 50

Example 4: Use as AI Agent Tool

1. Add a Supabase Memory node to your workflow
2. Connect it to the AI Agent node's tool input
3. The agent can now save/load/search memories dynamically!

🏗️ Development

# Clone the repository
git clone https://github.com/vittal/n8n-nodes-supabase-memory.git
cd n8n-nodes-supabase-memory

# Install dependencies
npm install

# Build
npm run build

# Development mode (auto-rebuild + starts n8n)
npm run dev

# Lint
npm run lint

📄 License

MIT