shabti 2.2.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shabti",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Agent Memory OS — semantic memory for AI agents",
   "type": "module",
   "main": "native.cjs",

package/src/commands/export.js

@@ -0,0 +1,44 @@
+import { writeFileSync } from "fs";
+import { createEngine } from "../core/engine.js";
+import { success, error } from "../utils/style.js";
+
+export function registerExport(program) {
+  program
+    .command("export")
+    .description("Export memory entries as JSONL")
+    .option("-n, --namespace <ns>", "Filter by namespace")
+    .option("--no-embeddings", "Exclude embedding vectors from output")
+    .option("-o, --output <file>", "Write to file instead of stdout")
+    .option("--limit <n>", "Maximum number of entries to export")
+    .action(async (opts) => {
+      try {
+        const engine = createEngine();
+        const listOpts = {};
+        if (opts.namespace) listOpts.namespace = opts.namespace;
+        if (opts.limit) listOpts.limit = parseInt(opts.limit, 10);
+        listOpts.includeEmbeddings = opts.embeddings !== false ? false : false;
+        // --no-embeddings sets opts.embeddings = false (commander negatable)
+        // default: exclude embeddings for smaller output
+        listOpts.includeEmbeddings = opts.embeddings === true;
+
+        const entries = engine.listEntries(listOpts);
+
+        const lines = entries.map((e) => JSON.stringify(e));
+        const output = lines.join("\n");
+
+        if (opts.output) {
+          writeFileSync(opts.output, output + (lines.length ? "\n" : ""), "utf8");
+          success(`Exported ${entries.length} entries to ${opts.output}`);
+        } else {
+          if (output) console.log(output);
+          // Print summary to stderr so it doesn't pollute piped output
+          process.stderr.write(`\n${entries.length} entries exported\n`);
+        }
+
+        await engine.shutdown();
+      } catch (err) {
+        error(err.message);
+        process.exitCode = 1;
+      }
+    });
+}

package/src/commands/import.js

@@ -0,0 +1,66 @@
+import { readFileSync } from "fs";
+import { createEngine } from "../core/engine.js";
+import { success, error, info, warn } from "../utils/style.js";
+
+export function registerImport(program) {
+  program
+    .command("import")
+    .description("Import memory entries from a JSONL file")
+    .argument("<file>", "Path to JSONL file")
+    .option("-n, --namespace <ns>", "Override namespace for all imported entries")
+    .option("--dry-run", "Parse and validate without storing")
+    .action(async (file, opts) => {
+      try {
+        const raw = readFileSync(file, "utf8");
+        const lines = raw
+          .split("\n")
+          .map((l) => l.trim())
+          .filter((l) => l.length > 0);
+
+        if (lines.length === 0) {
+          info("No entries found in file.");
+          return;
+        }
+
+        // Parse all lines first to validate
+        const entries = [];
+        for (let i = 0; i < lines.length; i++) {
+          try {
+            entries.push(JSON.parse(lines[i]));
+          } catch {
+            warn(`Skipping invalid JSON on line ${i + 1}`);
+          }
+        }
+
+        if (opts.dryRun) {
+          info(`Dry run: ${entries.length} entries parsed, 0 stored.`);
+          return;
+        }
+
+        const engine = createEngine();
+        let stored = 0;
+        let skipped = 0;
+
+        for (const entry of entries) {
+          const storeOpts = {};
+          storeOpts.namespace = opts.namespace || entry.namespace || undefined;
+          if (entry.tags && entry.tags.length) storeOpts.tags = entry.tags;
+          if (entry.sessionId || entry.session_id)
+            storeOpts.sessionId = entry.sessionId || entry.session_id;
+
+          const result = await engine.store(entry.content, storeOpts);
+          if (result.status === "stored") {
+            stored++;
+          } else {
+            skipped++;
+          }
+        }
+
+        success(`Import complete: ${stored} stored, ${skipped} skipped (duplicates)`);
+        await engine.shutdown();
+      } catch (err) {
+        error(err.message);
+        process.exitCode = 1;
+      }
+    });
+}

package/src/commands/store.js

@@ -9,6 +9,7 @@ export function registerStore(program) {
     .option("-n, --namespace <ns>", "Namespace for the entry")
     .option("-s, --session <id>", "Session ID")
     .option("-t, --tags <tags>", "Comma-separated tags")
+    .option("--ttl <seconds>", "Time-to-live in seconds (auto-expires after this duration)")
     .action(async (content, opts) => {
       try {
         const engine = createEngine();
@@ -16,6 +17,7 @@ export function registerStore(program) {
         if (opts.namespace) options.namespace = opts.namespace;
         if (opts.session) options.sessionId = opts.session;
         if (opts.tags) options.tags = opts.tags.split(",").map((t) => t.trim());
+        if (opts.ttl) options.ttlSeconds = parseInt(opts.ttl, 10);
 
         // Model versioning check
         const currentModelId = engine.modelId();

package/src/index.js

@@ -11,6 +11,8 @@ import { registerSearch } from "./commands/search.js";
 import { registerSnapshot } from "./commands/snapshot.js";
 import { registerSpin } from "./commands/spin.js";
 import { registerStatus } from "./commands/status.js";
+import { registerExport } from "./commands/export.js";
+import { registerImport } from "./commands/import.js";
 import { registerStore } from "./commands/store.js";
 
 const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -77,8 +79,27 @@ function buildProgram() {
   registerSnapshot(program);
   registerSpin(program);
   registerStatus(program);
+  registerExport(program);
+  registerImport(program);
   registerStore(program);
 
+  program
+    .command("gc")
+    .description("Garbage collect expired memory entries")
+    .action(async () => {
+      const { createEngine } = await import("./core/engine.js");
+      const { success, error: showError } = await import("./utils/style.js");
+      try {
+        const engine = createEngine();
+        const removed = await engine.gc();
+        success(`GC complete: ${removed} expired entries removed`);
+        await engine.shutdown();
+      } catch (err) {
+        showError(err.message);
+        process.exitCode = 1;
+      }
+    });
+
   program
     .command("mcp-config")
     .description("Print MCP server configuration JSON for Claude Code / Cursor")

package/src/mcp/server.js

@@ -24,6 +24,10 @@ const TOOLS = [
           items: { type: "string" },
           description: "Tags to associate with the memory",
         },
+        ttl: {
+          type: "integer",
+          description: "Time-to-live in seconds (entry auto-expires after this duration)",
+        },
       },
       required: ["content"],
     },
@@ -69,6 +73,25 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: "memory_export",
+    description: "Export all memory entries as a JSONL array",
+    inputSchema: {
+      type: "object",
+      properties: {
+        namespace: { type: "string", description: "Filter by namespace" },
+        limit: { type: "integer", description: "Maximum entries to export" },
+      },
+    },
+  },
+  {
+    name: "memory_gc",
+    description: "Garbage collect expired memory entries (removes entries past their TTL)",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
   {
     name: "memory_status",
     description: "Get the current status of the memory engine",
@@ -191,6 +214,7 @@ async function handleToolsCall(id, params) {
       const opts = {};
       if (args.namespace) opts.namespace = args.namespace;
       if (args.tags) opts.tags = args.tags;
+      if (args.ttl) opts.ttlSeconds = args.ttl;
       const result = await eng.store(content, opts);
       return respond(id, {
         content: [
@@ -293,6 +317,48 @@ async function handleToolsCall(id, params) {
     }
   }
 
+  if (name === "memory_export") {
+    if (!eng) {
+      return respondError(id, -32603, "Engine not available");
+    }
+    try {
+      const listOpts = {};
+      if (args?.namespace) listOpts.namespace = args.namespace;
+      if (args?.limit) listOpts.limit = args.limit;
+      const entries = eng.listEntries(listOpts);
+      const lines = entries.map((e) => JSON.stringify(e));
+      return respond(id, {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ entries: entries.length, data: lines.join("\n") }, null, 2),
+          },
+        ],
+      });
+    } catch (err) {
+      return respondError(id, -32603, err.message);
+    }
+  }
+
+  if (name === "memory_gc") {
+    if (!eng) {
+      return respondError(id, -32603, "Engine not available");
+    }
+    try {
+      const removed = await eng.gc();
+      return respond(id, {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ removed }, null, 2),
+          },
+        ],
+      });
+    } catch (err) {
+      return respondError(id, -32603, err.message);
+    }
+  }
+
   respondError(id, -32601, `Unknown tool: ${name}`);
 }
 

package/src/repl/slashCommands.js

@@ -9,6 +9,7 @@ const COMMANDS = {
   "/history": "Show conversation history",
   "/remember": "Store a memory (e.g. /remember Tokyo is the capital of Japan)",
   "/recall": "Search memories (e.g. /recall capital of Japan)",
+  "/gc": "Garbage collect expired memory entries",
 };
 
 /**
@@ -75,6 +76,9 @@ export function handleSlashCommand(cmd, args, session, rl, engine = null) {
     case "/recall":
       return handleRecall(args, engine);
 
+    case "/gc":
+      return handleGc(engine);
+
     default:
       return false;
   }
@@ -136,3 +140,20 @@ async function handleRecall(query, engine) {
   console.log();
   return true;
 }
+
+async function handleGc(engine) {
+  if (!engine) {
+    console.log();
+    warn("Memory engine not available. Start Qdrant to enable memory features.");
+    console.log();
+    return true;
+  }
+  try {
+    const removed = await engine.gc();
+    success(`GC complete: ${removed} expired entries removed`);
+  } catch (err) {
+    error(`Failed to run GC: ${err.message}`);
+  }
+  console.log();
+  return true;
+}