A fully self-hosted AI Agent built on n8n + PostgreSQL + Claude, featuring adaptive RAG memory, knowledge graph, MCP skills, expert sub-agents, and proactive task management, interacted via Telegram or Webhook API.
n8n-claw is a fully self-hosted AI Agent system built on n8n as the workflow engine, PostgreSQL as the data layer, and Claude as the default LLM, deployed via Docker Compose on a self-owned Linux VPS. It interacts with users through Telegram chat or HTTP Webhook API.
Core Capabilities#
Memory & Knowledge
- Hybrid-search enhanced long-term memory: semantic + full-text + entity matching with RRF fusion, time decay, tags, entity tracking, source attribution, and auto-expiration; degrades to keyword search when embedding API fails
- Knowledge graph: auto-tracks people, companies, products, and events with multi-hop traversal to reveal relationships
- Project memory: persistent Markdown documents tracking ongoing work across conversations
- Memory consolidation: daily at 3 AM, automatically writes conversation summaries to long-term memory
Task & Automation
- Task management: create, track, complete tasks with priority and deadlines
- Proactive heartbeat: checks and reminds expired/urgent tasks every 5 minutes
- Periodic actions: arbitrary scheduled recurring tasks (e.g., "check email every 15 minutes")
- Intelligent background checking: runs silently, notifies only on new discoveries
- Smart reminders & scheduled actions: timed Telegram reminders + execute instructions at due time (checks every 1 minute)
- Fault awareness: workflow errors auto-logged to memory and pushed as Telegram alerts, queryable via natural language
Skills & Agents
- Expert agents: delegate complex tasks to specialized sub-agents (3 built-in, 100+ available across 12 categories)
- MCP skills: install pre-built skills or build new API integrations on-demand via MCP Builder
- OpenClaw integration: delegate coding tasks to autonomous AI Agent (build websites, apps, execute shell commands)
Information Retrieval & Processing
- Web search: built-in SearXNG instance (no API key required)
- Web reader: Crawl4AI converts pages to clean Markdown (JS rendering supported)
- File passing: store Telegram documents and photos for skill use, download files from internet/cloud and return to chat
- Voice messages: OpenAI Whisper transcription (optional)
Architecture Overview#
Core call chain: Telegram / Webhook API → n8n-claw Agent (Claude Sonnet) → Task Manager / Project Manager / Memory / Knowledge Graph / MCP Client / Expert Agent / HTTP Tool and other modules.
Background workflows:
- Heartbeat (every 5 min): periodic actions + proactive reminders + file cleanup
- Background Checker: silent checking, notifies only on new findings
- Memory Consolidation (daily at 3 AM): conversation summaries → long-term memory
- Reminder Runner (every 1 min): send due reminders + trigger one-time actions
- Error Notification: capture workflow failures → Telegram alert + log to memory_long
Internal services: File Bridge (temporary binary file storage), Email Bridge (IMAP/SMTP REST API). Data layer uses PostgreSQL as the sole database, PostgREST auto-generates REST API, Kong as API gateway, Supabase Studio for management UI. Memory search implemented as PLpgSQL functions using RRF to fuse three retrieval paths. Docker Compose orchestrates all services.
Integration & Extension#
- Google Services OAuth2 support
- WhatsApp as alternative to Telegram
- Webhook adapters: Slack Trigger / Teams Trigger / Generic Webhook / Custom Webhook mapping
- External clients: Claude Desktop, ChatGPT, Claude Code, Lovable, Cursor
- Optional workflows (manual activation in n8n UI): MCP Builder, MCP: Weather, WorkflowBuilder
Deployment & Configuration#
Prerequisites: Linux VPS (Ubuntu 22.04/24.04 recommended), Telegram Bot Token + Chat ID, LLM API Key (supports Anthropic/OpenAI/OpenRouter/DeepSeek/Gemini/Mistral/Ollama), domain (or sslip.io auto-generated). Minimum: 4 GB RAM / 15 GB disk.
One-line install:
git clone https://github.com/freddy-schuetz/n8n-claw.git && cd n8n-claw && ./setup.sh
Setup script interactively guides configuration of n8n API Key, Telegram credentials, LLM API Key, domain, Agent persona (name/language/style/custom persona), and optional embedding model and voice transcription. Ready to use via Telegram immediately after installation.
Webhook API endpoint: POST /webhook/agent, authenticated via X-API-Key header, request body contains message and user_id fields.
MIT license, 489+ commits, 46 releases, latest version v1.5.0.