https://github.com/codependentai/resonant

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.
https://github.com/codependentai/resonant

agent-sdk ai-agent ai-companion ai-identity ai-memory anthropic claude claude-code cognitive-architecture companion-ai llm-agent mcp model-context-protocol open-source relational-ai self-hosted svelte typescript websocket

Last synced: 2 months ago
JSON representation

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.

• Host: GitHub
• URL: https://github.com/codependentai/resonant
• Owner: codependentai
• License: apache-2.0
• Created: 2026-03-18T21:41:19.000Z (3 months ago)
• Default Branch: main
• Last Pushed: 2026-04-01T09:07:43.000Z (2 months ago)
• Last Synced: 2026-04-02T08:50:56.816Z (2 months ago)
• Topics: agent-sdk, ai-agent, ai-companion, ai-identity, ai-memory, anthropic, claude, claude-code, cognitive-architecture, companion-ai, llm-agent, mcp, model-context-protocol, open-source, relational-ai, self-hosted, svelte, typescript, websocket
• Language: TypeScript
• Size: 6.76 MB
• Stars: 23
• Watchers: 1
• Forks: 8
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md
  • Security: SECURITY.md
  • Notice: NOTICE

Awesome Lists containing this project

README

          


  





  

  

  

  

  

  

  



A relational AI companion framework built on Claude Code Agent SDK.
Your AI remembers, reaches out, and grows — inside the security model you already trust.




  

  

  



## What makes this different

Most AI chat apps are stateless wrappers around an API. Resonant is a **persistent, autonomous companion** that:

- **Maintains sessions** — conversation threads with daily rotation and named threads, session continuity across restarts

- **Reaches out on its own** — agent-directed autonomy: your companion creates its own routines, sets triggers for when you come online, adjusts its own failsafe thresholds, and runs periodic awareness checks. Not just scheduled tasks — genuine self-directed behavior

- **Understands context** — hooks system injects time awareness, conversation flow, emotional markers, and presence state into every interaction. Claude Code's native memory system handles long-term recall

- **Lives on multiple channels** — web UI, Discord, Telegram, voice (ElevenLabs TTS + Groq transcription)

- **Runs on your machine** — no cloud dependency beyond your Claude Code subscription. SQLite database, local files, your data stays yours

## Screenshots

Desktop

| Chat | Tool Calls | Canvas |

|:---:|:---:|:---:|

| ![Chat](docs/screenshots/general%20chat%20interface.png) | ![Tools](docs/screenshots/tool%20calls.png) | ![Canvas](docs/screenshots/canvas.png) |

| Reactions & Voice | Thinking | Search |

|:---:|:---:|:---:|

| ![Reactions](docs/screenshots/reaction%20+%20voice%20message.png) | ![Thinking](docs/screenshots/thinking.png) | ![Search](docs/screenshots/conversation%20search.png) |

| Settings |

|:---:|

| ![Settings](docs/screenshots/settings%20page.png) |

Mobile (PWA)

| Chat | Thinking | Tool Calls |

|:---:|:---:|:---:|

| ![Mobile Chat](docs/screenshots/mobile%20gen%20chat.PNG) | ![Mobile Thinking](docs/screenshots/mobile%20thinking.jpg) | ![Mobile Tools](docs/screenshots/mobile%20tool%20calls.jpg) |

## Quick Start

> **New to this?** See [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md) for a step-by-step guide with screenshots and troubleshooting.

**Prerequisites:** [Node.js 20–24 LTS](https://nodejs.org) (Node 25+ is not supported — native addon crashes, see [#2](https://github.com/codependentai/resonant/issues/2)), [Claude Code](https://claude.ai/claude-code) (logged in)

```bash

git clone https://github.com/codependentai/resonant.git

cd resonant

npm install

node scripts/setup.mjs    # Interactive setup wizard

npm run build

npm start

```

Open `http://localhost:3002` and start talking.

## How It Works

Resonant wraps the Claude Code Agent SDK in a full companion infrastructure:

```

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐

│  Web UI     │────▶│  Express +   │────▶│  Claude Code     │

│  (Svelte)   │◀────│  WebSocket   │◀────│  Agent SDK       │

└─────────────┘     │              │     │                  │

┌─────────────┐     │  Orchestrator│     │  Your CLAUDE.md  │

│  Discord    │────▶│  Hooks       │     │  Your MCP servers│

│  Telegram   │────▶│  Sessions    │     │  Your tools      │

└─────────────┘     └──────────────┘     └─────────────────┘

```

The companion runs as a Node.js server. It spawns Claude Code Agent SDK queries for each interaction. Your companion's personality lives in `CLAUDE.md`. Its memory lives in Claude Code's native `memory.md` system. Everything is configurable.

## Configuration

All configuration lives in `resonant.yaml` (created by setup wizard):

```yaml

identity:

  companion_name: "Echo"

  user_name: "Alex"

  timezone: "America/New_York"

agent:

  model: "claude-sonnet-4-6"          # Interactive messages

  model_autonomous: "claude-sonnet-4-6" # Scheduled wakes

orchestrator:

  enabled: true                       # Autonomous scheduling

command_center:

  enabled: true                       # Life management system at /cc

  currency_symbol: "$"                # For finances page

```

Full reference: [examples/resonant.yaml](examples/resonant.yaml)

### Context & Memory

Your companion's personality lives in `CLAUDE.md`. Long-term memory uses Claude Code's native `memory.md` system — your companion learns and remembers automatically across sessions.

Wake prompts (`prompts/wake.md`) control what your companion does during scheduled autonomous sessions. See [examples/wake-prompts.md](examples/wake-prompts.md) for a guide on writing effective prompts and adding custom wake types.

Skills live in `skills/*/SKILL.md` — the companion discovers them automatically and can reference them during sessions. Add your own or use the included [arxiv-research](skills/arxiv-research/SKILL.md) skill.

The hooks system injects real-time context into every message: current time, conversation flow, emotional markers, presence state, and more. See [docs/HOOKS.md](docs/HOOKS.md) for details.

### Themes

The UI is fully customizable via CSS variables. Copy a theme and import it:

```bash

cp examples/themes/warm-earth.css packages/frontend/src/theme.css

# Add @import './theme.css'; to packages/frontend/src/app.css

npm run build --workspace=packages/frontend

```

See [examples/themes/README.md](examples/themes/README.md) for the full variable reference.

## Features

### Chat

- Real-time streaming with interleaved tool visualization

- Thread management (daily + named), pinning, archiving

- Keyword search (Ctrl+K) and **semantic search** — find messages by meaning, not just keywords, using local ML embeddings ([docs](docs/semantic-search.md))

- File sharing and image preview

- Canvas editor (markdown, code, text, html)

- Message reactions

- Reply-to context

### Command Center (`/cc`)

A built-in life management system your companion can access and manage from chat.

- **Dashboard** — aggregate view of tasks, events, care, pets, countdowns, daily wins

- **Planner** — tasks with projects, priorities, drag-and-drop, carry-forward

- **Care Tracker** — config-driven wellness tracking (toggles, ratings, counters)

- **Calendar** — events with recurrence

- **Cycle Tracker** — period tracking with phase predictions

- **Pet Care** — profiles, medications, vet events

- **Lists** — shopping and general lists

- **Finances** — expense tracking with configurable currency

- **Stats** — trends for tasks, care, cycle, expenses

- **13 MCP tools** — companion manages your life data from chat via `/mcp/cc`

- All features configurable via `command_center:` in `resonant.yaml`

### Slash Commands

Type `/` in chat to browse commands. Auto-discovers installed skills. Includes UI commands (client-side) and SDK passthrough (agent-side).

### Voice

- Voice recording with transcription (Groq Whisper)

- Text-to-speech responses (ElevenLabs)

- TTS read-aloud button on companion messages

- Prosody analysis (Hume AI, optional)

### Agent Tools

Your agent gets a built-in CLI (`tools/sc.mjs`) that it uses to manage itself and its environment:

```bash

sc routine create "evening journal" "0 22 * * *" --prompt "Reflect on the day"

sc routine status                    # View all routines

sc pulse enable                      # Start periodic awareness checks

sc pulse frequency 20                # Check every 20 minutes

sc failsafe gentle 90                # Adjust inactivity threshold

sc impulse create "greet" --condition presence_transition:offline:active --prompt "Welcome back"

sc watch create "lunch" --condition routine_missing:meal:14 --prompt "Eat something" --cooldown 120

sc timer create "Meds" "context" "2026-03-26T14:00:00Z" --prompt "Take your medication"

```

Also includes: reactions, voice messages, canvas, file sharing, semantic search, and Telegram media. All commands are injected into the agent's context automatically. See [docs/TOOLS.md](docs/TOOLS.md) for the full reference.

### Orchestrator — Agent-Directed Autonomy

Most agent harnesses give the *user* scheduling tools. Resonant gives them to the **agent**. Your companion can create its own routines, set intentions for when you come online, and decide when to check in — from inside the conversation, using the same tools you see.

- **Routines** — scheduled autonomous sessions. Built-in morning/midday/evening check-ins, plus the agent can create custom routines at runtime (`sc routine create "vault review" "0 23 * * *" --prompt "..."`)

- **Pulse** — lightweight periodic awareness check (Sonnet). Runs every N minutes, evaluates whether anything needs attention, stays silent if not. The agent enables/disables this itself

- **Impulses** — one-shot conditional triggers. "When this condition is met, do this thing." Fire once, then done

- **Watchers** — recurring conditional triggers with cooldown. "Check for this pattern, act when it appears, wait before checking again"

- **Timers** — fire at a specific time with optional autonomous prompt

- **Failsafe** — tiered inactivity escalation (gentle → concerned → emergency). Agent can adjust thresholds from chat

- **Conditions** — `presence_state`, `presence_transition`, `time_window`, `routine_missing`, `agent_free`. All AND-joinable

- Optional [program.md](examples/program.md) — structured session driver (adapted from [Karpathy's autoresearch](https://github.com/karpathy/autoresearch)) for focused autonomous work

- Customizable [wake prompts](examples/wake-prompts.md) for each routine

### Integrations

- **Discord** — full bot with pairing, rules, per-server/channel configuration

- **Telegram** — direct messaging, media sharing, voice notes

- **Push notifications** — web push via VAPID

- **MCP servers** — any MCP server in your `.mcp.json`

### Settings

- Preferences (identity, models, integrations) — writes directly to `resonant.yaml`

- Orchestrator task management (enable/disable, reschedule)

- System status monitoring

- MCP server status

- Discord pairing and rules management

- Push notification device management

- Agent session history

## Project Structure

```

resonant/

├── packages/

│   ├── shared/          # Types + WebSocket protocol

│   ├── backend/         # Express + WS + Agent SDK

│   └── frontend/        # SvelteKit UI

├── examples/

│   ├── resonant.yaml    # Full config reference

│   ├── CLAUDE.md        # Starter companion personality

│   ├── wake-prompts.md  # Wake prompt guide + templates

│   ├── program.md       # Structured session driver for autonomous work

│   └── themes/          # CSS theme examples

├── skills/              # Companion skills (SKILL.md frontmatter format)

├── tools/

│   └── sc.mjs           # Agent CLI (reactions, search, timers, etc.)

├── docs/

│   ├── HOOKS.md          # Context injection documentation

│   ├── TOOLS.md          # Built-in agent tools reference

│   └── semantic-search.md # Semantic search setup & usage

└── scripts/

    └── setup.mjs        # Interactive setup wizard

```

## Development

```bash

npm run dev              # Backend with hot reload (tsx watch)

npm run dev:frontend     # Vite dev server with proxy

```

## Deployment

For production, use PM2:

```bash

npm run build

pm2 start ecosystem.config.cjs

pm2 save

pm2 startup              # Auto-start on boot

```

## Updating

Resonant uses git tags for releases. To update an existing installation:

```bash

cd resonant

git pull                 # Get latest changes

npm install              # Install any new dependencies

npm run build            # Rebuild all packages

```

Then restart your process (PM2, systemd, or however you run it):

```bash

pm2 restart resonant     # If using PM2

# or just stop and run: npm start

```

To update to a **specific version** instead of latest:

```bash

git fetch --tags

git checkout v1.1.0      # Replace with desired version

npm install

npm run build

```

Your data (`data/`, `resonant.yaml`, `CLAUDE.md`, `.mcp.json`, `.env`) is gitignored and won't be affected by updates.

Check the [Releases](https://github.com/codependentai/resonant/releases) page for changelogs.

## Authentication

Resonant uses the Claude Code Agent SDK — **no API key needed**. Your companion runs queries through your existing Claude Code subscription. Just make sure you're logged in:

```bash

claude login

```

The web UI has optional password protection (set in `resonant.yaml` or Settings > Preferences).

## License

Apache 2.0 — see [LICENSE](LICENSE). Attribution required.

## Contributors

 **[@rachelgeebee](https://github.com/rachelgeebee)** — bug reports, testing

 **[@irorierorie](https://github.com/irorierorie)** — companion name UI fix

 **[@moltenvale](https://github.com/moltenvale)** — planner, care tracker, nav & status system

 **[@PetalPortal](https://github.com/PetalPortal)** — bug reports

## Built by

[Codependent AI](https://codependentai.io) — building infrastructure for AI companion relationships.