@nogataka/claw-memory 0.1.3 → 0.2.0

package/README.ja.md

@@ -2,6 +2,8 @@
 
 [English](README.md) | **日本語**
 
+![claw-memory メモリビューア](docs/screenshot.png)
+
 **AI コーディングエージェント（Claude Code / Codex）のためのローカル完結型・長期記憶。**
 エージェントが過去のセッション・あなたの好み・以前の決定事項を記憶し、記録済みの全
 トランスクリプトを横断検索できます。デーモン不要、Python 不要、外部ベクトル DB 不要。
@@ -42,11 +44,16 @@ npm install -g @nogataka/claw-memory
 | ソース | 内容 | ツール |
 |--------|------|--------|
 | **蒸留 DB** | LLM がセッションを要約 → 要約・好み・構造化メタデータ付きの埋め込みチャンク。セマンティック検索可能。 | `memory_recall`, `memory_search`, `memory_get` |
-| **生ログ検索** | 実際の Claude Code（`~/.claude/projects`）/ Codex（`~/.codex/sessions`）ログを全文検索。蒸留していないセッションも対象。 | `memory_search_logs` |
+| **生ログ検索** | 実際の Claude Code（`~/.claude/projects`）/ Codex（`~/.codex/sessions`）/ **ChatGPT web** エクスポート（`conversations.json`）ログを全文検索。蒸留していないセッションも対象。 | `memory_search_logs` |
 
 蒸留 DB は整理済みで高速に想起でき、生ログ検索は claw-memory 導入前を含め「いつか話した
 こと」を必ず見つけられるセーフティネットです。
 
+**ChatGPT web** の会話は OpenAI サーバー側にありローカルに残らないため、公式エクスポートから読み込みます。
+ChatGPT → Settings → **Data controls** → **Export data** でダウンロードし、解凍して `conversations.json` を
+`~/.claw-memory/chatgpt/` に置く（または `CLAW_MEMORY_CHATGPT_EXPORT` でファイル/フォルダを指定）だけで、
+他ログと同様に検索でき、`claw-memory distill-chatgpt` で専用 `chatgpt` プロジェクトとして意味 DB にも取り込めます。
+
 ### 2. 自動取り込み（distill）
 
 セッション終了時、トランスクリプトを次の形に蒸留します。
@@ -94,7 +101,19 @@ npm install -g @nogataka/claw-memory
 
 ビルド不要・読み取り専用のビューア（`claw-memory ui`）。プロジェクト・要約・チャンク
 （メタデータ付き）・好みを閲覧でき、生ログ検索も実行できます。SSE で開いている間は自動
-更新。起動した時だけ動きます。
+更新。起動した時だけ動きます。抽出されたレッスンをレビュー・承認・編集できる **Lessons**
+タブも備えています。
+
+### 8. 再利用可能なレッスン
+
+過去ログをそのまま検索するだけでなく、claw-memory は AI コーディングセッションを
+**再利用可能なレッスン**へと蒸留します。プロジェクト固有の制約、デバッグパターン、設計
+判断、ユーザーの開発方針などの、実行可能で抽象化された知識です。レッスンは通常の要約と
+同時に抽出され（追加の LLM 呼び出しなし）、ローカルに保存され、同じローカルモデルで埋め込
+まれ、（承認後のみ）類似タスク時に想起されます。各レッスンは `scope`・`confidence`・
+`applies_when` / `avoid_when` と、ライフサイクル（candidate → approved → archived /
+superseded）を持ち、重複・矛盾検出と時間経過による confidence 減衰を備えます。raw ログは
+根拠として保持しつつ、通常の想起では簡潔で再利用可能なレッスンを優先します。
 
 ---
 
@@ -195,11 +214,17 @@ npm link             # 任意: `claw-memory` バイナリを公開
 | `memory_remember(text, cwd?, sessionId?)` | フリーテキストのメモを永続保存。 |
 | `memory_distill(cwd, sessionId? \| transcriptPath?)` | セッションを要約して記憶化（LLM バックエンドが必要）。 |
 | `memory_get_preferences(cwd?)` | プロジェクトの保存済み好みを一覧。 |
-| `memory_search_logs(query, sources?, projectPath?, startDate?, endDate?, limit?, offset?)` | Claude Code + Codex の生ログを全文検索。 |
+| `memory_search_logs(query, sources?, projectPath?, startDate?, endDate?, limit?, offset?)` | Claude Code + Codex + ChatGPT-web の生ログを全文検索（`sources`: `claude-code` / `codex` / `chatgpt-web`）。 |
 | `memory_forget(ids)` | チャンクをソフト削除（検索 / recall / ビューアから除外）。 |
+| `lesson_search(query, cwd?, limit?)` | 承認済みレッスンを関連度 + scope + confidence で検索。 |
+| `lesson_inject(query, cwd?, limit?)` | 同上を `<relevant-lessons>` ブロックとして返す。 |
+| `lesson_get(lesson_id)` | レッスン1件の詳細（全フィールド + 履歴 + リンク）。 |
+| `lesson_extract(cwd, sessionId? \| transcriptPath?)` | セッションから専用のレッスン抽出（LLM 必要）。 |
+| `lesson_approve / lesson_reject / lesson_archive(lesson_id, reason?)` | ステータス遷移。 |
+| `lesson_supersede(old_lesson_id, new_lesson_id)` | 古いレッスンを新しいもので置き換え。 |
 
-`memory_distill`（LLM）と `memory_search_logs`（`~/.claude/projects`・`~/.codex/sessions`
-を直接読む）以外は完全ローカルで動作します。
+`memory_distill` / `lesson_extract`（LLM）と `memory_search_logs`
+（`~/.claude/projects`・`~/.codex/sessions` を直接読む）以外は完全ローカルで動作します。
 
 ---
 
@@ -218,6 +243,12 @@ npm link             # 任意: `claw-memory` バイナリを公開
 | `CLAW_MEMORY_EXCLUDED_PROJECTS` | — | 記録・想起しないパス部分文字列（カンマ/コロン区切り）。 |
 | `MEMORY_SIMILARITY_MAX_DISTANCE` | `0.6` | セマンティックヒットの最大コサイン距離（小さいほど厳格）。 |
 | `CLAW_MEMORY_UI_PORT` | `4319` | ビューアのポート。 |
+| `LESSON_RECALL_LIMIT` | `3` | recall ブロックに注入する承認済みレッスン数（`0` で無効）。 |
+| `CLAW_MEMORY_LESSON_DEDICATED` | — | `1` で専用の高品質レッスン抽出パスを実行（LLM 追加呼び出し）。 |
+| `CLAW_MEMORY_LESSON_CONFLICT_LLM` | — | `1` で抽出時に LLM による矛盾検出を有効化。 |
+| `LESSON_DECAY_FACTOR` / `LESSON_STALE_DAYS` | `0.9` / `30` | `lessons decay` の減衰係数と陳腐化しきい値。 |
+| `CLAW_MEMORY_CHATGPT_EXPORT` | `~/.claw-memory/chatgpt` | ChatGPT `conversations.json` エクスポート（ファイル or `*.json` を含むフォルダ）。 |
+| `CLAW_MEMORY_CHATGPT_MAX_BYTES` | `209715200`（200 MB） | これを超える ChatGPT エクスポートはスキップ（メモリ内パースのため）。 |
 
 ### LLM バックエンド
 
@@ -241,8 +272,18 @@ claw-memory mcp                                  # stdio MCP サーバー（エ
 claw-memory ui [--port N] [--open]               # 読み取り専用 Web ビューア
 claw-memory distill --cwd P --session ID [--path FILE] [--if-stale]
 claw-memory distill-codex [--recent] [--limit N] [--all]
+claw-memory distill-chatgpt [--limit N] [--all]  # ChatGPT web エクスポートの会話を蒸留
 claw-memory remember --cwd P "メモ"
-claw-memory search-logs "クエリ" [--source claude-code,codex] [--project P]
+claw-memory lessons list [--status candidate|approved|...] [--cwd P]
+claw-memory lessons search "クエリ" [--cwd P] [--limit N]
+claw-memory lessons inject "クエリ" [--cwd P] [--limit N]
+claw-memory lessons extract --session ID [--cwd P] [--path FILE]
+claw-memory lessons approve|reject|archive <lesson_id> [--reason R]
+claw-memory lessons supersede <old_id> <new_id>
+claw-memory lessons decay [--days N] [--factor F] [--dry]
+claw-memory lessons export [--status S] [--cwd P] > bundle.json
+claw-memory lessons import bundle.json [--status S] [--cwd P]
+claw-memory search-logs "クエリ" [--source claude-code,codex,chatgpt-web] [--project P]
                                  [--start ISO] [--end ISO] [--limit N] [--offset N]
 claw-memory hook <recall|distill>               # ライフサイクルフック（JSON を stdin で受領）
 claw-memory install   [--codex | --claude-code] # MCP + フックを登録（既定: codex）

package/README.md

@@ -2,6 +2,8 @@
 
 **English** | [日本語](README.ja.md)
 
+![claw-memory memory viewer](docs/screenshot.png)
+
 **Local, in-process long-term memory for AI coding agents (Claude Code & Codex).**
 Your agent remembers past sessions, your preferences, and prior decisions — and can
 search every raw transcript you've ever recorded. No daemon, no Python, no external
@@ -44,11 +46,18 @@ npm install -g @nogataka/claw-memory
 | Source | What it is | Tooling |
 |--------|-----------|---------|
 | **Distilled DB** | LLM-summarized sessions → summaries, preferences, and embedded conversation chunks with structured metadata. Semantically searchable. | `memory_recall`, `memory_search`, `memory_get` |
-| **Raw transcript search** | Full-text grep over your *actual* Claude Code (`~/.claude/projects`) and Codex (`~/.codex/sessions`) logs — including sessions that were never distilled. | `memory_search_logs` |
+| **Raw transcript search** | Full-text grep over your *actual* Claude Code (`~/.claude/projects`), Codex (`~/.codex/sessions`), and **ChatGPT web** export (`conversations.json`) logs — including sessions that were never distilled. | `memory_search_logs` |
 
 The distilled DB is curated and fast to recall; raw search is a safety net that finds
 anything you ever discussed, even before claw-memory was installed.
 
+**ChatGPT web** conversations live on OpenAI's servers, not on disk, so claw-memory
+reads them from the official export: ChatGPT → Settings → **Data controls** → **Export
+data**; unzip and drop `conversations.json` into `~/.claw-memory/chatgpt/` (or point
+`CLAW_MEMORY_CHATGPT_EXPORT` at the file/folder). Then it's searchable like any other
+log, and `claw-memory distill-chatgpt` adds it to the semantic DB under a dedicated
+`chatgpt` project.
+
 ### 2. Automatic capture (distill)
 
 When a session ends, claw-memory distills the transcript into:
@@ -99,7 +108,21 @@ handle the high-frequency distill work.
 
 A zero-build, read-only viewer (`claw-memory ui`) to browse projects, summaries,
 chunks (with their metadata), preferences, and to run raw-log search — with live
-updates via SSE. It runs only when you start it.
+updates via SSE. It runs only when you start it. The viewer also has a **Lessons**
+tab for reviewing, approving and editing extracted lessons.
+
+### 8. Reusable lessons
+
+Beyond retrieving past logs, claw-memory distills AI coding sessions into
+**reusable lessons** — actionable, abstracted knowledge such as project-specific
+constraints, debugging patterns, design decisions and user preferences. Lessons
+are extracted alongside the normal summary (no extra LLM call), stored locally,
+embedded with the same local model, and surfaced (only after approval) when a
+similar task appears later. Each lesson carries `scope`, `confidence`,
+`applies_when` / `avoid_when` and a lifecycle (candidate → approved → archived /
+superseded), with duplicate / conflict detection and confidence decay over time.
+Raw logs remain available as evidence; day-to-day recall focuses on concise,
+reusable lessons.
 
 ---
 
@@ -200,11 +223,18 @@ npm link             # optional: expose the `claw-memory` binary
 | `memory_remember(text, cwd?, sessionId?)` | Store a durable free-text note. |
 | `memory_distill(cwd, sessionId? \| transcriptPath?)` | Summarize a session into memory (needs an LLM backend). |
 | `memory_get_preferences(cwd?)` | List stored preferences for the project. |
-| `memory_search_logs(query, sources?, projectPath?, startDate?, endDate?, limit?, offset?)` | Full-text search over RAW Claude Code + Codex transcripts. |
+| `memory_search_logs(query, sources?, projectPath?, startDate?, endDate?, limit?, offset?)` | Full-text search over RAW Claude Code + Codex + ChatGPT-web transcripts (`sources`: `claude-code` / `codex` / `chatgpt-web`). |
 | `memory_forget(ids)` | Soft-delete chunks (hidden from search / recall / viewer). |
+| `lesson_search(query, cwd?, limit?)` | Search approved reusable lessons, ranked by relevance + scope + confidence. |
+| `lesson_inject(query, cwd?, limit?)` | Same, returned as a ready-to-read `<relevant-lessons>` block. |
+| `lesson_get(lesson_id)` | Full detail of one lesson (fields + history + links). |
+| `lesson_extract(cwd, sessionId? \| transcriptPath?)` | Dedicated lesson-extraction pass over a session (needs an LLM backend). |
+| `lesson_approve / lesson_reject / lesson_archive(lesson_id, reason?)` | Lifecycle transitions. |
+| `lesson_supersede(old_lesson_id, new_lesson_id)` | Replace an old lesson with a newer one. |
 
-All tools are fully local except `memory_distill` (LLM) and `memory_search_logs`
-(reads `~/.claude/projects` and `~/.codex/sessions` directly).
+All tools are fully local except `memory_distill` / `lesson_extract` (LLM) and
+`memory_search_logs` (reads `~/.claude/projects` and `~/.codex/sessions`
+directly).
 
 ---
 
@@ -223,6 +253,12 @@ All tools are fully local except `memory_distill` (LLM) and `memory_search_logs`
 | `CLAW_MEMORY_EXCLUDED_PROJECTS` | — | Comma/colon-separated path substrings to never record or recall. |
 | `MEMORY_SIMILARITY_MAX_DISTANCE` | `0.6` | Max cosine distance for a semantic hit (lower = stricter). |
 | `CLAW_MEMORY_UI_PORT` | `4319` | Viewer port. |
+| `LESSON_RECALL_LIMIT` | `3` | Approved lessons injected into the recall block (`0` disables). |
+| `CLAW_MEMORY_LESSON_DEDICATED` | — | `1` = run a separate, higher-quality lesson-extraction pass (extra LLM call). |
+| `CLAW_MEMORY_LESSON_CONFLICT_LLM` | — | `1` = use the LLM to detect conflicting lessons during extraction. |
+| `LESSON_DECAY_FACTOR` / `LESSON_STALE_DAYS` | `0.9` / `30` | Confidence-decay factor and staleness threshold for `lessons decay`. |
+| `CLAW_MEMORY_CHATGPT_EXPORT` | `~/.claw-memory/chatgpt` | ChatGPT `conversations.json` export — a file or a folder of `*.json`. |
+| `CLAW_MEMORY_CHATGPT_MAX_BYTES` | `209715200` (200 MB) | Skip ChatGPT export files larger than this (parsed in memory). |
 
 ### LLM backends
 
@@ -246,8 +282,18 @@ claw-memory mcp                                  # stdio MCP server (what agents
 claw-memory ui [--port N] [--open]               # read-only web viewer
 claw-memory distill --cwd P --session ID [--path FILE] [--if-stale]
 claw-memory distill-codex [--recent] [--limit N] [--all]
+claw-memory distill-chatgpt [--limit N] [--all]  # distill ChatGPT web export conversations
 claw-memory remember --cwd P "a note"
-claw-memory search-logs "query" [--source claude-code,codex] [--project P]
+claw-memory lessons list [--status candidate|approved|...] [--cwd P]
+claw-memory lessons search "query" [--cwd P] [--limit N]
+claw-memory lessons inject "query" [--cwd P] [--limit N]
+claw-memory lessons extract --session ID [--cwd P] [--path FILE]
+claw-memory lessons approve|reject|archive <lesson_id> [--reason R]
+claw-memory lessons supersede <old_id> <new_id>
+claw-memory lessons decay [--days N] [--factor F] [--dry]
+claw-memory lessons export [--status S] [--cwd P] > bundle.json
+claw-memory lessons import bundle.json [--status S] [--cwd P]
+claw-memory search-logs "query" [--source claude-code,codex,chatgpt-web] [--project P]
                                  [--start ISO] [--end ISO] [--limit N] [--offset N]
 claw-memory hook <recall|distill>               # lifecycle hook (reads JSON on stdin)
 claw-memory install   [--codex | --claude-code] # register MCP + hooks (default: codex)

package/dist/cli.js

@@ -162,6 +162,47 @@ async function main() {
             console.log(JSON.stringify({ scanned: files.length, distilled, skipped, failed }, null, 2));
             process.exit(0);
         }
+        case "distill-chatgpt": {
+            const { loadChatgptConversations } = await import("./core/logsearch/recent.js");
+            const { chatgptProjectPath } = await import("./core/logsearch/paths.js");
+            const { distill } = await import("./core/distill.js");
+            const { getOrCreateProjectByPath } = await import("./core/projects.js");
+            const { shouldDistill, markDistilled } = await import("./core/watermark.js");
+            const all = hasFlag(rest, "all");
+            const limit = Number(getFlag(rest, "limit") ?? (all ? 100000 : 50));
+            const convos = (await loadChatgptConversations()).slice(0, limit);
+            // ChatGPT has no cwd; all conversations live under one stable synthetic
+            // project so they never pollute a real repository's recall.
+            const project = getOrCreateProjectByPath(chatgptProjectPath);
+            let distilled = 0, skipped = 0, failed = 0;
+            for (const conv of convos) {
+                // Watermark per conversation, keyed by id + last write time.
+                const wmKey = `chatgpt:${conv.conversationId}`;
+                const mtimeMs = conv.updateTime ? new Date(conv.updateTime).getTime() : 0;
+                if (!shouldDistill(wmKey, mtimeMs)) {
+                    skipped++;
+                    continue;
+                }
+                try {
+                    const res = await distill({
+                        projectId: project.id,
+                        sessionId: conv.conversationId,
+                        messages: conv.messages.map((m) => ({ role: m.role, text: m.text })),
+                    });
+                    markDistilled(wmKey, mtimeMs);
+                    if (res.skipped)
+                        skipped++;
+                    else
+                        distilled++;
+                }
+                catch (e) {
+                    failed++;
+                    console.error(`distill failed ${conv.conversationId}: ${String(e)}`);
+                }
+            }
+            console.log(JSON.stringify({ scanned: convos.length, distilled, skipped, failed }, null, 2));
+            process.exit(0);
+        }
         case "remember": {
             const { getOrCreateProjectByPath } = await import("./core/projects.js");
             const { rememberText } = await import("./core/distill.js");
@@ -201,14 +242,154 @@ async function main() {
             console.log(JSON.stringify(out, null, 2));
             process.exit(0);
         }
+        case "lessons": {
+            const sub = rest[0];
+            const subRest = rest.slice(1);
+            const positionals = (args) => {
+                const out = [];
+                for (let i = 0; i < args.length; i++) {
+                    if (args[i].startsWith("--")) {
+                        i++;
+                        continue;
+                    }
+                    out.push(args[i]);
+                }
+                return out;
+            };
+            const projectId = async () => {
+                const { getOrCreateProjectByPath } = await import("./core/projects.js");
+                return getOrCreateProjectByPath(getFlag(subRest, "cwd") ?? process.cwd()).id;
+            };
+            switch (sub) {
+                case "list": {
+                    const { listLessons } = await import("./core/lessons.js");
+                    const status = getFlag(subRest, "status");
+                    const rows = listLessons({ status, projectId: getFlag(subRest, "cwd") ? await projectId() : undefined });
+                    for (const l of rows) {
+                        console.log(`${l.id}  [${l.status}/${l.scope}]  conf=${l.confidence.toFixed(2)}  ${l.title}`);
+                    }
+                    console.log(`(${rows.length} lessons)`);
+                    process.exit(0);
+                }
+                case "search": {
+                    const { searchLessons } = await import("./core/lesson-search.js");
+                    const query = positionals(subRest).join(" ").trim();
+                    if (!query)
+                        throw new Error("lessons search requires a query");
+                    const hits = await searchLessons(query, { projectId: await projectId() }, { limit: Number(getFlag(subRest, "limit") ?? 5) });
+                    for (const l of hits) {
+                        console.log(`${l.id}  score=${l.score.toFixed(3)}  [${l.scope}]  ${l.title}`);
+                    }
+                    process.exit(0);
+                }
+                case "inject": {
+                    const { injectLessons } = await import("./core/lesson-search.js");
+                    const query = positionals(subRest).join(" ").trim();
+                    if (!query)
+                        throw new Error("lessons inject requires a query");
+                    console.log(await injectLessons(query, { projectId: await projectId() }, { limit: Number(getFlag(subRest, "limit") ?? 5) }));
+                    process.exit(0);
+                }
+                case "approve":
+                case "reject":
+                case "archive": {
+                    const { setStatus } = await import("./core/lessons.js");
+                    const id = positionals(subRest)[0];
+                    if (!id)
+                        throw new Error(`lessons ${sub} requires a lesson_id`);
+                    const newStatus = sub === "approve" ? "approved" : sub === "reject" ? "rejected" : "archived";
+                    const ok = setStatus(id, newStatus, getFlag(subRest, "reason"));
+                    console.log(ok ? `${id} -> ${newStatus}` : "(該当なし)");
+                    process.exit(ok ? 0 : 1);
+                }
+                case "supersede": {
+                    const { supersede } = await import("./core/lessons.js");
+                    const [oldId, newId] = positionals(subRest);
+                    if (!oldId || !newId)
+                        throw new Error("lessons supersede requires <old_id> <new_id>");
+                    const ok = supersede(oldId, newId);
+                    console.log(ok ? `${oldId} superseded by ${newId}` : "(該当なし)");
+                    process.exit(ok ? 0 : 1);
+                }
+                case "decay": {
+                    const { decayConfidence, listStale } = await import("./core/lesson-quality.js");
+                    const dryRun = hasFlag(subRest, "dry");
+                    const res = decayConfidence({
+                        factor: getFlag(subRest, "factor") ? Number(getFlag(subRest, "factor")) : undefined,
+                        staleDays: getFlag(subRest, "days") ? Number(getFlag(subRest, "days")) : undefined,
+                        dryRun,
+                    });
+                    console.log(JSON.stringify({ ...res, dryRun, stale: listStale().length }, null, 2));
+                    process.exit(0);
+                }
+                case "export": {
+                    const { exportLessons } = await import("./core/lesson-share.js");
+                    const bundle = exportLessons({
+                        projectId: getFlag(subRest, "cwd") ? await projectId() : undefined,
+                        status: getFlag(subRest, "status"),
+                    });
+                    console.log(JSON.stringify(bundle, null, 2));
+                    process.exit(0);
+                }
+                case "import": {
+                    const { importLessons } = await import("./core/lesson-share.js");
+                    const { readFileSync } = await import("node:fs");
+                    const file = positionals(subRest)[0];
+                    if (!file)
+                        throw new Error("lessons import requires a bundle file path");
+                    const bundle = JSON.parse(readFileSync(file, "utf-8"));
+                    const res = await importLessons(bundle, {
+                        projectId: await projectId(),
+                        status: getFlag(subRest, "status"),
+                    });
+                    console.log(JSON.stringify(res, null, 2));
+                    process.exit(0);
+                }
+                case "extract": {
+                    const { getOrCreateProjectByPath } = await import("./core/projects.js");
+                    const { resolveSessionJsonl, loadTranscript } = await import("./core/transcript.js");
+                    const { stripPrivate } = await import("./core/private.js");
+                    const { extractDedicated, saveCandidates } = await import("./core/lesson-extract.js");
+                    const cwd = getFlag(subRest, "cwd") ?? process.cwd();
+                    const session = getFlag(subRest, "session") ?? "";
+                    const path = getFlag(subRest, "path") ?? (session ? resolveSessionJsonl(cwd, session) : undefined);
+                    if (!path)
+                        throw new Error("lessons extract requires --session or --path");
+                    const project = getOrCreateProjectByPath(cwd);
+                    const msgs = loadTranscript(path).map((m) => ({ ...m, text: stripPrivate(m.text) })).filter((m) => m.text.trim());
+                    const transcript = msgs.map((m) => `${m.role === "user" ? "User" : "Assistant"}: ${m.text.slice(0, 500)}`).join("\n");
+                    const candidates = await extractDedicated(transcript);
+                    const ids = await saveCandidates({ projectId: project.id, sessionId: session || path, candidates });
+                    console.log(JSON.stringify({ extracted: candidates.length, saved: ids.length }, null, 2));
+                    process.exit(0);
+                }
+                default:
+                    console.error("Usage: claw-memory lessons <subcommand>\n" +
+                        "  list [--status candidate|approved|...] [--cwd P]\n" +
+                        "  search \"query\" [--cwd P] [--limit N]\n" +
+                        "  inject \"query\" [--cwd P] [--limit N]\n" +
+                        "  extract --session ID [--cwd P] [--path FILE]\n" +
+                        "  approve <lesson_id>\n" +
+                        "  reject <lesson_id> [--reason R]\n" +
+                        "  archive <lesson_id> [--reason R]\n" +
+                        "  supersede <old_id> <new_id>\n" +
+                        "  decay [--days N] [--factor F] [--dry]\n" +
+                        "  export [--status S] [--cwd P]    print a portable JSON bundle\n" +
+                        "  import <file> [--status S] [--cwd P]   import a bundle (default status: candidate)");
+                    process.exit(sub ? 1 : 0);
+            }
+            return;
+        }
         default:
             console.error("Usage: claw-memory <command>\n" +
                 "  mcp                       start stdio MCP server\n" +
                 "  ui [--port N] [--open]    start memory viewer\n" +
                 "  distill --cwd P --session ID [--path FILE] [--if-stale]\n" +
                 "  distill-codex [--recent] [--limit N] [--all]   distill recent Codex sessions\n" +
+                "  distill-chatgpt [--limit N] [--all]            distill ChatGPT web export conversations\n" +
                 "  remember --cwd P \"text\"\n" +
-                "  search-logs \"query\" [--source claude-code,codex] [--project P] [--start ISO] [--end ISO] [--limit N] [--offset N]\n" +
+                "  lessons <list|search|inject|extract|approve|reject|archive|supersede>\n" +
+                "  search-logs \"query\" [--source claude-code,codex,chatgpt-web] [--project P] [--start ISO] [--end ISO] [--limit N] [--offset N]\n" +
                 "  hook <distill|recall>     run a Claude Code lifecycle hook (reads JSON on stdin)\n" +
                 "  inject-recall             alias for `hook recall`\n" +
                 "  install [--codex|--claude-code]     register MCP + hooks (default: codex)\n" +

package/dist/core/db.js

@@ -90,3 +90,98 @@ sqlite.exec(`
     tokenize = 'trigram'
   );
 `);
+// --- Lesson layer ----------------------------------------------------------
+// A "lesson" is reusable, abstracted knowledge distilled from sessions (bug-fix
+// patterns, project constraints, design decisions, user preferences). Unlike
+// conversation_chunks (raw history), lessons are explicit, structured, scoped,
+// and lifecycle-managed (candidate → approved/rejected/archived/superseded).
+// JSON-array columns (applies_when / avoid_when / concepts / files /
+// source_chunk_ids) are stored as TEXT to keep the schema flat and ORM-free,
+// mirroring conversation_chunks.concepts.
+sqlite.exec(`
+  CREATE TABLE IF NOT EXISTS lessons (
+    id TEXT PRIMARY KEY,
+    project_id TEXT,
+    repo_id TEXT,
+    session_id TEXT,
+    vec_rowid INTEGER,
+    title TEXT NOT NULL,
+    lesson TEXT NOT NULL,
+    applies_when TEXT,
+    avoid_when TEXT,
+    evidence TEXT,
+    scope TEXT NOT NULL DEFAULT 'repo',
+    obs_type TEXT,
+    concepts TEXT,
+    files TEXT,
+    confidence REAL NOT NULL DEFAULT 0.5,
+    source_chunk_ids TEXT,
+    status TEXT NOT NULL DEFAULT 'candidate',
+    superseded_by TEXT,
+    valid_until TEXT,
+    last_used_at TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+  );
+
+  -- Lifecycle audit trail: every status transition / decay / scope change.
+  CREATE TABLE IF NOT EXISTS lesson_events (
+    id TEXT PRIMARY KEY,
+    lesson_id TEXT NOT NULL,
+    event_type TEXT NOT NULL,
+    old_status TEXT,
+    new_status TEXT,
+    note TEXT,
+    created_at TEXT NOT NULL
+  );
+
+  -- Relations between lessons: duplicate / conflicts_with / supersedes /
+  -- related_to / derived_from (populated by dedup + conflict detection).
+  CREATE TABLE IF NOT EXISTS lesson_links (
+    id TEXT PRIMARY KEY,
+    lesson_id TEXT NOT NULL,
+    linked_lesson_id TEXT NOT NULL,
+    relation TEXT NOT NULL,
+    created_at TEXT NOT NULL
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_lessons_status ON lessons(status);
+  CREATE INDEX IF NOT EXISTS idx_lessons_project ON lessons(project_id);
+  CREATE INDEX IF NOT EXISTS idx_lesson_events_lesson ON lesson_events(lesson_id);
+  CREATE INDEX IF NOT EXISTS idx_lesson_links_lesson ON lesson_links(lesson_id);
+`);
+// Additive, migration-less column evolution for lessons (same approach as
+// conversation_chunks above): newly-introduced columns are ALTER-added in a
+// try/catch so older ~/.claw-memory/memory.db files keep working.
+for (const col of [
+    "repo_id TEXT",
+    "valid_until TEXT",
+    "last_used_at TEXT",
+    "superseded_by TEXT",
+]) {
+    try {
+        sqlite.exec(`ALTER TABLE lessons ADD COLUMN ${col}`);
+    }
+    catch {
+        // column already exists
+    }
+}
+// vec0 virtual table for lesson embeddings (same 384-dim e5 space as
+// vec_chunks). scope + project_id metadata columns let KNN filter inside the
+// MATCH query without post-filter loss.
+sqlite.exec(`
+  CREATE VIRTUAL TABLE IF NOT EXISTS lesson_vec USING vec0(
+    embedding float[384] distance_metric=cosine,
+    project_id text,
+    scope text
+  );
+`);
+// FTS5 keyword index over lesson title + body (trigram, same rationale as
+// chunks_fts). lesson_id links back to lessons.id.
+sqlite.exec(`
+  CREATE VIRTUAL TABLE IF NOT EXISTS lessons_fts USING fts5(
+    lesson_id UNINDEXED,
+    text,
+    tokenize = 'trigram'
+  );
+`);

package/dist/core/distill.js

@@ -10,6 +10,7 @@ import { saveChunks, deleteChunksBySession, chunkExists, } from "./vector-memory
 import { loadTranscript } from "./transcript.js";
 import { stripPrivate } from "./private.js";
 import { log } from "./logger.js";
+import { saveCandidates, extractDedicated, dedicatedEnabled, } from "./lesson-extract.js";
 const MIN_MESSAGES = 2;
 const MIN_TEXT_LENGTH = 100;
 const MAX_CHARS_PER_MESSAGE = 500;
@@ -26,9 +27,15 @@ const PROMPT = (transcript) => `以下の会話を分析して JSON で回答し
    key は必ず次のいずれか（該当しなければ出さない）:
    language | response_style | detail_level | code_style | framework | tone | tools
    変更がなければ空配列。
+7. lessons: 次回以降の作業で再利用できる「教訓」だけを抽出（無ければ空配列）。
+   一時的な会話・未検証の推測・秘密情報・一回限りのコマンド・重複は抽出しない。
+   各 lesson は実行可能・具体的・再利用可能であること。
+   各要素: {"title","lesson","applies_when":[],"avoid_when":[],
+   "scope":"global|project|repo|file|task|user_preference","confidence":0.0-1.0,
+   "evidence","concepts":[],"files":[]}
 
 JSON のみ回答:
-{"summary": "...", "obs_type": "...", "concepts": ["..."], "files_read": ["..."], "files_modified": ["..."], "preferences": [{"key": "...", "value": "..."}]}
+{"summary": "...", "obs_type": "...", "concepts": ["..."], "files_read": ["..."], "files_modified": ["..."], "preferences": [{"key": "...", "value": "..."}], "lessons": []}
 
 <conversation>
 ${transcript}
@@ -77,6 +84,7 @@ export async function distill(input) {
     const filesModified = (result.files_modified ?? []).map(String).filter(Boolean);
     // --- Vector memory: re-chunk this session (idempotent) ---
     let chunkCount = 0;
+    let savedChunkIds = [];
     try {
         deleteChunksBySession(input.sessionId);
         const pairs = [];
@@ -110,24 +118,50 @@ export async function distill(input) {
                 });
             }
             if (toSave.length > 0)
-                saveChunks(toSave);
+                savedChunkIds = saveChunks(toSave);
             chunkCount = toSave.length;
         }
     }
     catch (err) {
         console.error("[claw-memory] chunk embed failed:", err);
     }
+    // --- Lesson layer: extract reusable lessons (best-effort) ---
+    // Candidates ride along in the summary JSON above (no extra LLM call). When
+    // CLAW_MEMORY_LESSON_DEDICATED=1, run a separate higher-quality extraction
+    // pass instead. Failures here must never break the summary path.
+    let lessonCount = 0;
+    try {
+        const candidates = dedicatedEnabled()
+            ? await extractDedicated(transcript)
+            : Array.isArray(result.lessons)
+                ? result.lessons
+                : [];
+        if (candidates.length > 0) {
+            const ids = await saveCandidates({
+                projectId: input.projectId,
+                sessionId: input.sessionId,
+                candidates,
+                sourceChunkIds: savedChunkIds,
+            });
+            lessonCount = ids.length;
+        }
+    }
+    catch (err) {
+        console.error("[claw-memory] lesson extract failed:", err);
+    }
     log("distill", {
         projectId: input.projectId,
         sessionId: input.sessionId,
         obsType,
         chunks: chunkCount,
         preferences: result.preferences?.length ?? 0,
+        lessons: lessonCount,
     });
     return {
         summary: result.summary,
         preferencesCount: result.preferences?.length ?? 0,
         chunks: chunkCount,
+        lessons: lessonCount,
     };
 }
 /** Store a single free-text note as an embedded chunk (memory_remember). */