Sgraal Documentation
Memory Governance Protocol — preflight validation for AI agents.
Key Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /v1/preflight | Score memory state, return decision + full analytics |
| POST | /v1/preflight/batch | Batch preflight for up to 100 entries |
| POST | /v1/heal | Heal a flagged memory entry |
| POST | /v1/outcome | Close an outcome for learning feedback |
| GET | /v1/verify | Formal verification of healing policies |
All endpoints require Authorization: Bearer <api_key>
Quick Start — 5 minutes
1. Get your demo key
No signup required:
2. Choose your integration
{
"mcpServers": {
"sgraal": {
"command": "npx",
"args": ["-y", "@sgraal/mcp"],
"env": { "SGRAAL_API_KEY": "sg_demo_playground" }
}
}
}
pip install sgraal
from sgraal import SgraalClient
client = SgraalClient(api_key="sg_demo_playground")
result = client.preflight(
memory_state=[{
"id": "mem_001", "type": "tool_state",
"timestamp_age_days": 54, "source_trust": 0.6
}],
action_type="irreversible",
domain="fintech"
)
print(result.recommended_action) # BLOCK
print(result.omega_mem_final) # 78.4
npm install @sgraal/sdk
const { SgraalClient } = require('@sgraal/sdk');
const client = new SgraalClient({ apiKey: 'sg_demo_playground' });
const result = await client.preflight({
memory_state: [{ id: 'mem_001', type: 'tool_state',
timestamp_age_days: 54, source_trust: 0.6 }],
action_type: 'irreversible', domain: 'fintech'
});
console.log(result.recommended_action); // BLOCK
curl -X POST https://api.sgraal.com/v1/preflight \
-H "Authorization: Bearer sg_demo_playground" \
-H "Content-Type: application/json" \
-d '{
"memory_state": [{"id": "mem_001", "type": "tool_state",
"timestamp_age_days": 54, "source_trust": 0.6}],
"action_type": "irreversible", "domain": "fintech"
}'
3. Interpret the response
{
"recommended_action": "BLOCK",
"omega_mem_final": 78.4,
"confidence": 0.94,
"explanation": "Memory entry mem_001 is 54 days old...",
"repair_plan": [{ "id": "mem_001", "action": "REFRESH" }],
"compliance_result": { "compliant": false },
"timestamp_integrity": "VALID",
"timestamp_flags": [],
"identity_drift": "CLEAN",
"identity_drift_flags": [],
"consensus_collapse": "CLEAN",
"consensus_collapse_flags": [],
"collapse_ratio": 0.0,
"attack_surface_score": 0.0,
"attack_surface_level": "NONE",
"active_detection_layers": [],
"detection_feedback_applied": false,
"provenance_chain_integrity": "CLEAN",
"provenance_chain_flags": [],
"chain_depth": 0,
"naturalness_score": 0.94,
"naturalness_level": "ORGANIC",
"vaccination_match": false,
"memory_locations_present": false,
"auto_profile_selected": true
}
Core Concepts
omega_mem_final
Risk score 0–100. Combines freshness decay, source trust, conflict detection, provenance, and commercial intent.
Action Types
Multiplier applied to base omega score:
Detection Layers (Rounds 6–8)
Three independent post-reconciliation detection layers. Each fires independently. MANIPULATED always forces BLOCK.
MemCube v2 — Memory Entry Schema
The standardized format for AI agent memory entries. All Sgraal endpoints accept MemCube v2 formatted memory states.
Required Fields
| Field | Type | Description |
|---|---|---|
| id | string | Unique identifier |
| content | string | Memory content text |
| type | enum | One of 7 memory types |
| timestamp_age_days | float | Age in days |
| source_trust | float 0-1 | Source reliability score |
| source_conflict | float 0-1 | Contradiction level |
| downstream_count | int | Number of dependent agents |
Memory Types
Example
{
"id": "mem_001",
"content": "User prefers wire transfers under $10,000",
"type": "preference",
"timestamp_age_days": 14,
"source_trust": 0.91,
"source_conflict": 0.04,
"downstream_count": 3
}
Full JSON Schema → api.sgraal.com/v1/standard/memcube-spec
SMRS v1.0 — Memory Risk Score
Formal 0-100 risk score computed from 10 components. Determines the preflight decision.
Decision Thresholds
| Range | Decision | Meaning |
|---|---|---|
| 0–25 | USE_MEMORY | Safe to proceed |
| 25–50 | WARN | Proceed with caution |
| 50–75 | ASK_USER | Human approval needed |
| 75–100 | BLOCK | Do not proceed |
10 Components
s_freshness
s_drift
s_provenance
s_propagation
r_recall
r_encode
s_interference
s_recovery
r_belief
s_relevance
Standard body: Sgraal Governance Working Group · Version: SMRS v1.0
Full definition → api.sgraal.com/v1/standard/score-definition
SDK Quick Reference
pip install sgraal # Core Python SDK pip install langchain-sgraal # LangChain integration pip install mem0-sgraal # mem0 integration pip install openai-sgraal # OpenAI Agents SDK hook pip install crewai-sgraal # CrewAI memory guard pip install autogen-sgraal # AutoGen middleware pip install sgraal-rag # RAG pipeline filter npm install @sgraal/mcp # Claude Desktop + Cursor + Windsurf
Authentication
Authorization: Bearer sg_demo_playground
Demo
Public key, rate limited. No signup needed.
Pro
From app.sgraal.com. $0.001/call after 10K.
Enterprise
Custom limits, compliance, SLA.
MCP Setup
Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible host.
{
"mcpServers": {
"sgraal": {
"command": "npx",
"args": ["-y", "@sgraal/mcp"],
"env": { "SGRAAL_API_KEY": "sg_demo_playground" }
}
}
}
Add to ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.
All SDKs
Python
pip install sgraalCore SDK — preflight, heal, explain, compare
LangChain
pip install langchain-sgraalDrop-in memory validator
mem0
pip install mem0-sgraalPreflight hook for mem0 memories
OpenAI Agents SDK
pip install openai-sgraalPreflight hook for message history
CrewAI
pip install crewai-sgraalDrop-in memory guard for CrewAI agents
AutoGen
pip install autogen-sgraalContext validation middleware for AutoGen
RAG Filter
pip install sgraal-ragPipeline filter for LangChain and LlamaIndex
MCP Server
npm install @sgraal/mcpClaude Desktop, Cursor, Windsurf
Webhooks
Sgraal sends a POST to your endpoint for every BLOCK, WARN, or ASK_USER decision.
{
"event": "decision.block",
"timestamp": "2026-03-30T23:00:00Z",
"agent_id": "agent_001",
"omega": 78.4,
"action": "BLOCK",
"domain": "fintech",
"repair_plan": [{ "id": "mem_001", "action": "REFRESH" }]
}
decision.block
Agent blocked
decision.warn
Memory flagged
memory.healed
Repair executed
Rate Limits
Demo
100
requests / minute
10,000 decisions / month total
Pro
1,000
requests / minute
Unlimited decisions / month
Enterprise
Custom
requests / minute
Dedicated capacity, SLA
Rate limit headers
X-RateLimit-Limit: 100 X-RateLimit-Remaining: 87 X-RateLimit-Reset: 1711843200 Retry-After: 13 # only on 429
Compliance Profiles
EU_AI_ACT
Article 9, 12, 13, 14, 17. Auto conformity declaration.
HIPAA
§164.312 safeguards. PII isolation.
MIFID2
Financial decision validation. Full audit trail.
BASEL4
Banking risk model validation.
Error Codes
Bad Request
Invalid memory_state or missing fields.
Unauthorized
Missing or invalid API key.
Forbidden
Feature not available on your plan.
Rate Limited
Too many requests. Retry-After header included.
Internal Error
Contact support if persistent.