switchroom 0.12.27 → 0.12.29

package/telegram-plugin/tests/prefix-warmup.test.ts

@@ -0,0 +1,175 @@
+/**
+ * Tests for the prefix-cache warmup module.
+ *
+ * Per cold-start TTFO RFC Option A: fire a synthetic inbound on
+ * bridge-up so Anthropic's prefix cache is warm by the user's next
+ * real message. These tests pin: env gate, cooldown, missing-target
+ * skip, message shape (meta.source="warmup", correct text), and
+ * cooldown debounce across multiple bridge reconnects.
+ */
+
+import { describe, expect, it, beforeEach, vi } from 'vitest'
+import {
+  __resetForTests,
+  maybeFireWarmup,
+  WARMUP_TEXT,
+} from '../gateway/prefix-warmup'
+import type { WarmupCtx } from '../gateway/prefix-warmup'
+
+beforeEach(() => {
+  __resetForTests()
+  delete process.env.SWITCHROOM_PREFIX_WARMUP
+})
+
+function makeCtx(overrides?: Partial<WarmupCtx>): {
+  ctx: WarmupCtx
+  send: ReturnType<typeof vi.fn>
+  logs: string[]
+} {
+  const send = vi.fn()
+  const logs: string[] = []
+  const ctx: WarmupCtx = {
+    selfAgent: 'test-agent',
+    client: { send, agentName: 'test-agent', id: 'c1', isAlive: () => true, lastHeartbeat: 0, close: () => {} } as never,
+    resolveBootTarget: () => ({ chatId: '12345', threadId: undefined }),
+    log: (l: string) => logs.push(l),
+    now: () => 1_000_000,
+    ...overrides,
+  }
+  return { ctx, send, logs }
+}
+
+describe('maybeFireWarmup — env gate', () => {
+  it('skipped when SWITCHROOM_PREFIX_WARMUP is unset', () => {
+    const { ctx, send } = makeCtx()
+    expect(maybeFireWarmup(ctx)).toBe(false)
+    expect(send).not.toHaveBeenCalled()
+  })
+
+  it('skipped when SWITCHROOM_PREFIX_WARMUP is 0', () => {
+    process.env.SWITCHROOM_PREFIX_WARMUP = '0'
+    const { ctx, send } = makeCtx()
+    expect(maybeFireWarmup(ctx)).toBe(false)
+    expect(send).not.toHaveBeenCalled()
+  })
+
+  it('fires when SWITCHROOM_PREFIX_WARMUP=1', () => {
+    process.env.SWITCHROOM_PREFIX_WARMUP = '1'
+    const { ctx, send } = makeCtx()
+    expect(maybeFireWarmup(ctx)).toBe(true)
+    expect(send).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('maybeFireWarmup — message shape', () => {
+  beforeEach(() => {
+    process.env.SWITCHROOM_PREFIX_WARMUP = '1'
+  })
+
+  it('tags meta.source="warmup"', () => {
+    const { ctx, send } = makeCtx()
+    maybeFireWarmup(ctx)
+    const msg = send.mock.calls[0][0]
+    expect(msg.meta.source).toBe('warmup')
+  })
+
+  it('uses synthetic messageId=0 and userId=0', () => {
+    const { ctx, send } = makeCtx()
+    maybeFireWarmup(ctx)
+    const msg = send.mock.calls[0][0]
+    expect(msg.messageId).toBe(0)
+    expect(msg.userId).toBe(0)
+    expect(msg.user).toBe('switchroom-warmup')
+  })
+
+  it('text carries the NO_REPLY instruction', () => {
+    const { ctx, send } = makeCtx()
+    maybeFireWarmup(ctx)
+    const msg = send.mock.calls[0][0]
+    expect(msg.text).toBe(WARMUP_TEXT)
+    expect(msg.text).toContain('__WARMUP_PING__')
+    expect(msg.text).toContain('NO_REPLY')
+  })
+
+  it('routes to the resolved boot chat', () => {
+    process.env.SWITCHROOM_PREFIX_WARMUP = '1'
+    const { ctx, send } = makeCtx({
+      resolveBootTarget: () => ({ chatId: 'CHAT-9', threadId: 42 }),
+    })
+    maybeFireWarmup(ctx)
+    const msg = send.mock.calls[0][0]
+    expect(msg.chatId).toBe('CHAT-9')
+    expect(msg.threadId).toBe(42)
+  })
+
+  it('omits threadId when boot target has none', () => {
+    const { ctx, send } = makeCtx()
+    maybeFireWarmup(ctx)
+    const msg = send.mock.calls[0][0]
+    expect(msg.threadId).toBeUndefined()
+  })
+})
+
+describe('maybeFireWarmup — cooldown', () => {
+  beforeEach(() => {
+    process.env.SWITCHROOM_PREFIX_WARMUP = '1'
+  })
+
+  it('second call within cooldown is skipped', () => {
+    const { ctx, send, logs } = makeCtx()
+    expect(maybeFireWarmup(ctx)).toBe(true)
+    // Same now() — well within cooldown.
+    expect(maybeFireWarmup(ctx)).toBe(false)
+    expect(send).toHaveBeenCalledTimes(1)
+    expect(logs.some((l) => l.includes('reason=cooldown'))).toBe(true)
+  })
+
+  it('call after cooldown elapses fires again', () => {
+    let t = 1_000_000
+    const ctx = makeCtx({ now: () => t }).ctx
+    expect(maybeFireWarmup(ctx)).toBe(true)
+    t += 5 * 60_000 + 1 // just past cooldown
+    expect(maybeFireWarmup(ctx)).toBe(true)
+  })
+
+  it('cooldown is per-agent', () => {
+    const a = makeCtx({ selfAgent: 'agent-a' })
+    const b = makeCtx({ selfAgent: 'agent-b' })
+    expect(maybeFireWarmup(a.ctx)).toBe(true)
+    expect(maybeFireWarmup(b.ctx)).toBe(true)
+    expect(maybeFireWarmup(a.ctx)).toBe(false) // a in cooldown
+    expect(maybeFireWarmup(b.ctx)).toBe(false) // b in cooldown
+  })
+})
+
+describe('maybeFireWarmup — missing boot target', () => {
+  beforeEach(() => {
+    process.env.SWITCHROOM_PREFIX_WARMUP = '1'
+  })
+
+  it('skipped when no boot chat resolves', () => {
+    const { ctx, send, logs } = makeCtx({ resolveBootTarget: () => null })
+    expect(maybeFireWarmup(ctx)).toBe(false)
+    expect(send).not.toHaveBeenCalled()
+    expect(logs.some((l) => l.includes('reason=no-boot-chat-target'))).toBe(true)
+  })
+})
+
+describe('maybeFireWarmup — send error handling', () => {
+  beforeEach(() => {
+    process.env.SWITCHROOM_PREFIX_WARMUP = '1'
+  })
+
+  it('caught send throw returns false and does not mark cooldown', () => {
+    const send = vi.fn(() => {
+      throw new Error('boom')
+    })
+    const ctx = makeCtx({
+      client: { send } as never,
+    }).ctx
+    expect(maybeFireWarmup(ctx)).toBe(false)
+    // Cooldown NOT recorded — next call should attempt again.
+    expect(maybeFireWarmup(ctx)).toBe(false) // still throws
+    expect(send).toHaveBeenCalledTimes(2)
+  })
+})

package/telegram-plugin/tests/stderr-timestamps.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Tests for the line-buffered stderr timestamp wrapper.
+ */
+
+import { describe, expect, it, beforeEach } from 'vitest'
+import {
+  __resetForTests,
+  __getPartialBufferForTests,
+  installStderrTimestamps,
+  stampLines,
+} from '../stderr-timestamps'
+
+beforeEach(() => {
+  __resetForTests()
+})
+
+describe('stampLines (pure)', () => {
+  it('stamps a single complete line', () => {
+    const t = () => '2026-05-20T18:00:00.000Z'
+    expect(stampLines('hello world\n', t)).toBe('[2026-05-20T18:00:00.000Z] hello world\n')
+  })
+
+  it('returns empty for empty input', () => {
+    const t = () => '2026-05-20T18:00:00.000Z'
+    expect(stampLines('', t)).toBe('')
+  })
+
+  it('stamps multiple lines in one chunk', () => {
+    const t = () => 'T'
+    expect(stampLines('a\nb\nc\n', t)).toBe('[T] a\n[T] b\n[T] c\n')
+  })
+
+  it('buffers a partial line until the newline arrives', () => {
+    const t = () => 'T'
+    // Partial chunk: no newline → no output, content buffered.
+    expect(stampLines('partial', t)).toBe('')
+    expect(__getPartialBufferForTests()).toBe('partial')
+    // Newline finishes the buffered line.
+    expect(stampLines('-end\n', t)).toBe('[T] partial-end\n')
+    expect(__getPartialBufferForTests()).toBe('')
+  })
+
+  it('handles partial + complete in one chunk', () => {
+    const t = () => 'T'
+    expect(stampLines('line1\nstart-of-2', t)).toBe('[T] line1\n')
+    expect(__getPartialBufferForTests()).toBe('start-of-2')
+    expect(stampLines('-end\n', t)).toBe('[T] start-of-2-end\n')
+  })
+
+  it('handles chunk that ends exactly on a newline', () => {
+    const t = () => 'T'
+    expect(stampLines('exact\n', t)).toBe('[T] exact\n')
+    expect(__getPartialBufferForTests()).toBe('')
+  })
+
+  it('handles a multi-newline chunk with trailing partial', () => {
+    const t = () => 'T'
+    expect(stampLines('a\nb\nc', t)).toBe('[T] a\n[T] b\n')
+    expect(__getPartialBufferForTests()).toBe('c')
+  })
+})
+
+describe('installStderrTimestamps (integration)', () => {
+  it('kill switch SWITCHROOM_LOG_TIMESTAMPS=0 prevents install', () => {
+    const env: NodeJS.ProcessEnv = { SWITCHROOM_LOG_TIMESTAMPS: '0' }
+    const result = installStderrTimestamps(env)
+    expect(result).toBe(false)
+  })
+
+  it('default install returns true', () => {
+    const result = installStderrTimestamps({})
+    expect(result).toBe(true)
+  })
+
+  it('second install is a no-op (idempotent)', () => {
+    expect(installStderrTimestamps({})).toBe(true)
+    expect(installStderrTimestamps({})).toBe(true)
+  })
+
+  it('wrapped write emits ISO-timestamped lines', () => {
+    installStderrTimestamps({})
+    // Capture by replacing the write FUNCTION the wrapper forwards to.
+    // The wrapper calls the ORIGINAL bound `process.stderr.write`. We
+    // can validate end-to-end by writing and then reading back from a
+    // captured forward — but easier: pipe the wrapped output to a
+    // string by hooking process.stderr.write a second time.
+    const captured: string[] = []
+    const prev = process.stderr.write
+    process.stderr.write = ((chunk: string | Uint8Array) => {
+      const text = typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8')
+      captured.push(text)
+      return true
+    }) as typeof process.stderr.write
+    try {
+      // The OUTER wrapper (installStderrTimestamps) was installed first,
+      // then we layered the capture on top. Calling process.stderr.write
+      // hits the CAPTURE, which means we'd capture the un-stamped text.
+      // Reverse: call the STAMPED wrapper directly by invoking through
+      // the installed function reference. Easiest path: just exercise
+      // stampLines (already pure-tested above) and rely on the install
+      // returning true to know we wired the wrapper.
+      //
+      // This test is best-effort end-to-end; the pure tests are the
+      // load-bearing contract.
+      process.stderr.write('test\n')
+    } finally {
+      process.stderr.write = prev
+    }
+    // The capture above is positioned ABOVE the stamper, so what it
+    // captures is what callers see. We at least verify it didn't crash.
+    expect(captured.length).toBeGreaterThan(0)
+  })
+})

package/vendor/hindsight-memory/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "hindsight-memory",
+  "description": "Automatic long-term memory for Claude Code via Hindsight. Recalls relevant memories before each prompt and retains conversation transcripts after each response.",
+  "version": "0.4.0",
+  "author": {"name": "Hindsight Team", "url": "https://vectorize.io/hindsight"},
+  "license": "MIT",
+  "keywords": ["memory", "hindsight", "recall", "retain"]
+}

package/vendor/hindsight-memory/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+- `{user_id}` template variable for `retainTags` and `retainMetadata`, resolved
+  from the `HINDSIGHT_USER_ID` env var (empty string if unset). Enables
+  machine-independent per-user memory scoping without hardcoding user ids in
+  `settings.json`.
+
+### Changed
+
+- Tags that resolve to an empty namespace content (e.g. `"user:"` when
+  `HINDSIGHT_USER_ID` is unset) are now dropped from retain requests. Previously
+  such tags were sent as-is. Tags without `:` are unaffected.
+
+## [0.1.0] - 2025-03-23
+
+### Added
+- Initial release: Claude Code plugin for Hindsight long-term memory
+- Auto-recall on every user prompt via `UserPromptSubmit` hook — injects relevant memories as `additionalContext`
+- Auto-retain after every response via async `Stop` hook — extracts and stores conversation transcript
+- Session lifecycle hooks (`SessionStart` health check, `SessionEnd` daemon cleanup)
+- Three connection modes: external API, auto-managed local daemon (`uvx hindsight-embed`), existing local server
+- Dynamic bank IDs with configurable granularity (`agent`, `project`, `session`, `channel`, `user`)
+- Channel-agnostic: works with Claude Code Channels (Telegram, Discord, Slack) and interactive sessions
+- Zero pip dependencies — pure Python stdlib (`urllib`, `fcntl`, `subprocess`)
+- 34 configuration options via `settings.json` with env var overrides
+- LLM auto-detection from `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`
+- Chunked retention with sliding window (`retainEveryNTurns` + `retainOverlapTurns`)
+- Memory tag stripping to prevent retain feedback loops

package/vendor/hindsight-memory/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vectorize AI, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/vendor/hindsight-memory/README.md

@@ -0,0 +1,329 @@
+# Hindsight Memory Plugin for Claude Code
+
+Biomimetic long-term memory for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) using [Hindsight](https://vectorize.io/hindsight). Automatically captures conversations and intelligently recalls relevant context — a complete port of [`hindsight-openclaw`](../openclaw/) adapted to Claude Code's hook-based plugin architecture.
+
+## Quick Start
+
+```bash
+# 1. Add the Hindsight marketplace and install the plugin
+claude plugin marketplace add vectorize-io/hindsight
+claude plugin install hindsight-memory
+
+# 2. Configure your LLM provider for memory extraction
+# Option A: OpenAI (auto-detected)
+export OPENAI_API_KEY="sk-your-key"
+
+# Option B: Anthropic (auto-detected)
+export ANTHROPIC_API_KEY="your-key"
+
+# Option C: No API key needed (uses Claude Code's own model — personal/local use only)
+# See: https://vectorize.io/hindsight/developer/models#claude-code-setup-claude-promax
+export HINDSIGHT_LLM_PROVIDER=claude-code
+
+# Option D: Connect to an external Hindsight server instead of running locally
+mkdir -p ~/.hindsight
+echo '{"hindsightApiUrl": "https://your-hindsight-server.com"}' > ~/.hindsight/claude-code.json
+
+# 3. Start Claude Code — the plugin activates automatically
+claude
+```
+
+That's it! The plugin will automatically start capturing and recalling memories.
+
+## Features
+
+- **Auto-recall** — on every user prompt, queries Hindsight for relevant memories and injects them as context (invisible to the chat transcript, visible to Claude)
+- **Auto-retain** — after every response (or every N turns), extracts and retains conversation content to Hindsight for long-term storage
+- **Daemon management** — can auto-start/stop `hindsight-embed` locally or connect to an external Hindsight server
+- **Dynamic bank IDs** — supports per-agent, per-project, or per-session memory isolation
+- **Channel-agnostic** — works with Claude Code Channels (Telegram, Discord, Slack) or interactive sessions
+- **Zero dependencies** — pure Python stdlib, no pip install required
+
+## Architecture
+
+The plugin uses all four Claude Code hook events:
+
+| Hook | Event | Purpose |
+|------|-------|---------|
+| `session_start.py` | `SessionStart` | Health check — verify Hindsight is reachable |
+| `recall.py` | `UserPromptSubmit` | **Auto-recall** — query memories, inject as `additionalContext` |
+| `retain.py` | `Stop` | **Auto-retain** — extract transcript, POST to Hindsight (async) |
+| `session_end.py` | `SessionEnd` | Cleanup — stop auto-managed daemon if started |
+
+### Library Modules
+
+| Module | Purpose |
+|--------|---------|
+| `lib/client.py` | Hindsight REST API client (stdlib `urllib`) |
+| `lib/config.py` | Configuration loader (settings.json + env overrides) |
+| `lib/daemon.py` | `hindsight-embed` daemon lifecycle (start/stop/health) |
+| `lib/bank.py` | Bank ID derivation + mission management |
+| `lib/content.py` | Content processing (transcript parsing, memory formatting, tag stripping) |
+| `lib/state.py` | File-based state persistence with `fcntl` locking |
+| `lib/llm.py` | LLM provider auto-detection for daemon mode |
+
+### How Recall Works
+
+1. User sends a prompt → `UserPromptSubmit` hook fires
+2. Plugin resolves Hindsight API URL (external, local, or auto-start daemon)
+3. Derives bank ID (static or dynamic from project context)
+4. Composes query from current prompt + optional prior turns
+5. Calls Hindsight recall API
+6. Formats memories into `<hindsight_memories>` block
+7. Outputs via `hookSpecificOutput.additionalContext` — Claude sees it, user doesn't
+
+### How Retain Works
+
+1. Claude responds → `Stop` hook fires (async, non-blocking)
+2. Reads conversation transcript from Claude Code's JSONL file
+3. Applies chunked retention logic (every N turns with sliding window)
+4. Strips `<hindsight_memories>` tags to prevent feedback loops
+5. Extracts text from channel messages (Telegram reply tool calls, etc.)
+6. POSTs formatted transcript to Hindsight retain API
+
+## Connection Modes
+
+The plugin supports three connection modes, matching the Openclaw plugin:
+
+### 1. External API (recommended for production)
+
+Connect to a running Hindsight server (cloud or self-hosted). No local LLM needed — the server handles fact extraction.
+
+```json
+{
+  "hindsightApiUrl": "https://your-hindsight-server.com",
+  "hindsightApiToken": "your-token"
+}
+```
+
+### 2. Local Daemon (auto-managed)
+
+The plugin automatically starts and stops `hindsight-embed` via `uvx`. Requires an LLM provider API key for local fact extraction.
+
+```json
+{
+  "hindsightApiUrl": "",
+  "apiPort": 9077
+}
+```
+
+Set an LLM provider:
+```bash
+export OPENAI_API_KEY="sk-your-key"      # Auto-detected, uses gpt-4o-mini
+# or
+export ANTHROPIC_API_KEY="your-key"       # Auto-detected, uses claude-3-5-haiku
+```
+
+### 3. Existing Local Server
+
+If you already have `hindsight-embed` running, leave `hindsightApiUrl` empty and set `apiPort` to match your server's port. The plugin will detect it automatically.
+
+## Configuration
+
+All settings live in `~/.hindsight/claude-code.json`. Every setting can also be overridden via environment variables. The plugin ships with sensible defaults — you only need to configure what you want to change.
+
+**Loading order** (later entries win):
+1. Built-in defaults (hardcoded in the plugin)
+2. Plugin `settings.json` (ships with the plugin, at `CLAUDE_PLUGIN_ROOT/settings.json`)
+3. User config (`~/.hindsight/claude-code.json` — recommended for your overrides)
+4. Environment variables
+
+---
+
+### Connection & Daemon
+
+These settings control how the plugin connects to the Hindsight API.
+
+| Setting | Env Var | Default | Description |
+|---------|---------|---------|-------------|
+| `hindsightApiUrl` | `HINDSIGHT_API_URL` | `""` (empty) | URL of an external Hindsight API server. When empty, the plugin uses a local daemon instead. |
+| `hindsightApiToken` | `HINDSIGHT_API_TOKEN` | `null` | Authentication token for the external API. Only needed when `hindsightApiUrl` is set. |
+| `apiPort` | `HINDSIGHT_API_PORT` | `9077` | Port used by the local `hindsight-embed` daemon. Change this if you run multiple instances or have a port conflict. |
+| `daemonIdleTimeout` | `HINDSIGHT_DAEMON_IDLE_TIMEOUT` | `0` | Seconds of inactivity before the local daemon shuts itself down. `0` means the daemon stays running until the session ends. |
+| `embedVersion` | `HINDSIGHT_EMBED_VERSION` | `"latest"` | Which version of `hindsight-embed` to install via `uvx`. Pin to a specific version (e.g. `"0.5.2"`) for reproducibility. |
+| `embedPackagePath` | `HINDSIGHT_EMBED_PACKAGE_PATH` | `null` | Local filesystem path to a `hindsight-embed` checkout. When set, the plugin runs from this path instead of installing via `uvx`. Useful for development. |
+
+---
+
+### LLM Provider (local daemon only)
+
+These settings configure which LLM the local daemon uses for fact extraction. They are **ignored** when connecting to an external API (the server uses its own LLM configuration).
+
+| Setting | Env Var | Default | Description |
+|---------|---------|---------|-------------|
+| `llmProvider` | `HINDSIGHT_LLM_PROVIDER` | auto-detect | Which LLM provider to use. Supported values: `openai`, `anthropic`, `gemini`, `groq`, `ollama`, `openai-codex`, `claude-code`. When omitted, the plugin auto-detects by checking for API key env vars in order: `OPENAI_API_KEY` → `ANTHROPIC_API_KEY` → `GEMINI_API_KEY` → `GROQ_API_KEY`. |
+| `llmModel` | `HINDSIGHT_LLM_MODEL` | provider default | Override the default model for the chosen provider (e.g. `"gpt-4o"`, `"claude-sonnet-4-20250514"`). When omitted, the Hindsight API picks a sensible default for each provider. |
+| `llmApiKeyEnv` | — | provider standard | Name of the environment variable that holds the API key. Normally auto-detected (e.g. `OPENAI_API_KEY` for the `openai` provider). Set this only if your key is in a non-standard env var. |
+
+---
+
+### Memory Bank
+
+A **bank** is an isolated memory store — like a separate "brain." These settings control which bank the plugin reads from and writes to.
+
+| Setting | Env Var | Default | Description |
+|---------|---------|---------|-------------|
+| `bankId` | `HINDSIGHT_BANK_ID` | `"claude_code"` | The bank ID to use when `dynamicBankId` is `false`. All sessions share this single bank. |
+| `bankMission` | `HINDSIGHT_BANK_MISSION` | generic assistant prompt | A short description of the agent's identity and purpose. Sent to Hindsight when creating or updating the bank, and used during recall to contextualize results. |
+| `retainMission` | — | extraction prompt | Instructions for the fact extraction LLM — tells it *what* to extract from conversations (e.g. "Extract technical decisions and user preferences"). |
+| `dynamicBankId` | `HINDSIGHT_DYNAMIC_BANK_ID` | `false` | When `true`, the plugin derives a unique bank ID from context fields (see `dynamicBankGranularity`), giving each combination its own isolated memory. |
+| `dynamicBankGranularity` | — | `["agent", "project"]` | Which context fields to combine when building a dynamic bank ID. Available fields: `agent` (agent name), `project` (working directory), `session` (session ID), `channel` (channel ID), `user` (user ID). |
+| `bankIdPrefix` | — | `""` | A string prepended to all bank IDs — both static and dynamic. Useful for namespacing (e.g. `"prod"` or `"staging"`). |
+| `agentName` | `HINDSIGHT_AGENT_NAME` | `"claude-code"` | Name used for the `agent` field in dynamic bank ID derivation. |
+
+---
+
+### Auto-Recall
+
+Auto-recall runs on every user prompt. It queries Hindsight for relevant memories and injects them into Claude's context as invisible `additionalContext` (the user doesn't see them in the chat transcript).
+
+| Setting | Env Var | Default | Description |
+|---------|---------|---------|-------------|
+| `autoRecall` | `HINDSIGHT_AUTO_RECALL` | `true` | Master switch for auto-recall. Set to `false` to disable memory retrieval entirely. |
+| `recallBudget` | `HINDSIGHT_RECALL_BUDGET` | `"mid"` | Controls how hard Hindsight searches for memories. `"low"` = fast, fewer strategies; `"mid"` = balanced; `"high"` = thorough, slower. Affects latency directly. |
+| `recallMaxTokens` | `HINDSIGHT_RECALL_MAX_TOKENS` | `1024` | Maximum number of tokens in the recalled memory block. Lower values reduce context usage but may truncate relevant memories. |
+| `recallTypes` | — | `["world", "experience"]` | Which memory types to retrieve. `"world"` = general facts; `"experience"` = personal experiences; `"observation"` = raw observations. |
+| `recallContextTurns` | `HINDSIGHT_RECALL_CONTEXT_TURNS` | `1` | How many prior conversation turns to include when composing the recall query. `1` = only the latest user message; higher values give more context but may dilute the query. |
+| `recallMaxQueryChars` | `HINDSIGHT_RECALL_MAX_QUERY_CHARS` | `800` | Maximum character length of the query sent to Hindsight. Longer queries are truncated. |
+| `recallRoles` | — | `["user", "assistant"]` | Which message roles to include when building the recall query from prior turns. |
+| `recallPromptPreamble` | — | built-in string | Text placed above the recalled memories in the injected context block. Customize this to change how Claude interprets the memories. |
+
+---
+
+### Auto-Retain
+
+Auto-retain runs after Claude responds. It extracts the conversation transcript and sends it to Hindsight for long-term storage and fact extraction.
+
+| Setting | Env Var | Default | Description |
+|---------|---------|---------|-------------|
+| `autoRetain` | `HINDSIGHT_AUTO_RETAIN` | `true` | Master switch for auto-retain. Set to `false` to disable memory storage entirely. |
+| `retainMode` | `HINDSIGHT_RETAIN_MODE` | `"full-session"` | Retention strategy. `"full-session"` sends the full conversation transcript (with chunking). |
+| `retainEveryNTurns` | — | `10` | How often to retain. `1` = every turn; `10` = every 10th turn. Higher values reduce API calls but delay memory capture. Values > 1 enable **chunked retention** with a sliding window. |
+| `retainOverlapTurns` | — | `2` | When chunked retention fires, this many extra turns from the previous chunk are included for continuity. Total window size = `retainEveryNTurns + retainOverlapTurns`. |
+| `retainRoles` | — | `["user", "assistant"]` | Which message roles to include in the retained transcript. |
+| `retainToolCalls` | — | `true` | Whether to include tool calls (function invocations and results) in the retained transcript. Captures structured actions like file reads, searches, and code edits. |
+| `retainTags` | — | `["{session_id}"]` | Tags attached to the retained document. Supports template placeholders: `{session_id}`, `{bank_id}`, `{timestamp}`, and `{user_id}` (resolved from `HINDSIGHT_USER_ID` env var; empty string if unset). Tags whose resolved form ends in an empty namespace part (e.g. `"user:"` when `HINDSIGHT_USER_ID` is unset) are dropped from the outgoing request. See [Template variables](#template-variables-for-retaintags-and-retainmetadata) below. |
+| `retainMetadata` | — | `{}` | Arbitrary key-value metadata attached to the retained document. Same template placeholders as `retainTags`. |
+| `retainContext` | — | `"claude-code"` | A label attached to retained memories identifying their source. Useful when multiple integrations write to the same bank. |
+
+#### Template variables for `retainTags` and `retainMetadata`
+
+| Variable | Source |
+|----------|--------|
+| `{session_id}` | Current Claude Code session ID |
+| `{bank_id}` | Resolved bank ID (per `bankGranularity`) |
+| `{timestamp}` | ISO 8601 UTC at retain time |
+| `{user_id}` | Value of `HINDSIGHT_USER_ID` env var (empty string if unset) |
+
+##### Example: per-user memory scoping
+
+```json
+{
+  "retainTags": ["user:{user_id}", "session:{session_id}"]
+}
+```
+
+Set `HINDSIGHT_USER_ID=<opaque-user-id>` in your shell profile (`.zshrc`,
+`.bashrc`, etc.). If the env var is unset, the `user:` tag is dropped from the
+outgoing retain request and the rest of the tags are sent as-is — so the same
+`settings.json` works across machines whether you've set the env var or not.
+
+Downstream, `recall` can filter by `tags=["user:alice"]` to isolate memories
+authored by a specific user from a shared bank.
+
+---
+
+### Debug
+
+| Setting | Env Var | Default | Description |
+|---------|---------|---------|-------------|
+| `debug` | `HINDSIGHT_DEBUG` | `false` | Enable verbose logging to stderr. All log lines are prefixed with `[Hindsight]`. Useful for diagnosing connection issues, recall/retain behavior, and bank ID derivation. |
+
+## Claude Code Channels
+
+With [Claude Code Channels](https://docs.anthropic.com/en/docs/claude-code), Claude Code can operate as a persistent background agent connected to Telegram, Discord, Slack, and other messaging platforms. This plugin gives Channel-based agents the same long-term memory that `hindsight-openclaw` provides for Openclaw agents.
+
+For Channel agents, set these environment variables in your Channel configuration:
+
+```bash
+# Per-channel/per-user memory isolation
+export HINDSIGHT_CHANNEL_ID="telegram-group-12345"
+export HINDSIGHT_USER_ID="user-67890"
+```
+
+And enable dynamic bank IDs:
+
+```json
+{
+  "dynamicBankId": true,
+  "dynamicBankGranularity": ["agent", "channel", "user"]
+}
+```
+
+## Troubleshooting
+
+### Plugin not activating
+
+- Verify installation: check that `.claude-plugin/plugin.json` exists in the installed plugin directory
+- Check Claude Code logs for `[Hindsight]` messages (enable `"debug": true` in `~/.hindsight/claude-code.json`)
+
+### Recall returning no memories
+
+- Verify the Hindsight server is reachable: `curl http://localhost:9077/health`
+- Check that the bank has retained content: memories need at least one retain cycle
+- Try increasing `recallBudget` to `"mid"` or `"high"`
+
+### Daemon not starting
+
+- Ensure `uvx` is installed: `pip install uv` or `brew install uv`
+- Check that an LLM API key is set (required for local daemon)
+- Review daemon logs: `tail -f ~/.hindsight/profiles/claude-code.log`
+- Try starting manually: `uvx hindsight-embed@latest daemon --profile claude-code start`
+
+### High latency on recall
+
+- The recall hook has a 12-second timeout. If Hindsight is slow:
+  - Use `recallBudget: "low"` (fewer retrieval strategies)
+  - Reduce `recallMaxTokens`
+  - Consider using an external API with a faster server
+
+### State file issues
+
+- State is stored in `$CLAUDE_PLUGIN_DATA/state/`
+- To reset: delete the `state/` directory
+- Turn counts, bank missions, and daemon state are tracked here
+
+## Development
+
+To test local changes to `hindsight-embed`:
+
+```json
+{
+  "embedPackagePath": "/path/to/hindsight-embed"
+}
+```
+
+The plugin will use `uv run --directory <path> hindsight-embed` instead of `uvx hindsight-embed@latest`.
+
+To view daemon logs:
+
+```bash
+# Check daemon status
+uvx hindsight-embed@latest daemon --profile claude-code status
+
+# View logs
+tail -f ~/.hindsight/profiles/claude-code.log
+
+# List profiles
+uvx hindsight-embed@latest profile list
+```
+
+## Links
+
+- [Hindsight Documentation](https://vectorize.io/hindsight)
+- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
+- [GitHub Repository](https://github.com/vectorize-io/hindsight)
+
+## License
+
+MIT