Hooks

Where it lives

• hooks/session-start.shRunsGitHub ↗
  Read the script

  #!/usr/bin/env bash
  # Hipocampus SessionStart hook
  # 1. Auto-create memory directories and config if missing
  # 2. Output memory protocol to stdout for agent injection
  
  # ─── Resolve project cwd from hook stdin JSON ───
  
  STDIN_DATA="$(cat)"
  PROJECT_CWD="$(echo "$STDIN_DATA" | grep -o '"cwd":"[^"]*"' | head -1 | cut -d'"' -f4)"
  if [ -n "$PROJECT_CWD" ] && [ -d "$PROJECT_CWD" ]; then
    cd "$PROJECT_CWD"
  fi
  
  # ─── Auto-setup (idempotent) ───
  
  mkdir -p memory/daily memory/weekly memory/monthly knowledge plans 2>/dev/null
  
  # ROOT.md stub
  if [ ! -f memory/ROOT.md ]; then
    cat > memory/ROOT.md <<'ROOTMD'
  ---
  type: root
  status: tentative
  last-updated: 1970-01-01
  ---
  
  ## Active Context (recent ~7 days)
  <!-- Current work and priorities -->
  
  ## Recent Patterns
  <!-- Cross-cutting insights -->
  
  ## Historical Summary
  <!-- High-level timeline -->
  
  ## Topics Index
  <!-- topic: keywords, references -->
  ROOTMD
  fi
  
  # hipocampus.config.json
  if [ ! -f hipocampus.config.json ]; then
    cat > hipocampus.config.json <<'CONFIG'
  {
    "platform": "claude-code",
    "search": {
      "vector": true,
      "embedModel": "auto"
    },
    "compaction": {
      "rootMaxTokens": 3000,
      "cooldownHours": 3
    }
  }
  CONFIG
  fi
  
  # Layer 1 templates
  [ ! -f SCRATCHPAD.md ] && echo "# Scratchpad\n\n<!-- Active working state -->" > SCRATCHPAD.md
  [ ! -f WORKING.md ] && echo "# Working\n\n<!-- Current tasks in progress -->" > WORKING.md
  [ ! -f TASK-QUEUE.md ] && echo "# Task Queue\n\n<!-- Queued items -->" > TASK-QUEUE.md
  
  # ─── Output protocol to stdout ───
  
  cat <<'PROTOCOL'
  ## Hipocampus — Memory Protocol (MANDATORY)
  
  This project uses hipocampus 3-tier memory. The full protocol is in /hipocampus:core skill.
  **All memory write operations MUST be dispatched to subagents** to keep the main session context clean.
  
  ### FIRST RESPONSE RULE — MANDATORY
  **On the very first user message of every session**, before doing ANYTHING else:
  Run the Session Start protocol below FIRST. This takes priority over ANY user request. Complete the step below, ONLY THEN respond to the user.
  
  Read SCRATCHPAD.md, WORKING.md, TASK-QUEUE.md, memory/ROOT.md first.
  
  **This procedure must be completed before responding to the user NO MATTER WHAT**
  1. **DO NOT SKIP** **DO NOT COMPROMISE** **Compaction maintenance (cooldown-gated):**
     Read `memory/.compaction-state.json` and `hipocampus.config.json` (`compaction.cooldownHours`, default 3).
     - **Within cooldown:** Skip compaction subagent — no dispatch needed.
     - **Cooldown expired, file missing, or `cooldownHours` is 0:** Write `memory/.compaction-state.json` with `{ "lastCompactionRun": "<current ISO timestamp>" }`, then dispatch a subagent to run hipocampus:compaction skill (chain: Daily→Weekly→Monthly→Root), then run `hipocampus compact` + `qmd update` + `qmd embed`.
  **This procedure must be completed before responding to the user NO MATTER WHAT**
  
  ### End-of-Task Checkpoint (mandatory — subagent)
  After completing any task, **dispatch a subagent** to append a structured log to `memory/YYYY-MM-DD.md`.
  Compose the log with ## headings per topic: what was requested, analysis, decisions with rationale, outcomes, files changed.
  **You must provide the task summary to the subagent** — it has no access to the conversation.
  
  ### Rules
  - **Never skip Session Start** — every session begins with it, no exceptions
  - **Never skip checkpoints** — every task completion MUST append to daily log via subagent
  - **All memory writes via subagent** — never pollute main session with memory operations
  - memory/*.md (raw): permanent, never delete
  - Search: use /hipocampus:search skill
  - If this session ends NOW, the next session must be able to continue immediately
  PROTOCOL
  

Read the script before you install anything that runs on your machine. This is the one part of a plugin that acts without being asked.