Skip to main content
HashnodeJoeDayzJoeDayz

Command Palette

Search for a command to run...

kcp-commands & kcp-memory: las dos herramientas que le dan memoria a Claude Code en proyectos Java

Updated
•9 min read•View as Markdown
kcp-commands & kcp-memory: las dos herramientas que le dan memoria a Claude Code en proyectos Java
J
José Díaz

Línea de apertura (opcional, para el feed): Claude Code empieza cada sesión desde cero. No recuerda qué archivos modificaste ayer. No recuerda el bug que arreglaste la semana pasada. No recuerda que mvn clean install genera 800 líneas de las cuales solo 8 importan. Dos herramientas del ecosistema KCP resuelven exactamente eso.

Basado en la presentación "KCP-COMMANDS & KCP-MEMORY" (SDD Breakout — Herramientas ExoCortex) de Jose Diaz Diaz · Autor: Thor Henning Hetland (Totto) · Ægis, Santiago de los Caballeros 2026, y en The KCP Ecosystem: A Tour for New Arrivals (Thor Henning Hetland, julio 2026).

El artículo anterior de esta serie presentó el knowledge.yaml como el índice de navegación que le dice a la IA dónde está todo al inicio de sesión. Eso resuelve el problema del descubrimiento.

Pero hay dos problemas que el knowledge.yaml solo no resuelve:

  1. Context window burn: mvn test genera 500+ líneas. git log --oneline genera 200+ líneas. La IA consume tokens procesando ruido que nunca necesitó ver.

  2. Session amnesia: Cada sesión nueva es una pizarra en blanco. El agente no sabe que la semana pasada arreglaste el N+1 query en OrderRepository. No sabe que el refactor de autenticación dejó tres TODOs pendientes. No sabe que decidiste usar @Tag("integration") para separar tests que necesitan Docker.

kcp-commands resuelve el primero. kcp-memory resuelve el segundo. Están diseñados para usarse juntos.

El mapa del problema

kcp-commands y kcp-memory trabajan en cadena: el hook escribe el log de eventos, el daemon indexa ese log y lo convierte en memoria recuperable.

kcp-commands es un PreToolUse + PostToolUse hook de Claude Code. Se dispara en cada llamada Bash del agente, en tres fases consecutivas.

Fase A: antes de ejecutar — inyección de guía

Para comandos reconocidos, el hook inyecta un hint compacto con los flags que el agente probablemente necesita. En lugar de que Claude Code adivine los parámetros de mvn o kubectl, recibe una guía concisa antes de ejecutar.

Para Java developers, esto cubre:

  • mvn / ./mvnw — surefire flags, perfiles, skip tests

  • git — status, diff, log, branch, cherry-pick

  • docker / docker-compose — ps, logs, build, push

  • kubectl — get pods, describe, logs, apply

Fase B: después de ejecutar — filtrado de output

Esta es la fase de mayor impacto en context window. El manifiesto de cada comando define qué líneas conservar y qué desechar:

El manifest para mvn test se ve así (formato interno del hook):

# ~/.kcp/manifests/mvn-test.yaml
command: "mvn.*test|./mvnw.*test"
phase_a:
  inject: |
    Flags útiles: -pl <módulo> para módulo específico,
    -Dtest=NombreTest para test único,
    -DskipTests para compilar sin ejecutar.
phase_b:
  filter: keep_matching
  patterns:
    - "BUILD (SUCCESS|FAILURE)"
    - "Tests run:"
    - "FAILED:"
    - "ERROR:"
    - "\\[ERROR\\]"
  inject_on_failure: |
    Si hay fallos con @Tag("integration"), pueden necesitar
    la infraestructura de Docker levantada con docker-compose.
phase_c:
  log: true

Fase C: event logging

Cada llamada Bash queda registrada en ~/.kcp/events.jsonl. Este log es el insumo que consume kcp-memory. Sin kcp-commands, kcp-memory no tiene datos que indexar.

{"ts":"2026-07-31T09:14:22Z","cmd":"mvn test","project":"pedidos-api","exit":1,"summary":"FAILED: OrderServiceTest (1 failure)","filtered_lines":8,"original_lines":847}
{"ts":"2026-07-31T09:18:44Z","cmd":"git diff HEAD~1","project":"pedidos-api","exit":0,"summary":"Modified: OrderService.java, OrderRepository.java","filtered_lines":12,"original_lines":234}
{"ts":"2026-07-31T09:25:01Z","cmd":"mvn test","project":"pedidos-api","exit":0,"summary":"Tests run: 47, Failures: 0","filtered_lines":3,"original_lines":812}

Impacto medido

Métrica Valor
Ahorro de context window por sesión 33% promedio
Comandos cubiertos por manifests 84% de las llamadas Bash típicas
Latencia del hook (JVM) 12 ms por llamada
Manifests incluidos 292
Configuración requerida 0

El hook funciona out of the box. No requiere ningún knowledge.yaml. No requiere configurar manifests. Instálalo y empieza a ahorrar tokens en la próxima sesión.

Instalación

# Opción recomendada — daemon Java (12 ms/call):
curl -fsSL https://raw.githubusercontent.com/Cantara/kcp-commands/main/bin/install.sh | bash -s -- --java

# Alternativa — solo Node.js (no requiere JVM):
curl -fsSL https://raw.githubusercontent.com/Cantara/kcp-commands/main/bin/install.sh | bash -s -- --node

El installer registra el hook en el settings.json global de Claude Code. Después del primer claude que ejecutes, el hook está activo.

kcp-memory: memoria episódica cross-session

Repo: github.com/Cantara/kcp-memory · Versión: 0.32.0

Los agentes son amnésicos por diseño. Cada sesión nueva empieza desde cero. kcp-memory cierra ese hueco.

El problema concreto en un proyecto Java

Imagina este escenario real en un proyecto Spring Boot:

  • Lunes: Debuggeas un N+1 query. Encuentras que OrderRepository.findByCustomer() hace lazy loading mal configurado. Arreglas con @EntityGraph. 45 minutos de investigación.

  • Martes: Nueva sesión. Pides a Claude que optimice queries en el módulo de clientes. El agente vuelve a investigar el mismo patrón de lazy loading. 30 minutos para redescubrir lo que ya sabes.

  • Miércoles: Refactorizas autenticación. Dejas 3 TODOs marcados en JWT config. Sesión termina antes de completarlos.

  • Jueves: Nueva sesión. No hay contexto de los TODOs. El agente no sabe qué estaba en progreso.

kcp-memory convierte el martes, miércoles y jueves en sesiones que arrancan informadas.

Cómo funciona el daemon

Qué captura kcp-memory

El daemon indexa y prioriza cuatro categorías de información:

Categoría Ejemplo Java
Bugs descubiertos y cómo se arreglaron "N+1 en OrderRepository — @EntityGraph"
Decisiones de arquitectura de la sesión "Usamos MapStruct en vez de ModelMapper — ADR-012"
Archivos tocados y por qué "JwtTokenProvider.java — refactor expiración tokens"
Patrones extraídos como nuevas skills "jakarta-migration.md — javax→jakarta en imports"
Issues recurrentes entre sesiones "Port 5432 conflicto — usar POSTGRES_PORT=5433"

La diferencia práctica

Lo que Claude ve al abrir una sesión nueva en tu proyecto Spring Boot:

## Relevant session history — pedidos-api

2026-07-28: Fixed N+1 query in OrderRepository.findByCustomer().
Cause: default lazy loading on @OneToMany. Fix: @EntityGraph annotation.
Added pattern to performance-patterns.md skill.

2026-07-29: JWT refactor session ended mid-task.
3 TODOs pending in src/main/java/.../security/JwtTokenProvider.java (lines 87, 134, 201).
Context: expiry was calculated in seconds not ms — see PR #1847.

2026-07-30: Integration test failures.
Cause: docker-compose postgres port 5432 conflicts with local instance.
Fix: POSTGRES_PORT=5433 in .env.test

En lugar de empezar a explorar desde cero, el agente arranca con el contexto de lo que pasó — los problemas activos, las decisiones tomadas, los archivos en progreso.

Memoria compartida entre sub-agentes

kcp-memory indexa también los transcripts de sub-agentes. Esto significa que si usas Task tool o sub-agentes paralelos en Claude Code, la memoria es compartida entre todos ellos dentro del mismo proyecto. Un sub-agente que arregla tests y otro que refactoriza servicios ven el mismo contexto histórico.

Almacenamiento

SQLite local en ~/.kcp/memory.db. Sin cloud. Sin envío de datos. El contexto inyectado al inicio de sesión es generado localmente por el daemon.

Instalación

# Instalar kcp-memory (requiere kcp-commands instalado primero):
# Ver instrucciones actualizadas en:
# https://github.com/Cantara/kcp-memory#install

Cómo funcionan juntos: la cadena completa

kcp-commands + kcp-memory forman un sistema de dos capas:

La clave es que son independientes pero complementarios:

  • kcp-commands solo: ahorra context window en la sesión actual. Sin memoria cross-session.

  • kcp-memory solo: sin eventos que indexar (no hay events.jsonl), opera solo con transcripts de sesión — útil pero limitado.

  • Ambos juntos: ahorro de tokens + contexto histórico enriquecido = el loop completo.

Plan de adopción para un proyecto Java existente

No es necesario instalar todo a la vez. El ecosistema está diseñado para adopción incremental:

Día 1 — Ahorro de context window inmediato

# Instalar kcp-commands (Java daemon):
curl -fsSL https://raw.githubusercontent.com/Cantara/kcp-commands/main/bin/install.sh | bash -s -- --java

# Abrir Claude Code. Ejecutar cualquier comando Maven o Git.
# Observar: la Fase A inyecta hints antes del comando.
# Observar: la Fase B devuelve output filtrado.
# El ahorro empieza desde la primera sesión.

Día 2 — Agregar memoria episódica

# Instalar kcp-memory:
# https://github.com/Cantara/kcp-memory#install

# El daemon empieza a indexar events.jsonl y transcripts.
# La próxima sesión recibirá contexto de la sesión de hoy.

Día 3 — Agregar inteligencia de workspace (opcional)

# Configurar Synthesis MCP en .claude/mcp.json
# Luego: synthesis scan . (desde la raíz del proyecto)
# Claude Code puede buscar, relacionar y preguntar sobre todo el codebase.

Cuando necesites governance:

Agrega kcp-agent para load planning inspeccionable, y kcp-harness para enforcement. Estos son para cuando los agentes corren en producción o en entornos donde "el agente leyó el archivo X porque..." necesita ser auditable.

Manifest personalizado para tu proyecto Java

Si tu proyecto tiene patrones específicos — un wrapper de Maven, un runner de tests con flags especiales, un CLI interno — puedes agregar manifests propios en ~/.kcp/manifests/:

# ~/.kcp/manifests/my-project-test.yaml
command: "./scripts/run-tests.sh"
phase_a:
  inject: |
    Flags disponibles: --module <nombre>, --tag integration, --tag unit.
    Los tests de integración requieren: docker-compose up -d postgres redis
phase_b:
  filter: keep_matching
  patterns:
    - "PASSED|FAILED|ERROR"
    - "Tests run:"
    - "\\[WARN\\].*important"
  inject_on_failure: |
    Revisar logs en target/surefire-reports/ para stack traces completos.
phase_c:
  log: true

Los 292 manifests incluidos cubren las herramientas más comunes. Los manifests propios se fusionan sin sobreescribir los del sistema.

Qué resuelven estas herramientas y qué no

Problema Herramienta
"mvn test genera 800 líneas de ruido" ✅ kcp-commands Fase B
"La IA no sabe los flags correctos de kubectl" ✅ kcp-commands Fase A
"Mañana la IA no recuerda el bug que arreglé hoy" ✅ kcp-memory
"La IA no sabe la arquitectura del proyecto" CLAUDE.md + knowledge.yaml
"La IA no puede buscar en el codebase" Synthesis
"Necesito auditar qué cargó el agente" kcp-agent + kcp-harness

kcp-commands y kcp-memory son la entrada más directa al ecosistema KCP: impacto inmediato, configuración cero, instalación en dos comandos.

Recursos

Enjoy!

Joe

17 views

Comments

Join the discussion

No comments yet. Be the first to comment.

More from this blog

JoeDayz

79 posts

Community Guy | Java Champion | AWS Architect | Software Architect