Memory System

The memory system provides persistent context storage for AI conversations, enabling better continuity, personalization, and tool-specific knowledge.

What is the Memory System?

The memory system allows you to store contextual information that AI assistants can access during conversations. This creates a more personalized and continuous experience across multiple interactions.

Key Concepts

Memory Items

Individual pieces of information stored in the system:

• Label: Short, descriptive title
• Content: The actual information or context
• Category: Grouping (facts, preferences, context, instructions)
• Priority: Importance ranking (1-10)
• Applies To Tools: Which MCP tools should see this memory

Compiled Memory

The memory system automatically compiles memory items into:

• System Context: Global context for all tools
• Tool Contexts: Specific context for individual tools
• Full Prompt: Complete memory compilation

This compilation is regenerated whenever memory items change.

Creating Memory Items

From Dashboard

1. Navigate to Dashboard → Memory tab

2. Select an API key

3. Click Add Memory Item

4. Fill in the form:

   Label: My n8n instance details

   Content:

   My main n8n instance runs at https://n8n.example.com
   It contains production workflows for customer notifications

   Category: Context

   Priority: 8

   Applies To Tools: execute_workflow, list_workflows

5. Click Save

Memory Categories

Category	Purpose	Example
Facts	Unchanging information	"Company name is Acme Corp"
Preferences	User preferences	"Prefer JSON responses"
Context	Situational information	"Working on mobile app project"
Instructions	Behavioral guidelines	"Always ask before executing"

Priority Levels

Priority determines importance in context compilation:

• 10: Critical - Always include first
• 7-9: High - Important context
• 4-6: Medium - Useful but optional
• 1-3: Low - Nice to have
• 0: Archived - Not included in compilation

Using Memory

Automatic Context

When an AI assistant calls an MCP tool:

1. The memory system is queried for relevant items
2. Items are filtered by tool applicability
3. Items are sorted by priority
4. Context is compiled and injected
5. AI sees the context in tool responses

Example Flow

Memory Item:

Label: Production Workflow Info
Content: The "Send Welcome Email" workflow should only run for new users
Category: Instructions
Priority: 9
Applies To: execute_workflow

AI Request:

User: "Run the welcome email workflow"

Context Injection:

System Context: [Your memory items]
Tool Context for execute_workflow:
- The "Send Welcome Email" workflow should only run for new users

AI Response:

I'll execute the "Send Welcome Email" workflow. Based on your instructions,
I should verify this is for a new user. Should I proceed?

Managing Memory Items

View All Items

The Memory tab shows:

• All memory items for selected API key
• Organized by category
• Priority indicators
• Which tools they apply to

Edit Memory Items

To update an item:

1. Click the edit icon next to the item
2. Modify any fields
3. Click Save
4. Memory is automatically recompiled

Delete Memory Items

To remove an item:

1. Click the delete icon
2. Confirm deletion
3. Memory is recompiled without this item

Memory Compilation

How Compilation Works

1. Gather Items: Collect all memory items for the API key
2. Sort by Priority: Higher priority items first
3. Group by Category: Organize by facts, preferences, etc.
4. Generate Context: Create formatted context strings
5. Store Compiled: Save to mcpMemory table

Compiled Memory Structure

{
  systemContext: string // Global context for all tools
  toolContexts: {
    // Per-tool context
    execute_workflow: string
    list_workflows: string
    ping_n8n: string
  }
  fullPrompt: string // Complete compilation
}

Example Compilation

Memory Items:

1. [Facts/10] My company is Acme Corp
2. [Context/9] Working on customer notification system
3. [Instructions/8] Always test in dev before prod

Compiled System Context:

# Facts

- My company is Acme Corp

# Context

- Working on customer notification system

# Instructions

- Always test in dev before prod

Tool-Specific Memory

Applying Memory to Tools

When creating a memory item, specify which tools should see it:

Example:

Label: Workflow Naming Convention
Content: All workflows use kebab-case names (e.g., send-welcome-email)
Category: Instructions
Applies To: execute_workflow, list_workflows, search_workflows

This memory will only be included when the AI uses those specific tools.

Benefits

• Reduced Context Size: Only relevant memory is included
• Better Precision: Tool-specific instructions
• Improved Performance: Less noise in context

Use Cases

Workflow Documentation

Store information about your workflows:

Label: Payment Workflow Details
Content: |
  The "process-payment" workflow requires:
  - customerId (string)
  - amount (number)
  - currency (string, default: USD)

  It returns a paymentId on success
Category: Facts
Priority: 9
Applies To: execute_workflow

Business Context

Provide business-specific information:

Label: Business Hours
Content: Our business operates Mon-Fri, 9am-5pm EST
Category: Context
Priority: 7
Applies To: execute_workflow, schedule_workflow

Safety Instructions

Add guardrails and safety checks:

Label: Production Safety
Content: Never modify production data without explicit confirmation
Category: Instructions
Priority: 10
Applies To: execute_workflow, update_workflow

User Preferences

Store personal preferences:

Label: Communication Preference
Content: I prefer detailed explanations of what each workflow does
Category: Preferences
Priority: 6
Applies To: *

Memory Analytics

Usage Tracking

The system tracks:

• When memory items are created/updated
• How often they're included in tool calls
• Which tools use which memory items

View analytics in the Usage tab.

Memory Events

Logged events:

{
  eventType: 'memory_compiled',
  apiKeyId: '...',
  itemCount: 5,
  toolsAffected: ['execute_workflow', 'ping_n8n'],
  timestamp: '2024-01-15T10:30:00Z'
}

Best Practices

Organization

• Use clear labels: "Production DB Credentials" not "DB Info"
• Keep content focused: One concept per memory item
• Use categories: Properly categorize for better organization
• Set appropriate priority: Critical items get priority 9-10

Content Guidelines

• Be specific: "Workflow X requires parameter Y" not "Some workflows need params"
• Use examples: Show concrete examples in content
• Update regularly: Keep memory current as things change
• Avoid duplication: Don't repeat information across items

Privacy & Security

• No secrets: Don't store passwords or API keys in memory
• No PII: Avoid personal identifiable information
• Use references: Point to secure storage instead of including sensitive data
• Regular audit: Review memory items periodically

Limitations

Current limitations:

• No sharing: Memory is per-API key (not shared between keys)
• No import/export: Manual entry only
• Fixed categories: Cannot create custom categories
• No versioning: No history of changes

Future enhancements:

• Memory item sharing
• Import/export functionality
• Custom categories
• Version history
• AI-assisted memory creation

API Access

Get Compiled Memory

GET /api/memory/compiled?apiKeyId={id}

Response:
{
  systemContext: "...",
  toolContexts: { ... },
  fullPrompt: "...",
  itemCount: 5,
  lastUpdated: "2024-01-15T10:30:00Z"
}

Get Memory Items

GET /api/memory/items?apiKeyId={id}

Response:
{
  items: [
    {
      id: "...",
      label: "Workflow Info",
      content: "...",
      category: "facts",
      priority: 9,
      appliesToTools: ["execute_workflow"]
    }
  ]
}

Create Memory Item

POST /api/memory/items

{
  apiKeyId: "...",
  label: "New Memory",
  content: "Content here",
  category: "facts",
  priority: 8,
  appliesToTools: ["execute_workflow"]
}

Troubleshooting

Memory Not Appearing in Context

Check:

1. Priority is > 0
2. Tool name in "Applies To" matches exactly
3. Memory compilation is up to date
4. API key is correct

Context Too Large

If compiled memory is too large:

1. Reduce priority of less important items
2. Make content more concise
3. Remove unused memory items
4. Use tool-specific memory instead of global

Memory Not Updating

If changes don't take effect:

1. Verify item was saved successfully
2. Check compilation status
3. Restart MCP client
4. Clear any client-side caches

Next Steps

• View MCP Tools →
• Learn About n8n Workflows →
• Read Usage Guide →