@teammates/recall 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { LocalEmbeddings } from "./embeddings.js";
 export { Indexer, type IndexerConfig } from "./indexer.js";
-export { type SearchOptions, type SearchResult, search } from "./search.js";
+export { matchMemoryCatalog, scanMemoryCatalog } from "./memory-index.js";
+export { buildQueryVariations, extractKeywords } from "./query-expansion.js";
+export { type MultiSearchOptions, type SearchOptions, type SearchResult, multiSearch, search, } from "./search.js";

package/dist/index.js

@@ -1,3 +1,5 @@
 export { LocalEmbeddings } from "./embeddings.js";
 export { Indexer } from "./indexer.js";
-export { search } from "./search.js";
+export { matchMemoryCatalog, scanMemoryCatalog } from "./memory-index.js";
+export { buildQueryVariations, extractKeywords } from "./query-expansion.js";
+export { multiSearch, search, } from "./search.js";

package/dist/memory-index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Memory frontmatter scanning for Pass 1 recall queries.
+ *
+ * Reads the teammate's memory file catalog (name + description from frontmatter)
+ * and does fast text matching against the task prompt. This is a lightweight,
+ * no-embedding relevance signal — "here's a menu of what I might know about."
+ */
+import type { SearchResult } from "./search.js";
+interface MemoryEntry {
+    /** Relative URI (e.g. "beacon/memory/project_goals.md") */
+    uri: string;
+    /** Absolute file path */
+    absolutePath: string;
+    /** Frontmatter name field */
+    name: string;
+    /** Frontmatter description field */
+    description: string;
+}
+/**
+ * Scan a teammate's memory directory and build a catalog of memory entries
+ * with their frontmatter metadata.
+ */
+export declare function scanMemoryCatalog(teammatesDir: string, teammate: string): Promise<MemoryEntry[]>;
+/**
+ * Match task prompt text against memory catalog entries.
+ * Returns memory files whose name or description has significant word overlap
+ * with the task prompt. Each match is returned as a SearchResult with the
+ * file's full content.
+ *
+ * Matching is case-insensitive. A match requires at least one word from the
+ * task prompt appearing in the name or description.
+ */
+export declare function matchMemoryCatalog(teammatesDir: string, teammate: string, taskPrompt: string, maxTokens?: number): Promise<SearchResult[]>;
+export {};

package/dist/memory-index.js

@@ -0,0 +1,118 @@
+/**
+ * Memory frontmatter scanning for Pass 1 recall queries.
+ *
+ * Reads the teammate's memory file catalog (name + description from frontmatter)
+ * and does fast text matching against the task prompt. This is a lightweight,
+ * no-embedding relevance signal — "here's a menu of what I might know about."
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+/**
+ * Parse YAML-ish frontmatter from a markdown file's content.
+ * Returns name and description fields, or null if no frontmatter found.
+ */
+function parseFrontmatter(content) {
+    const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!match)
+        return null;
+    const fm = match[1];
+    const nameMatch = fm.match(/^name:\s*(.+)$/m);
+    const descMatch = fm.match(/^description:\s*(.+)$/m);
+    if (!nameMatch)
+        return null;
+    return {
+        name: nameMatch[1].trim(),
+        description: descMatch?.[1]?.trim() ?? "",
+    };
+}
+/**
+ * Scan a teammate's memory directory and build a catalog of memory entries
+ * with their frontmatter metadata.
+ */
+export async function scanMemoryCatalog(teammatesDir, teammate) {
+    const memoryDir = path.join(teammatesDir, teammate, "memory");
+    const entries = [];
+    try {
+        const files = await fs.readdir(memoryDir);
+        for (const file of files) {
+            if (!file.endsWith(".md"))
+                continue;
+            // Skip daily logs (YYYY-MM-DD.md)
+            const stem = path.basename(file, ".md");
+            if (/^\d{4}-\d{2}-\d{2}$/.test(stem))
+                continue;
+            const absolutePath = path.join(memoryDir, file);
+            const content = await fs.readFile(absolutePath, "utf-8");
+            const fm = parseFrontmatter(content);
+            if (!fm)
+                continue;
+            entries.push({
+                uri: `${teammate}/memory/${file}`,
+                absolutePath,
+                name: fm.name,
+                description: fm.description,
+            });
+        }
+    }
+    catch {
+        // No memory/ directory
+    }
+    return entries;
+}
+/**
+ * Match task prompt text against memory catalog entries.
+ * Returns memory files whose name or description has significant word overlap
+ * with the task prompt. Each match is returned as a SearchResult with the
+ * file's full content.
+ *
+ * Matching is case-insensitive. A match requires at least one word from the
+ * task prompt appearing in the name or description.
+ */
+export async function matchMemoryCatalog(teammatesDir, teammate, taskPrompt, maxTokens = 500) {
+    const catalog = await scanMemoryCatalog(teammatesDir, teammate);
+    if (catalog.length === 0)
+        return [];
+    // Tokenize the task prompt into lowercase words (3+ chars)
+    const promptWords = new Set(taskPrompt
+        .toLowerCase()
+        .replace(/[^\w\s@/-]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 2));
+    const results = [];
+    for (const entry of catalog) {
+        const catalogText = `${entry.name} ${entry.description}`.toLowerCase();
+        const catalogWords = catalogText
+            .replace(/[^\w\s@/_-]/g, " ")
+            .split(/\s+/)
+            .filter((w) => w.length > 2);
+        // Count overlapping words
+        let overlap = 0;
+        for (const w of catalogWords) {
+            if (promptWords.has(w))
+                overlap++;
+        }
+        // Also check if prompt words appear as substrings in the catalog text
+        // (e.g., "goal" matches "project_goals")
+        for (const pw of promptWords) {
+            if (catalogText.includes(pw) && !catalogWords.includes(pw)) {
+                overlap += 0.5;
+            }
+        }
+        if (overlap >= 1) {
+            // Read full file content for matched entries
+            const content = await fs.readFile(entry.absolutePath, "utf-8");
+            // Strip frontmatter from the content
+            const body = content.replace(/^---\s*\n[\s\S]*?\n---\s*\n?/, "").trim();
+            results.push({
+                teammate,
+                uri: entry.uri,
+                text: body.slice(0, maxTokens * 4), // rough token limit
+                score: 0.85 + Math.min(overlap * 0.02, 0.1), // 0.85-0.95 range
+                contentType: "typed_memory",
+            });
+        }
+    }
+    // Sort by score descending
+    results.sort((a, b) => b.score - a.score);
+    return results;
+}

package/dist/memory-index.test.d.ts

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

package/dist/memory-index.test.js

@@ -0,0 +1,96 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { matchMemoryCatalog, scanMemoryCatalog } from "./memory-index.js";
+const TEST_DIR = path.join(process.cwd(), ".test-memory-index");
+const TEAMMATE = "testmate";
+beforeAll(async () => {
+    const memoryDir = path.join(TEST_DIR, TEAMMATE, "memory");
+    await fs.mkdir(memoryDir, { recursive: true });
+    // Create typed memory files with frontmatter
+    await fs.writeFile(path.join(memoryDir, "project_goals.md"), `---
+name: project_goals
+description: Stack-ranked feature goals for the teammates project
+type: project
+---
+
+## Goals
+
+1. Recall query architecture
+2. CLI improvements
+`);
+    await fs.writeFile(path.join(memoryDir, "feedback_testing.md"), `---
+name: feedback_testing
+description: Integration tests must hit a real database, not mocks
+type: feedback
+---
+
+Use real databases in tests. Mocks hide migration bugs.
+`);
+    // Create a file without frontmatter (should be skipped)
+    await fs.writeFile(path.join(memoryDir, "notes.md"), "Just some notes without frontmatter.\n");
+    // Create a daily log (should be skipped)
+    await fs.writeFile(path.join(memoryDir, "2026-03-21.md"), "# 2026-03-21\nDaily log content.\n");
+});
+afterAll(async () => {
+    await fs.rm(TEST_DIR, { recursive: true, force: true });
+});
+describe("scanMemoryCatalog", () => {
+    it("returns entries with frontmatter", async () => {
+        const entries = await scanMemoryCatalog(TEST_DIR, TEAMMATE);
+        expect(entries.length).toBe(2);
+        const names = entries.map((e) => e.name);
+        expect(names).toContain("project_goals");
+        expect(names).toContain("feedback_testing");
+    });
+    it("skips files without frontmatter", async () => {
+        const entries = await scanMemoryCatalog(TEST_DIR, TEAMMATE);
+        const uris = entries.map((e) => e.uri);
+        expect(uris).not.toContain(`${TEAMMATE}/memory/notes.md`);
+    });
+    it("skips daily logs", async () => {
+        const entries = await scanMemoryCatalog(TEST_DIR, TEAMMATE);
+        const uris = entries.map((e) => e.uri);
+        expect(uris).not.toContain(`${TEAMMATE}/memory/2026-03-21.md`);
+    });
+    it("returns empty array for nonexistent teammate", async () => {
+        const entries = await scanMemoryCatalog(TEST_DIR, "nobody");
+        expect(entries).toEqual([]);
+    });
+});
+describe("matchMemoryCatalog", () => {
+    it("matches files whose frontmatter overlaps with the query", async () => {
+        const results = await matchMemoryCatalog(TEST_DIR, TEAMMATE, "what are our project goals and features?");
+        expect(results.length).toBeGreaterThanOrEqual(1);
+        expect(results[0].uri).toContain("project_goals");
+    });
+    it("matches on description keywords", async () => {
+        const results = await matchMemoryCatalog(TEST_DIR, TEAMMATE, "database testing integration");
+        expect(results.length).toBeGreaterThanOrEqual(1);
+        const uris = results.map((r) => r.uri);
+        expect(uris).toContain(`${TEAMMATE}/memory/feedback_testing.md`);
+    });
+    it("returns empty for unrelated queries", async () => {
+        const results = await matchMemoryCatalog(TEST_DIR, TEAMMATE, "quantum physics dark matter");
+        expect(results.length).toBe(0);
+    });
+    it("strips frontmatter from result text", async () => {
+        const results = await matchMemoryCatalog(TEST_DIR, TEAMMATE, "project goals features");
+        expect(results.length).toBeGreaterThanOrEqual(1);
+        expect(results[0].text).not.toContain("---");
+        expect(results[0].text).toContain("Goals");
+    });
+    it("assigns scores in the 0.85-0.95 range", async () => {
+        const results = await matchMemoryCatalog(TEST_DIR, TEAMMATE, "project goals features teammates");
+        for (const r of results) {
+            expect(r.score).toBeGreaterThanOrEqual(0.85);
+            expect(r.score).toBeLessThanOrEqual(0.95);
+        }
+    });
+    it("sets contentType to typed_memory", async () => {
+        const results = await matchMemoryCatalog(TEST_DIR, TEAMMATE, "project goals");
+        for (const r of results) {
+            expect(r.contentType).toBe("typed_memory");
+        }
+    });
+});

package/dist/query-expansion.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Lightweight query expansion for Pass 1 recall queries.
+ *
+ * No LLM needed — uses stopword removal and basic text analysis
+ * to generate multiple query variations from a task prompt.
+ */
+/**
+ * Extract meaningful keywords from text by removing stopwords and short tokens.
+ * Returns lowercase keywords in order of appearance.
+ */
+export declare function extractKeywords(text: string): string[];
+/**
+ * Build multiple query variations from a task prompt and optional conversation context.
+ *
+ * Returns 1-3 queries:
+ * 1. The original task prompt (always)
+ * 2. A focused keyword query (if keywords differ meaningfully from the original)
+ * 3. A conversation-derived query (if recent conversation context is provided)
+ */
+export declare function buildQueryVariations(taskPrompt: string, conversationContext?: string): string[];

package/dist/query-expansion.js

@@ -0,0 +1,92 @@
+/**
+ * Lightweight query expansion for Pass 1 recall queries.
+ *
+ * No LLM needed — uses stopword removal and basic text analysis
+ * to generate multiple query variations from a task prompt.
+ */
+/** Common English stopwords to filter from queries. */
+const STOPWORDS = new Set([
+    "a", "an", "the", "and", "or", "but", "in", "on", "at", "to", "for",
+    "of", "with", "by", "from", "is", "are", "was", "were", "be", "been",
+    "being", "have", "has", "had", "do", "does", "did", "will", "would",
+    "could", "should", "may", "might", "shall", "can", "need", "must",
+    "it", "its", "this", "that", "these", "those", "i", "you", "he", "she",
+    "we", "they", "me", "him", "her", "us", "them", "my", "your", "his",
+    "our", "their", "what", "which", "who", "whom", "where", "when", "how",
+    "why", "if", "then", "so", "not", "no", "just", "also", "very", "too",
+    "some", "any", "all", "each", "every", "both", "few", "more", "most",
+    "other", "into", "over", "after", "before", "between", "through",
+    "about", "up", "out", "off", "down", "here", "there", "again", "once",
+    "let", "lets", "let's", "get", "got", "go", "going", "make", "made",
+    "take", "took", "come", "came", "see", "saw", "know", "knew", "think",
+    "thought", "say", "said", "tell", "told", "ask", "asked", "want",
+    "wanted", "like", "look", "use", "used", "find", "give", "work",
+]);
+/**
+ * Extract meaningful keywords from text by removing stopwords and short tokens.
+ * Returns lowercase keywords in order of appearance.
+ */
+export function extractKeywords(text) {
+    const words = text
+        .toLowerCase()
+        .replace(/[^\w\s@/-]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 2 && !STOPWORDS.has(w));
+    // Deduplicate while preserving order
+    const seen = new Set();
+    const result = [];
+    for (const w of words) {
+        if (!seen.has(w)) {
+            seen.add(w);
+            result.push(w);
+        }
+    }
+    return result;
+}
+/**
+ * Build multiple query variations from a task prompt and optional conversation context.
+ *
+ * Returns 1-3 queries:
+ * 1. The original task prompt (always)
+ * 2. A focused keyword query (if keywords differ meaningfully from the original)
+ * 3. A conversation-derived query (if recent conversation context is provided)
+ */
+export function buildQueryVariations(taskPrompt, conversationContext) {
+    const queries = [taskPrompt];
+    // Query 2: Focused keywords from the task prompt
+    const keywords = extractKeywords(taskPrompt);
+    if (keywords.length >= 2 && keywords.length <= 20) {
+        const keywordQuery = keywords.slice(0, 8).join(" ");
+        // Only add if meaningfully different from original
+        if (keywordQuery.length < taskPrompt.length * 0.7) {
+            queries.push(keywordQuery);
+        }
+    }
+    // Query 3: Recent conversation topic
+    if (conversationContext) {
+        const recentTopic = extractRecentTopic(conversationContext);
+        if (recentTopic) {
+            queries.push(recentTopic);
+        }
+    }
+    return queries;
+}
+/**
+ * Extract the most recent topic/theme from conversation context.
+ * Takes the last 1-2 meaningful entries and extracts keywords.
+ */
+function extractRecentTopic(conversationContext) {
+    // Split on common conversation entry patterns
+    const entries = conversationContext
+        .split(/\n\*\*\w+:\*\*\s*/g)
+        .filter((e) => e.trim().length > 10);
+    if (entries.length === 0)
+        return null;
+    // Take the last 1-2 entries (most recent conversation)
+    const recent = entries.slice(-2).join(" ");
+    const keywords = extractKeywords(recent);
+    if (keywords.length < 2)
+        return null;
+    // Build a focused query from the recent conversation keywords
+    return keywords.slice(0, 6).join(" ");
+}

package/dist/query-expansion.test.d.ts

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

package/dist/query-expansion.test.js

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import { buildQueryVariations, extractKeywords } from "./query-expansion.js";
+describe("extractKeywords", () => {
+    it("removes stopwords", () => {
+        const result = extractKeywords("the quick brown fox jumps over the lazy dog");
+        expect(result).toContain("quick");
+        expect(result).toContain("brown");
+        expect(result).toContain("fox");
+        expect(result).toContain("jumps");
+        expect(result).toContain("lazy");
+        expect(result).toContain("dog");
+        expect(result).not.toContain("the");
+        expect(result).not.toContain("over");
+    });
+    it("filters short tokens (length <= 2)", () => {
+        const result = extractKeywords("an AI is a type of ML system");
+        expect(result).not.toContain("an");
+        expect(result).not.toContain("is");
+        // "type" and "system" stay, "AI" and "ML" filtered (length 2)
+        expect(result).toContain("type");
+        expect(result).toContain("system");
+    });
+    it("deduplicates while preserving order", () => {
+        const result = extractKeywords("recall search recall index search");
+        expect(result).toEqual(["recall", "search", "index"]);
+    });
+    it("lowercases all output", () => {
+        const result = extractKeywords("Update the HOOKS spec");
+        expect(result).toContain("update");
+        expect(result).toContain("hooks");
+        expect(result).toContain("spec");
+    });
+    it("returns empty array for all-stopword input", () => {
+        const result = extractKeywords("the is a");
+        expect(result).toEqual([]);
+    });
+    it("preserves @mentions and paths", () => {
+        const result = extractKeywords("deploy @pipeline src/hooks");
+        expect(result).toContain("deploy");
+        expect(result).toContain("@pipeline");
+        expect(result).toContain("src/hooks");
+    });
+});
+describe("buildQueryVariations", () => {
+    it("always includes the original prompt as the first query", () => {
+        const result = buildQueryVariations("fix the authentication bug");
+        expect(result[0]).toBe("fix the authentication bug");
+    });
+    it("generates a keyword-focused query when prompt is verbose", () => {
+        const verbose = "I want you to please update the recall search system so that it handles multiple queries at the same time and deduplicates the results properly";
+        const result = buildQueryVariations(verbose);
+        expect(result.length).toBeGreaterThanOrEqual(2);
+        // The keyword query should be shorter than the original
+        if (result.length > 1) {
+            expect(result[1].length).toBeLessThan(verbose.length);
+        }
+    });
+    it("adds a conversation-derived query when context is provided", () => {
+        const conversationContext = `## Conversation History
+
+**stevenic:** lets talk about the CI pipeline and hooks
+
+**pipeline:** CI Pipeline Hooks — Analysis`;
+        const result = buildQueryVariations("what should we do next?", conversationContext);
+        // Should have at least the original + conversation query
+        expect(result.length).toBeGreaterThanOrEqual(2);
+    });
+    it("skips conversation query when no context", () => {
+        const result = buildQueryVariations("short task");
+        // Short prompts with few keywords may only produce 1 query
+        expect(result.length).toBeGreaterThanOrEqual(1);
+        expect(result[0]).toBe("short task");
+    });
+    it("does not generate keyword query when prompt is already concise", () => {
+        const result = buildQueryVariations("recall search");
+        // Very short — keyword query wouldn't differ meaningfully
+        expect(result[0]).toBe("recall search");
+    });
+});

package/dist/search.d.ts

@@ -18,6 +18,13 @@ export interface SearchOptions {
     /** Relevance boost multiplier for typed memories over episodic summaries (default: 1.2) */
     typedMemoryBoost?: number;
 }
+/** Options for multi-query search with deduplication. */
+export interface MultiSearchOptions extends SearchOptions {
+    /** Additional queries beyond the primary (keyword-focused, conversation-derived, etc.) */
+    additionalQueries?: string[];
+    /** Pre-matched memory catalog results to merge into the final set */
+    catalogMatches?: SearchResult[];
+}
 export interface SearchResult {
     teammate: string;
     uri: string;
@@ -34,3 +41,12 @@ export interface SearchResult {
  * Results are merged, deduped, and typed memories get a relevance boost.
  */
 export declare function search(query: string, options: SearchOptions): Promise<SearchResult[]>;
+/**
+ * Multi-query search with deduplication and catalog merge.
+ *
+ * Fires the primary query plus any additional queries (keyword-focused,
+ * conversation-derived) and merges results. Catalog matches (from frontmatter
+ * text matching) are also merged. Deduplication is by URI — when the same
+ * URI appears from multiple queries, the highest score wins.
+ */
+export declare function multiSearch(primaryQuery: string, options: MultiSearchOptions): Promise<SearchResult[]>;

package/dist/search.js

@@ -132,3 +132,52 @@ export async function search(query, options) {
     allResults.sort((a, b) => b.score - a.score);
     return allResults.slice(0, maxResults + recencyDepth); // allow extra slots for recency results
 }
+/**
+ * Multi-query search with deduplication and catalog merge.
+ *
+ * Fires the primary query plus any additional queries (keyword-focused,
+ * conversation-derived) and merges results. Catalog matches (from frontmatter
+ * text matching) are also merged. Deduplication is by URI — when the same
+ * URI appears from multiple queries, the highest score wins.
+ */
+export async function multiSearch(primaryQuery, options) {
+    const additionalQueries = options.additionalQueries ?? [];
+    const catalogMatches = options.catalogMatches ?? [];
+    const maxResults = options.maxResults ?? 5;
+    const recencyDepth = options.recencyDepth ?? 2;
+    // Fire all queries — primary gets full treatment (recency pass + semantic)
+    // Additional queries get semantic only (skipRecency to avoid duplicate weeklies)
+    const primaryResults = await search(primaryQuery, options);
+    // Collect all results keyed by URI, keeping highest score
+    const bestByUri = new Map();
+    for (const r of primaryResults) {
+        const existing = bestByUri.get(r.uri);
+        if (!existing || r.score > existing.score) {
+            bestByUri.set(r.uri, r);
+        }
+    }
+    // Fire additional queries (reuse same search options minus recency to avoid dupes)
+    for (const query of additionalQueries) {
+        const results = await search(query, {
+            ...options,
+            recencyDepth: 0, // primary already got the weekly summaries
+        });
+        for (const r of results) {
+            const existing = bestByUri.get(r.uri);
+            if (!existing || r.score > existing.score) {
+                bestByUri.set(r.uri, r);
+            }
+        }
+    }
+    // Merge catalog matches (frontmatter text-matched results)
+    for (const r of catalogMatches) {
+        const existing = bestByUri.get(r.uri);
+        if (!existing || r.score > existing.score) {
+            bestByUri.set(r.uri, r);
+        }
+    }
+    // Sort by score descending, return top results
+    const merged = [...bestByUri.values()];
+    merged.sort((a, b) => b.score - a.score);
+    return merged.slice(0, maxResults + recencyDepth);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teammates/recall",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Local semantic memory search for teammates. Indexes WISDOM.md and memory files using Vectra + transformers.js.",
   "type": "module",
   "main": "dist/index.js",

package/src/index.ts

@@ -1,3 +1,11 @@
 export { LocalEmbeddings } from "./embeddings.js";
 export { Indexer, type IndexerConfig } from "./indexer.js";
-export { type SearchOptions, type SearchResult, search } from "./search.js";
+export { matchMemoryCatalog, scanMemoryCatalog } from "./memory-index.js";
+export { buildQueryVariations, extractKeywords } from "./query-expansion.js";
+export {
+  type MultiSearchOptions,
+  type SearchOptions,
+  type SearchResult,
+  multiSearch,
+  search,
+} from "./search.js";

package/src/memory-index.test.ts

@@ -0,0 +1,149 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { matchMemoryCatalog, scanMemoryCatalog } from "./memory-index.js";
+
+const TEST_DIR = path.join(process.cwd(), ".test-memory-index");
+const TEAMMATE = "testmate";
+
+beforeAll(async () => {
+  const memoryDir = path.join(TEST_DIR, TEAMMATE, "memory");
+  await fs.mkdir(memoryDir, { recursive: true });
+
+  // Create typed memory files with frontmatter
+  await fs.writeFile(
+    path.join(memoryDir, "project_goals.md"),
+    `---
+name: project_goals
+description: Stack-ranked feature goals for the teammates project
+type: project
+---
+
+## Goals
+
+1. Recall query architecture
+2. CLI improvements
+`,
+  );
+
+  await fs.writeFile(
+    path.join(memoryDir, "feedback_testing.md"),
+    `---
+name: feedback_testing
+description: Integration tests must hit a real database, not mocks
+type: feedback
+---
+
+Use real databases in tests. Mocks hide migration bugs.
+`,
+  );
+
+  // Create a file without frontmatter (should be skipped)
+  await fs.writeFile(
+    path.join(memoryDir, "notes.md"),
+    "Just some notes without frontmatter.\n",
+  );
+
+  // Create a daily log (should be skipped)
+  await fs.writeFile(
+    path.join(memoryDir, "2026-03-21.md"),
+    "# 2026-03-21\nDaily log content.\n",
+  );
+});
+
+afterAll(async () => {
+  await fs.rm(TEST_DIR, { recursive: true, force: true });
+});
+
+describe("scanMemoryCatalog", () => {
+  it("returns entries with frontmatter", async () => {
+    const entries = await scanMemoryCatalog(TEST_DIR, TEAMMATE);
+    expect(entries.length).toBe(2);
+    const names = entries.map((e) => e.name);
+    expect(names).toContain("project_goals");
+    expect(names).toContain("feedback_testing");
+  });
+
+  it("skips files without frontmatter", async () => {
+    const entries = await scanMemoryCatalog(TEST_DIR, TEAMMATE);
+    const uris = entries.map((e) => e.uri);
+    expect(uris).not.toContain(`${TEAMMATE}/memory/notes.md`);
+  });
+
+  it("skips daily logs", async () => {
+    const entries = await scanMemoryCatalog(TEST_DIR, TEAMMATE);
+    const uris = entries.map((e) => e.uri);
+    expect(uris).not.toContain(`${TEAMMATE}/memory/2026-03-21.md`);
+  });
+
+  it("returns empty array for nonexistent teammate", async () => {
+    const entries = await scanMemoryCatalog(TEST_DIR, "nobody");
+    expect(entries).toEqual([]);
+  });
+});
+
+describe("matchMemoryCatalog", () => {
+  it("matches files whose frontmatter overlaps with the query", async () => {
+    const results = await matchMemoryCatalog(
+      TEST_DIR,
+      TEAMMATE,
+      "what are our project goals and features?",
+    );
+    expect(results.length).toBeGreaterThanOrEqual(1);
+    expect(results[0].uri).toContain("project_goals");
+  });
+
+  it("matches on description keywords", async () => {
+    const results = await matchMemoryCatalog(
+      TEST_DIR,
+      TEAMMATE,
+      "database testing integration",
+    );
+    expect(results.length).toBeGreaterThanOrEqual(1);
+    const uris = results.map((r) => r.uri);
+    expect(uris).toContain(`${TEAMMATE}/memory/feedback_testing.md`);
+  });
+
+  it("returns empty for unrelated queries", async () => {
+    const results = await matchMemoryCatalog(
+      TEST_DIR,
+      TEAMMATE,
+      "quantum physics dark matter",
+    );
+    expect(results.length).toBe(0);
+  });
+
+  it("strips frontmatter from result text", async () => {
+    const results = await matchMemoryCatalog(
+      TEST_DIR,
+      TEAMMATE,
+      "project goals features",
+    );
+    expect(results.length).toBeGreaterThanOrEqual(1);
+    expect(results[0].text).not.toContain("---");
+    expect(results[0].text).toContain("Goals");
+  });
+
+  it("assigns scores in the 0.85-0.95 range", async () => {
+    const results = await matchMemoryCatalog(
+      TEST_DIR,
+      TEAMMATE,
+      "project goals features teammates",
+    );
+    for (const r of results) {
+      expect(r.score).toBeGreaterThanOrEqual(0.85);
+      expect(r.score).toBeLessThanOrEqual(0.95);
+    }
+  });
+
+  it("sets contentType to typed_memory", async () => {
+    const results = await matchMemoryCatalog(
+      TEST_DIR,
+      TEAMMATE,
+      "project goals",
+    );
+    for (const r of results) {
+      expect(r.contentType).toBe("typed_memory");
+    }
+  });
+});

package/src/memory-index.ts

@@ -0,0 +1,151 @@
+/**
+ * Memory frontmatter scanning for Pass 1 recall queries.
+ *
+ * Reads the teammate's memory file catalog (name + description from frontmatter)
+ * and does fast text matching against the task prompt. This is a lightweight,
+ * no-embedding relevance signal — "here's a menu of what I might know about."
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { SearchResult } from "./search.js";
+
+interface MemoryEntry {
+  /** Relative URI (e.g. "beacon/memory/project_goals.md") */
+  uri: string;
+  /** Absolute file path */
+  absolutePath: string;
+  /** Frontmatter name field */
+  name: string;
+  /** Frontmatter description field */
+  description: string;
+}
+
+/**
+ * Parse YAML-ish frontmatter from a markdown file's content.
+ * Returns name and description fields, or null if no frontmatter found.
+ */
+function parseFrontmatter(content: string): { name: string; description: string } | null {
+  const match = content.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  const fm = match[1];
+  const nameMatch = fm.match(/^name:\s*(.+)$/m);
+  const descMatch = fm.match(/^description:\s*(.+)$/m);
+
+  if (!nameMatch) return null;
+
+  return {
+    name: nameMatch[1].trim(),
+    description: descMatch?.[1]?.trim() ?? "",
+  };
+}
+
+/**
+ * Scan a teammate's memory directory and build a catalog of memory entries
+ * with their frontmatter metadata.
+ */
+export async function scanMemoryCatalog(
+  teammatesDir: string,
+  teammate: string,
+): Promise<MemoryEntry[]> {
+  const memoryDir = path.join(teammatesDir, teammate, "memory");
+  const entries: MemoryEntry[] = [];
+
+  try {
+    const files = await fs.readdir(memoryDir);
+    for (const file of files) {
+      if (!file.endsWith(".md")) continue;
+      // Skip daily logs (YYYY-MM-DD.md)
+      const stem = path.basename(file, ".md");
+      if (/^\d{4}-\d{2}-\d{2}$/.test(stem)) continue;
+
+      const absolutePath = path.join(memoryDir, file);
+      const content = await fs.readFile(absolutePath, "utf-8");
+      const fm = parseFrontmatter(content);
+      if (!fm) continue;
+
+      entries.push({
+        uri: `${teammate}/memory/${file}`,
+        absolutePath,
+        name: fm.name,
+        description: fm.description,
+      });
+    }
+  } catch {
+    // No memory/ directory
+  }
+
+  return entries;
+}
+
+/**
+ * Match task prompt text against memory catalog entries.
+ * Returns memory files whose name or description has significant word overlap
+ * with the task prompt. Each match is returned as a SearchResult with the
+ * file's full content.
+ *
+ * Matching is case-insensitive. A match requires at least one word from the
+ * task prompt appearing in the name or description.
+ */
+export async function matchMemoryCatalog(
+  teammatesDir: string,
+  teammate: string,
+  taskPrompt: string,
+  maxTokens = 500,
+): Promise<SearchResult[]> {
+  const catalog = await scanMemoryCatalog(teammatesDir, teammate);
+  if (catalog.length === 0) return [];
+
+  // Tokenize the task prompt into lowercase words (3+ chars)
+  const promptWords = new Set(
+    taskPrompt
+      .toLowerCase()
+      .replace(/[^\w\s@/-]/g, " ")
+      .split(/\s+/)
+      .filter((w) => w.length > 2),
+  );
+
+  const results: SearchResult[] = [];
+
+  for (const entry of catalog) {
+    const catalogText = `${entry.name} ${entry.description}`.toLowerCase();
+    const catalogWords = catalogText
+      .replace(/[^\w\s@/_-]/g, " ")
+      .split(/\s+/)
+      .filter((w) => w.length > 2);
+
+    // Count overlapping words
+    let overlap = 0;
+    for (const w of catalogWords) {
+      if (promptWords.has(w)) overlap++;
+    }
+
+    // Also check if prompt words appear as substrings in the catalog text
+    // (e.g., "goal" matches "project_goals")
+    for (const pw of promptWords) {
+      if (catalogText.includes(pw) && !catalogWords.includes(pw)) {
+        overlap += 0.5;
+      }
+    }
+
+    if (overlap >= 1) {
+      // Read full file content for matched entries
+      const content = await fs.readFile(entry.absolutePath, "utf-8");
+      // Strip frontmatter from the content
+      const body = content.replace(/^---\s*\n[\s\S]*?\n---\s*\n?/, "").trim();
+
+      results.push({
+        teammate,
+        uri: entry.uri,
+        text: body.slice(0, maxTokens * 4), // rough token limit
+        score: 0.85 + Math.min(overlap * 0.02, 0.1), // 0.85-0.95 range
+        contentType: "typed_memory",
+      });
+    }
+  }
+
+  // Sort by score descending
+  results.sort((a, b) => b.score - a.score);
+  return results;
+}

package/src/query-expansion.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from "vitest";
+import { buildQueryVariations, extractKeywords } from "./query-expansion.js";
+
+describe("extractKeywords", () => {
+  it("removes stopwords", () => {
+    const result = extractKeywords("the quick brown fox jumps over the lazy dog");
+    expect(result).toContain("quick");
+    expect(result).toContain("brown");
+    expect(result).toContain("fox");
+    expect(result).toContain("jumps");
+    expect(result).toContain("lazy");
+    expect(result).toContain("dog");
+    expect(result).not.toContain("the");
+    expect(result).not.toContain("over");
+  });
+
+  it("filters short tokens (length <= 2)", () => {
+    const result = extractKeywords("an AI is a type of ML system");
+    expect(result).not.toContain("an");
+    expect(result).not.toContain("is");
+    // "type" and "system" stay, "AI" and "ML" filtered (length 2)
+    expect(result).toContain("type");
+    expect(result).toContain("system");
+  });
+
+  it("deduplicates while preserving order", () => {
+    const result = extractKeywords("recall search recall index search");
+    expect(result).toEqual(["recall", "search", "index"]);
+  });
+
+  it("lowercases all output", () => {
+    const result = extractKeywords("Update the HOOKS spec");
+    expect(result).toContain("update");
+    expect(result).toContain("hooks");
+    expect(result).toContain("spec");
+  });
+
+  it("returns empty array for all-stopword input", () => {
+    const result = extractKeywords("the is a");
+    expect(result).toEqual([]);
+  });
+
+  it("preserves @mentions and paths", () => {
+    const result = extractKeywords("deploy @pipeline src/hooks");
+    expect(result).toContain("deploy");
+    expect(result).toContain("@pipeline");
+    expect(result).toContain("src/hooks");
+  });
+});
+
+describe("buildQueryVariations", () => {
+  it("always includes the original prompt as the first query", () => {
+    const result = buildQueryVariations("fix the authentication bug");
+    expect(result[0]).toBe("fix the authentication bug");
+  });
+
+  it("generates a keyword-focused query when prompt is verbose", () => {
+    const verbose = "I want you to please update the recall search system so that it handles multiple queries at the same time and deduplicates the results properly";
+    const result = buildQueryVariations(verbose);
+    expect(result.length).toBeGreaterThanOrEqual(2);
+    // The keyword query should be shorter than the original
+    if (result.length > 1) {
+      expect(result[1].length).toBeLessThan(verbose.length);
+    }
+  });
+
+  it("adds a conversation-derived query when context is provided", () => {
+    const conversationContext = `## Conversation History
+
+**stevenic:** lets talk about the CI pipeline and hooks
+
+**pipeline:** CI Pipeline Hooks — Analysis`;
+    const result = buildQueryVariations("what should we do next?", conversationContext);
+    // Should have at least the original + conversation query
+    expect(result.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it("skips conversation query when no context", () => {
+    const result = buildQueryVariations("short task");
+    // Short prompts with few keywords may only produce 1 query
+    expect(result.length).toBeGreaterThanOrEqual(1);
+    expect(result[0]).toBe("short task");
+  });
+
+  it("does not generate keyword query when prompt is already concise", () => {
+    const result = buildQueryVariations("recall search");
+    // Very short — keyword query wouldn't differ meaningfully
+    expect(result[0]).toBe("recall search");
+  });
+});

package/src/query-expansion.ts

@@ -0,0 +1,105 @@
+/**
+ * Lightweight query expansion for Pass 1 recall queries.
+ *
+ * No LLM needed — uses stopword removal and basic text analysis
+ * to generate multiple query variations from a task prompt.
+ */
+
+/** Common English stopwords to filter from queries. */
+const STOPWORDS = new Set([
+  "a", "an", "the", "and", "or", "but", "in", "on", "at", "to", "for",
+  "of", "with", "by", "from", "is", "are", "was", "were", "be", "been",
+  "being", "have", "has", "had", "do", "does", "did", "will", "would",
+  "could", "should", "may", "might", "shall", "can", "need", "must",
+  "it", "its", "this", "that", "these", "those", "i", "you", "he", "she",
+  "we", "they", "me", "him", "her", "us", "them", "my", "your", "his",
+  "our", "their", "what", "which", "who", "whom", "where", "when", "how",
+  "why", "if", "then", "so", "not", "no", "just", "also", "very", "too",
+  "some", "any", "all", "each", "every", "both", "few", "more", "most",
+  "other", "into", "over", "after", "before", "between", "through",
+  "about", "up", "out", "off", "down", "here", "there", "again", "once",
+  "let", "lets", "let's", "get", "got", "go", "going", "make", "made",
+  "take", "took", "come", "came", "see", "saw", "know", "knew", "think",
+  "thought", "say", "said", "tell", "told", "ask", "asked", "want",
+  "wanted", "like", "look", "use", "used", "find", "give", "work",
+]);
+
+/**
+ * Extract meaningful keywords from text by removing stopwords and short tokens.
+ * Returns lowercase keywords in order of appearance.
+ */
+export function extractKeywords(text: string): string[] {
+  const words = text
+    .toLowerCase()
+    .replace(/[^\w\s@/-]/g, " ")
+    .split(/\s+/)
+    .filter((w) => w.length > 2 && !STOPWORDS.has(w));
+
+  // Deduplicate while preserving order
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const w of words) {
+    if (!seen.has(w)) {
+      seen.add(w);
+      result.push(w);
+    }
+  }
+  return result;
+}
+
+/**
+ * Build multiple query variations from a task prompt and optional conversation context.
+ *
+ * Returns 1-3 queries:
+ * 1. The original task prompt (always)
+ * 2. A focused keyword query (if keywords differ meaningfully from the original)
+ * 3. A conversation-derived query (if recent conversation context is provided)
+ */
+export function buildQueryVariations(
+  taskPrompt: string,
+  conversationContext?: string,
+): string[] {
+  const queries: string[] = [taskPrompt];
+
+  // Query 2: Focused keywords from the task prompt
+  const keywords = extractKeywords(taskPrompt);
+  if (keywords.length >= 2 && keywords.length <= 20) {
+    const keywordQuery = keywords.slice(0, 8).join(" ");
+    // Only add if meaningfully different from original
+    if (keywordQuery.length < taskPrompt.length * 0.7) {
+      queries.push(keywordQuery);
+    }
+  }
+
+  // Query 3: Recent conversation topic
+  if (conversationContext) {
+    const recentTopic = extractRecentTopic(conversationContext);
+    if (recentTopic) {
+      queries.push(recentTopic);
+    }
+  }
+
+  return queries;
+}
+
+/**
+ * Extract the most recent topic/theme from conversation context.
+ * Takes the last 1-2 meaningful entries and extracts keywords.
+ */
+function extractRecentTopic(conversationContext: string): string | null {
+  // Split on common conversation entry patterns
+  const entries = conversationContext
+    .split(/\n\*\*\w+:\*\*\s*/g)
+    .filter((e) => e.trim().length > 10);
+
+  if (entries.length === 0) return null;
+
+  // Take the last 1-2 entries (most recent conversation)
+  const recent = entries.slice(-2).join(" ");
+  const keywords = extractKeywords(recent);
+
+  if (keywords.length < 2) return null;
+
+  // Build a focused query from the recent conversation keywords
+  return keywords.slice(0, 6).join(" ");
+}

package/src/search.ts

@@ -25,6 +25,14 @@ export interface SearchOptions {
   typedMemoryBoost?: number;
 }
 
+/** Options for multi-query search with deduplication. */
+export interface MultiSearchOptions extends SearchOptions {
+  /** Additional queries beyond the primary (keyword-focused, conversation-derived, etc.) */
+  additionalQueries?: string[];
+  /** Pre-matched memory catalog results to merge into the final set */
+  catalogMatches?: SearchResult[];
+}
+
 export interface SearchResult {
   teammate: string;
   uri: string;
@@ -176,3 +184,61 @@ export async function search(
   allResults.sort((a, b) => b.score - a.score);
   return allResults.slice(0, maxResults + recencyDepth); // allow extra slots for recency results
 }
+
+/**
+ * Multi-query search with deduplication and catalog merge.
+ *
+ * Fires the primary query plus any additional queries (keyword-focused,
+ * conversation-derived) and merges results. Catalog matches (from frontmatter
+ * text matching) are also merged. Deduplication is by URI — when the same
+ * URI appears from multiple queries, the highest score wins.
+ */
+export async function multiSearch(
+  primaryQuery: string,
+  options: MultiSearchOptions,
+): Promise<SearchResult[]> {
+  const additionalQueries = options.additionalQueries ?? [];
+  const catalogMatches = options.catalogMatches ?? [];
+  const maxResults = options.maxResults ?? 5;
+  const recencyDepth = options.recencyDepth ?? 2;
+
+  // Fire all queries — primary gets full treatment (recency pass + semantic)
+  // Additional queries get semantic only (skipRecency to avoid duplicate weeklies)
+  const primaryResults = await search(primaryQuery, options);
+
+  // Collect all results keyed by URI, keeping highest score
+  const bestByUri = new Map<string, SearchResult>();
+  for (const r of primaryResults) {
+    const existing = bestByUri.get(r.uri);
+    if (!existing || r.score > existing.score) {
+      bestByUri.set(r.uri, r);
+    }
+  }
+
+  // Fire additional queries (reuse same search options minus recency to avoid dupes)
+  for (const query of additionalQueries) {
+    const results = await search(query, {
+      ...options,
+      recencyDepth: 0, // primary already got the weekly summaries
+    });
+    for (const r of results) {
+      const existing = bestByUri.get(r.uri);
+      if (!existing || r.score > existing.score) {
+        bestByUri.set(r.uri, r);
+      }
+    }
+  }
+
+  // Merge catalog matches (frontmatter text-matched results)
+  for (const r of catalogMatches) {
+    const existing = bestByUri.get(r.uri);
+    if (!existing || r.score > existing.score) {
+      bestByUri.set(r.uri, r);
+    }
+  }
+
+  // Sort by score descending, return top results
+  const merged = [...bestByUri.values()];
+  merged.sort((a, b) => b.score - a.score);
+  return merged.slice(0, maxResults + recencyDepth);
+}