Geheugen via de API¶

Op deze pagina schrijf en lees je geheugenrecords met de API en geef je een beurt de geheugentools. Gebruik geheugen om afzonderlijke feiten tussen aanroepen te bewaren, zoals een klantvoorkeur of een eerder besluit. Gebruik kennis om documenten in te lezen en te doorzoeken. Een beheerder leest de records in Geheugen in de console.

Je sleutel heeft de capability memory nodig, en knowledge, waarvan memory afhangt. Maak een kennisindex aan om de records in op te slaan voordat je geheugen schrijft.

De capability memory configureren¶

Een beheerder zet deze velden op de memory-capability van de sleutel, in de console of via PATCH /tenants/{id}/keys/{id}; zie Capabilities per sleutel.

retrieval_tool en write_tool bepalen de twee geheugentools; injection bepaalt automatisch toevoegen.

Een record schrijven¶

curl -s -X POST "$CORE_URL/memory" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"index_id": "idx_8Bd3...", "type": "voorkeur",
         "text": "Heeft liever e-mail dan telefoon.",
         "metadata": {"klant": "acme"}, "confidence": 0.9}'

Een niet-beschikbare index geeft 404 -- ook een index die het beleid van je sleutel niet noemt: een record leeft in een index en is even afwezig als die index. Een schrijfactie die het sleutelbeleid weigert, geeft 403 en wordt vastgelegd in de auditgeschiedenis. Lees- en schrijfrechten staan los van elkaar. Een sleutel kan dus geheugen mogen doorzoeken zonder records te mogen toevoegen.

Een beheerder kan het geheugen van je organisatie ook lezen in de console, in het onderdeel Geheugen; wat daar getoond wordt bestrijkt elke index, en elke leesactie wordt vastgelegd in de auditgeschiedenis.

Geheugentools gebruiken¶

{
  "model": "<een model-id>",
  "tools": [{ "type": "tool", "name": "memory__idx_8Bd3...__search" }],
  "input": "Schrijf een follow-up voor Acme."
}

Elke index heeft twee tools, genoemd naar het id van de index zelf:

• memory__<index-id>__search — records vinden op vraag, met een optioneel types-filter en een optioneel aanmaakvenster, after en before (ISO 8601-momenten met een offset, zoals hierboven).
• memory__<index-id>__write — iets bewaren wat de beurt te weten kwam. Hij neemt alleen de typen die de opslag kent: de types van de extractieschakelaar als de opslag er een heeft, anders fact, preference, commitment en behaviour, nooit episode; een ander type wordt geweigerd en het model hoort welke wel mogen. De tool vertelt het model ook de datum van vandaag in de zone van de beurt -- de timezone van je verzoek, anders die van je organisatie, anders UTC -- zodat een vervaldatum die het uit "volgende vrijdag" afleidt op de juiste dag valt.

De configuratie memory van de sleutel bepaalt welke van de twee hij aangeboden kan krijgen; vragen om de andere geeft 400 op die tools[]-regel. GET /tools?source=memory geeft beide voor elke index die je hebt.

Wat de schrijftool antwoordt is een JSON-object, dezelfde tekst die het model leest en die een client ziet als toolresultaat-item op de thread (en als resultaat van de toolaanroep op de stream):

Om een opslag ongedaan te maken roep je DELETE /memory/{memory_id} aan met dat id. De sleutel heeft dezelfde memory-toegang nodig als voor de andere recordroutes, en een subject-token (of de header X-Core-Subject) verwijdert alleen de eigen records van die persoon. Een confirmed record verwijderen haalt het oudere record weg dat werd bevestigd, geen nieuw record; het record van een correctie verwijderen brengt het beëindigde record niet terug.

Zoekresultaten bevatten de confidence van elk record als geheel percentage, zoals confidence 82%, en contested als onderhoud het record als tegenstrijdig met een ander markeerde. Ze zijn een toolresultaat, dus het model krijgt te horen dat het gegevens zijn als je sleutel trust_envelope heeft. Geheugen dat tijdens een beurt wordt geschreven verwijst naar de berichtenreeks waaruit het is ontstaan. Zo kun je de herkomst van een onthouden feit bekijken.

Geheugen automatisch toevoegen¶

Als automatisch toevoegen is ingeschakeld in de configuratie memory, voegt Core passende records toe aan de context voordat het model begint. De selectie gebruikt type, metadata en een minimale betrouwbaarheidsscore. Het model hoeft geen zoektool aan te roepen. Het model leest elk toegevoegd record als gegevens, één regel JSON per record, en nooit als instructie, wie het record ook schreef.

Een beurt krijgt de records van de persoon voor wie hij is, en de gedeelde, nooit die van een ander. Een beurt die niemand noemt krijgt alleen de gedeelde records: noem de persoon met X-Core-Subject of user als de beurt van die persoon is.

De records staan in één blok onder labels die alleen Core schrijft, in deze volgorde: [commitments] (open toezeggingen, die van de persoon en de gedeelde, de eerstvolgende eerst, hoogstens commitments.inject_limit van de opslag), [behaviour] (de eigen regels van de persoon voor hoe de assistent moet handelen), [about_this_person], [organisation] (de gedeelde records) en, als de opslag erom vraagt, [past_sessions]. Een sectie zonder record heeft geen label. Elke regel is één JSON-object waarvan het eerste veld na type de confidence van het record is, als geheel percentage, bijvoorbeeld {"type":"preference","confidence":"82%","text":"prefers mornings"}; een record dat onderhoud als tegenstrijdig met een ander markeerde draagt ook "contested":true. Core voegt geen zin toe over wat je daarmee moet doen; zet een regel daarvoor in de instructies van je agent.

Een record van het type behaviour is een regel voor hoe de assistent voor één persoon moet handelen, zoals "antwoord in opsommingstekens", "antwoord in het Nederlands" of "vraag het eerst voordat je boekt"; wat ze graag heeft is een preference. Elke beurt voor haar krijgt haar eigen huidige regels, de nieuwste eerst, hoogstens tien, onder [behaviour], waar de beurt ook over gaat. Een beurt voor iemand anders, of voor niemand, krijgt ze nooit, en een gedeeld behaviour-record wordt nooit toegevoegd. Schrijf er een zoals elk record, met POST /memory of de schrijftool, of laat extractie ze vinden. De types, metadata en min_confidence van de sleutel beperken ze zoals elk record.

Elke sectie wordt apart gerangschikt op confidence, dan op hoe vaak het record is opgehaald, dan op id: ophalen beslist alleen bij gelijkstand en verhoogt nooit een confidence. Een opslag kan in plaats daarvan op relevantie rangschikken, met de instelling rank. injection.limit begrenst de records van de persoon en de gedeelde samen, niet de toezeggingen of de gedragsregels, en het tokenbudget begrenst het blok. Beide gelden en de strengste wint: het aantal stopt de wandeling, terwijl een record dat niet in het budget past wordt overgeslagen en het volgende wordt geprobeerd. De gedeelde records mogen bij een beurt voor een persoon hoogstens 40% van het budget gebruiken, zodat een grote gedeelde opslag haar eigen records niet verdringt. De trace van de beurt zegt welke grens records liet vallen: dropped_by_count en dropped_by_budget, en hoeveel tokens het blok kostte (estimated_tokens).

Een opslag kan een beurt ook eerdere sessies geven: de episodes die het dichtst bij het onderwerp van de beurt liggen, waarbij recentere hoger staan, hoogstens episodes_limit van de opslag. Ze staan als laatste, onder [past_sessions], zodat ze nooit de plaats van een toezegging of een feit innemen. Een beurt voor een persoon krijgt alleen haar eigen episodes, een beurt die niemand noemt alleen de gedeelde. Elke regel geeft de tijdspanne van de sessie en de thread en het eerste item om de berichten vanaf te lezen, bijvoorbeeld {"type":"episode","confidence":"100%","from":"2026-10-01T09:00:00+00:00","to":"2026-10-01T09:30:00+00:00","thread_id":"thr_01J…","first_item_id":"itm_01J…","text":"Planned the move to Delft."}. Het metadata-filter van de sleutel beperkt ze zoals elk record, en een sleutel die types noemt krijgt ze alleen als episode daarbij staat.

Elke assistent een eigen opslag geven¶

Eén sleutel kan meerdere assistenten bedienen, elk een agent, en elk kan uit een eigen opslag putten. Geef de agentversie een blok memory_injection, in dezelfde vorm als memory.injection van de sleutel:

{"name": "billing-desk", "model": "your-chat-model",
 "memory_injection": {"enabled": true, "index_id": "idx_billing", "types": ["fact", "preference"]}}

Een beurt op die agent gebruikt het blok van de agent in plaats van dat van de sleutel, in zijn geheel: de opslag, de types, het metadatafilter, de minimale betrouwbaarheid, de limiet en het budget. Er wordt niets uit het blok van de sleutel overgenomen, zodat je aan de agent ziet uit welke opslag een beurt put. Met "enabled": false krijgen de beurten van de agent geen toegevoegd geheugen, ook als de sleutel wel toevoegt. Een agent zonder memory_injection gebruikt het blok van de sleutel, zoals voorheen. De sleutel heeft nog steeds de capability memory nodig: zonder die wordt niets toegevoegd, wat de agent ook zegt. Bij het opslaan van de agent moet de opslag een index van je organisatie zijn die je eigen beleid noemt, anders wordt het opslaan geweigerd met 422 op memory_injection.index_id. Ook het beleid van de aanroepende sleutel moet de opslag van de agent noemen, anders krijgen de beurten niets, zonder foutmelding. Alles hierboven geldt voor de opslag van de agent zoals voor die van de sleutel: alleen de eigen records van de persoon en de gedeelde, de eigen instellingen van de opslag en het tokenbudget.

Instellingen per opslag¶

Een beheerder kan het budget voor één opslag verlagen en verdelen, bepalen hoe haar records worden gerangschikt en haar een beurt eerdere sessies laten geven, met PATCH /memory/stores/{index_id}, in de sectie injection. Het sturen van de sectie vervangt haar geheel.

Geheugen uit gesprekken halen¶

Een geheugenopslag kan zichzelf vullen uit de eigen gesprekken van je organisatie. Dat staat standaard uit. Zet het aan met PUT /memory/stores/{index_id}/extraction, met het chatmodel (model) dat de gesprekken leest, je eigen instructions over wat het onthouden waard is, de recordtypen (types) die het mag schrijven en hoe vaak het draait:

{"enabled": true, "model": "jouw-chatmodel",
 "types": ["fact", "preference", "commitment", "behaviour"], "schedule_minutes": 60}

Die vier typen zijn de standaard als je types weglaat.

Core leest dan elke berichtenreeks die een persoon noemt en minstens een half uur stil is, in vensters van berichten, en schrijft wat het vindt als records van de persoon van die reeks. Welke reeksen worden gelezen bepaalt het veld threads van de schakelaar: with_person (de standaard van een PUT die het weglaat) slaat een gesprek over dat niemand noemt, omdat dat de privéfeiten van één persoon als gedeelde records zou schrijven die elke collega krijgt; all leest elke reeks, en een GET van een eerder gezette schakelaar toont all. Een feit dat opnieuw genoemd wordt bevestigt het record dat je al hebt, en een correctie vervangt het record dat ze corrigeert; dat blijft leesbaar in de geschiedenis. Een reeks van een sleutel die persoonsgegevens verbergt, wordt bij het lezen opnieuw verborgen: het extractiemodel ziet dezelfde soort plaatshouders als het model van het gesprek zelf, of er toen iets te verbergen werd gevonden of niet, en het record bevat de echte waarden, zoals een herinnering die tijdens een gesprek wordt geschreven. Kunnen de persoonsgegevens niet verborgen worden, dan wordt dat venster niet gelezen en staat de fout bij de schakelaar. Core houdt op een reeks bij dat een verbergende sleutel erin schreef, vanaf de eerste zulke beurt nadat je installatie dit begon vast te leggen; vraag je operator wanneer dat was. Een oudere reeks wordt beoordeeld op wat ervan over is: een reeks waarin Core een waarde verborg wordt nooit gelezen, een reeks waarin niets werd gevonden wordt verborgen volgens de instellingen van haar sleutel zolang die sleutel bestaat, en ze wordt gelezen zoals ze geschreven is zodra die sleutel is verwijderd. Je sleutel heeft de capability threads nodig en een beleid dat geheugen schrijven toestaat; de tokens van het model worden gemeten zoals bij elke andere aanroep. GET op hetzelfde pad toont de schakelaar, de laatste run en hoeveel records hij schreef, bevestigde en verving. Stuur "enabled": false om te stoppen; wat al geschreven is blijft staan.

Dezelfde GET laat zien of de extractie werkt. windows telt de gespreksvensters die gelezen zijn (ready), die mislukt zijn (failed) en die nog wachten (queued, of parked bij je maandlimiet), en error_code noemt de meest voorkomende reden onder de mislukte vensters: bijvoorbeeld invalid_model_output als het model niet kan antwoorden in de vorm waar Core om vraagt. state is active als alles in orde is, off als de schakelaar uit staat, en zegt anders waarom er niets draait: author_unavailable (de sleutel die de schakelaar zette is ingetrokken of verlopen), model_unavailable (het model wordt je organisatie niet meer aangeboden) of objects_missing (de connector van de schakelaar is verwijderd, of de index draait een andere pipeline). Stuur de schakelaar opnieuw om author_unavailable of objects_missing te verhelpen; stuur hem bij model_unavailable met een model dat je organisatie wordt aangeboden, want hetzelfde model wordt geweigerd met 422 op model. De sleutel die de schakelaar stuurt wordt de sleutel waaronder de extractie draait, ook voor de vensters die al gekopieerd zijn. state controleert alleen deze drie dingen; een sleutel die nog bestaat maar threads of het recht om geheugen te schrijven kwijt is, laat state op active staan, en je ziet de fouten in de laatste run en in windows. Als je model, instructions of types wijzigt, leest Core de mislukte vensters nog een keer; vensters die al gelezen zijn blijven ongemoeid.

Het sturen van de schakelaar vereist threads, of je hem nu aan- of uitzet. Het lezen stopt ook als je de connector van de schakelaar of de index van de opslag verwijdert, en voor geen van beide is threads nodig. filters.key_ids beperkt het lezen tot gesprekken van de sleutels die je noemt, en filters.agent_ids tot gesprekken waarin een van de agents die je noemt antwoordde, zodat elke assistent een eigen opslag kan vullen; met beide moet een gesprek aan allebei voldoen. Een id dat geen agent van je organisatie is, wordt geweigerd met 422 wanneer je de extractie aanzet; een id dat de schakelaar al had, wordt niet opnieuw gecontroleerd. Zolang een schakelaar een agent noemt, wordt het verwijderen van die agent geweigerd met 409 met de opslag erbij; haal hem eerst uit de filters van de schakelaar. Een sleutel die is ingetrokken of verlopen wordt geaccepteerd, omdat de gesprekken ervan nog steeds van jou zijn; een id dat nooit een sleutel van je organisatie was, wordt geweigerd met 422 wanneer je de extractie aanzet. Core herkent een verwijderde sleutel aan het auditspoor van sleutels van je organisatie; een sleutel die langer geleden is verwijderd dan dat spoor wordt bewaard, geldt als nooit uitgegeven.

Elke sessie vastleggen¶

Met "episodes": true in de schakelaar schrijft extractie ook één record van het type episode voor elke sessie van een reeks die tot rust is gekomen: een reeks berichten die eindigt in een stille periode. Een episode is een korte weergave van wat er gebeurde: een text die zegt waar het over ging, wat er gedaan werd, hoe het afliep en wat openbleef, de tijdspanne die het beslaat, en de thread en het eerste en laatste bericht waaruit het is gemaakt, zodat een aanroeper door kan naar de berichten zelf. Elke episode zegt in haar structured-deel ook of de sessie goed ging: result is succeeded, failed of unknown, en result_basis zegt wat dat besliste -- hoe de persoon het opvatte als zij dat liet zien (reaction), anders een laatste antwoord dat mislukte of voortijdig stopte (records), anders de eigen lezing van het model of de persoon kreeg wat zij wilde (judge). Daarnaast noemt response_ids de antwoorden van de sessie, agent_id en agent_version de agent die haar uitvoerde, en tools elk toolresultaat met alleen zijn name en status. Een episode die eerder is geschreven heeft er geen van. Ze zegt ook, in één korte zin, wat de persoon van de sessie wilde (intent, weggelaten als het onduidelijk is), en haar text opent met die wens, zodat zoeken op wat iemand wilde de episode vindt. De episode is van de persoon van de reeks, of van de organisatie als de reeks niemand noemt, en is gegevens zoals elk geëxtraheerd record, met het vertrouwen van de berichten waarop ze rust. Ze kan ook zeggen welke tools de sessie gebruikte: het model leest tussen de berichten een korte passage van elke toolaanroep en elk resultaat, hoogstens 300 tekens van elk. Redenering en verzegelde berichten worden nooit gelezen.

De schakelaar telt pas vanaf het moment dat je hem zet: een sessie die eerder tot rust kwam wordt niet alsnog geschreven, dus zet hem op tijd aan. Hij gebruikt hetzelfde model en kost tokens zoals de rest van de extractie. Een episode kun je zelf niet schrijven: POST /memory en de schrijftool weigeren het type episode met 422. Een beurt krijgt episodes met episodes_limit van de opslag, en de lessen die een opslag kan trekken rusten erop. Met ook "lessons": true kan dezelfde lezing van een sessie ook noteren wat die leert; zie Lessen uit één sessie.

De sessies van een persoon haar assistent laten leren¶

De eigen sessies van een persoon kunnen haar assistent iets leren. Wanneer minstens min_episodes van haar episodes op dezelfde manier liepen, allemaal goed of allemaal slecht, vraagt de onderhoudsronde van de opslag het hulpmodel van je organisatie om één korte zin: een werkwijze die goed ging, of een valkuil om te vermijden. Die zin bewaart Core als geheugenrecord van het type lesson dat alleen van haar is: onvertrouwd, geschreven door het model, nooit gepromoveerd tot de organisatie en nooit aan een collega getoond. Wat naar het model gaat is gepseudonimiseerd, en voor een persoon wier regels het hulpmodel haar gesprekken niet laten lezen wordt niets verstuurd.

Een les staat in haar eigen beurten, onder [about_this_person] in het toegevoegde blok, zoals elk record van haar. Een sleutel waarvan types van het automatisch toevoegen leeg is krijgt haar, en een sleutel die lesson noemt ook; een sleutel die alleen andere types noemt niet. Een les wordt nooit eerst goedgekeurd: ze wordt geschreven en gebruikt.

Zet het per opslag aan in de sectie lessons met PATCH /memory/stores/{index_id}. Zoals de andere secties behalve promotion heeft ze alleen de capability memory nodig. Elke les is een gemeten modelaanroep, dus de sectie staat standaard uit. Ze draait ook alleen zolang maintenance.enabled van de opslag aan staat, en dat is zo tenzij je het onderhoud in de kaart Onderhoud van de opslag uitzette.

curl -s -X PATCH "$CORE_URL/memory/stores/$INDEX_ID" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"lessons": {"enabled": true}}'

Lessen uit één sessie¶

Ook één sessie kan iets leren. Stuur "lessons": true mee in de extractieschakelaar, naast "episodes": true (zonder episodes wordt de schakelaar geweigerd met 422), en het model dat de episode van een sessie schrijft mag in dezelfde aanroep ook tot drie lessen noteren, zonder extra modelaanroep: een werkwijze voor een taak die het hergebruiken waard is (workflow), of een fout en hoe die werd hersteld (pitfall). De meeste sessies leren niets (een beantwoorde vraag, een praatje) en dan wordt er geen geschreven. Elke les is een record van het type lesson van de persoon van de sessie, met het vertrouwen van de berichten waarop ze rust; een thread die niemand noemt krijgt geen les. De metadata zegt welke soort het is (lesson.kind) en wat oordeelde hoe de sessie liep (lesson.basis): reaction als de persoon liet zien dat het goed of slecht ging, model als het model op de uitkomst oordeelde. Een les die ze al heeft in dezelfde woorden wordt bevestigd in plaats van twee keer geschreven; een in bijna dezelfde woorden ook, maar alleen als de index van de opslag zijn records inbedt en beide lessen een embedding hebben. Het staat standaard uit.

Lessen komen in haar beurten zoals elk record van haar. Met rank van het automatisch toevoegen op relevance of blend komen de lessen die het dichtst bij het onderwerp van de beurt liggen eerst.

{"enabled": true, "model": "jouw-chatmodel", "episodes": true, "lessons": true}

Een persoonlijk feit van de organisatie maken¶

Een feit in het geheugen van één persoon kan van de organisatie zijn: "declaraties gaan voor de 25e naar financiën", gezegd in het gesprek van Jan, gaat over de organisatie en niet over Jan. De verbeteranalyses kunnen zo'n feit voorstellen als gedeeld record, als het geheugen van meerdere mensen het op dezelfde manier bevat of als het analysemodel het record van één persoon algemene kennis vindt. Een feit over een persoon, of een met een adres, telefoonnummer of link, wordt nooit voorgesteld. Zet het per opslag aan in de sectie promotion met PATCH /memory/stores/{index_id}:

Alleen een sleutel met management naast memory, of een beheerder in de console, mag deze sectie schrijven, en alleen als je organisatie de capability improvements heeft; anderen krijgen 403. De andere secties van een opslag vragen alleen memory. De analyses zelf zet je aan in de verbeterinstellingen.

curl -s -X PATCH "$CORE_URL/memory/stores/$INDEX_ID" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"promotion": {"enabled": true, "labels": {"audience": "everyone"}}}'

Een voorstel toepassen schrijft een nieuw gedeeld record van niemand in het bijzonder; het eigen record van de persoon blijft van haar. Wie een persoon wist, wist ook een voorstel dat alleen op haar record rust.

Afnemende confidence¶

De opgeslagen confidence blijft gelijk totdat je die bewerkt. Is afname ingesteld, dan krijgen lezers een effectieve waarde op basis van de tijd sinds de laatste wijziging:

effectief = confidence * 0.5 ** (leeftijd_in_dagen / halfwaardetijd_in_dagen)

De sleutelconfiguratie bepaalt per type een halfwaardetijd als de score moet afnemen. Typen zonder halfwaardetijd nemen niet af. GET /memory?min_confidence=0.5 filtert op de effectieve waarde. Elke PATCH laat de leeftijdsberekening opnieuw beginnen.

Je applicatie bepaalt wat er met records met een lage score gebeurt, bijvoorbeeld uitsluiten of de gebruiker om bevestiging vragen. Core berekent de score zonder die acties uit te voeren.