@teammates/recall 0.1.1 → 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,9 +90,9 @@ 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
@@ -117,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
   }
@@ -165,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,6 +1,7 @@
 #!/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 = `
@@ -12,15 +13,20 @@ Usage:
   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)
-  --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
+  --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,
     });
@@ -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/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,7 +12,7 @@ interface TeammateFiles {
     }[];
 }
 /**
- * Indexes teammate memory files (MEMORIES.md + memory/*.md) into Vectra.
+ * Indexes teammate memory files (WISDOM.md + memory/*.md) into Vectra.
  * One index per teammate, stored at .teammates/<name>/.index/
  */
 export declare class Indexer {

package/dist/indexer.js

@@ -1,9 +1,9 @@
-import { LocalDocumentIndex } from "vectra";
-import { LocalEmbeddings } from "./embeddings.js";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { LocalDocumentIndex } from "vectra";
+import { LocalEmbeddings } from "./embeddings.js";
 /**
- * Indexes teammate memory files (MEMORIES.md + memory/*.md) into Vectra.
+ * Indexes teammate memory files (WISDOM.md + memory/*.md) into Vectra.
  * One index per teammate, stored at .teammates/<name>/.index/
  */
 export class Indexer {
@@ -45,22 +45,26 @@ export class Indexer {
     async collectFiles(teammate) {
         const teammateDir = path.join(this._config.teammatesDir, teammate);
         const files = [];
-        // MEMORIES.md
-        const memoriesPath = path.join(teammateDir, "MEMORIES.md");
+        // WISDOM.md
+        const wisdomPath = path.join(teammateDir, "WISDOM.md");
         try {
-            await fs.access(memoriesPath);
-            files.push({ uri: `${teammate}/MEMORIES.md`, absolutePath: memoriesPath });
+            await fs.access(wisdomPath);
+            files.push({ uri: `${teammate}/WISDOM.md`, absolutePath: wisdomPath });
         }
         catch {
-            // No MEMORIES.md
+            // No WISDOM.md
         }
-        // memory/*.md (daily logs)
+        // memory/*.md — typed memories only (skip raw daily logs, they're in prompt context)
         const memoryDir = path.join(teammateDir, "memory");
         try {
             const memoryEntries = await fs.readdir(memoryDir);
             for (const entry of memoryEntries) {
                 if (!entry.endsWith(".md"))
                     continue;
+                const stem = path.basename(entry, ".md");
+                // Skip daily logs (YYYY-MM-DD) — they're already in prompt context
+                if (/^\d{4}-\d{2}-\d{2}$/.test(stem))
+                    continue;
                 files.push({
                     uri: `${teammate}/memory/${entry}`,
                     absolutePath: path.join(memoryDir, entry),
@@ -70,6 +74,38 @@ export class Indexer {
         catch {
             // No memory/ directory
         }
+        // memory/weekly/*.md — weekly summaries (primary episodic search surface)
+        const weeklyDir = path.join(memoryDir, "weekly");
+        try {
+            const weeklyEntries = await fs.readdir(weeklyDir);
+            for (const entry of weeklyEntries) {
+                if (!entry.endsWith(".md"))
+                    continue;
+                files.push({
+                    uri: `${teammate}/memory/weekly/${entry}`,
+                    absolutePath: path.join(weeklyDir, entry),
+                });
+            }
+        }
+        catch {
+            // No weekly/ directory
+        }
+        // memory/monthly/*.md — monthly summaries (long-term episodic context)
+        const monthlyDir = path.join(memoryDir, "monthly");
+        try {
+            const monthlyEntries = await fs.readdir(monthlyDir);
+            for (const entry of monthlyEntries) {
+                if (!entry.endsWith(".md"))
+                    continue;
+                files.push({
+                    uri: `${teammate}/memory/monthly/${entry}`,
+                    absolutePath: path.join(monthlyDir, entry),
+                });
+            }
+        }
+        catch {
+            // No monthly/ directory
+        }
         return { teammate, files };
     }
     /**

package/dist/indexer.test.d.ts

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