@yemi33/minions 0.1.2369 → 0.1.2370

package/dashboard/js/memory-search.js

@@ -0,0 +1,112 @@
+(function() {
+  function el(tag, className, text) {
+    const node = document.createElement(tag);
+    if (className) node.className = className;
+    if (text != null) node.textContent = text;
+    return node;
+  }
+
+  function open() {
+    document.getElementById('modal-title').textContent = 'Structured Memory';
+    const body = document.getElementById('modal-body');
+    body.textContent = '';
+    const controls = el('div');
+    controls.style.cssText = 'display:flex;gap:8px;margin-bottom:12px';
+    const input = el('input');
+    input.id = 'memory-search-query';
+    input.placeholder = 'Search facts, episodes, paths, or lessons';
+    input.style.cssText = 'flex:1;padding:8px;background:var(--bg);border:1px solid var(--border);border-radius:var(--radius-sm);color:var(--text)';
+    const status = el('select');
+    status.id = 'memory-search-status';
+    for (const value of ['active', 'superseded', 'retracted', 'expired']) {
+      const option = el('option', '', value);
+      option.value = value;
+      status.appendChild(option);
+    }
+    const button = el('button', 'btn-primary-lg', 'Search');
+    button.addEventListener('click', search);
+    input.addEventListener('keydown', event => { if (event.key === 'Enter') search(); });
+    controls.append(input, status, button);
+    body.append(controls, el('div', 'empty', 'Searches structured memory across all scopes. Results include provenance and lifecycle status.'));
+    body.lastChild.id = 'memory-search-results';
+    document.getElementById('modal').classList.add('open');
+    input.focus();
+  }
+
+  async function search() {
+    const input = document.getElementById('memory-search-query');
+    const status = document.getElementById('memory-search-status');
+    const results = document.getElementById('memory-search-results');
+    const query = input && input.value.trim();
+    if (!query || !results) return;
+    results.textContent = 'Searching...';
+    try {
+      const url = '/api/memory-records/search?q=' + encodeURIComponent(query)
+        + '&status=' + encodeURIComponent(status ? status.value : 'active') + '&limit=30';
+      const response = await fetch(url);
+      const data = await response.json();
+      if (!response.ok) throw new Error(data.error || 'search failed');
+      render(data.records || []);
+    } catch (error) {
+      results.textContent = 'Memory search failed: ' + error.message;
+    }
+  }
+
+  function render(records) {
+    const results = document.getElementById('memory-search-results');
+    if (!results) return;
+    results.textContent = '';
+    results.className = records.length ? '' : 'empty';
+    if (!records.length) {
+      results.textContent = 'No matching memory records.';
+      return;
+    }
+    for (const record of records) {
+      const item = el('div', 'kb-item');
+      item.style.marginBottom = '8px';
+      const body = el('div', 'kb-item-body');
+      body.appendChild(el('div', 'kb-item-title', record.title || record.id));
+      const meta = el('div', 'kb-item-meta');
+      const fields = [
+        record.memoryType,
+        record.scopeType + (record.scopeKey ? ':' + record.scopeKey : ''),
+        record.trust,
+        record.status,
+        record.sourceRef || record.sourcePath || record.sourceType,
+        Number.isFinite(record.ftsRank) ? 'rank ' + record.ftsRank.toFixed(2) : '',
+      ].filter(Boolean);
+      for (const field of fields) meta.appendChild(el('span', '', field));
+      body.appendChild(meta);
+      body.appendChild(el('div', 'kb-item-preview',
+        (record.body || '') + (record.bodyTruncated ? '\n\n[preview truncated]' : '')));
+      const actions = el('div');
+      actions.style.cssText = 'display:flex;gap:6px;margin-top:8px';
+      for (const action of ['pin', record.status === 'active' ? 'retract' : 'restore']) {
+        const button = el('button', 'pr-pager-btn', action);
+        button.addEventListener('click', () => update(record.id, action));
+        actions.appendChild(button);
+      }
+      body.appendChild(actions);
+      item.appendChild(body);
+      results.appendChild(item);
+    }
+  }
+
+  async function update(id, action) {
+    try {
+      const response = await fetch('/api/memory-records/' + encodeURIComponent(id) + '/action', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ action }),
+      });
+      const data = await response.json();
+      if (!response.ok) throw new Error(data.error || action + ' failed');
+      showToast('kb-sweep-toast', 'Memory record ' + action + ' complete', true);
+      search();
+    } catch (error) {
+      showToast('kb-sweep-toast', 'Memory update failed: ' + error.message, false);
+    }
+  }
+
+  window.MinionsMemorySearch = { open };
+})();

package/dashboard/js/render-kb.js

@@ -204,6 +204,21 @@ async function kbSweep() {
   }
 }
 
+let _memorySearchUiLoading = false;
+function openMemorySearchModal() {
+  if (window.MinionsMemorySearch) return window.MinionsMemorySearch.open();
+  if (_memorySearchUiLoading) return;
+  _memorySearchUiLoading = true;
+  const script = document.createElement('script');
+  script.src = '/assets/memory-search.js';
+  script.onload = () => window.MinionsMemorySearch.open();
+  script.onerror = () => {
+    _memorySearchUiLoading = false;
+    showToast('kb-sweep-toast', 'Memory search UI failed to load', false);
+  };
+  document.head.appendChild(script);
+}
+
 function openCreateKbModal() {
   document.getElementById('modal-title').textContent = 'New Knowledge Base Entry';
   document.getElementById('modal-body').innerHTML =

package/dashboard/js/settings.js

@@ -595,6 +595,16 @@ async function openSettings() {
       settingsField('Consolidation Threshold', 'set-inboxConsolidateThreshold', e.inboxConsolidateThreshold || 5, 'notes', 'Inbox notes before auto-consolidation') +
       settingsField('Version Check Interval', 'set-versionCheckInterval', e.versionCheckInterval || 3600000, 'ms', 'How often to check npm for updates (default: 1 hour)') +
     '</div>' +
+    '<h4>Agent Memory</h4>' +
+    '<div class="settings-stack">' +
+      settingsToggle('Shadow mode', 'set-memoryRetrievalShadowMode', e.memoryRetrievalShadowMode !== false, 'Measure retrieval without changing prompts') +
+      settingsToggle('Capture task episodes', 'set-memoryEpisodicCapture', !!e.memoryEpisodicCapture, 'Store compact outcomes, never transcripts') +
+    '</div>' +
+    '<div class="settings-grid-2">' +
+      settingsField('Retrieved records', 'set-memoryRetrievalTopK', e.memoryRetrievalTopK || 8, 'records', '1–30') +
+      settingsField('Prompt budget', 'set-memoryRetrievalMaxBytes', e.memoryRetrievalMaxBytes || 8192, 'bytes', '1024–65536') +
+      settingsField('Candidate pool', 'set-memoryRetrievalCandidateLimit', e.memoryRetrievalCandidateLimit || 50, 'records', '5–200') +
+    '</div>' +
     '<h4>Operator &amp; Comments</h4>' +
     '<div class="settings-grid-2">' +
       settingsField('Operator login (used in branch names)', 'set-operatorLogin', e.operatorLogin || '', '', 'Override the human operator login used in user/<loginname>/<wi-id>-<slug> branches. Empty = auto-resolve via gh / git email / OS username (currently resolves to: ' + (e._resolvedOperatorLogin || 'unknown') + ')') +
@@ -1089,6 +1099,11 @@ async function saveSettings() {
       tickInterval: document.getElementById('set-tickInterval').value,
       maxConcurrent: document.getElementById('set-maxConcurrent').value,
       inboxConsolidateThreshold: document.getElementById('set-inboxConsolidateThreshold').value,
+      memoryRetrievalShadowMode: document.getElementById('set-memoryRetrievalShadowMode').checked,
+      memoryEpisodicCapture: document.getElementById('set-memoryEpisodicCapture').checked,
+      memoryRetrievalTopK: document.getElementById('set-memoryRetrievalTopK').value,
+      memoryRetrievalMaxBytes: document.getElementById('set-memoryRetrievalMaxBytes').value,
+      memoryRetrievalCandidateLimit: document.getElementById('set-memoryRetrievalCandidateLimit').value,
       agentTimeout: document.getElementById('set-agentTimeout').value,
       maxTurns: document.getElementById('set-maxTurns').value,
       heartbeatTimeout: document.getElementById('set-heartbeatTimeout').value,

package/dashboard/pages/inbox.html

@@ -7,7 +7,7 @@
         <div id="notes-list">Loading...</div>
       </section>
       <section>
-        <h2>Knowledge Base <span class="count" id="kb-count">0</span> <button class="btn-add" style="margin-left:8px" onclick="openCreateKbModal()">+ New</button><button id="kb-sweep-btn" onclick="kbSweep()" style="font-size:var(--text-xs);padding:2px 8px;background:var(--surface2);border:1px solid var(--border);color:var(--muted);border-radius:4px;cursor:pointer;margin-left:8px;vertical-align:middle">sweep</button><span id="kb-swept-time" style="font-size:var(--text-sm);color:var(--muted);font-weight:400;text-transform:none;letter-spacing:0;margin-left:8px"></span></h2>
+        <h2>Knowledge Base <span class="count" id="kb-count">0</span> <button class="btn-add" style="margin-left:8px" onclick="openCreateKbModal()">+ New</button><button class="btn-add" style="margin-left:8px" onclick="openMemorySearchModal()">Memory search</button><button id="kb-sweep-btn" onclick="kbSweep()" style="font-size:var(--text-xs);padding:2px 8px;background:var(--surface2);border:1px solid var(--border);color:var(--muted);border-radius:4px;cursor:pointer;margin-left:8px;vertical-align:middle">sweep</button><span id="kb-swept-time" style="font-size:var(--text-sm);color:var(--muted);font-weight:400;text-transform:none;letter-spacing:0;margin-left:8px"></span></h2>
         <div id="kb-sweep-toast" class="cmd-toast cmd-toast-inline" style="margin:6px 0"></div>
         <div class="kb-tabs" id="kb-tabs"></div>
         <div class="kb-list" id="kb-list"><p class="empty">No knowledge entries yet. Notes are classified here after consolidation.</p></div>

package/dashboard.js

@@ -65,6 +65,7 @@ const prTrack = require('./engine/pr-track');
 const features = require('./engine/features');
 const ccWorkerPool = require('./engine/cc-worker-pool');
 const diagnosticsMemory = require('./engine/diagnostics-memory');
+const memoryStore = require('./engine/memory-store');
 const os = require('os');
 
 const { safeRead, safeReadOrNull, safeReadDir, safeWrite, safeJson, safeJsonObj, safeJsonArr, safeJsonNoRestore, safeUnlink, mutateJsonFileLocked, mutateTextFileLocked, mutateControl, mutateCooldowns, mutateWorkItems, getProjects: _getProjects, DONE_STATUSES, WI_STATUS, WORK_TYPE, WORKTREE_REQUIRING_TYPES, reopenWorkItem } = shared;
@@ -7896,6 +7897,46 @@ const server = http.createServer(async (req, res) => {
     return jsonReply(res, 200, result);
   }
 
+  function handleMemoryRecordsSearch(req, res) {
+    const url = new URL(req.url, 'http://localhost');
+    const query = String(url.searchParams.get('q') || '').trim();
+    if (!query) return jsonReply(res, 400, { error: 'q is required' });
+    if (query.length > 500) return jsonReply(res, 400, { error: 'q must be 500 characters or fewer' });
+    const limitRaw = Number.parseInt(url.searchParams.get('limit') || '20', 10);
+    const limit = Number.isFinite(limitRaw) ? Math.max(1, Math.min(100, limitRaw)) : 20;
+    const status = url.searchParams.get('status') || 'active';
+    if (!memoryStore.STATUSES.has(status)) return jsonReply(res, 400, { error: 'invalid status' });
+    try {
+      const records = memoryStore.searchMemoryRecords(query, {
+        allScopes: true,
+        statuses: [status],
+        limit,
+      });
+      const boundedRecords = records.map(record => ({
+        ...record,
+        body: String(record.body || '').slice(0, 4000),
+        bodyTruncated: String(record.body || '').length > 4000,
+      }));
+      return jsonReply(res, 200, { query, count: boundedRecords.length, records: boundedRecords });
+    } catch (e) {
+      return jsonReply(res, 400, { error: e.message });
+    }
+  }
+
+  async function handleMemoryRecordAction(req, res, match) {
+    const id = decodeURIComponent((match && match[1]) || '').trim();
+    if (!id) return jsonReply(res, 400, { error: 'memory record id is required' });
+    try {
+      const body = await readBody(req);
+      const record = memoryStore.updateMemoryRecordState(id, String(body.action || '').trim());
+      if (!record) return jsonReply(res, 404, { error: 'memory record not found' });
+      invalidateStatusCache();
+      return jsonReply(res, 200, { ok: true, record });
+    } catch (e) {
+      return jsonReply(res, 400, { error: e.message });
+    }
+  }
+
   async function handleKnowledgeRead(req, res, match) {
     const cat = match[1];
     // P-bfa2b-kb-path-traversal — whitelist the category param BEFORE any
@@ -11360,6 +11401,9 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           // 1 floor (sequential fallback) and 20 ceiling (above this the LLM
           // provider's per-second rate limits dominate; throughput gains taper).
           preDispatchEvalConcurrency: [1, 20],
+          memoryRetrievalTopK: [1, 30],
+          memoryRetrievalMaxBytes: [1024, 65536],
+          memoryRetrievalCandidateLimit: [5, 200],
         };
         for (const [key, [min, max]] of Object.entries(numericFields)) {
           if (e[key] !== undefined) {
@@ -14560,7 +14604,16 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } },
 
     // Knowledge base
+    { method: 'GET', path: '/assets/memory-search.js', desc: 'Serve the lazy-loaded structured memory search UI', handler: (req, res) => {
+      const content = safeRead(path.join(MINIONS_DIR, 'dashboard', 'js', 'memory-search.js'));
+      if (content == null) { res.statusCode = 404; return res.end('not found'); }
+      res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
+      res.setHeader('Cache-Control', 'no-cache');
+      res.end(content);
+    } },
     { method: 'GET', path: '/api/knowledge', desc: 'List all knowledge base entries grouped by category', handler: handleKnowledgeList },
+    { method: 'GET', path: /^\/api\/memory-records\/search(?:\?.*)?$/, template: '/api/memory-records/search', desc: 'Search structured memory records with provenance and lifecycle status', params: 'q, status?, limit?', handler: handleMemoryRecordsSearch },
+    { method: 'POST', path: /^\/api\/memory-records\/([^/?]+)\/action$/, template: '/api/memory-records/<id>/action', desc: 'Pin, retract, or restore a structured memory record', params: 'action (pin|retract|restore)', handler: handleMemoryRecordAction },
     { method: 'POST', path: '/api/knowledge', desc: 'Create a knowledge base entry', params: 'category, title, content', handler: async (req, res) => {
       const body = await readBody(req);
       const { category, title, content } = body;
@@ -14572,7 +14625,21 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       const dir = path.dirname(filePath);
       if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
       const header = '# ' + title + '\n\n*Created by human teammate on ' + new Date().toISOString().slice(0, 10) + '*\n\n';
-      safeWrite(filePath, header + content);
+      const fullContent = header + content;
+      safeWrite(filePath, fullContent);
+      memoryStore.upsertMemoryRecord({
+        memoryType: 'semantic',
+        scopeType: 'global',
+        title,
+        body: fullContent,
+        tags: [category],
+        sourceType: 'knowledge-base',
+        sourcePath: path.relative(MINIONS_DIR, filePath).replace(/\\/g, '/'),
+        sourceRef: path.relative(MINIONS_DIR, filePath).replace(/\\/g, '/'),
+        trust: 'human',
+        importance: 0.8,
+        confidence: 1,
+      });
       queries.invalidateKnowledgeBaseCache();
       invalidateStatusCache();
       recordCcTurnIfPresent(req, { kind: 'knowledge', title, path: filePath });

package/docs/team-memory.md

@@ -1,6 +1,6 @@
 # Team Memory
 
-Minions agents share knowledge through a layered memory system. Before an agent does any independent research — web searches, broad codebase exploration, external doc reading — it is expected to check what the team already knows.
+Minions agents share knowledge through a layered Markdown system plus a structured SQLite retrieval index. Before an agent does any independent research — web searches, broad codebase exploration, external doc reading — it is expected to check what the team already knows.
 
 This document describes the four-tier read order the engine enforces in dispatch prompts, the rationale, and the constraint that `knowledge/` is **sweep-write-only**.
 
@@ -12,7 +12,21 @@ Multiple agents work the same repository in parallel and across days. Without sh
 - Agents re-litigate decisions the team already made (drift, regressions).
 - Human-flagged warnings (e.g., "do not self-approve PRs") get ignored because they live outside the prompt.
 
-Team memory closes the loop. The engine injects pinned context and recent team notes into every dispatch prompt automatically, and the playbooks instruct agents to consult `knowledge/` and `notes/inbox/` on disk before going wider. This keeps work cheap, decisions sticky, and prior learnings reusable.
+Team memory closes the loop. The engine always injects pinned context. By default it also injects recent team and personal notes; when structured retrieval is enabled outside shadow mode, it replaces those broad appendices with a bounded task-relevant memory pack. Playbooks still instruct agents to consult `knowledge/` and `notes/inbox/` on disk before going wider.
+
+## Structured memory and retrieval
+
+Migration `017-agent-memory.js` backfills the existing Markdown sources into `memory_records` and an FTS5 index without deleting or rewriting those files. Records carry a type (`semantic`, `episodic`, or `procedural`), scope, trust level, source reference, confidence, importance, validity timestamps, and lifecycle status (`active`, `superseded`, `retracted`, or `expired`).
+
+`engine/memory-retrieval.js` searches active records in global, current-project, and assigned-agent scopes. It reranks lexical matches by scope, trust, path match, recency, importance, and confidence, then packs the best records into a strict byte budget. Agent- or external-authored procedural records are never recalled as instructions. Every injected pack remains inside an `<UNTRUSTED-INPUT>` fence.
+
+Rollout is controlled by the default-off `memoryRetrieval` feature flag:
+
+- **Flag off:** legacy prompt behavior.
+- **Flag on + `memoryRetrievalShadowMode: true` (default):** compute retrieval and telemetry, but keep legacy prompts.
+- **Flag on + shadow mode off:** inject `Relevant Memory` when retrieval finds evidence; otherwise fall back to legacy notes and personal memory.
+
+Settings expose top-k, candidate count, byte budget, shadow mode, and episodic capture. The Inbox page's **Memory search** control shows provenance and status and supports explicit pin, retract, and restore actions.
 
 ## The four-tier read order
 
@@ -54,7 +68,7 @@ Agents read `knowledge/` directly with grep/glob/view. They **do not** write to
 
 `notes.md` is the rolling team notebook. The consolidation sweep periodically merges high-signal findings from the inbox into dated `### YYYY-MM-DD` sections at the top of `notes.md`, with links back to the underlying KB entries.
 
-The engine injects `notes.md` into every prompt under a "Team Notes (MUST READ)" heading. When the file exceeds `ENGINE_DEFAULTS.maxNotesPromptBytes`, the engine keeps the most recent 10 sections, truncates the body, and appends a footer noting how many older sections live on disk so agents can read the full file when they need depth.
+In legacy and shadow modes, the engine injects `notes.md` under a "Team Notes (MUST READ)" heading. When active retrieval returns evidence, the bounded `Relevant Memory` pack replaces this broad appendix. When the file exceeds `ENGINE_DEFAULTS.maxNotesPromptBytes`, the legacy path keeps the most recent 10 sections, truncates the body, and appends a footer noting how many older sections live on disk.
 
 ### 4. `notes/inbox/` — fresh agent findings
 
@@ -70,7 +84,7 @@ The consolidation sweep is what eventually promotes inbox notes into `knowledge/
 
 #### Failure-path exception
 
-Inbox writes are **success artifacts only**. If a task fails, is blocked, is cancelled, or ends partial, the agent must **not** create an inbox note — the failure is reported through the completion JSON, the PR/work-item comment, or the task-specific failure channel instead. This keeps the inbox a clean signal and prevents noise from drowning out durable findings.
+Inbox writes are **success artifacts only**. If a task fails, is blocked, is cancelled, or ends partial, the agent must **not** create an inbox note. When `memoryEpisodicCapture` is enabled, lifecycle records a compact structured outcome for successful, partial, and failed dispatches; it never stores transcripts or chain-of-thought and skips nonce-mismatched or injection-flagged reports.
 
 ## Rationale
 

package/engine/consolidation.js

@@ -149,6 +149,44 @@ function extractInboxAgent(item) {
   return null;
 }
 
+function extractInboxProject(item) {
+  const content = String(item?.content || '');
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) return '';
+  const projectLine = fmMatch[1].split('\n').find(l => /^project:\s*/i.test(l));
+  return projectLine ? projectLine.replace(/^project:\s*/i, '').trim() : '';
+}
+
+function _indexMemoryRecord(record) {
+  try {
+    return require('./memory-store').upsertMemoryRecord(record);
+  } catch (err) {
+    log('warn', `Structured memory index write failed (${record?.sourceRef || 'unknown'}): ${err.message}`);
+    return null;
+  }
+}
+
+function _indexAgentMemoryItem(item, agent) {
+  const content = String(item?.content || '').trim();
+  if (!content) return null;
+  const titleMatch = content.match(/^#\s+(.+)/m);
+  return _indexMemoryRecord({
+    memoryType: 'semantic',
+    scopeType: 'agent',
+    scopeKey: agent,
+    title: titleMatch ? titleMatch[1].trim() : String(item.name || 'Agent learning').replace(/\.md$/, ''),
+    body: content,
+    tags: ['agent-memory', agent],
+    sourceType: 'inbox',
+    sourcePath: `notes/inbox/${item.name}`,
+    sourceRef: String(item.name),
+    trust: 'agent',
+    importance: 0.6,
+    confidence: 0.6,
+    metadata: { agent, project: extractInboxProject(item) || null },
+  });
+}
+
 /**
  * Append an inbox item to its author's personal memory file when the agent
  * is a known team member (must be present in `knownAgents`) and not a
@@ -207,6 +245,7 @@ function appendToAgentMemory(item, knownAgents, config) {
       const next = pruneAgentMemoryToBudget(existing + entry, agent, _pruneOptsFromConfig(config));
       safeWrite(memPath, next);
     });
+    _indexAgentMemoryItem(item, agent);
     return true;
   } catch (err) {
     log('warn', `Failed to append to knowledge/agents/${agent}.md: ${err.message}`);
@@ -571,7 +610,22 @@ function reconcileAndAppendToAgentMemory(item, knownAgents, config) {
       lockErr = err;
     }
 
-    if (reconciled) return true;
+    if (reconciled) {
+      const indexed = _indexAgentMemoryItem(item, agent);
+      if (indexed) {
+        try {
+          require('./memory-store').supersedeMatchingRecords({
+            scopeType: 'agent',
+            scopeKey: agent,
+            oldTexts: edits.map(edit => edit.old_text),
+            supersededBy: indexed.id,
+          });
+        } catch (err) {
+          log('warn', `Structured memory reconcile transition failed for ${agent}: ${err.message}`);
+        }
+      }
+      return true;
+    }
     if (lockErr) log('warn', `agent-memory reconcile: lock/write error for ${agent}: ${lockErr.message} — plain append`);
     return appendToAgentMemory(item, knownAgents, config);
   }).catch((err) => {
@@ -1291,6 +1345,22 @@ async function classifyToKnowledgeBase(items, config) {
       const frontmatter = `---\nsource: ${item.name}\nagent: ${agent}\ncategory: ${category}\ndate: ${dateStamp()}\nreusable: ${reusable}${isSystemAlert ? `\nalertHash: ${alertHash}` : ''}\n---\n\n`;
       try {
         safeWrite(kbPath, frontmatter + kbBody);
+        const project = extractInboxProject(item);
+        _indexMemoryRecord({
+          memoryType: 'semantic',
+          scopeType: project ? 'project' : 'global',
+          scopeKey: project || '',
+          title: titleMatch ? titleMatch[1].trim() : titleSlug,
+          body: frontmatter + kbBody,
+          tags: [category, agent, reusable ? 'reusable' : 'reference'],
+          sourceType: 'knowledge-base',
+          sourcePath: path.relative(shared.MINIONS_DIR, kbPath).replace(/\\/g, '/'),
+          sourceRef: item.name,
+          trust: 'agent',
+          importance: reusable ? 0.8 : 0.4,
+          confidence: 0.6,
+          metadata: { category, agent, reusable, inbox: item.name },
+        });
         classified++;
       } catch (err) {
         log('warn', `Failed to classify ${item.name} to knowledge base: ${err.message}`);
@@ -1430,6 +1500,7 @@ module.exports = {
   checkDuplicateHash,
   // per-agent memory routing
   extractInboxAgent,
+  extractInboxProject,
   appendToAgentMemory,
   reconcileAndAppendToAgentMemory,
   pruneAgentMemoryToBudget,

package/engine/db/migrations/017-agent-memory.js

@@ -0,0 +1,208 @@
+// engine/db/migrations/017-agent-memory.js
+//
+// Structured long-term memory for task-aware retrieval. Markdown remains the
+// operator-facing source/mirror during rollout; these rows are the searchable,
+// provenance-preserving representation used by dispatch.
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const KB_CATEGORIES = [
+  'architecture', 'conventions', 'project-notes', 'build-reports', 'reviews',
+  'learnings', 'decisions', 'incidents', 'api-notes',
+];
+
+function _resolveMinionsDir() {
+  return process.env.MINIONS_TEST_DIR
+    || process.env.MINIONS_HOME
+    || path.resolve(__dirname, '..', '..', '..');
+}
+
+function _read(filePath) {
+  try { return fs.readFileSync(filePath, 'utf8'); } catch { return ''; }
+}
+
+function _title(content, fallback) {
+  const match = String(content || '').match(/^#\s+(.+)/m);
+  return match ? match[1].trim() : fallback;
+}
+
+function _recordId(sourceType, sourceRef, content) {
+  const hash = crypto.createHash('sha256').update(`${sourceType}\0${sourceRef}\0${content}`).digest('hex');
+  return `M-${hash.slice(0, 24)}`;
+}
+
+function _contentHash(content) {
+  return crypto.createHash('sha256').update(String(content || '')).digest('hex');
+}
+
+function _splitAgentMemory(content) {
+  const boundary = /(?=\n---\n\n### \d{4}-\d{2}-\d{2}:)/g;
+  const parts = String(content || '').split(boundary).map(s => s.trim()).filter(Boolean);
+  return parts.length ? parts : [String(content || '')];
+}
+
+function _splitTeamNotes(content) {
+  const parts = String(content || '').split(/(?=^### \d{4}-\d{2}-\d{2})/m).map(s => s.trim()).filter(Boolean);
+  return parts.length ? parts : [String(content || '')];
+}
+
+module.exports = {
+  version: 17,
+  description: 'structured agent memory records, FTS5 retrieval, and retrieval telemetry',
+  up(db) {
+    db.exec(`
+      CREATE TABLE memory_records (
+        id              TEXT PRIMARY KEY,
+        memory_type     TEXT NOT NULL,
+        scope_type      TEXT NOT NULL,
+        scope_key       TEXT NOT NULL DEFAULT '',
+        title           TEXT NOT NULL,
+        body            TEXT NOT NULL,
+        tags            TEXT NOT NULL DEFAULT '[]',
+        source_type     TEXT NOT NULL,
+        source_path     TEXT,
+        source_ref      TEXT NOT NULL,
+        trust           TEXT NOT NULL DEFAULT 'agent',
+        importance      REAL NOT NULL DEFAULT 0.5,
+        confidence      REAL NOT NULL DEFAULT 0.5,
+        status          TEXT NOT NULL DEFAULT 'active',
+        valid_from      INTEGER,
+        valid_to        INTEGER,
+        supersedes_id   TEXT,
+        superseded_by   TEXT,
+        content_hash    TEXT NOT NULL,
+        metadata        TEXT NOT NULL DEFAULT '{}',
+        created_at      INTEGER NOT NULL,
+        updated_at      INTEGER NOT NULL
+      );
+      CREATE UNIQUE INDEX idx_memory_source_content
+        ON memory_records(source_type, source_ref, content_hash);
+      CREATE INDEX idx_memory_scope_status
+        ON memory_records(scope_type, scope_key, status);
+      CREATE INDEX idx_memory_type_status
+        ON memory_records(memory_type, status);
+      CREATE INDEX idx_memory_updated
+        ON memory_records(updated_at DESC);
+      CREATE INDEX idx_memory_supersedes
+        ON memory_records(supersedes_id);
+
+      CREATE VIRTUAL TABLE memory_records_fts USING fts5(
+        title,
+        body,
+        tags,
+        source_path,
+        content='memory_records',
+        content_rowid='rowid'
+      );
+
+      CREATE TRIGGER memory_records_ai AFTER INSERT ON memory_records BEGIN
+        INSERT INTO memory_records_fts(rowid, title, body, tags, source_path)
+        VALUES (new.rowid, new.title, new.body, new.tags, COALESCE(new.source_path, ''));
+      END;
+      CREATE TRIGGER memory_records_ad AFTER DELETE ON memory_records BEGIN
+        INSERT INTO memory_records_fts(memory_records_fts, rowid, title, body, tags, source_path)
+        VALUES ('delete', old.rowid, old.title, old.body, old.tags, COALESCE(old.source_path, ''));
+      END;
+      CREATE TRIGGER memory_records_au AFTER UPDATE OF title, body, tags, source_path ON memory_records BEGIN
+        INSERT INTO memory_records_fts(memory_records_fts, rowid, title, body, tags, source_path)
+        VALUES ('delete', old.rowid, old.title, old.body, old.tags, COALESCE(old.source_path, ''));
+        INSERT INTO memory_records_fts(rowid, title, body, tags, source_path)
+        VALUES (new.rowid, new.title, new.body, new.tags, COALESCE(new.source_path, ''));
+      END;
+
+      CREATE TABLE memory_retrieval_runs (
+        id               INTEGER PRIMARY KEY AUTOINCREMENT,
+        work_item_id     TEXT,
+        project          TEXT,
+        agent            TEXT,
+        query            TEXT NOT NULL,
+        candidate_count  INTEGER NOT NULL,
+        selected_count   INTEGER NOT NULL,
+        selected_bytes   INTEGER NOT NULL,
+        duration_ms      REAL NOT NULL,
+        shadow           INTEGER NOT NULL DEFAULT 1,
+        created_at       INTEGER NOT NULL
+      );
+      CREATE INDEX idx_memory_retrieval_created
+        ON memory_retrieval_runs(created_at DESC);
+    `);
+
+    const minionsDir = _resolveMinionsDir();
+    if (!minionsDir) return;
+
+    const insert = db.prepare(`
+      INSERT OR IGNORE INTO memory_records (
+        id, memory_type, scope_type, scope_key, title, body, tags,
+        source_type, source_path, source_ref, trust, importance, confidence,
+        status, valid_from, content_hash, metadata, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?)
+    `);
+    const now = Date.now();
+    const add = ({ type = 'semantic', scopeType = 'global', scopeKey = '', title, body,
+      tags = [], sourceType = 'legacy-markdown', sourcePath, sourceRef,
+      trust = 'agent', importance = 0.5, metadata = {} }) => {
+      if (!body || !String(body).trim()) return;
+      let mtime = now;
+      try { mtime = Math.round(fs.statSync(path.join(minionsDir, sourcePath)).mtimeMs); } catch {}
+      insert.run(
+        _recordId(sourceType, sourceRef, body),
+        type, scopeType, scopeKey, title || sourceRef, body, JSON.stringify(tags),
+        sourceType, sourcePath, sourceRef, trust, importance, 0.5,
+        mtime, _contentHash(body), JSON.stringify(metadata), mtime, now,
+      );
+    };
+
+    for (const category of KB_CATEGORIES) {
+      const dir = path.join(minionsDir, 'knowledge', category);
+      let files = [];
+      try { files = fs.readdirSync(dir).filter(f => f.endsWith('.md')); } catch {}
+      for (const file of files) {
+        const sourcePath = path.join('knowledge', category, file).replace(/\\/g, '/');
+        const body = _read(path.join(minionsDir, sourcePath));
+        add({
+          title: _title(body, file.replace(/\.md$/, '')),
+          body,
+          tags: [category],
+          sourceType: 'knowledge-base',
+          sourcePath,
+          sourceRef: sourcePath,
+          metadata: { category },
+        });
+      }
+    }
+
+    const agentDir = path.join(minionsDir, 'knowledge', 'agents');
+    let agentFiles = [];
+    try { agentFiles = fs.readdirSync(agentDir).filter(f => f.endsWith('.md') && f !== 'README.md'); } catch {}
+    for (const file of agentFiles) {
+      const agent = file.replace(/\.md$/, '').toLowerCase();
+      const sourcePath = path.join('knowledge', 'agents', file).replace(/\\/g, '/');
+      const body = _read(path.join(minionsDir, sourcePath));
+      _splitAgentMemory(body).forEach((section, index) => add({
+        scopeType: 'agent',
+        scopeKey: agent,
+        title: _title(section, `${agent} memory ${index + 1}`),
+        body: section,
+        tags: ['agent-memory', agent],
+        sourceType: 'agent-memory',
+        sourcePath,
+        sourceRef: `${sourcePath}#${index + 1}`,
+        metadata: { agent, section: index + 1 },
+      }));
+    }
+
+    const notesPath = 'notes.md';
+    const notes = _read(path.join(minionsDir, notesPath));
+    _splitTeamNotes(notes).forEach((section, index) => add({
+      title: _title(section, `Team notes ${index + 1}`),
+      body: section,
+      tags: ['team-notes'],
+      sourceType: 'team-notes',
+      sourcePath: notesPath,
+      sourceRef: `${notesPath}#${index + 1}`,
+      metadata: { section: index + 1 },
+    }));
+  },
+};

package/engine/features.js

@@ -95,6 +95,12 @@ const FEATURES = {
     addedIn: '0.1.2232',
     expires: '2026-12-01',
   },
+  'memoryRetrieval': {
+    description: 'Select bounded task-relevant long-term memory with SQLite FTS5 instead of injecting only recent team and personal notes. Starts in shadow mode by default.',
+    default: false,
+    addedIn: '0.1.2233',
+    expires: '2027-01-31',
+  },
 };
 
 const ENV_TRUTHY = new Set(['1', 'true', 'on', 'yes']);