techpack.yaml

schemaVersion: 1
identifier: memory
displayName: "Memory"
description: Persistent memory and knowledge management for Claude Code
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: "warn"
    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

  - id: ollama
    displayName: Ollama
    description: Local LLM runtime (compatible with all Apple Silicon)
    type: configuration
    shell: "curl -fsSL https://ollama.com/install.sh | sh"
    shellInteractive: true
    doctorChecks:
      - type: commandExists
        name: "Ollama installed"
        section: AI Models
        command: ollama
        args: ["--version"]

  - id: ollama-service
    displayName: Ollama service
    description: Ensure Ollama is running
    type: configuration
    dependencies: [ollama]
    shell: "open /Applications/Ollama.app --args hidden"
    doctorChecks:
      - type: commandExists
        name: "Ollama service running"
        section: AI Models
        command: curl
        args: ["-sf", "http://localhost:11434/api/tags"]
        fixCommand: "open /Applications/Ollama.app --args hidden"

  - id: ollama-nomic-embed
    displayName: nomic-embed-text model
    description: Embedding model for docs-mcp-server
    type: configuration
    dependencies: [ollama-service]
    shell: "ollama pull nomic-embed-text"
    doctorChecks:
      - type: commandExists
        name: "nomic-embed-text model"
        section: AI Models
        command: curl
        args: ["-sf", "http://localhost:11434/api/show", "-d", "{\"name\":\"nomic-embed-text\"}"]
      # Probes the exact endpoint docs-mcp-server calls. /api/show only reads the
      # manifest — it does not load the model. This check forces a full load+embed
      # round-trip, so a runner crash (e.g. Ollama/ggml incompatibility) surfaces
      # as HTTP 500 and fails the check.
      - type: commandExists
        name: "nomic-embed-text embedding endpoint"
        section: AI Models
        command: curl
        args:
          - "-sf"
          - "-X"
          - "POST"
          - "-H"
          - "Content-Type: application/json"
          - "-d"
          - '{"model":"nomic-embed-text","input":"ping"}'
          - "http://localhost:11434/v1/embeddings"

  # ── MCP Servers ─────────────────────────────────────────────────────────
  # Install the binary once (pinned) so Claude launches a prebuilt binary.
  # `npx @latest` re-downloaded on every cache eviction, blowing Claude's 30s
  # MCP startup limit → "MCP error -32000: Connection closed".
  - id: docs-mcp-server-install
    displayName: docs-mcp-server binary
    description: Installs the docs-mcp-server MCP binary once so Claude launches a prebuilt binary
    dependencies: [node]
    type: configuration
    shell: "npm install -g @arabold/docs-mcp-server@2.4.3"
    doctorChecks:
      # `list` loads the better-sqlite3 native addon (a broken/ABI-mismatched
      # build fails here); `--version` wouldn't — it never loads it.
      - type: commandExists
        name: "docs-mcp-server binary loads"
        section: MCP Servers
        command: docs-mcp-server
        args: ["list"]
        fixCommand: "npm install -g @arabold/docs-mcp-server@2.4.3"

  - id: docs-mcp-server
    description: Semantic search over memories using local Ollama embeddings
    isRequired: true
    dependencies: [node, ollama, docs-mcp-server-install]
    mcp:
      command: docs-mcp-server
      args:
        - "--read-only"
        - "--telemetry=false"
      env:
        OPENAI_API_KEY: "ollama"
        OPENAI_API_BASE: "http://localhost:11434/v1"
        DOCS_MCP_EMBEDDING_MODEL: "openai:nomic-embed-text"

  # ── 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: Checks Ollama health and syncs docs-mcp-server library on session start
    dependencies: [ollama, docs-mcp-server, 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 docs-mcp-server library when memories have changed mid-session
    dependencies: [ollama, docs-mcp-server, 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__docs-mcp-server__search_docs"
    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-gate/"
      - ".claude/.kb-gate.log"

# ---------------------------------------------------------------------------
# Ignore — maintainer-only files not shipped with the pack
# ---------------------------------------------------------------------------
ignore:
  - SYNC-BLOCKS.md
  - tests/

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