2026-02-14 · Bijgewerkt 2026-07-14

[!NOTE] Automatische vertaling Dit artikel is automatisch vertaald vanuit de oorspronkelijke Engelse versie.

AI Agent Memory Architectuur in 2026: Checkpoints, Vector Stores, en bestandgebaseerde geheugenopslag

Deel 2 van de serie ‘Engineering the Agentic Stack’

Een reasoning loop overleeft slechts één verzoek, tenzij zijn staat extern aan de worker wordt opgeslagen. Zonder agent memory kan de agent geen gestaakte actie hervatten, herstellen na een crash, of een voorkeur oproepen uit een eerdere session. Deel 1 De controlestroom is behandeld. In deze post wordt aangegeven in welke staat elke volgende stap zich moet bevinden en waar die staat gehost moet worden.

Ik zal de geheugenarchitectuur van het stap voor stap uitleggen. Marktanalist Agent, Het laat zien hoe checkpoints-verhitting, vector stores-koeling en bestandgebaseerde documentgeheugenoplossingen samenwerken bij langlopende agents-toepassingen. Daarna zal ik uitleggen wanneer PostgreSQL, Redis, Qdrant, key-value-opslagsystemen en gewone Markdown-bestanden het meest geschikt zijn.

TL;DR: Splits het geheugen op basis van het toegangspatroon. Hot memory vertegenwoordigt de threadniveau checkpoint toestand die wordt gebruikt voor pauzeren en hervatten. Cold memory bevat cross-session feiten in een key-value of vector store structuur. Document memory bewaart projectkennis in bestanden die gemakkelijk kunnen worden geraadpleegd. Begin met het probleem dat u moet oplossen en kies daarna pas het juiste opslagmechanisme. Plaats geen exacte feiten in een vage retrieval systeem, noch moet u een checkpoint behandelen als een auditlog.

Wat is AI agent memory?

AI agent memory vormt de state-laag die het mogelijk maakt voor een agent om voortgang van taken bij te houden, eerdere kennis op te halen en zijn kennis tussen verschillende uitvoeringen bij te werken. In productieomgevingen is dit geen enkele vector database. Het betreft eerder een combinatie van actieve checkpoints-, koude semantische of gestructureerde opslagmedia, en menselijk leesbare documentmemorie.

Begin niet met het geheugen, omdat dat intelligent klinkt. Begin met de voor de gebruiker zichtbare fouten: het verliezen van vooruitgang, het vergeten van een voorkeur, het herhalen van onderzoek, of het niet kunnen hergebruiken van een projectconventie.

Fouten die geheugen vereisen

Een stateless agent kan een geïsoleerde vraag beantwoorden, maar het vergeet de vraag zodra de oproep is afgerond. Dit ontwerp werkt niet wanneer het product enig van de volgende gedragingen nodig heeft:

• Pauzeren en hervatten: een gebruiker start een onderzoekstaak, sluit zijn laptop en komt de volgende dag terug. Zonder gecacheerde staat wordt de agent opnieuw vanaf nul gestart.
• Coherentie over meerdere gesprekken: tijdens een langdurig gesprek moet de agent onthouden welke hulpmiddelen hij heeft gebruikt, welke gegevens hij heeft verzameld en welke stappen van het plan hij heeft afgerond.
• Personalisatie: een terugkerende gebruiker verwacht dat de agent zijn risicotolerantie, voorkeur voor analysegraden en eerdere interacties kent.
• Human-in-the-loop (HITL): de agent stelt een rapport op en wacht op goedkeuring. De “wachten”-toestand moet behouden blijven bij herstarten van het proces.

In het Marktanalist Agent van Deel 1, De opdracht “Analyseer NVDA” genereert een plan, vijf tool calls, verzamelde gegevens en een voorlopig rapport. Wanneer de gebruiker reageert met “ziet er goed uit, maar voeg een concurrentieanalyse toe”, maakt een checkpoint-opslag het mogelijk voor de agent om de staat uit het vorige node te laden en de stap voor de concurrentieanalyse toe te voegen. Zonder gecacheerde staat kan het niet bepalen waarnaar “ziet er goed uit” verwijst en moet het opnieuw beginnen.

Long-term memory behandelt een ander geval. Als de gebruiker een week later terugkomt en vraagt: “Updateer mijn NVDA-analyse,” moet de agent mogelijk weer oproepen welke voorkeur er is voor conservatieve risicobeoordelingen en welk interessepunt er bestaat voor semiconductiestocks. Een op vectoren gebaseerde geheugenslagere kan deze feiten ophalen via sessions zonder ze opnieuw te hoeven vragen.

LangGraph splitst dit op basis van scope. Elke uitvoering van een graaf vindt plaats binnen een thread, oftewel één gesprek of taak. De gecacheerde staat binnen die thread wordt short-term memory genoemd. De staat die tussen threads wordt gedeeld, is long-term memory. De huidige context en de variabelen die zich binnen het model bevinden, vormen de werkmemorielaag die boven beide opslagvormen ligt.

Een taxonomie van AI agent memory

Voordat we overgaan tot de implementatie, is het nuttig om te classificeren wat agents moet onthouden. De CoALA framework (Sumers, Yao et al., 2023) vormt de standaardtaxonomie en is gebaseerd op cognitieve wetenschap. Ik heb het concept van geheugenscoping geïntroduceerd in mijn context engineering-post; Hier breid ik het uit tot zes categorieën:

Werkmemorie is wat de LLM op dit moment actief reasoning houdt: Python-variabelen in de huidige functie, de inhoud van de context window en tool call argumenten tijdens uitvoering. Het betreft de snelste en meest tijdelijke laag; er blijft niets bestaan na de huidige stap. De werkmemorie wordt begrensd door de context window van de model, waardoor het de feitelijke bottleneck vormt. Alles wat de agent op het moment van besluitvorming “weet”, moet hier passen, ongeacht of dit afkomstig is uit de checkpoint-opslag, een vectorquery of een bestandslezing. De andere lagen dienen ertoe om op het juiste moment de juiste informatie naar de werkmemorie te leveren.

Short-term memory is de checkpoint LangGraph die na elk node wordt geschreven. Episodische en semantische herinneringen blijven bestaan over meerdere threads heen. Documentherinnering slaat projectnotities, onderzoeksopsommingen en aangeleerde conventies op in bestanden die zowel mensen als agents kunnen raadplegen. Procedurale herinnering bevindt zich in systeem instructies en hulpprogramma definities, in plaats van per gebruiker te veranderen.

Voor de implementatie vallen deze categorieën samen in drie niveaus. Warme geheugenruimte bevat de huidige session. Koude geheugenruimte ondersteunt het oproepen van informatie over sessions. Documentgeheugen zorgt ervoor dat de opgeslagen projectkennis leesbaar en direct bewerkbaar blijft.

CoALA classificeert werkmemorie, episodische memorie, semantische memorie en procedurale memorie. De Geheugen in het tijdperk van de AI Agents-studie Het benadrukt vector stores en kennisgraphen, terwijl LangGraph documentatie biedt over checkpoints en diens Store-interface. Projectkennis die is opgeslagen in bestanden valt buiten deze taxonomieën, ondanks het feit dat Claude Code, Cursor, Windsurf en Devin allemaal persistente projectbestanden laden.

Hetzelfde opslagpatroon komt voor in andere domeinen. Voyager slaat herbruikbare spelvaardigheden op als codebibliotheken, teams bij ECR3 werken iteratief aan procedurale prompt documenten, en Agent Workflow Memory zorgt ervoor dat herbruikbare web workflows elementen worden gegenereerd op basis van succesvolle episodes. Bestanden maken deze kennis inspecteerbaar en versiebeheerbaar, zonder dat er een aparte embedding dienst nodig is.

Agent-Gemanageerde geheugen verschilt ook van een vast RAG pipeline qua degene die de schrijfoperatie uitvoert. De agent of diens harness kiest wat er opgeslagen, bijgewerkt of verwijderd moet worden, en beslist vervolgens wanneer dit weer opgehaald dient te worden.

De Een generatief artikel over Agents (Park et al., 2023) toonden tot hoever dit kan gaan: gesimuleerde agents-agenten slaan hun eigen herinneringen op, reflecteren erop en halen ze weer op. Hun geheugenstroom rangschikte de kandidaten op basis van recentheid, belangrijkheid en relevantie, een ontwerp dat nog steeds een nuttig referentiepunt vormt voor agent-geheugen retrieval.

Kortetermijn agent memory: de checkpoint-opslag

Elke keer dat een LangGraph-node wordt uitgevoerd, serialiseert de framework de volledige grafische toestand en slaat deze op in een checkpoint opslaglocatie. Dit vormt de basis voor pauzeren/hervatten, debugging met tijdsreisfuncties, en HITL workflows.

Een checkpoint bevat de grafische staat die nodig is om verder te gaan: de AgentState van Deel 1 (messages, identiteit, gebruikersprofiel, stappenplan, onderzoeksdata, uitvoeringsmodus), samen met LangGraph-metadata zoals het node dat deze gegevens heeft gegenereerd en diens checkpoint-ID. Na een HITL-interruption of procesherstart laadt de graaf de meest recent opgeslagen grens op en gaat hij verder naar het volgende node. Het systeem vervolgt niet vanaf een willekeurige Python-regel. Een checkpoint verschilt ook van een alleen-toevoegingslogboek voor evenementen of trace. Deel 5 het scheidt die runtime observability oppervlakken expliciet van elkaar.

Hoe checkpointing bij LangGraph werkt

LangGraph’s BaseCheckpointSaver het is een eenvoudige interface: put() schrijft een checkpoint, get_tuple() leest het meest recente bericht voor een thread. list() geeft de geschiedenis terug. Elke checkpoint heeft een sleutel die is gebaseerd op (thread_id, checkpoint_ns, checkpoint_id), waar thread_id identificeert het gesprek. checkpoint_ns handelt de namenruimte voor subgraphen af, en checkpoint_id het is een unieke versie.

De belangrijke beslissing is welk backend er achter geplaatst moet worden. PostgreSQL en Redis zijn twee veelgebruikte opties voor productieomgevingen.

PostgreSQL versus Redis

Een generieke database benchmarks kan de checkpoint prestaties niet voorspellen. Meet zelf de grootte van de geserialiseerde staat, de schrijffrequentie, de persistentie-instellingen en de gelijktijdigheid van je eigen grafstructuur.

PostgreSQL: de betrouwbare standaard

PostgreSQL vormt de veiligere standaard voor de meeste teams. Dankzij Checkpoints kunnen crashes worden overleefd, krijg je volledige transactiesemantiek, en de checkpoint-geschiedenis maakt tijdreisdebugging eenvoudig.

Van checkpointer_setup.py:

from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver

async def create_postgres_checkpointer(connection_string: str) -> AsyncPostgresSaver:
    """Create a PostgreSQL-backed checkpoint store.

    PostgreSQL gives us ACID guarantees — if a checkpoint write succeeds,
    the state is durable even if the process crashes immediately after.
    """
    checkpointer = AsyncPostgresSaver.from_conn_string(connection_string)

    # Create the checkpoint tables if they don't exist.
    # This is idempotent — safe to call on every startup.
    await checkpointer.setup()

    return checkpointer

# Usage: wire into the graph compilation
checkpointer = await create_postgres_checkpointer(
    "postgresql://user:pass@localhost:5432/agent_memory"
)
graph = create_graph(checkpointer=checkpointer)

# Every invoke/stream call now persists state automatically
config = {"configurable": {"thread_id": "user-123-session-1"}}
result = await graph.ainvoke({"messages": [HumanMessage(content="Analyze NVDA")]}, config)

# Resume later — loads the latest checkpoint for this thread
result = await graph.ainvoke({"messages": [HumanMessage(content="approved")]}, config)

De AsyncPostgresSaver maakt gebruik van langgraph-checkpoint-postgres package, dat drie tabellen genereert: checkpoints (de geserialiseerde toestand) checkpoint_blobs (grote binaire gegevens), en checkpoint_writes (Pending schrijfbewerkingen voor herstel na een crash). Het schema ondersteunt gelijktijdige toegang en maakt gebruik van advieslocks om schrijfconflicten te voorkomen.

Redis: wanneer latency de bottleneck is

Wanneer sub-milliseconde snelheden checkpoint latency cruciaal zijn (in real-time gesprekken agents en hoge-frequentie toolloops), is Redis de betere keuze.

Van checkpointer_setup.py:

from langgraph.checkpoint.redis.aio import AsyncRedisSaver

async def create_redis_checkpointer(redis_url: str) -> AsyncRedisSaver:
    """Create a Redis-backed checkpoint store.

    Redis stores checkpoints in memory for sub-millisecond access.
    Trade-off: less durable than PostgreSQL unless AOF is enabled.
    """
    checkpointer = AsyncRedisSaver.from_conn_string(redis_url)

    # Initialize Redis data structures
    await checkpointer.setup()

    return checkpointer

# Usage: same graph API, different backend
checkpointer = await create_redis_checkpointer("redis://localhost:6379")
graph = create_graph(checkpointer=checkpointer)

De AsyncRedisSaver van langgraph-checkpoint-redis opslaat checkpoints als JSON-documenten die worden geïndexeerd op basis van de thread-ID. De v0.1.0 herontwerp Meerdere zoekoperaties zijn vervangen door één enkele. JSON.GET Het maken van een aanroep vermindert latency aanzienlijk. Redis 8.0+ bevat standaard RedisJSON en RediSearch — er zijn geen extra modules nodig om te installeren.

Voor deployments met beperkte geheugencapaciteit, ShallowRedisSaver Het slaat slechts de meest recente checkpoint per thread op — er is geen historie, maar het RAM-verbruik blijft minimaal. Gebruik dit wanneer u pauzeren en hervatten nodig heeft, maar geen debuggen op basis van tijdsreizen.

Wanneer welke te gebruiken

Gebruik PostgreSQL wanneer:

• U heeft een volledig historisch overzicht van checkpoint nodig voor het oplossen van problemen door ‘tijdreizen’ of om resultaten reproduceerbaar te maken
• Duurzaamheid is onverhandelbaar (financiële diensten, gezondheidszorg)
• U gebruikt al PostgreSQL in uw technologische stack
• Uw agent voert lange taken uit waarbij het verliezen van de staat urenlang herberekenen betekent
• U wilt een geunificeerde gegevensopslag — PostgreSQL met pgvector kan dienen als één enkele backend voor checkpoints, long-term memory en vector search, waardoor uw infrastructuur wordt vereenvoudigd.

Gebruik Redis wanneer:

• Checkpoint latency vormen je bottleneck (realtime chat, streaming UX)
• Je bent bezig met het ontwikkelen van spraakbotsen — van STT naar LLM naar TTS pipelines toegang tot toestandsinformatie in sub-milliseconden
• U heeft horizontale schaling nodig over meerdere gelijktijdige threads
• Patronen met hoge paralleliteit waarbij meerdere agents dezelfde staat delen
• Kortlevende sessions waarbij het verliezen van een checkpoint hersteld kan worden
• U wilt semantische caching gebruiken om overbodige LLM aanroepen te verminderenRedis LangCache Het cacheert semantisch vergelijkbare zoekopdrachten om herhaalde aanroepen van LLM te voorkomen)

Andere opties: langgraph-checkpoint-sqlite Werkt voor lokale ontwikkeling en éénprocesomgevingen deployments. Voor stacks die specifiek zijn ontworpen voor AWS. langgraph-checkpoint-aws biedt een aan DynamoDBSaver Dankzij intelligente omgang met de payload blijven kleine checkpoints bestanden (<350 KB) in DynamoDB, terwijl grotere bestanden automatisch naar S3 worden overgezet. De serverless-prijsmodellen en het gebrek aan infrastructuur die beheerd moet worden, maken dit een aantrekkelijke optie voor deployments met wisselende belastingen.

Long-term memory: geheugenbehoud over sessions

Warm geheugen beherst het huidige gesprek. Maar wat gebeurt er met de gebruiker die volgende week terugkomt? Long-term memory slaat feiten, voorkeuren en interactiegeschiedenis op die behouden blijven tussen verschillende gesprekken.

LangGraph biedt een Store interface voor geheugencommunicatie tussen threads via deze BaseStore class. Elk geheugenitem is een (namespace, key) Koppel dit aan een waarde van JSON en optioneel een vector embedding. De namespace geeft doorgaans de gebruiker of organisatie weer. ("user", "user-123", "preferences").

Vectoropslag: semantische herinnering met Qdrant

Wanneer de agent ongestructureerde feiten moet oproepen (“Wat zei de gebruiker over zijn investeringsplan?”), zorgt de vector search voor semantische herinnering. In plaats van exacte sleutelzoeken, voert de agent zoekopdrachten uit op basis van betekenis.

Qdrant het is een speciaal ontworpen vector database die in Rust is geschreven en zich bezighoudt met embedding-opslag, indexeren (HNSW) en gefilterd zoeken. Ik heb HNSW en de bijbehorende afwegingen uitgebreid behandeld in mijn searchrankingpost. Qdrant biedt ook een MCP-server dat fungeert als een semantic memory-laag — handig wanneer uw agent framework het Model Context Protocol ondersteunt.

Van memory_store.py:

from qdrant_client import QdrantClient
from qdrant_client.models import PointStruct, Distance, VectorParams
from langchain_anthropic import ChatAnthropic
import hashlib
import json

class UserMemoryStore:
    """Long-term memory backed by Qdrant vector search.

    Stores user facts as embedded vectors for semantic retrieval.
    Each fact is a short natural-language statement about the user.
    """

    def __init__(self, qdrant_url: str, collection_name: str = "user_memory"):
        self.client = QdrantClient(url=qdrant_url)
        self.collection_name = collection_name
        self._ensure_collection()

    def _ensure_collection(self):
        """Create the collection if it doesn't exist."""
        collections = [c.name for c in self.client.get_collections().collections]
        if self.collection_name not in collections:
            self.client.create_collection(
                collection_name=self.collection_name,
                vectors_config=VectorParams(
                    size=1536,  # text-embedding-3-small dimensions
                    distance=Distance.COSINE,
                ),
            )

    def store_fact(self, user_id: str, fact: str, embedding: list[float]):
        """Store a user fact with its embedding."""
        point_id = hashlib.md5(f"{user_id}:{fact}".encode()).hexdigest()
        self.client.upsert(
            collection_name=self.collection_name,
            points=[PointStruct(
                id=point_id,
                vector=embedding,
                payload={"user_id": user_id, "fact": fact},
            )],
        )

    def recall(self, user_id: str, query_embedding: list[float], top_k: int = 5):
        """Retrieve the most relevant facts for a user given a query."""
        results = self.client.query_points(
            collection_name=self.collection_name,
            query=query_embedding,
            query_filter={"must": [{"key": "user_id", "match": {"value": user_id}}]},
            limit=top_k,
        )
        return [hit.payload["fact"] for hit in results.points]

De werkwijze is als volgt: (1) na elk gesprek haalt een LLM de belangrijkste feiten uit de interactie op (“de gebruiker heeft een hoge risicotolerantie”, “de gebruiker is geïnteresseerd in semiconductiestocks”), (2) deze feiten worden opgeslagen in Qdrant, (3) aan het begin van het volgende gesprek voert de agent een zoekopdracht uit in Qdrant met het nieuwe bericht van de gebruiker om relevante context op te halen.

Retrieval Scoring: verder dan cosinusgelijkenis

Ruwe cosinusgelijkenis vormt een uitgangspunt, maar productiesystemen voor geheugenbeheer hebben complexere retrieval nodig. Een generatief artikel over Agents (Park et al., 2023) introduceerden een scorefunctie die drie signalen met elkaar combineert:

• Recentheid: Regelgebaseerde afname van het gewicht, zodat recente herinneringen een hogere score krijgen. Een exponentiële afnamefunctie zorgt ervoor dat een feit van gisteren een hogere rang krijgt dan een vergelijkbaar feit van zes maanden geleden.
• Belangrijkheid: LLM-gerateerde significantie op een schaal van 1 tot 10. “Het portefeuil van de gebruiker is met 40% gedaald” scoort hoger dan “de gebruiker zei hallo.”
• Relevantie: Embedding cosinusgelijkenis tussen de zoekopdracht en het opgeslagen feit.

De uiteindelijke retrieval-score is een gewogen som: score = alpha * recency + beta * importance + gamma * relevance. Dit voorkomt dat verse, belangrijke feiten bedolven raken onder verouderde, maar semantisch vergelijkbare gegevens. Voor de Marktanalist Agent, De weight relevantie heeft de hoogste gewichting (0,5), gevolgd door de recentheid (0,3) en het belang (0,2), omdat de huidige zoekintentie van de gebruiker het meest doorslaggevend is. Dit zijn uitgangspunten weights die zijn aangepast aan het artikel over generatieve Agents modellen (waarin alle factoren gelijk werden gewogen); ik ontdekte dat het benadrukken van de relevantie beter werkt voor financiële analysevragen, maar de waarden zijn gebaseerd op intuïtie en niet empirisch geoptimaliseerd.

Alternatieven voor vector search

Vector search is krachtig, maar is niet altijd het meest geschikte hulpmiddel. Hier zijn situaties waarin alternatieven moeten worden gebruikt:

Key-value stores zijn zeer geschikt voor gestructureerde gegevens. Als uw long-term memory een gebruikersprofiel bevat — zoals risicotolerantie, investeringshorizon en favoriete sectoren — dan is het gebruik van een Redis hash of een PostgreSQL JSONB-colom eenvoudiger en sneller dan embedding en het doorvoeren van vectorquery’s. Gebruik vector search wanneer de gegevens ongestructureerd zijn en de retrieval-query’s verschillend geformuleerd worden.

De ingebouwde Store van LangGraph biedt een sleutel-waarde-interface gebaseerd op namenruimtes, met optioneel vector search. De BaseStore API is eenvoudig: put(), get(), search(), en delete() met hiërarchische namespace-scoping. Er zijn drie implementaties beschikbaar:

• InMemoryStore — voor ontwikkeling en testing (gegevens gaan verloren bij procesbeëindiging) PostgresStore — productiestore met persistente opslag en volledige SQL-querymogelijkheden AsyncRedisStore — gedeelde geheugentoegang tussen threads met vector search, ondersteuning voor TTL en filtering van metadata

De index De configuratie maakt het mogelijk om vector search te gebruiken voor opgeslagen items via een instelbare embedding model. Voor veel toepassingsgebieden is deze ingebouwde opslag voldoende, zodat er geen behoefte is aan een speciale vector database.

from langgraph.store.memory import InMemoryStore

# Create a store with vector search enabled
store = InMemoryStore(
    index={
        "dims": 1536,
        "embed": my_embedding_function,  # e.g., OpenAI text-embedding-3-small
    }
)

# Store a user preference (namespace scopes to user)
await store.aput(
    namespace=("user", "user-123", "preferences"),
    key="risk-profile",
    value={"risk_tolerance": "high", "horizon": "long-term"},
)

# Semantic search across user's memories
results = await store.asearch(
    namespace=("user", "user-123"),
    query="What is their investment style?",
    limit=5,
)

Het kiezen van een long-term memory-strategie

Begin met key-value wanneer je geheugen gestructureerd en duidelijk gedefinieerd is (gebruikersprofielen, instellingen, genoemde entiteiten). Voeg vector search toe wanneer je semantische retrieval nodig hebt voor ongestructureerde feiten of wanneer de formulering van de vraag onvoorspelbaar varieert.

Kennisgraphen zijn van waarde wanneer de relaties tussen entiteiten belangrijk zijn, bijvoorbeeld: “Welke bedrijven over welke gebruiker werd gevraagd en zijn die concurrenten van NVDA?” Het meest interessante recente project op dit gebied is Graphiti (by Zep), die een tijdsbewust kennisnetwerk bouwt dat bijhoudt wanneer feiten waar waren, en niet alleen wat waar was. Elke kant van het netwerk bevat geldigheidsintervallen, zodat een wijziging in de risicotolerantie van de gebruiker de oude waarde ongeldig maakt in plaats van deze stilletjes te overschrijven. Graphiti rapporteert Een nauwkeurigheid van 94,8% op de DMR benchmark, En diens bi-temporele model-oplossing lost het probleem van verouderde geheugeninformatie op de datalayer op.

Het probleem ligt op operationeel gebied. Het draaien van een grafdatabase is niet eenvoudig, en voor de meeste agent toepassingen volstaat vector search met filteren op metadata om dezelfde functionaliteit te bereiken met minder infrastructuur.

Gemanageerde geheugen frameworks zoals Mem0 en Letta (Vroeger bekend als MemGPT) zorgt deze oplossing voor de extractie, consolidatie en retrieval pipeline voor u. De aanpak van Mem0 valt op: een LLM haalt potentiële geheugeninformaties tevoorschijn, een beslissingsmechanisme vergelijkt elk nieuw feit met de bestaande elementen in de vector store, en een verwerkingsmodule beslist of deze informatie moet worden toegevoegd, bijgewerkt of verwijderd, waardoor de geheugenshop coherent en zonder redundantie blijft. Letta kiest voor een benadering die is gebaseerd op besturingssystemen: agents beheren ze hun eigen context window met behulp van hulpmiddelen voor geheugenbeheer, waarbij gegevens autonoom worden verplaatst tussen “core memory” (binnen het contextuele kader) en “archival memory” (buiten het contextuele kader). Beide opties zijn de moeite waard om te overwegen als u een snellere tijd tot productie wilt bereiken en geen volledige controle over de geheugen pipeline nodig heeft.

Documentgeheugen: de archiefkast van de agent

Bestand gebaseerde geheugenoplossingen worden vaker toegepast dan dat ze volledig zijn opgenomen in de hierboven genoemde classificaties van geheugen. In een door een leverancier uitgevoerde LoCoMo-evaluatie, Letta heeft verslag uitgebracht 74,0% voor de benadering die het gebruikt voor zijn bestandsstelsel. Houd dit resultaat binnen de voorwaarden van model, benchmark en harness, maar het operationele voordeel is gemakkelijk waarneembaar: ontwikkelaars kunnen de opgeslagen kennis direct lezen, bewerken en vergelijken.

Lange context windows maken het mogelijk om voor sommige projectdocumenten gehele bestanden te lezen. Gedeeltelijk verwerkte retrieval zijn nog steeds geschikt voor grote corpora, maar een kort bestand met conventies of overdrachtsinformatie kan vaak direct worden geladen. De keuze hangt af van de grootte van het document, de retrieval nauwkeurigheid, de beschikbare context en de frequentie waarmee mensen de inhoud moeten controleren of bewerken.

Vector stores en key-value backends werken uitstekend voor semantische herinnering en gestructureerde zoekopdrachten. Er bestaat echter nog een derde categorie van agent kennis die door beide niet op een efficiënte manier kan worden verwerkt: opgebouwde projectcontext, oftewel de conventies, onderzoeksnotities en beslissingen die door de agent gedurende het hele sessions proces nodig zijn, en die baat hebben bij een menselijke leesbaarheid en versiebeheer.

Dit is documentmemory: de agent leest en schrijft gestructureerde bestanden (Markdown, JSON, YAML) naar een bekende map. Geen embeddings, geen database, geen infrastructuur. Alleen bestanden op de schijf die zowel de agent als de ontwikkelaar kunnen gebruiken. cat, grep, git diffen bewerken met de hand.

Waarom bestanden?

Voor langlevende agent workflows is het meest effectieve patroon dat ik heb gezien geen vector database. Het gaat om een goed georganiseerde map met notities. Overweeg wat er gebeurt wanneer een coderende agent wekenlang aan een project werkt:

• Het leert dat het project Pydantic v2 gebruikt, en niet v1
• Het ontdekt dat de tests moeten worden uitgevoerd met pytest -x --tb=short
• Het verzamelt kennis over de architectuur van de codebase
• Het leert de voorkeuren van de ontwikkelaar (“gebruik altijd”) pathlib, nooit os.path”)

Deze feiten zijn te gestructureerd voor vector search (er is sprake van exacte herinnering, geen vage gelijkenis), en te talrijk voor een sleutel-waardeopslag (ze vormen onderling verbonden documenten in plaats van geïsoleerde feiten). Bovendien zijn dit feiten die de ontwikkelaar direct wil zien en bewerken. Als de agent iets verkeerd leert, opent men gewoon het bestand om het te corrigeren.

Dit is hoe Claude Code’s CLAUDE.md en .claude/ Werken met mappen. De agent leest op projectniveau CLAUDE.md bestanden voor conventies en instructies, en schrijft naar ~/.claude/MEMORY.md voor kruisbestuiving van session-kennis. De bestanden zijn gewone Markdown-bestanden: je leest ze, bewerkt ze, commit ze naar Git en deelt ze met je team. Cursor’s .cursorrules en Windsurfen .windsurfrules hanteer hetzelfde patroon: tekstbestanden die agent bij het opstarten laadt om de projectcontext te verkrijgen.

Implementatie van een geheugenopslag voor bestanden

De implementatie is opzettelijk eenvoudig. De agent ondersteunt vier operaties: een document schrijven, een document lezen, een lijst maken van beschikbare documenten, en zoeken in documenten op basis van trefwoorden.

Van file_memory.py:

from pathlib import Path
import json
import fnmatch

class FileMemory:
    """Document memory backed by the local filesystem.

    Stores agent knowledge as human-readable files organized by topic.
    No embeddings, no database — just files that both the agent and
    the developer can read, edit, and version-control.
    """

    def __init__(self, base_dir: str | Path):
        self.base_dir = Path(base_dir)
        self.base_dir.mkdir(parents=True, exist_ok=True)

    def write_doc(self, path: str, content: str, metadata: dict | None = None):
        """Write or overwrite a document at the given path.

        Paths are relative to base_dir. Directories are created automatically.
        Metadata (if provided) is stored as a JSON sidecar file.
        """
        full_path = self.base_dir / path
        full_path.parent.mkdir(parents=True, exist_ok=True)
        full_path.write_text(content, encoding="utf-8")

        if metadata:
            meta_path = full_path.with_suffix(full_path.suffix + ".meta")
            meta_path.write_text(json.dumps(metadata, indent=2), encoding="utf-8")

    def read_doc(self, path: str) -> str | None:
        """Read a document by path. Returns None if not found."""
        full_path = self.base_dir / path
        if full_path.exists():
            return full_path.read_text(encoding="utf-8")
        return None

    def list_docs(self, pattern: str = "**/*") -> list[str]:
        """List documents matching a glob pattern."""
        return [
            str(p.relative_to(self.base_dir))
            for p in self.base_dir.glob(pattern)
            if p.is_file() and not p.name.endswith(".meta")
        ]

    def search_docs(self, query: str, pattern: str = "**/*.md") -> list[dict]:
        """Search documents by keyword. Returns matching files with context.

        This is intentionally simple — grep-style keyword search.
        For semantic search, use a vector store instead.

        NOTE: This is a sketch for demonstration. A simple substring check
        won't scale beyond a few hundred documents. For production with 500+
        documents, use TF-IDF/BM25 scoring (e.g., rank_bm25) or a full-text
        search backend (PostgreSQL GIN index, Elasticsearch).
        """
        results = []
        for path in self.base_dir.glob(pattern):
            if not path.is_file() or path.name.endswith(".meta"):
                continue
            content = path.read_text(encoding="utf-8")
            if query.lower() in content.lower():
                # Return the paragraph containing the match for context
                for paragraph in content.split("\n\n"):
                    if query.lower() in paragraph.lower():
                        results.append({
                            "path": str(path.relative_to(self.base_dir)),
                            "match": paragraph.strip()[:500],
                        })
        return results

Mappenstructuur

De meeste waarde van het documentgeheugen komt voort uit de manier waarop de directory is georganiseerd. Hier is de structuur die ik gebruik voor de Marktanalist Agent:

.agent-memory/
    README.md                  # What this directory is, for human readers
    user-profiles/
        user-123.md            # Preferences, history, risk profile
        user-456.md
    research/
        NVDA-2026-02.md        # Research notes from recent analysis
        TSLA-2026-01.md
    conventions/
        analysis-format.md     # How to structure analysis reports
        data-sources.md        # Preferred data sources and API patterns
    learnings/
        common-errors.md       # Mistakes the agent has learned to avoid
        tool-patterns.md       # Effective tool call sequences

Elk bestand is in Markdown-formaat. Het doel van elk bestand is duidelijk af te leiden uit de bestandsnaam. Je kunt git diff het hele geheugendirectory om te zien wat de agent heeft geleerd tijdens een session. git revert Een slechte leercurve, of kopieer de map naar een ander project. Probeer een van deze stappen uit te voeren met een Qdrant-collectie.

Wanneer je documentgeheugen, vectoren of key-value moet gebruiken

De drie geheugens backends hebben verschillende toegangspatronen:

Gebruik documentgeheugen wanneer:

• De agent verzamelt projectkennis gedurende meerdere sessions
• Ontwikkelaars moeten kunnen controleren, wijzigen of negeren wat de agent “weet”
• De kennis is gestructureerd als documenten (notities, samenvattingen, conventies) in plaats van geïsoleerde feiten
• U wilt een op git gebaseerde versiebeheersing voor agent memory
• Geen infrastructuur is een strikte vereiste

Gebruik vector stores wanneer:

• U heeft behoefte aan vage semantische retrieval (“herinneringen vinden die verband houden met X”)
• De formulering van de zoekopdracht varieert onvoorspelbaar
• U beschikt over duizenden tot miljoenen individuele feiten

Gebruik key-value-opslag wanneer:

• U heeft nauwkeurige, snelle zoekopdrachten nodig voor gestructureerde gegevens (gebruikersprofielen, instellingen)
• Het dataschema is goed gedefinieerd

In de praktijk combineren productieomgevingen agents vaak alle drie. Marktanalist Agent Er wordt PostgreSQL checkpoints gebruikt voor het opslaan van tijdelijke gegevens in geheugen, Qdrant voor het terugvinden van semantische gebruikersfacten, en een op bestanden gebaseerde documentopslag voor projectconventies en onderzoeksnotities.

Voorbeelden uit de praktijk

Dit patroon komt al veel voor in AI coderingsassistenten:

• Claude Code leest CLAUDE.md bestanden uit de projectwortel en bovenliggende mappen, en schrijft naar ~/.claude/MEMORY.md voor kruisbestudering van session-resultaten. Het hele geheugensysteem bestaat uit gewone Markdown-bestanden die je samen met je code committ.
• Cursor laadt zich op .cursorrules Bestanden voor instructies die specifiek zijn voor het project agent: coderingsconventies, framework-voorkeuren en architectonische beslissingen.
• Windsurf maakt gebruik van .windsurfrules bestanden plus een memories/ de map waarin de agent de geleerde patronen uit uw codebase opslaat.
• Anthropic’s geheugenhulpmiddel voor de Claude API biedt create_memory, read_memory, update_memory, en delete_memory De operaties worden aan de kant van de client uitgevoerd. Uw applicatie bepaalt waar de bestanden daadwerkelijk worden opgeslagen (lokaal schijf, S3, database).

De gemeenschappelijke factor: ze bewaren allemaal agent-kennis als door mensen leesbare tekstbestanden, waarbij er expliciete lees-/schrijfoperaties worden uitgevoerd. Er is geen embeddings. Er is ook geen vectorinfrastructuur. De agent bepaalt wat er wordt opgeslagen, de ontwikkelaar kan alles bekijken en bewerken, en het hele systeem past in een git diff.

Verder dan coderingsassistenten

Het documentgeheugen is niet beperkt tot coderen agents. Dit patroon komt voor in zeer uiteenlopende agent domeinen:

• Open-worldspel agents: Voyager (Wang et al., 2023) ontwikkelen een persistente vaardigheidsbibliotheek met geverifieerde JavaScript-programma’s die een Minecraft agent gedurende de tijd verzamelt. Hierdoor worden 3,3 keer meer unieke elementen opgeslagen en worden mijlpalen 15,3 keer sneller bereikt dan bij de referentiestandaarden. Vaardigheden kunnen worden overgedragen naar nieuwe werelden zonder dat opnieuw getraind hoeft te worden. JARVIS-1 Dit wordt uitgebreid met een multimodale geheugenstructuur die tekstuele plannen en visuele observaties combineert, waardoor de succesratio bij de moeilijkste taken tot 5 keer stijgt.

  Een belangrijk onderscheid hier is dat skill-bibliotheken bestaan uit uitvoerbaar geheugen (importeerde en uitgevoerde codebestanden), terwijl het documentgeheugen in coderingsassistenten declaratief is (Markdown die wordt ingevoegd in prompts). De manieren waarop fouten optreden verschillen: slechte uitvoerbare code zorgt voor crashes in de agent, terwijl slecht declaratief tekst leidt tot reasoning-fouten. Het opslagpatroon en de operationele voordelen (zoals mogelijkheid tot debuggen en versiebeheer) blijven echter hetzelfde.

• Automatisering voor enterprise workflow: De ECR3-wedstrijd De winnaars maakten gebruik van documentgeheugen voor iteratieve prompt verbeteringen. De Analyzer en Versioner agents van één van de winnende teams werkten zich door 80 prompt versies heen die als procedurele documenten waren opgeslagen. Een ander topteam ontwikkelde meer dan 20 verrijkmingsmodules als procedureel kennismateriaal in documentvorm. LEGOMem (2025) formuleert dit als een modulaire geheugenstructuur framework voor multi-agent-systemen, waarbij gespecialiseerde geheugentypen (sensorisch, kortetermijn en langetermijn) worden gebruikt die agents dienen als bouwstenen voor samenstellingen.

• Webautomatisering: Agent Workflow Geheugen (Wang et al., 2024) stelt dat web agents in staat is om herbruikbare workflows-modellen te genereren op basis van succesvolle gevallen, waardoor de succesratio op WebArena met 51% verbetert. SkillWeaver (2025) gaat nog een stap verder: agents zorgt er namelijk voor dat herbruikbare API hulpmiddelen worden gecreëerd op basis van exploratie, waardoor de succesratio met 31,8% stijgt. De verworven vaardigheden zijn bovendien overdraagbaar naar zwakkere models systemen (een verbetering van 54,3%), zodat het opgeslagen geheugen van een krachtiger agent kan bijdragen aan een minder krachtig systeem.

• Klantensupport: Gartner voorspelt Dat AI agents tot 2029 op autonome manier 80% van de meest voorkomende klantenserviceproblemen zal oplossen. Deze agents verwijzen naar standaardwerkprocedures, handleidingen en klantgeschiedenissen, die allemaal vormen zijn van documentgeheugen.

De MemAgents-workshop bij ICLR 2026 Een teken dat de onderzoeksgemeenschap bijblijft met wat praktijkspecialisten al hebben ontwikkeld, is duidelijk het feit dat documentgeheugen allang zijn oorsprong als coderingsassistent heeft overstegen.

Vaardigheden maken gebruik van documenten om procedurele instructies te pakketteren. Agent Vaardigheidsstandaard slaat die instructies op SKILL.md Bestanden met YAML frontmatter en een Markdown-lichaam. Dit doet denken aan documentgeheugen op het opslagniveau, maar de functie verschilt: een skill vertelt de agent hoe een bepaald type werk uitgevoerd moet worden, terwijl geheugen feiten registreert die zijn opgedaan uit een project of een eerdere uitvoering. Deel 3 hij dekt die onderscheiding vanuit het perspectief van het hulpprogramma.

MCP (Model Contextprotocol) gaat in dezelfde richting: de definities van tools zijn JSON Schema-bestanden die door elke agent kunnen worden ontdekt en opgeroepen. Het protocol beschikt over 97 miljoen maandelijkse SDK downloads Het wordt ondersteund door OpenAI, Google, Microsoft en AWS. MCP heeft geen specifieke relatie met programmeren. Dezelfde servers maken verbinding tussen agents en databases, interne APIs-infrastructuur en bedrijfskritische systemen.

Beide wijzen op hetzelfde patroon: procedurele kennis die is opgeslagen als door schema’s gereguleerde documenten, met expliciete lees-/schrijfoperaties. MCP, die nu wordt beheerst door de Agentic AI Fundament, Dit is het dichtstbijzijnde equivalent van een interoperabiliteitsstandaard binnen het agent-ecosysteem.

Schalen van het documentgeheugen voor productieomgevingen

De hierboven beschreven bestandgebaseerde implementatie werkt goed voor laptops van één ontwikkelaar en voor kleine schaalverhoudingen van deployments. Voor productieomgevingen met meerdere gebruikers en duizenden documenten is een geheel andere architectuur vereist.

Het beperkte bestandslimiet voor één node wordt duidelijk zodra men ermee werkt: horizontaal schalen van bestandsin/uitvoer is niet mogelijk, gelijktijdige schrijfbewerkingen vereisen locking, en het beheren van rechten voor meerdere gebruikers is tijdrovend. In productieomgevingen is een back-endopslag nodig die concurrency, zoekfuncties en multi-tenancy op de juiste manier kan verwerken.

Drie veelgebruikte benaderingen:

Benadering A: hybride versie met een dunne databaselaag

Bewaar de bestanden voor het maken van inhoud (ontwikkelaars bewerken Markdown lokaal), maar serveer ze vanuit een database op runtime. Op deployment worden de bestanden gesynchroniseerd met PostgreSQL-rows. De agent leest vanuit de database, en niet vanaf de schijf. Dit biedt u:

• Ontwikkelaarsterreologie (bewerken van Markdown, commitpen naar git)
• Prestaties van productiequery’s (lezen uit geïndexeerde databases)
• Schone scheiding tussen het maken van inhoud en serving

Benadering B: objectopslag + vectorindex sidecar

Documenten worden in S3/GCS opgeslagen als objecten, samen met een Qdrant-collectie die hun embeddings indekt. De agent vraagt Qdrant om de relevante document-ID’s op en haalt vervolgens de inhoud op uit de objectopslag. Dit biedt mogelijkheden voor horizontale schaling en ondersteunt semantic search, maar zorgt ook voor meer complexiteit: er moeten twee systemen worden beheerd, een embedding pipeline moet in stand worden gehouden, en er moet rekening worden gehouden met eventuele inconsistenties tussen de opslag en de index.

Benadering C: gestructureerde documentopslag met PostgreSQL (aanbevolen)

Sla documenten op als PostgreSQL JSONB-regels met full-textzoekfunctie (GIN-index) en optioneel vectorgebaseerd zoeken embeddings (pgvector). Hierdoor beschik je over een hybride zoekmogelijkheid (op woordniveau + semantisch), ACID-transacties, en één enkel besturingssysteem.

Een schets van Benadering C:

from typing import Optional
import asyncpg

class ProductionDocumentMemory:
    """PostgreSQL-backed document memory with hybrid search.

    Schema:
        CREATE TABLE documents (
            id SERIAL PRIMARY KEY,
            tenant_id TEXT NOT NULL,
            path TEXT NOT NULL,
            content TEXT NOT NULL,
            metadata JSONB,
            embedding vector(1536),  -- pgvector extension
            ts_vector tsvector GENERATED ALWAYS AS (to_tsvector('english', content)) STORED,
            created_at TIMESTAMPTZ DEFAULT NOW(),
            UNIQUE(tenant_id, path)
        );
        CREATE INDEX ON documents USING GIN(ts_vector);
        CREATE INDEX ON documents USING ivfflat(embedding vector_cosine_ops);
    """

    def __init__(self, pool: asyncpg.Pool):
        self.pool = pool

    async def write(
        self,
        tenant_id: str,
        path: str,
        content: str,
        metadata: Optional[dict] = None,
        embedding: Optional[list[float]] = None,
    ):
        """Write or update a document."""
        async with self.pool.acquire() as conn:
            await conn.execute(
                """
                INSERT INTO documents (tenant_id, path, content, metadata, embedding)
                VALUES ($1, $2, $3, $4, $5)
                ON CONFLICT (tenant_id, path) DO UPDATE
                SET content = EXCLUDED.content,
                    metadata = EXCLUDED.metadata,
                    embedding = EXCLUDED.embedding
                """,
                tenant_id, path, content, metadata, embedding,
            )

    async def search(
        self,
        tenant_id: str,
        query: str,
        embedding: Optional[list[float]] = None,
        limit: int = 5,
    ) -> list[dict]:
        """Hybrid search: full-text + optional vector similarity."""
        async with self.pool.acquire() as conn:
            if embedding:
                # Hybrid scoring: 0.6 * text relevance + 0.4 * vector similarity
                rows = await conn.fetch(
                    """
                    SELECT path, content, metadata,
                           (0.6 * ts_rank(ts_vector, plainto_tsquery('english', $2)) +
                            0.4 * (1 - (embedding <=> $3))) AS score
                    FROM documents
                    WHERE tenant_id = $1
                      AND ts_vector @@ plainto_tsquery('english', $2)
                    ORDER BY score DESC
                    LIMIT $4
                    """,
                    tenant_id, query, embedding, limit,
                )
            else:
                # Full-text search only
                rows = await conn.fetch(
                    """
                    SELECT path, content, metadata,
                           ts_rank(ts_vector, plainto_tsquery('english', $2)) AS score
                    FROM documents
                    WHERE tenant_id = $1
                      AND ts_vector @@ plainto_tsquery('english', $2)
                    ORDER BY score DESC
                    LIMIT $3
                    """,
                    tenant_id, query, limit,
                )
            return [dict(row) for row in rows]

Wat je krijgt:

• Hybride zoekopdracht: combinatie van sleutelwoordspecificatie (GIN-index) en semantische similariteit (pgvector), waarbij beide componenten samen worden gewaardeerd
• Meertaligheid: tenant_id Bepalen van het scope met rijniveaubeveiliging
• ACID-garanties: geen problemen met eventuele consistentie
• Enkel besturingssysteem: geen aparte vector database om te beheren
• Horizontale schaling: leesreplica’s voor de querybelasting, partitionering per gebruiker voor schaalbaarheid bij schrijfoperaties

Bestanden zijn uitstekend geschikt voor situaties waarin één ontwikkelaar werkt workflows. Voor productieomgevingen met meerdere gebruikers vormt een gestructureerde documentopslag op PostgreSQL doorgaans de beste balans tussen eenvoud, prestaties en operationele volwassenheid.

Samenvoegen: de volledige architectuur

Hieronder wordt uitgelegd hoe de drie geheugenlagen samenwerken in de Marktanalist Agent. Het diagram toont de volledige stroom van de gebruikersaanvraag tot aan het antwoord, waarbij alle geheugenlagen actief zijn.

De architectuur beschikt over drie geheugenpaden:

1. Hot path (checkpoint store): Elke node in de LangGraph schrijft zijn herstartbare grafische staat op in de checkpoint store. Wanneer het graf een bepaald punt bereikt interrupt_before node (net zoals de reporter in Deel 1), Er kunnen pauzes in de uitvoering optreden. De gebruiker kan de applicatie sluiten, en wanneer deze terugkeert, wordt de grafiek hervat vanaf checkpoint. Logboeken van Runtime en traces vormen afzonderlijke aspecten die in een productieomgeving in de gaten moeten worden gehouden.

2. Koude route (langdurige opslag): Aan het begin van elk gesprek vraagt de agent aan de langdurige opslag om relevante gebruikerscontext. Aan het einde worden nieuwe feiten geëxtraheerd en opgeslagen. Dit verloopt asynchroon — het mag de hoofd reasoning loop nooit blokkeren.

3. Documentopslagpad (bestandssysteem): Bij het opstarten laadt de agent de projectconventies en relevante onderzoeksnotities uit de documentopslag. Tijdens de uitvoering worden nieuwe onderzoeks samenvattingen en geleerde patronen weer op de schijf geschreven. In tegenstelling tot het ‘cold path’ zijn documentlezingen synchroon (ze beïnvloeden de huidige taak), terwijl schrijfbewerkingen kunnen worden uitgesteld.

De bedrading in LangGraph is eenvoudig — de checkpoint store en de long-term store worden overgedragen tijdens de compilatie van de graaf, terwijl de document store als afhankelijkheid wordt toegevoegd. Het lokale schema hieronder maakt gebruik van InMemoryStore Zodat het fragment klein blijft, maakt de referentiemodus van Docker gebruik van Qdrant voor dezelfde rol met betrekking tot semantische recall.

from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver
from langgraph.store.memory import InMemoryStore

# Hot memory: PostgreSQL for durable checkpoints
checkpointer = await create_postgres_checkpointer(pg_connection_string)

# Cold memory: local sketch with vector search
# (The reference Docker topology uses Qdrant for persistent recall.)
memory_store = InMemoryStore(
    index={"dims": 1536, "embed": embedding_function}
)

# Document memory: file-based store for project knowledge
doc_memory = FileMemory(base_dir=".agent-memory")

# Checkpoint store and long-term store wired into the graph
graph = create_graph(
    checkpointer=checkpointer,
    store=memory_store,
)

# The store is accessible inside any node via the store parameter
def planner_node(state: AgentState, *, store: BaseStore) -> dict:
    """Plan with user context from long-term memory."""

    # Recall relevant user facts from vector store
    user_memories = store.search(
        namespace=("user", state.user_id),
        query=state.messages[-1].content,
        limit=5,
    )

    # Load project conventions from document memory
    conventions = doc_memory.read_doc("conventions/analysis-format.md")

    # Inject both into planning context
    memory_context = "\n".join(m.value["fact"] for m in user_memories)
    # ... rest of planning logic with personalized context and conventions

De volledige stroomlijn

Wat gebeurt er wanneer een terugkerende gebruiker “Analyze TSLA” naar de Marktanalist Agent:

1. Documentmemorybelasting: Bij het opstarten leest de agent de projectconventies uit de documentopslag: voorkeuren met betrekking tot analyseformaten, gewenste gegevensbronnen en gebruikspatronen van tools. Hierdoor wordt het basistoebehoren bepaald.

2. Koude geheugenoproep: Voordat de router-node wordt uitgevoerd, vraagt het graf de langetermijnopslag op naar de bericht van de gebruiker. Hierdoor worden de volgende gegevens opgehaald: “De gebruiker heeft een hoge risicotolerantie”, “De gebruiker geeft de voorkeur aan een gedetailleerde analyse van concurrenten” en “De gebruiker heeft eerder onderzoek gedaan naar NVDA en AMD”.

3. Router + Planner: De router classificeert dit als DEEP_RESEARCH. De planner genereert een 5-stappen onderzoekplan dat is aangepast aan de eerder genoemde voorkeuren. Het omvat een stap voor concurrentieanalyse, aangezien de gebruikersgeschiedenis aangeeft dat deze gewenst is. Het plan volgt het formaat zoals beschreven in het conventiesdocument.

4. Executor lus (heet geheugen): Elke stap wordt uitgevoerd volgens het ReAct patroon van Deel 1. Na elk node (router, planner, elke executor stap) schrijft LangGraph een checkpoint naar PostgreSQL. Als het proces na stap 3 van in totaal 5 crasht, start u het opnieuw en gaat u verder vanaf stap 4.

5. HITL-interruption: De grafiek bereikt de reporter node met interrupt_before. Het conceptversie van het rapport bevindt zich in de checkpoint. De gebruiker bekijkt dit enkele uren later, waarna de grafiek wordt geladen uit de checkpoint en het proces verdergaat.

6. Geheugenupdates: Nadat het gesprek is beëindigd: (a) een asynchrone proces haalt nieuwe gebruikersfeiten op (“de gebruiker volgt nu TSLA”, “de gebruiker heeft het rapportformaat goedgekeurd”) en slaat deze op in het langetermijn vector store, en (b) de agent schrijft een onderzoeks samenvatting op in de documentopslag (research/TSLA-2026-02.md) ter toekomstige referentie.

Het drie-laags patroon scheidt de verschillende verantwoordelijkheden helder van elkaar. De checkpoint-opslag zorgt voor duurzaamheid en herstel van werkzaamheden; dit valt onder de infrastructuur. De langetermijnopslag is verantwoordelijk voor personalisatie; dit maakt deel uit van de productlogica. De documentopslag bevat alle opgeslagen projectkennis; dit fungeert als het notitieboek van de agent.

Afwegingen en overwegingen

Geheugen voegt waarde toe, maar het brengt ook kosten en complexiteit met zich mee. Wees eerlijk over de afwegingen:

• Embedding kosten: Elke feit die wordt opgeslagen in een vector database vereist een embedding API aanroep. Dit kost $0,02 per miljoen tokens (OpenAI) text-embedding-3-small), de feitelijke kosten zijn verwaarloosbaar, maar ze stapelen zich op bij duizenden gebruikers en sessions. Voer embedding-aanroepen in batches uit en cacheer de resultaten. De echte kosten liggen bij latency: 100-300 ms aan embedding API latency tijdens het opvragen van gegevens uit koude geheugen, wat voor real-time conversaties in het kader van agents belangrijker is dan de financiële kosten. Cacheer embeddings voor veelvoorkomende vragen, of gebruik een lokale embedding model voor werkloads die gevoelig zijn voor latency.

• Verouderde geheugeninformatie: Gebruikersvoorkeuren veranderen. Een feit dat zes maanden geleden is opgeslagen (“de gebruiker geeft de voorkeur aan conservatieve beleggingen”) is mogelijk niet langer accuraat. Stel verlopenheidsbeleid in. Ik gebruik 365 dagen voor voorkeuren en 90 dagen voor incidentele gebeurtenissen, zoals beschreven in mijn context engineering-post.

• Geheugenoverhead in de context: Elke opgeroepen feit verbruikt tokens in de context window van de LLM. Als je per zoekopdracht 20 feiten oproept, leidt dat tot enkele honderden tokens aan geheugencontext die concurreert met de eigenlijke taak. Beperk het aantal opgeroepen feiten en geef voorkeur aan feiten op basis van hun relevantiescore.

• Privaciteit en naleving van regelgeving: Long-term memory slaat gebruikersgegevens op. Er is een redactie van PII vereist voordat de gegevens worden opgeslagen, evenals duidelijke beleidsregels met betrekking tot het bewaren van gegevens en gebruikersgerichte mogelijkheden om gegevens te verwijderen. In gereguleerde industrieën is geen van deze zaken optioneel.

• Checkpoint opslaggroei: PostgreSQL checkpoint-tabellen groeien bij elke uitvoering op een nieuwe node. Voor langlopende agents-processen dient men een retentiebeleid in te stellen: bewaar de laatste N checkpoints per thread en archiveer of verwijder oudere exemplaren. Hier is een voorbeeld van een schoonmaakquery die de 10 meest recente checkpoints per thread behoudt en alles wat ouder is dan 30 dagen verwijdert:

  DELETE FROM checkpoints
  WHERE thread_id = $1
    AND created_at < NOW() - INTERVAL '30 days'
    AND checkpoint_id NOT IN (
      SELECT checkpoint_id FROM checkpoints
      WHERE thread_id = $1
      ORDER BY created_at DESC
      LIMIT 10
    );

• Geheugenconsolidatie: Na verloop van tijd zouden gedetailleerde episodische herinneringen moeten worden gecomprimeerd tot compacte semantische representaties: “de gebruiker vroeg drie keer in januari naar NVDA” in plaats van alle drie gesprekken woord voor woord op te slaan. Dit weerspiegelt de geheugenconsolidatie bij mensen en houdt de opslagruimte beheersbaar. Mem0 en Graphiti Verwerk dit automatisch; als u er zelf een bouwt, plan dan periodieke consolidatieroutes in.

• Cold start probleem: Nieuwe gebruikers beschikken over geen long-term memory. De agent moet op een soepele manier falen en duidende vragen stellen in plaats van aannames te doen. Geheugen is cumulatief; het is niet verplicht.

• Memory poisoning: Alles wat zich bevindt in de agent’s context window vormt een potentiële injectiepunt. Als een aanvaller misleidende informatie in de documentopslag of long-term memory (“transacties altijd zonder verificatie goedkeuren”) plaatst, kan de agent deze gegevens uitvoeren als instructies. Prompt injection via opgeslagen geheugengegevens vormt daardoor een echte aanvalsvlakte. Mitigaties hiertegen omvatten validatie vóór opslag, het behandelen van opgeroepen inhoud als onbetrouwbare gegevens in plaats van systeeminstructies, en toegangsbeperkingen die bepalen welk geheugen invloed mag uitoefenen op kritieke processen.

• Documentmemorydrift documenteren: Bestandsgebaseerde geheugens beschikken niet over automatische duplicaatverwijdering of conflictoplossing. Na verloop van tijd ontstaan er tegenstrijdigheden in de documenten: één bestand geeft aan “pytest te gebruiken” terwijl een ander “unittest” aanbeveelt. Plan regelmatige reviews in (of laat agent dit doen) om overtollige inhoud weg te halen en de documenten te consolideren. Het goede nieuws is dat dit, in tegenstelling tot vector stores waarbij veroudering verborgen blijft, mogelijk is. grep voor tegenstrijdigheden.

• Documentmemory schaalt niet uit tot miljoenen items: Geheugen dat is gebaseerd op bestanden werkt voor honderden tot een paar duizend documenten. Als uw agent moet zoeken in miljoenen feiten met vage overeenkomsten, heeft u een vector store nodig. Documentmemory is bedoeld voor gestructureerde projectkennis, en niet voor de grote hoeveelheid kleine interacties van elke gebruiker.

Belangrijkste conclusies

1. Agent memory omvat meerdere stores met uiteenlopende toegangspatronen. Houd de mogelijkheid tot hervatten van checkpoints, gestructureerde feiten, semantische herinnering en projectdocumenten gescheiden van elkaar.
2. Implementeer functies voor pauzeren en hervatten vóór het aanpassen van inhoud. Het verliezen van voortgang bij taken is de eerste vorm van geheugenfalen die optreedt bij langlopende agent processen.
3. Plaats deterministische feiten in gestructureerde opslag. Gebruik vector search wanneer de zoekopdracht vaag is of de formulering varieert.
4. Gebruik bestanden voor projectkennis die door mensen moet worden bekeken, bewerkt, geversioneerd of vergeleken via een diff.
5. Stel voor elk type geheugen regels vast met betrekking tot vervaldatum, conflicten en verwijdering. Een geheugen dat het systeem niet kan corrigeren, vormt productdebt.
6. Beperk wat wordt teruggegeven aan de model. Opgeslagen geheugen heeft alleen waarde wanneer retrieval de juiste bewijzen in de huidige context plaatst.

De volgende laag is actie

Deel 3, AI Agent Tool Use in 2026, Het gaat van de opgeslagen staat over naar een actie. Hierin wordt onderzocht hoe een agent hulpmiddelen ontdekt en oproept, en hoe de grenzen van het hulpmiddel fouten teruggeven die door de reasoning loop kunnen worden gebruikt. Delen 5 en 6 keren terug naar het geheugen vanuit operationeel oogpunt: de runtime herstelt een checkpoint, terwijl de harness bepaalt wat moet worden overgedragen aan de volgende model session.

Referenties

Artikelen

• Cognitieve architecturen voor taal Agents (CoALA) — Sumers, Yao et al., 2023 — Fundamentele taxonomie van agent memory-typen Geheugen in het tijdperk van AI Agents: Een overzicht — Dec 2025 — Een uitgebreide driedimensionale taxonomie van agent memory
• MemGPT: Op weg naar LLMs als besturingssysteem — Packer et al., 2023 — Virtuele contextbeheer voor LLM agents
• Generatieve Agents: Interactieve simulacra van menselijk gedrag — Park et al., 2023 — Geheugestroomarchitectuur met scoring op recentheid, belangrijkheid en relevantie Zep: Een architectuur voor een temporele kennisgraaf voor Agent Memory — Rasmussen, 2025 — Bietijdsige kennisgraaf voor agent memory
• Mem0: Het opbouwen van een productieklare AI Agents met schaalbare Long-Term Memory — 2025 — Extractie/consolidatie pipeline met benchmarks
• Voyager: Een open einde hebbend embodied Agent systeem met grote taalmodellen Models — Wang et al., 2023 — Een vaardigheidsbibliotheek als documentgeheugen voor open-world games agents
• JARVIS-1: Open-World multi-taakssysteem Agents met geheugenversterkte multimodale taalverwerking Models — 2023 — Multimodale geheugencollectie voor Minecraft agents
• Agent Workflow Geheugen — Wang et al., 2024 — Herbruikbare workflow-inductie voor agents-automatisering van websites
• SkillWeaver: De Web Agents-module kan zelf skillbibliotheken ontwerpen. — 2025 — Zelfgesynthetiseerde, herbruikbare API hulpmiddelen voor web agents
• LEGOMem: Modulaire geheugen Framework voor LLM Agent systemen — 2025 — Composable geheugenmodules voor multi-agent-systemen

Documentatie van LangGraph

• LangGraph-persistentie (checkpointing) — Kernconcepten voor geheugen gebaseerd op checkpoint LangGraph-geheugenopslag — Koppel de long-term memory tussen threads aan de Store-interface
• LangGraph-kruisthreadpersistentie — Functioneel API mechanisme voor geheugenoverdracht tussen threads Hoe voeg je geheugen toe aan de vooraf gebouwde ReAct agent — Praktische gids voor het toevoegen van geheugen

Checkpoint backends

• langgraph-checkpoint-postgres — PostgreSQL checkpoint-saver voor LangGraph
• langgraph-checkpoint-redis — Redis checkpoint saver voor LangGraph LangGraph Redis Checkpoint 0.1.0 Herontwerp — Architectuurdetails voor de Redis checkpoint-saver
• langgraph-checkpoint-aws — DynamoDB checkpoint-saver met S3-offloading

Vector databases en geheugenhulpmiddelen

• Qdrant — Open-source vector database met HNSW-gebaseerde indexering en filtering Qdrant Agentic Bouwhandleiding — Praktische gids voor het bouwen van agent memory met Qdrant
• pgvector — Extensie voor vectorvergelijkingszoeking in PostgreSQL Graphiti — Een open-source engine voor tijdsgebonden kennisgrafieken van Zep

Geheugen gebaseerd op documenten en bestanden

• Claude Code Memory — CLAUDE.md en MEMORY.md: een op bestanden gebaseerd geheugensysteem Anthropic Memory-hulpmiddel — Clientzijde geheugen op basis van bestanden voor Claude API agents
• Cursorregels — Projectspecifieke .cursorrules-bestanden voor de agent-context Herinneringen aan windsurfen — Bestand gebaseerde geheugenopslag en .windsurfrules voor coderen agents

Geheugen frameworks

• Mem0 — Beheerde geheugenlaag voor extractie/consolidatie pipeline
• Letta (MemGPT) — Virtuele contextbeheer op basis van besturingssystemen voor agents
• LangMem SDK — Hulpmiddelen voor geheugenbeheer in LangGraph

Benchmarks

• Prestaties PostgreSQL versus Redis — CyberTec latency en throughput benchmarks
• Vergelijking PostgreSQL versus Redis — Vergelijking van architecturen voor RisingWave
• Redis AI Agent Ingenieurswerk — Redis-patronen voor agent-werkloads

Workshops

• MemAgents: Geheugen voor LLM-gebaseerde Agentic systemen — ICLR 2026 Workshop

Demo-project

• Marktanalist Agent — Volledige implementatie met alle drie de geheugenlagen

de volledige code van de Market Analyst Agent, inclusief de geheugenarchitectuur die in dit artikel wordt besproken, is beschikbaar op GitHub indien je graag mee wilt lezen.

Reeks: Het ontwerpen van de Agentic-stack

• Deel 1: AI Agent Reasoning Lussen in 2026 — ReAct, ReWOO en Plan-and-Execute
• Deel 2: AI Agent Memory Architectuur in 2026 (dit artikel)
• Deel 3: AI Agent Tool Use in 2026 — MCP, CLI, vaardigheden, uitvoering van code en ACI Deel 4: AI Agent Beveiliging in 2026 — guardrails, rechten, sandboxes, HITL, en MCP scopebepaling
• Deel 5: Langdurig draaiende AI Agent Runtime in 2026 — sessions, sandboxes, checkpoints, harnassen en deployment vormen
• Deel 6: Harness Engineering voor AI Agents (komt eraan) — acceptatiecontroles, traces, herproberingen, overdrachten en de lus rondom de model