198 lines
9.8 KiB
Plaintext
198 lines
9.8 KiB
Plaintext
---
|
||
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>
|