# How to Use the AgentContext Class for AI Agents: A Complete Guide

> Master the AgentContext class for AI agents. This guide explains how to manage memory, retrieval, and decision tracking using vector stores, knowledge graphs, and causal analysis components.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-22

---

**The `AgentContext` class provides a unified interface for managing AI agent memory, retrieval, and decision tracking by orchestrating vector stores, knowledge graphs, and causal analysis components.**

The `AgentContext` class in the `semantica-agi/semantica` repository eliminates the complexity of integrating disparate memory systems into AI agents. By abstracting vector storage, GraphRAG retrieval, and decision provenance into a single flag-driven API, it enables developers to implement sophisticated memory architectures without managing low-level component wiring. This guide examines the implementation details found in [`semantica/context/agent_context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py) and demonstrates how to leverage its full capabilities.

## Core Architecture and Components

The `AgentContext` class acts as an orchestration layer that lazily initializes internal components based on constructor flags. Understanding these underlying elements is essential for optimizing agent performance.

### Required Vector Store Backend

Every `AgentContext` instance requires a vector store implementation passed as the `vector_store` argument. This component handles embedding storage and similarity search operations. The class accepts any compatible vector store backend from the `semantica/vector_store/` directory, such as `FaissStore` or `QdrantStore`.

```python
from semantica.context import AgentContext
from semantica.vector_store.faiss_store import FaissStore

vector_store = FaissStore(dim=768)
ctx = AgentContext(vector_store=vector_store)

```

### Optional Knowledge Graph Integration

When a `knowledge_graph` parameter is provided (typically a `ContextGraph` instance), `AgentContext` instantiates a `ContextRetriever` for hybrid retrieval and exposes graph analytics methods. Without this parameter, the context operates in pure vector search mode.

```python
from semantica.graph.context_graph import ContextGraph

knowledge_graph = ContextGraph()
ctx = AgentContext(
    vector_store=vector_store,
    knowledge_graph=knowledge_graph,
    graph_expansion=True
)

```

### Decision Tracking Infrastructure

Setting `decision_tracking=True` activates a specialized subsystem that includes `DecisionRecorder`, `DecisionQuery`, `CausalChainAnalyzer`, and `PolicyEngine`. These components, implemented across [`semantica/context/decision_recorder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/decision_recorder.py) and [`semantica/context/causal_analyzer.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/causal_analyzer.py), enable full provenance tracking and causal chain analysis for agent decisions.

## Initializing the AgentContext

The constructor follows a flag-driven design pattern, enabling advanced features through boolean parameters without requiring architectural code changes. All components are lazily created to minimize runtime footprint when features are unused.

```python
from semantica.context import AgentContext
from semantica.vector_store.faiss_store import FaissStore
from semantica.graph.context_graph import ContextGraph

ctx = AgentContext(
    vector_store=FaissStore(dim=768),
    knowledge_graph=ContextGraph(),
    decision_tracking=True,
    advanced_analytics=True,
    graph_expansion=True,
    hybrid_alpha=0.7
)

```

**Key initialization parameters:**

- **`vector_store`** (required): The embedding storage backend used for similarity search.
- **`knowledge_graph`** (optional): Enables GraphRAG retrieval and graph-based analytics.
- **`decision_tracking`** (optional): Activates decision lifecycle management and causal analysis.
- **`advanced_analytics`** (optional): Enables knowledge graph analytics including centrality and community detection.
- **`graph_expansion`** (optional): Allows multi-hop graph expansion during retrieval operations.

## Storing Memories and Documents

The `store()` method in [`semantica/context/agent_context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py) automatically inspects input types to distinguish between single memories (strings) and document batches (lists). It additionally supports automatic entity and relationship extraction when a knowledge graph is present.

```python

# Store a single memory with metadata

mem_id = ctx.store(
    "User asked about loan eligibility",
    conversation_id="conv_42",
    user_id="alice"
)

# Store documents with automatic entity extraction

doc_stats = ctx.store(
    ["Doc about cybersecurity", "Doc about network topology"],
    extract_entities=True,
    extract_relationships=True
)

```

When `extract_entities=True` and a knowledge graph is configured, the method extracts entities and relationships from the content before storage, enriching the graph structure for future retrieval operations.

## Retrieving Context with Hybrid Search

The `retrieve()` method automatically selects between pure vector search and hybrid GraphRAG based on the presence of a knowledge graph. Developers can override this behavior using the `use_graph=False` parameter to force vector-only retrieval.

### Pure Vector Retrieval

Without graph expansion, the method queries the underlying `AgentMemory` instance (managed internally in [`semantica/context/agent_memory.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_memory.py)) for semantically similar content.

```python
results = ctx.retrieve(
    "What credit score is needed for a mortgage?",
    max_results=5,
    use_graph=False
)

```

### Hybrid Graph-Augmented Retrieval

When `knowledge_graph` is present and `expand_graph=True`, the method employs the `ContextRetriever` class from [`semantica/context/context_retriever.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_retriever.py) to perform hybrid retrieval combining vector similarity with graph traversal.

```python
results = ctx.retrieve(
    "What are the common attack vectors?",
    max_results=5,
    expand_graph=True,
    anchor_node="attack_vectors",
    proximity_weight=0.4
)

```

**Proximity metadata:** When supplying an `anchor_node`, results include hop distance from the anchor, confidence decay metrics, and a combined score blending vector relevance with graph proximity. The `proximity_weight` parameter (0.0-1.0) controls the blend ratio between semantic similarity and graph proximity.

## Tracking Decisions and Causal Chains

With `decision_tracking=True`, the `AgentContext` exposes methods for recording decisions, finding precedents, and analyzing causal influence through the knowledge graph.

### Recording Decisions

The `record_decision()` method persists decisions to the graph with full provenance metadata:

```python
decision_id = ctx.record_decision(
    category="approval",
    scenario="Mortgage Application",
    reasoning="Applicant has 750 credit score, stable income",
    outcome="approved",
    confidence=0.96
)

```

### Finding Precedents

The `find_precedents_advanced()` method performs knowledge graph-enhanced similarity searches to locate historically similar decisions:

```python
precedents = ctx.find_precedents_advanced(
    query="Mortgage Application",
    category="approval",
    use_kg_features=True
)

```

### Analyzing Causal Influence

The `analyze_decision_influence()` method, implemented through [`semantica/context/causal_analyzer.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/causal_analyzer.py), traces causal chains through the knowledge graph to identify influencing factors:

```python
influence_chain = ctx.analyze_decision_influence(decision_id)

```

## Configuration Flags and Performance Tuning

The `AgentContext` class uses boolean flags to enable sophisticated features without API changes:

- **`graph_expansion`**: Enables multi-hop traversal during retrieval, expanding context beyond immediate vector matches.
- **`hybrid_alpha`**: Controls the weighting between vector similarity and graph connectivity scores (range 0.0-1.0).
- **`advanced_analytics`**: Activates graph algorithms including centrality calculations and community detection on the knowledge graph.
- **`decision_tracking`**: Requires both this flag and a valid `knowledge_graph` to instantiate the decision management subsystem.

## Complete Working Example

The following implementation demonstrates a fully configured agent context with memory storage, hybrid retrieval, and decision tracking:

```python
from semantica.context import AgentContext
from semantica.vector_store.faiss_store import FaissStore
from semantica.graph.context_graph import ContextGraph

# Initialize components

vector_store = FaissStore(dim=768)
knowledge_graph = ContextGraph()

# Create configured context

ctx = AgentContext(
    vector_store=vector_store,
    knowledge_graph=knowledge_graph,
    decision_tracking=True,
    advanced_analytics=True,
    graph_expansion=True
)

# Store contextual data

ctx.store(["Document about AI safety guidelines"], extract_entities=True)

# Retrieve with graph enhancement

results = ctx.retrieve("Safety protocols", expand_graph=True)

# Record and analyze a decision

dec_id = ctx.record_decision(
    category=" Risk Assessment",
    scenario="AI Deployment",
    reasoning="Model passes safety benchmarks",
    outcome="proceed",
    confidence=0.95
)

# Analyze influence

influence = ctx.analyze_decision_influence(dec_id)

# Persist entire context

ctx.save("/tmp/agent_context_snapshot")

```

## Summary

- **The `AgentContext` class** in [`semantica/context/agent_context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py) unifies vector storage, knowledge graphs, and decision tracking into a single orchestration layer.
- **Flag-driven initialization** enables advanced features like GraphRAG and causal analysis through simple boolean parameters.
- **Automatic input detection** in the `store()` method handles both single memories and document batches, with optional entity extraction.
- **Hybrid retrieval** automatically combines vector similarity with graph traversal when a knowledge graph is provided, controlled by `expand_graph` and `proximity_weight` parameters.
- **Decision tracking** requires both `decision_tracking=True` and a `knowledge_graph` instance, leveraging [`decision_recorder.py`](https://github.com/semantica-agi/semantica/blob/main/decision_recorder.py) and [`causal_analyzer.py`](https://github.com/semantica-agi/semantica/blob/main/causal_analyzer.py) for provenance management.
- **Lazy component initialization** ensures minimal runtime overhead when advanced features are disabled.

## Frequently Asked Questions

### What is the difference between AgentMemory and AgentContext?

**`AgentMemory`** (defined in [`semantica/context/agent_memory.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_memory.py)) provides low-level CRUD operations for raw text storage and metadata management. **`AgentContext`** is the high-level orchestration class that wraps `AgentMemory` alongside `ContextRetriever`, knowledge graph interfaces, and decision tracking components, offering a unified API for complex agent architectures.

### Can I use AgentContext without a knowledge graph?

Yes. The `knowledge_graph` parameter is optional. When omitted, `AgentContext` operates in pure vector retrieval mode using only the required `vector_store`. Advanced features like GraphRAG, entity linking, and decision tracking require a knowledge graph instance to function.

### How does decision tracking work in AgentContext?

When initialized with `decision_tracking=True` and a valid knowledge graph, the class instantiates `DecisionRecorder` and `CausalChainAnalyzer` components. The `record_decision()` method persists decision metadata to the graph as structured nodes, while `find_precedents_advanced()` and `analyze_decision_influence()` query these structures to establish provenance chains and identify causal factors through graph traversal.

### What file contains the main AgentContext implementation?

The primary implementation resides in **[`semantica/context/agent_context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py)**. Supporting modules include [`semantica/context/agent_memory.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_memory.py) for low-level storage, [`semantica/context/context_retriever.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_retriever.py) for hybrid retrieval logic, and [`semantica/context/decision_recorder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/decision_recorder.py) for decision persistence. The public API exports these through [`semantica/context/__init__.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/__init__.py).