Design Layered Memory Architectures

This skill covers designing memory architectures for AI agents so they persist across sessions and reason over accumulated knowledge, spanning five layers on a spectrum from immediate context to permanent storage. Working memory is the context window itself - zero latency but volatile, vanishing at session end - used for scratchpad calculations, conversation history, task state, and active retrieved documents. Short-term memory persists across the current session only, implemented as session-scoped databases, file-system storage in session directories, or in-memory caches keyed by session ID, used to track conversation state, cache tool-call results, and maintain task checklists without stuffing the context window. Long-term memory persists across sessions indefinitely, ranging from simple key-value stores to graph databases, used for learning user preferences, building domain knowledge bases, and storing reusable successful patterns. Entity memory tracks people, places, concepts, and objects to maintain identity consistency across interactions, recording properties and relationships as they're discovered. Temporal knowledge graphs extend entity memory with explicit validity periods on facts (a "valid from" and optional "valid until" timestamp), enabling time-travel queries and preventing outdated facts from contradicting new ones.

The skill grounds these choices in Deep Memory Retrieval (DMR) benchmark figures: Zep, a temporal knowledge graph, scores 94.8% DMR accuracy at 2.58s retrieval latency - a 90% latency reduction versus a 28.9s full-context baseline on GPT-5.2, from retrieving only relevant subgraphs instead of entire context history; MemGPT scores 93.4% with variable latency; GraphRAG scores roughly 75-85%, a 20-35% accuracy gain over baseline RAG with up to 30% less hallucination via community-based summarization; plain vector RAG scores roughly 60-70% because it loses relationship structure; and recursive summarization scores just 35.3% from severe information loss. Four implementation patterns apply: file-system-as-memory (simple, transparent, portable, but no semantic search or relationship tracking), vector RAG with metadata (semantic search plus filtering on entity tags, temporal validity, source, and confidence), knowledge graphs (explicit entity and relationship types), and temporal knowledge graphs (adds validity periods) - plus semantic, entity-based, and temporal retrieval patterns, and a consolidation process (identify outdated facts, merge related facts, update validity periods, archive or delete obsolete facts, rebuild indexes) triggered by accumulation, retrieval noise, a schedule, or an explicit request.

Use it when building agents that must persist across sessions, maintain entity consistency across conversations, reason over accumulated knowledge, learn from past interactions, or track how state changes over time.

Match the architecture to the need instead of defaulting to one pattern: file-system memory for simple persistence, vector RAG with metadata for semantic search, a knowledge graph for relationship reasoning, and a temporal knowledge graph specifically when facts change over time and stale values must not contradict new ones.

Includes example Python for entity tracking (store and retrieve entity records with properties and a last-updated timestamp) and for a temporal graph query answering "what was the user's address on a given date" by filtering a LIVES_AT relationship on its valid_from/valid_until range. Builds on a context-fundamentals skill.

Connects to multi-agent-patterns for shared memory across agents, context-optimization for memory-based context loading, and evaluation for evaluating memory quality. References external graph database documentation (Neo4j and similar) and vector store documentation (Pinecone, Weaviate, and similar).

Engineers designing agent memory systems who need to choose between file-system storage, vector RAG, knowledge graphs, and temporal knowledge graphs based on concrete accuracy and latency benchmarks rather than defaulting to whichever is simplest to stand up.