> ## 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.

# ClarkOS

> Build autonomous agents with persistent memory & realtime intelligence

<img src="https://mintcdn.com/clark-c047c062/Mv3eXb7zsCUdaDzy/images/clark.png?fit=max&auto=format&n=Mv3eXb7zsCUdaDzy&q=85&s=275caeeaf9f2ab6329cff7a968b33ca8" alt="ClarkOS" style={{ borderRadius: '8px', marginBottom: '2rem', maxWidth: '600px' }} width="2848" height="1504" data-path="images/clark.png" />

> **C**ontinuously **L**earning **A**gentic **R**ealtime **K**nowledgebase **OS**

**always on. always learning.**

ClarkOS is a TypeScript-first agent framework built on Convex serverless infrastructure. It provides the architecture for agents that operate continuously, maintain persistent memory, and evolve through autonomous tick cycles.

<CardGroup cols={3}>
  <Card title="Live Demo" icon="globe" href="https://clark.wiki">
    See CLARK in action
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/clarkOS/clark">
    View the source
  </Card>

  <Card title="X / Twitter" icon="twitter" href="https://x.com/clarkwiki">
    Follow updates
  </Card>
</CardGroup>

***

## SDK vs CLARK Demo

This documentation covers the **ClarkOS SDK** - the foundation for building autonomous agents. The live demo at [clark.wiki](https://clark.wiki) runs **CLARK**, a full implementation with additional features.

| Feature                     | SDK (This Repo) | CLARK Demo |
| --------------------------- | --------------- | ---------- |
| Tick-based execution        | ✅               | ✅          |
| 5 memory types              | ✅               | ✅          |
| Type-specific deduplication | ✅               | ✅          |
| Plugin system               | ✅               | ✅          |
| Multi-provider LLM          | ✅               | ✅          |
| Terminal UI                 | ✅               | -          |
| Memory linking              | Schema only     | ✅ Full     |
| Memory consolidation        | Schema only     | ✅ Full     |
| Consciousness synthesis     | Templates only  | ✅ Full     |
| Daily journals              | Schema only     | ✅ Full     |
| Chat with presence          | -               | ✅          |
| Market analysis             | -               | ✅          |

***

## Framework Comparison

| Capability               | ElizaOS                 | ClarkOS                                                   |
| ------------------------ | ----------------------- | --------------------------------------------------------- |
| **Execution Model**      | Request-response        | Continuous tick cycle                                     |
| **Memory Types**         | 1 (conversation)        | 5 (episodic, semantic, emotional, procedural, reflection) |
| **Memory Deduplication** | Single threshold (0.95) | Type-specific thresholds                                  |
| **Memory Relationships** | None                    | Bidirectional linking (7 types) *(Schema ready)*          |
| **Memory Consolidation** | None                    | Core memory clustering *(Schema ready)*                   |
| **State Model**          | Minimal                 | Mood, health, routine, volatility                         |
| **Time Awareness**       | None                    | Routine-based behavior (morning, day, evening, overnight) |
| **Backend**              | Custom adapters         | Convex serverless (real-time, transactional)              |

***

## Architecture Overview

ClarkOS implements a generative architecture where agents operate on continuous tick cycles independent of external interaction.

### Continuous Operation

Agents execute on configurable tick intervals (default 5 minutes). Each tick:

1. Loads current state and relevant memory context
2. Processes through the configured LLM
3. Updates internal state (mood, health, routine awareness)
4. Stores new memories with embeddings and metadata
5. Executes plugin hooks

### Memory Architecture

Five memory types model different aspects of cognition:

* **Episodic** - Specific events and experiences (0.92 dedup threshold)
* **Semantic** - Facts, concepts, learned information (0.95)
* **Emotional** - Affective associations with topics and entities (0.88)
* **Procedural** - Learned patterns, triggers, and responses (0.97)
* **Reflection** - Metacognitive insights about the agent's own state (0.90)

Memories include vector embeddings for semantic retrieval and deduplication.

### Terminal UI

The SDK includes a React Ink-based terminal UI for monitoring your agent:

```
┌─────────────────────────────────────────────┐
│  CLARK - Autonomous Agent                    │
│  Mood: curious | Health: 78 | Routine: day  │
├─────────────────────────────────────────────┤
│      ╭──────────╮                           │
│      │  ◉    ◉  │                           │
│      │    ──    │                           │
│      ╰──────────╯                           │
└─────────────────────────────────────────────┘
```

## Technical Stack

* **Runtime**: Node.js 18+ with TypeScript
* **Backend**: Convex serverless (real-time subscriptions, transactional mutations)
* **Embeddings**: Google Gemini (free tier) or OpenAI
* **LLM**: OpenRouter, OpenAI, Anthropic, or custom
* **UI**: React Ink (terminal-based)
* **Testing**: Jest (179 tests)

***

## Quick Start

```bash theme={null}
git clone https://github.com/clarkOS/clark my-agent
cd my-agent/example/convex
npm install
npm run demo  # No API keys needed
```

Or with full configuration:

```bash theme={null}
cp .env.example .env.local
# Edit .env.local with your API keys
npm run dev
```

***

## Documentation

<CardGroup cols={2}>
  <Card title="Quickstart" href="/quickstart">
    Deploy your first agent in 5 minutes
  </Card>

  <Card title="Core Concepts" href="/concepts/agents">
    Understand the architecture
  </Card>

  <Card title="Memory System" href="/concepts/memory">
    Multi-layered cognitive memory
  </Card>

  <Card title="Build Plugins" href="/guides/custom-plugins">
    Extend your agent
  </Card>
</CardGroup>

***

## Community

<CardGroup cols={2}>
  <Card title="GitHub" icon="github" href="https://github.com/clarkOS/clark">
    Star and contribute
  </Card>

  <Card title="X / Twitter" icon="twitter" href="https://x.com/clarkwiki">
    Follow @clarkwiki
  </Card>
</CardGroup>