codemini-cli 0.4.1 → 0.4.2

package/src/core/command-loader.js

@@ -58,6 +58,12 @@ function isSafeEntry(entry) {
   return entry !== '.' && entry !== '..' && !entry.includes('/') && !entry.includes('\\');
 }
 
+function setCommand(out, name, command) {
+  const existing = out.get(name);
+  if (existing?.source === 'bundled-skill') return;
+  out.set(name, command);
+}
+
 function loadMarkdownCommandsFromDir(baseDir, source, out) {
   if (!fs.existsSync(baseDir)) return;
   for (const entry of safeEntries(baseDir)) {
@@ -70,7 +76,7 @@ function loadMarkdownCommandsFromDir(baseDir, source, out) {
       if (fs.existsSync(commandFile)) {
         const raw = fs.readFileSync(commandFile, 'utf8');
         const parsed = parseFrontmatter(raw);
-        out.set(entry, {
+        setCommand(out, entry, {
           name: entry,
           source,
           path: commandFile,
@@ -85,7 +91,7 @@ function loadMarkdownCommandsFromDir(baseDir, source, out) {
       const name = entry.replace(/\.md$/, '');
       const raw = fs.readFileSync(full, 'utf8');
       const parsed = parseFrontmatter(raw);
-      out.set(name, {
+      setCommand(out, name, {
         name,
         source,
         path: full,
@@ -107,7 +113,7 @@ function loadLegacySkillsFromDir(baseDir, source, out) {
     if (!fs.existsSync(skillFile)) continue;
     const raw = fs.readFileSync(skillFile, 'utf8');
     const parsed = parseFrontmatter(raw);
-    out.set(entry, {
+    setCommand(out, entry, {
       name: entry,
       source: `${source}-skill`,
       path: skillFile,
@@ -131,7 +137,7 @@ function loadBundledSkillsFromDir(baseDir, out) {
     if (!fs.existsSync(skillFile)) continue;
     const raw = fs.readFileSync(skillFile, 'utf8');
     const parsed = parseFrontmatter(raw);
-    out.set(entry, {
+    setCommand(out, entry, {
       name: entry,
       source: 'bundled-skill',
       path: skillFile,
@@ -151,12 +157,13 @@ function loadInstalledSkillsFromRegistry(baseDir, registry, out) {
   for (const skill of registry.skills) {
     if (skill.enabled === false) continue;
     const name = skill.name;
+    if (out.has(name)) continue;
     const entry = skill.entryFile || 'SKILL.md';
     const full = path.join(baseDir, name, entry);
     if (!fs.existsSync(full)) continue;
     const raw = fs.readFileSync(full, 'utf8');
     const parsed = parseFrontmatter(raw);
-    out.set(name, {
+    setCommand(out, name, {
       name,
       source: 'registry-skill',
       path: full,

package/src/core/context-compact.js

@@ -1,4 +1,5 @@
-import { summarizeToolResult, trimInline } from './agent-loop.js';
+import { trimInline } from './string-utils.js';
+import { summarizeToolResult } from './tool-result-store.js';
 
 function textFromContent(content) {
   if (typeof content === 'string') return content;

package/src/core/dream-audit.js

@@ -56,6 +56,18 @@ function renderReport(report) {
     lines.push('');
   }
 
+  if (report.maintenance?.length) {
+    lines.push('## Memory Maintenance');
+    for (const item of report.maintenance) {
+      if (item.skipped) {
+        lines.push(`- [${item.scope}] skipped: ${item.reason}`);
+      } else {
+        lines.push(`- [${item.scope}] ${item.before} -> ${item.after} item(s)${item.changed ? ' changed' : ' marked clean'}`);
+      }
+    }
+    lines.push('');
+  }
+
   if (report.disagreements?.length) {
     lines.push('## Reviewer Disagreements');
     for (const d of report.disagreements) {

package/src/core/dream-consolidate.js

@@ -1,6 +1,13 @@
-import { listMemories, listInbox, archiveEntry, promoteMemory } from './memory-store.js';
+import {
+  getMemoryBucketMaintenance,
+  listMemories,
+  listInbox,
+  archiveEntry,
+  promoteMemory,
+  replaceMemoryBucket
+} from './memory-store.js';
 import { writeDreamAuditReport } from './dream-audit.js';
-import { evaluateInboxBatch } from './dream-evaluator.js';
+import { evaluateInboxBatch, evaluateMemoryMaintenance } from './dream-evaluator.js';
 
 const LONGTERM_TYPES = new Set(['preference', 'pattern', 'win', 'decision']);
 const OPERATIONAL_TYPES = new Set(['correction', 'failure', 'gap', 'observation']);
@@ -22,6 +29,76 @@ function memoryContainsSummary(memory, summaryKey) {
   return content.includes(summaryKey) || summary.includes(summaryKey);
 }
 
+function maintenanceScopes(scopeFilter) {
+  const scope = normalizeText(scopeFilter);
+  if (!scope) return ['user', 'global', 'project'];
+  if (scope === 'repo') return ['project'];
+  if (['user', 'global', 'project'].includes(scope)) return [scope];
+  return ['user', 'global', 'project'];
+}
+
+async function runMemoryMaintenance({
+  dryRun = false,
+  scope = null,
+  workspaceRoot = process.cwd(),
+  config = {}
+} = {}) {
+  const reports = [];
+  const filesChanged = [];
+
+  for (const memoryScope of maintenanceScopes(scope)) {
+    const maintenance = await getMemoryBucketMaintenance({ scope: memoryScope, workspaceRoot });
+    const items = await listMemories({ scope: memoryScope, workspaceRoot });
+    if (items.length === 0) {
+      reports.push({ scope: memoryScope, skipped: true, reason: 'empty' });
+      continue;
+    }
+    if (maintenance.fresh) {
+      reports.push({ scope: memoryScope, skipped: true, reason: 'already-maintained', itemCount: items.length });
+      continue;
+    }
+
+    const evaluated = dryRun
+      ? { items, archives: [] }
+      : await evaluateMemoryMaintenance({ scope: memoryScope, items, config, workspaceRoot });
+    if (evaluated.error) {
+      reports.push({ scope: memoryScope, skipped: true, reason: `maintenance-error: ${evaluated.error}`, itemCount: items.length });
+      continue;
+    }
+    const nextItems = Array.isArray(evaluated.items) && evaluated.items.length > 0 ? evaluated.items : items;
+    const changed =
+      JSON.stringify(nextItems.map((item) => [item.kind, item.content, item.summary, item.lifecycle || ''])) !==
+      JSON.stringify(items.map((item) => [item.kind, item.content, item.summary, item.lifecycle || '']));
+
+    if (!dryRun) {
+      await replaceMemoryBucket({
+        scope: memoryScope,
+        items: nextItems,
+        workspaceRoot,
+        markMaintained: true
+      });
+      filesChanged.push({
+        file: memoryScope === 'project' ? 'memory/project/*.json' : `memory/${memoryScope}.json`,
+        why: changed
+          ? `LLM-maintained ${items.length} item(s) into ${nextItems.length} item(s)`
+          : `Marked ${items.length} item(s) as maintained`
+      });
+    }
+
+    reports.push({
+      scope: memoryScope,
+      skipped: false,
+      before: items.length,
+      after: nextItems.length,
+      changed,
+      archives: evaluated.archives || [],
+      dryRun
+    });
+  }
+
+  return { reports, filesChanged };
+}
+
 export async function runDreamConsolidation({
   dryRun = false,
   scope = null,
@@ -31,9 +108,6 @@ export async function runDreamConsolidation({
 } = {}) {
   const scopeFilter = scope || null;
   const inbox = await listInbox({ scope: scopeFilter });
-  if (inbox.length === 0) {
-    return { ok: true, dryRun, message: 'No inbox entries to consolidate.', promotions: [], rejections: [], archives: [] };
-  }
 
   const [globalMemories, userMemories, projectMemories] = await Promise.all([
     listMemories({ scope: 'global', workspaceRoot }),
@@ -77,67 +151,63 @@ export async function runDreamConsolidation({
     candidates.push(entry);
   }
 
-  if (candidates.length === 0) {
-    const report = { timestamp: new Date().toISOString(), filesRead, filesChanged: [], candidatesGenerated: inbox.length, promotions, rejections, archives };
-    if (!dryRun && writeAudit) {
-      const reportPath = await writeDreamAuditReport(report);
-      report.auditReport = reportPath;
-    }
-    return { ok: true, dryRun, ...report };
-  }
-
-  /* ── Phase 2: LLM 批量评估（质量门控 + scope 分类 + 内容提炼） ── */
-  const llmResults = dryRun
-    ? candidates.map((e) => ({ id: e.id, action: 'keep', scope: 'global', kind: e.type || 'observation', content: e.details || e.summary, summary: e.summary, confidence: 0.9 }))
-    : await evaluateInboxBatch({ entries: candidates, config, workspaceRoot });
+  if (candidates.length > 0) {
+    /* ── Phase 2: LLM 批量评估（质量门控 + scope 分类 + 内容提炼） ── */
+    const llmResults = dryRun
+      ? candidates.map((e) => ({ id: e.id, action: 'keep', scope: 'global', kind: e.type || 'observation', content: e.details || e.summary, summary: e.summary, confidence: 0.9 }))
+      : await evaluateInboxBatch({ entries: candidates, config, workspaceRoot });
 
-  const resultMap = new Map(llmResults.map((r) => [r.id, r]));
+    const resultMap = new Map(llmResults.map((r) => [r.id, r]));
 
-  /* ── Phase 3: 按评估结果 promote 或 archive ─────────────────── */
-  for (const entry of candidates) {
-    const evaluation = resultMap.get(entry.id);
+    /* ── Phase 3: 按评估结果 promote 或 archive ─────────────────── */
+    for (const entry of candidates) {
+      const evaluation = resultMap.get(entry.id);
 
-    if (!evaluation || evaluation.action === 'discard') {
-      const reason = evaluation?.reason || 'LLM discarded';
-      if (!dryRun) await archiveEntry(entry, 'discarded-by-evaluator', reason);
-      rejections.push({ summary: entry.summary, reason: `evaluator-discard: ${reason}` });
-      continue;
-    }
-
-    const promoteScope = evaluation.scope || 'global';
-    const lifecycle = chooseLifecycle(evaluation.kind);
-    const enrichedEntry = {
-      ...entry,
-      /* 用 LLM 提炼后的内容覆盖原始报错 */
-      summary: evaluation.summary || entry.summary,
-      details: evaluation.content || entry.details || entry.summary,
-      type: evaluation.kind || entry.type || 'observation'
-    };
+      if (!evaluation || evaluation.action === 'discard') {
+        const reason = evaluation?.reason || 'LLM discarded';
+        if (!dryRun) await archiveEntry(entry, 'discarded-by-evaluator', reason);
+        rejections.push({ summary: entry.summary, reason: `evaluator-discard: ${reason}` });
+        continue;
+      }
 
-    if (!dryRun) {
-      try {
-        await promoteMemory({
-          entry: enrichedEntry,
-          scope: promoteScope,
-          lifecycle,
-          workspaceRoot,
-          config,
-          confidence: evaluation.confidence || 0.8
-        });
-        filesChanged.push({ file: `memory/${promoteScope}.json`, why: `Promoted "${enrichedEntry.summary}" as ${lifecycle} (${promoteScope})` });
-        promotions.push({ summary: enrichedEntry.summary, scope: promoteScope, lifecycle, rationale: evaluation.kind, confidence: evaluation.confidence });
-      } catch (error) {
-        const reason = String(error?.message || error || 'promotion failed').slice(0, 180);
-        await archiveEntry(entry, 'promotion-failed', reason);
-        rejections.push({ summary: entry.summary, reason: `promotion-failed: ${reason}` });
-        archives.push({ summary: entry.summary, reason: 'promotion-failed' });
+      const promoteScope = evaluation.scope || 'global';
+      const lifecycle = chooseLifecycle(evaluation.kind);
+      const enrichedEntry = {
+        ...entry,
+        /* 用 LLM 提炼后的内容覆盖原始报错 */
+        summary: evaluation.summary || entry.summary,
+        details: evaluation.content || entry.details || entry.summary,
+        type: evaluation.kind || entry.type || 'observation'
+      };
+
+      if (!dryRun) {
+        try {
+          await promoteMemory({
+            entry: enrichedEntry,
+            scope: promoteScope,
+            lifecycle,
+            workspaceRoot,
+            config,
+            confidence: evaluation.confidence || 0.8
+          });
+          filesChanged.push({ file: `memory/${promoteScope}.json`, why: `Promoted "${enrichedEntry.summary}" as ${lifecycle} (${promoteScope})` });
+          promotions.push({ summary: enrichedEntry.summary, scope: promoteScope, lifecycle, rationale: evaluation.kind, confidence: evaluation.confidence });
+        } catch (error) {
+          const reason = String(error?.message || error || 'promotion failed').slice(0, 180);
+          await archiveEntry(entry, 'promotion-failed', reason);
+          rejections.push({ summary: entry.summary, reason: `promotion-failed: ${reason}` });
+          archives.push({ summary: entry.summary, reason: 'promotion-failed' });
+        }
+        continue;
       }
-      continue;
-    }
 
-    promotions.push({ summary: enrichedEntry.summary, scope: promoteScope, lifecycle, rationale: evaluation.kind, confidence: evaluation.confidence, dryRun: true });
+      promotions.push({ summary: enrichedEntry.summary, scope: promoteScope, lifecycle, rationale: evaluation.kind, confidence: evaluation.confidence, dryRun: true });
+    }
   }
 
+  const maintenance = await runMemoryMaintenance({ dryRun, scope: scopeFilter, workspaceRoot, config });
+  filesChanged.push(...maintenance.filesChanged);
+
   const report = {
     timestamp: new Date().toISOString(),
     filesRead,
@@ -145,7 +215,9 @@ export async function runDreamConsolidation({
     candidatesGenerated: inbox.length,
     promotions,
     rejections,
-    archives
+    archives,
+    maintenance: maintenance.reports,
+    ...(inbox.length === 0 ? { message: 'No inbox entries to consolidate; maintained existing memory buckets.' } : {})
   };
 
   if (!dryRun && writeAudit) {

package/src/core/dream-evaluator.js

@@ -22,6 +22,26 @@ Rules:
 - General coding/environment knowledge → scope "global"
 - If in doubt, discard. Memory is expensive; only promote what future sessions will genuinely benefit from.`;
 
+const MAINTENANCE_SYSTEM_PROMPT = `You are maintaining an existing persistent memory bucket for a coding assistant.
+
+Your job:
+1. Merge duplicates and near-duplicates.
+2. Summarize clusters into fewer, higher-signal memories.
+3. Remove stale, contradictory, trivial, or overly specific noise.
+4. Preserve important exact commands, file paths, preferences, and constraints.
+5. Keep memories scoped exactly to the bucket you receive.
+
+Respond with valid JSON only, no markdown fences:
+{"items":[{"kind":"preference|workflow|pattern|observation|correction|decision|failure|architecture|module|note","content":"durable memory text","summary":"under 80 chars","confidence":0.5,"pinned":false,"lifecycle":"longterm|operational"}],"archives":[{"source_ids":["mem_..."],"reason":"merged|stale|duplicate|noise|contradiction"}]}
+
+Rules:
+- Prefer fewer, clearer items, but do not collapse unrelated facts.
+- User preferences belong in user memory and should not become project rules.
+- Project conventions belong in project memory and should not become user preferences.
+- Global memory is only for reusable cross-project/tool/environment knowledge.
+- If a pinned item is still valid, keep it.
+- Return at least one item if the input has useful durable content.`;
+
 function parseResults(text) {
   try {
     const json = JSON.parse(text);
@@ -97,3 +117,69 @@ export async function evaluateInboxBatch({ entries, config, workspaceRoot }) {
     }));
   }
 }
+
+function parseMaintenanceResult(text) {
+  try {
+    const json = JSON.parse(text);
+    const items = Array.isArray(json?.items) ? json.items : [];
+    const archives = Array.isArray(json?.archives) ? json.archives : [];
+    return {
+      items: items
+        .map((item) => ({
+          kind: String(item.kind || 'note').slice(0, 40),
+          content: String(item.content || '').slice(0, 600),
+          summary: String(item.summary || item.content || '').slice(0, 120),
+          confidence: Math.min(1, Math.max(0.5, Number(item.confidence) || 0.8)),
+          pinned: item.pinned === true,
+          lifecycle: ['longterm', 'operational'].includes(String(item.lifecycle || '')) ? String(item.lifecycle) : undefined
+        }))
+        .filter((item) => item.content.trim()),
+      archives: archives.map((archive) => ({
+        source_ids: Array.isArray(archive.source_ids) ? archive.source_ids.map((id) => String(id)).filter(Boolean) : [],
+        reason: String(archive.reason || '').slice(0, 160)
+      }))
+    };
+  } catch {
+    return { items: [], archives: [] };
+  }
+}
+
+export async function evaluateMemoryMaintenance({ scope, items, config, workspaceRoot }) {
+  const sourceItems = Array.isArray(items) ? items : [];
+  if (sourceItems.length === 0) return { items: [], archives: [] };
+
+  const compactItems = sourceItems.map((item) => ({
+    id: item.id,
+    kind: item.kind,
+    content: String(item.content || '').slice(0, 600),
+    summary: String(item.summary || '').slice(0, 160),
+    confidence: item.confidence,
+    pinned: item.pinned === true,
+    lifecycle: item.lifecycle || ''
+  }));
+
+  try {
+    const result = await createChatCompletion({
+      sdkProvider: config?.sdk?.provider,
+      baseUrl: config?.gateway?.base_url,
+      apiKey: config?.gateway?.api_key,
+      model: config?.model?.name,
+      messages: [
+        { role: 'system', content: MAINTENANCE_SYSTEM_PROMPT },
+        {
+          role: 'user',
+          content: `Maintain this ${scope} memory bucket. Workspace: ${workspaceRoot || process.cwd()}\n\n${JSON.stringify(compactItems, null, 2)}`
+        }
+      ],
+      temperature: 0,
+      timeoutMs: EVAL_TIMEOUT_MS
+    });
+    return parseMaintenanceResult(result?.text || '');
+  } catch (error) {
+    return {
+      items: sourceItems,
+      archives: [],
+      error: String(error?.message || error || 'memory maintenance failed')
+    };
+  }
+}

package/src/core/fff-adapter.js

@@ -111,7 +111,7 @@ class FffMcpClient {
       capabilities: {},
       clientInfo: {
         name: 'codemini-cli',
-        version: '0.4.1'
+        version: '0.4.2'
       }
     });
     this.sendNotification('notifications/initialized', {});

package/src/core/memory-store.js

@@ -41,22 +41,92 @@ async function ensureParent(filePath) {
 function buildFilePath(scope, workspaceRoot = process.cwd(), projectAlias = '') {
   if (scope === 'user') return path.join(getMemoryDir(), 'user.json');
   if (scope === 'global') return path.join(getMemoryDir(), 'global.json');
-  return path.join(getProjectMemoryDir(workspaceRoot), `${getProjectMemoryKey(workspaceRoot, projectAlias)}.json`);
+  return path.join(getProjectMemoryDir(workspaceRoot), 'project.json');
+}
+
+async function listProjectMemoryFiles(workspaceRoot = process.cwd()) {
+  const dir = getProjectMemoryDir(workspaceRoot);
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+      .map((entry) => path.join(dir, entry.name))
+      .sort();
+  } catch {
+    return [];
+  }
 }
 
 async function readMemoryBucket(filePath) {
+  const doc = await readMemoryBucketDocument(filePath);
+  return doc.items;
+}
+
+async function readMemoryBucketDocument(filePath) {
   try {
     const raw = await fs.readFile(filePath, 'utf8');
     const parsed = JSON.parse(raw);
-    return Array.isArray(parsed?.items) ? parsed.items : [];
+    return {
+      items: Array.isArray(parsed?.items) ? parsed.items : [],
+      maintenance: parsed?.maintenance && typeof parsed.maintenance === 'object' ? parsed.maintenance : null
+    };
   } catch {
-    return [];
+    return { items: [], maintenance: null };
   }
 }
 
-async function writeMemoryBucket(filePath, items) {
+function memoryBucketHash(items = []) {
+  const stable = (Array.isArray(items) ? items : [])
+    .map((item) => ({
+      id: String(item?.id || ''),
+      kind: String(item?.kind || ''),
+      content: normalizeMemoryText(item?.content || ''),
+      summary: normalizeMemoryText(item?.summary || ''),
+      lifecycle: String(item?.lifecycle || ''),
+      pinned: item?.pinned === true
+    }))
+    .sort((left, right) => left.id.localeCompare(right.id));
+  return sha256(JSON.stringify(stable));
+}
+
+async function writeMemoryBucket(filePath, items, { maintenance = null } = {}) {
   await ensureParent(filePath);
-  await fs.writeFile(filePath, `${JSON.stringify({ items }, null, 2)}\n`, 'utf8');
+  const doc = { items };
+  if (maintenance) doc.maintenance = maintenance;
+  await fs.writeFile(filePath, `${JSON.stringify(doc, null, 2)}\n`, 'utf8');
+}
+
+function dedupeMemoryItems(items = []) {
+  const deduped = [];
+  const seen = new Set();
+  for (const item of items) {
+    const key = item.id ? `id:${item.id}` : `${item.kind}:${normalizeMemoryText(item.content)}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(item);
+  }
+  return deduped;
+}
+
+async function readProjectMemoryItems(workspaceRoot = process.cwd(), projectAlias = '') {
+  const projectKey = getProjectMemoryKey(workspaceRoot, projectAlias);
+  const files = await listProjectMemoryFiles(workspaceRoot);
+  const items = [];
+  for (const file of files) {
+    const bucket = await readMemoryBucket(file);
+    items.push(...bucket.map((item) => normalizeMemoryItem(item, 'project', projectKey)));
+  }
+  return dedupeMemoryItems(items)
+    .sort((left, right) => String(right.updatedAt).localeCompare(String(left.updatedAt)));
+}
+
+async function readScopeMemoryItems(scope, workspaceRoot = process.cwd(), projectAlias = '') {
+  const normalizedScope = ensureScope(scope);
+  if (normalizedScope === 'project') return readProjectMemoryItems(workspaceRoot, projectAlias);
+  const filePath = buildFilePath(normalizedScope, workspaceRoot, projectAlias);
+  return (await readMemoryBucket(filePath))
+    .map((item) => normalizeMemoryItem(item, normalizedScope, ''))
+    .sort((left, right) => String(right.updatedAt).localeCompare(String(left.updatedAt)));
 }
 
 function normalizeMemoryItem(item, scope, projectKey = '') {
@@ -74,7 +144,8 @@ function normalizeMemoryItem(item, scope, projectKey = '') {
     createdAt: String(item?.createdAt || now),
     updatedAt: String(item?.updatedAt || now),
     hits: Number.isFinite(Number(item?.hits)) ? Number(item.hits) : 0,
-    pinned: item?.pinned === true
+    pinned: item?.pinned === true,
+    ...(item?.lifecycle ? { lifecycle: String(item.lifecycle) } : {})
   };
 }
 
@@ -96,13 +167,69 @@ function budgetForScope(scope, config = {}) {
 }
 
 export async function listMemories({ scope, workspaceRoot = process.cwd(), projectAlias = '' }) {
+  const normalizedScope = ensureScope(scope);
+  return readScopeMemoryItems(normalizedScope, workspaceRoot, projectAlias);
+}
+
+export async function getMemoryBucketMaintenance({ scope, workspaceRoot = process.cwd(), projectAlias = '' }) {
+  const normalizedScope = ensureScope(scope);
+  const filePath = buildFilePath(normalizedScope, workspaceRoot, projectAlias);
+  const doc = await readMemoryBucketDocument(filePath);
+  const items = normalizedScope === 'project'
+    ? await readProjectMemoryItems(workspaceRoot, projectAlias)
+    : doc.items.map((item) => normalizeMemoryItem(item, normalizedScope, ''));
+  const currentHash = memoryBucketHash(items);
+  const storedHash = String(doc.maintenance?.contentHash || '');
+  const maintainedAt = String(doc.maintenance?.maintainedAt || '');
+  return {
+    scope: normalizedScope,
+    itemCount: items.length,
+    contentHash: currentHash,
+    storedHash,
+    maintainedAt,
+    fresh: Boolean(maintainedAt && storedHash && storedHash === currentHash)
+  };
+}
+
+export async function markMemoryBucketMaintained({ scope, workspaceRoot = process.cwd(), projectAlias = '' }) {
+  const normalizedScope = ensureScope(scope);
+  const filePath = buildFilePath(normalizedScope, workspaceRoot, projectAlias);
+  const items = await readScopeMemoryItems(normalizedScope, workspaceRoot, projectAlias);
+  const maintenance = {
+    maintainedAt: nowIso(),
+    contentHash: memoryBucketHash(items),
+    itemCount: items.length
+  };
+  await writeMemoryBucket(filePath, items, { maintenance });
+  return { scope: normalizedScope, ...maintenance };
+}
+
+export async function replaceMemoryBucket({
+  scope,
+  items = [],
+  workspaceRoot = process.cwd(),
+  projectAlias = '',
+  markMaintained = false
+} = {}) {
   const normalizedScope = ensureScope(scope);
   const filePath = buildFilePath(normalizedScope, workspaceRoot, projectAlias);
   const projectKey = normalizedScope === 'project' ? getProjectMemoryKey(workspaceRoot, projectAlias) : '';
-  const items = await readMemoryBucket(filePath);
-  return items
+  const normalizedItems = (Array.isArray(items) ? items : [])
     .map((item) => normalizeMemoryItem(item, normalizedScope, projectKey))
-    .sort((left, right) => String(right.updatedAt).localeCompare(String(left.updatedAt)));
+    .filter((item) => item.content);
+  const maintenance = markMaintained
+    ? {
+        maintainedAt: nowIso(),
+        contentHash: memoryBucketHash(normalizedItems),
+        itemCount: normalizedItems.length
+      }
+    : null;
+  await writeMemoryBucket(filePath, normalizedItems, { maintenance });
+  return {
+    scope: normalizedScope,
+    items: normalizedItems,
+    maintenance
+  };
 }
 
 export async function rememberMemory({
@@ -125,7 +252,7 @@ export async function rememberMemory({
 
   const filePath = buildFilePath(normalizedScope, workspaceRoot, projectAlias);
   const projectKey = normalizedScope === 'project' ? getProjectMemoryKey(workspaceRoot, projectAlias) : '';
-  const existing = (await readMemoryBucket(filePath)).map((item) => normalizeMemoryItem(item, normalizedScope, projectKey));
+  const existing = await readScopeMemoryItems(normalizedScope, workspaceRoot, projectAlias);
   const probe = normalizeMemoryItem({ content: normalizedContent, kind, summary, source, confidence, pinned }, normalizedScope, projectKey);
 
   const replaceIndex = replaceSimilar ? existing.findIndex((item) => sameMemory(item, probe)) : -1;
@@ -170,6 +297,14 @@ export async function forgetMemory({ scope, id, workspaceRoot = process.cwd(), p
   const existing = await listMemories({ scope: normalizedScope, workspaceRoot, projectAlias });
   const kept = existing.filter((item) => item.id !== id);
   await writeMemoryBucket(filePath, kept);
+  if (normalizedScope === 'project') {
+    const files = (await listProjectMemoryFiles(workspaceRoot)).filter((file) => file !== filePath);
+    await Promise.all(files.map(async (file) => {
+      const bucket = await readMemoryBucket(file);
+      const next = bucket.filter((item) => String(item?.id || '') !== id);
+      if (next.length !== bucket.length) await writeMemoryBucket(file, next);
+    }));
+  }
   return { removed: existing.length - kept.length };
 }