shabti 1.13.0 → 1.14.0

package/README.md

@@ -1,6 +1,8 @@
 # Shabti
 
-Demo CLI tool — showcasing npm-publishable CLI structure.
+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.
 
 ## Install
 
@@ -8,75 +10,181 @@ Demo CLI tool — showcasing npm-publishable CLI structure.
 npm install -g shabti
 ```
 
-## Usage
+### Prerequisites
+
+Shabti requires a running Qdrant instance for vector storage:
 
 ```bash
-shabti [command] [options]
+docker run -d --name qdrant -p 6333:6333 -p 6334:6334 qdrant/qdrant
 ```
 
-## Commands
+Verify the connection:
 
-| Command        | Description                       |
-| -------------- | --------------------------------- |
-| `hello <name>` | Greet someone                     |
-| `list`         | Show sample task list             |
-| `spin`         | Demo async operation with spinner |
+```bash
+shabti config setup --check
+```
 
-### hello
+## Quick Start
 
 ```bash
-shabti hello World
-# ✔ Hello, World!
+# Store a memory
+shabti store "Rust is a systems programming language"
+
+# Search memories
+shabti search "systems programming"
+
+# Search with score explanation
+shabti search "programming" --explain
 
-shabti hello World --shout
-# HELLO, WORLD!
+# Check engine status
+shabti status
 ```
 
-### list
+## Commands
 
-```bash
-# Table output
-shabti list
+| 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 |
 
-# JSON output
-shabti list --json
+### store
 
-# Filter by status
-shabti list --filter done
+```bash
+shabti store "Tokyo is the capital of Japan"
+shabti store "meeting at 3pm" --namespace work
+shabti store "buy groceries" --tags "todo,personal"
 ```
 
-### spin
+### search
 
 ```bash
-# Default 2000ms spinner
-shabti spin
+shabti search "capital of Japan"
+shabti search "meeting" --namespace work --limit 5
+shabti search "programming" --explain           # show score breakdown
+shabti search "AI" --follow-links 2             # expand via graph links
+shabti search "recent events" --min-score 0.5
+shabti search "query" --json                    # JSON output
+```
 
-# Custom duration
-shabti spin --duration 500
+### snapshot
+
+```bash
+shabti snapshot create
+shabti snapshot list
+shabti snapshot restore <id>
 ```
 
-## Development
+### config
 
 ```bash
-# Install dependencies
-npm install
+shabti config show
+shabti config show --json
+shabti config set qdrant_url http://localhost:6334
+shabti config setup           # show Qdrant setup instructions
+shabti config setup --check   # test Qdrant connection
+```
 
-# Run tests
-npm test
+## Interactive Mode (REPL)
 
-# Run linter
-npm run lint
+Run `shabti` with no arguments in a terminal to enter interactive mode:
 
-# Format code
-npm run format
+```
+$ shabti
+  shabti v2.0.0
+
+  [info] Memory engine connected (/remember, /recall available)
+  [info] Interactive mode — model: gpt-4o-mini
+
+you> /remember Tokyo is the capital of Japan
+  [ok] Remembered: a1b2c3d4-...
+
+you> /recall capital
+  0.9234  Tokyo is the capital of Japan
+
+you> /help
+  /help        Show this help message
+  /exit        Exit the REPL
+  /clear       Clear conversation history
+  /model       Show or switch the model
+  /history     Show conversation history
+  /remember    Store a memory
+  /recall      Search memories
+```
 
-# Run full CI pipeline
-npm run ci
+Requires `OPENAI_API_KEY` in `.env` for chat functionality. Memory commands (`/remember`, `/recall`) work with the local Qdrant engine.
+
+## Node.js API
+
+```javascript
+import { ShabtiEngine } from "shabti";
+
+const engine = new ShabtiEngine({
+  qdrantUrl: "http://localhost:6334",
+  collectionName: "my-app",
+  dataDir: "./data",
+});
+
+// Store
+await engine.store("Rust is a systems programming language", {});
+
+// Search
+const results = await engine.executeQuery({
+  text: "systems programming",
+  limit: 10,
+  withExplanation: true,
+});
+
+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)}`,
+    );
+  }
+}
+
+await engine.shutdown();
+```
+
+## 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)
 ```
 
-## Contributing
+## Benchmarks
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+See [BENCHMARKS.md](BENCHMARKS.md) for detailed results.
+
+| Metric     | Target   | Measured    |
+| ---------- | -------- | ----------- |
+| Recall@10  | >= 0.85  | **1.000**   |
+| Insert p99 | <= 100ms | **60.22ms** |
+| Search p99 | <= 100ms | **58.71ms** |
+
+## Development
+
+```bash
+npm install          # install JS dependencies
+cargo build          # build Rust workspace
+npm test             # run JS tests (vitest)
+cargo test           # run Rust tests
+npm run lint         # eslint
+cargo clippy         # Rust linter
+```
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shabti",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Demo CLI tool — showcasing npm-publishable CLI structure",
   "type": "module",
   "main": "native.cjs",

package/src/commands/config.js

@@ -48,7 +48,8 @@ export function registerConfig(program) {
   cmd
     .command("setup")
     .description("Show Qdrant setup instructions")
-    .action(() => {
+    .option("--check", "Test connection to Qdrant")
+    .action(async (opts) => {
       const config = loadConfig();
       heading("Qdrant Setup");
       console.log();
@@ -63,5 +64,21 @@ export function registerConfig(program) {
       console.log("  To change the URL:");
       console.log(`    shabti config set qdrant_url ${chalk.dim("<url>")}`);
       console.log();
+
+      if (opts.check) {
+        const restUrl = config.qdrant_url.replace(":6334", ":6333");
+        try {
+          const res = await fetch(`${restUrl}/healthz`);
+          if (res.ok) {
+            success("Qdrant is reachable and healthy.");
+          } else {
+            error(`Qdrant responded with status ${res.status}`);
+            process.exitCode = 1;
+          }
+        } catch (err) {
+          error(`Cannot reach Qdrant at ${restUrl}: ${err.message}`);
+          process.exitCode = 1;
+        }
+      }
     });
 }

package/src/repl/index.js

@@ -18,6 +18,18 @@ export async function launchRepl() {
 
   const model = "gpt-4o-mini";
 
+  // Try to connect memory engine (non-blocking)
+  let engine = null;
+  try {
+    const { createEngine } = await import("../core/engine.js");
+    engine = createEngine();
+    info(
+      `Memory engine connected (${chalk.cyan("/remember")}, ${chalk.cyan("/recall")} available)`,
+    );
+  } catch {
+    warn("Memory engine not available. Chat-only mode (start Qdrant to enable memory).");
+  }
+
   console.log();
   info(`Interactive mode — model: ${chalk.cyan(model)}`);
   console.log(chalk.dim("  Type a message, or /help for commands. Ctrl+C or /exit to quit.\n"));
@@ -26,7 +38,7 @@ export async function launchRepl() {
     apiKey,
     model,
     promptPrefix: "you> ",
-    onSlashCommand: handleSlashCommand,
+    onSlashCommand: (cmd, args, sess, rl) => handleSlashCommand(cmd, args, sess, rl, engine),
     legacyExitWord: false,
   });
 

package/src/repl/slashCommands.js

@@ -1,5 +1,5 @@
 import chalk from "chalk";
-import { success, info } from "../utils/style.js";
+import { success, info, warn, error } from "../utils/style.js";
 
 const COMMANDS = {
   "/help": "Show this help message",
@@ -7,6 +7,8 @@ const COMMANDS = {
   "/clear": "Clear conversation history",
   "/model": "Show or switch the model (e.g. /model gpt-4o)",
   "/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)",
 };
 
 /**
@@ -17,9 +19,10 @@ const COMMANDS = {
  * @param {string} args  - Arguments after the command
  * @param {import("../core/session.js").ChatSession} session
  * @param {import("readline").Interface} rl
- * @returns {boolean}
+ * @param {object|null} [engine] - ShabtiEngine instance (nullable)
+ * @returns {boolean|Promise<boolean>}
  */
-export function handleSlashCommand(cmd, args, session, rl) {
+export function handleSlashCommand(cmd, args, session, rl, engine = null) {
   switch (cmd) {
     case "/help":
       console.log();
@@ -66,7 +69,70 @@ export function handleSlashCommand(cmd, args, session, rl) {
       return true;
     }
 
+    case "/remember":
+      return handleRemember(args, engine);
+
+    case "/recall":
+      return handleRecall(args, engine);
+
     default:
       return false;
   }
 }
+
+async function handleRemember(text, engine) {
+  if (!engine) {
+    console.log();
+    warn("Memory engine not available. Start Qdrant to enable memory features.");
+    console.log();
+    return true;
+  }
+  if (!text) {
+    console.log();
+    info("Usage: /remember <text to store>");
+    console.log();
+    return true;
+  }
+  try {
+    const result = await engine.store(text, {});
+    if (result.status === "stored") {
+      success(`Remembered: ${result.id}`);
+    } else {
+      info(`Already remembered (duplicate)`);
+    }
+  } catch (err) {
+    error(`Failed to store: ${err.message}`);
+  }
+  console.log();
+  return true;
+}
+
+async function handleRecall(query, engine) {
+  if (!engine) {
+    console.log();
+    warn("Memory engine not available. Start Qdrant to enable memory features.");
+    console.log();
+    return true;
+  }
+  if (!query) {
+    console.log();
+    info("Usage: /recall <search query>");
+    console.log();
+    return true;
+  }
+  try {
+    const results = await engine.executeQuery({ text: query, limit: 5 });
+    console.log();
+    if (results.length === 0) {
+      console.log(chalk.dim("  No memories found."));
+    } else {
+      for (const r of results) {
+        console.log(`  ${chalk.yellow(r.score.toFixed(4))}  ${r.content}`);
+      }
+    }
+  } catch (err) {
+    error(`Failed to search: ${err.message}`);
+  }
+  console.log();
+  return true;
+}