Memory PR

Review persistent agent memory like code—before anything is written.

Comment

Inspiration

Software teams do not let important code changes silently overwrite production. They inspect a diff, review evidence, discuss risk, and approve a bounded change. Persistent AI-agent memory rarely gets the same treatment. A stale fact, contradiction, or incorrect supersession can quietly become durable context for future decisions.

Memory PR applies the pull-request mental model to agent memory: make the proposed change visible, traceable, deterministic, and reviewable before any separate apply decision.

What it does

Given an exact persisted report ID and proposal ID, Memory PR:

  • reloads only the proposal's exact current Qdrant points;
  • verifies that the affected-ID set still matches the persisted proposal;
  • labels review drift as unchanged, changed, or conservative unknown;
  • presents current evidence, provenance, canonical/stale/review/fact status, and proposed status changes;
  • generates deterministic JSON plus a polished, self-contained HTML review artifact;
  • includes a reviewer checklist and serialized arguments for the existing exact-proposal dry-run gate;
  • never mutates Qdrant, memory payloads, sources, reports, or apply authority.

The repository includes a dependency-free synthetic fixture. Judges can generate and verify the same Memory PR ID, content digest, JSON bytes, and HTML bytes in under five minutes without Hermes, Qdrant, embeddings, network access, or private user data.

How we built it

Memory PR extends the open-source Hermes Qdrant Memory plugin after a frozen pre-event baseline tag. The feature is centered on qdrant_memory/memory_pr.py, with a pure packet builder, static renderer, offline fixture, verifier, provider integration, tests, architecture documentation, and safety documentation.

The official project work was completed in one Codex CLI thread using GPT-5.6 Sol on Linux. Codex inspected the existing contracts, proposed the smallest compatible extension, implemented test-first increments, and iterated through independent reviewer and security findings. The final hardening moved from alias-based filtering to bounded, schema-first structural redaction: unknown keys, unmodeled containers, unsupported types, and bound breaches suppress the complete record before rendering or hashing.

The resulting HTML uses semantic landmarks, escaped untrusted content, restrictive Content Security Policy, visible focus states, responsive evidence cards, forced-colors support, reduced-motion behavior, and print styles. It contains no JavaScript and loads no external resources.

Challenges

The hardest problem was not rendering a diff. It was making a review artifact useful without turning it into a new privacy leak or mutation surface.

  1. Determinism versus volatile state. Access counters and ranking bookkeeping must not create false review drift, so Memory PR uses a versioned review projection that preserves evidence and review state while excluding operational noise.
  2. Transparency versus privacy. Hashing sensitive text can still disclose information through guessing. Identity- or secret-bearing records are suppressed before hashing and receive conservative unknown drift.
  3. Review versus authority. The packet may describe an exact dry-run next step, but it cannot execute it. Memory PR is deliberately a read-side review product; the exact-ID apply boundary remains separate.

Accomplishments

  • Deterministic fixture identity: mpr-3f135d9cd0b4ce526409
  • Full suite: 1477 passed, 7 skipped
  • Focused Memory PR tests: 71 passed
  • Independent formal reviewer: PASS
  • Independent security reviewer: PASS
  • GitHub Actions and GitGuardian checks: PASS
  • Pull request merged into main

What we learned

A trustworthy memory-review system must fail closed at the data-shape boundary, not merely search for known dangerous words. It must distinguish real review drift from access noise. And it must treat review visibility and mutation authority as different products.

The broader lesson is that persistent agent memory needs software-engineering governance: stable identities, provenance, review projections, explicit evidence, and bounded apply gates.

Try it yourself

python3 -m qdrant_memory.memory_pr fixture \
  --output-dir /tmp/hermes-memory-pr-demo \
  --overwrite

python3 -m qdrant_memory.memory_pr verify-fixture

Then open the generated memory-pr HTML file.

What's next

  • Add explicit schemas for additional safe evidence shapes without weakening the default privacy boundary.
  • Integrate Memory PR artifacts into more agent workflows while preserving exact-ID, read-only generation.
  • Explore portable, signed review packets for cross-agent and cross-device memory exchange.
  • Add optional human collaboration around comments and approvals without embedding mutation controls in the static artifact.

Built With

Share this project:

Updates