How to Record and Analyze AI Decisions in Semantica: A Complete Developer Guide

Semantica provides a dual-layer decision intelligence stack that persists AI decisions in a Knowledge Graph for causal tracing and indexes them in a Vector Store for semantic similarity search, precedent analysis, and impact assessment.

Recording and analyzing AI decisions in Semantica relies on a unique architecture that combines graph-based persistence with vector embedding search. According to the semantica-agi/semantica source code, the system captures every decision as a first-class node in a Knowledge Graph while simultaneously embedding decisions for fast, hybrid retrieval via the Vector Store layer.

Understanding Semantica's Dual-Layer Architecture

Semantica splits decision intelligence across two specialized layers that work in tandem to provide both durable persistence and fast analytical queries.

Knowledge Graph Layer (Persistence)

The Knowledge Graph (KG) layer persists every decision as a node linked to entities, policies, and causal relationships. Implementation lives primarily in semantica_mcp/mcp/tools/decisions.py, where the handle_record_decision function orchestrates the persistence flow. This layer handles input validation, node creation, and conditional persistence based on the SEMANTICA_KG_PATH environment variable.

Vector Store Layer (Analysis)

The Vector Store layer provides fast hybrid similarity search, batch processing, and explanation capabilities through embedded decision vectors. High-level convenience functions such as find_precedents, explain, and quick_decision reside in semantica/vector_store/decision_vector_methods.py and delegate to configurable backends like FAISS or Weaviate.

Recording AI Decisions

When recording a decision, Semantica validates required fields, creates a graph node, and optionally persists to disk. The handle_record_decision function in semantica_mcp/mcp/tools/decisions.py enforces mandatory fields: category, scenario, reasoning, outcome, and confidence.

The workflow proceeds through four stages:

1. Input validation – checks required fields
2. Graph acquisition – get_graph() retrieves the singleton KG instance
3. Node creation – graph.record_decision() stores the decision and returns a unique decision_id
4. Persistence – if SEMANTICA_KG_PATH is set and is_persistence_safe() returns true, the graph saves to disk; otherwise the mutation rolls back to maintain consistency

For application developers, the DecisionContext class in semantica/context/decision_context.py provides a simplified interface:

from semantica.context.decision_context import DecisionContext

ctx = DecisionContext()
decision_id = ctx.record_decision(
    category="credit",
    scenario="Approve loan for applicant X",
    reasoning="Credit score 750, low debt-to-income",
    outcome="approved",
    confidence=0.94,
    entities=["Applicant X", "Bank"],
)
print(f"Decision recorded with ID: {decision_id}")

Querying and Retrieving Decisions

Semantica offers two primary retrieval modes depending on your query pattern.

Natural-language search uses query_decisions, which delegates to graph.find_similar_decisions to perform semantic matching against decision text.

Structured filters apply category, outcome, or entity constraints to refine result sets after initial retrieval:

results = ctx.query_decisions(category="credit", limit=5)
for d in results["decisions"]:
    print(d["decision_id"], d["outcome"])

Finding Precedents with Hybrid Similarity

The find_precedents function in semantica/vector_store/decision_vector_methods.py enables case-based reasoning by retrieving historically similar decisions using hybrid weights that balance semantic meaning against structural graph features.

The function signature supports tuning the relevance algorithm:

from semantica.vector_store.decision_vector_methods import find_precedents

precedents = find_precedents(
    query="Approve loan for applicant X",
    limit=3,
    semantic_weight=0.8,
    structural_weight=0.2,
    category="credit"
)
for p in precedents:
    print(p["decision_id"], p["score"])

Higher semantic_weight prioritizes vector embedding similarity, while structural_weight emphasizes graph topology and relationship proximity.

Explaining, Tracing, and Analyzing Impact

Beyond retrieval, Semantica provides tools for decision interpretability and downstream impact analysis through three core functions.

Generating explanations – The explain function retrieves explanation data including reasoning paths, confidence scores, and similarity weights:

from semantica.vector_store.decision_vector_methods import explain

explanation = explain(decision_id, include_paths=True, include_confidence=True)
print(explanation)

Tracing causal chains – get_causal_chain follows decision dependencies upstream or downstream. According to semantica_mcp/mcp/tools/decisions.py, this attempts to use CausalChainAnalyzer when available, falling back to the graph's native get_causal_chain method:

chain = ctx.get_causal_chain(decision_id=decision_id, direction="downstream", max_depth=4)
print(chain)

Analyzing decision impact – analyze_decision_impact computes downstream effects across the Knowledge Graph by calling graph.analyze_decision_impact (or the legacy analyze_decision_influence):

impact = ctx.analyze_decision_impact(decision_id=decision_id)
print(impact)

Configuring the Vector Store Backend

Before using vector-based analysis methods, initialize the global vector store once per process. The set_global_vector_store function in semantica/vector_store/decision_vector_methods.py registers the backend that all convenience functions will use:

from semantica.vector_store.decision_vector_methods import set_global_vector_store
from semantica.vector_store.weaviate_store import WeaviateVectorStore

store = WeaviateVectorStore(endpoint="http://localhost:8080")
set_global_vector_store(store)

Once configured, utilities like quick_decision, similar_to, batch_decisions, and stats automatically utilize this store for embedding and retrieval operations.

Summary

• Dual-layer persistence: Semantica stores decisions in a Knowledge Graph (semantica_mcp/mcp/tools/decisions.py) for causal relationships and a Vector Store (semantica/vector_store/decision_vector_methods.py) for similarity search.
• Recording workflow: Use DecisionContext.record_decision() with mandatory fields (category, scenario, reasoning, outcome, confidence) to generate unique decision IDs with optional disk persistence via SEMANTICA_KG_PATH.
• Hybrid search: find_precedents combines semantic and structural weights to surface relevant historical decisions.
• Traceability: Functions like get_causal_chain and analyze_decision_impact trace downstream effects and policy changes across the graph.
• Setup requirement: Initialize the global vector store with set_global_vector_store() before calling embedding-based analysis methods.

Frequently Asked Questions

How does Semantica ensure decision data persists across restarts?

The Knowledge Graph layer checks for the SEMANTICA_KG_PATH environment variable after recording a decision. If set and is_persistence_safe() returns true, handle_record_decision calls graph.save_to_file(kg_path) to write the mutated graph to disk. Without this variable, decisions remain in memory only and roll back if persistence fails.

What is the difference between query_decisions and find_precedents?

query_decisions operates on the Knowledge Graph layer and performs natural-language similarity matching through graph.find_similar_decisions, suitable for broad semantic searches. find_precedents targets the Vector Store layer and constructs hybrid queries combining semantic embedding similarity with structural graph weights, optimized for case-based reasoning and legal precedent analysis.

Can I adjust how much weight Semantica gives to semantic meaning versus graph structure?

Yes. Both find_precedents and underlying vector store methods accept semantic_weight and structural_weight parameters (0.0–1.0 scale) that control the hybrid scoring algorithm. A semantic_weight of 0.8 and structural_weight of 0.2 prioritizes text meaning over relationship topology, while inverse values emphasize causal chain proximity.

Which file contains the JSON schemas for decision tool inputs?

The input shapes and validation schemas for all MCP decision tools are defined in semantica_mcp/mcp/schemas.py. This file specifies required fields, data types, and constraints for operations like record_decision, query_decisions, and find_precedents.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}