Walliiee/agent-harness

QMD — Motor de Búsqueda de Conocimiento Local

QMD es el motor de búsqueda local de vectores + palabras clave sobre los espacios de trabajo del usuario. Úsalo antes de responder preguntas que ya puedan estar documentadas — especialmente para obtener contexto sobre personas, proyectos, decisiones y trabajo pasado.

Flujo de trabajo

El flujo de trabajo es siempre:

1. Buscar documentos candidatos.
2. Recuperar la fuente completa con qmd get o qmd multi-get.
3. Responder a partir del texto recuperado, citando rutas o identificadores de documentos.

No respondas solo a partir de fragmentos cuando el usuario necesite hechos, decisiones, citas o matices. Los fragmentos son solo pistas.

Al informar lo que recuperaste, una nota compacta es suficiente; no pegues archivos completos a menos que sea necesario:

Recuperado: #abc123 wiki/projects/GenAICategorizer.md, #def432 memory/2026-05-26.md

Elige el modo de búsqueda adecuado

Modo	Comando	Cuándo usarlo
BM25 por palabras clave	qmd search	Palabras exactas, títulos, nombres, símbolos de código, frases raras
Híbrido + reranking	qmd query	Redacción indirecta, recuperación conceptual, mejor calidad
Estructurado	qmd query con campos lex:/vec:/hyde:	Búsquedas difíciles que necesitan anclajes exactos + recuperación semántica

Búsqueda simple:

qmd search "estado del proyecto challenger crew" -n 10
qmd search '"GenAI Categorizer"' -c wiki-main -n 5

Búsqueda de concepto semántico:

qmd query "la calidad de las decisiones depende de sacar a la luz suposiciones y contexto" -n 10

Consulta estructurada (búsquedas difíciles):

qmd query $'intent: Encontrar la nota conceptual sobre métricas como instrumentos sin dejar que los OKR reemplacen el juicio.
lex: instrumentos de cabina OKR métricas Goodhart juicio
vec: decisiones informadas por datos no impulsadas por métricas juicio del producto
hyde: Una nota conceptual dice que las métricas son útiles como los instrumentos de cabina, pero los líderes deben mantenerse informados por datos en lugar de impulsados por métricas porque los OKR y los paneles pueden afectar el juicio del producto según Goodhart.'

Campos de consulta estructurada:

• intent: indica qué estás tratando de encontrar y qué evitar.
• lex: términos exactos, alias, títulos y palabras raras.
• vec: parafrasea la idea en lenguaje natural.
• hyde: describe el documento o la respuesta que satisfaría la solicitud.

Recuperar fuentes

qmd get "#abc123"                        # por id de documento de resultados de búsqueda
qmd get "wiki/projects/GenAICategorizer.md" --full  # por ruta
qmd multi-get "#abc123,#def432" --md     # por lotes por ids de documentos
qmd multi-get 'memory/2026-05-*.md' -l 80  # por lotes con glob

Usa multi-get al comparar varios resultados o reunir contexto de varias páginas. Usa --full cuando la fuente exacta sea importante.

Colecciones por agente

Cada agente tiene su propio índice QMD con configuración aislada por XDG. La lista de agentes se encuentra en ${OPENCLAW_HOME}/config/agents.map. Al buscar desde la CLI, usa el envoltorio XDG del agente:

# agente principal
XDG_CONFIG_HOME=${OPENCLAW_HOME}/agents/main/qmd/xdg-config XDG_CACHE_HOME=${OPENCLAW_HOME}/agents/main/qmd/xdg-cache qmd query "..."
# agente de desarrollo y cualquier otro agente — mismo patrón, intercambia el nombre del agente

Colecciones del agente principal

Colección	Contenido
identity-main	Documentos principales — SOUL, IDENTITY, TOOLS, AGENTS, NETWORK, índice de MEMORY
wiki-main	Corteza de conocimiento duradero. Wiki — comportamientos de agente (reglas entre agentes), proyectos, herramientas, conceptos, personas. Hogar principal de la memoria duradera a partir del 28 de mayo de 2026.
memory-main	Archivos de memoria diarios (YYYY-MM-DD.md) — capa de captura de 7 días que promueve contenido a wiki-main
workspace-docs-main	Markdown completo del espacio de trabajo (referencia, tareas, transferencias, aprendizajes)
skills-main	Definiciones de habilidades (archivos SKILL.md)
agents-*-identity	Documentos de identidad/configuración raíz de otros agentes (espacios de trabajo por agente)
agents-*-memory	Archivos de memoria diarios de otros agentes (espacios de trabajo por agente)
agents-*-wiki	Wikipedias duraderas de otros agentes (espacios de trabajo por agente) — el agente principal puede consultar directamente el conocimiento duradero especializado.
handoffs-*	Archivos de transferencia por agente (principal, desarrollo y cualquier otro agente)

Pistas de colecciones especializadas

Los nombres de colecciones a continuación provienen de la configuración QMD de cada agente especializado. Desde el agente principal, usa los equivalentes entre agentes (agents-<agent>-wiki, agents-<agent>-memory).

Lo que buscas	Agente	Colecciones clave (dentro de ese agente)	Desde el agente principal
Proyectos de código, configuraciones de compilación, decisiones de ingeniería	dev	projects-dev, identity-dev, wiki-dev	agents-dev-wiki, agents-dev-memory

Contexto y ámbito de colección

El metadato context: de QMD (establecido en index.yml o mediante qmd context add) mejora la relevancia de la búsqueda al describir lo que contiene cada colección. Se devuelve junto con los resultados.

Limita las búsquedas con -c cuando las consultas amplias se desvíen hacia el corpus incorrecto:

qmd search "notas de reunión esta semana" -c agents-dev-memory -n 10
qmd query "estado del proyecto GenAI" -c wiki-main -c projects-dev -n 10

Omite -c para buscar en todo.

Diagnósticos

qmd status     # conteos de colecciones y embeddings pendientes
qmd update     # reindexar (usar después de agregar/editar archivos en rutas indexadas)
qmd embed      # generar/reconstruir vectores después de la actualización

Si qmd query o qmd vsearch falla (modelo/GPU no disponible), recurre a qmd search con términos léxicos más fuertes.

Nota: documentos antiguos hacían referencia a qmd doctor — ese subcomando no está presente en la versión actual de la CLI. Usa qmd status para salud, y qmd update/qmd embed para reparación.

Herramientas MCP

Al usar MCP (el predeterminado para agentes OpenClaw), prefiere consultas estructuradas:

{
  "searches": [
    { "type": "lex", "query": "estado del proyecto challenger crew" },
    { "type": "vec", "query": "¿cuál es el estado actual del proyecto challenger crew?" }
  ],
  "intent": "Encontrar el estado del proyecto, no conceptos generales sobre el equipo.",
  "limit": 10
}

Errores comunes

• No te detengas en fragmentos. Recupera documentos antes de hacer afirmaciones.
• No abuses de la búsqueda semántica. Si conoces títulos o términos exactos, BM25 es más rápido y a menudo mejor.
• No mutaciones los índices a la ligera. qmd collection add, qmd update y qmd embed cambian el estado local y pueden ser costosos.
• Los comandos basados en modelos pueden ser sensibles al entorno. Si qmd query o el reranking fallan, recurre a qmd search con términos léxicos más fuertes.
• Las redacciones ambiguas del usuario necesitan intención. Añade intent: en lugar de esperar que la expansión de consultas adivine el dominio correcto.
• Los nombres de colecciones importan. Limita con -c cuando la consulta pueda coincidir con múltiples dominios.
• Actualidad: QMD no degrada resultados antiguos. Para memoria sensible al tiempo, verifica los nombres de archivo — YYYY-MM-DD más cercano a hoy es más actual.

Configuración y mantenimiento

Ejecuta solo estos comandos cuando se te pida. Buscar y recuperar es seguro; la mutación del índice no es casual.

qmd collection add ~/notas --name notas   # alternativa CLI a editar index.yml
qmd context add qmd://notas "Descripción"  # alternativa CLI a context: en index.yml
qmd update                                # reindexar colecciones
qmd embed                                 # generar/reconstruir vectores
qmd status                                # verificación de salud después de cambios