n8n-nodes-smart-memory

A powerful n8n community node that provides flexible memory management for AI chatbots within n8n workflows. Store, retrieve, and manage conversational history across multiple storage backends with fine-grained control over data structure and output formatting.

Features

• 🔄 Multiple Storage Backends: Choose from In-Memory, Redis, PostgreSQL, or SQLite based on your needs
• 💬 Flexible Operations: Insert messages, retrieve memory with configurable windowing, or clear sessions
• 👥 Group Chat Support: Track multiple users with optional users map for token-efficient outputs
• ↩️ Reply Context: Preserve message threading with configurable reply context inclusion
• 🔧 Output Customization: Granular control over which fields appear in your output
• ⚡ Performance Optimized: Buffered writes, atomic operations, and connection pooling
• 🔒 Secure: Input validation via Zod schemas, parameterized queries, and error message sanitization

Table of Contents

• Installation
• Quick Start
• Operations
• Storage Backends
• Configuration
• Advanced Features
• Development
• Architecture
• API Reference
• Troubleshooting
• Contributing
• License

Installation

Via n8n Community Nodes (Recommended)

1. Open your n8n instance
2. Go to Settings → Community Nodes
3. Search for n8n-nodes-smart-memory
4. Click Install

Manual Installation

Follow the n8n community nodes installation guide.

# For global installation
npm install -g n8n-nodes-smart-memory

# For local n8n installation
cd ~/.n8n
npm install n8n-nodes-smart-memory

Quick Start

Basic Message Storage

1. Add a Smart Memory node to your workflow
2. Configure the Session ID (e.g., {{ $json.chat_id }} for Telegram)
3. Set the Operation to "Insert Message"
4. Map your message content (e.g., {{ $json.message.text }})
5. Configure Identity Settings for user tracking

Retrieving Memory for AI

1. Add another Smart Memory node
2. Set Operation to "Get Memory"
3. Use the same Session ID
4. Connect to your AI node - the output provides formatted conversation history

Operations

Insert Message

Adds a new message to the conversation memory with optional metadata.

| Parameter | Description | Required | |-----------|-------------|----------| | Session ID | Unique identifier for the conversation | ✅ | | Message Content | The text content to store | ✅ | | Insert Mode | append (default) or replace memory | ✅ | | Identity Settings | User info (ID, name, handle, role) | ❌ | | Chat Info Settings | Chat metadata (ID, type, name) | ❌ | | Message Settings | Message ID, reply context | ❌ |

Get Memory

Retrieves conversation history with configurable output.

| Parameter | Description | Default | |-----------|-------------|---------| | Session ID | Conversation to retrieve | Required | | Memory Window Size | Number of recent messages | 25 | | Get Memory Mode | full or fields (selective) | full | | Max Context Messages | Older messages to inject for replies | 10 |

Clear Memory

Removes conversation history.

| Parameter | Description | Required | |-----------|-------------|----------| | Session ID | Specific session to clear, or empty for all | ❌ |

Storage Backends

| Backend | Persistence | Speed | Use Case | |---------|-------------|-------|----------| | In-Memory | ❌ Lost on restart | ⚡⚡⚡ Fastest | Development, testing | | Redis | ✅ Distributed | ⚡⚡⚡ Fast | Production, multi-instance | | PostgreSQL | ✅ Relational | ⚡⚡ Good | Complex queries, analytics | | SQLite | ✅ File-based | ⚡⚡ Good | Single instance, simple setup |

Credentials Setup

Redis

• Host: Redis server hostname
• Port: Default 6379
• User/Password: Optional authentication
• Database: Redis database number (0-15)
• SSL: Enable TLS encryption

PostgreSQL

• Host: PostgreSQL server hostname
• Port: Default 5432
• Database: Database name
• User/Password: Authentication credentials
• SSL: Connection security options

SQLite

No credentials required - configure the database file path in Storage Settings.

Configuration

Memory Settings

Memory Window Size: 25        # Messages in output (5-70)
Max Storage Messages: 200     # Messages kept in storage
Max Context Messages: 10      # Injected context for replies

Output Control

Enable/disable specific fields in the output:

• Chat Info: ID, Type, Name
• Identity Info: ID, Name, Handle, Role
• Reply Context: Name, Handle, Content, Message ID
• Other: Timestamp, Token Estimate, Users Map

Reply Context

When a message is a reply, Smart Memory can include context about the original message:

{
  "content": "Great idea!",
  "reply": {
    "name": "Alice",
    "content": "Let's schedule a meeting",
    "msgId": "123"
  }
}

Special handling for bot replies ensures full context is preserved regardless of output settings.

Advanced Features

Buffered Writes

For performance optimization in workflows with multiple inserts:

1. Set Write to Storage: false for intermediate inserts
2. Set Write to Storage: true for the final insert
3. All buffered messages are written in a single batch

Context Injection

When a message replies to an older message outside the memory window, Smart Memory automatically injects that older message as context, up to the Max Context Messages limit.

Users Map

For group chats with many participants, enable Use Users Map to:

• Store user details once in a separate users object
• Reference users by ID in messages
• Reduce token count for AI context

Without Users Map:

{
  "messages": [
    { "content": "Hello", "sender": { "id": "1", "name": "Alice", "handle": "@alice" } },
    { "content": "Hi!", "sender": { "id": "2", "name": "Bob", "handle": "@bob" } }
  ]
}

With Users Map:

{
  "users": {
    "1": { "name": "Alice", "handle": "@alice" },
    "2": { "name": "Bob", "handle": "@bob" }
  },
  "messages": [
    { "content": "Hello", "sender": { "id": "1" } },
    { "content": "Hi!", "sender": { "id": "2" } }
  ]
}

Development

Prerequisites

• Node.js 18+
• npm or bun

Setup

git clone https://github.com/etircopyh/n8n-nodes-smart-memory.git
cd n8n-nodes-smart-memory
npm install

Development Commands

# Build the project
npm run build

# Watch mode for development
npm run build:watch

# Run linter
npm run lint
npm run lint:fix

# Run tests
npm test

# Start n8n with this node (development)
npm run dev

Testing

The project uses Jest with comprehensive test coverage:

# Run all tests
npm test

# Run with coverage
npm test -- --coverage

Note: Use bun run test instead of bun test to ensure proper mocking.

Project Structure

n8n-nodes-smart-memory/
├── credentials/              # n8n credential definitions
│   ├── PostgresApi.credentials.ts
│   └── RedisApi.credentials.ts
├── nodes/SmartMemory/
│   ├── SmartMemory.node.ts   # Main n8n node definition
│   ├── SmartMemory.ts        # Core memory manager (PureMemoryManager)
│   ├── constants.ts          # Shared constants and defaults
│   ├── handlers/             # Operation handlers
│   │   ├── InsertHandler.ts
│   │   ├── GetHandler.ts
│   │   └── ClearHandler.ts
│   ├── interfaces/           # TypeScript interfaces
│   │   └── MemoryInterfaces.ts
│   ├── storage/              # Storage backend implementations
│   │   ├── BaseStorage.ts    # Abstract base class
│   │   ├── BufferedStorage.ts
│   │   ├── InMemoryStorage.ts
│   │   ├── RedisStorage.ts
│   │   ├── PostgresStorage.ts
│   │   └── SqliteStorage.ts
│   ├── utils/                # Utility classes
│   │   ├── OutputCleaner.ts
│   │   ├── NodeParameterHelper.ts
│   │   ├── StorageFactory.ts
│   │   └── ...
│   └── __tests__/            # Test files
├── package.json
└── tsconfig.json

Architecture

For detailed architectural documentation including:

• Architecture Decision Records (ADRs)
• Storage backend comparison
• Performance benchmarks
• Security considerations

See ARCHITECTURE.md.

For developer documentation including:

• Technical debt analysis
• Improvement opportunities
• LangChain integration feasibility

See GEMINI.md.

API Reference

Output Structure

interface MemoryOutput {
  chat?: {
    id?: string;
    type?: 'private' | 'group' | 'supergroup' | 'channel';
    name?: string;
    handle?: string;
  };
  users?: Record<string, { name?: string; handle?: string; role?: string }>;
  messages: Array<{
    content: string;
    msgId?: string;
    time?: string;
    sender?: { id?: string; name?: string; handle?: string; role?: string };
    reply?: { name?: string; handle?: string; content?: string; msgId?: string };
  }>;
  count?: number;
  tokenEstimate?: number;
}

Session ID Format

Session IDs must:

• Be 1-255 characters
• Start with alphanumeric character or hyphen
• Contain only: a-z, A-Z, 0-9, ., _, -

Troubleshooting

Common Issues

Q: Memory is empty after restart A: You're using In-Memory storage. Switch to Redis, PostgreSQL, or SQLite for persistence.

Q: Connection timeout with Redis A: Check firewall rules, Redis bind address, and credentials. Enable SSL if required.

Q: Invalid Session ID error A: Ensure your session ID matches the allowed pattern. Avoid special characters.

Q: Messages missing from output A: Check Memory Window Size setting. Increase it or use Max Storage Messages to keep more history.

Debug Mode

Set Log Level to debug in the node configuration for detailed logging.

Compatibility

| n8n Version | Smart Memory | |-------------|--------------| | 1.0.0+ | 1.x |

Tested with n8n versions 1.x.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

See CONTRIBUTING.md for details.

License

MIT License - see LICENSE for details.

Resources

• n8n Community Nodes Documentation
• GitHub Repository
• NPM Package
• Issues & Feature Requests