@teammates/recall 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,8 @@
 # @teammates/recall
 
-Local semantic memory search for teammates. Indexes `MEMORIES.md` and daily logs (`memory/*.md`) using [Vectra](https://github.com/Stevenic/vectra) for vector search and [transformers.js](https://huggingface.co/docs/transformers.js) for embeddings.
+> Part of the [teammates](https://github.com/Stevenic/teammates) monorepo.
+
+Local semantic memory search for teammates. Indexes `WISDOM.md` and memory files (`memory/*.md` — daily logs and typed memories) using [Vectra](https://github.com/Stevenic/vectra) for vector search and [transformers.js](https://huggingface.co/docs/transformers.js) for embeddings.
 
 **Zero cloud dependencies.** Everything runs locally — embeddings are generated on-device, indexes are stored as local files.
 
@@ -88,11 +90,21 @@ teammates-recall status --dir ./.teammates
 ## How It Works
 
 1. **Discovers** teammate directories (any folder under `.teammates/` with a `SOUL.md`)
-2. **Collects** memory files: `MEMORIES.md` + `memory/*.md`
+2. **Collects** memory files: `WISDOM.md` + `memory/*.md` (daily logs and typed memories)
 3. **Chunks and embeds** text using transformers.js (`Xenova/all-MiniLM-L6-v2`, 384-dim vectors)
-4. **Stores** the index at `.teammates/.index/<teammate>/` (gitignored)
+4. **Stores** the index at `.teammates/<teammate>/.index/` (gitignored)
 5. **Searches** using Vectra's semantic similarity matching
 
+## Auto-Sync
+
+Every `search` call automatically detects new or changed memory files and indexes them before returning results. This is on by default — no manual `sync` or `index` step is needed.
+
+**How it works:** The indexer compares file modification times against stored metadata. Only files that are new or changed since the last sync get re-indexed, so the overhead is minimal for most queries.
+
+**Skip it when you need speed:** Pass `--no-sync` (CLI) or `skipSync: true` (library) to skip the check entirely. Useful for hot loops or large indexes where you control sync timing separately.
+
+**Why this matters for agents:** Agents write memory files as plain markdown — they shouldn't need to know about index state or remember to run a sync command. Auto-sync closes the gap between "file written" and "file searchable" so agents can write-then-search in a single workflow without extra steps.
+
 ## Use From Any Agent
 
 Any AI coding tool that can run shell commands can use recall:
@@ -107,7 +119,7 @@ The `--json` flag returns structured results that agents can parse:
 [
   {
     "teammate": "atlas",
-    "uri": "atlas/MEMORIES.md",
+    "uri": "atlas/WISDOM.md",
     "text": "### 2026-01-15: JWT Auth Pattern\n...",
     "score": 0.847
   }
@@ -134,6 +146,8 @@ const results = await search("database migration", {
   teammatesDir: "./.teammates",
   teammate: "atlas",
   maxResults: 5,
+  maxChunks: 3,    // max chunks per document (default: 3)
+  maxTokens: 500,  // max tokens per section (default: 500)
 });
 
 // Search without auto-sync
@@ -153,4 +167,4 @@ Default: `Xenova/all-MiniLM-L6-v2` (~23 MB, 384 dimensions)
 
 ## Storage
 
-Indexes live at `.teammates/.index/` and are gitignored. They're derived from the markdown source files and can be rebuilt at any time with `teammates-recall index`.
+Indexes live at `.teammates/<teammate>/.index/` and are gitignored. They're derived from the markdown source files and can be rebuilt at any time with `teammates-recall index`.

package/dist/cli.js

@@ -1,26 +1,32 @@
 #!/usr/bin/env node
-import * as path from "node:path";
+import { watch as fsWatch } from "node:fs";
 import * as fs from "node:fs/promises";
+import * as path from "node:path";
 import { Indexer } from "./indexer.js";
 import { search } from "./search.js";
-const HELP = `
-teammates-recall — Semantic memory search for teammates
-
-Usage:
-  teammates-recall index   [options]              Full rebuild of all indexes
-  teammates-recall sync    [options]              Sync new/changed files into indexes
-  teammates-recall add     <file> [options]       Add a single file to a teammate's index
-  teammates-recall search  <query> [options]      Search teammate memories (auto-syncs)
-  teammates-recall status  [options]              Show index status
-
-Options:
-  --dir <path>         Path to .teammates directory (default: ./.teammates)
-  --teammate <name>    Limit to a specific teammate
-  --results <n>        Max results (default: 5)
-  --model <name>       Embedding model (default: Xenova/all-MiniLM-L6-v2)
-  --no-sync            Skip auto-sync before search
-  --json               Output as JSON
-  --help               Show this help
+const HELP = `
+teammates-recall — Semantic memory search for teammates
+
+Usage:
+  teammates-recall index   [options]              Full rebuild of all indexes
+  teammates-recall sync    [options]              Sync new/changed files into indexes
+  teammates-recall add     <file> [options]       Add a single file to a teammate's index
+  teammates-recall search  <query> [options]      Search teammate memories (auto-syncs)
+  teammates-recall status  [options]              Show index status
+  teammates-recall watch   [options]              Watch for changes and auto-sync
+
+Options:
+  --dir <path>              Path to .teammates directory (default: ./.teammates)
+  --teammate <name>         Limit to a specific teammate
+  --results <n>             Max results (default: 5)
+  --max-chunks <n>          Max chunks per document (default: 3)
+  --max-tokens <n>          Max tokens per section (default: 500)
+  --recency-depth <n>       Number of recent weekly summaries to include (default: 2)
+  --typed-memory-boost <n>  Relevance boost for typed memories (default: 1.2)
+  --model <name>            Embedding model (default: Xenova/all-MiniLM-L6-v2)
+  --no-sync                 Skip auto-sync before search
+  --json                    Output as JSON
+  --help                    Show this help
 `.trim();
 function parseArgs(argv) {
     const args = {
@@ -34,17 +40,24 @@ function parseArgs(argv) {
     };
     let i = 0;
     // Skip node and script path
-    while (i < argv.length && (argv[i].includes("node") || argv[i].includes("teammates-recall") || argv[i].endsWith(".js"))) {
+    while (i < argv.length &&
+        (argv[i].includes("node") ||
+            argv[i].includes("teammates-recall") ||
+            argv[i].endsWith(".js"))) {
         i++;
     }
     if (i < argv.length && !argv[i].startsWith("-")) {
         args.command = argv[i++];
     }
     // For search, next non-flag arg is the query; for add, it's the file path
-    if (args.command === "search" && i < argv.length && !argv[i].startsWith("-")) {
+    if (args.command === "search" &&
+        i < argv.length &&
+        !argv[i].startsWith("-")) {
         args.query = argv[i++];
     }
-    else if (args.command === "add" && i < argv.length && !argv[i].startsWith("-")) {
+    else if (args.command === "add" &&
+        i < argv.length &&
+        !argv[i].startsWith("-")) {
         args.file = argv[i++];
     }
     while (i < argv.length) {
@@ -62,6 +75,18 @@ function parseArgs(argv) {
             case "--model":
                 args.model = argv[i++];
                 break;
+            case "--max-chunks":
+                args.maxChunks = parseInt(argv[i++], 10);
+                break;
+            case "--max-tokens":
+                args.maxTokens = parseInt(argv[i++], 10);
+                break;
+            case "--recency-depth":
+                args.recencyDepth = parseInt(argv[i++], 10);
+                break;
+            case "--typed-memory-boost":
+                args.typedMemoryBoost = parseFloat(argv[i++]);
+                break;
             case "--no-sync":
                 args.sync = false;
                 break;
@@ -157,7 +182,11 @@ async function cmdAdd(args) {
     const indexer = new Indexer({ teammatesDir, model: args.model });
     await indexer.upsertFile(args.teammate, args.file);
     if (args.json) {
-        console.log(JSON.stringify({ teammate: args.teammate, file: args.file, status: "ok" }));
+        console.log(JSON.stringify({
+            teammate: args.teammate,
+            file: args.file,
+            status: "ok",
+        }));
     }
     else {
         console.log(`Added ${args.file} to ${args.teammate}'s index`);
@@ -174,6 +203,10 @@ async function cmdSearch(args) {
         teammatesDir,
         teammate: args.teammate,
         maxResults: args.results,
+        maxChunks: args.maxChunks,
+        maxTokens: args.maxTokens,
+        recencyDepth: args.recencyDepth,
+        typedMemoryBoost: args.typedMemoryBoost,
         model: args.model,
         skipSync: !args.sync,
     });
@@ -199,7 +232,7 @@ async function cmdStatus(args) {
     const status = {};
     for (const teammate of teammates) {
         const { files } = await indexer.collectFiles(teammate);
-        const indexPath = path.join(indexer.indexRoot, teammate);
+        const indexPath = indexer.indexPath(teammate);
         let indexed = false;
         try {
             await fs.access(indexPath);
@@ -220,6 +253,81 @@ async function cmdStatus(args) {
         }
     }
 }
+async function cmdWatch(args) {
+    const teammatesDir = await resolveTeammatesDir(args.dir);
+    const indexer = new Indexer({ teammatesDir, model: args.model });
+    // Initial sync
+    console.error("Initial sync...");
+    const results = await indexer.syncAll();
+    for (const [teammate, count] of results) {
+        console.error(`  ${teammate}: ${count} files`);
+    }
+    console.error("Watching for changes...");
+    if (args.json) {
+        console.log(JSON.stringify({ status: "watching", dir: teammatesDir }));
+    }
+    // Debounce: collect changes, sync after 2s of quiet
+    let syncTimer = null;
+    const pendingTeammates = new Set();
+    const scheduleSync = (teammate) => {
+        pendingTeammates.add(teammate);
+        if (syncTimer)
+            clearTimeout(syncTimer);
+        syncTimer = setTimeout(async () => {
+            for (const t of pendingTeammates) {
+                try {
+                    const count = await indexer.syncTeammate(t);
+                    if (args.json) {
+                        console.log(JSON.stringify({ event: "sync", teammate: t, files: count }));
+                    }
+                    else {
+                        console.error(`  synced ${t}: ${count} files`);
+                    }
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    console.error(`  error syncing ${t}: ${msg}`);
+                }
+            }
+            pendingTeammates.clear();
+        }, 2000);
+    };
+    // Watch each teammate's directory for changes
+    const watchers = [];
+    const teammates = await indexer.discoverTeammates();
+    for (const teammate of teammates) {
+        const teammateDir = path.join(teammatesDir, teammate);
+        try {
+            const watcher = fsWatch(teammateDir, { recursive: true }, (_eventType, filename) => {
+                if (!filename)
+                    return;
+                // Only care about .md files, skip .index/
+                if (!filename.endsWith(".md") || filename.includes(".index"))
+                    return;
+                scheduleSync(teammate);
+            });
+            watchers.push(watcher);
+        }
+        catch {
+            console.error(`  warning: could not watch ${teammate}/`);
+        }
+    }
+    // Keep alive until killed
+    const shutdown = () => {
+        if (syncTimer)
+            clearTimeout(syncTimer);
+        for (const w of watchers)
+            w.close();
+        if (args.json) {
+            console.log(JSON.stringify({ status: "stopped" }));
+        }
+        process.exit(0);
+    };
+    process.on("SIGTERM", shutdown);
+    process.on("SIGINT", shutdown);
+    // Block forever
+    await new Promise(() => { });
+}
 async function main() {
     const args = parseArgs(process.argv);
     switch (args.command) {
@@ -238,6 +346,9 @@ async function main() {
         case "status":
             await cmdStatus(args);
             break;
+        case "watch":
+            await cmdWatch(args);
+            break;
         default:
             console.log(HELP);
             process.exit(args.command ? 1 : 0);

package/dist/cli.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.test.js

@@ -0,0 +1,270 @@
+import { describe, expect, it } from "vitest";
+function parseArgs(argv) {
+    const args = {
+        command: "",
+        query: "",
+        file: "",
+        dir: "./.teammates",
+        results: 5,
+        json: false,
+        sync: true,
+    };
+    let i = 0;
+    while (i < argv.length &&
+        (argv[i].includes("node") ||
+            argv[i].includes("teammates-recall") ||
+            argv[i].endsWith(".js"))) {
+        i++;
+    }
+    if (i < argv.length && !argv[i].startsWith("-")) {
+        args.command = argv[i++];
+    }
+    if (args.command === "search" &&
+        i < argv.length &&
+        !argv[i].startsWith("-")) {
+        args.query = argv[i++];
+    }
+    else if (args.command === "add" &&
+        i < argv.length &&
+        !argv[i].startsWith("-")) {
+        args.file = argv[i++];
+    }
+    while (i < argv.length) {
+        const arg = argv[i++];
+        switch (arg) {
+            case "--dir":
+                args.dir = argv[i++];
+                break;
+            case "--teammate":
+                args.teammate = argv[i++];
+                break;
+            case "--results":
+                args.results = parseInt(argv[i++], 10);
+                break;
+            case "--model":
+                args.model = argv[i++];
+                break;
+            case "--max-chunks":
+                args.maxChunks = parseInt(argv[i++], 10);
+                break;
+            case "--max-tokens":
+                args.maxTokens = parseInt(argv[i++], 10);
+                break;
+            case "--recency-depth":
+                args.recencyDepth = parseInt(argv[i++], 10);
+                break;
+            case "--typed-memory-boost":
+                args.typedMemoryBoost = parseFloat(argv[i++]);
+                break;
+            case "--no-sync":
+                args.sync = false;
+                break;
+            case "--json":
+                args.json = true;
+                break;
+        }
+    }
+    return args;
+}
+describe("parseArgs", () => {
+    it("parses search command with query", () => {
+        const args = parseArgs(["node", "cli.js", "search", "hello world"]);
+        expect(args.command).toBe("search");
+        expect(args.query).toBe("hello world");
+    });
+    it("parses add command with file path", () => {
+        const args = parseArgs([
+            "node",
+            "cli.js",
+            "add",
+            "memory/foo.md",
+            "--teammate",
+            "beacon",
+        ]);
+        expect(args.command).toBe("add");
+        expect(args.file).toBe("memory/foo.md");
+        expect(args.teammate).toBe("beacon");
+    });
+    it("parses index command", () => {
+        const args = parseArgs(["node", "cli.js", "index"]);
+        expect(args.command).toBe("index");
+    });
+    it("parses sync command", () => {
+        const args = parseArgs(["node", "cli.js", "sync"]);
+        expect(args.command).toBe("sync");
+    });
+    it("parses status command", () => {
+        const args = parseArgs(["node", "cli.js", "status"]);
+        expect(args.command).toBe("status");
+    });
+    it("parses watch command", () => {
+        const args = parseArgs(["node", "cli.js", "watch"]);
+        expect(args.command).toBe("watch");
+    });
+    it("defaults dir to ./.teammates", () => {
+        const args = parseArgs(["node", "cli.js", "index"]);
+        expect(args.dir).toBe("./.teammates");
+    });
+    it("parses --dir flag", () => {
+        const args = parseArgs([
+            "node",
+            "cli.js",
+            "index",
+            "--dir",
+            "/path/to/.teammates",
+        ]);
+        expect(args.dir).toBe("/path/to/.teammates");
+    });
+    it("parses --teammate flag", () => {
+        const args = parseArgs([
+            "node",
+            "cli.js",
+            "search",
+            "query",
+            "--teammate",
+            "scribe",
+        ]);
+        expect(args.teammate).toBe("scribe");
+    });
+    it("parses --results flag", () => {
+        const args = parseArgs([
+            "node",
+            "cli.js",
+            "search",
+            "query",
+            "--results",
+            "10",
+        ]);
+        expect(args.results).toBe(10);
+    });
+    it("parses --model flag", () => {
+        const args = parseArgs([
+            "node",
+            "cli.js",
+            "index",
+            "--model",
+            "custom/model",
+        ]);
+        expect(args.model).toBe("custom/model");
+    });
+    it("parses --json flag", () => {
+        const args = parseArgs(["node", "cli.js", "status", "--json"]);
+        expect(args.json).toBe(true);
+    });
+    it("defaults json to false", () => {
+        const args = parseArgs(["node", "cli.js", "status"]);
+        expect(args.json).toBe(false);
+    });
+    it("parses --no-sync flag", () => {
+        const args = parseArgs(["node", "cli.js", "search", "query", "--no-sync"]);
+        expect(args.sync).toBe(false);
+    });
+    it("defaults sync to true", () => {
+        const args = parseArgs(["node", "cli.js", "search", "query"]);
+        expect(args.sync).toBe(true);
+    });
+    it("defaults results to 5", () => {
+        const args = parseArgs(["node", "cli.js", "search", "query"]);
+        expect(args.results).toBe(5);
+    });
+    it("returns empty command for no args", () => {
+        const args = parseArgs(["node", "cli.js"]);
+        expect(args.command).toBe("");
+    });
+    it("handles multiple flags together", () => {
+        const args = parseArgs([
+            "node",
+            "cli.js",
+            "search",
+            "my query",
+            "--dir",
+            "/tmp/.teammates",
+            "--teammate",
+            "beacon",
+            "--results",
+            "3",
+            "--json",
+            "--no-sync",
+        ]);
+        expect(args.command).toBe("search");
+        expect(args.query).toBe("my query");
+        expect(args.dir).toBe("/tmp/.teammates");
+        expect(args.teammate).toBe("beacon");
+        expect(args.results).toBe(3);
+        expect(args.json).toBe(true);
+        expect(args.sync).toBe(false);
+    });
+    it("parses --max-chunks flag", () => {
+        const args = parseArgs([
+            "node",
+            "cli.js",
+            "search",
+            "query",
+            "--max-chunks",
+            "7",
+        ]);
+        expect(args.maxChunks).toBe(7);
+    });
+    it("parses --max-tokens flag", () => {
+        const args = parseArgs([
+            "node",
+            "cli.js",
+            "search",
+            "query",
+            "--max-tokens",
+            "1000",
+        ]);
+        expect(args.maxTokens).toBe(1000);
+    });
+    it("parses --recency-depth flag", () => {
+        const args = parseArgs([
+            "node",
+            "cli.js",
+            "search",
+            "query",
+            "--recency-depth",
+            "4",
+        ]);
+        expect(args.recencyDepth).toBe(4);
+    });
+    it("parses --typed-memory-boost flag", () => {
+        const args = parseArgs([
+            "node",
+            "cli.js",
+            "search",
+            "query",
+            "--typed-memory-boost",
+            "1.5",
+        ]);
+        expect(args.typedMemoryBoost).toBe(1.5);
+    });
+    it("handles multiple new search flags together", () => {
+        const args = parseArgs([
+            "node",
+            "cli.js",
+            "search",
+            "my query",
+            "--max-chunks",
+            "5",
+            "--max-tokens",
+            "800",
+            "--recency-depth",
+            "3",
+            "--typed-memory-boost",
+            "2.0",
+        ]);
+        expect(args.command).toBe("search");
+        expect(args.query).toBe("my query");
+        expect(args.maxChunks).toBe(5);
+        expect(args.maxTokens).toBe(800);
+        expect(args.recencyDepth).toBe(3);
+        expect(args.typedMemoryBoost).toBe(2.0);
+    });
+    it("leaves new flags undefined when not provided", () => {
+        const args = parseArgs(["node", "cli.js", "search", "query"]);
+        expect(args.maxChunks).toBeUndefined();
+        expect(args.maxTokens).toBeUndefined();
+        expect(args.recencyDepth).toBeUndefined();
+        expect(args.typedMemoryBoost).toBeUndefined();
+    });
+});

package/dist/embeddings.js

@@ -13,7 +13,10 @@ export class LocalEmbeddings {
     async createEmbeddings(inputs) {
         try {
             const extractor = await this._getExtractor();
-            const texts = Array.isArray(inputs) ? inputs : [inputs];
+            const texts = (Array.isArray(inputs) ? inputs : [inputs]).filter((t) => t.trim().length > 0);
+            if (texts.length === 0) {
+                return { status: "success", output: [] };
+            }
             const output = await extractor(texts, {
                 pooling: "mean",
                 normalize: true,

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { LocalEmbeddings } from "./embeddings.js";
 export { Indexer, type IndexerConfig } from "./indexer.js";
-export { search, type SearchOptions, type SearchResult } from "./search.js";
+export { type SearchOptions, type SearchResult, search } from "./search.js";

package/dist/indexer.d.ts

@@ -12,14 +12,15 @@ interface TeammateFiles {
     }[];
 }
 /**
- * Indexes teammate memory files (MEMORIES.md + memory/*.md) into Vectra.
- * One index per teammate, stored at .teammates/.index/<name>/
+ * Indexes teammate memory files (WISDOM.md + memory/*.md) into Vectra.
+ * One index per teammate, stored at .teammates/<name>/.index/
  */
 export declare class Indexer {
     private _config;
     private _embeddings;
     constructor(config: IndexerConfig);
-    get indexRoot(): string;
+    /** Get the index path for a specific teammate */
+    indexPath(teammate: string): string;
     /**
      * Discover all teammate directories (folders containing SOUL.md).
      */