# How to Implement Multi-Agent Shared Memory with AgentContext in Semantica

> Learn to implement multi-agent shared memory using AgentContext in Semantica. This façade unifies short-term memory, vector embeddings, and knowledge graphs for seamless agent collaboration.

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

---

**AgentContext acts as a high-level façade that coordinates short-term memory, vector embeddings, and knowledge-graph structures to provide unified shared memory accessible by multiple agents in the same system.**

The `semantica-agi/semantica` repository provides a robust framework for building multi-agent systems with persistent, queryable memory. At the center of this architecture sits **AgentContext**, a coordination layer that unifies vector storage, graph relationships, and decision tracking into a single interface that any agent instance can share.

## Architecture of the Shared Memory System

The shared memory implementation relies on three coordinated components defined in [`semantica/context/agent_context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py) and its dependencies.

### AgentMemory: The Core Storage Layer

The **AgentMemory** class, implemented in [`semantica/context/agent_memory.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_memory.py), manages the lifecycle of individual memory items. It maintains a **short-term deque** for recent context, persists embeddings to a configurable vector store, and optionally pushes extracted entities and relationships to a knowledge graph when one is supplied.

### ContextRetriever: Hybrid GraphRAG Retrieval

When a knowledge graph is present, **ContextRetriever** (located in [`semantica/mcp/tools/graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/tools/graph.py)) performs hybrid **GraphRAG** retrieval. It first queries the vector store for semantic matches, then expands results over the graph using configurable hop distances. The `hybrid_alpha` parameter balances vector similarity (weighted toward 0) against graph distance (weighted toward 1) in the final ranking.

### AgentContext: The Coordination Facade

**AgentContext** glues these pieces together. During construction, you provide a required vector store and an optional knowledge graph instance. Boolean flags such as `decision_tracking`, `kg_algorithms`, and `graph_expansion` toggle advanced features including decision provenance and causal-chain analysis.

## Implementing the Shared-Memory Workflow

To enable multi-agent shared memory, instantiate a single **AgentContext** and distribute references across your agent fleet.

### Step 1: Initialize Shared Components

First, configure the vector store and optional knowledge graph. The following example uses FAISS for vector storage and a custom ContextGraph for the knowledge base.

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

# Create a persisted vector store

vector_store = FaissVectorStore(dim=768, persist_path="faiss_index")

# Optional: initialize a knowledge graph supporting add_nodes/add_edges

knowledge_graph = ContextGraph()

```

### Step 2: Configure AgentContext

Build the shared context instance that all agents will reference. Enable graph expansion and decision tracking to support advanced multi-agent coordination.

```python
shared_context = AgentContext(
    vector_store=vector_store,
    knowledge_graph=knowledge_graph,
    retention_days=60,
    max_memories=20000,
    graph_expansion=True,
    hybrid_alpha=0.6,  # Favor graph signals slightly

    decision_tracking=True,
)

```

### Step 3: Store Memories for Multi-Agent Access

The `store()` method accepts raw text, document lists, or dictionaries with metadata. When storing a single string, the call forwards to `AgentMemory.store()`, which writes to the short-term buffer, persists the embedding, and updates the KG if present. When storing document batches, the method normalizes entries and optionally builds graph structures.

```python

# Store a single observation visible to all agents

mem_id = shared_context.store(
    "User asked how to calibrate a CNC lathe",
    conversation_id="conv_42",
    metadata={"type": "question", "domain": "manufacturing"},
)

# Store batch documents with entity extraction

docs = [
    {"content": "Lathe calibration steps …", "metadata": {"source": "wiki"}},
    {"content": "Safety checklist for CNC machines", "metadata": {"source": "internal"}},
]
stats = shared_context.store(
    docs, 
    extract_entities=True, 
    extract_relationships=True
)
print(f"Stored {stats['stored_count']} documents; graph nodes={stats['graph_nodes']}")

```

### Step 4: Retrieve Context with Hybrid GraphRAG

The `retrieve()` method automatically detects whether to use pure vector RAG or hybrid GraphRAG. If a knowledge graph is configured and a `ContextRetriever` exists, it merges vector results with graph proximity data using the `hybrid_alpha` weighting factor.

```python
results = shared_context.retrieve(
    query="What safety measures are required before calibrating a lathe?",
    max_results=5,
    proximity_weight=0.3,  # Blend graph distance into final score

    anchor_node="lathe",   # Prioritize nodes close to "lathe"

)

for r in results:
    print(f"[{r['score']:.2f}] {r['content']} (source={r['source']})")

```

### Step 5: Enable Decision Tracking Across Agents

When `decision_tracking=True` and a knowledge graph is supplied, **AgentContext** initializes **DecisionRecorder**, **DecisionQuery**, **CausalChainAnalyzer**, and **PolicyEngine** from [`semantica/mcp/tools/decisions.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/tools/decisions.py). Any agent can record decisions and query precedents.

```python

# Record a decision visible to all agents

decision_id = shared_context.record_decision(
    category="approval",
    scenario="lathe calibration",
    reasoning="All safety checks passed",
    outcome="approved",
    confidence=0.97,
)

# Query precedents from any agent instance

precedents = shared_context.find_precedents_advanced(
    "lathe calibration",
    category="approval",
    use_kg_features=True,
)

```

## Key Configuration Parameters

Understanding these parameters is essential for tuning multi-agent memory performance:

- **hybrid_alpha**: Float between 0 and 1 that balances vector similarity against graph distance in retrieval ranking. Values closer to 1 prioritize graph structure over semantic similarity.
- **graph_expansion**: Boolean flag enabling neighborhood expansion up to `max_expansion_hops` during retrieval.
- **decision_tracking**: Boolean that activates the decision provenance system, enabling causal-chain analysis and policy governance across agents.

## Summary

- **AgentContext** in [`semantica/context/agent_context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py) provides the unified interface for multi-agent shared memory.
- The system combines **AgentMemory** for short-term buffering and vector persistence with **ContextRetriever** for hybrid GraphRAG.
- Shared instances of the underlying vector store and knowledge graph ensure all agents access identical memory states.
- `decision_tracking` enables cross-agent decision provenance using components from [`semantica/mcp/tools/decisions.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/tools/decisions.py).
- Configuration parameters like `hybrid_alpha` and `graph_expansion` control the trade-off between semantic search and structured graph reasoning.

## Frequently Asked Questions

### How does AgentContext ensure consistency across multiple agents?

Consistency is achieved by sharing the same underlying **AgentMemory** and vector store instances among all agents. Because `AgentContext` acts as a façade to these shared resources, any write operation from one agent immediately becomes visible to others accessing the same context instance.

### What is the difference between vector-only and hybrid GraphRAG retrieval?

Vector-only retrieval searches semantic embeddings directly in the configured vector store. Hybrid **GraphRAG**, enabled when a knowledge graph is present, first retrieves vector matches then expands results over graph relationships using **ContextRetriever**. The `hybrid_alpha` parameter controls the weighting between vector similarity scores and graph proximity distances in the final result set.

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

Yes. The knowledge graph parameter is optional. Without it, **AgentContext** defaults to pure vector retrieval via **AgentMemory** methods, bypassing the **ContextRetriever** graph expansion logic while maintaining full short-term and long-term memory functionality.

### How does decision tracking work in a multi-agent environment?

When `decision_tracking=True`, **AgentContext** initializes **DecisionRecorder** and **DecisionQuery** components from [`semantica/mcp/tools/decisions.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/mcp/tools/decisions.py). Any agent can call `record_decision()` to persist reasoning steps and outcomes to the shared graph. Other agents then use `find_precedents_advanced()` to query historical decisions, enabling causal-chain analysis and consistent policy application across the agent fleet.