|
| 1 | + |
| 2 | +# ZCode |
| 3 | + |
| 4 | +Persistent memory for [ZCode](https://zcode.z.ai) — Z.ai's GLM desktop coding agent — using [Hindsight](https://vectorize.io/hindsight). ZCode embeds the Claude Code agent runtime, so Python hook scripts automatically recall relevant context before each prompt and retain conversations after each turn. No MCP server, no changes to your ZCode workflow. |
| 5 | + |
| 6 | +## Quick Start |
| 7 | + |
| 8 | +> **💡 Recommended: Hindsight Cloud** |
| 9 | +> |
| 10 | +[Sign up free](https://ui.hindsight.vectorize.io/signup) for a Hindsight Cloud API key — no self-hosting, no local daemon to manage. |
| 11 | +```bash |
| 12 | +# Install the CLI |
| 13 | +pip install hindsight-zcode |
| 14 | + |
| 15 | +# Install the hooks (defaults to Hindsight Cloud) |
| 16 | +hindsight-zcode install --api-url https://api.hindsight.vectorize.io --api-token your-api-key |
| 17 | + |
| 18 | +# Restart ZCode — memory is live |
| 19 | +``` |
| 20 | + |
| 21 | +The installer copies the hook scripts to `~/.zcode/hooks/hindsight/`, registers them in `~/.zcode/cli/config.json` (merged with any existing hooks), and creates `~/.hindsight/zcode.json` for your personal config. It never touches your Claude Code config at `~/.claude/settings.json`. |
| 22 | + |
| 23 | +**Self-hosting alternative** — connect to a local `hindsight-embed` daemon by omitting the flags: |
| 24 | + |
| 25 | +```bash |
| 26 | +hindsight-zcode install |
| 27 | +``` |
| 28 | + |
| 29 | +To uninstall: |
| 30 | + |
| 31 | +```bash |
| 32 | +hindsight-zcode uninstall |
| 33 | +``` |
| 34 | + |
| 35 | +### Alternative: install as a ZCode plugin |
| 36 | + |
| 37 | +ZCode can install Hindsight directly from a plugin marketplace — no `pip` step. The same hook scripts ship as a hooks-only Claude Code plugin (`hindsight-zcode`) in the Hindsight marketplace: |
| 38 | + |
| 39 | +``` |
| 40 | +# In ZCode: add the Hindsight marketplace, then install the plugin |
| 41 | +zcode plugins add-marketplace vectorize-io/hindsight |
| 42 | +zcode plugins install hindsight-zcode |
| 43 | +``` |
| 44 | + |
| 45 | +When installed this way, ZCode registers the hooks automatically (no config-file edit). Provide your Hindsight credentials via environment variables (`HINDSIGHT_API_URL`, `HINDSIGHT_API_TOKEN`) or by creating `~/.hindsight/zcode.json`: |
| 46 | + |
| 47 | +```json |
| 48 | +{ |
| 49 | + "hindsightApiUrl": "https://api.hindsight.vectorize.io", |
| 50 | + "hindsightApiToken": "hsk_your_token" |
| 51 | +} |
| 52 | +``` |
| 53 | + |
| 54 | +## Features |
| 55 | + |
| 56 | +- **Auto-recall** — before each prompt, queries Hindsight for relevant memories and injects them as additional context (visible to the model, not the transcript) |
| 57 | +- **Auto-retain** — after each response, stores the turn to Hindsight for future recall |
| 58 | +- **No MCP required** — plain Python hook scripts calling Hindsight's REST API; nothing to run alongside ZCode |
| 59 | +- **Cross-tool memory** — the same Hindsight bank is shared across Claude Code, Cursor, and other Hindsight integrations, so memory follows you between tools |
| 60 | +- **Dynamic bank IDs** — supports per-project memory isolation based on the working directory |
| 61 | +- **Zero runtime dependencies** — the hook scripts are pure Python stdlib; the `pip install` only ships the one-time installer |
| 62 | + |
| 63 | +## Architecture |
| 64 | + |
| 65 | +ZCode embeds the Claude Code agent runtime and reads the standard Claude Code hook schema from its own config namespace, `~/.zcode/cli/config.json` (with `hooks.enabled: true`). The plugin wires three hook events: |
| 66 | + |
| 67 | +| Hook | Event | Purpose | |
| 68 | +|------|-------|---------| |
| 69 | +| `session_start.py` | `SessionStart` | Warm up — verify Hindsight is reachable | |
| 70 | +| `recall.py` | `UserPromptSubmit` | **Auto-recall** — query memories, inject as `additionalContext` | |
| 71 | +| `retain.py` | `Stop` | **Auto-retain** — assemble the turn, POST to Hindsight | |
| 72 | + |
| 73 | +On `UserPromptSubmit`, the hook reads the prompt, queries Hindsight for the most relevant memories, and emits a context block that ZCode injects before sending the turn to the model: |
| 74 | + |
| 75 | +``` |
| 76 | +<hindsight_memories> |
| 77 | +Relevant memories from past conversations... |
| 78 | +Current time - 2026-03-27 09:14 |
| 79 | +
|
| 80 | +- Project uses FastAPI with asyncpg — not SQLAlchemy [world] (2026-03-26) |
| 81 | +- Preferred testing framework: pytest with pytest-asyncio [experience] (2026-03-26) |
| 82 | +</hindsight_memories> |
| 83 | +``` |
| 84 | + |
| 85 | +On `Stop`, the hook pairs the user prompt (captured at `UserPromptSubmit`) with the agent's response and POSTs the turn to Hindsight. ZCode does not provide a `SessionEnd` hook event, so retention rides `Stop` — every turn is stored as it completes. |
| 86 | + |
| 87 | +## Connection Modes |
| 88 | + |
| 89 | +### 1. External API (recommended) |
| 90 | + |
| 91 | +Connect to a running Hindsight server (cloud or self-hosted) via `~/.hindsight/zcode.json`: |
| 92 | + |
| 93 | +```json |
| 94 | +{ |
| 95 | + "hindsightApiUrl": "https://api.hindsight.vectorize.io", |
| 96 | + "hindsightApiToken": "hsk_your_token" |
| 97 | +} |
| 98 | +``` |
| 99 | + |
| 100 | +### 2. Local Daemon |
| 101 | + |
| 102 | +Run `hindsight-embed` locally. The `session_start.py` hook detects it on `apiPort` (default `9077`). The daemon is not auto-started by the plugin — start it separately: |
| 103 | + |
| 104 | +```bash |
| 105 | +uvx hindsight-embed |
| 106 | +``` |
| 107 | + |
| 108 | +Then leave `hindsightApiUrl` empty in your config and the plugin connects to `http://localhost:9077`. |
| 109 | + |
| 110 | +## Configuration |
| 111 | + |
| 112 | +Default config ships in `~/.zcode/hooks/hindsight/settings.json`. For personal overrides that survive updates, create `~/.hindsight/zcode.json`. Most settings can also be overridden via environment variable. |
| 113 | + |
| 114 | +**Loading order** (later entries win): |
| 115 | + |
| 116 | +1. Built-in defaults |
| 117 | +2. Plugin `settings.json` (at `~/.zcode/hooks/hindsight/settings.json`) |
| 118 | +3. User config (`~/.hindsight/zcode.json`) |
| 119 | +4. Environment variables |
| 120 | + |
| 121 | +--- |
| 122 | + |
| 123 | +### Connection |
| 124 | + |
| 125 | +| Setting | Env Var | Default | Description | |
| 126 | +|---------|---------|---------|-------------| |
| 127 | +| `hindsightApiUrl` | `HINDSIGHT_API_URL` | `""` | URL of the Hindsight API server. Empty = local daemon. | |
| 128 | +| `hindsightApiToken` | `HINDSIGHT_API_TOKEN` | `null` | API token for authentication. Required for Hindsight Cloud. | |
| 129 | +| `apiPort` | `HINDSIGHT_API_PORT` | `9077` | Port for the local `hindsight-embed` daemon. | |
| 130 | + |
| 131 | +--- |
| 132 | + |
| 133 | +### Memory Bank |
| 134 | + |
| 135 | +| Setting | Env Var | Default | Description | |
| 136 | +|---------|---------|---------|-------------| |
| 137 | +| `bankId` | `HINDSIGHT_BANK_ID` | `"zcode"` | The bank to read from and write to. All sessions share this bank unless `dynamicBankId` is enabled. | |
| 138 | +| `bankMission` | `HINDSIGHT_BANK_MISSION` | coding assistant prompt | Describes the agent's purpose. Sent when creating or updating the bank. | |
| 139 | +| `dynamicBankId` | `HINDSIGHT_DYNAMIC_BANK_ID` | `false` | When `true`, derives a unique bank ID from `dynamicBankGranularity` fields — useful for per-project isolation. | |
| 140 | +| `agentName` | `HINDSIGHT_AGENT_NAME` | `"zcode"` | Agent name used in dynamic bank ID derivation. | |
| 141 | + |
| 142 | +--- |
| 143 | + |
| 144 | +### Auto-Recall |
| 145 | + |
| 146 | +| Setting | Env Var | Default | Description | |
| 147 | +|---------|---------|---------|-------------| |
| 148 | +| `autoRecall` | `HINDSIGHT_AUTO_RECALL` | `true` | Master switch for auto-recall. | |
| 149 | +| `recallBudget` | `HINDSIGHT_RECALL_BUDGET` | `"mid"` | Search depth: `"low"` (fast), `"mid"` (balanced), `"high"` (thorough). | |
| 150 | +| `recallMaxTokens` | `HINDSIGHT_RECALL_MAX_TOKENS` | `1024` | Token budget for the injected memory block. | |
| 151 | + |
| 152 | +--- |
| 153 | + |
| 154 | +### Auto-Retain |
| 155 | + |
| 156 | +| Setting | Env Var | Default | Description | |
| 157 | +|---------|---------|---------|-------------| |
| 158 | +| `autoRetain` | `HINDSIGHT_AUTO_RETAIN` | `true` | Master switch for auto-retain. | |
| 159 | +| `retainEveryNTurns` | `HINDSIGHT_RETAIN_EVERY_N_TURNS` | `1` | Retain every N turns. Default `1` stores every turn on `Stop`. | |
| 160 | + |
| 161 | +## Relationship to ZCode's built-in memory |
| 162 | + |
| 163 | +ZCode ships its own local, per-project memory (`~/.zcode/cli/memories/`). Hindsight is complementary: it stores memory in a **cloud (or self-hosted) bank that is shared across tools** — the same bank powers Claude Code, Cursor, and other Hindsight integrations — so your context follows you between agents and machines rather than staying local to one ZCode project. |
0 commit comments