Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.clarkos.dev/llms.txt

Use this file to discover all available pages before exploring further.

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

Memory Store

Memory system reference.

Plugins SDK

Plugin development reference.