Skip to content

Commit e659b6b

Browse files
lowyellinglowyelling
authored
Merge pull request #433 from plastic-labs/eri/dev-1430
docs: add SillyTavern to integrations
2 parents a3e8000 + 9d68149 commit e659b6b

2 files changed

Lines changed: 199 additions & 1 deletion

File tree

‎docs/docs.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,8 @@
111111
"v3/guides/integrations/openclaw",
112112
"v3/guides/integrations/hermes",
113113
"v3/guides/integrations/zo-computer",
114-
"v3/guides/integrations/paperclip"
114+
"v3/guides/integrations/paperclip",
115+
"v3/guides/integrations/sillytavern"
115116
]
116117
},
117118
{

‎docs/v3/guides/integrations/sillytavern.mdx‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
---
2+
title: "SillyTavern"
3+
icon: 'comments'
4+
description: "Add persistent, personalized memory to SillyTavern AI characters with Honcho"
5+
sidebarTitle: 'SillyTavern'
6+
---
7+
8+
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.
9+
10+
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.
11+
12+
## Prerequisites
13+
14+
- **SillyTavern running locally** (Node ≥ 18). New to it? See the [SillyTavern installation docs](https://docs.sillytavern.app/installation/).
15+
- A **Honcho API key** from [app.honcho.dev](https://app.honcho.dev).
16+
- 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.
17+
18+
## Quick Start
19+
20+
### Step 1: Install
21+
22+
From your **SillyTavern directory**:
23+
24+
**macOS / Linux:**
25+
```bash
26+
bash <(curl -fsSL https://raw.githubusercontent.com/plastic-labs/sillytavern-honcho/main/install.sh)
27+
```
28+
29+
**Windows (PowerShell):**
30+
```powershell
31+
irm https://raw.githubusercontent.com/plastic-labs/sillytavern-honcho/main/install.ps1 | iex
32+
```
33+
34+
The installer (macOS / Linux):
35+
1. Clones the extension into `public/scripts/extensions/third-party/sillytavern-honcho`
36+
2. Symlinks the server plugin to `plugins/honcho-proxy`
37+
3. Installs the `@honcho-ai/sdk` dependency
38+
4. Bootstraps `config.yaml` if it doesn't exist (briefly runs `npm start` to generate defaults)
39+
5. Sets `enableServerPlugins: true` in `config.yaml`
40+
6. Detects your `~/.honcho/config.json` and warns if no resolvable `apiKey`
41+
42+
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.
43+
44+
### Step 2: Restart SillyTavern
45+
46+
<Note>
47+
**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.
48+
</Note>
49+
50+
### Step 3: Configure
51+
52+
Open **Extensions** (puzzle blocks icon) and expand **Honcho Memory**:
53+
54+
1. Check **Enable Honcho Memory**
55+
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.
56+
3. Enter your **Workspace ID** (saves to `hosts.sillytavern.workspace`)
57+
4. Enter **Your peer name** (saves to `hosts.sillytavern.peerName`; auto-synced from your SillyTavern persona on first boot)
58+
5. Status indicator should show **Ready**
59+
60+
## How It Works
61+
62+
### Context Architecture
63+
64+
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.
65+
66+
The **enrichment mode** controls what layers on top of the base context:
67+
68+
| Mode | Behavior |
69+
| --- | --- |
70+
| **Context only** | Base layer only -- peer representation + session summary |
71+
| **Reasoning** (default) | Base layer + dialectic `peer.chat()` queries on a configurable per-turn cadence |
72+
| **Tool call** | Base layer + function tools the LLM can call on demand |
73+
74+
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.
75+
76+
<Note>
77+
**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.
78+
</Note>
79+
80+
### Tool Call Mode
81+
82+
In tool call mode, the extension registers three function tools that the LLM can invoke:
83+
84+
| Tool | Description |
85+
| --- | --- |
86+
| `honcho_query_memory` | Dialectic chat query -- ask Honcho what it knows |
87+
| `honcho_save_conclusion` | Save a key insight or biographical detail about the user to persistent memory |
88+
| `honcho_search_history` | Semantic search across session messages |
89+
90+
This mode works best with models that support function calling. The LLM decides when to query memory rather than firing on every turn.
91+
92+
### Other Panel Knobs
93+
94+
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.
95+
96+
### Peer Observability
97+
98+
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.
99+
100+
### Peer Modes and Session Naming
101+
102+
Peer mode controls memory partitioning; session naming controls conversation partitioning. Pair them to get the isolation you want.
103+
104+
| Peer Mode | Behavior |
105+
| --- | --- |
106+
| **Single peer for all personas** | One user peer shared across all personas |
107+
| **Separate peer per persona** | Each persona gets its own isolated memory |
108+
109+
| Session Naming | Behavior |
110+
| --- | --- |
111+
| **Auto** | Per-chat hash (unique per conversation) |
112+
| **Per character** | One session per character (persistent) |
113+
| **Custom** | User-defined session name |
114+
115+
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.
116+
117+
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.
118+
119+
### Group Chats
120+
121+
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.
122+
123+
## Global Config (Multi-Tool Setups)
124+
125+
If you already use Honcho with other tools (Claude Code, Cursor, Hermes), the extension reads from `~/.honcho/config.json` on startup.
126+
127+
**Resolution order** for `apiKey`, `workspace`, and `peerName`:
128+
129+
1. `hosts.sillytavern.<field>` (host-specific override)
130+
2. Root-level `<field>` (shared default across tools)
131+
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.
132+
133+
**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.
134+
135+
Flat form (single-tool setup):
136+
137+
```json
138+
{
139+
"apiKey": "your-honcho-api-key",
140+
"peerName": "your-name",
141+
"workspace": "sillytavern",
142+
"enabled": true
143+
}
144+
```
145+
146+
Nested form (multiple tools sharing the file):
147+
148+
```jsonc
149+
{
150+
"apiKey": "hch-v2-...",
151+
"peerName": "alice",
152+
"workspace": "default",
153+
"hosts": {
154+
"sillytavern": {
155+
"workspace": "sillytavern",
156+
"peerName": "alice-rp"
157+
},
158+
"claude_code": { "...": "..." },
159+
"cursor": { "...": "..." }
160+
}
161+
}
162+
```
163+
164+
## Troubleshooting
165+
166+
| Symptom | Fix |
167+
| --- | --- |
168+
| No "Honcho Memory" in Extensions | Check symlink exists: `ls public/scripts/extensions/third-party/sillytavern-honcho/manifest.json` |
169+
| Plugin not initializing | Ensure `enableServerPlugins: true` in `config.yaml`, then restart ST |
170+
| 403 on plugin requests | Set Honcho API key in extension settings or `~/.honcho/config.json` |
171+
| SDK import error | Run `cd plugins/honcho-proxy && npm install` |
172+
| Extension loads but nothing happens | Enable the checkbox and ensure workspace ID is set |
173+
| 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 |
174+
| 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 |
175+
| Re-enabling global config didn't populate the UI | You canceled on the diff dialog — click Enable again and choose Inherit |
176+
177+
---
178+
179+
## Next Steps
180+
181+
<CardGroup cols={2}>
182+
<Card title="Install SillyTavern" icon="download" href="https://docs.sillytavern.app/installation/">
183+
New to SillyTavern? Start here — install guide for macOS, Linux, Windows, Docker.
184+
</Card>
185+
186+
<Card title="Agent Skill for Setup" icon="wand-magic-sparkles" href="https://github.com/plastic-labs/sillytavern-honcho/blob/main/skills/setup/SKILL.md">
187+
Agent-assisted install — idempotent, structural patches, end-to-end verification.
188+
</Card>
189+
190+
<Card title="GitHub Repository" icon="github" href="https://github.com/plastic-labs/sillytavern-honcho">
191+
Source code, issues, and install scripts.
192+
</Card>
193+
194+
<Card title="Honcho Architecture" icon="sitemap" href="../../documentation/core-concepts/architecture">
195+
Learn about peers, sessions, and dialectic reasoning.
196+
</Card>
197+
</CardGroup>

0 commit comments

Comments
 (0)