diff --git a/hindsight-docs/docs/sdks/integrations/skills.md b/hindsight-docs/docs/sdks/integrations/skills.md index 41f37c00..9af37e1e 100644 --- a/hindsight-docs/docs/sdks/integrations/skills.md +++ b/hindsight-docs/docs/sdks/integrations/skills.md @@ -14,6 +14,15 @@ Hindsight provides an Agent Skill that gives AI coding assistants persistent mem | [OpenCode](https://github.com/opencode-ai/opencode) | `~/.opencode/skills/` | | [Codex CLI](https://github.com/openai/codex) | `~/.codex/skills/` | +## Deployment Modes + +The skill supports two deployment modes: + +| Mode | Best For | Data Location | +|------|----------|---------------| +| **Local** | Individual developers | Your machine (`~/.pg0/`) | +| **Cloud** | Teams sharing knowledge | Hindsight Cloud | + ## Quick Install ```bash @@ -22,13 +31,14 @@ curl -fsSL https://hindsight.vectorize.io/get-skill | bash The installer will: 1. Prompt you to select your AI coding assistant -2. Run the LLM provider configuration -3. Install the skill to the appropriate directory +2. Select deployment mode (local or cloud) +3. Configure the appropriate settings +4. Install the skill to the appropriate directory ### Install for a Specific Platform ```bash -# Claude Code +# Claude Code (interactive mode selection) curl -fsSL https://hindsight.vectorize.io/get-skill | bash -s -- --app claude # OpenCode @@ -38,6 +48,13 @@ curl -fsSL https://hindsight.vectorize.io/get-skill | bash -s -- --app opencode curl -fsSL https://hindsight.vectorize.io/get-skill | bash -s -- --app codex ``` +### Install with Cloud Mode + +```bash +# Direct cloud setup (skips interactive prompts for mode) +curl -fsSL https://hindsight.vectorize.io/get-skill | bash -s -- --app claude --mode cloud +``` + ## What the Skill Provides Once installed, your AI assistant gains the ability to: @@ -68,6 +85,8 @@ The skill is optimized to store: ## Architecture +### Local Mode + ``` AI Coding Assistant │ @@ -86,7 +105,29 @@ Embedded PostgreSQL (~/.pg0/hindsight-embed/) All data stays on your machine. The daemon auto-starts when needed and shuts down after inactivity. -## Configuration +### Cloud Mode + +``` +AI Coding Assistant + │ + ▼ +Hindsight Skill (SKILL.md) + │ + ▼ +hindsight-cli + │ + ▼ +Hindsight Cloud API (https://api.hindsight.vectorize.io) + │ + ▼ +Shared Memory Bank (team-accessible) +``` + +Data is stored in Hindsight Cloud and shared across your team. All team members with the same bank ID can access shared memories. + +--- + +## Local Mode Setup The skill uses configuration stored in `~/.hindsight/config.env`. Reconfigure anytime: @@ -94,6 +135,110 @@ The skill uses configuration stored in `~/.hindsight/config.env`. Reconfigure an uvx hindsight-embed configure ``` +--- + +## Cloud Mode Setup + +Cloud mode connects to [Hindsight Cloud](https://vectorize.io/hindsight/cloud), allowing teams to share memories about a codebase. When one team member learns something, everyone benefits. + +### Prerequisites + +1. A Hindsight Cloud account ([request access](https://vectorize.io/hindsight/cloud)) +2. An API key from your team admin +3. A bank ID for your project (e.g., `team-acme-frontend`) + +### Installation + +Run the installer with cloud mode: + +```bash +curl -fsSL https://hindsight.vectorize.io/get-skill | bash -s -- --mode cloud +``` + +You'll be prompted for: + +| Setting | Description | Example | +|---------|-------------|---------| +| **Cloud API URL** | Hindsight Cloud endpoint | `https://api.hindsight.vectorize.io` | +| **API Key** | Your authentication key | `hs_xxx...` | +| **Bank ID** | Shared memory bank for your team | `team-acme-frontend` | + +### Configuration Files + +Cloud mode creates two files: + +**`~/.hindsight/config`** — API connection settings (TOML format): +```toml +api_url = "https://api.hindsight.vectorize.io" +api_key = "hs_xxx..." +``` + +**`~/.claude/skills/hindsight/SKILL.md`** — Skill definition with your bank ID baked in. + +### Team Setup + +To set up cloud mode for your team: + +1. **Team admin** creates a bank in Hindsight Cloud (e.g., `team-acme-frontend`) +2. **Team admin** generates API keys for each team member +3. **Each developer** runs the installer with their API key and the shared bank ID +4. All team members now share the same memory bank + +### What to Store in Team Banks + +Cloud mode uses a **shared team bank**. Be thoughtful about what goes in: + +| Type | Examples | How to Store | +|------|----------|--------------| +| **Project conventions** | Linting rules, testing requirements, Node version | `"Project uses ESLint with Airbnb config"` | +| **Team knowledge** | Architecture decisions, common pitfalls, domain logic | `"Auth module requires Redis 7+"` | +| **Individual preferences** | Personal coding style, communication preferences | `"Alice prefers verbose commit messages"` | + +**Key distinction**: Project conventions apply to everyone. Individual preferences should include the person's name so the AI knows when to apply them. + +### Example Workflow + +``` +Day 1: Alice discovers a requirement +───────────────────────────────────── +Alice's AI assistant stores: + "The auth module requires Redis 7+ due to HEXPIRE command usage" + "Alice prefers explicit error handling over silent failures" + +Day 2: Bob starts working on auth +───────────────────────────────── +Bob's AI assistant recalls: + "The auth module requires Redis 7+ due to HEXPIRE command usage" + +Bob avoids the same issue Alice hit! +(Alice's personal preference is stored but won't be applied to Bob) +``` + +### Testing Cloud Connection + +After installation, verify the connection: + +```bash +# Store a test memory +hindsight memory retain team-acme-frontend "Test memory from setup" + +# Recall it +hindsight memory recall team-acme-frontend "test" +``` + +### Switching Between Banks + +If you work on multiple projects, you can have different skills installed for each AI assistant, or manually switch banks: + +```bash +# Environment variable override (temporary) +HINDSIGHT_API_URL=https://api.hindsight.vectorize.io \ +HINDSIGHT_API_KEY=hs_xxx \ +hindsight memory recall different-bank "query" +``` + +For permanent multi-bank setups, reinstall the skill with a different bank ID. + ## Troubleshooting ### Skill not activating @@ -102,20 +247,55 @@ The skill activates based on its description matching your request. Try being ex - "Remember that..." triggers storage - "What do you know about..." triggers recall -### Daemon issues +### Local Mode Issues +**Daemon not starting:** ```bash uvx hindsight-embed daemon status uvx hindsight-embed daemon logs ``` -### Reconfigure - +**Reconfigure LLM provider:** ```bash uvx hindsight-embed configure ``` +### Cloud Mode Issues + +**Authentication errors:** +```bash +# Verify your config +cat ~/.hindsight/config + +# Test connection manually +hindsight bank list +``` + +**Wrong bank ID:** + +Check your SKILL.md file to see which bank ID is configured: +```bash +cat ~/.claude/skills/hindsight/SKILL.md | grep "memory retain" +``` + +To change the bank ID, reinstall the skill: +```bash +curl -fsSL https://hindsight.vectorize.io/get-skill | bash -s -- --mode cloud +``` + +**Network/firewall issues:** +```bash +# Test connectivity to cloud API +curl -I https://api.hindsight.vectorize.io/health +``` + ## Requirements +### Local Mode - Python 3.10+ (for `uvx`) - An LLM API key (OpenAI, Anthropic, Groq, etc.) + +### Cloud Mode +- Python 3.10+ (for `uvx`) +- Hindsight Cloud API key +- Network access to `https://api.hindsight.vectorize.io` diff --git a/hindsight-docs/static/get-skill b/hindsight-docs/static/get-skill index 00bb92ba..fbac63c9 100755 --- a/hindsight-docs/static/get-skill +++ b/hindsight-docs/static/get-skill @@ -6,11 +6,12 @@ # curl -fsSL https://hindsight.vectorize.io/get-skill | bash # # Options: -# --app Target app: claude, opencode, codex +# --app Target app: claude, opencode, codex +# --mode Mode: local (default) or cloud # # Examples: # curl -fsSL https://hindsight.vectorize.io/get-skill | bash -s -- --app claude -# curl -fsSL https://hindsight.vectorize.io/get-skill | bash -s -- --app opencode +# curl -fsSL https://hindsight.vectorize.io/get-skill | bash -s -- --app claude --mode cloud # set -e @@ -62,8 +63,8 @@ print_banner() { echo "" } -# Embedded SKILL.md content -SKILL_CONTENT='--- +# Embedded SKILL.md content for LOCAL mode (uses hindsight-embed with local daemon) +SKILL_CONTENT_LOCAL='--- name: hindsight description: Store user preferences, learnings from tasks, and procedure outcomes. Use to remember what works and recall context before new tasks. --- @@ -139,6 +140,107 @@ uvx hindsight-embed memory reflect default "How should I approach this task base 4. **Recall first**: Always check for relevant context before starting work ' +# Template for CLOUD mode SKILL.md (uses hindsight-cli directly with remote API) +# The BANK_ID placeholder will be replaced during installation +SKILL_CONTENT_CLOUD_TEMPLATE='--- +name: hindsight +description: Store team knowledge, project conventions, and learnings from tasks. Use to remember what works and recall context before new tasks. This is a shared team memory bank. +--- + +# Hindsight Memory Skill (Cloud) + +You have persistent memory via **Hindsight Cloud**. This memory bank is **shared with the team**, so knowledge stored here benefits everyone working on this codebase. + +**Proactively store team knowledge and recall context** to provide better assistance. + +## Commands + +### Store a memory + +Use `memory retain` to store what you learn: + +```bash +hindsight memory retain BANK_ID "Project uses ESLint with Airbnb config and Prettier for formatting" +hindsight memory retain BANK_ID "Running tests requires NODE_ENV=test" --context procedures +hindsight memory retain BANK_ID "Build failed when using Node 18, works with Node 20" --context learnings +hindsight memory retain BANK_ID "Alice prefers verbose commit messages with context" --context preferences +``` + +### Recall memories + +Use `memory recall` BEFORE starting tasks to get relevant context: + +```bash +hindsight memory recall BANK_ID "project conventions and coding standards" +hindsight memory recall BANK_ID "Alice preferences for this project" +hindsight memory recall BANK_ID "what issues have we encountered before" +hindsight memory recall BANK_ID "how does the auth module work" +``` + +### Reflect on memories + +Use `memory reflect` to synthesize context: + +```bash +hindsight memory reflect BANK_ID "How should I approach this task based on past experience?" +``` + +## IMPORTANT: When to Store Memories + +This is a **shared team bank**. Store knowledge that benefits the team. For individual preferences, include the persons name. + +### Project/Team Conventions (shared) +- Coding standards ("Project uses 2-space indentation") +- Required tools and versions ("Project requires Node 20+, PostgreSQL 15+") +- Linting and formatting rules ("ESLint with Airbnb config") +- Testing conventions ("Integration tests require Docker running") +- Branch naming and PR conventions + +### Individual Preferences (attribute to person) +- Personal coding style ("Alice prefers explicit type annotations") +- Communication preferences ("Bob prefers detailed PR descriptions") +- Tool preferences ("Carol uses vim keybindings") + +### Procedure Outcomes +- Steps that successfully completed a task +- Commands that worked (or failed) and why +- Workarounds discovered +- Configuration that resolved issues + +### Learnings from Tasks +- Bugs encountered and their solutions +- Performance optimizations that worked +- Architecture decisions and rationale +- Dependencies or version requirements + +### Team Knowledge +- Onboarding information for new team members +- Common pitfalls and how to avoid them +- Architecture decisions and their rationale +- Integration points with external systems +- Domain knowledge and business logic explanations + +## IMPORTANT: When to Recall Memories + +**Always recall** before: +- Starting any non-trivial task +- Making decisions about implementation +- Suggesting tools, libraries, or approaches +- Writing code in a new area of the project +- When answering questions about the codebase +- When a team member asks how something works + +## Best Practices + +1. **Store immediately**: When you discover something, store it right away +2. **Be specific**: Store "npm test requires --experimental-vm-modules flag" not "tests need a flag" +3. **Include outcomes**: Store what worked AND what did not work +4. **Recall first**: Always check for relevant context before starting work +5. **Think team-first**: Store knowledge that would help other team members +6. **Attribute individual preferences**: Store "Alice prefers X" not just "User prefers X" +7. **Distinguish project vs personal**: Project conventions apply to everyone; personal preferences are per-person +' + # Get skills directory for app (bash 3.x compatible) get_skills_dir() { case "$1" in @@ -161,16 +263,18 @@ get_app_name() { # Parse arguments APP="" +MODE="" show_usage() { - echo "Usage: $0 [--app ]" + echo "Usage: $0 [--app ] [--mode ]" echo "" echo "Options:" - echo " --app Target app: claude, opencode, codex" + echo " --app Target app: claude, opencode, codex" + echo " --mode Mode: local (default) or cloud" echo "" echo "Examples:" echo " $0 --app claude" - echo " $0 --app opencode" + echo " $0 --app claude --mode cloud" exit 1 } @@ -180,6 +284,10 @@ while [[ $# -gt 0 ]]; do APP="$2" shift 2 ;; + --mode) + MODE="$2" + shift 2 + ;; --help|-h) show_usage ;; @@ -233,6 +341,41 @@ fi print_info "Installing for ${BOLD}$APP_NAME${NC}" +# Select mode (local vs cloud) +if [ -z "$MODE" ]; then + if [ -t 0 ] || [ -e /dev/tty ]; then + echo "" + echo -e "${DIM}Select deployment mode:${NC}" + echo "" + echo -e " ${BOLD}1)${NC} Local ${DIM}- Run Hindsight on your machine (default)${NC}" + echo -e " ${BOLD}2)${NC} Cloud ${DIM}- Connect to Hindsight Cloud (for teams)${NC}" + echo "" + if [ -t 0 ]; then + read -p "Enter choice [1]: " mode_choice + else + read -p "Enter choice [1]: " mode_choice /dev/null && ! command -v uvx &> /dev/null; then fi print_success "Python/uvx available" -# Step 2: Configure LLM provider using the CLI -print_step "Configuring LLM provider" +# Configuration depends on mode +if [ "$MODE" = "local" ]; then + # LOCAL MODE: Configure LLM provider using hindsight-embed + print_step "Configuring LLM provider" + + # Install/run hindsight-embed configure + # Redirect stdin from /dev/tty to avoid "not a terminal" warnings + if command -v uvx &> /dev/null; then + uvx hindsight-embed configure "$SKILLS_DIR/hindsight/SKILL.md" + print_success "Installed to $SKILLS_DIR/hindsight/" + + # Done (local)! + echo "" + echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" + echo -e "${GREEN} ✓ Installation Complete!${NC}" + echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" + echo "" + echo -e " The Hindsight skill is now available in ${BOLD}$APP_NAME${NC}." + echo "" + echo -e " ${DIM}Test the CLI:${NC}" + echo -e " ${CYAN}uvx hindsight-embed memory retain default \"Test memory\"${NC}" + echo -e " ${CYAN}uvx hindsight-embed memory recall default \"test\"${NC}" + echo "" + echo -e " ${DIM}$APP_NAME will automatically use the skill when relevant.${NC}" + echo "" + echo -e " ${DIM}Documentation:${NC} ${BLUE}https://hindsight.vectorize.io${NC}" + echo "" -# Install/run hindsight-embed configure -# Redirect stdin from /dev/tty to avoid "not a terminal" warnings -if command -v uvx &> /dev/null; then - uvx hindsight-embed configure "$HINDSIGHT_CONFIG_FILE" << EOF +api_url = "$CLOUD_URL" +api_key = "$CLOUD_API_KEY" +EOF + + # Set restrictive permissions on config file (contains API key) + chmod 600 "$HINDSIGHT_CONFIG_FILE" + + print_success "Saved to $HINDSIGHT_CONFIG_FILE" + + # Install cloud skill with bank ID substituted + print_step "Installing skill to $APP_NAME" + + mkdir -p "$SKILLS_DIR/hindsight" + + # Replace BANK_ID placeholder with actual bank ID + SKILL_CONTENT_CLOUD=$(echo "$SKILL_CONTENT_CLOUD_TEMPLATE" | sed "s/BANK_ID/$CLOUD_BANK_ID/g") + echo "$SKILL_CONTENT_CLOUD" > "$SKILLS_DIR/hindsight/SKILL.md" + print_success "Installed to $SKILLS_DIR/hindsight/" + + # Done (cloud)! + echo "" + echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" + echo -e "${GREEN} ✓ Installation Complete!${NC}" + echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" + echo "" + echo -e " The Hindsight skill is now available in ${BOLD}$APP_NAME${NC}." + echo -e " Connected to: ${CYAN}$CLOUD_URL${NC}" + echo -e " Memory bank: ${CYAN}$CLOUD_BANK_ID${NC}" + echo "" + echo -e " ${DIM}Test the CLI:${NC}" + echo -e " ${CYAN}hindsight memory retain $CLOUD_BANK_ID \"Test memory\"${NC}" + echo -e " ${CYAN}hindsight memory recall $CLOUD_BANK_ID \"test\"${NC}" + echo "" + echo -e " ${DIM}Share this bank ID with your team for shared memories.${NC}" + echo -e " ${DIM}$APP_NAME will automatically use the skill when relevant.${NC}" + echo "" + echo -e " ${DIM}Documentation:${NC} ${BLUE}https://hindsight.vectorize.io${NC}" + echo "" fi - -# Step 3: Install skill to app's skills directory -print_step "Installing skill to $APP_NAME" - -mkdir -p "$SKILLS_DIR/hindsight" - -# Write embedded SKILL.md content -echo "$SKILL_CONTENT" > "$SKILLS_DIR/hindsight/SKILL.md" -print_success "Installed to $SKILLS_DIR/hindsight/" - -# Done! -echo "" -echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" -echo -e "${GREEN} ✓ Installation Complete!${NC}" -echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}" -echo "" -echo -e " The Hindsight skill is now available in ${BOLD}$APP_NAME${NC}." -echo "" -echo -e " ${DIM}Test the CLI:${NC}" -echo -e " ${CYAN}uvx hindsight-embed memory retain default \"Test memory\"${NC}" -echo -e " ${CYAN}uvx hindsight-embed memory recall default \"test\"${NC}" -echo "" -echo -e " ${DIM}$APP_NAME will automatically use the skill when relevant.${NC}" -echo "" -echo -e " ${DIM}Documentation:${NC} ${BLUE}https://hindsight.vectorize.io${NC}" -echo ""