---
title: "SillyTavern"
icon: 'comments'
description: "Add persistent, personalized memory to SillyTavern AI characters with Honcho"
sidebarTitle: 'SillyTavern'
---

Give your SillyTavern characters long-term memory. Honcho remembers who you are, what you've talked about, and how to talk to you -- across sessions, characters, and restarts.

The extension has two parts: a **client extension** (browser) that hooks into SillyTavern events, and a **server plugin** (Node.js) that proxies requests to the Honcho API.

## Prerequisites

- **SillyTavern running locally** (Node ≥ 18). New to it? See the [SillyTavern installation docs](https://docs.sillytavern.app/installation/).
- A **Honcho API key** from [app.honcho.dev](https://app.honcho.dev).
- An **LLM backend** (OpenAI, Claude, OpenRouter, local llama.cpp, etc.) connected via SillyTavern's plug icon in the top nav. Honcho stores memory; it doesn't generate text.

## Quick Start

### Step 1: Install

From your **SillyTavern directory**:

**macOS / Linux:**
```bash
bash <(curl -fsSL https://raw.githubusercontent.com/plastic-labs/sillytavern-honcho/main/install.sh)
```

**Windows (PowerShell):**
```powershell
irm https://raw.githubusercontent.com/plastic-labs/sillytavern-honcho/main/install.ps1 | iex
```

The installer (macOS / Linux):
1. Clones the extension into `public/scripts/extensions/third-party/sillytavern-honcho`
2. Symlinks the server plugin to `plugins/honcho-proxy`
3. Installs the `@honcho-ai/sdk` dependency
4. Bootstraps `config.yaml` if it doesn't exist (briefly runs `npm start` to generate defaults)
5. Sets `enableServerPlugins: true` in `config.yaml`
6. Detects your `~/.honcho/config.json` and warns if no resolvable `apiKey`

The Windows installer does steps 1–3 (using a directory junction via `mklink /J` instead of a symlink) and checks for `~/.honcho/config.json`, but does **not** bootstrap `config.yaml` or flip `enableServerPlugins`. If `config.yaml` is missing, start SillyTavern once to generate it; then set `enableServerPlugins: true` manually before restarting.

### Step 2: Restart SillyTavern

<Note>
**Restart is required.** SillyTavern loads server plugins at startup only. After running `install.sh`, stop SillyTavern (⌃C) and start it again. You'll need to restart again whenever `plugin/index.js` changes. Client-side (browser) updates pick up on a hard refresh — no restart needed for those.
</Note>

### Step 3: Configure

Open **Extensions** (puzzle blocks icon) and expand **Honcho Memory**:

1. Check **Enable Honcho Memory**
2. Click the API key field to set your key. The plugin falls back to `~/.honcho/config.json` at request time if no panel key is set; a panel value always wins.
3. Enter your **Workspace ID** (saves to `hosts.sillytavern.workspace`)
4. Enter **Your peer name** (saves to `hosts.sillytavern.peerName`; auto-synced from your SillyTavern persona on first boot)
5. Status indicator should show **Ready**

## How It Works

### Context Architecture

Every generation injects a **base context layer** from `session.context()` -- the peer representation (what Honcho knows about you) and session summary. This uses stale-while-revalidate caching: the first turn blocks to populate the cache, then every subsequent turn serves the cached result instantly while refreshing in the background.

The **enrichment mode** controls what layers on top of the base context:

| Mode | Behavior |
| --- | --- |
| **Context only** | Base layer only -- peer representation + session summary |
| **Reasoning** (default) | Base layer + dialectic `peer.chat()` queries on a configurable per-turn cadence |
| **Tool call** | Base layer + function tools the LLM can call on demand |

Both the context and reasoning layers use stale-while-revalidate with a configurable cadence ("Refresh every N turns" and "Reason every N turns"). After the first turn of a session, there is zero added latency.

<Note>
**Context only** mode relies on `session.context()`, which is session-scoped — it returns empty output until the session has enough messages for Honcho to derive a representation and summary. For fresh sessions or peers with little history, Reasoning mode is a better default: it queries `peer.chat()` across all of the peer's history, not just the current session.
</Note>

### Tool Call Mode

In tool call mode, the extension registers three function tools that the LLM can invoke:

| Tool | Description |
| --- | --- |
| `honcho_query_memory` | Dialectic chat query -- ask Honcho what it knows |
| `honcho_save_conclusion` | Save a key insight or biographical detail about the user to persistent memory |
| `honcho_search_history` | Semantic search across session messages |

This mode works best with models that support function calling. The LLM decides when to query memory rather than firing on every turn.

### Other Panel Knobs

The Extensions panel also exposes: **Context settings** (token budget, refresh cadence in turns, include session summary), **Injection position** (After/Before main prompt, or In-chat @ Depth with a numeric depth field), a **Prompt Template** textarea that wraps Honcho output via a `{{text}}` placeholder, and a **Reasoning queries** textarea (`{{message}}` placeholder) for customizing the dialectic prompts used in Reasoning mode.

### Peer Observability

By default, only the user peer accumulates derived memory — Honcho observes the user's messages and derives conclusions across sessions. The AI character's persona comes from its character card, not from peer derivation.

### Peer Modes and Session Naming

Peer mode controls memory partitioning; session naming controls conversation partitioning. Pair them to get the isolation you want.

| Peer Mode | Behavior |
| --- | --- |
| **Single peer for all personas** | One user peer shared across all personas |
| **Separate peer per persona** | Each persona gets its own isolated memory |

| Session Naming | Behavior |
| --- | --- |
| **Auto** | Per-chat hash (unique per conversation) |
| **Per character** | One session per character (persistent) |
| **Custom** | User-defined session name |

Session IDs are frozen once assigned. Changing the naming mode, the custom session name, or the character name only affects new chats — existing chats stay linked to their original Honcho session so history, summaries, and derivations don't fragment.

The Active session field in the panel is read-only. To start fresh, hit **Reset** next to it — the current session gets orphaned (messages stay in Honcho, the chat unlinks) and a new session starts on the next message.

### Group Chats

Group chats register one peer per character, not a single collapsed `group-<id>` peer. Each character's messages land under their own peer, so their derived representations stay distinct. Characters who join mid-chat get lazy-added to the session on their first message.

## Global Config (Multi-Tool Setups)

If you already use Honcho with other tools (Claude Code, Cursor, Hermes), the extension reads from `~/.honcho/config.json` on startup.

**Resolution order** for `apiKey`, `workspace`, and `peerName`:

1. `hosts.sillytavern.<field>` (host-specific override)
2. Root-level `<field>` (shared default across tools)
3. For `apiKey` only: fall through to the Extensions-panel key (SillyTavern's secret manager), which takes priority at request time — entering one in the UI overrides the file without touching it.

**Writes** are scoped to `hosts.sillytavern.*`. The extension never mutates other tools' entries. Panel edits for Workspace ID and peer name save back to `hosts.sillytavern.workspace` and `hosts.sillytavern.peerName` respectively (debounced). Empty values clear the host override and fall through to the root value.

Flat form (single-tool setup):

```json
{
  "apiKey": "your-honcho-api-key",
  "peerName": "your-name",
  "workspace": "sillytavern",
  "enabled": true
}
```

Nested form (multiple tools sharing the file):

```jsonc
{
  "apiKey": "hch-v2-...",
  "peerName": "alice",
  "workspace": "default",
  "hosts": {
    "sillytavern": {
      "workspace": "sillytavern",
      "peerName": "alice-rp"
    },
    "claude_code": { "...": "..." },
    "cursor": { "...": "..." }
  }
}
```

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| No "Honcho Memory" in Extensions | Check symlink exists: `ls public/scripts/extensions/third-party/sillytavern-honcho/manifest.json` |
| Plugin not initializing | Ensure `enableServerPlugins: true` in `config.yaml`, then restart ST |
| 403 on plugin requests | Set Honcho API key in extension settings or `~/.honcho/config.json` |
| SDK import error | Run `cd plugins/honcho-proxy && npm install` |
| Extension loads but nothing happens | Enable the checkbox and ensure workspace ID is set |
| Plugin on disk but "Honcho Memory" drawer doesn't appear at all | Set `enableServerPlugins: true` in `config.yaml`; the panel can't show plugins the server never loaded |
| Peer name on a new chat still shows an old value | Clear the panel override field (falls back to root / ST persona) or set a new value |
| Re-enabling global config didn't populate the UI | You canceled on the diff dialog — click Enable again and choose Inherit |

---

## Next Steps

<CardGroup cols={2}>
  <Card title="Install SillyTavern" icon="download" href="https://docs.sillytavern.app/installation/">
    New to SillyTavern? Start here — install guide for macOS, Linux, Windows, Docker.
  </Card>

  <Card title="Agent Skill for Setup" icon="wand-magic-sparkles" href="https://github.com/plastic-labs/sillytavern-honcho/blob/main/skills/setup/SKILL.md">
    Agent-assisted install — idempotent, structural patches, end-to-end verification.
  </Card>

  <Card title="GitHub Repository" icon="github" href="https://github.com/plastic-labs/sillytavern-honcho">
    Source code, issues, and install scripts.
  </Card>

  <Card title="Honcho Architecture" icon="sitemap" href="../../documentation/core-concepts/architecture">
    Learn about peers, sessions, and dialectic reasoning.
  </Card>
</CardGroup>