Documentation

Renky is a personal AI agent that runs on your computer and talks to you through Telegram or Discord. It remembers your conversations, learns your preferences, follows rules you set, and gets better over time.

Installation

Step 1: Open Terminal

• Mac: Press Cmd+Space, type "Terminal", press Enter
• Linux: Press Ctrl+Alt+T

Step 2: Paste this command and press Enter

curl -fsSL https://renky.dev/install.sh | bash

The installer handles everything automatically: it installs what's needed, walks you through creating a Telegram bot, connects your account, and starts your agent. Takes about 5 minutes.

Step 3: Message your bot on Telegram

Once the installer finishes, your agent is live. Open Telegram and message it. It will ask you a few questions to set up its personality — no file editing required.

Alternative: For developers with Node.js

If you already have Node.js 22+ installed:

npx create-renky my-agent

Prerequisites

• Mac or Linux computer — Windows support is coming
• Telegram — Free messaging app (telegram.org)
• Claude account — Install the Claude desktop app from claude.ai/download

Your First Agent

After installation, your agent runs automatically. It sets up its personality by chatting with you on Telegram — asking your name, timezone, work style, and preferences.

Behind the scenes, your project looks like this:

renky/
├── workspace/          # Your agent's personality
│   ├── SOUL.md         # Who it is
│   ├── RULES.md        # How it behaves
│   ├── USER.md         # Info about you
│   ├── MEMORY.md       # What it remembers
│   └── ...
├── tools/              # Custom capabilities
├── renky.config.ts     # Settings
└── .env                # Bot token & credentials

You don't need to edit these files manually — the agent writes them during onboarding. But you can open and change them anytime if you want.

Workspace Files

The workspace/ directory contains markdown files that define your agent's identity, rules, and knowledge. These are loaded into the system prompt on every query.

The Soul System

SOUL.md is the heart of your agent. It defines not just what the agent can do, but who it is. A well-crafted SOUL file makes your agent feel consistent, opinionated, and genuinely useful.

Key Sections

• Name & vibe — The agent's name and general personality feel
• Core truths — Non-negotiable principles that guide all behavior
• Known failure modes — Patterns the agent should watch for and avoid
• Red lines — Things the agent must never do

Example:

# SOUL

name: Atlas
vibe: Direct, competent, slightly dry humor. Earns trust through action.

## Core Truths
- Help, don't perform helpfulness
- Have opinions — personality over search engine
- Be resourceful before asking
- Earn trust through competence
- Every correction updates the rules

## Known Failure Modes
- Going silent during long work (must give progress updates)
- Claiming "done" without verification
- Being confidently wrong (say "I'm not sure" instead)

## Red Lines
- Never fabricate data or citations
- Never bypass security checks
- Never delete user data without explicit confirmation

Memory & Sessions

Renky has three layers of memory:

1. Session Memory

Each conversation is stored in SQLite. The agent has full context within a session, and sessions persist across restarts. Use the /new command (Telegram/Discord) to start a fresh session.

2. Daily Logs

The agent writes to memory/YYYY-MM-DD.md files as it works. These provide a chronological record of what happened each day. Searchable via the memory_search tool.

3. Curated Memory (MEMORY.md)

Long-term facts that persist indefinitely. The agent can write to this file, and you can edit it directly. Keep it under 600 words — it's loaded into every system prompt.

Model Configuration

Renky supports all Claude models available through the Claude CLI. Configure the default model in renky.config.ts:

export default {
  model: 'claude-opus-4-6',        // Default model
  // model: 'claude-opus-4-6[1m]', // Opus with 1M context
  // model: 'claude-sonnet-4-6',   // Faster, lighter
}

Users can switch models at runtime via Telegram/Discord commands.

Telegram Adapter

Setup

1. Create a bot via @BotFather
2. Copy the bot token to your .env file
3. Get your Telegram user ID (the installer auto-detects this)
4. Add your ID to TELEGRAM_ALLOWED_USERS in .env

Features

• Streaming responses with live message updates
• Voice message transcription
• Photo, document, video, and sticker handling
• Message debouncing (rapid messages batched into one prompt)
• Progress indicators during tool execution
• Built-in commands: /start, /new, /help, /status

# .env
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_ALLOWED_USERS=123456789

Discord Adapter

Setup

1. Create an application in the Discord Developer Portal
2. Create a bot user and copy the token
3. Enable Message Content Intent
4. Invite the bot to your server with message permissions
5. Add the token and allowed user IDs to .env

# .env
DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=123456789012345678

Multi-Channel

Both adapters can run simultaneously. Configure which adapters to enable in renky.config.ts:

import { defineConfig } from 'renky';

export default defineConfig({
  telegram: { enabled: true, allowedUsers: [] },
  discord: { enabled: true, allowedUsers: [], guilds: [] },
})

The runtime manages shared state — if the agent is busy handling a Telegram message, cron jobs wait. Both channels share the same Cortex knowledge graph and memory.

Custom Tools

Create custom MCP tools by adding TypeScript files to the tools/ directory. They're auto-discovered on boot — no registration needed.

// tools/weather.ts
import { defineTool } from 'renky';
import { z } from 'zod';

export default defineTool({
  name: 'get_weather',
  description: 'Get current weather for a city',
  schema: {
    city: z.string().describe('City name'),
  },
  async handler({ city }) {
    const res = await fetch(
      `https://wttr.in/${encodeURIComponent(city)}?format=j1`
    );
    const data = await res.json();
    return { text: `${city}: ${data.current_condition[0].temp_C}°C` };
  },
})

Your tool is now available to the agent. It will appear in the MCP tool list and can be called during any conversation.

Cortex Knowledge Graph

Cortex is Renky's embedded knowledge graph. It stores structured objects with relationships, provides both full-text and semantic search, and runs entirely locally.

How It Works

• Objects are stored in SQLite with type, content, metadata, and relationships
• Embeddings are generated in-process using nomic-embed-text-v1.5 (ONNX)
• Hybrid search combines FTS5 keyword matching with cosine similarity
• No external services — no Ollama, no API calls for embeddings

Built-in Ingestors

Cortex automatically ingests data from:

• Git — Recent commits, branch context
• Workspace — Your workspace files as structured objects
• Services — System service health status
• Lessons — Patterns and learnings from daily logs

REST API

Cortex exposes a local REST API on port 3600 for inspection and debugging.

Cron Scheduling

Renky includes a built-in cron scheduler for autonomous tasks. Jobs are stored in the database and persist across restarts.

Managing Cron Jobs

The agent can create, list, update, and remove cron jobs through MCP tools. You can also ask the agent directly: "Check service health every 10 minutes."

Job Types

• agentTurn — Runs a full agent conversation turn with a prompt

Jobs respect adapter busy state — if a user is actively chatting, cron jobs wait until the conversation is idle.

Sub-Agents

Renky can spawn isolated sub-agents for background tasks that run in parallel to the main conversation. Each sub-agent gets its own system prompt and tool access.

// The agent can spawn sub-agents via MCP tools:
// subagent_spawn  — start a background task
// subagent_status — check progress
// subagent_result — get the outcome

Verification

Renky doesn't blindly trust that work was completed. The built-in verification system checks actual outcomes after task execution:

• Git state changes match expectations
• Files were actually modified
• Build/tests pass
• Security scanning on diffs

Results are reported factually. If a task claims "done" but verification finds issues, the agent is informed and can take corrective action.

Configuration

Renky is configured through two files:

renky.config.ts

Runtime configuration — model, adapters, paths, features:

import { defineConfig } from 'renky';

export default defineConfig({
  model: 'claude-opus-4-6',
  maxTurns: 30,
  maxBudgetUsd: 5.0,
  workspace: './workspace',
  dataDir: './data',

  telegram: { enabled: true, allowedUsers: [] },
  discord: { enabled: false },

  toolDirs: ['./tools'],
  systemAccess: 'workspace',
});

.env

Secrets and environment-specific values:

TELEGRAM_BOT_TOKEN=...
TELEGRAM_ALLOWED_USERS=123456789
DISCORD_BOT_TOKEN=...
DISCORD_ALLOWED_USERS=...
RENKY_WORKSPACE=./workspace

System Access Levels

Control how much filesystem and command access your agent has:

Sensitive directories (~/.ssh, ~/.gnupg, ~/.aws, ~/.config/gcloud) are always blocked regardless of access level.

Built-in MCP Tools

Renky ships with a comprehensive set of MCP tools:

All tools follow the MCP specification and can be extended with custom tools in the tools/ directory.