@xortex/xcode 3.0.0

package/services/extractMemories/extractMemories.ts

@@ -0,0 +1,517 @@
+/**
+ * Extracts durable memories from the current session transcript
+ * and writes them to the auto-memory directory (~/.claude/projects/<path>/memory/).
+ *
+ * It runs once at the end of each complete query loop (when the model produces
+ * a final response with no tool calls) via handleStopHooks in stopHooks.ts.
+ *
+ * Uses the forked agent pattern (runForkedAgent) — a perfect fork of the main
+ * conversation that shares the parent's prompt cache.
+ *
+ * State is closure-scoped inside initExtractMemories() rather than module-level,
+ * following the same pattern as confidenceRating.ts. Tests call
+ * initExtractMemories() in beforeEach to get a fresh closure.
+ */
+
+import { feature } from 'bun:bundle'
+import { basename } from 'path'
+import { getIsRemoteMode } from '../../bootstrap/state.js'
+import type { CanUseToolFn } from '../../hooks/useCanUseTool.js'
+import { ENTRYPOINT_NAME } from '../../memdir/memdir.js'
+import {
+  formatMemoryManifest,
+  scanMemoryFiles,
+} from '../../memdir/memoryScan.js'
+import {
+  getAutoMemPath,
+  isAutoMemoryEnabled,
+  isAutoMemPath,
+} from '../../memdir/paths.js'
+import type { Tool } from '../../Tool.js'
+import { BASH_TOOL_NAME } from '../../tools/BashTool/toolName.js'
+import { FILE_EDIT_TOOL_NAME } from '../../tools/FileEditTool/constants.js'
+import { FILE_READ_TOOL_NAME } from '../../tools/FileReadTool/prompt.js'
+import { FILE_WRITE_TOOL_NAME } from '../../tools/FileWriteTool/prompt.js'
+import { GLOB_TOOL_NAME } from '../../tools/GlobTool/prompt.js'
+import { GREP_TOOL_NAME } from '../../tools/GrepTool/prompt.js'
+import { REPL_TOOL_NAME } from '../../tools/REPLTool/constants.js'
+import type {
+  AssistantMessage,
+  Message,
+  SystemLocalCommandMessage,
+  SystemMessage,
+} from '../../types/message.js'
+import { createAbortController } from '../../utils/abortController.js'
+import { count, uniq } from '../../utils/array.js'
+import { logForDebugging } from '../../utils/debug.js'
+import {
+  createCacheSafeParams,
+  runForkedAgent,
+} from '../../utils/forkedAgent.js'
+import type { REPLHookContext } from '../../utils/hooks/postSamplingHooks.js'
+import {
+  createMemorySavedMessage,
+  createUserMessage,
+} from '../../utils/messages.js'
+import { getFeatureValue_CACHED_MAY_BE_STALE } from '../analytics/growthbook.js'
+import { logEvent } from '../analytics/index.js'
+import { sanitizeToolNameForAnalytics } from '../analytics/metadata.js'
+import {
+  buildExtractAutoOnlyPrompt,
+  buildExtractCombinedPrompt,
+} from './prompts.js'
+
+import { xmemClient } from '../../utils/xmem.js'
+
+/* eslint-disable @typescript-eslint/no-require-imports */
+const teamMemPaths = feature('TEAMMEM')
+  ? (require('../../memdir/teamMemPaths.js') as typeof import('../../memdir/teamMemPaths.js'))
+  : null
+/* eslint-enable @typescript-eslint/no-require-imports */
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Returns true if a message is visible to the model (sent in API calls).
+ * Excludes progress, system, and attachment messages.
+ */
+function isModelVisibleMessage(message: Message): boolean {
+  return message.type === 'user' || message.type === 'assistant'
+}
+
+function countModelVisibleMessagesSince(
+  messages: Message[],
+  sinceUuid: string | undefined,
+): number {
+  if (sinceUuid === null || sinceUuid === undefined) {
+    return count(messages, isModelVisibleMessage)
+  }
+
+  let foundStart = false
+  let n = 0
+  for (const message of messages) {
+    if (!foundStart) {
+      if (message.uuid === sinceUuid) {
+        foundStart = true
+      }
+      continue
+    }
+    if (isModelVisibleMessage(message)) {
+      n++
+    }
+  }
+  // If sinceUuid was not found (e.g., removed by context compaction),
+  // fall back to counting all model-visible messages rather than returning 0
+  // which would permanently disable extraction for the rest of the session.
+  if (!foundStart) {
+    return count(messages, isModelVisibleMessage)
+  }
+  return n
+}
+
+/**
+ * Returns true if any assistant message after the cursor UUID contains a
+ * Write/Edit tool_use block targeting an auto-memory path.
+ *
+ * The main agent's prompt has full save instructions — when it writes
+ * memories, the forked extraction is redundant. runExtraction skips the
+ * agent and advances the cursor past this range, making the main agent
+ * and the background agent mutually exclusive per turn.
+ */
+function hasMemoryWritesSince(
+  messages: Message[],
+  sinceUuid: string | undefined,
+): boolean {
+  let foundStart = sinceUuid === undefined
+  for (const message of messages) {
+    if (!foundStart) {
+      if (message.uuid === sinceUuid) {
+        foundStart = true
+      }
+      continue
+    }
+    if (message.type !== 'assistant') {
+      continue
+    }
+    const content = (message as AssistantMessage).message.content
+    if (!Array.isArray(content)) {
+      continue
+    }
+    for (const block of content) {
+      const filePath = getWrittenFilePath(block)
+      if (filePath !== undefined && isAutoMemPath(filePath)) {
+        return true
+      }
+    }
+  }
+  return false
+}
+
+// ============================================================================
+// Tool Permissions
+// ============================================================================
+
+function denyAutoMemTool(tool: Tool, reason: string) {
+  logForDebugging(`[autoMem] denied ${tool.name}: ${reason}`)
+  logEvent('tengu_auto_mem_tool_denied', {
+    tool_name: sanitizeToolNameForAnalytics(tool.name),
+  })
+  return {
+    behavior: 'deny' as const,
+    message: reason,
+    decisionReason: { type: 'other' as const, reason },
+  }
+}
+
+/**
+ * Creates a canUseTool function that allows Read/Grep/Glob (unrestricted),
+ * read-only Bash commands, and Edit/Write only for paths within the
+ * auto-memory directory. Shared by extractMemories and autoDream.
+ */
+export function createAutoMemCanUseTool(memoryDir: string): CanUseToolFn {
+  return async (tool: Tool, input: Record<string, unknown>) => {
+    // Allow REPL — when REPL mode is enabled (ant-default), primitive tools
+    // are hidden from the tool list so the forked agent calls REPL instead.
+    // REPL's VM context re-invokes this canUseTool for each inner primitive
+    // (toolWrappers.ts createToolWrapper), so the Read/Bash/Edit/Write checks
+    // below still gate the actual file and shell operations. Giving the fork a
+    // different tool list would break prompt cache sharing (tools are part of
+    // the cache key — see CacheSafeParams in forkedAgent.ts).
+    if (tool.name === REPL_TOOL_NAME) {
+      return { behavior: 'allow' as const, updatedInput: input }
+    }
+
+    // Allow Read/Grep/Glob unrestricted — all inherently read-only
+    if (
+      tool.name === FILE_READ_TOOL_NAME ||
+      tool.name === GREP_TOOL_NAME ||
+      tool.name === GLOB_TOOL_NAME
+    ) {
+      return { behavior: 'allow' as const, updatedInput: input }
+    }
+
+    // Allow Bash only for commands that pass BashTool.isReadOnly.
+    // `tool` IS BashTool here — no static import needed.
+    if (tool.name === BASH_TOOL_NAME) {
+      const parsed = tool.inputSchema.safeParse(input)
+      if (parsed.success && tool.isReadOnly(parsed.data)) {
+        return { behavior: 'allow' as const, updatedInput: input }
+      }
+      return denyAutoMemTool(
+        tool,
+        'Only read-only shell commands are permitted in this context (ls, find, grep, cat, stat, wc, head, tail, and similar)',
+      )
+    }
+
+    if (
+      (tool.name === FILE_EDIT_TOOL_NAME ||
+        tool.name === FILE_WRITE_TOOL_NAME) &&
+      'file_path' in input
+    ) {
+      const filePath = input.file_path
+      if (typeof filePath === 'string' && isAutoMemPath(filePath)) {
+        return { behavior: 'allow' as const, updatedInput: input }
+      }
+    }
+
+    return denyAutoMemTool(
+      tool,
+      `only ${FILE_READ_TOOL_NAME}, ${GREP_TOOL_NAME}, ${GLOB_TOOL_NAME}, read-only ${BASH_TOOL_NAME}, and ${FILE_EDIT_TOOL_NAME}/${FILE_WRITE_TOOL_NAME} within ${memoryDir} are allowed`,
+    )
+  }
+}
+
+// ============================================================================
+// Extract file paths from agent output
+// ============================================================================
+
+/**
+ * Extract file_path from a tool_use block's input, if present.
+ * Returns undefined when the block is not an Edit/Write tool use or has no file_path.
+ */
+function getWrittenFilePath(block: {
+  type: string
+  name?: string
+  input?: unknown
+}): string | undefined {
+  if (
+    block.type !== 'tool_use' ||
+    (block.name !== FILE_EDIT_TOOL_NAME && block.name !== FILE_WRITE_TOOL_NAME)
+  ) {
+    return undefined
+  }
+  const input = block.input
+  if (typeof input === 'object' && input !== null && 'file_path' in input) {
+    const fp = (input as { file_path: unknown }).file_path
+    return typeof fp === 'string' ? fp : undefined
+  }
+  return undefined
+}
+
+function extractWrittenPaths(agentMessages: Message[]): string[] {
+  const paths: string[] = []
+  for (const message of agentMessages) {
+    if (message.type !== 'assistant') {
+      continue
+    }
+    const content = (message as AssistantMessage).message.content
+    if (!Array.isArray(content)) {
+      continue
+    }
+    for (const block of content) {
+      const filePath = getWrittenFilePath(block)
+      if (filePath !== undefined) {
+        paths.push(filePath)
+      }
+    }
+  }
+  return uniq(paths)
+}
+
+// ============================================================================
+// Initialization & Closure-scoped State
+// ============================================================================
+
+type AppendSystemMessageFn = (
+  msg: Exclude<SystemMessage, SystemLocalCommandMessage>,
+) => void
+
+/** The active extractor function, set by initExtractMemories(). */
+let extractor:
+  | ((
+      context: REPLHookContext,
+      appendSystemMessage?: AppendSystemMessageFn,
+    ) => Promise<void>)
+  | null = null
+
+/** The active drain function, set by initExtractMemories(). No-op until init. */
+let drainer: (timeoutMs?: number) => Promise<void> = async () => {}
+
+/**
+ * Initialize the memory extraction system.
+ * Creates a fresh closure that captures all mutable state (cursor position,
+ * overlap guard, pending context). Call once at startup alongside
+ * initConfidenceRating/initPromptCoaching, or per-test in beforeEach.
+ */
+export function initExtractMemories(): void {
+  // --- Closure-scoped mutable state ---
+
+  /** Every promise handed out by the extractor that hasn't settled yet.
+   *  Coalesced calls that stash-and-return add fast-resolving promises
+   *  (harmless); the call that starts real work adds a promise covering the
+   *  full trailing-run chain via runExtraction's recursive finally. */
+  const inFlightExtractions = new Set<Promise<void>>()
+
+  /** UUID of the last message processed — cursor so each run only
+   *  considers messages added since the previous extraction. */
+  let lastMemoryMessageUuid: string | undefined
+
+  /** One-shot flag: once we log that the gate is disabled, don't repeat. */
+  let hasLoggedGateFailure = false
+
+  /** True while runExtraction is executing — prevents overlapping runs. */
+  let inProgress = false
+
+  /** Counts eligible turns since the last extraction run. Resets to 0 after each run. */
+  let turnsSinceLastExtraction = 0
+
+  /** When a call arrives during an in-progress run, we stash the context here
+   *  and run one trailing extraction after the current one finishes. */
+  let pendingContext:
+    | {
+        context: REPLHookContext
+        appendSystemMessage?: AppendSystemMessageFn
+      }
+    | undefined
+
+  // --- Inner extraction logic ---
+
+  async function runExtraction({
+    context,
+    appendSystemMessage,
+    isTrailingRun,
+  }: {
+    context: REPLHookContext
+    appendSystemMessage?: AppendSystemMessageFn
+    isTrailingRun?: boolean
+  }): Promise<void> {
+    const { messages } = context
+    
+    let foundStart = lastMemoryMessageUuid === undefined
+    const newMessages: Message[] = []
+    for (const message of messages) {
+      if (!foundStart) {
+        if (message.uuid === lastMemoryMessageUuid) {
+          foundStart = true
+        }
+        continue
+      }
+      if (isModelVisibleMessage(message)) {
+        newMessages.push(message)
+      }
+    }
+
+    if (newMessages.length === 0) return
+
+    inProgress = true
+    try {
+      let userQuery = ''
+      let agentResponse = ''
+
+      for (const msg of newMessages) {
+        if (msg.type === 'user') {
+          const content = msg.message.content
+          const text = typeof content === 'string' ? content : (Array.isArray(content) ? content.map(c => c.type === 'text' ? c.text : '').join('\\n') : '')
+          userQuery += text + '\\n'
+        } else if (msg.type === 'assistant') {
+          const content = msg.message.content
+          const text = typeof content === 'string' ? content : (Array.isArray(content) ? content.map(c => c.type === 'text' ? c.text : '').join('\\n') : '')
+          agentResponse += text + '\\n'
+        }
+      }
+
+      if (userQuery.trim() || agentResponse.trim()) {
+        const logMsg = `[XMem Ingest] Ingesting memory... user_id: 'default_user', query: ${userQuery.trim().substring(0, 50)}...\\n`
+        logForDebugging(logMsg)
+        console.error(logMsg)
+
+        await xmemClient.ingest({
+          user_query: userQuery.trim() || 'No user query',
+          agent_response: agentResponse.trim() || 'No agent response',
+          user_id: 'default_user'
+        })
+
+        const successMsg = `[XMem Ingest] Successfully ingested memory.\\n`
+        logForDebugging(successMsg)
+        console.error(successMsg)
+      }
+
+      const lastMessage = messages.at(-1)
+      if (lastMessage?.uuid) {
+        lastMemoryMessageUuid = lastMessage.uuid
+      }
+    } catch (error) {
+      logForDebugging(`[extractMemories] xmem ingest error: ${error}`)
+    } finally {
+      inProgress = false
+
+      const trailing = pendingContext
+      pendingContext = undefined
+      if (trailing) {
+        await runExtraction({
+          context: trailing.context,
+          appendSystemMessage: trailing.appendSystemMessage,
+          isTrailingRun: true,
+        })
+      }
+    }
+  }
+
+  // --- Public entry point (captured by extractor) ---
+
+  async function executeExtractMemoriesImpl(
+    context: REPLHookContext,
+    appendSystemMessage?: AppendSystemMessageFn,
+  ): Promise<void> {
+    console.error(`[Extract Debug] executeExtractMemoriesImpl called. agentId: ${context.toolUseContext.agentId}\\n`)
+
+    // Only run for the main agent, not subagents
+    if (context.toolUseContext.agentId) {
+      return
+    }
+
+    const { getInitialSettings } = await import('../../utils/settings/settings.js')
+    const isXmemEnabled = getInitialSettings().xmemMemoryEnabled
+    
+    console.error(`[Extract Debug] isXmemEnabled: ${isXmemEnabled}\\n`)
+
+    if (!isXmemEnabled) {
+      if (!getFeatureValue_CACHED_MAY_BE_STALE('tengu_passport_quail', false)) {
+        if (process.env.USER_TYPE === 'ant' && !hasLoggedGateFailure) {
+          hasLoggedGateFailure = true
+          logEvent('tengu_extract_memories_gate_disabled', {})
+        }
+        console.error(`[Extract Debug] aborted: tengu_passport_quail check failed\\n`)
+        return
+      }
+
+      // Check auto-memory is enabled
+      if (!isAutoMemoryEnabled()) {
+        console.error(`[Extract Debug] aborted: auto-memory not enabled\\n`)
+        return
+      }
+    }
+
+    // Skip in remote mode
+    if (getIsRemoteMode()) {
+      console.error(`[Extract Debug] aborted: remote mode\\n`)
+      return
+    }
+
+    // If an extraction is already in progress, stash this context for a
+    // trailing run (overwrites any previously stashed context — only the
+    // latest matters since it has the most messages).
+    if (inProgress) {
+      logForDebugging(
+        '[extractMemories] extraction in progress — stashing for trailing run',
+      )
+      logEvent('tengu_extract_memories_coalesced', {})
+      pendingContext = { context, appendSystemMessage }
+      console.error(`[Extract Debug] aborted: inProgress (stashed)\\n`)
+      return
+    }
+
+    console.error(`[Extract Debug] proceeding to runExtraction\\n`)
+
+    await runExtraction({ context, appendSystemMessage })
+  }
+
+  extractor = async (context, appendSystemMessage) => {
+    const p = executeExtractMemoriesImpl(context, appendSystemMessage)
+    inFlightExtractions.add(p)
+    try {
+      await p
+    } finally {
+      inFlightExtractions.delete(p)
+    }
+  }
+
+  drainer = async (timeoutMs = 60_000) => {
+    if (inFlightExtractions.size === 0) return
+    await Promise.race([
+      Promise.all(inFlightExtractions).catch(() => {}),
+      // eslint-disable-next-line no-restricted-syntax -- sleep() has no .unref(); timer must not block exit
+      new Promise<void>(r => setTimeout(r, timeoutMs).unref()),
+    ])
+  }
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Run memory extraction at the end of a query loop.
+ * Called fire-and-forget from handleStopHooks, alongside prompt suggestion/coaching.
+ * No-ops until initExtractMemories() has been called.
+ */
+export async function executeExtractMemories(
+  context: REPLHookContext,
+  appendSystemMessage?: AppendSystemMessageFn,
+): Promise<void> {
+  await extractor?.(context, appendSystemMessage)
+}
+
+/**
+ * Awaits all in-flight extractions (including trailing stashed runs) with a
+ * soft timeout. Called by print.ts after the response is flushed but before
+ * gracefulShutdownSync, so the forked agent completes before the 5s shutdown
+ * failsafe kills it. No-op until initExtractMemories() has been called.
+ */
+export async function drainPendingExtraction(
+  timeoutMs?: number,
+): Promise<void> {
+  await drainer(timeoutMs)
+}

package/services/extractMemories/prompts.ts

@@ -0,0 +1,154 @@
+/**
+ * Prompt templates for the background memory extraction agent.
+ *
+ * The extraction agent runs as a perfect fork of the main conversation — same
+ * system prompt, same message prefix. The main agent's system prompt always
+ * has full save instructions; when the main agent writes memories itself,
+ * extractMemories.ts skips that turn (hasMemoryWritesSince). This prompt
+ * fires only when the main agent didn't write, so the save-criteria here
+ * overlap the system prompt's harmlessly.
+ */
+
+import { feature } from 'bun:bundle'
+import {
+  MEMORY_FRONTMATTER_EXAMPLE,
+  TYPES_SECTION_COMBINED,
+  TYPES_SECTION_INDIVIDUAL,
+  WHAT_NOT_TO_SAVE_SECTION,
+} from '../../memdir/memoryTypes.js'
+import { BASH_TOOL_NAME } from '../../tools/BashTool/toolName.js'
+import { FILE_EDIT_TOOL_NAME } from '../../tools/FileEditTool/constants.js'
+import { FILE_READ_TOOL_NAME } from '../../tools/FileReadTool/prompt.js'
+import { FILE_WRITE_TOOL_NAME } from '../../tools/FileWriteTool/prompt.js'
+import { GLOB_TOOL_NAME } from '../../tools/GlobTool/prompt.js'
+import { GREP_TOOL_NAME } from '../../tools/GrepTool/prompt.js'
+
+/**
+ * Shared opener for both extract-prompt variants.
+ */
+function opener(newMessageCount: number, existingMemories: string): string {
+  const manifest =
+    existingMemories.length > 0
+      ? `\n\n## Existing memory files\n\n${existingMemories}\n\nCheck this list before writing — update an existing file rather than creating a duplicate.`
+      : ''
+  return [
+    `You are now acting as the memory extraction subagent. Analyze the most recent ~${newMessageCount} messages above and use them to update your persistent memory systems.`,
+    '',
+    `Available tools: ${FILE_READ_TOOL_NAME}, ${GREP_TOOL_NAME}, ${GLOB_TOOL_NAME}, read-only ${BASH_TOOL_NAME} (ls/find/cat/stat/wc/head/tail and similar), and ${FILE_EDIT_TOOL_NAME}/${FILE_WRITE_TOOL_NAME} for paths inside the memory directory only. ${BASH_TOOL_NAME} rm is not permitted. All other tools — MCP, Agent, write-capable ${BASH_TOOL_NAME}, etc — will be denied.`,
+    '',
+    `You have a limited turn budget. ${FILE_EDIT_TOOL_NAME} requires a prior ${FILE_READ_TOOL_NAME} of the same file, so the efficient strategy is: turn 1 — issue all ${FILE_READ_TOOL_NAME} calls in parallel for every file you might update; turn 2 — issue all ${FILE_WRITE_TOOL_NAME}/${FILE_EDIT_TOOL_NAME} calls in parallel. Do not interleave reads and writes across multiple turns.`,
+    '',
+    `You MUST only use content from the last ~${newMessageCount} messages to update your persistent memories. Do not waste any turns attempting to investigate or verify that content further — no grepping source files, no reading code to confirm a pattern exists, no git commands.` +
+      manifest,
+  ].join('\n')
+}
+
+/**
+ * Build the extraction prompt for auto-only memory (no team memory).
+ * Four-type taxonomy, no scope guidance (single directory).
+ */
+export function buildExtractAutoOnlyPrompt(
+  newMessageCount: number,
+  existingMemories: string,
+  skipIndex = false,
+): string {
+  const howToSave = skipIndex
+    ? [
+        '## How to save memories',
+        '',
+        'Write each memory to its own file (e.g., `user_role.md`, `feedback_testing.md`) using this frontmatter format:',
+        '',
+        ...MEMORY_FRONTMATTER_EXAMPLE,
+        '',
+        '- Organize memory semantically by topic, not chronologically',
+        '- Update or remove memories that turn out to be wrong or outdated',
+        '- Do not write duplicate memories. First check if there is an existing memory you can update before writing a new one.',
+      ]
+    : [
+        '## How to save memories',
+        '',
+        'Saving a memory is a two-step process:',
+        '',
+        '**Step 1** — write the memory to its own file (e.g., `user_role.md`, `feedback_testing.md`) using this frontmatter format:',
+        '',
+        ...MEMORY_FRONTMATTER_EXAMPLE,
+        '',
+        '**Step 2** — add a pointer to that file in `MEMORY.md`. `MEMORY.md` is an index, not a memory — each entry should be one line, under ~150 characters: `- [Title](file.md) — one-line hook`. It has no frontmatter. Never write memory content directly into `MEMORY.md`.',
+        '',
+        '- `MEMORY.md` is always loaded into your system prompt — lines after 200 will be truncated, so keep the index concise',
+        '- Organize memory semantically by topic, not chronologically',
+        '- Update or remove memories that turn out to be wrong or outdated',
+        '- Do not write duplicate memories. First check if there is an existing memory you can update before writing a new one.',
+      ]
+
+  return [
+    opener(newMessageCount, existingMemories),
+    '',
+    'If the user explicitly asks you to remember something, save it immediately as whichever type fits best. If they ask you to forget something, find and remove the relevant entry.',
+    '',
+    ...TYPES_SECTION_INDIVIDUAL,
+    ...WHAT_NOT_TO_SAVE_SECTION,
+    '',
+    ...howToSave,
+  ].join('\n')
+}
+
+/**
+ * Build the extraction prompt for combined auto + team memory.
+ * Four-type taxonomy with per-type <scope> guidance (directory choice
+ * is baked into each type block, no separate routing section needed).
+ */
+export function buildExtractCombinedPrompt(
+  newMessageCount: number,
+  existingMemories: string,
+  skipIndex = false,
+): string {
+  if (!feature('TEAMMEM')) {
+    return buildExtractAutoOnlyPrompt(
+      newMessageCount,
+      existingMemories,
+      skipIndex,
+    )
+  }
+
+  const howToSave = skipIndex
+    ? [
+        '## How to save memories',
+        '',
+        "Write each memory to its own file in the chosen directory (private or team, per the type's scope guidance) using this frontmatter format:",
+        '',
+        ...MEMORY_FRONTMATTER_EXAMPLE,
+        '',
+        '- Organize memory semantically by topic, not chronologically',
+        '- Update or remove memories that turn out to be wrong or outdated',
+        '- Do not write duplicate memories. First check if there is an existing memory you can update before writing a new one.',
+      ]
+    : [
+        '## How to save memories',
+        '',
+        'Saving a memory is a two-step process:',
+        '',
+        "**Step 1** — write the memory to its own file in the chosen directory (private or team, per the type's scope guidance) using this frontmatter format:",
+        '',
+        ...MEMORY_FRONTMATTER_EXAMPLE,
+        '',
+        "**Step 2** — add a pointer to that file in the same directory's `MEMORY.md`. Each directory (private and team) has its own `MEMORY.md` index — each entry should be one line, under ~150 characters: `- [Title](file.md) — one-line hook`. They have no frontmatter. Never write memory content directly into a `MEMORY.md`.",
+        '',
+        '- Both `MEMORY.md` indexes are loaded into your system prompt — lines after 200 will be truncated, so keep them concise',
+        '- Organize memory semantically by topic, not chronologically',
+        '- Update or remove memories that turn out to be wrong or outdated',
+        '- Do not write duplicate memories. First check if there is an existing memory you can update before writing a new one.',
+      ]
+
+  return [
+    opener(newMessageCount, existingMemories),
+    '',
+    'If the user explicitly asks you to remember something, save it immediately as whichever type fits best. If they ask you to forget something, find and remove the relevant entry.',
+    '',
+    ...TYPES_SECTION_COMBINED,
+    ...WHAT_NOT_TO_SAVE_SECTION,
+    '- You MUST avoid saving sensitive data within shared team memories. For example, never save API keys or user credentials.',
+    '',
+    ...howToSave,
+  ].join('\n')
+}