diff --git a/hindsight-docs/docs/sdks/integrations/skills.md b/hindsight-docs/docs/sdks/integrations/skills.md index ee99dda0..788e154e 100644 --- a/hindsight-docs/docs/sdks/integrations/skills.md +++ b/hindsight-docs/docs/sdks/integrations/skills.md @@ -25,6 +25,8 @@ The skill supports two deployment modes: ## Quick Install +### Option 1: Interactive Installer (Recommended) + ```bash curl -fsSL https://hindsight.vectorize.io/get-skill | bash ``` @@ -55,6 +57,26 @@ curl -fsSL https://hindsight.vectorize.io/get-skill | bash -s -- --app codex curl -fsSL https://hindsight.vectorize.io/get-skill | bash -s -- --app claude --mode cloud ``` +### Option 2: Using add-skill + +If you use [add-skill](https://add-skill.org/) to manage your agent skills: + +```bash +# For local mode (individual developers) +npx add-skill vectorize-io/hindsight --skill hindsight-local + +# For Hindsight Cloud (teams) +npx add-skill vectorize-io/hindsight --skill hindsight-cloud + +# For self-hosted Hindsight servers +npx add-skill vectorize-io/hindsight --skill hindsight-self-hosted +``` + +On first use, the AI will guide you through the remaining setup: +- **Local**: Run `uvx hindsight-embed configure` to set up your LLM provider +- **Cloud**: Provide your API key and bank ID +- **Self-hosted**: Provide your server URL, API key, and bank ID + ## What the Skill Provides Once installed, your AI assistant gains the ability to: diff --git a/skills/hindsight-cloud/SKILL.md b/skills/hindsight-cloud/SKILL.md new file mode 100644 index 00000000..67d1aa54 --- /dev/null +++ b/skills/hindsight-cloud/SKILL.md @@ -0,0 +1,128 @@ +--- +name: hindsight +description: Store team knowledge, project conventions, and learnings from tasks. Use to remember what works and recall context before new tasks. Connects to Hindsight Cloud. (user) +--- + +# 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. + +## Setup Check (First-Time Only) + +Before using memory commands, verify the Hindsight CLI is configured: + +```bash +cat ~/.hindsight/config +``` + +**If the file doesn't exist or is missing credentials**, help the user set it up: + +1. **Install the CLI** (if `hindsight` command not found): + ```bash + curl -fsSL https://hindsight.vectorize.io/get-cli | bash + ``` + +2. **Create the config file** - ask the user for their **API Key** (get it from https://ui.hindsight.vectorize.io): + ```bash + mkdir -p ~/.hindsight + cat > ~/.hindsight/config << 'EOF' + api_url = "https://api.hindsight.vectorize.io" + api_key = "" + EOF + chmod 600 ~/.hindsight/config + ``` + +3. **Get the bank ID** - ask the user for their team's bank ID (e.g., `team-myproject`) + +After setup, use the bank ID in all commands below. + +## Commands + +Replace `` with the user's actual bank ID (e.g., `team-frontend`). + +### Store a memory + +Use `memory retain` to store what you learn: + +```bash +hindsight memory retain "Project uses ESLint with Airbnb config and Prettier for formatting" +hindsight memory retain "Running tests requires NODE_ENV=test" --context procedures +hindsight memory retain "Build failed when using Node 18, works with Node 20" --context learnings +hindsight memory retain "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 "project conventions and coding standards" +hindsight memory recall "Alice preferences for this project" +hindsight memory recall "what issues have we encountered before" +hindsight memory recall "how does the auth module work" +``` + +### Reflect on memories + +Use `memory reflect` to synthesize context: + +```bash +hindsight memory reflect "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 person's 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 diff --git a/skills/hindsight-local/SKILL.md b/skills/hindsight-local/SKILL.md new file mode 100644 index 00000000..a0ad411f --- /dev/null +++ b/skills/hindsight-local/SKILL.md @@ -0,0 +1,90 @@ +--- +name: hindsight +description: Store user preferences, learnings from tasks, and procedure outcomes. Use to remember what works and recall context before new tasks. (user) +--- + +# Hindsight Memory Skill (Local) + +You have persistent memory via the `hindsight-embed` CLI. **Proactively store learnings and recall context** to provide better assistance. + +## Setup Check (First-Time Only) + +Before using memory commands, verify Hindsight is configured: + +```bash +uvx hindsight-embed daemon status +``` + +**If this fails or shows "not configured"**, run the interactive setup: + +```bash +uvx hindsight-embed configure +``` + +This will prompt for an LLM provider and API key. After setup, the commands below will work. + +## Commands + +### Store a memory + +Use `memory retain` to store what you learn: + +```bash +uvx hindsight-embed memory retain default "User prefers TypeScript with strict mode" +uvx hindsight-embed memory retain default "Running tests requires NODE_ENV=test" --context procedures +uvx hindsight-embed memory retain default "Build failed when using Node 18, works with Node 20" --context learnings +``` + +### Recall memories + +Use `memory recall` BEFORE starting tasks to get relevant context: + +```bash +uvx hindsight-embed memory recall default "user preferences for this project" +uvx hindsight-embed memory recall default "what issues have we encountered before" +``` + +### Reflect on memories + +Use `memory reflect` to synthesize context: + +```bash +uvx hindsight-embed memory reflect default "How should I approach this task based on past experience?" +``` + +## IMPORTANT: When to Store Memories + +**Always store** after you learn something valuable: + +### User Preferences +- Coding style (indentation, naming conventions, language preferences) +- Tool preferences (editors, linters, formatters) +- Communication preferences +- Project conventions + +### 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 + +## 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 + +## 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 diff --git a/skills/hindsight-self-hosted/SKILL.md b/skills/hindsight-self-hosted/SKILL.md new file mode 100644 index 00000000..7ea20fc4 --- /dev/null +++ b/skills/hindsight-self-hosted/SKILL.md @@ -0,0 +1,131 @@ +--- +name: hindsight +description: Store team knowledge, project conventions, and learnings from tasks. Use to remember what works and recall context before new tasks. Connects to a self-hosted Hindsight server. (user) +--- + +# Hindsight Memory Skill (Self-Hosted) + +You have persistent memory via a **self-hosted Hindsight server**. This memory bank can be **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. + +## Setup Check (First-Time Only) + +Before using memory commands, verify the Hindsight CLI is configured: + +```bash +cat ~/.hindsight/config +``` + +**If the file doesn't exist or is missing credentials**, help the user set it up: + +1. **Install the CLI** (if `hindsight` command not found): + ```bash + curl -fsSL https://hindsight.vectorize.io/get-cli | bash + ``` + +2. **Create the config file** - ask the user for: + - **API URL**: Their self-hosted Hindsight server URL (e.g., `https://hindsight.mycompany.com`) + - **API Key**: Their authentication key + + ```bash + mkdir -p ~/.hindsight + cat > ~/.hindsight/config << 'EOF' + api_url = "" + api_key = "" + EOF + chmod 600 ~/.hindsight/config + ``` + +3. **Get the bank ID** - ask the user for their bank ID (e.g., `team-myproject`) + +After setup, use the bank ID in all commands below. + +## Commands + +Replace `` with the user's actual bank ID (e.g., `team-frontend`). + +### Store a memory + +Use `memory retain` to store what you learn: + +```bash +hindsight memory retain "Project uses ESLint with Airbnb config and Prettier for formatting" +hindsight memory retain "Running tests requires NODE_ENV=test" --context procedures +hindsight memory retain "Build failed when using Node 18, works with Node 20" --context learnings +hindsight memory retain "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 "project conventions and coding standards" +hindsight memory recall "Alice preferences for this project" +hindsight memory recall "what issues have we encountered before" +hindsight memory recall "how does the auth module work" +``` + +### Reflect on memories + +Use `memory reflect` to synthesize context: + +```bash +hindsight memory reflect "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 person's 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