{
  "markdown": "# hindsight-skills\n\nAI coding agent skills for [Hindsight](https://github.com/vectorize-io/hindsight) — long-term memory for AI agents.\n\nWorks with **Claude Code**, **Codex**, **Gemini CLI**, **Cursor**, **Kiro**, and **Factory Droid**.\n\nMost agents forget everything between sessions. Hindsight fixes that. It extracts facts, builds entity graphs, and synthesizes mental models from conversations — so your agent remembers users, learns patterns, and gets better over time.\n\nThese skills give your coding agent deep expertise in Hindsight's architecture, so you can go from \"I want my agent to remember things\" to working code in a single session.\n\n## See it work\n\n```\nYou:    /hindsight-architect\n\nClaude: [reads README, package.json, scans directory structure, checks for LLM usage]\n\n        I've looked at your project. It's a Next.js + Python customer support\n        platform with OpenAI calls in the ticket handler and no existing\n        Hindsight config.\n\n        How do you want to approach adding memory?\n        > A) Find opportunities for me\n          B) I already know what I want\n          C) Chat about it\n\nYou:    A\n\nClaude: [examines handlers, routes, LLM calls, data flows]\n\n        Here's how memory would work in this application:\n\n        Memory flow: Retain full ticket conversations per-user, recall past\n        context before each agent response, and synthesize patterns over time.\n\n        Integration points:\n        - api/chat.py:42 — add retain after each conversation turn\n        - api/chat.py:18 — add recall before the LLM call\n        - lib/agent.ts:31 — inject mental model content into system prompt\n\n        What this enables: The agent remembers every user's history, learns\n        each customer's product setup, and detects recurring issues across\n        your entire base.\n\n        Is this the direction you want, or would you adjust the scope?\n\nYou:    This is right. Let's do all of it.\n\nClaude: Are there any of these considerations for your solution?\n        > [ ] Enterprise security\n          [ ] Data privacy / PII\n          [ ] Regulatory compliance\n          [x] None of these\n\nClaude: [presents the three architecture decisions with reasoning]\n        1. What to retain — full conversations, upsert on session_id\n        2. Tag schema — userId:{id}, customerId:{id}\n        3. Mental models — per-user preferences, per-customer usage, cross-customer issues\n\n        Does this design work?\n\nYou:    Yes.\n\nClaude: [asks about deployment: Cloud, Local, or Self-hosted]\n        [asks about recall optimization: Balanced, Completeness, Cost, or Custom]\n\nClaude: # Memory Implementation Plan: support-agent\n        ## Bank Configuration — single bank, per-user tag isolation\n        ## Tag Schema — userId:{id}, customerId:{id}\n        ## Retain Strategy — full conversation upsert with document_id\n        ## Recall Strategy — 10K token budget, any_strict tag matching\n        ## Mental Models — 3 models with auto-refresh\n        ## Client Setup — Python SDK with environment variables\n        ## Implementation Checklist — 9 steps, executable in order\n\n        Ready to implement this plan?\n        > A) Yes, implement it\n          B) Not now\n\nYou:    A\n\nClaude: [installs SDK, adds env vars, wires up retain/recall, creates mental\n        models, runs test scenario — committing as it goes]\n```\n\nA guided conversation. One implementation plan. Then it builds it for you.\n\n## Skills\n\n| Skill | What it does |\n|-------|-------------|\n| `/hindsight-architect` | Memory architecture design. Understands your application, identifies where memory adds value, produces a complete implementation plan, and optionally implements it — bank config, tag schema, retain/recall patterns, mental models, and working code. |\n| `/hindsight-docs` | Full Hindsight reference. API operations, SDK guides, configuration, deployment, cookbook recipes. Your agent searches these docs to answer specific questions or debug your integration. |\n| `/hindsight-upgrade` | Version check and upgrade. Detects when a newer version of hindsight-skills is available and offers to install it. Runs automatically in the background; can also be invoked directly. |\n\n## Install\n\n### Claude Code\n\n```bash\ngit clone --depth 1 https://github.com/vectorize-io/hindsight-skills.git ~/hindsight-skills\ncd ~/hindsight-skills && ./setup\n```\n\nOr add to your repo so teammates get it:\n\n```bash\ngit clone --depth 1 https://github.com/vectorize-io/hindsight-skills.git .claude/skills/hindsight-skills\ncd .claude/skills/hindsight-skills && ./setup\n```\n\n### Codex, Gemini CLI, or Cursor\n\nThese agents all follow the [SKILL.md standard](https://github.com/anthropics/claude-code) and discover skills from `.agents/skills/` or `~/.codex/skills/`.\n\nInstall to one repo:\n\n```bash\ngit clone --depth 1 https://github.com/vectorize-io/hindsight-skills.git .agents/skills/hindsight-skills\ncd .agents/skills/hindsight-skills && ./setup --host codex\n```\n\nInstall globally:\n\n```bash\ngit clone --depth 1 https://github.com/vectorize-io/hindsight-skills.git ~/hindsight-skills\ncd ~/hindsight-skills && ./setup --host codex\n```\n\n### Kiro\n\n```bash\ngit clone --depth 1 https://github.com/vectorize-io/hindsight-skills.git ~/hindsight-skills\ncd ~/hindsight-skills && ./setup --host kiro\n```\n\n### Factory Droid\n\n```bash\ngit clone --depth 1 https://github.com/vectorize-io/hindsight-skills.git ~/hindsight-skills\ncd ~/hindsight-skills && ./setup --host factory\n```\n\n### Auto-detect\n\nIf you have multiple agents installed, setup will find and register with all of them:\n\n```bash\ngit clone --depth 1 https://github.com/vectorize-io/hindsight-skills.git ~/hindsight-skills\ncd ~/hindsight-skills && ./setup --host auto\n```\n\n### npx\n\n```bash\nnpx skills add vectorize-io/hindsight-skills --skill hindsight-architect\nnpx skills add vectorize-io/hindsight-skills --skill hindsight-docs\n```\n\n## What the architect actually knows\n\nThe architect skill isn't a generic template generator. It has deep knowledge of Hindsight internals and makes real architecture decisions:\n\n**Retain** — Knows that `document_id` enables conversation upsert (same ID = replace + re-extract), that content over 3K chars is auto-chunked, that `context` guides extraction quality, and that you send full conversations, not deltas.\n\n**Recall** — Understands the 4 parallel retrieval strategies (semantic, BM25, graph, temporal), how `tags_match` modes work (`any` includes untagged, `any_strict` excludes), and how to size token budgets for your use case.\n\n**Tags** — Knows tags are for identity scoping (userId, customerId), not content classification. Designs tag schemas that enforce memory isolation and prevent cross-user data leakage.\n\n**Mental models** — Understands that `source_query` determines what to synthesize, `tags` filter whose memories to analyze, and `trigger: { refresh_after_consolidation: true }` enables auto-refresh. Designs retrieval strategies so your application can find the right model at runtime.\n\n**Reflect** — Knows this is an expensive agentic loop (up to 10 iterations), not a routine pre-response call. Recommends recall + direct mental model fetch for the pre-response pattern, and reflect only for complex disposition-influenced reasoning.\n\n**Deployment** — Detects your stack (Python, Node.js, framework) and generates code for your specific setup: Hindsight Cloud, self-hosted, or embedded.\n\n## Troubleshooting\n\n**Skills not showing up?** Re-run setup and restart your agent:\n```bash\ncd ~/hindsight-skills && ./setup        # or --host codex, --host auto, etc.\n```\n\n**Slash commands don't autocomplete?** Skills must be at `~/.claude/skills/{name}/SKILL.md` (Claude Code), `~/.codex/skills/{name}/SKILL.md` (Codex/Gemini/Cursor), `~/.kiro/skills/{name}/SKILL.md` (Kiro), or `~/.factory/skills/{name}/SKILL.md` (Factory Droid). The setup script handles this — run it again if something got out of sync.\n\n**Want to update?** The `/hindsight-upgrade` skill checks automatically. To force-check or upgrade manually:\n```bash\ncd ~/hindsight-skills && git pull && ./setup --host auto\n```\n\n## Requirements\n\n- An AI coding agent: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://openai.com/index/codex/), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Cursor](https://cursor.com), [Kiro](https://kiro.dev), or [Factory Droid](https://factory.ai)\n- Either:\n  - A [Hindsight Cloud](https://ui.hindsight.vectorize.io) account — sign up at [ui.hindsight.vectorize.io](https://ui.hindsight.vectorize.io)\n  - A [Hindsight](https://github.com/vectorize-io/hindsight) self-hosted instance. \n\n## License\n\nMIT. Free and open source.\n\n[Documentation](https://hindsight.vectorize.io) · [GitHub](https://github.com/vectorize-io/hindsight) · [Sign up](https://ui.hindsight.vectorize.io)\n",
  "bytes": 8792,
  "sha": "c8532bb8868fa92fc6f68b20a800f4fafad892d2845f57c63414d34ea01b58d9",
  "repo_slug": "vectorize-io/hindsight-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://api.agentalog.com/api/listings/skl_vectorize_io_hindsight_skills_hindsight__2eedbc03/readme"
}