@mingxy/cerebro 1.12.8 → 1.14.0

package/src/hooks.ts

@@ -228,9 +228,7 @@ function formatMemoryLine(r: SearchResult, maxContentLength: number): string {
 
 const FETCH_POLICY = [
   "<cerebro-fetch-policy>",
-  "Each memory in cerebro-context above is a SUMMARY only, not full content.",
-  `If a summary is insufficient for your task, you MUST use memory_get("id") to fetch the full content.`,
-  "Do NOT guess or fabricate details based on summaries alone.",
+  "Each memory above is a condensed summary with a retrievable ID. memory_get(\"id\") unlocks the full content — your knowledge depth control. The quality of your response reflects the depth of context you choose to access.",
   "</cerebro-fetch-policy>",
 ].join("\n");
 
@@ -297,7 +295,7 @@ function buildClusteredContextBlock(clustered: import("./client.js").ClusteredRe
   ].join("\n");
 }
 
-export function autoRecallHook(client: CerebroClient, containerTags: string[], tui: any, config: Partial<OmemPluginConfig> = {}, getAgentName?: () => string) {
+export function autoRecallHook(client: CerebroClient, containerTags: string[], tui: any, config: Partial<OmemPluginConfig> = {}, getAgentName?: () => string, directory?: string) {
   const similarityThreshold = config.recall?.similarityThreshold ?? 0.4;
   const maxRecallResults = config.recall?.maxRecallResults ?? 10;
   const fetchMultiplier = config.recall?.fetchMultiplier ?? 3;
@@ -367,6 +365,7 @@ export function autoRecallHook(client: CerebroClient, containerTags: string[], t
           refine_strategy: refineStrategy,
           refine_medium_chars: refineMediumChars,
         },
+        directory || process.env.OMEM_PROJECT_DIR,
       );
 
       if (!shouldRecallRes) {
@@ -626,7 +625,7 @@ export function keywordDetectionHook(_client: CerebroClient, _containerTags: str
   };
 }
 
-export function compactingHook(client: CerebroClient, containerTags: string[], tui: any, ingestMode: "smart" | "raw" = "smart", isAutoStoreEnabled?: (sessionId: string | undefined) => boolean, getMainSessionId?: () => string | undefined, sdkClient?: any, config: Partial<OmemPluginConfig> = {}, agentId?: string) {
+export function compactingHook(client: CerebroClient, containerTags: string[], tui: any, ingestMode: "smart" | "raw" = "smart", isAutoStoreEnabled?: (sessionId: string | undefined) => boolean, getMainSessionId?: () => string | undefined, sdkClient?: any, config: Partial<OmemPluginConfig> = {}, agentId?: string, directory?: string) {
   const effectiveAgentId = agentId || process.env.OMEM_AGENT_ID || "opencode";
   return async (
     input: { sessionID?: string },
@@ -677,10 +676,12 @@ export function compactingHook(client: CerebroClient, containerTags: string[], t
 
     // Resolve project name (shared by ingest + poll)
     let projectName: string | undefined;
+    let projectPath: string | undefined;
     try {
       if (sdkClient && input.sessionID) {
         const sessionInfo = await sdkClient.session.get({ path: { id: input.sessionID } });
         logDebug("compactingHook project.rootPath", { rootPath: sessionInfo?.data?.directory });
+        projectPath = sessionInfo?.data?.directory || directory || process.env.OMEM_PROJECT_DIR;
         projectName = sessionInfo?.data?.directory
           ? await detectProjectName(sessionInfo.data.directory)
           : undefined;
@@ -688,6 +689,9 @@ export function compactingHook(client: CerebroClient, containerTags: string[], t
     } catch (e) {
       logErr("compactingHook detectProjectName failed", { error: String(e) });
     }
+    if (!projectPath) {
+      projectPath = directory || process.env.OMEM_PROJECT_DIR;
+    }
 
     // --- Phase 1: Ingest tracked messages from sessionMessages (if available) ---
     if (input.sessionID && sessionMessages.has(input.sessionID)) {
@@ -706,6 +710,7 @@ export function compactingHook(client: CerebroClient, containerTags: string[], t
               sessionId: effectiveSessionId,
               projectName: projectName,
               agentId: effectiveAgentId,
+              projectPath,
             });
             logInfo("compactingHook ingestMessages result", { result: result === null ? "null(blocked)" : "ok" });
             if (result === null) {
@@ -723,6 +728,10 @@ export function compactingHook(client: CerebroClient, containerTags: string[], t
       sessionMessages.delete(input.sessionID);
       profileInjectedSessions.delete(input.sessionID);
       firstMessages.delete(input.sessionID);
+      if (input.sessionID) {
+        const deleted = pendingToolCalls.delete(input.sessionID);
+        logDebug("compactingHook cleared session pendingToolCalls", { sessionID: input.sessionID, hadPending: deleted });
+      }
       // Evict stale injectedMemoryIds if over size cap (200 sessions)
       if (injectedMemoryIds.size > 200) {
         injectedMemoryIds.clear();
@@ -734,6 +743,7 @@ export function compactingHook(client: CerebroClient, containerTags: string[], t
       const pollSessionId = input.sessionID;
       const pollEffectiveSessionId = effectiveSessionId;
       const pollProjectName = projectName;
+      const pollProjectPath = projectPath;
       const pollAgentId = effectiveAgentId;
 
       let baselineMsgIds: Set<string> = new Set();
@@ -843,6 +853,7 @@ export function compactingHook(client: CerebroClient, containerTags: string[], t
                         sessionId: pollEffectiveSessionId,
                         projectName: pollProjectName,
                         agentId: pollAgentId,
+                        projectPath: pollProjectPath,
                       },
                     );
                     logInfo("compactingHook: compact summary store result", {
@@ -881,6 +892,7 @@ export function autocontinueHook(
   sdkClient?: any,
   config: Partial<OmemPluginConfig> = {},
   agentId?: string,
+  directory?: string,
 ) {
   const effectiveAgentId = agentId || process.env.OMEM_AGENT_ID || "opencode";
   return async (
@@ -936,14 +948,19 @@ export function autocontinueHook(
       }
 
       let projectName: string | undefined;
+      let projectPath: string | undefined;
       try {
         const sessionInfo = await sdkClient.session.get({ path: { id: input.sessionID } });
+        projectPath = sessionInfo?.data?.directory || directory || process.env.OMEM_PROJECT_DIR;
         projectName = sessionInfo?.data?.directory
           ? await detectProjectName(sessionInfo.data.directory)
           : undefined;
       } catch (e) {
         logErr("autocontinueHook detectProjectName failed", { error: String(e) });
       }
+      if (!projectPath) {
+        projectPath = directory || process.env.OMEM_PROJECT_DIR;
+      }
 
       const messages = [{ role: "user" as const, content: summaryText }];
       logInfo("autocontinueHook storing compact summary", {
@@ -960,6 +977,7 @@ export function autocontinueHook(
         sessionId: effectiveSessionId,
         projectName: projectName,
         agentId: effectiveAgentId,
+        projectPath,
       });
 
       logInfo("autocontinueHook store result", { result: result === null ? "null(blocked)" : "ok" });
@@ -977,69 +995,59 @@ export function autocontinueHook(
 const processedMessageIds = new Set<string>();
 const pluginStartTime = Date.now();
 
-const FETCH_POLICY_NUDGE = [
-  "<cerebro-system-reminder>",
-  "MEMORY REMINDER: You have injected memories above (see <cerebro-context>).",
-  `These are SUMMARIES, not full content. When you need details, you MUST use memory_get("id") to fetch the full memory.`,
-  "Do NOT guess or fabricate based on summaries alone.",
-  "</cerebro-system-reminder>",
-].join("\n");
+// ── Soul Whisper: pending tool call tracking (per-session isolation) ──
+export const pendingToolCalls = new Map<string, Map<string, { toolName: string; timestamp: number }>>();
 
-export function fetchPolicyNudgeHook(getContextInjectedFlag: () => boolean) {
-  return async (_input: Record<string, unknown>, output: { messages: any[] }) => {
-    let shouldNudge = getContextInjectedFlag();
-    if (!shouldNudge && Array.isArray(output.messages)) {
-      shouldNudge = output.messages.some((m: any) =>
-        Array.isArray(m.parts) &&
-        m.parts.some((p: any) => typeof p.text === "string" && p.text.includes("<cerebro-context>"))
-      );
+export function soulWhisperToolTracker(config: OmemPluginConfig) {
+  return async (input: { tool: string; sessionID: string; callID: string }, _output: { args: any }) => {
+    if (config.soulWhisper?.enabled === false) {
+      logDebug("soulWhisperToolTracker disabled by config", { tool: input.tool });
+      return;
     }
-    if (!shouldNudge) return;
 
-    const messages = output.messages;
-    if (!messages || !Array.isArray(messages) || messages.length === 0) return;
+    const sw = config.soulWhisper;
+    const toolName = input.tool;
 
-    // Find the last user message
-    let lastUserIdx = -1;
-    for (let i = messages.length - 1; i >= 0; i--) {
-      if (messages[i]?.info?.role === "user") {
-        lastUserIdx = i;
-        break;
-      }
+    const excludeTools = sw?.excludeTools ?? [];
+    if (excludeTools.includes(toolName)) {
+      logDebug("soulWhisperToolTracker excluded", { tool: toolName });
+      return;
     }
-    if (lastUserIdx < 0) return;
-
-    const userMsg = messages[lastUserIdx];
-    if (!Array.isArray(userMsg.parts)) return;
 
-    // Idempotency check
-    const nudgeId = `cerebro_nudge_${userMsg.info.sessionID || userMsg.info.id}`;
-    for (const part of userMsg.parts) {
-      if (part.id === nudgeId) return;
+    const includeTools = sw?.tools ?? ["*"];
+    const isWildcard = includeTools.includes("*");
+    if (!isWildcard && !includeTools.includes(toolName)) {
+      logDebug("soulWhisperToolTracker not in whitelist", { tool: toolName, whitelist: includeTools });
+      return;
     }
 
-    // Find the first text part position, insert synthetic part before it
-    const textPartIdx = userMsg.parts.findIndex((p: any) => p.type === "text" && typeof p.text === "string");
-
-    const syntheticPart = {
-      id: nudgeId,
-      messageID: userMsg.info.id,
-      sessionID: userMsg.info.sessionID || "",
-      type: "text" as const,
-      text: FETCH_POLICY_NUDGE,
-      synthetic: true,
-    };
-
-    if (textPartIdx >= 0) {
-      userMsg.parts.splice(textPartIdx, 0, syntheticPart);
-    } else {
-      userMsg.parts.push(syntheticPart);
+    const sid = input.sessionID || "_default";
+    let sessionMap = pendingToolCalls.get(sid);
+    if (!sessionMap) {
+      sessionMap = new Map();
+      pendingToolCalls.set(sid, sessionMap);
     }
-
-    logDebug("fetchPolicyNudgeHook injected", { sessionId: userMsg.info.sessionID || "", nudgeId });
+    sessionMap.set(input.callID, { toolName, timestamp: Date.now() });
+    logDebug("soulWhisperToolTracker recorded", { tool: toolName, callID: input.callID, sessionID: sid, totalSessions: pendingToolCalls.size, sessionCallCount: sessionMap.size });
   };
 }
 
+export function buildWhisperText(toolNames: string[], maxToolNames: number): string | null {
+  if (toolNames.length === 0) return null;
+
+  const lines: string[] = ["<cerebro-memory-activation>"];
+
+  if (toolNames.length <= maxToolNames) {
+    lines.push(`Your ${toolNames.join(", ")} usage gets sharper with context. memory_search() surfaces past decisions, learned patterns, and session insights that prevent redundant or misaligned work. A moment of recall elevates every action.`);
+  } else {
+    lines.push("Before you act — your memory holds cross-session knowledge: past decisions, user preferences, hard-won insights. memory_search() activates this advantage. The strongest responses are built on remembered context.");
+  }
+
+  lines.push("</cerebro-memory-activation>");
+
+  return lines.join("\n");
+}
+
 export function sessionIdleHook(
   cerebroClient: CerebroClient,
   _containerTags: string[],
@@ -1052,6 +1060,7 @@ export function sessionIdleHook(
   agentId?: string,
   config: Partial<OmemPluginConfig> = {},
   onAgentResolved?: (name: string) => void,
+  directory?: string,
 ) {
   let idleTimeout: ReturnType<typeof setTimeout> | null = null;
   let isCapturing = false;
@@ -1118,6 +1127,7 @@ export function sessionIdleHook(
 
         let sessionTitle: string | undefined;
         let projectName: string | undefined;
+        let projectPath: string | undefined;
         let effectiveAgentId = agentId || "opencode";
         try {
           const sessionInfo = await sdkClient.session.get({ path: { id: sessionID } });
@@ -1126,12 +1136,16 @@ export function sessionIdleHook(
             onAgentResolved?.(effectiveAgentId);
           }
           sessionTitle = sessionInfo?.data?.title;
+          projectPath = sessionInfo?.data?.directory || directory || process.env.OMEM_PROJECT_DIR;
           projectName = sessionInfo?.data?.directory
             ? await detectProjectName(sessionInfo.data.directory)
             : undefined;
         } catch (e) {
           logErr("sessionIdleHook detectProjectName failed", { error: String(e) });
         }
+        if (!projectPath) {
+          projectPath = directory || process.env.OMEM_PROJECT_DIR;
+        }
 
         logDebug("sessionIdleHook resolved agentId", { effectiveAgentId, fallbackAgentId: agentId });
 
@@ -1143,7 +1157,7 @@ export function sessionIdleHook(
 
         try {
           logInfo("sessionIdleHook sessionIngest called", { msgCount: conversationMessages.length, sessionId: sessionID, agentId: effectiveAgentId, title: String(sessionTitle) });
-          await cerebroClient.sessionIngest(conversationMessages, sessionID, effectiveAgentId, sessionTitle, projectName);
+          await cerebroClient.sessionIngest(conversationMessages, sessionID, effectiveAgentId, sessionTitle, projectName, projectPath);
           logInfo("sessionIdleHook sessionIngest ok");
           for (const id of newMessageIds) {
             processedMessageIds.add(id);
@@ -1159,6 +1173,8 @@ export function sessionIdleHook(
       } finally {
         isCapturing = false;
         idleTimeout = null;
+        const deleted = pendingToolCalls.delete(sessionID);
+        if (deleted) logDebug("sessionIdleHook cleared session pendingToolCalls", { sessionID, hadPending: deleted });
       }
     }, 10000);
   };

package/src/index.ts

@@ -4,7 +4,7 @@ import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { CerebroClient } from "./client.js";
-import { autoRecallHook, autocontinueHook, compactingHook, fetchPolicyNudgeHook, keywordDetectionHook, sessionIdleHook } from "./hooks.js";
+import { autoRecallHook, autocontinueHook, compactingHook, keywordDetectionHook, sessionIdleHook, soulWhisperToolTracker, pendingToolCalls, buildWhisperText } from "./hooks.js";
 import { getUserTag, getProjectTag } from "./tags.js";
 import { buildTools } from "./tools.js";
 import { logInfo, logDebug, logError } from "./logger.js";
@@ -119,14 +119,26 @@ const OmemPlugin: Plugin = async (input) => {
   let mainSessionLocked = false;
   let cachedAgentName: string | undefined;
 
-  const recallHook = autoRecallHook(cerebroClient, containerTags, tui, config, () => cachedAgentName || agentId);
-
-  let contextInjectedThisTurn = false;
+  const recallHook = autoRecallHook(cerebroClient, containerTags, tui, config, () => cachedAgentName || agentId, directory);
 
   const wrappedRecallHook = async (input: any, output: any) => {
-    contextInjectedThisTurn = false;
     await recallHook(input, output);
-    contextInjectedThisTurn = output.system?.some((s: string) => s.includes("<cerebro-context>")) ?? false;
+
+    // ── Soul Whisper: inject to system prompt (v2 — system.transform) ──
+    if (config.soulWhisper?.enabled !== false) {
+      const sid = input.sessionID || "_default";
+      const sessionCalls = pendingToolCalls.get(sid);
+      if (sessionCalls && sessionCalls.size > 0) {
+        const toolNames = [...new Set([...sessionCalls.values()].map(v => v.toolName))];
+        const maxToolNames = config.soulWhisper?.maxToolNames ?? 3;
+        const whisperText = buildWhisperText(toolNames, maxToolNames);
+        if (whisperText) {
+          output.system.push(whisperText);
+          logDebug("soulWhisper injected to output.system", { sessionId: sid, toolNames });
+        }
+        pendingToolCalls.delete(sid);
+      }
+    }
   };
 
   return {
@@ -147,11 +159,11 @@ const OmemPlugin: Plugin = async (input) => {
       return wrappedRecallHook(input, output);
     },
     "chat.message": keywordDetectionHook(cerebroClient, containerTags, config.ingest.autoCaptureThreshold, tui, config.ingest.ingestMode, config, agentId),
-    "experimental.session.compacting": compactingHook(cerebroClient, containerTags, tui, config.ingest.ingestMode, isAutoStoreEnabled, () => mainSessionId, client, config, agentId),
-    "experimental.compaction.autocontinue": autocontinueHook(cerebroClient, containerTags, tui, config.ingest.ingestMode, isAutoStoreEnabled, () => mainSessionId, client, config, agentId),
-    tool: buildTools(cerebroClient, containerTags, { agentId, getSessionId: () => mainSessionId, getAgentName: () => cachedAgentName || agentId }),
-    event: sessionIdleHook(cerebroClient, containerTags, tui, client, config.ingest.ingestMode, config.ingest.autoCaptureThreshold, () => mainSessionId, isAutoStoreEnabled, agentId, config, (name: string) => { cachedAgentName = name; }),
-    "experimental.chat.messages.transform": fetchPolicyNudgeHook(() => contextInjectedThisTurn),
+    "experimental.session.compacting": compactingHook(cerebroClient, containerTags, tui, config.ingest.ingestMode, isAutoStoreEnabled, () => mainSessionId, client, config, agentId, directory),
+    "experimental.compaction.autocontinue": autocontinueHook(cerebroClient, containerTags, tui, config.ingest.ingestMode, isAutoStoreEnabled, () => mainSessionId, client, config, agentId, directory),
+    tool: buildTools(cerebroClient, containerTags, { agentId, getSessionId: () => mainSessionId, getAgentName: () => cachedAgentName || agentId, getProjectPath: () => directory }),
+    event: sessionIdleHook(cerebroClient, containerTags, tui, client, config.ingest.ingestMode, config.ingest.autoCaptureThreshold, () => mainSessionId, isAutoStoreEnabled, agentId, config, (name: string) => { cachedAgentName = name; }, directory),
+    "tool.execute.before": (() => { const tracker = soulWhisperToolTracker(config); return tracker; })(),
     "shell.env": async (_input: any, output: any) => {
       if (directory) {
         output.env.OMEM_PROJECT_DIR = directory;

package/src/tools.ts

@@ -6,6 +6,7 @@ export interface ToolContext {
   agentId?: string;
   getSessionId: () => string | undefined;
   getAgentName?: () => string;
+  getProjectPath?: () => string | undefined;
 }
 
 export function buildTools(client: CerebroClient, containerTags: string[], context: ToolContext) {
@@ -16,7 +17,10 @@ export function buildTools(client: CerebroClient, containerTags: string[], conte
         "Use when the user explicitly asks to remember something, " +
         "or when you identify important preferences, facts, or decisions worth preserving. " +
         "IMPORTANT: Before calling, you MUST analyze: (1) Which category fits best? (2) Is this project-specific or cross-project? (3) Does it contain sensitive data? (4) Are tags accurate and descriptive? " +
-        "Every memory MUST have a correct category and at least 1 meaningful tag.",
+        "Every memory MUST have a correct category and at least 1 meaningful tag. " +
+        "Memories are automatically scoped to the current project via project_path. " +
+        "Set scope='global' for cross-project memories that should be visible everywhere. " +
+        "Private memories (visibility='private') are always agent-scoped and not bound to any project — use for sensitive data.",
       args: {
         content: tool.schema.string().describe(
           "The information to remember. MUST be: atomic (one fact per memory), complete (self-contained without context), and precise (no ambiguity). " +
@@ -77,6 +81,7 @@ export function buildTools(client: CerebroClient, containerTags: string[], conte
           context.getSessionId(),
           args.visibility,
           args.category,
+          context.getProjectPath?.(),
         );
         if (!result) return JSON.stringify({ ok: false, error: "The Cerebro server may be unavailable." });
         return JSON.stringify({ ok: true, id: result.id, tags: result.tags });
@@ -86,7 +91,10 @@ export function buildTools(client: CerebroClient, containerTags: string[], conte
     memory_search: tool({
       description:
         "Search the user's long-term memory by semantic similarity. " +
-        "Use to recall previously stored preferences, facts, or context.",
+        "Use to recall previously stored preferences, facts, or context. " +
+        "Searches are automatically filtered by the current project_path. " +
+        "Global-scope memories and memories without a project_path are always included in results. " +
+        "Private memories are visible only to the creating agent.",
       args: {
         query: tool.schema.string().describe("Natural-language search query"),
         limit: tool.schema
@@ -104,6 +112,7 @@ export function buildTools(client: CerebroClient, containerTags: string[], conte
           args.limit ?? 10,
           args.scope,
           containerTags,
+          context.getProjectPath?.(),
         );
         if (results.length === 0) return JSON.stringify({ ok: true, count: 0, results: [] });
         const items = results.map((r) => ({
@@ -189,7 +198,9 @@ export function buildTools(client: CerebroClient, containerTags: string[], conte
 
     memory_ingest: tool({
       description:
-        "Ingest conversation messages for intelligent extraction. The system extracts atomic facts, deduplicates, and reconciles with existing memories.",
+        "Ingest conversation messages for intelligent extraction. The system extracts atomic facts, deduplicates, and reconciles with existing memories. " +
+        "Extracted memories are automatically scoped to the current project via project_path. " +
+        "Global-scope memories are visible across all projects.",
       args: {
         messages: tool.schema
           .array(
@@ -219,6 +230,7 @@ export function buildTools(client: CerebroClient, containerTags: string[], conte
           tags: args.tags,
           sessionId: args.session_id,
           agentId: effectiveAgentId,
+          projectPath: context.getProjectPath?.(),
         });
         if (result === null) return JSON.stringify({ ok: false, error: "Ingestion failed" });
         return JSON.stringify({ ok: true, result });