H Runtime & memory architecture
Nagato architecture plan · 24 July 2026

Keep personal Hermes current. Keep Nagato dependable.

Separate the executable runtimes, connect them through supported contracts, and make memory prove that it is captured, retrieved, injected, and used—not merely stored.

Observed state

What is true today

These facts were checked live before proposing any installation or service changes.

Shared binary

Two profiles, one installation

Personal Hermes and the game-assist gateway have isolated profile homes, but they still share one patched executable, Python environment, dependency graph, desktop build, and updater.

Broken expectation

Mnemosyne is configured, not active

Both profiles name Mnemosyne as their provider, but Hermes reports the plugin as not installed. Structured external capture, recall, and consolidation are therefore not running.

Active today

Built-in and game context do work

Hermes injects each profile’s built-in memory files. Nagato separately injects bounded campaign memory, Codex records, retrieval evidence, and Recall-derived state into game conversations.

Update friction

The normal updater cannot track cleanly

The installed source is a pinned Nagato patch branch rather than upstream’s normal update branch. A routine update check currently fails before it can report a clean upgrade path.

Privacy boundary

Recall is not generic personal memory

Gameplay evidence is game-scoped and provenance-bearing. Raw screenshots, private paths, and unvalidated extraction output must not leak into a shared personal memory store.

Existing contract

The bridge already owns trust

Nagato’s bridge validates scope, redaction, evidence, artifacts, and agent mutations. A memory integration should extend that boundary rather than bypass it with a second source of truth.

Architecture decision

Split by executable responsibility

A profile isolates state. It does not isolate upgrades, dependencies, regressions, or patched core behavior. Those are the reasons to split the runtime itself.

Recommended: two durable installations, one small shared patch foundation, plus an ephemeral test lane

Your personal Hermes remains free to work inside the Nagato repository and carries only the temporarily shared capabilities it genuinely needs—most importantly Featherless compatibility. Nagato’s service runtime stays pinned and can be trimmed to the product essentials. Candidate gateways and risky memory experiments run in throwaway worktrees/environments until they pass the shared contracts.

RECOMMENDED
BOUNDARY
Lane A · Personal

Upstream Hermes

Your desktop and CLI agent for ordinary work, including working on Nagato’s codebase.

  • Upstream-oriented installation with a minimal reviewed shared patch set
  • Personal profile, sessions, skills, and memory store
  • Project-aware recall using a project namespace
  • No dependency on Nagato-only Runs, trace, artifact, or bridge patches
Lane B · Product

Nagato Hermes runtime

A service backend owned by the Game Assist compatibility and privacy contracts.

  • Separate install directory, virtual environment, and service command
  • Trimmed product runtime with pinned reviewed source + reproducible patch manifest
  • Dedicated profile home and game-assist credentials
  • Updated only after contract, privacy, and live smoke gates
Lane C · Disposable

Gateway laboratory

Candidate adapters and memory experiments that must not disturb either daily runtime.

  • Temporary data roots and fake dependencies by default
  • No personal or live gameplay memory
  • Producer conformance before promotion
  • Destroyed or archived after evidence is captured
Shared infrastructure

Extract the Featherless scheduler

Featherless coordination is useful beyond Nagato. Keeping it as repeated client patches makes every runtime carry the same provider policy and concurrency bugs.

Temporary rule: share the smallest proven Featherless patch set

Both durable Hermes installations may carry the current Featherless compatibility and safety patches during separation. Treat that as migration debt with an explicit exit: a standalone loopback scheduler becomes the single owner of capacity, reservations, model routing metadata, retry/backoff, and observability.

EXTRACT
THEN DELETE
1
One scheduling authority

Personal Hermes, Nagato Hermes, and future candidate harnesses call one local service instead of implementing provider concurrency independently.

2
Provider-neutral contract

Clients submit bounded model requests and priorities; the scheduler owns Featherless credentials, reservations, rate state, and fairness.

3
Failure isolation

A scheduler outage fails explicitly and cannot corrupt sessions, memory, or Nagato’s persisted traces. Direct-provider fallback is a deliberate policy, never an accidental bypass.

4
Patch retirement gate

Shared client patches are removed only after parity tests prove streaming, auxiliary calls, deadlines, accounting, and recovery through the scheduler.

Active learning contract

Memory must close the loop

“The database contains memories” is not an acceptance test. The model must receive relevant memory, use it correctly, and leave evidence that the loop worked.

01
ObserveConversation, tools, decisions, corrections, outcomes
02
ValidateScope, redaction, provenance, relevance, authority
03
OrganiseFacts, episodes, preferences, project and game namespaces
04
RecallQuery-triggered, bounded, freshness-aware retrieval
05
Inject & useVisible context identity, budget, citations, action constraints
06
LearnFeedback, correction, consolidation, expiry, deletion propagation
1
Canary recall

A planted prior decision is found in a new session and changes the answer or tool plan in the expected way.

2
Negative relevance

Irrelevant memories are withheld; the prompt records memory candidates and actual injected bytes without private content in diagnostics.

3
Correction wins

A newer explicit correction supersedes an older fact, while provenance and history remain auditable.

4
Isolation

Personal, project, profile, game, and Recall namespaces cannot read one another without an explicit sharing rule.

5
Recall evidence

Nagato may promote only validated derived facts tied to exact Recall evidence; raw screenshots never become generic memory.

6
Replay proof

Restarting the gateway preserves the same authoritative memory outcome and does not duplicate capture or actions.

Safe execution

Migration sequence

Every phase has an exit condition and a rollback. The live bridge keeps using its current runtime until the replacement passes the same requests side by side.

Freeze and inventory

Back up profile state, record ports/services/source heads, and define health probes. No mutation to the live gateways.

Inventory signed off

Create the personal runtime

Install an upstream-oriented build separately, carrying only the reviewed shared foundation patches needed now. Point desktop/CLI aliases to it and prove repository work, sessions, tools, Featherless behavior, and rollback.

Personal smoke green

Re-home Nagato’s pinned runtime

Reproduce the reviewed patch stack in its own installation and service identity, preserving the existing game-assist home without copying secrets into plans or logs.

Contract parity green

Activate structured memory as a plugin

Install the supported provider package per runtime. Personal, Nagato, and every candidate use separate stores. Personal Hermes may reach Nagato through authenticated development contracts, never by mounting Nagato’s memory database.

Active-loop gates green

Wire Nagato’s memory policy

Keep campaign/Codex/Recall authority in the bridge. Permit only bounded, provenance-linked derived facts into the product runtime’s provider namespace.

Privacy review clean

Cut over and observe

Switch the bridge endpoint, retain the old service stopped but recoverable, run live gaming-machine acceptance, then begin the update cadence.

Human acceptance

Resume gateway candidates

Only after the two stable lanes and active-memory contract exist should a candidate runtime compete to replace Nagato’s backend.

After memory baseline
Maintenance

Different update promises

“Stay current” and “stay compatible” are different jobs, so they get different release channels.

Personal Hermes · rolling shared-foundation

  • Automated update check on a chosen cadence
  • Backup, install, CLI/Desktop smoke, memory canary
  • Fast rollback to the previous upstream build
  • Allowed to advance independently when the small shared patch contract still passes

Nagato runtime · reviewed channel

  • Track upstream releases without auto-promoting them
  • Rebase or re-author the ordered patch stack deliberately
  • Run gateway, artifact, memory, privacy, and bridge suites
  • Promote only an exact reviewed source and dependency lock
Plan operations

HTML checkpoints

The main plan remains the stable decision record. Checkpoints are append-only snapshots linked from here and published after evidence-bearing events.

Checkpoint cadence

  • At the end of every migration phase
  • Whenever a blocker changes the architecture or schedule
  • Before and after any live runtime cutover
  • At final verification and human acceptance

Ephemeral plan-service target

  • High-entropy UUID-style capability URLs with expiry and explicit deletion
  • No directory listing, search indexing, or predictable project slugs by default
  • Save/promote a temporary plan into a durable directory only by explicit action
  • Later: authenticated replies, revisions, ownership, rate limits, and an audit trail
Human decisions

Direction recorded

These decisions now constrain Checkpoint 003 and the first separation spike.

Personal Hermes will be upstream-oriented, not patch-free.
Carry shared essentials such as Featherless temporarily; keep Nagato-only product behavior out.
Structured memory is isolated per runtime and per candidate.
Personal Hermes gets authenticated development access to Nagato’s service, not direct access to Nagato’s memory files.
/plans should evolve into an ephemeral plan service.
Use temporary capability links, TTL/deletion, optional save/promotion, and later authenticated replies. UUID links reduce discovery but are not a substitute for authentication.
Checkpoint cadence follows the development waves.
Publish at each subwave, blocker, pre/post cutover, and final acceptance.