Your First 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.

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

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.

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.

Property	Purpose
`name`	Agent identifier
`traits`	Personality characteristics
`interests`	What the agent pays attention to
`voice`	Communication style guidelines

Step 4: Understand State Model

ClarkOS agents maintain rich internal state:

Field	Description
`mood`	contemplative, expressive, curious, reflective, concerned
`health`	0-100, depletes with activity, recovers with rest
`routine`	morning, day, evening, overnight
`volatility`	How much state fluctuates
`cryo`	Hibernation mode when health critical

Reference: AgentState interface in src/types.ts

Step 5: Memory Types

CLARK uses all 5 memory types:

Type	Example	Dedup 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:

Load current state
Calculate routine from time
Gather relevant memories
Process through consciousness layer
Generate LLM response
Store new memories
Maybe generate reflection (every 10 ticks)
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:

Gather recent emotional memories
Identify procedural patterns
Prompt LLM for metacognitive insight
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:

Gather all memories from past 24 hours
Count brilliant thoughts
Generate narrative summary
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

Feature	Description
Continuous operation	Thinks every 5 minutes autonomously
5 memory types	Events, facts, feelings, patterns, insights
Consciousness layer	Filters noise, detects patterns
Moments of brilliance	Recognizes significant convergences
Self-reflection	Metacognitive observations
Daily journals	Consolidates experiences
State evolution	Mood 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.

Getting Started

Core Concepts

Guides

Plugins

Your First Agent

Overview

What CLARK Does

Prerequisites

Step 1: Create Project

Step 2: Deploy to Convex

Step 3: Define Character

Step 4: Understand State Model

Step 5: Memory Types

Step 6: Tick Cycle

Step 7: Consciousness Layer

Step 8: Self-Reflection

Step 9: Daily Journals

Step 10: Scheduled Execution

Step 11: Run

Querying CLARK

What You’ve Built

Key Insight

Next Steps

Custom Plugins

Memory Management

​Overview

​What CLARK Does

​Prerequisites

​Step 1: Create Project

​Step 2: Deploy to Convex

​Step 3: Define Character

​Step 4: Understand State Model

​Step 5: Memory Types

​Step 6: Tick Cycle

​Step 7: Consciousness Layer

​Step 8: Self-Reflection

​Step 9: Daily Journals

​Step 10: Scheduled Execution

​Step 11: Run

​Querying CLARK

​What You’ve Built

​Key Insight

​Next Steps

Custom Plugins

Memory Management

Overview

What CLARK Does

Prerequisites

Step 1: Create Project

Step 2: Deploy to Convex

Step 3: Define Character

Step 4: Understand State Model

Step 5: Memory Types

Step 6: Tick Cycle

Step 7: Consciousness Layer

Step 8: Self-Reflection

Step 9: Daily Journals

Step 10: Scheduled Execution

Step 11: Run

Querying CLARK

What You’ve Built

Key Insight

Next Steps