@teammates/recall 0.1.0

package/dist/search.d.ts

@@ -0,0 +1,26 @@
+export interface SearchOptions {
+    /** Path to the .teammates directory */
+    teammatesDir: string;
+    /** Teammate name to search (searches all if omitted) */
+    teammate?: string;
+    /** Max results per teammate (default: 5) */
+    maxResults?: number;
+    /** Max chunks per document (default: 3) */
+    maxChunks?: number;
+    /** Max tokens per section (default: 500) */
+    maxTokens?: number;
+    /** Embedding model name */
+    model?: string;
+    /** Skip auto-sync before searching (default: false) */
+    skipSync?: boolean;
+}
+export interface SearchResult {
+    teammate: string;
+    uri: string;
+    text: string;
+    score: number;
+}
+/**
+ * Search teammate memories using semantic + keyword search.
+ */
+export declare function search(query: string, options: SearchOptions): Promise<SearchResult[]>;

package/dist/search.js

@@ -0,0 +1,75 @@
+import { LocalDocumentIndex } from "vectra";
+import { LocalEmbeddings } from "./embeddings.js";
+import { Indexer } from "./indexer.js";
+import * as path from "node:path";
+import * as fs from "node:fs/promises";
+/**
+ * Search teammate memories using semantic + keyword search.
+ */
+export async function search(query, options) {
+    const indexRoot = path.join(options.teammatesDir, ".index");
+    const embeddings = new LocalEmbeddings(options.model);
+    const maxResults = options.maxResults ?? 5;
+    const maxChunks = options.maxChunks ?? 3;
+    const maxTokens = options.maxTokens ?? 500;
+    // Auto-sync: upsert any new/changed files before searching
+    if (!options.skipSync) {
+        const indexer = new Indexer({ teammatesDir: options.teammatesDir, model: options.model });
+        if (options.teammate) {
+            await indexer.syncTeammate(options.teammate);
+        }
+        else {
+            await indexer.syncAll();
+        }
+    }
+    // Determine which teammates to search
+    let teammates;
+    if (options.teammate) {
+        teammates = [options.teammate];
+    }
+    else {
+        try {
+            const entries = await fs.readdir(indexRoot, { withFileTypes: true });
+            teammates = entries
+                .filter((e) => e.isDirectory())
+                .map((e) => e.name);
+        }
+        catch {
+            return [];
+        }
+    }
+    const allResults = [];
+    for (const teammate of teammates) {
+        const indexPath = path.join(indexRoot, teammate);
+        try {
+            await fs.access(indexPath);
+        }
+        catch {
+            continue; // No index for this teammate
+        }
+        const index = new LocalDocumentIndex({
+            folderPath: indexPath,
+            embeddings,
+        });
+        if (!(await index.isIndexCreated()))
+            continue;
+        const docs = await index.queryDocuments(query, {
+            maxDocuments: maxResults,
+            maxChunks,
+        });
+        for (const doc of docs) {
+            const sections = await doc.renderSections(maxTokens, 1);
+            for (const section of sections) {
+                allResults.push({
+                    teammate,
+                    uri: doc.uri,
+                    text: section.text,
+                    score: section.score,
+                });
+            }
+        }
+    }
+    // Sort by score descending, return top results
+    allResults.sort((a, b) => b.score - a.score);
+    return allResults.slice(0, maxResults);
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@teammates/recall",
+  "version": "0.1.0",
+  "description": "Local semantic memory search for teammates. Indexes MEMORIES.md and daily logs using Vectra + transformers.js.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "teammates-recall": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "teammates",
+    "ai",
+    "memory",
+    "vector-search",
+    "embeddings"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@huggingface/transformers": "^3.0.0",
+    "vectra": "^0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,275 @@
+#!/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();
+
+interface Args {
+  command: string;
+  query: string;
+  file: string;
+  dir: string;
+  teammate?: string;
+  results: number;
+  model?: string;
+  json: boolean;
+  sync: boolean;
+}
+
+function parseArgs(argv: string[]): Args {
+  const args: 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: string): Promise<string> {
+  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: Args): Promise<void> {
+  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: Args): Promise<void> {
+  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: Args): Promise<void> {
+  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: Args): Promise<void> {
+  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: Args): Promise<void> {
+  const teammatesDir = await resolveTeammatesDir(args.dir);
+  const indexer = new Indexer({ teammatesDir, model: args.model });
+  const teammates = await indexer.discoverTeammates();
+
+  const status: Record<string, { memoryFiles: number; indexed: boolean }> = {};
+
+  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(): Promise<void> {
+  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/src/embeddings.ts

@@ -0,0 +1,43 @@
+import type { EmbeddingsModel, EmbeddingsResponse } from "vectra";
+
+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 implements EmbeddingsModel {
+  readonly maxTokens = MAX_TOKENS;
+
+  private _model: string;
+  private _extractor: any | null = null;
+
+  constructor(model?: string) {
+    this._model = model ?? DEFAULT_MODEL;
+  }
+
+  async createEmbeddings(
+    inputs: string | string[]
+  ): Promise<EmbeddingsResponse> {
+    try {
+      const extractor = await this._getExtractor();
+      const texts = Array.isArray(inputs) ? inputs : [inputs];
+      const output = await extractor(texts, {
+        pooling: "mean",
+        normalize: true,
+      });
+      const embeddings: number[][] = output.tolist();
+      return { status: "success", output: embeddings };
+    } catch (err: any) {
+      return { status: "error", message: err.message };
+    }
+  }
+
+  private async _getExtractor(): Promise<any> {
+    if (!this._extractor) {
+      const { pipeline } = await import("@huggingface/transformers");
+      this._extractor = await pipeline("feature-extraction", this._model);
+    }
+    return this._extractor;
+  }
+}

package/src/index.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/src/indexer.ts

@@ -0,0 +1,203 @@
+import { LocalDocumentIndex } from "vectra";
+import { LocalEmbeddings } from "./embeddings.js";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+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 class Indexer {
+  private _config: IndexerConfig;
+  private _embeddings: LocalEmbeddings;
+
+  constructor(config: IndexerConfig) {
+    this._config = config;
+    this._embeddings = new LocalEmbeddings(config.model);
+  }
+
+  get indexRoot(): string {
+    return path.join(this._config.teammatesDir, ".index");
+  }
+
+  /**
+   * Discover all teammate directories (folders containing SOUL.md).
+   */
+  async discoverTeammates(): Promise<string[]> {
+    const entries = await fs.readdir(this._config.teammatesDir, {
+      withFileTypes: true,
+    });
+    const teammates: string[] = [];
+    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: string): Promise<TeammateFiles> {
+    const teammateDir = path.join(this._config.teammatesDir, teammate);
+    const files: TeammateFiles["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: string): Promise<number> {
+    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(): Promise<Map<string, number>> {
+    const teammates = await this.discoverTeammates();
+    const results = new Map<string, number>();
+    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: string, filePath: string): Promise<void> {
+    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: string): Promise<number> {
+    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(): Promise<Map<string, number>> {
+    const teammates = await this.discoverTeammates();
+    const results = new Map<string, number>();
+    for (const teammate of teammates) {
+      const count = await this.syncTeammate(teammate);
+      results.set(teammate, count);
+    }
+    return results;
+  }
+}