@morningljn/mnemo 0.1.2 → 0.1.4

package/src/metrics.ts

@@ -0,0 +1,81 @@
+/**
+ * Performance metrics for mnemo-mcp.
+ * Tracks query timing, cache hit/miss, and retrieval paths.
+ * Only active when MNEMO_DEBUG=1.
+ */
+
+export interface QueryMetrics {
+  action: string
+  durationMs: number
+  resultCount: number
+  cacheHit: boolean
+  retrievalPath?: string
+}
+
+export class PerfMetrics {
+  private enabled: boolean
+  private totalQueries = 0
+  private cacheHits = 0
+  private cacheMisses = 0
+  private totalMissTimeMs = 0
+
+  constructor() {
+    this.enabled = process.env.MNEMO_DEBUG === '1'
+  }
+
+  isEnabled(): boolean {
+    return this.enabled
+  }
+
+  record(metrics: QueryMetrics): void {
+    if (!this.enabled) return
+
+    this.totalQueries++
+    if (metrics.cacheHit) {
+      this.cacheHits++
+    } else {
+      this.cacheMisses++
+      this.totalMissTimeMs += metrics.durationMs
+    }
+
+    const hitRatio = this.totalQueries > 0 ? (this.cacheHits / this.totalQueries * 100).toFixed(1) : '0.0'
+    const path = metrics.retrievalPath ? ` [${metrics.retrievalPath}]` : ''
+    console.error(
+      `[mnemo:debug] ${metrics.action} | ${metrics.cacheHit ? 'HIT' : 'MISS'} | ` +
+      `${metrics.durationMs.toFixed(2)}ms | ${metrics.resultCount} results | ` +
+      `hit_ratio=${hitRatio}%${path}`
+    )
+  }
+
+  getStats(): {
+    totalQueries: number
+    cacheHits: number
+    cacheMisses: number
+    hitRatio: number
+    avgQueryTime: number
+    totalTimeSaved: number
+  } {
+    const hitRatio = this.totalQueries > 0 ? this.cacheHits / this.totalQueries : 0
+    const avgQueryTime = this.cacheMisses > 0 ? this.totalMissTimeMs / this.cacheMisses : 0
+    const totalTimeSaved = this.cacheHits * avgQueryTime
+
+    return {
+      totalQueries: this.totalQueries,
+      cacheHits: this.cacheHits,
+      cacheMisses: this.cacheMisses,
+      hitRatio,
+      avgQueryTime,
+      totalTimeSaved,
+    }
+  }
+
+  logStats(): void {
+    if (!this.enabled) return
+    const stats = this.getStats()
+    console.error(
+      `[mnemo:debug] stats | total=${stats.totalQueries} hits=${stats.cacheHits} ` +
+      `misses=${stats.cacheMisses} hit_ratio=${(stats.hitRatio * 100).toFixed(1)}% ` +
+      `avg_time=${stats.avgQueryTime.toFixed(2)}ms saved=${stats.totalTimeSaved.toFixed(2)}ms`
+    )
+  }
+}

package/src/refine.ts

@@ -0,0 +1,127 @@
+/**
+ * Query refinement: strip noise tokens from user messages before memory search.
+ * Pure function — no side effects, no DB access.
+ */
+
+import type { FactCategory } from './types.js'
+
+// Action words / helper phrases to strip (Chinese)
+const ACTION_WORDS = [
+  '帮我看看', '能不能帮我', '给我看看',
+  '帮我', '看看', '看一下', '做一下', '能不能', '为什么', '怎么',
+  '是什么', '如何', '请', '麻烦', '可以', '给我',
+  '给我做', '给我写', '给我查', '给我找', '给我说', '给我讲',
+  '告诉我', '跟我说', '跟我讲', '给我解释', '给我说明', '给我介绍',
+  '运行', '执行', '启动', '停止', '创建', '删除', '修改', '更新', '查看',
+  '检查', '测试', '提交', '推送', '拉取', '合并', '切换', '重置', '重构',
+  '运行测试', '创建文件',
+]
+
+// Common CLI commands / low-signal English tokens to filter
+const NOISE_WORDS = new Set([
+  'git', 'npm', 'npx', 'yarn', 'pnpm', 'status', 'log', 'diff', 'add',
+  'commit', 'push', 'pull', 'merge', 'checkout', 'branch', 'stash',
+  'install', 'build', 'run', 'start', 'stop', 'test', 'lint', 'format',
+])
+// Sort by length descending so longer phrases match first during replacement
+const ACTION_WORDS_SORTED = [...ACTION_WORDS].sort((a, b) => b.length - a.length)
+const ACTION_WORDS_SET = new Set(ACTION_WORDS)
+
+// Reuse existing stop words from retriever
+const CN_STOP_WORDS = new Set([
+  '的', '了', '是', '在', '有', '和', '就', '不', '人', '都',
+  '一', '个', '上', '也', '很', '到', '说', '要', '去', '你',
+  '会', '着', '没', '看', '好', '自', '这', '他', '她', '它',
+  '那', '些', '用', '对', '下', '为', '从', '被', '把', '能',
+  '可', '以', '所', '而', '又', '与', '但', '或', '等', '中',
+  '大', '小', '多', '少', '其', '之', '做', '让', '给', '已',
+  '还', '来', '地', '得', '过', '时', '里', '后', '前', '当',
+])
+
+export interface RefineResult {
+  query: string | null
+  tokens: string[]
+  entityTokens: string[]
+}
+
+/**
+ * Refine a raw user message into memory-searchable keywords.
+ * Returns null if the message is a pure operation command with no memory relevance.
+ */
+export function refineQuery(raw: string): RefineResult | null {
+  const trimmed = raw.trim()
+  if (!trimmed) return null
+
+  // Extract high-signal tokens first: quoted content, book titles, capitalized phrases
+  const entityTokens: string[] = []
+
+  // Chinese quotes: 「深色主题」 or "深色主题" or '深色主题'
+  for (const m of trimmed.matchAll(/[「""'']([^「""''」]{2,20})[」""'']/g)) {
+    entityTokens.push(m[1])
+  }
+  // Book titles: 《记忆系统》
+  for (const m of trimmed.matchAll(/《([^》]+)》/g)) {
+    entityTokens.push(m[1])
+  }
+  // Capitalized English phrases: "TypeScript", "Visual Studio Code"
+  for (const m of trimmed.matchAll(/\b([A-Z][a-zA-Z]*(?:\s+[A-Z][a-zA-Z]*)+)\b/g)) {
+    entityTokens.push(m[1])
+  }
+
+  // Tokenize: split by spaces and Chinese character boundaries
+  const tokens: string[] = []
+  const parts = trimmed.split(/\s+/)
+  for (const part of parts) {
+    // English words
+    for (const word of part.match(/[a-zA-Z0-9_\-.]+/g) ?? []) {
+      if (word.length >= 2) tokens.push(word)
+    }
+    // For Chinese: strip action words first, then extract remaining chars
+    let cnText = part.replace(/[\u4e00-\u9fff]+/g, (seg) => {
+      let result = seg
+      for (const aw of ACTION_WORDS_SORTED) {
+        result = result.replaceAll(aw, '')
+      }
+      return result
+    })
+    const cnChars = cnText.match(/[\u4e00-\u9fff]/g) ?? []
+    for (const c of cnChars) {
+      if (!CN_STOP_WORDS.has(c)) tokens.push(c)
+    }
+    // Chinese 2-grams for better matching
+    for (let i = 0; i < cnChars.length - 1; i++) {
+      const bigram = cnChars[i] + cnChars[i + 1]
+      tokens.push(bigram)
+    }
+  }
+
+  // Filter stop words, noise, and short tokens
+  const filtered = tokens.filter(t => {
+    if (ACTION_WORDS_SET.has(t)) return false
+    if (CN_STOP_WORDS.has(t)) return false
+    if (NOISE_WORDS.has(t.toLowerCase())) return false
+    if (t.length < 2) return false
+    return true
+  })
+
+  // Deduplicate while preserving order
+  const seen = new Set<string>()
+  const deduped: string[] = []
+  for (const t of filtered) {
+    if (!seen.has(t)) {
+      seen.add(t)
+      deduped.push(t)
+    }
+  }
+
+  // If nothing left after filtering, check if we have entity tokens
+  if (deduped.length === 0 && entityTokens.length === 0) {
+    return null
+  }
+
+  // Combine: entity tokens first (higher signal), then deduped tokens
+  const allTokens = [...entityTokens, ...deduped.filter(t => !entityTokens.includes(t))]
+  const query = allTokens.join(' ')
+
+  return { query, tokens: deduped, entityTokens }
+}

package/src/resources.ts

@@ -0,0 +1,78 @@
+/**
+ * MCP Resource manager for mnemo-mcp.
+ * Exposes per-category memory summaries as MCP Resources for session warmup injection.
+ */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { MemoryStore } from './store.js'
+import type { FactCategory } from './types.js'
+
+const CATEGORIES: FactCategory[] = ['identity', 'coding_style', 'tool_pref', 'workflow', 'general']
+const RESOURCE_LIMIT = 10
+
+export interface ResourceFact {
+  fact_id: number
+  content: string
+  trust_score: number
+}
+
+export class ResourceManager {
+  private cache = new Map<FactCategory, ResourceFact[]>()
+
+  constructor(
+    private store: MemoryStore,
+  ) {}
+
+  /** Register all category resources with the MCP server */
+  registerResources(server: McpServer): void {
+    for (const category of CATEGORIES) {
+      const uri = `mnemo://global/${category}`
+      server.registerResource(
+        `mnemo-global-${category}`,
+        uri,
+        {
+          description: `${category} category global facts (top ${RESOURCE_LIMIT} by trust)`,
+          mimeType: 'application/json',
+        },
+        async () => this.readCategory(category),
+      )
+    }
+  }
+
+  /** Read handler for a specific category */
+  private readCategory(category: FactCategory): { contents: Array<{ uri: string; mimeType: string; text: string }> } {
+    const facts = this.getFacts(category)
+    return {
+      contents: [{
+        uri: `mnemo://global/${category}`,
+        mimeType: 'application/json',
+        text: JSON.stringify(facts, null, 2),
+      }],
+    }
+  }
+
+  /** Get facts for a category — with caching */
+  getFacts(category: FactCategory): ResourceFact[] {
+    const cached = this.cache.get(category)
+    if (cached) return cached
+
+    const facts = this.store.listFacts(category, 0.0, RESOURCE_LIMIT).map(f => ({
+      fact_id: f.factId,
+      content: f.content,
+      trust_score: f.trustScore,
+    }))
+
+    this.cache.set(category, facts)
+    return facts
+  }
+
+  /** Invalidate all caches — call after any write operation */
+  invalidate(): void {
+    this.cache.clear()
+  }
+
+  /** Get cache entry count for debugging */
+  cacheSize(): number {
+    return this.cache.size
+  }
+}

package/src/retriever.ts

@@ -10,6 +10,9 @@
 import type Database from 'better-sqlite3'
 import type { Fact, FactCategory, ScoredFact, Contradiction, SearchOptions, ContradictOptions, RetrieverOptions } from './types.js'
 import { MemoryStore } from './store.js'
+import { QueryCache } from './cache.js'
+import { PerfMetrics } from './metrics.js'
+import { refineQuery } from './refine.js'
 
 // 中文字符级匹配的虚词集合（这些单字太常见，不参与字符交叉匹配）
 const CN_OVERLAP_STOP = new Set([
@@ -31,6 +34,10 @@ export class FactRetriever {
   private ftsWeight: number
   private jaccardWeight: number
   private halfLifeDays: number
+  /** 查询缓存（60s TTL，进程内 Map） */
+  private cache: QueryCache
+  /** 性能指标（MNEMO_DEBUG=1 时生效） */
+  private metrics: PerfMetrics
   /** category → 高频 tag 集合（从事实库自动学习，惰性初始化） */
   private _categoryTagMap: Map<FactCategory, Set<string>> | null = null
   /** 中英术语对列表（从事实库自动学习，惰性初始化） */
@@ -44,16 +51,46 @@ export class FactRetriever {
     this.ftsWeight = options?.ftsWeight ?? 0.5
     this.jaccardWeight = options?.jaccardWeight ?? 0.5
     this.halfLifeDays = options?.temporalDecayHalfLife ?? 0
+    this.cache = new QueryCache()
+    this.metrics = new PerfMetrics()
+  }
+
+  /** 获取缓存实例（供 server.ts 写操作时调用 cache.clear()） */
+  getCache(): QueryCache {
+    return this.cache
+  }
+
+  /** 获取性能指标实例（供调试接口使用） */
+  getMetrics(): PerfMetrics {
+    return this.metrics
   }
 
   /** 主搜索：FTS5 → LIKE → 字符交叉 → 分类推断 → Jaccard → 信任评分 → 时间衰减 */
-  search(query: string, options?: SearchOptions): ScoredFact[] {
+  search(query: string, options?: SearchOptions & { skipRefine?: boolean }): ScoredFact[] {
+    const startTime = performance.now()
     const minTrust = options?.minTrust ?? 0.3
     const limit = options?.limit ?? 10
     const category = options?.category
 
+    // 查询提炼（除非显式跳过）
+    let searchQuery = query
+    if (!options?.skipRefine) {
+      const refined = refineQuery(query)
+      if (refined?.query) {
+        searchQuery = refined.query
+      }
+    }
+
+    // 缓存检查
+    const cacheKey = this.cache.makeKey({ action: 'search', query: searchQuery, category, minTrust, limit })
+    const cached = this.cache.get(cacheKey)
+    if (cached) {
+      this.metrics.record({ action: 'search', durationMs: performance.now() - startTime, resultCount: cached.length, cacheHit: true })
+      return cached
+    }
+
     // 查询双语扩展：中文术语追加英文，英文术语追加中文
-    const expandedQuery = this.expandQueryBilingually(query)
+    const expandedQuery = this.expandQueryBilingually(searchQuery)
 
     // Stage 1: FTS5 候选集，空时逐级 fallback（使用双语扩展后的查询）
     let candidates = this.ftsCandidates(expandedQuery, category, minTrust, limit * 3)
@@ -66,18 +103,22 @@ export class FactRetriever {
     if (candidates.length === 0) {
       // 分类推断 fallback（仅无 category 过滤时生效）
       if (!category) {
-        const inferred = this.categoryInferFallback(query, minTrust, limit)
+        const inferred = this.categoryInferFallback(searchQuery, minTrust, limit)
         if (inferred.length > 0) return inferred
       }
       // 个人/身份相关的短查询触发 trust fallback
-      if (this.isPersonalQuery(query)) {
+      if (this.isPersonalQuery(searchQuery)) {
         return this.trustFallback(category, minTrust, limit)
       }
       return []
     }
 
     // Stage 2-4: Jaccard 重排序 + 信任评分 + 时间衰减
-    const queryTokens = this.tokenize(query)
+    // 动态权重：短查询偏 FTS，长查询偏 Jaccard
+    const queryTokens = this.tokenize(searchQuery)
+    const tokenCount = queryTokens.size
+    const ftsWeight = tokenCount <= 3 ? 0.7 : 0.3
+    const jaccardWeight = tokenCount <= 3 ? 0.3 : 0.7
 
     const scored: ScoredFact[] = []
 
@@ -95,7 +136,7 @@ export class FactRetriever {
       const ftsScore = fact.ftsRank
 
       // 综合评分
-      const relevance = this.ftsWeight * ftsScore + this.jaccardWeight * similarity
+      const relevance = ftsWeight * ftsScore + jaccardWeight * similarity
 
       let score = relevance * fact.trustScore
 
@@ -109,52 +150,80 @@ export class FactRetriever {
 
     scored.sort((a, b) => b.score - a.score)
 
-    // Category 多样性：同类事实只保留评分最高的，避免 general 黑洞效应
-    const seenCategories = new Set<FactCategory>()
-    const diverse: ScoredFact[] = []
-    for (const s of scored) {
-      if (!seenCategories.has(s.category)) {
-        seenCategories.add(s.category)
-        diverse.push(s)
-      }
-      if (diverse.length >= limit) break
-    }
-    // 补位：如果去重后不足 limit，从原排序列表中补（允许同类多次出现）
-    if (diverse.length < limit) {
-      const diverseIds = new Set(diverse.map(f => f.factId))
-      for (const s of scored) {
-        if (!diverseIds.has(s.factId)) {
-          diverse.push(s)
-          if (diverse.length >= limit) break
+    // 相关性门控：过滤低相关性结果
+    const RELEVANCE_THRESHOLD = 0.15
+    const gated = scored.filter(s => s.score >= RELEVANCE_THRESHOLD)
+    const pool = gated.length > 0 ? gated : scored
+
+    // 内容去重：Jaccard > 0.7 的只保留高分
+    const results: ScoredFact[] = []
+    for (const candidate of pool) {
+      let isDuplicate = false
+      const candidateTokens = this.tokenize(candidate.content)
+      for (const kept of results) {
+        const keptTokens = this.tokenize(kept.content)
+        if (this.jaccardSimilarity(candidateTokens, keptTokens) > 0.7) {
+          isDuplicate = true
+          break
         }
       }
+      if (!isDuplicate) {
+        results.push(candidate)
+        if (results.length >= limit) break
+      }
     }
 
-    const results = diverse
-
     // 检索追踪：递增 retrieval_count + top3 信任刷新
     if (results.length > 0) {
       this.trackRetrieval(results)
     }
 
+    // 缓存存储 + 指标记录
+    this.cache.set(cacheKey, results)
+    this.metrics.record({ action: 'search', durationMs: performance.now() - startTime, resultCount: results.length, cacheHit: false, retrievalPath: 'FTS5' })
     return results
   }
 
   /** 实体探测：查询某实体关联的所有事实 */
   probe(entity: string, options?: SearchOptions): ScoredFact[] {
+    const startTime = performance.now()
     const limit = options?.limit ?? 10
-    const facts = this.store.getFactsByEntity(entity, options?.category, limit)
-    return facts.map((f, i) => ({
+    const category = options?.category
+
+    // 缓存检查
+    const cacheKey = this.cache.makeKey({ action: 'probe', entity, category, limit })
+    const cached = this.cache.get(cacheKey)
+    if (cached) {
+      this.metrics.record({ action: 'probe', durationMs: performance.now() - startTime, resultCount: cached.length, cacheHit: true })
+      return cached
+    }
+
+    const facts = this.store.getFactsByEntity(entity, category, limit)
+    const results = facts.map((f, i) => ({
       ...f,
       score: f.trustScore * (1 - i * 0.05), // 按信任评分排序并给微小梯度
     }))
+
+    // 缓存存储 + 指标记录
+    this.cache.set(cacheKey, results)
+    this.metrics.record({ action: 'probe', durationMs: performance.now() - startTime, resultCount: results.length, cacheHit: false, retrievalPath: 'entity' })
+    return results
   }
 
   /** 实体关联：查找与某实体共享上下文的其他事实 */
   related(entity: string, options?: SearchOptions): ScoredFact[] {
+    const startTime = performance.now()
     const limit = options?.limit ?? 10
     const category = options?.category
 
+    // 缓存检查
+    const cacheKey = this.cache.makeKey({ action: 'related', entity, category, limit })
+    const cached = this.cache.get(cacheKey)
+    if (cached) {
+      this.metrics.record({ action: 'related', durationMs: performance.now() - startTime, resultCount: cached.length, cacheHit: true })
+      return cached
+    }
+
     // Step 1: 获取实体关联的 fact_id 列表
     const entityFactsSql = `
       SELECT fe.fact_id FROM fact_entities fe
@@ -162,7 +231,12 @@ export class FactRetriever {
       WHERE e.name LIKE ?
     `
     const entityFactRows = this.db.prepare(entityFactsSql).all(entity) as Array<{ fact_id: number }>
-    if (entityFactRows.length === 0) return []
+    if (entityFactRows.length === 0) {
+      const emptyResults: ScoredFact[] = []
+      this.cache.set(cacheKey, emptyResults)
+      this.metrics.record({ action: 'related', durationMs: performance.now() - startTime, resultCount: 0, cacheHit: false, retrievalPath: 'entity' })
+      return emptyResults
+    }
 
     const factIds = entityFactRows.map(r => r.fact_id)
 
@@ -175,7 +249,12 @@ export class FactRetriever {
         AND e.name NOT LIKE ?
     `).all(...factIds, entity) as Array<{ name: string }>
 
-    if (otherEntityRows.length === 0) return []
+    if (otherEntityRows.length === 0) {
+      const emptyResults: ScoredFact[] = []
+      this.cache.set(cacheKey, emptyResults)
+      this.metrics.record({ action: 'related', durationMs: performance.now() - startTime, resultCount: 0, cacheHit: false, retrievalPath: 'entity' })
+      return emptyResults
+    }
 
     // Step 3: 获取关联这些其他实体但不包含原始事实的 facts
     const otherEntities = otherEntityRows.map(r => r.name)
@@ -210,7 +289,7 @@ export class FactRetriever {
       created_at: string; updated_at: string;
     }>
 
-    return rows.map((r, i) => ({
+    const results = rows.map((r, i) => ({
       factId: r.fact_id,
       content: r.content,
       category: r.category as FactCategory,
@@ -223,20 +302,44 @@ export class FactRetriever {
       updatedAt: r.updated_at,
       score: r.trust_score * (1 - i * 0.05),
     }))
+
+    // 缓存存储 + 指标记录
+    this.cache.set(cacheKey, results)
+    this.metrics.record({ action: 'related', durationMs: performance.now() - startTime, resultCount: results.length, cacheHit: false, retrievalPath: 'entity' })
+    return results
   }
 
   /** 多实体推理：查找同时关联多个实体的事实 */
   reason(entities: string[], options?: SearchOptions): ScoredFact[] {
+    const startTime = performance.now()
     if (entities.length === 0) return []
-    const facts = this.store.getFactsByEntities(entities, options?.category, options?.limit ?? 10)
-    return facts.map((f, i) => ({
+
+    const category = options?.category
+    const limit = options?.limit ?? 10
+
+    // 缓存检查
+    const cacheKey = this.cache.makeKey({ action: 'reason', entities, category, limit })
+    const cached = this.cache.get(cacheKey)
+    if (cached) {
+      this.metrics.record({ action: 'reason', durationMs: performance.now() - startTime, resultCount: cached.length, cacheHit: true })
+      return cached
+    }
+
+    const facts = this.store.getFactsByEntities(entities, category, limit)
+    const results = facts.map((f, i) => ({
       ...f,
       score: f.trustScore * (1 - i * 0.05),
     }))
+
+    // 缓存存储 + 指标记录
+    this.cache.set(cacheKey, results)
+    this.metrics.record({ action: 'reason', durationMs: performance.now() - startTime, resultCount: results.length, cacheHit: false, retrievalPath: 'entity' })
+    return results
   }
 
-  /** 矛盾检测：实体重叠 + 内容差异 */
+  /** 矛盾检测：实体重叠 + 内容差异（仅指标，不缓存 — 返回类型不同） */
   contradict(options?: ContradictOptions): Contradiction[] {
+    const startTime = performance.now()
     const threshold = options?.threshold ?? 0.3
     const limit = options?.limit ?? 10
     const category = options?.category
@@ -326,7 +429,11 @@ export class FactRetriever {
     }
 
     contradictions.sort((a, b) => b.contradictionScore - a.contradictionScore)
-    return contradictions.slice(0, limit)
+    const results = contradictions.slice(0, limit)
+
+    // 指标记录（无缓存 — Contradiction[] 不适用于 ScoredFact 缓存）
+    this.metrics.record({ action: 'contradict', durationMs: performance.now() - startTime, resultCount: results.length, cacheHit: false, retrievalPath: 'O(n²)' })
+    return results
   }
 
   // ------------------------------------------------------------------