Skip to content

Spec: deliver external Memory changes through the Inbox #350

Closed
4 of 4 issues completed
Closed

Description

@DoodleBears

Part of #114. Formalizes #349. Related: #324, #329. #351 is merged; #352 delivers Inbox admission.

Goal

A PersonaBot must receive an actionable Bot Inbox Event when its Git Memory Repository has changed outside its own turn, including a net change that remains after a DSH Host restart. The Event tells the Orchestrator what changed at path and Git-state level so it can inspect current files and decide what to do. A file change alone does not wake the Bot.

This is an application-defined BotHarness Source Event and Inbox Admission, not a DSH-native Agent Inbox item or a replacement Memory content store. Git's checked-out working tree remains current Memory.

Required behavior

  • After Host startup (once the durable stores are ready), and again before an ordinary turn, compare the current repository against the last durable observation checkpoint: repository identity, branch, HEAD, staged/index state, and content identity of dirty and untracked paths. Include additions, updates, removals, commits, and branch movement. A second edit to an already dirty path must still count.
  • Commit an immutable memory-change Source Event, its Inbox Admission, and the advanced observation checkpoint atomically. If no net change exists, create no Event.
  • Give the Event an actionable, bounded summary: event identity, observed time, old/new branch or HEAD when relevant, change categories and relative paths, and an overflow count. Do not put file bodies or a full diff in the Event; the Agent reads Git/current files when needed.
  • Admit it without waking an idle Bot. Show the admitted Event in the Bot Inbox without waking the Bot, then select it for the next ordinary turn, including the first turn after Host restart. Keep it pending until its summary enters the Orchestrator turn; a successful turn handles it, an explicit ignore remains distinct, and a failed turn follows existing Inbox repair semantics.
  • Do not claim the actor was Human: offline changes or an interrupted turn may have uncertain provenance. Describe what the Host observed, not an unprovable edit history.
  • Suppress Bot-owned changes by advancing the durable checkpoint after the Bot turn's reconcile/abort boundary. Preserve a pending Event independently of the checkpoint.
  • Keep the system-prompt prefix byte-stable. The Event belongs in the turn message and Bot Inbox projection.

Delivery slices

Out of scope

  • Inline editing or save-time admission from the ordinary read-only Memory UI. The former slice Slice: eager memory admission on UI save with join-only wake #353 is cancelled; the existing explicit Human save service contract remains.
  • Filesystem watchers, a turn caused solely by a file edit, automatic staging or commits, full file contents in Inbox, or a second Memory authority.
  • Reconstructing intermediate edits made and reverted entirely while the Host was offline. The comparison reports the net change between durable observations.

Acceptance

  • External additions, edits, removals, Git commits, and branch switches yield a bounded, actionable Memory Event in the Bot Inbox on the next ordinary turn, with no independent wake.
  • Editing the same already dirty file again is detected.
  • Edit, stop Host, restart Host, then send a normal message: the Orchestrator receives the Memory Event and can read the changed file.
  • A crash before the atomic write leaves the old checkpoint for rediscovery; a crash after the atomic write leaves one pending Event. No silent loss or duplicate Event.
  • Bot-owned changes and unchanged worktrees stay silent; PERSONA.md changes explain that the current Session keeps its frozen persona.
  • Existing DM, group, report, digest, and resume turn semantics remain correct; focused tests and an isolated real-model DSH run cover delivery and restart recovery.
  • Reconcile ADR-0060's older blanket rejection of Memory notices with this explicit out-of-band, no-wake, bottom-of-turn Inbox Event decision before implementation merges.

Activity

  1. added
    ready-for-agentFully specified, ready for an AFK agent
    feature:memoryPersonaBot Memory Repository and Memory Service
    feature:messagingMessaging module and external providers
    scope:specNormative specification for follow-on slices
    on Sep 27, 2026
  2. added this to the v1.0 milestone on Sep 27, 2026
  3. changed the title [-]Spec: unified memory-change delivery through the Inbox[/-] [+]Spec: deliver external Memory changes through the Inbox[/+] on Sep 29, 2026
  4. DoodleBears commented on Sep 29, 2026

    @DoodleBears
    ContributorAuthor

    Implementation handoff

    The two delivery slices #352 and #464 are implemented together in PR #473, with ADR-0092 reconciling ADR-0060. The PR includes a live DSH screenshot and local restart verification. Memory changes are actionable Bot Inbox facts on the next ordinary turn; startup adds pending facts without an independent wake. The remaining step is Human QA and PR merge. Task: codex/local/01a0e86b-16ab-7a01-baf9-e555eec3ea62.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    feature:memoryPersonaBot Memory Repository and Memory Servicefeature:messagingMessaging module and external providersready-for-agentFully specified, ready for an AFK agentscope:specNormative specification for follow-on slices

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions