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

Command	Purpose	Example
/memory-setup	Interactive installation wizard	/memory-setup
/memory-status	Health check and diagnostics	/memory-status --verbose
/memory-config	View/modify configuration	/memory-config show

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

Platform	Config	Data	Logs
macOS	~/.config/memory-daemon/	~/.memory-store/	~/Library/Logs/memory-daemon/
Linux	~/.config/memory-daemon/	~/.local/share/memory-daemon/	~/.local/state/memory-daemon/
Windows	%APPDATA%\memory-daemon\	%LOCALAPPDATA%\memory-daemon\	%LOCALAPPDATA%\memory-daemon\logs\

Error Handling

Error	Resolution
"command not found"	Cargo bin not in PATH, or not installed
"connection refused"	Daemon not running: memory-daemon start
"permission denied"	Check data directory permissions
"address in use"	Another process on port 50051

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:

Symbol	Meaning	When to Use
[check]	Success/Complete	Item verified or action succeeded
[x]	Missing/Failed	Item not found or action failed
[!]	Warning	Non-critical issue, can continue
[?]	Unknown	Could not determine status
[>]	In Progress	Currently executing

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:

Element	Color	ANSI Code
Success	Green	\033[32m
Error	Red	\033[31m
Warning	Yellow	\033[33m
Info	Blue	\033[34m
Headers	Bold	\033[1m
Reset	-	\033[0m

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