hindsight-skills

AI coding agent skills for Hindsight — long-term memory for AI agents.

Works with Claude Code, Codex, Gemini CLI, Cursor, Kiro, and Factory Droid.

Most 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.

These 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.

See it work

You:    /hindsight-architect

Claude: [reads README, package.json, scans directory structure, checks for LLM usage]

        I've looked at your project. It's a Next.js + Python customer support
        platform with OpenAI calls in the ticket handler and no existing
        Hindsight config.

        How do you want to approach adding memory?
        > A) Find opportunities for me
          B) I already know what I want
          C) Chat about it

You:    A

Claude: [examines handlers, routes, LLM calls, data flows]

        Here's how memory would work in this application:

        Memory flow: Retain full ticket conversations per-user, recall past
        context before each agent response, and synthesize patterns over time.

        Integration points:
        - api/chat.py:42 — add retain after each conversation turn
        - api/chat.py:18 — add recall before the LLM call
        - lib/agent.ts:31 — inject mental model content into system prompt

        What this enables: The agent remembers every user's history, learns
        each customer's product setup, and detects recurring issues across
        your entire base.

        Is this the direction you want, or would you adjust the scope?

You:    This is right. Let's do all of it.

Claude: Are there any of these considerations for your solution?
        > [ ] Enterprise security
          [ ] Data privacy / PII
          [ ] Regulatory compliance
          [x] None of these

Claude: [presents the three architecture decisions with reasoning]
        1. What to retain — full conversations, upsert on session_id
        2. Tag schema — userId:{id}, customerId:{id}
        3. Mental models — per-user preferences, per-customer usage, cross-customer issues

        Does this design work?

You:    Yes.

Claude: [asks about deployment: Cloud, Local, or Self-hosted]
        [asks about recall optimization: Balanced, Completeness, Cost, or Custom]

Claude: # Memory Implementation Plan: support-agent
        ## Bank Configuration — single bank, per-user tag isolation
        ## Tag Schema — userId:{id}, customerId:{id}
        ## Retain Strategy — full conversation upsert with document_id
        ## Recall Strategy — 10K token budget, any_strict tag matching
        ## Mental Models — 3 models with auto-refresh
        ## Client Setup — Python SDK with environment variables
        ## Implementation Checklist — 9 steps, executable in order

        Ready to implement this plan?
        > A) Yes, implement it
          B) Not now

You:    A

Claude: [installs SDK, adds env vars, wires up retain/recall, creates mental
        models, runs test scenario — committing as it goes]

A guided conversation. One implementation plan. Then it builds it for you.

Skills

Skill	What it does
/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.
/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.
/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.

Install

Claude Code

git clone --depth 1 https://github.com/vectorize-io/hindsight-skills.git ~/hindsight-skills
cd ~/hindsight-skills && ./setup

Or add to your repo so teammates get it:

git clone --depth 1 https://github.com/vectorize-io/hindsight-skills.git .claude/skills/hindsight-skills
cd .claude/skills/hindsight-skills && ./setup

Codex, Gemini CLI, or Cursor

These agents all follow the SKILL.md standard and discover skills from .agents/skills/ or ~/.codex/skills/.

Install to one repo:

git clone --depth 1 https://github.com/vectorize-io/hindsight-skills.git .agents/skills/hindsight-skills
cd .agents/skills/hindsight-skills && ./setup --host codex

Install globally:

git clone --depth 1 https://github.com/vectorize-io/hindsight-skills.git ~/hindsight-skills
cd ~/hindsight-skills && ./setup --host codex

Kiro

git clone --depth 1 https://github.com/vectorize-io/hindsight-skills.git ~/hindsight-skills
cd ~/hindsight-skills && ./setup --host kiro

Factory Droid

git clone --depth 1 https://github.com/vectorize-io/hindsight-skills.git ~/hindsight-skills
cd ~/hindsight-skills && ./setup --host factory

Auto-detect

If you have multiple agents installed, setup will find and register with all of them:

git clone --depth 1 https://github.com/vectorize-io/hindsight-skills.git ~/hindsight-skills
cd ~/hindsight-skills && ./setup --host auto

npx

npx skills add vectorize-io/hindsight-skills --skill hindsight-architect
npx skills add vectorize-io/hindsight-skills --skill hindsight-docs

What the architect actually knows

The architect skill isn't a generic template generator. It has deep knowledge of Hindsight internals and makes real architecture decisions:

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.

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.

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.

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.

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.

Deployment — Detects your stack (Python, Node.js, framework) and generates code for your specific setup: Hindsight Cloud, self-hosted, or embedded.

Troubleshooting

Skills not showing up? Re-run setup and restart your agent:

cd ~/hindsight-skills && ./setup        # or --host codex, --host auto, etc.

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.

Want to update? The /hindsight-upgrade skill checks automatically. To force-check or upgrade manually:

cd ~/hindsight-skills && git pull && ./setup --host auto

Requirements

• An AI coding agent: Claude Code, Codex, Gemini CLI, Cursor, Kiro, or Factory Droid
• Either:
  • A Hindsight Cloud account — sign up at ui.hindsight.vectorize.io
  • A Hindsight self-hosted instance.

License

MIT. Free and open source.

Documentation · GitHub · Sign up