shabti 2.6.0 → 2.8.0

package/README.md

@@ -2,7 +2,7 @@
 
 Agent Memory OS — semantic memory for AI agents.
 
-A Rust-powered memory engine with Node.js CLI that provides semantic search, deduplication, time-decay scoring, and graph-based memory linking for AI agents.
+A Rust-powered memory engine with Node.js CLI that provides semantic search, deduplication, time-decay scoring, and graph-based memory linking for AI agents. Integrates with Claude Code, Cursor, and other tools via MCP and A2A protocols.
 
 ## Install
 
@@ -30,11 +30,14 @@ shabti config setup --check
 # Store a memory
 shabti store "Rust is a systems programming language"
 
+# Store with namespace and TTL (auto-expires after 1 hour)
+shabti store "temp note" --namespace work --ttl 3600
+
 # Search memories
 shabti search "systems programming"
 
-# Search with score explanation
-shabti search "programming" --explain
+# Search with score explanation and graph expansion
+shabti search "programming" --explain --follow-links 2
 
 # Check engine status
 shabti status
@@ -42,14 +45,21 @@ shabti status
 
 ## Commands
 
-| Command           | Description                  |
-| ----------------- | ---------------------------- |
-| `store <content>` | Store a memory entry         |
-| `search <query>`  | Search memory entries        |
-| `status`          | Show engine status           |
-| `snapshot`        | Manage storage snapshots     |
-| `config`          | Manage configuration         |
-| `chat`            | Interactive chat with OpenAI |
+| Command           | Description                         |
+| ----------------- | ----------------------------------- |
+| `store <content>` | Store a memory entry                |
+| `search <query>`  | Search memory entries               |
+| `delete <id>`     | Delete a memory entry by ID         |
+| `status`          | Show engine status                  |
+| `export`          | Export memories as JSONL            |
+| `import <file>`   | Import memories from JSONL          |
+| `snapshot`        | Manage storage snapshots            |
+| `config`          | Manage configuration                |
+| `gc`              | Garbage collect expired entries     |
+| `health`          | Run health checks on engine         |
+| `a2a`             | Start A2A protocol server           |
+| `chat`            | Interactive chat with OpenAI        |
+| `mcp-config`      | Print MCP server configuration JSON |
 
 ### store
 
@@ -57,6 +67,7 @@ shabti status
 shabti store "Tokyo is the capital of Japan"
 shabti store "meeting at 3pm" --namespace work
 shabti store "buy groceries" --tags "todo,personal"
+shabti store "temporary note" --ttl 3600    # expires in 1 hour
 ```
 
 ### search
@@ -70,6 +81,28 @@ shabti search "recent events" --min-score 0.5
 shabti search "query" --json                    # JSON output
 ```
 
+### delete
+
+```bash
+shabti delete <uuid>
+```
+
+### export / import
+
+```bash
+# Export all entries to stdout
+shabti export
+
+# Export to file with namespace filter
+shabti export --namespace work --output backup.jsonl
+
+# Import from JSONL file
+shabti import backup.jsonl
+
+# Import with namespace override and dry-run
+shabti import data.jsonl --namespace imported --dry-run
+```
+
 ### snapshot
 
 ```bash
@@ -88,13 +121,18 @@ shabti config setup           # show Qdrant setup instructions
 shabti config setup --check   # test Qdrant connection
 ```
 
+### gc
+
+```bash
+shabti gc    # remove entries past their TTL
+```
+
 ## Interactive Mode (REPL)
 
 Run `shabti` with no arguments in a terminal to enter interactive mode:
 
 ```
 $ shabti
-  shabti v2.0.0
 
   [info] Memory engine connected (/remember, /recall available)
   [info] Interactive mode — model: gpt-4o-mini
@@ -119,14 +157,14 @@ Requires `OPENAI_API_KEY` in `.env` for chat functionality. Memory commands (`/r
 
 ## MCP Server
 
-shabti includes an MCP (Model Context Protocol) server for integration with Claude Code, Cursor, and other MCP-compatible tools.
+Shabti includes an MCP (Model Context Protocol) server for integration with Claude Code, Cursor, and other MCP-compatible tools.
 
 ```bash
 # Start the MCP server (stdio transport)
 npx shabti-mcp
 ```
 
-### Claude Code configuration
+### Claude Code / Cursor configuration
 
 Generate the MCP settings JSON:
 
@@ -147,23 +185,57 @@ Or manually add to your MCP settings:
 }
 ```
 
-### Available tools
+### MCP Tools
 
-| Tool            | Description                            |
-| --------------- | -------------------------------------- |
-| `memory_store`  | Store a memory entry                   |
-| `memory_search` | Search memories by semantic similarity |
-| `memory_delete` | Delete a memory entry by ID            |
-| `memory_list`   | List recent memory entries             |
-| `memory_status` | Get engine status                      |
+| Tool            | Description                                                 |
+| --------------- | ----------------------------------------------------------- |
+| `memory_store`  | Store a memory entry with optional namespace, tags, and TTL |
+| `memory_search` | Search memories by semantic similarity                      |
+| `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                                           |
 
-### Available resources
+### MCP Resources
 
 | URI               | Description                  |
 | ----------------- | ---------------------------- |
 | `shabti://status` | Engine status and statistics |
 | `shabti://config` | Current configuration        |
 
+## A2A Protocol Server
+
+Shabti supports Google's [Agent-to-Agent (A2A) protocol](https://google.github.io/A2A/) v0.3.0 for inter-agent communication.
+
+```bash
+# Start the A2A server (default port 3000)
+shabti a2a
+
+# Start on a custom port
+shabti a2a --port 4000
+```
+
+### Agent Card
+
+Discoverable at `GET /.well-known/agent-card.json`.
+
+### Skills
+
+| Skill           | Description                          |
+| --------------- | ------------------------------------ |
+| `memory_store`  | Store a memory entry via A2A message |
+| `memory_search` | Semantic search via A2A message      |
+| `memory_status` | Engine status via A2A message        |
+
+### JSON-RPC Methods
+
+| Method         | Description                      |
+| -------------- | -------------------------------- |
+| `message/send` | Send a message to invoke a skill |
+| `tasks/get`    | Retrieve task status and results |
+| `tasks/cancel` | Cancel a running task            |
+
 ## Node.js API
 
 ```javascript
@@ -176,7 +248,11 @@ const engine = new ShabtiEngine({
 });
 
 // Store
-await engine.store("Rust is a systems programming language", {});
+await engine.store("Rust is a systems programming language", {
+  namespace: "tech",
+  tags: ["rust", "programming"],
+  ttlSeconds: 86400, // expires in 24 hours
+});
 
 // Search
 const results = await engine.executeQuery({
@@ -187,29 +263,52 @@ const results = await engine.executeQuery({
 
 for (const r of results) {
   console.log(`${r.score.toFixed(4)}  ${r.content}`);
-  if (r.explanation) {
-    console.log(
-      `  sim=${r.explanation.semanticSimilarity.toFixed(3)} ` +
-        `decay=${r.explanation.timeDecayFactor.toFixed(3)} ` +
-        `boost=${r.explanation.accessBoostFactor.toFixed(3)}`,
-    );
-  }
 }
 
+// Export
+const entries = engine.listEntries({ namespace: "tech", limit: 100 });
+
+// Garbage collect
+const removed = await engine.gc();
+
 await engine.shutdown();
 ```
 
+## Configuration
+
+### Environment Variables
+
+| Variable            | Description                                           | Default                 |
+| ------------------- | ----------------------------------------------------- | ----------------------- |
+| `SHABTI_QDRANT_URL` | Override Qdrant URL                                   | `http://localhost:6334` |
+| `SHABTI_LOG_LEVEL`  | Log level: `debug`, `info`, `warn`, `error`, `silent` | `info`                  |
+| `SHABTI_LOG_JSON`   | Set to `1` for JSON-formatted log output              | —                       |
+| `SHABTI_A2A_PORT`   | A2A server port (standalone mode)                     | `3000`                  |
+| `OPENAI_API_KEY`    | Required for chat/REPL mode                           | —                       |
+
+### Config File
+
+Stored at `~/.shabti/config.json`. Manage via `shabti config` commands.
+
 ## Architecture
 
 ```
 shabti (npm CLI + Node.js API)
-  └── shabti-napi (Rust ↔ Node.js FFI via NAPI-RS)
-       └── shabti-engine (orchestration layer)
-            ├── shabti-embedding (fastembed-rs, MultilingualE5Small 384-dim)
-            ├── shabti-index (Qdrant vector DB client)
-            ├── shabti-storage (append-only log, event store, snapshots)
-            ├── shabti-graph (k-NN memory link graph)
-            └── shabti-core (data models, scoring, dedup, query DSL)
+  ├── src/commands/      12 CLI commands (Commander.js)
+  ├── src/repl/          Interactive REPL with slash commands
+  ├── src/mcp/           MCP server (stdio, 7 tools, 2 resources)
+  ├── src/a2a/           A2A server (HTTP, JSON-RPC 2.0)
+  ├── src/core/          Engine factory, session, retry logic
+  ├── src/utils/         Style, validation, structured logger
+  └── native.cjs         NAPI-RS bridge
+       └── crates/
+            ├── shabti-engine     Orchestration, store/search/gc
+            ├── shabti-core       Data models, scoring, dedup, query DSL
+            ├── shabti-embedding  fastembed-rs (MultilingualE5Small, 384-dim)
+            ├── shabti-index      Qdrant vector DB client
+            ├── shabti-storage    Append-only log, event store, snapshots
+            ├── shabti-graph      k-NN memory link graph
+            └── shabti-napi       NAPI-RS bindings
 ```
 
 ## Benchmarks
@@ -227,10 +326,10 @@ See [BENCHMARKS.md](BENCHMARKS.md) for detailed results.
 ```bash
 npm install          # install JS dependencies
 cargo build          # build Rust workspace
-npm test             # run JS tests (vitest)
-cargo test           # run Rust tests
+npm test             # run JS tests (vitest) — 129 tests
+cargo test           # run Rust tests — 26 test modules
 npm run lint         # eslint
-cargo clippy         # Rust linter
+npm run ci           # lint + format check + audit + coverage
 ```
 
 ## License

package/package.json

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

package/src/a2a/server.js

@@ -325,7 +325,7 @@ export function startA2AServer(port = 3000) {
       let body;
       try {
         body = await readBody(req);
-      } catch {
+      } catch (_) {
         res.writeHead(400);
         return res.end();
       }
@@ -333,7 +333,7 @@ export function startA2AServer(port = 3000) {
       let rpc;
       try {
         rpc = JSON.parse(body);
-      } catch {
+      } catch (_) {
         res.writeHead(200, { "Content-Type": "application/json" });
         return res.end(
           JSON.stringify({
@@ -376,7 +376,7 @@ export function startA2AServer(port = 3000) {
     if (engine && engine.shutdown) {
       try {
         await engine.shutdown();
-      } catch {
+      } catch (_) {
         // best-effort
       }
     }

package/src/commands/delete.js

@@ -0,0 +1,20 @@
+import { createEngine } from "../core/engine.js";
+import { success, error } from "../utils/style.js";
+
+export function registerDelete(program) {
+  program
+    .command("delete")
+    .description("Delete a memory entry by ID")
+    .argument("<id>", "UUID of the memory entry to delete")
+    .action(async (id) => {
+      try {
+        const engine = createEngine();
+        await engine.delete(id);
+        success(`Deleted: ${id}`);
+        await engine.shutdown();
+      } catch (err) {
+        error(err.message);
+        process.exitCode = 1;
+      }
+    });
+}

package/src/commands/health.js

@@ -0,0 +1,104 @@
+import chalk from "chalk";
+import { createEngine, loadConfig } from "../core/engine.js";
+import { heading, success, warn } from "../utils/style.js";
+
+export function registerHealth(program) {
+  program
+    .command("health")
+    .description("Run health checks on the shabti engine")
+    .option("-j, --json", "Output as JSON")
+    .action(async (opts) => {
+      const checks = [];
+
+      // 1. Qdrant connectivity
+      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,
+        });
+      }
+
+      // 2. Engine initialization
+      let engine = null;
+      try {
+        engine = createEngine();
+        const status = engine.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,
+        });
+      }
+
+      // 3. Embedding model
+      if (engine) {
+        try {
+          const modelId = engine.modelId();
+          checks.push({
+            name: "embedding",
+            status: "ok",
+            message: modelId,
+          });
+        } catch (err) {
+          checks.push({
+            name: "embedding",
+            status: "error",
+            message: err.message,
+          });
+        }
+      }
+
+      const allOk = checks.every((c) => c.status === "ok");
+
+      if (opts.json) {
+        console.log(JSON.stringify({ healthy: allOk, checks }, null, 2));
+      } else {
+        heading("Health Check");
+        console.log();
+        for (const check of checks) {
+          const icon =
+            check.status === "ok"
+              ? chalk.green("✓")
+              : check.status === "degraded"
+                ? chalk.yellow("⚠")
+                : chalk.red("✗");
+          console.log(`  ${icon} ${chalk.cyan(check.name.padEnd(12))} ${check.message}`);
+        }
+        console.log();
+        if (allOk) {
+          success("All checks passed");
+        } else {
+          warn("Some checks failed");
+        }
+        console.log();
+      }
+
+      if (engine) {
+        try {
+          await engine.shutdown();
+        } catch (_) {
+          // best-effort
+        }
+      }
+
+      if (!allOk) process.exitCode = 1;
+    });
+}

package/src/commands/import.js

@@ -32,7 +32,7 @@ export function registerImport(program) {
         for (let i = 0; i < lines.length; i++) {
           try {
             entries.push(JSON.parse(lines[i]));
-          } catch {
+          } catch (_) {
             warn(`Skipping invalid JSON on line ${i + 1}`);
           }
         }

package/src/core/engine.js

@@ -26,7 +26,7 @@ export function loadConfig() {
   if (existsSync(CONFIG_PATH)) {
     try {
       config = { ...config, ...JSON.parse(readFileSync(CONFIG_PATH, "utf8")) };
-    } catch {
+    } catch (_) {
       // keep defaults
     }
   }

package/src/index.js

@@ -15,6 +15,8 @@ import { registerStatus } from "./commands/status.js";
 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 { registerHealth } from "./commands/health.js";
 
 const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 
@@ -84,6 +86,8 @@ function buildProgram() {
   registerExport(program);
   registerImport(program);
   registerStore(program);
+  registerDelete(program);
+  registerHealth(program);
 
   program
     .command("gc")

package/src/mcp/server.js

@@ -428,7 +428,7 @@ async function handleRequest(line) {
   let req;
   try {
     req = JSON.parse(line);
-  } catch {
+  } catch (_) {
     return respondError(null, -32700, "Parse error");
   }
 
@@ -465,7 +465,7 @@ async function shutdown() {
   if (engine && engine.shutdown) {
     try {
       await engine.shutdown();
-    } catch {
+    } catch (_) {
       // best-effort
     }
   }

package/src/repl/index.js

@@ -26,7 +26,7 @@ export async function launchRepl() {
     info(
       `Memory engine connected (${chalk.cyan("/remember")}, ${chalk.cyan("/recall")} available)`,
     );
-  } catch {
+  } catch (_) {
     warn("Memory engine not available. Chat-only mode (start Qdrant to enable memory).");
   }