---
description: Semantic search for ACE patterns using natural language query
---

# ACE Semantic Search

Search for relevant patterns using natural language query instead of retrieving all patterns.

## What This Does

Uses semantic search to find only the most relevant patterns matching your query, reducing context usage by 50-80%.

## Instructions for Claude

When the user runs `/ace-search <query>`, use the Bash tool to call ce-ace CLI:

```bash
#!/usr/bin/env bash
set -euo pipefail

# Check ce-ace is available
if ! command -v ce-ace >/dev/null 2>&1; then
  echo "❌ ce-ace CLI not found in PATH"
  echo ""
  echo "Installation:"
  echo "  npm install -g @ace-sdk/cli"
  echo ""
  exit 1
fi

# Get context from .claude/settings.json and export as env vars
export ACE_ORG_ID=$(jq -r '.orgId // .env.ACE_ORG_ID // empty' .claude/settings.json 2>/dev/null || echo "")
export ACE_PROJECT_ID=$(jq -r '.projectId // .env.ACE_PROJECT_ID // empty' .claude/settings.json 2>/dev/null || echo "")

if [ -z "$ACE_ORG_ID" ] || [ -z "$ACE_PROJECT_ID" ]; then
  echo "❌ No .claude/settings.json found or missing orgId/projectId"
  echo "Run /ace-configure to set up ACE"
  exit 1
fi

# Call ce-ace search - CLI reads org/project from env vars automatically
# Threshold comes from server config (ce-ace tune show) - don't override!
ce-ace search "$*"
```

### Parameters

- **query** (required): Natural language description passed as command argument
  - Examples: "authentication patterns", "async debugging tips", "database connection pooling best practices"
- **--threshold**: Similarity threshold (optional, overrides server config)
  - Default: Uses server config from `ce-ace tune show`
  - Range: 0.0 - 1.0 (higher = stricter matching)
  - Only specify if you want to override project's default
- **--json**: Return JSON format for programmatic use

**Note**: To limit number of results, use `jq` for filtering:
```bash
ce-ace search "query" --json | jq '.patterns[:5]'  # First 5 results
```
The `--limit` flag is not supported by ce-ace CLI. Use `--top-k` via server config (`/ace-tune`) instead.

### Example Usage

```bash
/ace-search JWT authentication best practices
→ Calls: ce-ace search "JWT authentication best practices"
→ Uses: Server config threshold (e.g., 0.45)

/ace-search async test failures debugging
→ Calls: ce-ace search "async test failures debugging"

# Override threshold if needed:
/ace-search "JWT auth" --threshold 0.7
→ Calls: ce-ace search "JWT auth" --threshold 0.7
```

### When to Use This

✅ **Use `/ace-search` when**:
- You have a specific implementation question
- You're debugging a specific type of problem
- You know what domain/topic you need help with
- You want to minimize context usage

❌ **Don't use when**:
- You need comprehensive architectural overview
- You're working on multi-domain tasks
- You want to see all patterns in a section

For those cases, use `/ace-patterns` instead.

## Output Format

The tool returns JSON with matching patterns and metadata (v3.8.0+):

```json
{
  "patterns": [
    {
      "content": "Pattern description with context",
      "helpful": 8,
      "harmful": 0,
      "confidence": 0.92,
      "section": "strategies_and_hard_rules",
      "similarity": 0.87
    }
  ],
  "query": "your search query",
  "count": 10,
  "metadata": {
    "tokens_in_response": 2400,
    "tokens_saved_vs_full_playbook": 27600,
    "efficiency_gain": "92%",
    "full_playbook_size": 30000
  }
}
```

Patterns are sorted by semantic similarity to your query.

**Metadata field** (v3.8.0+): Provides token efficiency metrics. Omitted if `include_metadata=false`.

## Performance Impact

**Before** (full playbook):
- Retrieves: ALL patterns in section
- Token usage: ~10,000-15,000 tokens (measured via metadata)
- Time: 100-300ms

**After** (semantic search with metadata):
- Retrieves: Top 10 relevant patterns only
- Token usage: ~2,400 tokens (confirmed via metadata)
- Time: 150-400ms
- **50-92% token reduction** (exact savings shown in metadata.efficiency_gain)

**After** (semantic search without metadata):
- Token usage: ~2,000-2,200 tokens
- Time: 140-390ms (~10ms faster)
- **85-92% token reduction**

**Metadata overhead**: Adds ~5-10ms response time + ~200-400 tokens for efficiency metrics

## See Also

- `/ace-top` - Get highest-rated patterns by helpful score
- `/ace-patterns` - View full playbook (comprehensive)
- `/ace-status` - Check playbook statistics