Guía para agentes IA
Instrucciones para que Claude Code, Codex, Cursor o cualquier agente use SoluCortex de forma autónoma.
Configuración inicial
El agente lee las credenciales desde ai/.env.ai (nunca hardcodeadas):
bash
SOLUCORTEX_URL=https://solucortex.soluai.cl
SOLUCORTEX_PROJECT_ID=<uuid-del-proyecto>
SOLUCORTEX_API_KEY=scx_<api-key>ai/.env.ai debe estar en .gitignore. El agente nunca debe hardcodear ni commitear estas variables.
Flujo de inicio de sesión
Al comenzar cada sesión de trabajo, el agente siempre carga el contexto relevante para la tarea:
bash
source ai/.env.ai
CONTEXT=$(curl -s -X POST "$SOLUCORTEX_URL/api/v1/context/build" \
-H "Authorization: Bearer $SOLUCORTEX_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"project_id\": \"$SOLUCORTEX_PROJECT_ID\",
\"query\": \"$DESCRIPCION_DE_LA_TAREA\"
}" | python3 -c "import sys,json; print(json.load(sys.stdin).get('context_text',''))")
echo "$CONTEXT"Cuándo registrar memorias
El agente registra memorias de forma autónoma — sin esperar instrucción del usuario — cuando:
- Toma una decisión técnica que no estaba documentada.
- Detecta un riesgo o deuda técnica nueva.
- Cierra una tarea importante.
- Descubre un comportamiento no obvio del sistema (bug, workaround, restricción).
bash
source ai/.env.ai
curl -s -X POST "$SOLUCORTEX_URL/api/v1/memories" \
-H "Authorization: Bearer $SOLUCORTEX_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"project_id\": \"$SOLUCORTEX_PROJECT_ID\",
\"type\": \"decision\",
\"title\": \"Título corto de la decisión\",
\"content\": \"Descripción completa del porqué de esta decisión, alternativas descartadas y contexto.\",
\"importance\": 8
}"Tipos de memoria
Valores válidos para el campo type:
| Valor | Descripción |
|---|---|
architecture | Stack tecnológico, estructura del proyecto |
decision | Decisiones técnicas importantes ya tomadas |
risk | Riesgo identificado, resuelto o pendiente |
convention | Regla, estándar o convención del equipo |
bug_history | Bug resuelto con aprendizaje para el futuro |
tech_debt | Deuda técnica, código legacy o mejora pendiente |
sensitive_module | Módulo delicado que no debe modificarse a la ligera |
learning | Aprendizaje general del proyecto |
external_integration | Integración con servicio externo, API o dependencia |
Campo importance
Entero entre 1 y 10. Controla la prioridad en los resultados de context/build.
| Rango | Uso recomendado |
|---|---|
| 9–10 | Crítico — constraints del sistema, decisiones inamovibles |
| 7–8 | Importante — decisiones técnicas relevantes, estado de componentes clave |
| 5–6 | Normal — convenciones, estado general |
| 1–4 | Bajo — contexto de fondo, notas históricas |
Reglas críticas
Nunca ejecutar sin confirmación explícita del usuario:
Comandos destructivos sobre la base de datos: reseteos, drops, truncates o deletes sin condición.
Comandos destructivos sobre la base de datos: reseteos, drops, truncates o deletes sin condición.
Nunca:
• Hardcodear API keys, tokens o URLs en código o archivos de configuración.
• Commitear archivos con secretos o credenciales.
• Hardcodear API keys, tokens o URLs en código o archivos de configuración.
• Commitear archivos con secretos o credenciales.
Límites de frecuencia
Los límites se aplican por API key. Si el agente recibe un 429, debe esperar y reintentar con backoff exponencial.
| Endpoints | Límite |
|---|---|
| Memorias, snapshots, búsqueda, contexto | 120 req/min |
context/build y search/semantic | 20 req/min |
Referencia rápida de endpoints
| Acción | Endpoint |
|---|---|
| Cargar contexto | POST /api/v1/context/build |
| Registrar memoria | POST /api/v1/memories |
| Buscar memorias | POST /api/v1/search/semantic |
| Listar memorias | GET /api/v1/memories?project_id=...&per_page=50&page=1 |
| Actualizar memoria | PATCH /api/v1/memories/{id} |
| Crear snapshot | POST /api/v1/snapshots |