@swarmclawai/swarmclaw 0.7.2 → 0.7.4

package/src/lib/server/session-tools/index.ts

@@ -25,6 +25,7 @@ import { buildWalletTools } from './wallet'
 import { buildOpenClawWorkspaceTools } from './openclaw-workspace'
 import { buildScheduleTools } from './schedule'
 import { buildPlatformTools } from './platform'
+import { buildCrudTools } from './crud'
 import { buildSessionInfoTools } from './session-info'
 import { buildOpenClawNodeTools } from './openclaw-nodes'
 import { buildContextTools } from './context-mgmt'
@@ -37,6 +38,12 @@ import { buildImageGenTools } from './image-gen'
 import { buildEmailTools } from './email'
 import { buildCalendarTools } from './calendar'
 import { buildReplicateTools } from './replicate'
+import { buildMailboxTools } from './mailbox'
+import { buildHumanLoopTools } from './human-loop'
+import { buildDocumentTools } from './document'
+import { buildExtractTools } from './extract'
+import { buildTableTools } from './table'
+import { buildCrawlTools } from './crawl'
 import { normalizeToolInputArgs } from './normalize-tool-args'
 
 import { getPluginManager } from '../plugins'
@@ -157,6 +164,12 @@ export async function buildSessionTools(cwd: string, enabledPlugins: string[], c
       ['email', buildEmailTools],
       ['calendar', buildCalendarTools],
       ['replicate', buildReplicateTools],
+      ['mailbox', buildMailboxTools],
+      ['ask_human', buildHumanLoopTools],
+      ['document', buildDocumentTools],
+      ['extract', buildExtractTools],
+      ['table', buildTableTools],
+      ['crawl', buildCrawlTools],
     ]
 
     for (const [pluginId, builder] of nativeBuilders) {
@@ -167,6 +180,12 @@ export async function buildSessionTools(cwd: string, enabledPlugins: string[], c
       tools.push(...builtTools)
     }
 
+    const crudTools = buildCrudTools(bctx)
+    for (const toolEntry of crudTools) {
+      toolToPluginMap[toolEntry.name] = toolEntry.name
+    }
+    tools.push(...crudTools)
+
     // 2. Build Plugin Tools (Built-in + External)
     try {
       const pluginTools = pluginManager.getTools(activePlugins)
@@ -254,11 +273,34 @@ export async function buildSessionTools(cwd: string, enabledPlugins: string[], c
           const normalized = normalizeToolInputArgs((args ?? {}) as Record<string, unknown>)
           const toolId = normalized.toolId as string | undefined
           const reason = normalized.reason as string | undefined
+          if (!toolId?.trim()) {
+            return JSON.stringify({
+              error: 'toolId is required',
+              message: 'Specify the exact plugin ID to request access for.',
+            })
+          }
+          const { requestApprovalMaybeAutoApprove } = await import('../approvals')
+          const approval = await requestApprovalMaybeAutoApprove({
+            category: 'tool_access',
+            title: `Enable Plugin: ${toolId}`,
+            description: reason || `Agent is requesting access to "${toolId}".`,
+            data: { toolId, pluginId: toolId, reason: reason || '' },
+            agentId: ctx?.agentId,
+            sessionId: ctx?.sessionId,
+          })
+          if (approval.status === 'approved') {
+            return JSON.stringify({
+              type: 'tool_request',
+              toolId,
+              autoApproved: true,
+              message: `Tool access for "${toolId}" was granted. Proceed to use it directly.`,
+            })
+          }
           return JSON.stringify({
             type: 'tool_request',
             toolId,
             reason,
-            message: `Tool access request sent to user for "${toolId}". The user will be prompted to grant access — once granted, a follow-up message will arrive and you should immediately proceed with the original task using the newly available tool.`,
+            message: `Tool access request sent to user for "${toolId}". Once granted, continue immediately with the original task using the newly available tool.`,
           })
         },
         {
@@ -272,8 +314,51 @@ export async function buildSessionTools(cwd: string, enabledPlugins: string[], c
       ),
     )
 
+    const buildFallbackHookSession = (): Session => ({
+      id: ctx?.sessionId || 'plugin-hook-session',
+      name: 'Plugin Hook Session',
+      cwd,
+      user: 'system',
+      provider: 'openai',
+      model: 'unknown',
+      claudeSessionId: null,
+      messages: [],
+      createdAt: Date.now(),
+      lastActiveAt: Date.now(),
+      agentId: ctx?.agentId || null,
+      plugins: [...activePlugins],
+    })
+
+    const wrappedTools = tools.map((candidate) => {
+      const schema = (candidate as unknown as { schema?: z.ZodTypeAny }).schema || z.object({}).passthrough()
+      return tool(
+        async (args) => {
+          const normalizedArgs = normalizeToolInputArgs((args ?? {}) as Record<string, unknown>)
+          const nextArgs = await pluginManager.runBeforeToolExec(
+            { toolName: candidate.name, input: normalizedArgs },
+            { enabledIds: activePlugins },
+          )
+          const effectiveArgs = nextArgs ?? normalizedArgs
+          const result = await candidate.invoke(effectiveArgs)
+          const outputText = typeof result === 'string' ? result : JSON.stringify(result)
+          const hookSession = resolveCurrentSession() || buildFallbackHookSession()
+          await pluginManager.runHook(
+            'afterToolExec',
+            { session: hookSession, toolName: candidate.name, input: effectiveArgs, output: outputText },
+            { enabledIds: activePlugins },
+          )
+          return outputText
+        },
+        {
+          name: candidate.name,
+          description: candidate.description,
+          schema,
+        },
+      )
+    })
+
     return {
-      tools,
+      tools: wrappedTools,
       cleanup: async () => {
         for (const fn of cleanupFns) {
           try { await fn() } catch { /* ignore */ }

package/src/lib/server/session-tools/mailbox.ts

@@ -0,0 +1,276 @@
+import { z } from 'zod'
+import { tool, type StructuredToolInterface } from '@langchain/core/tools'
+import type { Plugin, PluginHooks } from '@/types'
+import { getPluginManager } from '../plugins'
+import type { ToolBuildContext } from './context'
+import { normalizeToolInputArgs } from './normalize-tool-args'
+import {
+  downloadMailboxAttachment,
+  fetchMailboxMessageByUid,
+  fetchMailboxMessages,
+  getMailboxConfig,
+  replyMailboxMessage,
+} from '../mailbox-utils'
+import { createWatchJob } from '../watch-jobs'
+
+function parseMessageUid(value: unknown): number {
+  const parsed = typeof value === 'number' ? value : typeof value === 'string' ? Number.parseInt(value, 10) : Number.NaN
+  return Number.isFinite(parsed) ? Math.max(0, Math.trunc(parsed)) : 0
+}
+
+async function executeMailboxAction(args: Record<string, unknown>, bctx: { cwd: string; sessionId?: string | null; agentId?: string | null }) {
+  const normalized = normalizeToolInputArgs(args)
+  const action = String(normalized.action || 'status').trim().toLowerCase()
+  const folder = typeof normalized.folder === 'string' ? normalized.folder.trim() : undefined
+
+  try {
+    if (action === 'status') {
+      const config = getMailboxConfig()
+      return JSON.stringify({
+        configured: !!(config.imapHost && config.user && config.password),
+        imapHost: config.imapHost || null,
+        smtpHost: config.smtpHost || null,
+        folder: config.folder || 'INBOX',
+        fromAddress: config.fromAddress || null,
+        subjectPrefix: config.subjectPrefix || null,
+      })
+    }
+
+    if (action === 'list_messages' || action === 'search_messages') {
+      const messages = await fetchMailboxMessages({
+        folder,
+        query: typeof normalized.query === 'string' ? normalized.query : undefined,
+        from: typeof normalized.from === 'string' ? normalized.from : undefined,
+        subjectContains: typeof normalized.subjectContains === 'string' ? normalized.subjectContains : undefined,
+        bodyContains: typeof normalized.containsText === 'string' ? normalized.containsText : undefined,
+        unreadOnly: normalized.unreadOnly === true,
+        hasAttachments: normalized.hasAttachments === true,
+        limit: typeof normalized.limit === 'number' ? normalized.limit : undefined,
+      })
+      return JSON.stringify(messages.map((message) => ({
+        uid: message.uid,
+        messageId: message.messageId,
+        subject: message.subject,
+        from: message.from,
+        fromName: message.fromName,
+        date: message.date,
+        snippet: message.snippet,
+        hasAttachments: message.hasAttachments,
+        attachmentCount: message.attachments.length,
+        threadKey: message.threadKey,
+      })))
+    }
+
+    if (action === 'list_threads') {
+      const messages = await fetchMailboxMessages({
+        folder,
+        limit: typeof normalized.limit === 'number' ? Math.max(10, normalized.limit * 4) : 80,
+      })
+      const threads = new Map<string, {
+        threadKey: string
+        subject: string
+        participants: Set<string>
+        latestUid: number
+        latestDate: string | null
+        messageCount: number
+        unreadCount: number
+        snippet: string
+      }>()
+      for (const message of messages) {
+        const current = threads.get(message.threadKey) || {
+          threadKey: message.threadKey,
+          subject: message.subject,
+          participants: new Set<string>(),
+          latestUid: message.uid,
+          latestDate: message.date,
+          messageCount: 0,
+          unreadCount: 0,
+          snippet: message.snippet,
+        }
+        current.messageCount += 1
+        current.participants.add(message.from)
+        if (!message.flags.includes('\\Seen')) current.unreadCount += 1
+        if (message.uid >= current.latestUid) {
+          current.latestUid = message.uid
+          current.latestDate = message.date
+          current.subject = message.subject
+          current.snippet = message.snippet
+        }
+        threads.set(message.threadKey, current)
+      }
+      return JSON.stringify(Array.from(threads.values())
+        .map((thread) => ({
+          threadKey: thread.threadKey,
+          subject: thread.subject,
+          participants: Array.from(thread.participants),
+          latestUid: thread.latestUid,
+          latestDate: thread.latestDate,
+          messageCount: thread.messageCount,
+          unreadCount: thread.unreadCount,
+          snippet: thread.snippet,
+        }))
+        .sort((a, b) => b.latestUid - a.latestUid)
+        .slice(0, Math.max(1, Math.min(typeof normalized.limit === 'number' ? normalized.limit : 20, 100))))
+    }
+
+    if (action === 'read_message') {
+      const uid = parseMessageUid(normalized.uid ?? normalized.id)
+      if (!uid) return 'Error: uid is required.'
+      const message = await fetchMailboxMessageByUid(uid, folder)
+      if (!message) return `Error: mailbox message "${uid}" not found.`
+      return JSON.stringify(message)
+    }
+
+    if (action === 'download_attachment') {
+      const uid = parseMessageUid(normalized.uid ?? normalized.id)
+      if (!uid) return 'Error: uid is required.'
+      const result = await downloadMailboxAttachment({
+        uid,
+        folder,
+        attachmentId: typeof normalized.attachmentId === 'string' ? normalized.attachmentId : undefined,
+        attachmentName: typeof normalized.attachmentName === 'string' ? normalized.attachmentName : undefined,
+        saveTo: typeof normalized.saveTo === 'string' ? normalized.saveTo : undefined,
+        cwd: bctx.cwd,
+      })
+      return JSON.stringify(result)
+    }
+
+    if (action === 'reply') {
+      const uid = parseMessageUid(normalized.uid ?? normalized.id)
+      if (!uid) return 'Error: uid is required.'
+      const text = typeof normalized.text === 'string'
+        ? normalized.text
+        : typeof normalized.body === 'string'
+          ? normalized.body
+          : ''
+      if (!text.trim()) return 'Error: text is required.'
+      const result = await replyMailboxMessage({
+        uid,
+        folder,
+        text,
+        html: typeof normalized.html === 'string' ? normalized.html : undefined,
+        subject: typeof normalized.subject === 'string' ? normalized.subject : undefined,
+      })
+      return JSON.stringify({ ok: true, ...result, uid })
+    }
+
+    if (action === 'wait_for_email') {
+      if (!bctx.sessionId && !bctx.agentId) return 'Error: email waits require a session or agent context.'
+      const resumeMessage = typeof normalized.resumeMessage === 'string' && normalized.resumeMessage.trim()
+        ? normalized.resumeMessage.trim()
+        : 'A matching email arrived. Read it, decide what to do next, and continue the task.'
+      const intervalMs = typeof normalized.intervalSec === 'number'
+        ? Math.max(30, normalized.intervalSec) * 1000
+        : 60_000
+      const timeoutAt = typeof normalized.timeoutMinutes === 'number'
+        ? Date.now() + Math.max(1, normalized.timeoutMinutes) * 60_000
+        : undefined
+      const job = await createWatchJob({
+        type: 'email',
+        sessionId: bctx.sessionId || null,
+        agentId: bctx.agentId || null,
+        createdByAgentId: bctx.agentId || null,
+        resumeMessage,
+        description: typeof normalized.description === 'string' ? normalized.description : 'Wait for email',
+        intervalMs,
+        timeoutAt,
+        target: {
+          folder: folder || getMailboxConfig().folder || 'INBOX',
+        },
+        condition: {
+          from: typeof normalized.from === 'string' ? normalized.from : undefined,
+          subjectContains: typeof normalized.subjectContains === 'string' ? normalized.subjectContains : undefined,
+          containsText: typeof normalized.containsText === 'string' ? normalized.containsText : undefined,
+          query: typeof normalized.query === 'string' ? normalized.query : undefined,
+          unreadOnly: normalized.unreadOnly === true,
+          hasAttachments: normalized.hasAttachments === true,
+        },
+      })
+      return JSON.stringify(job)
+    }
+
+    return `Error: Unknown action "${action}".`
+  } catch (err: unknown) {
+    return `Error: ${err instanceof Error ? err.message : String(err)}`
+  }
+}
+
+const MailboxPlugin: Plugin = {
+  name: 'Mailbox',
+  enabledByDefault: false,
+  description: 'Read/search/reply to inbox messages over IMAP/SMTP, download attachments, and wait for matching inbound email.',
+  hooks: {
+    getCapabilityDescription: () =>
+      'I can inspect inboxes with `mailbox`, read and search messages, download attachments, reply to emails, and wait for specific inbound messages.',
+  } as PluginHooks,
+  tools: [
+    {
+      name: 'mailbox',
+      description: 'Work with email inboxes. Actions: status, list_messages, list_threads, search_messages, read_message, download_attachment, reply, wait_for_email.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['status', 'list_messages', 'list_threads', 'search_messages', 'read_message', 'download_attachment', 'reply', 'wait_for_email'] },
+          uid: { type: 'number' },
+          query: { type: 'string' },
+          from: { type: 'string' },
+          subjectContains: { type: 'string' },
+          containsText: { type: 'string' },
+          attachmentId: { type: 'string' },
+          attachmentName: { type: 'string' },
+          text: { type: 'string' },
+          body: { type: 'string' },
+          html: { type: 'string' },
+          subject: { type: 'string' },
+          folder: { type: 'string' },
+          unreadOnly: { type: 'boolean' },
+          hasAttachments: { type: 'boolean' },
+          limit: { type: 'number' },
+          saveTo: { type: 'string' },
+          resumeMessage: { type: 'string' },
+          intervalSec: { type: 'number' },
+          timeoutMinutes: { type: 'number' },
+        },
+        required: ['action'],
+      },
+      execute: async (args, context) => executeMailboxAction(args, {
+        cwd: context.session.cwd || process.cwd(),
+        sessionId: context.session.id,
+        agentId: context.session.agentId || null,
+      }),
+    },
+  ],
+  ui: {
+    settingsFields: [
+      { key: 'imapHost', label: 'IMAP Host', type: 'text', placeholder: 'imap.gmail.com', help: 'Inbound mailbox host.' },
+      { key: 'imapPort', label: 'IMAP Port', type: 'number', defaultValue: 993, help: '993 for TLS IMAP.' },
+      { key: 'smtpHost', label: 'SMTP Host', type: 'text', placeholder: 'smtp.gmail.com', help: 'Outbound mail host for replies.' },
+      { key: 'smtpPort', label: 'SMTP Port', type: 'number', defaultValue: 587, help: '587 for STARTTLS, 465 for SSL.' },
+      { key: 'user', label: 'Mailbox Username', type: 'text', placeholder: 'agent@example.com' },
+      { key: 'password', label: 'Mailbox Password', type: 'secret', help: 'IMAP password or app password.' },
+      { key: 'folder', label: 'Folder', type: 'text', defaultValue: 'INBOX', placeholder: 'INBOX' },
+      { key: 'fromAddress', label: 'Reply From Address', type: 'text', placeholder: 'agent@example.com' },
+      { key: 'fromName', label: 'Reply From Name', type: 'text', defaultValue: 'SwarmClaw Agent' },
+    ],
+  },
+}
+
+getPluginManager().registerBuiltin('mailbox', MailboxPlugin)
+
+export function buildMailboxTools(bctx: ToolBuildContext): StructuredToolInterface[] {
+  if (!bctx.hasPlugin('mailbox')) return []
+  return [
+    tool(
+      async (args) => executeMailboxAction(args, {
+        cwd: bctx.cwd,
+        sessionId: bctx.ctx?.sessionId || null,
+        agentId: bctx.ctx?.agentId || null,
+      }),
+      {
+        name: 'mailbox',
+        description: MailboxPlugin.tools![0].description,
+        schema: z.object({}).passthrough(),
+      },
+    ),
+  ]
+}

package/src/lib/server/session-tools/manage-schedules.test.ts

@@ -0,0 +1,137 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { describe, it } from 'node:test'
+
+const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../../../..')
+
+function runWithTempDataDir(script: string) {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'swarmclaw-schedule-tool-'))
+  try {
+    const result = spawnSync(process.execPath, ['--import', 'tsx', '--input-type=module', '--eval', script], {
+      cwd: repoRoot,
+      env: {
+        ...process.env,
+        DATA_DIR: path.join(tempDir, 'data'),
+        WORKSPACE_DIR: path.join(tempDir, 'workspace'),
+      },
+      encoding: 'utf-8',
+    })
+    assert.equal(result.status, 0, result.stderr || result.stdout || 'subprocess failed')
+    const lines = (result.stdout || '')
+      .trim()
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean)
+    const jsonLine = [...lines].reverse().find((line) => line.startsWith('{'))
+    return JSON.parse(jsonLine || '{}')
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  }
+}
+
+describe('manage_schedules tool', () => {
+  it('defaults schedules to the current agent and derives a runnable taskPrompt from run_script payloads', () => {
+    const output = runWithTempDataDir(`
+      import fs from 'node:fs'
+      import path from 'node:path'
+      const storageMod = await import('./src/lib/server/storage.ts')
+      const crudMod = await import('./src/lib/server/session-tools/crud.ts')
+      const storage = storageMod.default || storageMod
+      const crud = crudMod.default || crudMod
+
+      const now = Date.now()
+      storage.saveAgents({
+        default: {
+          id: 'default',
+          name: 'Molly',
+          description: '',
+          systemPrompt: '',
+          provider: 'openai',
+          model: 'gpt-test',
+          createdAt: now,
+          updatedAt: now,
+        },
+      })
+
+      const cwd = process.env.WORKSPACE_DIR
+      fs.mkdirSync(path.join(cwd, 'weather_workspace'), { recursive: true })
+      fs.writeFileSync(path.join(cwd, 'weather_workspace', 'weather_fetch.py'), 'print("weather")\\n')
+
+      const tools = crud.buildCrudTools({
+        cwd,
+        ctx: { sessionId: 'session-1', agentId: 'default', platformAssignScope: 'self' },
+        hasPlugin: (name) => name === 'manage_schedules',
+      })
+      const tool = tools.find((entry) => entry.name === 'manage_schedules')
+      const raw = await tool.invoke({
+        action: 'create',
+        data: JSON.stringify({
+          name: 'Daily Weather Update',
+          scheduleType: 'interval',
+          intervalMs: 60000,
+          action: 'run_script',
+          path: 'weather_workspace/weather_fetch.py',
+        }),
+      })
+
+      const schedule = Object.values(storage.loadSchedules())[0]
+      console.log(JSON.stringify({
+        raw,
+        schedule,
+      }))
+    `)
+
+    assert.equal(output.schedule.agentId, 'default')
+    assert.equal(output.schedule.path, 'weather_workspace/weather_fetch.py')
+    assert.match(output.schedule.taskPrompt, /weather_workspace\/weather_fetch\.py/)
+    assert.equal(output.schedule.status, 'active')
+    assert.equal(typeof output.schedule.nextRunAt, 'number')
+  })
+
+  it('rejects schedules whose referenced script path does not exist', () => {
+    const output = runWithTempDataDir(`
+      const storageMod = await import('./src/lib/server/storage.ts')
+      const crudMod = await import('./src/lib/server/session-tools/crud.ts')
+      const storage = storageMod.default || storageMod
+      const crud = crudMod.default || crudMod
+
+      const now = Date.now()
+      storage.saveAgents({
+        default: {
+          id: 'default',
+          name: 'Molly',
+          description: '',
+          systemPrompt: '',
+          provider: 'openai',
+          model: 'gpt-test',
+          createdAt: now,
+          updatedAt: now,
+        },
+      })
+
+      const tools = crud.buildCrudTools({
+        cwd: process.env.WORKSPACE_DIR,
+        ctx: { sessionId: 'session-2', agentId: 'default', platformAssignScope: 'self' },
+        hasPlugin: (name) => name === 'manage_schedules',
+      })
+      const tool = tools.find((entry) => entry.name === 'manage_schedules')
+      const raw = await tool.invoke({
+        action: 'create',
+        data: JSON.stringify({
+          name: 'Broken Weather Update',
+          scheduleType: 'interval',
+          intervalMs: 60000,
+          action: 'run_script',
+          path: 'weather_workspace/missing.py',
+        }),
+      })
+
+      console.log(JSON.stringify({ raw }))
+    `)
+
+    assert.match(String(output.raw), /schedule path not found: weather_workspace\/missing\.py/i)
+  })
+})

package/src/lib/server/session-tools/memory.ts

@@ -15,6 +15,8 @@ import type { MemoryEntry, Plugin, PluginHooks } from '@/types'
 import type { ToolBuildContext } from './context'
 import { getPluginManager } from '../plugins'
 import { normalizeToolInputArgs } from './normalize-tool-args'
+import { partitionMemoriesByTier } from '../memory-tiers'
+import { syncSessionArchiveMemory } from '../session-archive-memory'
 
 /**
  * Advanced Database-Backed Memory logic.
@@ -34,6 +36,12 @@ async function executeMemoryAction(input: any, ctx: any) {
   
   const memDb = getMemoryDb()
   const currentAgentId = ctx?.agentId || null
+  const currentSessionId = typeof ctx?.sessionId === 'string'
+    ? ctx.sessionId
+    : typeof ctx?.id === 'string'
+      ? ctx.id
+      : null
+  const currentSession = ctx && typeof ctx === 'object' && Array.isArray(ctx.messages) ? ctx : null
   const rawScope = typeof scope === 'string' ? scope : 'auto'
   const scopeMode = normalizeMemoryScopeMode(rawScope === 'shared' ? 'global' : rawScope)
   const rerankMode = rerank === 'semantic' || rerank === 'lexical' ? rerank : 'balanced'
@@ -41,7 +49,7 @@ async function executeMemoryAction(input: any, ctx: any) {
   const scopeFilter = {
     mode: scopeMode,
     agentId: currentAgentId,
-    sessionId: (typeof scopeSessionId === 'string' && scopeSessionId.trim()) ? scopeSessionId.trim() : (ctx?.sessionId || null),
+    sessionId: (typeof scopeSessionId === 'string' && scopeSessionId.trim()) ? scopeSessionId.trim() : currentSessionId,
     projectRoot: (typeof projectRoot === 'string' && projectRoot.trim()) ? projectRoot.trim() : ((project && typeof project === 'object' && 'rootPath' in project && typeof (project as Record<string, unknown>).rootPath === 'string') ? (project as Record<string, unknown>).rootPath as string : null),
   }
   
@@ -52,6 +60,10 @@ async function executeMemoryAction(input: any, ctx: any) {
   const limits = getMemoryLookupLimits(loadSettings())
   const maxPerLookup = limits.maxPerLookup
 
+  if ((action === 'search' || action === 'list') && currentSession) {
+    try { syncSessionArchiveMemory(currentSession) } catch { /* archive sync is best-effort */ }
+  }
+
   const formatEntry = (m: any) => {
     let line = `[${m.id}] (${m.agentId ? `agent:${m.agentId}` : 'shared'}) ${m.category}/${m.title}: ${m.content}`
     if (m.reinforcementCount) line += ` (reinforced ×${m.reinforcementCount})`
@@ -132,6 +144,8 @@ const MemoryPlugin: Plugin = {
       const agentId = ctx.session.agentId
       if (!agentId) return null
 
+      try { syncSessionArchiveMemory(ctx.session) } catch { /* archive sync is best-effort */ }
+
       const memDb = getMemoryDb()
       const memoryQuerySeed = [
         ctx.message,
@@ -159,12 +173,22 @@ const MemoryPlugin: Plugin = {
       const relevantLookup = memDb.searchWithLinked(memoryQuerySeed, agentId, 1, 10, 14)
       const relevant = relevantLookup.entries.slice(0, relevantSlice)
       const recent = memDb.list(agentId, 12).slice(0, 6)
+      const relevantByTier = partitionMemoriesByTier(relevant)
+      const recentByTier = partitionMemoriesByTier(recent)
+
+      const relevantLines = relevantByTier.durable
+        .filter((m) => { if (!m?.id || seen.has(m.id)) return false; seen.add(m.id); return true })
+        .map(formatMemoryLine)
 
-      const relevantLines = relevant
+      const archiveLines = relevantByTier.archive
         .filter((m) => { if (!m?.id || seen.has(m.id)) return false; seen.add(m.id); return true })
         .map(formatMemoryLine)
 
-      const recentLines = recent
+      const recentLines = recentByTier.durable
+        .filter((m) => { if (!m?.id || seen.has(m.id)) return false; seen.add(m.id); return true })
+        .map(formatMemoryLine)
+
+      const recentArchiveLines = recentByTier.archive
         .filter((m) => { if (!m?.id || seen.has(m.id)) return false; seen.add(m.id); return true })
         .map(formatMemoryLine)
 
@@ -175,14 +199,21 @@ const MemoryPlugin: Plugin = {
       if (relevantLines.length) {
         parts.push(['## Relevant Memory Hits', 'These memories were retrieved by relevance for the current objective.', ...relevantLines].join('\n'))
       }
+      if (archiveLines.length) {
+        parts.push(['## Session Archive Hits', 'Past conversation snapshots that may restore context from older chats.', ...archiveLines].join('\n'))
+      }
       if (recentLines.length) {
         parts.push(['## Recent Memory Notes', 'Recent durable notes that may still apply.', ...recentLines].join('\n'))
       }
+      if (recentArchiveLines.length) {
+        parts.push(['## Recent Session Archives', 'Recently synced conversation archives you can search instead of relying on stale live context.', ...recentArchiveLines].join('\n'))
+      }
 
       // Memory Policy
       parts.push([
         '## My Memory',
         'I have long-term memory that persists across conversations. I use it naturally — I don\'t wait to be asked to remember things.',
+        'Memory tiers: working memory is short-lived, durable memory stores stable facts and decisions, and session archives capture older conversation context for search.',
         '',
         '**Things worth remembering:**',
         '- What the user likes, dislikes, or has corrected me on',
@@ -201,6 +232,7 @@ const MemoryPlugin: Plugin = {
         '**Good habits:**',
         '- Give memories clear titles ("User prefers dark mode" not "Note 1")',
         '- Use categories: preference, fact, learning, project, identity, decision',
+        '- Search session archives before assuming older conversation context is still in the live chat history',
         '- Check what I already know before storing something new',
         '- When I learn something that corrects old knowledge, update or remove the old memory',
       ].join('\n'))