wendkeep 0.1.0

package/README.md

@@ -0,0 +1,85 @@
+# wendkeep
+
+**Automatically capture your AI coding agent sessions as local Markdown in your Obsidian vault.** Every Claude Code / Codex session is written turn‑by‑turn into your vault — with token/cost tracking, auto‑extracted decisions, bugs and learnings, and a curated memory layer injected back at the start of the next session. 100% local, open‑core.
+
+> Status: `v0.1` — extracted from a system in daily production use. The capture engine, cost tracking and graph wiring are battle‑tested; the cross‑platform installer (`wendkeep init`) is the new part. See [`docs/`](docs/) for the project's strategy and decision log.
+
+---
+
+## Why
+
+The pieces to give a coding agent durable memory exist, but fragmented (qmd‑sessions, memsearch, Nexus, hand‑written hooks). wendkeep ships them as one turnkey package that lands the memory **inside the Obsidian graph you already use** — no manual setup, no snapshot to keep in sync.
+
+## What you get
+
+- **Automatic session capture** — `SessionStart` / `UserPromptSubmit` / `Stop` hooks write each session to `02-Sessões/<year>/<month>/DIA <dd>/` as Markdown with YAML frontmatter, turn‑by‑turn iterations, and wikilinks.
+- **Multi‑agent** — detects the real provider (Claude Code, Codex, Copilot) at runtime; one install covers all.
+- **Token & cost tracking** — per‑model, cache‑aware pricing (`pricing.json`) with a per‑session usage table.
+- **Auto‑extracted derived notes** — decisions (ADR‑style), bugs and learnings pulled from the transcript into `04-Decisões/`, `05-Bugs/`, `06-Aprendizados/`, backlinked to the session.
+- **Curated memory** — a cold frontmatter index (`.brain/`) plus a budget‑capped `CORE` + `DIGEST` injected at the next `SessionStart`.
+- **Local‑first** — everything is plain Markdown on your disk. The optional MCP server (`@bitbonsai/mcpvault`) lets the agent read/write the vault; no cloud, no account.
+
+## Requirements
+
+- Node.js ≥ 18
+- An AI coding agent with hooks (Claude Code today; Codex supported by the same hooks)
+- Obsidian (to view the graph) — optional but the point
+
+## Install & set up
+
+```bash
+# in your project
+npm install --save-dev wendkeep   # or: npm install -g wendkeep
+npx wendkeep init
+```
+
+`wendkeep init` is interactive and **idempotent**. It will:
+
+1. Create the vault folder taxonomy (default vault: `<project>/.wendkeep-vault`, override with `--vault`).
+2. **Merge** the three session hooks and `OBSIDIAN_VAULT_PATH` into `.claude/settings.json` — without clobbering your existing settings (a `.bak` is saved; an unparseable file is left untouched and a `.new` is written for you to merge).
+3. Add the `wendkeep-vault` MCP server to `.mcp.json` (skip with `--no-mcp`).
+
+```bash
+npx wendkeep init --vault "~/vaults/work" --project . --yes   # non-interactive
+```
+
+Then open the vault in Obsidian, send a test prompt in your agent, and confirm a note appears under `02-Sessões/…`.
+
+## Updating
+
+Because the hooks live inside the installed package (settings.json calls `npx wendkeep hook <name>`), upgrading is just:
+
+```bash
+npm update wendkeep
+```
+
+No re‑copying, no snapshot to re‑sync — the package is the single source of truth.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `wendkeep init` | Set up wendkeep in a project (vault taxonomy + settings + MCP). |
+| `wendkeep hook <name>` | Run a session hook; invoked by `settings.json` (reads agent JSON on stdin). |
+| `wendkeep doctor [--vault P]` | Run a vault health check (integrity of sessions, registry, links). |
+| `wendkeep --version` / `--help` | Version / usage. |
+
+## How it works
+
+```
+agent session ──hooks──▶ wendkeep ──▶ Markdown in vault ──▶ .brain index + Obsidian graph
+   (Claude/Codex)        (Node)      (02-Sessões/…)        (CORE+DIGEST, backlinks)
+```
+
+The agent's settings.json points each hook at `npx wendkeep hook …`. On `Stop`, wendkeep parses the session transcript, appends the turn, updates the token/cost table, and (idempotently) emits any decision/bug/learning notes. On the next `SessionStart`, the curated memory is injected back into context.
+
+## Known limitations (`v0.1`)
+
+- **Vault folder names and month labels are Portuguese** (`02-Sessões`, `04-Decisões`, …), hardcoded in the hooks. Internationalization is not done yet — the taxonomy `wendkeep init` creates matches what the hooks expect on purpose.
+- **Search is keyword/frontmatter scoring**, not on‑device embeddings (that's on the roadmap).
+- **Transcript formats are agent‑internal** and can change between agent versions; parsing is isolated but may need updates.
+- Installer wires **Claude Code** settings + `.mcp.json`. Codex hooks run on the same scripts but are not auto‑wired yet.
+
+## License
+
+MIT

package/bin/wendkeep.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// wendkeep CLI — single entrypoint.
+//   wendkeep init [--vault <path>] [--project <path>] [--no-mcp] [--yes] [--force]
+//   wendkeep hook <name>      (invoked by the agent's settings.json; pipes stdin/stdout)
+//   wendkeep doctor [--vault <path>]
+//   wendkeep --version | --help
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { RUNNABLE_HOOKS } from '../src/taxonomy.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = join(here, '..');
+const hooksDir = join(pkgRoot, 'hooks');
+
+function version() {
+  try {
+    return JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8')).version;
+  } catch {
+    return '0.0.0';
+  }
+}
+
+const HELP = `wendkeep ${version()} — capture AI coding agent sessions into your Obsidian vault.
+
+Usage:
+  wendkeep init [options]      Set up wendkeep in a project (cross-platform).
+    --vault <path>         Obsidian vault folder (default: <project>/.wendkeep-vault).
+    --project <path>       Project root to wire (default: current directory).
+    --no-mcp               Do not add the mcpvault MCP server to .mcp.json.
+    --yes, -y              Non-interactive; accept defaults.
+    --force                Overwrite existing wendkeep config blocks.
+
+  wendkeep hook <name>         Run a session hook (used by settings.json). Reads the
+                           agent's JSON on stdin. Names: ${RUNNABLE_HOOKS.join(', ')}.
+
+  wendkeep doctor [--vault P]  Run a vault health check.
+  wendkeep --version           Print version.
+  wendkeep --help              Show this help.
+`;
+
+function runHook(name) {
+  if (!name) {
+    process.stderr.write('wendkeep hook: missing hook name\n');
+    process.exit(2);
+  }
+  if (!RUNNABLE_HOOKS.includes(name)) {
+    process.stderr.write(`wendkeep hook: unknown hook "${name}". Known: ${RUNNABLE_HOOKS.join(', ')}\n`);
+    process.exit(2);
+  }
+  const file = join(hooksDir, `${name}.mjs`);
+  if (!existsSync(file)) {
+    process.stderr.write(`wendkeep hook: hook file not found: ${file}\n`);
+    process.exit(2);
+  }
+  // Spawn exactly as the agent would run `node <hook>.mjs`: stdio inherited so the
+  // hook's stdin (agent JSON) and stdout (hookSpecificOutput) pass through untouched.
+  const r = spawnSync(process.execPath, [file], { stdio: 'inherit' });
+  process.exit(r.status ?? 0);
+}
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  switch (cmd) {
+    case 'init': {
+      const { runInit } = await import('../src/init.mjs');
+      await runInit(rest);
+      break;
+    }
+    case 'hook':
+      runHook(rest[0]);
+      break;
+    case 'doctor': {
+      const { runDoctor } = await import('../src/doctor.mjs');
+      runDoctor(rest);
+      break;
+    }
+    case '--version':
+    case '-v':
+      process.stdout.write(`${version()}\n`);
+      break;
+    case undefined:
+    case '--help':
+    case '-h':
+    case 'help':
+      process.stdout.write(HELP);
+      break;
+    default:
+      process.stderr.write(`wendkeep: unknown command "${cmd}"\n\n${HELP}`);
+      process.exit(2);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`wendkeep: ${err?.stack || err}\n`);
+  process.exit(1);
+});

package/hooks/brain-core.mjs

@@ -0,0 +1,142 @@
+// .agent/hooks/brain-core.mjs
+// Camada fria do brain: indexa o frontmatter das notas de sessão (0 token LLM).
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensureDir, stripYamlQuotes, toVaultRelative } from './obsidian-common.mjs';
+
+export function brainDir(vaultBase) {
+  return join(vaultBase, '.brain');
+}
+
+// Frontmatter YAML simples: escalares `k: v` + listas `k:` seguido de `  - item`.
+export function parseFrontmatter(content) {
+  const m = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return {};
+  const data = {};
+  const lines = m[1].split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const kv = lines[i].match(/^([\w-]+):\s*(.*)$/);
+    if (!kv) continue;
+    const key = kv[1];
+    const val = kv[2];
+    if (val === '') {
+      const list = [];
+      while (i + 1 < lines.length && /^\s+-\s+/.test(lines[i + 1])) {
+        list.push(stripYamlQuotes(lines[++i].replace(/^\s+-\s+/, '').trim()));
+      }
+      data[key] = list.length ? list : '';
+    } else {
+      data[key] = stripYamlQuotes(val.trim());
+    }
+  }
+  return data;
+}
+
+function walkMd(dir) {
+  const out = [];
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    const fp = join(dir, e.name);
+    if (e.isDirectory()) out.push(...walkMd(fp));
+    else if (e.name.endsWith('.md')) out.push(fp);
+  }
+  return out;
+}
+
+const DERIVED_RE = /\[\[(0[456]-[^\]|]+?)(?:\|[^\]]*)?\]\]/g;
+function derivedLinks(content) {
+  const dec = new Set(), bug = new Set(), lea = new Set();
+  let m;
+  while ((m = DERIVED_RE.exec(content))) {
+    const t = m[1];
+    if (t.startsWith('04-')) dec.add(t);
+    else if (t.startsWith('05-')) bug.add(t);
+    else if (t.startsWith('06-')) lea.add(t);
+  }
+  return { decisions: [...dec], bugs: [...bug], learnings: [...lea] };
+}
+
+// Varre 02-Sessões/** e regrava .brain/index.jsonl inteiro. Provider-agnóstico.
+export function buildBrainIndex(vaultBase) {
+  const rows = [];
+  for (const fp of walkMd(join(vaultBase, '02-Sessões'))) {
+    let content;
+    try { content = readFileSync(fp, 'utf8'); } catch { continue; }
+    const fm = parseFrontmatter(content);
+    if (fm.type && fm.type !== 'session') continue;
+    const der = derivedLinks(content);
+    rows.push({
+      session_id: fm.session_id || '',
+      date: fm.date || '',
+      provider: fm.provider || '',
+      status: fm.status || '',
+      summary: fm.summary || '',
+      file: toVaultRelative(vaultBase, fp),
+      tags: Array.isArray(fm.tags) ? fm.tags : (fm.tags ? [fm.tags] : []),
+      decisions: der.decisions,
+      bugs: der.bugs,
+      learnings: der.learnings,
+    });
+  }
+  rows.sort((a, b) => (a.date + a.file).localeCompare(b.date + b.file));
+  ensureDir(brainDir(vaultBase));
+  const out = rows.map((r) => JSON.stringify(r)).join('\n') + (rows.length ? '\n' : '');
+  writeFileSync(join(brainDir(vaultBase), 'index.jsonl'), out, 'utf8');
+  return rows;
+}
+
+// Lê o índice gravado (linhas JSONL). Usado pelo recall e pelo digest.
+export function loadIndex(vaultBase) {
+  try {
+    return readFileSync(join(brainDir(vaultBase), 'index.jsonl'), 'utf8')
+      .split('\n').filter(Boolean).map((l) => JSON.parse(l));
+  } catch {
+    return [];
+  }
+}
+
+const DIGEST_CAPS = { decisions: 5, sessions: 4, bugs: 2, learnings: 2 };
+
+function adrNumber(path) {
+  const m = path.match(/ADR-(\d+)/);
+  return m ? Number(m[1]) : -1;
+}
+
+// Destila index.jsonl em .brain/DIGEST.md (camada quente, determinístico, 0 token LLM).
+// Cap por construção: 1 header + 13 itens (5/4/2/2) + 1 pointer = máx 15 linhas.
+export function buildBrainDigest(vaultBase, rows = null) {
+  const data = rows ?? loadIndex(vaultBase);
+  const byDateDesc = [...data].sort((a, b) =>
+    String(b.date || '').localeCompare(String(a.date || '')) || String(b.file || '').localeCompare(String(a.file || '')));
+
+  const seen = new Set();
+  const pick = (kind, max) => {
+    const out = [];
+    for (const r of byDateDesc) {
+      for (const p of r[kind] || []) {
+        if (out.length >= max) return out;
+        if (!seen.has(p)) { seen.add(p); out.push(p); }
+      }
+    }
+    return out;
+  };
+
+  const decisions = pick('decisions', DIGEST_CAPS.decisions).sort((a, b) => adrNumber(b) - adrNumber(a));
+  const sessions = byDateDesc.slice(0, DIGEST_CAPS.sessions);
+  const bugs = pick('bugs', DIGEST_CAPS.bugs);
+  const learnings = pick('learnings', DIGEST_CAPS.learnings);
+
+  const lines = ['<!-- AUTO-GERADO por brain-core.mjs (0 token LLM). NÃO editar. Rebuild: node .agent/hooks/brain-reindex.mjs -->'];
+  for (const d of decisions) lines.push(`- Decisão: [[${d}]]`);
+  for (const s of sessions) lines.push(`- Sessão ${s.date} (${s.provider || '?'}): ${s.summary || s.file} → [[${String(s.file || '').replace(/\.md$/, '')}]]`);
+  for (const b of bugs) lines.push(`- Bug: [[${b}]]`);
+  for (const l of learnings) lines.push(`- Aprendizado: [[${l}]]`);
+
+  const shown = sessions.length;
+  if (data.length > shown) lines.push(`- +${data.length - shown} mais no índice — use /brain-recall <tópico>`);
+
+  ensureDir(brainDir(vaultBase));
+  writeFileSync(join(brainDir(vaultBase), 'DIGEST.md'), lines.join('\n') + '\n', 'utf8');
+  return lines;
+}

package/hooks/brain-inject.mjs

@@ -0,0 +1,42 @@
+// .agent/hooks/brain-inject.mjs
+// Injeção da camada quente no SessionStart (Claude/Codex/Copilot): CORE curado +
+// DIGEST auto + 1-linha pointer do recall. Budget-capada. Nunca derruba o hook.
+// Uso (hook): node .agent/hooks/brain-inject.mjs   (input JSON via stdin)
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { getVaultBase, readHookInput, writeHookOutput } from './obsidian-common.mjs';
+import { brainDir } from './brain-core.mjs';
+
+const MAX_LINES = 45; // CORE ≤25 + DIGEST ≤15 + folga; salvaguarda se o CORE crescer à mão
+
+export function buildInjection(vaultBase) {
+  const dir = brainDir(vaultBase);
+  const read = (name) => {
+    try { return readFileSync(join(dir, name), 'utf8').trim(); } catch { return ''; }
+  };
+  const pointer = 'Memória profunda sob demanda: /brain-recall <tópico> (índice .brain/index.jsonl).';
+  // Quando CORE e DIGEST não existem, ''.split('\n') vira [''] — o filter derruba essa
+  // linha vazia para o caso "só pointer" ficar com exatamente 3 linhas.
+  let lines = [read('CORE.md'), read('DIGEST.md')].filter(Boolean).join('\n\n').split('\n').filter((l, i, a) => a.length > 1 || l);
+  if (lines.length > MAX_LINES) {
+    lines = lines.slice(0, MAX_LINES);
+    lines.push('*…truncado pelo budget — fonte completa: .brain/CORE.md + .brain/DIGEST.md*');
+  }
+  return ['<brain_memory>', ...lines, pointer, '</brain_memory>'].join('\n');
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    const input = readHookInput();
+    writeHookOutput({
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: buildInjection(getVaultBase(input)),
+      },
+    });
+  } catch (error) {
+    process.stderr.write(`[brain] inject falhou: ${error.message}\n`);
+    writeHookOutput({});
+  }
+}

package/hooks/brain-recall.mjs

@@ -0,0 +1,32 @@
+// .agent/hooks/brain-recall.mjs
+// Query engine read-only: pontua o índice por tópico. Token só no resultado.
+// Uso: node .agent/hooks/brain-recall.mjs <termos da busca>
+import { pathToFileURL } from 'node:url';
+import { getVaultBase } from './obsidian-common.mjs';
+import { loadIndex } from './brain-core.mjs';
+
+export { loadIndex };
+
+export function scoreRows(rows, query, topK = 5) {
+  const terms = String(query).toLowerCase().split(/\s+/).filter(Boolean);
+  if (!terms.length) return [];
+  return rows
+    .map((r) => {
+      // Inclui slug do file + paths das derivadas (ADR/bug/aprendizado) no haystack:
+      // os títulos das sessões e tags são genéricos; o sinal tópico vem dos slugs.
+      const hay = `${r.summary || ''} ${(r.tags || []).join(' ')} ${r.file || ''} ${(r.decisions || []).join(' ')} ${(r.bugs || []).join(' ')} ${(r.learnings || []).join(' ')}`.toLowerCase();
+      let score = 0;
+      for (const t of terms) if (hay.includes(t)) score++;
+      return { row: r, score };
+    })
+    .filter((s) => s.score > 0)
+    .sort((a, b) => b.score - a.score || String(b.row.date || '').localeCompare(String(a.row.date || '')))
+    .slice(0, topK)
+    .map((s) => s.row);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const vaultBase = getVaultBase();
+  const hits = scoreRows(loadIndex(vaultBase), process.argv.slice(2).join(' '));
+  process.stdout.write(JSON.stringify(hits, null, 2) + '\n');
+}

package/hooks/brain-reindex.mjs

@@ -0,0 +1,13 @@
+// .agent/hooks/brain-reindex.mjs
+// Backfill manual: reconstrói .brain/index.jsonl + .brain/DIGEST.md varrendo todo 02-Sessões.
+// Uso: node .agent/hooks/brain-reindex.mjs [caminho-do-vault]
+import { pathToFileURL } from 'node:url';
+import { getVaultBase } from './obsidian-common.mjs';
+import { buildBrainDigest, buildBrainIndex, brainDir } from './brain-core.mjs';
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const vaultBase = getVaultBase({ obsidian_vault_path: process.argv[2] });
+  const rows = buildBrainIndex(vaultBase);
+  const digest = buildBrainDigest(vaultBase, rows);
+  process.stdout.write(`[brain] index: ${rows.length} sessões; digest: ${digest.length} linhas → ${brainDir(vaultBase)}\n`);
+}