metame-cli 1.4.18 → 1.4.20

package/scripts/memory-write.js

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * memory-write.js — Active memory injection CLI
+ *
+ * Usage:
+ *   node memory-write.js "entity" "relation" "value"
+ *   node memory-write.js "entity" "relation" "value" --confidence high --project metame --tags "tag1,tag2"
+ *   node memory-write.js --help
+ *
+ * Reuses memory.js saveFacts() and acquire/release pattern. Zero new dependencies.
+ */
+
+'use strict';
+
+const path = require('path');
+const os = require('os');
+
+// ── Legal relation types ──────────────────────────────────────────────────────
+const VALID_RELATIONS = new Set([
+  'tech_decision',
+  'bug_lesson',
+  'arch_convention',
+  'config_fact',
+  'config_change',
+  'user_pref',
+  'workflow_rule',
+  'project_milestone',
+]);
+
+// ── Entity whitelist (no dot required for these) ──────────────────────────────
+const ENTITY_WHITELIST = new Set(['王总', 'system', 'user', 'MetaMe']);
+
+// ── Help text ─────────────────────────────────────────────────────────────────
+const HELP = `
+memory-write.js — 主动写入事实到 memory.db
+
+用法:
+  node memory-write.js <entity> <relation> <value> [options]
+
+参数:
+  entity      知识主体，须含点号（如 MetaMe.daemon）或在白名单（王总/system/user/MetaMe）
+  relation    关系类型，合法值：
+                ${[...VALID_RELATIONS].join(', ')}
+  value       事实内容，20-300 字符
+
+选项:
+  --confidence <level>   high | medium | low  （默认 medium）
+  --project <key>        项目标识（默认从 cwd 推断，推断不到则 '*'）
+  --tags <tag1,tag2>     最多 3 个标签，逗号分隔
+  --help                 显示此帮助
+
+示例:
+  node memory-write.js "MetaMe.daemon" "bug_lesson" "修复X前必须先Y，否则Z会挂"
+  node memory-write.js "MetaMe.bridge" "tech_decision" "飞书回调走 3000 端口，nginx 转发" --confidence high --project metame
+`.trim();
+
+// ── Project inference ─────────────────────────────────────────────────────────
+function inferProject(cwd) {
+  if (!cwd) return '*';
+  const known = { 'MetaMe': 'metame', 'metame-desktop': 'desktop' };
+  for (const [dir, key] of Object.entries(known)) {
+    if (cwd.includes(dir)) return key;
+  }
+  return '*';
+}
+
+// ── Argv parser (zero deps) ───────────────────────────────────────────────────
+function parseArgs(argv) {
+  const positional = [];
+  const opts = {};
+  let i = 0;
+  while (i < argv.length) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') { opts.help = true; i++; continue; }
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const val = argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : null;
+      if (val !== null) { opts[key] = val; i += 2; } else { opts[key] = true; i++; }
+    } else {
+      positional.push(a);
+      i++;
+    }
+  }
+  return { positional, opts };
+}
+
+// ── Validation ────────────────────────────────────────────────────────────────
+function validateEntity(entity) {
+  if (!entity) return 'entity 不能为空';
+  if (ENTITY_WHITELIST.has(entity)) return null;
+  if (!entity.includes('.')) return `entity 格式不合法：须含点号（如 MetaMe.daemon）或为白名单值（${[...ENTITY_WHITELIST].join('/')}）`;
+  return null;
+}
+
+function validateRelation(relation) {
+  if (!relation) return 'relation 不能为空';
+  if (!VALID_RELATIONS.has(relation)) {
+    return `relation 不合法："${relation}"\n合法值: ${[...VALID_RELATIONS].join(', ')}`;
+  }
+  return null;
+}
+
+function validateValue(value) {
+  if (!value) return 'value 不能为空';
+  if (value.length < 20) return `value 太短（${value.length} 字符），最少 20 字符`;
+  if (value.length > 300) return `value 太长（${value.length} 字符），最多 300 字符`;
+  return null;
+}
+
+function validateConfidence(conf) {
+  const valid = ['high', 'medium', 'low'];
+  if (!valid.includes(conf)) return `confidence 不合法："${conf}"，合法值: high | medium | low`;
+  return null;
+}
+
+// ── Resolve memory.js (supports both dev and deployed paths) ──────────────────
+function resolveMemory() {
+  const candidates = [
+    path.join(os.homedir(), '.metame', 'memory.js'),
+    path.join(__dirname, 'memory.js'),
+  ];
+  for (const p of candidates) {
+    try { require.resolve(p); return p; } catch { }
+  }
+  return null;
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+function main() {
+  const { positional, opts } = parseArgs(process.argv.slice(2));
+
+  if (opts.help) {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  const [entity, relation, value] = positional;
+  const confidence = opts.confidence || 'medium';
+  const project = opts.project || process.env.METAME_PROJECT || inferProject(process.cwd());
+  const tagsRaw = opts.tags || '';
+  const tags = tagsRaw ? tagsRaw.split(',').map(t => t.trim()).filter(Boolean).slice(0, 3) : [];
+
+  // Validate
+  const errors = [
+    validateEntity(entity),
+    validateRelation(relation),
+    validateValue(value),
+    opts.confidence ? validateConfidence(confidence) : null,
+  ].filter(Boolean);
+
+  if (errors.length) {
+    for (const e of errors) console.error('错误: ' + e);
+    console.error('\n运行 node memory-write.js --help 查看用法');
+    process.exit(1);
+  }
+
+  // Resolve memory module
+  const memoryPath = resolveMemory();
+  if (!memoryPath) {
+    console.error('错误: 找不到 memory.js，请确认 MetaMe 已部署');
+    process.exit(1);
+  }
+
+  const memory = require(memoryPath);
+  const sessionId = 'manual-' + Date.now();
+
+  if (typeof memory.acquire === 'function') memory.acquire();
+  try {
+    const result = memory.saveFacts(sessionId, project, [
+      { entity, relation, value, confidence, tags, source_type: 'manual' },
+    ]);
+
+    if (result.saved > 0) {
+      const preview = value.slice(0, 30) + (value.length > 30 ? '...' : '');
+      console.log(`✓ 已保存 [${relation}] ${entity}: "${preview}"`);
+      if (result.superseded > 0) {
+        console.log(`  (已将 ${result.superseded} 条旧记录标记为 superseded)`);
+      }
+    } else {
+      // skipped: duplicate or validation filtered by saveFacts
+      console.log(`⚠ 未保存（可能是重复内容）。已跳过: ${result.skipped}`);
+      process.exit(1);
+    }
+  } catch (err) {
+    console.error('错误: 写入失败 —', err.message);
+    process.exit(1);
+  } finally {
+    try { if (typeof memory.release === 'function') memory.release(); } catch { }
+  }
+}
+
+main();

package/scripts/memory.js

@@ -25,8 +25,17 @@ const fs = require('fs');
 
 const DB_PATH = path.join(os.homedir(), '.metame', 'memory.db');
 
+/** Minimal structured logger. level: 'INFO' | 'WARN' | 'ERROR' */
+function log(level, msg) {
+  const ts = new Date().toISOString();
+  process.stderr.write(`${ts} [${level}] ${msg}\n`);
+}
+
 // Lazy-init: only open DB when first called
 let _db = null;
+// Counts external callers that have called acquire() but not yet release().
+// Internal helpers (getDb, _trackSearch, etc.) do NOT affect this counter.
+let _refCount = 0;
 
 function getDb() {
   if (_db) return _db;
@@ -164,6 +173,9 @@ function getDb() {
   // One-time migration: copy recall_count → search_count for existing rows
   try { _db.exec('UPDATE facts SET search_count = recall_count WHERE recall_count > 0 AND search_count = 0'); } catch {}
 
+  // conflict_status: 'OK' (default) | 'CONFLICT' — set by _detectConflict for non-stateful relations
+  try { _db.exec("ALTER TABLE facts ADD COLUMN conflict_status TEXT NOT NULL DEFAULT 'OK'"); } catch {}
+
   return _db;
 }
 
@@ -260,13 +272,14 @@ function saveFacts(sessionId, project, facts, { scope = null } = {}) {
 
   const insert = db.prepare(`
     INSERT INTO facts (id, entity, relation, value, confidence, source_type, source_id, project, scope, tags, created_at, updated_at)
-    VALUES (?, ?, ?, ?, ?, 'session', ?, ?, ?, ?, datetime('now'), datetime('now'))
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'))
     ON CONFLICT(id) DO NOTHING
   `);
 
   let saved = 0;
   let skipped = 0;
   let superseded = 0;
+  let conflicts = 0;
   const savedFacts = [];
   const batchDedup = new Set();
 
@@ -287,8 +300,9 @@ function saveFacts(sessionId, project, facts, { scope = null } = {}) {
     const id = `f-${sessionId.slice(0, 8)}-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
     const tags = JSON.stringify(Array.isArray(f.tags) ? f.tags.slice(0, 3) : []);
     try {
+      const sourceType = f.source_type || 'session';
       insert.run(id, f.entity, f.relation, f.value.slice(0, 300),
-        f.confidence || 'medium', sessionId, normalizedProject, normalizedScope, tags);
+        f.confidence || 'medium', sourceType, sessionId, normalizedProject, normalizedScope, tags);
       batchDedup.add(dedupKey);
       savedFacts.push({ id, entity: f.entity, relation: f.relation, value: f.value,
         project: normalizedProject, scope: normalizedScope, tags: f.tags || [], created_at: new Date().toISOString() });
@@ -328,6 +342,20 @@ function saveFacts(sessionId, project, facts, { scope = null } = {}) {
         if (changes > 0) {
           _logSupersede(toSupersede, id, f.entity, f.relation, f.value, sessionId);
         }
+      } else {
+        // Conflict detection for non-stateful relations
+        let whereSql = '';
+        let filterParams = [];
+        if (normalizedScope === '*') {
+          whereSql = `((scope = '*') OR (scope IS NULL AND project = '*'))`;
+        } else if (normalizedScope) {
+          whereSql = `((scope = ?) OR (scope IS NULL AND project = ?))`;
+          filterParams = [normalizedScope, normalizedProject];
+        } else {
+          whereSql = `(project IN (?, '*'))`;
+          filterParams = [normalizedProject];
+        }
+        conflicts += _detectConflict(db, f, id, whereSql, filterParams, sessionId);
       }
     } catch { skipped++; }
   }
@@ -339,7 +367,9 @@ function saveFacts(sessionId, project, facts, { scope = null } = {}) {
     if (qmdClient) qmdClient.upsertFacts(savedFacts);
   }
 
-  return { saved, skipped, superseded };
+  if (conflicts > 0) log('WARN', `[MEMORY] ${conflicts} conflict(s) detected`);
+
+  return { saved, skipped, superseded, conflicts };
 }
 
 /**
@@ -361,6 +391,7 @@ function _trackSearch(ids) {
 }
 
 const SUPERSEDE_LOG = path.join(os.homedir(), '.metame', 'memory_supersede_log.jsonl');
+const CONFLICT_LOG  = path.join(os.homedir(), '.metame', 'memory_conflict_log.jsonl');
 
 /**
  * Append supersede operations to audit log (append-only, never mutated).
@@ -383,6 +414,77 @@ function _logSupersede(oldFacts, newId, entity, relation, newValue, sessionId) {
   } catch { /* non-fatal */ }
 }
 
+/**
+ * Detect value conflicts for non-stateful facts.
+ *
+ * When a new fact (entity, relation) already has an active record whose value
+ * differs significantly from the incoming value, both are flagged CONFLICT.
+ * "Significant difference" = trimmed values are not equal AND neither contains
+ * the other as a substring (handles minor rewording and prefix matches).
+ *
+ * @param {object} db            - DatabaseSync instance
+ * @param {object} fact          - The newly-inserted fact { entity, relation, value }
+ * @param {string} newId         - Row ID of the newly-inserted fact
+ * @param {string} whereSql      - Scope WHERE clause (reused from saveFacts)
+ * @param {Array}  filterParams  - Bind params for whereSql
+ * @param {string} sessionId     - Source session ID (for audit log)
+ * @returns {number} Number of conflicts detected (0 or more)
+ */
+function _detectConflict(db, fact, newId, whereSql, filterParams, sessionId) {
+  try {
+    const existing = db.prepare(
+      `SELECT id, value FROM facts
+       WHERE entity = ? AND relation = ? AND id != ? AND superseded_by IS NULL
+         AND (conflict_status IS NULL OR conflict_status NOT IN ('ARCHIVED', 'CONFLICT'))
+         AND ${whereSql}`
+    ).all(fact.entity, fact.relation, newId, ...filterParams);
+
+    if (existing.length === 0) return 0;
+
+    const newVal = fact.value.trim();
+    let conflictCount = 0;
+
+    const conflicting = [];
+    for (const row of existing) {
+      const oldVal = row.value.trim();
+      // Skip if values are equivalent or one contains the other
+      if (oldVal === newVal) continue;
+      if (oldVal.includes(newVal) || newVal.includes(oldVal)) continue;
+
+      // Mark existing record as CONFLICT
+      db.prepare(
+        `UPDATE facts SET conflict_status = 'CONFLICT', updated_at = datetime('now') WHERE id = ?`
+      ).run(row.id);
+
+      conflicting.push({ id: row.id, value: row.value.slice(0, 80) });
+      conflictCount++;
+    }
+
+    if (conflictCount > 0) {
+      // Mark the new fact as CONFLICT too
+      db.prepare(
+        `UPDATE facts SET conflict_status = 'CONFLICT', updated_at = datetime('now') WHERE id = ?`
+      ).run(newId);
+
+      // Audit log (append-only, never mutated)
+      try {
+        const entry = {
+          ts: new Date().toISOString(),
+          entity: fact.entity,
+          relation: fact.relation,
+          new_id: newId,
+          new_value: fact.value.slice(0, 80),
+          session_id: sessionId,
+          conflicting,
+        };
+        fs.appendFileSync(CONFLICT_LOG, JSON.stringify(entry) + '\n', 'utf8');
+      } catch { /* non-fatal */ }
+    }
+
+    return conflictCount;
+  } catch { return 0; }
+}
+
 /**
  * Scope filter semantics (new + legacy):
  * - New rows: prefer `scope` exact match or global scope '*'
@@ -426,7 +528,8 @@ async function searchFactsAsync(query, { limit = 5, project = null, scope = null
         const placeholders = ids.map(() => '?').join(',');
         let rows = db.prepare(
           `SELECT id, entity, relation, value, confidence, project, scope, tags, created_at
-           FROM facts WHERE id IN (${placeholders}) AND superseded_by IS NULL`
+           FROM facts WHERE id IN (${placeholders}) AND superseded_by IS NULL
+           AND (conflict_status IS NULL OR conflict_status NOT IN ('ARCHIVED', 'CONFLICT'))`
         ).all(...ids);
 
         // Apply project/scope filter
@@ -476,6 +579,7 @@ function searchFacts(query, { limit = 5, project = null, scope = null } = {}) {
         WHERE facts_fts MATCH ?
           AND ((f.scope = ? OR f.scope = '*') OR (f.scope IS NULL AND (f.project = ? OR f.project = '*')))
           AND f.superseded_by IS NULL
+          AND (f.conflict_status IS NULL OR f.conflict_status NOT IN ('ARCHIVED', 'CONFLICT'))
         ORDER BY rank LIMIT ?
       `;
       params = [sanitized, scope, project, limit];
@@ -484,6 +588,7 @@ function searchFacts(query, { limit = 5, project = null, scope = null } = {}) {
         SELECT f.id, f.entity, f.relation, f.value, f.confidence, f.project, f.scope, f.tags, f.created_at, rank
         FROM facts_fts fts JOIN facts f ON f.rowid = fts.rowid
         WHERE facts_fts MATCH ? AND (f.scope = ? OR f.scope = '*') AND f.superseded_by IS NULL
+          AND (f.conflict_status IS NULL OR f.conflict_status NOT IN ('ARCHIVED', 'CONFLICT'))
         ORDER BY rank LIMIT ?
       `;
       params = [sanitized, scope, limit];
@@ -492,6 +597,7 @@ function searchFacts(query, { limit = 5, project = null, scope = null } = {}) {
         SELECT f.id, f.entity, f.relation, f.value, f.confidence, f.project, f.scope, f.tags, f.created_at, rank
         FROM facts_fts fts JOIN facts f ON f.rowid = fts.rowid
         WHERE facts_fts MATCH ? AND (f.project = ? OR f.project = '*') AND f.superseded_by IS NULL
+          AND (f.conflict_status IS NULL OR f.conflict_status NOT IN ('ARCHIVED', 'CONFLICT'))
         ORDER BY rank LIMIT ?
       `;
       params = [sanitized, project, limit];
@@ -500,6 +606,7 @@ function searchFacts(query, { limit = 5, project = null, scope = null } = {}) {
         SELECT f.id, f.entity, f.relation, f.value, f.confidence, f.project, f.scope, f.tags, f.created_at, rank
         FROM facts_fts fts JOIN facts f ON f.rowid = fts.rowid
         WHERE facts_fts MATCH ? AND f.superseded_by IS NULL
+          AND (f.conflict_status IS NULL OR f.conflict_status NOT IN ('ARCHIVED', 'CONFLICT'))
         ORDER BY rank LIMIT ?
       `;
       params = [sanitized, limit];
@@ -518,20 +625,24 @@ function searchFacts(query, { limit = 5, project = null, scope = null } = {}) {
        FROM facts WHERE (entity LIKE ? OR value LIKE ? OR tags LIKE ?)
        AND ((scope = ? OR scope = '*') OR (scope IS NULL AND (project = ? OR project = '*')))
        AND superseded_by IS NULL
+       AND (conflict_status IS NULL OR conflict_status NOT IN ('ARCHIVED', 'CONFLICT'))
        ORDER BY created_at DESC LIMIT ?`
     : scope
       ? `SELECT id, entity, relation, value, confidence, project, scope, tags, created_at
        FROM facts WHERE (entity LIKE ? OR value LIKE ? OR tags LIKE ?)
        AND (scope = ? OR scope = '*') AND superseded_by IS NULL
+       AND (conflict_status IS NULL OR conflict_status NOT IN ('ARCHIVED', 'CONFLICT'))
        ORDER BY created_at DESC LIMIT ?`
       : project
         ? `SELECT id, entity, relation, value, confidence, project, scope, tags, created_at
        FROM facts WHERE (entity LIKE ? OR value LIKE ? OR tags LIKE ?)
        AND (project = ? OR project = '*') AND superseded_by IS NULL
+       AND (conflict_status IS NULL OR conflict_status NOT IN ('ARCHIVED', 'CONFLICT'))
        ORDER BY created_at DESC LIMIT ?`
         : `SELECT id, entity, relation, value, confidence, project, scope, tags, created_at
        FROM facts WHERE (entity LIKE ? OR value LIKE ? OR tags LIKE ?)
        AND superseded_by IS NULL
+       AND (conflict_status IS NULL OR conflict_status NOT IN ('ARCHIVED', 'CONFLICT'))
        ORDER BY created_at DESC LIMIT ?`;
   const likeResults = scope && project
     ? db.prepare(likeSql).all(like, like, like, scope, project, limit)
@@ -697,8 +808,35 @@ function stats() {
 /**
  * Close the database connection (for clean shutdown).
  */
-function close() {
+/**
+ * Acquire a reference. Call once per logical "session" (e.g. per task run).
+ * Ensures DB is open and increments the ref count.
+ * Must be paired with a matching release() call.
+ */
+function acquire() {
+  _refCount++;
+  getDb(); // ensure DB is initialised
+}
+
+/**
+ * Release a reference. When the last caller releases, the DB is closed.
+ * Safe to call even if acquire() was never called (no-op when _refCount <= 0).
+ */
+function release() {
+  if (_refCount > 0) _refCount--;
+  if (_refCount === 0 && _db) { _db.close(); _db = null; }
+}
+
+/**
+ * Backwards-compatible alias. Equivalent to release().
+ * External callers that previously called close() continue to work correctly.
+ */
+function close() { release(); }
+
+/** Force-close regardless of ref count. Only call on process exit. */
+function forceClose() {
+  _refCount = 0;
   if (_db) { _db.close(); _db = null; }
 }
 
-module.exports = { saveSession, saveFacts, searchFacts, searchFactsAsync, searchSessions, recentSessions, getSession, stats, close, DB_PATH };
+module.exports = { saveSession, saveFacts, searchFacts, searchFactsAsync, searchSessions, recentSessions, getSession, stats, acquire, release, close, forceClose, DB_PATH };

package/scripts/schema.js

@@ -11,8 +11,11 @@
  *   T1 — Identity (LOCKED, never auto-modify)
  *   T2 — Core Values (LOCKED, deep personality)
  *   T3 — Preferences (auto-writable, needs confidence)
- *   T4 — Context (free overwrite, current state)
  *   T5 — Evolution (system-managed, strict limits)
+ *
+ * NOTE: T4 (Context/Status) was intentionally removed. Work state (focus,
+ * active_projects, blockers) belongs in ~/.metame/memory/NOW.md (task
+ * whiteboard), not in the cognitive profile. This prevents role pollution.
  */
 
 const SCHEMA = {
@@ -49,14 +52,15 @@ const SCHEMA = {
   'cognition.metacognition.receptive_to_challenge': { tier: 'T3', type: 'enum', values: ['yes', 'sometimes', 'no'] },
   'cognition.metacognition.error_response': { tier: 'T3', type: 'enum', values: ['quick_pivot', 'root_cause_first', 'seek_help', 'retry_same'] },
 
-  // === T4: Context ===
-  'context.focus': { tier: 'T4', type: 'string', maxChars: 80 },
-  'context.focus_since': { tier: 'T4', type: 'string' },
-  'context.active_projects': { tier: 'T4', type: 'array', maxItems: 5 },
-  'context.blockers': { tier: 'T4', type: 'array', maxItems: 3 },
-  'context.energy': { tier: 'T4', type: 'enum', values: ['high', 'medium', 'low', null] },
-  'status.focus': { tier: 'T4', type: 'string', maxChars: 80 },
-  'status.language': { tier: 'T4', type: 'string' },
+  // === T3c: User Competence Map (ZPD scaffolding) ===
+  'user_competence_map': {
+    tier: 'T3',
+    type: 'map',         // dynamic key-value, keys are domain names
+    valueType: 'enum',
+    values: ['beginner', 'intermediate', 'expert'],
+    maxKeys: 20,
+    description: 'Per-domain skill level for ZPD-based explanation depth'
+  },
 
   // === T5: Evolution (system-managed) ===
   'evolution.last_distill': { tier: 'T5', type: 'string' },
@@ -144,6 +148,23 @@ function validate(key, value) {
     }
   }
 
+  if (def.type === 'map') {
+    if (typeof value !== 'object' || Array.isArray(value)) {
+      return { valid: false, reason: `${key} must be an object (map)` };
+    }
+    if (def.maxKeys && Object.keys(value).length > def.maxKeys) {
+      return { valid: false, reason: `${key} exceeds maxKeys (${def.maxKeys})` };
+    }
+    if (def.values) {
+      for (const [k, v] of Object.entries(value)) {
+        if (!def.values.includes(v)) {
+          return { valid: false, reason: `${key}.${k} must be one of: ${def.values.join(', ')}` };
+        }
+      }
+    }
+    return { valid: true };
+  }
+
   return { valid: true };
 }