hindsight-cc

hindsight-cc

A Claude Code plugin that provides persistent memory across conversations using the Hindsight vector database.

Installation

IMPORTANT Set the LLM provider, model, and token in your environment before installing in claude code.

Install directly from the GitHub marketplace:

claude plugin add gcswan/hindsight-cc

After installation, the first time you try to run Claude it will take longer than usual as it's installing dependencies.

To verify installation:

claude plugin list

Features

• Automatic Memory Injection: Relevant context from past conversations is automatically injected into your prompts
• Prompt Retention: User prompts are stored for future semantic search
• Transcript Retention: Complete conversation segments are stored at session end
• Per-Project Isolation: Each project has its own memory bank
• Automatic Server Management: Hindsight Docker container starts automatically when you begin a session

Requirements

• Docker installed and running
• Python 3.10+

# Groq (recommended for fast inference)
export HINDSIGHT_API_LLM_PROVIDER=groq
export HINDSIGHT_API_LLM_API_KEY=gsk_xxxxxxxxxxxx
export HINDSIGHT_API_LLM_MODEL=openai/gpt-oss-20b
# For free tier users: override to on_demand if you get service_tier errors
# export HINDSIGHT_API_LLM_GROQ_SERVICE_TIER=on_demand

# OpenAI
export HINDSIGHT_API_LLM_PROVIDER=openai
export HINDSIGHT_API_LLM_API_KEY=sk-xxxxxxxxxxxx
export HINDSIGHT_API_LLM_MODEL=gpt-4o

# Gemini
export HINDSIGHT_API_LLM_PROVIDER=gemini
export HINDSIGHT_API_LLM_API_KEY=xxxxxxxxxxxx
export HINDSIGHT_API_LLM_MODEL=gemini-2.0-flash

# Anthropic
export HINDSIGHT_API_LLM_PROVIDER=anthropic
export HINDSIGHT_API_LLM_API_KEY=sk-ant-xxxxxxxxxxxx
export HINDSIGHT_API_LLM_MODEL=claude-sonnet-4-20250514

# Ollama (local, no API key)
export HINDSIGHT_API_LLM_PROVIDER=ollama
export HINDSIGHT_API_LLM_BASE_URL=http://localhost:11434/v1
export HINDSIGHT_API_LLM_MODEL=llama3

# LM Studio (local, no API key)
export HINDSIGHT_API_LLM_PROVIDER=lmstudio
export HINDSIGHT_API_LLM_BASE_URL=http://localhost:1234/v1
export HINDSIGHT_API_LLM_MODEL=your-local-model

# OpenAI-compatible endpoint
export HINDSIGHT_API_LLM_PROVIDER=openai
export HINDSIGHT_API_LLM_BASE_URL=https://your-endpoint.com/v1
export HINDSIGHT_API_LLM_API_KEY=your-api-key
export HINDSIGHT_API_LLM_MODEL=your-model-name

Usage

Once installed, the plugin works automatically:

1. On session start: Dependencies are installed and Hindsight server is started if not already running
2. On each prompt: Your prompt is stored, and relevant memories are injected
3. On session end: The conversation transcript is stored

Slash Commands

• /hindsight-cc:memory-search <query> - Search your project's memory bank
• /hindsight-cc:memory-status - Check server status and bank info

How It Works

Memory Bank System

Each project gets its own isolated memory bank based on git repository identity (when available) or project path. The plugin auto-detects the project directory from git root or current working directory - no environment variables needed.

Git-based (preferred): Extracts owner/repo from git remote origin

• Any clone of gcswan/hindsight-cc → claude-code--gcswan-hindsight-cc
• Same memories across all paths: /home/user/hindsight-cc, /mnt/work/hindsight-cc, etc.

Path-based (fallback): Uses last 2 path components when not in a git repo

• /home/user/code/myapp → claude-code--code-myapp
• /projects/demo → claude-code--projects-demo

This ensures working on the same repository from different paths shares the same memory bank.

Hook Flow

1. SessionStart: Starts Hindsight server if not running
2. UserPromptSubmit:
   • Stores the prompt for future search
   • Queries for relevant memories and injects them
3. Stop: Stores the conversation transcript

Memory Format

Memories are injected as:

<hindsight-memories>
memory text 1
memory text 2
</hindsight-memories>

Configuration

Environment Variables