How to Build Agent Memory Pipelines with Semantica's AgentContext: A Complete Guide

Semantica's AgentContext class orchestrates vector storage, knowledge graphs, and decision tracking into a unified agent memory pipeline with minimal configuration.

The AgentContext class in semantica-agi/semantica provides a high-level API for building sophisticated agent memory pipelines. Rather than manually wiring together vector databases, graph stores, and retrieval logic, developers can instantiate a single AgentContext object that automatically coordinates these components. This guide walks through the architecture, core methods, and practical implementation patterns based on the actual source code in semantica/context/agent_context.py.

---

Core Components of Agent Memory Pipelines

The AgentContext aggregates six key components that work together to enable memory storage, hybrid retrieval, and decision tracking:

Component	Role	Source Location
Vector Store	Persists embeddings and enables similarity search	Passed as vector_store parameter
Knowledge Graph	Stores entities, relationships, enables GraphRAG	Passed as knowledge_graph parameter
AgentMemory	Wraps vector store with metadata and CRUD helpers	agent_context.py lines 69-96
ContextRetriever	Hybrid RAG/GraphRAG retrieval engine	agent_context.py lines 98-108
EntityLinker	Resolves text mentions to graph entities	agent_context.py lines 81-82
Decision-Tracking Stack	Records decisions, finds precedents, causal analysis	agent_context.py lines 129-150

Each component is instantiated lazily based on configuration flags. The vector store is required; the knowledge graph and decision tracking are optional but unlock advanced capabilities.

---

Initializing the AgentContext for Memory Pipelines

To build an agent memory pipeline, instantiate AgentContext with your chosen backends and feature flags. The constructor signature accepts:

• vector_store – Any vector store implementation (e.g., FAISSStore, PineconeStore)
• knowledge_graph – Optional graph backend exposing the Graph API
• decision_tracking – Boolean to enable decision-lifecycle management
• kg_algorithms – Boolean to enable knowledge graph algorithms
• advanced_analytics – Boolean for enhanced retrieval analytics

from semantica.context import AgentContext
from semantica.vector_store.faiss_store import FAISSStore
from semantica.integrations.agno.knowledge_graph import KnowledgeGraph

# Configure backends

vector_store = FAISSStore(dim=768)      # Required: your vector backend

kg = KnowledgeGraph()                    # Optional: enables GraphRAG

# Build the pipeline

ctx = AgentContext(
    vector_store=vector_store,
    knowledge_graph=kg,
    decision_tracking=True,      # Enable decision recording & analysis

    advanced_analytics=True,
    kg_algorithms=True,
)

The AgentContext stores the vector store reference directly and wraps it with AgentMemory for metadata handling. When a knowledge graph is provided, it lazily instantiates ContextRetriever for hybrid retrieval.

---

Storing Memories: Single Items and Batch Documents

The store() method handles both single strings and document batches with automatic graph building when configured.

Storing Single Memories

For conversation snippets or individual observations:

mem_id = ctx.store(
    "User asked how to reset their password",
    conversation_id="conv_42",
    user_id="user_7"
)

The method returns a memory ID for later reference. Metadata parameters like conversation_id and user_id enable filtered retrieval.

Batch Document Storage with Entity Extraction

For document ingestion pipelines, pass a list of dictionaries with content and metadata keys:

docs = [
    {"content": "Password reset flow description", "metadata": {"type": "doc"}},
    {"content": "Security policy for password complexity", "metadata": {"type": "policy"}},
]

store_stats = ctx.store(
    docs,
    extract_entities=True,           # Auto-extract entities to graph

    extract_relationships=True       # Auto-extract relationships

)

When extract_entities=True and a knowledge graph is present, AgentContext invokes _build_graph_from_documents to populate the graph automatically. The returned store_stats contains ingestion metrics.

---

Retrieving Context: Vector RAG and GraphRAG Modes

The retrieve() method automatically selects between pure vector search and hybrid GraphRAG based on configuration and parameters.

Vector-Only Retrieval

When no knowledge graph is configured or use_graph=False:

results = ctx.retrieve(
    "What are the steps to change a password?",
    max_results=5
)

Returns top-k similar memories from AgentMemory with similarity scores.

Hybrid GraphRAG Retrieval

When a knowledge graph exists and use_graph=True (or when include_entities=True triggers graph features):

results = ctx.retrieve(
    "What are the steps to change a password?",
    max_results=5,
    include_entities=True,
    use_graph=True          # Explicitly enable graph expansion

)

The ContextRetriever (instantiated at lines 98-108) performs:

1. Initial vector search for candidate nodes
2. Graph expansion around retrieved entities
3. Score merging via _apply_proximity_metadata to combine vector similarity with graph proximity

This hybrid approach surfaces relevant information that may not be semantically similar in embedding space but is connected through entity relationships.

---

Entity Linking for Structured Reasoning

The link() method resolves free-text mentions to knowledge graph entities using the EntityLinker component:

linked = ctx.link(
    "The user must comply with the PasswordPolicy",
    similarity_threshold=0.85
)

Returns a list of linked entities with confidence scores. This enables:

• Grounding agent responses in verified graph entities
• Building entity-aware prompts for LLM calls
• Validating mentions against the knowledge base

The implementation delegates to EntityLinker at lines 81-82 of agent_context.py.

---

Manual Graph Construction

For scenarios requiring explicit graph building from raw data:

ctx.build_graph(
    entities=[{"name": "PasswordPolicy", "type": "Policy"}],
    relationships=[{"source": "User", "target": "PasswordPolicy", "relation": "must_comply"}]
)

This method constructs graph structures from conversation transcripts or extracted data when automatic extraction is insufficient.

---

Decision Tracking and Causal Analysis

When decision_tracking=True and a knowledge graph is present, AgentContext initializes a full decision-lifecycle stack (lines 129-150).

Recording Decisions

Persist decisions with structured attributes:

decision_id = ctx.record_decision(
    category="access_grant",
    scenario="ResetPassword",
    reasoning="User verified via email",
    outcome="granted",
    confidence=0.97
)

This写入 to DecisionRecorder which persists records into the knowledge graph as typed nodes.

Finding Precedents

Search for similar past decisions with hybrid similarity:

precedents = ctx.find_precedents_advanced(
    query="ResetPassword",
    category="access_grant",
    use_kg_features=True      # Leverage graph structure in similarity

)

The DecisionQuery component (via find_precedents_advanced) combines vector similarity of decision descriptions with graph-based features when use_kg_features=True.

Causal Influence Analysis

Analyze how a decision propagated through the system:

influence = ctx.analyze_decision_influence(decision_id)

Returns a causal chain computed by CausalChainAnalyzer, traversing the graph to identify downstream effects and root causes.

---

Key Source Files for Agent Memory Pipelines

File	Purpose
semantica/context/agent_context.py	Central orchestrator with store, retrieve, link, record_decision
semantica/context/agent_memory.py	Vector store wrapper with metadata CRUD
semantica/context/context_retriever.py	Hybrid GraphRAG with score merging
semantica/context/entity_linker.py	Text-to-entity resolution
semantica/context/decision_recorder.py	Decision persistence to graph
semantica/context/decision_query.py	Precedent search and analytics
semantica/context/causal_analyzer.py	Decision influence chain traversal

---

Summary

• AgentContext consolidates vector storage, knowledge graphs, and decision tracking into one configurable class
• store() handles both single memories and batch documents with optional automatic graph building
• retrieve() automatically selects between vector RAG and hybrid GraphRAG based on parameters and configuration
• link() grounds free text in verified graph entities for structured reasoning
• Decision tracking enables full-lifecycle management when decision_tracking=True and a knowledge graph is provided
• All components are lazily instantiated and automatically orchestrated—no manual wiring required

---

Frequently Asked Questions

What vector stores work with AgentContext?

Any store implementing the vector store interface, including FAISSStore for local development, PineconeStore for managed cloud vectors, and custom implementations. The vector_store parameter is required and passed directly to AgentMemory.

Do I need a knowledge graph to use AgentContext?

No. The knowledge graph is optional. Without it, AgentContext provides pure vector-based storage and retrieval. Adding a knowledge graph enables GraphRAG, entity linking, and decision tracking features.

How does hybrid GraphRAG differ from standard RAG?

Standard RAG retrieves based on embedding similarity alone. Hybrid GraphRAG (enabled via use_graph=True or include_entities=True) first retrieves vector candidates, then expands through the knowledge graph to find connected entities, finally merging scores through _apply_proximity_metadata. This surfaces relevant information connected through relationships rather than semantic similarity.

What happens when decision_tracking is enabled without a knowledge graph?

The AgentContext initialization at lines 129-150 checks for both decision_tracking=True and the presence of a knowledge graph. Without a graph, decision-tracking features are not initialized—record_decision and related methods will either fail gracefully or be unavailable depending on version.

Can I extract entities without building the full graph?

No. The extract_entities and extract_relationships parameters in store() require a configured knowledge graph to receive the extracted data. Without knowledge_graph passed to the constructor, these parameters have no effect.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}