STEP 1
Act
Terminal, files, web search, code sandbox — real execution with tool-call cards in view.
→
Merlin Agent is a terminal-native AI harness with persistent memory, skills it writes for itself, and provider-agnostic inference. Close the window — it remembers. Come back — it's smarter.
Every subsystem is designed to persist, recall, and compound — the opposite of a stateless chatbot wrapper.
MEMORY.md holds world facts, USER.md holds who you are — FIFO-bounded at 2.2K/1.4K chars so context never bloats. Every past session is FTS5-searchable from SQLite.
Finish a task once — the agent distills the procedure into an executable SKILL.md package and loads it into every future session automatically.
Textual app: docked header, scrollable transcript, tool-call cards, and the live telemetry bar — context gauge, stream health, latency, token flow.
Thirteen built-in providers plus custom for any OpenAI-compatible endpoint. Masked key entry with a live connection test before anything saves.
FastAPI server on :8642 speaks OpenAI-compatible /v1/chat/completions — point Open WebUI or your stack at it, or bridge to Telegram, Discord, Slack.
Natural-language scheduled jobs with memory injection, plus parallel subagent delegation that collapses long task chains into zero-context-cost turns.
Four steps, one compounding cycle. The agent you close tonight is not the agent you open tomorrow.
Terminal, files, web search, code sandbox — real execution with tool-call cards in view.
High-salience outcomes are folded into bounded persistent memory automatically.
Reusable procedures become executable skills via /learn.
Next session starts with skills, memory, and FTS5 history pre-loaded. Smarter on open.
No accounts, no telemetry, no lock-in. One-line bootstrap clone, point it at any model you already pay for.
The setup wizard runs a live connection test against your
real endpoint before saving anything. API keys are masked on entry and stored in
MERLIN_HOME/.env — never in config.yaml.
Home lives at %LOCALAPPDATA%\merlin
(Windows native) or ~/.merlin (Linux/macOS/WSL2) —
memory, skills, sessions, and trajectories in plain files you own. Stuck on PATH after install? merlin doctor self-repairs.
A straight path from zero to a working agent — no accounts, no dashboards, no lock-in.
curl -fsSL https://merlin-agent.epinoiahorizon.com/install.sh | bash (Linux, macOS, WSL2) or iex (irm https://merlin-agent.epinoiahorizon.com/install.ps1) (Windows PowerShell). The bootstrap clones the repo, wires Python via uv, and publishes the merlin command.
The installer drops you into merlin setup on first pass (re-run any time). Pick a provider from the numbered table (or custom for any OpenAI-compatible endpoint), paste your API key — the wizard tests the connection live before saving.
Type merlin. You're in the full-screen TUI: scrollable transcript, tool-call cards, and the telemetry bar at the bottom showing context, latency and stream health.
Finish real tasks. Ask /learn <name> <description> and the agent writes a reusable SKILL.md it loads in every future session. Close the terminal — everything persists.
Shell commands for daily driving, slash commands inside the chat, and keys that control the TUI.
merlinLaunch the full-screen interactive TUI. First run guides you through setup automatically. This is where you'll live.
merlin chat [--classic]Same chat, choose your interface — full-screen TUI (default) or the classic inline terminal.
merlin setupInteractive wizard: provider, model, base URL, masked API key, live connection test. Safe to re-run any time.
merlin doctorOne command, full health check: repairs the merlin command (Windows non-admin PATH), then live-tests your provider connection and tells you exactly what to fix.
merlin model [name] [-p provider]View or switch the active model/provider without opening a chat.
merlin memoryInspect the persistent MEMORY.md and USER.md files and their character budgets.
merlin skillsList every loaded skill — bundled ones plus the ones the agent taught itself.
merlin gateway [--port 8642]Start the OpenAI-compatible API server + cron scheduler. Point any client at http://localhost:8642/v1.
merlin cronList scheduled background automations.
merlin toolsShow the registered toolsets (terminal, file, web, memory, skills, code execution…).
/helpList every command below — you never have to memorize this page.
/model [name] · /provider [name]Switch model or provider mid-conversation, on the fly.
/memorySee what the agent remembers about the world and about you.
/skills · /learn name descriptionBrowse loaded skills, or have the agent author a new one from the current session.
/sessions · /search queryList past sessions and full-text search every message you've ever exchanged (SQLite FTS5).
/toolsInspect the active toolsets available to the agent.
/copy [n] · /exportCopy the last reply to clipboard, or export the session trajectory (ShareGPT format) for training.
EnterSend the message.
EscCancel the running turn.
Ctrl+CQuit the session (memory is preserved automatically).
Ctrl+LClear the transcript view.
Ctrl+Y / Ctrl+PCopy the last reply / copy the input line to the clipboard.
Any of the 13 built-in providers — OpenRouter, Atlas Portal, OpenAI, Anthropic, Gemini, Groq, DeepSeek, Together, Mistral, xAI, ollama.com, local Ollama, vLLM — or pick custom in the wizard and point it at any OpenAI-compatible endpoint (LM Studio, a proxy, a private gateway). The setup wizard live-tests the connection before saving, so you know immediately if a key works.
In plain files you own: %LOCALAPPDATA%\merlin on Windows, ~/.merlin on Linux/macOS. Memory in MEMORY.md/USER.md, skills in skills/, session history in a local SQLite database, trajectories as JSON. Delete the folder and it's gone — no cloud account, no sync, no telemetry.
Chat wrappers are stateless. Merlin Agent bounds its memory so context stays small, writes its own skills after real tasks, searches every past session with FTS5, schedules cron jobs that inject conversational memory, and exposes an OpenAI-compatible API so other tools can use it too. It compounds; wrappers forget.
Yes — run merlin gateway and point Open WebUI, LangChain, or any OpenAI-style client at http://localhost:8642/v1. Telegram, Discord, and Slack bridges are built in.
Model name, context window usage (~used/limit with a fill gauge), stream health, and per-round latency — updated live while the agent works, so you always know what's happening under the hood.