graphiti

Graphiti temporal knowledge graph memory for n8n AI agents

Package Information

Downloads: 31 weeklyĀ /Ā 69 monthly
Latest Version: 1.0.18

Available Nodes

Graphiti Memory icon
Graphiti Memory
Graphiti temporal knowledge graph memory for AI agents

Documentation

n8n-nodes-graphiti

Graphiti Memory Node
npm version
License: MIT

šŸ§  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:

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

šŸ“ž Support

ā­ Star History

Star History Chart

Made with ā¤ļø for the n8n and Graphiti communities

Discussion