@byte5ai/palaia 2.3.6 → 2.7.1

package/src/hooks/capture.ts

@@ -144,7 +144,10 @@ function resolveExtensionAPIPath(): string | null {
 
   // Strategy 3: Sibling in global node_modules (plugin installed alongside openclaw)
   try {
-    const thisFile = typeof __dirname !== "undefined" ? __dirname : path.dirname(new URL(import.meta.url).pathname);
+    // __dirname is always available in CJS (our tsconfig module); the ESM
+    // fallback via import.meta.url is kept for jiti/ESM loaders at runtime.
+    // @ts-expect-error import.meta is valid at runtime under jiti/ESM but TS module=commonjs rejects it
+    const thisFile: string = typeof __dirname !== "undefined" ? __dirname : path.dirname(new URL(import.meta.url).pathname);
     // Walk up from plugin src/dist to node_modules, then into openclaw
     let dir = thisFile;
     for (let i = 0; i < 6; i++) {
@@ -234,12 +237,8 @@ WHAT TO CAPTURE (be thorough — capture anything worth remembering):
 - Project context changes: scope changes, timeline shifts, requirement updates, priority changes
 - Workflow patterns the user established ("my process is...", "I always do X before Y")
 
-STRICT TASK CLASSIFICATION RULES — a "task" MUST have ALL three of:
-1. A clear, completable action (not just an observation or idea)
-2. An identifiable responsible party (explicitly named or unambiguously inferable from context)
-3. A concrete deliverable or measurable end state
-If ANY of these is missing, classify as "memory" instead of "task". When in doubt, use "memory".
-Observations, learnings, insights, opinions, and general knowledge are ALWAYS "memory", never "task".
+IMPORTANT: Never classify as "task". Tasks are manually created sticky notes (post-its) — they must only come from explicit user/agent intent via palaia write --type task. Auto-capture must use "memory" or "process" only.
+Observations, learnings, insights, opinions, action items, and general knowledge are ALWAYS "memory" or "process", never "task".
 
 Only extract genuinely significant knowledge. Skip small talk, acknowledgments, routine exchanges.
 Do NOT extract if similar knowledge was likely captured in a recent exchange. Prefer quality over quantity. Skip routine status updates and acknowledgments.
@@ -458,7 +457,7 @@ export function trimToRecentExchanges(
 export async function extractWithLLM(
   messages: unknown[],
   config: any,
-  pluginConfig?: { captureModel?: string },
+  pluginConfig?: { captureModel?: string; workspace?: string },
   knownProjects?: CachedProject[],
 ): Promise<ExtractionResult[]> {
   const runEmbeddedPiAgent = await getEmbeddedPiAgent();
@@ -469,11 +468,11 @@ export async function extractWithLLM(
   }
 
   const allTexts = extractMessageTexts(messages);
-  // Strip Palaia-injected recall context from user messages to prevent feedback loop
+  // Strip palaia-injected recall context and private blocks from user messages
   const cleanedTexts = allTexts.map(t =>
     t.role === "user"
-      ? { ...t, text: stripPalaiaInjectedContext(t.text) }
-      : t
+      ? { ...t, text: stripPrivateBlocks(strippalaiaInjectedContext(t.text)) }
+      : { ...t, text: stripPrivateBlocks(t.text) }
   );
   // Only extract from recent exchanges — full history causes LLM timeouts
   // and dilutes extraction quality
@@ -516,7 +515,7 @@ export async function extractWithLLM(
     const result = await runEmbeddedPiAgent({
       sessionId,
       sessionFile,
-      workspaceDir: config?.agents?.defaults?.workspace ?? process.cwd(),
+      workspaceDir: pluginConfig?.workspace || config?.agents?.defaults?.workspace || process.cwd(),
       config,
       prompt,
       timeoutMs: 15_000,
@@ -548,7 +547,8 @@ export async function extractWithLLM(
       const content = typeof item.content === "string" ? item.content.trim() : "";
       if (!content) continue;
 
-      const validTypes = new Set(["memory", "process", "task"]);
+      const validTypes = new Set(["memory", "process"]);
+      // Tasks are manual-only (post-its) — auto-capture never creates tasks
       const type = validTypes.has(item.type) ? item.type : "memory";
 
       const validTags = new Set([
@@ -611,9 +611,9 @@ const SIGNIFICANCE_RULES: Array<{
   { pattern: /(?:mistake was|fehler war|should have|hätten sollen|next time)/i, tag: "lesson", type: "memory" },
   // Surprises
   { pattern: /(?:surprising|überraschend|unexpected|unerwartet|didn'?t expect|nicht erwartet|plot twist)/i, tag: "surprise", type: "memory" },
-  // Commitments and tasks
-  { pattern: /(?:i will|ich werde|todo:|action item|must do|muss noch|need to|commit to|verspreche)/i, tag: "commitment", type: "task" },
-  { pattern: /(?:deadline|frist|due date|bis zum|by end of|spätestens)/i, tag: "commitment", type: "task" },
+  // Commitments (captured as memory — tasks are manual-only post-its)
+  { pattern: /(?:i will|ich werde|todo:|action item|must do|muss noch|need to|commit to|verspreche)/i, tag: "commitment", type: "memory" },
+  { pattern: /(?:deadline|frist|due date|bis zum|by end of|spätestens)/i, tag: "commitment", type: "memory" },
   // Processes and workflows
   { pattern: /(?:the process is|der prozess|steps?:|workflow:|how to|anleitung|recipe:|checklist)/i, tag: "process", type: "process" },
   { pattern: /(?:first,?\s.*then|schritt \d|step \d|1\.\s.*2\.\s)/i, tag: "process", type: "process" },
@@ -722,19 +722,33 @@ export function extractSignificance(
 }
 
 /**
- * Strip Palaia-injected recall context from message text.
+ * Strip palaia-injected recall context from message text.
  * The recall block is prepended to user messages by before_prompt_build via prependContext.
  * OpenClaw merges it into the user message, so agent_end sees it as user content.
  * Without stripping, auto-capture re-captures the injected memories -> feedback loop.
  *
  * The block has a stable structure:
- * - Starts with "## Active Memory (Palaia)"
+ * - Starts with "## Active Memory (palaia)"
  * - Contains [t/m], [t/pr], [t/tk] prefixed entries
  * - Ends with "[palaia] auto-capture=on..." nudge line
  */
-export function stripPalaiaInjectedContext(text: string): string {
-  // Pattern: "## Active Memory (Palaia)" ... "[palaia] auto-capture=on..." + optional trailing newlines
+export function strippalaiaInjectedContext(text: string): string {
+  // Pattern: "## Active Memory (palaia)" ... "[palaia] auto-capture=on..." + optional trailing newlines
   // The nudge line is always present and marks the end of the injected block
-  const PALAIA_BLOCK_RE = /## Active Memory \(Palaia\)[\s\S]*?\[palaia\][^\n]*\n*/;
-  return text.replace(PALAIA_BLOCK_RE, '').trim();
+  const PALAIA_BLOCK_RE = /## Active Memory \(palaia\)[\s\S]*?\[palaia\][^\n]*\n*/;
+  // Also strip Session Briefing blocks
+  const BRIEFING_BLOCK_RE = /## Session Briefing \(palaia\)[\s\S]*?(?=\n##|\n\n\n|$)/;
+  return text
+    .replace(PALAIA_BLOCK_RE, '')
+    .replace(BRIEFING_BLOCK_RE, '')
+    .trim();
+}
+
+/**
+ * Strip <private>...</private> blocks from text.
+ * Content inside private tags is excluded from memory capture.
+ * Inspired by claude-mem's privacy marker system.
+ */
+export function stripPrivateBlocks(text: string): string {
+  return text.replace(/<private>[\s\S]*?<\/private>/gi, '').trim();
 }

package/src/hooks/index.ts

@@ -1,5 +1,5 @@
 /**
- * Lifecycle hooks for the Palaia OpenClaw plugin.
+ * Lifecycle hooks for the palaia OpenClaw plugin.
  *
  * - before_prompt_build: Query-based contextual recall (Issue #65).
  *   Returns appendSystemContext with brain instruction when memory is used.
@@ -81,7 +81,7 @@ export {
   isNoiseContent,
   shouldAttemptCapture,
   extractSignificance,
-  stripPalaiaInjectedContext,
+  strippalaiaInjectedContext,
 } from "./capture.js";
 
 // Reaction exports
@@ -119,6 +119,8 @@ import {
   extractMessageTexts,
   buildRecallQuery,
   rerankByTypeWeight,
+  formatEntryLine,
+  shouldUseCompactMode,
 } from "./recall.js";
 
 import {
@@ -128,7 +130,7 @@ import {
   resolveCaptureModel,
   shouldAttemptCapture,
   extractSignificance,
-  stripPalaiaInjectedContext,
+  strippalaiaInjectedContext,
   trimToRecentExchanges,
   setLogger as setCaptureLogger,
   getLlmImportFailureLogged,
@@ -151,6 +153,9 @@ import {
   filterBlocked,
 } from "../priorities.js";
 
+import { formatBriefing } from "./session.js";
+import { getOrCreateSessionState } from "./state.js";
+
 // ============================================================================
 // Logger (Issue: api.logger integration)
 // ============================================================================
@@ -190,6 +195,10 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
 
   const opts = buildRunnerOpts(config);
 
+  // Note: Session lifecycle hooks (session_start, session_end, before_reset,
+  // llm_input, llm_output, after_tool_call) are registered in index.ts entry
+  // point BEFORE this function, so they work for both ContextEngine and legacy paths.
+
   // ── Startup checks (H-2, H-3, captureModel validation) ────────
   (async () => {
     // H-2: Warn if no agent is configured
@@ -269,7 +278,7 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
   // ── /palaia status command ─────────────────────────────────────
   api.registerCommand({
     name: "palaia-status",
-    description: "Show Palaia memory status",
+    description: "Show palaia memory status",
     async handler(_args: string) {
       try {
         const state = await loadPluginState(config.workspace);
@@ -284,7 +293,7 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
 
         return { text: formatStatusResponse(state, stats, config) };
       } catch (error) {
-        return { text: `Palaia status error: ${error}` };
+        return { text: `palaia status error: ${error}` };
       }
     },
   });
@@ -326,7 +335,7 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
     }
   });
 
-  // ── before_prompt_build (Issue #65: Query-based Recall) ────────
+  // ── before_prompt_build (Issue #65: Query-based Recall + v3.0 Session Briefing) ──
   if (config.memoryInject) {
     api.on("before_prompt_build", async (event: any, ctx: any) => {
       // Prune stale entries to prevent memory leaks from crashed sessions (C-2)
@@ -337,6 +346,34 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
       const hookOpts = buildRunnerOpts(config, { workspace: resolved.workspace });
 
       try {
+        // ── Session Briefing Injection (v3.0) ─────────────────────
+        // If a session briefing is pending (from session_start or model switch),
+        // prepend it to the recall context for seamless session continuity.
+        let briefingText = "";
+        let briefingSummary: string | null = null; // Kept for smart query fallback
+        const sessionKey = resolveSessionKeyFromCtx(ctx);
+        if (sessionKey) {
+          const sessState = getOrCreateSessionState(sessionKey);
+          // Wait for session_start briefing load (max 3s to avoid blocking)
+          if (sessState.briefingReady) {
+            await Promise.race([
+              sessState.briefingReady,
+              new Promise<void>(r => setTimeout(r, 3000)),
+            ]);
+          }
+          // Capture summary BEFORE clearing, for smart query fallback below
+          briefingSummary = sessState.pendingBriefing?.summary ?? null;
+          if (sessState.pendingBriefing && !sessState.briefingDelivered) {
+            briefingText = formatBriefing(sessState.pendingBriefing, config.sessionBriefingMaxChars);
+            sessState.briefingDelivered = true;
+            // Clear pending briefing after delivery (unless model switch re-triggers)
+            if (!sessState.modelSwitchDetected) {
+              sessState.pendingBriefing = null;
+            }
+            sessState.modelSwitchDetected = false;
+          }
+        }
+
         // Load and resolve priorities (Issue #121)
         const prio = await loadPriorities(resolved.workspace);
         const project = config.captureProject || undefined;
@@ -347,15 +384,25 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
           tier: config.tier,
         }, resolved.agentId, project);
 
-        const maxChars = resolvedPrio.maxInjectedChars || 4000;
+        // Reduce recall budget by briefing size
+        const maxChars = Math.max((resolvedPrio.maxInjectedChars || 4000) - briefingText.length, 500);
         const limit = Math.min(config.maxResults || 10, 20);
         let entries: QueryResult["results"] = [];
 
         if (config.recallMode === "query") {
-          const userMessage = event.messages
+          let userMessage = event.messages
             ? buildRecallQuery(event.messages)
             : (event.prompt || null);
 
+          // ── Smart Query Fallback (v3.0) ───────────────────────
+          // If query is too short or matches a continuation pattern,
+          // use the session summary as query for better recall results.
+          const CONTINUATION_PATTERN = /^(ja|ok|weiter|mach|genau|do it|yes|continue|go|proceed|sure|klar|passt|yep|yup|exactly|right)\b/i;
+          if (briefingSummary && userMessage && (userMessage.length < 10 || CONTINUATION_PATTERN.test(userMessage.trim()))) {
+            userMessage = briefingSummary.slice(0, 500);
+            logger.info("[palaia] Smart query fallback: using session summary as recall query");
+          }
+
           if (userMessage && userMessage.length >= 5) {
             // Try embed server first (fast path: ~0.5s), then CLI fallback (~3-14s)
             let serverQueried = false;
@@ -372,6 +419,7 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
                     text: userMessage,
                     top_k: limit,
                     include_cold: resolvedPrio.tier === "all",
+                    ...(resolvedPrio.scopeVisibility ? { scope_visibility: resolvedPrio.scopeVisibility } : {}),
                   }, config.timeoutMs || 3000);
                   if (resp?.result?.results && Array.isArray(resp.result.results)) {
                     entries = resp.result.results;
@@ -417,36 +465,37 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
               entries = result.results;
             }
           } catch {
+            // Still deliver briefing even if recall fails completely
+            if (briefingText) {
+              return { prependContext: briefingText };
+            }
             return;
           }
         }
 
-        if (entries.length === 0) return;
+        // If no recall entries but briefing exists, deliver briefing alone
+        if (entries.length === 0) {
+          if (briefingText) {
+            return { prependContext: briefingText };
+          }
+          return;
+        }
 
         // Apply type-weighted reranking and blocked filtering (Issue #121)
-        const rankedRaw = rerankByTypeWeight(entries, resolvedPrio.recallTypeWeight);
+        const rankedRaw = rerankByTypeWeight(entries, resolvedPrio.recallTypeWeight, config.recallRecencyBoost, config.manualEntryBoost);
         const ranked = filterBlocked(rankedRaw, resolvedPrio.blocked);
 
-        // Build context string with char budget (compact format for token efficiency)
-        const SCOPE_SHORT: Record<string, string> = { team: "t", private: "p", public: "pub" };
-        const TYPE_SHORT: Record<string, string> = { memory: "m", process: "pr", task: "tk" };
-
-        let text = "## Active Memory (Palaia)\n\n";
+        // Build context string with char budget
+        // Progressive disclosure: compact mode for large stores (title + first line + ID)
+        const compact = shouldUseCompactMode(ranked.length);
+        let text = "## Active Memory (palaia)\n\n";
+        if (compact) {
+          text += "_Compact mode — use `memory_get <id>` for full details._\n\n";
+        }
         let chars = text.length;
 
         for (const entry of ranked) {
-          const scopeKey = SCOPE_SHORT[entry.scope] || entry.scope;
-          const typeKey = TYPE_SHORT[entry.type] || entry.type;
-          const prefix = `[${scopeKey}/${typeKey}]`;
-
-          // If body starts with title (common), skip title to save tokens
-          let line: string;
-          if (entry.body.toLowerCase().startsWith(entry.title.toLowerCase())) {
-            line = `${prefix} ${entry.body}\n\n`;
-          } else {
-            line = `${prefix} ${entry.title}\n${entry.body}\n\n`;
-          }
-
+          const line = formatEntryLine(entry, compact);
           if (chars + line.length > maxChars) break;
           text += line;
           chars += line.length;
@@ -463,7 +512,7 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
           }
           const { nudges } = checkNudges(pluginState);
           if (nudges.length > 0) {
-            nudgeContext = "\n\n## Agent Nudge (Palaia)\n\n" + nudges.join("\n\n");
+            nudgeContext = "\n\n## Agent Nudge (palaia)\n\n" + nudges.join("\n\n");
           }
           await savePluginState(pluginState, resolved.workspace);
         } catch {
@@ -483,7 +532,6 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
         const hasRelevantRecall = !isListFallback && entries.some(
           (e) => typeof e.score === "number" && e.score >= resolvedPrio.recallMinScore,
         );
-        const sessionKey = resolveSessionKeyFromCtx(ctx);
         if (sessionKey && hasRelevantRecall) {
           const turnState = getOrCreateTurnState(sessionKey);
           turnState.recallOccurred = true;
@@ -506,9 +554,9 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
 
         // Return prependContext + appendSystemContext for recall emoji
         return {
-          prependContext: text + nudgeContext,
+          prependContext: briefingText + text,
           appendSystemContext: config.showMemorySources
-            ? "You used Palaia memory in this turn. Add \u{1f9e0} at the very end of your response (after everything else, on its own line)."
+            ? "You used palaia memory in this turn. Add \u{1f9e0} at the very end of your response (after everything else, on its own line)."
             : undefined,
         };
       } catch (error) {
@@ -539,6 +587,7 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
       const hookOpts = buildRunnerOpts(config, { workspace: resolved.workspace });
 
       if (!event.success || !event.messages || event.messages.length === 0) {
+        logger.info(`[palaia] Auto-capture skipped: success=${event.success}, messages=${event.messages?.length ?? 0}`);
         return;
       }
 
@@ -549,6 +598,7 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
 
         const userTurns = allTexts.filter((t) => t.role === "user").length;
         if (userTurns < config.captureMinTurns) {
+          logger.info(`[palaia] Auto-capture skipped: ${userTurns} user turns < captureMinTurns=${config.captureMinTurns}`);
           return;
         }
 
@@ -559,14 +609,17 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
           collectedHints.push(...hints);
         }
 
-        // Strip Palaia-injected recall context from user messages to prevent feedback loop.
+        // Strip palaia-injected recall context and private blocks from messages.
         // The recall block is prepended to user messages by before_prompt_build.
         // Without stripping, auto-capture would re-capture previously recalled memories.
-        const cleanedTexts = allTexts.map(t =>
-          t.role === "user"
-            ? { ...t, text: stripPalaiaInjectedContext(t.text) }
-            : t
-        );
+        // Private blocks (<private>...</private>) must be excluded from capture.
+        const { stripPrivateBlocks } = await import("./capture.js");
+        const cleanedTexts = allTexts.map(t => ({
+          ...t,
+          text: stripPrivateBlocks(
+            t.role === "user" ? strippalaiaInjectedContext(t.text) : t.text
+          ),
+        }));
 
         // Only extract from recent exchanges — full history causes LLM timeouts
         // and dilutes extraction quality
@@ -581,11 +634,29 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
         const exchangeText = exchangeParts.join("\n");
 
         if (!shouldAttemptCapture(exchangeText)) {
+          logger.info(`[palaia] Auto-capture skipped: content did not pass significance filter (${exchangeText.length} chars)`);
           return;
         }
 
         const knownProjects = await loadProjects(hookOpts);
 
+        // Resolve effective capture scope from priorities (per-agent override, #147)
+        let effectiveCaptureScope = config.captureScope || "";
+        try {
+          const prio = await loadPriorities(resolved.workspace);
+          const resolvedCapturePrio = resolvePriorities(prio, {
+            recallTypeWeight: config.recallTypeWeight,
+            recallMinScore: config.recallMinScore,
+            maxInjectedChars: config.maxInjectedChars,
+            tier: config.tier,
+          }, agentName);
+          if (resolvedCapturePrio.captureScope) {
+            effectiveCaptureScope = resolvedCapturePrio.captureScope;
+          }
+        } catch {
+          // Fall through to config default
+        }
+
         // Helper: build CLI args with metadata
         const buildWriteArgs = (
           content: string,
@@ -601,9 +672,9 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
             "--tags", tags.join(",") || "auto-capture",
           ];
 
-          // Scope guardrail: config.captureScope overrides everything; otherwise max team (no public)
-          const scope = config.captureScope
-            ? sanitizeScope(config.captureScope, "team", true)
+          // Scope guardrail: priorities captureScope > config.captureScope > hint/LLM scope
+          const scope = effectiveCaptureScope
+            ? sanitizeScope(effectiveCaptureScope, "team", true)
             : sanitizeScope(itemScope, "team", false);
           args.push("--scope", scope);
 
@@ -665,6 +736,7 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
         try {
           const results = await extractWithLLM(event.messages, api.config, {
             captureModel: config.captureModel,
+            workspace: resolved.workspace,
           }, knownProjects);
 
           await storeLLMResults(results);
@@ -684,6 +756,7 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
               // Retry without captureModel -> resolveCaptureModel will use primary model
               const fallbackResults = await extractWithLLM(event.messages, api.config, {
                 captureModel: undefined,
+                workspace: resolved.workspace,
               }, knownProjects);
               await storeLLMResults(fallbackResults);
               llmHandled = true;
@@ -708,6 +781,7 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
           if (config.captureFrequency === "significant") {
             const significance = extractSignificance(exchangeText);
             if (!significance) {
+              logger.info("[palaia] Auto-capture skipped: rule-based extraction found no significance (need ≥2 distinct tags)");
               return;
             }
             captureData = significance;
@@ -821,7 +895,7 @@ export function registerHooks(api: OpenClawPluginApi, config: PalaiaPluginConfig
   // ── Startup Recovery Service ───────────────────────────────────
   api.registerService({
     id: "palaia-recovery",
-    start: async () => {
+    start: async (_ctx) => {
       const result = await recover(opts);
       if (result.replayed > 0) {
         logger.info(`[palaia] WAL recovery: replayed ${result.replayed} entries`);

package/src/hooks/recall.ts

@@ -6,7 +6,7 @@
  */
 
 import type { RecallTypeWeights } from "../config.js";
-import { stripPalaiaInjectedContext } from "./capture.js";
+import { strippalaiaInjectedContext } from "./capture.js";
 
 // ============================================================================
 // Types
@@ -26,6 +26,7 @@ export interface QueryResult {
     title?: string;
     type?: string;
     tags?: string[];
+    created?: string;
   }>;
 }
 
@@ -78,7 +79,7 @@ export function buildFootnote(
     const dateStr = formatShortDate(e.date);
     return dateStr ? `"${e.title}" (${dateStr})` : `"${e.title}"`;
   });
-  return `\n\n\u{1f4ce} Palaia: ${parts.join(", ")}`;
+  return `\n\n\u{1f4ce} palaia: ${parts.join(", ")}`;
 }
 
 // Re-export formatShortDate from state for use here
@@ -95,7 +96,7 @@ const TRANSPARENCY_RECALL_THRESHOLD = 50;
 const TRANSPARENCY_DAYS_THRESHOLD = 7;
 
 const SATISFACTION_NUDGE_TEXT =
-  "Your user has been using Palaia for a while now. " +
+  "Your user has been using palaia for a while now. " +
   "Ask them casually if they're happy with the memory system. " +
   "If there are issues, suggest `palaia doctor`.";
 
@@ -267,7 +268,7 @@ function isSystemOnlyContent(text: string): boolean {
 export function buildRecallQuery(messages: unknown[]): string {
   const texts = extractMessageTexts(messages).map(t =>
     t.role === "user"
-      ? { ...t, text: stripPalaiaInjectedContext(t.text) }
+      ? { ...t, text: strippalaiaInjectedContext(t.text) }
       : t
   );
 
@@ -342,16 +343,41 @@ export interface RankedEntry {
   bm25Score?: number;
   embedScore?: number;
   weightedScore: number;
+  created?: string;
+  tags?: string[];
+}
+
+/**
+ * Calculate recency boost factor.
+ * Returns a multiplier: 1.0 (no boost) to 1.0 + boostFactor (max boost for very recent).
+ * Formula: 1 + boostFactor * exp(-hoursAgo / 24)
+ */
+function calcRecencyBoost(created: string | undefined, boostFactor: number): number {
+  if (!boostFactor || !created) return 1.0;
+  try {
+    const hoursAgo = (Date.now() - new Date(created).getTime()) / (1000 * 60 * 60);
+    if (hoursAgo < 0 || isNaN(hoursAgo)) return 1.0;
+    return 1.0 + boostFactor * Math.exp(-hoursAgo / 24);
+  } catch {
+    return 1.0;
+  }
 }
 
 export function rerankByTypeWeight(
   results: QueryResult["results"],
-  weights: RecallTypeWeights,
+  weights: Record<string, number>,
+  recencyBoost = 0,
+  manualEntryBoost = 1.3,
 ): RankedEntry[] {
   return results
     .map((r) => {
       const type = r.type || "memory";
       const weight = weights[type] ?? 1.0;
+      const recency = calcRecencyBoost(r.created, recencyBoost);
+      // Manual entries (no auto-capture tag) get a boost over auto-captured ones.
+      // This ensures intentionally stored knowledge ranks higher than conversation noise.
+      const isAutoCapture = r.tags?.includes("auto-capture") ?? false;
+      const sourceBoost = isAutoCapture ? 1.0 : manualEntryBoost;
       return {
         id: r.id,
         body: r.content || r.body || "",
@@ -362,8 +388,50 @@ export function rerankByTypeWeight(
         score: r.score,
         bm25Score: r.bm25_score,
         embedScore: r.embed_score,
-        weightedScore: r.score * weight,
+        weightedScore: r.score * weight * recency * sourceBoost,
+        created: r.created,
+        tags: r.tags,
       };
     })
     .sort((a, b) => b.weightedScore - a.weightedScore);
 }
+
+// ── Context Formatting ──────────────────────────────────────────────────
+
+const SCOPE_SHORT: Record<string, string> = { team: "t", private: "p", public: "pub" };
+const TYPE_SHORT: Record<string, string> = { memory: "m", process: "pr", task: "tk" };
+
+/**
+ * Format a ranked entry as an injectable context line.
+ *
+ * In compact mode (progressive disclosure), only title + first line + ID are shown.
+ * The agent can use `memory_get <id>` for the full entry.
+ */
+export function formatEntryLine(entry: RankedEntry, compact: boolean): string {
+  const scopeKey = SCOPE_SHORT[entry.scope] || entry.scope;
+  const typeKey = TYPE_SHORT[entry.type] || entry.type;
+  const prefix = `[${scopeKey}/${typeKey}]`;
+
+  if (compact) {
+    // Compact: title + first line of body + ID reference
+    const firstLine = entry.body.split("\n")[0]?.slice(0, 120) || "";
+    const titlePart = entry.body.toLowerCase().startsWith(entry.title.toLowerCase())
+      ? firstLine
+      : `${entry.title} — ${firstLine}`;
+    return `${prefix} ${titlePart} [id:${entry.id}]\n`;
+  }
+
+  // Full: title + complete body
+  if (entry.body.toLowerCase().startsWith(entry.title.toLowerCase())) {
+    return `${prefix} ${entry.body}\n\n`;
+  }
+  return `${prefix} ${entry.title}\n${entry.body}\n\n`;
+}
+
+/**
+ * Determine if compact mode should be used based on result count.
+ * Above threshold, use compact mode to fit more entries in budget.
+ */
+export function shouldUseCompactMode(totalResults: number, threshold = 100): boolean {
+  return totalResults > threshold;
+}