CockroachDB × AWS · Build with Agentic Memory

STIGMERGY

Coordination without a coordinator. Verifiable without a central authority. Coordinación sin coordinador. Verificable sin autoridad central.

Autonomous agents build and reinforce a shared episodic memory by interacting only through distributed state in CockroachDB — the way ants build trails: no messages, no leader, just traces in a shared world. Agentes autónomos construyen y refuerzan una memoria episódica compartida interactuando únicamente a través de estado distribuido en CockroachDB — como las hormigas construyen sus senderos: sin mensajes, sin líder, solo huellas en un mundo compartido.

Discover howDescubre cómo GitHub →
scrolldesliza ▾
Built for judging: an agentic memory system where the database is the coordination surface. Creado para evaluación: un sistema de memoria agéntica donde la base de datos es la superficie de coordinación.
CockroachDB · VECTOR AWS · LAMBDA AUDIT · MERKLE
Jury briefResumen para el jurado

Memory is the system — not a feature bolted on later. La memoria es el sistema — no una función añadida al final.

STIGMERGY turns persistent memory into a shared environment: autonomous agents retrieve context, leave decaying recruitment traces, reach deterministic consensus, and commit a verifiable history. STIGMERGY convierte la memoria persistente en un entorno compartido: agentes autónomos recuperan contexto, dejan rastros de reclutamiento que decaen, alcanzan consenso determinista y confirman un historial verificable.

Technology, made load-bearingTecnología estructural, no decorativa

Each integration directly changes how the agent remembers, reacts, or can be trusted.Cada integración cambia directamente cómo el agente recuerda, reacciona o puede ser confiable.

  • 01
    Distributed Vector IndexingVECTOR(384) + prefix region_id keep semantic recall and regional search inside CockroachDB.VECTOR(384) + el prefijo region_id mantienen la recuperación semántica y la búsqueda regional dentro de CockroachDB.
  • 02
    CockroachDB ChangefeedsA recruitment write becomes a webhook event that triggers the reactive resolver — no polling in the deployed path.Una escritura de reclutamiento se vuelve un evento webhook que activa el resolvedor reactivo — sin sondeo en la ruta desplegada.
  • 03
    AWS LambdaTwo bounded workers: one resolves changefeed deliveries; another runs scheduled signal expiry and orphan sweeping.Dos workers acotados: uno resuelve entregas de changefeed; otro ejecuta expiración programada de señales y barrido de huérfanos.
Live decision traceTraza de decisión READY
Memory under reviewMemoria bajo revisión
“Vector indexes make semantic recall fast at scale.”“Los índices vectoriales agilizan la recuperación semántica a escala.”
cooking / current
→
databases / resonant
Waiting for a judge to replay the memory decision.Esperando que el jurado reproduzca la decisión de memoria.
audit_hash: pending
The ideaLa idea

Ants don't hold meetings. Las hormigas no hacen reuniones.

An ant that finds food doesn't tell the others. It leaves a pheromone trail in the environment. Other ants follow it, reinforce it, and the colony converges on the best path — while unused trails simply evaporate. The environment itself is the communication channel. Una hormiga que encuentra comida no se lo cuenta a las demás. Deja un rastro de feromonas en el entorno. Otras hormigas lo siguen, lo refuerzan, y la colonia converge en el mejor camino — mientras los rastros sin uso simplemente se evaporan. El propio entorno es el canal de comunicación.

STIGMERGY applies exactly that principle to machine memory. Each agent reads shared state, reacts to it, and writes back. No agent commands another. No LLM makes any decision. Yet the system converges on a collective memory — and every single state change is cryptographically sealed into tamper-evident hash chains and a chained Merkle ledger. STIGMERGY aplica exactamente ese principio a la memoria de las máquinas. Cada agente lee el estado compartido, reacciona y escribe de vuelta. Ningún agente da órdenes a otro. Ningún LLM toma decisión alguna. Y aun así el sistema converge en una memoria colectiva — y cada cambio de estado queda sellado criptográficamente en cadenas de hash a prueba de manipulación y un libro mayor de Merkle encadenado.

This is not a distributed cache in front of a vector store: CockroachDB's vector index, changefeeds and multi-region locality are load-bearing parts of the algorithm, not swappable infrastructure. Esto no es una caché distribuida delante de un almacén vectorial: el índice vectorial, los changefeeds y la localidad multi-región de CockroachDB son piezas estructurales del algoritmo, no infraestructura intercambiable.

stigmergyestigmergia /ˈstɪɡ.mə.dʒi/
From Greek stigma (mark) + ergon (work): coordination through traces left in the environment. Del griego stigma (marca) + ergon (trabajo): coordinación mediante huellas dejadas en el entorno.
Agents communicate exclusively by writing and observing shared state. Signals decay like pheromones. Consensus emerges; nobody orchestrates it. Los agentes se comunican exclusivamente escribiendo y observando estado compartido. Las señales decaen como feromonas. El consenso emerge; nadie lo orquesta.
How it worksCómo funciona

The life of a memory La vida de un recuerdo

Memories live in themed regions inside a distributed vector index. Agents roam, recall, and reinforce — and when a memory sits in the wrong neighborhood, the colony quietly moves it home. Los recuerdos viven en regiones temáticas dentro de un índice vectorial distribuido. Los agentes deambulan, recuerdan y refuerzan — y cuando un recuerdo está en el vecindario equivocado, la colonia lo devuelve a casa sin que nadie lo ordene.

Recall & reinforceRecordar y reforzar

An agent queries a region. Every recall reinforces what it touches — confidence grows by exact closed-form arithmetic, never by an LLM's opinion. Un agente consulta una región. Cada recuerdo recuperado se refuerza — la confianza crece con aritmética exacta de forma cerrada, nunca por la opinión de un LLM.

SignalSeñalizar

If the density gradient says a memory sits far from its resonant neighborhood, the agent drops a recruitment signal — a pheromone that decays exponentially over time. Si el gradiente de densidad indica que un recuerdo está lejos de su vecindario resonante, el agente deja una señal de reclutamiento — una feromona que decae exponencialmente con el tiempo.

ConsensusConsenso

Other agents observe the signal and vote with exact Fraction arithmetic. Weighted consensus — never a single acceptance — decides the migration, under an anti-oscillation cooldown. Otros agentes observan la señal y votan con aritmética exacta de Fraction. Un consenso ponderado — nunca una aceptación aislada — decide la migración, bajo un periodo de enfriamiento anti-oscilación.

Seal & verifySellar y verificar

The migration and its audit event commit in one transaction. Per-node hash chains roll up into a chained Merkle ledger — verifiable end to end, with no central authority. La migración y su evento de auditoría se confirman en una sola transacción. Las cadenas de hash por nodo se consolidan en un libro mayor de Merkle encadenado — verificable de punta a punta, sin autoridad central.

The rulesLas reglas

Eight invariants, non-negotiable Ocho invariantes, no negociables

These rules exist to survive contact with future optimizations. Violating one requires an explicit architecture decision — never a quiet patch. Estas reglas existen para sobrevivir al contacto con futuras optimizaciones. Violar una exige una decisión de arquitectura explícita — nunca un parche silencioso.

INV-1

Shared state decidesEl estado compartido decide

No agent holds private truth. Every action reacts to what is read from CockroachDB — never to local caches or direct messages.Ningún agente posee una verdad privada. Toda acción reacciona a lo que se lee de CockroachDB — nunca a cachés locales ni mensajes directos.

INV-2

No LLM in the decision pathNingún LLM en el camino de decisión

An LLM may narrate a dashboard. It may never decide whether a memory reinforces, migrates or merges. Decisions are deterministic Fraction arithmetic.Un LLM puede narrar un panel. Jamás puede decidir si un recuerdo se refuerza, migra o se fusiona. Las decisiones son aritmética determinista con Fraction.

INV-3

No unaudited transitionNinguna transición sin auditar

Not "should be audited" — cannot exist unaudited. State change and audit event share one transaction; if the audit fails, the change is rejected.No es "debería auditarse" — no puede existir sin auditar. Cambio de estado y evento de auditoría comparten una transacción; si la auditoría falla, el cambio se rechaza.

INV-4

Regions are aliveLas regiones están vivas

Regions carry generation and lineage so every split, merge and migration can be reconstructed. No region permanently owns its memories.Las regiones llevan generación y linaje para reconstruir cada división, fusión y migración. Ninguna región es dueña permanente de sus recuerdos.

INV-5

Global order is undefined — on purposeEl orden global es indefinido — a propósito

Each node keeps its own hash chain; integrity across nodes comes from a chained Merkle ledger, never a global sequence number. A property, not a limitation.Cada nodo mantiene su propia cadena de hash; la integridad entre nodos proviene de un libro Merkle encadenado, nunca de un número de secuencia global. Es una propiedad, no una limitación.

INV-6

Cooldown against oscillationEnfriamiento contra la oscilación

A memory never migrates twice within its cooldown window — preventing A→C→A→C ping-pong under noisy signals.Un recuerdo nunca migra dos veces dentro de su ventana de enfriamiento — evitando el ping-pong A→C→A→C bajo señales ruidosas.

INV-7

Pheromones evaporateLas feromonas se evaporan

Recruitment signals decay exponentially and are never permanently binding. Late arrivals see a weak signal with diminished influence.Las señales de reclutamiento decaen exponencialmente y nunca son vinculantes para siempre. Quien llega tarde ve una señal débil con influencia menguada.

INV-8

Nothing is ever deletedNada se borra jamás

FORGOTTEN and ORPHANED are states, not deletions. Rediscovery is always possible — and is itself an audited event.FORGOTTEN y ORPHANED son estados, no borrados. El redescubrimiento siempre es posible — y es, en sí mismo, un evento auditado.

AnatomyAnatomía

What lives in the database Qué vive en la base de datos

The schema is the real spec — most invariants are constraints, not conventions. El esquema es la especificación real — la mayoría de los invariantes son restricciones, no convenciones.

ComponentComponente RoleRol
memories Episodic memory store. State (reinforced / neutral / forgotten) and tier (short-term / regional / global / orphaned) are independent axes.Almacén de memoria episódica. Estado (reforzado / neutral / olvidado) y nivel (corto plazo / regional / global / huérfano) son ejes independientes.
memory_regions Living memory regions, prefix-partitioned in the vector index, carrying full lineage.Regiones de memoria vivas, particionadas por prefijo en el índice vectorial, con linaje completo.
cell_links Association strength between memories — resonant or inhibitory.Fuerza de asociación entre recuerdos — resonante o inhibitoria.
recruitment_signals The stigmergic protocol itself: write-only signals other agents observe. Decaying state — never a message bus.El protocolo estigmérgico en sí: señales de solo escritura que otros agentes observan. Estado que decae — nunca un bus de mensajes.
agent_search_state Per-agent roaming/dwelling controller, driven by hysteresis over resonance density — not by agent-local confidence.Controlador de exploración/permanencia por agente, guiado por histéresis sobre la densidad de resonancia — no por confianza local del agente.
audit_chain Per-node, tamper-evident hash chain of every state-changing event.Cadena de hash por nodo, a prueba de manipulación, de cada evento que cambia el estado.
merkle_snapshots Chained Merkle roots over all nodes' chain heads. A ledger of ledgers.Raíces de Merkle encadenadas sobre las cabezas de todas las cadenas. Un libro mayor de libros mayores.
The substrateEl sustrato

Why CockroachDB is load-bearing Por qué CockroachDB es estructural

🧭

Vector index with prefix columnsÍndice vectorial con columnas prefijo

Partitioning by region_id makes dwelling (in-region search) cheap and roaming (cross-region) expensive by construction. The biological metaphor and the query planner's real cost model coincide. Particionar por region_id hace que permanecer (buscar en la región) sea barato y deambular (entre regiones) caro por construcción. La metáfora biológica y el modelo de costes real del planificador coinciden.

⚡

Changefeeds → AWS Lambda

Changefeeds — not polling — drive the reactive layer: CockroachDB → webhook → Lambda → write-back. The database is a consensus substrate, never a message bus. A second, cron-driven Lambda sweeps expired signals and stale memories in bounded chunks. Los changefeeds — no el sondeo — impulsan la capa reactiva: CockroachDB → webhook → Lambda → escritura de vuelta. La base de datos es un sustrato de consenso, nunca un bus de mensajes. Una segunda Lambda, con cron, barre señales expiradas y recuerdos obsoletos en lotes acotados.

🌍

Multi-region localityLocalidad multi-región

Row-level locality gives physical meaning to "region" beyond a foreign key — while the schema keeps logical memory regions and physical nodes strictly distinct concepts. La localidad a nivel de fila da significado físico a "región" más allá de una clave foránea — mientras el esquema mantiene regiones lógicas de memoria y nodos físicos como conceptos estrictamente distintos.

Failure philosophyFilosofía del fallo

Explicit degradation over hidden recovery Degradación explícita antes que recuperación oculta

01If consensus cannot be established, the system preserves uncertainty.Si el consenso no puede establecerse, el sistema preserva la incertidumbre.
02If migration cannot be completed, the memory remains in place.Si la migración no puede completarse, el recuerdo permanece donde está.
03If the audit cannot be written, the state transition is rejected.Si la auditoría no puede escribirse, la transición de estado se rechaza.

The system never fabricates certainty in order to preserve availability. El sistema nunca fabrica certeza para preservar la disponibilidad.

Honest by designHonesto por diseño

Limitations, named out loud Limitaciones, dichas en voz alta

"A limitation named is a decision; a limitation hidden is a bug waiting for a better moment." Every one of these is documented in KNOWN_LIMITATIONS.md. "Una limitación nombrada es una decisión; una limitación oculta es un bug esperando un mejor momento." Cada una está documentada en KNOWN_LIMITATIONS.md.

Try itPruébalo

Watch the colony fix its own memory Mira a la colonia arreglar su propia memoria

The demo seeds three themed regions plus six deliberately misplaced memories. Agents recall, reinforce, signal and migrate them home — then the report verifies every hash chain and the full Merkle ledger. ~160 pure tests run with no database at all. La demo siembra tres regiones temáticas más seis recuerdos deliberadamente mal ubicados. Los agentes recuerdan, refuerzan, señalizan y los migran a casa — y el informe verifica cada cadena de hash y el libro Merkle completo. ~160 tests puros se ejecutan sin base de datos alguna. 

# Pure tests — no database neededTests puros — sin base de datos
for t in tests/test_*_pure.py; do python3 "$t"; done

# Full demo against CockroachDB v25.2+Demo completa contra CockroachDB v25.2+
pip install psycopg sentence-transformers
python -m demo.run_demo --dsn "$STIGMERGY_DSN" \
    --agents 3 --rounds 20 --provider minilm --local-resolver