Gestión de contexto de Pi Agent

La gestión de contexto es una habilidad central para usar Pi Agent de manera eficiente.

Este capítulo explica cómo controlar el comportamiento de la IA mediante archivos de entorno y cómo gestionar el contexto de la conversación.


Descripción general de los archivos de contexto

Al iniciarse, Pi Agent carga automáticamente el archivo de instrucciones del proyecto, para que la IA conozca las normas, comandos y preferencias de tu proyecto.

Estos archivos le dicen a la IA «cómo trabajar en este proyecto».


AGENTS.md / CLAUDE.md

Estos son los archivos de contexto más importantes de Pi Agent; el orden de carga es:

  1. ~/.pi/agent/AGENTS.md- Instrucciones globales, aplicables a todos los proyectos
  2. AGENTS.md o CLAUDE.md en los directorios padre, recorriéndolos hacia arriba desde el directorio actual
  3. AGENTS.md o CLAUDE.md en el directorio actual

A continuación se muestra un ejemploAGENTS.mdcompleto ubicado en el directorio raíz del proyecto:

Ejemplo

# Instrucciones del proyecto

## Estándares de código
- Todo el código usa el modo estricto de TypeScript
- Las funciones deben tener anotaciones de tipo de valor de retorno
- Usa ESLint y Prettier para mantener un estilo de código consistente

## Flujo de trabajo
- Después de modificar el código, ejecuta `npm run check` para validar
- Antes de confirmar, ejecuta `npm test` para asegurar que las pruebas pasen
- No ejecutes migraciones de base de datos de producción directamente en local

## Consejos de seguridad
- No escribas claves de API o contraseñas en el código
- Usa variables de entorno para configuraciones sensibles

## Estilo de respuesta
- Mantén las respuestas concisas, no expliques en exceso el código obvio
- Cuando surja un problema, primero da una solución y luego explica la causa

Después de actualizar AGENTS.md, usa/reloadel comando para recargar en caliente sin necesidad de reiniciar Pi Agent.

Si tienes tanto AGENTS.md como CLAUDE.md, Pi Agent carga AGENTS.md con prioridad.

Si usabas Claude Code anteriormente, puedes reutilizar directamente tu CLAUDE.md existente.

Si existe AGENTS.override.md en el directorio, este reemplaza a AGENTS.md y CLAUDE.md de ese directorio al cargarse.

Si deseas deshabilitar la carga de archivos de contexto, usa el parámetro de línea de comandos:

$ pi --no-context-files
$ pi -nc   # 短形式

SYSTEM.md

SYSTEM.md se usa para reemplazar por completo el prompt del sistema predeterminado de Pi Agent; si solo deseas añadir contenido, usa APPEND_SYSTEM.md.

Ambos se dividen en dos niveles: global y de proyecto. Las rutas y funciones son las siguientes:

ArchivoNivelFunción
~/.pi/agent/SYSTEM.mdGlobalReemplaza el prompt del sistema predeterminado
Directorio raíz del proyecto/.pi/SYSTEM.mdProyectoReemplaza el prompt del sistema predeterminado
~/.pi/agent/APPEND_SYSTEM.mdGlobalAñade después del prompt del sistema predeterminado
Directorio raíz del proyecto/.pi/APPEND_SYSTEM.mdProyectoAñade después del prompt del sistema predeterminado

En la mayoría de los casos no necesitas modificar el prompt del sistema.

AGENTS.md ya cubre la gran mayoría de las necesidades de personalización.

SYSTEM.md es adecuado para escenarios que requieren una personalización profunda del comportamiento de la IA; una modificación inadecuada puede afectar el rendimiento de la IA.


Compacción de contexto (Compaction)

Cuando la conversación se vuelve muy larga, la ventana de contexto (context window) de la IA se va llenando gradualmente.

Pi Agent resuelve este problema mediante la compacción de contexto (Compaction): resume automáticamente las partes más antiguas de la conversación en un breve resumen, liberando espacio en el contexto.

上下文压缩循环:消息追加、接近阈值、自动摘要、折叠早期消息

Compacción automática

De forma predeterminada, Pi Agent activa automáticamente la compacción cuando el contexto se acerca al límite del modelo.

El comportamiento de compacción está controlado por~/.pi/agent/settings.jsonla configuración `compaction` en:

Ejemplo

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}
Elemento de configuraciónTipoValor predeterminadoDescripción
compaction.enabledbooleantrueSi se habilita la compacción automática
compaction.reserveTokensnumber16384Número de tokens reservados para la respuesta del LLM
compaction.keepRecentTokensnumber20000Número de tokens recientes que se conservan sin comprimir

La condición de activación es que los tokens de contexto superen el espacio disponible después de restar reserveTokens de contextWindow.

El momento de verificación es después de cada ejecución de herramienta y antes de que se envíe el siguiente mensaje del usuario.

Compacción manual

También puedes activar la compacción manualmente en cualquier momento:

/compact

Al comprimir, puedes agregar instrucciones personalizadas para indicar a la IA en qué debe centrarse al resumir:

/compact 重点关注错误修复和 API 变更

La compacción es irreversible solo para el contexto de la conversación actual.

Los mensajes originales comprimidos se conservan íntegros en el archivo de sesión; usa /tree para volver al nodo anterior a la compacción y recuperar los detalles.

Si deseas hacer una copia de seguridad completa antes de comprimir, se recomienda usar /clone.

/clone copia por completo la rama activa actual a un nuevo archivo de sesión, adecuado para respaldar antes de comprimir.

/fork solo parte de un mensaje histórico del usuario; el contenido posterior no se incluye en la nueva sesión.


Visualización del proceso de razonamiento

Los modelos que admiten salida de razonamiento piensan antes de responder.

Puedes controlar la visualización del proceso de razonamiento con los siguientes ajustes:

AjusteTipoValor predeterminadoDescripción
hideThinkingBlockbooleanfalseOculta el proceso de razonamiento y solo muestra la respuesta final
showCacheMissNoticesbooleanfalseMuestra avisos de fallo de caché y también los avisos de uso de tokens generados por la compacción y el resumen de ramas

UsaCtrl+Tpara alternar la visualización del proceso de razonamiento en cualquier momento durante la conversación.


Recarga en caliente (/reload)

Si necesitas reiniciar después de modificar la configuración depende de qué hayas cambiado.

La siguiente tabla resume cómo se aplican los cambios comunes; para los elementos marcados como «No», basta con ejecutar /reload:

CambioRequiere reinicioDescripción
AGENTS.md o CLAUDE.md (archivos de contexto)noSe recargan inmediatamente después de ejecutar /reload
Extensions (extensiones)noSe recargan inmediatamente después de ejecutar /reload
Skills (habilidades)noSe recargan inmediatamente después de ejecutar /reload
Plantillas de promptnoSe recargan inmediatamente después de ejecutar /reload
Archivos de temanoSe recargan inmediatamente después de ejecutar /reload
Configuración de atajos de tecladonoSe recarga inmediatamente después de ejecutar /reload
Ciertos ajustes en ~/.pi/agent/settings.jsonSíAlgunas configuraciones se leen una vez al inicio
Paquetes de extensiones recién instaladosSíLas dependencias de paquetes se resuelven en la fase de inicio
Credenciales de auth.jsonSíLas credenciales se cargan en la fase de inicio

Ver el uso de contexto

La barra de estado inferior muestra en tiempo real el uso de tokens y el costo del contexto actual.

Usa/sessionel comando para ver información más detallada:

/session

Ejemplo de salida:

Session file: ~/.pi/agent/sessions/--Users-ejemplo-projects-ejemplo-demo--/2026-08-30T09-15-04-000Z_019fbb5d-7a2e-7f31-b5c4-1a2b3c4d5e6f.jsonl
Session ID:   abc123-def456
Messages:     42
Tokens:       85,432
Cost:         $0.52
Current model: claude-sonnet-4-20250514
Otras extensiones