prjct-cli 0.52.0 → 0.54.0

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # Changelog
 
+## [0.54.0] - 2026-01-30
+
+### Features
+
+- Add showMetrics config option - PRJ-70 (#82)
+- Selective memory retrieval based on task relevance - PRJ-107 (#81)
+- Add session stats to p. stats command - PRJ-89 (#80)
+
+
+## [0.55.1] - 2026-01-30
+
+### Added
+
+- **showMetrics config option** (PRJ-70)
+  - Add `showMetrics` boolean to `LocalConfig` (prjct.config.json)
+  - Defaults to `true` for new projects and existing projects without setting
+  - Added `getShowMetrics()` and `setShowMetrics()` to ConfigManager
+
+
+## [0.55.0] - 2026-01-30
+
+### Features
+
+- Selective memory retrieval based on task relevance - PRJ-107
+
+
+## [0.55.0] - 2026-01-30
+
+### Added
+
+- **Selective memory retrieval based on task relevance** (PRJ-107)
+  - Added `getRelevantMemoriesWithMetrics()` for domain-based filtering
+  - Relevance scoring considers: domain match (25pts), tag match (20pts), recency (15pts), confidence (20pts), keywords (15pts), user triggered (5pts)
+  - Returns retrieval metrics: total, considered, returned, filtering ratio, avg score
+  - New types: `RelevantMemoryQuery`, `ScoredMemory`, `MemoryRetrievalResult`, `TaskDomain`
+  - Integrates with PRJ-104 confidence scoring
+
+
+## [0.54.0] - 2026-01-30
+
+### Features
+
+- Session stats in p. stats command - PRJ-89
+
+
+## [0.54.0] - 2026-01-30
+
+### Added
+
+- **Session stats in `p. stats` command** (PRJ-89)
+  - Shows today's activity: duration, tasks completed, features shipped
+  - Displays agents used during the session with frequency
+  - Shows learned patterns: decisions, preferences, workflows
+  - Enhanced JSON and export modes include session data
+  - Added `getRecentEvents()` to memoryService
+
+
+## [0.53.0] - 2026-01-30
+
+### Features
+
+- Lazy template loading with TTL cache - PRJ-76 (#79)
+
+
+## [0.53.0] - 2026-01-30
+
+### Features
+
+- Lazy template loading with TTL cache - PRJ-76
+
+
+## [0.53.0] - 2026-01-30
+
+### Added
+
+- **Lazy template loading with TTL cache** (PRJ-76)
+  - Templates now loaded on-demand with 60-second TTL cache
+  - Added `getTemplate()` method with per-file caching
+  - `loadChecklists()` and `loadChecklistRouting()` now use TTL cache
+  - Added `clearTemplateCache()` method for testing/forced refresh
+  - Reduces disk I/O for frequently accessed templates
+
+
 ## [0.52.0] - 2026-01-30
 
 ### Features

package/core/agentic/memory-system.ts

@@ -30,9 +30,13 @@ export type {
   MemoryContext,
   MemoryContextParams,
   MemoryDatabase,
+  MemoryRetrievalResult,
   MemoryTag,
   Patterns,
   Preference,
+  RelevantMemoryQuery,
+  ScoredMemory,
+  TaskDomain,
   Workflow,
 } from '../types/memory'
 
@@ -44,9 +48,13 @@ import type {
   Memory,
   MemoryContext,
   MemoryDatabase,
+  MemoryRetrievalResult,
   MemoryTag,
   Patterns,
   Preference,
+  RelevantMemoryQuery,
+  ScoredMemory,
+  TaskDomain,
   Workflow,
 } from '../types/memory'
 
@@ -690,6 +698,202 @@ export class SemanticMemories extends CachedStore<MemoryDatabase> {
       .map(({ _score, ...memory }) => memory as Memory)
   }
 
+  /**
+   * Enhanced memory retrieval with domain-based filtering and metrics.
+   * Implements selective memory retrieval based on task relevance.
+   * @see PRJ-107
+   */
+  async getRelevantMemoriesWithMetrics(
+    projectId: string,
+    query: RelevantMemoryQuery
+  ): Promise<MemoryRetrievalResult> {
+    const db = await this.load(projectId)
+    const totalMemories = db.memories.length
+
+    if (totalMemories === 0) {
+      return {
+        memories: [],
+        metrics: {
+          totalMemories: 0,
+          memoriesConsidered: 0,
+          memoriesReturned: 0,
+          filteringRatio: 0,
+          avgRelevanceScore: 0,
+        },
+      }
+    }
+
+    const maxResults = query.maxResults ?? 10
+    const minRelevance = query.minRelevance ?? 10
+
+    // Score all memories
+    const scored: ScoredMemory[] = db.memories.map((memory) => {
+      const breakdown = {
+        domainMatch: 0,
+        tagMatch: 0,
+        recency: 0,
+        confidence: 0,
+        keywords: 0,
+        userTriggered: 0,
+      }
+
+      // Domain match scoring (0-25 points)
+      if (query.taskDomain) {
+        const domainTags = this._getDomainTags(query.taskDomain)
+        const matchingTags = (memory.tags || []).filter((tag) => domainTags.includes(tag))
+        breakdown.domainMatch = Math.min(25, matchingTags.length * 10)
+      }
+
+      // Tag match from command context (0-20 points)
+      if (query.commandName) {
+        const commandTags = this._getCommandTags(query.commandName)
+        const matchingTags = (memory.tags || []).filter((tag) => commandTags.includes(tag))
+        breakdown.tagMatch = Math.min(20, matchingTags.length * 8)
+      }
+
+      // Recency scoring (0-15 points)
+      const age = Date.now() - new Date(memory.updatedAt).getTime()
+      const daysSinceUpdate = age / (1000 * 60 * 60 * 24)
+      breakdown.recency = Math.max(0, Math.round(15 - daysSinceUpdate * 0.5))
+
+      // Confidence scoring (0-20 points) - PRJ-104 integration
+      if (memory.confidence) {
+        breakdown.confidence =
+          memory.confidence === 'high' ? 20 : memory.confidence === 'medium' ? 12 : 5
+      } else if (memory.observationCount) {
+        // Fallback to observation count
+        breakdown.confidence = Math.min(20, memory.observationCount * 3)
+      }
+
+      // Keyword matching (0-15 points)
+      if (query.taskDescription) {
+        const keywords = this._extractKeywordsFromText(query.taskDescription)
+        let keywordScore = 0
+        for (const keyword of keywords) {
+          if (memory.content.toLowerCase().includes(keyword)) keywordScore += 2
+          if (memory.title.toLowerCase().includes(keyword)) keywordScore += 3
+        }
+        breakdown.keywords = Math.min(15, keywordScore)
+      }
+
+      // User triggered bonus (0-5 points)
+      if (memory.userTriggered) {
+        breakdown.userTriggered = 5
+      }
+
+      const relevanceScore =
+        breakdown.domainMatch +
+        breakdown.tagMatch +
+        breakdown.recency +
+        breakdown.confidence +
+        breakdown.keywords +
+        breakdown.userTriggered
+
+      return {
+        ...memory,
+        relevanceScore,
+        scoreBreakdown: breakdown,
+      }
+    })
+
+    // Filter by minimum relevance
+    const considered = scored.filter((m) => m.relevanceScore >= minRelevance)
+
+    // Sort by relevance and take top N
+    const sorted = considered.sort((a, b) => b.relevanceScore - a.relevanceScore)
+    const returned = sorted.slice(0, maxResults)
+
+    // Calculate average relevance
+    const avgRelevanceScore =
+      returned.length > 0
+        ? Math.round(returned.reduce((sum, m) => sum + m.relevanceScore, 0) / returned.length)
+        : 0
+
+    return {
+      memories: returned,
+      metrics: {
+        totalMemories,
+        memoriesConsidered: considered.length,
+        memoriesReturned: returned.length,
+        filteringRatio: totalMemories > 0 ? returned.length / totalMemories : 0,
+        avgRelevanceScore,
+      },
+    }
+  }
+
+  /**
+   * Map task domain to relevant memory tags.
+   * @see PRJ-107
+   */
+  private _getDomainTags(domain: TaskDomain): MemoryTag[] {
+    const domainTagMap: Record<TaskDomain, MemoryTag[]> = {
+      frontend: [MEMORY_TAGS.CODE_STYLE, MEMORY_TAGS.FILE_STRUCTURE, MEMORY_TAGS.ARCHITECTURE],
+      backend: [
+        MEMORY_TAGS.CODE_STYLE,
+        MEMORY_TAGS.ARCHITECTURE,
+        MEMORY_TAGS.DEPENDENCIES,
+        MEMORY_TAGS.TECH_STACK,
+      ],
+      devops: [MEMORY_TAGS.SHIP_WORKFLOW, MEMORY_TAGS.TEST_BEHAVIOR, MEMORY_TAGS.DEPENDENCIES],
+      docs: [MEMORY_TAGS.CODE_STYLE, MEMORY_TAGS.NAMING_CONVENTION],
+      testing: [MEMORY_TAGS.TEST_BEHAVIOR, MEMORY_TAGS.CODE_STYLE],
+      database: [MEMORY_TAGS.ARCHITECTURE, MEMORY_TAGS.NAMING_CONVENTION],
+      general: Object.values(MEMORY_TAGS) as MemoryTag[],
+    }
+    return domainTagMap[domain] || []
+  }
+
+  /**
+   * Map command to relevant memory tags.
+   * @see PRJ-107
+   */
+  private _getCommandTags(commandName: string): MemoryTag[] {
+    const commandTags: Record<string, MemoryTag[]> = {
+      ship: [MEMORY_TAGS.COMMIT_STYLE, MEMORY_TAGS.SHIP_WORKFLOW, MEMORY_TAGS.TEST_BEHAVIOR],
+      feature: [MEMORY_TAGS.ARCHITECTURE, MEMORY_TAGS.CODE_STYLE],
+      done: [MEMORY_TAGS.SHIP_WORKFLOW],
+      analyze: [MEMORY_TAGS.TECH_STACK, MEMORY_TAGS.ARCHITECTURE],
+      spec: [MEMORY_TAGS.ARCHITECTURE, MEMORY_TAGS.CODE_STYLE],
+      task: [MEMORY_TAGS.BRANCH_NAMING, MEMORY_TAGS.CODE_STYLE],
+      sync: [MEMORY_TAGS.TECH_STACK, MEMORY_TAGS.ARCHITECTURE, MEMORY_TAGS.DEPENDENCIES],
+      test: [MEMORY_TAGS.TEST_BEHAVIOR],
+      bug: [MEMORY_TAGS.CODE_STYLE, MEMORY_TAGS.TEST_BEHAVIOR],
+    }
+    return commandTags[commandName] || []
+  }
+
+  /**
+   * Extract keywords from text for matching.
+   */
+  private _extractKeywordsFromText(text: string): string[] {
+    const words = text.toLowerCase().split(/\s+/)
+    const stopWords = new Set([
+      'the',
+      'a',
+      'an',
+      'is',
+      'are',
+      'to',
+      'for',
+      'and',
+      'or',
+      'in',
+      'on',
+      'at',
+      'by',
+      'with',
+      'from',
+      'as',
+      'it',
+      'this',
+      'that',
+      'be',
+      'have',
+      'has',
+    ])
+    return words.filter((w) => w.length > 2 && !stopWords.has(w))
+  }
+
   private _extractContextTags(context: MemoryContext): string[] {
     const tags: string[] = []
 
@@ -863,6 +1067,18 @@ export class MemorySystem {
     return this._semanticMemories.getMemoryStats(projectId)
   }
 
+  /**
+   * Get relevant memories with domain-based filtering and metrics.
+   * Implements selective memory retrieval based on task relevance.
+   * @see PRJ-107
+   */
+  getRelevantMemoriesWithMetrics(
+    projectId: string,
+    query: RelevantMemoryQuery
+  ): Promise<MemoryRetrievalResult> {
+    return this._semanticMemories.getRelevantMemoriesWithMetrics(projectId, query)
+  }
+
   // ===========================================================================
   // TIER 1: Session Memory
   // ===========================================================================

package/core/agentic/prompt-builder.ts

@@ -43,17 +43,73 @@ type Agent = PromptAgent
 type Context = PromptContext
 type State = PromptState
 
+/**
+ * Cached template entry with TTL support
+ * @see PRJ-76
+ */
+interface CachedTemplate {
+  content: string
+  loadedAt: number
+}
+
 /**
  * Builds prompts for Claude using templates, context, and learned patterns.
  * Supports plan mode, think blocks, and quality checklists.
  * Auto-injects unified state and performance insights.
+ *
+ * Uses lazy loading for templates with 60s TTL cache.
+ * @see PRJ-76
  */
 class PromptBuilder {
   private _checklistsCache: Record<string, string> | null = null
+  private _checklistsCacheTime: number = 0
   private _checklistRoutingCache: string | null = null
+  private _checklistRoutingCacheTime: number = 0
   private _currentContext: Context | null = null
   private _stateCache: Map<string, { state: ProjectState; timestamp: number }> = new Map()
   private _stateCacheTTL = 5000 // 5 seconds
+  private _templateCache: Map<string, CachedTemplate> = new Map()
+  private readonly TEMPLATE_CACHE_TTL_MS = 60_000 // 60 seconds
+
+  /**
+   * Get a template with TTL caching.
+   * Returns cached content if within TTL, otherwise loads from disk.
+   * @see PRJ-76
+   */
+  getTemplate(templatePath: string): string | null {
+    const cached = this._templateCache.get(templatePath)
+    const now = Date.now()
+
+    if (cached && now - cached.loadedAt < this.TEMPLATE_CACHE_TTL_MS) {
+      return cached.content
+    }
+
+    try {
+      if (fs.existsSync(templatePath)) {
+        const content = fs.readFileSync(templatePath, 'utf-8')
+        this._templateCache.set(templatePath, { content, loadedAt: now })
+        return content
+      }
+    } catch (error) {
+      if (!isNotFoundError(error)) {
+        console.error(`Template loading warning: ${(error as Error).message}`)
+      }
+    }
+
+    return null
+  }
+
+  /**
+   * Clear the template cache (for testing or forced refresh)
+   * @see PRJ-76
+   */
+  clearTemplateCache(): void {
+    this._templateCache.clear()
+    this._checklistsCache = null
+    this._checklistsCacheTime = 0
+    this._checklistRoutingCache = null
+    this._checklistRoutingCacheTime = 0
+  }
 
   /**
    * Reset context (for testing)
@@ -71,9 +127,16 @@ class PromptBuilder {
 
   /**
    * Load quality checklists from templates/checklists/
+   * Uses lazy loading with TTL cache.
+   * @see PRJ-76
    */
   loadChecklists(): Record<string, string> {
-    if (this._checklistsCache) return this._checklistsCache
+    const now = Date.now()
+
+    // Check if cache is still valid
+    if (this._checklistsCache && now - this._checklistsCacheTime < this.TEMPLATE_CACHE_TTL_MS) {
+      return this._checklistsCache
+    }
 
     const checklistsDir = path.join(__dirname, '..', '..', 'templates', 'checklists')
     const checklists: Record<string, string> = {}
@@ -83,8 +146,12 @@ class PromptBuilder {
         const files = fs.readdirSync(checklistsDir).filter((f) => f.endsWith('.md'))
         for (const file of files) {
           const name = file.replace('.md', '')
-          const content = fs.readFileSync(path.join(checklistsDir, file), 'utf-8')
-          checklists[name] = content
+          const templatePath = path.join(checklistsDir, file)
+          // Use getTemplate for individual files to leverage per-file caching
+          const content = this.getTemplate(templatePath)
+          if (content) {
+            checklists[name] = content
+          }
         }
       }
     } catch (error) {
@@ -95,6 +162,7 @@ class PromptBuilder {
     }
 
     this._checklistsCache = checklists
+    this._checklistsCacheTime = now
     return checklists
   }
 
@@ -215,9 +283,19 @@ class PromptBuilder {
 
   /**
    * Load checklist routing template for Claude to decide which checklists apply
+   * Uses lazy loading with TTL cache.
+   * @see PRJ-76
    */
   loadChecklistRouting(): string | null {
-    if (this._checklistRoutingCache) return this._checklistRoutingCache
+    const now = Date.now()
+
+    // Check if cache is still valid
+    if (
+      this._checklistRoutingCache &&
+      now - this._checklistRoutingCacheTime < this.TEMPLATE_CACHE_TTL_MS
+    ) {
+      return this._checklistRoutingCache
+    }
 
     const routingPath = path.join(
       __dirname,
@@ -228,15 +306,11 @@ class PromptBuilder {
       'checklist-routing.md'
     )
 
-    try {
-      if (fs.existsSync(routingPath)) {
-        this._checklistRoutingCache = fs.readFileSync(routingPath, 'utf-8')
-      }
-    } catch (error) {
-      // Silent fail - checklist routing is optional
-      if (!isNotFoundError(error)) {
-        console.error(`Checklist routing warning: ${(error as Error).message}`)
-      }
+    // Use getTemplate for consistent caching behavior
+    const content = this.getTemplate(routingPath)
+    if (content) {
+      this._checklistRoutingCache = content
+      this._checklistRoutingCacheTime = now
     }
 
     return this._checklistRoutingCache || null