/hindsight-docs

ZCode

Persistent memory for ZCode — Z.ai's GLM desktop coding agent — using 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.

View Changelog →

Quick Start

💡 Recommended: Hindsight Cloud

Sign up free for a Hindsight Cloud API key — no self-hosting, no local daemon to manage.

# Install the CLI
pip install hindsight-zcode

# Install the hooks (defaults to Hindsight Cloud)
hindsight-zcode install --api-url https://api.hindsight.vectorize.io --api-token your-api-key

# Restart ZCode — memory is live

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.

Self-hosting alternative — connect to a local hindsight-embed daemon by omitting the flags:

hindsight-zcode install

To uninstall:

hindsight-zcode uninstall

Alternative: install as a ZCode plugin

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:

# In ZCode: add the Hindsight marketplace, then install the plugin
zcode plugins add-marketplace vectorize-io/hindsight
zcode plugins install hindsight-zcode

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:

{
  "hindsightApiUrl": "https://api.hindsight.vectorize.io",
  "hindsightApiToken": "hsk_your_token"
}

Features

• Auto-recall — before each prompt, queries Hindsight for relevant memories and injects them as additional context (visible to the model, not the transcript)
• Auto-retain — after each response, stores the turn to Hindsight for future recall
• No MCP required — plain Python hook scripts calling Hindsight's REST API; nothing to run alongside ZCode
• Cross-tool memory — the same Hindsight bank is shared across Claude Code, Cursor, and other Hindsight integrations, so memory follows you between tools
• Dynamic bank IDs — supports per-project memory isolation based on the working directory
• Zero runtime dependencies — the hook scripts are pure Python stdlib; the pip install only ships the one-time installer

Architecture

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:

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:

<hindsight_memories>
Relevant memories from past conversations...
Current time - 2026-03-27 09:14

- Project uses FastAPI with asyncpg — not SQLAlchemy [world] (2026-03-26)
- Preferred testing framework: pytest with pytest-asyncio [experience] (2026-03-26)
</hindsight_memories>

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.

Connection Modes

1. External API (recommended)

Connect to a running Hindsight server (cloud or self-hosted) via ~/.hindsight/zcode.json:

{
  "hindsightApiUrl": "https://api.hindsight.vectorize.io",
  "hindsightApiToken": "hsk_your_token"
}

2. Local Daemon

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:

uvx hindsight-embed

Then leave hindsightApiUrl empty in your config and the plugin connects to http://localhost:9077.

Configuration

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.

Loading order (later entries win):

1. Built-in defaults
2. Plugin settings.json (at ~/.zcode/hooks/hindsight/settings.json)
3. User config (~/.hindsight/zcode.json)
4. Environment variables

Connection

Memory Bank

Auto-Recall

Auto-Retain

Relationship to ZCode's built-in memory

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.