@nogataka/claw-memory 0.1.3 → 0.3.0

package/dist/core/lesson-quality.js

@@ -0,0 +1,79 @@
+// src/core/lesson-quality.ts
+//
+// Lesson hygiene over time (design doc section 19 + section 7's quality phase):
+//  - confidence decay: lessons not surfaced in a while lose confidence, so
+//    stale advice naturally sinks in ranking. Long-lived general knowledge
+//    (global / user_preference) decays toward a higher floor.
+//  - expiry: lessons past their valid_until are auto-archived.
+//  - stale detection: report lessons unused for N days (no mutation).
+//
+// Intended to run periodically (CLI `claw-memory lessons decay`), not on the
+// hot path.
+import { sqlite } from "./db.js";
+import { listLessons, setStatus, recordEvent } from "./lessons.js";
+const DECAY_FACTOR = Number(process.env.LESSON_DECAY_FACTOR ?? 0.9);
+const STALE_DAYS = Number(process.env.LESSON_STALE_DAYS ?? 30);
+const FLOOR_DEFAULT = Number(process.env.LESSON_CONFIDENCE_FLOOR ?? 0.2);
+// General, broadly-true knowledge shouldn't decay into irrelevance.
+const FLOOR_GENERAL = Number(process.env.LESSON_CONFIDENCE_FLOOR_GENERAL ?? 0.5);
+function ageDays(ref, now) {
+    const t = new Date(ref).getTime();
+    if (!Number.isFinite(t))
+        return 0;
+    return (now - t) / 86_400_000;
+}
+function floorFor(scope) {
+    return scope === "global" || scope === "user_preference"
+        ? FLOOR_GENERAL
+        : FLOOR_DEFAULT;
+}
+/**
+ * Decay confidence of stale candidate/approved lessons and auto-archive expired
+ * ones. Returns counts. Idempotent enough to run on a schedule.
+ */
+export function decayConfidence(opts = {}) {
+    const factor = opts.factor ?? DECAY_FACTOR;
+    const staleDays = opts.staleDays ?? STALE_DAYS;
+    const now = Date.now();
+    const result = { scanned: 0, decayed: 0, archivedExpired: 0 };
+    const updateConfidence = sqlite.prepare("UPDATE lessons SET confidence = ?, updated_at = ? WHERE id = ?");
+    for (const status of ["candidate", "approved"]) {
+        for (const l of listLessons({ status }, 100_000)) {
+            result.scanned++;
+            // Expiry: valid_until in the past → archive.
+            if (l.validUntil && new Date(l.validUntil).getTime() < now) {
+                if (!opts.dryRun)
+                    setStatus(l.id, "archived", "valid_until passed");
+                result.archivedExpired++;
+                continue;
+            }
+            const age = ageDays(l.lastUsedAt ?? l.createdAt, now);
+            if (age < staleDays)
+                continue;
+            const floor = floorFor(l.scope);
+            const next = Math.max(floor, Math.round(l.confidence * factor * 10000) / 10000);
+            if (next < l.confidence - 1e-9) {
+                if (!opts.dryRun) {
+                    updateConfidence.run(next, new Date().toISOString(), l.id);
+                    recordEvent(l.id, "decay", {
+                        note: `confidence ${l.confidence.toFixed(4)}→${next.toFixed(4)} (age ${Math.round(age)}d)`,
+                    });
+                }
+                result.decayed++;
+            }
+        }
+    }
+    return result;
+}
+/** Lessons unused for >= `days` (no mutation) — candidates for review/removal. */
+export function listStale(days = STALE_DAYS) {
+    const now = Date.now();
+    const out = [];
+    for (const status of ["candidate", "approved"]) {
+        for (const l of listLessons({ status }, 100_000)) {
+            if (ageDays(l.lastUsedAt ?? l.createdAt, now) >= days)
+                out.push(l);
+        }
+    }
+    return out;
+}

package/dist/core/lesson-search.js

@@ -0,0 +1,145 @@
+// src/core/lesson-search.ts
+//
+// Lesson retrieval. Unlike conversation search (pure vector distance), lessons
+// are ranked by a weighted blend (design doc section 20): semantic similarity,
+// scope fit, confidence, recency, repo match and file match. Only 'approved'
+// lessons are surfaced by default — candidates stay out of agent context until
+// a human/rule promotes them.
+import { embedQuery } from "./embeddings.js";
+import { searchSimilarLessons, searchKeywordLessons, markUsed, } from "./lessons.js";
+import { resolveRepoId } from "./lesson-extract.js";
+const MAX_DISTANCE = Number(process.env.LESSON_SIMILARITY_MAX_DISTANCE ?? 0.6);
+const RECENCY_HALF_DAYS = Number(process.env.LESSON_RECENCY_DAYS ?? 180);
+// Section-20 weights (sum = 1.0).
+const W = {
+    semantic: 0.4,
+    scope: 0.2,
+    confidence: 0.15,
+    recency: 0.1,
+    repo: 0.1,
+    file: 0.05,
+};
+function fileOverlap(a, b) {
+    if (!b || b.length === 0 || a.length === 0)
+        return false;
+    return a.some((f) => b.some((g) => f.includes(g) || g.includes(f)));
+}
+/** How well a lesson's scope applies to the current context (0..1). */
+function scopeMatch(lesson, ctx) {
+    switch (lesson.scope) {
+        case "global":
+        case "user_preference":
+            return 0.7;
+        case "team":
+            return 0.6;
+        case "project":
+            return ctx.projectId && lesson.projectId === ctx.projectId ? 1 : 0.2;
+        case "repo":
+            return ctx.repoId && lesson.repoId === ctx.repoId ? 1 : 0.2;
+        case "file":
+            return fileOverlap(lesson.files, ctx.files) ? 1 : 0.2;
+        case "task":
+            return 0.3;
+        default:
+            return 0.3;
+    }
+}
+function recencyScore(lesson) {
+    const ref = lesson.lastUsedAt ?? lesson.createdAt;
+    const ageMs = Date.now() - new Date(ref).getTime();
+    const ageDays = ageMs / 86_400_000;
+    if (!Number.isFinite(ageDays) || ageDays < 0)
+        return 1;
+    return Math.max(0, 1 - ageDays / RECENCY_HALF_DAYS);
+}
+/** Cosine distance (0..2) → similarity (0..1). Keyword-only hits get a baseline. */
+function semanticScore(distance) {
+    if (distance == null)
+        return 0.5;
+    return Math.max(0, Math.min(1, 1 - distance));
+}
+function computeScore(lesson, distance, ctx) {
+    const repoMatch = ctx.repoId && lesson.repoId === ctx.repoId ? 1 : 0;
+    const fMatch = fileOverlap(lesson.files, ctx.files) ? 1 : 0;
+    return (W.semantic * semanticScore(distance) +
+        W.scope * scopeMatch(lesson, ctx) +
+        W.confidence * lesson.confidence +
+        W.recency * recencyScore(lesson) +
+        W.repo * repoMatch +
+        W.file * fMatch);
+}
+/**
+ * Hybrid lesson search: semantic (vector) + FTS keyword, de-duplicated by id,
+ * re-ranked by the section-20 blend. Returns highest-scoring first.
+ */
+export async function searchLessons(query, ctx = {}, opts = {}) {
+    const limit = opts.limit ?? 5;
+    const status = opts.status ?? "approved";
+    const repoId = ctx.repoId ?? resolveRepoId(ctx.projectId);
+    const fullCtx = { ...ctx, repoId };
+    const byId = new Map();
+    if (query.trim()) {
+        try {
+            const emb = await embedQuery(query);
+            for (const l of searchSimilarLessons(emb, {
+                topK: limit * 3,
+                maxDistance: MAX_DISTANCE,
+                status,
+            })) {
+                byId.set(l.id, { lesson: l, distance: l.distance });
+            }
+        }
+        catch (err) {
+            console.error("[claw-memory] lesson semantic search failed:", err);
+        }
+        for (const l of searchKeywordLessons(query, { topK: limit * 3, status })) {
+            if (!byId.has(l.id))
+                byId.set(l.id, { lesson: l });
+        }
+    }
+    const ranked = [...byId.values()]
+        .map(({ lesson, distance }) => ({
+        ...lesson,
+        distance: distance ?? 1,
+        score: computeScore(lesson, distance, fullCtx),
+    }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit);
+    if (opts.touch !== false && ranked.length > 0) {
+        markUsed(ranked.map((l) => l.id));
+    }
+    return ranked;
+}
+/**
+ * Format lessons as an agent-ready context block (design doc section 21).
+ * Lessons are presented as HINTS, not absolute facts — the agent must verify
+ * against current repository state before applying.
+ */
+export function formatLessonBlock(lessons) {
+    if (lessons.length === 0)
+        return "";
+    let text = "<relevant-lessons>\n";
+    text +=
+        "以下は、過去の類似セッションから抽出されたレッスンです。\n" +
+            "絶対的な事実ではなく、作業時のヒントとして扱ってください。\n" +
+            "適用前に現在のリポジトリ状態を確認してください。\n\n";
+    lessons.forEach((l, i) => {
+        text += `${i + 1}. ${l.lesson}\n`;
+        if (l.appliesWhen.length > 0) {
+            text += `   Applies when: ${l.appliesWhen.join("; ")}\n`;
+        }
+        if (l.avoidWhen.length > 0) {
+            text += `   Avoid when: ${l.avoidWhen.join("; ")}\n`;
+        }
+        text += `   Scope: ${l.scope} | Confidence: ${l.confidence.toFixed(2)}\n`;
+        if (l.sessionId)
+            text += `   Source: ${l.sessionId}\n`;
+    });
+    text += "</relevant-lessons>";
+    return text;
+}
+/** Convenience: search + format in one call (lesson_inject). */
+export async function injectLessons(query, ctx = {}, opts = {}) {
+    const lessons = await searchLessons(query, ctx, opts);
+    return formatLessonBlock(lessons);
+}

package/dist/core/lesson-share.js

@@ -0,0 +1,80 @@
+// src/core/lesson-share.ts
+//
+// Team sharing (design doc section 8 / Phase 8). claw-memory is local-first, so
+// there is no daemon and no automatic external sync. Sharing is explicit and
+// file-based: export a portable JSON bundle, import it elsewhere. Embeddings are
+// NOT exported — they are recomputed on import (the local e5 model is
+// deterministic), keeping bundles small and engine-version-independent.
+//
+// Imported lessons default to status 'candidate' so shared knowledge is
+// reviewed before it enters another developer's recall — the "public/team
+// 共有時の追加レビュー" requirement.
+import { embedPassage } from "./embeddings.js";
+import { listLessons, saveLesson, } from "./lessons.js";
+export const EXPORT_VERSION = 1;
+function toExported(l) {
+    return {
+        title: l.title,
+        lesson: l.lesson,
+        applies_when: l.appliesWhen,
+        avoid_when: l.avoidWhen,
+        evidence: l.evidence,
+        scope: l.scope,
+        obs_type: l.obsType,
+        concepts: l.concepts,
+        files: l.files,
+        confidence: l.confidence,
+        status: l.status,
+        created_at: l.createdAt,
+    };
+}
+/** Build a portable bundle. Defaults to approved lessons. */
+export function exportLessons(opts = {}) {
+    const status = opts.status ?? "approved";
+    const rows = listLessons({ projectId: opts.projectId ?? undefined, status }, 100_000);
+    return {
+        version: EXPORT_VERSION,
+        exported_at: new Date().toISOString(),
+        count: rows.length,
+        lessons: rows.map(toExported),
+    };
+}
+/** Import a bundle: re-embed each lesson and store it (default 'candidate'). */
+export async function importLessons(bundle, opts = {}) {
+    if (!bundle || !Array.isArray(bundle.lessons)) {
+        throw new Error("invalid lesson bundle: missing lessons[]");
+    }
+    if (bundle.version !== EXPORT_VERSION) {
+        throw new Error(`unsupported bundle version ${bundle.version} (expected ${EXPORT_VERSION})`);
+    }
+    const status = opts.status ?? "candidate";
+    let imported = 0;
+    let skipped = 0;
+    for (const it of bundle.lessons) {
+        const title = (it.title ?? "").trim();
+        const lesson = (it.lesson ?? "").trim();
+        if (!title || !lesson) {
+            skipped++;
+            continue;
+        }
+        const embedding = await embedPassage(`${title}\n${lesson}`);
+        saveLesson({
+            projectId: opts.projectId ?? null,
+            sessionId: opts.sessionId ?? "import",
+            title: title.slice(0, 200),
+            lesson: lesson.slice(0, 2000),
+            appliesWhen: (it.applies_when ?? []).map(String),
+            avoidWhen: (it.avoid_when ?? []).map(String),
+            evidence: it.evidence ?? null,
+            scope: it.scope ?? "repo",
+            obsType: it.obs_type ?? null,
+            concepts: (it.concepts ?? []).map(String),
+            files: (it.files ?? []).map(String),
+            confidence: typeof it.confidence === "number" ? it.confidence : 0.5,
+            status,
+            embedding,
+        });
+        imported++;
+    }
+    return { imported, skipped };
+}

package/dist/core/lessons.js

@@ -0,0 +1,332 @@
+// src/core/lessons.ts
+//
+// Lesson store: reusable, abstracted knowledge distilled from sessions. Mirrors
+// vector-memory.ts (vec0 embedding + readable metadata row + FTS5 keyword row),
+// but adds lifecycle (candidate → approved/rejected/archived/superseded), an
+// event audit trail, and inter-lesson links (duplicate / conflict / supersede).
+//
+// JSON-array fields (applies_when / avoid_when / concepts / files /
+// source_chunk_ids) are stored as TEXT, parsed on read — same convention as
+// conversation_chunks.concepts.
+import { randomUUID } from "node:crypto";
+import { sqlite, transaction } from "./db.js";
+function jsonArr(v) {
+    return v && v.length ? JSON.stringify(v) : null;
+}
+function parseArr(v) {
+    if (typeof v !== "string" || !v)
+        return [];
+    try {
+        const a = JSON.parse(v);
+        return Array.isArray(a) ? a.map(String) : [];
+    }
+    catch {
+        return [];
+    }
+}
+const LESSON_COLS = `l.id, l.project_id, l.repo_id, l.session_id, l.title, l.lesson,
+  l.applies_when, l.avoid_when, l.evidence, l.scope, l.obs_type, l.concepts, l.files,
+  l.confidence, l.source_chunk_ids, l.status, l.superseded_by, l.valid_until,
+  l.last_used_at, l.created_at, l.updated_at`;
+function mapRow(r) {
+    return {
+        id: r.id,
+        projectId: r.project_id,
+        repoId: r.repo_id,
+        sessionId: r.session_id,
+        title: r.title,
+        lesson: r.lesson,
+        appliesWhen: parseArr(r.applies_when),
+        avoidWhen: parseArr(r.avoid_when),
+        evidence: r.evidence,
+        scope: r.scope,
+        obsType: r.obs_type,
+        concepts: parseArr(r.concepts),
+        files: parseArr(r.files),
+        confidence: r.confidence,
+        sourceChunkIds: parseArr(r.source_chunk_ids),
+        status: r.status,
+        supersededBy: r.superseded_by,
+        validUntil: r.valid_until,
+        lastUsedAt: r.last_used_at,
+        createdAt: r.created_at,
+        updatedAt: r.updated_at,
+        distance: r.distance ?? 0,
+    };
+}
+/** Record a lifecycle event (status change, decay, scope edit, …). */
+export function recordEvent(lessonId, eventType, opts = {}) {
+    sqlite
+        .prepare(`INSERT INTO lesson_events(id, lesson_id, event_type, old_status, new_status, note, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`)
+        .run(randomUUID(), lessonId, eventType, opts.oldStatus ?? null, opts.newStatus ?? null, opts.note ?? null, new Date().toISOString());
+}
+/** Save one lesson: vec0 embedding + metadata row + FTS keyword row, atomically. */
+export function saveLesson(input) {
+    const insertVec = sqlite.prepare("INSERT INTO lesson_vec(embedding, project_id, scope) VALUES (?, ?, ?)");
+    const insertMeta = sqlite.prepare(`INSERT INTO lessons(
+        id, vec_rowid, project_id, repo_id, session_id, title, lesson,
+        applies_when, avoid_when, evidence, scope, obs_type, concepts, files,
+        confidence, source_chunk_ids, status, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const insertFts = sqlite.prepare("INSERT INTO lessons_fts(lesson_id, text) VALUES (?, ?)");
+    const id = randomUUID();
+    const now = new Date().toISOString();
+    const scope = input.scope ?? "repo";
+    const status = input.status ?? "candidate";
+    const confidence = input.confidence ?? 0.5;
+    transaction(() => {
+        const res = insertVec.run(Buffer.from(input.embedding.buffer), input.projectId ?? null, scope);
+        const vecRowid = res.lastInsertRowid;
+        insertMeta.run(id, vecRowid, input.projectId ?? null, input.repoId ?? null, input.sessionId ?? null, input.title, input.lesson, jsonArr(input.appliesWhen), jsonArr(input.avoidWhen), input.evidence ?? null, scope, input.obsType ?? null, jsonArr(input.concepts), jsonArr(input.files), confidence, jsonArr(input.sourceChunkIds), status, now, now);
+        insertFts.run(id, `${input.title}\n${input.lesson}`);
+        recordEvent(id, "created", { newStatus: status });
+    });
+    return id;
+}
+export function getLesson(id) {
+    const row = sqlite
+        .prepare(`SELECT ${LESSON_COLS} FROM lessons l WHERE l.id = ?`)
+        .get(id);
+    return row ? mapRow(row) : null;
+}
+export function getLessonsByIds(ids) {
+    if (ids.length === 0)
+        return [];
+    const placeholders = ids.map(() => "?").join(",");
+    const rows = sqlite
+        .prepare(`SELECT ${LESSON_COLS} FROM lessons l WHERE l.id IN (${placeholders})`)
+        .all(...ids);
+    return rows.map(mapRow);
+}
+/** Build a WHERE fragment from a LessonFilter. */
+function lessonWhere(filter) {
+    const clauses = [];
+    const params = [];
+    if (filter?.status) {
+        clauses.push("l.status = ?");
+        params.push(filter.status);
+    }
+    if (filter?.scope) {
+        clauses.push("l.scope = ?");
+        params.push(filter.scope);
+    }
+    if (filter?.projectId) {
+        clauses.push("l.project_id = ?");
+        params.push(filter.projectId);
+    }
+    if (filter?.concept) {
+        clauses.push("l.concepts LIKE ?");
+        params.push(`%${filter.concept}%`);
+    }
+    if (filter?.file) {
+        clauses.push("l.files LIKE ?");
+        params.push(`%${filter.file}%`);
+    }
+    return { sql: clauses.length ? clauses.join(" AND ") : "1=1", params };
+}
+export function listLessons(filter, limit = 200) {
+    const w = lessonWhere(filter);
+    const rows = sqlite
+        .prepare(`SELECT ${LESSON_COLS} FROM lessons l
+       WHERE ${w.sql}
+       ORDER BY l.updated_at DESC LIMIT ?`)
+        .all(...w.params, limit);
+    return rows.map(mapRow);
+}
+export function getLessonCount(filter) {
+    const w = lessonWhere(filter);
+    const row = sqlite
+        .prepare(`SELECT COUNT(*) c FROM lessons l WHERE ${w.sql}`)
+        .get(...w.params);
+    return row.c;
+}
+/** Lessons involved in a conflicts_with link (for Conflict Review). */
+export function listConflicts(projectId, limit = 200) {
+    const proj = projectId ? "AND l.project_id = ?" : "";
+    const rows = sqlite
+        .prepare(`SELECT DISTINCT ${LESSON_COLS} FROM lessons l
+       INNER JOIN lesson_links k
+         ON (k.lesson_id = l.id OR k.linked_lesson_id = l.id)
+       WHERE k.relation = 'conflicts_with' AND l.status != 'rejected' ${proj}
+       ORDER BY l.updated_at DESC LIMIT ?`)
+        .all(...(projectId ? [projectId] : []), limit);
+    return rows.map(mapRow);
+}
+export function getConflictCount(projectId) {
+    const proj = projectId ? "AND l.project_id = ?" : "";
+    const row = sqlite
+        .prepare(`SELECT COUNT(DISTINCT l.id) c FROM lessons l
+       INNER JOIN lesson_links k
+         ON (k.lesson_id = l.id OR k.linked_lesson_id = l.id)
+       WHERE k.relation = 'conflicts_with' AND l.status != 'rejected' ${proj}`)
+        .get(...(projectId ? [projectId] : []));
+    return row.c;
+}
+/** KNN semantic search over lessons, filtered by project/scope inside MATCH. */
+export function searchSimilarLessons(queryEmbedding, opts = {}) {
+    const topK = opts.topK ?? 8;
+    // vec0 MATCH metadata filters: project must match OR be a cross-project scope.
+    const stmt = sqlite.prepare(`
+    SELECT ${LESSON_COLS}, v.distance
+    FROM (
+      SELECT rowid, distance FROM lesson_vec
+      WHERE embedding MATCH ? AND k = ?
+    ) v
+    INNER JOIN lessons l ON l.vec_rowid = v.rowid
+    WHERE ${opts.status ? "l.status = ?" : "1=1"}
+      ${opts.maxDistance != null ? "AND v.distance <= ?" : ""}
+    ORDER BY v.distance
+  `);
+    const params = [
+        Buffer.from(queryEmbedding.buffer),
+        topK,
+    ];
+    if (opts.status)
+        params.push(opts.status);
+    if (opts.maxDistance != null)
+        params.push(opts.maxDistance);
+    const rows = stmt.all(...params);
+    return rows.map(mapRow);
+}
+/** FTS5 keyword search over lesson title + body. */
+export function searchKeywordLessons(query, opts = {}) {
+    const match = toFtsQuery(query);
+    if (!match)
+        return [];
+    const rows = sqlite
+        .prepare(`SELECT ${LESSON_COLS}
+       FROM lessons_fts f
+       INNER JOIN lessons l ON l.id = f.lesson_id
+       WHERE f.text MATCH ? ${opts.status ? "AND l.status = ?" : ""}
+       LIMIT ?`)
+        .all(match, ...(opts.status ? [opts.status] : []), opts.topK ?? 8);
+    return rows.map(mapRow);
+}
+/** Transition a lesson's status, stamping updated_at and recording the event. */
+export function setStatus(id, newStatus, note) {
+    const current = sqlite
+        .prepare("SELECT status FROM lessons WHERE id = ?")
+        .get(id);
+    if (!current)
+        return false;
+    const now = new Date().toISOString();
+    sqlite
+        .prepare("UPDATE lessons SET status = ?, updated_at = ? WHERE id = ?")
+        .run(newStatus, now, id);
+    recordEvent(id, "status_change", {
+        oldStatus: current.status,
+        newStatus,
+        note,
+    });
+    return true;
+}
+/** Mark `oldId` superseded by `newId` and link them. */
+export function supersede(oldId, newId) {
+    const current = sqlite
+        .prepare("SELECT status FROM lessons WHERE id = ?")
+        .get(oldId);
+    if (!current)
+        return false;
+    const now = new Date().toISOString();
+    transaction(() => {
+        sqlite
+            .prepare("UPDATE lessons SET status = 'superseded', superseded_by = ?, updated_at = ? WHERE id = ?")
+            .run(newId, now, oldId);
+        recordEvent(oldId, "superseded", {
+            oldStatus: current.status,
+            newStatus: "superseded",
+            note: `superseded_by=${newId}`,
+        });
+        linkLessons(newId, oldId, "supersedes");
+    });
+    return true;
+}
+/** Update one or more editable fields (scope / confidence / valid_until). */
+export function updateLesson(id, fields) {
+    const sets = [];
+    const params = [];
+    if (fields.scope !== undefined) {
+        sets.push("scope = ?");
+        params.push(fields.scope);
+    }
+    if (fields.confidence !== undefined) {
+        sets.push("confidence = ?");
+        params.push(fields.confidence);
+    }
+    if (fields.validUntil !== undefined) {
+        sets.push("valid_until = ?");
+        params.push(fields.validUntil);
+    }
+    if (sets.length === 0)
+        return false;
+    sets.push("updated_at = ?");
+    params.push(new Date().toISOString());
+    params.push(id);
+    const res = sqlite
+        .prepare(`UPDATE lessons SET ${sets.join(", ")} WHERE id = ?`)
+        .run(...params);
+    if (res.changes > 0)
+        recordEvent(id, "edited", { note: sets.join(",") });
+    return res.changes > 0;
+}
+/** Bump last_used_at when a lesson is surfaced by search/inject. */
+export function markUsed(ids) {
+    if (ids.length === 0)
+        return;
+    const now = new Date().toISOString();
+    const stmt = sqlite.prepare("UPDATE lessons SET last_used_at = ? WHERE id = ?");
+    transaction(() => {
+        for (const id of ids)
+            stmt.run(now, id);
+    });
+}
+export function linkLessons(lessonId, linkedLessonId, relation) {
+    sqlite
+        .prepare(`INSERT INTO lesson_links(id, lesson_id, linked_lesson_id, relation, created_at)
+       VALUES (?, ?, ?, ?, ?)`)
+        .run(randomUUID(), lessonId, linkedLessonId, relation, new Date().toISOString());
+}
+export function getEvents(lessonId) {
+    const rows = sqlite
+        .prepare(`SELECT id, event_type, old_status, new_status, note, created_at
+       FROM lesson_events WHERE lesson_id = ? ORDER BY created_at ASC`)
+        .all(lessonId);
+    return rows.map((r) => ({
+        id: r.id,
+        eventType: r.event_type,
+        oldStatus: r.old_status,
+        newStatus: r.new_status,
+        note: r.note,
+        createdAt: r.created_at,
+    }));
+}
+/** Links where this lesson is either side (incoming + outgoing). */
+export function getLinks(lessonId) {
+    const rows = sqlite
+        .prepare(`SELECT id, lesson_id, linked_lesson_id, relation, created_at
+       FROM lesson_links WHERE lesson_id = ? OR linked_lesson_id = ?
+       ORDER BY created_at ASC`)
+        .all(lessonId, lessonId);
+    return rows.map((r) => ({
+        id: r.id,
+        lessonId: r.lesson_id,
+        linkedLessonId: r.linked_lesson_id,
+        relation: r.relation,
+        createdAt: r.created_at,
+    }));
+}
+/**
+ * Turn a free-text query into a safe FTS5 OR-query of quoted terms (trigram
+ * tokenizer needs >=3-char terms). Mirrors vector-memory.toFtsQuery.
+ */
+function toFtsQuery(query) {
+    const terms = query
+        .replace(/["()*:^]/g, " ")
+        .split(/\s+/)
+        .filter((t) => t.length >= 3)
+        .map((t) => `"${t.replace(/"/g, "")}"`);
+    if (terms.length === 0)
+        return null;
+    return terms.join(" OR ");
+}

package/dist/core/logsearch/paths.js

@@ -6,6 +6,28 @@ import os from "node:os";
 import path from "node:path";
 export const claudeProjectsRoot = path.join(os.homedir(), ".claude", "projects");
 export const codexSessionsRoot = path.join(os.homedir(), ".codex", "sessions");
+/**
+ * Where to look for ChatGPT web "Export data" bundles (`conversations.json`).
+ * Unlike Claude Code / Codex, ChatGPT web conversations are NOT stored locally —
+ * the user downloads the official export and drops the file(s) here. Override
+ * `CLAW_MEMORY_CHATGPT_EXPORT` with either a single file or a directory.
+ */
+export const chatgptExportRoot = process.env.CLAW_MEMORY_CHATGPT_EXPORT ||
+    path.join(os.homedir(), ".claw-memory", "chatgpt");
+/**
+ * Stable synthetic "project" that distilled ChatGPT conversations are grouped
+ * under. Deliberately independent of where the export file lives, so moving the
+ * export doesn't fork a new project and the viewer always shows one tidy
+ * "chatgpt" project. ChatGPT conversations have no repo/cwd of their own.
+ */
+export const chatgptProjectPath = path.join(os.homedir(), ".claw-memory", "chatgpt");
 /** Max transcript size to scan; larger files are skipped (cc-search parity). */
 export const MAX_LOG_FILE_SIZE = 10 * 1024 * 1024;
+/**
+ * ChatGPT exports are a single JSON file holding the whole account history, so
+ * they can be much larger than a per-session transcript. JSON.parse reads the
+ * whole file into memory; this cap (default 200 MB) bounds that. Override with
+ * `CLAW_MEMORY_CHATGPT_MAX_BYTES`.
+ */
+export const MAX_CHATGPT_FILE_SIZE = Number(process.env.CLAW_MEMORY_CHATGPT_MAX_BYTES ?? 200 * 1024 * 1024);
 export const UUID_JSONL_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.jsonl$/i;