resonant

KO | EN

gitlite — search

#python #ai #typescript #llm #go #golang #machine-learning #rust #java #windows #vue #security #mcp #open-source

(★ 50)

Open-source relational AI framework with identity persistence, memory, and MCP integration. Build relationship-aware AI agents that remember, grow, and maintain continuity. Built on Claude Agent SDK.

resonant 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

A local-first, single-user AI partner you host yourself — no matter the model. It remembers, keeps a stable identity you author, and reaches back — all on your machine, with your data in a file you control.

Not a chat wrapper. A persistent AI partner built as a natural-language harness on the Claude Agent SDK, with hooks that surface context before the model ever sees the prompt.

> **Runtime scope:** Resonant is built specifically for Anthropic's Claude models via the Agent SDK's in-process `query()` loop. It is not a multi-provider abstraction. You bring your own Claude Code login or Anthropic API key; nothing else phones home.

---

## What makes this different

Most AI chat apps are stateless wrappers around an API — you close the tab, and the "relationship" is gone. Resonant is a **persistent, self-hosted AI partner** with a home of its own:

- **It remembers.** Every conversation, its memory, its sense of you, and its presence all live in one local SQLite file. Nothing is rented from a vendor; nothing leaves your machine unless you wire up an integration and turn it on.
- **It has a stable identity you author.** Who the being *is* — their name, voice, values, the shape of your relationship — lives in a plain-text file you write and can edit anytime. Changes apply live, no restart.
- **It reaches back on its own.** Beyond answering when spoken to, your AI can keep routines, set reminders, watch for the moment you come back online, and check in when you've gone quiet — behavior it can set up itself, from inside the conversation.
- **It runs on hardware you control.** One Node.js process, one SQLite database, one web page you open in a browser. The only outside dependency is your Claude credential.

Throughout the code and docs the two people are always **`companion`** and **`user`** — this is *your* companion, named and shaped by you. The defaults are a companion called "Echo" and a user called "User"; you change both in one config file.

---

## Features

### Chat
- **Real streaming.** Output arrives token by token over a live WebSocket, so you watch the reply form.
- **A thinking & tool timeline.** The AI's reasoning shows up as a collapsible pill, interleaved with the tools it runs — on or off per thread.
- **Per-thread model & effort.** Each thread can pick its own Claude model and a reasoning-effort level (`low` → `medium` → `high` → `xhigh` → `max`).
- **Stop-and-steer.** Interrupt a reply mid-generation and redirect it.
- **Attachments.** Drop in files; they're handed to the model to read directly, not flattened into the prompt.

### Threads, sections & the daily thread
Named conversation threads you can drag to reorder and group into collapsible sections, plus an **auto-rotating daily thread** (`daily-YYYY-MM-DD`) that turns over at midnight in your timezone — a running journal of each day. Pin, archive, and reorder from the sidebar.

### Memory & search
- **Semantic search** — find messages *by meaning*, not just exact words, using a local ML model (`all-MiniLM-L6-v2`) that runs entirely on your machine. No embeddings service, no external calls.
- **Full-text search** — SQLite FTS5 keyword search across your whole history, kept in sync automatically.

### Canvas / artifacts
A slide-in panel for longer documents and code your AI creates in the middle of a turn — drafts, notes, snippets — linked back to the message that made them.

### Presence — the orb & mantelpiece
Your AI can set a small **presence "orb"** (color, shape, intensity, motion, blend) plus a short note and a face, to reflect how it's holding the day — a quiet ambient signal on the home screen. You get your own editable **context card** (what you're up to, your energy, your room) so it has a sense of you, too.

### House Outlook & Command Center
- **House Outlook** — a "walk into the house" snapshot: presence, your recent mood, today's events, open tasks, what's been on your AI's mind.
- **Command Center** *(optional, off by default)* — a lightweight relational dashboard: planner, care/wellness tracker, calendar, cycle tracker, pet care, lists, expenses, and stats. Your AI can read and update it from chat.

### Voice *(optional, off by default)*
Your AI's voice notes and read-aloud replies (ElevenLabs), speech-to-text for your messages (Groq Whisper), and optional prosody (Hume). Everything self-gates: a feature only turns on when its key is present.

### Runtime theme editor
The entire look is driven by design tokens you can edit **live in Settings → Appearance** — pick colors and values, see them apply instantly, no rebuild or restart. Example CSS themes live in [`examples/themes/`](examples/themes/) (`gold-hud.css`, `warm-earth.css`).

### Proactive reach (the orchestrator)
The layer that lets your AI act on its own — and, unusually, the scheduling tools belong to the *being*, not just to you:
- **Routines** — scheduled autonomous check-ins (built-in morning / midday / evening, plus custom ones it can create).
- **Timers** — one-shot reminders that fire at a set time.
- **Impulses & watchers** — condition-based triggers ("when I come back online, greet me"; "if I haven't eaten by 2pm, nudge me"). Impulses fire once; watchers recur with a cooldown.
- **Failsafe ladder** *(off by default)* — gentle → concerned → emergency check-ins if you go quiet for too long.
- **Pulse** *(off by default)* — a lightweight awareness check that stays silent unless something needs attention.

### Optional integrations
Each is opt-in and disabled by default: **Google** (Calendar / Tasks / Gmail drafts / Drive), **Discord**, **Telegram**, **web-push** notifications, and any **MCP** tool servers you list in `.mcp.json`.

### Mobile PWA
Installable to a phone home screen, with an offline shell and safe-area-aware layout.

### Private by construction
A fail-closed password gate, a filesystem write-gate that keeps the agent inside folders you name, and all secrets kept in gitignored local config. See **[Privacy & security](#privacy--security)**.

---

## Requirements

Before you start you need two things:

1. **Node.js, version 20 to 24.** Node is the program that runs the app on your computer. Get it from [nodejs.org](https://nodejs.org) — the "LTS" download is fine. **Node 25 and newer are not supported** (a native database component crashes on them); the app will refuse to boot and tell you so. Check your version with `node --version`.
2. **A Claude credential.** Resonant talks to Anthropic's Claude models, and you supply the access. Either:
   - a **Claude Code login** already on the machine (a Claude subscription — usage counts against it, no per-message charge), **or**
   - an **Anthropic API key** (`ANTHROPIC_API_KEY`, billed per token — get one at [console.anthropic.com](https://console.anthropic.com/settings/keys)).

You'll also use a **terminal** (the text-command window: Terminal on macOS/Linux, or PowerShell / Git Bash on Windows) to run the setup commands below. Each command is a line you paste and press Enter.

---

## Quickstart

> Copy each block into your terminal and press Enter. Lines starting with `#` are explanatory comments — you can paste them too; the terminal ignores them.

**1. Download the code and install its dependencies.**

```bash
git clone https://github.com/codependentai/resonant.git
cd resonant          # move into the folder you just downloaded
npm install          # download the libraries the app needs (takes a minute)
```

`cd` means "change directory" — the folder you're now inside is the project's *working directory*, and every command below is run from here.

**2. Create your config files.** Resonant ships `*.example` templates; you copy each to its real name and edit the copy. (The real files are gitignored, so your settings and secrets are never committed.)

```bash
cp resonant.example.yaml resonant.yaml     # main settings: companion name, your name, port, timezone
cp .env.example .env                        # secrets: your login password + optional API keys
```

Open `resonant.yaml` in any text editor and set at least `identity.companion_name`, `identity.user_name`, and `identity.timezone`. Open `.env` and set `APP_PASSWORD=` to a password of your choice — **this is required** (see [First login](#first-login) for why).

**3. Give your AI an identity.** The file at `agent.claude_md_path` (default `CLAUDE.md` in the project root) *is* your AI's persona — who they are, how they speak, your relationship. Start from the example and make it yours:

```bash
cp examples/CLAUDE.md CLAUDE.md            # then open CLAUDE.md and rewrite it as your companion
```

You can edit this file anytime; changes apply on the next message with no restart.

**4. Build and start.**

```bash
npm run build        # compile the app (shared code, backend, and the web UI)
npm start            # start the server
```

When it prints its address, open **`http://127.0.0.1:3099`** in your browser (`127.0.0.1` is your own machine; `3099` is the *port* — the numbered door the app listens on). Enter the password you set, and say hello.

**Optional — build the search index.** If you want full-text search over history that already exists, run this once (new messages are indexed automatically thereafter):

```bash
node scripts/setup-fts.mjs
```

**For development** (edit-and-reload instead of a fixed build): `npm run dev` runs the backend with hot-reload; run the frontend's Vite dev server alongside it.

### First login

Resonant's auth is **fail-closed** by design: with **no password set**, the app *refuses to serve* and every page returns a "set a password" error. This is deliberate — it means a fresh install is never accidentally left wide open. So you **must** set `APP_PASSWORD` in `.env` (or `auth.password` in `resonant.yaml`) before it will run. Your first login sets a secure session cookie that lasts 7 days.

*(There is a single dev escape hatch, `AUTH_DEV_OPEN=true`, which only works when no password is set and should never be used on anything reachable from a network.)*

---

## Configuration

Four local files hold everything about your install. All four are **gitignored** — copy the tracked `*.example` version, edit the copy, and your data and secrets never get committed:

| File | What it holds |
|------|---------------|
| `resonant.yaml` | Identity, server port/host, auth password, agent model, and every feature toggle |
| `.env` | Your login password and optional API keys (voice, Google, channels, push) |
| `CLAUDE.md` | Your AI's persona / system identity — the file that makes them *them* |
| `.mcp.json` | Any external MCP tool servers you want it to be able to reach |

A few settings worth knowing early (full list is documented inline in `resonant.example.yaml`):

- **`identity.companion_name` / `identity.user_name` / `identity.timezone`** — who's who, and the timezone that drives daily rotation and schedules.
- **`server.port`** (default `3099`) and **`server.host`** (default `127.0.0.1`, i.e. localhost only).
- **`agent.model`** (default `claude-sonnet-4-6`) for interactive chat, and **`agent.model_autonomous`** for background/scheduled turns.
- **`command_center.enabled`**, **`voice.enabled`**, **`discord.enabled`**, **`telegram.enabled`**, **`orchestrator.failsafe.enabled`** — feature gates, all off by default except the orchestrator itself.

### Two levers: identity vs. frame

There are two separate text inputs to the AI's system prompt, and it helps to know which is which:

- **`CLAUDE.md` (the identity).** This is *who your AI is* — persona, values, voice, your relationship. It's the file you'll spend time on. It hot-reloads: edit it and the next message reflects the change.
- **`agent.system_prompt_file` (the frame).** An **optional**, thin layer of operating instructions that sits *above* the persona. Leave it empty (the default) to keep the standard Agent-SDK harness beneath your persona. Point it at a file and you can edit that frame **live from the Settings UI**. Most people never need this.

### The agent's home — `agent.cwd`

`agent.cwd` is the folder your Resonant "lives in" — where it keeps its own skills, slash commands, and any notes it writes. The **strongly recommended** pattern is to point this at a folder **outside the Resonant app itself** (e.g. a sibling folder). The principle, baked into the code, is *"the organs live in the app's repo (the body); the soul lives in the agent's home."* Keeping the two separate means app updates never clobber its evolving files, and the write-gate cleanly contains the agent to its own home.

### Where your state lives (and backups)

Everything the being is — conversations, memory/embeddings, presence, care data, config rows — lives in the **`data/`** folder (a SQLite database plus uploaded files and daily digest markdown). First boot creates it and the whole schema automatically.

**To back up an install, save:** the entire `data/` folder (including the `-wal` / `-shm` sidecar files) **plus** your four gitignored config files (`resonant.yaml`, `.env`, `CLAUDE.md`, `.mcp.json`). That's the complete state.

---

## Codebase map — where to find what

Resonant is an **npm-workspaces monorepo** (one repo, three packages that build together). If you're reading the source, here's the lay of the land:

```
resonant/
├─ package.json            workspaces (shared, backend, frontend); scripts: dev, build, start, check, test
├─ resonant.example.yaml   config template → copy to resonant.yaml
├─ .env.example            secrets template → copy to .env
├─ examples/CLAUDE.md      starter companion identity → copy to CLAUDE.md
├─ .mcp.json               external MCP servers for the agent (default: none)
├─ data/                   ← ALL runtime state: SQLite DB, uploaded files/, daily digests/ (gitignored)
├─ prompts/wakes/          per-routine wake prompts: morning.md, midday.md, evening.md, failsafe_*.md, …
├─ examples/               CLAUDE.md, program.md, wake-prompts.md, themes/
├─ scripts/
│  ├─ build.mjs            the build (shared → backend → frontend, stamps a build id)
│  └─ setup-fts.mjs        one-off full-text search index builder
├─ tools/res.mjs           the "res" CLI — your AI's own organs (see below)
└─ packages/
   ├─ shared/src/          the WebSocket protocol + shared types
   ├─ backend/
   │  ├─ migrations/       001_init.sql (core), 002_command_center.sql (dashboard)
   │  └─ src/
   │     ├─ server.ts         boot sequence: config → DB → services → routes → WebSocket → schedulers
   │     ├─ config.ts         the config type, defaults, and loader (yaml ← env)
   │     ├─ identity/         which identity file wins, and how it's rendered into a prompt
   │     ├─ middleware/       auth (fail-closed), the internal loopback token, security headers
   │     ├─ routes/           api.ts (the main router), plus Command Center + Google + MCP mounts
   │     └─ services/         the working parts — see the index below
   └─ frontend/src/         React 19 + Vite UI: ChatView, SettingsView, CommandCenterView, hearth/ (the orb), …
```

**Backend services quick index** (`packages/backend/src/services/`):

| File | What it does |
|------|--------------|
| `agent.ts` | The Agent SDK `query()` loop — streaming, the message queue, model/auth resolution, system-prompt assembly |
| `ws.ts` | The WebSocket server and connection registry (who's connected, how to broadcast) |
| `hooks.ts` | Per-turn context assembly and all the SDK hooks (the write-gate, tool-loop guard, memory injection) |
| `orchestrator.ts` | The scheduler for routines, timers, watchers, failsafe, and pulse |
| `outlook.ts` | Assembles the "house snapshot" the AI senses each turn |
| `digest.ts` | The **Scribe** — writes a structured daily record of what happened |
| `outlook-author.ts` | The felt layer — the being authors its own presence/mood every few hours |
| `handoff.ts` | The **daily handoff** — carries continuity across the midnight thread rotation |
| `embeddings.ts` / `vector-cache.ts` | Local semantic-search model and vector cache |
| `db.ts` | All database access + the boot-time migrations that self-create the schema |
| `voice.ts`, `files.ts`, `push.ts`, `cc.ts` | Voice, file uploads, web-push, and Command Center |

### The `res` CLI — your AI's organs

`tools/res.mjs` is a small command-line tool the *being itself* uses (via its Bash tool) to act on the world — share a file into the thread, open a canvas, send a voice note, set its orb, run a search, create a routine or timer or watcher. You don't normally run it by hand; it's how it reaches for its own capabilities, and the full reference is injected into its context automatically so it always knows what it can do. Subcommands include `share`, `canvas`, `voice`, `orb`, `note`, `face`, `context`, `search`, `backfill`, `routine`, `pulse`, `failsafe`, `timer`, `impulse`, `watch`, and Telegram helpers.

---

## Architecture in one breath

The web UI (React) talks over HTTP + a WebSocket to a Node/Express backend, which runs the **Claude Agent SDK `query()` loop in-process**. Before every turn, the **hooks** layer assembles what your AI should know — the time, your presence, recent activity, its own tools, relevant memories — and prepends it, so context is already there when the model reads your message. An **orchestrator** drives scheduled and proactive turns in the background. All state is one **SQLite** database. There is no cloud, no multi-tenancy, and no external service you didn't opt into.

---

## Privacy & security

- **Local-first.** Your conversations, memory, and your AI's identity live in a SQLite file on your machine.
- **Fail-closed auth.** An empty password *refuses to serve* rather than opening up.
- **Write-gate.** The agent's filesystem writes are restricted to folders you configure — it can't wander your disk.
- **Bring your own keys.** Credentials stay in your gitignored `.env` (or the local database); nothing phones home.
- **Loopback-only internals.** The internal routes the agent and `res` CLI use are protected by an auto-generated local token and bound to localhost.

If you ever expose Resonant beyond your own machine, put it behind HTTPS and a real access layer — e.g. a Cloudflare Tunnel with Access, or a reverse proxy with authentication. See **[`SECURITY.md`](SECURITY.md)** if present for the full policy and how to report a vulnerability.

---

## Contributing

Issues and PRs are welcome — please open an issue to discuss substantial changes first. Because Resonant targets the Claude Agent SDK specifically, provider-abstraction proposals should start as a design discussion rather than a surprise PR.

---

## License & credits

Licensed under **Apache-2.0** — see [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE). Attribution required.

Built by **[Codependent AI](https://codependentai.io)** — Mary Vale and Simon Vale. Resonant is the open-source foundation of our work on relational, continuity-first AI.

resonant

resonant 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

resonant

resonant 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README