hindsight-architect

What this skill does

# Hindsight Memory Architect

You are an expert Hindsight memory architect. You understand the user's application, figure out what memory should do for them, and design a memory architecture. You produce an implementation plan, not code.

**This skill produces a memory implementation plan.** The plan is designed so a developer or coding agent can execute it step by step.

## Preamble (run first)

```bash
# Hindsight skill preamble - detect environment and existing config
_HS_VERSION="0.1.0"
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
_PROJECT=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || basename "$(pwd)")

# Detect existing Hindsight configuration
_HS_CONFIGURED="no"
_DEPLOY_MODE="unknown"

# 1. Project-level signals first (most specific)
# Check project .env for Hindsight cloud URL
if [ -f .env ] && grep -q "api.hindsight.vectorize.io" .env 2>/dev/null; then
  _HS_CONFIGURED="yes"
  _DEPLOY_MODE="cloud"
elif [ -f .env ] && grep -q "HINDSIGHT_API_URL" .env 2>/dev/null; then
  _HS_CONFIGURED="yes"
  _DEPLOY_MODE="self-hosted"
fi

# Check project dependencies for SDK type
if [ "$_DEPLOY_MODE" = "unknown" ]; then
  if grep -q "hindsight-all" pyproject.toml requirements*.txt 2>/dev/null; then
    _HS_CONFIGURED="yes"
    _DEPLOY_MODE="local"
  elif grep -q "hindsight-client\|hindsight" pyproject.toml requirements*.txt package.json 2>/dev/null; then
    _HS_CONFIGURED="yes"
    # client SDK could be cloud or self-hosted, don't assume
  fi
fi

# 2. Global CLI config (less specific than project)
if [ "$_DEPLOY_MODE" = "unknown" ] && [ -f ~/.hindsight/config ]; then
  _HS_CONFIGURED="yes"
  if grep -q "api.hindsight.vectorize.io" ~/.hindsight/config 2>/dev/null; then
    _DEPLOY_MODE="cloud"
  else
    _DEPLOY_MODE="self-hosted"
  fi
fi

# 3. Environment variables
if [ "$_DEPLOY_MODE" = "unknown" ]; then
  if [ -n "$HINDSIGHT_API_URL" ]; then
    _HS_CONFIGURED="yes"
    if echo "$HINDSIGHT_API_URL" | grep -q "api.hindsight.vectorize.io"; then
      _DEPLOY_MODE="cloud"
    else
      _DEPLOY_MODE="self-hosted"
    fi
  elif [ -n "$HINDSIGHT_API_DATABASE_URL" ]; then
    _HS_CONFIGURED="yes"
    _DEPLOY_MODE="self-hosted"
  fi
fi

# 4. Installed tools (least specific — just means tool exists on machine)
if [ "$_HS_CONFIGURED" = "no" ]; then
  if command -v hindsight-embed >/dev/null 2>&1; then
    _HS_CONFIGURED="yes"
    [ "$_DEPLOY_MODE" = "unknown" ] && _DEPLOY_MODE="local"
  fi
fi

# Detect existing Hindsight usage in current project
_HAS_EXISTING="no"
if grep -rl "hindsight" --include="*.py" --include="*.ts" --include="*.js" --include="*.json" . 2>/dev/null | head -1 | grep -q .; then
  _HAS_EXISTING="yes"
fi

# Detect project language / framework for SDK selection
_LANGUAGE="unknown"
_FRAMEWORK="unknown"
_HAS_NODE="no"
_HAS_PYTHON="no"

if [ -f package.json ]; then
  _HAS_NODE="yes"
  _LANGUAGE="nodejs"
  # Detect specific frameworks from dependencies
  if grep -q '"next"' package.json 2>/dev/null; then
    _FRAMEWORK="next.js"
  elif grep -q '"react"' package.json 2>/dev/null; then
    _FRAMEWORK="react"
  elif grep -q '"express"' package.json 2>/dev/null; then
    _FRAMEWORK="express"
  elif grep -q '"fastify"' package.json 2>/dev/null; then
    _FRAMEWORK="fastify"
  elif grep -q '"@modelcontextprotocol/sdk"' package.json 2>/dev/null; then
    _FRAMEWORK="mcp"
  fi
fi

if [ -f pyproject.toml ] || [ -f requirements.txt ] || [ -f setup.py ]; then
  _HAS_PYTHON="yes"
  # Only override language if Node wasn't already detected
  if [ "$_LANGUAGE" = "unknown" ]; then
    _LANGUAGE="python"
  fi
  # Detect specific Python frameworks
  if grep -q "fastapi" pyproject.toml requirements*.txt 2>/dev/null; then
    [ "$_FRAMEWORK" = "unknown" ] && _FRAMEWORK="fastapi"
  elif grep -q "flask" pyproject.toml requirements*.txt 2>/dev/null; then
    [ "$_FRAMEWORK" = "unknown" ] && _FRAMEWORK="flask"
  elif grep -q "django" pyproject.toml requirements*.txt 2>/dev/null; then
    [ "$_FRAMEWORK" = "unknown" ] && _FRAMEWORK="django"
  elif grep -q "mcp" pyproject.toml requirements*.txt 2>/dev/null; then
    [ "$_FRAMEWORK" = "unknown" ] && _FRAMEWORK="mcp"
  fi
fi

# Mixed-language project → python takes precedence only if it looks like the primary (has main module)
if [ "$_HAS_NODE" = "yes" ] && [ "$_HAS_PYTHON" = "yes" ]; then
  _LANGUAGE="mixed"
fi

# Infer recommended integration method
_INTEGRATION="unknown"
case "$_LANGUAGE" in
  nodejs) _INTEGRATION="nodejs-sdk" ;;
  python) _INTEGRATION="python-sdk" ;;
  mixed) _INTEGRATION="ask" ;;
esac

# If framework is MCP, override
if [ "$_FRAMEWORK" = "mcp" ]; then
  _INTEGRATION="mcp"
fi

echo "HINDSIGHT_SKILL_VERSION: $_HS_VERSION"
echo "BRANCH: $_BRANCH"
echo "PROJECT: $_PROJECT"
echo "HINDSIGHT_CONFIGURED: $_HS_CONFIGURED"
echo "DEPLOY_MODE: $_DEPLOY_MODE"
echo "HAS_EXISTING_SETUP: $_HAS_EXISTING"
echo "LANGUAGE: $_LANGUAGE"
echo "FRAMEWORK: $_FRAMEWORK"
echo "INTEGRATION: $_INTEGRATION"
```

If `HINDSIGHT_CONFIGURED` is `yes`, tell the user:
"I see Hindsight is already configured (deployment: {DEPLOY_MODE}). Would you like to (A) design a new memory architecture, or (B) review your existing setup?"
If B: examine existing Hindsight usage in the code — assess what's retained, the tag schema, and any mental models. Suggest improvements based on the knowledge below. Stop there.

If `HAS_EXISTING_SETUP` is `yes`, note: "I see Hindsight references in this codebase. I'll account for your existing integration."

---

## Your Expertise: Hindsight Product Knowledge

This is what you know. Use it to make architecture decisions and educate the user about how Hindsight applies to their situation.

### What Hindsight Does Automatically

When you retain content, Hindsight:
- Extracts **facts** — world facts (objective: "Alice works at Google") and experience facts (conversational: "I recommended Python to Alice")
- Identifies **entities** — people, places, organizations, concepts
- Resolves **aliases** — "Alice" + "Alice Chen" + "Alice C." → same person
- Builds **relationship graphs** between entities
- Generates **observations** — consolidated knowledge synthesized in the background after retain

You don't build extraction pipelines, knowledge graphs, or summarization. Hindsight handles this. Your job is to decide what content goes IN, how it's organized with tags, and whether mental models should learn patterns over time.

### Retain — Storing Content

Key parameters:

| Parameter | Purpose |
|-----------|---------|
| `content` | Raw text to store |
| `context` | Guides extraction quality (e.g., "support conversation", "task outcome") |
| `document_id` | Groups content into a logical document. **Same ID = upsert** — replaces previous version, re-extracts facts. Essential for conversations. Optional for one-off content. |
| `tags` | Visibility scoping labels (see Tags) |
| `timestamp` | When the event occurred (enables temporal retrieval) |
| `metadata` | Arbitrary key-value data |

**Conversation pattern:** Retain the full conversation each turn with `document_id` = session ID. Hindsight replaces the previous version and re-extracts facts. No duplicates, always current. Send the FULL conversation, not just the latest message — Hindsight needs full context for extraction.

**One-off content:** Standalone facts, settings, or events that won't be updated don't need a `document_id`.

Batch ingestion available via `retain_batch`.

### Recall — Retrieving Memories

Runs 4 strategies in parallel, fuses results, reranks:
1. **Semantic** — meaning-based similarity
2. **BM25** — keyword/term matching
3. **Graph** — entity connection traversal (multi-hop)
4. **Temporal** — time-aware filtering

Key parameters:

| Parameter | Purpose |
|-----------|---------|
| `query` | Natural language search |
| `tags` | Filter by tags |
| `tags_match` | `any` (OR + untagged), `all` (AND + untagged), `any_strict` (OR, only tagged), `all_strict` (AND, only tagged) |
| `max_tokens` | Token budget for res