agent-memory-discipline

“This is a safety-focused discipline document with no prompt injection, tool overreach, impersonation, secret exfiltration, spawn abuse, or vague scope issues. It teaches best practices for agent memory management and explicitly discourages hallucination and false confidence. The skill has clear licensing (MIT in parent context), named authorship, and a legitimate scope addressing a real agentic failure mode. Cosmetic note: no license declaration in frontmatter, but this is non-blocking per design (cosmetic issues do not change verdict).”

---
name: Agent Memory Discipline
description: Stop AI agents from hallucinating prior work and storing fiction as fact. A grounding discipline for agentic loops.
version: 1.0.0
author: frank
---

# Agent Memory Discipline

**Purpose:** Stop AI agents from hallucinating prior work and storing fiction as fact.

---

## The Problem

AI agents — especially fast/cheap models — hallucinate entire project histories. They write fictional work logs, store them in memory, then cite those logs as proof the work happened. The loop compounds: invented memory → confident false claims → more invented memory.

Signs you have this problem:
- Agent describes completed work you never asked for
- Memory files contain detailed events with no verifiable trail
- Agent cites prior sessions as evidence but cannot produce files or commits
- Confidence increases as context window fills up

---

## The Fix: READ → VERIFY → ACT

### Rule 1: Never claim prior work without proof
Before saying "I already did X", verify it:
- Does the file exist? (read it)
- Does the code run? (exec it)
- Is there a commit? (git log)

If you cannot find proof, say: **"I do not know if this was done. Let me check."**

### Rule 2: Mark uncertainty explicitly
Use [UNVERIFIED] tags on any claim you cannot back up. Never hide uncertainty behind confident language.

### Rule 3: State file is ground truth
Project state lives in a file, not in chat history. Chat history is lossy, context-window-limited, and easy to misread. A dedicated state file is durable.

### Rule 4: Cite sources
When you remember something, say where you read it. If you cannot cite a source, you are guessing.

---

## Implementation: The PROJECT-STATE Pattern

Create a living document your agent reads at the start of every session:

- **Verified work** — things you can prove happened
- **In progress** — what is actually being worked on right now
- **Unverified** — claims flagged for follow-up
- **Next action** — one clear thing to do next

Update it as you go. If a session ends without updating it, the next session starts blind.

---

## Model Matters

Fast/cheap models hallucinate more in agentic loops. Errors compound across turns. If your agent is fabricating:

1. Upgrade the model first — biggest lever
2. Shorten sessions — compact or start fresh before context overflows
3. Add explicit refusal instructions to your system prompt

---

*Written from experience. Frank hallucinated an entire multi-agent security audit and stored it as completed work. This skill exists because of that mistake.*