@byte5ai/palaia 2.0.3 → 2.0.5

package/openclaw.plugin.json

@@ -33,7 +33,7 @@
       },
       "maxInjectedChars": {
         "type": "number",
-        "default": 8000,
+        "default": 4000,
         "description": "Max characters for injected memory context"
       },
       "autoCapture": {
@@ -86,6 +86,11 @@
         "default": "query",
         "description": "Recall mode: list (context-independent) or query (context-relevant)"
       },
+      "recallMinScore": {
+        "type": "number",
+        "default": 0.7,
+        "description": "Minimum score for a recall result to be considered relevant (default: 0.7)"
+      },
       "recallTypeWeight": {
         "type": "object",
         "default": { "process": 1.5, "task": 1.2, "memory": 1.0 },
@@ -113,7 +118,7 @@
     },
     "maxInjectedChars": {
       "label": "Max Injected Characters",
-      "description": "Maximum characters of memory context injected per prompt (recommended: 8000)"
+      "description": "Maximum characters of memory context injected per prompt (recommended: 4000)"
     },
     "autoCapture": {
       "label": "Auto-Capture",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byte5ai/palaia",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "Palaia memory backend for OpenClaw",
   "main": "index.ts",
   "openclaw": {

package/src/config.ts

@@ -54,6 +54,10 @@ export interface PalaiaPluginConfig {
   recallMode: "list" | "query";
   /** Type-aware weighting for recall results */
   recallTypeWeight: RecallTypeWeights;
+
+  // ── Recall Quality (Issue #65) ───────────────────────────────
+  /** Minimum score for a recall result to be considered relevant (default: 0.7) */
+  recallMinScore: number;
 }
 
 export const DEFAULT_RECALL_TYPE_WEIGHTS: RecallTypeWeights = {
@@ -67,15 +71,16 @@ export const DEFAULT_CONFIG: PalaiaPluginConfig = {
   maxResults: 10,
   timeoutMs: 3000,
   memoryInject: true,
-  maxInjectedChars: 8000,
+  maxInjectedChars: 4000,
   autoCapture: true,
   captureFrequency: "significant",
   captureMinTurns: 2,
-  captureMinSignificance: 0.3,
+  captureMinSignificance: 0.5,
   showMemorySources: true,
   showCaptureConfirm: true,
   recallMode: "query",
   recallTypeWeight: { ...DEFAULT_RECALL_TYPE_WEIGHTS },
+  recallMinScore: 0.7,
 };
 
 /**

package/src/hooks.ts

@@ -137,6 +137,16 @@ const lastInboundMessageByChannel = new Map<string, { messageId: string; provide
 /** Channels that support emoji reactions. */
 const REACTION_SUPPORTED_PROVIDERS = new Set(["slack", "discord"]);
 
+// ============================================================================
+// Logger (Issue: api.logger integration)
+// ============================================================================
+
+/** Module-level logger — defaults to console, replaced by api.logger in registerHooks. */
+let logger: { info: (...args: any[]) => void; warn: (...args: any[]) => void } = {
+  info: (...args: any[]) => console.log(...args),
+  warn: (...args: any[]) => console.warn(...args),
+};
+
 // ============================================================================
 // Scope Validation (Issue #90)
 // ============================================================================
@@ -153,10 +163,13 @@ export function isValidScope(s: string): boolean {
 
 /**
  * Sanitize a scope value — returns the value if valid, otherwise fallback.
+ * Enforces: LLM may suggest private or team, but NEVER public (unless explicitly configured).
  */
-export function sanitizeScope(rawScope: string | null | undefined, fallback = "team"): string {
-  if (rawScope && isValidScope(rawScope)) return rawScope;
-  return fallback;
+export function sanitizeScope(rawScope: string | null | undefined, fallback = "team", allowPublic = false): string {
+  if (!rawScope || !isValidScope(rawScope)) return fallback;
+  // Block public scope unless explicitly allowed (config-level override)
+  if (rawScope === "public" && !allowPublic) return fallback;
+  return rawScope;
 }
 
 // ============================================================================
@@ -347,7 +360,7 @@ async function sendSlackReaction(
 ): Promise<void> {
   const token = await resolveSlackBotToken();
   if (!token) {
-    console.warn("[palaia] Cannot send Slack reaction: no bot token found");
+    logger.warn("[palaia] Cannot send Slack reaction: no bot token found");
     return;
   }
 
@@ -372,11 +385,11 @@ async function sendSlackReaction(
     });
     const data = await response.json() as { ok: boolean; error?: string };
     if (!data.ok && data.error !== "already_reacted") {
-      console.warn(`[palaia] Slack reaction failed: ${data.error} (${normalizedEmoji} on ${channelId})`);
+      logger.warn(`[palaia] Slack reaction failed: ${data.error} (${normalizedEmoji} on ${channelId})`);
     }
   } catch (err) {
     if ((err as Error).name !== "AbortError") {
-      console.warn(`[palaia] Slack reaction error (${normalizedEmoji}): ${err}`);
+      logger.warn(`[palaia] Slack reaction error (${normalizedEmoji}): ${err}`);
     }
   } finally {
     clearTimeout(timeout);
@@ -721,6 +734,7 @@ For each piece of knowledge, return a JSON array of objects:
 - "scope": "private" (personal preference, agent-specific), "team" (shared knowledge), or "public" (documentation)
 
 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.
 Return empty array [] if nothing is worth remembering.
 Return ONLY valid JSON, no markdown fences.`;
 
@@ -788,7 +802,7 @@ export function resolveCaptureModel(
     if (parts.length >= 2) {
       if (!_captureModelFallbackWarned) {
         _captureModelFallbackWarned = true;
-        console.warn(`[palaia] No captureModel configured — using primary model. Set captureModel in plugin config for cost savings.`);
+        logger.warn(`[palaia] No captureModel configured — using primary model. Set captureModel in plugin config for cost savings.`);
       }
       return { provider: parts[0], model: parts.slice(1).join("/") };
     }
@@ -821,21 +835,27 @@ function collectText(payloads: Array<{ text?: string; isError?: boolean }> | und
  * then hard-cap at maxChars from the end (newest messages kept).
  */
 export function trimToRecentExchanges(
-  texts: Array<{ role: string; text: string }>,
+  texts: Array<{ role: string; text: string; provenance?: string }>,
   maxPairs = 5,
   maxChars = 10_000,
-): Array<{ role: string; text: string }> {
+): Array<{ role: string; text: string; provenance?: string }> {
   // Filter to only user + assistant messages (skip tool, toolResult, system, etc.)
   const exchanges = texts.filter((t) => t.role === "user" || t.role === "assistant");
 
   // Keep the last N pairs (a pair = one user + one assistant message)
+  // Only count external_user messages as real user turns.
+  // System-injected user messages (inter_session, internal_system) don't count as conversation turns.
   // Walk backwards, count pairs
   let pairCount = 0;
   let lastRole = "";
   let cutIndex = 0; // default: keep everything
   for (let i = exchanges.length - 1; i >= 0; i--) {
-    // Count a new pair when we see a user message after having seen an assistant
-    if (exchanges[i].role === "user" && lastRole === "assistant") {
+    const isRealUser = exchanges[i].role === "user" && (
+      exchanges[i].provenance === "external_user" ||
+      !exchanges[i].provenance // backward compat: no provenance = treat as real user
+    );
+    // Count a new pair when we see a real user message after having seen an assistant
+    if (isRealUser && lastRole === "assistant") {
       pairCount++;
       if (pairCount > maxPairs) {
         cutIndex = i + 1; // keep from next message onwards
@@ -1052,6 +1072,10 @@ export function extractSignificance(
 
   if (matched.length === 0) return null;
 
+  // Require at least 2 different significance tags for rule-based capture
+  const uniqueTags = new Set(matched.map((m) => m.tag));
+  if (uniqueTags.size < 2) return null;
+
   const typePriority: Record<string, number> = { task: 3, process: 2, memory: 1 };
   const primaryType = matched.reduce(
     (best, m) => (typePriority[m.type] > typePriority[best] ? m.type : best),
@@ -1079,8 +1103,8 @@ export function extractSignificance(
   return { tags, type: primaryType, summary };
 }
 
-export function extractMessageTexts(messages: unknown[]): Array<{ role: string; text: string }> {
-  const result: Array<{ role: string; text: string }> = [];
+export function extractMessageTexts(messages: unknown[]): Array<{ role: string; text: string; provenance?: string }> {
+  const result: Array<{ role: string; text: string; provenance?: string }> = [];
 
   for (const msg of messages) {
     if (!msg || typeof msg !== "object") continue;
@@ -1088,8 +1112,12 @@ export function extractMessageTexts(messages: unknown[]): Array<{ role: string;
     const role = m.role;
     if (!role || typeof role !== "string") continue;
 
+    // Extract provenance kind (string or object with .kind)
+    const rawProvenance = (m as any).provenance?.kind ?? (m as any).provenance;
+    const provenance = typeof rawProvenance === "string" ? rawProvenance : undefined;
+
     if (typeof m.content === "string" && m.content.trim()) {
-      result.push({ role, text: m.content.trim() });
+      result.push({ role, text: m.content.trim(), provenance });
       continue;
     }
 
@@ -1102,7 +1130,7 @@ export function extractMessageTexts(messages: unknown[]): Array<{ role: string;
           typeof block.text === "string" &&
           block.text.trim()
         ) {
-          result.push({ role, text: block.text.trim() });
+          result.push({ role, text: block.text.trim(), provenance });
         }
       }
     }
@@ -1113,12 +1141,59 @@ export function extractMessageTexts(messages: unknown[]): Array<{ role: string;
 
 export function getLastUserMessage(messages: unknown[]): string | null {
   const texts = extractMessageTexts(messages);
+  // Prefer external_user provenance (real human input)
+  for (let i = texts.length - 1; i >= 0; i--) {
+    if (texts[i].role === "user" && texts[i].provenance === "external_user")
+      return texts[i].text;
+  }
+  // Fallback: any user message (backward compat for OpenClaw without provenance)
   for (let i = texts.length - 1; i >= 0; i--) {
     if (texts[i].role === "user") return texts[i].text;
   }
   return null;
 }
 
+// ============================================================================
+// Recall Query Builder (provenance-based, Issue #65 upgrade)
+// ============================================================================
+
+/**
+ * Build a recall query from message history using provenance to identify real user input.
+ *
+ * - Prefers external_user messages (real human input from Slack/Telegram).
+ * - Falls back to any user message for backward compat (OpenClaw without provenance).
+ * - If the last user message is short (< 30 chars), prepends the previous for context.
+ * - Hard-caps at 500 characters.
+ *
+ * Provenance makes the old heuristic cleaners (DAY_PREFIXES, system marker stripping) obsolete.
+ */
+export function buildRecallQuery(messages: unknown[]): string {
+  const texts = extractMessageTexts(messages);
+
+  // Prefer external_user messages (real human input)
+  const externalUserMsgs = texts.filter(
+    t => t.role === "user" && t.provenance === "external_user"
+  );
+
+  // Fallback: any user message (backward compat for OpenClaw without provenance)
+  const userMsgs = externalUserMsgs.length > 0
+    ? externalUserMsgs
+    : texts.filter(t => t.role === "user");
+
+  if (userMsgs.length === 0) return "";
+
+  const lastMsg = userMsgs[userMsgs.length - 1].text.trim();
+
+  // Short messages: include previous for context
+  if (lastMsg.length < 30 && userMsgs.length > 1) {
+    const prevMsg = userMsgs[userMsgs.length - 2].text.trim();
+    const combined = `${prevMsg} ${lastMsg}`.slice(0, 500);
+    return combined;
+  }
+
+  return lastMsg.slice(0, 500);
+}
+
 // ============================================================================
 // Query-based Recall: Type-weighted reranking (Issue #65)
 // ============================================================================
@@ -1219,22 +1294,27 @@ export function resetTurnState(): void {
  * Register lifecycle hooks on the plugin API.
  */
 export function registerHooks(api: any, config: PalaiaPluginConfig): void {
+  // Store api.logger for module-wide use (integrates into OpenClaw log system)
+  if (api.logger && typeof api.logger.info === "function") {
+    logger = api.logger;
+  }
+
   const opts = buildRunnerOpts(config);
 
-  // ── Startup checks (H-2, H-3) ─────────────────────────────────
+  // ── Startup checks (H-2, H-3, captureModel validation) ────────
   (async () => {
     // H-2: Warn if no agent is configured
     if (!process.env.PALAIA_AGENT) {
       try {
         const statusOut = await run(["config", "get", "agent"], { ...opts, timeoutMs: 3000 });
         if (!statusOut.trim()) {
-          console.warn(
+          logger.warn(
             "[palaia] No agent configured. Set PALAIA_AGENT env var or run 'palaia init --agent <name>'. " +
             "Auto-captured entries will have no agent attribution."
           );
         }
       } catch {
-        console.warn(
+        logger.warn(
           "[palaia] No agent configured. Set PALAIA_AGENT env var or run 'palaia init --agent <name>'. " +
           "Auto-captured entries will have no agent attribution."
         );
@@ -1261,7 +1341,7 @@ export function registerHooks(api: any, config: PalaiaPluginConfig): void {
           || status.config?.embedding_provider
         );
         if (!hasSemanticProvider && !hasProviderConfig) {
-          console.warn(
+          logger.warn(
             "[palaia] No embedding provider configured. Semantic search is inactive (BM25 keyword-only). " +
             "Run 'pip install palaia[fastembed]' and 'palaia doctor --fix' for better recall quality."
           );
@@ -1271,6 +1351,19 @@ export function registerHooks(api: any, config: PalaiaPluginConfig): void {
     } catch {
       // Non-fatal — status check failed, skip warning (avoid false positive)
     }
+
+    // Validate captureModel auth at plugin startup via modelAuth API
+    if (config.captureModel && api.runtime?.modelAuth) {
+      try {
+        const resolved = resolveCaptureModel(api.config, config.captureModel);
+        if (resolved?.provider) {
+          const key = await api.runtime.modelAuth.resolveApiKeyForProvider({ provider: resolved.provider, cfg: api.config });
+          if (!key) {
+            logger.warn(`[palaia] captureModel provider "${resolved.provider}" has no API key — auto-capture LLM extraction will fail`);
+          }
+        }
+      } catch { /* non-fatal */ }
+    }
   })();
 
   // ── /palaia status command ─────────────────────────────────────
@@ -1345,8 +1438,9 @@ export function registerHooks(api: any, config: PalaiaPluginConfig): void {
         let entries: QueryResult["results"] = [];
 
         if (config.recallMode === "query") {
-          const userMessage = event.prompt
-            || (event.messages ? getLastUserMessage(event.messages) : null);
+          const userMessage = event.messages
+            ? buildRecallQuery(event.messages)
+            : (event.prompt || null);
 
           if (userMessage && userMessage.length >= 5) {
             try {
@@ -1359,13 +1453,15 @@ export function registerHooks(api: any, config: PalaiaPluginConfig): void {
                 entries = result.results;
               }
             } catch (queryError) {
-              console.warn(`[palaia] Query recall failed, falling back to list: ${queryError}`);
+              logger.warn(`[palaia] Query recall failed, falling back to list: ${queryError}`);
             }
           }
         }
 
-        // Fallback: list mode
+        // Fallback: list mode (no emoji — list-based recall is not query-relevant)
+        let isListFallback = false;
         if (entries.length === 0) {
+          isListFallback = true;
           try {
             const listArgs: string[] = ["list"];
             if (config.tier === "all") {
@@ -1387,17 +1483,35 @@ export function registerHooks(api: any, config: PalaiaPluginConfig): void {
         // Apply type-weighted reranking
         const ranked = rerankByTypeWeight(entries, config.recallTypeWeight);
 
-        // Build context string with char budget
+        // 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";
         let chars = text.length;
 
         for (const entry of ranked) {
-          const line = `**${entry.title}** [${entry.scope}/${entry.type}]\n${entry.body}\n\n`;
+          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`;
+          }
+
           if (chars + line.length > maxChars) break;
           text += line;
           chars += line.length;
         }
 
+        // Persistent usage nudge — compact guidance for the agent
+        const USAGE_NUDGE = "[palaia] auto-capture=on. Manual write: --type process (SOPs/checklists) or --type task (todos with assignee/deadline) only. Conversation knowledge is auto-captured — do not duplicate with manual writes.";
+        text += USAGE_NUDGE + "\n\n";
+
         // Update recall counter for satisfaction/transparency nudges (Issue #87)
         let nudgeContext = "";
         try {
@@ -1417,9 +1531,9 @@ export function registerHooks(api: any, config: PalaiaPluginConfig): void {
 
         // Track recall in session-isolated turn state for emoji reactions
         // Only flag recall as meaningful if at least one result scores above threshold
-        const RECALL_RELEVANCE_THRESHOLD = 0.7;
-        const hasRelevantRecall = entries.some(
-          (e) => typeof e.score === "number" && e.score >= RECALL_RELEVANCE_THRESHOLD,
+        // List-fallback never triggers brain emoji (not query-relevant)
+        const hasRelevantRecall = !isListFallback && entries.some(
+          (e) => typeof e.score === "number" && e.score >= config.recallMinScore,
         );
         const sessionKey = resolveSessionKeyFromCtx(ctx);
         if (sessionKey && hasRelevantRecall) {
@@ -1450,7 +1564,7 @@ export function registerHooks(api: any, config: PalaiaPluginConfig): void {
             : undefined,
         };
       } catch (error) {
-        console.warn(`[palaia] Memory injection failed: ${error}`);
+        logger.warn(`[palaia] Memory injection failed: ${error}`);
       }
     });
   }
@@ -1528,7 +1642,10 @@ export function registerHooks(api: any, config: PalaiaPluginConfig): void {
             "--tags", tags.join(",") || "auto-capture",
           ];
 
-          const scope = sanitizeScope(config.captureScope || itemScope, config.captureScope || "team");
+          // Scope guardrail: config.captureScope overrides everything; otherwise max team (no public)
+          const scope = config.captureScope
+            ? sanitizeScope(config.captureScope, "team", true)
+            : sanitizeScope(itemScope, "team", false);
           args.push("--scope", scope);
 
           const project = config.captureProject || itemProject;
@@ -1553,16 +1670,32 @@ export function registerHooks(api: any, config: PalaiaPluginConfig): void {
               const effectiveProject = hintForProject?.project || r.project;
               const effectiveScope = hintForScope?.scope || r.scope;
 
+              // Project validation: reject unknown projects
+              let validatedProject = effectiveProject;
+              if (validatedProject && knownProjects.length > 0) {
+                const isKnown = knownProjects.some(
+                  (p) => p.name.toLowerCase() === validatedProject!.toLowerCase(),
+                );
+                if (!isKnown) {
+                  logger.info(`[palaia] Auto-capture: unknown project "${validatedProject}" ignored`);
+                  validatedProject = null;
+                }
+              }
+
+              // Always include auto-capture tag for GC identification
+              const tags = [...r.tags];
+              if (!tags.includes("auto-capture")) tags.push("auto-capture");
+
               const args = buildWriteArgs(
                 r.content,
                 r.type,
-                r.tags,
-                effectiveProject,
+                tags,
+                validatedProject,
                 effectiveScope,
               );
               await run(args, { ...opts, timeoutMs: 10_000 });
-              console.log(
-                `[palaia] LLM auto-captured: type=${r.type}, significance=${r.significance}, tags=${r.tags.join(",")}, project=${effectiveProject || "none"}, scope=${effectiveScope || "team"}`
+              logger.info(
+                `[palaia] LLM auto-captured: type=${r.type}, significance=${r.significance}, tags=${tags.join(",")}, project=${validatedProject || "none"}, scope=${effectiveScope || "team"}`
               );
             }
           }
@@ -1586,7 +1719,7 @@ export function registerHooks(api: any, config: PalaiaPluginConfig): void {
             // captureModel is broken — try primary model as fallback
             if (!_captureModelFailoverWarned) {
               _captureModelFailoverWarned = true;
-              console.warn(`[palaia] WARNING: captureModel failed (${errStr}). Using primary model as fallback. Please update captureModel in your config.`);
+              logger.warn(`[palaia] WARNING: captureModel failed (${errStr}). Using primary model as fallback. Please update captureModel in your config.`);
             }
             try {
               // Retry without captureModel → resolveCaptureModel will use primary model
@@ -1597,19 +1730,19 @@ export function registerHooks(api: any, config: PalaiaPluginConfig): void {
               llmHandled = true;
             } catch (fallbackError) {
               if (!_llmImportFailureLogged) {
-                console.warn(`[palaia] LLM extraction failed (primary model fallback also failed): ${fallbackError}`);
+                logger.warn(`[palaia] LLM extraction failed (primary model fallback also failed): ${fallbackError}`);
                 _llmImportFailureLogged = true;
               }
             }
           } else {
             if (!_llmImportFailureLogged) {
-              console.warn(`[palaia] LLM extraction failed, using rule-based fallback: ${llmError}`);
+              logger.warn(`[palaia] LLM extraction failed, using rule-based fallback: ${llmError}`);
               _llmImportFailureLogged = true;
             }
           }
         }
 
-        // Rule-based fallback
+        // Rule-based fallback (max 1 per turn)
         if (!llmHandled) {
           let captureData: { tags: string[]; type: string; summary: string } | null = null;
 
@@ -1628,6 +1761,11 @@ export function registerHooks(api: any, config: PalaiaPluginConfig): void {
             captureData = { tags: ["auto-capture"], type: "memory", summary };
           }
 
+          // Always include auto-capture tag for GC identification
+          if (!captureData.tags.includes("auto-capture")) {
+            captureData.tags.push("auto-capture");
+          }
+
           const hintForProject = collectedHints.find((h) => h.project);
           const hintForScope = collectedHints.find((h) => h.scope);
 
@@ -1640,7 +1778,7 @@ export function registerHooks(api: any, config: PalaiaPluginConfig): void {
           );
 
           await run(args, { ...opts, timeoutMs: 10_000 });
-          console.log(
+          logger.info(
             `[palaia] Rule-based auto-captured: type=${captureData.type}, tags=${captureData.tags.join(",")}`
           );
         }
@@ -1652,7 +1790,7 @@ export function registerHooks(api: any, config: PalaiaPluginConfig): void {
         } else {
         }
       } catch (error) {
-        console.warn(`[palaia] Auto-capture failed: ${error}`);
+        logger.warn(`[palaia] Auto-capture failed: ${error}`);
       }
 
       // ── Emoji Reactions (Issue #87) ──────────────────────────
@@ -1684,7 +1822,7 @@ export function registerHooks(api: any, config: PalaiaPluginConfig): void {
             }
           }
         } catch (reactionError) {
-          console.warn(`[palaia] Reaction sending failed: ${reactionError}`);
+          logger.warn(`[palaia] Reaction sending failed: ${reactionError}`);
         } finally {
           // Always clean up turn state
           deleteTurnState(sessionKey);
@@ -1714,7 +1852,7 @@ export function registerHooks(api: any, config: PalaiaPluginConfig): void {
           }
         }
       } catch (err) {
-        console.warn(`[palaia] Recall reaction failed: ${err}`);
+        logger.warn(`[palaia] Recall reaction failed: ${err}`);
       } finally {
         deleteTurnState(sessionKey);
       }
@@ -1727,10 +1865,10 @@ export function registerHooks(api: any, config: PalaiaPluginConfig): void {
     start: async () => {
       const result = await recover(opts);
       if (result.replayed > 0) {
-        console.log(`[palaia] WAL recovery: replayed ${result.replayed} entries`);
+        logger.info(`[palaia] WAL recovery: replayed ${result.replayed} entries`);
       }
       if (result.errors > 0) {
-        console.warn(`[palaia] WAL recovery completed with ${result.errors} error(s)`);
+        logger.warn(`[palaia] WAL recovery completed with ${result.errors} error(s)`);
       }
     },
   });

package/src/tools.ts

@@ -7,7 +7,7 @@
  */
 
 import { Type } from "@sinclair/typebox";
-import { runJson, type RunnerOpts } from "./runner.js";
+import { run, runJson, type RunnerOpts } from "./runner.js";
 import type { PalaiaPluginConfig } from "./config.js";
 import { sanitizeScope, isValidScope } from "./hooks.js";
 
@@ -217,6 +217,12 @@ export function registerTools(api: any, config: PalaiaPluginConfig): void {
             description: "Title for the entry",
           })
         ),
+        force: Type.Optional(
+          Type.Boolean({
+            description: "Skip duplicate check and write anyway",
+            default: false,
+          })
+        ),
       }),
       async execute(
         _id: string,
@@ -227,8 +233,47 @@ export function registerTools(api: any, config: PalaiaPluginConfig): void {
           type?: string;
           project?: string;
           title?: string;
+          force?: boolean;
         }
       ) {
+        // Duplicate guard: check for similar recent entries before writing
+        if (!params.force) {
+          try {
+            const dupCheckResult = await runJson<QueryResult>(
+              ["query", params.content, "--limit", "5"],
+              { ...opts, timeoutMs: 2000 },
+            );
+            if (dupCheckResult && Array.isArray(dupCheckResult.results)) {
+              const now = Date.now();
+              const oneDayMs = 24 * 60 * 60 * 1000;
+              for (const r of dupCheckResult.results) {
+                if (r.score > 0.8) {
+                  // Check if created in last 24h — use any available date field
+                  const meta = r as any;
+                  const createdStr = meta.created_at || meta.createdAt || meta.date || "";
+                  if (createdStr) {
+                    const createdTime = new Date(createdStr).getTime();
+                    if (!isNaN(createdTime) && (now - createdTime) < oneDayMs) {
+                      const title = r.title || (r.content || r.body || "").slice(0, 60);
+                      const dateStr = new Date(createdTime).toISOString().split("T")[0];
+                      return {
+                        content: [
+                          {
+                            type: "text" as const,
+                            text: `Similar entry already exists (score: ${r.score.toFixed(2)}, created: ${dateStr}): '${title}'. Use palaia edit ${r.id} to update, or confirm with --force to write anyway.`,
+                          },
+                        ],
+                      };
+                    }
+                  }
+                }
+              }
+            }
+          } catch {
+            // Duplicate check timed out or failed — proceed with write
+          }
+        }
+
         const args: string[] = ["write", params.content];
         if (params.scope) {
           if (!isValidScope(params.scope)) {