Búsqueda semántica y búsqueda de texto

En una línea: en qué se diferencia semantic_search de search_content, y qué pregunta le toca a cada una.

Qué resuelve

MCP tiene más de una manera de encontrar cosas, y responden a preguntas distintas.

search_content encuentra las palabras que escribiste. Te acuerdas de haber escrito «horno de letras» y te devuelve todos los sitios donde aparece, con la ruta y las líneas de alrededor.

semantic_search encuentra aquello que querías decir. Preguntas «¿en qué escena sale a la superficie el rencor de la madre?» y te devuelve la escena aunque ninguna de esas palabras aparezca en ella.

Casi todas las preguntas que plantea de verdad un manuscrito largo son del segundo tipo. Recuerdas que había un pasaje; no recuerdas con qué palabras lo escribiste entonces.

Cuál usar

Lo que quieres	Usa
Todos los archivos que contienen «puerto de Linze»	search_content
Todas las menciones de un personaje, antes de cambiarle el nombre	search_content
La escena donde la relación empieza a torcerse	semantic_search
Si el libro ya explicó en algún sitio la prohibición de navegar	semantic_search
Aquella metáfora de la marea llevándose las palabras, la de antes de la reescritura	semantic_search
Si la base de conocimiento del equipo ya cubre esta situación	semantic_search

search_content: coincidencia literal

search_content({
  "book_token": "bk_...",
  "query": "horno de letras",
  "file_types": ["md"],
  "limit": 20
})

No distingue mayúsculas y devuelve la ruta de cada archivo con coincidencias más las líneas que rodean al resultado.

En un libro 4.0, file_types importa más de lo que parece. Los archivos estructurados (.beats, .timeline, .script, .map, .geomap) también se buscan, y se buscan como su JSON en crudo. Así que una palabra corriente como name o title puede volver convertida en una página de nombres de campo en vez de contenido. Pon file_types: ["md"] cuando quieras solo prosa.

Los libros antiguos de Script Studio funcionan al revés: ahí los archivos estructurados quedan excluidos por defecto y hay que añadir include_structured: true para incluirlos. Mira Herramientas que se comportan distinto en ciertos archivos.

semantic_search: coincidencia por significado

semantic_search({
  "book_token": "bk_...",
  "query": "donde Shen Yan duda por primera vez de su padre",
  "limit": 10
})

Tres argumentos: el libro, una pregunta en lenguaje corriente y cuántos resultados quieres (10 por defecto, con un tope de 50).

Cada resultado trae cuatro cosas: el §número del párrafo, el token del archivo, el pasaje en sí y una puntuación de similitud. El §número es un ancla citable: la IA puede decirte «esto está en el capítulo 3, §4» en lugar de señalar vagamente hacia la mitad del libro.

De dónde sale el índice

En la primera búsqueda, Slima parte en párrafos el contenido del último commit del libro y lo indexa. A partir de ahí solo vuelve a calcular lo que cambió, de modo que los archivos intactos no cuestan nada. Por eso la primera búsqueda en un libro grande es más lenta que las siguientes.

Un libro grande que nunca se ha indexado pasa el trabajo a una construcción en segundo plano. Esa búsqueda vuelve vacía, y «vacía» aquí significa «todavía no está construido», no «no hay coincidencias». Búscalo otra vez al rato y los resultados están.

Cuesta un poco

Convertir tu pregunta en un vector es un cálculo pequeño, así que semantic_search consume unos pocos créditos. La búsqueda literal no. La cantidad es mínima, pero es la única diferencia de coste entre ambas y conviene saberlo.

Tres cosas que no puede hacer

• Encontrar una cadena exacta. Para una palabra precisa o un signo de puntuación, search_content.
• Encontrar texto que aún no está en un commit. El índice se construye desde los commits. Un párrafo que el autor acaba de teclear en la app y todavía no ha entrado en un commit no está ahí.
• Llegar a los archivos de habilidad confidenciales de un equipo. Esos nunca se indexan, así que la similitud semántica no es una puerta trasera hacia ellos.

Donde más rinde: una base de conocimiento del equipo

Una base de conocimiento del equipo puede guardar decenas de normas de la casa, decisiones ya cerradas y detalles de libros anteriores. Ahí, la distancia entre búsqueda literal y búsqueda semántica es la distancia entre hojear y preguntar: ya no necesitas saber en qué archivo se escribió aquello ni bajo qué encabezado estaba. Basta con «¿ya fijamos cómo se llama la moneda de este mundo?».

Relacionado

• Docs: Herramientas de operaciones de archivo
• Docs: Herramientas de notas y comentarios
• Docs: Herramientas que se comportan distinto en ciertos archivos
• Docs: Buscar y reemplazar