Installation

git clone https://github.com/clarkOS/clark my-agent
cd my-agent/example/convex
npm install

npm run doctor

npm run demo

cp .env.example .env.local

# Required for full mode
CONVEX_URL=https://your-project.convex.cloud
OPENROUTER_KEY=your-openrouter-api-key
GEMINI_API_KEY=your-gemini-key

# Optional - auth tokens
TICK_TOKEN=secure-random-token
WRITE_TOKEN=secure-random-token

clark/
├── README.md
├── docs/                    # Audit documentation
├── scripts/
│   └── doctor.js            # Preflight validation
└── example/
    └── convex/              # Reference implementation
        ├── .env.example     # Environment template
        ├── package.json
        ├── convex/          # Convex backend
        │   ├── schema.ts    # Database schema
        │   ├── http.ts      # HTTP endpoints
        │   ├── state.ts     # State queries/mutations
        │   ├── memories.ts  # Memory operations
        │   ├── knowledge.ts # Knowledge operations
        │   └── logs.ts      # Logging
        ├── src/
        │   ├── cli.tsx      # CLI entry point
        │   ├── core/        # Agent runtime, tick system
        │   ├── memory/      # Memory store, deduplication
        │   ├── knowledge/   # Knowledge base
        │   ├── plugins/     # Plugin system
        │   ├── llm/         # LLM & embedding clients
        │   ├── services/    # Background services
        │   ├── templates/   # Prompt templates
        │   └── ui/          # Terminal UI (Ink + React)
        └── tests/           # Jest tests (179 total)

npm run dev

# Health check
curl http://localhost:3001/health

# Expected response:
# {"ok":true,"service":"clark-agent","now":...,"lastTick":...}

# Agent state
curl http://localhost:3001/state

npm test

# Install Convex CLI
npm install -g convex

# Initialize new project
npx convex init

# Start dev server
npx convex dev