@mingxy/cerebro 1.11.15 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mingxy/cerebro",
-  "version": "1.11.15",
+  "version": "1.12.0",
   "description": "Cerebro persistent memory plugin for OpenCode — auto-recall, auto-capture, 9 memory tools with clustering",
   "type": "module",
   "main": "src/index.ts",

package/schema.json

@@ -96,6 +96,61 @@
           "default": 10,
           "minimum": 1,
           "maximum": 50
+        },
+        "fetchMultiplier": {
+          "type": "number",
+          "description": "Search breadth multiplier: fetch_limit = max_results * N",
+          "default": 3,
+          "minimum": 1,
+          "maximum": 10
+        },
+        "topkCapMultiplier": {
+          "type": "number",
+          "description": "Candidate cap multiplier: topk_cap = max_results * N",
+          "default": 2,
+          "minimum": 1,
+          "maximum": 10
+        },
+        "mmrJaccardThreshold": {
+          "type": "number",
+          "description": "Jaccard similarity threshold for MMR diversity penalty",
+          "default": 0.85,
+          "minimum": 0.0,
+          "maximum": 1.0
+        },
+        "mmrPenaltyFactor": {
+          "type": "number",
+          "description": "Score penalty factor for similar memories in MMR diversity",
+          "default": 0.5,
+          "minimum": 0.0,
+          "maximum": 1.0
+        },
+        "phase2Multiplier": {
+          "type": "number",
+          "description": "Phase2 global fallback search multiplier",
+          "default": 2,
+          "minimum": 1,
+          "maximum": 10
+        },
+        "llmMaxEval": {
+          "type": "number",
+          "description": "Maximum candidates sent to LLM for relevance evaluation",
+          "default": 15,
+          "minimum": 1,
+          "maximum": 50
+        },
+        "refineStrategy": {
+          "type": "string",
+          "description": "LLM refinement strategy: strict (high only), balanced (high+medium), loose (keep all)",
+          "enum": ["strict", "balanced", "loose"],
+          "default": "balanced"
+        },
+        "refineMediumChars": {
+          "type": "number",
+          "description": "Character limit for medium-relevance content truncation",
+          "default": 200,
+          "minimum": 50,
+          "maximum": 2000
         }
       },
       "additionalProperties": false

package/src/client.ts

@@ -55,6 +55,14 @@ export interface ClusteredRecallResult {
   standalone_memories: MemoryDto[];
 }
 
+export interface DiscardedItem {
+  memory_id: string;
+  content: string;
+  score: number;
+  refine_relevance?: string;
+  refine_reasoning?: string;
+}
+
 export interface ShouldRecallResponse {
   should_recall: boolean;
   query?: string;
@@ -62,8 +70,8 @@ export interface ShouldRecallResponse {
   similarity_score?: number;
   confidence?: number;
   memories?: SearchResult[];
+  discarded?: DiscardedItem[];
   clustered?: ClusteredRecallResult;
-  event_id?: string;
 }
 
 export interface MemoryRelation {
@@ -332,6 +340,16 @@ export class CerebroClient {
     max_results?: number,
     project_tags?: string[],
     conversation_context?: string[],
+    recall_overrides?: {
+      fetch_multiplier?: number;
+      topk_cap_multiplier?: number;
+      mmr_jaccard_threshold?: number;
+      mmr_penalty_factor?: number;
+      phase2_multiplier?: number;
+      llm_max_eval?: number;
+      refine_strategy?: string;
+      refine_medium_chars?: number;
+    },
   ): Promise<ShouldRecallResponse | null> {
     const res = await this.post<ShouldRecallResponse>("/v1/should-recall", {
       query_text,
@@ -341,6 +359,7 @@ export class CerebroClient {
       max_results,
       project_tags,
       conversation_context,
+      ...recall_overrides,
     }, 20_000);
     return res;
   }
@@ -348,15 +367,42 @@ export class CerebroClient {
   async updateProfileInjected(
     event_id: string,
     profile_injected: boolean,
+    profile_content?: string,
   ): Promise<unknown | null> {
+    const body: Record<string, unknown> = { profile_injected };
+    if (profile_content !== undefined) {
+      body.profile_content = profile_content;
+    }
     const res = await this.patch(
       `/v1/recall-events/${event_id}/profile-injected`,
-      { profile_injected },
+      body,
       10_000,
     );
     return res;
   }
 
+  async createRecallEvent(params: {
+    session_id: string;
+    recall_type?: string;
+    query_text: string;
+    max_score: number;
+    llm_confidence: number;
+    profile_injected: boolean;
+    kept_count: number;
+    discarded_count: number;
+    injected_count: number;
+    profile_content?: string;
+    items?: Array<{
+      memory_id: string;
+      score: number;
+      refine_relevance?: string;
+      refine_reasoning?: string;
+      is_kept: boolean;
+    }>;
+  }): Promise<{ ok: boolean; event_id?: string } | null> {
+    return this.post("/v1/recall-events", params, 10_000);
+  }
+
   async sessionIngest(
     messages: Array<{ role: string; content: string }>,
     sessionId?: string,

package/src/config.ts

@@ -22,6 +22,14 @@ export interface OmemPluginConfig {
   recall: {
     similarityThreshold: number;
     maxRecallResults: number;
+    fetchMultiplier: number;
+    topkCapMultiplier: number;
+    mmrJaccardThreshold: number;
+    mmrPenaltyFactor: number;
+    phase2Multiplier: number;
+    llmMaxEval: number;
+    refineStrategy: "strict" | "balanced" | "loose";
+    refineMediumChars: number;
   };
   logging: {
     logEnabled: boolean;
@@ -55,6 +63,14 @@ const DEFAULTS: OmemPluginConfig = {
   recall: {
     similarityThreshold: 0.4,
     maxRecallResults: 10,
+    fetchMultiplier: 3,
+    topkCapMultiplier: 2,
+    mmrJaccardThreshold: 0.85,
+    mmrPenaltyFactor: 0.5,
+    phase2Multiplier: 2,
+    llmMaxEval: 15,
+    refineStrategy: "balanced",
+    refineMediumChars: 200,
   },
   logging: {
     logEnabled: true,
@@ -111,6 +127,14 @@ function migrateFlatToNested(flat: FlatConfig): OmemPluginConfig {
     recall: {
       similarityThreshold: flat.similarityThreshold ?? DEFAULTS.recall.similarityThreshold,
       maxRecallResults: flat.maxRecallResults ?? DEFAULTS.recall.maxRecallResults,
+      fetchMultiplier: DEFAULTS.recall.fetchMultiplier,
+      topkCapMultiplier: DEFAULTS.recall.topkCapMultiplier,
+      mmrJaccardThreshold: DEFAULTS.recall.mmrJaccardThreshold,
+      mmrPenaltyFactor: DEFAULTS.recall.mmrPenaltyFactor,
+      phase2Multiplier: DEFAULTS.recall.phase2Multiplier,
+      llmMaxEval: DEFAULTS.recall.llmMaxEval,
+      refineStrategy: DEFAULTS.recall.refineStrategy,
+      refineMediumChars: DEFAULTS.recall.refineMediumChars,
     },
     logging: {
       logEnabled: flat.logEnabled ?? DEFAULTS.logging.logEnabled,

package/src/hooks.ts

@@ -299,6 +299,14 @@ function buildClusteredContextBlock(clustered: import("./client.js").ClusteredRe
 export function autoRecallHook(client: CerebroClient, containerTags: string[], tui: any, config: Partial<OmemPluginConfig> = {}, getAgentName?: () => string) {
   const similarityThreshold = config.recall?.similarityThreshold ?? 0.4;
   const maxRecallResults = config.recall?.maxRecallResults ?? 10;
+  const fetchMultiplier = config.recall?.fetchMultiplier ?? 3;
+  const topkCapMultiplier = config.recall?.topkCapMultiplier ?? 2;
+  const mmrJaccardThreshold = config.recall?.mmrJaccardThreshold ?? 0.85;
+  const mmrPenaltyFactor = config.recall?.mmrPenaltyFactor ?? 0.5;
+  const phase2Multiplier = config.recall?.phase2Multiplier ?? 2;
+  const llmMaxEval = config.recall?.llmMaxEval ?? 15;
+  const refineStrategy = config.recall?.refineStrategy ?? "balanced";
+  const refineMediumChars = config.recall?.refineMediumChars ?? 200;
   const maxContentLength = Math.max(MIN_CONTENT_LENGTH, config.content?.maxContentLength ?? 500);
   const maxContentChars = Math.max(MIN_CONTENT_CHARS, config.content?.maxContentChars ?? 30000);
   const toastDelayMs = config.ui?.toastDelayMs ?? 7000;
@@ -348,13 +356,23 @@ export function autoRecallHook(client: CerebroClient, containerTags: string[], t
         similarityThreshold, maxRecallResults,
         projectTags.length > 0 ? projectTags : undefined,
         conversationContext && conversationContext.length > 0 ? conversationContext : undefined,
+        {
+          fetch_multiplier: fetchMultiplier,
+          topk_cap_multiplier: topkCapMultiplier,
+          mmr_jaccard_threshold: mmrJaccardThreshold,
+          mmr_penalty_factor: mmrPenaltyFactor,
+          phase2_multiplier: phase2Multiplier,
+          llm_max_eval: llmMaxEval,
+          refine_strategy: refineStrategy,
+          refine_medium_chars: refineMediumChars,
+        },
       );
 
       if (!shouldRecallRes) {
         showToast(tui, "🧠 Cerebro Service Unavailable", "Unable to reach memory API · check connection", "error", toastDelayMs);
         return;
       }
-      logDebug("autoRecallHook shouldRecall result", { shouldRecall: shouldRecallRes.should_recall, confidence: shouldRecallRes.confidence, memCount: shouldRecallRes.memories?.length ?? 0, clustered: !!shouldRecallRes.clustered });
+      logDebug("autoRecallHook shouldRecall result", { shouldRecall: shouldRecallRes.should_recall, confidence: shouldRecallRes.confidence, memCount: shouldRecallRes.memories?.length ?? 0, discardedCount: shouldRecallRes.discarded?.length ?? 0, clustered: !!shouldRecallRes.clustered });
 
       const profile = await client.getProfile();
       let profileInjected = false;
@@ -398,10 +416,56 @@ export function autoRecallHook(client: CerebroClient, containerTags: string[], t
         }
       }
 
-      if (!shouldRecallRes.should_recall) {
-        if (profileInjected && shouldRecallRes?.event_id) {
-          await client.updateProfileInjected(shouldRecallRes.event_id, true).catch(() => {});
+      const storedMemoryIds = shouldRecallRes.memories?.map((r) => r.memory.id) ?? [];
+      const storedDiscardedIds = shouldRecallRes.discarded?.map((d) => d.memory_id) ?? [];
+      const maxScore = storedMemoryIds.length > 0
+        ? Math.max(...(shouldRecallRes.memories?.map((r) => r.score) ?? [0]))
+        : 0;
+
+      const createEventAndReturn = async (
+        injectedCount: number,
+        keptCount: number,
+        discardedCount: number,
+      ): Promise<string | undefined> => {
+        try {
+          const items = [
+            ...(shouldRecallRes.memories?.map((r) => ({
+              memory_id: r.memory.id,
+              score: r.score,
+              refine_relevance: r.refine_relevance,
+              refine_reasoning: r.refine_reasoning,
+              is_kept: true,
+            })) ?? []),
+            ...(shouldRecallRes.discarded?.map((d) => ({
+              memory_id: d.memory_id,
+              score: d.score,
+              refine_relevance: d.refine_relevance,
+              refine_reasoning: d.refine_reasoning,
+              is_kept: false,
+            })) ?? []),
+          ];
+          const result = await client.createRecallEvent({
+            session_id: input.sessionID!,
+            recall_type: "auto",
+            query_text,
+            max_score: maxScore,
+            llm_confidence: shouldRecallRes.confidence ?? 0,
+            profile_injected: profileInjected,
+            kept_count: keptCount,
+            discarded_count: discardedCount,
+            injected_count: injectedCount,
+            profile_content: profileInjected && profileBlock ? profileBlock : undefined,
+            items: items.length > 0 ? items : undefined,
+          });
+          return result?.event_id;
+        } catch (e) {
+          logErr("autoRecallHook createRecallEvent failed", { error: String(e) });
+          return undefined;
         }
+      };
+
+      if (!shouldRecallRes.should_recall) {
+        await createEventAndReturn(0, 0, storedDiscardedIds.length);
         if (profileInjected && isFirstInjection) {
           showToast(tui, "👨 Profile Injected", `${profileCountText} · no memory recall needed`, "success", toastDelayMs);
         }
@@ -415,9 +479,7 @@ export function autoRecallHook(client: CerebroClient, containerTags: string[], t
       const newResults = results.filter((r) => !existingIds.has(r.memory.id));
       logDebug("autoRecallHook dedup", { totalResults: results.length, existingCount: existingIds.size, newCount: newResults.length });
       if (newResults.length === 0) {
-        if (profileInjected && shouldRecallRes?.event_id) {
-          await client.updateProfileInjected(shouldRecallRes.event_id, true).catch(() => {});
-        }
+        await createEventAndReturn(0, storedMemoryIds.length, storedDiscardedIds.length);
         if (profileInjected && isFirstInjection) {
           showToast(tui, "👨 Profile Injected", `${profileCountText} · all memories already injected`, "success", toastDelayMs);
         }
@@ -453,9 +515,7 @@ export function autoRecallHook(client: CerebroClient, containerTags: string[], t
       injectedMemoryIds.set(input.sessionID, new Set([...existingIds, ...newIds]));
       logDebug("autoRecallHook injection complete", { newIds: newIds.length, clustered: !!clustered });
 
-      if (profileInjected && shouldRecallRes?.event_id) {
-        await client.updateProfileInjected(shouldRecallRes.event_id, true).catch(() => {});
-      }
+      await createEventAndReturn(newResults.length, storedMemoryIds.length, storedDiscardedIds.length);
 
       const memDynamic = newResults.filter((r) => r.memory.memory_type === "fact" || r.memory.memory_type === "event").length;
       const memStatic = newResults.filter((r) => r.memory.memory_type === "pinned" || r.memory.memory_type === "preference").length;