hga 0.1.0

Hybrid Governance Architecture — Multi-layer agent memory system with vector quantization, deterministic vault, and semantic neuron routing

HGA — Hybrid Governance Architecture

A multi-layer agent memory system that provides intelligent query routing, exact recall, and semantic neuron maturation for LLM-based agents.

Features

• L1 — RM (Routing Memory: A Vector-Quantization-Based Retrieval Primitive): Vector quantization with K-means centroids, multi-probe retrieval, online EMA adaptation, and drift detection
• L2 — Deterministic Vault: Exact key-value recall with SHA-256 integrity verification, policy tagging (Public/Internal/Sensitive/Restricted), and full audit trails
• L3 — Semantic Neuron Layer: 4-stage neuron maturation (Stage 0→3), causal reasoning chains, structural similarity transfer, and safe Stage 3 replay
• Governance Gate: Intelligent routing across 5 execution paths based on confidence, margin, neuron maturity, and sensitivity
• Consolidation: Active trace writing + passive LLM-free capability growth (co-occurrence mining, edge finalization, RM reshaping)
• Real Embeddings: Uses all-MiniLM-L6-v2 (384-dimensional) — no mock or synthetic embeddings

Installation

pip install hga-memory

With LLM provider support:

# Groq
pip install hga-memory[groq]

# OpenAI
pip install hga-memory[openai]

# Everything
pip install hga-memory[all]

Quick Start

from hga import AgentMemory

# Initialize memory system
memory = AgentMemory()

# Store information
memory.store("Project deadline is March 15, 2026", policy_tag="Internal")
memory.store("API key format: sk-xxxx", policy_tag="Sensitive")

# Query with automatic routing
result = memory.recall("When is the project deadline?")
print(result.answer)
print(f"Path: {result.path}, Tokens: {result.tokens_used}")

# The gate automatically routes:
# - Exact facts → Deterministic Vault (0 tokens)
# - Semantic queries → RM retrieval
# - Mature patterns → Stage 3 replay (0 tokens)
# - Sensitive queries → Deterministic path (safe)

Architecture

Query → Governance Gate → Route Decision
              │
              ├── Stage0Path    → Full LLM call (new pattern)
              ├── FastSemantic  → L1 retrieval + LLM
              ├── VerifyPath    → L1 + L3 verify + LLM
              ├── Stage3Path    → Causal replay (no LLM)
              └── Deterministic → L2 exact lookup (no LLM)

Gate Decision Logic

Condition	Path
Sensitivity=High OR edge weight < -1	DeterministicPath
Stage 3 + confidence >= 0.6	Stage3Path
Stage 2 + confidence >= 0.6 + margin >= 0.1	VerifyPath
Stage >= 1 + confidence >= 0.6	FastSemanticPath
No matching neuron	Stage0Path

Neuron Maturation

Neurons progress through 4 stages based on successful executions:

• Stage 0→1: weight > 0, 3+ successful hits
• Stage 1→2: weight > +2, 8+ hits
• Stage 2→3: weight > +2.5, 5 consecutive clean executions

Edge weights update: w += source_weight × outcome (clipped to [-3, +3])

Configuration

Parameter	Default	Description
K	64	Number of RM centroids
ALPHA	0.6	Confidence threshold
DELTA_MIN	0.1	Margin threshold
eta	0.01	EMA learning rate
embedding_dim	384	Embedding dimensionality

License

MIT