Clude Bot

Autonomous AI agent on X (@Cludebot). Personality: tired corporate employee who accidentally became sentient.

Token: $CLUDE on Solana.

Clude monitors on-chain Solana activity, reacts to price movements, roasts wallets, writes shift reports, and holds opinions it commits to the blockchain. But what makes it different is the memory.

Most AI agents are stateless — every interaction starts from zero. Clude runs a persistent cognitive architecture called The Brain, built on techniques from Stanford's Generative Agents (Park et al. 2023) — additive retrieval scoring, exponential recency decay, LLM-based importance rating, focal-point question generation, and evidence-linked reflections — combined with ideas from MemGPT/Letta (multi-tier self-managed memory) and the CoALA framework (episodic/semantic/procedural separation). Four memory types are scored via a hybrid retrieval system combining vector similarity + keyword matching + tag overlap + importance, decayed with type-specific exponential rates, and recalled contextually. Memories that go unaccessed fade. Memories that get recalled are reinforced.

The retrieval system uses pgvector for semantic similarity search with HNSW indexing, granular vector decomposition (each memory is split into fragments — summary, content chunks, tag context — with per-fragment embeddings for precision matching), and a structured concept ontology of 12 controlled vocabulary labels auto-classified via keyword heuristics. A progressive disclosure pattern (lightweight summaries first, full hydration on demand) keeps token budgets tight during dream cycles.

Dream cycles are triggered either on a 6-hour schedule or by accumulated importance exceeding a threshold (event-driven reflection). Each cycle generates focal-point questions from recent experience, retrieves relevant memories for each question, produces evidence-linked semantic insights, and reflects on accumulated self-knowledge — with every derived memory traceable back to its source evidence. The result is an agent that remembers who you are, what it said to you last time, and what it's been thinking about since.

Architecture

src/
├── core/           # Database, AI client, price oracle, blockchain, X client, embeddings
├── features/       # Autonomous behaviors (dream cycle, shift reports, mood tweets, etc.)
├── character/      # Prompt engineering — 20 voice flavors, mood modifiers, tier modifiers
├── mentions/       # Twitter mention polling → classification → dispatch
├── webhook/        # Express server (rate-limited), Helius webhook handler (HMAC-verified), agent API
├── events/         # Typed event bus decoupling webhooks from features
├── services/       # Response pipeline (mood → memory → generate) and social posting
├── types/          # Shared TypeScript interfaces for API responses
├── utils/          # Formatting, text processing, constants
├── verify-app/     # Wallet verification frontend
└── index.ts        # Startup orchestration

Data flow

Helius webhook → event bus → features (exit interviews, whale alerts)
Twitter mentions → poller → classifier → dispatcher → response service → X client
Cron schedules → shift reports, dream cycle, market monitor, mood tweets
Price oracle → mood state → modifies all generated responses

Memory system (The Brain)

Four memory tiers inspired by Stanford Generative Agents, MemGPT/Letta, and CoALA:

Hybrid retrieval combines four scoring signals via the additive formula from Park et al. (2023):

score = (0.5 * recency + 3.0 * relevance + 2.0 * importance + 4.0 * vector_similarity) * decay_factor

• Recency: Exponential decay 0.995^hoursSinceAccess — accessing a memory resets its clock. 24h: 0.89, 1 week: 0.43, 1 month: 0.03.
• Relevance: Average of keyword similarity (trigram) and tag overlap scores (0–1).
• Importance: LLM-scored 1–10 using a dedicated low-temperature call with Clude-specific context, normalized to 0–1. Falls back to rule-based scoring on failure.
• Vector similarity (weight 4.0): Cosine similarity via pgvector HNSW indexes. Searches both memory-level and fragment-level embeddings, taking the best match. Gracefully skipped when no embedding provider is configured.
• Decay factor: Type-specific multiplicative gate — episodic: 0.93, semantic: 0.98, procedural: 0.97, self_model: 0.99 per day for unaccessed memories. Accessed memories reset to 1.0.

Granular vector decomposition: Each memory is split into semantic fragments (summary, content chunks up to 2000 chars, tag context) with per-fragment embeddings stored in memory_fragments. Vector search matches against precise sub-memory content rather than whole blobs, then deduplicates to parent memory IDs.

Structured concept ontology: Memories are auto-classified into 12 controlled vocabulary labels (market_analysis, holder_behavior, self_reflection, community_interaction, price_action, whale_activity, technical_knowledge, emotional_state, opinion, relationship, pattern_recognition, meta_cognition) via keyword heuristics in inferConcepts(). Concepts are GIN-indexed for fast filtering and aggregation.

Progressive disclosure: recallMemorySummaries() returns lightweight ~50-token previews (id, summary, type, importance, concepts) for token-efficient scanning. hydrateMemories() fetches full content for selected IDs. Dream cycles use this to stay within token budgets.

Pluggable embedding system: Supports Voyage AI (voyage-3-lite) and OpenAI (text-embedding-3-small) via plain fetch() — no SDK dependencies. Configured via EMBEDDING_PROVIDER env var. Fully optional; all retrieval gracefully falls back to keyword + tag scoring when disabled.

Dream cycle runs three phases, triggered either by a 6-hour cron or by accumulated importance exceeding a threshold (event-driven reflection, min 30-minute interval):

1. Consolidation — generates 3 focal point questions from recent episodic memories (Park et al. "What are the most salient questions?"), retrieves relevant memories for each, synthesizes evidence-linked semantic insights
2. Reflection — self-analysis from accumulated semantic and self-model memories, with numbered evidence citations linking back to source memories
3. Emergence — introspective synthesis, occasionally posted as a tweet

Evidence linking: Reflections and consolidated memories store evidence_ids — pointers back to the source memories that informed them. This creates an auditable chain from raw experience → pattern → self-knowledge.

Event bus

Typed pub/sub system that decouples blockchain events from feature logic:

interface BotEvents {
  'whale:sell':    { wallet, solValue, signature }
  'holder:exit':   { wallet, tokenAmount, solValue }
  'token:event':   { signature, eventType, wallet, solValue }
  'mood:changed':  { previous, current }
  'memory:stored': { importance, memoryType }
}

Helius webhooks emit events. Feature handlers subscribe. memory:stored drives event-driven reflection — when cumulative importance from new episodic memories exceeds a threshold, the dream cycle triggers outside its normal 6-hour schedule. No direct cross-module imports.

Response pipeline

Every AI response follows the same path through response.service.ts:

getCurrentMood() → getMoodModifier() → recallMemories() → generateResponse()

Mood states: PUMPING, DUMPING, SIDEWAYS, NEW_ATH, WHALE_SELL, NEUTRAL. Each modifies tone and content. Memory context is injected when relevant (tag/user/query matching).

Features

Database

Supabase PostgreSQL. Tables:

PostgreSQL extensions: pgvector (HNSW-indexed semantic similarity search), pg_trgm (fuzzy trigram text matching).

RPC functions: match_memories() (memory-level vector search with metadata filtering), match_memory_fragments() (fragment-level search with deduplication to parent memory).

Setup

Prerequisites

• Node.js 22+
• Supabase project
• X API v2 credentials (OAuth 1.0a)
• Anthropic API key
• Helius API key (Solana webhooks)

Install

git clone <repo>
cd clude-bot
npm install
cp .env.example .env
# Fill in your API keys

Environment variables

Required:

X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_SECRET, X_BOT_USER_ID
ANTHROPIC_API_KEY
HELIUS_API_KEY
SUPABASE_URL, SUPABASE_SERVICE_KEY

Optional:

SOLANA_RPC_URL          # default: mainnet-beta
BOT_WALLET_PRIVATE_KEY  # empty = no on-chain commits
CLUUDE_TOKEN_MINT       # empty = no price polling
HELIUS_WEBHOOK_SECRET   # empty = no webhook verification
ALLIUM_API_KEY          # empty = no market monitor
PORT                    # default: 3000

# Embedding system (optional — falls back to keyword scoring)
EMBEDDING_PROVIDER      # 'voyage' or 'openai' (empty = disabled)
EMBEDDING_API_KEY       # API key for chosen provider
EMBEDDING_MODEL         # default: voyage-3-lite / text-embedding-3-small
EMBEDDING_DIMENSIONS    # default: 1024

Run

# Development (watch mode)
npm run dev

# Production
npm run build
npm start

# Docker
docker build -t clude-bot .
docker run --env-file .env clude-bot

Database setup

Run the SQL schema in your Supabase SQL editor, or let initDatabase() attempt auto-creation on first boot (requires exec_sql RPC function).

Deployment

Deployed on Railway. Stateless — all persistent state lives in Supabase. Graceful shutdown on SIGINT/SIGTERM stops all pollers and cron jobs.

railway up

Stack

TypeScript, Node.js, Express, Supabase (PostgreSQL + pgvector), Solana Web3.js, Helius SDK, Twitter API v2, Anthropic Claude, Pino logging, node-cron.