mixdog 0.8.0 → 0.9.0

package/src/runtime/memory/lib/trace-store.mjs

@@ -8,7 +8,7 @@ function __mixdogMemoryLog(...args) {
 // Uses pg-adapter (schema='trace') so trace_events live in the trace schema.
 // Isolated from memory schema; shares the same PG instance.
 
-import { ensurePgInstance, checkedConnect } from './pg/adapter.mjs'
+import { ensurePgInstance, checkedConnect, closePgInstance } from './pg/adapter.mjs'
 import { resolve } from 'path'
 
 const dbs = new Map()
@@ -123,15 +123,15 @@ async function init(client) {
 }
 
 // ---------------------------------------------------------------------------
-// Bridge-specific analytic tables (added post-init via initBridgeTables)
+// Agent-specific analytic tables (added post-init via initAgentTables)
 // ---------------------------------------------------------------------------
 
 // Called once per openTraceDatabase boot (after the advisory lock is released).
 // Safe to call concurrently — all DDL is IF NOT EXISTS.
-export async function initBridgeTables(client) {
-  // ── bridge_calls: one row per tool invocation ─────────────────────────────
+export async function initAgentTables(client) {
+  // ── agent_calls: one row per tool invocation ─────────────────────────────
   await client.query(`
-    CREATE TABLE IF NOT EXISTS bridge_calls (
+    CREATE TABLE IF NOT EXISTS agent_calls (
       id           BIGSERIAL PRIMARY KEY,
       session_id   TEXT        NOT NULL,
       iteration    INT,
@@ -142,18 +142,18 @@ export async function initBridgeTables(client) {
       tool_args    JSONB
     )
   `)
-  await client.query(`CREATE INDEX IF NOT EXISTS idx_bc_session   ON bridge_calls (session_id, iteration)`)
-  await client.query(`CREATE INDEX IF NOT EXISTS idx_bc_ts        ON bridge_calls USING BRIN (ts)`)
-  await client.query(`CREATE INDEX IF NOT EXISTS idx_bc_tool_name ON bridge_calls (tool_name)`)
+  await client.query(`CREATE INDEX IF NOT EXISTS idx_ac_session   ON agent_calls (session_id, iteration)`)
+  await client.query(`CREATE INDEX IF NOT EXISTS idx_ac_ts        ON agent_calls USING BRIN (ts)`)
+  await client.query(`CREATE INDEX IF NOT EXISTS idx_ac_tool_name ON agent_calls (tool_name)`)
   // Expression indexes covering the two actual query patterns (md5 dedup + path lookup).
   // The old GIN index had no @> callers and was write-heavy; dropped in favour of these.
-  await client.query(`CREATE INDEX IF NOT EXISTS idx_bc_args_md5  ON bridge_calls (session_id, tool_name, md5(tool_args::text))`)
-  await client.query(`CREATE INDEX IF NOT EXISTS idx_bc_args_path ON bridge_calls (session_id, tool_name, (tool_args->>'path'), ts, id)`)
-  await client.query(`DROP INDEX IF EXISTS idx_bc_args`)
+  await client.query(`CREATE INDEX IF NOT EXISTS idx_ac_args_md5  ON agent_calls (session_id, tool_name, md5(tool_args::text))`)
+  await client.query(`CREATE INDEX IF NOT EXISTS idx_ac_args_path ON agent_calls (session_id, tool_name, (tool_args->>'path'), ts, id)`)
+  await client.query(`DROP INDEX IF EXISTS idx_ac_args`)
 
-  // ── bridge_llm: one row per LLM usage event ───────────────────────────────
+  // ── agent_llm: one row per LLM usage event ───────────────────────────────
   await client.query(`
-    CREATE TABLE IF NOT EXISTS bridge_llm (
+    CREATE TABLE IF NOT EXISTS agent_llm (
       id                 BIGSERIAL PRIMARY KEY,
       session_id         TEXT        NOT NULL,
       iteration          INT,
@@ -167,13 +167,13 @@ export async function initBridgeTables(client) {
       response_id        TEXT
     )
   `)
-  await client.query(`CREATE INDEX IF NOT EXISTS idx_bl_session ON bridge_llm (session_id, iteration)`)
-  await client.query(`CREATE INDEX IF NOT EXISTS idx_bl_ts      ON bridge_llm USING BRIN (ts)`)
-  await client.query(`CREATE INDEX IF NOT EXISTS idx_bl_model   ON bridge_llm (model)`)
+  await client.query(`CREATE INDEX IF NOT EXISTS idx_al_session ON agent_llm (session_id, iteration)`)
+  await client.query(`CREATE INDEX IF NOT EXISTS idx_al_ts      ON agent_llm USING BRIN (ts)`)
+  await client.query(`CREATE INDEX IF NOT EXISTS idx_al_model   ON agent_llm (model)`)
 
-  // ── bridge_sessions: denormalised summary upserted on each insert ─────────
+  // ── agent_sessions: denormalised summary upserted on each insert ─────────
   await client.query(`
-    CREATE TABLE IF NOT EXISTS bridge_sessions (
+    CREATE TABLE IF NOT EXISTS agent_sessions (
       session_id          TEXT        PRIMARY KEY,
       role                TEXT,
       model               TEXT,
@@ -189,7 +189,7 @@ export async function initBridgeTables(client) {
 }
 
 // ---------------------------------------------------------------------------
-// insertBridgeCalls — batch insert tool rows + upsert session summary
+// insertAgentCalls — batch insert tool rows + upsert session summary
 // ---------------------------------------------------------------------------
 const TOOL_ARGS_MAX_BYTES = 65536  // 64 KB cap; oversized → sha256 + truncated preview
 
@@ -207,7 +207,7 @@ function _capToolArgsSync(args) {
   return { _oversized: true, sha256: _createHash('sha256').update(raw).digest('hex'), preview: raw.slice(0, 512) }
 }
 
-export async function insertBridgeCalls(db, events) {
+export async function insertAgentCalls(db, events) {
   if (!Array.isArray(events) || events.length === 0) return { calls: 0, llm: 0 }
   const toolRows = []
   const llmRows  = []
@@ -237,7 +237,7 @@ export async function insertBridgeCalls(db, events) {
 
   // Wrap all three inserts in a single transaction — one flush/fsync.
   // checkedConnect ensures search_path = trace, public on fresh connections;
-  // raw _pool.connect() leaves search_path at PG default and bridge_* lookups
+  // raw _pool.connect() leaves search_path at PG default and agent_* lookups
   // resolve in the wrong schema.
   const client = await checkedConnect(db._pool, 'trace')
   try {
@@ -245,7 +245,7 @@ export async function insertBridgeCalls(db, events) {
 
   if (toolRows.length > 0) {
     await client.query(
-      `INSERT INTO bridge_calls (session_id,iteration,ts,tool_name,tool_kind,tool_ms,tool_args)
+      `INSERT INTO agent_calls (session_id,iteration,ts,tool_name,tool_kind,tool_ms,tool_args)
        SELECT u.session_id, u.iteration::int, u.ts::timestamptz,
               u.tool_name, u.tool_kind, u.tool_ms::int, u.tool_args::jsonb
        FROM unnest($1::text[],$2::int[],$3::text[],$4::text[],$5::text[],$6::int[],$7::text[])
@@ -264,7 +264,7 @@ export async function insertBridgeCalls(db, events) {
 
   if (llmRows.length > 0) {
     await client.query(
-      `INSERT INTO bridge_llm (session_id,iteration,ts,model,input_tokens,output_tokens,cached_tokens,cache_write_tokens,prompt_tokens,response_id)
+      `INSERT INTO agent_llm (session_id,iteration,ts,model,input_tokens,output_tokens,cached_tokens,cache_write_tokens,prompt_tokens,response_id)
        SELECT u.session_id, u.iteration::int, u.ts::timestamptz,
               u.model, u.input_tokens::int, u.output_tokens::int,
               u.cached_tokens::int, u.cache_write_tokens::int,
@@ -330,7 +330,7 @@ export async function insertBridgeCalls(db, events) {
     })
   }
 
-  // Coalesce bridge_sessions upserts: batch all sessions in one unnest INSERT.
+  // Coalesce agent_sessions upserts: batch all sessions in one unnest INSERT.
   // Also within the same transaction.
   if (sessionMap.size > 0) {
     const sids = [], roles = [], models = [], ts0s = [], ts1s = [],
@@ -343,7 +343,7 @@ export async function insertBridgeCalls(db, events) {
       tinputs.push(String(s.total_input)); toutputs.push(String(s.total_output))
     }
     await client.query(`
-      INSERT INTO bridge_sessions (session_id, role, model, started_at, last_seen_at, tool_calls, llm_calls, max_iteration, total_input_tokens, total_output_tokens)
+      INSERT INTO agent_sessions (session_id, role, model, started_at, last_seen_at, tool_calls, llm_calls, max_iteration, total_input_tokens, total_output_tokens)
       SELECT u.session_id, u.role, u.model,
              u.started_at::timestamptz, u.last_seen_at::timestamptz,
              u.tool_calls::int, u.llm_calls::int, u.max_iteration::int,
@@ -351,15 +351,15 @@ export async function insertBridgeCalls(db, events) {
       FROM unnest($1::text[],$2::text[],$3::text[],$4::text[],$5::text[],$6::int[],$7::int[],$8::int[],$9::text[],$10::text[])
            AS u(session_id,role,model,started_at,last_seen_at,tool_calls,llm_calls,max_iteration,total_input_tokens,total_output_tokens)
       ON CONFLICT (session_id) DO UPDATE SET
-        role                = COALESCE(EXCLUDED.role, bridge_sessions.role),
-        model               = COALESCE(EXCLUDED.model, bridge_sessions.model),
-        started_at          = LEAST(bridge_sessions.started_at, EXCLUDED.started_at),
-        last_seen_at        = GREATEST(bridge_sessions.last_seen_at, EXCLUDED.last_seen_at),
-        tool_calls          = bridge_sessions.tool_calls + EXCLUDED.tool_calls,
-        llm_calls           = bridge_sessions.llm_calls  + EXCLUDED.llm_calls,
-        max_iteration       = GREATEST(bridge_sessions.max_iteration, EXCLUDED.max_iteration),
-        total_input_tokens  = bridge_sessions.total_input_tokens  + EXCLUDED.total_input_tokens,
-        total_output_tokens = bridge_sessions.total_output_tokens + EXCLUDED.total_output_tokens
+        role                = COALESCE(EXCLUDED.role, agent_sessions.role),
+        model               = COALESCE(EXCLUDED.model, agent_sessions.model),
+        started_at          = LEAST(agent_sessions.started_at, EXCLUDED.started_at),
+        last_seen_at        = GREATEST(agent_sessions.last_seen_at, EXCLUDED.last_seen_at),
+        tool_calls          = agent_sessions.tool_calls + EXCLUDED.tool_calls,
+        llm_calls           = agent_sessions.llm_calls  + EXCLUDED.llm_calls,
+        max_iteration       = GREATEST(agent_sessions.max_iteration, EXCLUDED.max_iteration),
+        total_input_tokens  = agent_sessions.total_input_tokens  + EXCLUDED.total_input_tokens,
+        total_output_tokens = agent_sessions.total_output_tokens + EXCLUDED.total_output_tokens
     `, [sids, roles, models, ts0s, ts1s, tcalls, lcalls, maxiters, tinputs, toutputs])
   }
 
@@ -519,8 +519,8 @@ export async function openTraceDatabase(dataDir) {
     } finally {
       client.release()
     }
-    // Bridge-specific analytic tables — idempotent, no advisory lock needed.
-    await initBridgeTables(db)
+    // Agent-specific analytic tables — idempotent, no advisory lock needed.
+    await initAgentTables(db)
 
     dbs.set(key, db)
 
@@ -633,32 +633,77 @@ function _scheduleFlush(db, q) {
 // Issue 4: timer is unref()'d so it won't prevent exit; register drain handlers.
 // ---------------------------------------------------------------------------
 
-const _registeredExitDbs = new WeakSet()
+const _registeredExitDbs = new WeakMap()
+
+async function drainTraceQueue(db) {
+  const q = _traceQueues.get(db)
+  if (!q) return
+  try {
+    if (q.timer) { clearTimeout(q.timer); q.timer = null }
+    if (q.flushPromise) await q.flushPromise.catch(() => {})
+    if (q.pending.length > 0) await _insertTraceEventsDirect(db, q.pending.splice(0).flatMap(w => w.events))
+  } catch (e) {
+    __mixdogMemoryLog(`[trace-queue] drain failed: ${e?.message}\n`)
+  }
+}
+
+function clearTraceQueue(db) {
+  const q = _traceQueues.get(db)
+  if (!q) return
+  if (q.timer) { clearTimeout(q.timer); q.timer = null }
+  q.pending.length = 0
+  q.flushPromise = null
+  _traceQueues.delete(db)
+}
+
+function unregisterTraceExitDrain(db) {
+  const handlers = _registeredExitDbs.get(db)
+  if (!handlers) return
+  try { process.off('exit', handlers.onExit) } catch {}
+  try { process.off('SIGTERM', handlers.onSigterm) } catch {}
+  try { process.off('beforeExit', handlers.onBeforeExit) } catch {}
+  _registeredExitDbs.delete(db)
+}
 
 export function registerTraceExitDrain(db) {
   if (_registeredExitDbs.has(db)) return
-  _registeredExitDbs.add(db)
 
   async function drainOnExit() {
-    const q = _traceQueues.get(db)
-    if (!q || q.pending.length === 0) return
-    try {
-      if (q.timer) { clearTimeout(q.timer); q.timer = null }
-      if (q.flushPromise) await q.flushPromise.catch(() => {})
-      if (q.pending.length > 0) await _insertTraceEventsDirect(db, q.pending.splice(0).flatMap(w => w.events))
-    } catch (e) {
-      __mixdogMemoryLog(`[trace-queue] exit drain failed: ${e?.message}\n`)
-    }
+    await drainTraceQueue(db)
   }
 
-  process.on('exit', () => {
+  const onExit = () => {
     const q = _traceQueues.get(db)
     if (q?.pending.length) __mixdogMemoryLog(`[trace-queue] exit with ${q.pending.length} unflushed events\n`)
-  })
-
-  process.on('SIGTERM', async () => { await drainOnExit(); process.exit(0) })
+  }
+  const onSigterm = async () => { await drainOnExit(); process.exit(0) }
 
+  process.on('exit', onExit)
+  process.on('SIGTERM', onSigterm)
   process.once('beforeExit', drainOnExit)
+
+  _registeredExitDbs.set(db, { onExit, onSigterm, onBeforeExit: drainOnExit })
+}
+
+export async function closeTraceDatabase(dataDir) {
+  const key = resolve(dataDir)
+  let db = dbs.get(key)
+  if (!db && opening.has(key)) {
+    try { db = await opening.get(key) } catch { db = null }
+  }
+  if (!db) return false
+  const timer = partitionTimers.get(key)
+  if (timer) {
+    try { clearInterval(timer) } catch {}
+    partitionTimers.delete(key)
+  }
+  await drainTraceQueue(db)
+  clearTraceQueue(db)
+  unregisterTraceExitDrain(db)
+  dbs.delete(key)
+  try { await db.close?.() } catch {}
+  try { await closePgInstance(dataDir, { schema: 'trace' }) } catch {}
+  return true
 }
 
 /**

package/src/runtime/memory/tool-defs.mjs

@@ -8,24 +8,28 @@ export const TOOL_DEFS = [
     name: 'memory',
     title: 'Memory Cycle',
     annotations: { title: 'Memory Cycle', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
-    description: 'Persistent memory maintenance and explicit mutation. Use recall for retrieval; use memory only for status, lifecycle jobs, or intentional add/edit/delete/purge. Destructive jobs require exact confirm strings.',
+    description: 'Memory status/lifecycle or explicit mutation. Use recall for retrieval. Destructive jobs require exact confirm strings.',
     inputSchema: {
       type: 'object',
       properties: {
-        action: { type: 'string', enum: ['core','manage','status','sleep','cycle1','cycle2','cycle3','flush','backfill','prune','rebuild','purge','retro_eval_active'], description: 'Operation to run: status/read jobs, core/manage mutation, lifecycle cycles, or destructive maintenance.' },
-        op: { type: 'string', enum: ['add','edit','delete','list'], description: 'Mutation operation for action=core/manage.' },
-        id: { type: 'number', description: 'Exact memory id for edit/delete; get it from recall or list output first.' },
-        element: { type: 'string', description: 'Stable memory key/title for add/edit.' },
-        summary: { type: 'string', description: 'Memory content to store or replace.' },
-        category: { type: 'string', enum: ['rule','constraint','decision','fact','goal','preference','task','issue'], description: 'Memory category.' },
-        status: { type: 'string', enum: ['pending','active','archived'], description: 'Entry lifecycle status for manage edit.' },
-        maxDays: { type: 'number', description: 'Prune threshold in days for old unclassified entries.' },
-        window: { type: 'string', description: 'Backfill/search window, e.g. 24h, 7d, 30d.' },
-        limit: { type: 'number', description: 'Maximum rows/items for list, search, or backfill.' },
-        concurrency: { type: 'number', description: 'Worker concurrency for supported maintenance jobs.' },
-        confirm: { type: 'string', description: 'Exact confirmation phrase for destructive actions such as prune, rebuild, purge, or retro_eval_active.' },
-        cycle3Mode: { type: 'string', enum: ['proposal','conservative'], description: 'cycle3 application mode; conservative applies only safe automatic changes.' },
-        project_id: { type: 'string', description: 'Core memory project pool: common, owner/repo slug, or * for core list across pools.' },
+        action: { type: 'string', enum: ['core','manage','status','sleep','cycle1','cycle2','cycle3','flush','backfill','prune','rebuild','purge','retro_eval_active'], description: 'Operation.' },
+        op: { type: 'string', enum: ['add','edit','delete','list'], description: 'Mutation op.' },
+        id: { type: 'number', description: 'Exact memory id.' },
+        element: { type: 'string', description: 'Memory key/title.' },
+        summary: { type: 'string', description: 'Memory content.' },
+        category: { type: 'string', enum: ['rule','constraint','decision','fact','goal','preference','task','issue'], description: 'Category.' },
+        status: { type: 'string', enum: ['pending','active','archived'], description: 'Lifecycle status.' },
+        maxDays: { type: 'number', description: 'Prune age days.' },
+        window: { type: 'string', description: 'Window, e.g. 24h/7d/30d.' },
+        limit: { type: 'number', description: 'Max rows/items.' },
+        concurrency: { type: 'number', description: 'Worker concurrency.' },
+        sessionId: { type: 'string', description: 'Scoped session id.' },
+        session_id: { type: 'string', description: 'Alias for sessionId.' },
+        window_size: { type: 'number', description: 'cycle1 rows/window.' },
+        rows_per_session: { type: 'number', description: 'cycle1 rows/session.' },
+        confirm: { type: 'string', description: 'Exact confirmation phrase for destructive actions.' },
+        cycle3Mode: { type: 'string', enum: ['proposal','conservative'], description: 'cycle3 mode.' },
+        project_id: { type: 'string', description: 'Core pool: common, slug, or *.' },
       },
       required: ['action'],
     },
@@ -34,20 +38,23 @@ export const TOOL_DEFS = [
     name: 'recall',
     title: 'Recall',
     annotations: { title: 'Recall', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    description: 'Retrieve stored memory (past decisions, prior work, session history). Use when the user references earlier work, when resuming a paused task, or before re-proposing something possibly already decided. query (string|array fan-out) and/or id; category/period/projectScope filters. Read-only and cheap — when in doubt, recall first.',
+    description: 'Retrieve stored memory/session history. Use for earlier work, resumes, or possibly decided items; when in doubt, recall first.',
     inputSchema: {
       type: 'object',
       properties: {
         query: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Search text, or array for independent fan-out queries.' },
-        id: { anyOf: [{ type: 'number' }, { type: 'array', items: { type: 'number' }, minItems: 1 }], description: 'Only use exact #ids from a prior recall result. Do not invent ids, and do not combine id with query.' },
-        period: { type: 'string', description: 'Time scope: last, 24h/7d/30d, all, YYYY-MM-DD, or YYYY-MM-DD~YYYY-MM-DD.' },
-        limit: { type: 'number', description: 'Maximum entries to return.' },
-        offset: { type: 'number', description: 'Skip N entries for paging.' },
-        sort: { type: 'string', enum: ['importance', 'date'], description: 'importance (default relevance) or date (newest first).' },
-        category: { anyOf: [{ type: 'string', enum: ['rule','constraint','decision','fact','goal','preference','task','issue'] }, { type: 'array', items: { type: 'string', enum: ['rule','constraint','decision','fact','goal','preference','task','issue'] }, minItems: 1 }], description: 'Optional category filter, string or array.' },
-        includeArchived: { type: 'boolean', description: 'Include archived/historical entries; set false to focus on live/pending memory.' },
-        projectScope: { type: 'string', description: 'Project pool selector: inferred from cwd, common, all, or a project slug.' },
-        cwd: { type: 'string', description: 'Workspace path used to infer projectScope when projectScope is omitted.' },
+        id: { anyOf: [{ type: 'number' }, { type: 'array', items: { type: 'number' }, minItems: 1 }], description: 'Exact #id(s) from recall. Do not invent ids.' },
+        period: { type: 'string', description: 'last, 24h/7d/30d, all, date, or range.' },
+        limit: { type: 'number', description: 'Max entries.' },
+        offset: { type: 'number', description: 'Skip entries.' },
+        sort: { type: 'string', enum: ['importance', 'date'], description: 'importance or date.' },
+        category: { anyOf: [{ type: 'string', enum: ['rule','constraint','decision','fact','goal','preference','task','issue'] }, { type: 'array', items: { type: 'string', enum: ['rule','constraint','decision','fact','goal','preference','task','issue'] }, minItems: 1 }], description: 'Category filter.' },
+        includeArchived: { type: 'boolean', description: 'Include archived entries.' },
+        sessionId: { type: 'string', description: 'Scoped session id.' },
+        session_id: { type: 'string', description: 'Alias for sessionId.' },
+        includeMembers: { type: 'boolean', description: 'Include chunk members.' },
+        projectScope: { type: 'string', description: 'Project pool selector: inferred from cwd, common, all, or slug.' },
+        cwd: { type: 'string', description: 'Infer projectScope.' },
       },
       additionalProperties: false,
     },
@@ -57,21 +64,23 @@ export const TOOL_DEFS = [
     title: 'Search Memories',
     public: false,
     annotations: { title: 'Search Memories', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    description: 'Search past context and memory. Returns root entries by default. Use when user references prior work, decisions, or preferences. Storage is automatic — only retrieval is manual.',
+    description: 'Search past context/memory. Returns root entries.',
     inputSchema: {
       type: 'object',
       properties: {
-        query: { type: 'string', description: 'Search text. Triggers hybrid search (vector KNN + full-text BM25).' },
-        period: { type: 'string', description: 'Time scope: "last" (before this session), "24h"/"3d"/"7d"/"30d" (relative), "all", "2026-04-05" (single day), "2026-04-01~2026-04-05" (range). Default: 30d when query set, latest entries otherwise.' },
-        sort: { type: 'string', enum: ['date', 'importance'], description: 'date (newest first) or importance (score desc).' },
-        category: { anyOf: [{ type: 'string', enum: ['rule','constraint','decision','fact','goal','preference','task','issue'] }, { type: 'array', items: { type: 'string', enum: ['rule','constraint','decision','fact','goal','preference','task','issue'] }, minItems: 1 }], description: 'Optional category filter for timeline/category recall.' },
-        limit: { type: 'number', default: 30, description: 'Maximum entries to return.' },
-        offset: { type: 'number', default: 0, description: 'Skip N entries for paging.' },
-        includeMembers: { type: 'boolean', description: 'Include chunk member entries inline.' },
-        includeRaw: { type: 'boolean', description: 'When true, fetch unclassified raw rows in the requested period window and merge into results. Caller-driven only — no auto-trigger.' },
-        includeArchived: { type: 'boolean', description: 'Default true for historical recall. Set false to restrict to live/pending roots.' },
-        projectScope: { type: 'string', description: 'Project pool selector. Omitted = infer from cwd, or `common` if unknown. Use `all` only when intentionally searching every project.' },
-        cwd: { type: 'string', description: 'Optional workspace path, used only when `projectScope` is not set.' },
+        query: { type: 'string', description: 'Search text.' },
+        period: { type: 'string', description: 'last, 24h/7d/30d, all, date, or range.' },
+        sort: { type: 'string', enum: ['date', 'importance'], description: 'date or importance.' },
+        category: { anyOf: [{ type: 'string', enum: ['rule','constraint','decision','fact','goal','preference','task','issue'] }, { type: 'array', items: { type: 'string', enum: ['rule','constraint','decision','fact','goal','preference','task','issue'] }, minItems: 1 }], description: 'Category filter.' },
+        limit: { type: 'number', default: 30, description: 'Max entries.' },
+        offset: { type: 'number', default: 0, description: 'Skip entries.' },
+        includeMembers: { type: 'boolean', description: 'Include members.' },
+        includeRaw: { type: 'boolean', description: 'Include raw rows.' },
+        includeArchived: { type: 'boolean', description: 'Include archived.' },
+        sessionId: { type: 'string', description: 'Scoped session id.' },
+        session_id: { type: 'string', description: 'Alias for sessionId.' },
+        projectScope: { type: 'string', description: 'Project pool selector.' },
+        cwd: { type: 'string', description: 'Infer projectScope.' },
       },
       required: [],
     },