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

**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*](https://wiki.totto.org/blog/2026/07/17/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**

![](https://cdn.hashnode.com/uploads/covers/64a79aba336591d2a1481aae/0052e01d-d9a6-42f7-b115-2a5ba509f35f.png align="center")

`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](https://docs.anthropic.com/en/docs/claude-code/hooks) de Claude Code. Se dispara en **cada llamada Bash** del agente, en tres fases consecutivas.

![](https://cdn.hashnode.com/uploads/covers/64a79aba336591d2a1481aae/c3f0279f-e32a-432f-b4b9-e811d125e5a9.png align="center")

### **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:

![](https://cdn.hashnode.com/uploads/covers/64a79aba336591d2a1481aae/bf413ebc-338b-4dad-ac97-453ed4664b8c.png align="center")

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

```yaml
# ~/.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.

```jsonl
{"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**

```bash
# 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](https://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**

![](https://cdn.hashnode.com/uploads/covers/64a79aba336591d2a1481aae/28ef06d8-5f7b-44ba-a28f-aa2dd3509cf7.png align="center")

### **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](http://JwtTokenProvider.java) — refactor expiración tokens" |
| **Patrones extraídos como nuevas skills** | "[jakarta-migration.md](http://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:

```markdown
## 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](https://docs.anthropic.com/en/docs/claude-code/sub-agents) 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**

```bash
# 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:

![](https://cdn.hashnode.com/uploads/covers/64a79aba336591d2a1481aae/f71c8a46-e0da-4fac-9434-851a7984b820.png align="center")

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**

```bash
# 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**

```bash
# 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)**

```bash
# 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/`:

```yaml
# ~/.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](http://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**

*   [kcp-commands — GitHub](https://github.com/Cantara/kcp-commands)
    
*   [kcp-memory — GitHub](https://github.com/Cantara/kcp-memory)
    
*   [The KCP Ecosystem: A Tour for New Arrivals](https://wiki.totto.org/blog/2026/07/17/the-kcp-ecosystem-a-tour-for-new-arrivals/) — Thor Henning Hetland
    
*   [Knowledge Context Protocol spec](https://github.com/Cantara/knowledge-context-protocol)
    
*   [Artículo anterior: KCP — el protocolo de navegación](https://file+.vscode-resource.vscode-cdn.net/Users/josediaz/Projects/JoeDayz/articulos-joedayz/blog-kcp-knowledge-context-protocol-java.md)
    

* * *

*Enjoy!*

*Joe*