wendkeep 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -4,6 +4,25 @@ 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.18.0] — 2026-07-06
+
+Session identity in the note.
+
+### Added
+- Session notes now carry **`session_id`** in their frontmatter — both live capture and import,
+  Claude and Codex. Pairs with the existing `provider:` field so every note self-identifies
+  (which conversation, which agent) without consulting the registry.
+- **`wendkeep import --stamp-ids`** — backfill `session_id` into existing notes from the
+  `SESSION_REGISTRY` (for notes captured or imported before the field existed). Idempotent;
+  only touches notes missing the field.
+- Import dedup now also scans existing notes' `session_id` (`capturedSessionIds` = registry ∪
+  note frontmatter), so a session that already has a note on disk is never re-imported even if
+  the registry was reset or lost.
+
+### Changed
+- `buildSessionContent` accepts a `sessionId`; the SessionStart hook (all three create/recreate
+  paths) and `importSession` thread the id through, so a note records its identity at creation.
+
 ## [0.17.0] — 2026-07-06
 
 Retroactive memory, now agent-agnostic (Codex).

package/README.md

@@ -113,7 +113,8 @@ wendkeep import --vault .myproject-vault --source codex   # just Codex
 ```
 
 - **Both agents by default** (`--source all`). Claude sessions come from `~/.claude/projects/<slug>/`; Codex rollouts from `~/.codex/sessions/**`, scoped to this project by the `cwd` recorded in each session (case- and separator-insensitive, subdirs included). Narrow with `--source claude` / `--source codex`.
-- **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.
+- Every note records its **`session_id`** and **`provider`** in frontmatter (live capture and import alike). Backfill older notes with `wendkeep import --stamp-ids` (fills the id from the registry; idempotent).
+- **Deduped** by `session_id` against the vault's `SESSION_REGISTRY` **and** existing notes' frontmatter — only sessions not already present are imported, and it never overwrites an existing note. Re-running is a no-op.
 - **`--from <dir>`** / **`--codex-from <dir>`** point at the transcript folders explicitly (use if the auto-derived path misses). Also: `--since <date>`, `--limit <n>`, `--json`.
 - Once imported, `wendkeep cost` aggregates your entire history — retroactively, across both agents.
 

package/hooks/import-sessions.mjs

@@ -4,7 +4,7 @@
 // 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, openSync, readSync, closeSync } from 'fs';
+import { existsSync, readdirSync, writeFileSync, readFileSync, openSync, readSync, closeSync } from 'fs';
 import { basename, join } from 'path';
 import {
   parseTranscript,
@@ -19,6 +19,7 @@ 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';
+import { getLocale } from './locale.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`.
@@ -69,45 +70,71 @@ function cwdMatchesProject(cwd, projectPath) {
   return c === proj || c.startsWith(`${proj}/`);
 }
 
-// Recursively collect *.jsonl paths (manual walk: readdir recursive lands in Node 20; floor is 18).
-function walkJsonl(dir, out = []) {
+// Recursively collect paths matching `re` (manual walk: readdir recursive lands in Node 20; floor is 18).
+function walkFiles(dir, re, out = []) {
   let entries;
   try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
   for (const e of entries) {
     const p = join(dir, e.name);
-    if (e.isDirectory()) walkJsonl(p, out);
-    else if (/\.jsonl$/i.test(e.name)) out.push(p);
+    if (e.isDirectory()) walkFiles(p, re, out);
+    else if (re.test(e.name)) out.push(p);
   }
   return out;
 }
 
-// Read only the leading bytes to pull the session_meta payload (id + cwd); session_meta is the
-// first line of a rollout, so a bounded prefix read avoids parsing multi-MB transcripts twice.
-function readSessionMeta(path) {
+// Read only the leading bytes of a file (avoids slurping multi-MB transcripts / notes).
+function readPrefix(path, bytes = 4096) {
   let fd;
   try {
     fd = openSync(path, 'r');
-    const buf = Buffer.alloc(16384);
-    const n = readSync(fd, buf, 0, buf.length, 0);
-    for (const line of buf.slice(0, n).toString('utf-8').split('\n')) {
-      if (!line.trim()) continue;
-      let e;
-      try { e = JSON.parse(line); } catch { return null; } // partial/oversized first line -> skip
-      return e.type === 'session_meta' ? (e.payload || {}) : null; // meta is always line 1
-    }
+    const buf = Buffer.alloc(bytes);
+    const n = readSync(fd, buf, 0, bytes, 0);
+    return buf.slice(0, n).toString('utf-8');
   } catch {
-    return null;
+    return '';
   } finally {
     if (fd !== undefined) { try { closeSync(fd); } catch { /* already closed */ } }
   }
+}
+
+// Pull the session_meta payload (id + cwd). session_meta is line 1 of a rollout.
+function readSessionMeta(path) {
+  for (const line of readPrefix(path, 16384).split('\n')) {
+    if (!line.trim()) continue;
+    let e;
+    try { e = JSON.parse(line); } catch { return null; } // partial/oversized first line -> skip
+    return e.type === 'session_meta' ? (e.payload || {}) : null;
+  }
   return null;
 }
 
+// The `session_id` recorded in a note's frontmatter (empty when absent).
+function noteSessionId(path) {
+  const m = readPrefix(path, 2048).match(/^session_id:\s*["']?([^"'\r\n]+)["']?\s*$/m);
+  return m ? m[1].trim() : '';
+}
+
+// Every session_id the vault already has a record of: the SESSION_REGISTRY plus every session
+// note's frontmatter id. The registry is authoritative for wendkeep-native vaults, but scanning
+// notes too keeps import safe even if the registry was reset/lost — a session with a note on
+// disk is never re-imported.
+export function capturedSessionIds(vaultBase) {
+  const ids = new Set(Object.keys(readSessionRegistry(vaultBase).sessions || {}));
+  try {
+    const sessionsDir = join(vaultBase, getLocale(vaultBase).folders.sessions);
+    for (const path of walkFiles(sessionsDir, /\.md$/i)) {
+      const id = noteSessionId(path);
+      if (id) ids.add(id);
+    }
+  } catch { /* registry alone is enough */ }
+  return ids;
+}
+
 export function discoverCodexTranscripts(projectPath, fromDir) {
   const dir = fromDir || defaultCodexSessionsDir();
   if (!dir || !existsSync(dir)) return { dir, transcripts: [] };
   const transcripts = [];
-  for (const path of walkJsonl(dir)) {
+  for (const path of walkFiles(dir, /\.jsonl$/i)) {
     const meta = readSessionMeta(path);
     if (!meta || !meta.id) continue;
     if (projectPath && !cwdMatchesProject(meta.cwd, projectPath)) continue;
@@ -147,9 +174,9 @@ export function importSession(vaultBase, txPath, opts = {}) {
   const endDate = toDate(turns.at(-1).timestamp, startDate);
   const summary = deriveSummary(tx);
 
-  // Skeleton in the real dated folder, tagged with the transcript's own provider.
+  // Skeleton in the real dated folder, tagged with the transcript's own provider + session id.
   const { absPath, relPath } = allocateSessionPath(vaultBase, startDate, summary);
-  writeFileSync(absPath, buildSessionContent({ relPath, now: startDate, summary, provider: tx.provider }), 'utf-8');
+  writeFileSync(absPath, buildSessionContent({ relPath, now: startDate, summary, provider: tx.provider, sessionId }), 'utf-8');
 
   // One iteration block per turn (insertIteration dedups by turn marker -> re-import safe).
   for (const turn of turns) {
@@ -186,6 +213,34 @@ export function importSession(vaultBase, txPath, opts = {}) {
   return { sessionId, relPath, turns: turns.length };
 }
 
+// Stamp a missing/empty `session_id` into a note's frontmatter (only within the frontmatter
+// block, right after `provider:`). Leaves a note that already has a non-empty id untouched.
+function injectSessionIdFrontmatter(content, sessionId) {
+  const q = `"${String(sessionId).replace(/"/g, '\\"')}"`;
+  if (/^session_id:\s*$/m.test(content)) return content.replace(/^session_id:\s*$/m, `session_id: ${q}`);
+  if (/^session_id:\s*\S/m.test(content)) return content; // already has a value
+  if (/^provider:.*$/m.test(content)) return content.replace(/^(provider:.*)$/m, `$1\nsession_id: ${q}`);
+  return content.replace(/^---\s*$/m, `---\nsession_id: ${q}`);
+}
+
+// Backfill `session_id` into existing session notes from the SESSION_REGISTRY (session_file -> id).
+// For notes captured/imported before the field existed. Idempotent; only touches notes missing it.
+export function stampSessionIds(vaultBase) {
+  const reg = readSessionRegistry(vaultBase).sessions || {};
+  const report = { total: Object.keys(reg).length, stamped: 0, alreadyOk: 0, missingFile: 0 };
+  for (const [sessionId, entry] of Object.entries(reg)) {
+    if (!entry?.session_file) continue;
+    const abs = join(vaultBase, entry.session_file);
+    if (!existsSync(abs)) { report.missingFile++; continue; }
+    let content;
+    try { content = readFileSync(abs, 'utf-8'); } catch { report.missingFile++; continue; }
+    const next = injectSessionIdFrontmatter(content, sessionId);
+    if (next !== content) { writeFileSync(abs, next, 'utf-8'); report.stamped++; }
+    else { report.alreadyOk++; }
+  }
+  return report;
+}
+
 // Import every not-yet-captured transcript from the requested source(s). Deduped by session_id
 // against the registry. Options: { projectPath, source ('all'|'claude'|'codex'), from, codexFrom,
 // since (ISO/date), limit, dryRun }. importSession is provider-agnostic, so both sources share
@@ -206,7 +261,7 @@ export function runImport(vaultBase, opts = {}) {
     codexDir = d.dir;
     transcripts.push(...d.transcripts);
   }
-  const captured = new Set(Object.keys(readSessionRegistry(vaultBase).sessions || {}));
+  const captured = capturedSessionIds(vaultBase);
   const sinceMs = since ? Date.parse(since) : 0;
   const report = { source: src, claudeDir, codexDir, scanned: transcripts.length, imported: 0, skipped: 0, errors: [], sessions: [] };
 

package/hooks/session-start.mjs

@@ -31,7 +31,7 @@ import {
   yamlQuote,
 } from './obsidian-common.mjs';
 
-export function buildSessionContent({ relPath, now, summary = 'session', provider: providerId }) {
+export function buildSessionContent({ relPath, now, summary = 'session', provider: providerId, sessionId = '' }) {
   const date = formatDate(now);
   const startedAt = formatLocalIso(now);
   const titleTime = formatTime(now).slice(0, 5);
@@ -46,6 +46,7 @@ date: ${date}
 started_at: ${startedAt}
 ended_at:
 provider: ${provider.id}
+session_id: ${sessionId ? yamlQuote(sessionId) : ''}
 status: active
 summary: ${yamlQuote(summary)}
 cssclasses:
@@ -202,7 +203,7 @@ function main() {
       const knownAbs = join(vaultBase, known.session_file);
       if (!existsSync(knownAbs)) {
         ensureDir(join(vaultBase, known.session_file.split('/').slice(0, -1).join('/')));
-        writeFileSync(knownAbs, buildSessionContent({ relPath: known.session_file, now, summary: sessionSummaryFromInput(input) }), 'utf-8');
+        writeFileSync(knownAbs, buildSessionContent({ relPath: known.session_file, now, summary: sessionSummaryFromInput(input), sessionId }), 'utf-8');
       }
       const startedAt = known.started_at || control.started_at || formatLocalIso(now);
       writeControl(vaultBase, {
@@ -244,7 +245,7 @@ function main() {
       const matchAbs = join(vaultBase, match.session_file);
       if (!existsSync(matchAbs)) {
         ensureDir(join(vaultBase, match.session_file.split('/').slice(0, -1).join('/')));
-        writeFileSync(matchAbs, buildSessionContent({ relPath: match.session_file, now, summary: sessionSummaryFromInput(input) }), 'utf-8');
+        writeFileSync(matchAbs, buildSessionContent({ relPath: match.session_file, now, summary: sessionSummaryFromInput(input), sessionId: sessionId || match.sessionId }), 'utf-8');
       }
       const startedAt = match.started_at || control.started_at || formatLocalIso(now);
       writeControl(vaultBase, {
@@ -276,7 +277,7 @@ function main() {
   const summary = sessionSummaryFromInput(input);
   const { absPath, relPath } = allocateSessionPath(vaultBase, now, summary);
   const startedAt = formatLocalIso(now);
-  writeFileSync(absPath, buildSessionContent({ relPath, now, summary }), 'utf-8');
+  writeFileSync(absPath, buildSessionContent({ relPath, now, summary, sessionId }), 'utf-8');
   writeControl(vaultBase, {
     status: 'active',
     session_file: relPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.17.0",
+  "version": "0.18.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/import.mjs

@@ -3,7 +3,7 @@
 // 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 } from '../hooks/import-sessions.mjs';
+import { runImport, stampSessionIds } from '../hooks/import-sessions.mjs';
 
 function opt(argv, name) {
   const i = argv.indexOf(name);
@@ -18,6 +18,14 @@ export function runImportCli(argv) {
   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); }
 
+  // Repair mode: backfill session_id into existing notes from the registry, then stop.
+  if (argv.includes('--stamp-ids')) {
+    const r = stampSessionIds(vaultBase);
+    if (argv.includes('--json')) { process.stdout.write(`${JSON.stringify(r, null, 2)}\n`); process.exit(0); }
+    process.stdout.write(`session_id carimbado em ${r.stamped} nota(s) · ${r.alreadyOk} já ok · ${r.missingFile} sem arquivo (de ${r.total} no registry)\n`);
+    process.exit(0);
+  }
+
   const projectRaw = opt(argv, '--project') || process.cwd();
   const projectPath = isAbsolute(projectRaw) ? projectRaw : resolve(process.cwd(), projectRaw);
   const source = (opt(argv, '--source') || 'all').toLowerCase();