tlc-claude-code 1.8.5 → 2.1.0

package/server/lib/recall-command.test.js

@@ -0,0 +1,306 @@
+/**
+ * Recall Command Tests
+ *
+ * Tests for /tlc:recall — semantic search command for querying memory.
+ * "What did we decide about X?" Returns ranked results with similarity
+ * scores, supports scope/type/limit options, and falls back to text
+ * search when the vector store is unavailable.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { createRecallCommand } from './recall-command.js';
+
+/**
+ * Creates a mock semanticRecall dependency with a vi.fn() recall method.
+ * Returns configurable results so each test can set its own scenario.
+ *
+ * @param {Array} [results=[]] - Default results the recall method returns
+ * @returns {object} Mock semanticRecall with a `recall` method
+ */
+function createMockSemanticRecall(results = []) {
+  return {
+    recall: vi.fn().mockResolvedValue(results),
+  };
+}
+
+/**
+ * Creates a single mock recall result entry.
+ *
+ * @param {object} overrides - Properties to override on the default result
+ * @returns {object} A mock recall result
+ */
+function createMockResult(overrides = {}) {
+  return {
+    id: 'mem-1',
+    text: 'Use SQLite for vector storage because it is lightweight and embeddable',
+    score: 0.92,
+    type: 'decision',
+    source: {
+      project: 'my-project',
+      workspace: '/ws',
+      branch: 'main',
+      sourceFile: 'memory/decisions/use-sqlite.md',
+    },
+    date: Date.now() - 86400000,
+    permanent: false,
+    ...overrides,
+  };
+}
+
+describe('recall-command', () => {
+  let mockSemanticRecall;
+  let recallCmd;
+
+  beforeEach(() => {
+    mockSemanticRecall = createMockSemanticRecall();
+    recallCmd = createRecallCommand({
+      semanticRecall: mockSemanticRecall,
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('returns relevant results for a query', async () => {
+    const mockResults = [
+      createMockResult({ id: 'mem-1', text: 'Use SQLite for vector storage', score: 0.92 }),
+      createMockResult({ id: 'mem-2', text: 'Postgres for production data', score: 0.85 }),
+    ];
+    mockSemanticRecall.recall.mockResolvedValue(mockResults);
+
+    const result = await recallCmd.execute('/project', {
+      query: 'database architecture',
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.results).toHaveLength(2);
+    expect(mockSemanticRecall.recall).toHaveBeenCalledWith(
+      'database architecture',
+      expect.objectContaining({}),
+      expect.objectContaining({}),
+    );
+  });
+
+  it('results include title, date, score, type, excerpt', async () => {
+    const now = Date.now();
+    const mockResults = [
+      createMockResult({
+        id: 'mem-1',
+        text: 'Use SQLite for vector storage because it is lightweight and embeddable',
+        score: 0.92,
+        type: 'decision',
+        date: now - 86400000,
+        source: {
+          project: 'my-project',
+          workspace: '/ws',
+          branch: 'main',
+          sourceFile: 'memory/decisions/use-sqlite.md',
+        },
+        permanent: false,
+      }),
+    ];
+    mockSemanticRecall.recall.mockResolvedValue(mockResults);
+
+    const result = await recallCmd.execute('/project', {
+      query: 'vector storage',
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.results).toHaveLength(1);
+
+    const entry = result.results[0];
+    expect(entry).toHaveProperty('title');
+    expect(entry).toHaveProperty('date');
+    expect(entry).toHaveProperty('score');
+    expect(entry).toHaveProperty('type');
+    expect(entry).toHaveProperty('excerpt');
+    expect(entry.type).toBe('decision');
+    expect(entry.score).toBe(0.92);
+  });
+
+  it('score displayed as percentage in formatted output', async () => {
+    const mockResults = [
+      createMockResult({ score: 0.92 }),
+    ];
+    mockSemanticRecall.recall.mockResolvedValue(mockResults);
+
+    const result = await recallCmd.execute('/project', {
+      query: 'database architecture',
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.formatted).toBeDefined();
+    // 0.92 should appear as "92%" in the formatted output
+    expect(result.formatted).toMatch(/92%/);
+  });
+
+  it('--scope flag filters correctly (passes scope to semanticRecall)', async () => {
+    mockSemanticRecall.recall.mockResolvedValue([]);
+
+    await recallCmd.execute('/project', {
+      query: 'test query',
+      scope: 'workspace',
+    });
+
+    expect(mockSemanticRecall.recall).toHaveBeenCalledWith(
+      'test query',
+      expect.objectContaining({}),
+      expect.objectContaining({ scope: 'workspace' }),
+    );
+
+    // Test with project scope
+    await recallCmd.execute('/project', {
+      query: 'test query',
+      scope: 'project',
+    });
+
+    expect(mockSemanticRecall.recall).toHaveBeenCalledWith(
+      'test query',
+      expect.objectContaining({}),
+      expect.objectContaining({ scope: 'project' }),
+    );
+
+    // Test with global scope
+    await recallCmd.execute('/project', {
+      query: 'test query',
+      scope: 'global',
+    });
+
+    expect(mockSemanticRecall.recall).toHaveBeenCalledWith(
+      'test query',
+      expect.objectContaining({}),
+      expect.objectContaining({ scope: 'global' }),
+    );
+  });
+
+  it('--type flag filters correctly (passes types to semanticRecall)', async () => {
+    mockSemanticRecall.recall.mockResolvedValue([]);
+
+    await recallCmd.execute('/project', {
+      query: 'test query',
+      types: ['decision'],
+    });
+
+    expect(mockSemanticRecall.recall).toHaveBeenCalledWith(
+      'test query',
+      expect.objectContaining({}),
+      expect.objectContaining({ types: ['decision'] }),
+    );
+
+    // Test with multiple types
+    await recallCmd.execute('/project', {
+      query: 'test query',
+      types: ['decision', 'gotcha'],
+    });
+
+    expect(mockSemanticRecall.recall).toHaveBeenCalledWith(
+      'test query',
+      expect.objectContaining({}),
+      expect.objectContaining({ types: ['decision', 'gotcha'] }),
+    );
+  });
+
+  it('--limit flag respected', async () => {
+    mockSemanticRecall.recall.mockResolvedValue([]);
+
+    await recallCmd.execute('/project', {
+      query: 'test query',
+      limit: 3,
+    });
+
+    expect(mockSemanticRecall.recall).toHaveBeenCalledWith(
+      'test query',
+      expect.objectContaining({}),
+      expect.objectContaining({ limit: 3 }),
+    );
+  });
+
+  it('falls back gracefully when semanticRecall returns empty', async () => {
+    mockSemanticRecall.recall.mockResolvedValue([]);
+
+    const result = await recallCmd.execute('/project', {
+      query: 'nonexistent topic',
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.results).toEqual([]);
+    expect(result.formatted).toBeDefined();
+    // Should contain a helpful "no results" message
+    expect(result.formatted).toMatch(/no (results|memories|matches)/i);
+  });
+
+  it('source file path shown in results', async () => {
+    const mockResults = [
+      createMockResult({
+        source: {
+          project: 'my-project',
+          workspace: '/ws',
+          branch: 'main',
+          sourceFile: 'memory/decisions/use-sqlite.md',
+        },
+      }),
+    ];
+    mockSemanticRecall.recall.mockResolvedValue(mockResults);
+
+    const result = await recallCmd.execute('/project', {
+      query: 'sqlite',
+    });
+
+    expect(result.results[0]).toHaveProperty('sourceFile');
+    expect(result.results[0].sourceFile).toBe('memory/decisions/use-sqlite.md');
+    // Source file should also appear in the formatted output
+    expect(result.formatted).toContain('memory/decisions/use-sqlite.md');
+  });
+
+  it('permanent items marked with indicator in formatted output', async () => {
+    const mockResults = [
+      createMockResult({ id: 'mem-perm', permanent: true, score: 0.95 }),
+      createMockResult({ id: 'mem-temp', permanent: false, score: 0.80 }),
+    ];
+    mockSemanticRecall.recall.mockResolvedValue(mockResults);
+
+    const result = await recallCmd.execute('/project', {
+      query: 'something',
+    });
+
+    expect(result.results).toHaveLength(2);
+
+    const permResult = result.results.find((r) => r.permanent === true);
+    const tempResult = result.results.find((r) => r.permanent === false);
+    expect(permResult).toBeDefined();
+    expect(tempResult).toBeDefined();
+
+    // The formatted output should contain an indicator for the permanent item
+    // Common indicators: [PERMANENT], pin emoji, star, etc.
+    expect(result.formatted).toMatch(/permanent|\[PERMANENT\]|pinned/i);
+  });
+
+  it('empty/no results returns helpful message', async () => {
+    mockSemanticRecall.recall.mockResolvedValue([]);
+
+    const result = await recallCmd.execute('/project', {
+      query: 'completely unrelated topic xyz',
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.results).toEqual([]);
+    expect(result.formatted).toBeDefined();
+    expect(result.formatted.length).toBeGreaterThan(0);
+    // Should not just be empty — should tell the user nothing was found
+    expect(result.formatted).toMatch(/no (results|memories|matches)|nothing found/i);
+  });
+
+  it('empty query returns usage help', async () => {
+    const result = await recallCmd.execute('/project', {
+      query: '',
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.formatted).toBeDefined();
+    // Should contain usage instructions
+    expect(result.formatted).toMatch(/usage|query|provide/i);
+    // semanticRecall should NOT be called for empty queries
+    expect(mockSemanticRecall.recall).not.toHaveBeenCalled();
+  });
+});

package/server/lib/remember-command.js

@@ -0,0 +1,98 @@
+/**
+ * Remember Command
+ *
+ * Provides the /tlc:remember command that captures conversation context
+ * or explicit text as permanent memory entries.
+ *
+ * Permanent memories:
+ * - Have `permanent: true` in frontmatter and vector metadata
+ * - Are written to memory/conversations/ with [PERMANENT] prefix in title
+ * - Are indexed in the vector store with permanent = 1
+ * - Are never pruned or archived
+ *
+ * @module remember-command
+ */
+
+/**
+ * Creates a remember command instance with injected dependencies.
+ *
+ * @param {object} deps
+ * @param {object} deps.richCapture - Writer with writeConversationChunk(projectRoot, chunk)
+ * @param {object} deps.vectorIndexer - Indexer with indexChunk(projectRoot, chunk)
+ * @param {object} deps.embeddingClient - Client with embed(text) for generating embeddings
+ * @returns {{ execute: (projectRoot: string, options: object) => Promise<object> }}
+ */
+export function createRememberCommand({ richCapture, vectorIndexer, embeddingClient }) {
+  /**
+   * Execute the remember command.
+   *
+   * @param {string} projectRoot - Absolute path to the project root
+   * @param {object} options - Command options
+   * @param {string} [options.text] - Explicit text to remember
+   * @param {Array<{user: string, assistant: string, timestamp?: number}>} [options.exchanges] - Recent conversation exchanges
+   * @returns {Promise<{success: boolean, message: string, filePath?: string}>}
+   */
+  async function execute(projectRoot, options = {}) {
+    const { text, exchanges } = options;
+
+    // Handle empty text — return guidance
+    if (text !== undefined && !text) {
+      return {
+        success: false,
+        message:
+          'Please provide text to remember, or pass recent exchanges for automatic capture. ' +
+          'Usage: /tlc:remember "Always use UTC timestamps"',
+      };
+    }
+
+    // Build the chunk for richCapture
+    const chunk = {
+      permanent: true,
+    };
+
+    if (text) {
+      // Explicit text mode
+      chunk.title = `[PERMANENT] ${text}`;
+      chunk.topic = text;
+      chunk.content = text;
+      chunk.text = text;
+    } else if (exchanges && exchanges.length > 0) {
+      // Exchange capture mode
+      const summary = exchanges
+        .map((ex) => ex.user)
+        .join('; ')
+        .slice(0, 80);
+      chunk.title = `[PERMANENT] ${summary}`;
+      chunk.topic = summary;
+      chunk.exchanges = exchanges;
+      chunk.text = summary;
+    } else {
+      return {
+        success: false,
+        message:
+          'Nothing to remember. Provide text or recent exchanges. ' +
+          'Usage: /tlc:remember "Always use UTC timestamps"',
+      };
+    }
+
+    // Write the chunk to disk via richCapture
+    const filePath = await richCapture.writeConversationChunk(projectRoot, chunk);
+
+    // Index in the vector store with permanent flag
+    await vectorIndexer.indexChunk(projectRoot, {
+      ...chunk,
+      filePath,
+      permanent: true,
+    });
+
+    // Build confirmation message
+    const displayText = text || chunk.topic;
+    return {
+      success: true,
+      message: `Remembered permanently: ${displayText}`,
+      filePath,
+    };
+  }
+
+  return { execute };
+}

package/server/lib/remember-command.test.js

@@ -0,0 +1,288 @@
+/**
+ * Remember Command Tests
+ *
+ * Tests for the /tlc:remember command that captures conversation context
+ * or explicit text as permanent memory entries.
+ *
+ * Permanent memories:
+ * - Have `permanent: true` in frontmatter and vector metadata
+ * - Are written to memory/conversations/ with [PERMANENT] prefix in title
+ * - Are indexed in the vector store with permanent = 1
+ * - Are never pruned or archived
+ *
+ * These tests are written BEFORE the implementation (Red phase).
+ */
+
+import { describe, it, beforeEach, afterEach, expect, vi } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { createRememberCommand } from './remember-command.js';
+
+// ---------------------------------------------------------------------------
+// Mock factories
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a mock richCapture dependency with vi.fn() stubs.
+ * writeConversationChunk resolves to a deterministic file path.
+ * @param {string} projectRoot - Used to build the returned file path
+ * @returns {object}
+ */
+function createMockRichCapture(projectRoot) {
+  return {
+    writeConversationChunk: vi.fn().mockImplementation(async (root, chunk) => {
+      const convDir = path.join(root, 'memory', 'conversations');
+      const dateStr = new Date().toISOString().split('T')[0];
+      const slug = (chunk.topic || 'permanent-memory')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 60);
+      const filepath = path.join(convDir, `${dateStr}-${slug}.md`);
+      // Simulate file creation so downstream assertions can inspect it
+      fs.mkdirSync(convDir, { recursive: true });
+      const lines = [];
+      if (chunk.permanent) {
+        lines.push('---');
+        lines.push('permanent: true');
+        lines.push('---');
+        lines.push('');
+      }
+      lines.push(`# ${chunk.title}`);
+      lines.push('');
+      if (chunk.exchanges) {
+        for (const ex of chunk.exchanges) {
+          lines.push(`**User:** ${ex.user}`);
+          lines.push(`**Assistant:** ${ex.assistant}`);
+          lines.push('');
+        }
+      }
+      fs.writeFileSync(filepath, lines.join('\n'), 'utf8');
+      return filepath;
+    }),
+    writeDecisionDetail: vi.fn().mockResolvedValue('/mock/decision.md'),
+  };
+}
+
+/**
+ * Creates a mock vectorIndexer dependency.
+ * @returns {object}
+ */
+function createMockVectorIndexer() {
+  return {
+    indexChunk: vi.fn().mockResolvedValue({ success: true }),
+    indexFile: vi.fn().mockResolvedValue({ success: true }),
+    indexAll: vi.fn().mockResolvedValue({ indexed: 0, errors: 0 }),
+  };
+}
+
+/**
+ * Creates a mock embeddingClient dependency.
+ * @returns {object}
+ */
+function createMockEmbeddingClient() {
+  return {
+    embed: vi.fn().mockResolvedValue(new Float32Array(1024).fill(0.1)),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Sample data
+// ---------------------------------------------------------------------------
+
+/** Recent exchanges to simulate conversation context */
+const sampleExchanges = [
+  {
+    user: 'Should we always use UTC timestamps?',
+    assistant: 'Yes, UTC avoids timezone confusion in distributed systems.',
+    timestamp: Date.now() - 60000,
+  },
+  {
+    user: 'Even for user-facing display?',
+    assistant: 'Store UTC, convert to local for display.',
+    timestamp: Date.now() - 30000,
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('remember-command', () => {
+  let testDir;
+  let mockRichCapture;
+  let mockVectorIndexer;
+  let mockEmbeddingClient;
+  let remember;
+
+  beforeEach(() => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tlc-remember-cmd-test-'));
+    fs.mkdirSync(path.join(testDir, 'memory', 'conversations'), { recursive: true });
+
+    mockRichCapture = createMockRichCapture(testDir);
+    mockVectorIndexer = createMockVectorIndexer();
+    mockEmbeddingClient = createMockEmbeddingClient();
+
+    remember = createRememberCommand({
+      richCapture: mockRichCapture,
+      vectorIndexer: mockVectorIndexer,
+      embeddingClient: mockEmbeddingClient,
+    });
+  });
+
+  afterEach(() => {
+    fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  // -------------------------------------------------------------------------
+  // 1. Captures explicit text as permanent memory
+  // -------------------------------------------------------------------------
+  it('captures explicit text as permanent memory (writes file with permanent: true frontmatter)', async () => {
+    const result = await remember.execute(testDir, { text: 'Always use UTC timestamps' });
+
+    expect(result.success).toBe(true);
+
+    // richCapture.writeConversationChunk should have been called
+    expect(mockRichCapture.writeConversationChunk).toHaveBeenCalledTimes(1);
+
+    // The chunk passed to writeConversationChunk should have permanent: true
+    const calledChunk = mockRichCapture.writeConversationChunk.mock.calls[0][1];
+    expect(calledChunk.permanent).toBe(true);
+
+    // The written file should contain permanent: true in frontmatter
+    const writtenFile = result.filePath;
+    const content = fs.readFileSync(writtenFile, 'utf8');
+    expect(content).toMatch(/permanent:\s*true/);
+  });
+
+  // -------------------------------------------------------------------------
+  // 2. Captures recent exchanges when no text provided
+  // -------------------------------------------------------------------------
+  it('captures recent exchanges when no text provided', async () => {
+    const result = await remember.execute(testDir, { exchanges: sampleExchanges });
+
+    expect(result.success).toBe(true);
+
+    // Should have called writeConversationChunk with the exchanges
+    expect(mockRichCapture.writeConversationChunk).toHaveBeenCalledTimes(1);
+    const calledChunk = mockRichCapture.writeConversationChunk.mock.calls[0][1];
+    expect(calledChunk.exchanges).toBeDefined();
+    expect(calledChunk.exchanges.length).toBeGreaterThan(0);
+  });
+
+  // -------------------------------------------------------------------------
+  // 3. File written to memory/conversations/ directory
+  // -------------------------------------------------------------------------
+  it('file written to memory/conversations/ directory', async () => {
+    const result = await remember.execute(testDir, { text: 'Use named exports everywhere' });
+
+    expect(result.filePath).toBeDefined();
+
+    // File path should be under memory/conversations/
+    const convDir = path.join(testDir, 'memory', 'conversations');
+    expect(result.filePath.startsWith(convDir)).toBe(true);
+
+    // File should exist on disk
+    expect(fs.existsSync(result.filePath)).toBe(true);
+  });
+
+  // -------------------------------------------------------------------------
+  // 4. File has [PERMANENT] prefix in title
+  // -------------------------------------------------------------------------
+  it('file has [PERMANENT] prefix in title', async () => {
+    const result = await remember.execute(testDir, { text: 'Never commit .env files' });
+
+    expect(mockRichCapture.writeConversationChunk).toHaveBeenCalledTimes(1);
+    const calledChunk = mockRichCapture.writeConversationChunk.mock.calls[0][1];
+
+    // Title should start with [PERMANENT]
+    expect(calledChunk.title).toMatch(/^\[PERMANENT\]/);
+  });
+
+  // -------------------------------------------------------------------------
+  // 5. permanent: true set in frontmatter of written file
+  // -------------------------------------------------------------------------
+  it('permanent: true set in frontmatter of written file', async () => {
+    const result = await remember.execute(testDir, { text: 'Always run lint before commit' });
+
+    const content = fs.readFileSync(result.filePath, 'utf8');
+
+    // File should start with YAML frontmatter containing permanent: true
+    expect(content).toMatch(/^---\n[\s\S]*permanent:\s*true[\s\S]*\n---/);
+  });
+
+  // -------------------------------------------------------------------------
+  // 6. Vector indexer called with permanent flag
+  // -------------------------------------------------------------------------
+  it('vector indexer called with permanent flag', async () => {
+    await remember.execute(testDir, { text: 'Use Vitest for all tests' });
+
+    // indexChunk should have been called
+    expect(mockVectorIndexer.indexChunk).toHaveBeenCalledTimes(1);
+
+    // The chunk passed to indexChunk should have permanent: true (or permanent = 1)
+    const indexedChunk = mockVectorIndexer.indexChunk.mock.calls[0][1];
+    expect(indexedChunk.permanent).toBeTruthy();
+  });
+
+  // -------------------------------------------------------------------------
+  // 7. Returns success with confirmation message
+  // -------------------------------------------------------------------------
+  it('returns success with confirmation message', async () => {
+    const result = await remember.execute(testDir, { text: 'Always use UTC timestamps' });
+
+    expect(result.success).toBe(true);
+    expect(result.message).toBeDefined();
+    expect(result.message).toContain('Remembered permanently');
+    expect(result.message).toContain('Always use UTC timestamps');
+  });
+
+  // -------------------------------------------------------------------------
+  // 8. Returns file path in result
+  // -------------------------------------------------------------------------
+  it('returns file path in result', async () => {
+    const result = await remember.execute(testDir, { text: 'Prefer composition over inheritance' });
+
+    expect(result).toHaveProperty('filePath');
+    expect(typeof result.filePath).toBe('string');
+    expect(result.filePath.length).toBeGreaterThan(0);
+    // Should be an absolute path ending in .md
+    expect(result.filePath).toMatch(/\.md$/);
+  });
+
+  // -------------------------------------------------------------------------
+  // 9. Handles empty text gracefully (returns error/guidance)
+  // -------------------------------------------------------------------------
+  it('handles empty text gracefully (returns error/guidance)', async () => {
+    const result = await remember.execute(testDir, { text: '' });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toBeDefined();
+    // Should provide guidance about what to provide
+    expect(result.message.length).toBeGreaterThan(0);
+  });
+
+  // -------------------------------------------------------------------------
+  // 10. Phase 81: chunk.text must be set for vector indexing
+  // -------------------------------------------------------------------------
+  it('explicit text remember sets chunk.text on indexChunk call', async () => {
+    await remember.execute(testDir, { text: 'Always use UTC timestamps' });
+
+    expect(mockVectorIndexer.indexChunk).toHaveBeenCalledTimes(1);
+    const indexedChunk = mockVectorIndexer.indexChunk.mock.calls[0][1];
+    // chunk.text MUST be set — vectorIndexer.indexChunk only reads chunk.text
+    expect(indexedChunk.text).toBe('Always use UTC timestamps');
+  });
+
+  it('exchange capture sets chunk.text to exchange summary', async () => {
+    await remember.execute(testDir, { exchanges: sampleExchanges });
+
+    expect(mockVectorIndexer.indexChunk).toHaveBeenCalledTimes(1);
+    const indexedChunk = mockVectorIndexer.indexChunk.mock.calls[0][1];
+    // chunk.text MUST be non-empty for vector indexing to work
+    expect(indexedChunk.text).toBeDefined();
+    expect(typeof indexedChunk.text).toBe('string');
+    expect(indexedChunk.text.length).toBeGreaterThan(0);
+  });
+});