@morningljn/mnemo 0.1.3 → 0.1.4

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

@@ -12,6 +12,7 @@ import type { Fact, FactCategory, ScoredFact, Contradiction, SearchOptions, Cont
 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([
@@ -65,14 +66,23 @@ export class FactRetriever {
   }
 
   /** 主搜索：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, category, minTrust, limit })
+    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 })
@@ -80,7 +90,7 @@ export class FactRetriever {
     }
 
     // 查询双语扩展：中文术语追加英文，英文术语追加中文
-    const expandedQuery = this.expandQueryBilingually(query)
+    const expandedQuery = this.expandQueryBilingually(searchQuery)
 
     // Stage 1: FTS5 候选集，空时逐级 fallback（使用双语扩展后的查询）
     let candidates = this.ftsCandidates(expandedQuery, category, minTrust, limit * 3)
@@ -93,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[] = []
 
@@ -122,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
 
@@ -136,29 +150,29 @@ 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)

package/src/server.ts

@@ -7,6 +7,7 @@ import { homedir } from 'node:os'
 import { z } from 'zod/v4'
 import { MemoryStore } from './store.js'
 import { FactRetriever } from './retriever.js'
+import { ResourceManager } from './resources.js'
 import { fullSecurityScan } from './security.js'
 import type { FactStoreArgs, FactFeedbackArgs, FactCategory } from './types.js'
 
@@ -64,6 +65,10 @@ store.auditContradictions()
 // -- MCP Server --
 const server = new McpServer({ name: 'mnemo-mcp', version: '0.1.0' })
 
+// -- MCP Resources: 会话预热注入 --
+const resourceManager = new ResourceManager(store)
+resourceManager.registerResources(server)
+
 server.tool(
   'fact_store',
   FACT_STORE_DESCRIPTION,
@@ -101,6 +106,7 @@ server.tool(
           }
 
           retriever.getCache().clear()
+          resourceManager.invalidate()
           const response = Array.isArray(a.content) ? results : results[0]
           return { content: [{ type: 'text' as const, text: JSON.stringify(response) }] }
         }
@@ -139,6 +145,7 @@ server.tool(
           if (!a.fact_id) return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'Missing required argument: fact_id' }) }] }
           const updated = store.updateFact(a.fact_id as number, { content: a.content as string | undefined, tags: a.tags, category, trustDelta: a.trust_delta })
           retriever.getCache().clear()
+          resourceManager.invalidate()
           return { content: [{ type: 'text' as const, text: JSON.stringify({ updated }) }] }
         }
 
@@ -147,6 +154,7 @@ server.tool(
           const ids = Array.isArray(a.fact_id) ? a.fact_id : [a.fact_id]
           const results = ids.map(id => ({ fact_id: id, removed: store.removeFact(id) }))
           retriever.getCache().clear()
+          resourceManager.invalidate()
           const response = Array.isArray(a.fact_id) ? results : results[0]
           return { content: [{ type: 'text' as const, text: JSON.stringify(response) }] }
         }

package/tests/refine.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest'
+import { refineQuery } from '../src/refine.js'
+
+describe('refineQuery', () => {
+  it('filters action words from Chinese query', () => {
+    const result = refineQuery('帮我用 TypeScript 重构 auth 模块')
+    expect(result).not.toBeNull()
+    expect(result!.query).toContain('TypeScript')
+    expect(result!.query).toContain('auth')
+    expect(result!.query).not.toContain('帮我')
+    expect(result!.query).not.toContain('重构')
+  })
+
+  it('returns null for pure operation commands', () => {
+    expect(refineQuery('运行测试')).toBeNull()
+    expect(refineQuery('git status')).toBeNull()
+    expect(refineQuery('创建文件')).toBeNull()
+  })
+
+  it('extracts quoted Chinese entities', () => {
+    const result = refineQuery('我喜欢「深色主题」')
+    expect(result).not.toBeNull()
+    expect(result!.entityTokens).toContain('深色主题')
+    expect(result!.query).toContain('深色主题')
+  })
+
+  it('extracts book title entities', () => {
+    const result = refineQuery('读了《设计模式》这本书')
+    expect(result).not.toBeNull()
+    expect(result!.entityTokens).toContain('设计模式')
+  })
+
+  it('extracts capitalized English phrases', () => {
+    const result = refineQuery('使用 Visual Studio Code 编辑器')
+    expect(result).not.toBeNull()
+    expect(result!.entityTokens).toContain('Visual Studio Code')
+  })
+
+  it('returns null for empty string', () => {
+    expect(refineQuery('')).toBeNull()
+    expect(refineQuery('   ')).toBeNull()
+  })
+
+  it('preserves meaningful Chinese tokens', () => {
+    const result = refineQuery('用户偏好深色主题')
+    expect(result).not.toBeNull()
+    expect(result!.query).toContain('用户')
+    expect(result!.query).toContain('偏好')
+    expect(result!.query).toContain('深色')
+    expect(result!.query).toContain('主题')
+  })
+})

package/tests/resource.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { MemoryStore } from '../src/store.js'
+import { ResourceManager } from '../src/resources.js'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+
+let store: MemoryStore
+let manager: ResourceManager
+let tmpDir: string
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), 'mnemo-test-'))
+  store = new MemoryStore(join(tmpDir, 'test.db'))
+  manager = new ResourceManager(store)
+})
+
+afterEach(() => {
+  store.close()
+  rmSync(tmpDir, { recursive: true, force: true })
+})
+
+describe('ResourceManager', () => {
+  it('returns empty array for empty category', () => {
+    const facts = manager.getFacts('identity')
+    expect(facts).toEqual([])
+  })
+
+  it('returns facts ordered by trust score', () => {
+    store.addFact('用户偏好深色主题', 'tool_pref')
+    store.addFact('用户喜欢 VS Code', 'tool_pref')
+    const facts = manager.getFacts('tool_pref')
+    expect(facts.length).toBe(2)
+    // listFacts returns trust_score DESC, first fact added gets default trust
+    expect(facts.length).toBeGreaterThan(0)
+  })
+
+  it('caches results', () => {
+    store.addFact('测试事实', 'general')
+    manager.getFacts('general')
+    expect(manager.cacheSize()).toBe(1)
+    // Second call should hit cache
+    const facts2 = manager.getFacts('general')
+    expect(facts2.length).toBe(1)
+  })
+
+  it('invalidates cache on write', () => {
+    store.addFact('测试事实', 'general')
+    manager.getFacts('general')
+    expect(manager.cacheSize()).toBe(1)
+    manager.invalidate()
+    expect(manager.cacheSize()).toBe(0)
+  })
+
+  it('limits to top 10 facts', () => {
+    for (let i = 0; i < 15; i++) {
+      store.addFact(`事实 ${i}`, 'general')
+    }
+    const facts = manager.getFacts('general')
+    expect(facts.length).toBe(10)
+  })
+})