fix: gate cortex memory injection to real user turns

README.md

@@ -70,6 +70,12 @@ cd cortex && npm install --omit=dev
 | `autoRecall` | `boolean` | `true` | Retrieve relevant memories before each agent turn |
 | `autoCapture` | `boolean` | `true` | Extract and store memories after each agent turn |
 | `shadowMode` | `boolean` | `false` | Dry-run mode — runs extraction but skips storage |
+| `gbrainShadowEnabled` | `boolean` | `false` | Enable observe-only GBrain shadow v1 scaffolding |
+| `gbrainShadowCapture` | `boolean` | `true` | Log what GBrain shadow would process on end-of-turn capture |
+| `gbrainShadowRecall` | `boolean` | `true` | Log what GBrain shadow would contribute on recall |
+| `gbrainShadowLogEnabled` | `boolean` | `true` | Persist structured timestamped shadow logs under `dist/logs/` |
+| `gbrainShadowProviderBaseUrl` | `string` | `https://api.minimax.io/v1` | Base URL for MiniMax full-model observe-only path |
+| `gbrainShadowModel` | `string` | `MiniMax-M2.7` | Model name used in GBrain shadow log metadata |
 | `retrievalBudget` | `number` | `2000` | Max token budget for retrieved memories |
 | `maxInjectionChars` | `number` | `8000` | Max characters injected into agent context |
 | `retrievalMode` | `string` | `fast` | Retrieval mode: `auto`, `fast`, or `thorough` |
@@ -126,6 +132,10 @@ Cortex operates two invisible loops around every agent conversation:
 
 Memories include metadata (dates, salience, categories) and are deduplicated, contradiction-checked, and relevance-scored at retrieval time.
 
+## GBrain Shadow v1
+
+This plugin now includes a narrow, safe GBrain shadow scaffold. When `gbrainShadowEnabled` is on, Cortex keeps authoritative recall/capture behavior unchanged and only writes observe-only JSONL log entries describing what a GBrain layer would have seen or contributed. Logs are timestamped, capped, and include MiniMax provider metadata so you can wire a full-model path later without taking over the hot path.
+
 ## Benchmarks
 
 > 🚧 **Benchmarks coming soon.** We're running evaluations against [LoCoMo](https://github.com/snap-research/locomo), [AMB](https://github.com/microsoft/AMB), and [MSC](https://github.com/facebookresearch/ParlAI/tree/main/projects/msc) — the standard long-term memory benchmarks for conversational AI.

dist/__tests__/gbrain-shadow.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=gbrain-shadow.test.d.ts.map

dist/__tests__/turn-gating.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=turn-gating.test.d.ts.map

dist/index.d.ts

@@ -30,6 +30,15 @@ interface EvaMemoryConfig {
     autoRecall: boolean;
     autoCapture: boolean;
     shadowMode: boolean;
+    gbrainShadowEnabled: boolean;
+    gbrainShadowCapture: boolean;
+    gbrainShadowRecall: boolean;
+    gbrainShadowLogEnabled: boolean;
+    gbrainShadowMaxPromptChars: number;
+    gbrainShadowLogMaxEntries: number;
+    gbrainShadowProviderBaseUrl: string;
+    gbrainShadowModel: string;
+    gbrainShadowApiKey: string;
     retrievalBudget: number;
     maxInjectionChars: number;
     maxInjectedMemories: number;
@@ -72,7 +81,52 @@ interface ProcessedItem {
     conflictWithId?: string;
     relationHint?: string;
 }
+interface GBrainShadowEvent {
+    schemaVersion: "gbrain-shadow-v1";
+    ts: string;
+    phase: "recall" | "capture";
+    sessionId?: string;
+    turnId?: string;
+    mode: "observe";
+    provider: {
+        baseUrl: string;
+        model: string;
+        liveCall: boolean;
+    };
+    gbrainRetrieval?: {
+        attempted: boolean;
+        ok: boolean;
+        query?: string;
+        hits?: Array<{
+            slug: string;
+            preview: string;
+        }>;
+        summary?: string;
+    };
+    promptPreview?: string;
+    conversationPreview?: Array<{
+        role: string;
+        content: string;
+    }>;
+    status: "skipped" | "simulated" | "disabled";
+    reason?: string;
+    note: string;
+    source: "gbrain-shadow-scaffold";
+    divergenceFromAuthoritative?: string;
+}
 declare function parseConfig(raw: unknown): EvaMemoryConfig;
+export declare function isMemoryRelevant(prompt: string): boolean;
+type HookRunKind = "main" | "subagent" | "cron" | "isolated" | "hook" | "unknown";
+type HookLaneContext = {
+    runKind?: HookRunKind;
+    isHeartbeat?: boolean;
+    sessionKey?: string;
+    trigger?: string;
+};
+export declare function classifyTurnForMemory(prompt: string | undefined, messages: unknown[] | undefined, ctx?: HookLaneContext): {
+    allow: boolean;
+    reason: string;
+};
 /** Session risk mode for dynamic threshold selection. */
 type InjectionMode = "critical" | "technical" | "personal";
 /** Parse raw plugin config into a validated EvaMemoryConfig object. */
@@ -98,6 +152,38 @@ export declare function detectInjectionMode(promptText: string): InjectionMode;
 export declare function screenInjectionCandidates(items: RetrievedItem[], promptText: string, cfg: Pick<EvaMemoryConfig, "injectionHardFloor" | "injectionCriticalThreshold" | "injectionTechnicalThreshold" | "injectionPersonalThreshold">, log?: (msg: string) => void): RetrievedItem[];
 export declare function preprocessClaims(items: RetrievedItem[], options: Pick<EvaMemoryConfig, "showConflicts" | "showRelations" | "dedup">): ProcessedItem[];
 export declare function formatMemoryContext(items: RetrievedItem[], maxChars: number, totalCount?: number, maxCount?: number, minScore?: number, options?: Pick<EvaMemoryConfig, "injectionFormat" | "showConflicts" | "showRelations" | "dedup">): string;
+export declare function getGBrainShadowLogPath(ownerId: string): string;
+export declare function createGBrainShadowEvent(params: {
+    phase: "recall" | "capture";
+    sessionId?: string;
+    turnId?: string;
+    providerBaseUrl: string;
+    model: string;
+    prompt?: string;
+    conversation?: Array<{
+        role: string;
+        content: string;
+    }>;
+    maxPromptChars: number;
+    status: "skipped" | "simulated" | "disabled";
+    reason?: string;
+    note: string;
+    divergenceFromAuthoritative?: string;
+    gbrainRetrieval?: {
+        attempted: boolean;
+        ok: boolean;
+        query?: string;
+        hits?: Array<{
+            slug: string;
+            preview: string;
+        }>;
+        summary?: string;
+    };
+}): GBrainShadowEvent;
+export declare function extractMessages(rawMessages: unknown[]): Array<{
+    role: string;
+    content: string;
+}>;
 declare const cortexPlugin: {
     id: string;
     name: string;
@@ -128,6 +214,42 @@ declare const cortexPlugin: {
                     type: string;
                     description: string;
                 };
+                gbrainShadowEnabled: {
+                    type: string;
+                    description: string;
+                };
+                gbrainShadowCapture: {
+                    type: string;
+                    description: string;
+                };
+                gbrainShadowRecall: {
+                    type: string;
+                    description: string;
+                };
+                gbrainShadowLogEnabled: {
+                    type: string;
+                    description: string;
+                };
+                gbrainShadowMaxPromptChars: {
+                    type: string;
+                    description: string;
+                };
+                gbrainShadowLogMaxEntries: {
+                    type: string;
+                    description: string;
+                };
+                gbrainShadowProviderBaseUrl: {
+                    type: string;
+                    description: string;
+                };
+                gbrainShadowModel: {
+                    type: string;
+                    description: string;
+                };
+                gbrainShadowApiKey: {
+                    type: string;
+                    description: string;
+                };
                 retrievalBudget: {
                     type: string;
                 };