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

> Learn to build agent memory pipelines using Semantica's AgentContext. Integrate vector storage, knowledge graphs, and decision tracking effortlessly for powerful AI agents.

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

---

**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](https://github.com/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/agent_context.py) lines 69-96 |
| **ContextRetriever** | Hybrid RAG/GraphRAG retrieval engine | [`agent_context.py`](https://github.com/semantica-agi/semantica/blob/main/agent_context.py) lines 98-108 |
| **EntityLinker** | Resolves text mentions to graph entities | [`agent_context.py`](https://github.com/semantica-agi/semantica/blob/main/agent_context.py) lines 81-82 |
| **Decision-Tracking Stack** | Records decisions, finds precedents, causal analysis | [`agent_context.py`](https://github.com/semantica-agi/semantica/blob/main/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

```python
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:

```python
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:

```python
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`:

```python
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):

```python
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:

```python
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`](https://github.com/semantica-agi/semantica/blob/main/agent_context.py).

---

## Manual Graph Construction

For scenarios requiring explicit graph building from raw data:

```python
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:

```python
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:

```python
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:

```python
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`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py) | Central orchestrator with `store`, `retrieve`, `link`, `record_decision` |
| [`semantica/context/agent_memory.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_memory.py) | Vector store wrapper with metadata CRUD |
| [`semantica/context/context_retriever.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_retriever.py) | Hybrid GraphRAG with score merging |
| [`semantica/context/entity_linker.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/entity_linker.py) | Text-to-entity resolution |
| [`semantica/context/decision_recorder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/decision_recorder.py) | Decision persistence to graph |
| [`semantica/context/decision_query.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/decision_query.py) | Precedent search and analytics |
| [`semantica/context/causal_analyzer.py`](https://github.com/semantica-agi/semantica/blob/main/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.