feat(temporal): add experimental temporal_awareness flag

ualtinok · ualtinok · commit 99aa41ea189b · 2026-04-21T12:44:47.000+03:00
Give the agent wall-clock awareness across long-running sessions without
busting prompt cache.

When experimental.temporal_awareness is true (default false):

  * User messages are prefixed with HTML-comment gap markers showing
    time elapsed since the previous message's effective end:

        &lt;!-- +12m --&gt;      under an hour
        &lt;!-- +2h 15m --&gt;   under a day
        &lt;!-- +3d 4h --&gt;    under a week
        &lt;!-- +2w 3d --&gt;    week or more

    Zero-component forms elide to &lt;!-- +2h --&gt; etc. Gaps &lt;= 5 min emit
    nothing. Previous anchor is any role, timed from time.completed if
    present else time.created, so an 8-minute assistant turn answered
    instantly produces no marker.

  * Compartments in &lt;session-history&gt; carry start-date and end-date
    attributes (YYYY-MM-DD) resolved from OpenCode message.time_created
    for the compartment's start_message_id and end_message_id. Separate
    from existing ordinal start=/end= attributes so no collision.

  * The injected Magic Context agent prompt gains a short paragraph
    explaining both markers (only when the flag is enabled).

Cache-safe properties:

  * Gap markers derive from immutable message.time values. Idempotent
    across passes — pre-existing &lt;!-- +Xm --&gt; prefixes are detected via
    TEMPORAL_MARKER_PATTERN before insertion.
  * Marker sits after any §N§ tag prefix so tag round-trip stays stable.
  * Compartment date attributes are recomputed on each injection build
    from stored message IDs + DB times. The existing memory_block_cache
    behavior applies.
  * Historian input (read-session-chunk.ts) is unchanged — historian
    stays temporally neutral; time context only reaches live agent view.

Retroactive: when the flag flips on, all live-tail user messages and
compartments get markers/dates on the first transform pass. The cache
bust on the flag-flip itself is expected.

Verified: 712/712 tests pass, typecheck clean, 20 unit tests for the
pure formatting and injection functions.
diff --git a/packages/plugin/src/agents/magic-context-prompt.ts b/packages/plugin/src/agents/magic-context-prompt.ts
@@ -225,20 +225,24 @@ export function detectAgentFromSystemPrompt(systemPrompt: string): AgentType | n
     return null;
 }
 
+const TEMPORAL_AWARENESS_GUIDANCE = `\n**Temporal awareness**: User messages may be preceded by HTML comments like \`<!-- +12m -->\`, \`<!-- +2h 15m -->\`, or \`<!-- +3d 4h -->\` indicating time elapsed since the previous message's completion. Compartments in \`<session-history>\` carry \`start-date\` and \`end-date\` attributes (YYYY-MM-DD) showing real-time boundaries. Use these when reasoning about workflow pacing, log durations, build times, or how long ago something happened.`;
+
 export function buildMagicContextSection(
     agent: AgentType | null,
     protectedTags: number,
     ctxReduceEnabled = true,
     dreamerEnabled = false,
     dropToolStructure = true,
+    temporalAwarenessEnabled = false,
 ): string {
     const smartNoteGuidance = dreamerEnabled
         ? `\nWhen \`surface_condition\` is provided with \`write\`, the note becomes a project-scoped smart note.\nThe dreamer evaluates smart note conditions during nightly runs and surfaces them when conditions are met.\nExample: \`ctx_note(action="write", content="Implement X because Y", surface_condition="When PR #42 is merged in this repo")\``
         : "";
+    const temporalGuidance = temporalAwarenessEnabled ? TEMPORAL_AWARENESS_GUIDANCE : "";
 
     if (!ctxReduceEnabled) {
-        return `## Magic Context\n\n${BASE_INTRO_NO_REDUCE(dropToolStructure)}${smartNoteGuidance}`;
+        return `## Magic Context\n\n${BASE_INTRO_NO_REDUCE(dropToolStructure)}${smartNoteGuidance}${temporalGuidance}`;
     }
     const section = agent ? AGENT_SECTIONS[agent] : GENERIC_SECTION;
-    return `## Magic Context\n\n${BASE_INTRO(protectedTags, dropToolStructure)}${smartNoteGuidance}\n${section}\n\nPrefer many small targeted operations over one large blanket operation. Compress early and often — don't wait for warnings.`;
+    return `## Magic Context\n\n${BASE_INTRO(protectedTags, dropToolStructure)}${smartNoteGuidance}${temporalGuidance}\n${section}\n\nPrefer many small targeted operations over one large blanket operation. Compress early and often — don't wait for warnings.`;
 }
diff --git a/packages/plugin/src/config/schema/magic-context.test.ts b/packages/plugin/src/config/schema/magic-context.test.ts
@@ -80,6 +80,7 @@ describe("MagicContextConfigSchema", () => {
                         token_budget: 10000,
                         min_reads: 4,
                     },
+                    temporal_awareness: false,
                 },
                 embedding: {
                     provider: "openai-compatible",
diff --git a/packages/plugin/src/config/schema/magic-context.ts b/packages/plugin/src/config/schema/magic-context.ts
@@ -181,6 +181,9 @@ export interface MagicContextConfig {
             /** Minimum full-read count before a file is considered for pinning (default: 4) */
             min_reads: number;
         };
+        /** Inject elapsed-time markers between user messages and date ranges on
+         *  compartments so the agent has a wall-clock sense of the session. */
+        temporal_awareness: boolean;
     };
     embedding: EmbeddingConfig;
     memory: {
@@ -346,10 +349,16 @@ export const MagicContextConfigSchema = z
                         min_reads: z.number().min(2).max(20).default(4),
                     })
                     .default({ enabled: false, token_budget: 10000, min_reads: 4 }),
+                /** Inject wall-clock gap markers (<!-- +Xm -->) between user messages
+                 *  where > 5 min elapsed since the previous message, and add start/end
+                 *  date attributes on compartments. Gives the agent a sense of session
+                 *  pacing and "how long ago" across multi-day sessions. Default: false. */
+                temporal_awareness: z.boolean().default(false),
             })
             .default({
                 user_memories: { enabled: false, promotion_threshold: 3 },
                 pin_key_files: { enabled: false, token_budget: 10000, min_reads: 4 },
+                temporal_awareness: false,
             }),
         /** Cross-session memory configuration */
         memory: z
diff --git a/packages/plugin/src/features/magic-context/compartment-storage.ts b/packages/plugin/src/features/magic-context/compartment-storage.ts
@@ -269,10 +269,16 @@ export function replaceAllCompartmentState(
     })();
 }
 
+export interface CompartmentDateRanges {
+    /** Map compartment id → `{ start: "YYYY-MM-DD", end: "YYYY-MM-DD" }` */
+    byId: Map<number, { start: string; end: string }>;
+}
+
 export function buildCompartmentBlock(
     compartments: Compartment[],
     facts: SessionFact[],
     memoryBlock?: string,
+    dateRanges?: CompartmentDateRanges,
 ): string {
     const lines: string[] = [];
 
@@ -282,8 +288,10 @@ export function buildCompartmentBlock(
     }
 
     for (const c of compartments) {
+        const dates = dateRanges?.byId.get(c.id);
+        const dateAttr = dates ? ` start-date="${dates.start}" end-date="${dates.end}"` : "";
         lines.push(
-            `<compartment start="${c.startMessage}" end="${c.endMessage}" title="${escapeXmlAttr(c.title)}">`,
+            `<compartment start="${c.startMessage}" end="${c.endMessage}"${dateAttr} title="${escapeXmlAttr(c.title)}">`,
         );
         lines.push(escapeXmlContent(c.content));
         lines.push("</compartment>");
diff --git a/packages/plugin/src/hooks/magic-context/compartment-runner-types.ts b/packages/plugin/src/hooks/magic-context/compartment-runner-types.ts
@@ -21,6 +21,8 @@ export interface CompartmentRunnerDeps {
     experimentalCompactionMarkers?: boolean;
     /** When true, extract user behavior observations from historian output */
     experimentalUserMemories?: boolean;
+    /** When true, inject wall-clock dates on compartments in <session-history>. */
+    experimentalTemporalAwareness?: boolean;
     /** When true, run an editor pass after successful historian output to clean
      *  low-signal U: lines and cross-compartment duplicates. */
     historianTwoPass?: boolean;
diff --git a/packages/plugin/src/hooks/magic-context/hook.ts b/packages/plugin/src/hooks/magic-context/hook.ts
@@ -91,6 +91,7 @@ export interface MagicContextDeps {
         experimental?: {
             user_memories?: { enabled: boolean; promotion_threshold: number };
             pin_key_files?: { enabled: boolean; token_budget: number; min_reads: number };
+            temporal_awareness?: boolean;
         };
     };
 }
@@ -259,6 +260,7 @@ export function createMagicContextHook(deps: MagicContextDeps) {
         projectPath,
         experimentalCompactionMarkers: deps.config.compaction_markers,
         experimentalUserMemories: deps.config.experimental?.user_memories?.enabled,
+        experimentalTemporalAwareness: deps.config.experimental?.temporal_awareness === true,
         historianTwoPass: deps.config.historian?.two_pass === true,
         compressorMinCompartmentRatio:
             deps.config.compressor?.enabled === false
@@ -440,6 +442,7 @@ export function createMagicContextHook(deps: MagicContextDeps) {
         experimentalUserMemories: deps.config.experimental?.user_memories?.enabled,
         experimentalPinKeyFiles: deps.config.experimental?.pin_key_files?.enabled ?? false,
         experimentalPinKeyFilesTokenBudget: deps.config.experimental?.pin_key_files?.token_budget,
+        experimentalTemporalAwareness: deps.config.experimental?.temporal_awareness === true,
     });
 
     const eventHook = createEventHook({
diff --git a/packages/plugin/src/hooks/magic-context/inject-compartments.ts b/packages/plugin/src/hooks/magic-context/inject-compartments.ts
@@ -1,6 +1,7 @@
 import type { Database } from "bun:sqlite";
 import {
     buildCompartmentBlock,
+    type CompartmentDateRanges,
     escapeXmlContent,
     getCompartments,
     getSessionFacts,
@@ -9,8 +10,10 @@ import { CATEGORY_PRIORITY } from "../../features/magic-context/memory/constants
 import { getMemoriesByProject } from "../../features/magic-context/memory/storage-memory";
 import type { Memory, MemoryCategory } from "../../features/magic-context/memory/types";
 import { sessionLog } from "../../shared/logger";
+import { getMessageTimesFromOpenCodeDb } from "./read-session-db";
 import { estimateTokens } from "./read-session-formatting";
 import type { MessageLike } from "./tag-messages";
+import { formatDate } from "./temporal-awareness";
 
 export interface PreparedCompartmentInjection {
     block: string;
@@ -162,6 +165,7 @@ export function prepareCompartmentInjection(
     isCacheBusting: boolean,
     projectPath?: string,
     injectionBudgetTokens?: number,
+    temporalAwareness?: boolean,
 ): PreparedCompartmentInjection | null {
     // On defer (cache-safe) passes, replay the cached injection result so that
     // historian publications between passes do not bust the prompt-cache prefix.
@@ -249,7 +253,27 @@ export function prepareCompartmentInjection(
         return null;
     }
 
-    const block = buildCompartmentBlock(compartments, facts, memoryBlock);
+    let dateRanges: CompartmentDateRanges | undefined;
+    if (temporalAwareness && compartments.length > 0) {
+        // Resolve start/end message times from OpenCode's DB in a single batched query.
+        const ids = new Set<string>();
+        for (const c of compartments) {
+            if (c.startMessageId) ids.add(c.startMessageId);
+            if (c.endMessageId) ids.add(c.endMessageId);
+        }
+        const times = getMessageTimesFromOpenCodeDb(sessionId, Array.from(ids));
+        const byId = new Map<number, { start: string; end: string }>();
+        for (const c of compartments) {
+            const startMs = times.get(c.startMessageId);
+            const endMs = times.get(c.endMessageId);
+            if (startMs !== undefined && endMs !== undefined) {
+                byId.set(c.id, { start: formatDate(startMs), end: formatDate(endMs) });
+            }
+        }
+        if (byId.size > 0) dateRanges = { byId };
+    }
+
+    const block = buildCompartmentBlock(compartments, facts, memoryBlock, dateRanges);
 
     // When there are no compartments yet (new session, or memories seeded before
     // historian first run), inject memories/facts without a boundary cutoff.
diff --git a/packages/plugin/src/hooks/magic-context/read-session-db.ts b/packages/plugin/src/hooks/magic-context/read-session-db.ts
@@ -75,6 +75,49 @@ interface AssistantModelRow {
  *
  * Returns null for brand-new sessions with no assistant turn yet.
  */
+interface MessageTimeRow {
+    id?: string;
+    time_created?: number;
+}
+
+/**
+ * Resolve `time_created` (ms since epoch) for a set of OpenCode message IDs.
+ * Returns a Map keyed by message ID. Missing IDs are simply omitted.
+ *
+ * Used by temporal-awareness to map compartment start/end message IDs to
+ * wall-clock dates for the `start="YYYY-MM-DD"` / `end="YYYY-MM-DD"` attrs
+ * on the `<compartment>` elements in `<session-history>`.
+ */
+export function getMessageTimesFromOpenCodeDb(
+    sessionId: string,
+    messageIds: readonly string[],
+): Map<string, number> {
+    const result = new Map<string, number>();
+    if (messageIds.length === 0) return result;
+
+    try {
+        withReadOnlySessionDb((db) => {
+            // SQLite limits on IN (?, ?, ...) are high (~999 by default) so a
+            // single batched query is safe for any realistic compartment count.
+            const placeholders = messageIds.map(() => "?").join(",");
+            const rows = db
+                .prepare(
+                    `SELECT id, time_created FROM message WHERE session_id = ? AND id IN (${placeholders})`,
+                )
+                .all(sessionId, ...messageIds) as MessageTimeRow[];
+            for (const row of rows) {
+                if (typeof row.id === "string" && typeof row.time_created === "number") {
+                    result.set(row.id, row.time_created);
+                }
+            }
+        });
+    } catch (error) {
+        log("[magic-context] failed to resolve message times from OpenCode DB:", error);
+    }
+
+    return result;
+}
+
 export function findLastAssistantModelFromOpenCodeDb(
     sessionId: string,
 ): { providerID: string; modelID: string } | null {
diff --git a/packages/plugin/src/hooks/magic-context/system-prompt-hash.ts b/packages/plugin/src/hooks/magic-context/system-prompt-hash.ts
@@ -81,6 +81,8 @@ export function createSystemPromptHashHandler(deps: {
     experimentalPinKeyFiles?: boolean;
     /** Token budget for key files injection (default 10000) */
     experimentalPinKeyFilesTokenBudget?: number;
+    /** When true, add a temporal-awareness guidance paragraph + surface compartment dates */
+    experimentalTemporalAwareness?: boolean;
 }): (input: { sessionID?: string }, output: { system: string[] }) => Promise<void> {
     // Per-session sticky date: we freeze the date string from the system prompt
     // and only update it on cache-busting passes. This prevents a midnight date
@@ -108,6 +110,7 @@ export function createSystemPromptHashHandler(deps: {
                 deps.ctxReduceEnabled,
                 deps.dreamerEnabled,
                 deps.dropToolStructure,
+                deps.experimentalTemporalAwareness,
             );
             output.system.push(guidance);
             sessionLog(
diff --git a/packages/plugin/src/hooks/magic-context/temporal-awareness.test.ts b/packages/plugin/src/hooks/magic-context/temporal-awareness.test.ts
diff --git a/packages/plugin/src/hooks/magic-context/temporal-awareness.ts b/packages/plugin/src/hooks/magic-context/temporal-awareness.ts
diff --git a/packages/plugin/src/hooks/magic-context/transform-compartment-phase.ts b/packages/plugin/src/hooks/magic-context/transform-compartment-phase.ts
diff --git a/packages/plugin/src/hooks/magic-context/transform.ts b/packages/plugin/src/hooks/magic-context/transform.ts
