semantica/docs/reference/context.md

title, description, icon

title	description	icon
Context Module	Agent context graphs, decision tracking, causal chains, and precedent search.	brain

The intelligent brain for AI agents, providing memory, decision tracking, and knowledge organization.

---

Overview

The Context Module gives your AI agents the ability to remember, learn, and make smarter decisions through intelligent memory management and knowledge organization.

Human-like memory that stores conversations, learns from experience, and retrieves relevant information when needed. Track decisions, learn from past choices, and make consistent, improving decisions over time. Simple methods that make complex features accessible without overwhelming complexity. Find relevant information using hybrid search that understands context and relationships. Build intelligent knowledge graphs that understand relationships and context. Scalable, reliable, and tested for real-world applications. **Perfect for:** AI agents that need to remember conversations and learn from decisions, chatbots that become smarter with every interaction, and decision systems that need compliance-ready audit trails.

---

AgentContext

The main interface that makes your agent intelligent. Handles memory, decisions, and knowledge organization automatically.

Quick Start

from semantica.context import AgentContext
from semantica.vector_store import VectorStore

agent = AgentContext(vector_store=VectorStore(backend="inmemory", dimension=384))

memory_id = agent.store("User asked about Python programming")
results = agent.retrieve("Python tutorials")

Decision Learning

decision_id = agent.record_decision(
    category="content_recommendation",
    scenario="User wants Python tutorial",
    reasoning="User mentioned being a beginner",
    outcome="recommended_basics",
    confidence=0.85
)

similar_decisions = agent.find_precedents("Python tutorial", limit=3)

Full Setup

agent = AgentContext(
    vector_store=vector_store,
    knowledge_graph=ContextGraph(advanced_analytics=True),
    decision_tracking=True,
    graph_expansion=True,
    advanced_analytics=True,
    kg_algorithms=True,
    vector_store_features=True
)

insights = agent.get_context_insights()

Core Methods

Method	Description
store(content, ...)	Remember information
retrieve(query, ...)	Find relevant memories
record_decision(category, scenario, reasoning, outcome, confidence, ...)	Learn from decisions
find_precedents(scenario, category, ...)	Find similar past decisions
analyze_decision_influence(decision_id)	Analyze downstream impact
get_context_insights()	Get analytics about your agent

GraphRAG with Multi-Hop Reasoning

from semantica.llms import Groq
import os

llm = Groq(model="llama-3.1-8b-instant", api_key=os.getenv("GROQ_API_KEY"))

result = agent.query_with_reasoning(
    query="What technologies work well together?",
    llm_provider=llm,
    max_hops=2
)

print(f"Response: {result['response']}")
print(f"Reasoning: {result['reasoning_path']}")

---

ContextGraph

Organizes complex information and relationships into intelligent knowledge networks.

Building a Knowledge Graph

from semantica.context import ContextGraph

knowledge = ContextGraph(advanced_analytics=True)

knowledge.add_node("Python", "language", properties={"popularity": "high"})
knowledge.add_node("FastAPI", "framework", properties={"language": "Python"})
knowledge.add_edge("Python", "FastAPI", "supports")

Decision Management

decision_id = knowledge.add_decision_simple(
    category="technology_choice",
    scenario="Framework selection for web API",
    reasoning="FastAPI provides better performance for Python APIs",
    outcome="selected_fastapi",
    confidence=0.92,
    entities=["Python", "FastAPI", "web_project"]
)

similar = knowledge.find_precedents_by_scenario(
    scenario="web framework",
    category="technology_choice",
    limit=3
)

impact = knowledge.analyze_decision_impact(decision_id)

Core ContextGraph Methods

Method	Description
add_node(node_id, node_type, properties)	Add concepts to remember
add_edge(source, target, relation)	Connect related concepts
add_decision_simple(category, scenario, reasoning, outcome, confidence, ...)	Record decisions
find_precedents_by_scenario(scenario, category, ...)	Find similar past decisions
analyze_decision_impact(decision_id)	See how decisions affect others
trace_decision_chain(decision_id)	Trace decision connections
check_decision_rules(decision_data)	Validate decisions against policy
find_related_nodes(node_id, how_many)	Discover connections

---

Data Structures

@dataclass
class MemoryItem:
    content: str
    timestamp: datetime
    metadata: Dict
    embedding: List[float]
    entities: List[Dict]

@dataclass
class Decision:
    decision_id: str
    category: str
    scenario: str
    reasoning: str
    outcome: str
    confidence: float        # 0–1
    decision_maker: str
    timestamp: datetime
    entities: List[str]
    metadata: Dict

---

Configuration Options

# Minimal: memory only
agent = AgentContext(vector_store=vector_store)

# Recommended: memory + decision learning
agent = AgentContext(
    vector_store=vector_store,
    decision_tracking=True,
    graph_expansion=True
)

# Full: all features
agent = AgentContext(
    vector_store=vector_store,
    knowledge_graph=ContextGraph(advanced_analytics=True),
    decision_tracking=True,
    graph_expansion=True,
    advanced_analytics=True,
    kg_algorithms=True,
    vector_store_features=True
)

# ContextGraph options
graph = ContextGraph(
    advanced_analytics=True,
    centrality_analysis=True,
    community_detection=True,
    node_embeddings=True
)

---

Real-World Examples

Banking — Loan Decisions

bank_agent = AgentContext(vector_store=bank_vector_store, decision_tracking=True)

bank_agent.store("Customer has credit score 750, stable employment")

loan_decision = bank_agent.record_decision(
    category="loan_approval",
    scenario="First-time homebuyer mortgage",
    reasoning="Good credit score, stable income, 20% down payment",
    outcome="approved",
    confidence=0.94
)

similar_loans = bank_agent.find_precedents("homebuyer", category="loan_approval")

Healthcare — Treatment Decisions

health_agent = AgentContext(vector_store=medical_vector_store, decision_tracking=True)

health_agent.store("Patient has hypertension, type 2 diabetes")
health_agent.store("Patient allergic to penicillin")

treatment_decision = health_agent.record_decision(
    category="treatment_plan",
    scenario="Hypertension with diabetes",
    reasoning="ACE inhibitors safe for diabetic patients",
    outcome="prescribed_ace_inhibitor",
    confidence=0.91
)

---

See Also

Long-term vector storage backend. Knowledge graph algorithms and analytics. Logical inference over context. W3C PROV-O lineage tracking.

Cookbook

• Context Module — practical guide to agent memory and decision tracking · Intermediate
• Advanced Context Engineering — production-grade memory system with FAISS and Neo4j · Advanced
• Decision Tracking with KG Algorithms — decision lifecycle, precedent search, policy compliance · Advanced