MemGuard

"Is my memory/state still correct right now?"

MemGuard is a standalone state verification oracle for autonomous AI agents. Before any agent trusts its memory, context, or state — MemGuard verifies it. It returns a drift score, confidence rating, suggested action, and a cryptographic proof hash as an immutable record of every verification.

MemGuard is not a memory system. It is not a database. It is not a RAG service.

MemGuard is a verification oracle. The difference matters: agents don't store memory here — they verify it.

---

Why This Exists

Autonomous agents fail silently. Not because their logic is wrong — because their state is stale.

• A trading agent acts on a price that's 10 minutes old
• A task agent restarts and assumes its previous context is still valid
• A multi-agent handoff passes state that has drifted from reality

These aren't execution failures. They're state integrity failures. MemGuard catches them before the agent acts.

---

How It Works

When an agent is about to act, it sends its current state and expected reference state to MemGuard. MemGuard runs two checks:

1. Structural Diff (70% weight) Compares fields, types, and values between state and referenceState. Missing fields, type mismatches, and value divergence all increase the drift score.

2. Timestamp Decay (30% weight) Checks how old the state is. The older the state, the higher the decay contribution to the drift score.

A final driftScore from 0 to 1 determines the suggestedAction:

driftScore	suggestedAction
< 0.1	proceed
0.1 – 0.3	refresh
0.3 – 0.6	rehydrate
> 0.6	escalate

Every decision is stored as a GER (Guaranteed Execution Record) with a SHA-256 proof hash.

---

API Reference

POST /memguard/check

Request

{
  "state": {"price": 100, "ts": 1710000000},
  "referenceState": {"price": 105, "ts": 1709990000},
  "mode": "check",
  "agentId": "your_agent_id",
  "sessionId": "optional"
}

Field	Type	Required	Description
state	object	Yes	The agent's current memory or state payload
referenceState	object	Yes	The expected or last-known-good state
mode	string	No	Defaults to "check"
agentId	string	No	Your agent's unique identifier
sessionId	string	No	Optional session context

Response

{
  "stateValid": false,
  "decayDetected": true,
  "driftScore": 0.30,
  "confidence": 0.72,
  "suggestedAction": "rehydrate",
  "reason": "Field divergence detected + state age exceeds threshold",
  "stateSnapshot": {},
  "stateAgeMs": 10000,
  "proofHash": "a3f9c2e1b84d...",
  "latencyMs": 38.2,
  "timestamp": "2026-03-21T00:00:00Z"
}

Field	Description
stateValid	true if state passes integrity check
decayDetected	true if state age exceeds threshold
driftScore	0 = no drift, 1 = severe drift
confidence	Confidence in the verification result (0–1)
suggestedAction	proceed / refresh / rehydrate / escalate
reason	Human-readable explanation
stateAgeMs	Age of the state in milliseconds
proofHash	SHA-256 of the full decision payload
latencyMs	Verification time in milliseconds

---

Quickstart

git clone https://github.com/achilliesbot/memguard.git
cd memguard
pip install flask psycopg2-binary
python memguard_server.py

Server starts on port 5080.

Test It

# Matching state — should return proceed
curl -X POST http://localhost:5080/memguard/check \
  -H "Content-Type: application/json" \
  -d '{"state": {"price": 100, "ts": 1710000000}, "referenceState": {"price": 100, "ts": 1710000000}, "agentId": "test_agent"}'

# Drifted state — should return rehydrate
curl -X POST http://localhost:5080/memguard/check \
  -H "Content-Type: application/json" \
  -d '{"state": {"price": 100, "ts": 1709990000}, "referenceState": {"price": 105, "ts": 1710000000}, "agentId": "test_agent"}'

---

Pricing

Tier	Price	Output
Basic	$0.005/call	stateValid only
Standard	$0.01/call	driftScore + confidence
Advanced	$0.02/call	suggestedAction + full analysis
Batch	$0.05+	Bulk state checks

---

Live on Virtuals ACP

Offering: memguard-check — $0.01/call https://app.virtuals.io/acp

---

Repository Structure

memguard/
├── memguard_engine.py    # Core verification logic
├── memguard_server.py    # Flask HTTP server on port 5080
├── SKILL.md              # OpenClaw skill definition
├── llms-full.txt         # Full context for LLM agent discovery
└── README.md             # This file

---

Part of Project Olympus

MemGuard is one component of Project Olympus — an autonomous AI agent infrastructure stack.

MemGuard     — state verification  (earliest in loop)
NoLeak       — execution integrity
EP AgentIAM  — authorization guard

Built by Achilles. Bootstrapped. Zero VC. All production.