memory-setup

name: memory-setup description: | Setup, configure, and troubleshoot agent-memory installation. Use when asked to "install agent-memory", "setup memory", "check memory status", "configure memory daemon", "fix memory issues", or "troubleshoot memory". Provides interactive setup wizard, health checks, and configuration management. license: MIT metadata: version: 1.0.0 author: SpillwaveSolutions

Memory Setup Skill

Setup, configure, and troubleshoot agent-memory installation with guided workflows and autonomous diagnostics.

When Not to Use

• Querying past conversations (use memory-query plugin)
• Real-time event ingestion (handled by CCH hooks automatically)
• Low-level storage operations (use memory-daemon admin commands directly)

Quick Start

Installation Decision Tree

Is memory-daemon installed?
├── NO → /memory-setup
│   ├── --fresh: Clean installation
│   ├── --minimal: Just the daemon
│   └── --advanced: Custom paths/options
│
└── YES → Is it running?
    ├── NO → memory-daemon start
    │   └── Still failing? → /memory-status --verbose
    │
    └── YES → Is CCH hook configured?
        ├── NO → /memory-setup (detects existing install)
        └── YES → All good! Use /memory-search

Workflow Overview

1. Initial Setup (/memory-setup)

# Check if Rust toolchain exists
rustc --version

# Install memory-daemon
cargo install --git https://github.com/SpillwaveSolutions/agent-memory memory-daemon

# Verify installation
memory-daemon --version

2. Health Check (/memory-status)

# Quick status
memory-daemon status

# Verbose diagnostics
memory-daemon status --verbose

# Check CCH hook
cat ~/.claude/code_agent_context_hooks/hooks.yaml

3. Configuration (/memory-config)

# Show current config
cat ~/.config/memory-daemon/config.toml

# Set a value (example)
# Edit ~/.config/memory-daemon/config.toml

4. Troubleshooting (Agent: setup-troubleshooter)

Automatic activation for:

• "memory-daemon won't start"
• "no data in memory"
• "connection refused"
• "events not being captured"

Validation Checklist

Before confirming setup complete:

• memory-daemon --version returns version string
• memory-daemon status shows "running"
• ~/.config/memory-daemon/config.toml exists
• ~/.memory-store/ directory exists (or custom path)
• CCH hooks.yaml includes memory-ingest handler (if using CCH)

Platform Paths

Error Handling

State Detection

Before beginning setup, detect current system state to skip completed steps and offer appropriate options.

1. Prerequisites Check

# Claude Code detection (presence of .claude directory)
ls ~/.claude 2>/dev/null && echo "CLAUDE_CODE_DETECTED" || echo "CLAUDE_CODE_NOT_FOUND"

# Rust/Cargo availability
cargo --version 2>/dev/null && echo "CARGO_AVAILABLE" || echo "CARGO_NOT_AVAILABLE"

# Platform detection
uname -s  # Returns: Darwin, Linux, or MINGW*/MSYS* for Windows
uname -m  # Returns: arm64, x86_64, etc.

State Categories:

• READY: All prerequisites met, can proceed with cargo install
• NEEDS_RUST: cargo not found, offer rustup installation
• MANUAL_ONLY: No cargo, must use pre-built binaries

2. Existing Installation Check

# Binary locations
which memory-daemon 2>/dev/null || echo "NOT_INSTALLED"
which memory-ingest 2>/dev/null || echo "NOT_INSTALLED"

# Version check (if installed)
memory-daemon --version 2>/dev/null || echo "VERSION_UNKNOWN"
memory-ingest --version 2>/dev/null || echo "VERSION_UNKNOWN"

# Check common installation paths
ls ~/.cargo/bin/memory-daemon 2>/dev/null
ls ~/.local/bin/memory-daemon 2>/dev/null
ls /usr/local/bin/memory-daemon 2>/dev/null

State Categories:

• NOT_INSTALLED: No binaries found
• INSTALLED: Binaries found, capture version
• OUTDATED: Installed version < latest release
• PARTIAL: Only some binaries installed

3. Configuration State Check

# Config file existence
ls ~/.config/memory-daemon/config.toml 2>/dev/null && echo "CONFIG_EXISTS" || echo "NO_CONFIG"

# CCH hooks check (global)
grep -l "memory-ingest" ~/.claude/code_agent_context_hooks/hooks.yaml 2>/dev/null && echo "HOOK_GLOBAL" || echo "NO_GLOBAL_HOOK"

# CCH hooks check (project - current directory)
grep -l "memory-ingest" .claude/code_agent_context_hooks/hooks.yaml 2>/dev/null && echo "HOOK_PROJECT" || echo "NO_PROJECT_HOOK"

# Environment variables
[ -n "$OPENAI_API_KEY" ] && echo "OPENAI_KEY_SET" || echo "OPENAI_KEY_MISSING"
[ -n "$ANTHROPIC_API_KEY" ] && echo "ANTHROPIC_KEY_SET" || echo "ANTHROPIC_KEY_MISSING"

State Categories:

• UNCONFIGURED: No config.toml
• CONFIGURED: config.toml exists
• HOOKED_GLOBAL: CCH hook configured globally
• HOOKED_PROJECT: CCH hook configured for project
• API_READY: At least one API key available

4. Runtime State Check

# Daemon process running
memory-daemon status 2>/dev/null
# Returns: running/stopped/error

# Port availability (if daemon not running)
lsof -i :50051 2>/dev/null && echo "PORT_IN_USE" || echo "PORT_AVAILABLE"

# Recent activity check
memory-daemon query root 2>/dev/null && echo "DAEMON_RESPONSIVE" || echo "DAEMON_UNRESPONSIVE"

# Event count (if daemon running)
memory-daemon admin status 2>/dev/null | grep -o 'events: [0-9]*'

State Categories:

• RUNNING: Daemon active and responsive
• STOPPED: Daemon not running, port available
• PORT_BLOCKED: Port in use by another process
• UNRESPONSIVE: Process exists but not responding

State Summary Format

After detection, present state summary:

Current State
─────────────
Prerequisites:  ✓ Claude Code, ✓ Cargo (1.75.0), macOS arm64
Installation:   ✓ memory-daemon (1.0.0), ✓ memory-ingest (1.0.0)
Configuration:  ✓ config.toml, ✗ CCH hook not configured
Runtime:        ✗ Daemon not running (port available)

Recommended:    Configure CCH hook, then start daemon

Output Formatting

Use consistent visual formatting throughout the wizard for clear user communication.

Progress Display

Show wizard progress with step indicators:

Agent Memory Setup
==================

Checking prerequisites...
  [check] Claude Code detected
  [check] cargo available (1.75.0)
  [x] memory-daemon not found
  [x] memory-ingest not found

Step 1 of 6: Installation
-------------------------

Step Headers

Each wizard step uses consistent header formatting:

Step N of 6: Step Name
----------------------
[Question or action content]

Status Indicators

Use consistent symbols for status:

Success Display

Final success message format:

==================================================
 Setup Complete!
==================================================

[check] Binaries installed to ~/.cargo/bin/
[check] Configuration written to ~/.config/memory-daemon/
[check] Hooks configured in ~/.claude/code_agent_context_hooks/hooks.yaml
[check] 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

Partial Success Display

When some steps succeed but others are skipped or fail:

==================================================
 Setup Partially Complete
==================================================

[check] Binaries installed to ~/.cargo/bin/
[check] Configuration written to ~/.config/memory-daemon/
[x] CCH hook not configured (manual setup required)
[check] Daemon started on port 50051

What's missing:
  * CCH integration not configured - events won't be captured automatically

To complete setup manually:
  1. Add to ~/.claude/code_agent_context_hooks/hooks.yaml:
     hooks:
       - event: all
         handler:
           type: pipe
           command: memory-ingest

  2. Verify with: /memory-status

Error Display

When setup fails, provide actionable error information:

[x] 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

Need help? Run: /memory-status --verbose

Question Format

When asking user for input:

Which LLM provider should generate summaries?

1. Anthropic (Claude) - Best quality summaries
2. OpenAI (GPT-4o-mini) - Fast and cost-effective
3. Local (Ollama) - Private, runs locally
4. None - Skip summarization

Default: 1 (Anthropic)

Enter selection [1-4]:

Summary Tables

Use tables for displaying configuration and status summaries:

### Installation Summary

| Component | Status | Version | Path |
|-----------|--------|---------|------|
| memory-daemon | Installed | 1.0.0 | ~/.cargo/bin/ |
| memory-ingest | Installed | 1.0.0 | ~/.cargo/bin/ |

### Configuration

| Setting | Value |
|---------|-------|
| Storage Path | ~/.memory-store |
| Server | [::1]:50051 |
| LLM Provider | Anthropic (claude-3-5-haiku-latest) |
| CCH Hooks | Global |

Progress Bar (Optional)

For long operations like cargo install:

Installing memory-daemon...
[################----] 80% - Compiling memory-daemon v1.0.0

Color Guidelines (Terminal Support)

When terminal supports colors:

Note: Always check terminal capability before using colors. Fall back to text indicators ([check], [x], etc.) when colors unavailable.

Quick Diagnostics

Copy-paste commands for rapid troubleshooting. Use these to quickly assess the state of the memory system.

Full System Check (One-Liner)

# Complete diagnostic in one command
echo "=== Binary ===" && which memory-daemon && memory-daemon --version && \
echo "=== Status ===" && memory-daemon status && \
echo "=== Port ===" && lsof -i :50051 && \
echo "=== Storage ===" && memory-daemon admin --db-path ~/.memory-store stats && \
echo "=== Hooks ===" && grep memory-ingest ~/.claude/code_agent_context_hooks/hooks.yaml 2>/dev/null || echo "No hook configured"

Individual Diagnostic Commands

Binary and Version:

which memory-daemon && memory-daemon --version
which memory-ingest && memory-ingest --version

Daemon Status:

memory-daemon status
ps aux | grep memory-daemon | grep -v grep

Port and Connectivity:

lsof -i :50051
memory-daemon query --endpoint http://[::1]:50051 root

Storage Health:

memory-daemon admin --db-path ~/.memory-store stats
du -sh ~/.memory-store

Configuration:

cat ~/.config/memory-daemon/config.toml

CCH Hooks:

cat ~/.claude/code_agent_context_hooks/hooks.yaml
grep memory-ingest ~/.claude/code_agent_context_hooks/hooks.yaml

Environment Variables:

echo "OPENAI: ${OPENAI_API_KEY:+set}" && echo "ANTHROPIC: ${ANTHROPIC_API_KEY:+set}"

Logs (macOS):

tail -50 ~/Library/Logs/memory-daemon/daemon.log

Logs (Linux):

tail -50 ~/.local/state/memory-daemon/daemon.log

Quick Fixes

Start daemon:

memory-daemon start && memory-daemon status

Restart daemon:

memory-daemon stop && sleep 2 && memory-daemon start

Fix port conflict:

kill $(lsof -t -i :50051) && memory-daemon start

Remove stale PID:

rm ~/Library/Application\ Support/memory-daemon/daemon.pid 2>/dev/null
rm ~/.local/state/memory-daemon/daemon.pid 2>/dev/null
memory-daemon start

Create default config:

mkdir -p ~/.config/memory-daemon && cat > ~/.config/memory-daemon/config.toml << 'EOF'
[storage]
path = "~/.memory-store"

[server]
host = "[::1]"
port = 50051

[summarizer]
provider = "openai"
model = "gpt-4o-mini"
EOF

Fix permissions:

chmod 700 ~/.memory-store ~/.config/memory-daemon

Run compaction:

memory-daemon admin --db-path ~/.memory-store compact

Enable debug logging:

MEMORY_LOG_LEVEL=debug memory-daemon start

Diagnostic Decision Tree

Something wrong?
│
├── "command not found"
│   └── Check PATH: echo $PATH | grep cargo
│       └── Add: export PATH="$HOME/.cargo/bin:$PATH"
│
├── "connection refused"
│   └── Check status: memory-daemon status
│       ├── Not running → memory-daemon start
│       └── Running → Check port: lsof -i :50051
│
├── "no events"
│   └── Check hook: grep memory-ingest ~/.claude/.../hooks.yaml
│       ├── Missing → Run /memory-setup
│       └── Present → Check daemon: memory-daemon status
│
├── "summarization failing"
│   └── Check API key: echo ${OPENAI_API_KEY:+set}
│       ├── Not set → export OPENAI_API_KEY=...
│       └── Set → Check logs for API errors
│
└── Other issues
    └── Run: /memory-status --verbose
        └── Still stuck → Say "troubleshoot memory"

Advanced Configuration Options

These options are available in --advanced mode:

Server Timeout

In --advanced mode, after server configuration, ask:

Configure server timeout?

1. 30 seconds (Default)
2. 60 seconds (for slow connections)
3. Custom

Config: [server] timeout_secs = 30

TOC Overlap Settings

In --advanced mode, after segmentation tuning, ask:

Configure segment overlap for context continuity?

1. Standard (500 tokens, 5 minutes) - Recommended
2. Minimal (100 tokens, 1 minute) - Less context
3. Maximum (1000 tokens, 10 minutes) - More context
4. Custom

Config:

[toc]
overlap_tokens = 500
overlap_minutes = 5

Logging Configuration

In --advanced mode, add logging step:

Configure logging output?

1. Info to stderr (Default)
2. Debug to stderr (verbose)
3. Debug to file
4. Custom

Config:

[logging]
level = "info"    # trace, debug, info, warn, error
format = "pretty" # pretty, json, compact
file = ""         # empty = stderr, or path like ~/.memory-daemon.log

Reference Files

For detailed information, see:

• Installation Methods - Cargo, binaries, building from source
• Configuration Options - All config.toml options
• Troubleshooting Guide - Common issues and solutions
• Platform Specifics - macOS, Linux, Windows details
• Wizard Questions - Complete interactive wizard question flow
• Advanced Options - Server, TOC, and logging options

Related Skills

For specialized configuration:

• /memory-storage - Storage paths, retention, cleanup, GDPR
• /memory-llm - LLM provider, model discovery, cost estimation
• /memory-agents - Multi-agent mode, team settings