Memory is what separates MAEL’s agents from stateless prompt calls: each layer trades off scope, latency, and durability for a specific job.

​
Four layers

An agent’s live scratch pad during one invocation — tool results across reasoning-loop iterations, intermediate outputs, self-correction history. Lives entirely in the worker process heap; never queried by anything else. A 50MB soft cap triggers truncation of the oldest tool results before the next LLM turn, rather than an OOM.

​
Vector search (pgvector)

Embeddings live in PostgreSQL via pgvector, indexed with HNSW (hierarchical navigable small world) for approximate nearest-neighbor search — no separate vector database to operate. ADR-002 documents a real correctness fix here: the HNSW index must not be wrapped in a subquery, and the embedding model version must be filtered at query time, not assumed constant.

​
Hybrid retrieval

Three search modalities combine via Reciprocal Rank Fusion:
  1. Vector search — semantic similarity via pgvector
  2. Keyword search — BM25-style full-text search (PostgreSQL’s native FTS)
  3. Graph search — relationship traversal through the knowledge graph
Single-pass vector retrieval is the default; multi-stage retrieval (broaden → rerank) is used where recall matters more than latency.

​
Embedding providers

Memory writes never hard-depend on one vendor. EmbeddingProvider is a protocol (mirroring LLMProvider) with OpenAI, vLLM, and Ollama implementations — selected via Settings.embedding_provider (default openai, so existing deployments are unaffected). An Anthropic-only or air-gapped deployment can run memory entirely on a local embedding model.

​
PII and confidence

The memory service scrubs PII before persistence and attaches a confidence_score to long-term and graph writes, so retrieval can weight or filter on how trustworthy a stored fact actually is — a keyword decision made from a single data point is not treated the same as one backed by 90 days of GSC data.

AI Agents

Workflow Engine