ua-embeddings

/ua-embeddings

Generates a vector embedding for each node in .understand-anything/knowledge-graph.json and writes the results to .understand-anything/embeddings.json. Once generated, the MCP server's search_nodes tool automatically uses these for semantic search — enabling conceptual queries like "which files handle rate limiting?" rather than just keyword matching.

Requirements

An OpenAI-compatible embedding API. Set one of:

• OPENAI_API_KEY — uses OpenAI's text-embedding-3-small model (recommended)
• EMBEDDING_ENDPOINT + EMBEDDING_API_KEY — uses any compatible endpoint (e.g. Cohere, Together, local)

Note: Anthropic's Claude API does not expose an embedding endpoint. An OpenAI-compatible provider is required. The MCP server degrades gracefully to Fuse.js fuzzy search when embeddings are absent — this skill is optional.

Instructions

1. Check the graph exists:

   [ -f .understand-anything/knowledge-graph.json ] || { echo "No knowledge graph found. Run /understand first."; exit 1; }
   

2. Check API key is set:

   [ -n "$OPENAI_API_KEY" ] || [ -n "$EMBEDDING_API_KEY" ] || {
     echo "No embedding API key found."
     echo ""
     echo "To use OpenAI embeddings:"
     echo "  export OPENAI_API_KEY=<your-key>"
     echo ""
     echo "To use any OpenAI-compatible provider:"
     echo "  export EMBEDDING_ENDPOINT=<url>"
     echo "  export EMBEDDING_API_KEY=<key>"
     exit 1
   }
   

3. Resolve the plugin root using the standard pattern (check $CLAUDE_PLUGIN_ROOT, then ~/.understand-anything-plugin, then symlink resolution from ~/.agents/skills/ua-embeddings):

   SKILL_REAL=$(realpath ~/.agents/skills/ua-embeddings 2>/dev/null || readlink -f ~/.agents/skills/ua-embeddings 2>/dev/null || echo "")
   SELF_RELATIVE=$([ -n "$SKILL_REAL" ] && cd "$SKILL_REAL/../.." 2>/dev/null && pwd || echo "")
   
   PLUGIN_ROOT=""
   for candidate in \
     "${CLAUDE_PLUGIN_ROOT}" \
     "$HOME/.understand-anything-plugin" \
     "$SELF_RELATIVE" \
     "$HOME/.codex/understand-anything/understand-anything-plugin" \
     "$HOME/.opencode/understand-anything/understand-anything-plugin" \
     "$HOME/understand-anything/understand-anything-plugin"; do
     if [ -n "$candidate" ] && [ -f "$candidate/package.json" ] && [ -f "$candidate/pnpm-workspace.yaml" ]; then
       PLUGIN_ROOT="$candidate"
       break
     fi
   done
   
   if [ -z "$PLUGIN_ROOT" ]; then
     echo "Error: Cannot find the understand-anything plugin root."
     exit 1
   fi
   

4. Set PROJECT_ROOT to the current working directory (or argument if provided):

   PROJECT_ROOT="${1:-$(pwd)}"
   

5. Run the generation script:

   node "$PLUGIN_ROOT/scripts/ua-generate-embeddings.mjs" "$PROJECT_ROOT"
   

6. The script handles progress reporting and writes .understand-anything/embeddings.json. Report its output to the user.

After completion

The MCP server's search_nodes tool automatically detects and uses embeddings.json when the server is connected. No server restart is needed — the file is read on each tool call.

Re-run /ua-embeddings after /understand refreshes the graph to keep embeddings current.