diff --git a/docs/guides/agent-memory.md b/docs/guides/agent-memory.md
index 3b4f0a01..c28f2c93 100644
--- a/docs/guides/agent-memory.md
+++ b/docs/guides/agent-memory.md
@@ -6,6 +6,45 @@ icon: "brain"
 
 `AgentContext` maintains a persistent memory layer for LLM agents — storing observations as vector embeddings, retrieving them by semantic similarity, and optionally blending graph proximity into the ranking. Use it when your agent needs to recall past findings across sessions without re-reading source material on every restart.
 
+## What Is Agent Memory?
+
+Agent Memory provides persistent storage and intelligent retrieval of information across multiple agent sessions. `AgentContext` is the core component that orchestrates memory storage, retrieval, and management by combining three key systems:
+
+**VectorStore** handles semantic search using vector embeddings. It stores text as high-dimensional vectors and retrieves similar content through cosine similarity or other distance metrics.
+
+**ContextGraph** maintains structured knowledge as nodes (entities) and edges (relationships). This enables multi-hop traversal and graph-aware retrieval that follows connections between related entities.
+
+**AgentContext** orchestrates both components, providing a unified interface for storing memories, retrieving relevant context, and managing conversations across sessions.
+
+**Persistent memory vs stateless retrieval:** Traditional RAG systems lose context between sessions. Agent Memory persists learned information, conversation history, and accumulated knowledge across restarts, enabling long-term memory and cross-session recall.
+
+## Why Use Agent Memory?
+
+**Cross-session recall.** Agents remember previous interactions, findings, and decisions without re-processing source material after restarts.
+
+**Long-term knowledge accumulation.** Information builds up over time as agents process more documents, creating increasingly rich knowledge bases for future queries.
+
+**Conversation history.** Agents maintain context within conversations and can reference earlier parts of extended interactions or investigations.
+
+**Graph-aware retrieval.** Beyond simple semantic similarity, retrieval follows entity relationships to find connected information that pure vector search would miss.
+
+**Decision tracking.** Record decisions with full context and reasoning paths, enabling audit trails and precedent matching for similar future scenarios.
+
+## When To Use / When Not To Use
+
+**Use Agent Memory for:**
+- Long-running agents that need to accumulate knowledge over time
+- Research assistants that build understanding across multiple sessions
+- Investigation workflows where context builds incrementally
+- Systems that must remember prior interactions and decisions
+- Scenarios requiring audit trails and decision precedents
+
+**Do not use when:**
+- Building simple stateless RAG systems for one-time document queries
+- Performing one-off document searches without need for persistence
+- Running temporary experiments that don't require knowledge retention
+- Simple retrieval tasks where relationships between entities don't matter
+
 <Info>
   This guide covers the memory layer. For graph-enriched traversal and entity linking, see [Context Graphs](context-graphs). For decision accountability — recording, auditing, and causally tracing what the agent chose — see [Decision Intelligence](decision-intelligence).
 </Info>
@@ -18,11 +57,10 @@ Configure the vector store, knowledge graph, and `AgentContext` together at star
 from semantica.context import AgentContext, ContextGraph
 from semantica.vector_store import VectorStore
 
-# The FAISS index persists to disk at index_path — restart-safe
+# The VectorStore relies on explicit save()/load() for persistence
 ti_vs = VectorStore(
     backend="faiss",
     dimension=768,
-    index_path="ti_agent/memory.faiss",
 )
 
 # The ContextGraph holds entity nodes and their relationships
@@ -141,7 +179,7 @@ results = ti_agent.retrieve(
     "cloud OAuth token theft campaigns",
     max_results=10,
     use_graph=True,
-    anchor_node="APT29",      # BFS starts from this node in the knowledge graph
+    anchor_node="APT29",      # Breadth-First Search (BFS) starts from this node in the knowledge graph
     max_hops=3,
     proximity_weight=0.35,    # 65% semantic + 35% proximity — tune to your graph density
     min_score=0.1,
@@ -242,7 +280,7 @@ from semantica.llms import Groq
 
 ti_graph = ContextGraph(advanced_analytics=True, node_embeddings=True)
 ti_agent = AgentContext(
-    vector_store=VectorStore(backend="faiss", dimension=768, index_path="ti_memory.faiss"),
+    vector_store=VectorStore(backend="faiss", dimension=768),
     knowledge_graph=ti_graph,
     retention_days=365,
     max_memories=50000,
@@ -297,7 +335,7 @@ from semantica.llms import Groq
 
 soc_graph = ContextGraph()
 soc_agent = AgentContext(
-    vector_store=VectorStore(backend="faiss", dimension=768, index_path="soc_memory.faiss"),
+    vector_store=VectorStore(backend="faiss", dimension=768),
     knowledge_graph=soc_graph,
     retention_days=180,
     max_memories=100000,
@@ -370,7 +408,7 @@ from semantica.vector_store import VectorStore
 
 clinical_graph = ContextGraph(advanced_analytics=True)
 clinical_agent = AgentContext(
-    vector_store=VectorStore(backend="faiss", dimension=768, index_path="clinical.faiss"),
+    vector_store=VectorStore(backend="faiss", dimension=768),
     knowledge_graph=clinical_graph,
     retention_days=3650,      # 10-year clinical record retention
     max_memories=500000,
@@ -446,7 +484,7 @@ from semantica.vector_store import VectorStore
 
 credit_graph = ContextGraph(advanced_analytics=True)
 credit_agent = AgentContext(
-    vector_store=VectorStore(backend="faiss", dimension=768, index_path="credit.faiss"),
+    vector_store=VectorStore(backend="faiss", dimension=768),
     knowledge_graph=credit_graph,
     retention_days=2555,      # 7-year regulatory retention
     max_memories=1000000,
@@ -546,7 +584,7 @@ from semantica.vector_store import VectorStore
 
 # Create a fresh context with matching configuration
 ti_agent_restored = AgentContext(
-    vector_store=VectorStore(backend="faiss", dimension=768, index_path="ti_memory.faiss"),
+    vector_store=VectorStore(backend="faiss", dimension=768),
     knowledge_graph=ContextGraph(advanced_analytics=True),
     retention_days=365,
     decision_tracking=True,
@@ -605,6 +643,18 @@ s = ti_agent.stats()
 print("Total memories: {}".format(s.get("total_items", 0)))
 ```
 
+## Common Pitfalls
+
+**Forgetting to persist memory before shutdown.** Agent Memory is stored in memory during execution. Without calling `save()` before process termination, all accumulated memories, graph relationships, and conversations are lost.
+
+**Using the same conversation namespace for unrelated tasks.** Conversation IDs should scope related interactions. Using a single conversation for multiple unrelated investigations pollutes retrieval results and makes context less focused.
+
+**Storing excessive low-value information.** Not every observation needs permanent storage. Focus on storing insights, decisions, and significant findings rather than verbose raw logs or temporary calculations.
+
+**Using Agent Memory when simple retrieval would be sufficient.** For one-time document lookups or stateless queries, traditional retrieval is simpler and more efficient than setting up persistent memory infrastructure.
+
+**Retrieving too much context and increasing latency.** Large `max_results`, high `max_hops`, or broad queries can retrieve excessive context, increasing LLM token usage and response latency. Start with focused retrieval parameters.
+
 ## Related Guides
 
 - [Context Graphs](context-graphs) — How the underlying `ContextGraph` stores entity nodes and decision nodes; temporal interval reasoning; deduplication before node insertion; ontology from graph.
diff --git a/docs/guides/decision-intelligence.md b/docs/guides/decision-intelligence.md
index f52f1903..072f2b5b 100644
--- a/docs/guides/decision-intelligence.md
+++ b/docs/guides/decision-intelligence.md
@@ -559,7 +559,7 @@ context.save("agent_state/")
 
 # Start of next session
 context = AgentContext(
-    vector_store=VectorStore(backend="faiss", dimension=768, index_path="decisions.faiss"),
+    vector_store=VectorStore(backend="faiss", dimension=768),
     knowledge_graph=ContextGraph(),
     decision_tracking=True,
 )
diff --git a/docs/guides/graphrag.md b/docs/guides/graphrag.md
index 661fa59b..0f142532 100644
--- a/docs/guides/graphrag.md
+++ b/docs/guides/graphrag.md
@@ -83,7 +83,7 @@ from semantica.context import AgentContext, ContextGraph
 from semantica.vector_store import VectorStore
 
 # FAISS runs locally with no external dependencies
-vs = VectorStore(backend="faiss", dimension=768, index_path="intel.faiss")
+vs = VectorStore(backend="faiss", dimension=768)
 graph = ContextGraph(advanced_analytics=True)
 
 context = AgentContext(
diff --git a/docs/guides/ingest.md b/docs/guides/ingest.md
index 4d558192..62549dd6 100644
--- a/docs/guides/ingest.md
+++ b/docs/guides/ingest.md
@@ -468,8 +468,7 @@ def run_daily_ingest(since: datetime = None):
 
     graph   = ContextGraph(advanced_analytics=True)
     context = AgentContext(
-        vector_store    = VectorStore(backend="faiss", dimension=768,
-                                      index_path="cti_index.faiss"),
+        vector_store    = VectorStore(backend="faiss", dimension=768),
         knowledge_graph = graph,
         graph_expansion = True,
     )
diff --git a/docs/guides/semantic-extraction.md b/docs/guides/semantic-extraction.md
index cbf79024..af5b349e 100644
--- a/docs/guides/semantic-extraction.md
+++ b/docs/guides/semantic-extraction.md
@@ -313,7 +313,7 @@ def ingest_intel_report(
 # Process all 200 reports
 intel_graph = ContextGraph(advanced_analytics=True)
 intel_agent = AgentContext(
-    vector_store=VectorStore(backend="faiss", dimension=768, index_path="intel.faiss"),
+    vector_store=VectorStore(backend="faiss", dimension=768),
     knowledge_graph=intel_graph,
     decision_tracking=True,
 )
diff --git a/docs/reference/context.md b/docs/reference/context.md
index 4768edaf..3a415816 100644
--- a/docs/reference/context.md
+++ b/docs/reference/context.md
@@ -272,7 +272,7 @@ icon: "brain"
 </Tip>
 
 <Tip>
-  **Persist your vector store between runs.** Pass `index_path="context.faiss"` to `VectorStore` so the FAISS index survives process restarts.
+  **Persist your context between runs.** `VectorStore` does not auto-persist — passing `index_path=` to its constructor is a no-op. Call `context.save("agent_state/")` to write memory, the vector index, and the graph to disk, and `context.load("agent_state/")` on the next process to restore them. See the "Persist & Restore" tab under [Real-World Patterns](#real-world-patterns) below.
 </Tip>
 
 ### Memory Methods