# AI Agent Memory Architecture

**Type:** Technical Framework
**Domain:** AI Systems / Engineering
**Source:** [[Raw/IB-BVH-Publications/MPB-BVH-MasterPlaybooks/PBO-BVH-AIAgentMemoryArchitecture-v01]]
**Last Updated:** 2026-04-11

## Summary
Framework para ingeniería de memoria en agentes de IA. Los LLMs son inherentemente sin estado — cada conversación empieza en blanco. La arquitectura correcta no requiere RAG ni bases de datos vectoriales: sistemas altamente efectivos se construyen con archivos Markdown simples + mecanismos de lectura/escritura precisos. Es la base técnica de [[BrainOS]] y del [[SherpaX]] como sistema persistente.

## Key Points
- **No se necesita RAG** para empezar — Claude Code y OpenClaw usan markdown files exitosamente
- 3 tipos de memoria de largo plazo (Google 2025 whitepaper): Episódica, Semántica, Procedimental
- La pregunta guía: *¿Qué vale la pena recordar, dónde va, y cuándo se escribe?*
- **Compaction** = el proceso de comprimir el historial de conversación antes de que se llene la ventana de contexto

## Arquitectura de 3 Capas de Memoria

| Tipo | Almacenamiento | Contenido |
|------|---------------|-----------|
| **Semántica** | `memory.md` (≤200 líneas) | Hechos estables, identidad, preferencias — inyectado en cada prompt |
| **Episódica** | Daily Logs + Session Snapshots | Contexto reciente — últimas 15 interacciones significativas |
| **Procedimental** | Workflows, Skills | Cómo hacer tareas específicas |

## Los 4 Mecanismos de Lectura/Escritura
1. **Bootstrap Loading** — Al inicio de sesión, inyectar Semantic Store + leer Daily Logs de hoy y ayer
2. **Pre-Compaction Flush** — Antes de llenar la ventana de contexto, guardar info vital al Daily Log
3. **Session Snapshot Hook** — Al resetear sesión, guardar snapshot de las últimas interacciones
4. **User-Directed Routing** — "Recuerda esto" → el agente escribe a Semantic Store o Daily Log

## Relationships
- Implements: [[BrainOS]] (arquitectura técnica de la memoria semántica del CEO)
- Enables: [[SherpaX]] (persistencia entre sesiones)
- Part of: [[FactoryOS]] (memoria persistente como componente)
- Owner: [[Victor-Heredia]]

## Open Questions / Gaps
- Estrategia de consolidación: cómo detectar y resolver memorias contradictorias
- Límite óptimo del Semantic Store (200 líneas es orientativo — depende del modelo)
- Event-based compaction (semántico) es lo más inteligente pero más difícil de implementar