@swarmclawai/swarmclaw 0.2.0

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

@@ -0,0 +1,264 @@
+import { z } from 'zod'
+import { tool, type StructuredToolInterface } from '@langchain/core/tools'
+import fs from 'fs'
+import path from 'path'
+import { UPLOAD_DIR } from '../storage'
+import type { ToolBuildContext } from './context'
+import { safePath, truncate, listDirRecursive, MAX_OUTPUT, MAX_FILE } from './context'
+
+export function buildFileTools(bctx: ToolBuildContext): StructuredToolInterface[] {
+  const tools: StructuredToolInterface[] = []
+
+  const filesEnabled = bctx.hasTool('files')
+  const canReadFiles = filesEnabled || bctx.hasTool('read_file')
+  const canWriteFiles = filesEnabled || bctx.hasTool('write_file')
+  const canListFiles = filesEnabled || bctx.hasTool('list_files')
+  const canSendFiles = filesEnabled || bctx.hasTool('send_file')
+  const canCopyFiles = filesEnabled || bctx.hasTool('copy_file')
+  const canMoveFiles = filesEnabled || bctx.hasTool('move_file')
+  const canDeleteFiles = bctx.hasTool('delete_file')
+
+  if (canReadFiles) {
+    tools.push(
+      tool(
+        async ({ filePath }) => {
+          try {
+            const resolved = safePath(bctx.cwd, filePath)
+            const content = fs.readFileSync(resolved, 'utf-8')
+            return truncate(content, MAX_FILE)
+          } catch (err: any) {
+            return `Error reading file: ${err.message}`
+          }
+        },
+        {
+          name: 'read_file',
+          description: 'Read a file from the session working directory.',
+          schema: z.object({
+            filePath: z.string().describe('Relative path to the file'),
+          }),
+        },
+      ),
+    )
+  }
+
+  if (canWriteFiles) {
+    tools.push(
+      tool(
+        async ({ filePath, content }) => {
+          try {
+            const resolved = safePath(bctx.cwd, filePath)
+            fs.mkdirSync(path.dirname(resolved), { recursive: true })
+            fs.writeFileSync(resolved, content, 'utf-8')
+            return `File written: ${filePath} (${content.length} bytes)`
+          } catch (err: any) {
+            return `Error writing file: ${err.message}`
+          }
+        },
+        {
+          name: 'write_file',
+          description: 'Write content to a file in the session working directory. Creates directories if needed.',
+          schema: z.object({
+            filePath: z.string().describe('Relative path to the file'),
+            content: z.string().describe('The content to write'),
+          }),
+        },
+      ),
+    )
+  }
+
+  if (canListFiles) {
+    tools.push(
+      tool(
+        async ({ dirPath }) => {
+          try {
+            const resolved = safePath(bctx.cwd, dirPath || '.')
+            const tree = listDirRecursive(resolved, 0, 3)
+            return tree.length ? tree.join('\n') : '(empty directory)'
+          } catch (err: any) {
+            return `Error listing files: ${err.message}`
+          }
+        },
+        {
+          name: 'list_files',
+          description: 'List files in the session working directory recursively (max depth 3).',
+          schema: z.object({
+            dirPath: z.string().optional().describe('Relative path to list (defaults to working directory)'),
+          }),
+        },
+      ),
+    )
+  }
+
+  if (canCopyFiles) {
+    tools.push(
+      tool(
+        async ({ sourcePath, destinationPath, overwrite }) => {
+          try {
+            const source = safePath(bctx.cwd, sourcePath)
+            const destination = safePath(bctx.cwd, destinationPath)
+            if (!fs.existsSync(source)) return `Error: source file not found: ${sourcePath}`
+            const sourceStat = fs.statSync(source)
+            if (sourceStat.isDirectory()) return `Error: source must be a file (directories are not supported by copy_file).`
+            if (fs.existsSync(destination) && !overwrite) return `Error: destination already exists: ${destinationPath} (set overwrite=true to replace).`
+            fs.mkdirSync(path.dirname(destination), { recursive: true })
+            fs.copyFileSync(source, destination)
+            return `File copied: ${sourcePath} -> ${destinationPath}`
+          } catch (err: any) {
+            return `Error copying file: ${err.message}`
+          }
+        },
+        {
+          name: 'copy_file',
+          description: 'Copy a file to a new location in the working directory.',
+          schema: z.object({
+            sourcePath: z.string().describe('Source file path (relative to working directory)'),
+            destinationPath: z.string().describe('Destination file path (relative to working directory)'),
+            overwrite: z.boolean().optional().describe('Overwrite destination if it exists (default false)'),
+          }),
+        },
+      ),
+    )
+  }
+
+  if (canMoveFiles) {
+    tools.push(
+      tool(
+        async ({ sourcePath, destinationPath, overwrite }) => {
+          try {
+            const source = safePath(bctx.cwd, sourcePath)
+            const destination = safePath(bctx.cwd, destinationPath)
+            if (!fs.existsSync(source)) return `Error: source file not found: ${sourcePath}`
+            const sourceStat = fs.statSync(source)
+            if (sourceStat.isDirectory()) return `Error: source must be a file (directories are not supported by move_file).`
+            if (fs.existsSync(destination) && !overwrite) return `Error: destination already exists: ${destinationPath} (set overwrite=true to replace).`
+            fs.mkdirSync(path.dirname(destination), { recursive: true })
+            if (fs.existsSync(destination) && overwrite) fs.unlinkSync(destination)
+            fs.renameSync(source, destination)
+            return `File moved: ${sourcePath} -> ${destinationPath}`
+          } catch (err: any) {
+            return `Error moving file: ${err.message}`
+          }
+        },
+        {
+          name: 'move_file',
+          description: 'Move (rename) a file to a new location in the working directory.',
+          schema: z.object({
+            sourcePath: z.string().describe('Source file path (relative to working directory)'),
+            destinationPath: z.string().describe('Destination file path (relative to working directory)'),
+            overwrite: z.boolean().optional().describe('Overwrite destination if it exists (default false)'),
+          }),
+        },
+      ),
+    )
+  }
+
+  if (canDeleteFiles) {
+    tools.push(
+      tool(
+        async ({ filePath, recursive, force }) => {
+          try {
+            const resolved = safePath(bctx.cwd, filePath)
+            const root = path.resolve(bctx.cwd)
+            if (resolved === root) return 'Error: refusing to delete the session working directory root.'
+            if (!fs.existsSync(resolved)) {
+              return force ? `Path already absent: ${filePath}` : `Error: path not found: ${filePath}`
+            }
+            const stat = fs.statSync(resolved)
+            if (stat.isDirectory() && !recursive) {
+              return 'Error: target is a directory. Set recursive=true to delete directories.'
+            }
+            fs.rmSync(resolved, { recursive: !!recursive, force: !!force })
+            return `Deleted: ${filePath}`
+          } catch (err: any) {
+            return `Error deleting file: ${err.message}`
+          }
+        },
+        {
+          name: 'delete_file',
+          description: 'Delete a file or directory from the working directory. Disabled by default and must be explicitly enabled.',
+          schema: z.object({
+            filePath: z.string().describe('Path to delete (relative to working directory)'),
+            recursive: z.boolean().optional().describe('Required for deleting directories'),
+            force: z.boolean().optional().describe('Ignore missing paths and force deletion where possible'),
+          }),
+        },
+      ),
+    )
+  }
+
+  if (canSendFiles) {
+    tools.push(
+      tool(
+        async ({ filePath: rawPath }) => {
+          try {
+            // Resolve relative to cwd, but also allow absolute paths
+            const resolved = path.isAbsolute(rawPath) ? rawPath : path.resolve(bctx.cwd, rawPath)
+            if (!fs.existsSync(resolved)) return `Error: file not found: ${rawPath}`
+            const stat = fs.statSync(resolved)
+            if (stat.isDirectory()) return `Error: cannot send a directory. Send individual files instead.`
+            if (stat.size > 100 * 1024 * 1024) return `Error: file too large (${(stat.size / 1024 / 1024).toFixed(1)}MB). Max 100MB.`
+
+            const ext = path.extname(resolved).slice(1).toLowerCase()
+            const basename = path.basename(resolved)
+            const filename = `${Date.now()}-${basename}`
+            const dest = path.join(UPLOAD_DIR, filename)
+            fs.copyFileSync(resolved, dest)
+
+            const IMAGE_EXTS = ['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg', 'bmp', 'ico']
+            const VIDEO_EXTS = ['mp4', 'webm', 'mov', 'avi', 'mkv']
+
+            if (IMAGE_EXTS.includes(ext)) {
+              return `![${basename}](/api/uploads/${filename})`
+            } else if (VIDEO_EXTS.includes(ext)) {
+              return `![${basename}](/api/uploads/${filename})`
+            } else {
+              return `[Download ${basename}](/api/uploads/${filename})`
+            }
+          } catch (err: any) {
+            return `Error sending file: ${err.message}`
+          }
+        },
+        {
+          name: 'send_file',
+          description: 'Send a file to the user so they can view or download it in the chat. Works with images, videos, PDFs, documents, and any other file type. The file will appear inline for images/videos, or as a download link for other types.',
+          schema: z.object({
+            filePath: z.string().describe('Path to the file (relative to working directory, or absolute)'),
+          }),
+        },
+      ),
+    )
+  }
+
+  if (bctx.hasTool('edit_file')) {
+    tools.push(
+      tool(
+        async ({ filePath, oldText, newText }) => {
+          try {
+            const resolved = safePath(bctx.cwd, filePath)
+            if (!fs.existsSync(resolved)) return `Error: File not found: ${filePath}`
+            const content = fs.readFileSync(resolved, 'utf-8')
+            const count = content.split(oldText).length - 1
+            if (count === 0) return `Error: oldText not found in ${filePath}`
+            if (count > 1) return `Error: oldText found ${count} times in ${filePath}. Make it more specific.`
+            const updated = content.replace(oldText, newText)
+            fs.writeFileSync(resolved, updated, 'utf-8')
+            return `Successfully edited ${filePath}`
+          } catch (err: any) {
+            return `Error editing file: ${err.message}`
+          }
+        },
+        {
+          name: 'edit_file',
+          description: 'Search and replace text in a file. The oldText must match exactly once in the file.',
+          schema: z.object({
+            filePath: z.string().describe('Relative path to the file'),
+            oldText: z.string().describe('Exact text to find (must be unique in the file)'),
+            newText: z.string().describe('Text to replace it with'),
+          }),
+        },
+      ),
+    )
+  }
+
+  return tools
+}

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

@@ -0,0 +1,164 @@
+import { z } from 'zod'
+import { tool, type StructuredToolInterface } from '@langchain/core/tools'
+import { loadSettings, loadSessions, saveSessions, loadMcpServers } from '../storage'
+import { loadRuntimeSettings } from '../runtime-settings'
+import { log } from '../logger'
+import { resolveSessionToolPolicy } from '../tool-capability-policy'
+import type { ToolContext, SessionToolsResult, ToolBuildContext } from './context'
+import { buildShellTools } from './shell'
+import { buildFileTools } from './file'
+import { buildDelegateTools } from './delegate'
+import { buildWebTools, sweepOrphanedBrowsers, cleanupSessionBrowser, getActiveBrowserCount, hasActiveBrowser } from './web'
+import { buildMemoryTools } from './memory'
+import { buildCrudTools } from './crud'
+import { buildSessionInfoTools } from './session-info'
+import { buildConnectorTools } from './connector'
+import { buildContextTools } from './context-mgmt'
+
+export type { ToolContext, SessionToolsResult }
+export { sweepOrphanedBrowsers, cleanupSessionBrowser, getActiveBrowserCount, hasActiveBrowser }
+
+export async function buildSessionTools(cwd: string, enabledTools: string[], ctx?: ToolContext): Promise<SessionToolsResult> {
+  const tools: StructuredToolInterface[] = []
+  const cleanupFns: (() => Promise<void>)[] = []
+  const runtime = loadRuntimeSettings()
+  const commandTimeoutMs = runtime.shellCommandTimeoutMs
+  const claudeTimeoutMs = runtime.claudeCodeTimeoutMs
+  const cliProcessTimeoutMs = runtime.cliProcessTimeoutMs
+  const appSettings = loadSettings()
+  const toolPolicy = resolveSessionToolPolicy(enabledTools, appSettings)
+  const activeTools = toolPolicy.enabledTools
+  const hasTool = (toolName: string) => activeTools.includes(toolName)
+
+  if (toolPolicy.blockedTools.length > 0) {
+    log.info('session-tools', 'Capability policy blocked tool families', {
+      sessionId: ctx?.sessionId || null,
+      agentId: ctx?.agentId || null,
+      blockedTools: toolPolicy.blockedTools.map((entry) => `${entry.tool}:${entry.reason}`),
+    })
+  }
+
+  const resolveCurrentSession = (): any | null => {
+    if (!ctx?.sessionId) return null
+    const sessions = loadSessions()
+    return sessions[ctx.sessionId] || null
+  }
+
+  const readStoredDelegateResumeId = (key: 'claudeCode' | 'codex' | 'opencode'): string | null => {
+    const session = resolveCurrentSession()
+    if (!session?.delegateResumeIds || typeof session.delegateResumeIds !== 'object') return null
+    const raw = session.delegateResumeIds[key]
+    return typeof raw === 'string' && raw.trim() ? raw.trim() : null
+  }
+
+  const persistDelegateResumeId = (key: 'claudeCode' | 'codex' | 'opencode', resumeId: string | null | undefined): void => {
+    const normalized = typeof resumeId === 'string' ? resumeId.trim() : ''
+    if (!normalized || !ctx?.sessionId) return
+    const sessions = loadSessions()
+    const target = sessions[ctx.sessionId]
+    if (!target) return
+    const current = (target.delegateResumeIds && typeof target.delegateResumeIds === 'object')
+      ? target.delegateResumeIds
+      : {}
+    target.delegateResumeIds = {
+      ...current,
+      [key]: normalized,
+    }
+    target.updatedAt = Date.now()
+    sessions[ctx.sessionId] = target
+    saveSessions(sessions)
+  }
+
+  const bctx: ToolBuildContext = {
+    cwd,
+    ctx,
+    hasTool,
+    cleanupFns,
+    commandTimeoutMs,
+    claudeTimeoutMs,
+    cliProcessTimeoutMs,
+    persistDelegateResumeId,
+    readStoredDelegateResumeId,
+    resolveCurrentSession,
+    activeTools,
+  }
+
+  tools.push(
+    ...buildShellTools(bctx),
+    ...buildFileTools(bctx),
+    ...buildDelegateTools(bctx),
+    ...buildWebTools(bctx),
+    ...buildMemoryTools(bctx),
+    ...buildCrudTools(bctx),
+    ...buildSessionInfoTools(bctx),
+    ...buildConnectorTools(bctx),
+    ...buildContextTools(bctx),
+  )
+
+  // ---------------------------------------------------------------------------
+  // MCP server tools — first-class injection (each MCP tool becomes its own LangChain tool)
+  // ---------------------------------------------------------------------------
+  const disabledMcpToolNames = new Set<string>(ctx?.mcpDisabledTools ?? [])
+
+  if (ctx?.mcpServerIds?.length) {
+    const mcpConnections: Array<{ client: any; transport: any }> = []
+    const allMcpServers = loadMcpServers()
+
+    for (const serverId of ctx.mcpServerIds) {
+      const config = allMcpServers[serverId]
+      if (!config) continue
+      try {
+        const { connectMcpServer, mcpToolsToLangChain } = await import('../mcp-client')
+        const conn = await connectMcpServer(config)
+        mcpConnections.push(conn)
+        const mcpLcTools = await mcpToolsToLangChain(conn.client, config.name)
+        for (const t of mcpLcTools) {
+          if (!disabledMcpToolNames.has(t.name)) {
+            tools.push(t)
+          }
+        }
+      } catch (err: any) {
+        log.warn('session-tools', `Failed to connect MCP server "${config.name}"`, { serverId, error: err.message })
+      }
+    }
+
+    // Register cleanup for all MCP connections
+    cleanupFns.push(async () => {
+      const { disconnectMcpServer } = await import('../mcp-client')
+      for (const conn of mcpConnections) {
+        await disconnectMcpServer(conn.client, conn.transport)
+      }
+    })
+  }
+
+  // request_tool_access: always available
+  tools.push(
+    tool(
+      async ({ toolId, reason }) => {
+        return JSON.stringify({
+          type: 'tool_request',
+          toolId,
+          reason,
+          message: `Tool access request sent to user for "${toolId}". Wait for the user to grant access before trying to use it.`,
+        })
+      },
+      {
+        name: 'request_tool_access',
+        description: 'Request access to a tool that is currently disabled. The user will be prompted to grant access. Use this when you need a tool from the disabled tools list.',
+        schema: z.object({
+          toolId: z.string().describe('The tool ID to request access for (e.g. manage_tasks, shell, claude_code)'),
+          reason: z.string().describe('Brief explanation of why you need this tool'),
+        }),
+      },
+    ),
+  )
+
+  return {
+    tools,
+    cleanup: async () => {
+      for (const fn of cleanupFns) {
+        try { await fn() } catch { /* ignore */ }
+      }
+    },
+  }
+}

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

@@ -0,0 +1,230 @@
+import { z } from 'zod'
+import { tool, type StructuredToolInterface } from '@langchain/core/tools'
+import fs from 'fs'
+import crypto from 'crypto'
+import { getMemoryDb, getMemoryLookupLimits, storeMemoryImageAsset } from '../memory-db'
+import { loadSettings } from '../storage'
+import type { ToolBuildContext } from './context'
+
+export function buildMemoryTools(bctx: ToolBuildContext): StructuredToolInterface[] {
+  const tools: StructuredToolInterface[] = []
+  const { ctx, hasTool } = bctx
+
+  if (hasTool('memory')) {
+    const memDb = getMemoryDb()
+
+    tools.push(
+      tool(
+        async ({ action, key, value, category, query, scope, filePaths, references, project, imagePath, linkedMemoryIds, depth, linkedLimit, targetIds, tags }) => {
+          try {
+            const scopeMode = scope || 'auto'
+            const currentAgentId = ctx?.agentId || null
+            const canAccessMemory = (m: any) => !m?.agentId || m.agentId === currentAgentId
+            const filterScope = (rows: any[]) => {
+              if (scopeMode === 'shared') return rows.filter((m) => !m.agentId)
+              if (scopeMode === 'agent') return rows.filter((m) => currentAgentId && m.agentId === currentAgentId)
+              return rows.filter(canAccessMemory)
+            }
+
+            const limits = getMemoryLookupLimits(loadSettings())
+            const requestedDepth = typeof depth === 'number' ? depth : 0
+            const requestedLinkedLimit = typeof linkedLimit === 'number' ? linkedLimit : limits.maxLinkedExpansion
+            const effectiveDepth = Math.max(0, Math.min(requestedDepth, limits.maxDepth))
+            const effectiveLinkedLimit = Math.max(0, Math.min(requestedLinkedLimit, limits.maxLinkedExpansion))
+            const maxPerLookup = limits.maxPerLookup
+
+            const normalizedLegacyRefs = Array.isArray(filePaths)
+              ? filePaths.map((f: any) => ({
+                  type: f.kind === 'project' ? 'project' : (f.kind === 'folder' ? 'folder' : 'file'),
+                  path: f.path,
+                  projectRoot: f.projectRoot,
+                  projectName: f.projectName,
+                  note: f.contextSnippet,
+                  timestamp: typeof f.timestamp === 'number' ? f.timestamp : Date.now(),
+                }))
+              : []
+            const normalizedRefs = Array.isArray(references) ? references : []
+            if (project?.rootPath) {
+              normalizedRefs.push({
+                type: 'project',
+                path: project.rootPath,
+                projectRoot: project.rootPath,
+                projectName: project.name,
+                title: project.name,
+                note: project.note,
+                timestamp: Date.now(),
+              })
+            }
+            const mergedRefs = [...normalizedLegacyRefs, ...normalizedRefs]
+
+            const formatEntry = (m: any) => {
+              let line = `[${m.id}] (${m.agentId ? `agent:${m.agentId}` : 'shared'}) ${m.category}/${m.title}: ${m.content}`
+              if (m.references?.length) {
+                line += `\n  refs: ${m.references.map((r: any) => {
+                  const core = r.path || r.title || r.type
+                  const projectMeta = r.projectName ? ` @${r.projectName}` : ''
+                  const existsMeta = typeof r.exists === 'boolean' ? (r.exists ? ' (exists)' : ' (missing)') : ''
+                  return `${r.type}:${core}${projectMeta}${existsMeta}`
+                }).join(', ')}`
+              } else if (m.filePaths?.length) {
+                line += `\n  files: ${m.filePaths.map((f: any) => `${f.path}${f.contextSnippet ? ` (${f.contextSnippet})` : ''}`).join(', ')}`
+              }
+              if (m.image?.path || m.imagePath) line += `\n  image: ${m.image?.path || m.imagePath}`
+              if (m.linkedMemoryIds?.length) line += `\n  linked: ${m.linkedMemoryIds.join(', ')}`
+              return line
+            }
+
+            if (action === 'store') {
+              let storedImage: any = null
+              if (imagePath) {
+                if (!fs.existsSync(imagePath)) {
+                  return `Error: image file not found: ${imagePath}`
+                }
+                try {
+                  storedImage = await storeMemoryImageAsset(imagePath, crypto.randomBytes(6).toString('hex'))
+                } catch {
+                  return `Error: failed to process image at ${imagePath}`
+                }
+              }
+
+              const entry = memDb.add({
+                agentId: scopeMode === 'shared' ? null : currentAgentId,
+                sessionId: ctx?.sessionId || null,
+                category: category || 'note',
+                title: key,
+                content: value || '',
+                references: mergedRefs as any,
+                filePaths: filePaths as any,
+                image: storedImage,
+                imagePath: storedImage?.path || undefined,
+                linkedMemoryIds,
+              })
+              const memoryScope = entry.agentId ? 'agent' : 'shared'
+              let result = `Stored ${memoryScope} memory "${key}" (id: ${entry.id})`
+              if (mergedRefs.length) result += ` with ${mergedRefs.length} reference(s)`
+              if (storedImage?.path) result += ` with image`
+              if (linkedMemoryIds?.length) result += ` linked to ${linkedMemoryIds.length} memor${linkedMemoryIds.length === 1 ? 'y' : 'ies'}`
+              return result
+            }
+            if (action === 'get') {
+              if (effectiveDepth > 0) {
+                const result = memDb.getWithLinked(key, effectiveDepth, maxPerLookup, effectiveLinkedLimit)
+                if (!result) return `Memory not found: ${key}`
+                const accessible = result.entries.filter(canAccessMemory)
+                if (!accessible.length) return 'Error: you do not have access to that memory.'
+                let output = accessible.map(formatEntry).join('\n---\n')
+                if (result.truncated) output += `\n\n[Results truncated at ${maxPerLookup} memories / ${effectiveLinkedLimit} linked expansions]`
+                return output
+              }
+              const found = memDb.get(key)
+              if (!found) return `Memory not found: ${key}`
+              if (!canAccessMemory(found)) return 'Error: you do not have access to that memory.'
+              return formatEntry(found)
+            }
+            if (action === 'search') {
+              if (effectiveDepth > 0) {
+                const result = memDb.searchWithLinked(query || key, undefined, effectiveDepth, maxPerLookup, effectiveLinkedLimit)
+                const accessible = filterScope(result.entries)
+                if (!accessible.length) return 'No memories found.'
+                let output = accessible.map(formatEntry).join('\n')
+                if (result.truncated) output += `\n\n[Results truncated at ${maxPerLookup} memories / ${effectiveLinkedLimit} linked expansions]`
+                return output
+              }
+              const results = filterScope(memDb.search(query || key))
+              if (!results.length) return 'No memories found.'
+              return results.slice(0, maxPerLookup).map(formatEntry).join('\n')
+            }
+            if (action === 'list') {
+              const results = filterScope(memDb.list(undefined, maxPerLookup))
+              if (!results.length) return 'No memories stored yet.'
+              return results.map(formatEntry).join('\n')
+            }
+            if (action === 'delete') {
+              const found = memDb.get(key)
+              if (!found) return `Memory not found: ${key}`
+              if (!canAccessMemory(found)) return 'Error: you do not have access to that memory.'
+              memDb.delete(key)
+              return `Deleted memory "${key}"`
+            }
+            if (action === 'link') {
+              if (!targetIds?.length) return 'Error: targetIds required for link action.'
+              const result = memDb.link(key, targetIds, true)
+              if (!result) return `Memory not found: ${key}`
+              return `Linked memory "${key}" to ${targetIds.length} memor${targetIds.length === 1 ? 'y' : 'ies'} (bidirectional): ${targetIds.join(', ')}`
+            }
+            if (action === 'unlink') {
+              if (!targetIds?.length) return 'Error: targetIds required for unlink action.'
+              const result = memDb.unlink(key, targetIds, true)
+              if (!result) return `Memory not found: ${key}`
+              return `Unlinked ${targetIds.length} memor${targetIds.length === 1 ? 'y' : 'ies'} from "${key}" (bidirectional)`
+            }
+            if (action === 'knowledge_store') {
+              const { addKnowledge } = await import('../memory-db')
+              if (!value) return 'Error: value (content) is required for knowledge_store'
+              const entry = addKnowledge({
+                title: key || 'Untitled',
+                content: value,
+                tags: tags,
+                createdByAgentId: ctx?.agentId || null,
+                createdBySessionId: ctx?.sessionId || null,
+              })
+              return `Knowledge stored: "${entry.title}" (id: ${entry.id})`
+            }
+            if (action === 'knowledge_search') {
+              const { searchKnowledge } = await import('../memory-db')
+              const results = searchKnowledge(query || key || '', tags, 10)
+              if (!results.length) return 'No knowledge entries found.'
+              return results.map(r => `[${r.id}] ${r.title}: ${r.content.slice(0, 200)}`).join('\n---\n')
+            }
+            return `Unknown action "${action}". Use: store, get, search, list, delete, link, unlink, knowledge_store, or knowledge_search.`
+          } catch (err: any) {
+            return `Error: ${err.message}`
+          }
+        },
+        {
+          name: 'memory_tool',
+          description: 'Store and retrieve long-term memories that persist across sessions. Memories can be shared or agent-scoped. Supports file references, image attachments, and linking memories together with depth traversal. Also supports a cross-agent knowledge base via "knowledge_store" and "knowledge_search". Use "store", "get", "search", "list", "delete", "link", "unlink", "knowledge_store", or "knowledge_search".',
+          schema: z.object({
+            action: z.enum(['store', 'get', 'search', 'list', 'delete', 'link', 'unlink', 'knowledge_store', 'knowledge_search']).describe('The action to perform'),
+            key: z.string().describe('For store: memory title. For get/delete/link/unlink: memory ID. For search: optional query fallback.'),
+            value: z.string().optional().describe('The memory content (for store action)'),
+            category: z.string().optional().describe('Category like "note", "fact", "preference", "project", "identity" (for store action, defaults to "note")'),
+            query: z.string().optional().describe('Search query (alternative to key for search action)'),
+            scope: z.enum(['auto', 'shared', 'agent']).optional().describe('Scope hint: auto (shared + own), shared, or agent'),
+            filePaths: z.array(z.object({
+              path: z.string().describe('File or folder path'),
+              contextSnippet: z.string().optional().describe('Brief context about this file reference'),
+              kind: z.enum(['file', 'folder', 'project']).optional().describe('Reference type for legacy filePaths compatibility'),
+              projectRoot: z.string().optional().describe('Optional project root path'),
+              projectName: z.string().optional().describe('Optional project display name'),
+              exists: z.boolean().optional().describe('Optional known existence state'),
+              timestamp: z.number().describe('When this file was referenced'),
+            })).optional().describe('File/folder references to attach to the memory (for store action)'),
+            references: z.array(z.object({
+              type: z.enum(['project', 'folder', 'file', 'task', 'session', 'url']),
+              path: z.string().optional(),
+              projectRoot: z.string().optional(),
+              projectName: z.string().optional(),
+              title: z.string().optional(),
+              note: z.string().optional(),
+              timestamp: z.number().optional(),
+            })).optional().describe('Structured references attached to the memory (preferred over filePaths).'),
+            project: z.object({
+              rootPath: z.string().describe('Project/workspace root path'),
+              name: z.string().optional().describe('Optional project display name'),
+              note: z.string().optional().describe('Optional note about the project context'),
+            }).optional().describe('Shortcut to add a project reference on store action.'),
+            imagePath: z.string().optional().describe('Path to an image file to attach (will be compressed and stored). For store action.'),
+            linkedMemoryIds: z.array(z.string()).optional().describe('IDs of other memories to link to (for store action)'),
+            depth: z.number().optional().describe('How deep to traverse linked memories (for get/search). Respects configured maxDepth limit. Default: 0 (no traversal).'),
+            linkedLimit: z.number().optional().describe('Max linked memories expanded during traversal. Respects configured server cap.'),
+            targetIds: z.array(z.string()).optional().describe('Memory IDs to link/unlink (for link/unlink actions)'),
+            tags: z.array(z.string()).optional().describe('Tags for categorizing knowledge entries'),
+          }),
+        },
+      ),
+    )
+  }
+
+  return tools
+}