shabti 2.10.1 → 2.12.0

package/README.md

@@ -60,6 +60,7 @@ shabti status
 | ----------------- | ----------------------------------- |
 | `store <content>` | Store a memory entry                |
 | `search <query>`  | Search memory entries               |
+| `get <id>`        | Retrieve a memory entry by ID       |
 | `delete <id>`     | Delete a memory entry by ID         |
 | `status`          | Show engine status                  |
 | `export`          | Export memories as JSONL            |
@@ -92,6 +93,13 @@ shabti search "recent events" --min-score 0.5
 shabti search "query" --json                    # JSON output
 ```
 
+### get
+
+```bash
+shabti get <uuid>
+shabti get <uuid> --json
+```
+
 ### delete
 
 ```bash
@@ -202,11 +210,13 @@ Or manually add to your MCP settings:
 | --------------- | ----------------------------------------------------------- |
 | `memory_store`  | Store a memory entry with optional namespace, tags, and TTL |
 | `memory_search` | Search memories by semantic similarity                      |
+| `memory_get`    | Retrieve a specific memory entry by UUID                    |
 | `memory_delete` | Delete a memory entry by ID                                 |
 | `memory_list`   | List recent memory entries                                  |
 | `memory_export` | Export entries as JSONL                                     |
 | `memory_gc`     | Garbage collect expired entries                             |
 | `memory_status` | Get engine status                                           |
+| `memory_health` | Run health checks on engine components                      |
 
 ### MCP Resources
 
@@ -247,6 +257,10 @@ Discoverable at `GET /.well-known/agent-card.json`.
 | `tasks/get`    | Retrieve task status and results |
 | `tasks/cancel` | Cancel a running task            |
 
+### CORS
+
+The A2A server sets `Access-Control-Allow-Origin: *` to allow requests from any origin. This is intentional for local development and inter-agent communication where the caller's origin is not known in advance. For production deployments behind a reverse proxy, restrict the origin at the proxy level.
+
 ## Node.js API
 
 ```javascript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shabti",
-  "version": "2.10.1",
+  "version": "2.12.0",
   "description": "Agent Memory OS — semantic memory for AI agents",
   "type": "module",
   "main": "native.cjs",
@@ -77,6 +77,7 @@
     "@commitlint/config-conventional": "^20.4.1",
     "@eslint/js": "^10.0.1",
     "@napi-rs/cli": "^3.5.1",
+    "@semantic-release/changelog": "^6.0.3",
     "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^10.0.0",
     "eslint-config-prettier": "^10.1.8",

package/src/a2a/agentCard.js

@@ -43,6 +43,54 @@ export function buildAgentCard(baseUrl) {
         inputModes: ["text"],
         outputModes: ["application/json"],
       },
+      {
+        id: "memory_get",
+        name: "Get Memory",
+        description: "Retrieve a specific memory entry by its ID",
+        tags: ["memory", "get", "retrieve", "fetch"],
+        inputModes: ["application/json"],
+        outputModes: ["application/json"],
+      },
+      {
+        id: "memory_delete",
+        name: "Delete Memory",
+        description: "Delete a specific memory entry by its ID",
+        tags: ["memory", "delete", "remove"],
+        inputModes: ["application/json"],
+        outputModes: ["application/json"],
+      },
+      {
+        id: "memory_list",
+        name: "List Memories",
+        description: "List stored memory entries with optional filters",
+        tags: ["memory", "list", "entries"],
+        inputModes: ["text", "application/json"],
+        outputModes: ["application/json"],
+      },
+      {
+        id: "memory_export",
+        name: "Export Memories",
+        description: "Export all memory entries as JSONL data",
+        tags: ["memory", "export", "dump", "backup"],
+        inputModes: ["text", "application/json"],
+        outputModes: ["application/json"],
+      },
+      {
+        id: "memory_gc",
+        name: "Garbage Collect",
+        description: "Remove expired memory entries and reclaim storage",
+        tags: ["memory", "gc", "garbage", "cleanup"],
+        inputModes: ["text"],
+        outputModes: ["application/json"],
+      },
+      {
+        id: "memory_health",
+        name: "Health Check",
+        description: "Check the health of the memory engine and its dependencies",
+        tags: ["memory", "health", "diagnostics"],
+        inputModes: ["text"],
+        outputModes: ["application/json"],
+      },
     ],
   };
 }

package/src/a2a/server.js

@@ -122,6 +122,112 @@ function handleMemoryStatus(engine) {
   };
 }
 
+async function handleMemoryDelete(engine, parts) {
+  let id = null;
+
+  for (const part of parts) {
+    if (part.kind === "data" && part.data?.id) {
+      id = part.data.id;
+    }
+  }
+
+  if (!id) {
+    throw Object.assign(new Error("Missing id in message parts"), { code: -32602 });
+  }
+
+  await engine.delete(id);
+  return {
+    artifactId: randomUUID(),
+    name: "delete_result",
+    parts: [{ kind: "data", data: { deleted: true, id } }],
+  };
+}
+
+async function handleMemoryGet(engine, parts) {
+  let id = null;
+
+  for (const part of parts) {
+    if (part.kind === "data" && part.data?.id) {
+      id = part.data.id;
+    }
+  }
+
+  if (!id) {
+    throw Object.assign(new Error("Missing id in message parts"), { code: -32602 });
+  }
+
+  const entry = await engine.get(id);
+  return {
+    artifactId: randomUUID(),
+    name: "get_result",
+    parts: [{ kind: "data", data: entry }],
+  };
+}
+
+function handleMemoryList(engine, parts) {
+  let opts = {};
+
+  for (const part of parts) {
+    if (part.kind === "data" && part.data) {
+      if (part.data.limit) opts.limit = part.data.limit;
+      if (part.data.namespace) opts.namespace = part.data.namespace;
+    }
+  }
+
+  const entries = engine.listEntries(opts);
+  return {
+    artifactId: randomUUID(),
+    name: "list_result",
+    parts: [{ kind: "data", data: { entries, count: entries.length } }],
+  };
+}
+
+function handleMemoryExport(engine) {
+  const entries = engine.listEntries();
+  const lines = entries.map((e) => JSON.stringify(e));
+  return {
+    artifactId: randomUUID(),
+    name: "export_result",
+    parts: [{ kind: "data", data: { entries: entries.length, data: lines.join("\n") } }],
+  };
+}
+
+async function handleMemoryGc(engine) {
+  const removed = await engine.gc();
+  return {
+    artifactId: randomUUID(),
+    name: "gc_result",
+    parts: [{ kind: "data", data: { removed } }],
+  };
+}
+
+async function handleMemoryHealth(engine) {
+  const checks = [];
+  const status = engine.status();
+  const qdrantUrl = status.qdrantUrl.replace(/:\d+$/, ":6333");
+
+  try {
+    const res = await fetch(`${qdrantUrl}/healthz`, { signal: AbortSignal.timeout(3000) });
+    checks.push({
+      name: "qdrant",
+      status: res.ok ? "ok" : "degraded",
+      message: res.ok ? "Reachable" : `HTTP ${res.status}`,
+    });
+  } catch (err) {
+    checks.push({ name: "qdrant", status: "error", message: err.message });
+  }
+
+  checks.push({ name: "engine", status: "ok", message: `${status.entryCount} entries` });
+  checks.push({ name: "embedding", status: "ok", message: `Model: ${engine.modelId()}` });
+
+  const healthy = checks.every((c) => c.status === "ok");
+  return {
+    artifactId: randomUUID(),
+    name: "health_result",
+    parts: [{ kind: "data", data: { healthy, checks } }],
+  };
+}
+
 // ============================================================
 // Skill Router
 // ============================================================
@@ -140,6 +246,11 @@ export function resolveSkill(parts) {
       const lower = part.text.toLowerCase();
       if (/\b(store|save|remember)\b/.test(lower)) return "memory_store";
       if (/\b(search|find|recall|query)\b/.test(lower)) return "memory_search";
+      if (/\b(delete|remove)\b/.test(lower)) return "memory_delete";
+      if (/\b(get|retrieve)\b/.test(lower)) return "memory_get";
+      if (/\b(list)\b/.test(lower)) return "memory_list";
+      if (/\b(export|dump)\b/.test(lower)) return "memory_export";
+      if (/\b(garbage|cleanup)\b/.test(lower)) return "memory_gc";
       if (/\b(status|health|stats|info)\b/.test(lower)) return "memory_status";
     }
   }
@@ -149,6 +260,7 @@ export function resolveSkill(parts) {
     if (part.kind === "data" && part.data) {
       if (part.data.content) return "memory_store";
       if (part.data.query) return "memory_search";
+      if (part.data.id) return "memory_get";
     }
   }
 
@@ -204,6 +316,24 @@ async function handleMessageSend(engine, taskStore, params) {
       case "memory_status":
         artifact = handleMemoryStatus(engine);
         break;
+      case "memory_delete":
+        artifact = await handleMemoryDelete(engine, message.parts);
+        break;
+      case "memory_get":
+        artifact = await handleMemoryGet(engine, message.parts);
+        break;
+      case "memory_list":
+        artifact = handleMemoryList(engine, message.parts);
+        break;
+      case "memory_export":
+        artifact = handleMemoryExport(engine);
+        break;
+      case "memory_gc":
+        artifact = await handleMemoryGc(engine);
+        break;
+      case "memory_health":
+        artifact = await handleMemoryHealth(engine);
+        break;
       default:
         task.status = { state: "failed", timestamp: new Date().toISOString() };
         taskStore.set(task.id, task);

package/src/commands/get.js

@@ -0,0 +1,42 @@
+import chalk from "chalk";
+import { createEngine } from "../core/engine.js";
+import { error, heading } from "../utils/style.js";
+
+export function registerGet(program) {
+  program
+    .command("get")
+    .description("Retrieve a memory entry by ID")
+    .argument("<id>", "UUID of the memory entry to retrieve")
+    .option("-j, --json", "Output as JSON")
+    .action(async (id, opts) => {
+      try {
+        const engine = createEngine();
+        const entry = await engine.get(id);
+
+        if (opts.json) {
+          console.log(JSON.stringify(entry, null, 2));
+        } else {
+          heading(`Memory Entry`);
+          console.log();
+          console.log(`  ${chalk.cyan("ID:")}         ${entry.id}`);
+          console.log(`  ${chalk.cyan("Content:")}    ${entry.content}`);
+          console.log(`  ${chalk.cyan("Namespace:")}  ${entry.namespace}`);
+          console.log(`  ${chalk.cyan("Score:")}      ${entry.score}`);
+          console.log(
+            `  ${chalk.cyan("Created:")}    ${new Date(entry.createdAt * 1000).toISOString()}`,
+          );
+          if (entry.expiresAt) {
+            console.log(
+              `  ${chalk.cyan("Expires:")}    ${new Date(entry.expiresAt * 1000).toISOString()}`,
+            );
+          }
+          console.log();
+        }
+
+        await engine.shutdown();
+      } catch (err) {
+        error(err.message);
+        process.exitCode = 1;
+      }
+    });
+}

package/src/index.js

@@ -16,6 +16,7 @@ import { registerExport } from "./commands/export.js";
 import { registerImport } from "./commands/import.js";
 import { registerStore } from "./commands/store.js";
 import { registerDelete } from "./commands/delete.js";
+import { registerGet } from "./commands/get.js";
 import { registerHealth } from "./commands/health.js";
 
 const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -87,6 +88,7 @@ function buildProgram() {
   registerImport(program);
   registerStore(program);
   registerDelete(program);
+  registerGet(program);
   registerHealth(program);
 
   program

package/src/mcp/server.js

@@ -103,6 +103,26 @@ const TOOLS = [
       properties: {},
     },
   },
+  {
+    name: "memory_health",
+    description:
+      "Run health checks on the memory engine (Qdrant connectivity, engine status, embedding model)",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+  {
+    name: "memory_get",
+    description: "Retrieve a specific memory entry by its UUID",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "UUID of the memory entry to retrieve" },
+      },
+      required: ["id"],
+    },
+  },
 ];
 
 const RESOURCES = [
@@ -373,6 +393,78 @@ async function handleToolsCall(id, params) {
     }
   }
 
+  if (name === "memory_health") {
+    const checks = [];
+    const config = loadConfig();
+    const qdrantUrl = config.qdrant_url.replace(/:\d+$/, ":6333");
+    try {
+      const res = await fetch(`${qdrantUrl}/healthz`, {
+        signal: AbortSignal.timeout(3000),
+      });
+      checks.push({
+        name: "qdrant",
+        status: res.ok ? "ok" : "degraded",
+        message: res.ok ? "Reachable" : `HTTP ${res.status}`,
+      });
+    } catch (err) {
+      checks.push({ name: "qdrant", status: "error", message: err.message });
+    }
+
+    if (eng) {
+      try {
+        const status = eng.status();
+        checks.push({
+          name: "engine",
+          status: "ok",
+          message: `${status.entryCount} entries, tier: ${status.tier}`,
+        });
+      } catch (err) {
+        checks.push({ name: "engine", status: "error", message: err.message });
+      }
+      try {
+        const modelId = eng.modelId();
+        checks.push({ name: "embedding", status: "ok", message: modelId });
+      } catch (err) {
+        checks.push({ name: "embedding", status: "error", message: err.message });
+      }
+    } else {
+      checks.push({ name: "engine", status: "error", message: "Engine not available" });
+    }
+
+    const healthy = checks.every((c) => c.status === "ok");
+    return respond(id, {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ healthy, checks }, null, 2),
+        },
+      ],
+    });
+  }
+
+  if (name === "memory_get") {
+    if (!eng) {
+      return respondError(id, -32603, "Engine not available");
+    }
+    const entryId = args?.id;
+    if (!entryId) {
+      return respondError(id, -32602, "Missing required parameter: id");
+    }
+    try {
+      const entry = await eng.get(entryId);
+      return respond(id, {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(entry, null, 2),
+          },
+        ],
+      });
+    } catch (err) {
+      return respondError(id, -32603, err.message);
+    }
+  }
+
   respondError(id, -32601, `Unknown tool: ${name}`);
 }