@teammates/recall 0.1.1 → 0.2.0

package/src/indexer.test.ts

@@ -0,0 +1,262 @@
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { Indexer } from "./indexer.js";
+
+// Stub embeddings — we don't want to load the real model in tests
+class StubEmbeddings {
+  readonly maxTokens = 256;
+  async createEmbeddings(inputs: string | string[]) {
+    const texts = Array.isArray(inputs) ? inputs : [inputs];
+    return {
+      status: "success" as const,
+      output: texts.map(() => new Array(384).fill(0).map(() => Math.random())),
+    };
+  }
+}
+
+// Create an Indexer with stubbed embeddings
+function createIndexer(teammatesDir: string): Indexer {
+  const indexer = new Indexer({ teammatesDir });
+  // Swap out the real embeddings with our stub
+  (indexer as any)._embeddings = new StubEmbeddings();
+  return indexer;
+}
+
+let testDir: string;
+
+beforeEach(async () => {
+  testDir = join(
+    tmpdir(),
+    `recall-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  await mkdir(testDir, { recursive: true });
+});
+
+afterEach(async () => {
+  await rm(testDir, { recursive: true, force: true });
+});
+
+describe("Indexer", () => {
+  describe("discoverTeammates", () => {
+    it("finds directories containing SOUL.md", async () => {
+      const beacon = join(testDir, "beacon");
+      const scribe = join(testDir, "scribe");
+      const notTeammate = join(testDir, "random");
+
+      await mkdir(beacon, { recursive: true });
+      await mkdir(scribe, { recursive: true });
+      await mkdir(notTeammate, { recursive: true });
+
+      await writeFile(join(beacon, "SOUL.md"), "# Beacon");
+      await writeFile(join(scribe, "SOUL.md"), "# Scribe");
+      // notTeammate has no SOUL.md
+
+      const indexer = createIndexer(testDir);
+      const teammates = await indexer.discoverTeammates();
+
+      expect(teammates).toContain("beacon");
+      expect(teammates).toContain("scribe");
+      expect(teammates).not.toContain("random");
+    });
+
+    it("ignores dot-prefixed directories", async () => {
+      const hidden = join(testDir, ".tmp");
+      await mkdir(hidden, { recursive: true });
+      await writeFile(join(hidden, "SOUL.md"), "# Hidden");
+
+      const indexer = createIndexer(testDir);
+      const teammates = await indexer.discoverTeammates();
+
+      expect(teammates).not.toContain(".tmp");
+      expect(teammates).toHaveLength(0);
+    });
+
+    it("returns empty array when no teammates exist", async () => {
+      const indexer = createIndexer(testDir);
+      const teammates = await indexer.discoverTeammates();
+      expect(teammates).toEqual([]);
+    });
+  });
+
+  describe("collectFiles", () => {
+    it("collects WISDOM.md", async () => {
+      const beacon = join(testDir, "beacon");
+      await mkdir(beacon, { recursive: true });
+      await writeFile(join(beacon, "WISDOM.md"), "# Wisdom");
+
+      const indexer = createIndexer(testDir);
+      const { files } = await indexer.collectFiles("beacon");
+
+      expect(files).toHaveLength(1);
+      expect(files[0].uri).toBe("beacon/WISDOM.md");
+    });
+
+    it("collects typed memory files from memory/", async () => {
+      const memDir = join(testDir, "beacon", "memory");
+      await mkdir(memDir, { recursive: true });
+      await writeFile(join(memDir, "feedback_testing.md"), "# Feedback");
+      await writeFile(join(memDir, "project_goals.md"), "# Goals");
+
+      const indexer = createIndexer(testDir);
+      const { files } = await indexer.collectFiles("beacon");
+
+      const uris = files.map((f) => f.uri);
+      expect(uris).toContain("beacon/memory/feedback_testing.md");
+      expect(uris).toContain("beacon/memory/project_goals.md");
+    });
+
+    it("skips daily logs (YYYY-MM-DD.md pattern)", async () => {
+      const memDir = join(testDir, "beacon", "memory");
+      await mkdir(memDir, { recursive: true });
+      await writeFile(join(memDir, "2026-03-14.md"), "# Day 1");
+      await writeFile(join(memDir, "2026-03-15.md"), "# Day 2");
+      await writeFile(join(memDir, "feedback_testing.md"), "# Feedback");
+
+      const indexer = createIndexer(testDir);
+      const { files } = await indexer.collectFiles("beacon");
+
+      const uris = files.map((f) => f.uri);
+      expect(uris).not.toContain("beacon/memory/2026-03-14.md");
+      expect(uris).not.toContain("beacon/memory/2026-03-15.md");
+      expect(uris).toContain("beacon/memory/feedback_testing.md");
+    });
+
+    it("collects weekly summaries from memory/weekly/", async () => {
+      const weeklyDir = join(testDir, "beacon", "memory", "weekly");
+      await mkdir(weeklyDir, { recursive: true });
+      await writeFile(join(weeklyDir, "2026-W10.md"), "# Week 10");
+      await writeFile(join(weeklyDir, "2026-W11.md"), "# Week 11");
+
+      const indexer = createIndexer(testDir);
+      const { files } = await indexer.collectFiles("beacon");
+
+      const uris = files.map((f) => f.uri);
+      expect(uris).toContain("beacon/memory/weekly/2026-W10.md");
+      expect(uris).toContain("beacon/memory/weekly/2026-W11.md");
+    });
+
+    it("collects monthly summaries from memory/monthly/", async () => {
+      const monthlyDir = join(testDir, "beacon", "memory", "monthly");
+      await mkdir(monthlyDir, { recursive: true });
+      await writeFile(join(monthlyDir, "2025-12.md"), "# Dec 2025");
+
+      const indexer = createIndexer(testDir);
+      const { files } = await indexer.collectFiles("beacon");
+
+      const uris = files.map((f) => f.uri);
+      expect(uris).toContain("beacon/memory/monthly/2025-12.md");
+    });
+
+    it("skips non-md files", async () => {
+      const memDir = join(testDir, "beacon", "memory");
+      await mkdir(memDir, { recursive: true });
+      await writeFile(join(memDir, "notes.txt"), "not markdown");
+      await writeFile(join(memDir, "feedback_test.md"), "# Feedback");
+
+      const indexer = createIndexer(testDir);
+      const { files } = await indexer.collectFiles("beacon");
+
+      expect(files).toHaveLength(1);
+      expect(files[0].uri).toBe("beacon/memory/feedback_test.md");
+    });
+
+    it("returns empty files when teammate has no content", async () => {
+      await mkdir(join(testDir, "beacon"), { recursive: true });
+
+      const indexer = createIndexer(testDir);
+      const { files } = await indexer.collectFiles("beacon");
+      expect(files).toEqual([]);
+    });
+  });
+
+  describe("indexPath", () => {
+    it("returns correct path under teammate directory", () => {
+      const indexer = createIndexer(testDir);
+      const p = indexer.indexPath("beacon");
+      expect(p).toBe(join(testDir, "beacon", ".index"));
+    });
+  });
+
+  describe("indexTeammate", () => {
+    it("creates an index and returns file count", async () => {
+      const beacon = join(testDir, "beacon");
+      const memDir = join(beacon, "memory");
+      await mkdir(memDir, { recursive: true });
+      await writeFile(join(beacon, "WISDOM.md"), "# Wisdom content");
+      await writeFile(join(memDir, "feedback_test.md"), "# Feedback content");
+
+      const indexer = createIndexer(testDir);
+      const count = await indexer.indexTeammate("beacon");
+
+      expect(count).toBe(2);
+    });
+
+    it("returns 0 when no files to index", async () => {
+      await mkdir(join(testDir, "beacon"), { recursive: true });
+
+      const indexer = createIndexer(testDir);
+      const count = await indexer.indexTeammate("beacon");
+      expect(count).toBe(0);
+    });
+
+    it("skips empty files", async () => {
+      const beacon = join(testDir, "beacon");
+      await mkdir(beacon, { recursive: true });
+      await writeFile(join(beacon, "WISDOM.md"), "   "); // whitespace only
+
+      const indexer = createIndexer(testDir);
+      const count = await indexer.indexTeammate("beacon");
+      expect(count).toBe(0);
+    });
+  });
+
+  describe("indexAll", () => {
+    it("indexes all discovered teammates", async () => {
+      const beacon = join(testDir, "beacon");
+      const scribe = join(testDir, "scribe");
+      await mkdir(beacon, { recursive: true });
+      await mkdir(scribe, { recursive: true });
+      await writeFile(join(beacon, "SOUL.md"), "# Beacon");
+      await writeFile(join(beacon, "WISDOM.md"), "# Beacon wisdom");
+      await writeFile(join(scribe, "SOUL.md"), "# Scribe");
+
+      const indexer = createIndexer(testDir);
+      const results = await indexer.indexAll();
+
+      expect(results.get("beacon")).toBe(1); // WISDOM.md only (SOUL.md not collected)
+      expect(results.get("scribe")).toBe(0); // no indexable files
+    });
+  });
+
+  describe("syncTeammate", () => {
+    it("falls back to full index when no index exists", async () => {
+      const beacon = join(testDir, "beacon");
+      await mkdir(beacon, { recursive: true });
+      await writeFile(join(beacon, "WISDOM.md"), "# Wisdom");
+
+      const indexer = createIndexer(testDir);
+      const count = await indexer.syncTeammate("beacon");
+      expect(count).toBe(1);
+    });
+
+    it("upserts files into existing index", async () => {
+      const beacon = join(testDir, "beacon");
+      const memDir = join(beacon, "memory");
+      await mkdir(memDir, { recursive: true });
+      await writeFile(join(beacon, "WISDOM.md"), "# Wisdom");
+
+      const indexer = createIndexer(testDir);
+      // First build the index
+      await indexer.indexTeammate("beacon");
+
+      // Add a new file
+      await writeFile(join(memDir, "project_goals.md"), "# Goals");
+
+      // Sync should pick up the new file
+      const count = await indexer.syncTeammate("beacon");
+      expect(count).toBe(2); // WISDOM + project_goals
+    });
+  });
+});

package/src/indexer.ts

@@ -1,7 +1,7 @@
-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";
 
 export interface IndexerConfig {
   /** Path to the .teammates directory */
@@ -16,7 +16,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 class Indexer {
@@ -46,7 +46,7 @@ export class Indexer {
       const soulPath = path.join(
         this._config.teammatesDir,
         entry.name,
-        "SOUL.md"
+        "SOUL.md",
       );
       try {
         await fs.access(soulPath);
@@ -65,21 +65,24 @@ export class Indexer {
     const teammateDir = path.join(this._config.teammatesDir, teammate);
     const files: TeammateFiles["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),
@@ -89,6 +92,36 @@ export class Indexer {
       // 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/src/search.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+
+// classifyUri is not exported, so we test it indirectly via a re-implementation
+// or we can import the module and test the search function behavior.
+// Since classifyUri is a pure function, let's extract and test its logic.
+
+describe("classifyUri", () => {
+  // Re-implement the classification logic for unit testing
+  function classifyUri(uri: string): string {
+    if (uri.includes("/memory/weekly/")) return "weekly";
+    if (uri.includes("/memory/monthly/")) return "monthly";
+    const memoryMatch = uri.match(/\/memory\/([^/]+)\.md$/);
+    if (memoryMatch) {
+      const stem = memoryMatch[1];
+      if (/^\d{4}-\d{2}-\d{2}$/.test(stem)) return "daily";
+      return "typed_memory";
+    }
+    return "other";
+  }
+
+  it("classifies weekly summaries", () => {
+    expect(classifyUri("beacon/memory/weekly/2026-W10.md")).toBe("weekly");
+  });
+
+  it("classifies monthly summaries", () => {
+    expect(classifyUri("beacon/memory/monthly/2025-12.md")).toBe("monthly");
+  });
+
+  it("classifies typed memories", () => {
+    expect(classifyUri("beacon/memory/feedback_testing.md")).toBe(
+      "typed_memory",
+    );
+    expect(classifyUri("beacon/memory/project_goals.md")).toBe("typed_memory");
+  });
+
+  it("classifies daily logs", () => {
+    expect(classifyUri("beacon/memory/2026-03-14.md")).toBe("daily");
+    expect(classifyUri("beacon/memory/2026-01-01.md")).toBe("daily");
+  });
+
+  it("classifies WISDOM.md as other", () => {
+    expect(classifyUri("beacon/WISDOM.md")).toBe("other");
+  });
+
+  it("classifies non-memory paths as other", () => {
+    expect(classifyUri("beacon/SOUL.md")).toBe("other");
+    expect(classifyUri("beacon/notes/todo.md")).toBe("other");
+  });
+});

package/src/search.ts

@@ -1,8 +1,8 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
 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";
 
 export interface SearchOptions {
   /** Path to the .teammates directory */
@@ -19,6 +19,10 @@ export interface SearchOptions {
   model?: string;
   /** Skip auto-sync before searching (default: false) */
   skipSync?: boolean;
+  /** Number of recent weekly summaries to always include (default: 2) */
+  recencyDepth?: number;
+  /** Relevance boost multiplier for typed memories over episodic summaries (default: 1.2) */
+  typedMemoryBoost?: number;
 }
 
 export interface SearchResult {
@@ -26,20 +30,47 @@ export interface SearchResult {
   uri: string;
   text: string;
   score: number;
+  /** Content type: "typed_memory", "weekly", "monthly", or "other" */
+  contentType?: string;
+}
+
+/**
+ * Classify a URI into a content type for priority scoring.
+ */
+function classifyUri(uri: string): string {
+  if (uri.includes("/memory/weekly/")) return "weekly";
+  if (uri.includes("/memory/monthly/")) return "monthly";
+  // Typed memories are in memory/ but not daily logs (YYYY-MM-DD) and not in subdirs
+  const memoryMatch = uri.match(/\/memory\/([^/]+)\.md$/);
+  if (memoryMatch) {
+    const stem = memoryMatch[1];
+    if (/^\d{4}-\d{2}-\d{2}$/.test(stem)) return "daily";
+    return "typed_memory";
+  }
+  return "other";
 }
 
 /**
- * Search teammate memories using semantic + keyword search.
+ * Search teammate memories using multi-pass retrieval.
+ *
+ * Pass 1 (Recency): Always returns the N most recent weekly summaries.
+ * Pass 2 (Semantic): Query-driven search across all indexed content.
+ * Results are merged, deduped, and typed memories get a relevance boost.
  */
 export async function search(
   query: string,
-  options: SearchOptions
+  options: SearchOptions,
 ): Promise<SearchResult[]> {
   const embeddings = new LocalEmbeddings(options.model);
-  const indexer = new Indexer({ teammatesDir: options.teammatesDir, model: options.model });
+  const indexer = new Indexer({
+    teammatesDir: options.teammatesDir,
+    model: options.model,
+  });
   const maxResults = options.maxResults ?? 5;
   const maxChunks = options.maxChunks ?? 3;
   const maxTokens = options.maxTokens ?? 500;
+  const recencyDepth = options.recencyDepth ?? 2;
+  const typedMemoryBoost = options.typedMemoryBoost ?? 1.2;
 
   // Auto-sync: upsert any new/changed files before searching
   if (!options.skipSync) {
@@ -59,13 +90,49 @@ export async function search(
   }
 
   const allResults: SearchResult[] = [];
+  const seenUris = new Set<string>();
 
+  // ── Pass 1: Recency (recent weekly summaries, always included) ───
+  for (const teammate of teammates) {
+    const weeklyDir = path.join(
+      options.teammatesDir,
+      teammate,
+      "memory",
+      "weekly",
+    );
+    try {
+      const entries = await fs.readdir(weeklyDir);
+      const weeklyFiles = entries
+        .filter((e) => e.endsWith(".md"))
+        .sort()
+        .reverse()
+        .slice(0, recencyDepth);
+
+      for (const file of weeklyFiles) {
+        const uri = `${teammate}/memory/weekly/${file}`;
+        const text = await fs.readFile(path.join(weeklyDir, file), "utf-8");
+        if (text.trim().length === 0) continue;
+        seenUris.add(uri);
+        allResults.push({
+          teammate,
+          uri,
+          text: text.slice(0, maxTokens * 4), // rough token estimate
+          score: 0.9, // high base score for recency results
+          contentType: "weekly",
+        });
+      }
+    } catch {
+      // No weekly/ directory for this teammate
+    }
+  }
+
+  // ── Pass 2: Semantic (query-driven across all indexed content) ───
   for (const teammate of teammates) {
     const indexPath = indexer.indexPath(teammate);
     try {
       await fs.access(indexPath);
     } catch {
-      continue; // No index for this teammate
+      continue;
     }
 
     const index = new LocalDocumentIndex({
@@ -81,13 +148,25 @@ export async function search(
     });
 
     for (const doc of docs) {
+      if (seenUris.has(doc.uri)) continue; // dedup with recency pass
+      seenUris.add(doc.uri);
+
       const sections = await doc.renderSections(maxTokens, 1);
+      const contentType = classifyUri(doc.uri);
+
       for (const section of sections) {
+        let score = section.score;
+        // Apply type-based priority boost for typed memories
+        if (contentType === "typed_memory") {
+          score *= typedMemoryBoost;
+        }
+
         allResults.push({
           teammate,
           uri: doc.uri,
           text: section.text,
-          score: section.score,
+          score,
+          contentType,
         });
       }
     }
@@ -95,5 +174,5 @@ export async function search(
 
   // Sort by score descending, return top results
   allResults.sort((a, b) => b.score - a.score);
-  return allResults.slice(0, maxResults);
+  return allResults.slice(0, maxResults + recencyDepth); // allow extra slots for recency results
 }

package/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.ts"],
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json-summary"],
+      reportsDirectory: "coverage",
+    },
+  },
+});