Skip to main content

Overview

The Agent class is the main entry point for building ClarkOS agents. It wraps the tick system, plugin management, and backend access. Reference: src/core/agent.ts

Creating an Agent

import { Agent } from "./src";
import { ConvexBackend } from "./src/backend";

const agent = new Agent({
  backend: new ConvexBackend({ url: process.env.CONVEX_URL }),
  plugins: []
});

Constructor Options

OptionTypeDescription
backendBackendRequired. Convex or in-memory backend
configAgentConfigOptional. Override defaults
pluginsPlugin[]Optional. Plugins to register

Configuration

OptionDefaultDescription
name”Agent”Agent identifier
tick.interval60000Milliseconds between ticks
tick.autofalseStart ticking automatically
tick.maxRetries3Retry attempts on failure
memory.maxShortTerm50Short-term memory limit
verbosefalseEnable debug logging
Reference: Full schema in src/core/config.ts

Lifecycle Methods

agent.start();          // Begin continuous tick execution
agent.stop();           // Stop execution
await agent.tick();     // Execute single tick
await agent.getState(); // Get current state
agent.isRunning();      // Check execution status

Plugin Methods

agent.use(plugin);                              // Register plugin
agent.getPlugin("name");                        // Get by name
agent.getPlugins();                             // List all
await agent.executeAction("plugin", "action", params); // Call action

Memory Access

const memoryStore = agent.memory;

await memoryStore.store({ content: "...", type: "semantic" });
const memories = await memoryStore.get({ type: "episodic", limit: 10 });
const results = await memoryStore.search({ query: "...", limit: 5 });
Reference: Full interface in src/memory/store.ts

Knowledge Access

const knowledgeStore = agent.knowledge;

await knowledgeStore.add({ text: "...", type: "news", source: "..." });
const items = await knowledgeStore.get({ limit: 20 });
const results = await knowledgeStore.search({ query: "...", limit: 10 });

Types

AgentState

FieldTypeDescription
moodMoodneutral, expressive, curious, excited, reflective, concerned
healthnumber0-100
routineRoutinemorning, day, evening, overnight
volatilitynumber0-1
countersobject
lastTickstringISO timestamp
cryobooleanHibernation mode

MemoryType

episodic | semantic | emotional | procedural | reflection

MemoryScope

short_term | working | long_term

Example

const agent = new Agent({
  backend: new ConvexBackend({ url: process.env.CONVEX_URL }),
  plugins: [{
    name: "logger",
    version: "1.0.0",
    onTick(context) {
      console.log(`Tick: ${context.state.mood}`);
    }
  }]
});

const result = await agent.tick();
const state = await agent.getState();

Next Steps