tealtiger-hindsight
Importance-weighted governance decision memory using Hindsight — contextual recall and natural decay for AI agent compliance.
Part of the TealTiger ecosystem — deterministic AI agent governance.
What it does
tealtiger-hindsight stores governance decisions with importance-weighted retention:
- 🔴 Critical DENYs (PII detected, secrets blocked) → importance 0.90 → retained for months
- 🟡 Notable MONITORs (flagged but allowed) → importance 0.70 → retained for weeks
- 🟢 Routine ALLOWs (passed all checks) → importance 0.55 → natural decay within days
Enables contextual recall: "what governance decisions were made for this agent in similar situations?" — informing future policy evaluation without overriding deterministic enforcement.
Design Principle
Storage = evidence/continuity, NOT authority.
A stored ALLOW from yesterday cannot authorize today's action. Every new request gets a fresh deterministic evaluation. Storage informs; it doesn't permit.
Installation
pip install tealtiger-hindsight
Quick Start
from hindsight_client import Hindsight
from tealtiger_hindsight import HindsightGovernanceMemory
# Connect to Hindsight
client = Hindsight(base_url="http://localhost:8888")
# Create governance memory
memory = HindsightGovernanceMemory(
client=client,
bank_id="governance",
)
# Store a governance decision (from TealTiger's on_decision callback)
memory.store({
"action": "DENY",
"correlation_id": "dec-001",
"agent_id": "research-agent",
"tool_name": "send_email",
"reason_codes": ["PII_DETECTED:ssn"],
"risk_score": 90,
"mode": "ENFORCE",
})
# Recall past decisions for context
past_decisions = memory.recall(
agent_id="research-agent",
context="tool:send_email",
limit=5,
)
# Reflect on governance patterns
insights = memory.reflect(
agent_id="research-agent",
query="What are the most common denial reasons?"
)
With TealTiger observe()
from tealtiger import observe
from tealtiger_hindsight import HindsightGovernanceMemory
from hindsight_client import Hindsight
from openai import OpenAI
client = Hindsight(base_url="http://localhost:8888")
memory = HindsightGovernanceMemory(client=client)
# Every governance decision auto-stored with importance weighting
llm = observe(
OpenAI(),
guardrails={"pii_detection": True},
on_decision=memory.store,
)
Custom Importance Function
Override the default importance mapping for richer decay behavior:
def custom_importance(decision) -> float:
"""Custom importance: risk_score + recurrence boost."""
base = {"DENY": 0.85, "MONITOR": 0.65, "ALLOW": 0.50}
score = base.get(decision.get("action", "ALLOW"), 0.55)
# Risk contributes but doesn't dominate
risk_boost = (decision.get("risk_score", 0) / 100) * 0.15
# Repeated patterns are more important to remember
if decision.get("is_recurring"):
score += 0.10
return min(score + risk_boost, 1.0)
memory = HindsightGovernanceMemory(
client=client,
importance_fn=custom_importance,
)
How Memory Decay Works
| Decision Type | Default Importance | Retention Behavior |
|---|---|---|
| DENY (PII, secrets) | 0.90 | Persists for months — compliance evidence |
| REFER/REQUIRE_APPROVAL | 0.85 | Persists for weeks — approval tracking |
| MONITOR (flagged) | 0.70 | Weeks — pattern detection baseline |
| ALLOW (routine) | 0.55 | Days — fades from context, doesn't pollute recall |
Hindsight's importance-based memory means routine ALLOWs naturally fade from recall context while critical DENYs remain easily retrievable for compliance audits.
Use Cases
- Contextual governance: Before evaluating a new tool call, recall similar past decisions. If an agent was denied 5 times for PII in web_search results, that context is available.
- Anomaly detection: Query "agents whose denial rate spiked vs. historical baseline" — natural with importance-weighted memory.
- Compliance audits: Critical DENYs persist indefinitely.
recall(min_importance=0.85)retrieves only security-relevant events. - Storage efficiency: Routine ALLOWs decay naturally — no manual cleanup needed.
Requirements
- Python 3.10+
hindsight-client >= 0.4.0- A running Hindsight server (or Hindsight Cloud)
Links
- 📖 TealTiger Docs
- 🧠 Hindsight Docs
- 🐙 GitHub
- 📦 PyPI
- Issue: vectorize-io/hindsight#2284
License
Apache 2.0 — see LICENSE.
Metadata
Release files for tealtiger-hindsight 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tealtiger_hindsight-0.1.0.tar.gz | 8.8 kB | Without provenance | Details for tealtiger_hindsight-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tealtiger_hindsight-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for tealtiger_hindsight-0.1.0-py3-none-any.whl |
Total release size: 17.1 kB
Release files / tealtiger_hindsight-0.1.0.tar.gz
| Download URL | tealtiger_hindsight-0.1.0.tar.gz |
|---|---|
| Size | 8.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
604246b55ba515187daf644b8a55df15bfe27be55ab8ce7fe505395aec167098
|
|
BLAKE2b-256 checksum How to use checksums |
e3bbf31c54c4a6bee813361142c9b896ea08c907afd5d122629776348fa2a295
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Release files / tealtiger_hindsight-0.1.0-py3-none-any.whl
| Download URL | tealtiger_hindsight-0.1.0-py3-none-any.whl |
|---|---|
| Size | 8.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7da318312372d7419df7df5d0ca8aef501b9e8cb91aeaf638f9a0514bbe06c61
|
|
BLAKE2b-256 checksum How to use checksums |
c28ec7d605b97e3e9a00c79fe04fbbdb892e54f04cd3afa04d5b4d4b5fe6432f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.2
|
Security for tealtiger-hindsight 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.