knowledge-ops

Operaciones de Conocimiento

Gestiona un sistema de conocimiento multicapa para ingerir, organizar, sincronizar y recuperar conocimiento a través de múltiples almacenes.

Prefiere el modelo de espacio de trabajo activo:

• El trabajo con código vive en los repos clonados reales
• El contexto de ejecución activo vive en GitHub, Linear y archivos de contexto local del repositorio
• Las notas más amplias orientadas a humanos pueden vivir en una carpeta de contexto/archivo fuera del repositorio
• La memoria duradera entre máquinas pertenece a la base de conocimiento, no a un espacio de trabajo espejo

Cuándo activarlo

• El usuario quiere guardar información en su base de conocimiento
• Ingerir documentos, conversaciones o datos en almacenamiento estructurado
• Sincronizar conocimiento entre sistemas (archivos locales, memoria MCP, Supabase, repos Git)
• Deduplicar u organizar conocimiento existente
• El usuario dice "guarda esto en la KB", "sincroniza el conocimiento", "¿qué sé sobre X?", "ingiere esto", "actualiza la base de conocimiento"
• Cualquier tarea de gestión de conocimiento más allá de un simple recuerdo de memoria

Arquitectura del Conocimiento

Capa 1: Verdad de ejecución activa

• Fuentes: Incidencias de GitHub, PRs, discusiones, notas de versión, incidencias/proyectos/docs de Linear
• Uso: el estado operativo actual del trabajo
• Regla: si algo afecta a un plan de ingeniería activo, hoja de ruta, despliegue o versión, prefiere ponerlo aquí primero

Capa 2: Memoria de Claude Code (Acceso Rápido)

• Ruta: ~/.claude/projects/*/memory/
• Formato: Archivos Markdown con metadatos YAML
• Tipos: preferencias de usuario, comentarios, contexto del proyecto, referencia
• Uso: contexto de acceso rápido que persiste entre sesiones
• Se carga automáticamente al inicio de la sesión

Capa 3: Servidor de Memoria MCP (Grafo de Conocimiento Estructurado)

• Acceso: herramientas de memoria MCP (create_entities, create_relations, add_observations, search_nodes)
• Uso: búsqueda semántica en todas las memorias almacenadas, mapeo de relaciones
• Persistencia entre sesiones con estructura de grafo consultable

Capa 4: Repositorio de base de conocimiento / almacén de documentos duraderos

• Uso: notas duraderas seleccionadas, exportaciones de sesiones, investigación sintetizada, memoria del operador, documentos extensos
• Regla: este es el almacén duradero preferido para el contexto entre máquinas cuando el contenido no es código propiedad del repositorio

Capa 5: Almacén de datos externo (Supabase, PostgreSQL, etc.)

• Uso: datos estructurados, almacenamiento de documentos grandes, búsqueda de texto completo
• Ideal para: documentos demasiado grandes para archivos de memoria, datos que requieren consultas SQL

Capa 6: Carpeta de contexto/archivo local

• Uso: notas orientadas a humanos, planes de juego archivados, organización de medios locales, documentos temporales no relacionados con código
• Regla: escribible para almacenar información, pero no es un espacio de trabajo de código espejo
• No usar para: cambios de código activos o verdad del repositorio que debería vivir upstream

Flujo de Ingesta

Cuando sea necesario capturar nuevo conocimiento:

1. Clasificar

¿Qué tipo de conocimiento es?

• Decisión de negocio -> archivo de memoria (tipo proyecto) + memoria MCP
• Estado activo de hoja de ruta / versión / implementación -> GitHub + Linear primero
• Preferencia personal -> archivo de memoria (tipo usuario/comentarios)
• Información de referencia -> archivo de memoria (tipo referencia) + memoria MCP
• Documento grande -> almacén de datos externo + resumen en la memoria
• Conversación/sesión -> repositorio KB + resumen breve en la memoria

2. Deduplicar

Comprueba si este conocimiento ya existe:

• Busca en los archivos de memoria entradas existentes
• Consulta la memoria MCP con términos relevantes
• Verifica si la información ya existe en GitHub o Linear antes de crear otra nota local
• No crees duplicados. Actualiza las entradas existentes en su lugar.

3. Almacenar

Escribe en la(s) capa(s) adecuada(s):

• Siempre actualiza la memoria de Claude Code para acceso rápido
• Usa la memoria MCP para capacidad de búsqueda semántica y mapeo de relaciones
• Actualiza GitHub / Linear primero cuando la información cambia la verdad del proyecto activo
• Haz commit al repositorio KB para adiciones duraderas en formato extenso

4. Indexar

Actualiza cualquier índice o archivo de resumen relevante.

Operaciones de Sincronización

Sincronización de Conversaciones

Sincroniza periódicamente el historial de conversaciones en la base de conocimiento:

• Fuentes: archivos de sesión de Claude, sesiones de Codex, otras sesiones de agente
• Destino: repositorio de base de conocimiento
• Genera un índice de sesiones para navegación rápida
• Haz commit y push

Sincronización del Estado del Espacio de Trabajo

Refleja la configuración y scripts importantes del espacio de trabajo en la base de conocimiento:

• Genera mapas de directorios
• Oculta la configuración sensible antes de hacer commit
• Rastrea cambios a lo largo del tiempo
• No trates la base de conocimiento ni la carpeta de archivo como el espacio de trabajo de código activo

Sincronización de GitHub / Linear

Cuando la información afecta a la ejecución activa:

• actualiza la incidencia, PR, discusión, notas de versión o hilo de hoja de ruta correspondiente de GitHub
• adjunta documentos de soporte a Linear cuando el trabajo necesita contexto de planificación duradero
• solo refleja una nota local después si aún añade valor

Sincronización de Conocimiento entre Fuentes

Recoge conocimiento de múltiples fuentes en un solo lugar:

• Exportaciones de conversaciones de Claude/ChatGPT/Grok
• Marcadores del navegador
• Eventos de actividad de GitHub
• Escribe un resumen de estado, haz commit y push

Patrones de Memoria

# Corto plazo: contexto de la sesión actual
Usa TodoWrite para el seguimiento de tareas dentro de la sesión

# Medio plazo: archivos de memoria del proyecto
Escribe en ~/.claude/projects/*/memory/ para recuperación entre sesiones

# Largo plazo: GitHub / Linear / KB
Pon la verdad de ejecución activa en GitHub + Linear
Pon el contexto sintetizado duradero en el repositorio de base de conocimiento

# Capa semántica: grafo de conocimiento MCP
Usa mcp__memory__create_entities para datos estructurados permanentes
Usa mcp__memory__create_relations para mapeo de relaciones
Usa mcp__memory__add_observations para nuevos hechos sobre entidades conocidas
Usa mcp__memory__search_nodes para encontrar conocimiento existente

Buenas Prácticas

• Mantén los archivos de memoria concisos. Archiva datos antiguos en lugar de dejar que los archivos crezcan sin límite.
• Usa metadatos YAML para metadatos en todos los archivos de conocimiento.
• Deduplica antes de almacenar. Busca primero, luego crea o actualiza.
• Prefiere un único hogar canónico por conjunto de hechos. Evita copias paralelas del mismo plan entre notas locales, archivos del repositorio y documentos del rastreador de tareas.
• Oculta información sensible (claves API, contraseñas) antes de hacer commit a Git.
• Usa convenciones de nomenclatura consistentes para los archivos de conocimiento (minúsculas-con-guiones).
• Etiqueta las entradas con temas/categorías para una recuperación más fácil.

Puerta de Calidad

Antes de completar cualquier operación de conocimiento:

• no se crearon entradas duplicadas
• datos sensibles ocultados en cualquier archivo rastreado por Git
• índices y resúmenes actualizados
• capa de almacenamiento adecuada elegida para el tipo de datos
• referencias cruzadas añadidas donde sea relevante