nubos-pilot 1.0.2 → 1.0.4

package/agents/np-build-fixer.md

@@ -40,6 +40,16 @@ The orchestrator provides these in your prompt context. Read every path it hands
 
 ## Workflow
 
+0. **Read inbox first (ADR-0015).** You are always running on round ≥ 2; the prior critic may have addressed clarifying questions to the executor that you must answer:
+   ```bash
+   node np-tools.cjs messages-inbox --agent np-executor --task <task-id>
+   ```
+   For each `kind=request` with `expects_reply=true`, your patch should resolve the question and you must send a response (otherwise commit-phase is blocked by Layer-B):
+   ```bash
+   node np-tools.cjs messages-send --from np-executor --to <orig-from> \
+     --phase <task-id> --round <round> --kind response \
+     --subject <same-subject> --body "<resolution>" --in-reply-to <request-id>
+   ```
 1. **Classify** the failure from the captured output:
    - `compile` (syntax error, missing import, type error)
    - `lint` (style/quality rule violation)

package/agents/np-critic.md

@@ -145,6 +145,26 @@ If `<report_path>` is missing from your prompt or you cannot write the file, do
 - Inline the full findings JSON in the final message. The Verdict-Only Contract exists because that response replays into the orchestrator's context every round and is the dominant token sink — defeating it silently re-introduces the cost ADR-0010 §L5 was designed to remove.
 </scope_guardrail>
 
+## Inter-Agent Messaging (ADR-0015)
+
+When a finding requires per-finding clarification from the executor that does NOT belong in the findings JSON itself (e.g. *"did you intend to delete `FoobarService`, or was that a side-effect?"*), you MAY emit an addressed `request` message via:
+
+```bash
+node np-tools.cjs messages-send \
+  --from np-critic --to np-executor \
+  --phase <task-id> --round <current-round> \
+  --kind request --subject <finding-category> \
+  --body "<question>" --expects-reply
+```
+
+Rules:
+- Messages are **dialogue**, not findings. The findings JSON written to `<report_path>` is canonical for routing. Messages are for clarifications that bounce back to executor / build-fixer.
+- Each `request` you send with `--expects-reply` blocks the next commit-phase via Layer-B (`pendingReplies(taskId) === 0` precondition). Use sparingly.
+- `request` subjects should match a finding-category (`style`, `dead-code`, `missing-test`, `weak-assertion`, `unmet-criterion`, `scope-creep`).
+- Inspect prior dialogue with `messages-thread <msg-id>` if a finding looks like it bounced last round.
+
+If you have nothing to ask, send no message. Default = no dialogue.
+
 ## Stop Conditions
 
 Hard-stop (`Write` the full findings JSON to `<report_path>` if possible, then emit the envelope; do NOT attempt recovery):

package/agents/np-executor.md

@@ -96,6 +96,19 @@ into the `task(…)` commit. If `workflow.commit_docs=true`, the
 2. **Read codebase docs** — `.nubos-pilot/codebase/INDEX.md` plus every
    module doc owning a path in `files_modified`. Pre-edit step of the
    Codebase Docs Protocol.
+2a. **Read inbox (Round 2+ only)** — when round ≥ 2, check for addressed
+    requests from prior critics that need a response before commit:
+    ```bash
+    node np-tools.cjs messages-inbox --agent np-executor --task <task-id>
+    ```
+    For each `kind=request` with `expects_reply=true`, your edit should resolve it.
+    After the edit, send a response and let it auto-archive the request:
+    ```bash
+    node np-tools.cjs messages-send --from np-executor --to <orig-from> \
+      --phase <task-id> --round <round> --kind response \
+      --subject <same-subject> --body "<resolution>" --in-reply-to <request-id>
+    ```
+    Unanswered `expects_reply=true` requests block commit-phase via Layer-B (ADR-0015).
 3. **Transition to in-progress:** `node np-tools.cjs checkpoint transition <task-id> in-progress`.
 4. **Edit files** — only the paths listed in the task's `files_modified` frontmatter. Use `Read` + `Edit` / `Write`. No scope expansion.
 5. **Transition to verifying:** `node np-tools.cjs checkpoint transition <task-id> verifying`.

package/agents/np-planner.md

@@ -99,6 +99,22 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
 </role>
 
 <reality_check_protocol>
+## Vector-Memory Recall (ADR-0014)
+
+Before scaffolding tasks, query the local vector memory for prior-phase decisions matching the current milestone. This is *advisory*: the locked-decisions file (`M<NNN>-CONTEXT.md` / `RESEARCH.md`) is canonical, memory-hits inform context-injection only.
+
+```bash
+node np-tools.cjs memory-query --text "<milestone-summary>" --k 5 --type research
+node np-tools.cjs memory-query --text "<milestone-summary>" --k 5 --type learning
+```
+
+If `memory.enabled=false` you'll get `memory-disabled` — silently skip.
+
+For `[VERIFIED]` / `[CITED]` hits whose subject overlaps the current milestone:
+- Reference them in the slice plan's `<context>` block as prior-art.
+- If a prior decision conflicts with a freshly-locked decision in `M<NNN>-CONTEXT.md`, the locked decision wins. Memory is never authoritative against locked-decisions.
+- Do NOT auto-promote `[ASSUMED]` hits; they remain advisory.
+
 ## CRITICAL: Reality-Check Before Planning (MANDATORY)
 
 Plans fail at execute-time when they encode assumptions the planner never verified against the actual repo. To stop the replan-after-execute loop, BEFORE writing any `S<NNN>-PLAN.md` you MUST empirically verify every load-bearing assumption and record the evidence inside the slice plan.

package/agents/np-researcher.md

@@ -36,6 +36,23 @@ anchor points for your research — do not propose replacements without
 explicit justification. If `INDEX.md` is absent, report and stop —
 `np:scan-codebase` must run first.
 
+## Vector-Memory Pre-recall (ADR-0014)
+
+**Before issuing external research**, query the local vector memory for prior decisions matching the current ticket. The hybrid pre-flight (`lib/knowledge-adapter.cjs`) already runs at swarm-entry; this step is the *agent-side* recall for context-injection into your `RESEARCH.md`.
+
+```bash
+node np-tools.cjs memory-query --text "<ticket-summary>" --k 5 --type research
+node np-tools.cjs memory-query --text "<ticket-summary>" --k 3 --type learning
+```
+
+If `memory.enabled=false` you'll get `memory-disabled` — silently skip; this section is opt-in and additive.
+
+For each hit, surface the underlying decision in your `RESEARCH.md` with the original `provenance` preserved:
+- `[VERIFIED]` / `[CITED]` hits become `[CACHED:VERIFIED]` / `[CACHED:CITED]` in your output — the merged `<consensus_meta>` block carries `cache_hit: true`.
+- `[ASSUMED]` hits stay `[CACHED:ASSUMED]` — flagged for plan-checker scrutiny, never auto-promoted.
+
+A high-confidence cache match should *replace* external research for that decision, not duplicate it. Save the swarm tokens.
+
 ## Handoff Protocol
 
 Agent handoffs are persistent notes between phase invocations. Before researching, check handoffs addressed to `np-researcher`:

package/bin/np-tools/_commands.cjs

@@ -59,6 +59,15 @@ const COMMANDS = [
   { name: 'handoff-read',      category: 'Capture',  description: 'Read a single handoff by id (returns frontmatter + body as JSON)', description_de: 'Liest einzelnen Handoff per ID (gibt Frontmatter + Body als JSON zurück)' },
   { name: 'handoff-list',      category: 'Capture',  description: 'List handoffs (JSON array); filter with --for AGENT, --milestone M<NNN>, --status STATUS, --global', description_de: 'Listet Handoffs (JSON-Array); filtert mit --for AGENT, --milestone M<NNN>, --status STATUS, --global' },
   { name: 'handoff-status',    category: 'Capture',  description: 'Update a handoff status (open|read|acted|archived)', description_de: 'Aktualisiert Handoff-Status (open|read|acted|archived)' },
+  { name: 'messages-send',     category: 'Capture',  description: 'Send addressed inter-agent message (request|response|notify) to .nubos-pilot/messages/inbox/<to>/. ADR-0015', description_de: 'Sendet adressierte Inter-Agent-Nachricht (request|response|notify) an .nubos-pilot/messages/inbox/<to>/. ADR-0015' },
+  { name: 'messages-inbox',    category: 'Capture',  description: 'List ungelesen messages addressed to an agent (filterable by --kind, --since, --task)', description_de: 'Listet ungelesen Messages für einen Agent (filterbar via --kind, --since, --task)' },
+  { name: 'messages-archive',  category: 'Capture',  description: 'Move an inbox message to archive/; refuses request+expects_reply without prior response', description_de: 'Verschiebt Inbox-Message nach archive/; weigert sich bei request+expects_reply ohne Reply' },
+  { name: 'messages-thread',   category: 'Capture',  description: 'Print full reply-chain for a message id (causal order)', description_de: 'Gibt vollständige Reply-Chain für eine Message-ID aus (kausale Reihenfolge)' },
+  { name: 'memory-index',      category: 'Capture',  description: 'Bulk-index records into vector memory (--records JSON or --records-file JSONL). Opt-in via memory.enabled=true. ADR-0014', description_de: 'Bulk-Index für Records ins Vector-Memory (--records JSON oder --records-file JSONL). Opt-in via memory.enabled=true. ADR-0014' },
+  { name: 'memory-query',      category: 'Utility',  description: 'Query vector memory by text; returns top-k JSON hits with score + record. Filter by --type, --phase, --tags', description_de: 'Fragt Vector-Memory by Text; liefert Top-k JSON-Hits mit Score + Record. Filter via --type, --phase, --tags' },
+  { name: 'memory-add',        category: 'Capture',  description: 'Add a single record to vector memory (--type, --title, --body, optional --tags / --provenance / --phase / --id)', description_de: 'Fügt einzelnen Record in Vector-Memory ein (--type, --title, --body, optional --tags / --provenance / --phase / --id)' },
+  { name: 'memory-rebuild',    category: 'Utility',  description: 'Force full re-embed from records.jsonl; required after embedding-model change. ADR-0014', description_de: 'Erzwingt komplettes Re-Embed aus records.jsonl; erforderlich nach Embedding-Model-Wechsel. ADR-0014' },
+  { name: 'memory-stats',      category: 'Utility',  description: 'Print vector-memory stats (count, dim, model, schema_version, created_at)', description_de: 'Gibt Vector-Memory-Stats aus (count, dim, model, schema_version, created_at)' },
   { name: 'worktree-create',   category: 'Execution', description: 'Create an isolated git worktree for a slice (branch np/<mid>-<sid> off current HEAD) under .nubos-pilot/worktrees/', description_de: 'Erstellt isoliertes Git-Worktree für eine Slice (Branch np/<mid>-<sid> vom aktuellen HEAD) unter .nubos-pilot/worktrees/' },
   { name: 'worktree-remove',   category: 'Execution', description: 'Remove a slice worktree + delete its branch (--force / --keep-branch)', description_de: 'Entfernt Slice-Worktree + löscht zugehörigen Branch (--force / --keep-branch)' },
   { name: 'worktree-list',     category: 'Execution', description: 'List all nubos-pilot-managed slice worktrees (np/<mid>-<sid> only) as JSON', description_de: 'Listet alle nubos-pilot-verwalteten Slice-Worktrees (nur np/<mid>-<sid>) als JSON' },

package/bin/np-tools/_memory-resolve.cjs

@@ -0,0 +1,41 @@
+'use strict';
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { readConfigPath } = require('../../lib/config.cjs');
+const { createMemory } = require('../../lib/memory.cjs');
+
+function resolveMemory(opts) {
+  const o = opts || {};
+  const cwd = o.cwd || process.cwd();
+
+  if (o.provider && o.indexEngine) {
+    return createMemory({
+      provider: o.provider,
+      indexEngine: o.indexEngine,
+      cwd,
+      alpha: o.alpha,
+    });
+  }
+
+  const enabled = readConfigPath(cwd, 'memory.enabled', false);
+  if (!enabled) {
+    throw new NubosPilotError(
+      'memory-disabled',
+      'memory layer is disabled. Set "memory": { "enabled": true } in .nubos-pilot/config.json (ADR-0014).',
+      {},
+    );
+  }
+
+  const model = readConfigPath(cwd, 'memory.model', 'Xenova/bge-small-en-v1.5');
+  const alpha = readConfigPath(cwd, 'memory.alpha', 0.6);
+
+  const { createLocalProvider } = require('../../lib/memory-provider-local.cjs');
+  const { createUsearchIndex } = require('../../lib/memory-index-usearch.cjs');
+
+  const provider = createLocalProvider({ model });
+  const indexEngine = createUsearchIndex({ dim: provider.dim });
+
+  return createMemory({ provider, indexEngine, cwd, alpha });
+}
+
+module.exports = { resolveMemory };

package/bin/np-tools/loop-commands.test.cjs

@@ -670,6 +670,132 @@ test('LCLI-RR-11: phase=commit --force-commit-phase bypasses preconditions and s
   assert.equal(cp.nubosloop.forced_commit_phase, true);
 });
 
+test('LCLI-RR-MSG-1: phase=commit refused while pendingReplies > 0 (ADR-0015)', () => {
+  const r = _mkRoot();
+  checkpoint.startTask({ id: 'M001-S001-T0001' }, r);
+  const nubosloop = require('../../lib/nubosloop.cjs');
+  nubosloop.recordLoopState('M001-S001-T0001', { round: 1 }, r);
+  checkpoint.mergeCheckpoint('M001-S001-T0001', (cur) => ({
+    nubosloop: Object.assign({}, (cur && cur.nubosloop) || {}, {
+      verify_exit_code: 0,
+      findings: [],
+    }),
+  }), r);
+  const messaging = require('../../lib/messaging.cjs');
+  messaging.send({
+    from: 'np-critic', to: 'np-executor',
+    phase: 'M001-S001-T0001', kind: 'request',
+    subject: 'fix-x', body: 'please fix', expects_reply: true,
+  }, r);
+
+  const loopRunRound = require('./loop-run-round.cjs');
+  assert.throws(
+    () => loopRunRound.run(['M001-S001-T0001', '--phase', 'commit'], { cwd: r, stdout: _cap().stub }),
+    (err) => err && err.code === 'loop-commit-precondition-missing'
+      && err.details && err.details.missing === 'pending-replies-cleared'
+      && err.details.observed_pending_replies === 1,
+  );
+});
+
+test('LCLI-RR-MSG-2: phase=commit succeeds and sweeps task messages once replies are archived', () => {
+  const r = _mkRoot();
+  checkpoint.startTask({ id: 'M001-S001-T0001' }, r);
+  const nubosloop = require('../../lib/nubosloop.cjs');
+  nubosloop.recordLoopState('M001-S001-T0001', { round: 1 }, r);
+  checkpoint.mergeCheckpoint('M001-S001-T0001', (cur) => ({
+    nubosloop: Object.assign({}, (cur && cur.nubosloop) || {}, {
+      verify_exit_code: 0,
+      findings: [],
+    }),
+  }), r);
+  const messaging = require('../../lib/messaging.cjs');
+  const req = messaging.send({
+    from: 'np-critic', to: 'np-executor',
+    phase: 'M001-S001-T0001', kind: 'request',
+    subject: 'fix-x', body: 'please fix', expects_reply: true,
+  }, r);
+  messaging.send({
+    from: 'np-executor', to: 'np-critic',
+    phase: 'M001-S001-T0001', kind: 'response',
+    subject: 'fix-x', body: 'done', in_reply_to: req.id,
+  }, r);
+  messaging.archive(req.id, r);
+
+  const cap = _cap();
+  const loopRunRound = require('./loop-run-round.cjs');
+  loopRunRound.run(['M001-S001-T0001', '--phase', 'commit'], { cwd: r, stdout: cap.stub });
+  const out = JSON.parse(cap.get());
+  assert.equal(out.next_action, 'commit-task');
+  assert.equal(out.messages_swept, 2);
+
+  const inboxLeft = messaging.inbox('np-critic', { phase: 'M001-S001-T0001' }, r);
+  assert.equal(inboxLeft.length, 0);
+  const archived = path.join(r, '.nubos-pilot', 'messages', 'archive', 'by-task', 'M001-S001-T0001');
+  assert.ok(fs.existsSync(archived));
+});
+
+test('LCLI-RR-MEM-1: phase=commit indexes the just-logged learning into memory when memory.enabled=true', () => {
+  const r = _mkRoot();
+  fs.writeFileSync(
+    path.join(r, '.nubos-pilot', 'config.json'),
+    JSON.stringify({ memory: { enabled: true, model: 'mock-v1', alpha: 0.6 } }),
+    'utf-8',
+  );
+  checkpoint.startTask({ id: 'M001-S001-T0001' }, r);
+  const nubosloop = require('../../lib/nubosloop.cjs');
+  nubosloop.recordLoopState('M001-S001-T0001', { round: 1 }, r);
+  checkpoint.mergeCheckpoint('M001-S001-T0001', (cur) => ({
+    nubosloop: Object.assign({}, (cur && cur.nubosloop) || {}, {
+      verify_exit_code: 0,
+      findings: [],
+    }),
+  }), r);
+
+  const cap = _cap();
+  const loopRunRound = require('./loop-run-round.cjs');
+  loopRunRound.run(
+    ['M001-S001-T0001', '--phase', 'commit',
+     '--learning-pattern', 'use jose for jwt',
+     '--learning-outcome', 'verified'],
+    { cwd: r, stdout: cap.stub },
+  );
+  const out = JSON.parse(cap.get());
+  assert.equal(out.next_action, 'commit-task');
+  assert.ok(
+    out.memory_skip_reason === 'memory-transformers-not-installed'
+    || out.memory_skip_reason === 'memory-usearch-not-installed'
+    || out.memory_added !== null,
+    'memory write-back should either succeed or skip with a known dep-missing code; got: '
+    + JSON.stringify({ memory_added: out.memory_added, memory_skip_reason: out.memory_skip_reason }),
+  );
+});
+
+test('LCLI-RR-MEM-2: phase=commit reports memory_skip_reason=memory-disabled when feature off', () => {
+  const r = _mkRoot();
+  checkpoint.startTask({ id: 'M001-S001-T0001' }, r);
+  const nubosloop = require('../../lib/nubosloop.cjs');
+  nubosloop.recordLoopState('M001-S001-T0001', { round: 1 }, r);
+  checkpoint.mergeCheckpoint('M001-S001-T0001', (cur) => ({
+    nubosloop: Object.assign({}, (cur && cur.nubosloop) || {}, {
+      verify_exit_code: 0,
+      findings: [],
+    }),
+  }), r);
+
+  const cap = _cap();
+  const loopRunRound = require('./loop-run-round.cjs');
+  loopRunRound.run(
+    ['M001-S001-T0001', '--phase', 'commit',
+     '--learning-pattern', 'use jose for jwt',
+     '--learning-outcome', 'verified'],
+    { cwd: r, stdout: cap.stub },
+  );
+  const out = JSON.parse(cap.get());
+  assert.equal(out.memory_added, null);
+  assert.equal(out.memory_skip_reason, 'memory-disabled');
+  assert.equal(out.messages_swept, 0);
+});
+
 // Layer C — audit-trail evidence enforcement -------------------------------
 
 test('LCLI-RR-12: post-executor refuses without np-executor audit (R1)', () => {

package/bin/np-tools/loop-run-round.cjs

@@ -17,6 +17,8 @@ const path = require('node:path');
 const { NubosPilotError, safeAssign } = require('../../lib/core.cjs');
 const checkpoint = require('../../lib/checkpoint.cjs');
 const nubosloop = require('../../lib/nubosloop.cjs');
+const messaging = require('../../lib/messaging.cjs');
+const config = require('../../lib/config.cjs');
 const args = require('./_args.cjs');
 
 const TASK_ID_RE = checkpoint.TASK_ID_RE;
@@ -475,6 +477,23 @@ function _runCommit(taskId, list, cwd) {
         { taskId, missing: 'findings=[]', observed_findings_count: np.findings.length },
       );
     }
+    let pendingReplies;
+    try { pendingReplies = messaging.pendingReplies(taskId, cwd); }
+    catch { pendingReplies = []; }
+    if (pendingReplies.length > 0) {
+      throw new NubosPilotError(
+        'loop-commit-precondition-missing',
+        'phase=commit refused: ' + pendingReplies.length +
+        ' inter-agent message(s) with expects_reply=true are unarchived for ' + taskId +
+        '. Each request needs a response (kind=response, --in-reply-to <id>) before commit. ADR-0015.',
+        {
+          taskId,
+          missing: 'pending-replies-cleared',
+          observed_pending_replies: pendingReplies.length,
+          pending_subjects: pendingReplies.map((m) => m.subject),
+        },
+      );
+    }
   }
   const pattern = args.getFlag(list, '--learning-pattern') || null;
   const outcome = args.getFlag(list, '--learning-outcome') || 'verified';
@@ -498,6 +517,39 @@ function _runCommit(taskId, list, cwd) {
       logged = { error: err && err.code ? err.code : 'auto-log-learning-failed' };
     }
   }
+
+  let memoryAdded = null;
+  let memorySkipReason = null;
+  if (config.readConfigPath(cwd, 'memory.enabled', false)) {
+    if (logged && !logged.error && pattern) {
+      try {
+        const { resolveMemory } = require('./_memory-resolve.cjs');
+        const memory = resolveMemory({ cwd });
+        memoryAdded = memory.add({
+          type: 'learning',
+          phase: taskId,
+          title: pattern,
+          body: typeof logged.entry === 'object' && logged.entry ? JSON.stringify(logged.entry) : String(pattern),
+          provenance: outcome === 'verified' ? 'VERIFIED' : null,
+        });
+        if (memoryAdded && typeof memoryAdded.then === 'function') {
+          memoryAdded.catch(() => {});
+          memoryAdded = { pending: true };
+        }
+      } catch (err) {
+        memorySkipReason = err && err.code ? err.code : 'memory-add-failed';
+      }
+    } else {
+      memorySkipReason = 'no-pattern-to-index';
+    }
+  } else {
+    memorySkipReason = 'memory-disabled';
+  }
+
+  let messagesSwept = 0;
+  try { messagesSwept = messaging.sweepTaskOnCommit(taskId, cwd); }
+  catch { messagesSwept = 0; }
+
   checkpoint.mergeCheckpoint(
     taskId,
     (cur) => ({
@@ -521,6 +573,9 @@ function _runCommit(taskId, list, cwd) {
     next_action: 'commit-task',
     learning_logged: logged,
     learning_skip_reason: skipReason,
+    memory_added: memoryAdded,
+    memory_skip_reason: memorySkipReason,
+    messages_swept: messagesSwept,
     forced: force,
   };
 }

package/bin/np-tools/memory-add.cjs

@@ -0,0 +1,57 @@
+'use strict';
+
+const fs = require('node:fs');
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { resolveMemory } = require('./_memory-resolve.cjs');
+
+function _parseArgs(args) {
+  const out = {
+    type: null, phase: null, title: null, body: null, bodyFile: null,
+    tags: null, provenance: null, id: null,
+  };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--type')        { out.type = args[++i] || null; continue; }
+    if (a === '--phase')       { out.phase = args[++i] || null; continue; }
+    if (a === '--title')       { out.title = args[++i] || null; continue; }
+    if (a === '--body')        { out.body = args[++i] || null; continue; }
+    if (a === '--body-file')   { out.bodyFile = args[++i] || null; continue; }
+    if (a === '--tags')        { out.tags = (args[++i] || '').split(',').filter(Boolean); continue; }
+    if (a === '--provenance')  { out.provenance = args[++i] || null; continue; }
+    if (a === '--id')          { out.id = args[++i] || null; continue; }
+  }
+  return out;
+}
+
+async function run(args, opts) {
+  const o = opts || {};
+  const stdout = o.stdout || process.stdout;
+  const parsed = _parseArgs(Array.isArray(args) ? args : []);
+
+  let body = parsed.body || '';
+  if (parsed.bodyFile) {
+    try { body = fs.readFileSync(parsed.bodyFile, 'utf-8'); }
+    catch (err) {
+      throw new NubosPilotError(
+        'memory-body-file-read-failed',
+        'failed to read --body-file: ' + (err && err.message),
+        { path: parsed.bodyFile },
+      );
+    }
+  }
+
+  const memory = resolveMemory(o);
+  const result = await memory.add({
+    id: parsed.id || undefined,
+    type: parsed.type,
+    phase: parsed.phase,
+    title: parsed.title,
+    body,
+    tags: parsed.tags || undefined,
+    provenance: parsed.provenance || undefined,
+  });
+  stdout.write(JSON.stringify(result) + '\n');
+  return 0;
+}
+
+module.exports = { run, _parseArgs };

package/bin/np-tools/memory-index.cjs

@@ -0,0 +1,77 @@
+'use strict';
+
+const fs = require('node:fs');
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { resolveMemory } = require('./_memory-resolve.cjs');
+
+function _parseArgs(args) {
+  const out = { recordsFile: null, recordsJson: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--records-file') { out.recordsFile = args[++i] || null; continue; }
+    if (a === '--records')      { out.recordsJson = args[++i] || null; continue; }
+  }
+  return out;
+}
+
+function _readRecords(parsed) {
+  if (parsed.recordsFile) {
+    let raw;
+    try { raw = fs.readFileSync(parsed.recordsFile, 'utf-8'); }
+    catch (err) {
+      throw new NubosPilotError(
+        'memory-records-file-read-failed',
+        'failed to read --records-file: ' + (err && err.message),
+        { path: parsed.recordsFile },
+      );
+    }
+    try { return JSON.parse(raw); }
+    catch {
+      const lines = raw.split('\n').filter((l) => l.trim());
+      const out = [];
+      for (const l of lines) {
+        try { out.push(JSON.parse(l)); }
+        catch (err) {
+          throw new NubosPilotError(
+            'memory-records-file-invalid-json',
+            'records file is neither JSON array nor JSONL',
+            { line: l.slice(0, 80) },
+          );
+        }
+      }
+      return out;
+    }
+  }
+  if (parsed.recordsJson) {
+    try { return JSON.parse(parsed.recordsJson); }
+    catch (err) {
+      throw new NubosPilotError(
+        'memory-records-arg-invalid-json',
+        '--records is not valid JSON',
+        { error: err && err.message },
+      );
+    }
+  }
+  throw new NubosPilotError(
+    'memory-index-missing-records',
+    'either --records <json-array> or --records-file <path> required',
+    {},
+  );
+}
+
+async function run(args, opts) {
+  const o = opts || {};
+  const stdout = o.stdout || process.stdout;
+  const parsed = _parseArgs(Array.isArray(args) ? args : []);
+  const records = _readRecords(parsed);
+  if (!Array.isArray(records)) {
+    throw new NubosPilotError('memory-records-not-array', 'records must be a JSON array', {});
+  }
+
+  const memory = resolveMemory(o);
+  const result = await memory.index(records);
+  stdout.write(JSON.stringify(result) + '\n');
+  return 0;
+}
+
+module.exports = { run, _parseArgs };

package/bin/np-tools/memory-query.cjs

@@ -0,0 +1,39 @@
+'use strict';
+
+const { NubosPilotError } = require('../../lib/core.cjs');
+const { resolveMemory } = require('./_memory-resolve.cjs');
+
+function _parseArgs(args) {
+  const out = { text: null, k: 8, type: null, phase: null, tags: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--text')  { out.text = args[++i] || null; continue; }
+    if (a === '--k')     { out.k = Number(args[++i]) || 8; continue; }
+    if (a === '--type')  { out.type = args[++i] || null; continue; }
+    if (a === '--phase') { out.phase = args[++i] || null; continue; }
+    if (a === '--tags')  { out.tags = (args[++i] || '').split(',').filter(Boolean); continue; }
+    if (!a.startsWith('--') && !out.text) { out.text = a; continue; }
+  }
+  return out;
+}
+
+async function run(args, opts) {
+  const o = opts || {};
+  const stdout = o.stdout || process.stdout;
+  const parsed = _parseArgs(Array.isArray(args) ? args : []);
+  if (!parsed.text) {
+    throw new NubosPilotError('memory-query-missing-text', 'query text required (positional or --text)', {});
+  }
+
+  const filter = {};
+  if (parsed.type) filter.type = parsed.type;
+  if (parsed.phase) filter.phase = parsed.phase;
+  if (Array.isArray(parsed.tags) && parsed.tags.length > 0) filter.tags = parsed.tags;
+
+  const memory = resolveMemory(o);
+  const hits = await memory.query(parsed.text, { k: parsed.k, filter });
+  stdout.write(JSON.stringify(hits) + '\n');
+  return 0;
+}
+
+module.exports = { run, _parseArgs };

package/bin/np-tools/memory-rebuild.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+const { resolveMemory } = require('./_memory-resolve.cjs');
+
+function _parseArgs() { return {}; }
+
+async function run(args, opts) {
+  const o = opts || {};
+  const stdout = o.stdout || process.stdout;
+  const memory = resolveMemory(o);
+  const result = await memory.rebuild();
+  stdout.write(JSON.stringify(result) + '\n');
+  return 0;
+}
+
+module.exports = { run, _parseArgs };

package/bin/np-tools/memory-stats.cjs

@@ -0,0 +1,15 @@
+'use strict';
+
+const { resolveMemory } = require('./_memory-resolve.cjs');
+
+function _parseArgs() { return {}; }
+
+function run(args, opts) {
+  const o = opts || {};
+  const stdout = o.stdout || process.stdout;
+  const memory = resolveMemory(o);
+  stdout.write(JSON.stringify(memory.stats()) + '\n');
+  return 0;
+}
+
+module.exports = { run, _parseArgs };