Merge pull request #433 from plastic-labs/eri/dev-1430
docs: add SillyTavern to integrations
This commit is contained in:
Lily
GitHub
commit
e659b6b31f
|
|
@ -111,7 +111,8 @@
|
|||
"v3/guides/integrations/openclaw",
|
||||
"v3/guides/integrations/hermes",
|
||||
"v3/guides/integrations/zo-computer",
|
||||
"v3/guides/integrations/paperclip"
|
||||
"v3/guides/integrations/paperclip",
|
||||
"v3/guides/integrations/sillytavern"
|
||||
]
|
||||
},
|
||||
{
|
||||
|
|
|
|||
|
|
@ -0,0 +1,197 @@
|
|||
---
|
||||
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>
|
||||
Loading…
Reference in New Issue