TRUCHA ▸ TABLERO

project-trucha · memoria persistente para agentes de código

DECISIÓN TÉCNICA 01 / 5
QUÉ VAMOS A CONSTRUIR

Memoria persistente para agentes de código

Un índice local del codebase —léxico y semántico— que el agente consulta en milisegundos, sin levantar servicios externos. Local-first, portable y de baja fricción: pip install y listo.

  • Indexado incremental · búsqueda híbrida · memoria de decisiones
  • Capa store desacoplada: interfaz estable, backend intercambiable
  • CLI + API + (futuro) servidor MCP para el agente

01
Indexado
Recorre, trocea (archivo/símbolo/bloque) y persiste el repo
02
Léxica
Full-text BM25: match exacto por identificador
03
Semántica
Embeddings + similitud: recupera por significado
04
Híbrida
RRF: fusiona léxico + vectorial en una respuesta
05
Memoria
Guarda notas/ADRs y las recupera por contexto
06
Incremental
Reindexa por hash/mtime sólo lo que cambió
PIPELINE

Del repo al agente, con la memoria en el centro

Dos flujos convergen en store: la ingesta indexa el contenido y la recuperación lo consulta. El store es el único punto que la decisión técnica deja abierto — todo lo demás depende de su interfaz, no de su implementación.

  • ingesta → embeddings → store ← retrieve ← interfaz ← agente
  • El agente pregunta por la interfaz; nunca toca el backend directo
DECISIÓN #1 · ABIERTA

¿Qué backend de memoria?

Necesitamos léxica + vectorial + metadata con la menor fricción operativa, porque el consumidor es un agente local, no un servicio multi-tenant. Hipótesis actual a validar: SQLite + FTS5 (+ sqlite-vec).

  • menor fricción, latencia y consumo para el caso local
  • Vector DB dedicada se justifica a escala / millones de docs
  • Se cierra en ADR-0001 cuando el equipo converja

SQLite+vec
FTS5 + sqlite-vec: 1 archivo, sin servidor, híbrida. Hipótesis actual
SQLite FTS5
Base léxica BM25, muy baja fricción. Sin vectorial nativa
LanceDB
Vector store embebido y veloz; léxico menos maduro
ChromaDB
Vectorial dedicada; suma deps y estado propio
pgvector
SQL + vector potente, pero exige servidor Postgres
Qdrant
Features avanzadas; overkill para local individual
DECISIÓN REVERSIBLE

Una interfaz estable, backends intercambiables

Mientras la decisión siga abierta, el resto del toolkit habla con una interfaz de store, no con un motor concreto. Así podemos comparar —y hasta cambiar— el backend sin reescribir ingest, retrieve ni la interfaz del agente.

  • Hoy: SQLite + FTS5 + sqlite-vec (embebido, 1 archivo)
  • Alternativa embebida: LanceDB
  • A escala: ChromaDB / pgvector con servidor
ROADMAP

De la decisión al toolkit

Fase 0 en curso: cerrar el backend y congelar la interfaz. El resto se construye encima, de a fases y en comunidad. El aporte más valioso hoy es participar en la decisión de arquitectura.

  • Cada decisión cerrada → un ADR en docs/adr/
  • 🐟 Maximiliano Soria · Gerardo Lopez · Yoel Enriquez

0
Decisión
Cerrar backend (ADR-0001) + congelar interfaz store · ACTUAL
1
Núcleo
Indexado + búsqueda léxica + reindex incremental
2
Semántica
Embeddings + vectorial + fusión híbrida
3
MCP
CLI estable + servidor MCP para el agente
← → · F focus