techpack.yaml

schemaVersion: 1
identifier: memory
displayName: "The Memory Loop"
description: Persistent project memory that compounds across Claude Code sessions
author: Bruno Guidolim
minMCSVersion: "2026.4.12"

# ---------------------------------------------------------------------------
# Prompts — asked once per project during `mcs sync`, then remembered
# ---------------------------------------------------------------------------
prompts:
  - key: KB_GATE_MODE
    type: select
    label: "KB gate — how strictly must Claude check the KB before delegating?"
    default: "enforce"
    options:
      - value: "warn"
        label: "Warn — remind and log when a sub-agent is spawned without KB findings"
      - value: "enforce"
        label: "Enforce — block the spawn until the KB has been searched this turn"
      - value: "observe"
        label: "Observe — never gate the main thread, just log (sub-agents are still briefed)"
      - value: "off"
        label: "Off — no gating and no sub-agent briefing; prompt reminder only"

# ---------------------------------------------------------------------------
# Components
# ---------------------------------------------------------------------------
components:
  # ── Dependencies ────────────────────────────────────────────────────────
  - id: node
    displayName: Node.js
    description: JavaScript runtime (for npx-based MCP servers)
    brew: node

  - id: gh
    displayName: GitHub CLI
    description: GitHub CLI for PR operations
    brew: gh

  - id: jq
    displayName: jq
    description: Lightweight JSON processor
    brew: jq

  # ── Retrieval engine ────────────────────────────────────────────────────
  # Pinned so no package manager runs inside a hook, and because the rerank and
  # generate neutralisation relies on undocumented fallback behaviour a version
  # bump could change. See CLAUDE.md.
  - id: qmd-install
    displayName: qmd
    description: Local search engine over markdown — no daemon, bundled SQLite + sqlite-vec
    dependencies: [node]
    type: configuration
    shell: "npm install -g @tobilu/qmd@2.8.3"
    doctorChecks:
      # ONE check, deliberately: `isAlreadyInstalled` takes the first *passing*
      # check as proof the component is installed, so any second check that can
      # pass while the pin is unsatisfied silently disables the install.
      # Asserts the version and that the binary loads (`--version` alone never
      # loads the native modules); a qmd that runs proves Node is new enough.
      # Anchored, so 2.8.30 and 12.8.3 do not pass. Keep the literal in step
      # with `shell:` above.
      #
      # The load probe runs against a throwaway index. A bare `qmd status` adopts
      # whatever config it finds by walking up from the working directory, so in a
      # project where the user keeps their own .qmd/ it writes model keys into
      # their config and creates their index.sqlite — the pack must not touch it.
      # `--index` is what skips that discovery; QMD_CONFIG_DIR alone does not,
      # because a discovered .qmd/ outranks it.
      - type: commandExists
        name: "qmd 2.8.3 installed and loading"
        section: MCP Servers
        command: /bin/sh
        args:
          - "-c"
          - |
            PATH="$PATH:/opt/homebrew/bin:/usr/local/bin"
            qmd --version 2>/dev/null | grep -qE '^qmd 2\.8\.3( |$)' || exit 1
            d=$(mktemp -d) || exit 1
            QMD_CONFIG_DIR="$d" INDEX_PATH="$d/probe.sqlite" \
              qmd --index probe status >/dev/null 2>&1
            s=$?; rm -rf "$d"; exit $s
        fixCommand: "npm install -g @tobilu/qmd@2.8.3"

  # One model serves all three of qmd's slots, so this downloads a single file.
  # It runs at sync time on purpose: a first-run download inside the async
  # indexing hook would blow its timeout and leave the index silently empty.
  - id: qmd-model
    displayName: Embedding model
    description: Downloads Qwen3-Embedding-0.6B once (~610 MB, shared across all projects)
    dependencies: [qmd-install]
    type: configuration
    shell: |
      d=$(mktemp -d)
      m="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"
      QMD_CONFIG_DIR="$d" INDEX_PATH="$d/pull.sqlite" \
        QMD_EMBED_MODEL="$m" QMD_GENERATE_MODEL="$m" QMD_RERANK_MODEL="$m" \
        qmd --index pull pull --progress
      s=$?; rm -rf "$d"; exit $s
    doctorChecks:
      - type: commandExists
        name: "Qwen3-Embedding-0.6B downloaded"
        section: AI Models
        command: /bin/sh
        args: ["-c", 'test -f "${XDG_CACHE_HOME:-$HOME/.cache}/qmd/models/hf_Qwen_Qwen3-Embedding-0.6B-Q8_0.gguf"']

  # ── MCP Server ──────────────────────────────────────────────────────────
  # One static command line serves every project, so the index path is computed
  # at launch — Claude spawns MCP servers with the project as their working
  # directory. Using `--index` rather than a project-local .qmd/ is an invariant;
  # see CLAUDE.md.
  #
  # `mkdir -p` because qmd cannot open an index under a directory that does not
  # exist, and the server would fail to connect in every project that has not
  # captured a memory yet — which is every new project. The CLAUDE.md section is
  # installed globally and tells Claude to search before each task, so the tool
  # has to exist everywhere that instruction does. An empty index is honest: the
  # server reports "0 markdown documents" in its own instructions.
  #
  # keep in sync with hooks/sync-memories.sh — it writes the index this opens.
  - id: memory-loop
    description: Semantic search over this project's memories, backed by local embeddings
    isRequired: true
    dependencies: [node, qmd-install, qmd-model]
    mcp:
      command: /bin/sh
      args:
        - "-c"
        - |
          r=$(git rev-parse --show-toplevel 2>/dev/null)
          [ -n "$r" ] || r="${CLAUDE_PROJECT_DIR:-$PWD}"
          d="$r/.claude/.kb-index"
          PATH="$PATH:/opt/homebrew/bin:/usr/local/bin"
          mkdir -p "$d"
          export QMD_CONFIG_DIR="$d" INDEX_PATH="$d/memory-loop.sqlite"
          exec qmd --index memory-loop mcp
    # All three pass quietly when nothing is indexed yet, and each repeats the
    # launcher's project-root ladder verbatim — every check is its own process, so
    # the duplication is forced. Keep the copies identical. The two that invoke qmd
    # also harden PATH, because `mcs doctor` runs them through Process, which has
    # no login shell.
    doctorChecks:
      # Tier 2, and the only thing that would catch a silent model downgrade:
      # a weaker embedding model produces no error, just worse results.
      - type: commandExists
        name: "Memory index uses the expected embedding model"
        section: AI Models
        command: /bin/sh
        args:
          - "-c"
          - |
            r=$(git rev-parse --show-toplevel 2>/dev/null)
            [ -n "$r" ] || r="${CLAUDE_PROJECT_DIR:-$PWD}"
            d="$r/.claude/.kb-index"
            PATH="$PATH:/opt/homebrew/bin:/usr/local/bin"
            command -v qmd >/dev/null 2>&1 || exit 0
            [ -f "$d/memory-loop.yml" ] || exit 0
            export QMD_CONFIG_DIR="$d" INDEX_PATH="$d/memory-loop.sqlite"
            qmd --index memory-loop status 2>/dev/null | grep -q Qwen3-Embedding-0.6B
      # The indexing hook removes its log on success, so the file existing at all
      # means the last run failed or left documents unembedded — and the reason is
      # inside it. Without this, a broken index is only visible as searches quietly
      # returning nothing.
      - type: commandExists
        name: "Memory indexing completed"
        section: AI Models
        command: /bin/sh
        args:
          - "-c"
          - |
            r=$(git rev-parse --show-toplevel 2>/dev/null)
            [ -n "$r" ] || r="${CLAUDE_PROJECT_DIR:-$PWD}"
            [ ! -f "$r/.claude/.kb-index/memory-loop.log" ]
      # Queries with *default* arguments — reranking on — because that is the path
      # this pack neutralises. If an upgrade made that fatal rather than a warning,
      # this check is where it surfaces. The alarm is the timeout `commandExists`
      # does not provide.
      - type: commandExists
        name: "Memory search returns results"
        section: MCP Servers
        command: /bin/sh
        args:
          - "-c"
          - |
            r=$(git rev-parse --show-toplevel 2>/dev/null)
            [ -n "$r" ] || r="${CLAUDE_PROJECT_DIR:-$PWD}"
            d="$r/.claude/.kb-index"
            PATH="$PATH:/opt/homebrew/bin:/usr/local/bin"
            command -v qmd >/dev/null 2>&1 || exit 0
            [ -f "$d/memory-loop.sqlite" ] || exit 0
            export QMD_CONFIG_DIR="$d" INDEX_PATH="$d/memory-loop.sqlite"
            v=$(qmd --index memory-loop status 2>/dev/null |
                  sed -n 's/.*Vectors: *\([0-9][0-9]*\).*/\1/p' | head -1)
            [ "${v:-0}" -gt 0 ] || exit 0
            perl -e 'alarm 30; exec @ARGV' \
              qmd --index memory-loop query "vec: past decisions and learnings" \
              -n 1 --format json 2>/dev/null | grep -q docid

  # ── Skills ──────────────────────────────────────────────────────────────
  - id: skill-continuous-learning
    displayName: continuous-learning skill
    description: Extracts learnings and decisions from sessions into memory
    isRequired: true
    skill:
      source: skills/continuous-learning
      destination: continuous-learning

  - id: skill-memory-audit
    displayName: memory-audit skill
    description: Reviews and audits memories to keep the knowledge base lean and valuable
    skill:
      source: skills/memory-audit
      destination: memory-audit

  # ── Hooks ───────────────────────────────────────────────────────────────
  - id: hook-continuous-learning
    displayName: Continuous learning activator
    description: Reminds to evaluate learnings on each prompt
    isRequired: true
    hookEvent: UserPromptSubmit
    hook:
      source: hooks/continuous-learning-activator.sh
      destination: continuous-learning-activator.sh

  - id: hook-sync-memories
    displayName: Sync memories hook
    description: Indexes memories into the project's search index on session start
    dependencies: [qmd-install, jq]
    hookEvent: SessionStart
    hookAsync: true
    hookTimeout: 120
    hookStatusMessage: "Indexing memories..."
    hook:
      source: hooks/sync-memories.sh
      destination: sync-memories.sh

  - id: hook-reindex-memories
    displayName: Reindex memories hook
    description: Reindexes memories when they have changed mid-session
    dependencies: [qmd-install, jq]
    hookEvent: UserPromptSubmit
    hookAsync: true
    hookTimeout: 120
    hookStatusMessage: "Reindexing memories..."
    hook:
      source: hooks/sync-memories.sh
      destination: sync-memories.sh

  # ── KB-first delegation ─────────────────────────────────────────────────
  # Four registrations of one dispatcher script, which branches on
  # `hook_event_name`. Together they keep KB lookups ahead of delegated discovery,
  # so sub-agents don't rediscover what a memory already recorded. Matchers stay
  # broad on purpose — which agent types count as "discovery" is decided in one
  # place, by `GATED_AGENTS` in the script.
  - id: hook-kb-gate-turn
    displayName: KB gate — turn boundary
    description: Marks each new prompt so the KB check is required again per turn
    dependencies: [jq]
    hookEvent: UserPromptSubmit
    hook:
      source: hooks/kb-gate.sh
      destination: kb-gate.sh
    # Checked because losing this one corrupts the gate rather than disabling it:
    # with no turn stamp the counter reads 0 forever, so every search ever made in
    # the session counts as fresh and the barrier silently widens from per-turn to
    # per-session.
    doctorChecks:
      - type: hookEventExists
        name: "UserPromptSubmit hook registered"
        section: Hooks
        event: UserPromptSubmit

  - id: hook-kb-gate-record
    displayName: KB gate — record searches
    description: Records each KB search so delegated discovery can be checked against it
    dependencies: [jq]
    hookEvent: PostToolUse
    hookMatcher: "mcp__memory-loop__query"
    hook:
      source: hooks/kb-gate.sh
      destination: kb-gate.sh
    # Same reasoning: without this, no search is ever recorded and the gate is
    # pure friction until the budget releases it.
    doctorChecks:
      - type: hookEventExists
        name: "PostToolUse hook registered"
        section: Hooks
        event: PostToolUse

  - id: hook-kb-gate-check
    displayName: KB gate — check sub-agent spawns
    description: Warns or blocks when a discovery sub-agent is spawned without KB findings in its prompt
    dependencies: [jq]
    hookEvent: PreToolUse
    # The spawn tool is `Agent` in current Claude Code and `Task` in older
    # builds. Matching only `Task` silently matches nothing.
    hookMatcher: "Agent|Task"
    hook:
      source: hooks/kb-gate.sh
      destination: kb-gate.sh
    doctorChecks:
      - type: hookEventExists
        name: "PreToolUse hook registered"
        section: Hooks
        event: PreToolUse

  - id: hook-kb-subagent-brief
    displayName: Sub-agent KB brief
    description: Tells discovery sub-agents that the KB exists, so they search it instead of sweeping files
    dependencies: [jq]
    hookEvent: SubagentStart
    hook:
      source: hooks/kb-gate.sh
      destination: kb-gate.sh
    doctorChecks:
      - type: hookEventExists
        name: "SubagentStart hook registered"
        section: Hooks
        event: SubagentStart

  # ── Configuration ───────────────────────────────────────────────────────
  - id: settings
    displayName: Settings
    description: Disables built-in auto-memory in favor of continuous learning system
    settingsFile: config/settings.json

  - id: gitignore
    displayName: Global gitignore
    description: Ignores memory files from version control
    gitignore:
      - ".claude/.memories-last-indexed"
      - ".claude/.kb-index/"
      - ".claude/.kb-gate/"
      - ".claude/.kb-gate.log"

# ---------------------------------------------------------------------------
# Ignore — suppress update notifications for changes to maintainer-only files.
# Does not affect what installs; that is decided by the components above.
# ---------------------------------------------------------------------------
ignore:
  - CLAUDE.md
  - SYNC-BLOCKS.md
  - assets/
  - tests/

# ---------------------------------------------------------------------------
# Templates — CLAUDE.local.md sections
# ---------------------------------------------------------------------------
templates:
  - sectionIdentifier: continuous-learning
    contentFile: templates/continuous-learning.md