wendkeep 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to **wendkeep** are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.16.0] — 2026-07-06
+
+Retroactive memory.
+
+### Added
+- **`wendkeep import`** — backfill the vault with this project's *past* Claude Code sessions.
+  It scans `.claude/projects/<slug>/*.jsonl`, and for every session not already in the vault
+  (deduped by `session_id` against the `SESSION_REGISTRY`) reconstructs a full, dated session
+  note — frontmatter, one iteration block per turn, cost + subagent telemetry, derived
+  decision/bug/learning notes, and a finalized closing — placed in its **real** date folder
+  (`02-Sessões/<year>/<MM-MMM>/DIA <dd>/`), not today's. One command turns your whole history
+  into memory that `wendkeep cost` immediately aggregates.
+  - Offline replay of the live capture flow (same `buildSessionContent` / `insertIteration` /
+    `finalizeSessionFile` / usage + subagent code) so an imported note is indistinguishable
+    from a captured one.
+  - Options: `--from <dir>` (point at the `.claude/projects` folder explicitly), `--project`,
+    `--since <date>`, `--limit <n>`, `--dry-run` (report without writing), `--json`.
+  - Idempotent: re-running skips everything already imported. Never overwrites an existing note.
+  - v1 covers Claude Code transcripts; Codex is a follow-up.
+
+### Changed
+- `session-start.mjs` now guards its `main()` behind the standard `import.meta.url` check (like
+  `session-stop.mjs`) so its note-building helpers can be imported by `import`/tests without
+  running the hook. No behavioral change when invoked as a hook.
+
+## [0.15.0] — 2026-07-06
+
+### Added
+- **`wendkeep cost --top [N]`** — the N priciest sessions (cost incl. subagents · date · file),
+  most expensive first (default 10). Spot where the money went. `cost --json` now also carries
+  the per-session `sessions` list.
+
 ## [0.14.0] — 2026-07-06
 
 ### Changed
@@ -283,6 +315,7 @@ Initial release — the capture engine, extracted from a system in daily product
 - `wendkeep init` (cross-platform installer) + optional `@bitbonsai/mcpvault` MCP server.
 
 <!-- Only v0.4.0+ is tagged in git (history starts here); older versions link to npm. -->
+[0.15.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.15.0
 [0.14.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.14.0
 [0.13.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.13.0
 [0.12.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.12.0

package/README.md

@@ -95,12 +95,27 @@ No re‑copying, no snapshot to re‑sync — the package is the single source o
 | `wendkeep spec <sub>` | Living specs: `list` / `show <capability>`. |
 | `wendkeep sensors <sub>` | `list` / `add <id> "<command>"` — view/edit `wendkeep.sensors.json` (JSON Schema shipped). |
 | `wendkeep cost [--since d]` | Aggregate AI-coding spend across the vault's sessions — total, by model, by day (`--json`). |
+| `wendkeep import [opts]` | **Retroactive memory** — backfill past Claude sessions into the vault (deduped by `session_id`). `--from <dir>` / `--since d` / `--limit n` / `--dry-run` / `--json`. |
 | `wendkeep lesson add "t" "l"` | Record a project-local lesson (injected at the next SessionStart). |
 | `wendkeep sync-defs` | Copy `.brain/agents\|skills` into the project (`.codex/agents`, `.claude/skills`). |
 | `wendkeep validate-memory [path]` | Validate `.brain/CORE.md` (cap 25, 3 sections, no secrets/PII). |
 | `wendkeep doctor [--vault P]` | Run a vault health check (integrity of sessions, registry, links). |
 | `wendkeep --version` / `--help` | Version / usage. |
 
+## Retroactive memory (`import`)
+
+Install wendkeep into an existing project and it only remembers sessions **from now on**. `wendkeep import` fixes that: it reads the project's past Claude Code transcripts (`~/.claude/projects/<slug>/*.jsonl`) and rebuilds each one as a full session note in its **real** date folder — frontmatter, one iteration block per turn, cost + subagent telemetry, derived decision/bug/learning notes, finalized closing. It is an offline replay of the live capture flow, so an imported note is indistinguishable from a captured one.
+
+```bash
+wendkeep import --vault .myproject-vault --dry-run   # preview what would be imported
+wendkeep import --vault .myproject-vault             # write the notes
+```
+
+- **Deduped** by `session_id` against the vault's `SESSION_REGISTRY` — only sessions not already present are imported, and it never overwrites an existing note. Re-running is a no-op.
+- **`--from <dir>`** points at the `.claude/projects/<slug>/` folder explicitly (use it if the auto-derived path misses). Also: `--since <date>`, `--limit <n>`, `--json`.
+- Once imported, `wendkeep cost` aggregates your entire history — retroactively.
+- v1 covers Claude Code; Codex import is a follow-up.
+
 ## Change lifecycle — the a2 loop (spec‑driven, native)
 
 Beyond capturing sessions, wendkeep is a **harness**: a native, zero‑dependency loop that keeps *intent* (specs), *work* (changes) and *proof* (sensors) together in the vault, wikilinked into the Obsidian graph.

package/bin/wendkeep.mjs

@@ -47,7 +47,9 @@ Usage:
                            done <id> | undone <id> | diff | archive [--force].
   wendkeep spec <sub>          Living specs: list | show <capability>.
   wendkeep sensors <sub>       list | add <id> "<command>" [--severity --type --report].
-  wendkeep cost [--since d]    Aggregate AI-coding spend across the vault's sessions (--json).
+  wendkeep cost [opts]         Aggregate AI-coding spend across the vault's sessions.
+  wendkeep import [opts]       Backfill: import this project's past Claude sessions into the vault.
+                           --since <date> · --top [N] (priciest sessions) · --json.
   wendkeep verify [--change s] Run a change's task sensors + record evidence (the gate).
   wendkeep lesson add "t" "l"   Record a project-local lesson (injected at SessionStart).
   wendkeep validate-memory [path]  Validate .brain/CORE.md against the compaction
@@ -136,6 +138,11 @@ async function main() {
       runCost(rest);
       break;
     }
+    case 'import': {
+      const { runImportCli } = await import('../src/import.mjs');
+      runImportCli(rest);
+      break;
+    }
     case '--version':
     case '-v':
       process.stdout.write(`${version()}\n`);

package/hooks/import-sessions.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// Retroactive memory: import Claude Code transcripts that predate wendkeep into the vault.
+// Each `.claude/projects/<slug>/<session_id>.jsonl` becomes a full session note in its real
+// dated folder, deduped by session_id against the vault's SESSION_REGISTRY. This is an offline
+// replay of the live capture flow — same skeleton, same iteration blocks, same cost/subagent
+// telemetry, same finalize — so an imported note is indistinguishable from a captured one.
+import { existsSync, readdirSync, writeFileSync } from 'fs';
+import { basename, join } from 'path';
+import {
+  parseTranscript,
+  buildIterationBlock,
+  insertIteration,
+  finalizeSessionFile,
+  mergeCreatedNotes,
+  findLinkedDerivedNotes,
+} from './session-stop.mjs';
+import { buildSessionContent, allocateSessionPath } from './session-start.mjs';
+import { createLinkedNotes } from './linked-notes.mjs';
+import { updateSessionUsage } from './token-usage.mjs';
+import { upsertSubagentUsage } from './subagent-usage.mjs';
+import { readSessionRegistry, upsertSessionRegistry, formatLocalIso, formatDate } from './obsidian-common.mjs';
+
+// Claude encodes a project's absolute path as its `.claude/projects` dir name by replacing each
+// path separator and the drive colon with '-'. `C:\GitHub\WendKeep` -> `C--GitHub-WendKeep`.
+// Note: each char maps 1:1 (no collapsing), so `C:\` yields `C--`.
+export function claudeProjectSlug(projectPath) {
+  return String(projectPath || '').replace(/[\\/:]/g, '-');
+}
+
+function homeDir() {
+  return process.env.USERPROFILE || process.env.HOME || '';
+}
+
+export function defaultClaudeProjectsDir(projectPath) {
+  const home = homeDir();
+  if (!home) return '';
+  return join(home, '.claude', 'projects', claudeProjectSlug(projectPath));
+}
+
+// List candidate transcripts. The Claude session_id IS the filename, so we get it without
+// parsing — cheap dedup for the (usually large) set of already-captured sessions.
+export function discoverTranscripts(projectPath, fromDir) {
+  const dir = fromDir || defaultClaudeProjectsDir(projectPath);
+  if (!dir || !existsSync(dir)) return { dir, transcripts: [] };
+  const transcripts = readdirSync(dir)
+    .filter((name) => /\.jsonl$/i.test(name))
+    .map((name) => ({ path: join(dir, name), sessionId: basename(name, '.jsonl') }));
+  return { dir, transcripts };
+}
+
+// Session objective for the note title/frontmatter: first real user prompt, one line.
+function deriveSummary(tx) {
+  for (const turn of tx.turns || []) {
+    const prompt = (turn.userPrompts || []).find(Boolean);
+    if (prompt) {
+      return prompt.replace(/[\r\n#]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 80) || 'session';
+    }
+  }
+  return 'session';
+}
+
+function toDate(ts, fallback) {
+  const d = ts ? new Date(ts) : null;
+  return d && Number.isFinite(d.getTime()) ? d : fallback;
+}
+
+// Replay one transcript into a fresh, finalized note. Returns {sessionId, relPath, turns} or
+// null when the transcript has no memorializable turns. Assumes the caller already deduped.
+export function importSession(vaultBase, txPath, preParsed) {
+  const tx = preParsed || parseTranscript(txPath);
+  const turns = tx.turns || [];
+  if (!turns.length) return null;
+
+  const sessionId = tx.sessionId || basename(String(txPath), '.jsonl');
+  const startDate = toDate(turns[0].timestamp, new Date());
+  const endDate = toDate(turns.at(-1).timestamp, startDate);
+  const summary = deriveSummary(tx);
+
+  // Skeleton in the real dated folder.
+  const { absPath, relPath } = allocateSessionPath(vaultBase, startDate, summary);
+  writeFileSync(absPath, buildSessionContent({ relPath, now: startDate, summary }), 'utf-8');
+
+  // One iteration block per turn (insertIteration dedups by turn marker -> re-import safe).
+  for (const turn of turns) {
+    const block = buildIterationBlock(tx, { turn_id: turn.turnId, now: turn.timestamp });
+    insertIteration(absPath, block, turn.turnId, tx);
+  }
+
+  // Cost + subagent telemetry, exactly like the live Stop hook. Fail-open.
+  try {
+    updateSessionUsage({ vaultBase, sessionRel: relPath, sessionPath: absPath, transcriptPath: txPath });
+  } catch { /* usage is best-effort */ }
+  try {
+    upsertSubagentUsage(absPath, txPath);
+  } catch { /* subagent telemetry is best-effort */ }
+
+  // Finalize: derived notes + closing section + ended_at from the last turn.
+  const endedAt = formatLocalIso(endDate);
+  const created = mergeCreatedNotes(
+    createLinkedNotes(vaultBase, formatDate(endDate), relPath, tx),
+    findLinkedDerivedNotes(vaultBase, relPath),
+  );
+  finalizeSessionFile(absPath, tx, created, endedAt);
+
+  upsertSessionRegistry(vaultBase, sessionId, {
+    session_file: relPath,
+    status: 'done',
+    started_at: formatLocalIso(startDate),
+    ended_at: endedAt,
+    last_turn_id: turns.at(-1).turnId,
+    transcript_path: txPath,
+    imported: true,
+  });
+
+  return { sessionId, relPath, turns: turns.length };
+}
+
+// Import every not-yet-captured transcript. Deduped by session_id against the registry.
+// Options: { projectPath, from, since (ISO/date), limit, dryRun }.
+export function runImport(vaultBase, opts = {}) {
+  const { projectPath = process.cwd(), from = '', since = '', limit = 0, dryRun = false } = opts;
+  const { dir, transcripts } = discoverTranscripts(projectPath, from);
+  const captured = new Set(Object.keys(readSessionRegistry(vaultBase).sessions || {}));
+  const sinceMs = since ? Date.parse(since) : 0;
+  const report = { dir, scanned: transcripts.length, imported: 0, skipped: 0, errors: [], sessions: [] };
+
+  let done = 0;
+  for (const t of transcripts) {
+    if (captured.has(t.sessionId)) { report.skipped++; continue; }
+    if (limit && done >= limit) break;
+
+    let tx;
+    try {
+      tx = parseTranscript(t.path);
+    } catch (error) {
+      report.errors.push({ sessionId: t.sessionId, error: error.message });
+      continue;
+    }
+    const turns = tx.turns || [];
+    if (!turns.length) { report.skipped++; continue; }
+
+    const startTs = turns[0].timestamp || '';
+    if (sinceMs && startTs && Number.isFinite(Date.parse(startTs)) && Date.parse(startTs) < sinceMs) {
+      report.skipped++;
+      continue;
+    }
+
+    if (dryRun) {
+      report.sessions.push({ sessionId: t.sessionId, turns: turns.length, startTs, dryRun: true });
+      report.imported++;
+      done++;
+      continue;
+    }
+
+    try {
+      const r = importSession(vaultBase, t.path, tx);
+      if (r) { report.sessions.push(r); report.imported++; done++; }
+      else { report.skipped++; }
+    } catch (error) {
+      report.errors.push({ sessionId: t.sessionId, error: error.message });
+    }
+  }
+
+  return report;
+}

package/hooks/session-start.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { existsSync, writeFileSync } from 'fs';
 import { basename, join } from 'path';
+import { pathToFileURL } from 'url';
 import {
   controlPath,
   ensureDir,
@@ -30,7 +31,7 @@ import {
   yamlQuote,
 } from './obsidian-common.mjs';
 
-function buildSessionContent({ relPath, now, summary = 'session' }) {
+export function buildSessionContent({ relPath, now, summary = 'session' }) {
   const date = formatDate(now);
   const startedAt = formatLocalIso(now);
   const titleTime = formatTime(now).slice(0, 5);
@@ -112,7 +113,7 @@ Sessão ainda em andamento.
 `;
 }
 
-function allocateSessionPath(vaultBase, now, summary = 'session') {
+export function allocateSessionPath(vaultBase, now, summary = 'session') {
   const folderRel = sessionFolderRel(now, vaultBase);
   const folderAbs = join(vaultBase, folderRel);
   ensureDir(folderAbs);
@@ -301,11 +302,13 @@ function main() {
   });
 }
 
-try {
-  main();
-} catch (error) {
-  process.stderr.write(`[codex-obsidian] SessionStart falhou: ${error.message}\n`);
-  writeHookOutput({
-    systemMessage: `[codex-obsidian] Não foi possível criar a sessão Obsidian: ${error.message}`,
-  });
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    main();
+  } catch (error) {
+    process.stderr.write(`[codex-obsidian] SessionStart falhou: ${error.message}\n`);
+    writeHookOutput({
+      systemMessage: `[codex-obsidian] Não foi possível criar a sessão Obsidian: ${error.message}`,
+    });
+  }
 }

package/hooks/session-stop.mjs

@@ -781,7 +781,7 @@ function noteReferencesSession(content, sessionRel) {
   return content.includes(sessionRel) || content.includes(sessionLink);
 }
 
-function findLinkedDerivedNotes(vaultBase, sessionRel) {
+export function findLinkedDerivedNotes(vaultBase, sessionRel) {
   const linked = { decisions: [], bugs: [], learnings: [] };
   const locF = getLocale(vaultBase).folders;
   const folders = {
@@ -808,7 +808,7 @@ function findLinkedDerivedNotes(vaultBase, sessionRel) {
   return linked;
 }
 
-function mergeCreatedNotes(created, linked) {
+export function mergeCreatedNotes(created, linked) {
   const merged = { decisions: [], bugs: [], learnings: [] };
   for (const key of Object.keys(merged)) {
     merged[key] = [...new Set([...(created[key] || []), ...(linked[key] || [])])];
@@ -861,7 +861,7 @@ function replaceClosingSection(content, closing) {
   return `${content.slice(0, index).trimEnd()}\n\n${closing}\n`;
 }
 
-function finalizeSessionFile(sessionPath, tx, created, endedAt) {
+export function finalizeSessionFile(sessionPath, tx, created, endedAt) {
   const pending = extractPending(tx.rawTextForDetection);
   const links = (items) => items.length ? items.map((rel) => `  - ${wikilinkFromRel(rel)}`).join('\n') : '  - Nenhuma';
   const summary = tx.latestAssistantMessage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "A persistent-memory harness for AI coding agents on your Obsidian vault: turn-by-turn session capture plus a native, zero-dependency spec→change→verify→archive loop (sensor-gated, independent verdict, mutation discrimination). Local-first, agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "bin": {

package/src/cost.mjs

@@ -76,9 +76,15 @@ export function collectVaultCost(vaultBase, { since } = {}) {
     try { e = parseSessionCost(readFileSync(f, 'utf8')); } catch { continue; }
     if (!e) continue;
     if (since && e.date && e.date < since) continue;
+    e.file = f.slice(vaultBase.length + 1).replace(/\\/g, '/');
     entries.push(e);
   }
-  return aggregateCosts(entries);
+  const agg = aggregateCosts(entries);
+  // Per-session list (main+sub), most expensive first — powers `cost --top`.
+  agg.sessions = entries
+    .map((e) => ({ file: e.file, date: e.date, cost: round4(e.mainCost + e.subCost) }))
+    .sort((a, b) => b.cost - a.cost);
+  return agg;
 }
 
 function opt(argv, name) {
@@ -97,6 +103,14 @@ export function runCost(argv) {
 
   if (argv.includes('--json')) { process.stdout.write(`${JSON.stringify(agg, null, 2)}\n`); process.exit(0); }
 
+  const topIdx = argv.indexOf('--top');
+  if (topIdx >= 0) {
+    const n = Number(argv[topIdx + 1]) || 10;
+    process.stdout.write(`Sessões mais caras (top ${n} de ${agg.count}):\n`);
+    for (const s of agg.sessions.slice(0, n)) process.stdout.write(`  ${usd(s.cost).padStart(11)}  ${s.date || '?'}  ${s.file}\n`);
+    process.exit(0);
+  }
+
   process.stdout.write(`Custo total (vault): ${usd(agg.total)} — ${agg.count} sessão(ões) · ${usd(agg.avg)}/sessão\n`);
   process.stdout.write(`  main: ${usd(agg.main)} · subagents: ${usd(agg.sub)}\n`);
   if (agg.wasted) process.stdout.write(`  desperdiçado (runs killed/failed): ${usd(agg.wasted)}\n`);

package/src/import.mjs

@@ -0,0 +1,53 @@
+// `wendkeep import` — retroactive memory. Scans this project's Claude Code transcripts and
+// turns every session that isn't already in the vault into a full, dated session note (deduped
+// by session_id). One command backfills your whole history: cost, subagents, iterations.
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { runImport, defaultClaudeProjectsDir } from '../hooks/import-sessions.mjs';
+
+function opt(argv, name) {
+  const i = argv.indexOf(name);
+  if (i >= 0) return argv[i + 1];
+  const eq = argv.find((a) => a.startsWith(`${name}=`));
+  return eq ? eq.slice(name.length + 1) : undefined;
+}
+
+export function runImportCli(argv) {
+  const vaultRaw = opt(argv, '--vault') || process.env.OBSIDIAN_VAULT_PATH;
+  if (!vaultRaw) { process.stderr.write('wendkeep import: no vault (--vault or OBSIDIAN_VAULT_PATH).\n'); process.exit(2); }
+  const vaultBase = isAbsolute(vaultRaw) ? vaultRaw : resolve(process.cwd(), vaultRaw);
+  if (!existsSync(vaultBase)) { process.stderr.write(`wendkeep import: vault not found: ${vaultBase}\n`); process.exit(2); }
+
+  const projectRaw = opt(argv, '--project') || process.cwd();
+  const projectPath = isAbsolute(projectRaw) ? projectRaw : resolve(process.cwd(), projectRaw);
+  const from = opt(argv, '--from') || '';
+  const since = opt(argv, '--since') || '';
+  const limit = Number(opt(argv, '--limit')) || 0;
+  const dryRun = argv.includes('--dry-run');
+
+  const sourceDir = from || defaultClaudeProjectsDir(projectPath);
+  if (!from && (!sourceDir || !existsSync(sourceDir))) {
+    process.stderr.write(`wendkeep import: no Claude transcripts for this project.\n`);
+    process.stderr.write(`  Looked in: ${sourceDir || '(home not resolved)'}\n`);
+    process.stderr.write(`  Pass --from <dir> pointing at .claude/projects/<slug>/ explicitly.\n`);
+    process.exit(2);
+  }
+
+  const report = runImport(vaultBase, { projectPath, from, since, limit, dryRun });
+
+  if (argv.includes('--json')) { process.stdout.write(`${JSON.stringify(report, null, 2)}\n`); process.exit(0); }
+
+  const verb = dryRun ? 'importaria' : 'importadas';
+  process.stdout.write(`Fonte: ${report.dir}\n`);
+  process.stdout.write(`${report.scanned} transcript(s) · ${report.imported} ${verb} · ${report.skipped} já no vault\n`);
+  for (const s of report.sessions) {
+    const tag = s.dryRun ? '(dry-run)' : '→';
+    process.stdout.write(`  ${tag} ${s.sessionId}  ${s.turns} turno(s)${s.relPath ? `  ${s.relPath}` : ''}\n`);
+  }
+  if (report.errors.length) {
+    process.stdout.write(`\n${report.errors.length} com erro (pulados):\n`);
+    for (const e of report.errors) process.stdout.write(`  ${e.sessionId}: ${e.error}\n`);
+  }
+  if (dryRun) process.stdout.write('\nNada foi escrito (--dry-run). Rode sem --dry-run para criar as notas.\n');
+  process.exit(0);
+}

package/src/taxonomy.mjs

@@ -43,6 +43,7 @@ export const HOOK_FILES = [
   'brain-recall.mjs',
   'brain-reindex.mjs',
   'session-backfill.mjs',
+  'import-sessions.mjs',
   'vault-health.mjs',
   'understand-inject.mjs',
 ];