n8n-nodes-graphiti

🧠 Temporal Knowledge Graph Memory for n8n AI Agents

⚠️ Dependencies

This node requires Graphiti Awesome Memory backend to be running.

Graphiti Awesome Memory is a FastAPI-based adapter that provides REST API endpoints for Graphiti temporal knowledge graph. It handles:

• User session management
• Message persistence
• Semantic fact extraction
• Episode (conversation history) storage
• Knowledge graph querying

📖 Setup Graphiti Awesome Memory Backend →

✨ Features

🧠 Dual Memory Architecture

• Short-term Memory: Recent conversation episodes from database (persistent across restarts)
• Long-term Memory: Extracted facts stored in temporal knowledge graph
• Semantic Search: Intelligent fact retrieval based on query relevance

🔧 n8n Integration

• ✅ AI Agent node compatible
• ✅ Session-based memory per user
• ✅ Configurable context windows
• ✅ Graceful error handling with fallbacks
• ✅ Comprehensive logging

🚀 Production Ready

• ⏱️ 180-second timeout for slow LLM processing
• 🔄 Network resilience with automatic fallbacks
• 📊 Structured memory formatting for optimal LLM consumption
• 📄 Memory source tracking - AI knows if facts come from files or conversation
• 🎯 Version 1.0.17 with grouped query support

📦 Installation

Via n8n Community Nodes (Recommended)

1. Open your n8n instance
2. Go to Settings → Community Nodes
3. Click Install
4. Enter: n8n-nodes-graphiti
5. Click Install
6. Restart n8n

Manual Installation

npm install n8n-nodes-graphiti

⚙️ Configuration

1. Set up Graphiti Awesome Memory Backend

Follow the setup instructions at Graphiti Awesome Memory

Quick start:

# Clone and configure
git clone https://github.com/GoGoButters/Graphiti_Awesome_Memory.git
cd Graphiti_Awesome_Memory

# Configure secrets (LLM, Embeddings, Neo4j, etc.)
nano config.yml

# Generate env files and start Docker containers
bash scripts/generate_envs.sh
docker compose up -d --build

Services will be available at:

• Adapter API: http://localhost:8000/docs
• Admin UI: http://localhost:3000
• Neo4j Browser: http://localhost:7474

2. Configure Credentials in n8n

1. Go to Credentials → New
2. Search for "Graphiti API"
3. Fill in:
   • API URL: Your Graphiti server URL (e.g., http://192.168.1.98:8000)
   • API Key: Your authentication key
4. Test and save

🎯 Usage

Basic AI Agent Workflow

[Webhook/Chat Trigger]
       ↓
[Settings Node] ← Define chatId/userId
       ↓
[Graphiti Memory] ← Load context (before agent)
       ↓
[AI Agent] ← Uses enriched memory
       ↓
[Graphiti Memory] ← Save conversation (after agent)
       ↓
[Respond to User]

Node Parameters

| Parameter | Default | Description | |-----------|---------|-------------| | Session ID Type | fromInput | How to determine session ID | | Session Key | ={{ $json.sessionId }} | Expression to extract user/session ID | | Context Window Length | 5 | Number of recent episodes to fetch from database | | Search Limit | 10 | Maximum facts retrieved from knowledge graph |

How It Works

When AI Agent requests memory, the node performs 2 API calls:

1. Grouped Semantic Search (POST /memory/query/grouped)

   • Searches knowledge graph for relevant facts
   • Groups results by source (files vs conversation)
   • Returns facts with source attribution and confidence scores

2. Episode Retrieval (GET /memory/users/{userId}/episodes)

   • Fetches last N conversation messages from database
   • Persistent across n8n restarts
   • Returns actual user/assistant dialogue

Memory Output Format

=== Relevant Facts from Long-term Memory ===

📄 From file: medical_records.pdf
  1. Patient has hypertension history (confidence: 0.95)
  2. Last checkup was in November 2024 (confidence: 0.89)

📄 From file: lab_results.pdf
  1. Blood pressure: 120/80 (confidence: 0.92)

💬 From conversation:
  1. User's name is Alice (confidence: 0.95)
  2. Alice prefers morning appointments (confidence: 0.87)

=== Recent Conversation ===
User: Hi, how are you?
Assistant: I'm doing well, thanks for asking!
User: What's my name?

Note: The 📄 and 💬 icons help AI agents understand and cite where each fact originated.

🔌 API Reference

Graphiti Awesome Memory Endpoints

POST /memory/append - Save conversation message

{
  "user_id": "35145416",
  "text": "User message content",
  "metadata": {
    "role": "user",
    "source": "n8n",
    "session_id": "35145416",
    "timestamp": "2025-12-01T12:00:00Z"
  }
}

POST /memory/query/grouped - Grouped semantic fact search

{
  "user_id": "35145416",
  "query": "What do I like?",
  "limit": 10
}

Response:

{
  "groups": [
    {
      "source_type": "file",
      "source_name": "interests.pdf",
      "facts": [{"fact": "User likes robotics", "score": 0.95}]
    },
    {
      "source_type": "conversation",
      "source_name": null,
      "facts": [{"fact": "User mentioned hiking", "score": 0.85}]
    }
  ],
  "total_facts": 2
}

GET /memory/users/{userId}/episodes - Retrieve conversation history

GET /memory/users/35145416/episodes?limit=5

🛠️ Development

Prerequisites

• Node.js 18+
• n8n installed locally
• Graphiti Awesome Memory backend running

Setup

# Clone repository
git clone https://github.com/GoGoButters/Graphiti_n8n_node.git
cd Graphiti_n8n_node

# Install dependencies
npm install

# Build
npm run build

# Link for local n8n development
npm link
cd ~/.n8n/nodes
npm link n8n-nodes-graphiti

Scripts

• npm run build - Compile TypeScript and copy assets
• npm run dev - Watch mode for development
• npm run format - Format code with Prettier
• npm run lint - Lint code with ESLint
• npm run lintfix - Auto-fix linting issues

🐛 Troubleshooting

Memory not loading

• ✅ Check Graphiti Awesome Memory backend is running
• ✅ Verify API credentials are correct
• ✅ Check Session Key expression resolves correctly
• ✅ Look at n8n server logs for detailed error messages

Server Logs Location:

# Docker
docker logs n8n-container --tail 100

# PM2
pm2 logs n8n

Connection timeout issues

• ✅ Ensure Graphiti server is reachable from n8n
• ✅ Check firewall/network settings
• ✅ Verify API URL format (no trailing slash)
• ✅ Consider increasing timeout if processing is slow

Session ID not persisted

• ✅ Set Session ID Type to Define Below
• ✅ Use expression: ={{ $('Settings').first().json.chatId }}
• ✅ Ensure Settings node passes chatId/userId
• ✅ Check logs for [Graphiti Node] FINAL sessionId

Episodes endpoint fails

Node automatically falls back to in-memory chatHistory if episodes endpoint is unavailable. Check logs:

[Graphiti] Error fetching episodes: ...
[Graphiti] Falling back to chatHistory...

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Ensure linting passes (npm run lint)
5. Commit changes (git commit -m 'feat: Add amazing feature')
6. Push to branch (git push origin feature/amazing-feature)
7. Open a Pull Request

💰 Support the Project

If you find this project valuable, consider supporting its development:

Cryptocurrency Donations

• USDT (ERC20): 0xd91e775b3636f2be35d85252d8a17550c0f869a6
• Bitcoin (BTC): 3Eaa654UHa7GZnKTpYr5Nt2UG5XoUcKXgx
• Ethereum (ETH): 0x4dbf76b16b9de343ff17b88963d114f8155a2df0
• Tron (TRX): TT9gPkor4QoR9c12x8HLbvCLeNcS9KDutc

Your support helps maintain and improve this project! 🙏

📄 License

MIT © GoGoButters

🔗 Links

• GitHub Repository
• npm Package
• Graphiti Awesome Memory Backend
• Graphiti Project
• n8n Documentation

📞 Support

• 🐛 Report Issues
• 💬 n8n Community Forum
• 📧 Create an issue on GitHub for questions

⭐ Star History

Made with ❤️ for the n8n and Graphiti communities