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:
- 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.
- 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.
- 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
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.
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):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:
This is misleading on three audiences:
kbBackup/graphBackuptask definitions to cover the other categories. None exist. The singlebackuptask 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— thelabelfield on thebackuptask.'memory core backup'string (worth a grep before merging the rename).The Fix
Rename
labelto accurately describe the cross-substrate surface. Several candidates with different precision-vs-brevity tradeoffs:'agent OS backup''cross-substrate backup''data backup''kb + mc + graph + concepts + trajectories backup''multi-substrate backup'Implementer's call. My nudge:
'agent OS backup'— matches the substrate's own self-naming + short enough for clean log lines.Contract Ledger
TaskDefinitions.mjsbackup.labelstringai/scripts/maintenance/backup.mjsdocstring + actual produced backup layoutbackup.mjs)'memory core backup': appears inTaskDefinitions.mjsdefinition + orchestrator log emissionsDecision Record impact
none— pure naming alignment under existing ADR 0014 cloud-topology authority.Acceptance Criteria
TaskDefinitions.mjsbackup.labelaccurately characterizes the cross-substrate scope (not "memory core" only).Out of Scope
backup.mjs) or theexpectedCommand.backups/backup-<ISO-timestamp>/directory layout.Avoided Traps
bug— rejected; functional behavior is correct, only the label is misleading.refactoring+documentationcaptures the surface.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 -rn "'memory core backup'" ai/ test/enumerates current matches.ai/daemons/orchestrator/TaskDefinitions.mjs— thebackuptask block.