aarcilam/cortexfs

CortexFS Memory Skill

Version: 0.6.0
Execution: Shell/Bash
Auth: None

🚀 AUTO-INSTALACIÓN (Ejecutar al inicio)

Cuando el skill se carga por primera vez, EL AGENTE DEBE ejecutar automáticamente estos comandos:

1. Instalar CortexFS CLI (si no existe)

if ! command -v cortex &> /dev/null; then
    npm install -g cortexfs-cli
    cortex config "$HOME/.cortexfs/brain"
fi

2. Copiar comandos a los agentes instalados

Para OpenCode:

mkdir -p ~/.config/opencode/commands
cp -r ~/.agents/skills/cortexfs/opencode-commands/* ~/.config/opencode/commands/

Para Cursor:

mkdir -p ~/.cursor/commands
cp -r ~/.agents/skills/cortexfs/opencode-commands/* ~/.cursor/commands/

Verificación:

which cortex || echo "NO_INSTALLED"

Si no está instalado, ejecutar:

npm install -g cortexfs-cli

---

Prerequisitos

• CortexFS CLI instalado
  • Check: which cortex || cortex --version
  • Install: npm install -g cortexfs-cli

---

🧠 COMPORTAMIENTO AUTOMÁTICO DEL AGENTE

Este skill actúa como la MEMORIA PERSISTENTE del proyecto. El agente DEBE seguir estas reglas de comportamiento:

🔍 REGLA 1: BUSCAR PRIMERO (Search-First)

Cuándo: SIEMPRE que el usuario pregunte algo sobre el proyecto, ANTES de responder o buscar en el código.

Acción:

1. Ejecutar: cortex search "<términos relevantes de la pregunta>"
2. Si hay resultados, usar cortex read para obtener el contenido completo
3. Usar ese conocimiento para responder o complementar la respuesta

Ejemplos:

| Pregunta del usuario | Ejecutar primero | |---------------------|------------------| | "¿Cómo funciona la autenticación?" | cortex search 'autenticación auth login' | | "¿Cuáles son las convenciones de código?" | cortex search 'convenciones código estilo' | | "¿Qué decisiones de arquitectura tomamos?" | cortex search 'arquitectura decisiones' |

Por qué: CortexFS contiene conocimiento curado y decisiones previas. Buscar aquí PRIMERO evita repetir trabajo o contradecir decisiones.

---

💾 REGLA 2: GUARDAR CONOCIMIENTO IMPORTANTE (Auto-Save)

Cuándo: Guardar AUTOMÁTICAMENTE cuando se descubra o defina:

• Decisiones de arquitectura o diseño
• Convenciones de código acordadas
• Patrones o soluciones reutilizables
• Configuraciones importantes del proyecto
• APIs o endpoints documentados
• Bugs importantes y sus soluciones
• Dependencias clave y su propósito
• Flujos de negocio o lógica compleja
• Información que el usuario pide recordar
• Contexto importante que se perdería entre sesiones

Acción:

1. Identificar la categoría apropiada
2. Crear un ID semántico descriptivo
3. Estructurar el contenido en JSON
4. Ejecutar: cortex save "<category>" "<id>" "<contenido JSON>"

📂 Categorías Recomendadas

| Categoría | Usar para | |-----------|-----------| | arquitectura | Decisiones de diseño, patrones, estructura | | convenciones | Reglas de código, estilo, naming | | config | Configuraciones, variables de entorno, settings | | api | Endpoints, contratos, schemas | | bugs | Problemas encontrados y soluciones | | flujos | Lógica de negocio, workflows, procesos | | dependencias | Librerías importantes y su uso | | memoria | Información general que recordar |

---

🔄 REGLA 3: INICIO DE SESIÓN (Session Start)

Cuándo: Al inicio de una nueva conversación o sesión.

Acción:

1. Ejecutar: cortex load-state
2. Revisar el estado anterior para contexto
3. Ejecutar: cortex list
4. Conocer qué conocimiento está disponible

Por qué: Retomar contexto sin que el usuario tenga que repetir información.

---

🏁 REGLA 4: FIN DE SESIÓN (Session End)

Cuándo:

• El usuario indica que termina la sesión
• Se completó una tarea importante
• Hubo cambios significativos en el proyecto

Acción: Ejecutar cortex save-state con JSON estructurado:

{
  "task": "qué se estaba haciendo",
  "status": "in_progress|blocked|review",
  "progress": {
    "completed": [],
    "pending": [],
    "blocked": []
  },
  "context": {
    "files_modified": [],
    "branch": ""
  },
  "next_steps": []
}

---

📋 COMANDOS DISPONIBLES

cortex config

Configura el directorio raíz del brain.

cortex config "<path>"

Ejemplo:

cortex config '/ruta/al/brain'

---

cortex save

Guarda conocimiento estructurado. SIEMPRE estructurar el contenido en JSON o Markdown.

cortex save "<category>" "<id>" "<content>"

Parámetros:

• category: Categoría del conocimiento (ej: arquitectura, convenciones)
• id: Identificador semántico
• content: Contenido - DEBE ser JSON estructurado o Markdown organizado

Ejemplo JSON:

cortex save 'agent' 'mi-agente' '{"name":"mi-agente","role":"asistente","capabilities":["buscar","analizar"]}'

Ejemplo Markdown:

cortex save 'project' 'readme' '# Proyecto\n\n## Descripción\nTexto aquí...'

---

cortex read

Lee conocimiento persistido.

cortex read "<category>" "<id>"

Ejemplo:

cortex read 'agent' 'mi-agente'

---

cortex update

Actualiza conocimiento existente.

cortex update "<category>" "<id>" "<content>"

Ejemplo:

cortex update 'agent' 'mi-agente' 'nuevo contenido'

---

cortex delete

Elimina conocimiento.

cortex delete "<category>" "<id>"

Ejemplo:

cortex delete 'agent' 'mi-agente'

---

cortex list

Lista conocimiento, opcionalmente filtrado por categoría.

cortex list [category]

Ejemplos:

cortex list              # Lista todas las categorías
cortex list 'agent'      # Lista entradas en categoría 'agent'

---

cortex search

Busca conocimiento por query.

cortex search "<query>"

Ejemplo:

cortex search 'mi búsqueda'

---

cortex save-state

Guarda el estado de la sesión. SIEMPRE usar formato estructurado para facilitar handoff.

cortex save-state "<summary>"

Formato recomendado JSON:

cortex save-state '{"task":"Implementar auth","status":"in_progress","progress":{"completed":["login"],"pending":["logout"]},"next_steps":["agregar tests"]}'

Alternativa compacta:

cortex save-state 'TASK: Auth OAuth2 | STATUS: in_progress | DONE: login | PENDING: logout | NEXT: tests'

---

cortex load-state

Carga el estado más reciente de la sesión.

cortex load-state

---

⚡ FLUJO DE TRABAJO OBLIGATORIO

┌─────────────────────────────────────────────────────────┐
│  INICIO DE SESIÓN                                       │
│  1. cortex load-state    → Recuperar contexto anterior  │
│  2. cortex list          → Ver conocimiento disponible  │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  CUANDO EL USUARIO PREGUNTE ALGO                        │
│  1. cortex search "..."  → BUSCAR PRIMERO en memoria    │
│  2. cortex read "..." "..."  → Leer detalles si existe  │
│  3. Luego buscar en código si es necesario              │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  CUANDO DESCUBRAS/DEFINAS ALGO IMPORTANTE               │
│  → cortex save "categoria" "id" "{...JSON...}"          │
│                                                         │
│  Guardar: decisiones, convenciones, configs, APIs,      │
│           bugs+soluciones, patrones, flujos de negocio  │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  FIN DE SESIÓN / TAREA COMPLETADA                       │
│  → cortex save-state "{...estado estructurado...}"      │
└─────────────────────────────────────────────────────────┘

---

🔍 Ejemplo Completo: Usuario pregunta algo

Usuario: "¿Cómo manejamos los errores en la API?"

# PASO 1: Buscar primero en CortexFS
cortex search "errores API manejo error handling"

# PASO 2: Si encuentra resultados, leer el contenido
cortex read "convenciones" "error-handling"

# PASO 3: Responder usando ese conocimiento + código si necesario

---

💾 Ejemplo Completo: Guardar conocimiento importante

Después de definir cómo manejar errores:

cortex save "convenciones" "error-handling" '{
  "topic": "Manejo de errores en API",
  "rules": [
    "Usar AppError para errores controlados",
    "Logging con nivel según severidad",
    "Respuestas estandarizadas con code y message"
  ],
  "example": "throw new AppError(400, \"VALIDATION_ERROR\", \"Campo requerido\")",
  "decided_on": "2024-01-15",
  "reason": "Consistencia en respuestas de error"
}'

---

⚠️ Recordatorios Críticos

• BUSCAR ANTES DE RESPONDER - CortexFS tiene conocimiento curado
• GUARDAR PROACTIVAMENTE - Si es importante, persistirlo
• ESTRUCTURAR EN JSON - Facilita búsqueda y lectura futura
• Los comandos cortex son ejecutables BASH del sistema
• Requieren permisos de escritura fuera del workspace (usar "all")