docs: improve agent memory guide onboarding and usage guidance (#691)

* docs: improve agent memory guide onboarding and usage guidance

* docs: align Agent Memory guide with persistence implementation

* docs: fix misleading index_path persistence claim across guides

VectorStore's index_path kwarg is silently absorbed into FAISSStore's
**config and never read anywhere in faiss_store.py, so it does not make
the FAISS index persist across restarts as several docs implied. Real
persistence requires an explicit VectorStore.save()/.load() call, or
AgentContext.save()/.load() which cascades to it.

- docs/reference/context.md: rewrite the "Persist your vector store"
  tip to explain the actual save()/load() mechanism instead of the
  dead index_path kwarg.
- docs/guides/graphrag.md, decision-intelligence.md, ingest.md,
  semantic-extraction.md: drop the dead index_path=... kwarg from
  VectorStore(backend="faiss", ...) constructor calls.

Follow-up to #691, which fixed the same false claim in
docs/guides/agent-memory.md but missed these other files.

---------

Co-authored-by: KaifAhmad1 <kaifahmad087@gmail.com>

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.

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,
 )

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(

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,
     )

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,
 )

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