clementine-agent 1.6.2 → 1.7.0

package/dist/memory/store.js

@@ -223,6 +223,32 @@ export class MemoryStore {
             this.conn.exec('CREATE INDEX idx_chunks_has_embedding ON chunks(id) WHERE embedding IS NOT NULL');
         }
         catch { /* already exists */ }
+        // Confidence column — orthogonal to salience. Salience = "how important
+        // is this if true?", confidence = "how certain am I this is still true?"
+        // Decays via the daily heartbeat sweep on chunks that haven't been
+        // accessed or reinforced. Used in Phase 3 for fading stale facts and as
+        // input to the supersession decision.
+        try {
+            this.conn.exec('ALTER TABLE chunks ADD COLUMN confidence REAL DEFAULT 1.0');
+        }
+        catch { /* already exists */ }
+        // Supersede graph — explicit "this old chunk is replaced by this new
+        // chunk." Distinct from soft-delete because supersedes carries provenance
+        // (which fact replaced which) and lets us reconstruct corrections later.
+        // Search joins LEFT JOIN this table and excludes rows where the chunk
+        // appears as `old_chunk_id`, mirroring the soft-delete pattern.
+        this.conn.exec(`
+      CREATE TABLE IF NOT EXISTS chunk_supersedes (
+        old_chunk_id INTEGER PRIMARY KEY,
+        new_chunk_id INTEGER NOT NULL,
+        reason TEXT,
+        superseded_at TEXT DEFAULT (datetime('now')),
+        superseded_by_agent TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_chunk_supersedes_new ON chunk_supersedes(new_chunk_id);
+    `);
+        // Maintenance meta key for the salience decay sweep — last run timestamp.
+        // (maintenance_meta table itself is created elsewhere if not yet present.)
         // Access log table for salience tracking
         this.conn.exec(`
       CREATE TABLE IF NOT EXISTS access_log (
@@ -713,6 +739,12 @@ export class MemoryStore {
       CREATE INDEX IF NOT EXISTS idx_recall_traces_retrieved
         ON recall_traces(retrieved_at);
     `);
+        // Phase 4 migration: per-result match types stored alongside chunk_ids/scores
+        // so we can aggregate "which retrieval signal earned the recall" over time.
+        try {
+            this.conn.exec('ALTER TABLE recall_traces ADD COLUMN match_types TEXT DEFAULT NULL');
+        }
+        catch { /* column already exists */ }
         // Dense neural embeddings (transformers.js — arctic-embed-m by default).
         // Parallel to the existing chunks.embedding (TF-IDF, 512-dim) so we can
         // backfill incrementally and fall back gracefully if the dense model
@@ -1737,6 +1769,7 @@ export class MemoryStore {
                 chunkIds: finalResults.map(r => r.chunkId),
                 scores: finalResults.map(r => r.score),
                 agentSlug: agentSlug ?? null,
+                matchTypes: finalResults.map(r => r.matchType),
             });
         }
         return finalResults;
@@ -1758,6 +1791,7 @@ export class MemoryStore {
                 chunkIds: [...opts.chunkIds],
                 scores: [...opts.scores],
                 agentSlug: opts.agentSlug ?? null,
+                matchTypes: opts.matchTypes ? [...opts.matchTypes] : undefined,
             });
             return;
         }
@@ -1768,8 +1802,8 @@ export class MemoryStore {
         if (opts.chunkIds.length === 0)
             return;
         try {
-            this.conn.prepare(`INSERT INTO recall_traces (session_key, message_id, query, chunk_ids, scores, agent_slug)
-         VALUES (?, ?, ?, ?, ?, ?)`).run(opts.sessionKey, opts.messageId ?? null, opts.query, JSON.stringify(opts.chunkIds), JSON.stringify(opts.scores), opts.agentSlug ?? null);
+            this.conn.prepare(`INSERT INTO recall_traces (session_key, message_id, query, chunk_ids, scores, agent_slug, match_types)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`).run(opts.sessionKey, opts.messageId ?? null, opts.query, JSON.stringify(opts.chunkIds), JSON.stringify(opts.scores), opts.agentSlug ?? null, opts.matchTypes ? JSON.stringify(opts.matchTypes) : null);
         }
         catch {
             // Non-fatal — recall trace logging never breaks retrieval
@@ -2040,7 +2074,7 @@ export class MemoryStore {
         // least strict mode no longer scans foreign-agent chunks.
         let sql = `SELECT c.id, c.source_file, c.section, c.content, c.chunk_type,
                       c.embedding, c.salience, c.last_outcome_score, c.agent_slug,
-                      c.updated_at, c.category, c.topic
+                      c.updated_at, c.category, c.topic, c.confidence
                  FROM chunks c
                  LEFT JOIN chunk_soft_deletes sd ON sd.chunk_id = c.id
                  WHERE c.embedding IS NOT NULL AND sd.chunk_id IS NULL`;
@@ -2064,6 +2098,9 @@ export class MemoryStore {
                 const outcome = row.last_outcome_score ?? 0;
                 if (outcome !== 0)
                     score *= 1.0 + 0.3 * outcome;
+                const conf = row.confidence ?? 1;
+                if (conf < 1)
+                    score *= (0.5 + 0.5 * conf);
                 // Soft isolation: apply boost (only when not strict)
                 if (!strict && agentSlug && row.agent_slug === agentSlug)
                     score *= 1.4;
@@ -2110,7 +2147,7 @@ export class MemoryStore {
     searchByDenseEmbedding(queryVec, limit, agentSlug, strict = false) {
         let sql = `SELECT c.id, c.source_file, c.section, c.content, c.chunk_type,
                       c.embedding_dense, c.salience, c.last_outcome_score, c.agent_slug,
-                      c.updated_at, c.category, c.topic
+                      c.updated_at, c.category, c.topic, c.confidence
                  FROM chunks c
                  LEFT JOIN chunk_soft_deletes sd ON sd.chunk_id = c.id
                  WHERE c.embedding_dense IS NOT NULL AND sd.chunk_id IS NULL`;
@@ -2129,6 +2166,11 @@ export class MemoryStore {
                 if (sim < 0.3)
                     continue; // dense models produce more confident similarities; raise threshold from 0.15
                 let score = sim * 10;
+                // Confidence multiplier: tentative chunks (low confidence) lose ranking
+                // weight without being hidden. confidence=1.0 → no effect, 0.5 → 0.75×.
+                const conf = row.confidence ?? 1;
+                if (conf < 1)
+                    score *= (0.5 + 0.5 * conf);
                 if (row.salience > 0)
                     score *= (1.0 + row.salience);
                 const outcome = row.last_outcome_score ?? 0;
@@ -3534,6 +3576,233 @@ export class MemoryStore {
          WHERE id = ?`)
             .run(boost, chunkId);
     }
+    /**
+     * Mark a chunk as superseded by a newer one. The old chunk becomes
+     * invisible to retrieval but stays in the DB for provenance. Idempotent:
+     * supersede(A, B) followed by supersede(A, C) records C as the new
+     * pointer. Won't link a chunk to itself or to a missing chunk.
+     */
+    markChunkSuperseded(oldChunkId, newChunkId, opts = {}) {
+        if (!Number.isFinite(oldChunkId) || !Number.isFinite(newChunkId))
+            return false;
+        if (oldChunkId === newChunkId)
+            return false;
+        const exists = this.conn.prepare('SELECT 1 FROM chunks WHERE id IN (?, ?)').all(oldChunkId, newChunkId);
+        if (exists.length < 2)
+            return false;
+        this.conn
+            .prepare(`INSERT INTO chunk_supersedes (old_chunk_id, new_chunk_id, reason, superseded_at, superseded_by_agent)
+         VALUES (?, ?, ?, datetime('now'), ?)
+         ON CONFLICT(old_chunk_id) DO UPDATE SET
+           new_chunk_id = excluded.new_chunk_id,
+           reason = excluded.reason,
+           superseded_at = excluded.superseded_at,
+           superseded_by_agent = excluded.superseded_by_agent`)
+            .run(oldChunkId, newChunkId, opts.reason ?? null, opts.agent ?? null);
+        // Piggyback on chunk_soft_deletes so every existing search path (FTS,
+        // dense, sparse, recency) excludes the old chunk without needing edits.
+        // The supersede table retains provenance; soft-delete just hides it.
+        this.conn
+            .prepare(`INSERT OR IGNORE INTO chunk_soft_deletes (chunk_id, deleted_at, deleted_by)
+         VALUES (?, datetime('now'), ?)`)
+            .run(oldChunkId, opts.agent ? `superseded:${opts.agent}` : 'superseded');
+        return true;
+    }
+    /**
+     * Daily salience-decay sweep. Multiplies salience by `decayFactor` (default
+     * 0.95) on chunks that haven't been accessed or written-to in `staleDays`.
+     * Pinned chunks are exempt — pinning is the user's explicit "keep this hot."
+     * Soft-deleted and superseded chunks are also skipped (they're already out
+     * of circulation). Returns count of rows updated.
+     */
+    decayStaleSalience(opts = {}) {
+        const staleDays = opts.staleDays ?? 30;
+        const decay = Math.max(0, Math.min(1, opts.decayFactor ?? 0.95));
+        const floor = Math.max(0, opts.floor ?? 0);
+        const result = this.conn
+            .prepare(`UPDATE chunks
+         SET salience = MAX(?, salience * ?)
+         WHERE pinned = 0
+           AND salience > ?
+           AND (
+             SELECT MAX(accessed_at) FROM access_log WHERE chunk_id = chunks.id
+           ) < datetime('now', ?)
+           AND id NOT IN (SELECT chunk_id FROM chunk_soft_deletes)
+           AND id NOT IN (SELECT old_chunk_id FROM chunk_supersedes)`)
+            .run(floor, decay, floor, `-${staleDays} days`);
+        return Number(result.changes ?? 0);
+    }
+    /**
+     * Composition / graph stats — wikilink density + per-match-type recall
+     * contribution over a recent window. Surfaces whether entity linking is
+     * paying off in retrieval.
+     */
+    getGraphStats(opts = {}) {
+        const topN = opts.topN ?? 12;
+        const lookbackHours = opts.lookbackHours ?? 24 * 7;
+        const wikilinkCount = this.conn
+            .prepare('SELECT COUNT(*) as c FROM wikilinks')
+            .get()?.c ?? 0;
+        const topLinkedTargets = this.conn
+            .prepare(`SELECT target_file as target, COUNT(*) as count
+         FROM wikilinks GROUP BY target_file
+         ORDER BY count DESC LIMIT ?`)
+            .all(topN);
+        const traceRows = this.conn
+            .prepare(`SELECT match_types FROM recall_traces
+         WHERE retrieved_at > datetime('now', ?)
+           AND match_types IS NOT NULL`)
+            .all(`-${lookbackHours} hours`);
+        const counts = {};
+        for (const row of traceRows) {
+            try {
+                const arr = JSON.parse(row.match_types);
+                for (const t of arr)
+                    counts[t] = (counts[t] ?? 0) + 1;
+            }
+            catch { /* skip */ }
+        }
+        return { wikilinkCount, topLinkedTargets, recallContributionByType: counts, tracesAnalyzed: traceRows.length };
+    }
+    /**
+     * Cross-channel session bridge — the most recent N session summaries per
+     * channel (Discord / dashboard / cron / etc). Channel inferred from the
+     * sessionKey prefix (everything before first ':'). Powers the dashboard
+     * "Cross-channel handoff" panel so we can see whether continuity is
+     * actually flowing between sources.
+     */
+    getRecentSummariesByChannel(limitPerChannel = 3) {
+        const rows = this.conn
+            .prepare(`SELECT session_key, summary, exchange_count, created_at
+         FROM session_summaries ORDER BY created_at DESC LIMIT 200`)
+            .all();
+        const grouped = {};
+        for (const row of rows) {
+            const colonIdx = row.session_key.indexOf(':');
+            const channel = colonIdx > 0 ? row.session_key.slice(0, colonIdx) : 'other';
+            if (!grouped[channel])
+                grouped[channel] = [];
+            if (grouped[channel].length >= limitPerChannel)
+                continue;
+            grouped[channel].push({
+                sessionKey: row.session_key,
+                summary: row.summary,
+                exchangeCount: row.exchange_count,
+                createdAt: row.created_at,
+            });
+        }
+        return grouped;
+    }
+    /**
+     * Stats for the supersede graph — count of superseded chunks (excluded
+     * from retrieval) for the dashboard.
+     */
+    getSupersedeStats() {
+        const total = this.conn
+            .prepare('SELECT COUNT(*) as c FROM chunk_supersedes')
+            .get()?.c ?? 0;
+        const recent = this.conn
+            .prepare(`SELECT old_chunk_id as oldId, new_chunk_id as newId, reason, superseded_at as supersededAt
+         FROM chunk_supersedes
+         ORDER BY superseded_at DESC
+         LIMIT 20`)
+            .all();
+        return { superseded: total, recent };
+    }
+    /**
+     * Apply an agent-supplied salience hint to chunks freshly written by
+     * memory_write. Called after incrementalSync so the new chunks exist.
+     * Sets salience to MAX(existing, hint) — a higher hint wins, but we
+     * never trample reinforcement that already accumulated. Allowed range
+     * 0.5–2.0; values >1.0 are reserved for explicit "this is critical"
+     * signals from the agent (e.g. user identity, hard preferences,
+     * irreversible decisions).
+     */
+    applyWriteSalience(sourceFile, section, hint) {
+        if (!Number.isFinite(hint))
+            return 0;
+        const clamped = Math.max(0.5, Math.min(2.0, hint));
+        const sql = section
+            ? `UPDATE chunks SET salience = MAX(salience, ?), updated_at = datetime('now')
+         WHERE source_file = ? AND section = ?`
+            : `UPDATE chunks SET salience = MAX(salience, ?), updated_at = datetime('now')
+         WHERE source_file = ?`;
+        const params = section ? [clamped, sourceFile, section] : [clamped, sourceFile];
+        const result = this.conn.prepare(sql).run(...params);
+        return Number(result.changes ?? 0);
+    }
+    /**
+     * Apply an agent-supplied confidence value to chunks freshly written by
+     * memory_write. Confidence (0.0–1.0) is orthogonal to salience: salience
+     * = "how important if true," confidence = "how certain it's still true."
+     * Defaults to 1.0 on insert; agents lower it for tentative facts. Used as
+     * a multiplier in retrieval scoring so uncertain chunks lose ranking.
+     */
+    applyWriteConfidence(sourceFile, section, confidence) {
+        if (!Number.isFinite(confidence))
+            return 0;
+        const clamped = Math.max(0, Math.min(1, confidence));
+        const sql = section
+            ? `UPDATE chunks SET confidence = ?, updated_at = datetime('now')
+         WHERE source_file = ? AND section = ?`
+            : `UPDATE chunks SET confidence = ?, updated_at = datetime('now')
+         WHERE source_file = ?`;
+        const params = section ? [clamped, sourceFile, section] : [clamped, sourceFile];
+        const result = this.conn.prepare(sql).run(...params);
+        return Number(result.changes ?? 0);
+    }
+    /**
+     * Recent writes panel — surfaces what the agent has been capturing and why.
+     * Joins memory_extractions to chunks (best-effort match by source_file +
+     * section if the tool_input carries those). Limit defaults to 50 since this
+     * powers a dashboard panel, not analytics.
+     */
+    getRecentWrites(limit = 50) {
+        const rows = this.conn
+            .prepare(`SELECT id, session_key, user_message, tool_name, tool_input,
+                extracted_at, status, agent_slug
+         FROM memory_extractions
+         WHERE tool_name LIKE 'memory_%' OR tool_name = 'note_create'
+         ORDER BY extracted_at DESC
+         LIMIT ?`)
+            .all(limit);
+        return rows.map((r) => {
+            let action = null;
+            let section = null;
+            let filePath = null;
+            let reason = null;
+            let salienceHint = null;
+            try {
+                const parsed = JSON.parse(r.tool_input ?? '{}');
+                if (typeof parsed.action === 'string')
+                    action = parsed.action;
+                if (typeof parsed.section === 'string')
+                    section = parsed.section;
+                if (typeof parsed.file_path === 'string')
+                    filePath = parsed.file_path;
+                if (typeof parsed.reason === 'string')
+                    reason = parsed.reason;
+                const sh = parsed.salience_hint;
+                if (typeof sh === 'number' && Number.isFinite(sh))
+                    salienceHint = sh;
+            }
+            catch { /* tool_input wasn't JSON — fall back to nulls */ }
+            return {
+                id: r.id,
+                extractedAt: r.extracted_at,
+                sessionKey: r.session_key,
+                agentSlug: r.agent_slug,
+                toolName: r.tool_name,
+                action,
+                section,
+                filePath,
+                reason,
+                salienceHint,
+                status: r.status,
+                userMessage: r.user_message,
+            };
+        });
+    }
     // ── Memory Extractions ──────────────────────────────────────────
     /**
      * Log a memory extraction event for transparency tracking.
@@ -4086,6 +4355,23 @@ export class MemoryStore {
             })(),
             dbSizeBytes: this.dbSizeBytes(),
             lastVacuumAt: this.getMaintenanceMeta('last_vacuum_at'),
+            denseEmbeddings: (() => {
+                const withDense = this.conn
+                    .prepare('SELECT COUNT(*) as cnt FROM chunks WHERE embedding_dense IS NOT NULL')
+                    .get()?.cnt ?? 0;
+                const models = this.conn
+                    .prepare(`SELECT COALESCE(embedding_dense_model, '(unknown)') as model, COUNT(*) as count
+                    FROM chunks WHERE embedding_dense IS NOT NULL
+                    GROUP BY embedding_dense_model ORDER BY count DESC`)
+                    .all();
+                return {
+                    withDense,
+                    total: chunkAgg.total,
+                    models,
+                    currentModel: embeddingsModule.currentDenseModel(),
+                    ready: embeddingsModule.isDenseReady(),
+                };
+            })(),
         };
     }
     /**

package/dist/memory/write-queue.d.ts

@@ -32,6 +32,7 @@ export type QueueOp = {
     chunkIds: number[];
     scores: number[];
     agentSlug: string | null;
+    matchTypes?: string[];
 } | {
     kind: 'outcome';
     outcomes: Array<{

package/dist/memory/write-queue.js

@@ -136,6 +136,7 @@ export class WriteQueue {
                     chunkIds: op.chunkIds,
                     scores: op.scores,
                     agentSlug: op.agentSlug,
+                    matchTypes: op.matchTypes,
                 });
                 break;
             case 'outcome':

package/dist/tools/builder-tools.js

@@ -34,16 +34,29 @@ const stepShape = z.object({
 });
 export function registerBuilderTools(server) {
     // ── Discovery ──────────────────────────────────────────────────────────
-    server.tool('workflow_list', 'List all workflows and crons visible in the Builder. Returns one per line: id|name|origin|enabled|schedule|stepCount.', {
+    server.tool('workflow_list', 'List all workflows and crons visible in the Builder. Returns one per line: id|name|origin|owner|enabled|schedule|stepCount. Owner is "global" or "@<agentSlug>".', {
         enabledOnly: z.boolean().optional().describe('If true, return only enabled workflows'),
+        owner: z.string().optional().describe('Filter by owner: "global", "<agentSlug>", or "@<agentSlug>". Omit to include all.'),
         verbose: z.boolean().optional(),
-    }, async ({ enabledOnly, verbose }) => {
-        const items = listAllForBuilder().filter(i => !enabledOnly || i.enabled);
+    }, async ({ enabledOnly, owner, verbose }) => {
+        const ownerFilter = owner ? owner.replace(/^@/, '') : null;
+        const items = listAllForBuilder().filter(i => {
+            if (enabledOnly && !i.enabled)
+                return false;
+            if (ownerFilter == null)
+                return true;
+            if (ownerFilter === 'global')
+                return i.scope === 'global';
+            return i.scope === 'agent' && i.agentSlug === ownerFilter;
+        });
         if (verbose)
             return textResult(JSON.stringify(items, null, 2));
         if (items.length === 0)
             return textResult('(no workflows or crons found)');
-        return textResult(items.map(i => `${i.id}|${i.name}|${i.origin}|${i.enabled ? 'on' : 'off'}|${i.schedule ?? '-'}|${i.stepCount}step${i.stepCount === 1 ? '' : 's'}`).join('\n'));
+        return textResult(items.map(i => {
+            const ownerCol = i.scope === 'agent' ? '@' + (i.agentSlug ?? '?') : 'global';
+            return `${i.id}|${i.name}|${i.origin}|${ownerCol}|${i.enabled ? 'on' : 'off'}|${i.schedule ?? '-'}|${i.stepCount}step${i.stepCount === 1 ? '' : 's'}`;
+        }).join('\n'));
     });
     server.tool('workflow_read', 'Read a workflow as canonical JSON. Use this before editing — patches reference current step ids.', {
         id: z.string().describe('Builder id (e.g., cron:morning-briefing or workflow:daily-digest)'),

package/dist/tools/memory-tools.js

@@ -243,12 +243,16 @@ export function registerMemoryTools(server) {
         return textResult(`**${rel}:**\n\n${capped}`);
     });
     // ── 2. memory_write ────────────────────────────────────────────────────
-    server.tool('memory_write', getToolDescription('memory_write') ?? "Write or append to a vault note. Actions: 'append_daily' (add to today's log), 'update_memory' (update MEMORY.md section), 'write_note' (write/overwrite a note), 'update_identity' (set identity seed — who you are, your role, key context).", {
-        action: z.enum(['append_daily', 'update_memory', 'write_note', 'update_identity']).describe('Write action'),
+    server.tool('memory_write', getToolDescription('memory_write') ?? "Write or append to a vault note. Actions: 'append_daily' (add to today's log), 'update_memory' (update MEMORY.md section), 'write_note' (write/overwrite a note), 'update_identity' (set identity seed), 'supersede' (replace a stale fact: requires supersedes_chunk_id). Optional `salience_hint` (0.5–2.0; >1.0 = critical) and `reason` (one-sentence WHY) help the system remember the right things and explain itself later.", {
+        action: z.enum(['append_daily', 'update_memory', 'write_note', 'update_identity', 'supersede']).describe('Write action'),
         content: z.string().describe('Text to write/append'),
-        section: z.string().optional().describe('Section for append_daily or update_memory'),
+        section: z.string().optional().describe('Section for append_daily, update_memory, or supersede'),
         file_path: z.string().optional().describe('Relative vault path for write_note action'),
-    }, async ({ action, content, section, file_path }) => {
+        salience_hint: z.number().min(0.5).max(2.0).optional().describe('How important is this fact? 0.5=tentative, 1.0=normal (default), 1.5=durable preference/decision, 2.0=identity-level (rare). Sets the chunk salience floor so retrieval prioritizes it.'),
+        confidence: z.number().min(0).max(1).optional().describe('How certain is this fact still true? 1.0=certain (default), 0.7=probable, 0.5=uncertain/heard secondhand, 0.3=tentative. Lowers retrieval ranking without hiding — orthogonal to salience.'),
+        reason: z.string().max(200).optional().describe('One-sentence WHY this is worth keeping (e.g. "user just stated firm preference for X over Y"). Stored for observability and future supersession decisions.'),
+        supersedes_chunk_id: z.number().int().positive().optional().describe('Chunk ID of the old fact this write replaces. Required for action="supersede". The old chunk becomes invisible to retrieval; provenance is preserved.'),
+    }, async ({ action, content, section, file_path, salience_hint, confidence, reason, supersedes_chunk_id }) => {
         if (action === 'append_daily') {
             const sec = section ?? 'Interactions';
             const dailyPath = ensureDailyNote();
@@ -266,6 +270,23 @@ export function registerMemoryTools(server) {
             writeFileSync(dailyPath, body, 'utf-8');
             const rel = path.relative(VAULT_DIR, dailyPath);
             await incrementalSync(rel, ACTIVE_AGENT_SLUG ?? undefined);
+            try {
+                const store = await getStore();
+                if (typeof salience_hint === 'number') {
+                    store.applyWriteSalience(rel, sec, salience_hint);
+                }
+                if (typeof confidence === 'number') {
+                    store.applyWriteConfidence(rel, sec, confidence);
+                }
+                store.logExtraction({
+                    sessionKey: 'mcp', userMessage: content.slice(0, 200),
+                    toolName: 'memory_write',
+                    toolInput: JSON.stringify({ action, section: sec, reason, salience_hint, confidence }),
+                    extractedAt: new Date().toISOString(), status: 'active',
+                    agentSlug: ACTIVE_AGENT_SLUG ?? undefined,
+                });
+            }
+            catch { /* observability is best-effort */ }
             return textResult(`Appended to ${path.basename(dailyPath)} > ${sec}`);
         }
         if (action === 'update_memory') {
@@ -287,11 +308,14 @@ export function registerMemoryTools(server) {
                 const store = await getStore();
                 const dup = store.checkDuplicate(content, path.relative(VAULT_DIR, targetMemFile));
                 if (dup.isDuplicate && dup.matchId) {
-                    // Reinforce the existing chunk — the fact was mentioned again, so it's important
-                    store.bumpChunkSalience(dup.matchId, 0.1);
+                    // Reinforce the existing chunk — the fact was mentioned again, so it's important.
+                    // If the agent provided a salience hint higher than usual reinforcement, use it instead.
+                    const boost = typeof salience_hint === 'number' && salience_hint > 1.0 ? 0.2 : 0.1;
+                    store.bumpChunkSalience(dup.matchId, boost);
                     store.logExtraction({
                         sessionKey: 'mcp', userMessage: content.slice(0, 200),
-                        toolName: 'memory_write', toolInput: JSON.stringify({ action, section: sec }),
+                        toolName: 'memory_write',
+                        toolInput: JSON.stringify({ action, section: sec, reason, salience_hint }),
                         extractedAt: new Date().toISOString(), status: 'dedup_skipped',
                         agentSlug: ACTIVE_AGENT_SLUG ?? undefined,
                     });
@@ -340,6 +364,23 @@ export function registerMemoryTools(server) {
             writeFileSync(targetMemFile, body, 'utf-8');
             const rel = path.relative(VAULT_DIR, targetMemFile);
             await incrementalSync(rel, ACTIVE_AGENT_SLUG ?? undefined);
+            try {
+                const store = await getStore();
+                if (typeof salience_hint === 'number') {
+                    store.applyWriteSalience(rel, sec, salience_hint);
+                }
+                if (typeof confidence === 'number') {
+                    store.applyWriteConfidence(rel, sec, confidence);
+                }
+                store.logExtraction({
+                    sessionKey: 'mcp', userMessage: content.slice(0, 200),
+                    toolName: 'memory_write',
+                    toolInput: JSON.stringify({ action, section: sec, reason, salience_hint, confidence }),
+                    extractedAt: new Date().toISOString(), status: 'active',
+                    agentSlug: ACTIVE_AGENT_SLUG ?? undefined,
+                });
+            }
+            catch { /* observability is best-effort */ }
             const label = ACTIVE_AGENT_SLUG ? `${ACTIVE_AGENT_SLUG}/MEMORY.md` : 'MEMORY.md';
             return textResult(`Updated ${label} > ${sec}`);
         }
@@ -348,6 +389,23 @@ export function registerMemoryTools(server) {
             writeFileSync(IDENTITY_FILE, content, 'utf-8');
             const rel = path.relative(VAULT_DIR, IDENTITY_FILE);
             await incrementalSync(rel, ACTIVE_AGENT_SLUG ?? undefined);
+            try {
+                const store = await getStore();
+                // Identity is intrinsically high-salience — default to 1.5 if no hint.
+                const effectiveHint = typeof salience_hint === 'number' ? salience_hint : 1.5;
+                store.applyWriteSalience(rel, null, effectiveHint);
+                if (typeof confidence === 'number') {
+                    store.applyWriteConfidence(rel, null, confidence);
+                }
+                store.logExtraction({
+                    sessionKey: 'mcp', userMessage: content.slice(0, 200),
+                    toolName: 'memory_write',
+                    toolInput: JSON.stringify({ action, reason, salience_hint: effectiveHint, confidence }),
+                    extractedAt: new Date().toISOString(), status: 'active',
+                    agentSlug: ACTIVE_AGENT_SLUG ?? undefined,
+                });
+            }
+            catch { /* observability is best-effort */ }
             return textResult('Updated identity seed (IDENTITY.md)');
         }
         if (action === 'write_note') {
@@ -358,8 +416,95 @@ export function registerMemoryTools(server) {
             mkdirSync(path.dirname(full), { recursive: true });
             writeFileSync(full, content, 'utf-8');
             await incrementalSync(relPath, ACTIVE_AGENT_SLUG ?? undefined);
+            try {
+                const store = await getStore();
+                if (typeof salience_hint === 'number') {
+                    store.applyWriteSalience(relPath, null, salience_hint);
+                }
+                if (typeof confidence === 'number') {
+                    store.applyWriteConfidence(relPath, null, confidence);
+                }
+                store.logExtraction({
+                    sessionKey: 'mcp', userMessage: content.slice(0, 200),
+                    toolName: 'memory_write',
+                    toolInput: JSON.stringify({ action, file_path: relPath, reason, salience_hint, confidence }),
+                    extractedAt: new Date().toISOString(), status: 'active',
+                    agentSlug: ACTIVE_AGENT_SLUG ?? undefined,
+                });
+            }
+            catch { /* observability is best-effort */ }
             return textResult(`Wrote: ${relPath}`);
         }
+        if (action === 'supersede') {
+            // Explicit replacement: write the new content the same way as
+            // update_memory (or write_note if file_path given), then mark the old
+            // chunk as superseded. Reason is required — supersession is a strong
+            // signal that should always be explainable.
+            if (!supersedes_chunk_id)
+                return textResult("Error: 'supersedes_chunk_id' required for supersede");
+            if (!reason)
+                return textResult("Error: 'reason' required for supersede — explain why the old fact is wrong/stale");
+            const store = await getStore();
+            // Resolve old chunk for routing the new write to the same location.
+            const oldChunk = store.getChunkDetail?.(supersedes_chunk_id);
+            if (!oldChunk)
+                return textResult(`Error: chunk ${supersedes_chunk_id} not found`);
+            // Route by old chunk's location: MEMORY.md → update_memory style, other → write_note overwrite.
+            const targetRel = oldChunk.sourceFile;
+            const targetSection = section ?? oldChunk.section;
+            const fullPath = path.join(VAULT_DIR, targetRel);
+            if (existsSync(fullPath) && targetRel.endsWith('MEMORY.md')) {
+                // MEMORY.md path: replace the section content with new content.
+                let body = readFileSync(fullPath, 'utf-8');
+                const pattern = new RegExp(`(## ${targetSection.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\n)(.*?)(\\n## |$)`, 's');
+                const match = pattern.exec(body);
+                if (match) {
+                    body = body.slice(0, match.index + match[1].length) + content.trim() + '\n' + body.slice(match.index + match[1].length + match[2].length);
+                }
+                else {
+                    body += `\n\n## ${targetSection}\n\n${content.trim()}\n`;
+                }
+                writeFileSync(fullPath, body, 'utf-8');
+            }
+            else if (existsSync(fullPath)) {
+                writeFileSync(fullPath, content, 'utf-8');
+            }
+            else {
+                return textResult(`Error: target file ${targetRel} not found — cannot supersede`);
+            }
+            await incrementalSync(targetRel, ACTIVE_AGENT_SLUG ?? undefined);
+            // Find the new chunk that just landed (same source_file + section as old).
+            let newChunkId = null;
+            try {
+                const row = store.getChunkBySection?.(targetRel, targetSection);
+                if (row)
+                    newChunkId = row.id;
+            }
+            catch { /* fall through */ }
+            const marked = newChunkId
+                ? store.markChunkSuperseded(supersedes_chunk_id, newChunkId, { reason, agent: ACTIVE_AGENT_SLUG ?? undefined })
+                : false;
+            if (typeof salience_hint === 'number' && newChunkId) {
+                store.applyWriteSalience(targetRel, targetSection, salience_hint);
+            }
+            if (typeof confidence === 'number' && newChunkId) {
+                store.applyWriteConfidence(targetRel, targetSection, confidence);
+            }
+            try {
+                store.logExtraction({
+                    sessionKey: 'mcp', userMessage: content.slice(0, 200),
+                    toolName: 'memory_write',
+                    toolInput: JSON.stringify({ action, supersedes_chunk_id, new_chunk_id: newChunkId, reason, salience_hint, confidence, section: targetSection }),
+                    extractedAt: new Date().toISOString(),
+                    status: marked ? 'superseded' : 'supersede_failed',
+                    agentSlug: ACTIVE_AGENT_SLUG ?? undefined,
+                });
+            }
+            catch { /* best-effort */ }
+            return textResult(marked
+                ? `Superseded chunk #${supersedes_chunk_id} → #${newChunkId} (${targetRel} > ${targetSection}). Reason: ${reason}`
+                : `Wrote new content but failed to mark old chunk superseded (new chunk not found after sync — file may not have re-chunked yet).`);
+        }
         return textResult(`Unknown action: ${action}`);
     });
     // ── 2b. memory_record_procedure ────────────────────────────────────────

package/dist/tools/shared.d.ts

@@ -122,6 +122,15 @@ export type MemoryStoreType = {
     correctExtraction(id: number, correction: string): void;
     dismissExtraction(id: number): void;
     bumpChunkSalience(chunkId: number, boost?: number): void;
+    applyWriteSalience(sourceFile: string, section: string | null, hint: number): number;
+    applyWriteConfidence(sourceFile: string, section: string | null, confidence: number): number;
+    markChunkSuperseded(oldChunkId: number, newChunkId: number, opts?: {
+        reason?: string;
+        agent?: string;
+    }): boolean;
+    getChunkBySection(sourceFile: string, section: string): {
+        id: number;
+    } | null;
     getRecentCorrections(limit?: number): Array<{
         toolInput: string;
         correction: string;