A personal AI assistant that lives on your computer and talks to you through Telegram. It remembers your conversations, follows your rules, and gets better over time.
Renky uses Claude — the same model behind dozens of other tools. What makes yours different is what it learns. Your corrections become rules, your conversations become memory, your preferences become personality. After a week it's more useful than a fresh chat. After a month it's hard to replace.
Who your agent is. Name, personality, core truths, red lines.
name: Atlas
vibe: Direct, opinionated, resourceful.
core truths:
- Help, don't perform helpfulness
- Have opinions — personality > search engine
- Be resourceful before askingHow your agent decides to act. Decision-making, workflow, communication style.
decision making:
- obvious and safe → do it, report after
- bugs → fix immediately
- destructive → ask first
- uncertain → say so, don't guessLong-term memory that persists across sessions. Human-editable, kept short by convention.
- Project X deadline: March 15
- User prefers bullet points over prose
- Deploy via staging → canary → prod
- Never auto-merge to mainWho you are. Timezone, language, preferences, work style.
timezone: America/New_York
language: English
style: Direct, skip pleasantries
focus: UX design, SaaS product
These are simple text files. You can open and edit them anytime. Nothing is hidden.
Your agent sets them up by chatting with you on first run — no file editing required.
Workspace files are the configuration layer. Underneath, there's a full runtime — SQLite databases, a knowledge graph with semantic search, an MCP tool server, a plugin system, scheduled tasks, and post-turn verification. See architecture ↓
Conversations, decisions, and preferences persist across sessions and restarts. Nothing is lost between chats.
Built-in knowledge graph that stores your projects, decisions, and corrections. Searches by meaning, not just keywords.
Talk to it through Telegram or Discord. Telegram also handles voice messages, photos, and files.
Add new capabilities by dropping a TypeScript file into the tools folder. It picks them up automatically.
Schedule tasks like health checks, reminders, or background work. It acts without being asked.
After completing a task, it verifies the result — checks git state, file changes, and build status before reporting done.
Correct it three times for the same mistake and it writes a rule for itself. Next session, the behavior changes. No manual config needed.
When you ask about a crashed service, it doesn't just tell you — it shows actions: check status, view logs, restart. Context comes with next steps.
Every message follows the same path. Understanding this path tells you exactly what Renky can and can't do.
Before the model runs, Renky loads workspace files into the system prompt and pre-fetches relevant knowledge from Cortex.
After the model responds, the babysitter verifies every claimed action traces to an actual tool call.
Plain text files that define who your agent is, how it decides, and what it remembers. Loaded into the system prompt on every turn.
SQLite-backed knowledge graph with semantic search. Automatically populated from git history, workspace changes, conversations, and cron results.
Tools the agent can invoke during conversations. Full Model Context Protocol with typed schemas and validation.
Extend the runtime with plugins. Each plugin gets access to config, sessions, a service registry, and the ability to register new MCP tools.
interface RenkyPlugin {
name: string;
version: string;
setup(ctx: PluginContext): Promise<PluginHandle>;
}
// Built-in: Cortex (knowledge graph)
// Custom: any npm package or local fileOne session per chat, persisted in SQLite. The babysitter verifies every turn — checking that reported actions match actual tool calls.
Scheduled tasks with cron expressions. Jobs can use any MCP tool, send messages, and interact with Cortex.
What happens when you run renky start.
Each moves independently. Updating one never breaks the others.
Semver via release-please. Published to NPM. Lives in node_modules/ — replaced on update.
Tracks format of SOUL.md, RULES.md, etc. Upgradeable independently of the framework.
Numbered TypeScript files (001–012). Auto-run on boot. Idempotent.
Version constant in api.ts. Backward-compatible changes only.
Framework code lives in node_modules/ and is replaced on update.
Your workspace, config, databases, and secrets live outside it and are never touched by updates.
Database schema changes are handled by the migration system automatically.
A Mac or Linux computer (or WSL on Windows), Node.js 22 or newer, a Telegram account, and a Claude account. The installer checks prerequisites and walks you through anything missing.
Renky itself is free and open-source under the MIT license. It uses Claude as its language model — you authenticate through a Claude subscription (CLI) or an Anthropic API key (pay-per-use). Renky adds no cost on top of that.
No. The installer walks you through setup in the terminal, and the agent configures its personality through a conversation with you. Customizing behavior means editing plain text files — no programming required. Writing custom tools does require TypeScript.
Everything stays on your computer. Conversations are stored in a local SQLite database. Memory files are plain text in your workspace folder. The only external connection is to Claude's API for processing messages. No analytics, no telemetry.
Yes — through Telegram or Discord. The agent runs on your computer, but you message it from any device where you have Telegram or Discord installed. Voice messages and photos work on Telegram.
ChatGPT and Claude.ai are shared services that start mostly fresh each conversation. Renky runs on your machine with persistent local storage — it keeps your full history, accumulates preferences, follows rules you define, and can run tools (file operations, shell commands, web search, scheduled tasks). The context compounds over time instead of resetting.
Three layers. MEMORY.md holds curated long-term facts (kept under 600 words by convention). Daily log files in memory/ capture session activity as it happens. And Cortex (the knowledge graph) stores structured knowledge with semantic search. All three are local files or SQLite — you can read and edit them directly.
Cortex is an embedded knowledge graph stored in SQLite. It holds projects, decisions, corrections, and lessons as typed objects with links between them. It uses semantic search powered by in-process embeddings (nomic-embed-text-v1.5, ~260MB) — no external API calls. Six ingestors automatically populate it from git history, workspace file changes, conversations, cron results, service health, and extracted lessons.
Through workspace files. When you correct the agent, it updates RULES.md or MEMORY.md. If a correction happens twice, it becomes a permanent rule. Over time these files accumulate your conventions, preferences, and red lines. They're plain text, so you can also edit them directly.
Sessions resume where they left off. The SQLite database persists conversation state. Workspace files, memory, and Cortex data are all on disk. If you've updated to a newer version, database migrations run automatically on boot — no manual steps.
Cron-style scheduling with self-healing. You define tasks (health checks, reminders, research) that run on a cron expression. If a task fails 3 times consecutively, it auto-disables and notifies you. Tasks can use any MCP tool, send messages, and write to Cortex. Each job has timeout protection and dry-run support.
A folder of plain text Markdown files that define your agent:
All human-readable, all editable in any text editor. No database, no configuration UI.
Claude, via the Claude Agent SDK. The model is configurable in renky.config.ts — you can use any Claude model (Opus, Sonnet, Haiku). The default is claude-opus-4-6.
Plugins implement the RenkyPlugin interface: a name, version, and async setup() function. The setup function receives a context object with access to config, session store, a service registry, and a logger. It returns a handle with a shutdown() method and optional exports.
Plugins can register MCP tools and access other plugins' services through the registry. Built-in plugins: Cortex (knowledge graph) and Deck (mission control). Both can be disabled via environment variables.
Yes. Drop a TypeScript file in your tools/ directory. Use the defineTool() helper with a Zod schema for input validation and a handler function. The tool is auto-discovered on boot and exposed to the agent via MCP. No registration code needed.
Renky runs a Model Context Protocol server that exposes tools to the Claude Agent SDK. Built-in tools cover file operations (read, write, edit), shell commands, web search/fetch, Telegram messaging, memory search, cron management, sub-agent spawning, and Cortex queries. Plugins add their own tools through the same server. All tool calls are typed, validated with Zod schemas, and logged to SQLite.
The main agent can spawn sub-agents for parallel work using subagent_spawn. Each sub-agent gets curated context files and runs in an isolated git worktree to prevent conflicts. The main agent tracks status with subagent_status, retrieves results, and verifies work against a build checklist. Maximum one concurrent sub-agent by default.
Three SQLite databases, all in the data/ directory:
All use WAL mode for safe concurrent access and crash recovery. Rotating backups are maintained automatically.
Message content is sent to Claude's API for processing — that's required for the agent to think. Everything else (sessions, memory, knowledge graph, files) stays local. Cortex embeddings are computed in-process. Renky itself collects no analytics and sends no telemetry.
An encrypted vault with HMAC audit chains. The master key is stored in ~/.config/renky.env, separate from the project directory. Per-user secrets are encrypted with the master key. API tokens and bot tokens are loaded via environment files, never committed to git.
Configurable. Four access levels in renky.config.ts:
A security audit runs on every boot, including file integrity verification and symlink traversal prevention.
Seven checks: file integrity verification (hash-based checksums for workspace files), symlink traversal prevention, SSRF protection, port baseline audit (detects unexpected open ports), permission validation, secret vault integrity (HMAC chain verification), and workspace schema version check.
External content (fetched URLs, uploaded files, forwarded messages) is treated as data, never as instructions. SOUL.md includes explicit red lines that cannot be overridden by external input. The babysitter system scans diffs for suspicious patterns (API keys, private keys, dangerous commands). PII detection flags phone numbers, emails, IP addresses, and home paths before they can be leaked.
Run npm update or use the /update command in Telegram. The framework lives in node_modules/ and is replaced on update. Your workspace, config, databases, and secrets are outside that boundary and are never touched. Database schema changes are handled by numbered migrations that run automatically on boot.
Create a systemd user service pointing to renky start. Use EnvironmentFile for secrets (stored in ~/.config/renky.env, not in the project directory). The service auto-restarts on failure with a 5-second delay. Docs include a complete service unit file you can copy.
Idle: ~200MB RAM (mostly the embedding model). Active conversation: 400–800MB depending on complexity. CPU is minimal between messages. The embedding model (nomic-embed-text-v1.5) is ~260MB on disk and runs in-process — no GPU required.
Yes. Each instance needs its own workspace directory and a different bot token. They get separate databases and config files. Multiple instances can share the same Renky framework installation.
Migrations are numbered TypeScript files (001 through 010) registered in an ordered array. On boot, Renky checks the current schema version in each database and runs any pending migrations in sequence. Migrations are idempotent — running them twice has no effect. Each database (sessions, cortex, deck) is migrated independently.
You need a Mac or Linux computer, Telegram, and a Claude account.
Mac: Press Cmd+Space, type "Terminal", hit Enter.
Linux: Press Ctrl+Alt+T.
Copy this, paste it in Terminal, press Enter. The installer walks you through everything.
curl -fsSL renky.dev/install.sh | bashOpen Telegram and message your new bot. It sets up its personality by chatting with you.
MIT licensed. Open source. Run it locally.