@titan-design/brain 0.5.0 → 0.7.0

package/README.md

@@ -46,52 +46,53 @@ See [PM Quick Start](docs/pm-module/quickstart.md) for the full 5-minute guide.
 
 ### Core
 
-| Command | Description |
-|---------|-------------|
-| `brain init` | Initialize workspace and database |
-| `brain index` | Index all markdown notes |
-| `brain search "query"` | Hybrid BM25 + vector search |
-| `brain add <file>` | Add a note from file or stdin |
-| `brain quick "text"` | Zero-friction capture to inbox |
-| `brain inbox` | View/manage inbox items |
-| `brain ingest` | Bulk-import files to inbox |
-| `brain feed` | Manage RSS feed subscriptions |
-| `brain extract` | Extract memories from notes (Ollama) |
-| `brain memories` | List, history, and stats for memories |
-| `brain context <id>` | Show context for a note (relations + memories) |
-| `brain lineage <id>` | Show memory version lineage |
-| `brain profile` | Generate agent context profile |
-| `brain tidy` | LLM-powered note cleanup suggestions |
-| `brain doctor` | System health checks (`--fix` for auto-repair) |
-| `brain install-hooks` | Set up launchd/systemd scheduled processing |
-| `brain status` | Database stats |
-| `brain stale` | Notes needing review |
-| `brain graph <id>` | Show note relations |
-| `brain template <type>` | Output frontmatter template |
-| `brain archive` | Archive expired notes |
-| `brain config` | View/set configuration |
+| Command                 | Description                                                     |
+| ----------------------- | --------------------------------------------------------------- |
+| `brain init`            | Initialize workspace and database                               |
+| `brain index`           | Index all markdown notes                                        |
+| `brain search "query"`  | Hybrid BM25 + vector search                                     |
+| `brain add <file>`      | Add a note from file or stdin                                   |
+| `brain quick "text"`    | Zero-friction capture to inbox                                  |
+| `brain inbox`           | View/manage inbox items                                         |
+| `brain import <paths>`  | Smart import with three-tier extraction (`--dry-run`, `--tier`) |
+| `brain ingest`          | Bulk-import files to inbox                                      |
+| `brain feed`            | Manage RSS feed subscriptions                                   |
+| `brain extract`         | Extract memories from notes (Ollama)                            |
+| `brain memories`        | List, history, and stats for memories                           |
+| `brain context <id>`    | Show context for a note (relations + memories)                  |
+| `brain lineage <id>`    | Show memory version lineage                                     |
+| `brain profile`         | Generate agent context profile                                  |
+| `brain tidy`            | LLM-powered note cleanup suggestions                            |
+| `brain doctor`          | System health checks (`--fix` for auto-repair)                  |
+| `brain install-hooks`   | Set up launchd/systemd scheduled processing                     |
+| `brain status`          | Database stats                                                  |
+| `brain stale`           | Notes needing review                                            |
+| `brain graph <id>`      | Show note relations                                             |
+| `brain template <type>` | Output frontmatter template                                     |
+| `brain archive`         | Archive expired notes                                           |
+| `brain config`          | View/set configuration                                          |
 
 ### Project Management (`brain pm`)
 
-| Command | Description |
-|---------|-------------|
-| `brain pm init <name> --prefix <P>` | Initialize a new project |
-| `brain pm use <prefix>` | Set active project context |
-| `brain pm list` | List all projects |
-| `brain pm status [prefix]` | Show project status |
-| `brain pm workstream add <name>` | Add a workstream |
-| `brain pm task add <name>` | Create a task |
-| `brain pm task list` | List tasks (filterable by status, workstream) |
-| `brain pm task done <id>` | Mark task done |
-| `brain pm next` | Show eligible tasks (all deps satisfied) |
-| `brain pm waves` | Topological wave grouping of remaining tasks |
-| `brain pm dispatch <id>` | Assemble context bundle for a task |
-| `brain pm complete <id>` | Mark done, run impact analysis |
-| `brain pm briefing` | Session briefing with project state overview |
-| `brain pm audit summary` | Activity log, cost tracking |
-| `brain pm check [--deep]` | Consistency check (structural + semantic analysis) |
-| `brain pm setup` | Configure PM module (paths, hooks) |
-| `brain pm install-hooks` | Install PM hooks and skills (orchestrator + sanity-check) |
+| Command                             | Description                                               |
+| ----------------------------------- | --------------------------------------------------------- |
+| `brain pm init <name> --prefix <P>` | Initialize a new project                                  |
+| `brain pm use <prefix>`             | Set active project context                                |
+| `brain pm list`                     | List all projects                                         |
+| `brain pm status [prefix]`          | Show project status                                       |
+| `brain pm workstream add <name>`    | Add a workstream                                          |
+| `brain pm task add <name>`          | Create a task                                             |
+| `brain pm task list`                | List tasks (filterable by status, workstream)             |
+| `brain pm task done <id>`           | Mark task done                                            |
+| `brain pm next`                     | Show eligible tasks (all deps satisfied)                  |
+| `brain pm waves`                    | Topological wave grouping of remaining tasks              |
+| `brain pm dispatch <id>`            | Assemble context bundle for a task                        |
+| `brain pm complete <id>`            | Mark done, run impact analysis                            |
+| `brain pm briefing`                 | Session briefing with project state overview              |
+| `brain pm audit summary`            | Activity log, cost tracking                               |
+| `brain pm check [--deep]`           | Consistency check (structural + semantic analysis)        |
+| `brain pm setup`                    | Configure PM module (paths, hooks)                        |
+| `brain pm install-hooks`            | Install PM hooks and skills (orchestrator + sanity-check) |
 
 ## Architecture
 
@@ -107,6 +108,7 @@ src/
     context.ts           — Module context factory
     loader.ts            — Module discovery and loading
     validation.ts        — Frontmatter schema validation
+    knowledge/           — Knowledge module (core note types)
     pm/                  — Project management module
       commands/          — 15 command groups (incl. check)
       data/              — CRUD operations and queries
@@ -146,10 +148,32 @@ Brain indexes markdown files with YAML frontmatter into a SQLite database. It co
 - `slow` — permanent knowledge (decisions, patterns, research) with review intervals
 - `fast` — ephemeral (meetings, session logs) with expiry dates
 
+### Knowledge Graph
+
+Link related notes and traverse connections:
+
+1. Add `related` field to YAML frontmatter:
+   ```yaml
+   related:
+     - database-migration-patterns
+     - service-architecture-overview
+   ```
+2. Re-index after adding relations: `brain index`
+3. Traverse the graph:
+   ```bash
+   brain graph <note-id>           # Show direct relations
+   brain graph <note-id> --depth 2 # Show 2-hop connections
+   brain graph <note-id> --json    # Machine-readable output
+   ```
+4. Use `--expand` in search to include graph-connected notes:
+   ```bash
+   brain search "query" --expand
+   ```
+
 ## Testing
 
 ```bash
-npm test          # 1,095 tests (Vitest)
+npm test          # ~2,350 tests (Vitest)
 npm run typecheck # TypeScript checking
 npm run lint      # ESLint
 npm run build     # Production build (tsup)

package/dist/{brain-service-2QO6JM3Z.js → brain-service-TYFNTBT6.js}

@@ -1,9 +1,9 @@
 import {
   withBrain,
   withDb
-} from "./chunk-QL2GPXP6.js";
+} from "./chunk-IESQY2UZ.js";
 import "./chunk-BDNH2E2O.js";
-import "./chunk-4SD4JRLS.js";
+import "./chunk-LLAHWRO4.js";
 import "./chunk-PO3GJPIC.js";
 export {
   withBrain,

package/dist/{chunk-ZVXSW52A.js → chunk-4GDSQB2E.js}

@@ -1,6 +1,6 @@
 import {
   addFrontmatterField
-} from "./chunk-4SD4JRLS.js";
+} from "./chunk-LLAHWRO4.js";
 
 // src/services/search.ts
 import { existsSync } from "fs";

package/dist/chunk-HSQ2ZVJJ.js

@@ -0,0 +1,258 @@
+// src/services/extraction-tiers/deterministic.ts
+import { extname } from "path";
+
+// src/services/format-adapters/csv-adapter.ts
+function parseCsv(content) {
+  const lines = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+  const result = [];
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    result.push(parseRow(line));
+  }
+  if (result.length === 0) return { headers: [], rows: [] };
+  const headers = result[0].map((h) => h.trim());
+  const rows = result.slice(1).map((r) => r.map((c) => c.trim()));
+  return { headers, rows };
+}
+function parseRow(line) {
+  const cells = [];
+  let current = "";
+  let inQuotes = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (inQuotes) {
+      if (ch === '"' && line[i + 1] === '"') {
+        current += '"';
+        i++;
+      } else if (ch === '"') {
+        inQuotes = false;
+      } else {
+        current += ch;
+      }
+    } else if (ch === '"') {
+      inQuotes = true;
+    } else if (ch === ",") {
+      cells.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  cells.push(current);
+  return cells;
+}
+function csvToMarkdownTable(parsed) {
+  const escape = (s) => s.replace(/\|/g, "\\|");
+  const header = "| " + parsed.headers.map(escape).join(" | ") + " |";
+  const separator = "| " + parsed.headers.map(() => "---").join(" | ") + " |";
+  const rows = parsed.rows.map((r) => "| " + r.map(escape).join(" | ") + " |");
+  return [header, separator, ...rows].join("\n");
+}
+var LINEAR_COLUMNS = /* @__PURE__ */ new Set([
+  "id",
+  "title",
+  "status",
+  "priority",
+  "assignee",
+  "labels",
+  "team",
+  "cycle",
+  "estimate"
+]);
+var NOTION_COLUMNS = /* @__PURE__ */ new Set([
+  "name",
+  "tags",
+  "status",
+  "created time",
+  "last edited time",
+  "url"
+]);
+function detectCsvFlavor(headers) {
+  const lower = headers.map((h) => h.toLowerCase().trim());
+  const linearHits = lower.filter((h) => LINEAR_COLUMNS.has(h)).length;
+  if (linearHits >= 3) return "linear";
+  const notionHits = lower.filter((h) => NOTION_COLUMNS.has(h)).length;
+  if (notionHits >= 3) return "notion-db";
+  return "generic";
+}
+
+// src/services/extraction-tiers/deterministic.ts
+import matter from "gray-matter";
+async function extractDeterministic(content, filePath, registry, embedder) {
+  const ext = extname(filePath).toLowerCase();
+  if (ext === ".csv") {
+    const csvResult = tryCsvMatch(content, registry);
+    if (csvResult) return csvResult;
+  }
+  if (ext === ".md" || ext === ".markdown") {
+    const fmResult = tryFrontmatterMatch(content, registry);
+    if (fmResult) return fmResult;
+  }
+  const tableResult = tryTableMatch(content, registry);
+  if (tableResult) return tableResult;
+  const embeddingResult = await tryEmbeddingMatch(content, filePath, registry, embedder);
+  if (embeddingResult) return embeddingResult;
+  return { items: [], remainder: content };
+}
+function tryCsvMatch(content, registry) {
+  const parsed = parseCsv(content);
+  if (parsed.headers.length === 0 || parsed.rows.length === 0) return null;
+  const match = registry.matchColumnHeaders(parsed.headers);
+  if (!match) return null;
+  const items = [];
+  for (let i = 0; i < parsed.rows.length; i++) {
+    const row = parsed.rows[i];
+    const fields = {};
+    for (let j = 0; j < parsed.headers.length && j < row.length; j++) {
+      const headerLower = parsed.headers[j].toLowerCase().trim();
+      const schemaField = match.columnMapping[headerLower];
+      if (schemaField) {
+        fields[schemaField] = row[j];
+      } else {
+        fields[headerLower] = row[j];
+      }
+    }
+    const title = fields.name ?? fields.title ?? `Row ${i + 1}`;
+    delete fields.name;
+    delete fields.title;
+    items.push({
+      noteType: match.noteType,
+      title,
+      content: Object.entries(fields).filter(([k]) => k !== "description").map(([k, v]) => `**${k}:** ${v}`).join("\n"),
+      fields,
+      sourceRegion: { startLine: i + 2, endLine: i + 2 }
+    });
+  }
+  return items.length > 0 ? { items, remainder: null } : null;
+}
+function tryFrontmatterMatch(content, registry) {
+  try {
+    const { data, content: body } = matter(content);
+    if (!data.type || typeof data.type !== "string") return null;
+    const noteType = registry.getNoteType(data.type);
+    if (!noteType) return null;
+    const title = data.title ?? "Untitled";
+    return {
+      items: [
+        {
+          noteType: data.type,
+          title,
+          content: body.trim(),
+          fields: extractFieldsFromFrontmatter(data)
+        }
+      ],
+      remainder: null
+    };
+  } catch {
+    return null;
+  }
+}
+function extractFieldsFromFrontmatter(data) {
+  const fields = {};
+  const skip = /* @__PURE__ */ new Set(["id", "title", "type", "tier", "module"]);
+  for (const [key, value] of Object.entries(data)) {
+    if (skip.has(key)) continue;
+    if (value instanceof Date) {
+      fields[key] = value.toISOString().split("T")[0];
+    } else if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      fields[key] = String(value);
+    }
+  }
+  return fields;
+}
+function tryTableMatch(content, registry) {
+  const lines = content.split("\n");
+  const headerLine = lines.find((l) => /^\|.+\|/.test(l));
+  if (!headerLine) return null;
+  const headerIdx = lines.indexOf(headerLine);
+  const sepIdx = headerIdx + 1;
+  if (sepIdx >= lines.length || !/^\|[\s\-:|]+\|/.test(lines[sepIdx])) return null;
+  const headers = headerLine.split("|").map((h) => h.trim()).filter(Boolean);
+  const match = registry.matchColumnHeaders(headers);
+  if (!match) return null;
+  const items = [];
+  for (let i = sepIdx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!/^\|.+\|/.test(line)) continue;
+    const cells = line.split("|").map((c) => c.trim()).filter(Boolean);
+    const fields = {};
+    for (let j = 0; j < headers.length && j < cells.length; j++) {
+      const headerLower = headers[j].toLowerCase().trim();
+      const schemaField = match.columnMapping[headerLower];
+      if (schemaField) {
+        fields[schemaField] = cells[j];
+      } else {
+        fields[headerLower] = cells[j];
+      }
+    }
+    const title = fields.name ?? fields.title ?? `Row ${i - sepIdx}`;
+    delete fields.name;
+    delete fields.title;
+    items.push({
+      noteType: match.noteType,
+      title,
+      content: Object.entries(fields).filter(([k]) => k !== "description").map(([k, v]) => `**${k}:** ${v}`).join("\n"),
+      fields,
+      sourceRegion: { startLine: i + 1, endLine: i + 1 }
+    });
+  }
+  return items.length > 0 ? { items, remainder: null } : null;
+}
+async function tryEmbeddingMatch(content, filePath, registry, embedder) {
+  const archetypeTexts = registry.getArchetypeTexts();
+  if (archetypeTexts.size === 0) return null;
+  let body;
+  try {
+    const parsed = matter(content);
+    body = parsed.content.trim();
+  } catch {
+    body = content.trim();
+  }
+  if (body.length < 50 || body.length > 1e4) return null;
+  const typeNames = Array.from(archetypeTexts.keys());
+  const texts = typeNames.map((t) => archetypeTexts.get(t));
+  const allVectors = await embedder.embed([body, ...texts]);
+  const docVec = allVectors[0];
+  let bestType = "";
+  let bestScore = 0.85;
+  for (let i = 0; i < typeNames.length; i++) {
+    const score = cosineSimilarity(docVec, allVectors[i + 1]);
+    if (score > bestScore) {
+      bestScore = score;
+      bestType = typeNames[i];
+    }
+  }
+  if (!bestType) return null;
+  const title = filePath.split("/").pop()?.replace(/\.[^.]+$/, "") ?? "Untitled";
+  return {
+    items: [
+      {
+        noteType: bestType,
+        title,
+        content: body,
+        fields: {}
+      }
+    ],
+    remainder: null
+  };
+}
+function cosineSimilarity(a, b) {
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+export {
+  parseCsv,
+  csvToMarkdownTable,
+  detectCsvFlavor,
+  extractDeterministic,
+  cosineSimilarity
+};

package/dist/{chunk-QL2GPXP6.js → chunk-IESQY2UZ.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-BDNH2E2O.js";
 import {
   addFrontmatterField
-} from "./chunk-4SD4JRLS.js";
+} from "./chunk-LLAHWRO4.js";
 
 // src/services/config.ts
 import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync } from "fs";
@@ -1664,6 +1664,50 @@ var ModuleRegistry = class {
   getContentHandlers() {
     return [...this.contentHandlers];
   }
+  // --- Import Hints ---
+  /** Returns all note types that have importHints configured */
+  getImportableNoteTypes() {
+    return this.getAllNoteTypes().filter(({ noteType }) => noteType.importHints);
+  }
+  /** Match CSV/table column headers against registered tableColumnAliases.
+   *  Returns the best-matching note type if 2+ columns match, else null. */
+  matchColumnHeaders(headers) {
+    const lowerHeaders = headers.map((h) => h.toLowerCase().trim());
+    let bestMatch = null;
+    for (const { module, noteType } of this.getImportableNoteTypes()) {
+      const aliases = noteType.importHints?.tableColumnAliases;
+      if (!aliases) continue;
+      const mapping = {};
+      let hits = 0;
+      for (const [schemaField, columnNames] of Object.entries(aliases)) {
+        const matched = lowerHeaders.find(
+          (h) => columnNames.map((c) => c.toLowerCase()).includes(h)
+        );
+        if (matched) {
+          mapping[matched] = schemaField;
+          hits++;
+        }
+      }
+      if (hits >= 2 && (!bestMatch || hits > bestMatch.hits)) {
+        bestMatch = { module, noteType: noteType.name, columnMapping: mapping, hits };
+      }
+    }
+    return bestMatch ? {
+      module: bestMatch.module,
+      noteType: bestMatch.noteType,
+      columnMapping: bestMatch.columnMapping
+    } : null;
+  }
+  /** Returns archetype texts for embedding-based classification */
+  getArchetypeTexts() {
+    const result = /* @__PURE__ */ new Map();
+    for (const { noteType } of this.getImportableNoteTypes()) {
+      if (noteType.importHints?.archetypeText) {
+        result.set(noteType.name, noteType.importHints.archetypeText);
+      }
+    }
+    return result;
+  }
 };
 
 // src/modules/context.ts

package/dist/{chunk-4SD4JRLS.js → chunk-LLAHWRO4.js}

@@ -18,7 +18,8 @@ var VALID_CORE_NOTE_TYPES = [
   "research",
   "meeting",
   "session-log",
-  "guide"
+  "guide",
+  "workflow"
 ];
 var VALID_NOTE_TIERS = ["slow", "fast"];
 var VALID_NOTE_CONFIDENCES = ["high", "medium", "low", "speculative"];
@@ -826,7 +827,6 @@ export {
   slugify,
   parseIntervalDays,
   parseMarkdown,
-  splitIntoSections,
   computeAutoLinks,
   traverseGraph,
   expandResults,