Hanzo Brain: grafo di conoscenza local-first per gli agenti

Il tuo agente è sveglio, ma dimentica. Lo abbiamo sistemato. Oggi rilasciamo Hanzo Brain — un solo binario, un solo file SQLite in ~/.hanzo/brain/brain.db, e la stessa superficie di algoritmi in TypeScript, Python, Rust, Go e C++. Lascia un file markdown in ~/.hanzo/workspace/. Il cervello lo ingerisce, estrae archi tipizzati e indicizza il contenuto per il recupero ibrido. Nessun LLM viene chiamato. Il grafo si capitalizza.

Questo è lo strato di memoria di ogni runtime Hanzo — il bot, il server MCP, l'Hanzo Node e qualunque cosa incorpori nel tuo host.

Che cos'è il cervello

Il cervello sono tre cose in un solo processo:

1. Pagine — contenuto indirizzato per slug, scritto da ovunque, osservato su disco.
2. Archi — relazioni tipizzate (mentions, attended, works_at, invested_in, founded, advises) estratte a ogni scrittura da regex e inferenza di ruolo. Zero LLM.
3. Fatti — tuple (subject, predicate, object, ts, confidence) interrogabili in tempo reale tra le sessioni.

Le pagine ricevono un indice FTS5. Gli archi ricevono una chiave primaria su (source, target, type). I fatti ricevono un id e un timestamp. Lo schema è abbastanza corto da tenerlo in testa:

CREATE TABLE pages (slug TEXT PRIMARY KEY, content TEXT, frontmatter TEXT, updated_at TEXT);
CREATE VIRTUAL TABLE pages_fts USING fts5(content, content='pages', content_rowid='rowid');
CREATE TABLE edges (source TEXT, target TEXT, type TEXT, evidence TEXT, PRIMARY KEY (source, target, type));
CREATE TABLE facts (id TEXT PRIMARY KEY, subject TEXT, predicate TEXT, object TEXT, source TEXT, ts TEXT, confidence REAL);

Questo è l'intero contratto. Ogni backend lo onora. Ogni runtime scrive un file identico byte per byte.

Perché conta l'estrazione senza LLM

Gli estrattori basati su LLM bruciano token, latenza e soldi a ogni scrittura. Producono deriva tra un'esecuzione e l'altra. Rendono il grafo non deterministico.

Il cervello estrae gli archi con regex e inferenza di ruolo al momento della scrittura. È veloce, è gratis e produce gli stessi archi ogni volta, a parità di input. Quando ingerisci «Alice ha fondato Acme. Lei ha investito in Foobar», ottieni:

people/alice -[founded]->     companies/acme
people/alice -[invested_in]-> companies/foobar

Ogni volta. Su ogni runtime. Nessun round-trip.

Se vuoi un arricchimento LLM sopra — disambiguazione delle entità, verifica delle affermazioni, riassunto — chiami il tuo modello sopra il grafo deterministico. Il grafo è il substrato. L'LLM è la finitura facoltativa.

Un file. Ogni runtime.

Lo stesso brain.db si apre in TypeScript, Python, Rust, Go e C++. Nessuna traduzione di formato, nessuna migrazione. Se scrivi da hanzobot/go su un server e leggi da @hanzo/bot-memory in un worker del browser, leggi il file che il server ha scritto.

Funzione	TS	Python	Rust	Go	C++
Interfaccia BrainStore	sì	sì	sì	sì	sì
SQLite (predefinito)	sì	sì	sì	sì	sì
Ricerca ibrida FTS5	sì	sì	trait	sì	sì
Estrattore di link del grafo	sì	sì	sì	sì	sì
Caricatore di ricette	sì	sì	sì	sì	sì
Backend innestabili	sì	sì	sì	sì	sì

Totali dei test tra i runtime al lancio: 121 TS + 53 Python + 58 Go + 38 Rust (mcp) + 38 Rust (node) + 98 C++ = 406 test, tutti verdi. Ogni runtime porta la stessa fusione, lo stesso rerank (MMR), lo stesso RRF, la stessa normalizzazione degli slug, lo stesso estrattore di archi.

Interrogabile da MCP

Il cervello è esposto tramite MCP come tre strumenti:

• brain.recall <entity> — ogni fatto mai affermato su un'entità, con timestamp.
• brain.search <query> — FTS ibrido più vettore, fusi con RRF, rerank MMR facoltativo.
• brain.ingest <slug> <content> — scrive una pagina, estrae gli archi da solo, aggiorna l'FTS.

Ogni agente che parla con un Hanzo Node, con il server MCP di Hanzo o con un bot costruito su hanzobot/* riceve questi strumenti gratis. Niente sidecar, niente servizio extra, niente database separato da gestire.

Per la via del binario unico Go:

go install github.com/hanzobot/go/cmd/hanzo-bot@latest

hanzo-bot brain init                  # opens ~/.hanzo/brain/brain.db
hanzo-bot brain ingest people/alice.md
hanzo-bot brain recall people/alice
hanzo-bot brain search "founded"

Per Python:

from hanzo_memory.graph_links import extract_edges
edges = extract_edges(slug="people/alice", content="Alice founded Acme.")

Per Rust, incorporato dentro hanzo-mcp:

use hanzo_mcp::brain::{extract_edges, slugify};
let edges = extract_edges("people/alice", "Alice is CEO of Acme.", Some("person"));

Storage innestabile, stesso contratto

SQLite è la scelta predefinita. Basta per le prime centomila pagine su un portatile. Quando lo superi, registri un altro backend senza cambiare il codice dell'applicazione:

Backend	Quando
sqlite	da soli, < 100K pagine
qdrant	ANN vettoriale su scala
meilisearch	FTS per parole chiave su scala
zapdb	store nativo canonico e multilingue
replicate	WAL di SQLite trasmesso su S3 per il backup
vfs	file system a blocchi in streaming su S3, dimensione illimitata
postgres	deployment di team multi-tenant

Per una semantica distribuita a forma di SQLite su più macchine usiamo il trasporto ZAP, il consenso Quasar e zapdb. Il cervello resta lo stesso. Il contratto byte in entrata, byte in uscita regge.

Memoria che si capitalizza

Il punto del cervello non è un database. È il cambio di assunzione. Il tuo agente non inizia ogni sessione in bianco. Il markdown che hai scritto un anno fa è già un grafo. Le conversazioni di ieri hanno prodotto archi e fatti che la sessione di oggi può interrogare senza pagare token. Due agenti su due macchine possono condividere brain.db tramite replicate e convergere sulla stessa vista.

È questo che intendiamo per memoria che si capitalizza. Il grafo cresce. Il modello costa meno. L'utente vede un assistente che ricorda.

Prendi il cervello

• Canone TypeScript (arriva con il bot): npm install -g @hanzo/bot && hanzo-bot serve
• Python: pip install hanzo-memory
• Binario unico Go: go install github.com/hanzobot/go/cmd/hanzo-bot@latest
• Rust: membro del workspace di hanzoai/node e di hanzoai/mcp
• C++: solo header in hanzobot/cpp/include/hanzo/brain/

Sorgente: github.com/hanzoai/brain. Licenza: MIT.

---

Un file. Cinque runtime. Zero chiamate LLM per le operazioni sul grafo. Local-first, per progetto.