feat: unified recall across notes and trailers (GIT-68)

src/application/services/MemoryService.ts

@@ -2,34 +2,204 @@
  * MemoryService
  *
  * Application service that orchestrates memory operations.
- * Delegates storage to IMemoryRepository.
+ * Dual-writes to git notes (rich JSON) and commit trailers
+ * (lightweight, natively queryable metadata).
  */
 
 import type { IMemoryService } from '../interfaces/IMemoryService';
 import type { IMemoryRepository, IMemoryQueryOptions, IMemoryQueryResult } from '../../domain/interfaces/IMemoryRepository';
-import type { IMemoryEntity, ICreateMemoryOptions } from '../../domain/entities/IMemoryEntity';
+import type { IMemoryEntity, ICreateMemoryOptions, MemoryType } from '../../domain/entities/IMemoryEntity';
+import type { ITrailerService, ICommitTrailers } from '../../domain/interfaces/ITrailerService';
+import type { ITrailer } from '../../domain/entities/ITrailer';
+import { AI_TRAILER_KEYS, AI_TRAILER_PREFIX } from '../../domain/entities/ITrailer';
+import type { ConfidenceLevel } from '../../domain/types/IMemoryQuality';
 import type { ILogger } from '../../domain/interfaces/ILogger';
 
+const MEMORY_TYPE_TO_TRAILER_KEY: Record<MemoryType, string> = {
+  decision: AI_TRAILER_KEYS.DECISION,
+  gotcha: AI_TRAILER_KEYS.GOTCHA,
+  convention: AI_TRAILER_KEYS.CONVENTION,
+  fact: AI_TRAILER_KEYS.FACT,
+};
+
+const TRAILER_KEY_TO_MEMORY_TYPE: Record<string, MemoryType> = {
+  [AI_TRAILER_KEYS.DECISION]: 'decision',
+  [AI_TRAILER_KEYS.GOTCHA]: 'gotcha',
+  [AI_TRAILER_KEYS.CONVENTION]: 'convention',
+  [AI_TRAILER_KEYS.FACT]: 'fact',
+};
+
 export class MemoryService implements IMemoryService {
   constructor(
     private readonly memoryRepository: IMemoryRepository,
     private readonly logger?: ILogger,
+    private readonly trailerService?: ITrailerService,
   ) {}
 
   remember(text: string, options?: ICreateMemoryOptions): IMemoryEntity {
     const memory = this.memoryRepository.create(text, options);
     this.logger?.info('Memory stored', { id: memory.id, type: memory.type, sha: memory.sha });
+
+    // Dual-write: also add AI-* trailers to the commit (opt-out via trailers: false)
+    if (options?.trailers !== false && this.trailerService) {
+      try {
+        const trailers = this.buildTrailers(memory);
+        this.trailerService.addTrailers(trailers, options?.cwd);
+        this.logger?.info('Trailers written', { count: trailers.length, sha: memory.sha });
+      } catch (err) {
+        // Trailer write failure is non-fatal (commit may be pushed already)
+        this.logger?.warn('Trailer write failed', {
+          error: err instanceof Error ? err.message : String(err),
+          sha: memory.sha,
+        });
+      }
+    }
+
     return memory;
   }
 
+  private buildTrailers(memory: IMemoryEntity): ITrailer[] {
+    const trailers: ITrailer[] = [
+      { key: MEMORY_TYPE_TO_TRAILER_KEY[memory.type], value: memory.content },
+      { key: AI_TRAILER_KEYS.CONFIDENCE, value: memory.confidence },
+      { key: AI_TRAILER_KEYS.MEMORY_ID, value: memory.id },
+    ];
+
+    if (memory.tags.length > 0) {
+      trailers.push({ key: AI_TRAILER_KEYS.TAGS, value: memory.tags.join(', ') });
+    }
+
+    return trailers;
+  }
+
   recall(query?: string, options?: IMemoryQueryOptions): IMemoryQueryResult {
     const effectiveQuery = query ?? options?.query;
-    const result = this.memoryRepository.query({
+
+    // 1. Search notes (existing path)
+    const notesResult = this.memoryRepository.query({
       ...options,
       query: effectiveQuery,
     });
-    this.logger?.info('Memory recall', { query: effectiveQuery, count: result.memories.length, total: result.total });
-    return result;
+
+    // 2. Search trailers if service available
+    if (!this.trailerService) {
+      this.logger?.info('Memory recall', { query: effectiveQuery, count: notesResult.memories.length, total: notesResult.total });
+      return notesResult;
+    }
+
+    const trailerMemories = this.recallFromTrailers(effectiveQuery, options, notesResult.memories);
+
+    // 3. Merge results (notes first, then trailer-only)
+    const allMemories = [...notesResult.memories, ...trailerMemories];
+    const limit = options?.limit ?? allMemories.length;
+    const merged = allMemories.slice(0, limit);
+
+    this.logger?.info('Memory recall', {
+      query: effectiveQuery,
+      notesCount: notesResult.memories.length,
+      trailerCount: trailerMemories.length,
+      total: allMemories.length,
+    });
+
+    return {
+      memories: merged,
+      total: allMemories.length,
+    };
+  }
+
+  private recallFromTrailers(
+    query: string | undefined,
+    options: IMemoryQueryOptions | undefined,
+    notesMemories: readonly IMemoryEntity[],
+  ): IMemoryEntity[] {
+    if (!this.trailerService) return [];
+
+    try {
+      const trailerCommits = this.trailerService.queryTrailers(AI_TRAILER_PREFIX, {
+        cwd: options?.cwd,
+        since: options?.since,
+      });
+
+      // IDs already present in notes results (for deduplication)
+      const noteIds = new Set(notesMemories.map(m => m.id));
+
+      const results: IMemoryEntity[] = [];
+
+      for (const commit of trailerCommits) {
+        const entities = this.trailerCommitToEntities(commit);
+
+        for (const entity of entities) {
+          // Deduplicate: skip if AI-Memory-Id matches a notes entry
+          if (noteIds.has(entity.id)) continue;
+
+          // Apply query filter
+          if (query && !this.matchesQuery(entity, query)) continue;
+
+          // Apply type filter
+          if (options?.type && entity.type !== options.type) continue;
+
+          // Apply tag filter
+          if (options?.tag && !entity.tags.some(t => t.toLowerCase() === options.tag!.toLowerCase())) continue;
+
+          results.push(entity);
+        }
+      }
+
+      return results;
+    } catch (err) {
+      this.logger?.warn('Trailer recall failed', {
+        error: err instanceof Error ? err.message : String(err),
+      });
+      return [];
+    }
+  }
+
+  private trailerCommitToEntities(commit: ICommitTrailers): IMemoryEntity[] {
+    const entities: IMemoryEntity[] = [];
+
+    // Find all memory-type trailers on this commit
+    const typeTrailers = commit.trailers.filter(t => t.key in TRAILER_KEY_TO_MEMORY_TYPE);
+    if (typeTrailers.length === 0) return entities;
+
+    // Collect all AI-Memory-Ids (one per remember() call)
+    const memoryIds = commit.trailers
+      .filter(t => t.key === AI_TRAILER_KEYS.MEMORY_ID)
+      .map(t => t.value);
+
+    // Shared metadata from the commit's trailers
+    const confidence = (commit.trailers.find(t => t.key === AI_TRAILER_KEYS.CONFIDENCE)?.value || 'high') as ConfidenceLevel;
+    const tagsStr = commit.trailers.find(t => t.key === AI_TRAILER_KEYS.TAGS)?.value;
+    const tags: readonly string[] = tagsStr ? tagsStr.split(',').map(t => t.trim()) : [];
+
+    for (let i = 0; i < typeTrailers.length; i++) {
+      const typeTrailer = typeTrailers[i];
+      const type = TRAILER_KEY_TO_MEMORY_TYPE[typeTrailer.key];
+      if (!type) continue;
+
+      // Pair with AI-Memory-Id by position, or generate synthetic ID
+      const id = memoryIds[i] || `trailer:${commit.sha}:${type}`;
+
+      entities.push({
+        id,
+        content: typeTrailer.value,
+        type,
+        sha: commit.sha,
+        confidence,
+        source: 'commit-trailer',
+        lifecycle: 'project',
+        tags,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      });
+    }
+
+    return entities;
+  }
+
+  private matchesQuery(entity: IMemoryEntity, query: string): boolean {
+    const lower = query.toLowerCase();
+    return entity.content.toLowerCase().includes(lower) ||
+      entity.tags.some(t => t.toLowerCase().includes(lower));
   }
 
   get(id: string, cwd?: string): IMemoryEntity | null {

src/cli.ts

@@ -36,6 +36,7 @@ program
   .option('--confidence <level>', 'Confidence: verified, high, medium, low', 'high')
   .option('--lifecycle <tier>', 'Lifecycle: permanent, project, session', 'project')
   .option('--tags <tags>', 'Comma-separated tags')
+  .option('--no-trailers', 'Skip writing AI-* trailers to the commit message')
   .action((text, options) => rememberCommand(text, options, logger));
 
 program

src/commands/remember.ts

@@ -14,6 +14,7 @@ interface IRememberOptions {
   confidence?: string;
   lifecycle?: string;
   tags?: string;
+  noTrailers?: boolean;
 }
 
 export async function rememberCommand(text: string, options: IRememberOptions, logger?: ILogger): Promise<void> {
@@ -27,6 +28,7 @@ export async function rememberCommand(text: string, options: IRememberOptions, l
     confidence: (options.confidence || 'high') as ConfidenceLevel,
     lifecycle: (options.lifecycle || 'project') as MemoryLifecycle,
     tags: options.tags,
+    trailers: !options.noTrailers,
   });
 
   console.log(`Remembered: ${memory.content}`);

src/domain/entities/IMemoryEntity.ts

@@ -69,6 +69,8 @@ export interface ICreateMemoryOptions {
   readonly source?: SourceType;
   /** Working directory. */
   readonly cwd?: string;
+  /** Write AI-* trailers to the commit message (default: true). */
+  readonly trailers?: boolean;
 }
 
 /**

src/domain/interfaces/ITrailerService.ts

@@ -58,4 +58,21 @@ export interface ITrailerService {
    * @returns Array of commits with matching trailers.
    */
   queryTrailers(key: string, options?: ITrailerQueryOptions): ICommitTrailers[];
+
+  /**
+   * Amend HEAD commit to append AI-* trailers to the commit message.
+   * Preserves existing trailers and skips duplicates.
+   * @param trailers - Trailers to add.
+   * @param cwd - Working directory.
+   */
+  addTrailers(trailers: readonly ITrailer[], cwd?: string): void;
+
+  /**
+   * Build a commit message with trailers appended.
+   * Pure string operation — no git commands.
+   * @param message - Original commit message.
+   * @param trailers - Trailers to append.
+   * @returns Complete commit message with trailer block.
+   */
+  buildCommitMessage(message: string, trailers: readonly ITrailer[]): string;
 }

src/infrastructure/di/container.ts

@@ -21,6 +21,7 @@ import type { IGitClient } from '../../domain/interfaces/IGitClient';
 import { NotesService } from '../services/NotesService';
 import { GitClient } from '../git/GitClient';
 import { MemoryRepository } from '../repositories/MemoryRepository';
+import { TrailerService } from '../services/TrailerService';
 import { EventBus } from '../events/EventBus';
 import { createLogger } from '../logging/factory';
 import { createLLMClient } from '../llm/LLMClientFactory';
@@ -55,6 +56,7 @@ export function createContainer(options?: IContainerOptions): AwilixContainer<IC
     notesService: asClass(NotesService).singleton(),
     gitClient: asClass(GitClient).singleton(),
     memoryRepository: asClass(MemoryRepository).singleton(),
+    trailerService: asClass(TrailerService).singleton(),
 
     eventBus: asFunction(() => {
       const bus = new EventBus(container.cradle.logger);

src/infrastructure/di/types.ts

@@ -23,13 +23,15 @@ import type { ILiberateService } from '../../application/interfaces/ILiberateSer
 import type { IMemoryContextLoader } from '../../domain/interfaces/IMemoryContextLoader';
 import type { IContextFormatter } from '../../domain/interfaces/IContextFormatter';
 import type { ISessionCaptureService } from '../../domain/interfaces/ISessionCaptureService';
+import type { ITrailerService } from '../../domain/interfaces/ITrailerService';
 
 export interface ICradle {
   // Infrastructure
   logger: ILogger;
   notesService: INotesService;
   gitClient: IGitClient;
   memoryRepository: IMemoryRepository;
+  trailerService: ITrailerService;
   triageService: IGitTriageService;
   llmClient: ILLMClient | null;
   eventBus: IEventBus;

src/infrastructure/services/TrailerService.ts

@@ -92,6 +92,61 @@ export class TrailerService implements ITrailerService {
     }
   }
 
+  addTrailers(trailers: readonly ITrailer[], cwd?: string): void {
+    // Only operate on AI-* trailers to match readTrailers/parseTrailerBlock behavior.
+    const aiTrailers = trailers.filter(t => t.key.startsWith(AI_TRAILER_PREFIX));
+    if (aiTrailers.length === 0) return;
+
+    // Read existing trailers to avoid duplicates
+    const existing = this.readTrailers('HEAD', cwd);
+    const existingKeys = new Set(existing.map(t => `${t.key}:${t.value}`));
+    const newTrailers = aiTrailers.filter(t => !existingKeys.has(`${t.key}:${t.value}`));
+    if (newTrailers.length === 0) return;
+
+    // Get current commit message
+    const currentMessage = execFileSync(
+      'git',
+      ['log', '-1', '--format=%B', 'HEAD'],
+      { encoding: 'utf8', cwd, stdio: ['pipe', 'pipe', 'pipe'] }
+    ).trimEnd();
+
+    // Build amended message with new trailers
+    const amended = this.buildCommitMessage(currentMessage, newTrailers);
+
+    // Amend HEAD with the new message
+    execFileSync(
+      'git',
+      ['commit', '--amend', '--no-edit', '-m', amended],
+      { encoding: 'utf8', cwd, stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+  }
+
+  buildCommitMessage(message: string, trailers: readonly ITrailer[]): string {
+    if (trailers.length === 0) return message;
+
+    const trailerBlock = this.formatTrailers(trailers);
+    const trimmed = message.trimEnd();
+
+    // Detect existing trailer block: lines after the last blank line
+    // must all match "Key: Value" format (git trailer convention).
+    if (this.hasTrailerBlock(trimmed)) {
+      return `${trimmed}\n${trailerBlock}\n`;
+    }
+
+    return `${trimmed}\n\n${trailerBlock}\n`;
+  }
+
+  private hasTrailerBlock(message: string): boolean {
+    const lastBlankIdx = message.lastIndexOf('\n\n');
+    if (lastBlankIdx === -1) return false;
+
+    const afterBlank = message.slice(lastBlankIdx + 2).trim();
+    if (!afterBlank) return false;
+
+    const lines = afterBlank.split('\n').filter(l => l.trim().length > 0);
+    return lines.length > 0 && lines.every(l => /^[\w-]+:\s/.test(l));
+  }
+
   private parseTrailerBlock(block: string): ITrailer[] {
     const trailers: ITrailer[] = [];
     const lines = block.split('\n');

src/mcp/tools/remember.ts

@@ -22,6 +22,7 @@ export function registerRememberTool(server: McpServer): void {
       confidence: z.enum(['verified', 'high', 'medium', 'low']).optional().describe('Confidence level (default: high)'),
       tags: z.string().optional().describe('Comma-separated tags'),
       lifecycle: z.enum(['permanent', 'project', 'session']).optional().describe('Lifecycle tier (default: project)'),
+      trailers: z.boolean().optional().describe('Write AI-* trailers to commit message (default: true)'),
     },
     async (args) => {
       const container = createContainer({ scope: 'mcp:remember' });
@@ -35,6 +36,7 @@ export function registerRememberTool(server: McpServer): void {
           confidence: (args.confidence || 'high') as ConfidenceLevel,
           lifecycle: (args.lifecycle || 'project') as MemoryLifecycle,
           tags: args.tags,
+          trailers: args.trailers,
         });
 
         return {