Ebb — unfo de conocimiento orientado a agentes

Memoria a largo plazo para agentes de IA, construida como un grafo. La relevancia es fuerza de conexión ponderada por recencia: reutilizar el conocimiento lo mantiene vivo, el conocimiento no utilizado decae y archiva, nada se elimina hasta que un humano lo aprueba. Se ejecuta integrado (cero infraestructura) o en Neo4j (producción).

Los dos mecanismos en torno a los que se construye — relevancia ponderada por conexión y decaimiento temporal — son operaciones nativas de grafos, y ambos tienen antecedentes profundos (PageRank/centralidad; activación de nivel base y activación propagada de ACT-R de la ciencia cognitiva; curvas de olvido de repetición espaciada). Esta es una implementación pequeña y honesta de ese linaje, dirigida específicamente a la memoria de agentes.

Por qué está construido así

1. El motor y la interfaz están separados. El almacén de grafos se detrás de una pequeña interfaz (GraphStore). Los agentes y la lógica de puntuación nunca tocan una base de datos específica, por lo que ejecutar exactamente el mismo grafo en un motor integrado hoy y cambiarlo a Neo4j más tarde con una variable de entorno.

2. La relevancia está ponderada por recencia, no por el recuento bruto de conexiones. «Más conexiones = más relevante» recompensa para siempre los datos antiguos y muy referenciados — exactamente el problema de datos obsoletos el sistema pretende eliminar. Aquí, la contribución de cada arista a la relevancia se multiplica por un factor de decaimiento temporal vinculado a cuándo se reforzó por última vez la conexión. Una arista reforzada ayer cuenta casi al completo; una tocada por última vez hace seis meses cuenta casi nada. Reutilizar una conexión (recall/reinforce) restablece su reloj — así la relevancia sigue lo que está realmente activo, y el conocimiento obsoleto se hunde por sí solo.

Prueba, desde el grafo semilla de demostración (python -m ebb.demo):

node                             raw#   activation
decision:outcome-pricing            3        6.116   <- fresh, few links, ranks #1
decision:seat-pricing              11        3.077   <- MOST links, ranks #3
...
note:analysis-* (x10)               1        0.051   <- decayed -> archived (tier 4)

La decisión por asiento superada tiene el recuento bruto de conexiones más alto del grafo y aun así ocupa el tercer lugar, detrás de una decisión reciente con un tercio de los enlaces. El recuento bruto perdió; la recencia ganó.

Related MCP server: Memory Engine MCP

Qué incluye

• Modelo de grafo — cada nota, decisión, reunión, persona, cliente, hecho es un nodo; cada referencia es una arista con marca de tiempo, tipada y ponderada.

• Motor de puntuación (scoring.py) — activación ponderada por recencia, decaimiento exponencial (vida media configurable), un salto de activación propagada (un sustituto portátil de PageRank) y asignación de niveles. Funciones puras, completamente probadas con pruebas unitarias.

• Cuatro niveles de archivo — 1 caliente (recuperación predeterminada) · 2 templado (recuperación más profunda) · 3 frío (archivado, solo bajo demanda) · 4 congelado (pendiente de aprobación humana antes de la eliminación). Los nodos fijados nunca se archivan automáticamente.

• Servidor MCP (mcp_server.py) — la interfaz del agente: remember, recall, connect, reinforce, forget, neighbors, pin, maintain, review_queue, stats.

• Dos backends — KuzuStore (integrado, predeterminado) y Neo4jStore (producción), misma interfaz, mismas formas de Cypher.

Inicio rápido (integrado — cero infraestructura)

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

python -m ebb.demo      # narrated end-to-end walkthrough
pytest -q                 # 11 tests, all green

Sin Docker, sin servidor, sin puertos. Kùzu es una base de datos de grafos en proceso, por lo que Ebb es solo una carpeta (./ebb_db).

Conéctalo a un cliente MCP (p. ej. Claude Desktop)

1. Copia el bloque ebb de claude_desktop_config.example.json en la configuración MCP de tu cliente, corrigiendo las rutas absolutas.

2. Reinicia el cliente. Las herramientas de ebb aparecen en el menú de herramientas.

3. El agente ahora puede remember cosas entre sesiones, recall lo que es relevante y reinforce lo que sigue usando — con el decaimiento y el archivado gestionados por él.

Modo producción (Neo4j)

docker compose up -d      # Neo4j + Graph Data Science + APOC
EBB_BACKEND=neo4j NEO4J_PASSWORD=brainbrain python -m ebb.demo

Mismo código, mismo comportamiento. En Neo4j además obtienes la librería GDS, por lo que el paso de activación propagada en scoring.py puede ascender a PageRank / centralidad / detección de comunidades reales cuando la escala lo exija. (El Cypher del backend de Neo4j refleja el backend de Kùzu completamente probado; ejecuta pytest contra una instancia en vivo antes de confiar en él en producción.)

El modelo, brevemente

Activación de un nodo = Σ (edge.weight × decay(age_since_last_reinforced)) + read-recency-bonus, más un salto amortiguado de lo mismo desde sus vecinos. El decaimiento es una vida media (30 días por defecto, ajustable). Los niveles se cortan en la activación normalizada contra el nodo no fijado más activo. recall combina esta activación con la coincidencia de texto de la consulta y devuelve por qué apareció cada resultado. Todo es ajustable en un solo lugar — ebb/scoring.py::Config.

Escribir un adaptador de ingesta

Ebb es agnóstico respecto a la fuente: cualquier cosa que llame a remember/connect puede alimentarlo. Una fuente (una carpeta de notas, una wiki, un rastreador de incidencias) se convierte en un grafo mapeando documentos a nodos, enlaces/menciones a aristas y una marca de tiempo de edición al reloj de recencia. Mantén los adaptadores y sus datos fuera del repositorio.

Estructura

src/ebb/
  model.py        # Node, Edge, tiers
  scoring.py      # decay, activation, spreading, tiering  <- the core
  store.py        # GraphStore interface
  kuzu_store.py   # embedded backend (default)
  neo4j_store.py  # production backend
  engine.py       # Brain: remember/recall/connect/reinforce/maintain/...
  mcp_server.py   # agent-facing MCP tools
  seed.py         # fictional demo graph
  demo.py         # narrated walkthrough
tests/            # 11 tests: scoring + end-to-end
docker-compose.yml

Licencia

MIT — ver LICENSE.