@kitsonk/hindsight-cline

A Cline plugin that gives your agent Hindsight's persistent long-term memory. Drop it in, point it at Hindsight Cloud or a self-hosted server, and the agent gets three memory tools plus automatic recall / retain behavior.

This plugin mirrors the OpenCode and Roo Code integrations on the Hindsight side, but is wired to Cline's AgentPlugin SDK.

Features

• Three explicit tools the agent can call:
  • hindsight_retain — store facts, preferences, decisions, and project context
  • hindsight_recall — search long-term memory for relevant information
  • hindsight_reflect — synthesize a coherent answer from memory
• Auto-recall on session start — relevant memories are injected into the system prompt on the first model call of a session
• Auto-retain at run end — the conversation transcript is written to Hindsight when a run completes
• Anti-feedback-loop guard — a message builder strips injected <hindsight_memories> blocks before retention, so recall output is never re-stored
• Per-project bank isolation by default — bank ID is derived from your working directory
• Cloud or self-hosted — works against Hindsight Cloud and any self-hosted Hindsight server

Install

# From npm
npm install -g @kitsonk/hindsight-cline
cline plugin install npm:@kitsonk/hindsight-cline

# Or from a local clone
git clone https://github.com/kitsonk/hindsight-cline
cd hindsight-cline
npm install
npm run build
cline plugin install /absolute/path/to/hindsight-cline

Configure

Configuration is resolved in this order (later wins):

1. Built-in defaults
2. On-disk JSON at ~/.hindsight/cline.json (override the path with HINDSIGHT_CONFIG_PATH)
3. Environment variables
4. Options passed to the createHindsightPlugin({...}) factory in your own Cline config (highest priority)

Hindsight Cloud (recommended)

Get an API key at ui.hindsight.vectorize.io/connect:

export HINDSIGHT_API_TOKEN="hk-..."

That's it. The plugin defaults to https://api.hindsight.vectorize.io.

Self-hosted

Point the plugin at your local Hindsight server:

export HINDSIGHT_API_URL="http://localhost:8888"
# HINDSIGHT_API_TOKEN is optional for self-hosted setups

Config file

~/.hindsight/cline.json:

{
  "hindsightApiUrl": "http://localhost:8888",
  "hindsightApiToken": "hk-...",
  "autoRecall": true,
  "autoRetain": true,
  "recallBudget": "mid",
  "recallMaxTokens": 1024
}

Environment variables

| Variable | Description | Default | | ----------------------------- | ------------------------------------------------ | ------------------------------------ | | HINDSIGHT_API_URL | Hindsight API base URL | https://api.hindsight.vectorize.io | | HINDSIGHT_API_TOKEN | API key for authentication | (none — required for Cloud) | | HINDSIGHT_BANK_ID | Static memory bank ID (overrides dynamic) | (derived) | | HINDSIGHT_AGENT_NAME | Agent name used in dynamic bank IDs | cline | | HINDSIGHT_AUTO_RECALL | Inject memories on the first model call of a run | true | | HINDSIGHT_AUTO_RETAIN | Retain the transcript when a run completes | true | | HINDSIGHT_RECALL_BUDGET | low | mid | high | mid | | HINDSIGHT_RECALL_MAX_TOKENS | Max tokens for recall results | 1024 | | HINDSIGHT_RECALL_TAGS_MATCH | any | all | any_strict | all_strict | any | | HINDSIGHT_DYNAMIC_BANK_ID | Derive bank ID from working directory | true | | HINDSIGHT_BANK_MISSION | Bank mission / identity (set on first write) | (none) | | HINDSIGHT_DEBUG | Log diagnostics to stderr | false | | HINDSIGHT_CONFIG_PATH | Override the on-disk config file location | ~/.hindsight/cline.json |

Tools

hindsight_retain

Store information in Hindsight's long-term memory.

{
  "content": "User prefers Bun over Node for new projects because of faster install times",
  "context": "team standup, 2025-01-15",
  "tags": ["preferences", "runtime"]
}

The bank mission is automatically configured on the first write per bank when HINDSIGHT_BANK_MISSION is set.

hindsight_recall

Search long-term memory for relevant information. Returns a formatted list of matches plus a count.

{
  "query": "user's runtime preferences",
  "budget": "mid",
  "tags": ["preferences"]
}

hindsight_reflect

Generate a synthesized answer from memory. Unlike hindsight_recall (which returns raw memories), hindsight_reflect asks Hindsight to formulate a coherent answer.

{
  "query": "Summarize what we know about the user's environment and tooling preferences",
  "budget": "low"
}

Auto-features

| Feature | Default | Disable via | | ------------------ | ------- | ---------------------------------------------------- | | Auto-recall | on | autoRecall: false / HINDSIGHT_AUTO_RECALL=false | | Auto-retain | on | autoRetain: false / HINDSIGHT_AUTO_RETAIN=false | | Anti-feedback loop | on | (always active; uses the registered message builder) |

• Auto-recall injects a <hindsight_memories> block into the system prompt on the first model call of a session. The injection is per-session and idempotent. If the recall returns no memories, the system prompt is left untouched.
• Auto-retain writes the conversation transcript to Hindsight as a single document per session when a run completes. The document is upserted on each run, so the bank always holds the latest version.
• Anti-feedback loop ensures the auto-retained transcript never includes the auto-injected memory block.

Bank IDs

By default the plugin uses dynamic bank IDs derived from your working directory using the format cline::<basename>. For example, when run from /Users/me/projects/hindsight-cline, the bank is cline::hindsight-cline. This gives every project its own memory.

To use a fixed bank ID:

export HINDSIGHT_BANK_ID="my-shared-bank"
export HINDSIGHT_DYNAMIC_BANK_ID=false

For multi-user setups (e.g., the same agent serving many users):

export HINDSIGHT_DYNAMIC_BANK_ID=true
export HINDSIGHT_DYNAMIC_BANK_GRANULARITY='["agent","user"]'  # JSON, not yet a top-level env var

See src/bank.ts for the full granularity list (agent, project, gitProject, channel, user).

Programmatic options

If you embed the plugin in a larger Cline config you can pass options directly:

// cline.config.ts
import { createHindsightPlugin } from "@kitsonk/hindsight-cline";

export default createHindsightPlugin({
  apiUrl: "http://localhost:8888",
  apiToken: process.env.HINDSIGHT_API_TOKEN,
  bankId: "research-agent",
  autoRecall: true,
  autoRetain: true,
  recallBudget: "high",
});

These options override both the on-disk config file and the environment variables.

Development

git clone https://github.com/kitsonk/hindsight-cline
cd hindsight-cline
npm install
npm test         # Run unit tests
npm run build    # Build to dist/

License

MIT