diff --git a/hindsight-docs/docs/sdks/integrations/skills.md b/hindsight-docs/docs/sdks/integrations/skills.md new file mode 100644 index 00000000..41f37c00 --- /dev/null +++ b/hindsight-docs/docs/sdks/integrations/skills.md @@ -0,0 +1,121 @@ +--- +sidebar_position: 3 +--- + +# Skills + +Hindsight provides an Agent Skill that gives AI coding assistants persistent memory across sessions. Skills are reusable prompt templates that agents can load when needed to gain specialized capabilities. + +## Supported Platforms + +| Platform | Skills Directory | +|----------|-----------------| +| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `~/.claude/skills/` | +| [OpenCode](https://github.com/opencode-ai/opencode) | `~/.opencode/skills/` | +| [Codex CLI](https://github.com/openai/codex) | `~/.codex/skills/` | + +## Quick Install + +```bash +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 + +### Install for a Specific Platform + +```bash +# Claude Code +curl -fsSL https://hindsight.vectorize.io/get-skill | bash -s -- --app claude + +# OpenCode +curl -fsSL https://hindsight.vectorize.io/get-skill | bash -s -- --app opencode + +# Codex CLI +curl -fsSL https://hindsight.vectorize.io/get-skill | bash -s -- --app codex +``` + +## What the Skill Provides + +Once installed, your AI assistant gains the ability to: + +- **Retain** - Store user preferences, learnings, and procedure outcomes +- **Recall** - Search for relevant context before starting tasks +- **Reflect** - Synthesize memories into contextual answers + +The skill uses the `hindsight-embed` CLI which runs a lightweight local daemon with an embedded database. + +## How Skills Work + +Skills are **model-invoked**, meaning the AI assistant automatically decides when to use them based on the context of your conversation. You don't need to explicitly trigger the skill. + +The assistant will: +- **Store** when you share preferences, when tasks succeed/fail, or when learnings emerge +- **Recall** before starting non-trivial tasks to get relevant context + +### What Gets Stored + +The skill is optimized to store: + +| Category | Examples | +|----------|----------| +| **User Preferences** | Coding style, tool preferences, language choices | +| **Procedure Outcomes** | Commands that worked, configurations that resolved issues | +| **Learnings** | Bug solutions, workarounds, architecture decisions | + +## Architecture + +``` +AI Coding Assistant + │ + ▼ +Hindsight Skill (SKILL.md) + │ + ▼ +hindsight-embed CLI + │ + ▼ +Local Daemon (auto-started) + │ + ▼ +Embedded PostgreSQL (~/.pg0/hindsight-embed/) +``` + +All data stays on your machine. The daemon auto-starts when needed and shuts down after inactivity. + +## Configuration + +The skill uses configuration stored in `~/.hindsight/config.env`. Reconfigure anytime: + +```bash +uvx hindsight-embed configure +``` + +## Troubleshooting + +### Skill not activating + +The skill activates based on its description matching your request. Try being explicit: +- "Remember that..." triggers storage +- "What do you know about..." triggers recall + +### Daemon issues + +```bash +uvx hindsight-embed daemon status +uvx hindsight-embed daemon logs +``` + +### Reconfigure + +```bash +uvx hindsight-embed configure +``` + +## Requirements + +- Python 3.10+ (for `uvx`) +- An LLM API key (OpenAI, Anthropic, Groq, etc.) diff --git a/hindsight-docs/sidebars.ts b/hindsight-docs/sidebars.ts index 7dd79f18..011694c7 100644 --- a/hindsight-docs/sidebars.ts +++ b/hindsight-docs/sidebars.ts @@ -172,6 +172,11 @@ const sidebars: SidebarsConfig = { id: 'sdks/integrations/litellm', label: 'LiteLLM', }, + { + type: 'doc', + id: 'sdks/integrations/skills', + label: 'Skills', + }, ], }, ], diff --git a/hindsight-docs/static/get-skill b/hindsight-docs/static/get-skill index b3171387..00bb92ba 100755 --- a/hindsight-docs/static/get-skill +++ b/hindsight-docs/static/get-skill @@ -65,77 +65,78 @@ print_banner() { # Embedded SKILL.md content SKILL_CONTENT='--- name: hindsight -description: Give your agent persistent memory that works like human memory. Store facts, preferences, and context that persist across sessions. +description: Store user preferences, learnings from tasks, and procedure outcomes. Use to remember what works and recall context before new tasks. --- # Hindsight Memory Skill -You have access to persistent memory via the `hindsight-embed` CLI. Use it to remember important information about the user and recall it when relevant. - -## Setup (first time only) - -Run: `uvx hindsight-embed configure` - -This will configure your LLM provider and start a local daemon that manages your memory bank. +You have persistent memory via the `hindsight-embed` CLI. **Proactively store learnings and recall context** to provide better assistance. ## Commands -The CLI uses a bank ID to organize memories. Use `default` for general memories or create project-specific banks. - ### Store a memory -Use `memory retain` to store important facts, preferences, decisions, or context: +Use `memory retain` to store what you learn: ```bash -uvx hindsight-embed memory retain default "User prefers dark mode for all UIs" -uvx hindsight-embed memory retain default "Project uses Python 3.11 with FastAPI" --context work -uvx hindsight-embed memory retain myproject "API uses JWT authentication" +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` to search for relevant memories before starting tasks: +Use `memory recall` BEFORE starting tasks to get relevant context: ```bash -uvx hindsight-embed memory recall default "What are the user'"'"'s UI preferences?" -uvx hindsight-embed memory recall default "What tech stack does this project use?" +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` for contextual answers that synthesize multiple memories: +Use `memory reflect` to synthesize context: ```bash -uvx hindsight-embed memory reflect default "How should I set up the dev environment?" +uvx hindsight-embed memory reflect default "How should I approach this task based on past experience?" ``` -### Other commands +## IMPORTANT: When to Store Memories -```bash -uvx hindsight-embed bank list # List all memory banks -uvx hindsight-embed daemon status # Check daemon status -uvx hindsight-embed --help # Full CLI help -``` +**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 -## When to Use +### Learnings from Tasks +- Bugs encountered and their solutions +- Performance optimizations that worked +- Architecture decisions and rationale +- Dependencies or version requirements -### Store memories when you learn: -- User preferences (coding style, tools, UI preferences) -- Project context (tech stack, architecture decisions) -- Personal information the user shares (name, role, company) -- Important decisions or outcomes +## IMPORTANT: When to Recall Memories -### Recall memories when: -- Starting a new task (get relevant context first) -- Making decisions that should consider user preferences -- Working on a project where past context would help +**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. **Be specific**: Store "User prefers 2-space indentation" not "User has preferences" -2. **Recall first**: Before starting tasks, recall relevant context -3. **Use context tags**: Organize with `--context` (work, personal, preferences) -4. **Use project banks**: Create separate banks for different projects +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 ' # Get skills directory for app (bash 3.x compatible) diff --git a/uv.lock b/uv.lock index 73ec7a0f..a84b7dc9 100644 --- a/uv.lock +++ b/uv.lock @@ -1292,7 +1292,7 @@ wheels = [ [[package]] name = "hindsight-all" -version = "0.1.15" +version = "0.1.16" source = { editable = "hindsight" } dependencies = [ { name = "hindsight-api" }, @@ -1316,7 +1316,7 @@ provides-extras = ["test"] [[package]] name = "hindsight-api" -version = "0.1.15" +version = "0.1.16" source = { editable = "hindsight-api" } dependencies = [ { name = "alembic" }, @@ -1422,7 +1422,7 @@ dev = [ [[package]] name = "hindsight-client" -version = "0.1.15" +version = "0.1.16" source = { editable = "hindsight-clients/python" } dependencies = [ { name = "aiohttp" }, @@ -1456,7 +1456,7 @@ provides-extras = ["test"] [[package]] name = "hindsight-dev" -version = "0.1.15" +version = "0.1.16" source = { editable = "hindsight-dev" } dependencies = [ { name = "hindsight-api" }, @@ -1491,7 +1491,7 @@ dev = [ [[package]] name = "hindsight-embed" -version = "0.1.0" +version = "0.1.16" source = { editable = "hindsight-embed" } dependencies = [ { name = "httpx" },