Hippoagent Entity Recall

HippoAgent — entity-first recall (hippo_entity_get)

Quando l'utente chiede "che sai di X?" / "ricordami chi è Y?" / "dammi tutto su Z", chiama hippo_entity_get(name=<X>) PRIMA di rispondere da memoria interna. Il tool ritorna l'entity canonica (risolvendo eventuali alias) + la lista di fact collegati, da un knowledge graph SQLite persistente.

⚠️ Quando ATTIVARE (trigger)

Pattern lessicali che attivano il skill:

• Italiano: "che sai di X", "cosa ricordi di Y", "dammi tutto su Z", "chi è W", "ricostruisci ciò che sappiamo di V", "abbiamo discusso di U", "informazioni su T", "storia di S".
• English: "what do you know about X", "tell me about Y", "facts about Z", "who is W", "history of V", "what have we said about U", "summarize what we know on T".
• Implicito: l'utente menziona un nome Capitalized (persona, paper, repo, progetto interno) e ti aspetti che ne sappia qualcosa.

Risoluzione automatica alias: lookup di "S. Tonegawa" trova l'entity canonica "Tonegawa" se è stato registrato l'alias.

Case + Unicode-safe: "müller", "MÜLLER", "Müller" trovano tutti la stessa entity. Anche NFC vs NFD (unicodedata.normalize forma decomposta vs composta) sono trattati come uguali.

NON serve per:

• Claim factual da validare ("X is Y") → hippo_validate_claim
• Ricerca su episodi/dialoghi su un topic → hippo_search, hippo_recall
• Ricerca su fact per topic-namespace → hippo_facts_search, hippo_facts_list
• Saluti, chat casuale, opinioni

Flow

1. Identifica il nome dell'entity nella domanda (Capitalized,
   eventualmente con prefisso "S." / "Dr." / titolo).
2. hippo_entity_get(name="<entity>")
3. Read payload:
   {
     "entity": { "id": "...", "canonical_name": "...", "type": "..." }
              | None,
     "aliases": ["...", "..."],
     "facts": ["fact_id_1", "fact_id_2", ...]
   }
4. Act:
   ┌─ entity is None     → "Non ho memoria di <name> nel KG. Vuoi
   │                       che cerchi episodi correlati?
   │                       (`hippo_search`)"
   ├─ entity, facts == [] → "Ho il nodo <canonical_name> (id=...,
   │                       type=...) ma nessun fatto direttamente
   │                       linkato. Posso cercare con
   │                       `hippo_facts_search` o `hippo_recall`."
   └─ entity, facts ≠ []  → Leggi i fact con `hippo_facts_list`
                           (passando i fact_id ottenuti) per
                           ricostruire la conoscenza completa,
                           poi rispondi citando i fact_id come
                           evidenza.

Output semantics

Parametri

• name: str — il nome o alias da cercare. Trim + Unicode NFC + case-fold automatici dal backend.

Esempi concreti

Esempio 1 — entity trovata con facts

User: "cosa ricordi di Tonegawa?"

hippo_entity_get(name="Tonegawa")
→ {
    "entity": {
      "id": "a8f3c9d12e4b",
      "canonical_name": "Tonegawa",
      "type": "person"
    },
    "aliases": ["S. Tonegawa", "Susumu Tonegawa"],
    "facts": ["f_tonegawa_nobel_1987", "f_tonegawa_engram_2014"]
  }

Azione: chiama hippo_facts_list(fact_ids=["f_tonegawa_nobel_1987", "f_tonegawa_engram_2014"]) per leggere le proposizioni complete, poi rispondi:

Tonegawa (Susumu Tonegawa, person) — 2 fact in memoria:

1. Nobel Prize 1987 per immunology (V(D)J recombination) [f_tonegawa_nobel_1987]
2. Lavori sull'engram a MIT 2014 [f_tonegawa_engram_2014] Alias noti: "S. Tonegawa", "Susumu Tonegawa".

Esempio 2 — alias risolve a canonical

User: "dammi tutto su S. Tonegawa"

hippo_entity_get(name="S. Tonegawa")
→ {
    "entity": {"id": "a8f3c9d12e4b", "canonical_name": "Tonegawa", ...},
    "aliases": [...],
    "facts": [...]
  }

L'alias è risolto trasparentemente: stesso id dell'entity canonica.

Esempio 3 — entity sconosciuta

User: "che sai di Marie Curie?"

hippo_entity_get(name="Marie Curie")
→ {"entity": None, "aliases": [], "facts": []}

Risposta corretta (onesta):

Non ho memoria di Marie Curie nel knowledge graph entity-centric. Posso cercare episodi correlati con hippo_search("Marie Curie") o fatti con hippo_facts_search?

NON CONFABULARE una risposta basata su training data — l'utente ha chiesto cosa c'è in memoria persistente, non cosa sa il modello.

Esempio 4 — entity nota, zero fact linkati

User: "abbiamo discusso di NeuroFlask?"

hippo_entity_get(name="NeuroFlask")
→ {
    "entity": {"id": "...", "canonical_name": "NeuroFlask", "type": "repo"},
    "aliases": [],
    "facts": []
  }

Risposta:

Il nodo entity "NeuroFlask" esiste nel KG (type=repo) ma non ha fatti direttamente linkati. Probabilmente è stato menzionato in episodi senza che facts/triple siano state estratte (l'auto- extraction OpenIE è P2.c, non ancora attiva). Vuoi che cerchi negli episodi con hippo_search?

Esempio 5 — Unicode case-fold + NFC

User: "che sai di müller?" (lowercase, NFC)

User store-side: hippo_entity_get(name="MÜLLER") o name="Müller" o anche forma NFD u+combining-diaeresis → tutti risolvono allo stesso id. Backend usa unicodedata.normalize ("NFC", s).strip().lower() su una colonna name_norm indicizzata UNIQUE (schema v4).

Limitazioni note (P2.a)

• No edges: non c'è ancora entity_edges (predicate + weight), quindi nessuna navigazione multi-hop tipo "entity vicine di X" o "fact che connettono X a Y". P2.b lo aggiungerà con hippo_entity_neighbors + hippo_ppr_retrieve (HippoRAG-style Personalized PageRank).
• No auto-extraction: le entity e i link entity↔fact non vengono estratti automaticamente dagli episodi. Per ora vanno inseriti manualmente con script di seed. P2.c esporrà hippo_extract_entities(text) LLM-based con json.loads strict.
• No type schema: il campo type è una stringa libera ("person", "paper", ...). Non ci sono vincoli o gerarchie.
• Solo lookup esatto: cerca per canonical_name o alias con match Unicode case-insensitive. Nessun fuzzy match, nessuna espansione semantica. "Schroedinger" NON matcha "Schrödinger" (Ö vs OE è translitterazione, fuori scope).
• Population seed-only: il KG è popolato manualmente fino a P2.c.

Cost

• Zero LLM call.
• Sub-50ms su corpus ~500 entity (SQLite WAL + UNIQUE INDEX su name_norm).
• Free in hosted mode (read on local SQLite + Python str ops).

Quando NON chiamarlo

• Claim factual da validare ("X did Y in YEAR") → hippo_validate_claim
• Ricerca topic-based su fact ("fatti su engram") → hippo_facts_search(query="engram")
• Ricerca episodica su dialoghi/sessioni ("quando abbiamo parlato di Dominic") → hippo_search o hippo_recall
• Domanda generica senza nome Capitalized ("che lavoro ho fatto ieri") → hippo_episode_list + hippo_session_recap
• Chat casuale, saluti, opinioni, output codice

Combinazioni utili

• Entity + tutti i suoi fact: hippo_entity_get(name) → prendi facts[] → hippo_facts_list(fact_ids=facts) per le proposizioni complete.
• Entity + episodi correlati (workaround per assenza di edges): hippo_entity_get(name) → leggi i fact_id → per ogni fact_id chiama hippo_lineage_trace(start_id=fact_id, kind="fact", direction="backward") per arrivare agli episodi sorgente.
• Disambigua un nome: hippo_entity_get ritorna gli aliases — utile per capire come l'utente potrebbe averlo chiamato in altre sessioni.

Storia

P2.a della roadmap Engram-amplifies-Claude (cycle #70).

• Commit 54a0c35 (2026-05-15): MVP iniziale, engram/entity_kg.py, 3 tabelle SQLite (entities + entity_aliases + entity_facts), 10 RED→GREEN test, tool MCP hippo_entity_get.

• Commit 12fa4ff (2026-05-15 notte tarda): hardening multi-round critic-driven. 5 round adversariali consecutivi con critic-orchestrator hanno scoperto 6 bug reali e li hanno forzati a essere fixati:

  1. Race condition check-then-insert non atomico (8 thread paralleli → 2-8 duplicate). Fix: BEGIN IMMEDIATE + UNIQUE INDEX su name_norm + IntegrityError fallback re-SELECT.
  2. Cross-alias dedupe contract violation. Fix: SELECT canonical-only (no JOIN su alias durante store).
  3. Empty canonical_name bypass. Fix: strip + ValueError.
  4. Unicode case-folding bug (SQLite LOWER() ASCII-only: MÜLLER/Müller diventavano 2 entity). Fix: colonne name_norm/alias_norm Python-side via str.lower() full-Unicode + migration v3 backfill + dedup duplicate pre-existenti.
  5. NFC vs NFD form-folding bypass. Fix: unicodedata.normalize("NFC", ...) in _norm() + migration v4 re-backfill.
  6. Migration v4 IntegrityError su DB v3 con duplicate NFC+NFD. Fix: DROP UNIQUE INDEX a inizio v4, UPDATE+dedup, ricreare UNIQUE alla fine.

  Schema finale v4: entities(id, canonical_name, name_norm, type, created_at) con UNIQUE su name_norm + entity_aliases con alias_norm + entity_facts (PRIMARY KEY composito, idempotente via INSERT OR IGNORE).

  Test coverage: 17/17 PASS (10 base + 7 critic-driven). Full pytest 2451 PASS 0 fail.

• Spec: docs/specs/p2-entity-centric-kg.md (commit 48678a2).

• Test: tests/test_entity_kg.py.

Cosa arriva dopo (NON ANCORA disponibile)

• P2.b (next): hippo_entity_neighbors(entity_id, k, hops) + hippo_ppr_retrieve(query_entities, damping=0.5, k=20) per recall multi-hop tipo HippoRAG. Dipendenza: networkx (prpack).
• P2.c: hippo_extract_entities(text, mode="ner+triple") LLM-based 2-step (NER → triple) con json.loads strict, NO parser eseguibile su LLM output. Hook automatico in hippo_record_episode quando l'episodio è abbastanza ricco.
• P2.b/c addendum: hippo_entity_link(fact_id, entities[]) per manual override e seed pipeline.