Skip to content

Phase 9 Setup Plugin

Jump to bottom
Rick Hightower edited this page Feb 1, 2026 · 1 revision

Phase 9: Setup & Installer Plugin

This page aggregates all Phase 9 documentation for the Setup & Installer Plugin phase.

Phase Overview

Interactive setup wizard plugin with commands and agents.

09-01-PLAN

Plan 09-01: Setup Plugin Structure

Metadata

phase: 9
plan: 01
wave: 1
depends_on: []
files_modified:
  - plugins/memory-setup-plugin/.claude-plugin/marketplace.json
  - plugins/memory-setup-plugin/skills/memory-setup/SKILL.md
  - plugins/memory-setup-plugin/skills/memory-setup/references/installation-methods.md
  - plugins/memory-setup-plugin/skills/memory-setup/references/configuration-options.md
  - plugins/memory-setup-plugin/skills/memory-setup/references/troubleshooting-guide.md
  - plugins/memory-setup-plugin/skills/memory-setup/references/platform-specifics.md
  - plugins/memory-setup-plugin/commands/memory-setup.md
  - plugins/memory-setup-plugin/commands/memory-status.md
  - plugins/memory-setup-plugin/commands/memory-config.md
  - plugins/memory-setup-plugin/agents/setup-troubleshooter.md
  - plugins/memory-setup-plugin/README.md
  - plugins/memory-setup-plugin/.gitignore
autonomous: true

Objective

Create the complete plugin structure for the memory-setup plugin with marketplace manifest, skill, commands, and agent definitions following Claude Code plugin best practices.

Context

This plugin provides interactive setup, configuration, and troubleshooting for agent-memory. It should:

  • Guide users through first-time installation
  • Provide health checks and status monitoring
  • Enable configuration changes without file editing
  • Offer autonomous troubleshooting for common issues

Tasks

Task 1: Create Plugin Directory Structure

<task id="1">
  <title>Create plugin directory structure</title>
  <description>
    Create the full directory structure for memory-setup-plugin:

    plugins/memory-setup-plugin/
    ├── .claude-plugin/
    ├── skills/memory-setup/
    │   └── references/
    ├── commands/
    └── agents/
  </description>
  <acceptance>
    - All directories exist
    - Structure matches marketplace plugin spec
  </acceptance>
</task>

Task 2: Create marketplace.json

<task id="2">
  <title>Create marketplace.json manifest</title>
  <description>
    Create .claude-plugin/marketplace.json with:
    - Plugin name: "memory-setup"
    - Description focused on setup and management
    - Version: "1.0.0"
    - Author information
    - plugins array with skills, commands, agents references
  </description>
  <acceptance>
    - Valid JSON format
    - All plugin components referenced
    - Description explains value proposition
  </acceptance>
</task>

Task 3: Create SKILL.md

<task id="3">
  <title>Create core SKILL.md with PDA structure</title>
  <description>
    Create skills/memory-setup/SKILL.md with:
    - YAML frontmatter (name, description, triggers)
    - Quick Start section (most common path)
    - Workflow overview (setup → status → config → troubleshoot)
    - Reference file navigation
    - Decision trees for common scenarios
    - Validation checklists

    Follow Progressive Disclosure Architecture:
    - Level 1: Quick start (10% of users need more)
    - Level 2: Workflow details (next 20%)
    - Level 3: Reference files (power users)
  </description>
  <acceptance>
    - Valid YAML frontmatter
    - Clear trigger phrases
    - Progressive disclosure structure
    - Links to all reference files
  </acceptance>
</task>

Task 4: Create Reference Files

<task id="4">
  <title>Create reference documentation files</title>
  <description>
    Create references/ directory with:

    1. installation-methods.md
       - Cargo install instructions
       - Pre-built binary download
       - Platform-specific paths
       - Verification steps

    2. configuration-options.md
       - config.toml format and options
       - Environment variables
       - hooks.yaml configuration
       - Default values and overrides

    3. troubleshooting-guide.md
       - Common issues and solutions
       - Diagnostic commands
       - Log locations
       - How to report bugs

    4. platform-specifics.md
       - macOS (launchd, paths)
       - Linux (systemd, paths)
       - Windows (Task Scheduler, paths)
  </description>
  <acceptance>
    - Each file is self-contained
    - Copy-paste commands work
    - Platform variations documented
  </acceptance>
</task>

Task 5: Create Command Files

<task id="5">
  <title>Create command definition files</title>
  <description>
    Create commands/ directory with:

    1. memory-setup.md
       - Slash command: /memory-setup
       - Interactive wizard flow
       - Flags: --fresh, --minimal, --advanced
       - Step-by-step instructions for the agent

    2. memory-status.md
       - Slash command: /memory-status
       - Health check output format
       - Flags: --json, --verbose
       - What to check and how

    3. memory-config.md
       - Slash command: /memory-config
       - Subcommands: show, set, reset
       - Configuration key paths
       - Validation rules
  </description>
  <acceptance>
    - Each command has clear purpose
    - Flags documented with examples
    - Output formats specified
  </acceptance>
</task>

Task 6: Create Agent Definition

<task id="6">
  <title>Create setup-troubleshooter agent</title>
  <description>
    Create agents/setup-troubleshooter.md with:
    - Agent name and description
    - Trigger conditions (when to invoke)
    - Diagnostic capabilities
    - Fix capabilities (what it can modify)
    - Escalation path (when to ask user)
    - Example diagnostic flows
  </description>
  <acceptance>
    - Clear trigger conditions
    - Comprehensive diagnostic checklist
    - Safe fix actions defined
    - Knows when to escalate
  </acceptance>
</task>

Task 7: Create README and .gitignore

<task id="7">
  <title>Create README.md and .gitignore</title>
  <description>
    Create:

    1. README.md
       - What the plugin does
       - Installation instructions
       - Quick start guide
       - Command reference
       - Troubleshooting tips

    2. .gitignore
       - Standard ignores for plugin development
  </description>
  <acceptance>
    - README covers all commands
    - Installation is one-liner
    - Examples are copy-paste ready
  </acceptance>
</task>

Verification

verification:
  - [ ] Plugin directory structure matches spec
  - [ ] marketplace.json is valid JSON
  - [ ] SKILL.md has valid YAML frontmatter
  - [ ] All reference files exist and are complete
  - [ ] All command files define their slash command
  - [ ] Agent file defines trigger conditions
  - [ ] README provides quick start path

Must-Haves (Goal-Backward)

For Phase 9 success, this plan must deliver:

  1. Complete plugin structure that can be installed in ~/.claude/skills/
  2. SKILL.md that Claude can discover and invoke
  3. Command definitions for /memory-setup, /memory-status, /memory-config
  4. Agent definition for autonomous troubleshooting
  5. Reference documentation for all configuration options

09-01-SUMMARY

phase: 9 plan: 01 subsystem: plugins tags: [plugin, setup, cli, configuration] dependency-graph: requires: [] provides: [memory-setup-plugin, setup-wizard, status-check, config-management] affects: [09-02, 09-03, 09-04] tech-stack: added: [] patterns: [progressive-disclosure, slash-commands, autonomous-agent] key-files: created: - plugins/memory-setup-plugin/.claude-plugin/marketplace.json - plugins/memory-setup-plugin/skills/memory-setup/SKILL.md - plugins/memory-setup-plugin/skills/memory-setup/references/installation-methods.md - plugins/memory-setup-plugin/skills/memory-setup/references/configuration-options.md - plugins/memory-setup-plugin/skills/memory-setup/references/troubleshooting-guide.md - plugins/memory-setup-plugin/skills/memory-setup/references/platform-specifics.md - plugins/memory-setup-plugin/commands/memory-setup.md - plugins/memory-setup-plugin/commands/memory-status.md - plugins/memory-setup-plugin/commands/memory-config.md - plugins/memory-setup-plugin/agents/setup-troubleshooter.md - plugins/memory-setup-plugin/README.md - plugins/memory-setup-plugin/.gitignore modified: [] decisions:

  • id: plugin-structure decision: Follow memory-query-plugin structure exactly rationale: Consistency across plugins for discoverability
  • id: pda-design decision: Progressive Disclosure Architecture for SKILL.md rationale: Most users need quick start, power users need references metrics: duration: ~5min completed: 2026-01-31

Phase 9 Plan 01: Setup Plugin Structure Summary

Created complete memory-setup-plugin with marketplace manifest, SKILL.md, commands, agent, and reference documentation.

One-liner

Plugin skeleton with /memory-setup wizard, /memory-status check, /memory-config management, and setup-troubleshooter agent.

What Was Built

Plugin Structure

plugins/memory-setup-plugin/
├── .claude-plugin/
│   └── marketplace.json      # Plugin manifest
├── skills/memory-setup/
│   ├── SKILL.md              # Core skill with PDA
│   └── references/
│       ├── installation-methods.md
│       ├── configuration-options.md
│       ├── troubleshooting-guide.md
│       └── platform-specifics.md
├── commands/
│   ├── memory-setup.md       # /memory-setup wizard
│   ├── memory-status.md      # /memory-status health check
│   └── memory-config.md      # /memory-config management
├── agents/
│   └── setup-troubleshooter.md
├── README.md
└── .gitignore

Commands

Command Purpose Flags
/memory-setup Interactive installation wizard --fresh, --minimal, --advanced
/memory-status Health check and diagnostics --verbose, --json
/memory-config View/modify configuration show, set, reset

Agent

setup-troubleshooter: Autonomous agent for diagnosing and fixing issues.

Triggers:

  • "memory-daemon won't start"
  • "no events in memory"
  • "connection refused"
  • "fix memory issues"

Capabilities:

  • Diagnostic checks (safe, no permission needed)
  • Auto-fix (start daemon, create config dirs)
  • Permission-required fixes (reinstall, port change, CCH hooks)

Reference Documentation

  1. installation-methods.md: Cargo install, binaries, source build, post-install
  2. configuration-options.md: Full config.toml reference, env vars, scenarios
  3. troubleshooting-guide.md: 10 common issues with solutions
  4. platform-specifics.md: macOS, Linux, Windows details with service configs

Decisions Made

Decision Rationale
Follow memory-query-plugin structure Consistency across plugins
Progressive Disclosure Architecture Quick start for 90%, deep refs for power users
Three slash commands Clear separation: setup/status/config
Autonomous agent with safe/permission tiers Safety while enabling automation

Deviations from Plan

None - plan executed exactly as written.

Commits

Hash Description
39084b6 chore(09-01): create directory structure
936a7b4 feat(09-01): add marketplace.json
d1d1582 feat(09-01): add SKILL.md
0aa323b docs(09-01): add reference files
f8aa031 feat(09-01): add command definitions
5fae4d2 feat(09-01): add setup-troubleshooter agent
33275e9 docs(09-01): add README.md and .gitignore

Next Phase Readiness

Blockers

None.

Ready For

  • Plan 09-02: Implement actual wizard logic using cargo commands
  • Plan 09-03: Implement status/config CLI integration
  • Plan 09-04: Testing and polish

Verification Checklist

  • Plugin directory structure matches spec
  • marketplace.json is valid JSON
  • SKILL.md has valid YAML frontmatter
  • All 4 reference files exist and are complete
  • All 3 command files define their slash command
  • Agent file defines trigger conditions
  • README provides quick start path

09-02-PLAN

Plan 09-02: Interactive Wizard Flow

Metadata

phase: 9
plan: 02
wave: 2
depends_on: [09-01]
files_modified:
  - plugins/memory-setup-plugin/skills/memory-setup/SKILL.md (update)
  - plugins/memory-setup-plugin/commands/memory-setup.md (update)
  - plugins/memory-setup-plugin/skills/memory-setup/references/wizard-questions.md
autonomous: true

Objective

Implement the detailed interactive wizard flow for /memory-setup that guides users through installation and configuration with progressive questioning.

Context

The wizard should:

  • Detect current state before asking questions
  • Skip steps that are already complete
  • Offer sensible defaults with option to customize
  • Validate each step before proceeding
  • Provide clear success/failure feedback

Tasks

Task 1: Define State Detection Logic

<task id="1">
  <title>Define state detection logic in SKILL.md</title>
  <description>
    Add state detection section to SKILL.md that checks:

    1. Prerequisites
       - Claude Code installation detected
       - Rust/cargo availability
       - Platform detection (macOS/Linux/Windows)

    2. Existing Installation
       - memory-daemon binary location
       - memory-ingest binary location
       - Current version if installed

    3. Configuration State
       - ~/.config/agent-memory/config.toml exists
       - hooks.yaml exists (global or project)
       - Environment variables set

    4. Runtime State
       - Daemon process running
       - Port availability
       - Recent event ingestion

    Include bash commands for each check.
  </description>
  <acceptance>
    - All checks have specific commands
    - Output parsing documented
    - State categories defined
  </acceptance>
</task>

Task 2: Create Wizard Question Flow

<task id="2">
  <title>Create wizard-questions.md reference file</title>
  <description>
    Create references/wizard-questions.md with complete question flow:

    Step 1: Installation Method
    - Condition: binaries not found
    - Options: cargo install, download binary, manual
    - Default: cargo install if cargo available

    Step 2: Installation Location
    - Condition: installing binaries
    - Options: ~/.local/bin, ~/.cargo/bin, custom
    - Default: ~/.local/bin

    Step 3: Summarizer Provider
    - Condition: config.toml not found OR --fresh
    - Options: Anthropic, OpenAI, Local (ollama), None
    - Default: Anthropic

    Step 4: API Key
    - Condition: provider requires API key AND env var not set
    - Input: API key value
    - Validation: format check, test call

    Step 5: Hook Scope
    - Condition: hooks.yaml not found OR --fresh
    - Options: Global, Project-only, Skip
    - Default: Global

    Step 6: Daemon Startup
    - Condition: daemon not running
    - Options: Start + auto-start, Start only, Manual
    - Default: Start + auto-start

    Include skip conditions and dependencies between questions.
  </description>
  <acceptance>
    - All questions have conditions
    - Skip logic documented
    - Defaults are sensible
    - Validation rules specified
  </acceptance>
</task>

Task 3: Update memory-setup.md Command

<task id="3">
  <title>Update memory-setup.md with detailed wizard instructions</title>
  <description>
    Expand commands/memory-setup.md with:

    1. State Detection Phase
       - What to check
       - How to report current state

    2. Question Phase
       - How to use AskUserQuestion tool
       - Question grouping (max 4 per call)
       - How to handle "Other" responses

    3. Execution Phase
       - How to execute installation
       - How to write configuration files
       - How to start daemon

    4. Verification Phase
       - What to check after setup
       - How to report success/failure
       - What to suggest as next steps

    Include example output formatting.
  </description>
  <acceptance>
    - Clear phase separation
    - Tool usage documented
    - Output format specified
    - Error handling defined
  </acceptance>
</task>

Task 4: Define Wizard Output Format

<task id="4">
  <title>Define wizard output formatting</title>
  <description>
    Add output formatting section to SKILL.md:

    Progress Display:
    ```
    Agent Memory Setup
    ══════════════════

    Checking prerequisites...
      ✓ Claude Code detected
      ✓ cargo available
      ✗ memory-daemon not found
      ✗ memory-ingest not found

    Step 1 of 6: Installation
    ─────────────────────────
    ```

    Success Display:
    ```
    ══════════════════════════════════════════════════
     Setup Complete!
    ══════════════════════════════════════════════════

    ✓ Binaries installed to ~/.local/bin/
    ✓ Configuration written to ~/.config/agent-memory/
    ✓ Hooks configured in ~/.claude/hooks.yaml
    ✓ Daemon started on port 50051

    Next steps:
      • Start a conversation and it will be recorded
      • Use /memory-recent to see captured events
      • Use /memory-search <topic> to find past discussions
    ```

    Error Display:
    ```
    ✗ Setup Failed
    ──────────────

    Error: Could not start daemon - port 50051 in use

    To fix:
      1. Run: lsof -i :50051
      2. Kill the process using the port
      3. Run: /memory-setup --fresh
    ```
  </description>
  <acceptance>
    - Consistent visual style
    - Clear progress indicators
    - Actionable error messages
  </acceptance>
</task>

Task 5: Add Flag Handling

<task id="5">
  <title>Document flag handling for wizard modes</title>
  <description>
    Add flag documentation to memory-setup.md:

    --fresh
    - Ignore existing configuration
    - Re-ask all questions
    - Overwrite existing config files
    - Use case: Reset to clean state

    --minimal
    - Use all defaults without asking
    - Only ask for required inputs (API key if not in env)
    - Skip optional steps
    - Use case: Quick setup for experienced users

    --advanced
    - Show all configuration options
    - Include port selection
    - Include database path selection
    - Include segmentation tuning
    - Use case: Power users
  </description>
  <acceptance>
    - Each flag clearly documented
    - Behavior differences specified
    - Use cases provided
  </acceptance>
</task>

Verification

verification:
  - [ ] State detection covers all components
  - [ ] Question flow handles all scenarios
  - [ ] Skip logic prevents redundant questions
  - [ ] Output formatting is consistent
  - [ ] All flags documented with behaviors
  - [ ] Error messages are actionable

Must-Haves (Goal-Backward)

For Phase 9 success, this plan must deliver:

  1. Complete wizard question flow with conditions and defaults
  2. State detection that identifies what's already configured
  3. Clear output formatting for progress, success, and errors
  4. Flag support for different user expertise levels

09-02-SUMMARY

phase: 9 plan: 02 subsystem: setup-plugin tags: [wizard, interactive, installation, configuration] dependency-graph: requires: [09-01] provides: [wizard-flow, state-detection, output-formatting] affects: [09-03, 09-04] tech-stack: added: [] patterns: [progressive-disclosure, state-machine] key-files: created: - plugins/memory-setup-plugin/skills/memory-setup/references/wizard-questions.md modified: - plugins/memory-setup-plugin/skills/memory-setup/SKILL.md - plugins/memory-setup-plugin/commands/memory-setup.md decisions:

  • 6-step progressive wizard with conditional skip logic
  • State detection before asking questions to skip completed steps
  • Three flag modes: fresh (reset), minimal (defaults), advanced (full options)
  • Consistent output formatting with [check]/[x] status indicators metrics: duration: 4min completed: 2026-01-31

Phase 9 Plan 02: Interactive Wizard Flow Summary

One-liner: 6-step progressive wizard with state detection, conditional skipping, and three operational modes (fresh/minimal/advanced)

What Was Built

1. State Detection Logic (SKILL.md)

Added comprehensive state detection covering:

  • Prerequisites: Claude Code, cargo/Rust, platform detection
  • Installation: Binary locations, versions, installation paths
  • Configuration: config.toml, hooks.yaml (global/project), env vars
  • Runtime: Daemon status, port availability, responsiveness

State categories defined for each check type (READY, NEEDS_RUST, NOT_INSTALLED, CONFIGURED, RUNNING, etc.)

2. Wizard Question Flow (wizard-questions.md)

Created complete 6-step progressive wizard:

Step Question Condition Default
1 Installation Method Binaries not found cargo if available
2 Installation Location Binary/source selected ~/.local/bin
3 Summarizer Provider No config.toml anthropic if key set
4 API Key Provider needs key, no env var N/A (required)
5 Hook Scope hooks.yaml not configured global
6 Daemon Startup Daemon not running auto-start

Includes skip conditions, dependencies between questions, and validation rules.

3. Command Documentation (memory-setup.md)

Expanded with four execution phases:

  • Phase 1: State Detection - Commands and output format
  • Phase 2: Question Phase - User interaction patterns
  • Phase 3: Execution Phase - Installation, config, hooks, daemon
  • Phase 4: Verification Phase - Success/partial/failure outputs

4. Output Formatting (SKILL.md)

Defined consistent visual formatting:

  • Progress display with step indicators
  • Status symbols: [check], [x], [!], [?], [>]
  • Success, partial success, and error display formats
  • Question format for user input
  • Summary tables for configuration display
  • Optional color support with ANSI codes

5. Flag Handling (memory-setup.md)

Documented three operational flags:

Flag Purpose Behavior
--fresh Reset to clean state Ignore existing, re-ask all, backup overwrite
--minimal Quick setup Use defaults, only ask for required inputs
--advanced Power users Additional port/path/tuning options

Added flag combination rules and mutual exclusivity handling.

Commits

Hash Description
7e8db4a feat(09-02): add state detection logic to SKILL.md
ebc39bd feat(09-02): create wizard question flow reference
495c535 feat(09-02): update memory-setup.md with detailed wizard instructions
d000dfa feat(09-02): add wizard output formatting to SKILL.md
d88de00 feat(09-02): enhance flag handling documentation

Files Changed

plugins/memory-setup-plugin/
  skills/memory-setup/
    SKILL.md                    (modified: +282 lines)
    references/
      wizard-questions.md       (created: 511 lines)
  commands/
    memory-setup.md             (modified: +524 lines, -106 lines)

Deviations from Plan

None - plan executed exactly as written.

Decisions Made

  1. 6-step progressive flow - Questions asked one at a time with conditional skipping based on state detection
  2. State-before-questions pattern - Always detect current state before asking any questions
  3. Three operational modes - Fresh (reset), minimal (defaults), advanced (full options)
  4. Consistent status indicators - [check], [x], [!], [?], [>] for clear visual feedback
  5. Backup-before-overwrite - --fresh flag creates .bak files before overwriting

Next Phase Readiness

09-03 Prerequisites:

  • Wizard flow defined and documented
  • State detection logic complete
  • Output formatting standardized

Ready for: Status and Config command implementation (09-03)

09-03-PLAN

Plan 09-03: Installation Automation

Metadata

phase: 9
plan: 03
wave: 2
depends_on: [09-01]
files_modified:
  - plugins/memory-setup-plugin/skills/memory-setup/references/installation-methods.md (update)
  - plugins/memory-setup-plugin/skills/memory-setup/references/platform-specifics.md (update)
  - plugins/memory-setup-plugin/skills/memory-setup/scripts/install-helper.sh
autonomous: true

Objective

Document and implement the installation automation that the setup wizard executes, including binary installation, configuration file generation, and auto-start setup.

Context

Installation must:

  • Work across macOS, Linux, and Windows
  • Handle multiple installation methods
  • Generate correct configuration files
  • Set up auto-start appropriately for each platform
  • Be reversible (uninstall path)

Tasks

Task 1: Document Cargo Installation

<task id="1">
  <title>Document cargo install method</title>
  <description>
    Update installation-methods.md with cargo install details:

    Prerequisites:
    - Rust toolchain (rustup recommended)
    - C compiler (for RocksDB)

    Commands:
    ```bash
    # Install from crates.io (when published)
    cargo install memory-daemon memory-ingest

    # Install from git (current)
    cargo install --git https://github.com/SpillwaveSolutions/agent-memory memory-daemon
    cargo install --git https://github.com/SpillwaveSolutions/agent-memory memory-ingest
    ```

    Verification:
    ```bash
    memory-daemon --version
    memory-ingest --version
    ```

    Troubleshooting:
    - RocksDB compilation errors
    - Missing C compiler
    - Permission issues
  </description>
  <acceptance>
    - Commands are copy-paste ready
    - Prerequisites clearly stated
    - Common errors addressed
  </acceptance>
</task>

Task 2: Document Binary Download Installation

<task id="2">
  <title>Document pre-built binary installation</title>
  <description>
    Add binary download section to installation-methods.md:

    GitHub Releases URL pattern:
    ```
    https://github.com/SpillwaveSolutions/agent-memory/releases/latest/download/
      memory-daemon-{os}-{arch}
      memory-ingest-{os}-{arch}
    ```

    Platform detection:
    ```bash
    OS=$(uname -s | tr '[:upper:]' '[:lower:]')
    ARCH=$(uname -m)
    # Map arch: x86_64 -> amd64, arm64 -> arm64
    ```

    Download and install:
    ```bash
    # macOS/Linux
    curl -L -o memory-daemon "https://github.com/.../${OS}-${ARCH}"
    chmod +x memory-daemon
    mv memory-daemon ~/.local/bin/

    # Windows (PowerShell)
    Invoke-WebRequest -Uri "https://github.com/..." -OutFile memory-daemon.exe
    Move-Item memory-daemon.exe $env:USERPROFILE\.local\bin\
    ```

    Checksum verification:
    ```bash
    curl -L -o checksums.txt "https://github.com/.../checksums.txt"
    sha256sum -c checksums.txt
    ```
  </description>
  <acceptance>
    - URLs use correct pattern
    - Platform detection works
    - Checksum verification included
  </acceptance>
</task>

Task 3: Document Configuration Generation

<task id="3">
  <title>Document configuration file generation</title>
  <description>
    Add configuration generation section to configuration-options.md:

    config.toml generation:
    ```bash
    mkdir -p ~/.config/agent-memory

    cat > ~/.config/agent-memory/config.toml << 'EOF'
    [daemon]
    port = 50051
    db_path = "~/.local/share/agent-memory/db"

    [summarizer]
    provider = "${PROVIDER}"
    model = "${MODEL}"
    EOF
    ```

    hooks.yaml generation (global):
    ```bash
    cat >> ~/.claude/hooks.yaml << 'EOF'

    # Agent Memory event capture
    hooks:
      - event: "*"
        run: "~/.local/bin/memory-ingest"
    EOF
    ```

    hooks.yaml generation (project):
    ```bash
    cat > .claude/hooks.yaml << 'EOF'
    hooks:
      - event: "*"
        run: "~/.local/bin/memory-ingest"
    EOF
    ```

    Database directory:
    ```bash
    mkdir -p ~/.local/share/agent-memory/db
    ```
  </description>
  <acceptance>
    - Config templates are complete
    - Variable substitution documented
    - Directory creation included
  </acceptance>
</task>

Task 4: Document Auto-Start Setup

<task id="4">
  <title>Document platform-specific auto-start setup</title>
  <description>
    Update platform-specifics.md with auto-start configuration:

    macOS (launchd):
    ```bash
    cat > ~/Library/LaunchAgents/com.spillwave.memory-daemon.plist << 'EOF'
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" ...>
    <plist version="1.0">
    <dict>
        <key>Label</key>
        <string>com.spillwave.memory-daemon</string>
        <key>ProgramArguments</key>
        <array>
            <string>~/.local/bin/memory-daemon</string>
            <string>start</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
        <key>KeepAlive</key>
        <true/>
    </dict>
    </plist>
    EOF

    launchctl load ~/Library/LaunchAgents/com.spillwave.memory-daemon.plist
    ```

    Linux (systemd user service):
    ```bash
    mkdir -p ~/.config/systemd/user

    cat > ~/.config/systemd/user/memory-daemon.service << 'EOF'
    [Unit]
    Description=Agent Memory Daemon
    After=network.target

    [Service]
    ExecStart=%h/.local/bin/memory-daemon start
    Restart=always
    RestartSec=10

    [Install]
    WantedBy=default.target
    EOF

    systemctl --user daemon-reload
    systemctl --user enable memory-daemon
    systemctl --user start memory-daemon
    ```

    Windows (Task Scheduler):
    ```powershell
    $action = New-ScheduledTaskAction -Execute "$env:USERPROFILE\.local\bin\memory-daemon.exe" -Argument "start"
    $trigger = New-ScheduledTaskTrigger -AtLogOn
    $settings = New-ScheduledTaskSettingsSet -RestartCount 3 -RestartInterval (New-TimeSpan -Minutes 1)
    Register-ScheduledTask -TaskName "AgentMemoryDaemon" -Action $action -Trigger $trigger -Settings $settings
    ```
  </description>
  <acceptance>
    - All three platforms covered
    - Commands are complete and functional
    - Restart on failure configured
  </acceptance>
</task>

Task 5: Create Install Helper Script

<task id="5">
  <title>Create install-helper.sh utility script</title>
  <description>
    Create scripts/install-helper.sh with functions:

    ```bash
    #!/bin/bash
    # Agent Memory Installation Helper
    # Used by setup wizard for common operations

    detect_platform() {
      # Returns: macos, linux, windows
    }

    detect_arch() {
      # Returns: amd64, arm64
    }

    check_binary_installed() {
      # Args: binary_name
      # Returns: 0 if found, 1 if not
    }

    get_binary_version() {
      # Args: binary_name
      # Returns: version string
    }

    check_daemon_running() {
      # Returns: 0 if running, 1 if not
    }

    get_daemon_pid() {
      # Returns: PID or empty
    }

    check_port_available() {
      # Args: port
      # Returns: 0 if available, 1 if in use
    }

    install_binary_cargo() {
      # Args: package_name
      # Installs via cargo
    }

    install_binary_download() {
      # Args: binary_name
      # Downloads from GitHub releases
    }

    setup_autostart() {
      # Sets up platform-appropriate auto-start
    }

    remove_autostart() {
      # Removes auto-start configuration
    }
    ```
  </description>
  <acceptance>
    - All functions documented
    - Cross-platform support
    - Error handling included
  </acceptance>
</task>

Task 6: Document Uninstall Process

<task id="6">
  <title>Document uninstall/cleanup process</title>
  <description>
    Add uninstall section to installation-methods.md:

    Stop daemon:
    ```bash
    memory-daemon stop
    # or
    pkill memory-daemon
    ```

    Remove auto-start:
    ```bash
    # macOS
    launchctl unload ~/Library/LaunchAgents/com.spillwave.memory-daemon.plist
    rm ~/Library/LaunchAgents/com.spillwave.memory-daemon.plist

    # Linux
    systemctl --user stop memory-daemon
    systemctl --user disable memory-daemon
    rm ~/.config/systemd/user/memory-daemon.service

    # Windows
    Unregister-ScheduledTask -TaskName "AgentMemoryDaemon" -Confirm:$false
    ```

    Remove binaries:
    ```bash
    rm ~/.local/bin/memory-daemon
    rm ~/.local/bin/memory-ingest
    ```

    Remove configuration (optional):
    ```bash
    rm -rf ~/.config/agent-memory
    ```

    Remove data (optional - destructive):
    ```bash
    rm -rf ~/.local/share/agent-memory
    ```

    Remove hooks:
    ```bash
    # Edit ~/.claude/hooks.yaml and remove memory-ingest entries
    ```
  </description>
  <acceptance>
    - Complete uninstall path documented
    - Data preservation vs deletion choices
    - Platform-specific commands
  </acceptance>
</task>

Verification

verification:
  - [ ] Cargo installation documented with troubleshooting
  - [ ] Binary download documented with checksums
  - [ ] Configuration generation templates complete
  - [ ] Auto-start setup for macOS, Linux, Windows
  - [ ] Helper script covers common operations
  - [ ] Uninstall process documented

Must-Haves (Goal-Backward)

For Phase 9 success, this plan must deliver:

  1. Working installation commands for cargo and binary download
  2. Configuration file templates that generate valid config
  3. Auto-start setup for all major platforms
  4. Reversible installation (clean uninstall path)

09-03-SUMMARY

phase: 09-setup-installer-plugin plan: 03 subsystem: installer tags: [bash, shell, launchd, systemd, cargo, binary-download, cross-platform]

Dependency graph

requires:

  • phase: 09-01 provides: Plugin structure, reference file templates provides:
  • Installation automation documentation
  • Cross-platform install helper script
  • Auto-start configuration for macOS/Linux/Windows
  • Uninstall procedures affects: [09-04, memory-setup-plugin]

Tech tracking

tech-stack: added: [bash, shell-scripting] patterns: [helper-script-functions, platform-detection, service-management]

key-files: created: - plugins/memory-setup-plugin/skills/memory-setup/scripts/install-helper.sh modified: - plugins/memory-setup-plugin/skills/memory-setup/references/installation-methods.md - plugins/memory-setup-plugin/skills/memory-setup/references/configuration-options.md - plugins/memory-setup-plugin/skills/memory-setup/references/platform-specifics.md

key-decisions:

  • "Install helper as sourced shell functions for flexibility"
  • "Both cargo and binary download methods documented equally"
  • "SHA256 checksum verification for binary downloads"
  • "User services (launchd/systemd user) not system services"

patterns-established:

  • "Platform detection: detect_os/detect_arch/detect_platform functions"
  • "Installation check: check_binary_installed with fallback paths"
  • "Service setup: platform-specific setup_autostart_* functions"

Metrics

duration: 5min completed: 2026-01-31

Phase 9 Plan 03: Installation Automation Summary

Cross-platform install helper script with cargo/binary installation, auto-start setup, and complete uninstall procedures for macOS/Linux/Windows

Performance

  • Duration: 5 min
  • Started: 2026-01-31T19:07:12Z
  • Completed: 2026-01-31T19:12:28Z
  • Tasks: 6
  • Files modified: 4

Accomplishments

  • Comprehensive cargo installation documentation with prerequisites and troubleshooting
  • Binary download documentation with platform detection and checksum verification
  • Configuration generation documentation for config.toml and hooks.yaml
  • Auto-start setup for all platforms (macOS launchd, Linux systemd, Windows Task Scheduler)
  • 683-line install helper script with 20+ functions
  • Complete uninstall procedures with data preservation options

Task Commits

Each task was committed atomically:

  1. Task 1: Document Cargo Installation - 2866004 (docs)
  2. Task 2: Document Binary Download Installation - e406a78 (docs)
  3. Task 3: Document Configuration Generation - 709c189 (docs)
  4. Task 4: Document Auto-Start Setup - 3bacde8 (docs)
  5. Task 5: Create Install Helper Script - 25fdec0 (feat)
  6. Task 6: Document Uninstall Process - d690db8 (docs)

Files Created/Modified

  • plugins/memory-setup-plugin/skills/memory-setup/scripts/install-helper.sh - Cross-platform installation helper with detect_platform, check_binary_installed, install_binary_cargo, install_binary_download, setup_autostart, remove_autostart, generate_config, uninstall functions
  • plugins/memory-setup-plugin/skills/memory-setup/references/installation-methods.md - Expanded with cargo prerequisites, binary download with checksums, detailed uninstall
  • plugins/memory-setup-plugin/skills/memory-setup/references/configuration-options.md - Added configuration generation section for wizard
  • plugins/memory-setup-plugin/skills/memory-setup/references/platform-specifics.md - Expanded auto-start sections with setup scripts and troubleshooting

Decisions Made

  1. Helper script as sourced functions - Script designed to be sourced (source install-helper.sh) or executed directly with function name as argument, providing flexibility for both wizard automation and manual use
  2. User-level services, not system services - All auto-start configurations use user-level service managers (launchd user agents, systemd user services, Task Scheduler user tasks) to avoid requiring admin/root privileges
  3. SHA256 checksum verification - Binary downloads include checksum verification documentation; script downloads .sha256 files when available
  4. Dual install paths - Both ~/.local/bin (no sudo) and /usr/local/bin (with sudo) documented for binary installation

Deviations from Plan

None - plan executed exactly as written.

Issues Encountered

None.

User Setup Required

None - no external service configuration required. The helper script handles all installation automation.

Next Phase Readiness

  • Installation automation complete and documented
  • Ready for 09-04 (Testing and Polish) to validate installation flows
  • install-helper.sh ready to be invoked by setup wizard
  • All platform-specific auto-start procedures documented with troubleshooting

Phase: 09-setup-installer-plugin Completed: 2026-01-31

09-04-PLAN

Plan 09-04: Health Check and Troubleshooting

Metadata

phase: 9
plan: 04
wave: 3
depends_on: [09-01, 09-02]
files_modified:
  - plugins/memory-setup-plugin/commands/memory-status.md (update)
  - plugins/memory-setup-plugin/commands/memory-config.md (update)
  - plugins/memory-setup-plugin/agents/setup-troubleshooter.md (update)
  - plugins/memory-setup-plugin/skills/memory-setup/references/troubleshooting-guide.md (update)
autonomous: true

Objective

Implement comprehensive health checking via /memory-status, configuration management via /memory-config, and autonomous troubleshooting via the setup-troubleshooter agent.

Context

After installation, users need:

  • Quick health check: "Is it working?"
  • Configuration access: "What's my current setup?"
  • Problem diagnosis: "Why isn't it capturing events?"
  • Self-healing: "Fix common issues automatically"

Tasks

Task 1: Implement /memory-status Command

<task id="1">
  <title>Complete memory-status.md command definition</title>
  <description>
    Update commands/memory-status.md with full implementation:

    Health Checks:
    ```bash
    # Daemon running
    pgrep -x memory-daemon || echo "NOT RUNNING"

    # Port listening
    lsof -i :50051 | grep LISTEN

    # gRPC connectivity
    grpcurl -plaintext localhost:50051 list

    # Database accessible
    ls -la ~/.local/share/agent-memory/db/

    # Recent events
    memory-daemon query events --limit 1

    # Hook configured
    grep -r "memory-ingest" ~/.claude/hooks.yaml
    ```

    Output Format (default):
    ```
    Agent Memory Status
    ═══════════════════════════════════════════════════

    Component       Status    Details
    ─────────────────────────────────────────────────────
    Daemon          ✓ OK      Running (PID 12345, port 50051)
    Database        ✓ OK      1.2 GB, 15,432 events
    Hooks           ✓ OK      Global hooks.yaml configured
    API Key         ✓ OK      ANTHROPIC_API_KEY set
    Auto-start      ✓ OK      launchd service enabled

    Recent Activity
    ─────────────────────────────────────────────────────
    Last event:     2 minutes ago
    Today:          47 events
    This week:      312 events
    ```

    Output Format (--json):
    ```json
    {
      "daemon": {"status": "ok", "pid": 12345, "port": 50051},
      "database": {"status": "ok", "size_bytes": 1288490188, "event_count": 15432},
      "hooks": {"status": "ok", "location": "global"},
      "api_key": {"status": "ok", "provider": "anthropic"},
      "autostart": {"status": "ok", "method": "launchd"},
      "activity": {"last_event": "2024-01-30T10:15:00Z", "today": 47, "week": 312}
    }
    ```

    Output Format (--verbose):
    - Include full configuration dump
    - Show all environment variables
    - List all database column families with sizes
  </description>
  <acceptance>
    - All health checks documented
    - Three output formats defined
    - Status symbols consistent
  </acceptance>
</task>

Task 2: Implement /memory-config Command

<task id="2">
  <title>Complete memory-config.md command definition</title>
  <description>
    Update commands/memory-config.md with full implementation:

    Subcommand: show
    ```
    /memory-config show

    Current Configuration
    ═════════════════════

    [daemon]
    port = 50051
    db_path = ~/.local/share/agent-memory/db

    [summarizer]
    provider = anthropic
    model = claude-3-haiku-20240307

    [segmentation]
    time_threshold_mins = 30
    token_threshold = 4000

    Environment:
    ANTHROPIC_API_KEY = ****...****
    MEMORY_DAEMON_PORT = (not set)
    ```

    Subcommand: set
    ```
    /memory-config set <key> <value>

    Examples:
    /memory-config set daemon.port 50052
    /memory-config set summarizer.provider openai
    /memory-config set segmentation.time_threshold_mins 60
    ```

    Validation:
    - daemon.port: 1024-65535, check availability
    - summarizer.provider: anthropic|openai|local|none
    - summarizer.model: validate against provider
    - segmentation.*: positive integers

    After set:
    - Write to config.toml
    - Warn if daemon restart needed
    - Offer to restart daemon

    Subcommand: reset
    ```
    /memory-config reset

    This will reset configuration to defaults.
    Your data will NOT be deleted.

    Proceed? [y/N]
    ```
  </description>
  <acceptance>
    - All subcommands documented
    - Validation rules specified
    - Side effects explained
  </acceptance>
</task>

Task 3: Implement Troubleshooter Agent

<task id="3">
  <title>Complete setup-troubleshooter.md agent definition</title>
  <description>
    Update agents/setup-troubleshooter.md with full diagnostic capabilities:

    Trigger Conditions:
    - User says "memory not working"
    - User says "events not being captured"
    - /memory-status shows failures
    - Explicit: "troubleshoot my memory setup"

    Diagnostic Flow:
    ```
    1. Check daemon status
       - Not running → Start daemon
       - Port conflict → Find and resolve
       - Crash loop → Check logs

    2. Check hook configuration
       - Missing → Generate hooks.yaml
       - Wrong path → Fix binary path
       - Not triggering → Verify hook format

    3. Check gRPC connectivity
       - Connection refused → Daemon issue
       - Timeout → Firewall/network issue
       - Auth error → Check configuration

    4. Check event flow
       - Events arriving → Working
       - No events → Trace from hook
       - Events malformed → Check mapping

    5. Check summarization
       - API key missing → Prompt for key
       - API error → Check quota/validity
       - Local model → Check ollama running
    ```

    Fix Capabilities (can modify without asking):
    - Start stopped daemon
    - Create missing directories
    - Add execute permission to binaries
    - Write missing config with defaults

    Fix Capabilities (ask first):
    - Kill process using port
    - Overwrite existing configuration
    - Install missing binaries
    - Modify hooks.yaml

    Escalation Triggers:
    - Multiple failed fix attempts
    - Unknown error type
    - User data might be affected
    - Requires credentials input

    Example Diagnostic Session:
    ```
    User: "My conversations aren't being saved"

    Troubleshooter:
    ───────────────────────────────────────────────
    Diagnosing Agent Memory...

    ✓ Daemon: Running (PID 12345)
    ✓ Port: 50051 available
    ✓ Database: Accessible
    ✗ Hooks: Not configured

    Issue Found: No hooks.yaml configuration

    Fix: I'll add the hook configuration to ~/.claude/hooks.yaml

    [Writes hooks.yaml]

    ✓ Hooks: Configured

    Verification: Please send a test message and I'll check
    if it was captured...

    ✓ Event captured successfully!

    Your memory setup is now working.
    ───────────────────────────────────────────────
    ```
  </description>
  <acceptance>
    - Clear trigger conditions
    - Comprehensive diagnostic flow
    - Safe vs ask-first fixes defined
    - Escalation criteria specified
  </acceptance>
</task>

Task 4: Create Troubleshooting Guide

<task id="4">
  <title>Complete troubleshooting-guide.md reference</title>
  <description>
    Update references/troubleshooting-guide.md with common issues:

    Issue: Daemon won't start
    ```
    Symptoms: memory-daemon start fails silently
    Causes:
    - Port 50051 already in use
    - Missing RocksDB library
    - Permission denied on db_path

    Diagnosis:
    lsof -i :50051
    memory-daemon start 2>&1 | head

    Solutions:
    1. Kill existing process: kill $(lsof -t -i:50051)
    2. Install RocksDB: brew install rocksdb (macOS)
    3. Fix permissions: chmod -R 755 ~/.local/share/agent-memory
    ```

    Issue: Events not being captured
    ```
    Symptoms: /memory-recent shows no recent events
    Causes:
    - Hooks not configured
    - memory-ingest not in PATH
    - Daemon not running
    - Hook errors silently failing

    Diagnosis:
    cat ~/.claude/hooks.yaml
    which memory-ingest
    memory-daemon status

    Solutions:
    1. Add hooks: /memory-setup --fresh
    2. Fix PATH: export PATH="$HOME/.local/bin:$PATH"
    3. Start daemon: memory-daemon start
    ```

    Issue: Summarization failing
    ```
    Symptoms: TOC nodes have no summaries
    Causes:
    - API key not set
    - API quota exceeded
    - Network issues

    Diagnosis:
    echo $ANTHROPIC_API_KEY | head -c 10
    curl -s https://api.anthropic.com/v1/messages -H "x-api-key: $ANTHROPIC_API_KEY"

    Solutions:
    1. Set API key: export ANTHROPIC_API_KEY="sk-..."
    2. Check Anthropic dashboard for quota
    3. Try alternative provider: /memory-config set summarizer.provider openai
    ```

    Issue: High disk usage
    ```
    Symptoms: Database growing rapidly
    Causes:
    - Normal for heavy usage
    - Compaction not running
    - Too many events retained

    Diagnosis:
    du -sh ~/.local/share/agent-memory/db/
    memory-daemon admin status

    Solutions:
    1. Trigger compaction: memory-daemon admin compact
    2. Configure retention (future feature)
    ```

    Include 10+ common issues with diagnosis and solutions.
  </description>
  <acceptance>
    - At least 10 common issues covered
    - Each has symptoms, causes, diagnosis, solutions
    - Commands are copy-paste ready
  </acceptance>
</task>

Task 5: Add Diagnostic Commands to SKILL.md

<task id="5">
  <title>Add quick diagnostic commands to SKILL.md</title>
  <description>
    Add "Quick Diagnostics" section to SKILL.md:

    ```markdown
    ## Quick Diagnostics

    Copy-paste these commands for rapid troubleshooting:

    ### Is the daemon running?
    ```bash
    pgrep -x memory-daemon && echo "Running" || echo "Not running"
    ```

    ### What's using port 50051?
    ```bash
    lsof -i :50051
    ```

    ### Can I connect to the daemon?
    ```bash
    memory-daemon query root 2>&1 | head -5
    ```

    ### Are hooks configured?
    ```bash
    grep -l "memory-ingest" ~/.claude/hooks.yaml .claude/hooks.yaml 2>/dev/null
    ```

    ### Is my API key set?
    ```bash
    [ -n "$ANTHROPIC_API_KEY" ] && echo "Set" || echo "Not set"
    ```

    ### What's the database size?
    ```bash
    du -sh ~/.local/share/agent-memory/db/
    ```

    ### Recent events count?
    ```bash
    memory-daemon admin status | grep -i event
    ```
    ```
  </description>
  <acceptance>
    - Commands work on macOS and Linux
    - Output is clear
    - Covers main diagnostic needs
  </acceptance>
</task>

Verification

verification:
  - [ ] /memory-status shows all component health
  - [ ] /memory-status --json produces valid JSON
  - [ ] /memory-config show displays current config
  - [ ] /memory-config set validates and updates
  - [ ] Troubleshooter has clear diagnostic flow
  - [ ] Troubleshooter knows when to ask vs auto-fix
  - [ ] Troubleshooting guide covers 10+ issues
  - [ ] Quick diagnostics in SKILL.md are functional

Must-Haves (Goal-Backward)

For Phase 9 success, this plan must deliver:

  1. /memory-status that quickly shows if everything is working
  2. /memory-config that allows changing settings without file editing
  3. Autonomous troubleshooter that can diagnose and fix common issues
  4. Comprehensive troubleshooting guide for manual resolution

09-04-SUMMARY

phase: 09-setup-installer-plugin plan: 04 subsystem: setup, diagnostics tags: [health-check, troubleshooting, configuration, status, diagnostics]

Dependency graph

requires:

  • phase: 09-01 provides: Plugin structure, command definitions, agent skeleton
  • phase: 09-02 provides: Interactive wizard flow provides:
  • Comprehensive /memory-status command with health checks
  • Full /memory-config command with validation and side effects
  • Autonomous setup-troubleshooter agent with 5-step diagnostic flow
  • Troubleshooting guide with 15 common issues
  • Quick diagnostics section in SKILL.md affects: [memory-query-plugin, end-users, support]

Tech tracking

tech-stack: added: [] patterns: - Health check pattern (7 sequential checks with status levels) - Configuration management with validation and restart detection - Autonomous troubleshooter with safe/permission-required fix tiers - Decision tree troubleshooting flow

key-files: created: [] modified: - plugins/memory-setup-plugin/commands/memory-status.md - plugins/memory-setup-plugin/commands/memory-config.md - plugins/memory-setup-plugin/agents/setup-troubleshooter.md - plugins/memory-setup-plugin/skills/memory-setup/references/troubleshooting-guide.md - plugins/memory-setup-plugin/skills/memory-setup/SKILL.md

key-decisions:

  • "7 health checks in sequence: binary, daemon, port, gRPC, database, events, CCH"
  • "4 status levels: healthy, degraded, unhealthy, not installed"
  • "Config validation with restart-required matrix for side effect handling"
  • "Troubleshooter uses 6 diagnostic categories: INSTALLATION, STARTUP, CONNECTION, INGESTION, SUMMARIZATION, RUNTIME"
  • "Safe auto-fixes vs permission-required fixes tier system"

patterns-established:

  • "Health check sequence pattern for system diagnostics"
  • "Configuration change with side effect notification"
  • "Autonomous troubleshooter with escalation triggers"
  • "Quick diagnostics section with copy-paste commands"

Metrics

duration: 6min completed: 2026-01-31

Phase 9 Plan 4: Health Check and Troubleshooting Summary

Comprehensive health checking, configuration management, and autonomous troubleshooting for agent-memory setup plugin

Performance

  • Duration: 6 min
  • Started: 2026-01-31T19:14:28Z
  • Completed: 2026-01-31T19:20:40Z
  • Tasks: 5
  • Files modified: 5

Accomplishments

  • Implemented /memory-status with 7 health checks and 3 output formats (default, verbose, JSON)
  • Implemented /memory-config with show/set/reset subcommands and full validation
  • Implemented setup-troubleshooter agent with 5-step diagnostic flow and auto-fix capabilities
  • Created comprehensive troubleshooting guide with 15 documented issues and solutions
  • Added Quick Diagnostics section to SKILL.md with copy-paste commands

Task Commits

Each task was committed atomically:

  1. Task 1: Implement /memory-status Command - 57ae05b (feat)
  2. Task 2: Implement /memory-config Command - f1efe5f (feat)
  3. Task 3: Implement Troubleshooter Agent - 6b8eefb (feat)
  4. Task 4: Create Troubleshooting Guide - b46174f (docs)
  5. Task 5: Add Diagnostic Commands to SKILL.md - 364054a (docs)

Files Created/Modified

  • plugins/memory-setup-plugin/commands/memory-status.md - Full health check implementation with 7 checks, 3 output formats, troubleshooting hints
  • plugins/memory-setup-plugin/commands/memory-config.md - Configuration management with show/set/reset, validation, restart detection
  • plugins/memory-setup-plugin/agents/setup-troubleshooter.md - Autonomous troubleshooter with 5-step diagnostic flow, 6 categories, fix tiers
  • plugins/memory-setup-plugin/skills/memory-setup/references/troubleshooting-guide.md - 15 common issues with symptoms, diagnosis, solutions
  • plugins/memory-setup-plugin/skills/memory-setup/SKILL.md - Added Quick Diagnostics section with copy-paste commands

Decisions Made

  1. 7 Health Checks - Binary installed, daemon running, port listening, gRPC connectivity, database accessible, recent events, CCH hook configured
  2. 4 Status Levels - Healthy (all pass), Degraded (daemon running but issues), Unhealthy (not running), Not Installed (no binary)
  3. Configuration Validation - Type validation, value validation, provider-model validation, restart-required matrix
  4. 6 Diagnostic Categories - INSTALLATION, STARTUP, CONNECTION, INGESTION, SUMMARIZATION, RUNTIME
  5. Two-Tier Fix System - Safe auto-fixes (start daemon, create dirs, remove stale PID) vs permission-required fixes (install, change port, modify hooks)

Deviations from Plan

None - plan executed exactly as written.

Issues Encountered

None - all tasks completed successfully.

User Setup Required

None - no external service configuration required.

Next Phase Readiness

Phase 9 is now complete. The memory-setup-plugin provides:

  • Interactive setup wizard (/memory-setup)
  • Health checking (/memory-status)
  • Configuration management (/memory-config)
  • Autonomous troubleshooting (setup-troubleshooter agent)
  • Installation automation (install helper script)
  • Comprehensive troubleshooting documentation

Ready for:

  • User testing and feedback
  • Integration with memory-query-plugin
  • v2.0 planning

Phase: 09-setup-installer-plugin Completed: 2026-01-31

09-RESEARCH

Phase 9 Research: Setup & Installer Plugin

Objective

Create an interactive setup wizard plugin that guides users through installing, configuring, and managing agent-memory. The plugin should make first-time setup effortless while providing power-user options for advanced configuration.

User Journey Analysis

Target Users

  1. First-time users — Never used agent-memory, need guided installation
  2. Migrating users — Moving from manual setup to plugin-managed
  3. Power users — Want fine-grained control over configuration
  4. Troubleshooters — Something broke, need diagnostics

Key Questions Users Have

  1. "How do I install agent-memory?"
  2. "How do I configure it to capture my Claude Code sessions?"
  3. "Is it working? How do I check?"
  4. "How do I change settings after initial setup?"
  5. "Something's not working — how do I fix it?"

Installation Paths

Binary Installation Options

Method Pros Cons
Cargo install Works everywhere Rust is installed Requires Rust toolchain
Pre-built binaries Fast, no dependencies Need to host releases
Homebrew (macOS) Familiar to Mac users Mac-only, need tap
Download script One-liner install Security concerns

Recommended approach: Support multiple methods, detect what's available:

  1. Check for existing installation
  2. Check for cargo
  3. Offer download from GitHub releases
  4. Provide manual instructions as fallback

Installation Targets

Binary Purpose Install Location
memory-daemon gRPC service ~/.local/bin/ or ~/.cargo/bin/
memory-ingest CCH hook handler ~/.local/bin/ or ~/.cargo/bin/
memory-query (optional) CLI tool ~/.local/bin/ or ~/.cargo/bin/

Configuration Components

1. Daemon Configuration

File: ~/.config/agent-memory/config.toml

[daemon]
port = 50051
db_path = "~/.local/share/agent-memory/db"

[summarizer]
provider = "anthropic"  # or "openai", "local"
model = "claude-3-haiku-20240307"
# api_key loaded from ANTHROPIC_API_KEY env var

[segmentation]
time_threshold_mins = 30
token_threshold = 4000
overlap_mins = 5
overlap_tokens = 500

2. CCH Hook Configuration

File: ~/.claude/hooks.yaml (or project-level)

hooks:
  - event: "*"
    run: "~/.local/bin/memory-ingest"

3. Environment Variables

Variable Purpose Required
ANTHROPIC_API_KEY Summarization API Yes (if using Anthropic)
OPENAI_API_KEY Summarization API Yes (if using OpenAI)
MEMORY_DAEMON_PORT Override default port No
MEMORY_DB_PATH Override database location No

Interactive Wizard Flow

/memory-setup

┌─────────────────────────────────────────────────────┐
│  Agent Memory Setup Wizard                          │
└─────────────────────────────────────────────────────┘

Step 1: Check Prerequisites
  ✓ Claude Code detected
  ✗ memory-daemon not found
  ✗ memory-ingest not found

Step 2: Installation
  Q: How would you like to install?
  > [1] cargo install (recommended)
  > [2] Download pre-built binaries
  > [3] Manual installation (show instructions)

Step 3: Summarizer Configuration
  Q: Which AI provider for summarization?
  > [1] Anthropic Claude (recommended)
  > [2] OpenAI GPT
  > [3] Local model (ollama)
  > [4] Skip summarization (store events only)

  Q: Enter your API key (or press Enter to use env var):
  > [uses ANTHROPIC_API_KEY]

Step 4: Hook Configuration
  Q: Where should hooks be configured?
  > [1] Global (~/.claude/hooks.yaml)
  > [2] Current project only (.claude/hooks.yaml)
  > [3] Skip (I'll configure manually)

Step 5: Daemon Startup
  Q: How should the daemon start?
  > [1] Start now and on login (launchd/systemd)
  > [2] Start now only
  > [3] Manual start (show command)

Step 6: Verification
  ✓ Daemon started on port 50051
  ✓ Hook configuration written
  ✓ Test event ingested successfully

  Setup complete! Try: /memory-recent

Plugin Structure

plugins/memory-setup-plugin/
├── .claude-plugin/
│   └── marketplace.json
├── skills/
│   └── memory-setup/
│       ├── SKILL.md
│       └── references/
│           ├── installation-methods.md
│           ├── configuration-options.md
│           ├── troubleshooting-guide.md
│           └── platform-specifics.md
├── commands/
│   ├── memory-setup.md      # Interactive wizard
│   ├── memory-status.md     # Health check
│   └── memory-config.md     # Modify settings
└── agents/
    └── setup-troubleshooter.md  # Complex diagnostics

Commands Specification

/memory-setup

Purpose: Interactive setup wizard for first-time installation

Behavior:

  1. Detect current state (what's installed, what's configured)
  2. Ask questions progressively based on context
  3. Execute installation steps
  4. Verify setup works
  5. Provide next steps

Flags:

  • --fresh — Start from scratch, ignore existing config
  • --minimal — Quick setup with defaults, minimal questions
  • --advanced — Show all configuration options

/memory-status

Purpose: Check installation health and show current configuration

Output:

Agent Memory Status
───────────────────
Daemon:     ✓ Running (port 50051, PID 12345)
Database:   ✓ 1.2 GB, 15,432 events
Hooks:      ✓ Global hooks.yaml configured
API Key:    ✓ ANTHROPIC_API_KEY set

Recent Activity:
  Last event: 2 minutes ago
  Today: 47 events ingested
  This week: 312 events

Flags:

  • --json — Output as JSON for scripting
  • --verbose — Show full configuration details

/memory-config

Purpose: View or modify configuration after initial setup

Subcommands:

  • /memory-config show — Display current config
  • /memory-config set <key> <value> — Update setting
  • /memory-config reset — Reset to defaults

Examples:

/memory-config show
/memory-config set summarizer.provider openai
/memory-config set daemon.port 50052

Agent: setup-troubleshooter

Purpose: Diagnose and fix setup issues autonomously

Triggers:

  • User reports memory not working
  • /memory-status shows failures
  • Explicit /memory-troubleshoot invocation

Capabilities:

  1. Check daemon process status
  2. Verify port availability
  3. Test gRPC connectivity
  4. Validate configuration files
  5. Check API key validity
  6. Verify hook configuration
  7. Inspect recent logs
  8. Suggest and apply fixes

Example Flow:

User: "My conversations aren't being saved"

Agent:
1. Check if daemon is running → Not running
2. Attempt to start daemon → Port 50051 in use
3. Find process using port → Another memory-daemon
4. Offer to kill and restart → User approves
5. Start daemon → Success
6. Verify event ingestion → Working
7. Report resolution

Platform Considerations

macOS

  • Install location: ~/.local/bin/ (add to PATH in ~/.zshrc)
  • Auto-start: launchd plist in ~/Library/LaunchAgents/
  • Config: ~/.config/agent-memory/

Linux

  • Install location: ~/.local/bin/
  • Auto-start: systemd user service in ~/.config/systemd/user/
  • Config: ~/.config/agent-memory/

Windows

  • Install location: %USERPROFILE%.local\bin\
  • Auto-start: Task Scheduler or startup folder
  • Config: %APPDATA%\agent-memory\

Security Considerations

  1. API Keys: Never store in config files; use environment variables
  2. Binary Downloads: Verify checksums from GitHub releases
  3. Hook Permissions: Warn about hook execution permissions
  4. Database Location: Default to user-private directory

Integration with Existing Plugins

The setup plugin should detect and integrate with:

  • memory-query plugin: Suggest installation after setup complete
  • CCH hooks: Check for existing hooks.yaml before writing

Success Metrics

  1. User can go from zero to working memory in < 5 minutes
  2. All common issues have automated diagnostics
  3. Power users can access all options without wizard
  4. No manual file editing required for basic setup

Research Conclusions

  1. Plugin structure: Full marketplace plugin with 3 commands + 1 agent
  2. Installation: Support cargo install + pre-built binaries
  3. Wizard: Progressive disclosure, detect context, minimal questions
  4. Platform: macOS first, with Linux/Windows patterns documented
  5. Troubleshooting: Autonomous agent with diagnostic capabilities

Clone this wiki locally