wazap-mcp 0.18.2 → 0.18.3

package/README.md

@@ -8,7 +8,7 @@
 ```
 
 **WhatsApp for your AI agent.** An MCP server that puts your WhatsApp account —
-chats, messages, media, contacts, groups — behind 33 tools any MCP client can
+chats, messages, media, contacts, groups — behind 34 tools any MCP client can
 call. Pairing-code login, no browser, no phone-number reseller, ~20 MB of RAM.
 
 Built on [Baileys](https://github.com/WhiskeySockets/Baileys), which speaks the
@@ -284,6 +284,7 @@ them. `--dry-run` prints the plan and touches nothing.
 | `get_stories` | read | The stories (status updates) received in the last day, by author, with previews on request. They show nowhere else. |
 | `wait_for_messages` | read | Block up to 55 s until a message arrives, then return it with a cursor for the next call. `addressed_to_me` wakes only for direct messages, @-mentions and replies. |
 | `search_messages` | read | Text search across the locally held messages; `since`, `until` and `from` narrow it. |
+| `recall` | read | Semantic search over the whole indexed history: matches by meaning, so a paraphrase or another language still hits, and it finds messages too old for `search_messages`. Off until [turned on](#semantic-recall). |
 | `get_message` | read | One message in full, with its quoted message and reactions. |
 | `search_contacts` | read | Find contacts by name or number. |
 | `sync_contacts` | read | Fetch the phone's address book from WhatsApp again, when names are missing. |
@@ -423,6 +424,41 @@ transcribed once and not again after a restart. Audio *files* are left alone,
 since one can be an hour long; call `transcribe_audio(message_id)` for those.
 `WAZAP_TRANSCRIBE_AUTO=0` keeps the tool and stops the background work.
 
+## Semantic recall
+
+`search_messages` matches exact words; `recall` matches what was meant. A
+paraphrase or another language still hits, and it keeps finding messages too
+old for `search_messages` to see — those come back marked `index only`, which
+`get_message` and `download_media` cannot open. For an exact string — an id,
+a phone number, a URL — `search_messages` stays the right tool.
+
+Off by default, and fully local: a `llama-server` sidecar bound to loopback
+does the embedding, so nothing leaves the machine. It needs llama.cpp, the
+pinned model and persisted history (`WAZAP_PERSIST_HISTORY`, on by default):
+
+```bash
+brew install llama.cpp      # macOS; elsewhere build llama.cpp and put llama-server on PATH
+wazap embed download        # fetch the embedding model, ~318 MB sha256-verified
+wazap config recall local   # then restart the service
+```
+
+`wazap embed download` offers the `brew install` itself when `llama-server`
+is missing. `wazap status` runs the three checks — `recall`, `llama-server`,
+`embed model` — and `get_status` reports the index as `off`, `indexing`,
+`ready` or `degraded`.
+
+`chat_id`, `since`, `until` and `from` narrow a recall exactly like
+`search_messages`. Hits rank by similarity scaled by recency, and anything
+under the similarity floor is dropped rather than listed. The index lives at
+`accounts/<id>/recall/` (dir `0700`, files `0600`), holds only what persisted
+history already stores, and tombstones a message out when it is deleted or
+revoked.
+
+The knobs — `WAZAP_RECALL`, `WAZAP_EMBED_MODEL` (`embeddinggemma-300m` by
+default, `e5-base-multilingual` for an older llama.cpp), `WAZAP_EMBED_BIN`,
+`WAZAP_RECALL_MAX`, `WAZAP_RECALL_MIN_SIMILARITY` — are documented in
+`.env.example`.
+
 ## Skills
 
 wazap ships five [Agent Skills](https://agentskills.io) that teach an agent the workflows behind the tools, not just the tools:
@@ -512,11 +548,12 @@ accounts moves into `accounts/default/` the first time a wazap command runs.
     auth/           WhatsApp credentials — treat this like a password
     media/          downloads from download_media
     history/        per-chat message history, so a restart is not amnesia
+    recall/         the semantic index, when recall is on
     previews/       one small JPEG per photo or video already previewed
     notes.json      notes on contacts and "handled" marks; never sent anywhere
     store.json      chat-list snapshot
     qr.png          last QR, when login showed one
-  models/           whisper.cpp models, when transcription runs locally
+  models/           whisper.cpp and embedding models, when transcription or recall run locally
   server.lock       pid of the running server
   daemon.json       loopback endpoint a second wazap bridges to
   oauth.json        registered agents and hashed OAuth grants, when OAuth is on

package/dist/doctor.js

@@ -313,8 +313,11 @@ async function checkRecall(config) {
     const spec = EMBED_MODELS[settings.model];
     const size = fileSize(embedModelPath(settings.modelsDir, spec));
     const readiness = await embedReady(settings, spec);
+    // An env-set floor is the user's own calibration; only the model's
+    // unmeasured default gets flagged.
+    const uncalibrated = !spec.floorCalibrated && process.env.WAZAP_RECALL_MIN_SIMILARITY === undefined ? ", uncalibrated floor" : "";
     return [
-        { name: "recall", state: "ok", detail: `local (${settings.model})` },
+        { name: "recall", state: "ok", detail: `local (${settings.model}${uncalibrated})` },
         readiness.ok
             ? { name: "llama-server", state: "ok", detail: settings.embedUrl ?? "found" }
             : { name: "llama-server", state: "fail", detail: readiness.detail, fix: readiness.fix },

package/dist/recall/engine.js

@@ -3,6 +3,11 @@
  * loopback, restarted when it dies, killed when wazap stops. The queue is the
  * only caller, so a slow restart stalls indexing — never ingestion.
  *
+ * The /embedding API is stateless, so every account in the process shares one
+ * server: the registry below spawns on the first acquire and kills on the
+ * last release, keyed by the only things that make a sidecar distinct — the
+ * resolved binary and the model file.
+ *
  * WAZAP_EMBED_URL points at an already-running compatible server instead of
  * spawning one; that seam exists for the test stub, not as a supported option.
  */
@@ -204,6 +209,66 @@ class UrlBackend {
         return Promise.resolve();
     }
 }
+/** The seam the tests replace; production always spawns a real llama-server. */
+export const sidecarFactory = {
+    open: (bin, model, onLog) => new LlamaSidecar(bin, model, onLog),
+};
+const sharedSidecars = new Map();
+/**
+ * One consumer's claim on a shared sidecar. Embedding calls reach the child
+ * directly; stop() only gives this claim back — the last one out is the one
+ * that kills the server. The child's restart lines keep arriving through the
+ * first consumer's onLog, which in production is the same `log` for everyone.
+ */
+class SharedSidecar {
+    key;
+    entry;
+    released = false;
+    constructor(key, entry) {
+        this.key = key;
+        this.entry = entry;
+    }
+    /** First claim on a key spawns; later ones join the start already under way. */
+    static acquire(bin, model, onLog) {
+        const key = `${bin}\n${model}`;
+        let entry = sharedSidecars.get(key);
+        if (entry === undefined) {
+            const sidecar = sidecarFactory.open(bin, model, onLog);
+            entry = { refs: 0, sidecar, started: sidecar.start() };
+            sharedSidecars.set(key, entry);
+            // A failed start frees the slot, so the next acquire spawns fresh
+            // instead of joining a rejection. Consumers still holding refs release
+            // into a sidecar that never ran — stop() on it is a safe no-op.
+            entry.started.catch(() => {
+                if (sharedSidecars.get(key) === entry)
+                    sharedSidecars.delete(key);
+            });
+        }
+        entry.refs++;
+        return new SharedSidecar(key, entry);
+    }
+    /** The shared start; the engine releases its claim when this rejects. */
+    started() {
+        return this.entry.started;
+    }
+    get base() {
+        return this.entry.sidecar.base;
+    }
+    waitReady() {
+        return this.entry.sidecar.waitReady();
+    }
+    async stop() {
+        if (this.released)
+            return;
+        this.released = true;
+        this.entry.refs--;
+        if (this.entry.refs > 0)
+            return;
+        if (sharedSidecars.get(this.key) === this.entry)
+            sharedSidecars.delete(this.key);
+        await this.entry.sidecar.stop();
+    }
+}
 /**
  * The queue's handle on embeddings. `embed` waits out a restart for up to
  * START_TIMEOUT_MS, then fails the batch — the queue retries, so a dying
@@ -225,9 +290,17 @@ export class EmbedEngine {
         if (bin === null) {
             throw new WazapError("RECALL_UNAVAILABLE", "llama-server not found; semantic recall needs llama.cpp", llamaInstallFix());
         }
-        const sidecar = new LlamaSidecar(bin, embedModelPath(settings.modelsDir, spec), onLog);
-        await sidecar.start();
-        return new EmbedEngine(sidecar, spec);
+        // Accounts on the same binary and model share one server: acquire bumps
+        // the registry's refcount, this engine's stop() hands just this claim back.
+        const target = SharedSidecar.acquire(bin, embedModelPath(settings.modelsDir, spec), onLog);
+        try {
+            await target.started();
+        }
+        catch (err) {
+            await target.stop();
+            throw err;
+        }
+        return new EmbedEngine(target, spec);
     }
     /**
      * `kind` picks the model's task prefix: the index holds "document" texts,

package/dist/recall/models.js

@@ -24,6 +24,10 @@ export const EMBED_MODELS = {
         url: "https://huggingface.co/ggml-org/embeddinggemma-300M-GGUF/resolve/main/embeddinggemma-300M-Q8_0.gguf",
         // EmbeddingGemma's own retrieval task, from its model card.
         prompts: { query: "task: search result | query: ", document: "title: none | text: " },
+        // Measured on a real index under those prompts: noise tops out ~0.31,
+        // real paraphrases start ~0.35.
+        defaultMinSimilarity: 0.35,
+        floorCalibrated: true,
     },
     "e5-base-multilingual": {
         alias: "e5-base-multilingual",
@@ -34,6 +38,15 @@ export const EMBED_MODELS = {
         url: "https://huggingface.co/dinab/multilingual-e5-base-Q8_0-GGUF/resolve/main/multilingual-e5-base-q8_0.gguf",
         // e5's documented asymmetric prefixes.
         prompts: { query: "query: ", document: "passage: " },
+        // UNCALIBRATED — a placeholder, not a measurement. e5's contrastive
+        // training compresses prompted cosines into a much higher band than
+        // gemma's: unrelated pairs commonly read ~0.6-0.75 where real matches
+        // start ~0.8, so gemma's 0.35 would pass noise as answers. 0.7 errs
+        // high on purpose: a dropped real hit answers "nothing found", a false
+        // hit is a wrong memory an agent will repeat. Re-measure on a real
+        // index before flipping floorCalibrated.
+        defaultMinSimilarity: 0.7,
+        floorCalibrated: false,
     },
 };
 export function embedModelSpec(name) {

package/dist/recall/settings.js

@@ -6,18 +6,12 @@
 import { join } from "node:path";
 import { WazapError } from "../errors.js";
 import { stripPasted } from "../transcribe/index.js";
+import { EMBED_MODELS } from "./models.js";
 const OFF = new Set(["", "off", "0", "no", "none", "false"]);
 const ON = new Set(["local", "on", "1", "yes", "true"]);
 const MODEL_ALIASES = ["embeddinggemma-300m", "e5-base-multilingual"];
 const DEFAULT_MAX_ROWS = 50_000;
 const MIN_MAX_ROWS = 100;
-/**
- * Cosine floor for embeddinggemma-300m under its task prompts, measured on a
- * real index: noise tops out ~0.31, real paraphrases start ~0.35. The prompts
- * widened the noise/signal gap enough for the floor to mean something.
- * e5-base needs its own calibration.
- */
-const DEFAULT_MIN_SIMILARITY = 0.35;
 function parseEnabled(raw) {
     const value = stripPasted(raw ?? "").toLowerCase();
     if (OFF.has(value))
@@ -43,10 +37,14 @@ function parseMaxRows(raw) {
         return n;
     throw new WazapError("INVALID_ID", `WAZAP_RECALL_MAX must be a number >= ${MIN_MAX_ROWS}, got "${value}".`, "Fix WAZAP_RECALL_MAX or remove it");
 }
-function parseMinSimilarity(raw) {
+/**
+ * The env wins over the model's own floor — a cosine that means "real match"
+ * is the model's to price, the override is the user's.
+ */
+function parseMinSimilarity(raw, fallback) {
     const value = stripPasted(raw ?? "");
     if (value === "")
-        return DEFAULT_MIN_SIMILARITY;
+        return fallback;
     const n = Number(value);
     if (Number.isFinite(n) && n >= 0 && n <= 1)
         return n;
@@ -68,13 +66,14 @@ function parseUrl(raw) {
 }
 export function readRecallSettings(env, dataDir) {
     const embedBin = stripPasted(env.WAZAP_EMBED_BIN ?? "");
+    const model = parseModel(env.WAZAP_EMBED_MODEL);
     return {
         enabled: parseEnabled(env.WAZAP_RECALL),
-        model: parseModel(env.WAZAP_EMBED_MODEL),
+        model,
         embedBin: embedBin === "" ? null : embedBin,
         embedUrl: parseUrl(env.WAZAP_EMBED_URL),
         modelsDir: join(dataDir, "models"),
         maxRows: parseMaxRows(env.WAZAP_RECALL_MAX),
-        minSimilarity: parseMinSimilarity(env.WAZAP_RECALL_MIN_SIMILARITY),
+        minSimilarity: parseMinSimilarity(env.WAZAP_RECALL_MIN_SIMILARITY, EMBED_MODELS[model].defaultMinSimilarity),
     };
 }

package/dist/whatsapp.js

@@ -1248,8 +1248,9 @@ export class WhatsAppService {
         }
     }
     /**
-     * The sidecar, started on the first embedding request. A failed start is not
-     * cached — the next queued batch tries again.
+     * The sidecar, started on the first embedding request and shared with every
+     * other account in the process on the same binary and model. A failed start
+     * is not cached — the next queued batch tries again.
      */
     recallEngine() {
         if (this.stopped)
@@ -1390,9 +1391,10 @@ export class WhatsAppService {
         return { state: pending > 0 ? "indexing" : "ready", indexed, pending };
     }
     /**
-     * Queue first, then the sidecar — stopping it unblocks an embedding call in
-     * flight — then the store, whose own write queue drains before it closes.
-     * An engine still coming up is stopped whenever its start resolves.
+     * Queue first, then the engine — releasing its claim on the shared sidecar
+     * unblocks an embedding call in flight — then the store, whose own write
+     * queue drains before it closes. An engine still coming up is released
+     * whenever its start resolves.
      */
     async stopRecall() {
         const queueStop = this.recallQueue?.stop() ?? Promise.resolve();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wazap-mcp",
-  "version": "0.18.2",
+  "version": "0.18.3",
   "mcpName": "io.github.razvangirgiz/wazap",
   "description": "WhatsApp for your AI agent. MCP server over Baileys: pairing-code login, several accounts, 33 tools, stdio or HTTP.",
   "license": "MIT",