@vheins/local-memory-mcp 0.13.1 → 0.14.0

package/dist/{chunk-UZWV2DYU.js → chunk-GXQCHTXK.js}

@@ -81,8 +81,8 @@ function loadServerInstructions() {
 // src/mcp/capabilities.ts
 var __dirname2 = path2.dirname(fileURLToPath2(import.meta.url));
 var pkgVersion = "0.1.0";
-if ("0.13.1") {
-  pkgVersion = "0.13.1";
+if ("0.14.0") {
+  pkgVersion = "0.14.0";
 } else {
   let searchDir = __dirname2;
   for (let i = 0; i < 5; i++) {
@@ -1119,6 +1119,23 @@ var BaseEntity = class {
 };
 
 // src/mcp/entities/memory.ts
+var VALID_COLUMNS = /* @__PURE__ */ new Set([
+  "code",
+  "type",
+  "title",
+  "content",
+  "importance",
+  "agent",
+  "role",
+  "model",
+  "completed_at",
+  "expires_at",
+  "supersedes",
+  "status",
+  "hit_count",
+  "recall_count",
+  "last_used_at"
+]);
 var MemoryEntity = class extends BaseEntity {
   insert(entry) {
     this.run(
@@ -1179,7 +1196,7 @@ var MemoryEntity = class extends BaseEntity {
         } else if (k === "is_global") {
           fields.push(`${k} = ?`);
           values.push(val ? 1 : 0);
-        } else if (k !== "id" && k !== "created_at") {
+        } else if (VALID_COLUMNS.has(k)) {
           fields.push(`${k} = ?`);
           values.push(val);
         }
@@ -1303,13 +1320,27 @@ var MemoryEntity = class extends BaseEntity {
     Object.keys(updates).forEach((key) => {
       const value = updates[key];
       if (value !== void 0) {
-        if (key === "tags" || key === "metadata") {
+        if (key === "scope") {
+          const scope = updates.scope;
+          if (scope?.repo) {
+            fields.push("repo = ?");
+            values.push(scope.repo);
+          }
+          if (scope?.folder !== void 0) {
+            fields.push("folder = ?");
+            values.push(scope.folder);
+          }
+          if (scope?.language !== void 0) {
+            fields.push("language = ?");
+            values.push(scope.language);
+          }
+        } else if (key === "tags" || key === "metadata") {
           fields.push(`${key} = ?`);
           values.push(JSON.stringify(value));
         } else if (key === "is_global") {
           fields.push(`${key} = ?`);
           values.push(value ? 1 : 0);
-        } else {
+        } else if (VALID_COLUMNS.has(key)) {
           fields.push(`${key} = ?`);
           values.push(value);
         }
@@ -1332,19 +1363,6 @@ var MemoryEntity = class extends BaseEntity {
       return count;
     });
   }
-  bulkDeleteMemories(ids) {
-    if (ids.length === 0) return 0;
-    return this.transaction(() => {
-      let count = 0;
-      const chunkSize = 500;
-      for (let i = 0; i < ids.length; i += chunkSize) {
-        const chunk = ids.slice(i, i + chunkSize);
-        const result = this.run(`DELETE FROM memories WHERE id IN (${chunk.map(() => "?").join(",")})`, chunk);
-        count += result.changes;
-      }
-      return count;
-    });
-  }
   getRecentMemories(repo, limit, offset = 0, includeArchived = false, excludeTypes = [], sortOrder = "DESC") {
     let query = "SELECT * FROM memories WHERE repo = ?";
     const params = [repo];
@@ -1390,24 +1408,6 @@ var MemoryEntity = class extends BaseEntity {
       id
     ]);
   }
-  getVectorCandidates(repo, limit = 100) {
-    let sql = `SELECT mv.memory_id, mv.vector FROM memory_vectors mv JOIN memories m ON mv.memory_id = m.id`;
-    const params = [];
-    if (repo) {
-      sql += " WHERE m.repo = ?";
-      params.push(repo);
-    }
-    sql += " LIMIT ?";
-    params.push(limit);
-    return this.all(sql, params);
-  }
-  upsertVectorEmbedding(memoryId, vector) {
-    this.run(
-      `INSERT INTO memory_vectors (memory_id, vector, updated_at) VALUES (?, ?, ?)
-			ON CONFLICT(memory_id) DO UPDATE SET vector = excluded.vector, updated_at = excluded.updated_at`,
-      [memoryId, JSON.stringify(vector), (/* @__PURE__ */ new Date()).toISOString()]
-    );
-  }
   getSummary(repo) {
     const row = this.get(
       "SELECT summary, updated_at FROM memory_summary WHERE repo = ?",
@@ -1487,6 +1487,28 @@ var MemoryEntity = class extends BaseEntity {
     }));
     return { items, memories: items, total, limit, offset };
   }
+};
+
+// src/mcp/entities/memory.vector.ts
+var MemoryVectorEntity = class extends BaseEntity {
+  getVectorCandidates(repo, limit = 100) {
+    let sql = `SELECT mv.memory_id, mv.vector FROM memory_vectors mv JOIN memories m ON mv.memory_id = m.id`;
+    const params = [];
+    if (repo) {
+      sql += " WHERE m.repo = ?";
+      params.push(repo);
+    }
+    sql += " LIMIT ?";
+    params.push(limit);
+    return this.all(sql, params);
+  }
+  upsertVectorEmbedding(memoryId, vector) {
+    this.run(
+      `INSERT INTO memory_vectors (memory_id, vector, updated_at) VALUES (?, ?, ?)
+			ON CONFLICT(memory_id) DO UPDATE SET vector = excluded.vector, updated_at = excluded.updated_at`,
+      [memoryId, JSON.stringify(vector), (/* @__PURE__ */ new Date()).toISOString()]
+    );
+  }
   searchBySimilarity(query, repo, limit = 10, includeArchived = false, currentTags = []) {
     const queryVector = this.computeVector(query);
     const now = /* @__PURE__ */ new Date();
@@ -1504,8 +1526,12 @@ var MemoryEntity = class extends BaseEntity {
     if (candidates.length < 5) {
       const recentSql = `SELECT * FROM memories WHERE (${where.join(" OR ")}) AND status = 'active' AND (expires_at IS NULL OR expires_at > ?) ORDER BY created_at DESC LIMIT 10`;
       const recent = this.all(recentSql, [...params, now.toISOString()]);
+      const candidateIds = new Set(candidates.map((c) => c.id));
       for (const r of recent) {
-        if (!candidates.find((c) => c.id === r.id)) candidates.push(r);
+        if (!candidateIds.has(r.id)) {
+          candidateIds.add(r.id);
+          candidates.push(r);
+        }
       }
     }
     return candidates.map((row) => {
@@ -1531,6 +1557,23 @@ var MemoryEntity = class extends BaseEntity {
     }
     return null;
   }
+};
+
+// src/mcp/entities/memory.archive.ts
+var MemoryArchiveEntity = class extends BaseEntity {
+  bulkDeleteMemories(ids) {
+    if (ids.length === 0) return 0;
+    return this.transaction(() => {
+      let count = 0;
+      const chunkSize = 500;
+      for (let i = 0; i < ids.length; i += chunkSize) {
+        const chunk = ids.slice(i, i + chunkSize);
+        const result = this.run(`DELETE FROM memories WHERE id IN (${chunk.map(() => "?").join(",")})`, chunk);
+        count += result.changes;
+      }
+      return count;
+    });
+  }
   archiveExpiredMemories(force = false) {
     if (process.env.ENABLE_AUTO_ARCHIVE !== "true" && !force) return 0;
     const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -1606,7 +1649,7 @@ var TaskEntity = class extends BaseEntity {
     const fields = [];
     const values = [];
     const anyUpdates = updates;
-    const VALID_COLUMNS = /* @__PURE__ */ new Set([
+    const VALID_COLUMNS2 = /* @__PURE__ */ new Set([
       "repo",
       "task_code",
       "phase",
@@ -1629,7 +1672,7 @@ var TaskEntity = class extends BaseEntity {
       "changed_files"
     ]);
     Object.keys(updates).forEach((key) => {
-      if (VALID_COLUMNS.has(key) && anyUpdates[key] !== void 0) {
+      if (VALID_COLUMNS2.has(key) && anyUpdates[key] !== void 0) {
         if (key === "tags" || key === "metadata" || key === "changed_files") {
           fields.push(`${key} = ?`);
           values.push(JSON.stringify(anyUpdates[key]));
@@ -1659,7 +1702,7 @@ var TaskEntity = class extends BaseEntity {
 			 WHERE t.id = ?`,
       [id]
     );
-    return row ? { ...this.rowToTask(row), comments: this.getTaskCommentsByTaskId(id) } : null;
+    return row ? { ...this.rowToTask(row), comments: this.all("SELECT * FROM task_comments WHERE task_id = ? ORDER BY created_at DESC, id DESC", [id]) } : null;
   }
   getTasksByIds(ids) {
     if (ids.length === 0) return [];
@@ -1700,7 +1743,7 @@ var TaskEntity = class extends BaseEntity {
 			 WHERE t.repo = ? AND t.task_code = ?`,
       [repo, taskCode]
     );
-    return row ? { ...this.rowToTask(row), comments: this.getTaskCommentsByTaskId(row.id) } : null;
+    return row ? { ...this.rowToTask(row), comments: this.all("SELECT * FROM task_comments WHERE task_id = ? ORDER BY created_at DESC, id DESC", [row.id]) } : null;
   }
   getTasksByRepo(repo, status, limit, offset, search) {
     let query = `
@@ -1886,6 +1929,10 @@ var TaskEntity = class extends BaseEntity {
       return count;
     });
   }
+};
+
+// src/mcp/entities/task-comment.ts
+var TaskCommentEntity = class extends BaseEntity {
   insertTaskComment(comment) {
     this.run(
       `INSERT INTO task_comments (
@@ -1909,8 +1956,17 @@ var TaskEntity = class extends BaseEntity {
     const fields = [];
     const values = [];
     const anyUpdates = updates;
+    const VALID_COLUMNS2 = /* @__PURE__ */ new Set([
+      "repo",
+      "comment",
+      "agent",
+      "role",
+      "model",
+      "previous_status",
+      "next_status"
+    ]);
     Object.keys(updates).forEach((key) => {
-      if (anyUpdates[key] !== void 0) {
+      if (VALID_COLUMNS2.has(key) && anyUpdates[key] !== void 0) {
         fields.push(`${key} = ?`);
         values.push(anyUpdates[key]);
       }
@@ -1935,6 +1991,10 @@ var TaskEntity = class extends BaseEntity {
       repo
     ]);
   }
+};
+
+// src/mcp/entities/task-stats.ts
+var TaskStatsEntity = class extends BaseEntity {
   getTaskStats(repo) {
     const rows = this.all(
       "SELECT status, COUNT(*) as count FROM tasks WHERE repo = ? GROUP BY status",
@@ -2863,7 +2923,11 @@ var DB_PATH = resolveDbPath();
 var SQLiteStore = class _SQLiteStore {
   db;
   memories;
+  memoryVectors;
+  memoryArchives;
   tasks;
+  taskComments;
+  taskStats;
   actions;
   system;
   summaries;
@@ -2894,7 +2958,11 @@ var SQLiteStore = class _SQLiteStore {
     migrator.addMemoryCodeColumn();
     migrator.addStandardCodeColumn();
     this.memories = new MemoryEntity(this.db);
+    this.memoryVectors = new MemoryVectorEntity(this.db);
+    this.memoryArchives = new MemoryArchiveEntity(this.db);
     this.tasks = new TaskEntity(this.db);
+    this.taskComments = new TaskCommentEntity(this.db);
+    this.taskStats = new TaskStatsEntity(this.db);
     this.actions = new ActionEntity(this.db);
     this.system = new SystemEntity(this.db);
     this.summaries = new SummaryEntity(this.db);
@@ -3045,7 +3113,7 @@ var RealVectorStore = class {
       if (kind === "standard") {
         this.db.standards.upsertVectorEmbedding(id, vector);
       } else {
-        this.db.memories.upsertVectorEmbedding(id, vector);
+        this.db.memoryVectors.upsertVectorEmbedding(id, vector);
       }
     } catch (error) {
       logger.error("[Vectors] Error during upsert", { id, kind, error: String(error) });
@@ -3061,7 +3129,7 @@ var RealVectorStore = class {
       const extractor = await this.getExtractor();
       const output = await extractor(query, { pooling: "mean", normalize: true });
       const queryVector = Array.from(output.data);
-      const rows = kind === "standard" ? this.db.standards.getVectorCandidates(repo, 100).map((row) => ({ id: row.standard_id, vector: row.vector })) : this.db.memories.getVectorCandidates(repo, 100).map((row) => ({ id: row.memory_id, vector: row.vector }));
+      const rows = kind === "standard" ? this.db.standards.getVectorCandidates(repo, 100).map((row) => ({ id: row.standard_id, vector: row.vector })) : this.db.memoryVectors.getVectorCandidates(repo, 100).map((row) => ({ id: row.memory_id, vector: row.vector }));
       const results = rows.map((row) => {
         const memoryVector = JSON.parse(row.vector);
         return {
@@ -3206,7 +3274,8 @@ var MemoryStoreSchema = z.object({
   structured: z.boolean().default(false)
 });
 var MemoryUpdateSchema = z.object({
-  id: z.string().uuid(),
+  id: z.string().uuid().optional(),
+  code: z.string().max(20).optional(),
   type: MemoryTypeSchema.optional(),
   title: z.string().min(3).max(255).optional(),
   content: z.string().min(10).optional(),
@@ -3220,6 +3289,8 @@ var MemoryUpdateSchema = z.object({
   is_global: z.boolean().optional(),
   completed_at: z.string().optional(),
   structured: z.boolean().default(false)
+}).refine((data) => data.id !== void 0 || data.code !== void 0, {
+  message: "Either id or code must be provided"
 }).refine(
   (data) => data.type !== void 0 || data.content !== void 0 || data.title !== void 0 || data.importance !== void 0 || data.status !== void 0 || data.supersedes !== void 0 || data.tags !== void 0 || data.metadata !== void 0 || data.is_global !== void 0 || data.agent !== void 0 || data.role !== void 0 || data.completed_at !== void 0,
   { message: "At least one field must be provided for update" }
@@ -3240,10 +3311,13 @@ var MemorySearchSchema = z.object({
   structured: z.boolean().default(false)
 });
 var MemoryAcknowledgeSchema = z.object({
-  memory_id: z.string().uuid(),
+  memory_id: z.string().uuid().optional(),
+  code: z.string().max(20).optional(),
   status: z.enum(["used", "irrelevant", "contradictory"]),
   application_context: z.string().min(10).optional(),
   structured: z.boolean().default(false)
+}).refine((data) => data.memory_id !== void 0 || data.code !== void 0, {
+  message: "Either memory_id or code must be provided"
 });
 var MemoryRecapSchema = z.object({
   repo: z.string().min(1).transform(normalizeRepo),
@@ -3255,10 +3329,15 @@ var MemoryDeleteSchema = z.object({
   repo: z.string().min(1).transform(normalizeRepo).optional(),
   id: z.string().uuid().optional(),
   ids: z.array(z.string().uuid()).min(1).optional(),
+  code: z.string().max(20).optional(),
+  codes: z.array(z.string().max(20)).min(1).optional(),
   structured: z.boolean().default(false)
-}).refine((data) => data.id !== void 0 || data.ids !== void 0, {
-  message: "Either 'id' or 'ids' must be provided for deletion"
-});
+}).refine(
+  (data) => data.id !== void 0 || data.ids !== void 0 || data.code !== void 0 || data.codes !== void 0,
+  {
+    message: "Either 'id', 'ids', 'code', or 'codes' must be provided for deletion"
+  }
+);
 var MemorySummarizeSchema = z.object({
   repo: z.string().min(1).transform(normalizeRepo),
   signals: z.array(z.string().max(200)).min(1),
@@ -3366,6 +3445,8 @@ var TaskSearchSchema = z.object({
   repo: z.string().min(1).transform(normalizeRepo),
   query: z.string().min(1),
   status: z.string().optional(),
+  phase: z.string().optional(),
+  priority: z.number().min(1).max(5).optional(),
   limit: z.number().min(1).max(100).default(10),
   offset: z.number().min(0).default(0),
   structured: z.boolean().default(false)
@@ -3374,9 +3455,10 @@ var TaskDeleteSchema = z.object({
   repo: z.string().min(1).transform(normalizeRepo),
   id: z.string().uuid().optional(),
   ids: z.array(z.string().uuid()).min(1).optional(),
+  task_code: z.string().optional(),
   structured: z.boolean().default(false)
-}).refine((data) => data.id !== void 0 || data.ids !== void 0, {
-  message: "Either 'id' or 'ids' must be provided for deletion"
+}).refine((data) => data.id !== void 0 || data.ids !== void 0 || data.task_code !== void 0, {
+  message: "Either 'id', 'ids', or 'task_code' must be provided for deletion"
 });
 var MemoryDetailSchema = z.object({
   id: z.string().uuid().optional(),
@@ -3396,10 +3478,15 @@ var StandardDeleteSchema = z.object({
   repo: z.string().min(1).transform(normalizeRepo).optional(),
   id: z.string().uuid().optional(),
   ids: z.array(z.string().uuid()).min(1).optional(),
+  code: z.string().max(20).optional(),
+  codes: z.array(z.string().max(20)).min(1).optional(),
   structured: z.boolean().default(false)
-}).refine((data) => data.id !== void 0 || data.ids !== void 0, {
-  message: "Either 'id' or 'ids' must be provided for deletion"
-});
+}).refine(
+  (data) => data.id !== void 0 || data.ids !== void 0 || data.code !== void 0 || data.codes !== void 0,
+  {
+    message: "Either 'id', 'ids', 'code', or 'codes' must be provided for deletion"
+  }
+);
 var TaskGetSchema = z.object({
   repo: z.string().min(1).transform(normalizeRepo),
   id: z.string().uuid().optional(),
@@ -3494,7 +3581,8 @@ var StandardStoreSchema = z.object({
   message: "repo is required for repo-specific standards"
 });
 var StandardUpdateSchema = z.object({
-  id: z.string().uuid(),
+  id: z.string().uuid().optional(),
+  code: z.string().max(20).optional(),
   name: z.string().min(3).max(255).optional(),
   content: z.string().min(10).optional(),
   parent_id: z.string().uuid().nullable().optional(),
@@ -3509,6 +3597,8 @@ var StandardUpdateSchema = z.object({
   agent: z.string().optional(),
   model: z.string().optional(),
   structured: z.boolean().default(false)
+}).refine((data) => data.id !== void 0 || data.code !== void 0, {
+  message: "Either id or code must be provided"
 }).refine(
   (data) => data.name !== void 0 || data.content !== void 0 || data.parent_id !== void 0 || data.context !== void 0 || data.version !== void 0 || data.language !== void 0 || data.stack !== void 0 || data.repo !== void 0 || data.is_global !== void 0 || data.tags !== void 0 || data.metadata !== void 0 || data.agent !== void 0 || data.model !== void 0,
   { message: "At least one field must be provided for update" }
@@ -3781,12 +3871,13 @@ var TOOL_DEFINITIONS = [
     inputSchema: {
       type: "object",
       properties: {
-        memory_id: { type: "string", format: "uuid" },
+        memory_id: { type: "string", format: "uuid", description: "Memory entry ID. Optional if code is provided." },
+        code: { type: "string", maxLength: 20, description: "Short memory code. Optional if memory_id is provided." },
         status: { type: "string", enum: ["used", "irrelevant", "contradictory"] },
         application_context: { type: "string", minLength: 10 },
         structured: { type: "boolean", default: false, description: "If true, returns structured JSON result." }
       },
-      required: ["memory_id", "status"]
+      required: ["status"]
     },
     outputSchema: {
       type: "object",
@@ -3811,7 +3902,8 @@ var TOOL_DEFINITIONS = [
     inputSchema: {
       type: "object",
       properties: {
-        id: { type: "string", format: "uuid" },
+        id: { type: "string", format: "uuid", description: "Memory entry ID. Optional if code is provided." },
+        code: { type: "string", maxLength: 20, description: "Short memory code. Optional if id is provided." },
         type: {
           type: "string",
           enum: ["code_fact", "decision", "mistake", "pattern", "task_archive"]
@@ -3832,21 +3924,21 @@ var TOOL_DEFINITIONS = [
           default: false,
           description: "If true, returns structured JSON of the updated memory."
         }
-      },
-      required: ["id"]
+      }
     },
     outputSchema: {
       type: "object",
       properties: {
         success: { type: "boolean" },
         id: { type: "string" },
+        code: { type: "string" },
         repo: { type: "string" },
         updatedFields: {
           type: "array",
           items: { type: "string" }
         }
       },
-      required: ["success", "id", "repo", "updatedFields"]
+      required: ["success", "repo", "updatedFields"]
     }
   },
   {
@@ -3976,13 +4068,20 @@ var TOOL_DEFINITIONS = [
       type: "object",
       properties: {
         repo: { type: "string", description: "Repository name (optional for single id)" },
-        id: { type: "string", format: "uuid", description: "Memory entry ID to delete" },
+        id: { type: "string", format: "uuid", description: "Memory entry ID to delete. Optional if code is provided." },
         ids: {
           type: "array",
           items: { type: "string", format: "uuid" },
           minItems: 1,
           description: "Array of memory IDs to delete"
         },
+        code: { type: "string", maxLength: 20, description: "Short memory code. Optional if id is provided." },
+        codes: {
+          type: "array",
+          items: { type: "string", maxLength: 20 },
+          minItems: 1,
+          description: "Array of memory codes to delete"
+        },
         structured: { type: "boolean", default: false, description: "If true, returns structured JSON result." }
       }
     },
@@ -3991,7 +4090,9 @@ var TOOL_DEFINITIONS = [
       properties: {
         success: { type: "boolean" },
         id: { type: "string" },
+        code: { type: "string" },
         ids: { type: "array", items: { type: "string" } },
+        codes: { type: "array", items: { type: "string" } },
         repo: { type: "string" },
         deletedCount: { type: "number" }
       },
@@ -4012,13 +4113,24 @@ var TOOL_DEFINITIONS = [
       type: "object",
       properties: {
         repo: { type: "string", description: "Repository name (optional for single id)" },
-        id: { type: "string", format: "uuid", description: "Coding standard ID to delete" },
+        id: {
+          type: "string",
+          format: "uuid",
+          description: "Coding standard ID to delete. Optional if code is provided."
+        },
         ids: {
           type: "array",
           items: { type: "string", format: "uuid" },
           minItems: 1,
           description: "Array of coding standard IDs to delete"
         },
+        code: { type: "string", maxLength: 20, description: "Short standard code. Optional if id is provided." },
+        codes: {
+          type: "array",
+          items: { type: "string", maxLength: 20 },
+          minItems: 1,
+          description: "Array of standard codes to delete"
+        },
         structured: { type: "boolean", default: false, description: "If true, returns structured JSON result." }
       }
     },
@@ -4027,7 +4139,9 @@ var TOOL_DEFINITIONS = [
       properties: {
         success: { type: "boolean" },
         id: { type: "string" },
+        code: { type: "string" },
         ids: { type: "array", items: { type: "string" } },
+        codes: { type: "array", items: { type: "string" } },
         repo: { type: "string" },
         deletedCount: { type: "number" }
       },
@@ -4150,7 +4264,10 @@ var TOOL_DEFINITIONS = [
         doc_path: { type: "string" },
         tags: { type: "array", items: { type: "string" } },
         metadata: { type: "object" },
-        parent_id: { type: "string", description: "Optional parent task ID (UUID) or parent task code (e.g. TASK-001). Resolved to UUID before storing." },
+        parent_id: {
+          type: "string",
+          description: "Optional parent task ID (UUID) or parent task code (e.g. TASK-001). Resolved to UUID before storing."
+        },
         depends_on: { type: "string", format: "uuid" },
         est_tokens: { type: "number", minimum: 0, description: "Estimated tokens budget for this task" },
         tasks: {
@@ -4178,7 +4295,10 @@ var TOOL_DEFINITIONS = [
               doc_path: { type: "string" },
               tags: { type: "array", items: { type: "string" } },
               metadata: { type: "object" },
-              parent_id: { type: "string", description: "Optional parent task ID (UUID) or parent task code (e.g. TASK-001). Resolved to UUID before storing." },
+              parent_id: {
+                type: "string",
+                description: "Optional parent task ID (UUID) or parent task code (e.g. TASK-001). Resolved to UUID before storing."
+              },
               depends_on: { type: "string", format: "uuid" },
               est_tokens: { type: "number", minimum: 0 }
             },
@@ -4250,7 +4370,10 @@ var TOOL_DEFINITIONS = [
         doc_path: { type: "string" },
         tags: { type: "array", items: { type: "string" } },
         metadata: { type: "object" },
-        parent_id: { type: "string", description: "Optional parent task ID (UUID) or parent task code (e.g. TASK-001). Resolved to UUID before storing." },
+        parent_id: {
+          type: "string",
+          description: "Optional parent task ID (UUID) or parent task code (e.g. TASK-001). Resolved to UUID before storing."
+        },
         depends_on: { type: "string", format: "uuid" },
         est_tokens: {
           type: "number",
@@ -4306,8 +4429,13 @@ var TOOL_DEFINITIONS = [
       type: "object",
       properties: {
         repo: { type: "string", description: "Repository name" },
-        id: { type: "string", format: "uuid", description: "Task ID (for single deletion)" },
+        id: {
+          type: "string",
+          format: "uuid",
+          description: "Task ID (for single deletion). Optional if task_code is provided."
+        },
         ids: { type: "array", items: { type: "string", format: "uuid" }, description: "Task IDs (for bulk deletion)" },
+        task_code: { type: "string", description: "Task code (e.g. TASK-001). Optional if id is provided." },
         structured: { type: "boolean", default: false, description: "If true, returns structured JSON result." }
       },
       required: ["repo"]
@@ -4317,6 +4445,7 @@ var TOOL_DEFINITIONS = [
       properties: {
         success: { type: "boolean" },
         id: { type: "string" },
+        task_code: { type: "string" },
         ids: { type: "array", items: { type: "string" } },
         repo: { type: "string" },
         deletedCount: { type: "number" }
@@ -4400,6 +4529,58 @@ var TOOL_DEFINITIONS = [
       required: ["schema", "tasks", "count"]
     }
   },
+  {
+    name: "task-search",
+    title: "Task Search",
+    description: "Dedicated search tool for tasks. Returns a compact pointer table of matching tasks [id, task_code, title, status, priority, updated_at, phase]. Use task-detail for full task content.",
+    annotations: {
+      readOnlyHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        repo: { type: "string", description: "Repository name" },
+        query: { type: "string", minLength: 1, description: "Search keyword matching task code, title, or description" },
+        status: { type: "string", description: "Optional status filter (single or comma-separated)" },
+        phase: { type: "string", description: "Filter by phase (e.g., 'research', 'implementation')" },
+        priority: { type: "number", minimum: 1, maximum: 5, description: "Filter by priority (1-5)" },
+        limit: { type: "number", minimum: 1, maximum: 100, default: 10 },
+        offset: { type: "number", minimum: 0, default: 0 },
+        structured: { type: "boolean", default: false, description: "If true, returns structured JSON result." }
+      },
+      required: ["repo", "query"]
+    },
+    outputSchema: {
+      type: "object",
+      properties: {
+        schema: { type: "string", enum: ["task-search"] },
+        query: { type: "string" },
+        count: { type: "number", description: "Number of rows returned" },
+        total: { type: "number", description: "Total matching tasks before pagination" },
+        offset: { type: "number" },
+        limit: { type: "number" },
+        results: {
+          type: "object",
+          properties: {
+            columns: {
+              type: "array",
+              items: { type: "string" },
+              description: "Column names: [id, task_code, title, status, priority, updated_at, phase]"
+            },
+            rows: {
+              type: "array",
+              items: { type: "array" },
+              description: "Each row: [id, task_code, title, status, priority, updated_at, phase]. Use task-detail to fetch full task."
+            }
+          },
+          required: ["columns", "rows"]
+        }
+      },
+      required: ["schema", "query", "count", "total", "offset", "limit", "results"]
+    }
+  },
   {
     name: "handoff-create",
     title: "Handoff Create",
@@ -4762,7 +4943,8 @@ var TOOL_DEFINITIONS = [
     inputSchema: {
       type: "object",
       properties: {
-        id: { type: "string", description: "Standard ID to update" },
+        id: { type: "string", format: "uuid", description: "Standard ID to update. Optional if code is provided." },
+        code: { type: "string", maxLength: 20, description: "Short standard code. Optional if id is provided." },
         name: { type: "string", minLength: 3, maxLength: 255 },
         content: { type: "string", minLength: 10 },
         parent_id: { type: "string", format: "uuid", nullable: true },
@@ -4777,8 +4959,7 @@ var TOOL_DEFINITIONS = [
         agent: { type: "string" },
         model: { type: "string" },
         structured: { type: "boolean", default: false }
-      },
-      required: ["id"]
+      }
     },
     outputSchema: {
       type: "object",
@@ -5373,6 +5554,369 @@ async function completePromptArgument(name, argName, value, contextArguments, da
   return [];
 }
 
+// src/mcp/utils/mcp-response.ts
+import { z as z2 } from "zod";
+var McpAnnotationsSchema = z2.object({
+  audience: z2.array(z2.enum(["user", "assistant"])).optional(),
+  priority: z2.number().min(0).max(1).optional(),
+  lastModified: z2.string().optional()
+}).strict().optional();
+var McpContentSchema = z2.discriminatedUnion("type", [
+  z2.object({
+    type: z2.literal("text"),
+    text: z2.string(),
+    annotations: McpAnnotationsSchema
+  }),
+  z2.object({
+    type: z2.literal("image"),
+    data: z2.string(),
+    mimeType: z2.string(),
+    annotations: McpAnnotationsSchema
+  }),
+  z2.object({
+    type: z2.literal("resource"),
+    resource: z2.object({
+      uri: z2.string(),
+      mimeType: z2.string().optional(),
+      text: z2.string().optional(),
+      annotations: McpAnnotationsSchema
+    })
+  })
+]);
+function createMcpResponse(data, summary, options) {
+  const { structuredContentPathHint, contentSummary, includeSerializedStructuredContent = false } = options || {};
+  void includeSerializedStructuredContent;
+  let finalData = data;
+  if (data && typeof data === "object") {
+    const cloned = JSON.parse(JSON.stringify(data));
+    finalData = cloned;
+    const arrayKeys = ["results", "tasks", "memories", "items"];
+    let foundArray = false;
+    for (const key of arrayKeys) {
+      const value = cloned[key];
+      if (Array.isArray(value)) {
+        cloned[key] = value.map(
+          (item) => pruneMetadata(item)
+        );
+        foundArray = true;
+      }
+    }
+    if (Array.isArray(cloned)) {
+      finalData = cloned.map((item) => pruneMetadata(item));
+    } else if (!foundArray) {
+      finalData = pruneMetadata(cloned);
+    }
+  }
+  const content = [];
+  if (contentSummary && contentSummary.trim().length > 0) {
+    content.push({
+      type: "text",
+      text: contentSummary.trim()
+    });
+  } else if (summary && summary.trim().length > 0) {
+    const pointerText = structuredContentPathHint ? `Read structuredContent.${structuredContentPathHint} for details.` : `Read structuredContent for machine-readable results.`;
+    content.push({
+      type: "text",
+      text: `${summary.trim()} ${pointerText}`
+    });
+  }
+  const response = {
+    structuredContent: finalData,
+    isError: false
+  };
+  if (includeSerializedStructuredContent === false) {
+    delete response.structuredContent;
+  }
+  response.content = content;
+  return response;
+}
+function pruneMetadata(item) {
+  if (!item || typeof item !== "object") return item;
+  const pruned = { ...item };
+  const toRemove = [
+    "hit_count",
+    "recall_count",
+    "last_used_at",
+    "expires_at",
+    "agent",
+    "role",
+    "model",
+    "recall_rate",
+    "vector_version",
+    "similarity"
+    // Similarity is useful but adds noise if many results
+  ];
+  for (const field of toRemove) {
+    delete pruned[field];
+  }
+  return pruned;
+}
+function getPrimaryTextContent(response) {
+  if (!Array.isArray(response.content)) return "";
+  const textItem = response.content.find((item) => item.type === "text");
+  return textItem?.type === "text" ? textItem.text : "";
+}
+
+// src/mcp/tools/handoff.manage.ts
+function buildHandoffListSummary(repo, count, status, fromAgent, toAgent) {
+  const parts = [`Found ${count} handoff${count === 1 ? "" : "s"} in repo "${repo}".`];
+  if (status) {
+    parts.push(`Status filter: ${status}.`);
+  }
+  if (fromAgent) {
+    parts.push(`From agent: ${fromAgent}.`);
+  }
+  if (toAgent) {
+    parts.push(`To agent: ${toAgent}.`);
+  }
+  return parts.join("\n");
+}
+function buildClaimListSummary(repo, count, agent, activeOnly) {
+  const parts = [`Found ${count} claim${count === 1 ? "" : "s"} in repo "${repo}".`];
+  if (agent) {
+    parts.push(`Agent filter: ${agent}.`);
+  }
+  if (activeOnly) {
+    parts.push("Showing active claims only.");
+  }
+  return parts.join("\n");
+}
+async function handleHandoffCreate(args, storage) {
+  const validated = HandoffCreateSchema.parse(args);
+  const { repo, from_agent, to_agent, task_id, task_code, summary, context, expires_at, structured } = validated;
+  let resolvedTaskId = task_id ?? null;
+  if (!resolvedTaskId && task_code) {
+    const task = storage.tasks.getTaskByCode(repo, task_code);
+    if (!task) {
+      throw new Error(`Task not found: ${task_code} in repo ${repo}`);
+    }
+    resolvedTaskId = task.id;
+  }
+  const handoff = storage.handoffs.createHandoff({
+    repo,
+    from_agent,
+    to_agent,
+    task_id: resolvedTaskId,
+    summary,
+    context,
+    expires_at
+  });
+  const contentSummary = [
+    `Created handoff ${handoff.id}.`,
+    `Repo: ${handoff.repo}`,
+    `From: ${handoff.from_agent}`,
+    `To: ${handoff.to_agent || "unassigned"}`,
+    `Status: ${handoff.status}`,
+    `Task ID: ${handoff.task_id || "-"}`,
+    `Summary: ${handoff.summary}`
+  ].join("\n");
+  return createMcpResponse(handoff, contentSummary, {
+    contentSummary,
+    includeSerializedStructuredContent: structured
+  });
+}
+async function handleHandoffList(args, storage) {
+  const validated = HandoffListSchema.parse(args);
+  const { repo, status, from_agent, to_agent, limit, offset, structured } = validated;
+  const handoffs = storage.handoffs.listHandoffs({
+    repo,
+    status,
+    from_agent,
+    to_agent,
+    limit,
+    offset
+  });
+  const COLUMNS = [
+    "id",
+    "from_agent",
+    "to_agent",
+    "task_id",
+    "task_code",
+    "status",
+    "created_at",
+    "updated_at",
+    "expires_at",
+    "summary",
+    "context"
+  ];
+  const rows = handoffs.map((handoff) => [
+    handoff.id,
+    handoff.from_agent,
+    handoff.to_agent,
+    handoff.task_id,
+    handoff.task_code ?? null,
+    handoff.status,
+    handoff.created_at,
+    handoff.updated_at,
+    handoff.expires_at,
+    handoff.summary,
+    handoff.context
+  ]);
+  const structuredData = {
+    schema: "handoff-list",
+    handoffs: {
+      columns: [...COLUMNS],
+      rows
+    },
+    count: rows.length,
+    offset
+  };
+  const contentSummary = buildHandoffListSummary(repo, rows.length, status, from_agent, to_agent);
+  return createMcpResponse(structuredData, contentSummary, {
+    contentSummary,
+    includeSerializedStructuredContent: structured
+  });
+}
+async function handleHandoffUpdate(args, storage) {
+  const validated = HandoffUpdateSchema.parse(args);
+  const { id, status, structured } = validated;
+  const existing = storage.handoffs.getHandoffById(id);
+  if (!existing) {
+    throw new Error(`Handoff not found: ${id}`);
+  }
+  const success = storage.handoffs.updateHandoffStatus(id, status);
+  if (!success) {
+    throw new Error(`Failed to update handoff: ${id}`);
+  }
+  const updated = storage.handoffs.getHandoffById(id);
+  const result = {
+    success,
+    id,
+    status,
+    handoff: updated
+  };
+  const contentSummary = [`Updated handoff ${id}.`, `Status: ${status}`].join("\n");
+  return createMcpResponse(result, contentSummary, {
+    contentSummary,
+    includeSerializedStructuredContent: structured
+  });
+}
+async function handleTaskClaim(args, storage) {
+  const validated = TaskClaimSchema.parse(args);
+  const { repo, task_id, task_code, agent, role, metadata, structured } = validated;
+  let taskId = task_id;
+  let resolvedTaskCode;
+  if (taskId) {
+    const task = storage.tasks.getTaskById(taskId);
+    if (!task || task.repo !== repo) {
+      throw new Error(`Task not found: ${taskId} in repo ${repo}`);
+    }
+    resolvedTaskCode = task.task_code;
+  } else if (task_code) {
+    const task = storage.tasks.getTaskByCode(repo, task_code);
+    if (!task) {
+      throw new Error(`Task not found: ${task_code} in repo ${repo}`);
+    }
+    taskId = task.id;
+    resolvedTaskCode = task.task_code;
+  } else {
+    throw new Error("Either task_id or task_code must be provided");
+  }
+  const claim = storage.handoffs.claimTask({
+    repo,
+    task_id: taskId,
+    agent,
+    role,
+    metadata
+  });
+  const responseData = {
+    ...claim,
+    task_code: resolvedTaskCode
+  };
+  const contentSummary = [
+    `Claimed task ${resolvedTaskCode || claim.task_id}.`,
+    `Repo: ${claim.repo}`,
+    `Task ID: ${claim.task_id}`,
+    `Agent: ${claim.agent}`,
+    `Role: ${claim.role}`,
+    `Claimed At: ${claim.claimed_at}`
+  ].join("\n");
+  const response = createMcpResponse(responseData, contentSummary, {
+    contentSummary,
+    includeSerializedStructuredContent: structured
+  });
+  if (structured) {
+    response.structuredContent = responseData;
+  }
+  return response;
+}
+async function handleClaimList(args, storage) {
+  const validated = ClaimListSchema.parse(args);
+  const { repo, agent, active_only, limit, offset, structured } = validated;
+  const claims = storage.handoffs.listClaims({
+    repo,
+    agent,
+    active_only,
+    limit,
+    offset
+  });
+  const COLUMNS = ["id", "task_id", "task_code", "agent", "role", "claimed_at", "released_at", "metadata"];
+  const rows = claims.map((claim) => [
+    claim.id,
+    claim.task_id,
+    claim.task_code ?? null,
+    claim.agent,
+    claim.role,
+    claim.claimed_at,
+    claim.released_at,
+    claim.metadata
+  ]);
+  const structuredData = {
+    schema: "claim-list",
+    claims: {
+      columns: [...COLUMNS],
+      rows
+    },
+    count: rows.length,
+    offset
+  };
+  const contentSummary = buildClaimListSummary(repo, rows.length, agent, active_only);
+  return createMcpResponse(structuredData, contentSummary, {
+    contentSummary,
+    includeSerializedStructuredContent: structured
+  });
+}
+async function handleClaimRelease(args, storage) {
+  const validated = ClaimReleaseSchema.parse(args);
+  const { repo, task_id, task_code, agent, structured } = validated;
+  let resolvedTaskId = task_id;
+  let resolvedTaskCode = task_code ?? null;
+  if (resolvedTaskId) {
+    const task = storage.tasks.getTaskById(resolvedTaskId);
+    if (!task || task.repo !== repo) {
+      throw new Error(`Task not found: ${resolvedTaskId} in repo ${repo}`);
+    }
+    resolvedTaskCode = task.task_code;
+  } else if (task_code) {
+    const task = storage.tasks.getTaskByCode(repo, task_code);
+    if (!task) {
+      throw new Error(`Task not found: ${task_code} in repo ${repo}`);
+    }
+    resolvedTaskId = task.id;
+    resolvedTaskCode = task.task_code;
+  }
+  const success = storage.handoffs.releaseClaim(resolvedTaskId, agent);
+  if (!success) {
+    throw new Error(`No active claim found for task ${resolvedTaskCode || resolvedTaskId}`);
+  }
+  const result = {
+    success,
+    repo,
+    task_id: resolvedTaskId,
+    task_code: resolvedTaskCode,
+    agent: agent ?? null
+  };
+  const contentSummary = [
+    `Released claim for task ${resolvedTaskCode || resolvedTaskId}.`,
+    `Repo: ${repo}`,
+    agent ? `Agent: ${agent}` : "Agent: any active claimant"
+  ].join("\n");
+  return createMcpResponse(result, contentSummary, {
+    contentSummary,
+    includeSerializedStructuredContent: structured
+  });
+}
+
 // src/mcp/tools/standard.shared.ts
 function toContextSlug(value) {
   return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
@@ -5414,17 +5958,12 @@ export {
   TaskCreateInteractiveSchema,
   TaskUpdateSchema,
   TaskListSchema,
+  TaskSearchSchema,
   TaskDeleteSchema,
   MemoryDetailSchema,
   StandardDetailSchema,
   StandardDeleteSchema,
   TaskGetSchema,
-  HandoffCreateSchema,
-  HandoffUpdateSchema,
-  HandoffListSchema,
-  TaskClaimSchema,
-  ClaimListSchema,
-  ClaimReleaseSchema,
   StandardStoreSchema,
   StandardUpdateSchema,
   StandardSearchSchema,
@@ -5447,6 +5986,14 @@ export {
   listPrompts,
   getPrompt,
   completePromptArgument,
+  createMcpResponse,
+  getPrimaryTextContent,
+  handleHandoffCreate,
+  handleHandoffList,
+  handleHandoffUpdate,
+  handleTaskClaim,
+  handleClaimList,
+  handleClaimRelease,
   toContextSlug,
   buildStandardVectorText
 };