shabti 1.14.0 → 2.1.0

package/BENCHMARKS.md

@@ -0,0 +1,32 @@
+# Shabti Benchmarks
+
+Measured on real Qdrant (localhost:6334) + fastembed-rs (MultilingualE5Small, 384 dimensions).
+
+## Environment
+
+- OS: Windows 11 Pro
+- Rust: release build (`--release`)
+- Qdrant: Docker container (v1.13+), gRPC port 6334
+- Embedding model: `MultilingualE5Small` (384-dim, local inference via ONNX Runtime)
+- Corpus: 30 diverse English sentences
+
+## Results
+
+| Metric                  | Target   | Measured               | Status |
+| ----------------------- | -------- | ---------------------- | ------ |
+| **Recall@10**           | >= 0.85  | **1.000** (11/11 hits) | PASS   |
+| **Insert latency p99**  | <= 100ms | **60.22ms**            | PASS   |
+| **Insert latency p50**  | —        | 53.64ms                | —      |
+| **Insert latency mean** | —        | 51.69ms                | —      |
+| **Search latency p99**  | <= 100ms | **58.71ms**            | PASS   |
+| **Search latency p50**  | —        | 51.43ms                | —      |
+| **Search latency mean** | —        | 52.19ms                | —      |
+
+## Notes
+
+- Latency is dominated by local embedding computation (~50ms per text via ONNX Runtime).
+  Qdrant round-trip adds ~1-10ms.
+- Recall@10 achieves perfect score on the benchmark corpus, indicating strong semantic
+  matching quality with the MultilingualE5Small model.
+- Score explanation breakdown confirms `time_decay = 1.0` (freshly inserted) and
+  `access_boost = 1.0` (no prior accesses), so composite score equals raw cosine similarity.

package/README.md

@@ -117,6 +117,45 @@ you> /help
 
 Requires `OPENAI_API_KEY` in `.env` for chat functionality. Memory commands (`/remember`, `/recall`) work with the local Qdrant engine.
 
+## MCP Server
+
+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
+
+Add to your MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "shabti-memory": {
+      "command": "npx",
+      "args": ["shabti-mcp"]
+    }
+  }
+}
+```
+
+### Available tools
+
+| Tool            | Description                            |
+| --------------- | -------------------------------------- |
+| `memory_store`  | Store a memory entry                   |
+| `memory_search` | Search memories by semantic similarity |
+| `memory_status` | Get engine status                      |
+
+### Available resources
+
+| URI               | Description                  |
+| ----------------- | ---------------------------- |
+| `shabti://status` | Engine status and statistics |
+| `shabti://config` | Current configuration        |
+
 ## Node.js API
 
 ```javascript

package/package.json

@@ -1,18 +1,20 @@
 {
   "name": "shabti",
-  "version": "1.14.0",
-  "description": "Demo CLI tool — showcasing npm-publishable CLI structure",
+  "version": "2.1.0",
+  "description": "Agent Memory OS — semantic memory for AI agents",
   "type": "module",
   "main": "native.cjs",
   "types": "native.d.ts",
   "bin": {
-    "shabti": "src/index.js"
+    "shabti": "src/index.js",
+    "shabti-mcp": "src/mcp/server.js"
   },
   "files": [
     "src/",
     "native.cjs",
     "native.d.ts",
-    "*.node"
+    "*.node",
+    "BENCHMARKS.md"
   ],
   "napi": {
     "binaryName": "shabti",
@@ -34,9 +36,15 @@
     "prepare": "husky"
   },
   "keywords": [
-    "cli",
-    "demo",
-    "tool"
+    "ai",
+    "agent",
+    "memory",
+    "semantic-search",
+    "vector-database",
+    "qdrant",
+    "embeddings",
+    "mcp",
+    "cli"
   ],
   "author": "Kaga Hinata",
   "engines": {

package/src/mcp/server.js

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+import { createInterface } from "readline";
+import { createEngine, loadConfig } from "../core/engine.js";
+
+const SERVER_INFO = {
+  name: "shabti-memory",
+  version: "2.0.0",
+};
+
+const TOOLS = [
+  {
+    name: "memory_store",
+    description: "Store a memory entry in shabti",
+    inputSchema: {
+      type: "object",
+      properties: {
+        content: { type: "string", description: "The text content to store" },
+        namespace: {
+          type: "string",
+          description: "Target namespace (default: 'default')",
+        },
+        tags: {
+          type: "array",
+          items: { type: "string" },
+          description: "Tags to associate with the memory",
+        },
+      },
+      required: ["content"],
+    },
+  },
+  {
+    name: "memory_search",
+    description: "Search stored memories by semantic similarity",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search query text" },
+        limit: {
+          type: "integer",
+          description: "Maximum number of results (default: 10)",
+        },
+        namespace: { type: "string", description: "Namespace to search within" },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "memory_status",
+    description: "Get the current status of the memory engine",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+];
+
+const RESOURCES = [
+  {
+    uri: "shabti://status",
+    name: "Engine status",
+    description: "Current shabti engine status and statistics",
+    mimeType: "application/json",
+  },
+  {
+    uri: "shabti://config",
+    name: "Engine configuration",
+    description: "Current engine configuration",
+    mimeType: "application/json",
+  },
+];
+
+let engine = null;
+
+function initEngine() {
+  if (engine) return engine;
+  try {
+    engine = createEngine();
+  } catch {
+    // engine stays null — tools will return errors
+  }
+  return engine;
+}
+
+function respond(id, result) {
+  const msg = JSON.stringify({ jsonrpc: "2.0", id, result });
+  process.stdout.write(msg + "\n");
+}
+
+function respondError(id, code, message) {
+  const msg = JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } });
+  process.stdout.write(msg + "\n");
+}
+
+function handleInitialize(id) {
+  respond(id, {
+    protocolVersion: "2024-11-05",
+    serverInfo: SERVER_INFO,
+    capabilities: {
+      tools: {},
+      resources: {},
+    },
+  });
+}
+
+function handleToolsList(id) {
+  respond(id, { tools: TOOLS });
+}
+
+function handleResourcesList(id) {
+  respond(id, { resources: RESOURCES });
+}
+
+async function handleToolsCall(id, params) {
+  const { name, arguments: args } = params;
+
+  const eng = initEngine();
+
+  if (name === "memory_status") {
+    if (!eng) {
+      return respond(id, {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { status: "unavailable", entry_count: 0, model_id: "unknown" },
+              null,
+              2,
+            ),
+          },
+        ],
+      });
+    }
+    const status = eng.status();
+    return respond(id, {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              status: "ok",
+              entry_count: status.entryCount,
+              tier: status.tier,
+              model_id: status.modelId,
+              qdrant_url: status.qdrantUrl,
+            },
+            null,
+            2,
+          ),
+        },
+      ],
+    });
+  }
+
+  if (name === "memory_store") {
+    if (!eng) {
+      return respondError(id, -32603, "Engine not available");
+    }
+    const content = args?.content;
+    if (!content) {
+      return respondError(id, -32602, "Missing required parameter: content");
+    }
+    try {
+      const opts = {};
+      if (args.namespace) opts.namespace = args.namespace;
+      if (args.tags) opts.tags = args.tags;
+      const result = await eng.store(content, opts);
+      return respond(id, {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { status: result.status, id: result.id || result.existingId },
+              null,
+              2,
+            ),
+          },
+        ],
+      });
+    } catch (err) {
+      return respondError(id, -32603, err.message);
+    }
+  }
+
+  if (name === "memory_search") {
+    if (!eng) {
+      return respondError(id, -32603, "Engine not available");
+    }
+    const query = args?.query;
+    if (!query) {
+      return respondError(id, -32602, "Missing required parameter: query");
+    }
+    try {
+      const limit = args.limit || 10;
+      const queryObj = { text: query, limit };
+      if (args.namespace) queryObj.namespace = args.namespace;
+      const results = await eng.executeQuery(queryObj);
+      const formatted = results.map((r) => ({
+        content: r.content,
+        score: r.score,
+        id: r.id,
+        namespace: r.namespace,
+      }));
+      return respond(id, {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ query, results: formatted }, null, 2),
+          },
+        ],
+      });
+    } catch (err) {
+      return respondError(id, -32603, err.message);
+    }
+  }
+
+  respondError(id, -32601, `Unknown tool: ${name}`);
+}
+
+function handleResourcesRead(id, params) {
+  const { uri } = params;
+  const eng = initEngine();
+
+  if (uri === "shabti://status") {
+    if (!eng) {
+      return respond(id, {
+        contents: [
+          {
+            uri,
+            mimeType: "application/json",
+            text: JSON.stringify({ status: "unavailable", entry_count: 0 }),
+          },
+        ],
+      });
+    }
+    const status = eng.status();
+    return respond(id, {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify({
+            status: "ok",
+            entry_count: status.entryCount,
+            tier: status.tier,
+            model_id: status.modelId,
+          }),
+        },
+      ],
+    });
+  }
+
+  if (uri === "shabti://config") {
+    const config = loadConfig();
+    return respond(id, {
+      contents: [
+        {
+          uri,
+          mimeType: "application/json",
+          text: JSON.stringify(config),
+        },
+      ],
+    });
+  }
+
+  respondError(id, -32602, `Unknown resource: ${uri}`);
+}
+
+async function handleRequest(line) {
+  let req;
+  try {
+    req = JSON.parse(line);
+  } catch {
+    return respondError(null, -32700, "Parse error");
+  }
+
+  const { id, method, params } = req;
+
+  switch (method) {
+    case "initialize":
+      return handleInitialize(id);
+    case "notifications/initialized":
+      return; // no response needed for notifications
+    case "tools/list":
+      return handleToolsList(id);
+    case "tools/call":
+      return handleToolsCall(id, params || {});
+    case "resources/list":
+      return handleResourcesList(id);
+    case "resources/read":
+      return handleResourcesRead(id, params || {});
+    default:
+      return respondError(id, -32601, "Method not found");
+  }
+}
+
+// stdio transport: read newline-delimited JSON from stdin
+const rl = createInterface({ input: process.stdin, terminal: false });
+rl.on("line", (line) => {
+  const trimmed = line.trim();
+  if (trimmed) handleRequest(trimmed);
+});
+rl.on("close", () => process.exit(0));