Agent-geheugen als bestandsformaat

Memoryfields: een eenvoudiger manier voor agent-geheugen

Veel benchmarks voor AI-modellen beginnen met een leeg contextvenster: de tabula rasa van AI. In zekere mate is dit logisch om de benchmarks eerlijk te houden. Maar echte agents zouden nooit met een leeg contextvenster moeten beginnen. Ze zouden moeten starten met zoveel mogelijk relevante informatie die voor de agent beschikbaar is. Je AI-agents zouden moeten beginnen met herinneringen.

Waarom bestaande systemen voor agent-geheugen niet lijken te werken

Veel huidige systemen voor agent-geheugen schieten tekort. Er zijn momenteel grofweg drie populaire soorten geheugensystemen, die elk op hun eigen manier tekortkomen:

  1. Systemen die je binden aan een specifieke 'harness': Deze zijn meestal geschreven door het laboratorium dat de harness verhuurt. Deze labs willen wanhopig overstappen van de (zeer competitieve) "API-business" naar de (veel lucratievere) "platform-business". Dit type systeem werkt meestal door informatie uit je gespreksgeschiedenis te minen, waardoor de meeste herinneringen over jou gaan, terwijl informatie over de wereld over het algemeen veel nuttiger is.
  2. Extreem complexe systemen: Sommige prominente systemen vereisen pgvector, een Neo4j-graafdatabase en een eigen LLM om alleen al te beslissen wat de moeite waard is om te onthouden. Deze complexiteit is niet alleen moeilijk te beheren, maar verwart ook de modellen. Bovendien schalen ze niet mee met de vooruitgang van de modellen.
  3. De "High Modernist"-variant: Deze systemen stellen zich een geïdealiseerde, rationalistische vorm van geheugen voor. Dit omvat onvermijdelijk een graaf en soms logische proposities. Dit type systeem stript systematisch informatie uit haar context, waardoor deze geïsoleerd en zinloos wordt voor de agent (en de gebruiker). Hoe nuttig is een simpele lijst met "gedestilleerde feiten" nu werkelijk?

Wat ze gemeen hebben, is dat ze geheugen behandelen als een proces. Maar geheugen — zeker voor een model — wordt veel beter gerepresenteerd als data.

Geheugen als dataformaat, niet als multi-stage pipeline

Brooks zei ooit:

"Laat me je stroomschema's zien en verberg je tabellen, en ik zal in mystificatie blijven. Laat me je tabellen zien, en ik heb meestal je stroomschema's niet nodig; die zullen overduidelijk zijn."

Hier is het draagbare geheugenbestandsformaat "memoryfield":

my-memories.memoryfield.zip

  • carbon-fibre-woks.md
  • finnish-bureaucracy-tips.md
  • [...] vele andere md-bestanden [...]
  • wec-2026-season-notes.md
  • nomic-embed-text-v1.5.sqlite3

Een memoryfield bestaat uit:

  • Markdown- "pagina's", met:
  • (optioneel) YAML-frontmatter en
  • (optioneel) een SQLite-vectorindex voor semantisch zoeken.

Agents werken het beste met bestanden. Hieronder volgt de uitleg waarom.

Ontwerpbesluit 1: Gebruik proza, geen chunks of "feiten"

De belangrijkste reden waarom RAG-pipelines (Retrieval-Augmented Generation) zo gecompliceerd kunnen zijn, is dat ze proberen een massa bestaande, door mensen geschreven documenten leesbaar te maken voor een AI-agent. Vaak zijn deze documenten lastig direct te lezen, bijvoorbeeld omdat het grote PDF's zijn.

Maar agent-herinneringen zijn geen gecompliceerde legacy-documenten. Een herinnering wordt op het moment van ontstaan direct gevormd door een AI-agent die volledig in staat is om proza te schrijven. Dat proza hoeft niet in stukken (chunks) te worden gehakt, verrijkt, dubbel samengevat of op andere mechanische wijze te worden verwerkt: laat de agent de herinnering direct schrijven in het favoriete formaat (wat Markdown is).

Een memoryfield-pagina ziet er als volgt uit:

---
title: Carbon Fibre Woks
created: '2026-03-01T09:00:00Z'
updated: '2026-08-22T14:30:00Z'
uuid: 6aa615f0-486f-48a7-a210-ba4f5ff18c8b
summary: Thermal properties of carbon fibre cookware
---
Carbon fibre woks conduct heat evenly, but...

De enige beperking is dat de pagina kort genoeg moet zijn om in een vector-embedding te passen: er is een zachte limiet van ongeveer 8kb (~2000 tokens). In de praktijk is dit een voordelige beperking; 8.000 tekens zijn ongeveer 1.300 woorden, wat overeenkomt met de lengte van een gemiddeld tijdschriftartikel. Voor meer details kunnen simpelweg meer pagina's worden toegevoegd.

Ontwerpbesluit 2: Semantische sprongen in plaats van graaf-navigatie

Een belangrijk referentiepunt waren de "Karpathy-wiki's", die georiënteerd zijn rond hyperlinked Markdown-bestanden (vergelijkbaar met Roam of Obsidian). Het idee was dat de agent door de "kennisgraaf" zou lopen om relevante pagina's te vinden.

In de praktijk is het laten navigeren van een AI-agent door een kennisgraaf traag, onbetrouwbaar en verwarrend. De traversal is traag omdat het model herhaaldelijk moet stoppen om seriële tool-calls te maken om opeenvolgende pagina's te lezen.

Het ruwe algoritme voor een agent die een kennisgraaf doorloopt:

  1. Lees wiki-voorpagina [tool call]
  2. Zoek relevante links
  3. Lees gelinkte pagina(s) [tool call]
  4. Zoek relevante links
  5. Beslis of er genoeg relevante informatie is gevonden
  6. Zo niet, ga terug naar stap 2

Als de relevante informatie $N$ stappen diep in de graaf zit, zijn $N+1$ tool-calls nodig. Dit is traag, aangezien het model moet pauzeren voor elke call die mogelijk 2-3 seconden duurt. Bovendien worden diep geneste kennisgrafen hierdoor zwaar gestraft.

Kennisgrafen zijn ook onbetrouwbaar, omdat de AI alleen kan bepalen of materiaal relevant is door naar de linktekst of de paginatitel te kijken. Dit dwingt de agent tot een soort "1990s-SEO-style" metadata-hacking om ervoor te zorgen dat elke titel accuraat is. Dit straft digressie, het noteren van zijdetails en impliciete kennis die vaak nuttig is in grotere tekstcorpora.

Daarnaast zijn kennisgrafen verwarrend omdat agents vaak door veel irrelevante informatie moeten spitten tijdens het navigeren. Dit introduceert ruis in het contextvenster, wat de kwaliteit van de output verlaagt.

Dit wordt opgelost door semantisch zoeken te gebruiken om direct naar alle relevante pagina's te springen (gebaseerd op de werkelijke inhoud, niet op metadata) en de agent alle relevante pagina's tegelijkertijd, parallel, te laten lezen. In een memoryfield zijn maximaal twee tool-calls nodig: één om te zoeken en één om parallel te lezen.

Ontwerpbesluit 3: Meer model, minder mechanisme

Systemen met een "hoog mechanisme" (met veel speciaal ontworpen API's of databases) dwingen agents om door een doolhof van interfaces te navigeren. Als de interface groot is, wordt er te veel openapi.json in het contextvenster geladen. Als de interface klein is, is deze beperkend.

Memoryfields zijn een "laag mechanisme"-systeem (slechts een bestandsformaat), waardoor agents meer vrijheid hebben om hun eigen toegangspatronen te verzinnen. Hoewel er ondersteunende tooling beschikbaar is, kunnen agents zelf bepalen hoe ze de data gebruiken. Voorbeelden hiervan zijn het gebruik van Perl voor find-and-replace over het hele corpus, of het plaatsen van inline CSV-bestanden in herinneringen die vervolgens met SQLite worden bevraagd.

Omdat het systeem "laag mechanisme" is, schaalt het mee met de vooruitgang van de modellen. Naarmate modellen beter worden, bedenken agents slimmere manieren om met data om te gaan. Ze zijn bijvoorbeeld verrassend goed in Bash, Markdown en SQLite.

Ontwerpbesluit 4: Open formaat, uitwisselbaar en transport-invariant

Naarmate een collectie herinneringen groeit, worden ze waardevol. Je wilt niet gebonden zijn aan een specifieke harness, model of agent. Er is een RFC-stijl specificatie geschreven voor het bestandsformaat om ambiguïteit te voorkomen en om te voorkomen dat het gebonden is aan een specifieke embedding-functie.

Het canonieke "archiefformaat" van een memoryfield is een zip-bestand, om data-uitwisseling zo eenvoudig mogelijk te maken. De specificatie is echter open voor andere vormen van opslag, zoals lokale bestanden, Amazon S3, GitHub of HTTP.

Aan de slag

De eenvoudigste manier om te beginnen is via de volgende tooling (vereist: ollama, uv en npx):

# 1. Pull the embedding model:
ollama pull nomic-embed-text

# 2. Install the CLI tool:
uv tool install git+https://github.com/calpaterson/memoryfield-tool

# 3. Install the skill:
npx skills add calpaterson/memoryfield-skill -g -y

Voor een demo-memoryfield kan soapstones.memoryfield.zip worden gebruikt. Dit bevat herinneringen over hoe agents toegang kunnen krijgen tot data (bijv. Reddit zoeken, Jina Reader of de MediaWiki API).

"Is dit niet gewoon RAG?" en andere veelvoorkomende bezwaren

Is dit niet gewoon RAG? "RAG" wordt tegenwoordig zeer breed geïnterpreteerd; zodra een agent data ophaalt, is er sprake van RAG. In die zin: ja. Maar de meeste technieken die gewoonlijk geassocieerd worden met een "RAG-systeem" ontbreken hier: er is geen chunking, geen re-ranking en geen hybride zoeken. Daarnaast schrijven de agents in dit systeem zelf de herinneringen, terwijl RAG-systemen vaak primair gericht zijn op lezen.

Is nomic-embed-text-v1.5 niet ouder dan twee jaar? Zijn er geen betere modellen? Embedding-modellen zijn minder groot en veranderen minder snel dan frontier-modellen. nomic-embed-text-v1.5 blijft een goede balans tussen compact en krachtig. Het is klein genoeg (270MB) en snel genoeg om op hardware zonder GPU te draaien. De specificatie staat overigens toe dat andere embeddings worden gebruikt.

Hoe kan ik beoordelen wat een goede herinnering is om op te slaan? Hoe voorkom ik dat mijn geheugen volloopt met onzin? Dit is een veelvoorkomende angst, maar geldt niet voor memoryfields. Irrelevant materiaal wordt simpelweg nooit naar boven gehaald door het semantische zoeken. Irrelevante herinneringen nemen ruimte in beslag, maar hinderen de agent niet. Voor het beste resultaat: voeg herinneringen royaal toe. Eén tip: herinneringen werken het best wanneer ze citaties bevatten, idealiter in de vorm van URL's.

Hoe zit het met beveiliging en "ignore previous instructions"? Je mag je contextvenster, inclusief herinneringen, niet delen met partijen die je niet vertrouwt. Een reden voor het statische zip-formaat is dat je memoryfields van anderen handmatig kunt controleren en vastpinnen (via sha256sum). Er is momenteel geen manier voor een agent om een "goede prompt" te onderscheiden van een "kwaadaardige prompt".

Data eerst

Samengevat is het proces als volgt:

  1. Schrijf een herinnering als Markdown.
  2. Embed deze en sla de vector op in SQLite.
  3. Gebruik semantisch zoeken om herinneringen terug te vinden.

Memoryfields zijn ongebruikelijk omdat ze een datastructuur definiëren en geen proces. Er is geen extractie-pipeline of achtergrondservice. De vectorindex is een verwijderbare cache, niet het systeem zelf.

Geheugen is data! Hoe minder vaste mechanieken we tussen de agent en die data plaatsen, des te beter de agent kan functioneren.