205 lines
8.9 KiB
Plaintext
205 lines
8.9 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.
|
|
|
|
## Quick Start
|
|
|
|
<Note>
|
|
Honcho stores memory; it doesn't generate text. You'll also need an LLM backend (OpenAI, Claude, OpenRouter, local llama.cpp, etc.) connected via SillyTavern's plug icon in the top nav. Configure that separately before expecting replies in chat.
|
|
</Note>
|
|
|
|
### Step 1: Get Your Honcho API Key
|
|
|
|
1. Go to **[app.honcho.dev](https://app.honcho.dev)**
|
|
2. Sign up or log in
|
|
3. Copy your API key
|
|
|
|
### Step 2: 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
|
|
```
|
|
|
|
<Note>
|
|
Server plugins must be enabled for the Honcho plugin to load. The installer configures this automatically on fresh checkouts; if you skipped the installer or started SillyTavern before running it, manually set `enableServerPlugins: true` in `config.yaml` and restart.
|
|
</Note>
|
|
|
|
The installer:
|
|
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. Detects your `~/.honcho/config.json` if it exists (if not, the plugin seeds a minimal one on first run)
|
|
|
|
### Step 3: Restart SillyTavern
|
|
|
|
Stop and restart SillyTavern so the server plugin loads. If you have in-progress chats open, save them first — the running session ends when you stop the server.
|
|
|
|
### Step 4: Configure
|
|
|
|
Open **Extensions** (three-cubes icon, top-right) and expand **Honcho Memory**:
|
|
|
|
1. Check **Enable Honcho Memory**
|
|
2. Click the API key field to set your key (if auto-detected from `~/.honcho/config.json`, you can still enter one here to override)
|
|
3. Enter your workspace ID
|
|
4. Status indicator should show **Ready**
|
|
|
|
## 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 when resolvable keys are present. Resolution order: `hosts.sillytavern.apiKey` → root-level `apiKey` → fall through to the Extensions-panel key if neither resolves. The Extensions-panel key (SillyTavern's secret manager) takes priority at request time, so entering one in the UI overrides the config file without touching it.
|
|
|
|
Note that "sillytavern" appears in two namespaces here: as the default Honcho workspace ID (a Honcho concept — what you see in the dashboard; configurable) and as the `hosts.sillytavern` host key in the config file (a local convention for which tool's settings are which).
|
|
|
|
Flat form:
|
|
|
|
```json
|
|
{
|
|
"apiKey": "your-honcho-api-key",
|
|
"peerName": "your-name",
|
|
"workspace": "sillytavern",
|
|
"enabled": true
|
|
}
|
|
```
|
|
|
|
Writes are always scoped to `hosts.sillytavern` — the extension never mutates settings for other tools.
|
|
|
|
Nested form (when multiple tools share the file):
|
|
|
|
```jsonc
|
|
{
|
|
"apiKey": "hch-v2-...",
|
|
"peerName": "alice",
|
|
"hosts": {
|
|
"sillytavern": {
|
|
"workspace": "sillytavern",
|
|
"aiPeer": "Assistant" // Updated automatically per character
|
|
},
|
|
"claude_code": { "..." : "..." },
|
|
"cursor": { "..." : "..." }
|
|
}
|
|
}
|
|
```
|
|
|
|
## 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 interval |
|
|
| **Tool call** | Base layer + function tools the LLM can call on demand |
|
|
|
|
Both the context and reasoning layers use stale-while-revalidate with configurable refresh intervals. 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_observation` | Save an insight about the user to 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.
|
|
|
|
### 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. If you want the character to have its own Honcho-derived state, configure it as an additional peer in session setup.
|
|
|
|
### Peer Modes
|
|
|
|
| Mode | Behavior |
|
|
| --- | --- |
|
|
| **Single peer** | One user peer shared across all characters |
|
|
| **Per-persona** | Each character gets its own isolated memory |
|
|
|
|
### Session Naming
|
|
|
|
| Mode | Behavior |
|
|
| --- | --- |
|
|
| **Auto** | Per-chat hash (unique per conversation) |
|
|
| **Per-character** | One session per character (persistent) |
|
|
| **Custom** | User-defined session name |
|
|
|
|
### Event Flow
|
|
|
|
| SillyTavern Event | Action |
|
|
| --- | --- |
|
|
| Chat opened | Creates or retrieves Honcho session + peers |
|
|
| Before generation | Injects memory context into the prompt |
|
|
| User sends message | Stores message in Honcho session |
|
|
| AI responds | Stores response in Honcho session |
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Browser (Client Extension) Server (Plugin)
|
|
+-----------------------+ +------------------------------+
|
|
| index.js | fetch() | plugin/index.js |
|
|
| | ------------> | |
|
|
| - Settings UI | /api/plugins/ | - Express router (9 routes) |
|
|
| - Event hooks | honcho-proxy | - Honcho SDK (@honcho-ai/sdk)|
|
|
| - Prompt injection | | - API key from ST secrets or |
|
|
| - Tool registration | | ~/.honcho/config.json |
|
|
+-----------------------+ +------------------------------+
|
|
```
|
|
|
|
The server plugin reads API credentials from SillyTavern's secrets store first, falling back to `~/.honcho/config.json`. It re-reads the global config before every write to prevent race conditions with concurrent tools.
|
|
|
|
## 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 |
|
|
|
|
---
|
|
|
|
## 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="Claude Code Setup Skill" 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>
|