memind/experience-service.mjs

import crypto from 'node:crypto';

import {
  experienceSearchHaystack,
  mapExperienceRow,
  normalizeExperienceRecordInput,
  serializeExperienceJson,
} from './experience-schema.mjs';

/**
 * Shared experience store (etat C of the goose scale plan).
 *
 * All goosed Worker instances read/write the same learned experience so that
 * capability is not siloed per instance. This first implementation is backed by
 * MySQL (`h5_experience`) with a keyword + recency ranking. The retrieval scoring
 * is deliberately isolated in `rankRows` so that swapping to PostgreSQL + pgvector
 * later only replaces the query/scoring layer, not the calling contract
 * (record / search / reflect).
 *
 * @param {import('mysql2/promise').Pool} pool
 * @param {object} [options]
 * @param {() => number} [options.now] - injectable clock for tests
 */
export function createExperienceService(pool, options = {}) {
  const now = options.now ?? (() => Date.now());
  const halfLifeMs = Math.max(
    60_000,
    Number(options.recencyHalfLifeMs ?? 30 * 24 * 60 * 60 * 1000),
  );

  function rankRows(rows, queryTerms, nowMs) {
    return rows
      .map((row) => {
        const haystack = experienceSearchHaystack(row);
        let keywordScore = 0;
        for (const term of queryTerms) {
          if (haystack.includes(term)) keywordScore += 1;
        }
        const ageMs = Math.max(0, nowMs - Number(row.updated_at));
        const recency = Math.pow(0.5, ageMs / halfLifeMs);
        return { row, score: keywordScore * recency };
      })
      .filter((entry) => entry.score > 0)
      .sort((a, b) => b.score - a.score);
  }

  function tokenize(query) {
    return [
      ...new Set(
        String(query ?? '')
          .toLowerCase()
          .split(/[^\p{L}\p{N}]+/u)
          .map((t) => t.trim())
          .filter((t) => t.length >= 2),
      ),
    ];
  }

  /**
   * Persist a piece of experience. Returns the stored record.
   */
  async function record(input) {
    const normalized = normalizeExperienceRecordInput(input);
    if (!normalized.title) throw experienceError('经验标题不能为空', 'invalid_experience_input');
    if (!normalized.body) throw experienceError('经验内容不能为空', 'invalid_experience_input');

    const id = crypto.randomUUID();
    const ts = now();
    const environmentJson = serializeExperienceJson(normalized.environment);
    const actionJson = serializeExperienceJson(normalized.action);
    const evidenceJson = serializeExperienceJson(normalized.evidence);

    await pool.query(
      `INSERT INTO h5_experience
         (id, scope, kind, title, body, tags_json, source_session_id, source_user_id,
          use_count, problem, environment_json, hypothesis, action_json, result, confidence,
          evidence_json, parent_experience_id, supersedes_id, status, created_at, updated_at)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
      [
        id,
        normalized.scope,
        normalized.kind,
        normalized.title,
        normalized.body,
        JSON.stringify(normalized.tags),
        normalized.sourceSessionId,
        normalized.sourceUserId,
        normalized.problem,
        environmentJson,
        normalized.hypothesis,
        actionJson,
        normalized.result,
        normalized.confidence,
        evidenceJson,
        normalized.parentExperienceId,
        normalized.supersedesId,
        normalized.status,
        ts,
        ts,
      ],
    );

    return mapExperienceRow({
      id,
      scope: normalized.scope,
      kind: normalized.kind,
      title: normalized.title,
      body: normalized.body,
      tags_json: JSON.stringify(normalized.tags),
      source_session_id: normalized.sourceSessionId,
      source_user_id: normalized.sourceUserId,
      use_count: 0,
      problem: normalized.problem,
      environment_json: environmentJson,
      hypothesis: normalized.hypothesis,
      action_json: actionJson,
      result: normalized.result,
      confidence: normalized.confidence,
      evidence_json: evidenceJson,
      parent_experience_id: normalized.parentExperienceId,
      supersedes_id: normalized.supersedesId,
      status: normalized.status,
      created_at: ts,
      updated_at: ts,
    });
  }

  /**
   * Retrieve the most relevant experience for a query within a scope.
   * @returns {Promise<Array>} ranked experiences (best first), max `limit`.
   */
  async function search(query, { scope = 'global', limit = 5 } = {}) {
    const terms = tokenize(query);
    if (terms.length === 0) return [];
    const [rows] = await pool.query(
      `SELECT id, scope, kind, title, body, tags_json, source_session_id,
              source_user_id, use_count, problem, environment_json, hypothesis,
              action_json, result, confidence, evidence_json, parent_experience_id,
              supersedes_id, status, created_at, updated_at
       FROM h5_experience
       WHERE scope = ? AND status = 'active'
       ORDER BY updated_at DESC
       LIMIT 500`,
      [scope],
    );
    const ranked = rankRows(rows, terms, now()).slice(0, Math.max(1, limit));
    if (ranked.length > 0) {
      const ids = ranked.map((entry) => entry.row.id);
      const placeholders = ids.map(() => '?').join(',');
      await pool
        .query(
          `UPDATE h5_experience SET use_count = use_count + 1 WHERE id IN (${placeholders})`,
          ids,
        )
        .catch(() => {});
    }
    return ranked.map((entry) => mapExperienceRow(entry.row));
  }

  /**
   * Placeholder for the reflection pass that distills raw session traces into
   * durable lessons. Wired later once the record() trigger points are defined;
   * kept here so the calling contract is stable.
   */
  async function reflect() {
    return { ok: false, reason: 'not_implemented' };
  }

  return { record, search, reflect };
}

function experienceError(message, code) {
  return Object.assign(new Error(message), { code });
}

export { formatExperienceInjectionBlock, formatExperienceInjectionLine } from './experience-schema.mjs';