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

$3

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

$3

Follow the n8n community nodes installation guide.

``bash


For global installation

npm install -g n8n-nodes-smart-memory

For local n8n installation

cd ~/.n8n
npm install n8n-nodes-smart-memory
`

Quick Start

$3

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

$3

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

$3

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 | ❌ |

$3

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 |

$3

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 |

$3

#### 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

$3

`
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
`

$3

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

$3

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

`json
{
"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

$3

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

$3

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.

$3

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:

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

With Users Map:

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

Development

$3

- Node.js 18+
- npm or bun

$3

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

$3

`bash


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
`

$3

The project uses Jest with comprehensive test coverage:

`bash


Run all tests

npm test

Run with coverage

npm test -- --coverage
`

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

$3

`
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.

API Reference

$3

`typescript
interface MemoryOutput {
chat?: {
id?: string;
type?: 'private' | 'group' | 'supergroup' | 'channel';
name?: string;
handle?: string;
};
users?: Record;
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;
}
`

$3

Session IDs must:

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

Troubleshooting

$3

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.

$3

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