DriftGuard
DriftGuard is a semantic mistake-memory and guardrail layer for autonomous agents. It stores failures as causal chains and retrieves them by meaning, not string match, to warn agents before they repeat past mistakes. It is for developers building agents that need to avoid repeating semantically similar failures.
✨ Key features
- Stores failures as causal chains (action → feedback → outcome).
- Retrieves similar past mistakes by semantic meaning, not text.
- Dual-graph design: separate mistake and success memories.
- Policies: warn, block, acknowledge, record_only.
- Pluggable storage backends: JSON, SQLite, Postgres.
- MCP integration for Claude Desktop and other clients.
🎯 Use cases
- Prevent agents from repeating failed actions phrased differently.
- Provide cited warnings before executing risky steps.
- Reinforce successful strategies with similar past successes.
- Integrate with LangGraph as a review node.
- Use as a guardrail in MCP-based agent workflows.
📦 Installation
🧰 Requirements: Python environment; requires installing spaCy model en_core_web_sm via command line; optional extras for test, demo, and Postgres.
pip install driftguard-ai
python -m spacy download en_core_web_sm
Optional extras:
pip install "driftguard-ai[test]" # pytest
pip install "driftguard-ai[demo]" # LangGraph + langchain-openai demo
pip install "driftguard-ai[postgres]" # SQLAlchemy + psycopg
🚀 Usage
from driftguard import DriftGuard
guard = DriftGuard()
# 1. Ask before acting
review = guard.before_step("retry the payment webhook with the same payload")
for warning in review.warnings:
print(f"⚠️ {warning.trigger} → {warning.risk} (confidence {warning.confidence:.2f})")
for reinforcement in review.reinforcements:
print(f"✅ {reinforcement.trigger} → {reinforcement.recommendation}")
# 2. Tell it what happened
guard.record(
action="retry the payment webhook with the same payload",
feedback="server returned 422 again",
outcome="duplicate charge risk, run aborted",
)
⚠️ Good to know
The base install pulls sentence-transformers (and PyTorch) and spaCy, resulting in a multi-gigabyte environment; making the embedding backend pluggable is on the roadmap.
❓ FAQ
How does DriftGuard prevent repeating mistakes?
It stores failures as causal chains and retrieves them by semantic similarity. Before an action, it checks if a similar action has failed before and returns warnings with confidence scores.
What is the dual-graph design?
DriftGuard keeps two independent graphs: one for mistakes and one for successes. They share engine instances but never share nodes or storage, so recording a mistake cannot weaken a success memory.
What policies are available?
Policies include warn, block, acknowledge, and record_only. They control whether DriftGuard returns warnings, raises exceptions, or skips review.
What storage backends are supported?
JSON, SQLite, and Postgres are supported. Postgres requires installing the optional extra 'driftguard-ai[postgres]'.
📊 Repository
🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.