@cortexkit/opencode-magic-context 0.49.11 → 0.49.13

package/src/agents/smart-notes-dreamer-gate.test.ts

@@ -0,0 +1,161 @@
+import { afterAll, beforeAll, expect, test } from "bun:test";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadPluginConfigDetailed, parsePluginConfig } from "../config";
+import { isDreamerRunnable, isSmartNoteSurfaceAvailable } from "../config/agent-disable";
+import { pluginConfigReader } from "../config/live-run-config";
+import { closeDatabase, openDatabase } from "../features/magic-context/storage";
+import type { Database } from "../shared/sqlite";
+import { createTestTempDirFromPath } from "../shared/test-temp-dir";
+import {
+    GATE_CASE_COUNT,
+    gateCases,
+    renderToolSurfaces,
+    type ToolSurfaceDigests,
+} from "./smart-notes-dreamer-gate.fixture";
+import golden from "./smart-notes-dreamer-gate.golden.json";
+
+// Smart notes are evaluated by the dreamer, so ctx_note drops its smart-note
+// argument and text when the dreamer is not runnable, as it already did for
+// smart_notes.enabled=false. The golden holds the tool bytes from before that
+// gate; every config with a runnable dreamer must still render them exactly.
+
+const SMART_NOTE_TEXT = /surface_condition|smart.note|outside checker/i;
+const oldXdg = process.env.XDG_DATA_HOME;
+let dir: string;
+let db: Database;
+
+beforeAll(() => {
+    dir = createTestTempDirFromPath(join(tmpdir(), "smart-notes-dreamer-gate-"));
+    process.env.XDG_DATA_HOME = dir;
+    db = openDatabase();
+});
+afterAll(() => {
+    closeDatabase();
+    if (oldXdg === undefined) delete process.env.XDG_DATA_HOME;
+    else process.env.XDG_DATA_HOME = oldXdg;
+    rmSync(dir, { recursive: true, force: true });
+});
+
+const render = (raw: Record<string, unknown>): Promise<ToolSurfaceDigests> => {
+    const config = parsePluginConfig(raw);
+    // The value context.ts passes to the OpenCode 2 per-request rewrite.
+    return renderToolSurfaces({
+        config,
+        directory: dir,
+        db,
+        oc2SmartNotes: isSmartNoteSurfaceAvailable(config),
+    });
+};
+
+test("ctx_* tool bytes match the pre-gate golden for every config with a runnable dreamer, and only ctx_note changes when the dreamer is off", async () => {
+    const cases = gateCases();
+    const expected = (golden as { cases: Array<Omit<ToolSurfaceDigests, "text">> }).cases;
+    expect(cases).toHaveLength(GATE_CASE_COUNT);
+    expect(expected).toHaveLength(GATE_CASE_COUNT);
+
+    let runnable = 0;
+    let gatedChanged = 0;
+    let gatedAlreadyOff = 0;
+    for (const [index, raw] of cases.entries()) {
+        const config = parsePluginConfig(raw);
+        const got = await render(raw);
+        const before = expected[index];
+        if (!before) throw new Error(`golden has no case ${index}`);
+        const label = `case ${index} ${JSON.stringify(raw)}`;
+        if (isDreamerRunnable(config)) {
+            runnable++;
+            expect({ label, oc1: got.oc1, oc2: got.oc2 }).toEqual({
+                label,
+                oc1: before.oc1,
+                oc2: before.oc2,
+            });
+            continue;
+        }
+        // Dreamer off: every other tool is untouched...
+        expect({ label, oc1: got.oc1.other, oc2: got.oc2.other }).toEqual({
+            label,
+            oc1: before.oc1.other,
+            oc2: before.oc2.other,
+        });
+        // ...and ctx_note is exactly the smart-notes-off surface of the same config.
+        const off = await render({ ...raw, smart_notes: { enabled: false } });
+        expect({ label, oc1: got.oc1.note, oc2: got.oc2.note }).toEqual({
+            label,
+            oc1: off.oc1.note,
+            oc2: off.oc2.note,
+        });
+        const ctxNote = (text: string) =>
+            JSON.stringify((JSON.parse(text) as Record<string, unknown>).ctx_note);
+        expect(ctxNote(got.text.oc1)).not.toMatch(SMART_NOTE_TEXT);
+        expect(ctxNote(got.text.oc2)).not.toMatch(SMART_NOTE_TEXT);
+        if (config.smart_notes.enabled === false) {
+            gatedAlreadyOff++;
+            expect(got.oc1.note).toBe(before.oc1.note);
+            expect(got.oc2.note).toBe(before.oc2.note);
+        } else {
+            gatedChanged++;
+            expect(got.oc1.note).not.toBe(before.oc1.note);
+            expect(got.oc2.note).not.toBe(before.oc2.note);
+        }
+    }
+    // Keep the differential meaningful: both sides must be well populated.
+    expect(runnable).toBeGreaterThanOrEqual(100);
+    expect(gatedChanged).toBeGreaterThanOrEqual(40);
+    expect(gatedAlreadyOff).toBeGreaterThanOrEqual(20);
+});
+
+test("the OpenCode 2 per-request rewrite receives the dreamer-aware smart-note flag", () => {
+    // The differential above passes this flag itself, so pin the production call.
+    const source = readFileSync(join(import.meta.dir, "../v2/hooks/context.ts"), "utf8");
+    expect(source).toMatch(
+        /applyV2PromptSurfaceTools\(\s*draft,\s*promptSurfaceRuntime,\s*config\.prompt_surface,[^)]*isSmartNoteSurfaceAvailable\(config\),\s*\)/,
+    );
+});
+
+test("a live dreamer toggle never changes the tool bytes registered for this process", async () => {
+    const previousHome = process.env.HOME;
+    const previousConfigHome = process.env.XDG_CONFIG_HOME;
+    try {
+        for (const [bootDreamer, liveDreamer] of [
+            [{}, { disable: true }],
+            [{ disable: true }, { disable: false }],
+        ] as const) {
+            const root = createTestTempDirFromPath(join(dir, "live-"));
+            process.env.HOME = root;
+            process.env.XDG_CONFIG_HOME = join(root, "config");
+            const directory = join(root, "project");
+            const configPath = join(root, "config", "cortexkit", "magic-context.jsonc");
+            mkdirSync(directory, { recursive: true });
+            mkdirSync(join(root, "config", "cortexkit"), { recursive: true });
+            writeFileSync(configPath, JSON.stringify({ dreamer: bootDreamer }));
+            const boot = loadPluginConfigDetailed(directory, false).config;
+            const bootAvailable = isSmartNoteSurfaceAvailable(boot);
+            // Registration reads the boot config once, as the hosts do.
+            const registered = () =>
+                renderToolSurfaces({
+                    config: boot,
+                    directory,
+                    db,
+                    oc2SmartNotes: isSmartNoteSurfaceAvailable(boot),
+                });
+            const before = await registered();
+
+            const reader = pluginConfigReader(directory, boot);
+            writeFileSync(configPath, JSON.stringify({ dreamer: liveDreamer }));
+            const effective = reader.poll().effective;
+            // The live view did flip, so the comparison below is not vacuous...
+            expect(isSmartNoteSurfaceAvailable(effective)).toBe(!bootAvailable);
+            // ...while the boot config the tools were built from is untouched.
+            expect(isSmartNoteSurfaceAvailable(boot)).toBe(bootAvailable);
+            const after = await registered();
+            expect(after.text).toEqual(before.text);
+        }
+    } finally {
+        if (previousHome === undefined) delete process.env.HOME;
+        else process.env.HOME = previousHome;
+        if (previousConfigHome === undefined) delete process.env.XDG_CONFIG_HOME;
+        else process.env.XDG_CONFIG_HOME = previousConfigHome;
+    }
+});

package/src/config/agent-disable.ts

@@ -12,6 +12,19 @@ export function isDreamerRunnable(config: { dreamer?: { disable?: boolean } | nu
     return !!config.dreamer && config.dreamer.disable !== true;
 }
 
+/**
+ * Whether smart notes can work at all: `smart_notes.enabled` is not false AND
+ * the dreamer, which evaluates every smart-note condition, is runnable. A smart
+ * note written without a runnable dreamer would stay parked forever, so the
+ * ctx_note tool definition advertises `surface_condition` only when this holds.
+ */
+export function isSmartNoteSurfaceAvailable(config: {
+    dreamer?: { disable?: boolean } | null;
+    smart_notes?: { enabled?: boolean } | null;
+}): boolean {
+    return config.smart_notes?.enabled !== false && isDreamerRunnable(config);
+}
+
 export function isHistorianRunnable(config: { historian?: { disable?: boolean } | null }): boolean {
     return config.historian?.disable !== true;
 }

package/src/config/dependency-notes.test.ts

@@ -0,0 +1,114 @@
+import { afterEach, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parsePluginConfig } from ".";
+import {
+    configDependencyNotes,
+    logConfigDependencyNotesOnce,
+    resetConfigDependencyNotesForTest,
+} from "./dependency-notes";
+
+afterEach(() => resetConfigDependencyNotesForTest());
+
+const notesFor = (raw: Record<string, unknown>) => configDependencyNotes(parsePluginConfig(raw));
+
+test("a default or fully enabled config produces no dependency notes", () => {
+    expect(notesFor({})).toEqual([]);
+    expect(notesFor({ dreamer: {} })).toEqual([]);
+    expect(notesFor({ dreamer: {}, memory: { enabled: true } })).toEqual([]);
+    // Memory off without a runnable dreamer has no dreamer schedule to lose.
+    expect(notesFor({ memory: { enabled: false } })).toEqual([]);
+    expect(
+        notesFor({
+            dreamer: { disable: true },
+            smart_notes: { enabled: false },
+            memory: { enabled: false },
+        }),
+    ).toHaveLength(1);
+});
+
+test("memory off with a runnable dreamer names the dreamer schedule it stops", () => {
+    const notes = notesFor({ dreamer: {}, memory: { enabled: false } });
+    expect(notes).toHaveLength(1);
+    expect(notes[0]).toBe(
+        "memory.enabled is false, so these scheduled dreamer tasks do not run for this project, on schedule or through /ctx-dream: map-memories, verify, verify-broad, curate, compress-cues, classify-memories, retrospective, promote-primers, refresh-primers. maintain-docs, evaluate-smart-notes and review-user-memories still run.",
+    );
+    // Every task unscheduled: nothing is lost, so nothing is reported.
+    const tasks = Object.fromEntries(
+        [
+            "map-memories",
+            "verify",
+            "verify-broad",
+            "curate",
+            "compress-cues",
+            "classify-memories",
+            "retrospective",
+            "maintain-docs",
+            "evaluate-smart-notes",
+            "review-user-memories",
+            "promote-primers",
+            "refresh-primers",
+        ].map((task) => [task, { schedule: "" }]),
+    );
+    expect(notesFor({ dreamer: { tasks }, memory: { enabled: false } })).toEqual([]);
+    // Only tasks that do not need project memory scheduled: nothing is lost either.
+    const nonMemory = {
+        ...tasks,
+        "maintain-docs": { schedule: "0 1 * * *" },
+        "evaluate-smart-notes": { schedule: "0 3 * * *" },
+        "review-user-memories": { schedule: "0 3 * * *" },
+    };
+    expect(notesFor({ dreamer: { tasks: nonMemory }, memory: { enabled: false } })).toEqual([]);
+    // One memory task scheduled: the note names just that one.
+    expect(
+        notesFor({
+            dreamer: { tasks: { ...tasks, curate: { schedule: "0 4 * * 0" } } },
+            memory: { enabled: false },
+        }),
+    ).toEqual([
+        "memory.enabled is false, so these scheduled dreamer tasks do not run for this project, on schedule or through /ctx-dream: curate. maintain-docs, evaluate-smart-notes and review-user-memories still run.",
+    ]);
+});
+
+test("a disabled dreamer reports smart notes and the user-memory review schedule", () => {
+    const notes = notesFor({ dreamer: { disable: true } });
+    expect(notes).toEqual([
+        expect.stringContaining("smart_notes.enabled has no effect") as unknown as string,
+        expect.stringContaining(
+            "dreamer.tasks.review-user-memories.schedule has no effect",
+        ) as unknown as string,
+    ]);
+    expect(notesFor({ dreamer: { disable: true }, smart_notes: { enabled: false } })).toHaveLength(
+        1,
+    );
+    expect(
+        notesFor({
+            dreamer: { disable: true, tasks: { "review-user-memories": { schedule: "" } } },
+            smart_notes: { enabled: false },
+        }),
+    ).toEqual([]);
+});
+
+test("each note is logged once per process", () => {
+    const lines: string[] = [];
+    const config = parsePluginConfig({ dreamer: { disable: true } });
+    expect(logConfigDependencyNotesOnce(config, (line) => lines.push(line))).toHaveLength(2);
+    expect(logConfigDependencyNotesOnce(config, (line) => lines.push(line))).toEqual([]);
+    expect(lines).toHaveLength(2);
+    expect(lines.every((line) => line.startsWith("[magic-context] config note: "))).toBe(true);
+    // A second plugin instance with a different config still reports its own notes.
+    const memoryOff = parsePluginConfig({ dreamer: {}, memory: { enabled: false } });
+    expect(logConfigDependencyNotesOnce(memoryOff, (line) => lines.push(line))).toHaveLength(1);
+    expect(lines).toHaveLength(3);
+});
+
+test("every host logs the dependency notes at startup", () => {
+    const src = join(import.meta.dir, "..");
+    for (const [file, call] of [
+        ["index.ts", "logConfigDependencyNotesOnce(pluginConfig, log);"],
+        ["v2/hooks/context.ts", "logConfigDependencyNotesOnce(config, log);"],
+        ["../../pi-plugin/src/index.ts", "logConfigDependencyNotesOnce(config, log);"],
+    ] as const) {
+        expect(readFileSync(join(src, file), "utf8")).toContain(call);
+    }
+});

package/src/config/dependency-notes.ts

@@ -0,0 +1,80 @@
+import { PROJECT_MEMORY_DREAM_TASKS } from "../features/magic-context/dreamer/task-registry";
+import { isDreamerRunnable } from "./agent-disable";
+
+/**
+ * Settings whose effect depends on a different section of the config. These
+ * lines name a setting that is on but cannot act because another setting turns
+ * off what it relies on, so a user reading the log can tell why nothing happens.
+ *
+ * Only settings the user can see as "on" are reported: an explicit
+ * `memory.enabled: false` or `dreamer.disable: true` is the cause in every line,
+ * so a configuration that sets neither produces none.
+ */
+export interface DependencyNoteConfig {
+    memory?: { enabled?: boolean } | null;
+    smart_notes?: { enabled?: boolean } | null;
+    dreamer?: {
+        disable?: boolean;
+        tasks?: Record<string, { schedule?: string } | undefined>;
+    } | null;
+}
+
+function scheduledTasks(config: DependencyNoteConfig): string[] {
+    const tasks = config.dreamer?.tasks ?? {};
+    return Object.entries(tasks)
+        .filter(([, task]) => typeof task?.schedule === "string" && task.schedule.trim() !== "")
+        .map(([name]) => name);
+}
+
+/** The dependency notes for one resolved config, in a stable order. */
+export function configDependencyNotes(config: DependencyNoteConfig): string[] {
+    const notes: string[] = [];
+    const dreamerRunnable = isDreamerRunnable(config);
+    const dreamerDisabled = config.dreamer?.disable === true;
+    const memoryOff = config.memory?.enabled === false;
+
+    const memoryTasks = scheduledTasks(config).filter((task) =>
+        (PROJECT_MEMORY_DREAM_TASKS as readonly string[]).includes(task),
+    );
+    if (dreamerRunnable && memoryOff && memoryTasks.length > 0) {
+        notes.push(
+            `memory.enabled is false, so these scheduled dreamer tasks do not run for this project, on schedule or through /ctx-dream: ${memoryTasks.join(", ")}. maintain-docs, evaluate-smart-notes and review-user-memories still run.`,
+        );
+    }
+    if (dreamerDisabled && config.smart_notes?.enabled !== false) {
+        notes.push(
+            "dreamer.disable is true, so smart_notes.enabled has no effect: ctx_note does not offer surface_condition and pending smart notes are not evaluated.",
+        );
+    }
+    const reviewSchedule = config.dreamer?.tasks?.["review-user-memories"]?.schedule;
+    if (dreamerDisabled && typeof reviewSchedule === "string" && reviewSchedule.trim() !== "") {
+        notes.push(
+            "dreamer.disable is true, so dreamer.tasks.review-user-memories.schedule has no effect: the historian does not collect user observations and the <user-profile> block gets no new entries.",
+        );
+    }
+    return notes;
+}
+
+const loggedNotes = new Set<string>();
+
+/**
+ * Log each dependency note once per process. OpenCode Desktop starts one
+ * plugin instance per open project in the same process, so a note already
+ * written by another instance is skipped rather than repeated.
+ */
+export function logConfigDependencyNotesOnce(
+    config: DependencyNoteConfig,
+    log: (message: string) => void,
+): string[] {
+    const fresh = configDependencyNotes(config).filter((note) => !loggedNotes.has(note));
+    for (const note of fresh) {
+        loggedNotes.add(note);
+        log(`[magic-context] config note: ${note}`);
+    }
+    return fresh;
+}
+
+/** Test-only: forget which notes this process has logged. */
+export function resetConfigDependencyNotesForTest(): void {
+    loggedNotes.clear();
+}

package/src/config/schema/magic-context.ts

@@ -613,6 +613,8 @@ export const DreamTasksSchema = z
         ),
         "review-user-memories": ReviewUserMemoriesTaskConfigSchema.default(() =>
             ReviewUserMemoriesTaskConfigSchema.parse(defaultTaskConfig("review-user-memories")),
+        ).describe(
+            "Promote recurring user observations into the <user-profile> block. A non-empty schedule also makes the historian collect user observations, but only while the dreamer is runnable (dreamer.disable not true); collection and review follow that one gate and do not depend on memory.enabled.",
         ),
         "promote-primers": PromotePrimersTaskConfigSchema.default(() =>
             PromotePrimersTaskConfigSchema.parse(defaultTaskConfig("promote-primers")),
@@ -644,7 +646,12 @@ export const DreamerConfigSchema = AgentMetadataSchema.extend({
     // Its own node rather than the one shared with the historian through
     // AgentMetadataSchema: `dreamer.disable` is a live-reload key and the
     // historian's is not, and the live marker is set on the schema node.
-    disable: z.boolean().optional().describe("Disable this agent"),
+    disable: z
+        .boolean()
+        .optional()
+        .describe(
+            "Disable the dreamer: no scheduled or manual dream task runs. Also turns off smart notes (ctx_note drops surface_condition even with smart_notes.enabled true) and the historian's collection of user observations for review-user-memories. dreamer.inject_docs still applies.",
+        ),
     runner: z
         .enum(["broca", "host"])
         .optional()
@@ -659,7 +666,7 @@ export const DreamerConfigSchema = AgentMetadataSchema.extend({
         .boolean()
         .default(true)
         .describe(
-            "Inject ARCHITECTURE.md and STRUCTURE.md into the m[0] `<project-docs>` block (default true)",
+            "Inject ARCHITECTURE.md and STRUCTURE.md into the m[0] `<project-docs>` block (default true). Not a dreamer setting despite its place under dreamer: it applies on every host, also with dreamer.disable true.",
         ),
 });
 export type DreamerConfig = z.infer<typeof DreamerConfigSchema>;
@@ -1181,7 +1188,7 @@ export const MagicContextConfigSchema = z
             "Historian metadata plus independent strict OpenCode, Pi, and OMP execution blocks. Retained metadata stays at historian; model, fallback_models, variant, and thinking_level belong only in historian.opencode, historian.pi, or historian.omp.",
         ),
         dreamer: DreamerConfigSchema.optional().describe(
-            "Dreamer metadata and scheduling plus independent strict OpenCode, Pi, and OMP execution blocks. schedule and promotion_threshold stay at dreamer.tasks; model, fallback_models, variant, thinking_level, and timeout_minutes belong only in the matching harness block.",
+            "Dreamer metadata and scheduling plus independent strict OpenCode, Pi, and OMP execution blocks. schedule and promotion_threshold stay at dreamer.tasks; model, fallback_models, variant, thinking_level, and timeout_minutes belong only in the matching harness block. Each task follows the setting it serves: memory tasks need memory.enabled, evaluate-smart-notes needs smart_notes.enabled, review-user-memories needs its schedule, maintain-docs only a runnable dreamer.",
         ),
         smart_notes: z
             .object({
@@ -1189,7 +1196,7 @@ export const MagicContextConfigSchema = z
                     .boolean()
                     .default(true)
                     .describe(
-                        "Enable smart-note authoring and condition evaluation. User-level only: tool definitions are process-wide. Changes require a host restart and rebuild each session's cached prompt once. Pending notes remain stored and unchecked; already-ready notes still surface.",
+                        "Enable smart-note authoring and condition evaluation. Needs a runnable dreamer, which evaluates the conditions: with dreamer.disable true (or no dreamer block) ctx_note offers no surface_condition whatever this says. User-level only: tool definitions are process-wide. Changes require a host restart and rebuild each session's cached prompt once. Pending notes remain stored and unchecked; already-ready notes still surface.",
                     ),
                 retina_handoff: z
                     .boolean()
@@ -1303,7 +1310,7 @@ export const MagicContextConfigSchema = z
             .min(60_000)
             .default(DEFAULT_HISTORIAN_TIMEOUT_MS)
             .describe(
-                "Timeout for each historian prompt call in both TypeScript and Rust transform modes, in milliseconds (default: 600000)",
+                "Timeout for each historian prompt call in both TypeScript and Rust transform modes, in milliseconds (default: 600000). A historian setting kept at the top level for compatibility; no effect while historian.disable is true or compaction.enabled is false.",
             ),
         commit_cluster_trigger: z
             .object({
@@ -1321,7 +1328,7 @@ export const MagicContextConfigSchema = z
             })
             .default({ enabled: true, min_clusters: 3 })
             .describe(
-                "Commit-cluster trigger: fire historian when enough commit clusters accumulate in the unsummarized tail",
+                "Commit-cluster trigger: fire historian when enough commit clusters accumulate in the unsummarized tail. A historian setting kept at the top level for compatibility; no effect while historian.disable is true or compaction.enabled is false.",
             ),
         system_prompt_injection: z
             .object({
@@ -1510,7 +1517,7 @@ export const MagicContextConfigSchema = z
                     .boolean()
                     .default(true)
                     .describe(
-                        "Enable cross-session memory (default: true). Does not affect history embedding or semantic ctx_search over session history; set embedding.provider to 'off' to stop all embedding.",
+                        "Enable cross-session project memory (default: true). Also gates the dreamer's project-memory tasks: while false, map-memories, verify, verify-broad, curate, compress-cues, classify-memories, retrospective, promote-primers and refresh-primers neither run on schedule nor through /ctx-dream; maintain-docs, evaluate-smart-notes and review-user-memories still run. memory.auto_search and memory.git_commit_indexing do not depend on it. Does not affect history embedding or semantic ctx_search over session history; set embedding.provider to 'off' to stop all embedding.",
                     ),
                 injection_budget_tokens: z
                     .number()
@@ -1524,14 +1531,14 @@ export const MagicContextConfigSchema = z
                     .boolean()
                     .default(true)
                     .describe(
-                        "Automatically promote eligible session facts into memory (default: true)",
+                        "Automatically promote eligible session facts into memory (default: true). No effect while memory.enabled is false.",
                     ),
                 retrieval_count_promotion_threshold: z
                     .number()
                     .min(1)
                     .default(3)
                     .describe(
-                        "retrieval_count threshold for promoting memory to permanent status (min: 1, default: 3)",
+                        "Currently has no effect: no code reads this value, and memories are not promoted to permanent by retrieval count. Kept so existing configs stay valid (min: 1, default: 3).",
                     ),
                 auto_search: z
                     .object({
@@ -1539,7 +1546,7 @@ export const MagicContextConfigSchema = z
                             .boolean()
                             .default(true)
                             .describe(
-                                "Automatically append a compact <ctx-search-hint> to eligible user messages when relevant memories, conversation, or commits are found. Graduated from experimental.auto_search; on by default (set false to opt out). Independent of memory.enabled.",
+                                "Automatically append a compact <ctx-search-hint> to eligible user messages when relevant memories, conversation, or commits are found. Graduated from experimental.auto_search; on by default (set false to opt out). Independent of memory.enabled despite its place under memory: with memory off it still searches past conversation and commits, only the memory source is skipped.",
                             ),
                         score_threshold: z
                             .number()
@@ -1560,7 +1567,7 @@ export const MagicContextConfigSchema = z
                     })
                     .default({ enabled: true, score_threshold: 0.6, min_prompt_chars: 20 })
                     .describe(
-                        "Auto-search hint: transform-time ctx_search on each new user message; when the top hit clears the threshold, append a compact <ctx-search-hint> block of vague fragments to that user message. Does NOT inject full content. Graduated from experimental.auto_search; enabled by default (set enabled: false to opt out). Independent of memory.enabled.",
+                        "Auto-search hint: transform-time ctx_search on each new user message; when the top hit clears the threshold, append a compact <ctx-search-hint> block of vague fragments to that user message. Does NOT inject full content. Graduated from experimental.auto_search; enabled by default (set enabled: false to opt out). Independent of memory.enabled despite its place under memory: with memory off it still searches past conversation and commits.",
                     ),
                 git_commit_indexing: z
                     .object({
@@ -1568,7 +1575,7 @@ export const MagicContextConfigSchema = z
                             .boolean()
                             .default(false)
                             .describe(
-                                "Index HEAD git commits for ctx_search (git_commit source). Graduated from experimental.git_commit_indexing; opt-in, default off. Independent of memory.enabled.",
+                                "Index HEAD git commits for ctx_search (git_commit source). Graduated from experimental.git_commit_indexing; opt-in, default off. Independent of memory.enabled despite its place under memory.",
                             ),
                         since_days: z
                             .number()
@@ -1589,7 +1596,7 @@ export const MagicContextConfigSchema = z
                     })
                     .default({ enabled: false, since_days: 365, max_commits: 2000 })
                     .describe(
-                        "Index git commit messages from HEAD into ctx_search. Commits become a 4th searchable source alongside memories and session history. Graduated from experimental.git_commit_indexing; opt-in, default off (per-project embedding cost). Independent of memory.enabled.",
+                        "Index git commit messages from HEAD into ctx_search. Commits become a 4th searchable source alongside memories and session history. Graduated from experimental.git_commit_indexing; opt-in, default off (per-project embedding cost). Independent of memory.enabled despite its place under memory.",
                     ),
             })
             .default({
@@ -1600,7 +1607,9 @@ export const MagicContextConfigSchema = z
                 auto_search: { enabled: true, score_threshold: 0.6, min_prompt_chars: 20 },
                 git_commit_indexing: { enabled: false, since_days: 365, max_commits: 2000 },
             })
-            .describe("Cross-session memory configuration"),
+            .describe(
+                "Cross-session memory configuration. auto_search and git_commit_indexing sit here for history but work with memory.enabled false.",
+            ),
     })
     .transform((data): MagicContextConfig => {
         return {

package/src/features/magic-context/dreamer/task-registry.ts

@@ -278,6 +278,46 @@ export const MEMORY_DOMAIN_TASKS: readonly DreamTaskName[] = [
 
 const MEMORY_DOMAIN_SET = new Set<DreamTaskName>(MEMORY_DOMAIN_TASKS);
 
+/**
+ * The dreamer tasks that maintain project memory or knowledge derived from it
+ * (primers grow out of the same sessions and live beside the memories). They
+ * run only while `memory.enabled` is true. Every other task serves a different
+ * setting and runs with memory off:
+ *  - evaluate-smart-notes follows `smart_notes.enabled`;
+ *  - review-user-memories follows user-observation collection, which is on
+ *    exactly when the review is scheduled and the dreamer is runnable, so
+ *    observations are collected exactly when they will be reviewed;
+ *  - maintain-docs needs only a runnable dreamer.
+ * A runnable dreamer is the precondition for any scheduler call at all.
+ */
+export const PROJECT_MEMORY_DREAM_TASKS: readonly DreamTaskName[] = [
+    "map-memories",
+    "verify",
+    "verify-broad",
+    "curate",
+    "compress-cues",
+    "classify-memories",
+    "retrospective",
+    "promote-primers",
+    "refresh-primers",
+];
+
+const PROJECT_MEMORY_DREAM_TASK_SET = new Set<DreamTaskName>(PROJECT_MEMORY_DREAM_TASKS);
+
+/**
+ * Whether the per-project settings let this task run. `memory.enabled` gates
+ * only the project-memory tasks and `smart_notes.enabled` only
+ * evaluate-smart-notes; an omitted setting counts as on.
+ */
+export function dreamTaskAllowedBySettings(
+    task: DreamTaskName,
+    settings: { projectMemoryEnabled?: boolean; smartNotesEnabled?: boolean },
+): boolean {
+    if (PROJECT_MEMORY_DREAM_TASK_SET.has(task)) return settings.projectMemoryEnabled !== false;
+    if (task === "evaluate-smart-notes") return settings.smartNotesEnabled !== false;
+    return true;
+}
+
 /**
  * Lease KIND per task. `memory` + the three independent kinds are per-project;
  * `user-memories` is GLOBAL (mutates the cross-project user-profile pool, so two

package/src/shared/data-path.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import {
@@ -14,6 +14,7 @@ import {
     getOpenCodeStorageDir,
     getProjectMagicContextDir,
     getProjectMagicContextHistorianDir,
+    isMagicContextStorageOutsideEngram,
 } from "./data-path";
 import { createTestTempDirFromPath } from "./test-temp-dir";
 
@@ -108,12 +109,45 @@ describe("data-path", () => {
             expect(getMagicContextStorageDir()).toBe(
                 path.join(os.homedir(), ".local", "share", "cortexkit", "magic-context"),
             );
+            expect(isMagicContextStorageOutsideEngram()).toBe(false);
         } finally {
             if (savedTestDir !== undefined) process.env.MAGIC_CONTEXT_TEST_DATA_DIR = savedTestDir;
             if (savedNodeEnv !== undefined) process.env.NODE_ENV = savedNodeEnv;
         }
     });
 
+    test("an external storage override is outside the Engram backup folder", () => {
+        const root = createTestTempDirFromPath(path.join(os.tmpdir(), "mc-storage-backup-"));
+        process.env.MAGIC_CONTEXT_STORAGE_DIR = path.join(root, "external-store");
+
+        expect(isMagicContextStorageOutsideEngram()).toBe(true);
+    });
+
+    test("storage below the Engram backup folder is considered inside it", () => {
+        const root = createTestTempDirFromPath(path.join(os.tmpdir(), "mc-storage-backup-"));
+        const backupDir = path.join(root, "default", "magic-context");
+
+        expect(isMagicContextStorageOutsideEngram(path.join(backupDir, "nested"), backupDir)).toBe(
+            false,
+        );
+    });
+
+    test("a storage symlink into the default folder is considered inside it", () => {
+        const root = createTestTempDirFromPath(path.join(os.tmpdir(), "mc-storage-backup-"));
+        const backupDir = path.join(root, "default", "magic-context");
+        const storageLink = path.join(root, "storage-link");
+        mkdirSync(backupDir, { recursive: true });
+        symlinkSync(backupDir, storageLink, "dir");
+
+        expect(isMagicContextStorageOutsideEngram(storageLink, backupDir)).toBe(false);
+    });
+
+    test("an unset storage override keeps the platform default inside the backup folder", () => {
+        expect(process.env.MAGIC_CONTEXT_STORAGE_DIR).toBeUndefined();
+        expect(process.env.XDG_DATA_HOME).toBeUndefined();
+        expect(isMagicContextStorageOutsideEngram()).toBe(false);
+    });
+
     test("getMagicContextStorageDir backstops to a temp dir under NODE_ENV=test with no guard set", () => {
         // CWD-independent backstop: a `bun test` from a dir whose bunfig has no
         // `[test] preload` runs every suite with neither guard env var set. The