A first-principles walk through agent memory: from Python lists to markdown files to vector search to graph-vector hybrids, and finally, a clean, open-source solution for all of this. An LLM is stateless by design. Every API call starts fresh. The "memory" you feel when chatting with ChatGPT is an illusion created by re-sending the entire conversation history with every request. That trick works for casual chat. It falls apart the moment you try to build a real agent. Here are 7 failure modes show up the instant you skip memory: Context amnesia: the agent asks for information you already gave it Zero personalization: every interaction feels generic Multi-step task failure: intermediate state silently drops mid-task Repeated mistakes: no episodic recall means the same errors, forever No knowledge accumulation: every session starts from scratch Hallucination from gaps: when context overflows, the model invents Identity collapse: no continuity, no trust The obvious response is "throw more context at it." That's why 128K and 200K token windows feel like they should solve everything. They don't. Accuracy drops over 30% when relevant information sits in the middle of a long context. This is the well-documented "lost in the middle" effect. Context is a shared budget: system prompts, retrieved docs, conversation history, and output all fight for the same tokens. Even at 100K tokens, the absence of persistence, prioritization, and salience makes raw context length insufficient. Memory isn't about cramming more text into the prompt. It's about structuring what the agent remembers so it can find what matters. The cognitive science frame that actually helps Lilian Weng's 2023 formulation has become the default framework: Agent = LLM + Memory + Planning + Tool Use. The four co-equal pillars. Her taxonomy borrows from cognitive science, where human memory splits into three systems: Sensory memory captures raw perceptual input and holds it for a fraction of a second. Only the portions you pay attention to get passed forward. Working memory is where active thinking happens. It holds roughly 7±2 items at a time (Miller's 1956 finding). Lose focus, and the contents disappear. Long-term memory is durable storage with no practical capacity limit. Retrieval is the bottleneck: you can store millions of things and still fail to recall the one you need. Each maps directly to a component in modern agent architectures: Long-term memory itself splits further: Episodic: specific past events ("on Tuesday, the PostgreSQL cluster went down") Semantic: facts and concepts ("PostgreSQL is a relational database") Procedural: skills and workflows ("when a user asks for a refund, first check the purchase date") The bridge between episodic and semantic is memory consolidation: repeated specific events distilling into general knowledge. An agent that notices "users consistently prefer executive summaries" across dozens of interactions should turn that into a reusable rule. Without consolidation, your agent replays individual events rather than learning from them. The minimal agent, and what breaks first Strip away the frameworks and an agent is a loop: perceive, think, act. Tell it "I have 4 apples," then ask "I ate one, how many left?" and it has no idea what apples you're talking about. Each call exists in isolation. Layer 1: The Python list The first fix everyone reaches for: Multi-turn works now. The apples question gets answered correctly because the full conversation re-ships with every call. Two problems show up fast: The list grows unbounded. Around turn 200, you hit the context ceiling and the oldest messages silently drop. The user's name from turn 1 disappears long before yesterday's throwaway joke. No prioritization, just strict chronological order. Everything lives in RAM. The moment the Python process ends, your agent has no idea who you are. Layer 2: Markdown files for persistence The next move is writing memory to disk. Markdown is a natural fit: human-readable, Git-friendly, and the agent can read it back as plain text. Claude Code uses exactly this pattern with CLAUDE.md and MEMORY.md files. Persistence is solved. Restart the script, and the conversation is still on disk. You could also maintain a separate facts file that the agent extracts over time: You can open the file in any editor, see exactly what the agent knows, and fix it by hand. Genuinely useful for prototyping. With 4 facts, this works perfectly. Load the entire file into context and the LLM handles any question about Sarah, her company, or her industry. Now fast-forward three months. Your agent has 2,000 extracted facts and 200 conversation logs. That's 500K+ tokens of markdown on disk, and your context window is 128K. You can no longer load everything. You need to selectively retrieve only the facts relevant to the current query. With flat files, your only option is keyword search: At small scale, markdown files work. At real scale, they for