@teammates/recall 0.1.0

package/README.md

@@ -0,0 +1,156 @@
+# @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.
+
+**Zero cloud dependencies.** Everything runs locally — embeddings are generated on-device, indexes are stored as local files.
+
+## Install
+
+```bash
+npm install -g @teammates/recall
+```
+
+Or use with npx:
+
+```bash
+npx @teammates/recall search "token budget issues" --dir ./.teammates
+```
+
+## How Agents Use It
+
+The typical agent workflow:
+
+```bash
+# 1. Agent writes a memory file (normal file write, no special tool needed)
+echo "## Notes\n- Fixed the auth token refresh bug" >> .teammates/atlas/memory/2026-03-11.md
+
+# 2. Agent searches memories (auto-syncs new files before searching)
+teammates-recall search "auth token refresh" --json
+
+# 3. That's it. No manual index/sync step needed.
+```
+
+**Search auto-syncs by default** — any new or changed memory files are indexed before results are returned. For large indexes where sync latency matters, use `--no-sync` and manage syncing separately.
+
+## Commands
+
+### search
+
+Search across teammate memories. Auto-syncs new/changed files before querying.
+
+```bash
+teammates-recall search "database migration pattern" --dir ./.teammates
+teammates-recall search "rate limiting" --teammate atlas --results 3
+teammates-recall search "auth token expiration" --json
+teammates-recall search "deploy process" --no-sync    # skip auto-sync
+```
+
+Options:
+- `--teammate <name>` — Search a specific teammate (default: all)
+- `--results <n>` — Max results (default: 5)
+- `--no-sync` — Skip auto-sync before searching
+- `--json` — Output as JSON (useful for piping to agents)
+
+### add
+
+Add a single file to a teammate's index. Use this right after writing a memory file for immediate indexing without a full sync.
+
+```bash
+teammates-recall add .teammates/atlas/memory/2026-03-11.md --teammate atlas
+```
+
+### sync
+
+Incrementally sync new/changed memory files into existing indexes. Faster than a full rebuild.
+
+```bash
+teammates-recall sync --dir ./.teammates
+teammates-recall sync --teammate atlas
+```
+
+### index
+
+Full rebuild of all indexes from scratch. Use when setting up for the first time or when indexes seem stale.
+
+```bash
+teammates-recall index --dir ./.teammates
+teammates-recall index --teammate beacon
+```
+
+### status
+
+Check which teammates have memory files and whether they're indexed.
+
+```bash
+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`
+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)
+5. **Searches** using Vectra's semantic similarity matching
+
+## Use From Any Agent
+
+Any AI coding tool that can run shell commands can use recall:
+
+```bash
+teammates-recall search "how does auth work" --dir ./.teammates --json
+```
+
+The `--json` flag returns structured results that agents can parse:
+
+```json
+[
+  {
+    "teammate": "atlas",
+    "uri": "atlas/MEMORIES.md",
+    "text": "### 2026-01-15: JWT Auth Pattern\n...",
+    "score": 0.847
+  }
+]
+```
+
+## Use As a Library
+
+```typescript
+import { Indexer, search } from "@teammates/recall";
+
+// Full index rebuild
+const indexer = new Indexer({ teammatesDir: "./.teammates" });
+await indexer.indexAll();
+
+// Incremental sync
+await indexer.syncTeammate("atlas");
+
+// Add a single file after writing it
+await indexer.upsertFile("atlas", ".teammates/atlas/memory/2026-03-11.md");
+
+// Search (auto-syncs by default)
+const results = await search("database migration", {
+  teammatesDir: "./.teammates",
+  teammate: "atlas",
+  maxResults: 5,
+});
+
+// Search without auto-sync
+const results2 = await search("database migration", {
+  teammatesDir: "./.teammates",
+  skipSync: true,
+});
+```
+
+## Embedding Model
+
+Default: `Xenova/all-MiniLM-L6-v2` (~23 MB, 384 dimensions)
+
+- Downloaded automatically on first run, cached locally
+- No API keys required
+- Override with `--model <name>` for any transformers.js-compatible model
+
+## 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`.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+import * as path from "node:path";
+import * as fs from "node:fs/promises";
+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
+`.trim();
+function parseArgs(argv) {
+    const args = {
+        command: "",
+        query: "",
+        file: "",
+        dir: "./.teammates",
+        results: 5,
+        json: false,
+        sync: true,
+    };
+    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"))) {
+        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("-")) {
+        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 "--no-sync":
+                args.sync = false;
+                break;
+            case "--json":
+                args.json = true;
+                break;
+            case "--help":
+            case "-h":
+                console.log(HELP);
+                process.exit(0);
+        }
+    }
+    return args;
+}
+async function resolveTeammatesDir(dir) {
+    const resolved = path.resolve(dir);
+    try {
+        await fs.access(resolved);
+        return resolved;
+    }
+    catch {
+        console.error(`Error: .teammates directory not found at ${resolved}`);
+        process.exit(1);
+    }
+}
+async function cmdIndex(args) {
+    const teammatesDir = await resolveTeammatesDir(args.dir);
+    const indexer = new Indexer({ teammatesDir, model: args.model });
+    if (args.teammate) {
+        console.error(`Indexing ${args.teammate}...`);
+        const count = await indexer.indexTeammate(args.teammate);
+        if (args.json) {
+            console.log(JSON.stringify({ teammate: args.teammate, files: count }));
+        }
+        else {
+            console.log(`Indexed ${count} files for ${args.teammate}`);
+        }
+    }
+    else {
+        console.error("Indexing all teammates...");
+        const results = await indexer.indexAll();
+        if (args.json) {
+            const obj = Object.fromEntries(results);
+            console.log(JSON.stringify(obj));
+        }
+        else {
+            for (const [teammate, count] of results) {
+                console.log(`  ${teammate}: ${count} files`);
+            }
+            console.log(`Done.`);
+        }
+    }
+}
+async function cmdSync(args) {
+    const teammatesDir = await resolveTeammatesDir(args.dir);
+    const indexer = new Indexer({ teammatesDir, model: args.model });
+    if (args.teammate) {
+        console.error(`Syncing ${args.teammate}...`);
+        const count = await indexer.syncTeammate(args.teammate);
+        if (args.json) {
+            console.log(JSON.stringify({ teammate: args.teammate, files: count }));
+        }
+        else {
+            console.log(`Synced ${count} files for ${args.teammate}`);
+        }
+    }
+    else {
+        console.error("Syncing all teammates...");
+        const results = await indexer.syncAll();
+        if (args.json) {
+            const obj = Object.fromEntries(results);
+            console.log(JSON.stringify(obj));
+        }
+        else {
+            for (const [teammate, count] of results) {
+                console.log(`  ${teammate}: ${count} files`);
+            }
+            console.log(`Done.`);
+        }
+    }
+}
+async function cmdAdd(args) {
+    if (!args.file) {
+        console.error("Error: add requires a file path argument");
+        console.error("Usage: teammates-recall add <file> --teammate <name>");
+        process.exit(1);
+    }
+    if (!args.teammate) {
+        console.error("Error: add requires --teammate <name>");
+        process.exit(1);
+    }
+    const teammatesDir = await resolveTeammatesDir(args.dir);
+    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" }));
+    }
+    else {
+        console.log(`Added ${args.file} to ${args.teammate}'s index`);
+    }
+}
+async function cmdSearch(args) {
+    if (!args.query) {
+        console.error("Error: search requires a query argument");
+        console.error("Usage: teammates-recall search <query> [options]");
+        process.exit(1);
+    }
+    const teammatesDir = await resolveTeammatesDir(args.dir);
+    const results = await search(args.query, {
+        teammatesDir,
+        teammate: args.teammate,
+        maxResults: args.results,
+        model: args.model,
+        skipSync: !args.sync,
+    });
+    if (args.json) {
+        console.log(JSON.stringify(results, null, 2));
+    }
+    else {
+        if (results.length === 0) {
+            console.log("No results found.");
+            return;
+        }
+        for (const result of results) {
+            console.log(`--- ${result.teammate} | ${result.uri} (score: ${result.score.toFixed(3)}) ---`);
+            console.log(result.text);
+            console.log();
+        }
+    }
+}
+async function cmdStatus(args) {
+    const teammatesDir = await resolveTeammatesDir(args.dir);
+    const indexer = new Indexer({ teammatesDir, model: args.model });
+    const teammates = await indexer.discoverTeammates();
+    const status = {};
+    for (const teammate of teammates) {
+        const { files } = await indexer.collectFiles(teammate);
+        const indexPath = path.join(indexer.indexRoot, teammate);
+        let indexed = false;
+        try {
+            await fs.access(indexPath);
+            indexed = true;
+        }
+        catch {
+            // Not indexed
+        }
+        status[teammate] = { memoryFiles: files.length, indexed };
+    }
+    if (args.json) {
+        console.log(JSON.stringify(status, null, 2));
+    }
+    else {
+        for (const [teammate, info] of Object.entries(status)) {
+            const tag = info.indexed ? "indexed" : "not indexed";
+            console.log(`  ${teammate}: ${info.memoryFiles} memory files (${tag})`);
+        }
+    }
+}
+async function main() {
+    const args = parseArgs(process.argv);
+    switch (args.command) {
+        case "index":
+            await cmdIndex(args);
+            break;
+        case "sync":
+            await cmdSync(args);
+            break;
+        case "add":
+            await cmdAdd(args);
+            break;
+        case "search":
+            await cmdSearch(args);
+            break;
+        case "status":
+            await cmdStatus(args);
+            break;
+        default:
+            console.log(HELP);
+            process.exit(args.command ? 1 : 0);
+    }
+}
+main().catch((err) => {
+    console.error(err.message);
+    process.exit(1);
+});

package/dist/embeddings.d.ts

@@ -0,0 +1,12 @@
+import type { EmbeddingsModel, EmbeddingsResponse } from "vectra";
+/**
+ * Local embeddings using transformers.js. No API keys, no network after first model download.
+ */
+export declare class LocalEmbeddings implements EmbeddingsModel {
+    readonly maxTokens = 256;
+    private _model;
+    private _extractor;
+    constructor(model?: string);
+    createEmbeddings(inputs: string | string[]): Promise<EmbeddingsResponse>;
+    private _getExtractor;
+}

package/dist/embeddings.js

@@ -0,0 +1,35 @@
+const DEFAULT_MODEL = "Xenova/all-MiniLM-L6-v2";
+const MAX_TOKENS = 256;
+/**
+ * Local embeddings using transformers.js. No API keys, no network after first model download.
+ */
+export class LocalEmbeddings {
+    maxTokens = MAX_TOKENS;
+    _model;
+    _extractor = null;
+    constructor(model) {
+        this._model = model ?? DEFAULT_MODEL;
+    }
+    async createEmbeddings(inputs) {
+        try {
+            const extractor = await this._getExtractor();
+            const texts = Array.isArray(inputs) ? inputs : [inputs];
+            const output = await extractor(texts, {
+                pooling: "mean",
+                normalize: true,
+            });
+            const embeddings = output.tolist();
+            return { status: "success", output: embeddings };
+        }
+        catch (err) {
+            return { status: "error", message: err.message };
+        }
+    }
+    async _getExtractor() {
+        if (!this._extractor) {
+            const { pipeline } = await import("@huggingface/transformers");
+            this._extractor = await pipeline("feature-extraction", this._model);
+        }
+        return this._extractor;
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/indexer.d.ts

@@ -0,0 +1,54 @@
+export interface IndexerConfig {
+    /** Path to the .teammates directory */
+    teammatesDir: string;
+    /** Embedding model name (default: Xenova/all-MiniLM-L6-v2) */
+    model?: string;
+}
+interface TeammateFiles {
+    teammate: string;
+    files: {
+        uri: string;
+        absolutePath: string;
+    }[];
+}
+/**
+ * Indexes teammate memory files (MEMORIES.md + memory/*.md) into Vectra.
+ * One index per teammate, stored at .teammates/.index/<name>/
+ */
+export declare class Indexer {
+    private _config;
+    private _embeddings;
+    constructor(config: IndexerConfig);
+    get indexRoot(): string;
+    /**
+     * Discover all teammate directories (folders containing SOUL.md).
+     */
+    discoverTeammates(): Promise<string[]>;
+    /**
+     * Collect all indexable memory files for a teammate.
+     */
+    collectFiles(teammate: string): Promise<TeammateFiles>;
+    /**
+     * Build or rebuild the index for a single teammate.
+     */
+    indexTeammate(teammate: string): Promise<number>;
+    /**
+     * Build or rebuild indexes for all teammates.
+     */
+    indexAll(): Promise<Map<string, number>>;
+    /**
+     * Upsert a single file into an existing teammate index.
+     * Creates the index if it doesn't exist yet.
+     */
+    upsertFile(teammate: string, filePath: string): Promise<void>;
+    /**
+     * Sync a teammate's index with their current memory files.
+     * Upserts new/changed files without a full rebuild.
+     */
+    syncTeammate(teammate: string): Promise<number>;
+    /**
+     * Sync indexes for all teammates.
+     */
+    syncAll(): Promise<Map<string, number>>;
+}
+export {};

package/dist/indexer.js

@@ -0,0 +1,172 @@
+import { LocalDocumentIndex } from "vectra";
+import { LocalEmbeddings } from "./embeddings.js";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+/**
+ * Indexes teammate memory files (MEMORIES.md + memory/*.md) into Vectra.
+ * One index per teammate, stored at .teammates/.index/<name>/
+ */
+export class Indexer {
+    _config;
+    _embeddings;
+    constructor(config) {
+        this._config = config;
+        this._embeddings = new LocalEmbeddings(config.model);
+    }
+    get indexRoot() {
+        return path.join(this._config.teammatesDir, ".index");
+    }
+    /**
+     * Discover all teammate directories (folders containing SOUL.md).
+     */
+    async discoverTeammates() {
+        const entries = await fs.readdir(this._config.teammatesDir, {
+            withFileTypes: true,
+        });
+        const teammates = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith("."))
+                continue;
+            const soulPath = path.join(this._config.teammatesDir, entry.name, "SOUL.md");
+            try {
+                await fs.access(soulPath);
+                teammates.push(entry.name);
+            }
+            catch {
+                // Not a teammate folder
+            }
+        }
+        return teammates;
+    }
+    /**
+     * Collect all indexable memory files for a teammate.
+     */
+    async collectFiles(teammate) {
+        const teammateDir = path.join(this._config.teammatesDir, teammate);
+        const files = [];
+        // MEMORIES.md
+        const memoriesPath = path.join(teammateDir, "MEMORIES.md");
+        try {
+            await fs.access(memoriesPath);
+            files.push({ uri: `${teammate}/MEMORIES.md`, absolutePath: memoriesPath });
+        }
+        catch {
+            // No MEMORIES.md
+        }
+        // memory/*.md (daily logs)
+        const memoryDir = path.join(teammateDir, "memory");
+        try {
+            const memoryEntries = await fs.readdir(memoryDir);
+            for (const entry of memoryEntries) {
+                if (!entry.endsWith(".md"))
+                    continue;
+                files.push({
+                    uri: `${teammate}/memory/${entry}`,
+                    absolutePath: path.join(memoryDir, entry),
+                });
+            }
+        }
+        catch {
+            // No memory/ directory
+        }
+        return { teammate, files };
+    }
+    /**
+     * Build or rebuild the index for a single teammate.
+     */
+    async indexTeammate(teammate) {
+        const { files } = await this.collectFiles(teammate);
+        if (files.length === 0)
+            return 0;
+        const indexPath = path.join(this.indexRoot, teammate);
+        const index = new LocalDocumentIndex({
+            folderPath: indexPath,
+            embeddings: this._embeddings,
+        });
+        // Recreate index from scratch
+        await index.createIndex({ version: 1, deleteIfExists: true });
+        let count = 0;
+        for (const file of files) {
+            const text = await fs.readFile(file.absolutePath, "utf-8");
+            if (text.trim().length === 0)
+                continue;
+            await index.upsertDocument(file.uri, text, "md");
+            count++;
+        }
+        return count;
+    }
+    /**
+     * Build or rebuild indexes for all teammates.
+     */
+    async indexAll() {
+        const teammates = await this.discoverTeammates();
+        const results = new Map();
+        for (const teammate of teammates) {
+            const count = await this.indexTeammate(teammate);
+            results.set(teammate, count);
+        }
+        return results;
+    }
+    /**
+     * Upsert a single file into an existing teammate index.
+     * Creates the index if it doesn't exist yet.
+     */
+    async upsertFile(teammate, filePath) {
+        const teammateDir = path.join(this._config.teammatesDir, teammate);
+        const absolutePath = path.resolve(filePath);
+        const relativePath = path.relative(teammateDir, absolutePath);
+        const uri = `${teammate}/${relativePath.replace(/\\/g, "/")}`;
+        const text = await fs.readFile(absolutePath, "utf-8");
+        if (text.trim().length === 0)
+            return;
+        const indexPath = path.join(this.indexRoot, teammate);
+        const index = new LocalDocumentIndex({
+            folderPath: indexPath,
+            embeddings: this._embeddings,
+        });
+        if (!(await index.isIndexCreated())) {
+            await index.createIndex({ version: 1 });
+        }
+        await index.upsertDocument(uri, text, "md");
+    }
+    /**
+     * Sync a teammate's index with their current memory files.
+     * Upserts new/changed files without a full rebuild.
+     */
+    async syncTeammate(teammate) {
+        const { files } = await this.collectFiles(teammate);
+        if (files.length === 0)
+            return 0;
+        const indexPath = path.join(this.indexRoot, teammate);
+        const index = new LocalDocumentIndex({
+            folderPath: indexPath,
+            embeddings: this._embeddings,
+        });
+        if (!(await index.isIndexCreated())) {
+            // No index yet — do a full build
+            return this.indexTeammate(teammate);
+        }
+        // Upsert all files (Vectra handles dedup internally via URI)
+        let count = 0;
+        for (const file of files) {
+            const text = await fs.readFile(file.absolutePath, "utf-8");
+            if (text.trim().length === 0)
+                continue;
+            await index.upsertDocument(file.uri, text, "md");
+            count++;
+        }
+        return count;
+    }
+    /**
+     * Sync indexes for all teammates.
+     */
+    async syncAll() {
+        const teammates = await this.discoverTeammates();
+        const results = new Map();
+        for (const teammate of teammates) {
+            const count = await this.syncTeammate(teammate);
+            results.set(teammate, count);
+        }
+        return results;
+    }
+}