@jack200714/mafw 4.5.1

package/gateway/dist/recall/index-scan.js

@@ -0,0 +1,437 @@
+"use strict";
+// Index scan: a cheap worker-model call reads the full harmonic index
+// (formatted as compact text) and picks relevant memory IDs for a given query.
+// This catches the semantic gap that BM25 misses — preference queries,
+// paraphrase, cross-session aggregation.
+//
+// Transport: direct OpenAI-compatible HTTP chat completion (NOT an opencode
+// session). The scan is a stateless classification call — a session adds
+// create/prompt/delete churn and a per-session prompt-cache key for zero
+// benefit, and one-shot sessions flooded the session registry.
+//
+// Cache-first design (the dominant cost lever is provider prompt-cache hits):
+//   - The index text is a cacheable prefix: static header (no entry count),
+//     entries sorted oldest-first (append-only), no volatile fields (energy
+//     omitted), and an explicit `cache_control: ephemeral` marker on the
+//     index block → deterministic DashScope explicit-cache hits (10% input
+//     billing, 5-min TTL reset on hit) instead of best-effort implicit cache.
+//   - The query is always the final suffix — dynamic content last.
+//
+// The index text is ~25-30k tokens for 690 entries — well within the model's
+// context window. Scan latency with a warm cache is a few seconds; results
+// are consumed via async prefetch snapshots, never on the sync recall path
+// (the plugin client aborts recall requests after 100ms).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IndexScanService = void 0;
+exports.resolveScanBaseUrl = resolveScanBaseUrl;
+exports.hashText = hashText;
+exports.formatEntryForIndex = formatEntryForIndex;
+exports.formatIndexForScan = formatIndexForScan;
+exports.formatIndexForScanSlim = formatIndexForScanSlim;
+exports.parseScanResponse = parseScanResponse;
+exports.resolveShortIds = resolveShortIds;
+const logger_1 = require("../core/utils/logger");
+const memory_curator_agent_1 = require("../skills/memory-curator-agent");
+const completion_http_1 = require("../runtime/completion-http");
+/**
+ * Map a provider id to its OpenAI-compatible chat-completions endpoint.
+ * `endpoints` (config `recall.scanEndpoints`) wins over the hardcoded table;
+ * unknown providers resolve to undefined — the caller may still inject an
+ * endpoint via ScanHttpDeps.resolveEndpoint (e.g. derived from the opencode
+ * provider config) or fall back to BM25-only recall.
+ */
+function resolveScanBaseUrl(providerID, endpoints) {
+    if (!providerID)
+        return undefined;
+    const mapped = endpoints?.[providerID];
+    if (mapped)
+        return mapped;
+    const p = providerID.toLowerCase();
+    if (p.includes('alibaba') || p.includes('dashscope') || p.includes('qwen')) {
+        return 'https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions';
+    }
+    return undefined;
+}
+/** FNV-1a (32-bit) — cheap byte-stability fingerprint for the index text. */
+function hashText(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(16).padStart(8, '0');
+}
+const SCAN_SYSTEM = `You are a memory retrieval system. Given a memory index and a user query, identify the most relevant memory entries.
+
+The index lists memories in this format:
+- [id:<short_id>] (<date>) <type> | <summary> | anchors: <keywords>
+
+Return ONLY valid JSON (no markdown):
+{"relevant_ids": ["<short_id>", ...], "reasoning": "<one sentence>", "confidence": <0.0-1.0>}
+
+Rules:
+- You MUST return 5-8 entry IDs. If the index has entries at all, return at least 5.
+- Return MORE entries rather than fewer — false negatives are worse than false positives
+- Rank them by relevance (most relevant first)
+- Consider semantic relevance, not just keyword matching — look for topic overlap, related concepts, paraphrases
+- For preference queries (what does the user like/dislike), prioritize entries with "preference" type or "pref:" anchors
+- For temporal queries (when/what happened), prioritize entries with matching dates
+- For multi-session queries (what did we discuss about X), look for entries sharing topic anchors
+- If answering the question requires combining information from multiple memories, include ALL relevant entries
+- confidence = how sure you are that the selected entries answer the query (0.0 = guess, 1.0 = certain)
+- If nothing is relevant, return {"relevant_ids": [], "reasoning": "no relevant memories", "confidence": 0.0}
+${memory_curator_agent_1.HARD_BOUNDARIES}`;
+/**
+ * Format a single harmonic index entry into a compact index line.
+ * Only immutable fields are included (date, type, summary, anchors) —
+ * volatile fields like energy would invalidate the provider prompt cache
+ * on every decay pass.
+ *
+ * Truncation opts (Step 4 slimming): absCap/anchorCap shorten the line for
+ * scan-prompt size; caps are caller-fixed constants so the rendered text
+ * stays byte-stable across refreshes (cache-safe). Truncation slices at
+ * UTF-16 code-unit boundaries — fine for CJK BMP text, only cosmetic for
+ * the rare astral char.
+ */
+function formatEntryForIndex(entry, opts) {
+    // Tail-10 short id: harmonic ids are mem_<millis>_<rand>, so a head prefix
+    // collides for same-millisecond writes (batch ingests share one prefix —
+    // "unique 12-char prefixes: 1/53" in the LongMemEval harness). The tail
+    // (rand + ts suffix) is unique per entry; resolveShortIds matches endsWith.
+    const id = (entry.id || '?').slice(-10);
+    const date = formatDateOnly(entry.created_at);
+    const type = entry.type || 'unknown';
+    // Don't truncate abstraction — let the model see full content for better relevance judgment
+    let summary = (entry.primary_abstraction || '').replace(/\n/g, ' ');
+    if (opts?.absCap && summary.length > opts.absCap)
+        summary = summary.slice(0, opts.absCap) + '…';
+    const anchors = (entry.cue_anchors || []).slice(0, opts?.anchorCap ?? 5).join(', ');
+    return `- [id:${id}] (${date}) ${type} | ${summary} | anchors: ${anchors}`;
+}
+function formatDateOnly(iso) {
+    if (!iso)
+        return 'unknown';
+    try {
+        const d = new Date(iso);
+        if (Number.isNaN(d.getTime()))
+            return 'unknown';
+        const yyyy = d.getFullYear();
+        const mm = String(d.getMonth() + 1).padStart(2, '0');
+        const dd = String(d.getDate()).padStart(2, '0');
+        return `${yyyy}-${mm}-${dd}`;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Format the full harmonic index into a compact text block for scanning.
+ * Excludes superseded entries. Sorted by created_at ASCENDING (oldest first)
+ * so the text is append-only: after new writes the refreshed text keeps the
+ * entire previous prefix byte-identical, preserving provider prompt-cache
+ * hits across hourly refreshes. Header is static (no entry count) for the
+ * same reason.
+ */
+function formatIndexForScan(index) {
+    const entries = index.getIndex().entries
+        .filter((e) => !e.superseded_by)
+        .sort((a, b) => {
+        const ta = a.created_at ? new Date(a.created_at).getTime() : 0;
+        const tb = b.created_at ? new Date(b.created_at).getTime() : 0;
+        return ta - tb; // oldest first — append-only order
+    });
+    const lines = entries.map((e) => formatEntryForIndex(e));
+    return `# Memory Index\n\n${lines.join('\n')}`;
+}
+/** Slimming variant — same ordering/filtering, truncated lines (Step 4 A/B). */
+function formatIndexForScanSlim(index, opts) {
+    const entries = index.getIndex().entries
+        .filter((e) => !e.superseded_by)
+        .sort((a, b) => {
+        const ta = a.created_at ? new Date(a.created_at).getTime() : 0;
+        const tb = b.created_at ? new Date(b.created_at).getTime() : 0;
+        return ta - tb;
+    });
+    const lines = entries.map((e) => formatEntryForIndex(e, opts));
+    return `# Memory Index\n\n${lines.join('\n')}`;
+}
+/**
+ * Parse the scan response into structured result.
+ * Tolerant of markdown fences and extra text around JSON.
+ */
+function parseScanResponse(text) {
+    if (!text?.trim())
+        return null;
+    try {
+        // Strip markdown fences if present
+        const cleaned = text.replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/, '').trim();
+        const parsed = JSON.parse(cleaned);
+        if (!Array.isArray(parsed?.relevant_ids))
+            return null;
+        return {
+            relevantIds: parsed.relevant_ids.filter((id) => typeof id === 'string').slice(0, 10),
+            confidence: typeof parsed.confidence === 'number' ? parsed.confidence : 0.5,
+            reasoning: typeof parsed.reasoning === 'string' ? parsed.reasoning : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve short IDs from scan response to full harmonic index entry IDs.
+ * The index shows tail-10 short ids (see formatEntryForIndex); this maps
+ * them back with endsWith. Ambiguous tails resolve to the first match —
+ * tail collisions are ~0 for 10 chars over ~1k entries.
+ */
+function resolveShortIds(shortIds, index) {
+    const entries = index.getIndex().entries;
+    const resolved = [];
+    for (const shortId of shortIds) {
+        const match = entries.find((e) => e.id.endsWith(shortId));
+        if (match)
+            resolved.push(match.id);
+    }
+    return resolved;
+}
+/**
+ * IndexScanService runs scan queries over direct HTTP and caches the index
+ * text. Created once by the gateway, reused across all scan calls.
+ */
+class IndexScanService {
+    index;
+    workerModel;
+    deps;
+    cachedIndexText = null;
+    cachedAt = 0;
+    lastIndexHash = null;
+    inFlight = null;
+    // Failure cooldown state: a slow or broken worker model must not burn a
+    // request on every recall call. Exponential backoff (1/2/4 min, capped);
+    // a healthy scan resets the streak. Low-confidence results are healthy
+    // "no match" answers and do NOT arm the cooldown.
+    lastFailAt = 0;
+    consecutiveFails = 0;
+    lastAttemptFailed = false;
+    // Warn-once flag for unresolvable endpoint/key so a misconfiguration
+    // doesn't spam the log on every scan attempt.
+    warnedUnresolvable = false;
+    // Async prefetch snapshots: scan results precomputed when a user message
+    // arrives, consumed later by the sync recall path (never awaited there).
+    snapshots = new Map();
+    lastPrefetchAt = new Map();
+    static SNAPSHOT_TTL_MS = 10 * 60_000;
+    static SNAPSHOT_CAP = 64;
+    static PREFETCH_THROTTLE_MS = 60_000;
+    constructor(index, workerModel, deps = {}) {
+        this.index = index;
+        this.workerModel = workerModel;
+        this.deps = deps;
+    }
+    /** Refresh the cached index text. Called hourly by turn-compress cron. */
+    refreshCache() {
+        const text = formatIndexForScan(this.index);
+        const hash = hashText(text);
+        const changed = this.lastIndexHash !== null && this.lastIndexHash !== hash;
+        logger_1.log.info(`[IndexScan] cache refreshed: ${text.split('\n').length - 2} entries, ${text.length} chars, hash=${hash}${this.lastIndexHash !== null ? `, changed=${changed}` : ''}`);
+        this.cachedIndexText = text;
+        this.lastIndexHash = hash;
+        this.cachedAt = Date.now();
+    }
+    /** Get the cached index text, refreshing if needed. */
+    getIndexText() {
+        if (!this.cachedIndexText) {
+            this.refreshCache();
+        }
+        return this.cachedIndexText;
+    }
+    /**
+     * Run a scan: send cached index + query to the worker model over direct
+     * HTTP, parse the response. Returns null on failure (fail-open: callers
+     * fall back to BM25 only). Deduplicates concurrent calls — if a scan is
+     * already in-flight, returns the same promise.
+     */
+    async scan(query, options = {}) {
+        const timeoutMs = options.timeoutMs ?? this.deps.timeoutMs ?? 30_000;
+        const minConfidence = options.minConfidence ?? 0.3;
+        // Failure cooldown (exponential backoff: 1/2/4 min, capped)
+        if (this.consecutiveFails > 0) {
+            const cooldown = Math.min(60_000 * 2 ** (this.consecutiveFails - 1), 240_000);
+            if (Date.now() - this.lastFailAt < cooldown)
+                return null;
+        }
+        // Deduplicate concurrent scans
+        if (this.inFlight)
+            return this.inFlight;
+        this.inFlight = this._doScan(query, timeoutMs, minConfidence);
+        try {
+            const result = await this.inFlight;
+            if (this.lastAttemptFailed) {
+                this.consecutiveFails++;
+                this.lastFailAt = Date.now();
+            }
+            else {
+                this.consecutiveFails = 0;
+            }
+            return result;
+        }
+        finally {
+            this.inFlight = null;
+        }
+    }
+    async _doScan(query, timeoutMs, minConfidence) {
+        const providerID = this.workerModel?.providerID;
+        const modelID = this.workerModel?.modelID;
+        const startedAt = Date.now();
+        try {
+            const indexText = this.getIndexText();
+            const req = {
+                model: { providerID: providerID ?? '', modelID: modelID ?? '' },
+                system: [
+                    { text: SCAN_SYSTEM },
+                    // Cacheable-prefix hint: DashScope caches the block from the start
+                    // of the messages up to here (SCAN_SYSTEM + index) for 5 minutes,
+                    // reset on every hit → deterministic ~10% input cost. Mapped to
+                    // `cache_control: ephemeral` by the direct-HTTP transport; other
+                    // runtimes may ignore it (fail-open).
+                    { text: indexText, cacheable: true },
+                ],
+                user: [{ type: 'text', text: `User query: ${query}\n\nSelect the most relevant memory entries from the index above.` }],
+                temperature: 0,
+                // Reasoning models (glm-5.3-flash always thinks, ~300-1500 reasoning
+                // tokens) need headroom or the JSON gets truncated mid-stream
+                // (finish_reason=length → unparsable → cooldown). The JSON itself is
+                // ~100 tokens; 4096 covers the reasoning budget with margin.
+                maxTokens: 4096,
+                timeoutMs,
+            };
+            let content;
+            let usage;
+            const channel = this.deps.completion?.();
+            try {
+                if (!channel)
+                    throw new Error('no completion channel');
+                const res = await channel.complete(req);
+                content = res.text;
+                usage = res.usage;
+            }
+            catch (contractErr) {
+                if (channel) {
+                    logger_1.log.warn(`[IndexScan] completion channel failed (${contractErr.message}), falling back to direct HTTP`);
+                }
+                let res;
+                try {
+                    res = await (0, completion_http_1.httpComplete)(req, this.deps);
+                }
+                catch (httpErr) {
+                    if (/no endpoint or API key/.test(httpErr.message)) {
+                        if (!this.warnedUnresolvable) {
+                            logger_1.log.warn(`[IndexScan] no endpoint or API key for provider "${providerID ?? '?'}" — scan disabled`);
+                            this.warnedUnresolvable = true;
+                        }
+                        this.lastAttemptFailed = true;
+                        return null;
+                    }
+                    logger_1.log.warn(`[IndexScan] scan failed: ${httpErr.message}`);
+                    this.lastAttemptFailed = true;
+                    return null;
+                }
+                content = res.text;
+                usage = res.usage;
+            }
+            const result = parseScanResponse(content);
+            // Self-record usage: direct-HTTP scans bypass opencode, so without this
+            // sink the memory-system token stats silently lose the scan's share.
+            if (this.deps.recordUsage && usage) {
+                try {
+                    this.deps.recordUsage({
+                        providerID,
+                        modelID,
+                        input: usage.input,
+                        cached: usage.cached,
+                        output: usage.output,
+                        latencyMs: Date.now() - startedAt,
+                        ok: result != null,
+                        indexHash: hashText(this.getIndexText()),
+                    });
+                }
+                catch { /* never block the scan path on recorder errors */ }
+            }
+            if (!result) {
+                this.lastAttemptFailed = true; // unparsable output — model likely broken
+                logger_1.log.warn(`[IndexScan] scan failed: unparsable response (${Date.now() - startedAt}ms)`);
+                return null;
+            }
+            // Resolve short IDs to full IDs
+            result.relevantIds = resolveShortIds(result.relevantIds, this.index);
+            const elapsed = Date.now() - startedAt;
+            if (result.confidence < minConfidence) {
+                logger_1.log.info(`[IndexScan] ok: low confidence ${result.confidence} < ${minConfidence}, discarding (${elapsed}ms${usage?.cached != null ? `, cachedTokens=${usage.cached}` : ''})`);
+                this.lastAttemptFailed = false; // healthy "no match"
+                return null;
+            }
+            this.lastAttemptFailed = false;
+            logger_1.log.info(`[IndexScan] ok: ids=${result.relevantIds.length} confidence=${result.confidence} (${elapsed}ms${usage?.cached != null ? `, cachedTokens=${usage.cached}` : ''})`);
+            return result;
+        }
+        catch (err) {
+            logger_1.log.warn(`[IndexScan] scan failed: ${err.message}`);
+            this.lastAttemptFailed = true;
+            return null;
+        }
+    }
+    /**
+     * Fire-and-forget prefetch: scan the query now and store the result as a
+     * per-session snapshot for later sync-path consumption. Throttled per
+     * session (60s); scan-internal dedup/cooldown still apply.
+     */
+    prefetch(sessionID, query) {
+        if (!sessionID || !query.trim())
+            return;
+        const now = Date.now();
+        const last = this.lastPrefetchAt.get(sessionID) ?? 0;
+        if (now - last < IndexScanService.PREFETCH_THROTTLE_MS)
+            return;
+        this.lastPrefetchAt.set(sessionID, now);
+        void this.scan(query)
+            .then((result) => {
+            if (result)
+                this.setSnapshot(sessionID, result);
+        })
+            .catch(() => { });
+    }
+    setSnapshot(sessionID, result) {
+        if (this.snapshots.size >= IndexScanService.SNAPSHOT_CAP && !this.snapshots.has(sessionID)) {
+            // Evict the oldest snapshot when at capacity.
+            let oldestKey = '';
+            let oldestAt = Infinity;
+            for (const [k, v] of this.snapshots) {
+                if (v.at < oldestAt) {
+                    oldestAt = v.at;
+                    oldestKey = k;
+                }
+            }
+            if (oldestKey)
+                this.snapshots.delete(oldestKey);
+        }
+        this.snapshots.set(sessionID, { result, at: Date.now() });
+    }
+    /**
+     * Latest precomputed scan snapshot for a session. The sync recall path
+     * merges this in-memory and never awaits a scan. Snapshots expire after
+     * 10 minutes.
+     */
+    getSnapshot(sessionID) {
+        const snap = this.snapshots.get(sessionID);
+        if (!snap)
+            return null;
+        if (Date.now() - snap.at > IndexScanService.SNAPSHOT_TTL_MS) {
+            this.snapshots.delete(sessionID);
+            return null;
+        }
+        return snap.result;
+    }
+    /** No long-lived resources to dispose (direct HTTP, no sessions). */
+    async dispose() { }
+}
+exports.IndexScanService = IndexScanService;

package/gateway/dist/recall/inject-format.js

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOTE_BOARD_BUDGET = exports.PINNED_BUDGET = void 0;
+exports.renderMemoryBlocks = renderMemoryBlocks;
+exports.formatRecallContext = formatRecallContext;
+exports.formatPinnedProfile = formatPinnedProfile;
+exports.formatNoteBoard = formatNoteBoard;
+function formatDate(iso) {
+    if (!iso)
+        return '';
+    try {
+        const d = new Date(iso);
+        if (Number.isNaN(d.getTime()))
+            return '';
+        const yyyy = d.getFullYear();
+        const mm = String(d.getMonth() + 1).padStart(2, '0');
+        const dd = String(d.getDate()).padStart(2, '0');
+        return `${yyyy}-${mm}-${dd}`;
+    }
+    catch {
+        return '';
+    }
+}
+function pointerLine(m) {
+    const tags = [];
+    const date = formatDate(m.created_at);
+    if (date)
+        tags.push(date);
+    if (m.type)
+        tags.push(m.type);
+    const tagStr = tags.length > 0 ? `[${tags.join(' ')}] ` : '';
+    const text = (m.primary_abstraction || m.memory_value || '?').replace(/\n/g, ' ');
+    const energy = typeof m.energy === 'number' ? m.energy.toFixed(1) : '?';
+    // ids are `mem_<timestamp>_<rand>` — the FIRST 6 chars are constant across
+    // every memory; use the tail so pointers stay unique and verifiable.
+    return `- #mem-${(m.id || '?').slice(-6)} ${tagStr}"${text}" (E:${energy})`;
+}
+// Maps an entry to its block bucket. Order matters: parametric/delta entries go
+// to <deltas>, procedural patterns to <patterns>, episodic/history to
+// <history>, everything else to <facts>. Mirrors the classification used by
+// the gateway first-turn transform.
+function bucketFor(entry) {
+    if (entry.source === 'parametric' || entry.type === 'delta' || entry.type === 'constraint' || entry.type === 'prompt')
+        return 'deltas';
+    if (entry.source === 'procedural' || entry.type === 'pattern')
+        return 'patterns';
+    if (entry.source === 'episodic' || entry.type === 'history' || entry.type === 'review' || entry.verdict)
+        return 'history';
+    return 'facts';
+}
+function lineFor(entry) {
+    switch (bucketFor(entry)) {
+        case 'deltas':
+            return `[Δ ${entry.type || 'constraint'}] ${entry.content || entry.rule || entry.prompt_delta || entry.pattern_template || ''}`;
+        case 'patterns':
+            return `[${((entry.successRate || 0) * 100).toFixed(0)}%] ${entry.pattern || entry.content || ''}`;
+        case 'history':
+            return `Loop ${entry.loopNum || '?'}: ${entry.verdict || '?'} ☑ ${entry.summary || entry.content || ''}`;
+        case 'facts': {
+            const content = (entry.facts && entry.facts.length ? entry.facts.join('; ') : entry.content) || '';
+            return content ? `☑ ${content}` : '';
+        }
+    }
+}
+/**
+ * Renders a list of memory entries into XML block strings, one per bucket:
+ * `<deltas>`, `<patterns>`, `<facts>`, `<history>`. Empty buckets are omitted.
+ * Callers join with "\n\n".
+ */
+function renderMemoryBlocks(entries) {
+    const buckets = { deltas: [], patterns: [], facts: [], history: [] };
+    for (const entry of entries) {
+        const line = lineFor(entry);
+        if (line.trim())
+            buckets[bucketFor(entry)].push(line);
+    }
+    const chunks = [];
+    for (const tag of ['deltas', 'patterns', 'facts', 'history']) {
+        if (buckets[tag].length > 0)
+            chunks.push(`<${tag}>\n${buckets[tag].join('\n')}\n</${tag}>`);
+    }
+    return chunks;
+}
+// ---- Pointer rendering (boundary recall) ----
+const POINTER_HEADER = `[联想线索 · 依据前请验证：取全文 → mafw_get_memory("#mem-后6位")；检索更多 → mafw_search_hybrid]`;
+const TAG = `<recall>`;
+const END_TAG = `</recall>`;
+/**
+ * Group memories by type for better cross-session visibility.
+ * Multi-session queries benefit from seeing memories organized by topic.
+ */
+function groupMemoriesByType(memories) {
+    const groups = new Map();
+    for (const m of memories) {
+        const type = m.type || 'other';
+        if (!groups.has(type))
+            groups.set(type, []);
+        groups.get(type).push(m);
+    }
+    return groups;
+}
+function formatRecallContext(memories) {
+    if (memories.length === 0)
+        return { pointers: null };
+    // Episodic grouping: memories sharing a source session render under one
+    // session header with a date range (Memora-style narrative recovery —
+    // multi-session questions need to see that two hits came from one episode).
+    const sessionGroups = new Map();
+    for (const m of memories) {
+        if (!m.source_session_id)
+            continue;
+        if (!sessionGroups.has(m.source_session_id))
+            sessionGroups.set(m.source_session_id, []);
+        sessionGroups.get(m.source_session_id).push(m);
+    }
+    const groupedIds = new Set();
+    for (const mems of sessionGroups.values()) {
+        if (mems.length < 2)
+            continue;
+        for (const m of mems)
+            groupedIds.add(m.id);
+    }
+    const groups = groupMemoriesByType(memories);
+    const lines = [];
+    let sessionHeaders = 0;
+    for (const [sessionId, mems] of sessionGroups) {
+        if (mems.length < 2)
+            continue;
+        const dates = mems.map(m => formatDate(m.created_at)).filter(Boolean).sort();
+        const range = dates.length >= 2 && dates[0] !== dates[dates.length - 1]
+            ? `${dates[0]}~${dates[dates.length - 1]}`
+            : dates[0] ?? '';
+        lines.push(`[session ${sessionId.slice(0, 8)}${range ? ' · ' + range : ''}]`);
+        for (const m of mems) {
+            lines.push(`  ${pointerLine(m)}`);
+        }
+        sessionHeaders++;
+    }
+    // Everything else (ungrouped or singletons) renders as before.
+    const rest = memories.filter(m => !groupedIds.has(m.id));
+    const restGroups = groupMemoriesByType(rest);
+    if (restGroups.size <= 1 && sessionHeaders === 0) {
+        lines.push(...rest.slice(0, 3).map(pointerLine));
+    }
+    else if (rest.length > 0) {
+        for (const [type, mems] of restGroups) {
+            if (mems.length === 0)
+                continue;
+            lines.push(`[${type}]`);
+            for (const m of mems.slice(0, 2)) {
+                lines.push(`  ${pointerLine(m)}`);
+            }
+        }
+    }
+    const pointers = `${TAG}\n${POINTER_HEADER}\n${lines.slice(0, 5).join('\n')}\n${END_TAG}`;
+    return { pointers };
+}
+// ---- Pinned disclosure profile rendering (GET /api/recall/pinned) ----
+exports.PINNED_BUDGET = { max: 20, maxChars: 2000 };
+const PROFILE_TAG = '<user-profile>';
+const PROFILE_END_TAG = '</user-profile>';
+/**
+ * Renders pinned memories into the <user-profile> disclosure block.
+ * Enforces the hard budget (max entries / max chars); entries beyond the
+ * budget are dropped (caller logs the overflow count). Returns null profile
+ * for an empty set — callers must not inject an empty block.
+ */
+function formatPinnedProfile(entries) {
+    const lines = [];
+    let chars = 0;
+    for (const m of entries.slice(0, exports.PINNED_BUDGET.max)) {
+        const text = (m.memory_value || m.primary_abstraction || '?').replace(/\n/g, ' ');
+        const line = `- ${text}`;
+        if (chars + line.length > exports.PINNED_BUDGET.maxChars)
+            break;
+        lines.push(line);
+        chars += line.length;
+    }
+    if (lines.length === 0)
+        return { profile: null, used: 0 };
+    return { profile: `${PROFILE_TAG}\n${lines.join('\n')}\n${PROFILE_END_TAG}`, used: lines.length };
+}
+// ---- Sticky note board rendering (appended to /api/recall/context) ----
+// maxChars 1600 ≈ 800-1200 tok/turn（中文 ≈1 字/token），低于 pinned 的 2000
+// 保持"pinned=长期身份 > sticky=近期提醒"的层级。perNoteCap 是防饿死关键：
+// 无上限时一条超长便签吃光总预算，后续条目全部被 break 丢弃（实证 bug）。
+exports.NOTE_BOARD_BUDGET = { max: 10, maxChars: 1600, perNoteCap: 240 };
+const BOARD_TAG = '<note-board>';
+const BOARD_END_TAG = '</note-board>';
+/**
+ * Renders sticky notes into the <note-board> block: guaranteed per-turn
+ * visibility for user-commissioned memories until their sticky_until passes.
+ * Board-level expiry only — the memory itself is never deleted or hidden
+ * from search. Enforces a hard budget; returns null board for an empty set.
+ * `now` is injectable for deterministic tests.
+ */
+function formatNoteBoard(entries, now = new Date()) {
+    const lines = [];
+    let chars = 0;
+    for (const m of entries.slice(0, exports.NOTE_BOARD_BUDGET.max)) {
+        let text = (m.memory_value || m.primary_abstraction || '?').replace(/\n/g, ' ');
+        if (text.length > exports.NOTE_BOARD_BUDGET.perNoteCap) {
+            // 单条截断防饿死：板上只留前 240 字；完整内容 NotesDock/get_memory 可看
+            text = `${text.slice(0, exports.NOTE_BOARD_BUDGET.perNoteCap)}…`;
+        }
+        const until = m.sticky_until ? new Date(m.sticky_until) : null;
+        const valid = until && !Number.isNaN(until.getTime());
+        const daysLeft = valid ? Math.max(0, Math.ceil((until.getTime() - now.getTime()) / 86400e3)) : null;
+        const date = valid ? formatDate(m.sticky_until) : '';
+        const line = `- ${date ? `[${date.slice(5)}] ` : ''}${text}${daysLeft !== null ? `（剩 ${daysLeft} 天）` : ''}`;
+        if (chars + line.length > exports.NOTE_BOARD_BUDGET.maxChars)
+            break;
+        lines.push(line);
+        chars += line.length;
+    }
+    if (lines.length === 0)
+        return { board: null, used: 0 };
+    return {
+        board: `${BOARD_TAG}\n[用户叮嘱 · 到期自动下架，记忆本体保留]\n${lines.join('\n')}\n${BOARD_END_TAG}`,
+        used: lines.length,
+    };
+}