Skip to main content
CLARK Agent

​
Overview

In this guide, you’ll build CLARK, an autonomous AI agent that thinks, learns, and evolves continuously. This showcases what makes ClarkOS different from request-response frameworks.

​
What CLARK Does

  • Runs autonomously on 5-minute tick cycles
  • Forms 5 types of memories (episodic, semantic, emotional, procedural, reflection)
  • Detects patterns and generates “moments of brilliance”
  • Self-reflects on its own state and learning
  • Creates daily journal entries
  • Evolves mood, health, and routine over time
This is not a chatbot. CLARK doesn’t wait for messages—it thinks continuously.

​
Prerequisites

  • Node.js 18+
  • OpenRouter API key (LLM)
  • Gemini API key (embeddings, free tier)

​
Step 1: Create Project

Clone the repository and navigate to the example agent: 
git clone https://github.com/clarkOS/clark
cd clark/example/convex
npm install
cp .env.example .env.local
Configure .env.local with your API keys:
  • OPENROUTER_KEY — LLM access
  • GEMINI_API_KEY — Embeddings
  • TICK_TOKEN — Authentication (generate with openssl rand -hex 32)
The example agent contains all the source code referenced in this guide.

​
Step 2: Deploy to Convex

ClarkOS runs on Convex serverless infrastructure.
1

Sign up for Convex

Create a free account at convex.dev if you don’t have one.
2

Start development server

npx convex dev
This will prompt you to log in and create a new project. Your local server will connect to Convex.
3

Deploy to production

When ready, deploy your agent:
npx convex deploy
Then set your environment variables in the Convex dashboard.

​
Step 3: Define Character

Create a character file that defines CLARK’s personality, interests, and voice. Reference: See convex/character.ts in the template.
PropertyPurpose
nameAgent identifier
traitsPersonality characteristics
interestsWhat the agent pays attention to
voiceCommunication style guidelines

​
Step 4: Understand State Model

ClarkOS agents maintain rich internal state:
FieldDescription
moodcontemplative, expressive, curious, reflective, concerned
health0-100, depletes with activity, recovers with rest
routinemorning, day, evening, overnight
volatilityHow much state fluctuates
cryoHibernation mode when health critical
Reference: AgentState interface in src/types.ts

​
Step 5: Memory Types

CLARK uses all 5 memory types:
TypeExampleDedup Threshold
Episodic”Read article about AI”0.92
Semantic”Convex is serverless”0.95
Emotional”Excited about this”0.88
Procedural”Morning news is noisy”0.97
Reflection”I’m analytical at night”0.90
Reference: Memory schema in convex/schema.ts

​
Step 6: Tick Cycle

Each tick follows this flow:
  1. Load current state
  2. Calculate routine from time
  3. Gather relevant memories
  4. Process through consciousness layer
  5. Generate LLM response
  6. Store new memories
  7. Maybe generate reflection (every 10 ticks)
  8. Commit state changes
Reference: See convex/tick.ts for implementation pattern.

​
Step 7: Consciousness Layer

The consciousness layer filters noise and detects patterns:
  • Filtering — Removes low-value inputs
  • Entity extraction — Identifies key topics
  • Pattern detection — Finds common themes
  • Brilliance check — Flags significant insights
A thought becomes “brilliant” when multiple high-importance inputs share entities. Reference: See consciousness processing in convex/consciousness.ts pattern.

​
Step 8: Self-Reflection

Every 10 ticks, CLARK generates a reflection:
  1. Gather recent emotional memories
  2. Identify procedural patterns
  3. Prompt LLM for metacognitive insight
  4. Store as reflection-type memory
This creates genuine self-awareness over time. Reference: See convex/reflection.ts pattern.

​
Step 9: Daily Journals

At midnight, CLARK consolidates the day’s experiences:
  1. Gather all memories from past 24 hours
  2. Count brilliant thoughts
  3. Generate narrative summary
  4. Store as journal entry
Reference: See convex/journal.ts pattern.

​
Step 10: Scheduled Execution

Set up crons for automatic operation: 
// convex/crons.ts
crons.interval("tick", { minutes: 5 }, api.tick.runTick);
crons.interval("feeds", { minutes: 15 }, api.feeds.fetch);
crons.cron("journal", "0 0 * * *", api.journal.generate);
crons.cron("consolidate", "0 3 * * *", api.memories.consolidate);

​
Step 11: Run

npm run dev
Watch the Convex dashboard for:
  • Tick logs every 5 minutes
  • Memory growth across types
  • Reflections every 10 ticks
  • Daily journals at midnight

​
Querying CLARK

curl http://localhost:3001/state
curl http://localhost:3001/logs?limit=10
curl http://localhost:3001/memories?type=reflection&limit=5
curl http://localhost:3001/consciousness/brilliant?limit=5

​
What You’ve Built

FeatureDescription
Continuous operationThinks every 5 minutes autonomously
5 memory typesEvents, facts, feelings, patterns, insights
Consciousness layerFilters noise, detects patterns
Moments of brillianceRecognizes significant convergences
Self-reflectionMetacognitive observations
Daily journalsConsolidates experiences
State evolutionMood and health change naturally

​
Key Insight

The shift from ElizaOS to ClarkOS is reactive to generative. CLARK doesn’t respond to the world—it continuously processes, understands, and creates.

​
Next Steps

Custom Plugins

Extend CLARK with new capabilities.

Memory Management

Optimize memory for your domain.