setup.sh

#!/usr/bin/env bash
# setup.sh — Initialize persistent memory structure for an AI coding agent
#
# Usage:
#   ./setup.sh                    # Interactive — prompts for project info
#   ./setup.sh --dir .claude      # Non-interactive — use defaults
#   ./setup.sh --help             # Show help

set -euo pipefail

# Defaults
MEMORY_DIR=".claude/memory"
CLAUDE_MD=".claude/CLAUDE.md"
PROJECT_NAME=""
TECH_STACK=""
NON_INTERACTIVE=false

usage() {
    cat <<EOF
Usage: $(basename "$0") [OPTIONS]

Initialize persistent memory structure for an AI coding agent.

Options:
  --dir DIR          Base directory for memory files (default: .claude)
  --name NAME        Project name
  --stack STACK       Tech stack summary (e.g., "Next.js, TypeScript, PostgreSQL")
  --non-interactive  Skip prompts, use defaults
  --help             Show this help

Examples:
  $(basename "$0")                              # Interactive setup
  $(basename "$0") --dir .claude --name myapp   # Specify project name
  $(basename "$0") --non-interactive            # Use all defaults
EOF
    exit 0
}

# Parse arguments
while [[ $# -gt 0 ]]; do
    case "$1" in
        --dir)    MEMORY_DIR="$2/memory"; CLAUDE_MD="$2/CLAUDE.md"; shift 2 ;;
        --name)   PROJECT_NAME="$2"; shift 2 ;;
        --stack)  TECH_STACK="$2"; shift 2 ;;
        --non-interactive) NON_INTERACTIVE=true; shift ;;
        --help)   usage ;;
        *)        echo "Unknown option: $1"; usage ;;
    esac
done

# Interactive prompts
if [[ "$NON_INTERACTIVE" != true ]]; then
    if [[ -z "$PROJECT_NAME" ]]; then
        read -rp "Project name (or press Enter to skip): " PROJECT_NAME
    fi
    if [[ -z "$TECH_STACK" ]]; then
        read -rp "Tech stack (e.g., 'Next.js, TypeScript, PostgreSQL', or press Enter to skip): " TECH_STACK
    fi
fi

# Create directory structure
echo "Creating memory structure in $(dirname "$MEMORY_DIR")/"
mkdir -p "$MEMORY_DIR"

# --- MEMORY.md (index file) ---
if [[ ! -f "$MEMORY_DIR/MEMORY.md" ]]; then
    cat > "$MEMORY_DIR/MEMORY.md" <<MEMEOF
# Project Memory

**Keep this file under 200 lines.** Push details into topic files and link to them here.

---

## Architecture
${PROJECT_NAME:+- **Project**: $PROJECT_NAME}
${TECH_STACK:+- **Stack**: $TECH_STACK}
- Details: \`memory/architecture.md\`

## Patterns & Conventions
- Details: \`memory/patterns.md\`

## Debugging Notes
- Details: \`memory/debugging.md\`

## Workflows
- Details: \`memory/workflows.md\`

## User Preferences
- *(Add preferences as you discover them — communication style, tooling choices, etc.)*
MEMEOF
    echo "  Created $MEMORY_DIR/MEMORY.md"
else
    echo "  Skipped $MEMORY_DIR/MEMORY.md (already exists)"
fi

# --- Topic files ---
create_topic_file() {
    local file="$1"
    local title="$2"
    local content="$3"

    if [[ ! -f "$MEMORY_DIR/$file" ]]; then
        cat > "$MEMORY_DIR/$file" <<TOPICEOF
# $title

$content
TOPICEOF
        echo "  Created $MEMORY_DIR/$file"
    else
        echo "  Skipped $MEMORY_DIR/$file (already exists)"
    fi
}

create_topic_file "architecture.md" "Architecture" \
"Key architectural decisions and project structure.

## Project Structure
*(Document your project's directory layout and key files here)*

## Key Decisions
*(Record important architectural decisions and their rationale)*

## Dependencies
*(Note critical dependencies and why they were chosen)*"

create_topic_file "patterns.md" "Patterns & Conventions" \
"Recurring patterns, naming conventions, and code standards.

## Code Style
*(Document coding conventions used in this project)*

## API Patterns
*(Common patterns for API routes, data fetching, etc.)*

## Component Patterns
*(UI component conventions, file organization, etc.)*"

create_topic_file "debugging.md" "Debugging Notes" \
"Solutions to problems that took real effort to solve. Update in place — don't let stale fixes accumulate.

*(Add entries as you solve non-obvious problems. Format: problem → root cause → fix)*"

create_topic_file "workflows.md" "Workflows" \
"How-to guides and processes for this project.

## Development
*(Local dev setup, build commands, etc.)*

## Testing
*(How to run tests, what to test, etc.)*

## Deployment
*(Deploy process, environments, etc.)*"

# --- CLAUDE.md integration ---
if [[ ! -f "$CLAUDE_MD" ]]; then
    cat > "$CLAUDE_MD" <<CLAUDEEOF
# Project Instructions

## Memory

You have persistent memory at \`$(dirname "$MEMORY_DIR")/memory/\`. Its contents persist across conversations.

**At the start of every session**, read \`memory/MEMORY.md\` to load context from previous sessions.

### How to use memory:
- Consult memory files before starting work
- Update memory when you learn something stable and reusable
- Organize by topic, not chronologically — update in place
- Keep MEMORY.md under 200 lines — push details into topic files
- Delete or update memories that turn out to be wrong
- Do not save session-specific or speculative information

### What to save:
- Stable patterns confirmed across multiple interactions
- Key architectural decisions and important file paths
- User preferences for workflow, tools, and communication style
- Solutions to recurring problems and debugging insights

### What NOT to save:
- Session-specific context (current task details, in-progress work)
- Information that might be incomplete — verify first
- Anything that duplicates existing project documentation
CLAUDEEOF
    echo "  Created $CLAUDE_MD"
else
    echo "  Skipped $CLAUDE_MD (already exists)"
    echo ""
    echo "  To add memory support to your existing CLAUDE.md, add:"
    echo "    \"Read memory/MEMORY.md at the start of every session.\""
fi

echo ""
echo "Done! Memory structure initialized at $(dirname "$MEMORY_DIR")/"
echo ""
echo "Next steps:"
echo "  1. Review and customize the generated files"
echo "  2. Add project-specific context to MEMORY.md"
echo "  3. Start a Claude Code session — it will read MEMORY.md automatically"
echo ""
echo "Tip: Add memory/ to version control so it persists across machines."