Subscribe Now
Trending News
Deep Dives

Hindsight v Codexu: paměť, která má agentovi vracet zkušenost, ne jen historii

et, 6 měsíců ago
Hindsight v Codexu: paměť, která má agentovi vracet zkušenost, ne jen historii

Deep dive k integraci Hindsight s Codex CLI, porovnání se Serena memories a praktickému lokálnímu nasazení přes Docker Compose.

AI coding agent bez paměti je zvláštní pracovník. V jedné session opraví problém, pochopí architekturu, najde bezpečnostní pravidlo, vyřeší slepou uličku. Zavřete terminál a příště začne znovu. Ne proto, že by byl hloupý. Prostě nemá kam uložit zkušenost.

To je přesně místo, kam míří Hindsight: persistentní memory layer pro AI agenty. Ne jako obyčejný zápis konverzace, ale jako pokus udělat z minulých interakcí strukturovanou paměť, kterou agent umí později vyhledat, zkonsolidovat a použít při rozhodování. U coding agentů to začíná být praktické hlavně ve chvíli, kdy paměť není jen „uživatel má rád stručné odpovědi“, ale „tenhle projekt nesmí volat WordPress API napřímo“, „testy se spouští přes wrapper“, „minule jsme zjistili, že migrace padá kvůli pořadí seedů“.

Tento text se dívá na Hindsight z pohledu Codex CLI. Vysvětluje retain, recall, reflect, observations, storage, výkonová nastavení, rozdíl proti RAG a praktickou integraci přes hooky. Druhá část porovnává Hindsight s nástrojem Serena, konkrétně s jeho memory managementem, a ukazuje, proč nejde o dvě konkurenční paměti, ale o dvě různé vrstvy cognition stacku coding agenta.

Co je Hindsight

Hindsight je open-source agent memory systém od Vectorize. Repozitář vectorize-io/hindsight popisuje projekt jako „Agent Memory That Learns“ a dokumentace jej staví jako paměťovou vrstvu pro AI agenty, kteří si mají uchovávat zkušenosti napříč sessions. Oficiální přehled říká, že agent do Hindsight ukládá informace přes retain(), hledá přes recall() a uvažuje nad pamětí přes reflect().

Důležité je slovo agent. Hindsight není jen doplněk pro chatbota, který má uživateli připomenout oblíbenou barvu. Je navržený pro scénáře, kde agent opakovaně pracuje v nějakém kontextu, sbírá fakta, vrací se k nim, odvozuje vztahy a postupně si vytváří znalostní model. V coding workflow to znamená paměť pro projektové konvence, debugging zkušenosti, architektonická rozhodnutí, zakázané postupy, fungující příkazy, známé slepé uličky a vzorce práce s nástroji.

Hindsight se snaží řešit několik slabin jednoduché paměti:

  • čistý vector search často nestačí, protože dotazy typu „co jsme řešili loni na jaře“ potřebují práci s časem,
  • izolované chunks ztrácí vztahy mezi fakty,
  • agent potřebuje odlišit surové důkazy od syntetizovaných pozorování,
  • paměť má být oddělená podle bank, projektů nebo uživatelů.

V dokumentaci Hindsight stojí, že systém organizuje knowledge do hierarchie mental models, observations, world facts a experience facts. Při reflect() pak používá prioritu Mental Models → Observations → Raw Facts. To je dobrý mentální model: Hindsight se nesnaží jen vytáhnout „podobný kus textu“, ale držet paměť jako kombinaci faktů, zkušeností a konsolidovaných závěrů.

Pro Codex to má jednoduchý dopad. Codex sám nemusí mít vlastní dlouhodobou paměť. Stačí, aby při správných momentech zavolal Hindsight: před promptem se zeptá na relevantní memory, po odpovědi uloží transcript nebo jeho část. V praxi to zajišťují hooky.

Kdo za Hindsight stojí

Hindsight vyvíjí Vectorize. Projekt je veřejně dostupný na GitHubu v organizaci vectorize-io. Web Vectorize jej prezentuje jako open-source, MIT licencovaný systém pro agent memory, který má fungovat s libovolným LLM backendem a držet persistentní kontext odděleně podle uživatelů nebo agentů.

Kromě samotného repozitáře má Hindsight dokumentaci, integrační návody pro různé agent frameworky a samostatnou architekturu kolem memory banks, storage backendu, API a lokálního nebo cloudového nasazení. Pro tento článek je nejdůležitější integrace OpenAI Codex CLI, protože tam Hindsight funguje přes lifecycle hooky.

Proč je Hindsight zajímavý právě pro coding agenty

Coding agent má jiný typ paměti než osobní asistent. Méně ho zajímá, že uživatel pije espresso. Více ho zajímá, že projekt používá NestJS s vlastním auth guardem, že migrace databáze se nesmí pouštět proti produkci, že API wrapper má retry politiku, že konkrétní knihovna v monorepu je legacy a nemá se refaktorovat bez testů.

To jsou informace, které se často neobjeví v README. Vznikají během práce:

  • při opravě chyby,
  • při čtení diffu,
  • při interpretaci stack trace,
  • při používání MCP nástrojů,
  • při rozhodování, proč se jedna varianta zavrhla,
  • při ručním vysvětlení od uživatele.

Jednorázový context window takovou zkušenost neudrží. RAG nad repozitářem ji také nemusí znát, protože část těchto znalostí nikdy nebyla zapsaná do souborů. Hindsight se snaží právě tuto zkušenost uložit jako dlouhodobou paměť agenta.

V praktickém nasazení popsaném v dodaných poznámkách se potvrdilo, že při retainToolCalls: true Hindsight neumí ukládat jen čisté textové zprávy, ale také tool calls, tool outputs, debugging context, terminal output a orchestration artefakty. To z něj dělá spíš semantic operational memory než běžnou znalostní databázi.

Architektura Hindsight

Zvenku se Hindsight tváří jednoduše:

Agent / aplikace
  ↓
Hindsight API
  ↓
Memory bank
  ↓
PostgreSQL + pgvector + full-text + graph-like vztahy
  ↓
LLM / embedding / reranking backend

Uvnitř je důležité několik pojmů.

Memory bank

Memory bank je izolovaný prostor paměti. Může odpovídat jednomu uživateli, jednomu agentovi, jednomu projektu nebo kombinaci těchto dimenzí. U coding agenta je praktické používat per-project banky, aby se poznatky z jednoho repozitáře nemíchaly s jiným. Codex integrace má pro to nastavení dynamicBankId a dynamicBankGranularity, typicky ['agent', 'project'].

Memory typy

Hindsight rozlišuje více vrstev paměti:

  • World facts: fakta o světě, lidech, projektech, technologiích nebo entitách. V coding kontextu třeba „projekt používá FastAPI s asyncpg“.
  • Experience facts: zkušenosti agenta, tedy co agent udělal, doporučil nebo zažil v interakci. Například „agent minule zkusil spustit testy přes npm, ale projekt používá pnpm“.
  • Observations: konsolidovaná, evidence-grounded přesvědčení vzniklá z více faktů.
  • Mental models: uživatelsky kurátorované nebo předpočítané odpovědi na časté dotazy.

TEMPR retrieval

Recall nepoužívá jen jeden vector search. Dokumentace popisuje TEMPR jako kombinaci čtyř strategií: semantic, keyword/BM25, graph a temporal retrieval. Výsledky se spojí, seřadí a rerankují. To je rozdíl proti jednoduchému RAG, který typicky embeduje dotaz, najde top-k podobných chunks a přidá je do promptu.

Storage

Hindsight používá PostgreSQL jako primární storage backend. Dokumentace explicitně uvádí PostgreSQL, pgvector s HNSW indexy pro vector search, tsvector s GIN indexy pro full-text, JSONB pro dokumenty a rekurzivní CTE pro graph queries. Enterprise alternativou může být Oracle AI Database, ale defaultní mentální model je: jeden PostgreSQL backend, žádná obecná storage abstrakce.

LLM backend

Hindsight sám není LLM. Potřebuje modely pro extrakci faktů, sumarizaci, reasoning, reranking nebo embeddings. Backend může být cloudový nebo lokální. V praktickém lokálním nasazení přes Docker a Ollama běželo Hindsight API v Dockeru a modely přes Ollama na host macOS.

Codex CLI
  ↓
Codex hooks
  ↓
Hindsight API v Dockeru
  ↓
Ollama na host systému
  ↓
LLM + embedding modely

Retain: jak Hindsight ukládá paměť

retain() je write path. Když agent nebo integrace zavolá retain, Hindsight nevezme text a neuloží ho jen jako chunk. Dokumentace říká, že retain transformuje konverzace a dokumenty do strukturovaných, vyhledatelných memories, které zachovávají význam a kontext.

V praxi retain dělá několik věcí.

1. Extrahuje bohatá fakta

Hindsight se snaží zachytit nejen „co bylo řečeno“, ale také proč, jak a co to znamenalo. Dokumentace ukazuje příklad s větou o Alice, která nastoupila do Googlu kvůli research opportunities. Systém z toho extrahuje základní fakta, čas, emoci i důvod.

U coding agenta to znamená, že z konverzace typu:

Tenhle projekt používá bezpečnostní wrapper nad WordPress API.
Agent nesmí volat WordPress API napřímo.

nemá vzniknout jen kus textu. Má vzniknout pravidlo použitelné při budoucí práci:

Project constraint: WordPress API must be accessed only through the security wrapper.
Direct WordPress API calls are forbidden.

2. Zachovává kontext

Běžné systémy často rozsekají konverzaci na samostatné fragmenty. Hindsight se snaží ukládat narativní jednotky tak, aby pozdější search nevrátil izolované věty bez důvodu. To je u debuggingu zásadní. Samotná věta „test selhal“ je k ničemu. Užitečný je řetězec: jaký test, po jaké změně, jaký stack trace, jaký příkaz opravil problém.

3. Rozlišuje world a experience facts

Hindsight rozlišuje fakta o světě a zkušenosti agenta:

world:      Projekt používá PostgreSQL a Temporal.
experience: Agent minule zjistil, že worker padal kvůli chybějícímu env var.

Tohle rozlišení je pro coding agenta důležité. Architektonická fakta jsou jiný typ znalosti než zkušenost s konkrétní opravou.

4. Rozpoznává entity a vztahy

Retain provádí entity recognition a entity resolution. Stejnou entitu zmíněnou různými způsoby se snaží sjednotit. U softwaru to může být služba, modul, knihovna, endpoint, osoba, tým, issue nebo doména.

Pro coding agenta je to užitečné například u dotazů:

Co víš o publish workflow?
Co jsme řešili kolem WordPress wrapperu?
Jaké problémy byly s Temporal workerem?

Pokud systém umí propojit entity, nemusí se spoléhat jen na přesnou shodu slov.

5. Buduje spojení mezi memories

Dokumentace popisuje entity connections, time-based connections, meaning-based connections a causal connections. To je jeden z klíčových rozdílů proti obyčejnému vector store.

U coding agenta může causal connection vypadat takto:

Migration failed
  ← caused by
Seed script ran before enum migration
  ← fixed by
Changing migration order

Budoucí dotaz „proč nám padaly migrace“ pak není jen semantic search. Je to hledání v paměti, která si drží i příčinu.

6. Ukládá temporalitu

Hindsight sleduje dvě časové dimenze: kdy se událost stala a kdy se o ní systém dozvěděl. U projektů je to praktické. Něco mohlo platit v lednu, ale v březnu se architektura změnila. Memory systém musí umět pracovat s tím, že staré informace nejsou nutně špatné, ale mohou být stale.

Recall: jak Hindsight vyhledává paměť

recall() je read path. Agent položí dotaz a Hindsight má vrátit relevantní memories v token budgetu, který se vejde do context window.

Čtyři retrieval strategie

Hindsight používá čtyři paralelní strategie:

  1. Semantic search Hledá významovou podobnost. Dotaz „jak je řešená autentizace“ může najít memory „API používá JWT guard a refresh token rotation“, i když slovo autentizace v paměti není.

  2. Keyword search Drží přesná jména, unikátní termíny, knihovny, endpointy a názvy modulů. To je důležité u dotazů typu asyncpg, Temporal, WordPress, HNSW, publishEntityWorkflow.

  3. Graph traversal Sleduje vztahy mezi entitami. Pokud agent ví, že modul A používá službu B a služba B volá API C, může najít související informace i bez přímé textové podobnosti.

  4. Temporal search Pracuje s časem. Dotazy „co jsme řešili minulý týden“ nebo „co se změnilo po migraci“ potřebují víc než embedding.

Výsledky se potom fuse-nou a rerankují. Hindsight popisuje, že memory nalezená více strategiemi dostane vyšší prioritu. To dává smysl: pokud výsledek zároveň obsahuje správný technický termín, je sémanticky podobný a časově odpovídá dotazu, je pravděpodobně relevantnější.

Token budget místo top-k

Klasický search často mluví o top_k. Agent ale nežije v počtu výsledků, nýbrž v tokenech. Hindsight proto umožňuje řídit velikost vrácené paměti přes max_tokens a search depth přes budget (low, mid, high).

U Codexu je to praktické. Nechcete, aby paměť sežrala půlku context window. Chcete dost relevantních faktů, ale pořád prostor na aktuální zadání, soubory, diffy a odpověď.

Doporučený start pro coding agenta:

{
  "recallBudget": "mid",
  "recallMaxTokens": 1024
}

Pro rychlejší odezvu lze jít na low nebo snížit recallMaxTokens. Pro investigativní práci ve velkém projektu může dávat smysl high, ale ne jako default pro každý prompt.

Recall není history replay

Tohle je důležitý rozdíl. Recall nemá vrátit posledních deset zpráv. Má vrátit relevantní paměťové jednotky. U coding agenta by tedy neměl do promptu cpát celou minulou session, ale například:

- Project uses a security wrapper for WordPress API; direct API calls are forbidden.
- Tests should be run through ./scripts/test-safe.sh because direct npm test misses env setup.
- Previous migration issue was caused by seed order, not database connectivity.

Taková paměť má hodnotu. Syrová historie často jen zabírá místo.

Reflect: reasoning nad pamětí

reflect() je třetí hlavní operace. Zatímco recall vrací relevantní memories, reflect spouští agentic reasoning loop nad pamětí. Dokumentace popisuje, že reflect autonomně sbírá důkazy, používá hierarchii mental models → observations → raw facts, aplikuje disposition a direktivy banky a vrací odpověď s citacemi použitých memories.

To je důležité rozlišení:

recall  = najdi relevantní paměti
reflect = uvažuj nad pamětí a vrať odpověď

U coding agenta lze reflect použít pro dotazy typu:

Jaký je bezpečný postup pro přidání nového WordPress endpointu v tomhle projektu?

Recall může vrátit jednotlivé relevantní facts. Reflect může složit odpověď:

  • projekt zakazuje přímé volání WordPress API,
  • existuje wrapper,
  • minule se řešila bezpečnostní validace,
  • agent má direktivu preferovat bezpečné cesty,
  • proto má nový endpoint jít přes wrapper, testy a audit log.

Reflect se hodí tam, kde nechcete jen kontext do promptu, ale chcete, aby memory systém sám vytvořil odpověď nebo interní doporučení. U Codex hooků se typicky používá auto-recall před promptem a auto-retain po odpovědi. Reflect je spíš pokročilejší operace, kterou může agent nebo aplikace volat explicitně.

Observations: konsolidace znalostí

Observations jsou možná nejzajímavější část Hindsight, protože řeší problém, který se u dlouhodobé paměti objeví velmi rychle: opakování a stárnutí.

Surová fakta se hromadí. Agent během měsíce desetkrát slyší, že projekt preferuje funkcionální styl, pětkrát narazí na stejný wrapper, třikrát řeší stejný typ testu. Kdyby se všechno vracelo jako facts, paměť by byla hlučná. Observations z toho mají vytvořit deduplikovaná, evidence-grounded přesvědčení.

Podle dokumentace Hindsight po retain automaticky konsoliduje související facts do observations. Každá observation má:

  • supporting evidence,
  • proof count,
  • historii změn,
  • freshness trend typu stable, strengthening, weakening, new nebo stale.

U coding agenta by observation mohla vypadat takto:

Projekt dlouhodobě preferuje bezpečné wrappery nad přímým voláním externích API.
Evidence: WordPress API wrapper rule, debugging session around direct API call, code review instruction.
Trend: strengthening.

To je jiný typ znalosti než jednorázová vzpomínka. Agent už nemusí při každém dotazu znovu skládat preferenci z deseti fragmentů. Má konsolidovaný závěr, ale pořád s odkazem na důkazy.

Výkon a výkonová nastavení

Hindsight je navržený s prioritou rychlého čtení. Dokumentace říká, že systém upřednostňuje read performance před write performance. Dává to smysl: paměť se zapíše jednou, ale čte se často.

Typické latence

Dokumentace uvádí orientační latence:

Operace Typická latence Hlavní bottleneck
Recall 100–600 ms reranker, zejména na CPU
Reflect 800–3000 ms LLM generation
Retain 500–2000 ms na batch LLM fact extraction

Čísla berte jako orientační, protože lokální Ollama, model, CPU/GPU, velikost dokumentu a nastavení budgetu udělají velký rozdíl.

Proč jsou reads rychlejší

Hindsight přesouvá drahou práci na write path:

  • embeddings se počítají při retain,
  • HNSW indexy se připravují pro rychlé approximate nearest neighbor search,
  • fact extraction běží při zápisu,
  • vztahy a temporalita se řeší dopředu.

Výsledek: recall() nemusí při každém promptu znovu analyzovat celý transcript. Jen hledá v předpřipravené struktuře.

Nastavení pro Codex

Pro běžnou práci:

{
  "recallBudget": "mid",
  "recallMaxTokens": 1024,
  "retainEveryNTurns": 10,
  "retainMode": "full-session"
}

Pro testování:

{
  "retainEveryNTurns": 1,
  "debug": true
}

Dodaný praktický test ukázal, že první pokus o retain může vypadat neúspěšně, pokud zůstane default retainEveryNTurns: 10. Retain se jednoduše ještě nespustí. Pro ověření instalace je lepší nastavit retainEveryNTurns: 1 a zapnout debug.

Retain mode: full-session vs chunked

Codex integrace podporuje retainMode:

  • full-session: posílá celou session a používá session ID jako document ID, takže opakované retain běhy aktualizují stejný dokument,
  • chunked: posílá sliding windows po N turns s překryvem.

full-session je pohodlný pro menší sessions a lepší kontext při extrakci. chunked je vhodnější, když jsou sessions dlouhé a nechcete při každém retain posílat všechno.

retainToolCalls

Pro coding agenta je klíčové nastavení:

{
  "retainToolCalls": true
}

Výhoda: Hindsight si může pamatovat nejen slova uživatele, ale i operativní postup agenta — nástroje, výstupy, chyby, příkazy, MCP interakce, debugging kroky.

Nevýhoda: do paměti se mohou dostat stack traces, terminal output, logy, command output nebo citlivé informace. Pro lokální trusted prostředí to může být správný kompromis. Pro produkční nebo compliance citlivé prostředí bych byl opatrnější:

{
  "retainToolCalls": false
}

Storage: kde Hindsight drží data

Hindsight používá PostgreSQL. Prakticky to znamená jeden backend pro:

  • vector search přes pgvector,
  • full-text search přes tsvector a GIN indexy,
  • relační data,
  • JSON dokumenty přes JSONB,
  • graph-like dotazy přes rekurzivní CTE.

To je sympatická volba pro lokální i self-hosted deployment. Nevyžaduje samostatný Elasticsearch, zvláštní graph database a separátní vector DB. Na druhou stranu to znamená, že PostgreSQL je kritická komponenta: backup, volume, migrace a monitoring nejsou doplněk, ale základ.

V Docker Compose nasazení je důležité nepouštět Hindsight bez persistentního volume. Jinak memory zmizí s kontejnerem.

Příklad lokálního volume:

volumes:
  - ~/.hindsight-docker:/home/hindsight/.pg0

Tady není žádná osobní cesta. ~ odkazuje na home aktuálního uživatele a nevystavuje konkrétní jméno účtu.

RAG vs Hindsight z pohledu memory

RAG a Hindsight se často pletou, protože oba umí „něco najít a dát to modelu“. Jenže řeší jiný problém.

RAG

Typický RAG postup:

1. Embed query
2. Vector similarity search
3. Return top-k chunks
4. Generate response

RAG je dobrý, když máte dokumenty a chcete najít relevantní pasáže. Například „najdi v dokumentaci, jak se nastavuje Docker“. V coding workflow je RAG nad repozitářem užitečný pro README, docs, comments, API reference.

Hindsight

Hindsight podle dokumentace přidává:

  • semantic + keyword + graph + temporal retrieval,
  • entity understanding,
  • temporal reasoning,
  • konsolidaci knowledge,
  • disposition a directives pro reflect,
  • persistentní state napříč sessions.

Hindsight tedy není jen retrieval nad dokumenty. Je to paměťový systém, který z interakcí vytváří fakta, vztahy, zkušenosti a pozorování.

Praktický rozdíl:

RAG:       „Najdi podobný chunk v dokumentech.“
Hindsight: „Co jsme se v minulých sessions naučili a jak to souvisí s tímto úkolem?“

U coding agenta bych to rozdělil takto:

Úloha Lepší nástroj
Najít definici funkce v repozitáři Serena / IDE tools / code search
Najít pasáž v dokumentaci RAG
Připomenout projektové pravidlo řečené v minulé session Hindsight
Pochopit symboly a reference Serena
Vzít v úvahu debugging zkušenost z minula Hindsight
Držet explicitní onboarding poznámky Serena memories
Konsolidovat opakované zkušenosti agenta Hindsight observations

Integrace Hindsight do Codex CLI

Oficiální integrace pro Codex funguje přes hooky. To je důležité: Hindsight se nemusí spoléhat na to, že model sám správně zavolá memory tool. Codex spustí skript v konkrétní fázi životního cyklu.

Dokumentace uvádí tři hook eventy:

Hook skript Codex event Účel
session_start.py SessionStart warm-up, ověření dostupnosti Hindsight
recall.py UserPromptSubmit auto-recall, dotaz na memories, injection do additionalContext
retain.py Stop auto-retain, čtení transcriptu, async POST do Hindsight

Co se děje při UserPromptSubmit

Když uživatel odešle prompt, recall.py dostane aktuální prompt a případně několik předchozích turns podle nastavení. Sestaví query, zavolá Hindsight recall a výsledek vrátí Codexu jako hookSpecificOutput.additionalContext.

Codex tento blok přidá do kontextu před zavoláním modelu. Vypadá to zhruba takto:


<hindsight_memories>
Relevant memories from past conversations...
Current time - 2026-03-27 09:14
- Project uses FastAPI with asyncpg — not SQLAlchemy [world] (2026-03-26)
- Preferred testing framework: pytest with pytest-asyncio [experience] (2026-03-26)
</hindsight_memories>

Model tedy memory nevyhledává sám. Dostane ji už připravenou v promptu.

Co se děje při Stop

Po dokončení odpovědi se spustí retain.py. Hook přečte session transcript, odstraní dříve injectnuté hindsight_memories tagy, aby nevznikla feedback smyčka, a pošle obsah do Hindsight. Dokumentace uvádí, že POST probíhá asynchronně.

Tohle je dobrý design. Agent se nemusí ptát „mám si to uložit?“ po každém kroku. Lifecycle vrstva se postará o základní retenční tok.

Per-project memory

Pro coding workflow je důležité zapnout dynamické banky:

{
  "dynamicBankId": true,
  "dynamicBankGranularity": ["agent", "project"]
}

Pak se paměť odvozuje z agenta a working directory. Codex spuštěný v různých projektech nepíše do stejné memory banky. To je prakticky nutnost. Jinak by se pravidla z jednoho repozitáře mohla objevit v jiném.

Hook vs MCP vs skill

Tyto tři pojmy se často míchají, ale chovají se jinak.

Hook

Hook je lifecycle automatizace. Spouští se v konkrétní fázi běhu klienta. U Codex integrace pro Hindsight jsou to hlavně:

SessionStart      → ověř dostupnost Hindsight
UserPromptSubmit  → proveď recall a injectni memory
Stop              → proveď retain transcriptu

Hook je determinističtější než tool, protože se spustí bez ohledu na to, zda si model vzpomene. Agent může být zaneprázdněný opravou kódu, ale Stop hook stejně proběhne.

Výhoda:

  • automatický recall,
  • automatický retain,
  • menší závislost na poslušnosti modelu,
  • dobré pro persistentní paměť.

Nevýhoda:

  • méně jemné rozhodování,
  • může ukládat šum,
  • špatně nastavený hook může injectovat příliš mnoho kontextu.

MCP

MCP znamená Model Context Protocol. Model dostane sadu nástrojů a sám rozhoduje, kdy je použije. Serena funguje právě tímto stylem: poskytne agentovi semantic IDE tools, symbol search, refactoring nástroje a memory tools.

Výhoda:

  • flexibilita,
  • nástroj se volá jen tam, kde model usoudí, že je potřeba,
  • dobré pro explicitní operace typu „přečti memory“, „zapiš memory“, „najdi symbol“.

Nevýhoda:

  • není to plně deterministické,
  • model může nástroj nepoužít,
  • kvalita závisí na instrukcích a disciplíně agenta.

Skill

Skill je instrukční workflow. Říká modelu, jak má postupovat. Například:

Před začátkem práce si načti projektové memories.
Po dokončení důležité změny zapiš novou memory.
Při práci s Hindsight preferuj recall před domněnkami.

Výhoda:

  • levné a přenositelné,
  • dobré pro styl práce,
  • lze kombinovat s hooky i MCP.

Nevýhoda:

  • model instrukci nemusí vždy dodržet,
  • není to runtime garance,
  • neřeší storage ani API.

Praktické srovnání

Hook  = automatická lifecycle vrstva
MCP   = sada toolů, které model může volat
Skill = instrukční postup, který model vede

Pro Hindsight v Codexu je hook správná volba pro základní persistentní paměť. Pro Serenu je MCP správná volba, protože agent potřebuje explicitně pracovat s kódem, symboly a markdown memories. Skill se hodí jako doplňková disciplína: připomenout agentovi, kdy číst Serenu, kdy spoléhat na Hindsight a kdy zapsat explicitní memory.

Instalace přes Docker Compose a první test

Tato část vychází z prakticky ověřeného lokálního nasazení: macOS, Docker Desktop, Ollama běžící na host systému, Hindsight API v Dockeru, Codex CLI a Serena MCP.

Oficiální integrace pro Codex používá jednoduchý bootstrap installer:

curl -fsSL https://hindsight.vectorize.io/get-codex | bash

Installer automaticky:

  • stáhne Codex integration package

  • vytvoří Codex hooky

  • vytvoří potřebné config soubory

  • nastaví recall a retain lifecycle pipeline

  • propojí Codex s Hindsight API

Instalátor typicky vytvoří:

~/.codex/

a do něj:

hooks/
settings.json
skills/

Podle verze integrace může vytvořit například:

~/.codex/hooks/hindsight_recall.py
~/.codex/hooks/hindsight_retain.py
~/.codex/hooks/session_start.py

nebo shell wrappery okolo těchto hooků.

1. Ověřte Ollama modely

Na host systému musí běžet Ollama:

ollama list

Pro lokální Hindsight potřebujete LLM model a embedding model. V ověřeném nasazení byly použity:

qwen3.6:35b-a3b-coding-nvfp4
nomic-embed-text-v2-moe:latest

LLM model se používá pro extraction, reranking, summarization a retain processing. Embedding model se používá pro semantic similarity a vector retrieval.

Důležitá poznámka: embedding model po vytvoření memory DB neměňte bez plánu na rebuild embeddings. Vektorový prostor jiného embedding modelu nemusí být kompatibilní se starými embeddings.

2. Docker Compose

Příklad docker-compose.yml:

services:
  hindsight:
    image: ghcr.io/vectorize-io/hindsight:latest
    container_name: hindsight
    restart: unless-stopped

    ports:
      - "8888:8888"
      - "9999:9999"

    environment:
      HINDSIGHT_API_LLM_PROVIDER: ollama
      HINDSIGHT_API_LLM_BASE_URL: http://host.docker.internal:11434/v1
      HINDSIGHT_API_LLM_MODEL: qwen3.6:35b-a3b-coding-nvfp4

      HINDSIGHT_API_EMBEDDING_PROVIDER: ollama
      HINDSIGHT_API_EMBEDDING_BASE_URL: http://host.docker.internal:11434
      HINDSIGHT_API_EMBEDDING_MODEL: nomic-embed-text-v2-moe:latest

    volumes:
      - ~/.hindsight-docker:/home/hindsight/.pg0

Proč host.docker.internal? Docker kontejner na macOS nevidí localhost host systému jako hostitelský stroj. Z pohledu kontejneru je Ollama dostupná přes:

host.docker.internal:11434

3. Start

docker compose up -d

4. Health check

curl http://localhost:8888/health

5. UI

open http://localhost:9999

6. Docker logy

docker logs -f hindsight

7. Ověření dostupnosti Ollama z kontejneru

docker exec -it hindsight curl http://host.docker.internal:11434/api/tags

Pokud toto nefunguje, Hindsight v kontejneru nebude umět volat lokální modely.

Codex config pro Hindsight

Ověřený ~/.hindsight/codex.json pro lokální Docker API:

{
  "hindsightApiUrl": "http://localhost:8888",

  "dynamicBankId": true,
  "dynamicBankGranularity": ["agent", "project"],

  "autoRecall": true,
  "autoRetain": true,

  "retainMode": "full-session",
  "retainToolCalls": true,

  "retainEveryNTurns": 1,

  "recallBudget": "mid",
  "recallMaxTokens": 1024,

  "debug": true
}

Pro běžné používání bych po testu zvážil změnu:

{
  "retainEveryNTurns": 10,
  "debug": false
}

Pro první test je ale retainEveryNTurns: 1 lepší, protože retain proběhne hned. Dodané poznámky výslovně potvrzují, že defaultní retainEveryNTurns: 10 může mást: uživatel čeká uloženou paměť, ale retain hook se ještě nespustil.

Ověření hooks v Codexu

Pokud hooky neběží, zkontrolujte Codex config. Oficiální dokumentace uvádí, že má být zapnuté:

[features]
codex_hooks = true

Instalační skript Hindsight pro Codex by to měl nastavit, ale při ručním troubleshooting stojí za to tento bod ověřit.

První použití a testování

Dobrý testovací prompt:

Zapamatuj si pro Hindsight test:
tento projekt používá bezpečnostní wrapper nad WordPress API
a agent nesmí volat WordPress API napřímo.

Po dokončení odpovědi by měl Stop hook spustit retain. V debug logu můžete hledat zprávy typu:

[Hindsight] Retaining to bank 'codex', doc 'sess-...', ...

Potom v nové session nebo novém promptu otestujte recall:

Co si pamatuješ o pravidlech pro WordPress API v tomto projektu?

Očekávaný výsledek: Codex by měl dostat z Hindsight memory o bezpečnostním wrapperu a zákazu přímých WordPress API calls. Ne proto, že to je v aktuální konverzaci, ale proto, že recall hook injectnul relevantní memory.

Co kontrolovat při neúspěchu

  1. Hindsight API běží?
curl http://localhost:8888/health
  1. Hindsight vidí Ollamu?
docker exec -it hindsight curl http://host.docker.internal:11434/api/tags
  1. Běží hooky?
[features]
codex_hooks = true
  1. Nečekáte retain moc brzy?
{
  "retainEveryNTurns": 1,
  "debug": true
}
  1. Máte správnou banku?

Pokud používáte dynamicBankId, spouštějte Codex ze stejné working directory, ve které jste memory vytvořili. Jiný projekt znamená jinou banku.

Privacy a bezpečnost

retainToolCalls: true je pro coding agenta lákavé, ale není zadarmo. Do paměti může uložit:

  • terminálové výstupy,
  • stack traces,
  • logy,
  • části diffů,
  • tool outputs,
  • MCP interaction history,
  • citlivé cesty,
  • náhodně vypsané tokeny nebo secrets.

Pro lokální setup na vlastním stroji je to často přijatelný kompromis. Pro týmové, cloudové nebo produkční prostředí bych nastavil přísnější pravidla:

{
  "retainToolCalls": false,
  "retainEveryNTurns": 10,
  "recallMaxTokens": 768
}

A hlavně: neukládat secrets do transcriptu. Memory systém není secret manager.

Co je Serena

Serena je nástroj, který dává AI agentovi IDE-like schopnosti přes MCP. Oficiální dokumentace ji popisuje jako sadu nástrojů pro coding workflows, kde LLM dělá samotnou orchestrace tool use. Serena se umí připojit k moderním AI klientům přes Model Context Protocol, včetně terminálových klientů typu Claude Code, Codex, OpenCode nebo Gemini CLI.

Nejstručnější popis:

Serena = semantic IDE cognition layer pro coding agenta

Agentovi pomáhá hlavně v těchto oblastech:

  • symbol-aware navigation,
  • reference lookup,
  • refactoring,
  • cross-file změny,
  • onboarding projektu,
  • práce s projektovými memories.

Serena je tedy blíž IDE než memory backendu. Umí agentovi dát schopnost bezpečněji měnit kód, protože agent nemusí dělat textovou chirurgii naslepo. Může najít symbol, reference, moduly a vztahy v codebase.

Serena memory management

Serena má vlastní memory systém. Je výrazně jednodušší než Hindsight, ale právě v tom je jeho síla.

Dokumentace říká, že memories jsou jednoduché, lidsky čitelné Markdown soubory, které může vytvářet, číst a editovat uživatel i agent. Serena rozlišuje:

  • project-specific memories uložené v .serena/memories/ v projektu,
  • global memories sdílené napříč projekty, defaultně v ~/.serena/memories/global/.

Agent při aktivaci projektu dostane seznam dostupných memories a má být instruován, aby je četl, když je to vhodné. Vhodnost odhaduje mimo jiné z názvu souboru. Memories lze organizovat do topiců pomocí /, například:

.serena/memories/modules/frontend.md
.serena/memories/security/wordpress-api-wrapper.md
.serena/memories/build/test-commands.md

Serena může mít také read-only patterns pro globální memory nebo ignored patterns pro archivované memories.

Serena memory je explicitní

Serena memory se zapisuje explicitně přes MCP tools typu:

write_memory
read_memory
list_memories
edit_memory

To znamená, že agent nebo uživatel rozhodne, co je dost důležité na zápis. Typická Serena memory je něco jako projektová mini-wiki:

# WordPress API wrapper

Projekt nesmí volat WordPress API napřímo. Všechny requesty musí jít přes bezpečnostní wrapper, který řeší validaci, retry politiku a audit log.

## Důsledky pro agenta

- Nepřidávat přímé HTTP klienty na WordPress endpointy.
- Před změnou wrapperu spustit integrační testy.
- Při novém endpointu doplnit validaci payloadu.

To je velmi dobře čitelné pro člověka. Dá se verzovat v gitu, reviewovat, ručně editovat, rozdělit do témat.

Serena vs Hindsight: rozdíly

Nejlepší mentální model:

Serena    = projektová wiki + semantic IDE tools
Hindsight = episodická operační paměť agenta

Nebo ještě kratší:

Serena    = explicitní znalost
Hindsight = implicitní zkušenost
Oblast Serena Hindsight
Integrace MCP tools Codex hooks / API / SDK
Typ paměti explicitní, kurátorovaná implicitní, automatická
Formát Markdown soubory strukturovaná memory v PostgreSQL
Čitelnost pro člověka vysoká nízká až střední přes UI/API
Retrieval agent volá tools hook injectuje relevantní memory
Ukládání write_memory retain() pipeline
Konsolidace ruční / agentem řízená observations na pozadí
Temporal reasoning omezené vestavěné v recall
Graph/entity vztahy primárně přes code intelligence memory graph/entities
Determinismus vyšší probabilistický retrieval + extraction
Nejlepší use case kanonická projektová znalost zkušenost z minulých sessions

Kdy použít Serenu

Serena je správná vrstva pro:

  • onboarding projektu,
  • pravidla práce v repozitáři,
  • build/test commands,
  • architekturu,
  • bezpečnostní zásady,
  • coding conventions,
  • modulové mapy,
  • explicitní rozhodnutí, která chce člověk číst a verzovat.

Příklad:

„Do Serena memory zapiš, že všechny publish workflow musí jít přes Temporal activity publishEntityActivity a nesmí zapisovat přímo do production DB.“

Kdy použít Hindsight

Hindsight je správná vrstva pro:

  • debugging continuity,
  • zkušenosti z minulých sessions,
  • tool orchestration memory,
  • implicitní pravidla z opakované práce,
  • temporal dotazy,
  • memory recall bez ručního zápisu,
  • konsolidované observations z více interakcí.

Příklad:

„Minule jsme zkoušeli tři cesty, proč worker padá. Která nakonec fungovala?“

Tohle se do projektové wiki často nezapíše. Ale pro agenta je to přesně zkušenost, která šetří čas.

Synergie: jak je používat společně

Serena a Hindsight se neduplikuji. Doplňují se.

Praktická topologie:

Codex CLI
 ├── Serena MCP
 │   ├── symbol navigation
 │   ├── reference lookup
 │   ├── refactoring tools
 │   └── explicit markdown memories
 │
 └── Hindsight hooks
     ├── UserPromptSubmit → recall
     ├── Stop → retain
     └── observations / episodic memory

Doporučené rozdělení odpovědnosti

Serena:

„Co je pravda o projektu a má být čitelné člověkem.“

Hindsight:

„Co agent zažil, pochopil, zkusil nebo se naučil během práce.“

Příklad společného workflow

  1. Uživatel vysvětlí pravidlo:
Tenhle projekt nesmí volat WordPress API napřímo. Vždy přes wrapper.
  1. Agent ho zapíše do Serena memory jako kanonické pravidlo:
.serena/memories/security/wordpress-api-wrapper.md

  1. Hindsight retain automaticky uloží celou session včetně toho, že pravidlo vzniklo při práci, jaký byl kontext a jaké tool calls kolem toho proběhly.

  2. Příště Codex při promptu dostane Hindsight recall:

Relevant memory: Project forbids direct WordPress API calls; use security wrapper.
  1. Pokud agent potřebuje víc, použije Serena MCP:
read_memory("security/wordpress-api-wrapper")

Výsledek: Hindsight připomene, že něco existuje. Serena drží kurátorovaný detail.

Praktická doporučení pro Codex

1. Zapněte dynamic banky

{
  "dynamicBankId": true,
  "dynamicBankGranularity": ["agent", "project"]
}

Bez toho riskujete míchání paměti mezi projekty.

2. Začněte s mid recall budgetem

{
  "recallBudget": "mid",
  "recallMaxTokens": 1024
}

Je to dobrý kompromis mezi rychlostí a užitečností.

3. Pro lokální coding workflow zvažte retainToolCalls

{
  "retainToolCalls": true
}

Dává agentovi operační paměť. Jen ji nepoužívejte bez rozmyslu v prostředí, kde se v terminálu objevují secrets.

4. Serenu používejte jako projektovou knowledge base

Do Serena memories patří to, co má mít podobu stabilní dokumentace:

  • architektura,
  • pravidla,
  • příkazy,
  • onboarding,
  • bezpečnostní omezení.

5. Hindsight nechte sbírat zkušenost

Do Hindsight se hodí:

  • co agent vyzkoušel,
  • co selhalo,
  • co fungovalo,
  • jaké tool workflow bylo úspěšné,
  • jak se měnila rozhodnutí v čase.

6. Občas paměť auditujte

Memory není bezúdržbová magie. U Hindsight sledujte šum a citlivá data. U Sereny udržujte markdown memories krátké, tematické a aktuální.

Slabiny a rizika

Hindsight přináší silnou automatizaci, ale tím i několik rizik.

Automatická paměť může ukládat šum

Pokud retain posílá příliš mnoho tool outputů, memory DB může bobtnat. Výsledkem je horší relevance a více práce při údržbě.

Extraction není stoprocentní

LLM-based fact extraction může něco pochopit špatně, vynechat důležitý detail nebo přehnaně zobecnit. Observations pomáhají, ale nejsou náhradou za lidsky kontrolovaná pravidla v Serena memory.

Retrieval je probabilistický

Recall může vrátit relevantní paměť, ale nemusí. Proto bych klíčové projektové zásady nenechával jen v Hindsight. Dejte je i do Serena memory, README, AGENTS.md nebo podobného explicitního zdroje.

Privacy

Největší praktické riziko je ukládání citlivých dat. Lokální self-hosted deployment s vlastním volume je bezpečnější než posílat všechno do cizího API, ale pořád platí: co se objeví v transcriptu, může skončit v memory.

Závěr

Hindsight a Serena řeší dva různé problémy coding agenta. Serena dává agentovi ruce a oči uvnitř codebase: symboly, reference, refaktoringy a explicitní markdown knowledge. Hindsight mu dává paměť zkušenosti: co se stalo v minulých sessions, co fungovalo, co selhalo, jaká pravidla se opakovaně potvrdila a jaké vztahy mezi fakty se časem vytvořily.

Nejlepší výsledek vzniká kombinací:

Serena pro kanonickou projektovou znalost.
Hindsight pro dlouhodobou operační zkušenost.
Codex hooky pro automatický recall/retain.
MCP pro explicitní práci s kódem a memories.
Skill pro disciplínu postupu.

Pokud bych měl vybrat jednu praktickou větu pro nasazení: kritická pravidla pište do Sereny, zkušenost nechte sbírat Hindsight a v Codexu zapněte hooky s per-project memory bankami.

Tohle není jen pohodlí. U větších projektů je to rozdíl mezi agentem, který pokaždé znovu objevuje stejnou mapu, a agentem, který si konečně začne pamatovat cesty, kterými už jednou prošel.

Zdroje

Tags #agentic AI #ai coding agents #ai infrastructure #AI-assisted development #codex cli #developer-tools #mcp #model context protocol #Ollama #RAG #retrieval augmented generation

Related posts