n8n-nodes-memmachine

An n8n community node that integrates with the MemMachine API, enabling advanced conversational memory management in your n8n workflows.

Nodes Overview

This package provides two n8n community nodes for MemMachine integration:

• Main Node (MemMachine Manager)
  • Actions:
    1. Store a message — Save conversational messages to MemMachine
    2. Enrich with context — Retrieve historical context from MemMachine and enrich AI agent responses
• AI Memory Node (MemMachine Memory)
  • Connects directly to the AI agent’s memory port in n8n workflows
  • Enables advanced memory operations and seamless integration with AI agent tools for conversational context management

Installation

Community Nodes

Follow the installation guide in the n8n community nodes documentation.

1. Go to Settings > Community Nodes.
2. Select Install.
3. Enter @memmachine/n8n-nodes-memmachine in Enter npm package name.
4. Agree to the risks of using community nodes: select I understand the risks of installing unverified code from a public source.
5. Select Install.

After installing the node, you can use it like any other node. n8n displays the node in search results in the Nodes panel.

Docker Installation

This directory contains a distribution build of the n8n-nodes-memmachine package ready for testing with a local n8n instance.

Quick Start with Docker Compose

Prerequisites

• Docker and Docker Compose installed
• MemMachine running externally (on host or separate Docker network)

Start n8n with the Memory Node

# Start n8n and Jaeger
docker-compose up -d

# View logs
docker-compose logs -f

# Access services:
# - n8n UI: http://localhost:5678
# - Jaeger UI: http://localhost:16686
# Default n8n credentials on first run: create your own

# Stop services
docker-compose down

The stack includes:

• n8n (localhost:5678) - Workflow automation with Memory node
• Jaeger (localhost:16686) - Distributed tracing UI for observability

Configure MemMachine Connection

The MemMachine service must be running separately. Configure credentials in n8n:

If MemMachine is on your host:

• API Endpoint: http://host.docker.internal:8080 (Mac/Windows)
• API Endpoint: http://172.17.0.1:8080 (Linux - Docker bridge IP)

If MemMachine is in another Docker network:

• Add n8n to that network in docker-compose.yml
• API Endpoint: http://memmachine:8080 (use service name)

If MemMachine is on remote server:

• API Endpoint: http://your-memmachine-host:8080
• API Key: (if authentication is enabled)

Local Install as npm Package

Alternatively, you can install directly into a local n8n instance:

# Link to local n8n
npm link
cd ~/.n8n/custom
npm link n8n-nodes-memory

# Or install globally
npm install -g .

# Restart n8n

Configuration

MemMachine API Credentials

1. Open n8n at http://localhost:5678
2. Go to Credentials → New
3. Search for "MemMachine API"
4. Configure:
   • API Endpoint: http://memmachine:8080 (Docker) or http://localhost:8080/api/v2 (local)
   • API Key: (optional, if your MemMachine requires authentication)
5. Test and save

Using the Memory Node

1. Create a new workflow
2. Add the MemMachine node
3. Select operation:
   • Store: Save conversation messages
   • Enrich: Retrieve historical context
4. Configure context:
   • Organization ID, Project ID, Group ID, Agent ID, User ID, Session ID

Files in This Directory

• package.json - Package metadata
• nodes/ - MemMachine nodes implementation
• credentials/ - MemMachine API credentials definition
• dist/ - Compiled JavaScript
• LICENSE - MIT license
• README.md - This file
• docker-compose.yml - Docker setup for local testing

Advanced Docker Configuration

Connecting to MemMachine on Same Docker Network

If your MemMachine is in another Docker Compose stack, connect them:

# In this docker-compose.yml, add external network
networks:
  n8n-network:
    name: n8n-memory-network
    driver: bridge
  memmachine-network:
    external: true
    name: your-memmachine-network

services:
  n8n:
    networks:
      - n8n-network
      - memmachine-network

Then use the MemMachine service name as endpoint: http://memmachine:8080

Using Host Network (Linux only)

services:
  n8n:
    network_mode: host

Then use http://localhost:8080/api/v2 as the MemMachine endpoint.

Troubleshooting

Node not appearing in n8n

1. Check logs: docker-compose logs n8n
2. Verify volume mount: docker exec -it n8n-memory-test ls /data/nodes
3. Restart: docker-compose restart n8n

Cannot connect to MemMachine

1. Check MemMachine is running: curl http://localhost:8080/api/v2/health
2. Check network connectivity: docker exec -it n8n-memory-test ping memmachine
3. Verify credentials configuration in n8n UI

Jaeger not showing traces

1. Check Jaeger is running: docker-compose logs jaeger
2. Access Jaeger UI: http://localhost:16686
3. Verify environment variables in docker-compose.yml:
   • JAEGER_AGENT_HOST=jaeger
   • JAEGER_AGENT_PORT=6831
4. Check traces are being sent: Look for "Service" dropdown in Jaeger UI
5. If no traces appear, check Memory node logs for OpenTelemetry errors

Permission issues

# Fix permissions
chmod -R 755 .
docker-compose down -v
docker-compose up -d

Observability with Jaeger

The Memory node includes OpenTelemetry instrumentation for distributed tracing. Use Jaeger to:

• Monitor performance: See execution time for store and enrich operations
• Debug issues: Trace requests through n8n → Memory node → MemMachine
• Analyze patterns: Identify slow queries or error patterns

Viewing Traces:

1. Open Jaeger UI at http://localhost:16686
2. Select service from dropdown (look for Memory node service name)
3. Click "Find Traces" to see recent operations
4. Click on a trace to see detailed span information

Publishing to npm

Automated Publishing with GitHub Actions

This distribution includes a GitHub Actions workflow (.github/workflows/publish.yml) that automatically publishes to npm when you push a version tag:

Setup (one-time):

1. Create npm token at https://www.npmjs.com/settings/[your-username]/tokens

   • Token type: "Automation" or "Publish"
   • Copy the token

2. Add token as GitHub repository secret:

   • Go to repository Settings > Secrets and variables > Actions
   • Click "New repository secret"
   • Name: NPM_TOKEN
   • Value: (paste your npm token)

To publish a new version:

# Update version in package.json
npm version patch  # or minor, major

# Push the tag (this triggers the workflow)
git push origin v1.0.1

The workflow will:

• ✅ Verify package.json version matches the tag
• ✅ Create package tarball
• ✅ Publish to npm with provenance
• ✅ Create GitHub release with installation instructions

Manual Publishing

If you prefer to publish manually:

# Test the package
npm pack
npm install -g ./n8n-nodes-memory-*.tgz

# Publish to npm
npm publish

# Or publish to private registry
npm publish --registry https://your-registry.com

Development

1. Install dependencies:

npm install

2. Build the project:

npm run build

3. Build the project before publishing:

npm run prepublishOnly

4. Start Docker:

npm run docker:start

5. Stop Docker:

npm run docker:stop

6. View Docker logs:

npm run docker:logs

Resources

• n8n Documentation
• MemMachine Documentation
• Creating n8n Nodes

Support

For issues or questions:

• GitHub Issues: [Your repository URL]
• MemMachine Docs