0.1 Why Agent Memory Matters

Every agent eventually faces the same wall: it forgets. Not because the LLM is broken, but because the context window is finite, sessions end, processes restart, and the only thing the model "knows" at the start of a new conversation is what you stuff into the prompt.

In practice, this means agents repeat mistakes, contradict prior decisions, fail to learn from corrections, and force users to re-explain the same project for the tenth time. Memory is the missing primitive that turns a stateless function call into a learning system.

The four problems memory solves

Context continuity. The agent picks up where it left off — across sessions, days, or process restarts.
Decision auditability. "Why did we choose Postgres over DynamoDB three months ago?" becomes answerable.
Cross-agent state. Multiple agents (or agent + human) share a common ground truth without rebuilding it every time.
Self-improvement. Mistakes become LessonLearned thoughts; corrections supersede prior beliefs; the agent gets measurably better at its job over time.

What "memory" is not

Memory is not just a vector database. Vectors are great for similarity search, but a memory system also needs:

Identity — who wrote this? which agent? which user?
Structure — is this a decision, a fact, a question, a mistake?
Time — when was this true? is it still true?
Relations — does this contradict that? was this derived from that?
Integrity — can I prove this hasn't been tampered with?
Retrieval — not just vectors, but lexical + graph + hybrid rerank

A pure vector store gives you the last item. MentisDB gives you all six, with a single API and an append-only, hash-chained log at its core.

The agent memory stack

Think of memory as a stack, from the LLM outward:

Working memory — the prompt itself, what the model "sees" right now
Short-term memory — the current session's scratchpad, conversation buffer, tool outputs
Long-term memory — durable facts, decisions, preferences, lessons, episodic history
Shared memory — what multiple agents or the user + agent co-author

MentisDB is a long-term and shared memory layer. You bring your own working/short-term (typically LangChain's conversation buffer, or a simple in-process list). MentisDB is what persists across sessions, survives crashes, and serves as the audit log when something goes wrong.

When you need it

You need durable memory when your agent has any of:

Sessions that span more than one turn
Tasks that span more than one session
Multiple agents that need to share state
A user who expects the agent to remember their preferences
A team that needs to audit what the agent decided and why

When you don't need it: Single-turn Q&A, stateless RAG over a fixed document corpus (use a regular vector DB), or chat UIs where every conversation is fresh by design. Memory adds a write path and a retrieval step; make sure the use case justifies it.

What this book assumes

You have an LLM application that needs to persist context. You have tried stuffing things into the prompt and noticed it doesn't scale. You are evaluating memory systems and want to understand the design space, not just the API surface.

The next chapter introduces the MentisDB mental model: chains, thoughts, agents, scopes, and retrieval modes. If those terms are already familiar, skip to 0.3 for the quickstart.