feat: add recallMode config (full/summary/off) for resume_context

Allow users to control how much context resume_context returns:
- full: existing compose behavior (stable + patterns + cases + guidance)
- summary: checkpoint-only, lightweight (suitable for dev scenarios)
- off: no recall, guides agent to use search_memory on demand

Priority resolution: per-call override > RECALLNEST_RECALL_MODE env > config.recallMode > default ("summary")

Motivation: auto-recall conflicts with compact in complex dev sessions,
wastes attention budget, and reduces signal-to-noise ratio per Anthropic/OpenAI
context engineering recommendations.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: AliceLJY

config.json.example

@@ -1,5 +1,6 @@
 {
   "dbPath": "~/.recallnest/data/lancedb",
+  "recallMode": "summary",
   "embedding": {
     "provider": "jina",
     "apiKey": "${JINA_API_KEY}",

src/__tests__/recall-mode.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { resolveRecallMode, type LocalMemoryConfig } from "../runtime-config.js";
+
+const baseConfig: LocalMemoryConfig = {
+  dbPath: "./data/lancedb",
+  embedding: {
+    provider: "jina",
+    apiKey: "test",
+    model: "test-model",
+  },
+  sources: {},
+};
+
+describe("resolveRecallMode", () => {
+  const originalEnv = process.env.RECALLNEST_RECALL_MODE;
+
+  beforeEach(() => {
+    delete process.env.RECALLNEST_RECALL_MODE;
+  });
+
+  afterEach(() => {
+    if (originalEnv === undefined) {
+      delete process.env.RECALLNEST_RECALL_MODE;
+    } else {
+      process.env.RECALLNEST_RECALL_MODE = originalEnv;
+    }
+  });
+
+  it("defaults to 'summary' when no config, no env, no override", () => {
+    delete process.env.RECALLNEST_RECALL_MODE;
+    expect(resolveRecallMode(baseConfig)).toBe("summary");
+  });
+
+  it("reads from config.recallMode", () => {
+    delete process.env.RECALLNEST_RECALL_MODE;
+    expect(resolveRecallMode({ ...baseConfig, recallMode: "full" })).toBe("full");
+    expect(resolveRecallMode({ ...baseConfig, recallMode: "off" })).toBe("off");
+  });
+
+  it("env var overrides config", () => {
+    process.env.RECALLNEST_RECALL_MODE = "off";
+    expect(resolveRecallMode({ ...baseConfig, recallMode: "full" })).toBe("off");
+  });
+
+  it("per-call override takes highest priority", () => {
+    process.env.RECALLNEST_RECALL_MODE = "off";
+    expect(resolveRecallMode({ ...baseConfig, recallMode: "full" }, "summary")).toBe("summary");
+  });
+
+  it("ignores invalid per-call override, falls back to env", () => {
+    process.env.RECALLNEST_RECALL_MODE = "full";
+    expect(resolveRecallMode(baseConfig, "invalid")).toBe("full");
+  });
+
+  it("ignores invalid env var, falls back to config", () => {
+    process.env.RECALLNEST_RECALL_MODE = "garbage";
+    expect(resolveRecallMode({ ...baseConfig, recallMode: "off" })).toBe("off");
+  });
+
+  it("ignores invalid env var and no config, falls back to default", () => {
+    process.env.RECALLNEST_RECALL_MODE = "garbage";
+    expect(resolveRecallMode(baseConfig)).toBe("summary");
+  });
+});

src/mcp-server.ts

@@ -72,7 +72,7 @@ import type { MemoryStore } from "./store.js";
 import { distillResults, formatExplainResults, formatSearchResults, selectBriefSeedResults, summarizeResults } from "./memory-output.js";
 import { archiveDirtyBriefAsset, assetSummaryLine, buildBriefAsset, buildPinAsset, listDirtyBriefAssets, listMemoryAssets, listPinAssets, saveBriefAsset, savePinAsset, writeExportArtifact } from "./memory-assets.js";
 import { indexAsset, indexPinnedAsset } from "./asset-sync.js";
-import { createComponentResolver, loadConfig, loadDotEnv } from "./runtime-config.js";
+import { createComponentResolver, loadConfig, loadDotEnv, resolveRecallMode } from "./runtime-config.js";
 import { DurableMemoryCategorySchema, StoreMemorySourceSchema } from "./memory-schema.js";
 import { persistCaseMemory, persistMemory, persistWorkflowPattern, promoteMemory } from "./capture-engine.js";
 import { buildSessionCheckpointResult } from "./session-engine.js";
@@ -613,8 +613,54 @@ registerTool(
     limitPerSection: z.number().int().min(1).max(6).default(3).describe("Max items per section"),
     includeLatestCheckpoint: z.boolean().default(true).describe("Whether to include the latest checkpoint summary"),
     profile: z.enum(["default", "writing", "debug", "fact-check"]).optional().describe("Retrieval profile"),
+    mode: z.enum(["full", "summary", "off"]).optional().describe("Override recall mode (default: from config.recallMode)"),
   },
-  async ({ task, scope, sessionId, limitPerSection, includeLatestCheckpoint, profile: profileName }) => {
+  async ({ task, scope, sessionId, limitPerSection, includeLatestCheckpoint, profile: profileName, mode: modeOverride }) => {
+    const effectiveMode = resolveRecallMode(config, modeOverride);
+
+    // --- off mode: no recall, guide agent to use search_memory ---
+    if (effectiveMode === "off") {
+      return {
+        content: [{
+          type: "text" as const,
+          text: "Recall mode is off. Use search_memory to retrieve specific memories on demand.",
+        }],
+      };
+    }
+
+    // --- summary mode: checkpoint only, lightweight ---
+    if (effectiveMode === "summary") {
+      const scopeSelection = resolveScopeSelection({
+        scope,
+        sessionId,
+        operation: "resume_context",
+        allowUnscoped: true,
+      });
+      const latest = await checkpointStore.getLatest({
+        sessionId,
+        scope: scopeSelection.resolvedScope,
+      });
+      const summaryText = formatCheckpointSummary(latest) +
+        "\n\nFor detailed recall, use search_memory with specific queries.";
+      await saveManagedObservation({
+        workflowId: "resume_context",
+        outcome: "success",
+        summary: `Managed resume_context returned summary-mode checkpoint${latest ? "" : " (none found)"}.`,
+        scope: scopeSelection.resolvedScope || scope || "global",
+        source: "managed:recallnest",
+        signal: "managed-resume-summary",
+        task,
+        tags: ["managed", "recallnest", "summary-mode"],
+      });
+      return {
+        content: [{
+          type: "text" as const,
+          text: summaryText,
+        }],
+      };
+    }
+
+    // --- full mode: existing compose behavior ---
     const { retriever, profile } = getComponents(profileName);
     const scopeSelection = resolveScopeSelection({
       scope,

src/runtime-config.ts

@@ -10,8 +10,11 @@ import { AccessTracker } from "./access-tracker.js";
 import { createLLMClient, type LLMClient, type LLMConfig } from "./llm-client.js";
 import { logInfo } from "./stderr-log.js";
 
+export type RecallMode = "full" | "summary" | "off";
+
 export interface LocalMemoryConfig {
   dbPath: string;
+  recallMode?: RecallMode;
   embedding: {
     provider: string;
     apiKey: string;
@@ -143,3 +146,19 @@ export function createComponentResolver(config: LocalMemoryConfig) {
     return created;
   };
 }
+
+const VALID_RECALL_MODES: RecallMode[] = ["full", "summary", "off"];
+
+/**
+ * Resolve effective recall mode: per-call override > env var > config > default ("summary").
+ */
+export function resolveRecallMode(config: LocalMemoryConfig, perCallOverride?: string): RecallMode {
+  if (perCallOverride && VALID_RECALL_MODES.includes(perCallOverride as RecallMode)) {
+    return perCallOverride as RecallMode;
+  }
+  const envMode = process.env.RECALLNEST_RECALL_MODE;
+  if (envMode && VALID_RECALL_MODES.includes(envMode as RecallMode)) {
+    return envMode as RecallMode;
+  }
+  return config.recallMode ?? "summary";
+}