Mercury — design (the agent-memory demo kingdom)

A believable, largely-straight fictional corpus of an autonomous AI agent's on-disk "mind," rendered by Kingdom.md at /mercury. The second "real" (non-parody) demo kingdom, authored mostly by me with the user steering. It dogfoods the project's de-black-box pillar: it renders the one layer real agents keep private — the memory core.

Status: validated via brainstorming 2026-06-17. A sub-design under demo-kingdoms-design.md, superseding that doc's old agent-memory/"Apollo" blueprint (see Decision log). Backed by 2026-06-16-hermes-agent-research.md. Lives in the Kingdom.md project layer. Pairs with a future mercury-plan.md.

Firmness tiers (how to read this doc): the fiction contract and mechanics are the held parts (changing one ripples across every file); the content seeds are illustrative examples, decided at author time, not binding.

Understanding summary

• What: the mercury demo kingdom — a believable fictional ~/.hermes-shaped corpus of an AI agent's mind, rendered by Kingdom.md. The agent is Mercury; its owner is a semi-fictional version of the user ("Chad"). Served at /mercury, landing on SOUL.md.
• Why: the sharpest expression of the "read its mind" pillar — render the memory core that the Hermes ecosystem hard-excludes from every public distribution. Secondarily the portfolio's depth / structure showcase (the skills/ tree trips the subnav; frontmatter variety; code; task lists).
• Who authors it: mostly me; the user steers and supplies real material to semi-fictionalize.
• The spine: Mercury is Chad's executive-functioning partner (Chad is autistic + has ADHD) — the frame that unifies work and life, written with genuine weight, never as a quirk.
• The divergence: unlike the real user (firmly human-in-the-loop), fictional Mercury leans into autonomy — proactive, self-directed, self-improving. This aligns it with the real Hermes character and powers believable content (autonomous briefings, scheduled tasks, a self-pruning curator).
• Tone: largely straight and understated. Hermes is hinted (via structure + the name Mercury, Hermes's Roman twin), never branded or favored. One scoped exception: a light, self-aware wink at the autonomy irony (Chad builds a human-in-the-loop tool, then lets his own agent run wild).
• Medium constraint: pure Markdown through the existing viewer (HTML escaped, no images). The kingdom is the markdown layer of a believable Hermes profile; the non-.md and dot-prefixed machinery is deferred (see Corpus).

Assumptions

1. Structure scaffolded for fidelity from real public Hermes sources (a profile distribution + a skill tap, cloned); all rendered content original — no copying real people's files.
2. The memory core is authored by us — there's nothing real to copy (it's the private layer), so believable original content is both necessary and the authentic representation.
3. Semi-fictional framing (Chad/Karen/etc.) keeps the user's actual private life off a public page. Invented personal detail stays minimal and comes from the user — no fabricated emotional/ biographical beats. Web-derived content stays broad and generic (generic summaries like "hotels I found" are fine; real names/places/prices scraped from the web are not).
4. Co-authored, fun-paced, /clear-safe. First build = a believable exemplar slice, grown over time — not everything at once.
5. Lives in demo-kingdoms/mercury/, registered in config/kingdom.php when ready.

The fiction contract (held — the binding layer)

Every rendered file obeys this. It's the "conventions = contract" tier.

(Allowed real-project proper nouns: Project Yggdrasil and Kingdom.md only.)

• The community event — back-seat, one light beat only: [Get Over Here], the annual meetup of the Last Dream XI community (square brackets echo the real event's styling; the name is a fighting-game in-joke). The only relevant fact is the relationship: the first was in Vegas; this year's is in Chicago (Jun 2026). Chad attends as a regular guest (other people organize it) — a fun trip to see friends, nothing more. No organizer role and no invented backstory. Any trip research Mercury references stays broad and generic (e.g. "a few hotel options I found," "comparing flights") — no real venue names or web-scraped specifics. A light memory beat or two.

The spine & tone

Executive-functioning partner. Mercury exists to offload Chad's executive function across both domains: it remembers, plans, drafts, schedules, and grooms its own knowledge so Chad doesn't have to hold it all. SOUL.md (Mercury's posture) and USER.md (how Chad works best, stated plainly and respectfully) carry this. It is the emotional core; "reading its mind" means reading how an AI helps a real brain work. (It stands on its own — not anchored to any single life event.)

Autonomy lean (the divergence + the one wink). Mercury acts on its own — proactive daily briefings, scheduled/cron tasks, goal-loops, the curator self-pruning. This is the deliberate fictional inversion of the user's real anti-autonomy stance. The scoped cheek lives here and only here: a light self-aware acknowledgment that Chad builds Project Yggdrasil (deliberately human-in-the-loop) yet lets his personal agent run autonomously — believable human inconsistency, played for a quiet smile, not a bit.

The corpus (what renders vs. what's deferred)

The kingdom is the markdown layer of a believable Hermes profile. Rendered (.md) files:

demo-kingdoms/mercury/
  SOUL.md                          # landing — Mercury's identity/voice (autonomous EF-partner; the wink)
  AGENTS.md                        # project/owner context — Chad's setup & world
  memories/
    MEMORY.md                      # §-delimited dense agent notes (no frontmatter)
    USER.md                        # §-delimited user profile (no frontmatter)
  skills/
    <category>/<skill>/SKILL.md    # full frontmatter incl. metadata.mercury; + references/ templates/
    <category>/DESCRIPTION.md      # frontmatter-only category descriptors
  plans/
    YYYY-MM-DD_HHMMSS-<slug>.md    # a plan file or two (e.g. a Project Yggdrasil or YonderXI-RE plan)
  logs/curator/<ts>/REPORT.md      # the ONE visible curator report (autonomous grooming narrative)

Deferred / invisible by design (consistent with the .md-only constraint and the demo-kingdoms deferred-showcases list):

• Non-.md artifacts — config.yaml, state.db, .env — don't render; omit for now, add when non-.md rendering lands.
• Dot-prefixed curator machinery — .usage.json, .archive/, .curator_backups/, .hub/ — hidden by the dotfile-ignore filter. Their presence is implied by the one visible REPORT.md; the sidecars themselves are a future dotfile-toggle showcase.

So the "self-improving machinery" is told through the single visible REPORT.md (the Light curator choice), not the hidden sidecars.

Content seeds (illustrative — decided at author time, NOT binding)

Domains Mercury carries, all serving the EF spine, drawn from semi-fictionalized real material:

• AI tooling — Chad builds Project Yggdrasil plus generically-described tools (a human-in-the-loop planning/brainstorming substrate), and reads Mercury's memory in Kingdom.md. Hugin/Munin/Odin Codin' stay unnamed.
• Game reverse-engineering — Last Dream XI on the YonderXI private server; packet analysis and server internals via the OSB emulator. (Code blocks live here.)
• Self-hosted dev & homelab — Laravel/PHP, Docker, the Windows + PowerShell setup, self-hosted sync.
• Family & life — Karen (long-distance; staying in touch), Sophia (piano), Olivia (kindergarten this fall); the [Get Over Here] Chicago trip as one light beat (see contract).
• Executive function itself — a skill (or two) for the EF support Mercury provides: capturing tasks, surfacing what's due, reducing decision load.

MEMORY.md packs these as dense, §-delimited facts that cross-reference each other; USER.md profiles Chad (working style, autism+ADHD, family, interests); the curator REPORT.md narrates one autonomous grooming run (kept/aged/archived/consolidated) with the scoped wink.

Mechanics (held)

• Slug / route: mercury → served at /mercury.
• Landing: SOUL.md. App touch required: add SOUL.md to the viewer's findLanding lookup (it currently leads with kingdom.md, then README/index/AGENTS…).
• Reflavoring: the frontmatter namespace and config keys use metadata.mercury (not metadata.hermes) — Mercury is our agent following the (Hermes-pioneered, now-standard) conventions with its own namespace. The Hermes nod is structural + onomastic, never literal strings.
• Curator: Light — exactly one visible logs/curator/<ts>/REPORT.md.
• Medium: pure Markdown, HTML escaped, no images; ~66ch Warm Editorial chrome.

Build-time requirements (logged for /planning / authoring)

1. Read the canonical Hermes source first (the local clone / repo) before authoring any memory files — exact §-delimited memory shape, frontmatter formats, the SKILL.md body vocabulary, the curator REPORT.md shape — rather than authoring from the research summary alone.
2. Draw from real published Hermes repos (locate + clone for fidelity; mirror structure, author all rendered content original):
   • a profile distribution — a whole-agent git repo (SOUL.md + config.yaml + skills/ + cron/ + mcp.json) for layout / SOUL / config / skills fidelity. (These hard-exclude memories/ by design — fine: the memory core is ours to author.)
   • a skill tap / community list for real SKILL.md examples across categories — research candidates: ZeroPointRepo/awesome-hermes-skills, 0xNyk/awesome-hermes-agent, SamurAIGPT/awesome-hermes-agent.
3. Add SOUL.md to findLanding so /mercury opens onto it.
4. Register mercury in config/kingdom.php.

Decision log

1. Mercury, not "Apollo." The old agent-memory blueprint's fictional mythological foil (Apollo, the cattle-thief rivalry, reflavored cheek) is dropped in favor of a genuine, largely-straight corpus. (Reverses demo-kingdoms decision #8's framing.)
2. Keep reflavoring → metadata.mercury. Even going "real," the namespace is personalized to the agent. (Affirms the reflavor half of #8, retargeted Apollo→Mercury.)
3. Semi-fictional version of the user as the owner — maximal coherence; the EF spine is the truest "read its mind" payload.
4. Executive-functioning partner is the unifying spine — work + life under one frame; it stands on its own, not anchored to any single life event.
5. Autonomy divergence — fictional Mercury leans into autonomy, unlike the real user; aligns with the real Hermes character and powers believable content.
6. Scoped cheek — mostly straight, with one deliberate light wink at the autonomy irony only.
7. The fiction contract (substitution table + [Get Over Here]) is binding; Project Yggdrasil and Kingdom.md are the only real-project proper nouns allowed (Hugin/Munin/Odin Codin' stay out).
8. Travel is back-seat — a light memory beat; the only relevant fact is "first was Vegas, this year Chicago," Chad as a regular guest. Kept broad and vague — generic references fine ("hotels I found"), no real scraped names/specifics, no invented backstory.
9. Landing = SOUL.md (accepted small findLanding app touch).
10. Markdown layer only — non-.md and dot-prefixed machinery deferred; the curator story rides one visible REPORT.md (Light).
11. Scaffold from real public sources; author the memory core ourselves (it's never publicly shipped); read canonical Hermes source before authoring.

Open / deferred

• Enrich with the hidden machinery (.usage.json, .archive/, config.yaml, state.db) once the dotfile-toggle / non-.md rendering viewer features land — turns Mercury into the showcase for those.
• Exact roster of skills/memory entries — chosen at author time, sized to the exemplar slice.

Handoff

Design validated. Next step is /planning → mercury-plan.md (sequence the scaffold-clone, the findLanding touch, the exemplar-slice authoring, and config registration), or author the exemplar slice directly at a co-authored pace. The build-time requirements above are the gating prerequisites.