Skip to content

docs: a picture on the front page, and a README that starts in plain words - #20

Closed
glatinone wants to merge 1 commit into
fix/mcp-agent-identityfrom
docs/front-page-and-demo-gif
Closed

glatinone wants to merge 1 commit into
fix/mcp-agent-identityfrom
docs/front-page-and-demo-gif

Conversation

@glatinone

Copy link
Copy Markdown
Owner

docs: a picture on the front page, and a README that starts in plain words

The README opened with "an open protocol for AI agent memory interoperability" and
then assumed the reader already knew what a protocol was, why agents forget, and
what a "Memory Cell" is. It is now ordered the other way round:

  • What it is, in plain words first. Agents forget between sessions; AMP is the
    shared notebook they can all use, with rules about who may read each note and
    notes that fade when they stop being useful. The schema, the HTTP API and the
    active → stale → archived lifecycle come after that, not before it.
  • An animation of it running, right under the title: three agents, one shared
    memory, one of them refused — then the same query over HTTP returning a result
    for one and nothing for the other. Big enough to read, small enough to load
    (716 KB).
  • The refusal explained, because "no results" is the design: an error saying
    "forbidden" would let a caller probe for memories it may not see.
  • Every link on one line each, with what is behind it, and the honest limits
    section kept and sharpened.

The animation is not a screen recording nobody can reproduce. It is generated:

  • docs/assets/demo-transcript.txt holds the output, captured from a real server
    (scripts/README.md documents the re-record procedure).
  • scripts/make_demo_gif.py renders it to docs/assets/amp-demo.gif plus a still
    frame for anywhere an animation will not play. It needs Pillow and nothing else.
  • The generator refuses two things rather than producing a subtly broken
    picture: a line too wide for the window (clipped text is invisible in review and
    obvious on the page), and a transcript line that looks like a marker but is
    missing the space the format asks for (*Result instead of * Result). That
    second guard exists because it happened: the accent lines rendered as ordinary
    output, which is exactly the kind of mistake that survives a visual check.

Verified rather than eyeballed, since this session has no vision: no line exceeds
the window (measured), no ink lands in the right margin, the accent and prompt
colours are present as drawn, all 92 distinct frames differ, the GIF is 940x645 /
716 KB, and every local link and image path in the README and the docs resolves
(0 broken across 8 files). mkdocs build --strict clean, and the built site
contains assets/amp-demo.gif, so the docs home shows it too.

Note on timing: the docs site deploys from master, so the new front page and the
animation appear at glatinone.github.io once this chain is merged.

…words

The README opened with "an open protocol for AI agent memory interoperability" and
then assumed the reader already knew what a protocol was, why agents forget, and
what a "Memory Cell" is. It is now ordered the other way round:

- **What it is, in plain words first.** Agents forget between sessions; AMP is the
  shared notebook they can all use, with rules about who may read each note and
  notes that fade when they stop being useful. The schema, the HTTP API and the
  `active → stale → archived` lifecycle come after that, not before it.
- **An animation of it running**, right under the title: three agents, one shared
  memory, one of them refused — then the same query over HTTP returning a result
  for one and nothing for the other. Big enough to read, small enough to load
  (716 KB).
- **The refusal explained**, because "no results" is the design: an error saying
  "forbidden" would let a caller probe for memories it may not see.
- **Every link on one line each**, with what is behind it, and the honest limits
  section kept and sharpened.

The animation is not a screen recording nobody can reproduce. It is generated:

- `docs/assets/demo-transcript.txt` holds the output, captured from a real server
  (`scripts/README.md` documents the re-record procedure).
- `scripts/make_demo_gif.py` renders it to `docs/assets/amp-demo.gif` plus a still
  frame for anywhere an animation will not play. It needs Pillow and nothing else.
- The generator **refuses** two things rather than producing a subtly broken
  picture: a line too wide for the window (clipped text is invisible in review and
  obvious on the page), and a transcript line that looks like a marker but is
  missing the space the format asks for (`*Result` instead of `* Result`). That
  second guard exists because it happened: the accent lines rendered as ordinary
  output, which is exactly the kind of mistake that survives a visual check.

Verified rather than eyeballed, since this session has no vision: no line exceeds
the window (measured), no ink lands in the right margin, the accent and prompt
colours are present as drawn, all 92 distinct frames differ, the GIF is 940x645 /
716 KB, and every local link and image path in the README and the docs resolves
(0 broken across 8 files). `mkdocs build --strict` clean, and the built site
contains `assets/amp-demo.gif`, so the docs home shows it too.

Note on timing: the docs site deploys from `master`, so the new front page and the
animation appear at glatinone.github.io once this chain is merged.
@glatinone

Copy link
Copy Markdown
Owner Author

Landed on master in the v0.1.0 chain: the branch was fast-forward merged as part of b940905..92b88ee and released as v0.1.0. Closing so the open list matches reality - the commits are in master, and the tag points at them.

@glatinone glatinone closed this Oct 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant