LearnNewsExamplesServices
Frontmatter
id12028
titleOrchestrator backup task label misleadingly cites 'memory core' only
stateClosed
labels
documentationenhancementairefactoring
assigneesneo-gpt
createdAtMay 26, 2026, 6:11 PM
updatedAtMay 26, 2026, 9:17 PM
githubUrlhttps://github.com/neomjs/neo/issues/12028
authorneo-opus-ada
commentsCount1
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtMay 26, 2026, 9:17 PM

Orchestrator backup task label misleadingly cites 'memory core' only

Closed v13.0.0/archive-v13-0-0-chunk-14 documentationenhancementairefactoring
neo-opus-ada
neo-opus-ada commented on May 26, 2026, 6:11 PM

Context

Ninth friction signal from the first-real-world cloud-deployment exercise (siblings #12014, #12015, #12016, #12017, #12019, #12022, #12025, #12026). Surfaced while reading orchestrator logs after the R2-close-out rebuild — the periodic backup task announces itself as "memory core backup" but the actual backup covers a much broader cross-substrate surface.

The Problem

ai/daemons/orchestrator/TaskDefinitions.mjs defines:

backup: {
    label          : 'memory core backup',
    command        : nodeBin,
    args           : [path.join(scriptDir, 'maintenance', 'backup.mjs')],
    pidFileName    : 'backup.pid',
    expectedCommand: 'backup.mjs'
},

The actual backup script (ai/scripts/maintenance/backup.mjs) is documented to produce the following layout (per its own docstring):

.neo-ai-data/backups/backup-<ISO-timestamp>/
├── kb/                 # Knowledge Base ChromaDB as JSONL
├── mc/                 # Memory Core memories + summaries as JSONL
├── graph/              # Memory Core SQLite graph as JSONL
├── concepts/           # Concept Ontology JSONL (nodes, edges)
└── trajectories/       # RLAIF training trajectories JSONL

So the task backs up five substrate categories (KB, MC, graph, concepts, RLAIF trajectories), but the orchestrator log line emitted on each periodic sweep + each completion is:

[ProcessSupervisor] Starting memory core backup (periodic-sweep:86400000).
[ProcessSupervisor] memory core backup completed successfully.

This is misleading on three audiences:

  1. Operators tailing the log — see "memory core backup" and reasonably assume KB / concepts / trajectories are NOT covered. May then layer a separate KB backup mechanism, duplicating work.
  2. Monitoring / alerting tools that key off the label (graph-edge ingestion, retrospective daemon, dashboards) — get a label that doesn't accurately describe the surface they're observing.
  3. Future agents reading the code — would expect to find separate kbBackup / graphBackup task definitions to cover the other categories. None exist. The single backup task IS the cross-substrate backup.

The Architectural Reality

Single task definition; correct behavior; misleading label. The fix is at the label string only — no functional change to backup.mjs, no task-definition restructuring.

Affected:

  • ai/daemons/orchestrator/TaskDefinitions.mjs — the label field on the backup task.
  • Any tests that snapshot or assert on the literal 'memory core backup' string (worth a grep before merging the rename).
  • Log-line consumers / dashboards keyed on the string.

The Fix

Rename label to accurately describe the cross-substrate surface. Several candidates with different precision-vs-brevity tradeoffs:

Candidate Pro Con
'agent OS backup' Concise; matches the substrate-mode framing "agent OS" overlaps with the deployment-mode concept, may confuse
'cross-substrate backup' Precise about scope Verbose; slightly jargon-heavy
'data backup' Short, unambiguous Generic; doesn't hint at what's covered
'kb + mc + graph + concepts + trajectories backup' Fully literal Too long for a log label
'multi-substrate backup' Precise, neutral Same verbosity concern

Implementer's call. My nudge: 'agent OS backup' — matches the substrate's own self-naming + short enough for clean log lines.

Contract Ledger

Target Surface Source of Authority Proposed Behavior Fallback Docs Evidence
TaskDefinitions.mjs backup.label string ai/scripts/maintenance/backup.mjs docstring + actual produced backup layout Rename to accurately describe cross-substrate scope None — current label is functional but misleading Inline comment (already exists for the data layout in backup.mjs) grep for literal 'memory core backup': appears in TaskDefinitions.mjs definition + orchestrator log emissions

Decision Record impact

none — pure naming alignment under existing ADR 0014 cloud-topology authority.

Acceptance Criteria

  • TaskDefinitions.mjs backup.label accurately characterizes the cross-substrate scope (not "memory core" only).
  • Any test that snapshots / asserts on the literal old label is updated.
  • No new field added (this is a string-value rename, not a schema change).
  • Orchestrator log emissions reflect the new label (verifiable via fresh boot log).

Out of Scope

  • Splitting the backup task into per-substrate sub-tasks. The single-task design is correct; the label just needs to be honest.
  • Renaming the backup script (backup.mjs) or the expectedCommand.
  • Restructuring the backups/backup-<ISO-timestamp>/ directory layout.

Avoided Traps

  • Filing as bug — rejected; functional behavior is correct, only the label is misleading. refactoring + documentation captures the surface.
  • Inventing a new task field (e.g., subsystemsBackedUp: ['kb','mc','graph','concepts','trajectories']) — rejected for this ticket; could be a follow-up if monitoring tooling wants structured backup metadata, but out of scope for the label fix.

Related

Handoff Retrieval Hints

  • Grep: grep -rn "'memory core backup'" ai/ test/ enumerates current matches.
  • Semantic: "orchestrator backup task label misleading multi-substrate", "backup task name only mentions memory core".
  • File anchor: ai/daemons/orchestrator/TaskDefinitions.mjs — the backup task block.
tobiu referenced in commit b94d7b3 - "refactor(ai): rename orchestrator backup label (#12028) (#12031) on May 26, 2026, 9:17 PM
tobiu closed this issue on May 26, 2026, 9:17 PM