fix(agent-core-v2): re-remind uninjected AGENTS.md on directory access after context loss

.changeset/agents-md-access-reminder.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Re-show directory AGENTS.md reminders when the agent next touches the directory after context compaction, instead of right after compaction.

packages/agent-core-v2/docs/state-manifest.d.ts

@@ -27,7 +27,7 @@
 // references become '(circular)', and class instances collapse to a '(ClassName)'
 // marker — the wire shape of an entry is the JSON projection of the type here.
 //
-// Index (App: 0 keys · Workspace: 6 keys · Session: 9 keys · Agent: 83 keys)
+// Index (App: 0 keys · Workspace: 6 keys · Session: 9 keys · Agent: 82 keys)
 //   App
 //   Workspace
 //     workspaceDirs.ephemeralDirs          src/workspace/workspaceDirs/workspaceDirsService.ts
@@ -55,7 +55,6 @@
 //     agentPlugin.sessionStartRefreshPending          src/agent/plugin/agentPluginService.ts
 //     agentsMdReminder.cwd                            src/agent/agentsMdReminder/agentsMdReminderService.ts
 //     agentsMdReminder.known                          src/agent/agentsMdReminder/agentsMdReminderService.ts
-//     agentsMdReminder.pending                        src/agent/agentsMdReminder/agentsMdReminderService.ts
 //     agentsMdReminder.seeded                         src/agent/agentsMdReminder/agentsMdReminderService.ts
 //     contextMemory                                   src/agent/contextMemory/contextOps.ts
 //     contextProjector.lastRepairSignature            src/agent/contextProjector/contextProjectorService.ts
@@ -1041,7 +1040,6 @@ export interface AgentStateSnapshot {
   // src/agent/agentsMdReminder/agentsMdReminderService.ts
   'agentsMdReminder.cwd': string | undefined;
   'agentsMdReminder.known': Set<string>;
-  'agentsMdReminder.pending': Set<string>;
   'agentsMdReminder.seeded': boolean;
   // src/agent/contextMemory/contextOps.ts
   // replayable · durable · undoable — folds: ContextAppendMessage, ContextAppendLoopEvent, ContextClear, ContextApplyCompaction

packages/agent-core-v2/src/agent/agentsMdReminder/agentsMdReminderService.ts

@@ -11,6 +11,8 @@ import { ITelemetryService } from '#/app/telemetry/telemetry';
 import type { IHostFileSystem } from '#/os/interface/hostFileSystem';
 import type { HostFsChange } from '#/os/interface/hostFsWatch';
 import { IAgentRuntimeService } from '#/agent/runtimeBinding/agentRuntime';
+import { IAgentContextMemoryService } from '#/agent/contextMemory/contextMemory';
+import { IAgentLoopService } from '#/agent/loop/loop';
 import { ISessionContext } from '#/session/sessionContext/sessionContext';
 import { ISessionInstructionsProvider } from '#/session/sessionInstructions/instructionsProvider';
 import { normalizeUserPath } from '#/tool/path-access';
@@ -26,10 +28,6 @@ import {
 import { profileKey } from '#/agent/profile/profileOps';
 import { IAgentStateService } from '#/agent/state/agentState';
 import { IAgentReminderService } from '#/features/reminder/reminderService';
-import type {
-  ContextInjectionContext,
-  ContextInjectionResult,
-} from '#/features/reminder/types';
 import { IAgentScopeContext } from '#/agent/scopeContext/scopeContext';
 import { IAgentToolExecutorService } from '#/agent/toolExecutor/toolExecutor';
 import type { ToolDidExecuteContext } from '#/agent/toolExecutor/toolHooks';
@@ -42,14 +40,12 @@ const AGENTS_MD_BASENAMES: ReadonlySet<string> = new Set<string>(AGENTS_MD_PLAIN
 
 const BASH_PARSE_OPTIONS = { timeoutMs: 20, maxNodes: 10_000 } as const;
 
+const DISCOVERY_REMINDER_VARIANT = 'agents_md';
+
 export const agentsMdReminderKnownKey = defineState<Set<string>>(
   'agentsMdReminder.known',
   () => new Set(),
 );
-export const agentsMdReminderPendingKey = defineState<Set<string>>(
-  'agentsMdReminder.pending',
-  () => new Set(),
-);
 export const agentsMdReminderCwdKey = defineState<string | undefined>(
   'agentsMdReminder.cwd',
   () => undefined as string | undefined,
@@ -68,6 +64,8 @@ export class AgentAgentsMdReminderService
   constructor(
     @IAgentToolExecutorService toolExecutor: IAgentToolExecutorService,
     @IAgentReminderService private readonly reminder: IAgentReminderService,
+    @IAgentContextMemoryService private readonly contextMemory: IAgentContextMemoryService,
+    @IAgentLoopService loop: IAgentLoopService,
     @IAgentScopeContext private readonly scopeContext: IAgentScopeContext,
     @IAgentStateService private readonly states: IAgentStateService,
     @ISessionContext private readonly sessionContext: ISessionContext,
@@ -80,19 +78,19 @@ export class AgentAgentsMdReminderService
   ) {
     super();
     this.states.contributeState(agentsMdReminderKnownKey);
-    this.states.contributeState(agentsMdReminderPendingKey);
     this.states.contributeState(agentsMdReminderCwdKey);
     this.states.contributeState(agentsMdReminderSeededKey);
-    this._register(
-      this.reminder.register<readonly string[]>('agents_md', (context) =>
-        this.injectReminder(context),
-      ),
-    );
     this._register(
       this.instructions.onDidChange((changes) => {
         this.announceChanged(changes);
       }),
     );
+    this._register(
+      loop.hooks.onWillBeginStep.register('agentsMdReminder', async (_ctx, next) => {
+        this.claimed.clear();
+        await next();
+      }),
+    );
     this._register(
       this.dispatcher.hooks.onDidRestore.register('agentsMdReminder', async (_ctx, next) => {
         const profile = this.states.get(profileKey);
@@ -113,9 +111,6 @@ export class AgentAgentsMdReminderService
     const known = new Set(this.known);
     for (const path of paths) known.add(normalize(path));
     this.states.set(agentsMdReminderKnownKey, known);
-    const pending = new Set(this.pending);
-    for (const path of paths) pending.delete(normalize(path));
-    this.states.set(agentsMdReminderPendingKey, pending);
     this.states.set(agentsMdReminderCwdKey, cwd);
     this.states.set(agentsMdReminderSeededKey, true);
   }
@@ -135,9 +130,6 @@ export class AgentAgentsMdReminderService
     this.markKnown(
       list.filter((change) => change.action === 'modified').map((change) => change.path),
     );
-    this.markPending(
-      list.filter((change) => change.action === 'created').map((change) => change.path),
-    );
     this.markDeleted(
       list.filter((change) => change.action === 'deleted').map((change) => change.path),
     );
@@ -149,28 +141,22 @@ export class AgentAgentsMdReminderService
     return this.states.get(agentsMdReminderKnownKey);
   }
 
-  private get pending(): Set<string> {
-    return this.states.get(agentsMdReminderPendingKey);
-  }
-
   private get agentCwd(): string {
     return this.states.get(agentsMdReminderCwdKey) ?? this.sessionContext.cwd;
   }
 
-  private hasPath(path: string): boolean {
-    return this.known.has(path) || this.pending.has(path);
-  }
-
-  private injectReminder(
-    context: ContextInjectionContext<readonly string[]>,
-  ): ContextInjectionResult<readonly string[]> | undefined {
-    const known = this.known;
-    const pending = [...this.pending].filter((path) => !known.has(path));
-    if (pending.length === 0) return undefined;
-    const covered = context.lastDisclosure ?? [];
-    const fresh = pending.filter((path) => !covered.includes(path));
-    if (fresh.length === 0) return undefined;
-    return { content: reminderText(fresh), disclosure: pending };
+  private inContextCoverage(): Set<string> {
+    const covered = new Set<string>();
+    for (const message of this.contextMemory.get()) {
+      if (message.origin?.kind !== 'injection') continue;
+      if (message.origin.variant !== DISCOVERY_REMINDER_VARIANT) continue;
+      const disclosure = message.origin.disclosure;
+      if (!Array.isArray(disclosure)) continue;
+      for (const path of disclosure) {
+        if (typeof path === 'string') covered.add(normalize(path));
+      }
+    }
+    return covered;
   }
 
   private async ensureSeeded(): Promise<void> {
@@ -191,67 +177,54 @@ export class AgentAgentsMdReminderService
   private async probeAndRemind(ctx: ToolDidExecuteContext): Promise<void> {
     if (ctx.outcome !== 'executed') return;
     const discovered: string[] = [];
+    let keepClaims = false;
     try {
       await this.ensureSeeded();
       const { dirs, selfKnown } = this.targetDirs(ctx);
       const selfKnownSet = new Set(selfKnown);
       for (const dir of dirs) {
         for (const path of await this.probeDir(dir)) {
-          if (this.hasPath(path) || this.claimed.has(path) || selfKnownSet.has(path)) continue;
+          if (this.known.has(path) || this.claimed.has(path) || selfKnownSet.has(path)) continue;
           this.claimed.add(path);
           discovered.push(path);
         }
       }
-      if (discovered.length === 0) {
-        this.markKnown(selfKnown);
-        return;
-      }
+      this.markKnown(selfKnown);
+      if (discovered.length === 0) return;
+      const covered = this.inContextCoverage();
+      const fresh = discovered.filter((path) => !covered.has(path));
+      if (fresh.length === 0) return;
       const properties: AgentsMdReminderShownEvent = {
         turn_id: ctx.turnId,
         tool_name: ctx.toolCall.name,
-        reminded_count: discovered.length,
+        reminded_count: fresh.length,
         trace_id: ctx.trace?.traceId,
       };
       this.telemetry.track2('agents_md_reminder_shown', properties);
-      this.markKnown(selfKnown);
-      this.markPending(discovered);
+      this.reminder.notify(reminderText(fresh), {
+        variant: DISCOVERY_REMINDER_VARIANT,
+        disclosure: fresh,
+      });
+      keepClaims = true;
     } catch {} finally {
-      for (const path of discovered) this.claimed.delete(path);
+      if (!keepClaims) {
+        for (const path of discovered) this.claimed.delete(path);
+      }
     }
   }
 
   private markKnown(paths: readonly string[]): void {
     if (paths.length === 0) return;
     const known = new Set(this.known);
-    const pending = new Set(this.pending);
-    for (const path of paths) {
-      known.add(path);
-      pending.delete(path);
-    }
+    for (const path of paths) known.add(path);
     this.states.set(agentsMdReminderKnownKey, known);
-    this.states.set(agentsMdReminderPendingKey, pending);
-  }
-
-  private markPending(paths: readonly string[]): void {
-    if (paths.length === 0) return;
-    const known = this.known;
-    const pending = new Set(this.pending);
-    for (const path of paths) {
-      if (!known.has(path)) pending.add(path);
-    }
-    this.states.set(agentsMdReminderPendingKey, pending);
   }
 
   private markDeleted(paths: readonly string[]): void {
     if (paths.length === 0) return;
     const known = new Set(this.known);
-    const pending = new Set(this.pending);
-    for (const path of paths) {
-      known.delete(path);
-      pending.delete(path);
-    }
+    for (const path of paths) known.delete(path);
     this.states.set(agentsMdReminderKnownKey, known);
-    this.states.set(agentsMdReminderPendingKey, pending);
   }
 
   private targetDirs(ctx: ToolDidExecuteContext): { dirs: string[]; selfKnown: string[] } {
@@ -339,7 +312,7 @@ export class AgentAgentsMdReminderService
       const found: string[] = [];
       for (const chainDir of chain) {
         const candidates = agentsMdCandidatePaths(chainDir);
-        if (candidates.every((candidate) => this.hasPath(normalize(candidate)))) continue;
+        if (candidates.every((candidate) => this.known.has(normalize(candidate)))) continue;
         for (const path of await findAgentsMdInDir(deps, chainDir)) {
           found.push(normalize(path));
         }

packages/agent-core-v2/src/app/telemetry/events.ts

@@ -958,7 +958,7 @@ export const telemetryEventDefinitions = {
   }),
   agents_md_reminder_shown: defineAgentTelemetryEvent<AgentsMdReminderShownEvent>({
     owner: 'kimi-code',
-    comment: 'An AGENTS.md discovery reminder is queued for context injection after a tool call.',
+    comment: 'An AGENTS.md discovery reminder is appended to the context after a tool call.',
     properties: {
       turn_id: 'Per-agent turn index (main or subagent); pair with agent_id to locate a turn within a session',
       tool_name: 'Registered tool name whose execution discovered the file',

packages/agent-core-v2/src/features/reminder/reminderService.ts

@@ -69,6 +69,7 @@ function appendReminder(
       kind: 'injection',
       variant: notification.variant,
       ownerPromptId: notification.ownerPromptId,
+      disclosure: notification.disclosure,
     },
   });
 }

packages/agent-core-v2/src/features/reminder/types.ts

@@ -40,4 +40,5 @@ export interface ReminderRegistration extends IDisposable {}
 export interface ReminderNotification {
   readonly variant: string;
   readonly ownerPromptId?: string;
+  readonly disclosure?: unknown;
 }