Memscend Memory Node for n8n

Production-ready n8n memory node that integrates the Memscend multi-tenant memory service with AI Agent workflows. Unlike simple chat history buffers, this node uses semantic search to retrieve the most relevant memories for each conversation turn.

Key Features

• True Semantic Search: Automatically searches for relevant context using vector similarity, not just recent messages
• Multi-Tenant Architecture: Strict isolation via org/agent/session scoping
• Efficient Batch Operations: Parallel API calls minimize latency
• Flexible Memory Scopes: Organize memories as facts, preferences, persona traits, or constraints
• Smart Defaults: Works out-of-the-box with sensible configuration
• Production Ready: Comprehensive error handling, idempotency support, and TTL management

How It Works

Revolutionary Architecture

Previous implementations treated memory as a simple chat log - loading once and returning stale messages. This node implements a query-based retrieval system:

1. On Each Turn: Performs a fresh semantic search using the user's current input
2. Relevant Context: Returns the most similar memories based on vector embeddings, not just chronological order
3. Time-Aware Ranking: Balances relevance with recency using configurable time decay
4. Efficient Storage: Saves both user input and AI output in parallel batches

This architecture unlocks Memscend's full potential - your AI agent remembers what matters, when it matters.

Installation

From npm (Recommended)

npm install @yoda.digital/n8n-nodes-memscend-memory

From Source

cd packages/n8n-nodes-memscend-memory
npm install
npm run build
npm link  # For local development

In your n8n instance, ensure community packages are enabled:

export N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true

Quick Start

1. Create Memscend API Credential

In n8n, add a new Memscend API credential:

• Base URL: https://mem.yoda.digital (or your self-hosted instance)
• Shared Secret: Your Memscend authentication token (demo: dev-secret-token)
• Organisation ID: Your tenant identifier (demo: demo-org)
• Agent ID: Identifies this agent/workflow (e.g., support-bot)
• Default User ID: Optional fallback user identifier

2. Add Memory Node to AI Agent

1. Create an AI Agent node in your workflow
2. Add a Memscend Memory node
3. Connect it to the Agent's memory input
4. Configure the Session ID (defaults to {{ $json.sessionId }})

3. Configure Memory Behavior

Basic Settings:

• Session ID: Unique conversation identifier (isolates memory per chat)
• User ID: Attribute memories to specific users (for multi-user agents)
• Scope: facts (default), prefs, persona, or constraints
• Tags: Additional categorization (comma-separated)

Search Settings:

• Search Mode: semantic (relevance-based) or recent (chronological)
• Top K Results: Number of memories to retrieve (default: 5)

Advanced Options:

• TTL (Days): Auto-expire memories after N days (0 = permanent)
• Time Decay Weight: Balance relevance vs. recency (0.0-1.0)
• Idempotency Key: Prevent duplicate saves (use {{ $execution.id }})

Configuration Examples

Customer Support Bot

Session ID: {{ $json.ticketId }}
User ID: {{ $json.customerId }}
Scope: facts
Tags: support,ticket
Search Mode: semantic
Top K: 8
TTL: 90 days  # Auto-cleanup after case closure

Retrieves relevant past interactions and support history for each customer.

Personal Assistant

Session ID: {{ $json.userId }}
User ID: {{ $json.userId }}
Scope: prefs
Tags: assistant,personal
Search Mode: semantic
Top K: 5
Time Decay: 0.3  # Favor relevance over recency

Remembers user preferences and habits across all conversations.

Code Review Bot

Session ID: {{ $json.prId }}
User ID: {{ $json.author }}
Scope: constraints
Tags: code-review,{{ $json.repo }}
Search Mode: semantic
Top K: 10
TTL: 30 days

Recalls project-specific coding standards and past review comments.

API Compatibility

Works with Memscend API v1. Required endpoints:

• POST /api/v1/mem/add - Store memories
• GET /api/v1/mem/search - Semantic search
• GET /api/v1/mem/list - List recent memories
• POST /api/v1/mem/delete/batch - Clear session

Architecture Overview

┌─────────────────────┐
│   AI Agent Node     │
│  (n8n workflow)     │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Memscend Memory    │
│  (this package)     │
├─────────────────────┤
│ • loadMemoryVars()  │ ◄─── Semantic search on user input
│ • saveContext()     │ ◄─── Batch save user + AI messages
│ • clear()           │ ◄─── Delete session memories
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│ MemscendApiClient   │
│  (HTTP layer)       │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│  Memscend Service   │
│ (TEI + Qdrant + LLM)│
└─────────────────────┘

Key Implementation Details

Semantic Search on Every Turn

Unlike traditional chat memory that loads once and caches, this implementation:

// In loadMemoryVariables()
const input = values?.['input'];  // Current user message

// Perform fresh search using input as query
const memories = await apiClient.search({
  q: input,
  k: this.topK,
  tags: [sessionTag, ...customTags],
  time_decay: 0.5
});

// Return most relevant memories, not just recent ones
return { chat_history: memories };

This means your agent always has the right context, even in long-running conversations.

Efficient Batch Saves

When the agent completes a turn:

// In saveContext()
const payloads = [
  createPayload(userInput, 'human'),
  createPayload(aiOutput, 'ai')
];

// Save both in parallel
await apiClient.addBatch(payloads);

Reduces API calls by 50% compared to sequential saves.

Graceful Degradation

Memory failures don't break workflows:

try {
  const memories = await loadMemories();
  return memories;
} catch (error) {
  console.error('Memory error:', error);
  return [];  // Continue with empty context
}

Your agents remain operational even if Memscend is temporarily unavailable.

Troubleshooting

"Session ID is required" Error

Ensure your workflow data includes a session identifier. Add a Set node before the agent:

{
  "sessionId": "{{ $workflow.id }}-{{ $execution.id }}"
}

Empty Memories Returned

Check:

1. Memories were actually saved (inspect Memscend via API or logs)
2. Session ID is consistent across turns
3. Tags and scope match between save and load operations

Slow Performance

• Reduce topK (fewer memories = faster retrieval)
• Use recent mode instead of semantic for simple chronological history
• Check network latency to Memscend instance

Build Errors

# Clean rebuild
cd packages/n8n-nodes-memscend-memory
rm -rf dist node_modules
npm install
npm run build

Development

Project Structure

src/
├── api/
│   └── MemscendApiClient.ts    # HTTP client for Memscend API
├── credentials/
│   └── MemscendApi.credentials.ts  # n8n credential definition
└── memory/
    └── MemscendMemory.memory.ts    # Memory node implementation

Build Commands

npm run build      # Compile TypeScript
npm run dev        # Watch mode for development
npm run lint       # ESLint check
npm run lintfix    # Auto-fix lint issues

Testing Locally

1. Build the package: npm run build
2. Link to n8n: npm link (in package dir), then npm link @yoda.digital/n8n-nodes-memscend-memory (in n8n dir)
3. Restart n8n
4. Node appears in n8n's node palette under "AI"

Comparison with Other Memory Solutions

| Feature | Memscend Memory | Redis Memory | Postgres Memory | Window Buffer | |---------|----------------|--------------|-----------------|---------------| | Semantic Search | ✅ Yes | ❌ No | ❌ No | ❌ No | | Vector Similarity | ✅ Yes | ❌ No | ⚠️ pgvector only | ❌ No | | Multi-Tenant | ✅ Built-in | ⚠️ Manual | ⚠️ Manual | ❌ No | | Time Decay | ✅ Yes | ❌ No | ❌ No | ❌ No | | Auto-Expiry (TTL) | ✅ Yes | ✅ Yes | ⚠️ Manual | ❌ No | | Memory Scopes | ✅ Yes | ❌ No | ❌ No | ❌ No | | LLM Normalization | ✅ Optional | ❌ No | ❌ No | ❌ No | | Setup Complexity | ⚠️ Medium | ✅ Low | ⚠️ Medium | ✅ Low |

When to use Memscend:

• Long-running conversations (days/weeks)
• Multi-user agents (support, sales, etc.)
• Need semantic relevance, not just history
• Want automated memory management (TTL, deduplication)

When to use alternatives:

• Simple chatbots (use Window Buffer)
• Existing Redis/Postgres infrastructure
• Sub-second latency requirements (use in-memory)

Roadmap

Planned improvements based on gemini-architect analysis:

• [ ] Action Nodes: Standalone nodes for search, add, delete operations (use outside AI agents)
• [ ] Memory Analytics: Statistics on memory usage per user/session
• [ ] Export/Import: Backup and migration utilities
• [ ] Advanced Filters: Search by date range, score threshold, multiple scopes
• [ ] Batch Management: Bulk operations UI in n8n

License

MIT

Support

• Issues: https://github.com/nalyk/memscend/issues
• Documentation: https://mem.yoda.digital/docs
• API Reference: https://mem.yoda.digital/api/v1/docs

Credits

Built with:

• n8n - Workflow automation platform
• LangChain - AI framework
• Memscend - Multi-tenant memory service

Architecture designed with strategic guidance from Gemini 2.5 Pro and implementation by Qwen 3 Coder, orchestrated via Claude Code multi-agent system.