# How to Use AgentContext for Storing and Retrieving Information in Semantica

> Learn to use AgentContext in Semantica to store text, documents, and decisions in a vector store and memory. Retrieve information efficiently with configurable hybrid search.

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

---

**Call `AgentContext.store()` to persist text, documents, or decisions to the vector store and memory, then use `AgentContext.retrieve()` to query them with configurable hybrid (vector + graph) search.**

The [`AgentContext`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py) class serves as the primary interface for memory management in the [semantica-agi/semantica](https://github.com/semantica-agi/semantica) framework. It abstracts the complexity of vector stores, knowledge graphs, and retrieval algorithms into simple methods for **storing and retrieving information**. By composing specialized components like [`AgentMemory`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_memory.py) and [`ContextRetriever`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_retriever.py), the class enables both basic persistence and advanced GraphRAG workflows without exposing underlying implementation details.

## Initializing AgentContext

Before storing or retrieving data, instantiate the class with a vector store and optional knowledge graph. Boolean flags activate advanced features such as decision tracking and graph analytics.

```python
from semantica.context import AgentContext

# Basic initialization with only vector storage

ctx = AgentContext(vector_store=my_vector_store)

# Advanced initialization with knowledge graph and decision tracking

ctx = AgentContext(
    vector_store=my_vector_store,
    knowledge_graph=my_kg,
    decision_tracking=True,
    kg_algorithms=True,
    graph_expansion=True,
    hybrid_alpha=0.6  # 60% graph weight, 40% vector weight

)

```

## Storing Information with `store()`

The [`store()`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py) method in [`semantica/context/agent_context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py) accepts raw text or document objects and automatically detects the content type. It delegates persistence to [`AgentMemory`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_memory.py) while extracting entities and relationships when a knowledge graph is present.

```python

# Store a user utterance as a memory entry

mem_id = ctx.store(
    "User asked about the benefits of Python decorators",
    conversation_id="conv_42",
    metadata={"topic": "python", "complexity": "intermediate"}
)

# Store returns a unique identifier for later reference

print(f"Stored with ID: {mem_id}")

```

For structured decision records, use the dedicated `record_decision()` method when `decision_tracking` is enabled. This writes to [`DecisionRecorder`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/decision_recorder.py) and links the decision to the knowledge graph for provenance tracking.

```python
decision_id = ctx.record_decision(
    category="approval",
    scenario="Loan application",
    reasoning="Applicant has strong credit history",
    outcome="approved",
    confidence=0.94
)

```

## Retrieving Information with `retrieve()`

The [`retrieve()`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py) method performs **hybrid retrieval**, combining semantic similarity from the vector store with structural cues from the knowledge graph. It delegates the actual query execution to [`ContextRetriever`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_retriever.py), which blends scores based on the `hybrid_alpha` parameter (0.0 = pure vector, 1.0 = pure graph).

```python

# Retrieve relevant context for a new query

results = ctx.retrieve(
    "Explain how decorators work in Python",
    top_k=5,
    graph_expansion=True  # Follow graph edges to expand context

)

for hit in results:
    print(f"Content: {hit['content']}")
    print(f"Score: {hit['metadata']['score']}")

```

## Advanced Decision Analytics

When `decision_tracking=True`, the context exposes additional methods powered by [`DecisionQuery`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/decision_query.py) and [`CausalChainAnalyzer`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/causal_analyzer.py). These enable governance workflows such as finding precedent decisions and analyzing causal influence chains.

```python

# Find similar past decisions using KG-enhanced features

precedents = ctx.find_precedents_advanced(
    query="Loan application",
    category="approval",
    use_kg_features=True,
    top_k=10
)

# Analyze the causal influence of a specific decision

influence = ctx.analyze_decision_influence(decision_id)
print(f"Decision influenced {len(influence['downstream'])} subsequent actions")

```

## Key Source Files

The **storing and retrieving** pipeline is implemented across the following modules:

- [[`semantica/context/agent_context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py)](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py) – Central class exposing `store()`, `retrieve()`, and decision-tracking APIs.
- [[`semantica/context/agent_memory.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_memory.py)](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_memory.py) – Implements memory persistence, retention policies, and basic vector-store interactions.
- [[`semantica/context/context_retriever.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_retriever.py)](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_retriever.py) – Handles hybrid RAG/GraphRAG queries, graph expansion, and score blending.
- [[`semantica/context/decision_recorder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/decision_recorder.py)](https://github.com/semantica-agi/semantica/blob/main/semantica/context/decision_recorder.py) – Records decisions and metadata into the knowledge graph.
- [[`semantica/context/decision_query.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/decision_query.py)](https://github.com/semantica-agi/semantica/blob/main/semantica/context/decision_query.py) – Provides enriched search over decisions using knowledge graph algorithms.
- [[`semantica/context/causal_analyzer.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/causal_analyzer.py)](https://github.com/semantica-agi/semantica/blob/main/semantica/context/causal_analyzer.py) – Analyzes decision causality and influence chains.
- [[`semantica/context/policy_engine.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/policy_engine.py)](https://github.com/semantica-agi/semantica/blob/main/semantica/context/policy_engine.py) – Enforces governance policies on stored decisions.

## Summary

- **Initialize** [`AgentContext`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py) with a `vector_store` and optional `knowledge_graph` to enable storage and retrieval.
- **Store** raw text or documents using `store()`, which automatically handles content detection and entity extraction.
- **Retrieve** relevant context using `retrieve()`, tuning the `hybrid_alpha` and `graph_expansion` parameters to balance vector similarity against graph structure.
- **Track decisions** by setting `decision_tracking=True` and using `record_decision()` for full provenance and causal analysis.

## Frequently Asked Questions

### What is the difference between `store()` and `record_decision()` in AgentContext?

The `store()` method is designed for general text and document persistence, automatically routing data to [`AgentMemory`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_memory.py) and the vector store. The `record_decision()` method is a specialized interface for governance workflows that writes structured decision metadata to [`DecisionRecorder`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/decision_recorder.py) and links decisions into the knowledge graph for provenance tracking and causal analysis.

### How does hybrid retrieval balance vector search and graph traversal?

Hybrid retrieval is implemented in [`ContextRetriever`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_retriever.py) using the `hybrid_alpha` parameter. A value of 0.0 weights results purely by vector embedding similarity, while 1.0 weights purely by graph connectivity and centrality. Intermediate values blend both scores to surface contextually relevant information that is both semantically similar and structurally significant within the knowledge graph.

### Is a knowledge graph required to use AgentContext?

No. The `knowledge_graph` parameter is optional. If omitted, [`AgentContext`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py) operates in vector-only mode, using [`AgentMemory`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_memory.py) for storage and standard semantic search for retrieval. Knowledge graph features like `graph_expansion` and `kg_algorithms` are automatically disabled when no graph is provided.

### Which file handles the actual vector storage operations?

Vector storage operations are delegated to [`AgentMemory`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_memory.py) in [`semantica/context/agent_memory.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_memory.py). This module manages the persistence layer, retention policies, and basic CRUD operations for the vector store backend, while [`AgentContext`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py) provides the high-level orchestration.