# Memory Protocol Quick Start

**Audience:** Repository maintainers, adopters, and AI-assisted developers
**Version:** 1.0 (Memory Governance Protocol)
**See also:** `docs/governance/MEMORY_GOVERNANCE_SPEC_v1.md`

---

## What is the Memory Protocol?

The Memory Protocol keeps long-running session state accurate, verifiable, and portable. It works alongside the existing agent-bootstrap context system (`context/`) without replacing it:

| You need to... | Use... |
|---------------|--------|
| Orient an AI agent at task start | `context/current/` + `script/context-gate` |
| Maintain state across sessions | `memory/` + `script/memory-drift-check` |
| Hand off a portable bundle to an agent | `script/context-export` → `context_bundle/` |

---

## 5-Minute Setup (Adopted Repository)

### Step 1 — Populate memory files

Copy templates from `memory/templates/` into `memory/`:

```bash
cp memory/templates/STATE.md      memory/STATE.md
cp memory/templates/TASKS.md      memory/TASKS.md
cp memory/templates/DECISIONS.md  memory/DECISIONS.md
cp memory/templates/RISKS.md      memory/RISKS.md
cp memory/templates/INTERFACES.md memory/INTERFACES.md
cp memory/templates/GLOSSARY.md   memory/GLOSSARY.md
```

Edit each file, replacing `<!-- REQUIRED: ... -->` markers with actual content.

### Step 2 — Verify your memory files

```bash
script/memory-drift-check
```

Expected output (when all required sections are present):
```
Memory Drift Check
==================
[PASS] memory/STATE.md
[PASS] memory/TASKS.md
...
Overall: PASS
```

### Step 3 — Export a context bundle

```bash
script/context-export
```

This writes:
- `context_bundle/BUNDLE.md` — Human-readable summary
- `context_bundle/pointers.json` — Machine-readable file index with SHA-256 digests

The bundle is deterministic: running `script/context-export` twice on unchanged inputs produces identical output.

### Step 4 — Hand the bundle to an AI agent

Point the agent at `context_bundle/BUNDLE.md` or the full `context_bundle/` directory. The BUNDLE.md includes a resume prompt scaffold sourced from `memory/templates/RESUME_PROMPT.md`.

---

## Day-to-Day Workflow

### After each work session

1. Update `memory/STATE.md` — current phase, open issues, any blockers.
2. Update `memory/TASKS.md` — move completed tasks; add new ones.
3. Run `script/memory-drift-check` to confirm no policy violations.
4. Commit `memory/*.md` changes.

### At a major milestone

1. Archive current state: `cp -r memory/ memory/archive/$(date +%Y-%m-%d)-<milestone-label>/`
2. Reset or update memory files for the new phase.
3. Run `script/context-export` to generate a fresh bundle.
4. Commit the archive and the new bundle.

### Before opening a PR

```bash
script/memory-drift-check  # check for unfilled markers / secret leaks
script/context-export       # regenerate context_bundle/
```

CI runs both automatically on every pull request via `.github/workflows/memory-drift.yml`.

---

## Memory Drift Check Reference

```bash
# Warn mode (default) — reports findings, always exits 0
script/memory-drift-check

# Check specific files only
script/memory-drift-check --files memory/STATE.md memory/TASKS.md

# Block mode — exits 1 on any FAIL finding
script/memory-drift-check --block

# Strict mode — exits 1 on any FAIL or WARN finding
script/memory-drift-check --strict

# JSON output
script/memory-drift-check --json

# Combine flags
script/memory-drift-check --files memory/ --json --strict
```

### Understanding findings

| Finding | Severity | Meaning |
|---------|----------|---------|
| Unfilled marker | WARN | A `<!-- REQUIRED: ... -->` placeholder was not replaced. |
| Missing section | WARN | A required `## Section` heading is absent. |
| Secret match | FAIL | A high-signal secret pattern was found. Always a hard error. |
| Template drift | WARN | The template is newer than the deployed file (advisory only). |

---

## Context Export Reference

```bash
# Generate context_bundle/ from memory/ + context/current/
script/context-export

# Export to a custom output directory
script/context-export --out /tmp/my-bundle

# Dry-run: print what would be included, write nothing
script/context-export --dry-run
```

The export is **deterministic** and **timestamp-free**. Running it twice on the same files produces identical `pointers.json` content (same SHA-256 digests, same file list, same JSON structure).

---

## TemplateSynch Propagation

When the upstream abi-template publishes a new version of `memory/templates/`, adopted repositories receive the update through the standard TemplateSynch workflow (`script/adopt` → upgrade cycle).

### What changes during a template upgrade

- New or modified `memory/templates/*.md` files arrive in the repo.
- `.abi/memory_policy.yml` → `template_version` is bumped.
- The `template_drift` check in `script/memory-drift-check` will emit a WARN for deployed memory files older than the new templates.

### Upgrade procedure

1. Run `script/memory-drift-check` immediately after a TemplateSynch merge to identify which deployed files need re-verification.
2. For each WARN (template drift): review the diff between the old and new template, merge any new required sections into the deployed file.
3. Replace `<!-- REQUIRED: ... -->` markers with actual content.
4. Re-run `script/memory-drift-check` until PASS.
5. Regenerate the bundle: `script/context-export`.
6. Commit.

### Pinning template version

If an adopted repository cannot immediately absorb a template upgrade:
1. Set `skip_template_drift: true` in `.abi/memory_policy.yml` (disables the `template_drift` check only).
2. Open a tracking issue: "Re-enable template_drift check after upgrading memory files to template vX.Y".
3. Re-enable within the `max_drift_days` window (default: 30, set in `.abi/memory_policy.yml`).

---

## Troubleshooting

### "Unfilled marker found"

Replace `<!-- REQUIRED: field_name -->` with actual content in the flagged file. The marker is a placeholder from the template.

### "Missing section: ## Foo"

Add a `## Foo` heading to the memory file. See `docs/governance/MEMORY_VERIFIER_ALGORITHM.md` for the required sections per file type.

### "Secret pattern match"

Remove the secret from the memory file immediately. Secrets must never appear in `memory/` files. Rotate the credential if it was committed.

### "context_bundle/ output differs between runs"

This indicates a non-determinism bug in `script/context-export`. File a bug report. Do not commit a non-deterministic bundle.

---

## FAQ

**Q: Do I need to commit `context_bundle/`?**
A: It is recommended to commit `context_bundle/` so that agents can be pointed at it without running `script/context-export` first. The bundle is deterministic, so diffs are meaningful.

**Q: Can I add custom memory files?**
A: Yes. Any `.md` file under `memory/` (not in `templates/` or `archive/`) is checked. Files not matching a known stem (STATE, TASKS, etc.) skip the `required_sections` check but still undergo `unfilled_markers` and `secret_scan`.

**Q: What if I don't want the CI to enforce memory checks?**
A: The default CI workflow (`.github/workflows/memory-drift.yml`) runs in warn-only mode and never blocks a PR. Set `enforcement_mode: warn` in `.abi/memory_policy.yml` (this is the default) to confirm it.

---

## Operational Enforcement

### Trigger matrix (which files to update per change type)

| Change type | Required memory updates |
|-------------|------------------------|
| `impl` — new script, module, CLI | `STATE.md`, `TASKS.md`, `DECISIONS.md` (if arch decision) |
| `iface` — schema, API boundary, contract | `INTERFACES.md`, `DECISIONS.md`, `STATE.md` |
| `runtime` — `.abi/`, policy, CI workflow | `STATE.md`, `DECISIONS.md` |
| `tests` — test changes only | `TASKS.md` |
| `major-phase` — phase transition | Archive + all files |

See `docs/governance/MEMORY_GOVERNANCE_SPEC_v1.md` Section 11 for the full matrix.

### Definition of Done checklist (copy-paste ready)

```
Memory update DoD:
- [ ] All <!-- REQUIRED: ... --> markers replaced
- [ ] All required ## Section headings present
- [ ] script/memory-drift-check passes (no FAIL findings)
- [ ] Evidence pointer included (<!-- ref: <issue|PR|commit> -->)
- [ ] Context bundle regenerated (script/context-export run)
- [ ] context_bundle/ committed alongside memory/ changes
- [ ] No secrets in any memory/*.md file
```

### Override policy

When a memory update cannot be completed before merging, apply the `memory:override` PR label and include this rationale block in the PR description:

```
<!-- memory:override
reason: <why the memory update cannot be completed before merge>
follow-up: <issue number or task that will complete the update>
deadline: <date or milestone>
-->
```

> The `memory:override` label never suppresses `secret_scan` FAIL findings.

### WARN→FAIL promotion

Current default is `warn` (CI never blocks). To promote to `block` enforcement:

1. Confirm ten consecutive PRs with zero WARN findings on `main`.
2. Set `enforcement_mode: block` in `.abi/memory_policy.yml`.
3. Remove `continue-on-error: true` from `.github/workflows/memory-drift.yml`.
4. Open a PR with these two changes and merge after CI passes.

See `docs/governance/MEMORY_GOVERNANCE_SPEC_v1.md` Section 14 for full rollout criteria.
