prjct-cli 0.11.5 → 0.12.0

package/core/agentic/memory-system/index.ts

@@ -0,0 +1,192 @@
+/**
+ * Layered Memory System
+ * Three-tier memory for learning user patterns and preferences.
+ *
+ * @module agentic/memory-system
+ * @version 3.3
+ */
+
+import { SemanticMemories } from './semantic-memories'
+import { PatternStore } from './patterns'
+import { HistoryStore } from './history'
+import { SessionStore } from './session'
+import type { Memory, Context, Workflow } from './types'
+export { MEMORY_TAGS } from './types'
+
+/**
+ * Three-tier memory system for learning user patterns.
+ * Tier 1: Session (ephemeral), Tier 2: Patterns (persistent), Tier 3: History (JSONL)
+ */
+class MemorySystem {
+  private _semanticMemories: SemanticMemories
+  private _patternStore: PatternStore
+  private _historyStore: HistoryStore
+  private _sessionStore: SessionStore
+
+  constructor() {
+    this._semanticMemories = new SemanticMemories()
+    this._patternStore = new PatternStore()
+    this._historyStore = new HistoryStore()
+    this._sessionStore = new SessionStore()
+  }
+
+  // ═══════════════════════════════════════════════════════════
+  // P3.3: SEMANTIC MEMORIES
+  // ═══════════════════════════════════════════════════════════
+
+  loadMemories(projectId: string) {
+    return this._semanticMemories.loadMemories(projectId)
+  }
+
+  saveMemories(projectId: string) {
+    return this._semanticMemories.saveMemories(projectId)
+  }
+
+  createMemory(
+    projectId: string,
+    options: { title: string; content: string; tags?: string[]; userTriggered?: boolean }
+  ): Promise<string> {
+    return this._semanticMemories.createMemory(projectId, options)
+  }
+
+  updateMemory(
+    projectId: string,
+    memoryId: string,
+    updates: { title?: string; content?: string; tags?: string[] }
+  ): Promise<boolean> {
+    return this._semanticMemories.updateMemory(projectId, memoryId, updates)
+  }
+
+  deleteMemory(projectId: string, memoryId: string): Promise<boolean> {
+    return this._semanticMemories.deleteMemory(projectId, memoryId)
+  }
+
+  findByTags(projectId: string, tags: string[], matchAll?: boolean): Promise<Memory[]> {
+    return this._semanticMemories.findByTags(projectId, tags, matchAll)
+  }
+
+  searchMemories(projectId: string, query: string): Promise<Memory[]> {
+    return this._semanticMemories.searchMemories(projectId, query)
+  }
+
+  getRelevantMemories(projectId: string, context: Context, limit?: number): Promise<Memory[]> {
+    return this._semanticMemories.getRelevantMemories(projectId, context, limit)
+  }
+
+  autoRemember(projectId: string, decisionType: string, value: string, context?: string): Promise<void> {
+    return this._semanticMemories.autoRemember(projectId, decisionType, value, context)
+  }
+
+  getAllMemories(projectId: string): Promise<Memory[]> {
+    return this._semanticMemories.getAllMemories(projectId)
+  }
+
+  getMemoryStats(projectId: string) {
+    return this._semanticMemories.getMemoryStats(projectId)
+  }
+
+  // ═══════════════════════════════════════════════════════════
+  // TIER 1: Session Memory
+  // ═══════════════════════════════════════════════════════════
+
+  setSession(key: string, value: unknown): void {
+    this._sessionStore.setSession(key, value)
+  }
+
+  getSession(key: string): unknown {
+    return this._sessionStore.getSession(key)
+  }
+
+  clearSession(): void {
+    this._sessionStore.clearSession()
+  }
+
+  // ═══════════════════════════════════════════════════════════
+  // TIER 2: Patterns
+  // ═══════════════════════════════════════════════════════════
+
+  loadPatterns(projectId: string) {
+    return this._patternStore.loadPatterns(projectId)
+  }
+
+  savePatterns(projectId: string) {
+    return this._patternStore.savePatterns(projectId)
+  }
+
+  recordDecision(projectId: string, key: string, value: string, context?: string): Promise<void> {
+    return this._patternStore.recordDecision(projectId, key, value, context)
+  }
+
+  getDecision(projectId: string, key: string): Promise<{ value: string; confidence: string } | null> {
+    return this._patternStore.getDecision(projectId, key)
+  }
+
+  hasPattern(projectId: string, key: string): Promise<boolean> {
+    return this._patternStore.hasPattern(projectId, key)
+  }
+
+  recordWorkflow(projectId: string, workflowName: string, pattern: Record<string, unknown>): Promise<void> {
+    return this._patternStore.recordWorkflow(projectId, workflowName, pattern)
+  }
+
+  getWorkflow(projectId: string, workflowName: string): Promise<Workflow | null> {
+    return this._patternStore.getWorkflow(projectId, workflowName)
+  }
+
+  setPreference(projectId: string, key: string, value: unknown): Promise<void> {
+    return this._patternStore.setPreference(projectId, key, value)
+  }
+
+  getPreference(projectId: string, key: string, defaultValue?: unknown): Promise<unknown> {
+    return this._patternStore.getPreference(projectId, key, defaultValue)
+  }
+
+  getPatternsSummary(projectId: string) {
+    return this._patternStore.getPatternsSummary(projectId)
+  }
+
+  // ═══════════════════════════════════════════════════════════
+  // TIER 3: History
+  // ═══════════════════════════════════════════════════════════
+
+  appendHistory(projectId: string, entry: Record<string, unknown>): Promise<void> {
+    return this._historyStore.appendHistory(projectId, entry)
+  }
+
+  getRecentHistory(projectId: string, limit?: number) {
+    return this._historyStore.getRecentHistory(projectId, limit)
+  }
+
+  // ═══════════════════════════════════════════════════════════
+  // CONVENIENCE: Combined operations
+  // ═══════════════════════════════════════════════════════════
+
+  async getSmartDecision(projectId: string, key: string): Promise<string | null> {
+    const sessionValue = this.getSession(`decision:${key}`)
+    if (sessionValue !== undefined) return sessionValue as string
+
+    const pattern = await this.getDecision(projectId, key)
+    if (pattern) return pattern.value
+
+    return null
+  }
+
+  async learnDecision(projectId: string, key: string, value: string, context: string = ''): Promise<void> {
+    this.setSession(`decision:${key}`, value)
+    await this.recordDecision(projectId, key, value, context)
+    await this.appendHistory(projectId, { type: 'decision', key, value, context })
+  }
+
+  /**
+   * Reset internal state (for testing)
+   */
+  resetState(): void {
+    this._sessionStore.clearSession()
+    this._semanticMemories.reset()
+    this._patternStore.reset()
+  }
+}
+
+const memorySystem = new MemorySystem()
+export default memorySystem
+export { MemorySystem }

package/core/agentic/memory-system/patterns.ts

@@ -0,0 +1,156 @@
+/**
+ * Patterns - Tier 2
+ * Persistent learned preferences and decisions.
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+import pathManager from '../../infrastructure/path-manager'
+import type { Patterns, Decision, Workflow } from './types'
+
+export class PatternStore {
+  private _patterns: Patterns | null = null
+  private _patternsLoaded: boolean = false
+
+  private _getPatternsPath(projectId: string): string {
+    return path.join(pathManager.getGlobalProjectPath(projectId), 'memory', 'patterns.json')
+  }
+
+  async loadPatterns(projectId: string): Promise<Patterns> {
+    if (this._patternsLoaded && this._patterns) {
+      return this._patterns
+    }
+
+    try {
+      const patternsPath = this._getPatternsPath(projectId)
+      const content = await fs.readFile(patternsPath, 'utf-8')
+      this._patterns = JSON.parse(content)
+      this._patternsLoaded = true
+      return this._patterns!
+    } catch {
+      this._patterns = {
+        version: 1,
+        decisions: {},
+        preferences: {},
+        workflows: {},
+        counters: {},
+      }
+      this._patternsLoaded = true
+      return this._patterns
+    }
+  }
+
+  async savePatterns(projectId: string): Promise<void> {
+    if (!this._patterns) return
+
+    const patternsPath = this._getPatternsPath(projectId)
+    await fs.mkdir(path.dirname(patternsPath), { recursive: true })
+    await fs.writeFile(patternsPath, JSON.stringify(this._patterns, null, 2), 'utf-8')
+  }
+
+  async recordDecision(projectId: string, key: string, value: string, context: string = ''): Promise<void> {
+    const patterns = await this.loadPatterns(projectId)
+
+    if (!patterns.decisions[key]) {
+      patterns.decisions[key] = {
+        value,
+        count: 1,
+        firstSeen: new Date().toISOString(),
+        lastSeen: new Date().toISOString(),
+        confidence: 'low',
+        contexts: [context].filter(Boolean),
+      }
+    } else {
+      const decision = patterns.decisions[key]
+
+      if (decision.value === value) {
+        decision.count++
+        decision.lastSeen = new Date().toISOString()
+        if (context && !decision.contexts.includes(context)) {
+          decision.contexts.push(context)
+        }
+
+        if (decision.count >= 5) {
+          decision.confidence = 'high'
+        } else if (decision.count >= 3) {
+          decision.confidence = 'medium'
+        }
+      } else {
+        decision.value = value
+        decision.count = 1
+        decision.lastSeen = new Date().toISOString()
+        decision.confidence = 'low'
+      }
+    }
+
+    await this.savePatterns(projectId)
+  }
+
+  async getDecision(projectId: string, key: string): Promise<{ value: string; confidence: string } | null> {
+    const patterns = await this.loadPatterns(projectId)
+    const decision = patterns.decisions[key]
+
+    if (!decision) return null
+    if (decision.confidence === 'low') return null
+
+    return { value: decision.value, confidence: decision.confidence }
+  }
+
+  async hasPattern(projectId: string, key: string): Promise<boolean> {
+    const decision = await this.getDecision(projectId, key)
+    return decision !== null
+  }
+
+  async recordWorkflow(projectId: string, workflowName: string, pattern: Record<string, unknown>): Promise<void> {
+    const patterns = await this.loadPatterns(projectId)
+
+    if (!patterns.workflows[workflowName]) {
+      patterns.workflows[workflowName] = {
+        ...pattern,
+        count: 1,
+        firstSeen: new Date().toISOString(),
+        lastSeen: new Date().toISOString(),
+      }
+    } else {
+      patterns.workflows[workflowName].count++
+      patterns.workflows[workflowName].lastSeen = new Date().toISOString()
+    }
+
+    await this.savePatterns(projectId)
+  }
+
+  async getWorkflow(projectId: string, workflowName: string): Promise<Workflow | null> {
+    const patterns = await this.loadPatterns(projectId)
+    const workflow = patterns.workflows[workflowName]
+
+    if (!workflow || workflow.count < 3) return null
+    return workflow
+  }
+
+  async setPreference(projectId: string, key: string, value: unknown): Promise<void> {
+    const patterns = await this.loadPatterns(projectId)
+    patterns.preferences[key] = { value, updatedAt: new Date().toISOString() }
+    await this.savePatterns(projectId)
+  }
+
+  async getPreference(projectId: string, key: string, defaultValue: unknown = null): Promise<unknown> {
+    const patterns = await this.loadPatterns(projectId)
+    return patterns.preferences[key]?.value ?? defaultValue
+  }
+
+  async getPatternsSummary(projectId: string) {
+    const patterns = await this.loadPatterns(projectId)
+
+    return {
+      decisions: Object.keys(patterns.decisions).length,
+      learnedDecisions: Object.values(patterns.decisions).filter((d) => d.confidence !== 'low').length,
+      workflows: Object.keys(patterns.workflows).length,
+      preferences: Object.keys(patterns.preferences).length,
+    }
+  }
+
+  reset(): void {
+    this._patterns = null
+    this._patternsLoaded = false
+  }
+}

package/core/agentic/memory-system/semantic-memories.ts

@@ -0,0 +1,277 @@
+/**
+ * Semantic Memories
+ * P3.3: Tagged, searchable, CRUD memory operations.
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+import pathManager from '../../infrastructure/path-manager'
+import type { Memory, MemoryDatabase, Context } from './types'
+import { MEMORY_TAGS } from './types'
+
+export class SemanticMemories {
+  private _memories: MemoryDatabase | null = null
+  private _memoriesLoaded: boolean = false
+
+  private _getMemoriesPath(projectId: string): string {
+    return path.join(pathManager.getGlobalProjectPath(projectId), 'memory', 'memories.json')
+  }
+
+  async loadMemories(projectId: string): Promise<MemoryDatabase> {
+    if (this._memoriesLoaded && this._memories) {
+      return this._memories
+    }
+
+    try {
+      const memoriesPath = this._getMemoriesPath(projectId)
+      const content = await fs.readFile(memoriesPath, 'utf-8')
+      this._memories = JSON.parse(content)
+      this._memoriesLoaded = true
+      return this._memories!
+    } catch {
+      this._memories = {
+        version: 1,
+        memories: [],
+        index: {},
+      }
+      this._memoriesLoaded = true
+      return this._memories
+    }
+  }
+
+  async saveMemories(projectId: string): Promise<void> {
+    if (!this._memories) return
+
+    const memoriesPath = this._getMemoriesPath(projectId)
+    await fs.mkdir(path.dirname(memoriesPath), { recursive: true })
+    await fs.writeFile(memoriesPath, JSON.stringify(this._memories, null, 2), 'utf-8')
+  }
+
+  async createMemory(
+    projectId: string,
+    {
+      title,
+      content,
+      tags = [],
+      userTriggered = false,
+    }: { title: string; content: string; tags?: string[]; userTriggered?: boolean }
+  ): Promise<string> {
+    const db = await this.loadMemories(projectId)
+
+    const memory: Memory = {
+      id: `mem_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+      title,
+      content,
+      tags,
+      userTriggered,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    }
+
+    db.memories.push(memory)
+
+    for (const tag of tags) {
+      if (!db.index[tag]) db.index[tag] = []
+      db.index[tag].push(memory.id)
+    }
+
+    await this.saveMemories(projectId)
+    return memory.id
+  }
+
+  async updateMemory(
+    projectId: string,
+    memoryId: string,
+    updates: { title?: string; content?: string; tags?: string[] }
+  ): Promise<boolean> {
+    const db = await this.loadMemories(projectId)
+
+    const index = db.memories.findIndex((m) => m.id === memoryId)
+    if (index === -1) return false
+
+    const memory = db.memories[index]
+    const oldTags = memory.tags || []
+
+    if (updates.title) memory.title = updates.title
+    if (updates.content) memory.content = updates.content
+    if (updates.tags) {
+      for (const tag of oldTags) {
+        if (db.index[tag]) {
+          db.index[tag] = db.index[tag].filter((id) => id !== memoryId)
+        }
+      }
+      for (const tag of updates.tags) {
+        if (!db.index[tag]) db.index[tag] = []
+        db.index[tag].push(memoryId)
+      }
+      memory.tags = updates.tags
+    }
+
+    memory.updatedAt = new Date().toISOString()
+    await this.saveMemories(projectId)
+    return true
+  }
+
+  async deleteMemory(projectId: string, memoryId: string): Promise<boolean> {
+    const db = await this.loadMemories(projectId)
+
+    const index = db.memories.findIndex((m) => m.id === memoryId)
+    if (index === -1) return false
+
+    const memory = db.memories[index]
+
+    for (const tag of memory.tags || []) {
+      if (db.index[tag]) {
+        db.index[tag] = db.index[tag].filter((id) => id !== memoryId)
+      }
+    }
+
+    db.memories.splice(index, 1)
+    await this.saveMemories(projectId)
+    return true
+  }
+
+  async findByTags(projectId: string, tags: string[], matchAll: boolean = false): Promise<Memory[]> {
+    const db = await this.loadMemories(projectId)
+
+    if (matchAll) {
+      return db.memories.filter((m) => tags.every((tag) => (m.tags || []).includes(tag)))
+    } else {
+      const matchingIds = new Set<string>()
+      for (const tag of tags) {
+        const ids = db.index[tag] || []
+        ids.forEach((id) => matchingIds.add(id))
+      }
+      return db.memories.filter((m) => matchingIds.has(m.id))
+    }
+  }
+
+  async searchMemories(projectId: string, query: string): Promise<Memory[]> {
+    const db = await this.loadMemories(projectId)
+    const queryLower = query.toLowerCase()
+
+    return db.memories.filter(
+      (m) => m.title.toLowerCase().includes(queryLower) || m.content.toLowerCase().includes(queryLower)
+    )
+  }
+
+  async getRelevantMemories(projectId: string, context: Context, limit: number = 5): Promise<Memory[]> {
+    const db = await this.loadMemories(projectId)
+
+    const scored = db.memories.map((memory) => {
+      let score = 0
+
+      const contextTags = this._extractContextTags(context)
+      for (const tag of memory.tags || []) {
+        if (contextTags.includes(tag)) score += 10
+      }
+
+      const age = Date.now() - new Date(memory.updatedAt).getTime()
+      const daysSinceUpdate = age / (1000 * 60 * 60 * 24)
+      score += Math.max(0, 5 - daysSinceUpdate)
+
+      if (memory.userTriggered) score += 5
+
+      const keywords = this._extractKeywords(context)
+      for (const keyword of keywords) {
+        if (memory.content.toLowerCase().includes(keyword)) score += 2
+        if (memory.title.toLowerCase().includes(keyword)) score += 3
+      }
+
+      return { ...memory, _score: score }
+    })
+
+    return scored
+      .filter((m) => m._score > 0)
+      .sort((a, b) => b._score - a._score)
+      .slice(0, limit)
+      .map(({ _score, ...memory }) => memory as Memory)
+  }
+
+  private _extractContextTags(context: Context): string[] {
+    const tags: string[] = []
+
+    const commandTags: Record<string, string[]> = {
+      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],
+    }
+
+    if (context.commandName && commandTags[context.commandName]) {
+      tags.push(...commandTags[context.commandName])
+    }
+
+    return tags
+  }
+
+  private _extractKeywords(context: Context): string[] {
+    const keywords: string[] = []
+
+    if (context.params?.description) {
+      keywords.push(...(context.params.description as string).toLowerCase().split(/\s+/))
+    }
+    if (context.params?.feature) {
+      keywords.push(...(context.params.feature as string).toLowerCase().split(/\s+/))
+    }
+
+    const stopWords = ['the', 'a', 'an', 'is', 'are', 'to', 'for', 'and', 'or', 'in']
+    return keywords.filter((k) => k.length > 2 && !stopWords.includes(k))
+  }
+
+  async autoRemember(projectId: string, decisionType: string, value: string, context: string = ''): Promise<void> {
+    const tagMap: Record<string, string[]> = {
+      commit_footer: [MEMORY_TAGS.COMMIT_STYLE],
+      branch_naming: [MEMORY_TAGS.BRANCH_NAMING],
+      test_before_ship: [MEMORY_TAGS.TEST_BEHAVIOR, MEMORY_TAGS.SHIP_WORKFLOW],
+      preferred_agent: [MEMORY_TAGS.AGENT_PREFERENCE],
+      code_style: [MEMORY_TAGS.CODE_STYLE],
+      verbosity: [MEMORY_TAGS.OUTPUT_VERBOSITY],
+    }
+
+    const tags = tagMap[decisionType] || []
+
+    const existing = await this.searchMemories(projectId, decisionType)
+    if (existing.length > 0) {
+      await this.updateMemory(projectId, existing[0].id, {
+        content: `${decisionType}: ${value}`,
+        tags,
+      })
+    } else {
+      await this.createMemory(projectId, {
+        title: `Preference: ${decisionType}`,
+        content: `${decisionType}: ${value}${context ? `\nContext: ${context}` : ''}`,
+        tags,
+        userTriggered: true,
+      })
+    }
+  }
+
+  async getAllMemories(projectId: string): Promise<Memory[]> {
+    const db = await this.loadMemories(projectId)
+    return db.memories
+  }
+
+  async getMemoryStats(projectId: string) {
+    const db = await this.loadMemories(projectId)
+
+    const tagCounts: Record<string, number> = {}
+    for (const [tag, ids] of Object.entries(db.index)) {
+      tagCounts[tag] = ids.length
+    }
+
+    return {
+      totalMemories: db.memories.length,
+      userTriggered: db.memories.filter((m) => m.userTriggered).length,
+      tagCounts,
+      oldestMemory: db.memories[0]?.createdAt,
+      newestMemory: db.memories[db.memories.length - 1]?.createdAt,
+    }
+  }
+
+  reset(): void {
+    this._memories = null
+    this._memoriesLoaded = false
+  }
+}

package/core/agentic/memory-system/session.ts

@@ -0,0 +1,21 @@
+/**
+ * Session Memory - Tier 1
+ * Ephemeral, single command context.
+ */
+
+export class SessionStore {
+  private _sessionMemory: Map<string, { value: unknown; timestamp: number }> = new Map()
+
+  setSession(key: string, value: unknown): void {
+    this._sessionMemory.set(key, { value, timestamp: Date.now() })
+  }
+
+  getSession(key: string): unknown {
+    const entry = this._sessionMemory.get(key)
+    return entry?.value
+  }
+
+  clearSession(): void {
+    this._sessionMemory.clear()
+  }
+}