@soederpop/luca 0.1.3 → 0.2.1

package/src/introspection/generated.web.ts

@@ -1,7 +1,7 @@
 import { setBuildTimeData, setContainerBuildTimeData } from './index.js';
 
 // Auto-generated introspection registry data
-// Generated at: 2026-04-03T01:24:52.187Z
+// Generated at: 2026-04-05T06:58:06.168Z
 
 setBuildTimeData('features.containerLink', {
   "id": "features.containerLink",

package/src/node/features/content-db.ts

@@ -5,6 +5,7 @@ import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { realpathSync } from 'node:fs'
 import type { GrepOptions } from './grep.js'
+import type { Helper } from '../../helper.js'
 
 export const ContentDbStateSchema = FeatureStateSchema.extend({
   loaded: z.boolean().default(false).describe('Whether the content collection has been loaded and parsed'),
@@ -49,67 +50,93 @@ export class ContentDb extends Feature<ContentDbState, ContentDbOptions> {
   static override tools: Record<string, { schema: z.ZodType; handler?: Function }> = {
     getCollectionOverview: {
       schema: z.object({}).describe(
-        'Get a high-level overview of the document collection: models, document counts, directory tree, and search index status. Call this first to understand what is available.'
+        'Get a high-level overview of the document collection: what models exist, how many documents each has, the directory tree, and search index status. Call this FIRST to understand the collection before exploring individual documents.'
       ),
     },
     listDocuments: {
       schema: z.object({
-        model: z.string().optional().describe('Filter to documents belonging to this model name'),
-        glob: z.string().optional().describe('Glob pattern to filter document path IDs (e.g. "guides/*", "apis/**")'),
+        model: z.string().optional().describe('Filter to documents of this model type (e.g. "Plan", "Task"). Get model names from getCollectionOverview.'),
+        glob: z.string().optional().describe('Glob pattern to filter by document path (e.g. "guides/*", "apis/**/*.md")'),
       }).describe(
-        'List available document IDs in the collection, optionally filtered by model or glob pattern.'
+        'List document IDs in the collection. Use this to browse what\'s available before reading. Filter by model or glob to narrow results.'
       ),
     },
     readDocument: {
       schema: z.object({
-        id: z.string().describe('The document path ID to read (e.g. "guides/intro")'),
-        include: z.array(z.string()).optional().describe('Only return these section headings'),
-        exclude: z.array(z.string()).optional().describe('Remove these section headings from the output'),
-        meta: z.boolean().optional().describe('Include YAML frontmatter in the output'),
+        id: z.string().describe('The document path ID (e.g. "guides/intro", "apis/auth"). Get valid IDs from listDocuments.'),
+        include: z.array(z.string()).optional().describe('Only return sections with these headings. Use to read specific parts of long documents without loading everything.'),
+        exclude: z.array(z.string()).optional().describe('Skip sections with these headings. Use to filter out irrelevant parts.'),
+        meta: z.boolean().optional().describe('Include the YAML frontmatter (title, status, tags, etc.) in the output. Useful for understanding document metadata.'),
       }).describe(
-        'Read a single document by its path ID. Use include/exclude to read only specific sections and avoid loading unnecessary content.'
+        'Read a document by its path ID. Use include/exclude to request only the sections you need — don\'t load an entire document when you only need one section.'
       ),
     },
     readMultipleDocuments: {
       schema: z.object({
-        ids: z.array(z.string()).describe('Array of document path IDs to read'),
-        include: z.array(z.string()).optional().describe('Only return these section headings from each document'),
-        exclude: z.array(z.string()).optional().describe('Remove these section headings from each document'),
-        meta: z.boolean().optional().describe('Include YAML frontmatter in the output'),
+        ids: z.array(z.string()).describe('Array of document path IDs to read. Get valid IDs from listDocuments.'),
+        include: z.array(z.string()).optional().describe('Only return sections with these headings from each document.'),
+        exclude: z.array(z.string()).optional().describe('Skip sections with these headings from each document.'),
+        meta: z.boolean().optional().describe('Include YAML frontmatter for each document.'),
       }).describe(
-        'Read multiple documents at once, concatenated with dividers. Use include/exclude to focus on relevant sections.'
+        'Read multiple documents in one call. More efficient than calling readDocument in a loop. Returns documents concatenated with dividers.'
       ),
     },
     queryDocuments: {
       schema: z.object({
-        model: z.string().describe('The model name to query (e.g. "Plan", "Task")'),
-        where: z.string().optional().describe('Filter conditions as JSON string, e.g. \'{ "meta.status": "approved" }\' or \'{ "meta.priority": { "$gt": 3 } }\''),
-        sort: z.string().optional().describe('Sort specification as JSON string, e.g. \'{ "meta.priority": "desc" }\''),
-        limit: z.number().optional().describe('Maximum number of results to return'),
-        offset: z.number().optional().describe('Number of results to skip'),
-        select: z.array(z.string()).optional().describe('Fields to include in output (e.g. ["id", "title", "meta.status"])'),
+        model: z.string().describe('The model name to query (e.g. "Plan", "Task", "Guide"). Must match a model defined in the collection — check getCollectionOverview.'),
+        where: z.string().optional().describe('MongoDB-style filter as a JSON string. Dot notation for nested fields. Examples: \'{"meta.status": "approved"}\', \'{"meta.priority": {"$gt": 3}}\', \'{"meta.tags": {"$in": ["urgent"]}}\''),
+        sort: z.string().optional().describe('Sort as a JSON string. Example: \'{"meta.priority": "desc"}\', \'{"meta.createdAt": "asc"}\''),
+        limit: z.number().optional().describe('Maximum number of results. Default: all matching documents.'),
+        offset: z.number().optional().describe('Skip this many results (for pagination).'),
+        select: z.array(z.string()).optional().describe('Only include these fields in output (e.g. ["id", "title", "meta.status"]). Reduces noise when you only need specific metadata.'),
       }).describe(
-        'Query documents by model with MongoDB-style filtering, sorting, and pagination. Returns serialized model instances.'
+        'Query documents by model with filtering, sorting, and pagination. Use this when you need to find documents matching specific criteria (status, priority, tags, dates) rather than browsing by name.'
       ),
     },
     searchContent: {
       schema: z.object({
-        pattern: z.string().describe('Regex pattern to search for across all documents'),
-        caseSensitive: z.boolean().optional().describe('Whether the search is case-sensitive (default: false)'),
+        pattern: z.string().describe('Regex pattern to search for across all document content. Examples: "TODO|FIXME", "authentication", "def.*handler"'),
+        caseSensitive: z.boolean().optional().describe('Case-sensitive search. Default: false (case insensitive).'),
       }).describe(
-        'Text/regex search (grep) across all documents in the collection. Returns matching lines with file context.'
+        'Text/regex search (grep) across all documents. Use for exact pattern matching, code references, or finding specific terms. Returns matching lines with file context. For natural language questions, use semanticSearch instead.'
       ),
     },
     semanticSearch: {
       schema: z.object({
-        query: z.string().describe('Natural language search query'),
-        limit: z.number().optional().describe('Maximum number of results (default: 10)'),
+        query: z.string().describe('A natural language question or topic description. Example: "how does the authentication flow work?" or "deployment configuration options"'),
+        limit: z.number().optional().describe('Maximum results to return. Default: 10.'),
       }).describe(
-        'Semantic search across documents using keyword + vector similarity. Falls back to text search if no search index exists.'
+        'Search documents using natural language — combines keyword matching with semantic similarity. Best for questions and topic exploration. Falls back to text search if no vector index exists. For exact pattern matching, use searchContent instead.'
       ),
     },
   }
 
+  /**
+   * When an assistant uses contentDb, inject system prompt guidance
+   * about progressive document exploration.
+   */
+  override setupToolsConsumer(consumer: Helper) {
+    if (typeof (consumer as any).addSystemPromptExtension === 'function') {
+      (consumer as any).addSystemPromptExtension('contentDb', [
+        '## Document Collection',
+        '',
+        'You have access to a structured document collection (markdown files with frontmatter, organized by model/type).',
+        '',
+        '**Progressive exploration — go broad to narrow:**',
+        '1. `getCollectionOverview` — start here. Shows models, document counts, and directory structure.',
+        '2. `listDocuments` — browse document IDs, optionally filtered by model or glob.',
+        '3. `readDocument` — read a specific document. Use `include`/`exclude` to skip irrelevant sections.',
+        '4. `queryDocuments` — filter documents by metadata (status, priority, tags, etc.) with MongoDB-style queries.',
+        '',
+        '**Searching:**',
+        '- `semanticSearch` — best for natural language questions ("how does authentication work?")',
+        '- `searchContent` — best for exact patterns, code references, or regex across all documents',
+        '',
+        '**Efficiency:** Don\'t read entire documents when you only need one section. Use `include` to request specific headings. Use `readMultipleDocuments` to batch reads instead of calling `readDocument` in a loop.',
+      ].join('\n'))
+    }
+  }
+
   override get initialState(): ContentDbState {
     return {
       ...super.initialState,

package/src/node/features/process-manager.ts

@@ -4,6 +4,7 @@ import { Feature } from '../feature.js'
 import { State } from '../../state.js'
 import { Bus, type EventMap } from '../../bus.js'
 import type { ChildProcess } from './proc.js'
+import type { Helper } from '../../helper.js'
 
 // ─── Output Buffer ─────────────────────────────────────────────────────────
 
@@ -439,43 +440,43 @@ export class ProcessManager extends Feature {
   static override tools: Record<string, { schema: z.ZodType; handler?: Function }> = {
     spawnProcess: {
       schema: z.object({
-        command: z.string().describe('The command to execute (e.g. "node", "bun", "python")'),
-        args: z.string().optional().describe('Space-separated arguments to pass to the command'),
-        tag: z.string().optional().describe('A label for this process so you can find it later'),
-        cwd: z.string().optional().describe('Working directory for the process'),
+        command: z.string().describe('The executable to run (e.g. "node", "bun", "python"). NOT a shell command — use runCommand for shell syntax like pipes or &&.'),
+        args: z.string().optional().describe('Arguments as a single space-separated string. WARNING: spaces are used to split args, so paths with spaces will break. For complex argument quoting, prefer runCommand instead.'),
+        tag: z.string().optional().describe('A short, descriptive label for this process (e.g. "api-server", "file-watcher"). Always set a tag — it makes the process easy to find later with getProcessOutput and killProcess.'),
+        cwd: z.string().optional().describe('Working directory for the process. Defaults to the project root.'),
       }).describe(
-        'Spawn a long-running process (server, watcher, daemon) that runs in the background. Returns immediately with a process ID you can use to check status or kill it later.'
+        'Start a long-running background process (server, watcher, daemon). Returns immediately with a process ID — the process keeps running. Use this for anything that runs indefinitely. After spawning, call getProcessOutput to check if it started successfully. Always set a tag.'
       ),
     },
     runCommand: {
       schema: z.object({
-        command: z.string().describe('The command to execute (e.g. "npm install", "bun test")'),
-        cwd: z.string().optional().describe('Working directory for the command'),
+        command: z.string().describe('A full shell command string (executed via sh -c). Supports pipes, &&, redirects, env vars, globs — anything you can type in a terminal. Examples: "bun test", "npm install && npm run build", "cat logs/*.txt | grep ERROR"'),
+        cwd: z.string().optional().describe('Working directory for the command. Defaults to the project root.'),
       }).describe(
-        'Run a command and wait for it to complete. Returns the full stdout/stderr output and exit code. Use this for commands you expect to finish (builds, installs, tests).'
+        'Run a shell command and wait for it to complete. Returns stdout, stderr, and exit code. Use this for commands that finish on their own — builds, installs, tests, one-off scripts. For anything that runs forever (servers, watchers), use spawnProcess instead.'
       ),
     },
     listProcesses: {
       schema: z.object({}).describe(
-        'List all tracked processes with their status, PID, command, uptime, and a preview of recent output.'
+        'List all tracked background processes with their status, PID, command, uptime, and the last few lines of output. Call this to get an overview before deciding which process to inspect or kill.'
       ),
     },
     getProcessOutput: {
       schema: z.object({
-        id: z.string().optional().describe('The process ID to get output for'),
-        tag: z.string().optional().describe('The tag of the process to get output for'),
-        stream: z.string().optional().describe('Which stream to read: "stdout" (default) or "stderr"'),
+        id: z.string().optional().describe('The process ID (returned by spawnProcess). Provide either id or tag, not both.'),
+        tag: z.string().optional().describe('The tag you assigned when spawning the process. Provide either id or tag, not both.'),
+        stream: z.string().optional().describe('"stdout" (default) or "stderr". Check stderr when a process crashes or behaves unexpectedly.'),
       }).describe(
-        'Peek at a process\'s buffered output — shows the first 20 lines and last 50 lines of stdout or stderr.'
+        'Read a background process\'s buffered output — the first 20 lines (startup) and last 50 lines (recent activity). Call this after spawning to verify the process started correctly, and periodically to monitor its health.'
       ),
     },
     killProcess: {
       schema: z.object({
-        id: z.string().optional().describe('The process ID to kill'),
-        tag: z.string().optional().describe('The tag of the process to kill'),
-        signal: z.string().optional().describe('Signal to send: "SIGTERM" (default, graceful) or "SIGKILL" (force)'),
+        id: z.string().optional().describe('The process ID to kill. Provide either id or tag, not both.'),
+        tag: z.string().optional().describe('The tag of the process to kill. Provide either id or tag, not both.'),
+        signal: z.string().optional().describe('"SIGTERM" (default) for graceful shutdown, "SIGKILL" to force-kill a stuck process. Try SIGTERM first.'),
       }).describe(
-        'Kill a running process by ID or tag.'
+        'Stop a running background process. Use SIGTERM (default) for graceful shutdown. If a process doesn\'t respond, follow up with SIGKILL. Always clean up processes you spawned when they\'re no longer needed.'
       ),
     },
   }
@@ -593,6 +594,38 @@ export class ProcessManager extends Feature {
     return { id: handler.id, status: handler.status, signal, message: 'Process killed.' }
   }
 
+  /**
+   * When an assistant uses processManager, inject system prompt guidance
+   * about how to manage processes safely and effectively.
+   */
+  override setupToolsConsumer(consumer: Helper) {
+    if (typeof (consumer as any).addSystemPromptExtension === 'function') {
+      (consumer as any).addSystemPromptExtension('processManager', [
+        '## Process Management',
+        '',
+        '**Choosing the right tool:**',
+        '- `runCommand` — for anything that finishes on its own (builds, tests, installs, queries). Blocks until done.',
+        '- `spawnProcess` — for anything that runs indefinitely (servers, watchers, tails). Returns immediately.',
+        '- When in doubt: if you\'d press Ctrl-C to stop it, use `spawnProcess`. If you\'d wait for it, use `runCommand`.',
+        '',
+        '**After spawning a process:**',
+        '1. Always assign a descriptive `tag` so you can reference it later',
+        '2. Call `getProcessOutput` within a few seconds to verify it started correctly',
+        '3. Check `stderr` if the process crashes or output looks wrong',
+        '',
+        '**Monitoring:**',
+        '- Call `listProcesses` to see all running and finished processes at a glance',
+        '- Call `getProcessOutput` to read recent output — it keeps the first 20 and last 50 lines',
+        '- A process with status "crashed" exited with a non-zero code — check its stderr for the error',
+        '',
+        '**Cleanup:**',
+        '- Always `killProcess` background processes when they\'re no longer needed',
+        '- Use SIGTERM (default) first for graceful shutdown. Only use SIGKILL if SIGTERM doesn\'t work.',
+        '- If you spawned it, you\'re responsible for killing it',
+      ].join('\n'))
+    }
+  }
+
   // ─── Core API ───────────────────────────────────────────────────────────
 
   /**

package/src/python/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated Python bridge script
-// Generated at: 2026-04-03T01:24:54.795Z
+// Generated at: 2026-04-05T06:58:08.827Z
 // Source: src/python/bridge.py
 //
 // Do not edit manually. Run: luca build-python-bridge

package/src/scaffolds/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated scaffold and MCP readme content
-// Generated at: 2026-04-03T01:24:53.146Z
+// Generated at: 2026-04-05T06:58:07.148Z
 // Source: docs/scaffolds/*.md, docs/examples/assistant/, and docs/mcp/readme.md
 //
 // Do not edit manually. Run: luca build-scaffolds

package/test/assistant.test.ts

@@ -15,18 +15,27 @@ describe('Assistant', () => {
 			expect(assistant.systemPrompt).toContain('coding assistant')
 		})
 
-		it('loads tools from tools.ts via the VM', () => {
-			const assistant = container.feature('assistant', { folder: 'assistants/codingAssistant' })
+		it('loads tools from codingTools feature after start', async () => {
+			const assistant = container.feature('assistant', {
+				folder: 'assistants/codingAssistant',
+				local: true,
+				model: 'qwen/qwen3-8b',
+			})
+			await assistant.start()
 			const tools = assistant.availableTools
 			expect(tools).toContain('rg')
 			expect(tools).toContain('ls')
 			expect(tools).toContain('cat')
-			expect(tools).toContain('pwd')
 			expect(tools.length).toBeGreaterThan(0)
 		})
 
-		it('tools have descriptions and parameter schemas', () => {
-			const assistant = container.feature('assistant', { folder: 'assistants/codingAssistant' })
+		it('tools have descriptions and parameter schemas', async () => {
+			const assistant = container.feature('assistant', {
+				folder: 'assistants/codingAssistant',
+				local: true,
+				model: 'qwen/qwen3-8b',
+			})
+			await assistant.start()
 			const { rg, ls, cat } = assistant.tools
 			expect(rg.description.length).toBeGreaterThan(0)
 			expect(rg.parameters.type).toBe('object')

package/test-integration/memory.test.ts

@@ -0,0 +1,204 @@
+import {
+  requireEnv,
+  describeWithRequirements,
+  createAGIContainer,
+  API_TIMEOUT,
+} from './helpers'
+import type { AGIContainer } from '../src/agi/container.server'
+import type { Memory } from '../src/agi/features/agent-memory'
+
+const openaiKey = requireEnv('OPENAI_API_KEY')
+
+describeWithRequirements('Memory Integration', [openaiKey], () => {
+  let container: AGIContainer
+  let mem: Memory
+
+  beforeAll(async () => {
+    container = createAGIContainer()
+    mem = container.feature('memory', { namespace: 'test-integration' }) as unknown as Memory
+    await mem.initDb()
+    await mem.wipeAll()
+  })
+
+  afterAll(async () => {
+    await mem.wipeAll()
+  })
+
+  describe('Feature registration', () => {
+    it('registers in the container', () => {
+      expect(container.features.available).toContain('memory')
+    })
+
+    it('has correct shortcut', () => {
+      const { Memory: MemClass } = require('../src/agi/features/agent-memory')
+      expect(MemClass.shortcut).toBe('features.memory')
+    })
+
+    it('initializes database', () => {
+      expect(mem.state.get('dbReady')).toBe(true)
+    })
+  })
+
+  describe('CRUD operations', () => {
+    it('creates and retrieves a memory', async () => {
+      const m = await mem.create('facts', 'Jonathan is a software engineer based in Austin')
+      expect(m.id).toBeGreaterThan(0)
+      expect(m.category).toBe('facts')
+      expect(m.document).toBe('Jonathan is a software engineer based in Austin')
+
+      const fetched = await mem.get('facts', m.id)
+      expect(fetched).not.toBeNull()
+      expect(fetched!.document).toBe(m.document)
+    }, API_TIMEOUT)
+
+    it('updates a memory', async () => {
+      const m = await mem.create('facts', 'Prefers dark mode')
+      const updated = await mem.update('facts', m.id, {
+        text: 'Prefers dark mode, especially Dracula theme',
+        metadata: { updated: 'true' },
+      })
+      expect(updated!.document).toBe('Prefers dark mode, especially Dracula theme')
+      expect(updated!.metadata.updated).toBe('true')
+    }, API_TIMEOUT)
+
+    it('deletes a memory', async () => {
+      const m = await mem.create('scratch', 'temporary memory')
+      expect(await mem.delete('scratch', m.id)).toBe(true)
+      expect(await mem.get('scratch', m.id)).toBeNull()
+    }, API_TIMEOUT)
+
+    it('lists categories', async () => {
+      const cats = await mem.categories()
+      expect(cats).toContain('facts')
+    })
+
+    it('counts memories', async () => {
+      const total = await mem.count()
+      expect(total).toBeGreaterThan(0)
+      const factCount = await mem.count('facts')
+      expect(factCount).toBeGreaterThan(0)
+    })
+
+    it('gets all memories with filtering', async () => {
+      await mem.create('prefs', 'Likes iterative delivery', { source: 'onboarding' })
+      await mem.create('prefs', 'Prefers concise responses')
+
+      const onboarding = await mem.getAll('prefs', { filterMetadata: { source: 'onboarding' } })
+      expect(onboarding.length).toBeGreaterThan(0)
+      expect(onboarding.every(m => m.metadata.source === 'onboarding')).toBe(true)
+    }, API_TIMEOUT)
+  })
+
+  describe('Semantic search', () => {
+    it('finds relevant memories by query', async () => {
+      const results = await mem.search('facts', 'Where does the user live?', 3)
+      expect(results.length).toBeGreaterThan(0)
+      expect(results[0].distance).toBeLessThan(1)
+    }, API_TIMEOUT)
+  })
+
+  describe('Deduplication', () => {
+    it('blocks near-duplicate memories', async () => {
+      const before = await mem.count('facts')
+      const dup = await mem.createUnique('facts', 'Jonathan is a software engineer living in Austin, TX')
+      const after = await mem.count('facts')
+      expect(dup).toBeNull()
+      expect(after).toBe(before)
+    }, API_TIMEOUT)
+  })
+
+  describe('Epochs and events', () => {
+    it('tracks epoch state', () => {
+      expect(mem.getEpoch()).toBe(1)
+    })
+
+    it('creates events and increments epoch', async () => {
+      await mem.createEvent('User started a new project')
+      await mem.incrementEpoch()
+      expect(mem.getEpoch()).toBe(2)
+
+      await mem.createEvent('User requested a test script')
+
+      const e1 = await mem.getEvents({ epoch: 1 })
+      const e2 = await mem.getEvents({ epoch: 2 })
+      expect(e1.length).toBeGreaterThan(0)
+      expect(e2.length).toBeGreaterThan(0)
+    }, API_TIMEOUT)
+  })
+
+  describe('Export and import', () => {
+    it('roundtrips through export/import', async () => {
+      const exported = await mem.exportToJson()
+      expect(exported.memories.length).toBeGreaterThan(0)
+
+      await mem.wipeAll()
+      expect(await mem.count()).toBe(0)
+
+      const imported = await mem.importFromJson(exported)
+      expect(imported).toBe(exported.memories.length)
+      expect(await mem.count()).toBe(exported.memories.length)
+    }, API_TIMEOUT * 3)
+  })
+
+  describe('Tool interface (toTools)', () => {
+    it('exposes tools via standard toTools() pattern', () => {
+      const { schemas, handlers } = mem.toTools()
+      expect(Object.keys(schemas)).toContain('remember')
+      expect(Object.keys(schemas)).toContain('recall')
+      expect(Object.keys(schemas)).toContain('forgetCategory')
+      expect(Object.keys(schemas)).toContain('listCategories')
+      expect(typeof handlers.remember).toBe('function')
+      expect(typeof handlers.recall).toBe('function')
+      expect(typeof handlers.forgetCategory).toBe('function')
+      expect(typeof handlers.listCategories).toBe('function')
+    })
+
+    it('toTools only/except filtering works', () => {
+      const { schemas: onlySchemas } = mem.toTools({ only: ['remember', 'recall'] })
+      expect(Object.keys(onlySchemas)).toEqual(['remember', 'recall'])
+
+      const { schemas: exceptSchemas } = mem.toTools({ except: ['forgetCategory'] })
+      expect(Object.keys(exceptSchemas)).not.toContain('forgetCategory')
+      expect(Object.keys(exceptSchemas)).toContain('remember')
+    })
+
+    it('remember tool stores and deduplicates', async () => {
+      const { handlers } = mem.toTools()
+      const result = await handlers.remember({ category: 'facts', text: 'Has a golden retriever named Max' })
+      expect(result.stored).toBe(true)
+
+      const dup = await handlers.remember({ category: 'facts', text: 'Has a golden retriever named Max' })
+      expect(dup.stored).toBe(false)
+    }, API_TIMEOUT)
+
+    it('recall tool searches memories', async () => {
+      const { handlers } = mem.toTools()
+      const results = await handlers.recall({ category: 'facts', query: 'pets and animals', n_results: 2 })
+      expect(results.length).toBeGreaterThan(0)
+      expect(results[0]).toHaveProperty('document')
+      expect(results[0]).toHaveProperty('distance')
+    }, API_TIMEOUT)
+
+    it('listCategories tool returns counts', async () => {
+      const { handlers } = mem.toTools()
+      const result = await handlers.listCategories()
+      expect(result.categories).toBeDefined()
+      expect(typeof result.categories.facts).toBe('number')
+    })
+  })
+
+  describe('Wipe operations', () => {
+    it('wipeCategory removes only that category', async () => {
+      const before = await mem.count()
+      const deleted = await mem.wipeCategory('scratch')
+      const after = await mem.count()
+      expect(after).toBeLessThanOrEqual(before)
+    })
+
+    it('wipeAll removes everything and resets epoch', async () => {
+      await mem.wipeAll()
+      expect(await mem.count()).toBe(0)
+      expect(mem.getEpoch()).toBe(1)
+    })
+  })
+})