recallnest 2.2.0 → 2.3.0

package/logs/ingest-2026-04-12.log

@@ -0,0 +1,90 @@
+=== 2026-04-12 03:00:01 增量更新开始 ===
+[INFO] LLM client initialized: qwen-turbo @ https://dashscope.aliyuncs.com/compatible-mode/v1
+
+🔑 验证 Embedding API...
+  ✅ jina-embeddings-v5-text-small (1024d)
+  ✅ LLM: qwen-turbo (L0 摘要 + 语义去重)
+  ✅ 两阶段去重: vector + LLM 语义判断
+
+🔄 开始导入记忆 (source: all)...
+
+📝 导入 Claude Code 对话...
+[INFO] noise-filter: denial pattern matched: "<task-notification>
+<task-id>ac1e8c3a46f90bcc6</task-id>
+<to..."
+  CC: 400/976 files, 269 chunks ingested
+[INFO] noise-filter: denial pattern matched: "完全破案了。
+
+**根因：4月10日 22:55（新加坡时间）发生了一次批量仓库可见性修改**
+
+时间线还原：
+
+| U..."
+  CC: 770/976 files, 541 chunks ingested
+  ✅ CC: 19 files, 563 ingested, 505 deduped (hard:24, exact:228, llm-skip:114, llm-merge:139), 0 errors
+🤖 导入 Codex 对话...
+  ✅ Codex: 0 files, 0 ingested, 0 deduped (hard:0, exact:0, llm-skip:0, llm-merge:0), 0 errors
+💎 导入 Gemini 对话...
+  ✅ Gemini: 0 files, 0 ingested, 0 deduped (hard:0, exact:0, llm-skip:0, llm-merge:0), 0 errors
+🖥️  导入 Claude Desktop 对话...
+  ✅ Desktop: 0 files, 0 ingested, 0 deduped (hard:0, exact:0, llm-skip:0, llm-merge:0), 0 errors
+📚 导入记忆文件...
+  ✅ Memory: 5 files, 4 ingested, 188 deduped (hard:0, exact:172, llm-skip:13, llm-merge:3), 0 errors
+
+📊 导入汇总:
+  总计: 567 chunks 已索引, 693 chunks 去重 (hard:24, exact:400, llm-skip:127, llm-merge:142), 0 errors
+
+=== 2026-04-12 03:16:02 增量更新完成 ===
+
+=== 2026-04-12 11:16:02 增量更新开始 ===
+[INFO] LLM client initialized: qwen-turbo @ https://dashscope.aliyuncs.com/compatible-mode/v1
+
+🔑 验证 Embedding API...
+  ✅ jina-embeddings-v5-text-small (1024d)
+  ✅ LLM: qwen-turbo (L0 摘要 + 语义去重)
+  ✅ 两阶段去重: vector + LLM 语义判断
+
+🔄 开始导入记忆 (source: all)...
+
+📝 导入 Claude Code 对话...
+  ✅ CC: 5 files, 141 ingested, 90 deduped (hard:4, exact:24, llm-skip:30, llm-merge:32), 0 errors
+🤖 导入 Codex 对话...
+  ✅ Codex: 0 files, 0 ingested, 0 deduped (hard:0, exact:0, llm-skip:0, llm-merge:0), 0 errors
+💎 导入 Gemini 对话...
+  ✅ Gemini: 0 files, 0 ingested, 0 deduped (hard:0, exact:0, llm-skip:0, llm-merge:0), 0 errors
+🖥️  导入 Claude Desktop 对话...
+  ✅ Desktop: 0 files, 0 ingested, 0 deduped (hard:0, exact:0, llm-skip:0, llm-merge:0), 0 errors
+📚 导入记忆文件...
+  ✅ Memory: 1 files, 0 ingested, 182 deduped (hard:0, exact:171, llm-skip:11, llm-merge:0), 0 errors
+
+📊 导入汇总:
+  总计: 141 chunks 已索引, 272 chunks 去重 (hard:4, exact:195, llm-skip:41, llm-merge:32), 0 errors
+
+=== 2026-04-12 11:21:02 增量更新完成 ===
+
+=== 2026-04-12 19:21:02 增量更新开始 ===
+[INFO] LLM client initialized: qwen-turbo @ https://dashscope.aliyuncs.com/compatible-mode/v1
+
+🔑 验证 Embedding API...
+  ✅ jina-embeddings-v5-text-small (1024d)
+  ✅ LLM: qwen-turbo (L0 摘要 + 语义去重)
+  ✅ 两阶段去重: vector + LLM 语义判断
+
+🔄 开始导入记忆 (source: all)...
+
+📝 导入 Claude Code 对话...
+  ✅ CC: 3 files, 55 ingested, 188 deduped (hard:2, exact:134, llm-skip:33, llm-merge:19), 0 errors
+🤖 导入 Codex 对话...
+  ✅ Codex: 0 files, 0 ingested, 0 deduped (hard:0, exact:0, llm-skip:0, llm-merge:0), 0 errors
+💎 导入 Gemini 对话...
+  ✅ Gemini: 0 files, 0 ingested, 0 deduped (hard:0, exact:0, llm-skip:0, llm-merge:0), 0 errors
+🖥️  导入 Claude Desktop 对话...
+  ✅ Desktop: 0 files, 0 ingested, 0 deduped (hard:0, exact:0, llm-skip:0, llm-merge:0), 0 errors
+📚 导入记忆文件...
+  ✅ Memory: 1 files, 0 ingested, 182 deduped (hard:0, exact:171, llm-skip:11, llm-merge:0), 0 errors
+
+📊 导入汇总:
+  总计: 55 chunks 已索引, 370 chunks 去重 (hard:2, exact:305, llm-skip:44, llm-merge:19), 0 errors
+
+=== 2026-04-12 19:25:03 增量更新完成 ===
+

package/logs/ingest-2026-04-13.log

@@ -0,0 +1,87 @@
+=== 2026-04-13 03:00:04 增量更新开始 ===
+[INFO] LLM client initialized: qwen-turbo @ https://dashscope.aliyuncs.com/compatible-mode/v1
+
+🔑 验证 Embedding API...
+  ✅ jina-embeddings-v5-text-small (1024d)
+  ✅ LLM: qwen-turbo (L0 摘要 + 语义去重)
+  ✅ 两阶段去重: vector + LLM 语义判断
+
+🔄 开始导入记忆 (source: all)...
+
+📝 导入 Claude Code 对话...
+[INFO] noise-filter: short boilerplate filtered: "收到！多路并行处理："
+  CC: 430/1002 files, 87 chunks ingested
+  CC: 680/1002 files, 217 chunks ingested
+  ✅ CC: 23 files, 378 ingested, 655 deduped (hard:67, exact:279, llm-skip:202, llm-merge:107), 0 errors
+🤖 导入 Codex 对话...
+  ✅ Codex: 0 files, 0 ingested, 0 deduped (hard:0, exact:0, llm-skip:0, llm-merge:0), 0 errors
+💎 导入 Gemini 对话...
+  ✅ Gemini: 0 files, 0 ingested, 0 deduped (hard:0, exact:0, llm-skip:0, llm-merge:0), 0 errors
+🖥️  导入 Claude Desktop 对话...
+  ✅ Desktop: 0 files, 0 ingested, 0 deduped (hard:0, exact:0, llm-skip:0, llm-merge:0), 0 errors
+📚 导入记忆文件...
+  ✅ Memory: 7 files, 26 ingested, 216 deduped (hard:1, exact:192, llm-skip:16, llm-merge:7), 0 errors
+
+📊 导入汇总:
+  总计: 404 chunks 已索引, 871 chunks 去重 (hard:68, exact:471, llm-skip:218, llm-merge:114), 0 errors
+
+=== 2026-04-13 03:13:05 增量更新完成 ===
+
+=== 2026-04-13 11:13:05 增量更新开始 ===
+[INFO] LLM client initialized: qwen-turbo @ https://dashscope.aliyuncs.com/compatible-mode/v1
+
+🔑 验证 Embedding API...
+  ✅ jina-embeddings-v5-text-small (1024d)
+  ✅ LLM: qwen-turbo (L0 摘要 + 语义去重)
+  ✅ 两阶段去重: vector + LLM 语义判断
+
+🔄 开始导入记忆 (source: all)...
+
+📝 导入 Claude Code 对话...
+  CC: 480/1006 files, 20 chunks ingested
+[INFO] noise-filter: denial pattern matched: "好，全文读完了。这篇文章标题是「Claude Code 省 Token 指南：慎用 1M 上下文，不开新会话或者总是开新..."
+  ✅ CC: 5 files, 130 ingested, 153 deduped (hard:14, exact:44, llm-skip:46, llm-merge:49), 0 errors
+🤖 导入 Codex 对话...
+[INFO] noise-filter: meta-question filtered: "# AGENTS.md instructions for /Users/anxianjingya
+
+<INSTRUCTI..."
+  Codex: 295/295 files, 2 chunks ingested
+  ✅ Codex: 1 files, 2 ingested, 1 deduped (hard:0, exact:0, llm-skip:0, llm-merge:1), 0 errors
+💎 导入 Gemini 对话...
+  ✅ Gemini: 0 files, 0 ingested, 0 deduped (hard:0, exact:0, llm-skip:0, llm-merge:0), 0 errors
+🖥️  导入 Claude Desktop 对话...
+  ✅ Desktop: 0 files, 0 ingested, 0 deduped (hard:0, exact:0, llm-skip:0, llm-merge:0), 0 errors
+📚 导入记忆文件...
+  ✅ Memory: 1 files, 1 ingested, 185 deduped (hard:0, exact:172, llm-skip:13, llm-merge:0), 0 errors
+
+📊 导入汇总:
+  总计: 133 chunks 已索引, 339 chunks 去重 (hard:14, exact:216, llm-skip:59, llm-merge:50), 0 errors
+
+=== 2026-04-13 11:19:05 增量更新完成 ===
+
+=== 2026-04-13 19:19:05 增量更新开始 ===
+[INFO] LLM client initialized: qwen-turbo @ https://dashscope.aliyuncs.com/compatible-mode/v1
+
+🔑 验证 Embedding API...
+  ✅ jina-embeddings-v5-text-small (1024d)
+  ✅ LLM: qwen-turbo (L0 摘要 + 语义去重)
+  ✅ 两阶段去重: vector + LLM 语义判断
+
+🔄 开始导入记忆 (source: all)...
+
+📝 导入 Claude Code 对话...
+  ✅ CC: 12 files, 193 ingested, 225 deduped (hard:19, exact:71, llm-skip:74, llm-merge:61), 0 errors
+🤖 导入 Codex 对话...
+  ✅ Codex: 0 files, 0 ingested, 0 deduped (hard:0, exact:0, llm-skip:0, llm-merge:0), 0 errors
+💎 导入 Gemini 对话...
+  ✅ Gemini: 0 files, 0 ingested, 0 deduped (hard:0, exact:0, llm-skip:0, llm-merge:0), 0 errors
+🖥️  导入 Claude Desktop 对话...
+  ✅ Desktop: 0 files, 0 ingested, 0 deduped (hard:0, exact:0, llm-skip:0, llm-merge:0), 0 errors
+📚 导入记忆文件...
+  ✅ Memory: 6 files, 16 ingested, 229 deduped (hard:0, exact:202, llm-skip:16, llm-merge:11), 0 errors
+
+📊 导入汇总:
+  总计: 209 chunks 已索引, 454 chunks 去重 (hard:19, exact:273, llm-skip:90, llm-merge:72), 0 errors
+
+=== 2026-04-13 19:27:06 增量更新完成 ===
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "recallnest",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "RecallNest \u2014 MCP-native, local-first memory search and distillation for AI conversations",
   "license": "MIT",
   "type": "module",

package/src/cli.ts

@@ -29,6 +29,8 @@ import {
   ingestCodexSessions,
   ingestGeminiSessions,
   ingestMarkdownFiles,
+  ingestObsidianVault,
+  ingestConnectorFile,
 } from "./ingest.js";
 import { runDoctor, formatDoctorResults } from "./doctor.js";
 import { persistCaseMemory, persistMemory, persistWorkflowPattern } from "./capture-engine.js";
@@ -1306,6 +1308,8 @@ program
   .option("--no-dedup", "跳过向量去重")
   .option("--no-llm", "禁用 LLM 提取（原始对话将跳过不存入，排入待处理队列）")
   .option("--recent [hours]", "快速模式：只处理最近 N 小时修改的文件（默认 2 小时），跳过 ingested-files 检查")
+  .option("--obsidian <vault-path>", "导入 Obsidian vault（自动检测 .obsidian/ 目录）")
+  .option("--connector <file-path>", "导入 connector-v1 格式 JSON 文件")
   .action(async (options) => {
     const config = loadConfig();
     const { store, embedder, llm } = createComponents(config);
@@ -1440,6 +1444,32 @@ program
       }
     }
 
+    // Obsidian vault (--obsidian <path>)
+    if (options.obsidian) {
+      console.log("🗃️  导入 Obsidian vault...");
+      const r = await ingestObsidianVault(store, embedder, options.obsidian, {
+        verbose,
+        noDedup,
+        llm: effectiveLlm,
+      });
+      results.push(r);
+      console.log(`  ✅ Obsidian: ${formatIngestSummary(r)}`);
+    }
+
+    // Connector-v1 file (--connector <path>)
+    if (options.connector) {
+      console.log("🔌 导入 connector-v1 文件...");
+      const { readFileSync: readFs } = await import("node:fs");
+      const connectorContent = readFs(options.connector, "utf-8");
+      const r = await ingestConnectorFile(store, embedder, connectorContent, {
+        verbose,
+        noDedup,
+        llm: effectiveLlm,
+      });
+      results.push(r);
+      console.log(`  ✅ Connector: ${formatIngestSummary(r)}`);
+    }
+
     // Summary
     console.log("\n📊 导入汇总:");
     let totalChunks = 0;

package/src/connector-types.ts

@@ -0,0 +1,57 @@
+/**
+ * Connector Standard Types (connector-v1)
+ *
+ * 定义外部数据源（Obsidian、Email、RSS、自定义脚本）统一产出的 JSON 格式。
+ * ingest.ts 的 ingestConnectorFile 消费这个格式，走已有的 dedup/extract/入库管线。
+ *
+ * 协议版本管理：version 字段用于未来兼容性。当前固定 "connector-v1"。
+ */
+
+export interface ConnectorOutputV1 {
+  /** 格式版本，固定 "connector-v1" */
+  version: "connector-v1";
+  /** 数据源标识，如 "obsidian", "email", "rss", "x-bookmarks" */
+  source: string;
+  /** 目标 scope，如 "vault:my-notes", "project:research" */
+  scope: string;
+  /** 批次 ID（可选，用于幂等重试） */
+  batchId?: string;
+  /** 产出时间 ISO 8601 */
+  producedAt: string;
+  /** 记录列表 */
+  records: ConnectorRecord[];
+}
+
+export interface ConnectorRecord {
+  /** 记录唯一 ID（source 内唯一，用于增量去重） */
+  id: string;
+  /** 正文 */
+  text: string;
+  /** 标题/heading（可选） */
+  title?: string;
+  /** 分类提示：preferences / events / knowledge / facts / decisions */
+  categoryHint?: string;
+  /** 重要性提示 0-1（可选，默认 0.7） */
+  importanceHint?: number;
+  /** 标签 */
+  tags?: string[];
+  /** 原始时间戳 ISO 8601 */
+  timestamp?: string;
+  /** 内容哈希（用于增量同步，调用方计算） */
+  contentHash?: string;
+  /** 来源元数据（自由字段） */
+  sourceMetadata?: Record<string, unknown>;
+}
+
+/** 运行时格式验证：判定一个 parsed JSON 是否是合法 connector-v1 */
+export function isConnectorOutputV1(value: unknown): value is ConnectorOutputV1 {
+  if (!value || typeof value !== "object") return false;
+  const obj = value as Record<string, unknown>;
+  return (
+    obj.version === "connector-v1"
+    && typeof obj.source === "string"
+    && typeof obj.scope === "string"
+    && typeof obj.producedAt === "string"
+    && Array.isArray(obj.records)
+  );
+}

package/src/conversation-importer.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import type { PersistMemoryDeps } from "./capture-engine.js";
 import { persistMemory } from "./capture-engine.js";
 import type { StoredMemoryRecord } from "./memory-schema.js";
+import { isConnectorOutputV1, type ConnectorOutputV1 } from "./connector-types.js";
 
 export interface NormalizedMessage {
   role: "user" | "assistant" | "system";
@@ -14,7 +15,8 @@ export type ConversationFormat =
   | "claude-ai"
   | "chatgpt"
   | "slack"
-  | "plaintext";
+  | "plaintext"
+  | "connector-v1";
 
 // ---------------------------------------------------------------------------
 // Format detection
@@ -40,6 +42,10 @@ export function detectFormat(content: string): ConversationFormat {
       }
 
       if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        // connector-v1: highest priority — explicit version tag
+        if (isConnectorOutputV1(parsed)) {
+          return "connector-v1";
+        }
         if (parsed.chat_conversations !== undefined) {
           return "claude-ai";
         }
@@ -366,6 +372,22 @@ export function normalizePlaintext(content: string): NormalizedMessage[] {
   return messages;
 }
 
+// ---------------------------------------------------------------------------
+// Connector-v1 normalizer
+// ---------------------------------------------------------------------------
+
+export function normalizeConnectorV1(content: string): NormalizedMessage[] {
+  const parsed: ConnectorOutputV1 = JSON.parse(content);
+  if (!isConnectorOutputV1(parsed)) {
+    throw new Error("Invalid connector-v1 format: missing version/source/scope/records");
+  }
+  return parsed.records.map((r) => ({
+    role: "user" as const,
+    content: r.title ? `[${r.title}] ${r.text}` : r.text,
+    ...(r.timestamp ? { timestamp: r.timestamp } : {}),
+  }));
+}
+
 // ---------------------------------------------------------------------------
 // Unified normalize dispatcher
 // ---------------------------------------------------------------------------
@@ -382,6 +404,8 @@ export function normalizeConversation(content: string, format: ConversationForma
       return normalizeSlack(content);
     case "plaintext":
       return normalizePlaintext(content);
+    case "connector-v1":
+      return normalizeConnectorV1(content);
   }
 }
 

package/src/data-checkup.ts

@@ -15,6 +15,7 @@
 import type { MemoryEntry, MemoryStore } from "./store.js";
 import { resolveTier, type MemoryTier } from "./decay-engine.js";
 import { measureInterferenceDensity } from "./interference-detector.js";
+import { readHeartbeats, checkSourceStaleness, formatAge } from "./source-heartbeat.js";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -151,7 +152,33 @@ function checkVersionGroups(entries: MemoryEntry[]): CheckResult {
   };
 }
 
-/** Check 6 (F2): Interference density — detect semantic clustering pressure. */
+/** Check 6 (GB-3): Source health — detect stale connector data sources. */
+function checkSourceHealth(heartbeatPath?: string): CheckResult {
+  const heartbeats = readHeartbeats(heartbeatPath);
+  const sources = Object.values(heartbeats);
+  if (sources.length === 0) {
+    return { name: "source_health", status: "ok", detail: "No connector sources tracked yet" };
+  }
+
+  const stale30 = checkSourceStaleness(30, heartbeatPath);
+  const stale7 = checkSourceStaleness(7, heartbeatPath);
+
+  const summary = sources
+    .map((s) => `${s.source}: ${formatAge(s.lastIngest)}`)
+    .join(", ");
+
+  if (stale30.length > 0) {
+    const names = stale30.map((s) => `${s.source} (${s.daysSince}d)`).join(", ");
+    return { name: "source_health", status: "error", detail: `${summary} — critically stale: ${names}` };
+  }
+  if (stale7.length > 0) {
+    const names = stale7.map((s) => `${s.source} (${s.daysSince}d)`).join(", ");
+    return { name: "source_health", status: "warning", detail: `${summary} — stale: ${names}` };
+  }
+  return { name: "source_health", status: "ok", detail: `All sources fresh: ${summary}` };
+}
+
+/** Check 7 (F2): Interference density — detect semantic clustering pressure. */
 function checkInterferenceDensity(entries: MemoryEntry[]): CheckResult {
   // Only check entries with vectors (skip schema/empty entries)
   const withVectors = entries.filter(e => e.vector && e.vector.length > 0);
@@ -192,6 +219,8 @@ function checkInterferenceDensity(entries: MemoryEntry[]): CheckResult {
 export interface CheckupDeps {
   store: Pick<MemoryStore, "list" | "stats">;
   openConflictCount: number;
+  /** Optional override path for source-heartbeat.json (used in tests). */
+  heartbeatPath?: string;
 }
 
 export async function runDataCheckup(deps: CheckupDeps): Promise<CheckupReport> {
@@ -204,6 +233,7 @@ export async function runDataCheckup(deps: CheckupDeps): Promise<CheckupReport>
       checkTierDistribution(entries),
       checkConflictBacklog(deps.openConflictCount),
       checkVersionGroups(entries),
+      checkSourceHealth(deps.heartbeatPath),
       checkInterferenceDensity(entries),
     ],
     totalEntries: entries.length,

package/src/doctor.ts

@@ -27,6 +27,7 @@ import {
 } from "./memory-schema.js";
 import { collectScopeInventory, type ScopeInventoryReport } from "./scope-inventory.js";
 import { MemoryStore, type MemoryEntry, validateStoragePath } from "./store.js";
+import { readHeartbeats, formatAge } from "./source-heartbeat.js";
 
 interface CheckResult {
   name: string;
@@ -508,6 +509,34 @@ export async function runDoctor(options: { ci?: boolean } = {}): Promise<CheckRe
     ));
   }
 
+  // GB-3: Source heartbeat summary
+  try {
+    const heartbeats = readHeartbeats();
+    const sources = Object.values(heartbeats);
+    if (sources.length === 0) {
+      results.push(pass("Source heartbeats", "no connector sources tracked yet"));
+    } else {
+      const summary = sources
+        .map((s) => `${s.source}: ${formatAge(s.lastIngest)}`)
+        .join(", ");
+      const staleCount = sources.filter((s) => {
+        const daysSince = (Date.now() - Date.parse(s.lastIngest)) / 86_400_000;
+        return daysSince > 7;
+      }).length;
+      if (staleCount > 0) {
+        results.push(warn(
+          "Source heartbeats",
+          `${summary} (${staleCount} stale >7d)`,
+          "lm ingest --connector <file>",
+        ));
+      } else {
+        results.push(pass("Source heartbeats", summary));
+      }
+    }
+  } catch {
+    results.push(warn("Source heartbeats", "unable to read heartbeat file"));
+  }
+
   return results;
 }
 

package/src/ingest.ts

@@ -15,6 +15,9 @@ import { detectLang, tokenizeFts } from "./language-hook.js";
 import type { MemoryStore, MemoryEntry } from "./store.js";
 import type { Embedder } from "./embedder.js";
 import { chunkDocument, type ChunkerConfig } from "./chunker.js";
+import type { ConnectorOutputV1, ConnectorRecord } from "./connector-types.js";
+import { isConnectorOutputV1 } from "./connector-types.js";
+import { isObsidianVault, scanVault } from "./obsidian-connector.js";
 import { segmentEvents, type EventSegmenterConfig, DEFAULT_EVENT_SEGMENTER_CONFIG } from "./event-segmenter.js";
 import { isProcessed, markProcessed } from "./tracker.js";
 import type { LLMClient, SmartExtraction } from "./llm-client.js";
@@ -1850,3 +1853,203 @@ export async function ingestGenericText(
 
   return result;
 }
+
+// ============================================================================
+// Connector-v1 Ingest (GB-2)
+// ============================================================================
+
+/**
+ * Ingest a connector-v1 formatted JSON payload.
+ *
+ * External connectors (Obsidian, Email, RSS, etc.) produce a standard
+ * ConnectorOutputV1 JSON → this function consumes it through the existing
+ * dedup / smartExtract / buildIngestedEntry pipeline.
+ *
+ * contentHash on each record enables incremental sync: if a record with the
+ * same hash is already in the store, it is skipped without embedding.
+ */
+export async function ingestConnectorFile(
+  store: MemoryStore,
+  embedder: Embedder,
+  content: string,
+  options: { verbose?: boolean; noDedup?: boolean; llm?: LLMClient | null } = {},
+): Promise<IngestResult> {
+  const parsed = JSON.parse(content);
+  if (!isConnectorOutputV1(parsed)) {
+    return {
+      source: "connector",
+      filesProcessed: 0,
+      chunksIngested: 0,
+      chunksSkipped: 0,
+      chunksDeduped: 0,
+      dedupReasonCounts: createDedupReasonCounts(),
+      errors: ["Invalid connector-v1 format: missing version/source/scope/records"],
+    };
+  }
+
+  const connectorData = parsed as ConnectorOutputV1;
+  const { source, scope, records } = connectorData;
+
+  const result: IngestResult = {
+    source: `connector:${source}`,
+    filesProcessed: 1,
+    chunksIngested: 0,
+    chunksSkipped: 0,
+    chunksDeduped: 0,
+    dedupReasonCounts: createDedupReasonCounts(),
+    errors: [],
+  };
+
+  if (records.length === 0) return result;
+
+  const batchSize = 32;
+
+  for (let i = 0; i < records.length; i += batchSize) {
+    const batch = records.slice(i, i + batchSize);
+    const texts = batch.map((r: ConnectorRecord) =>
+      r.title ? `[${r.title}] ${r.text}` : r.text,
+    );
+
+    try {
+      const vectors = await embedder.embedBatchPassage(texts);
+
+      // --- dedup pass ---
+      const dedupedTexts: string[] = [];
+      const dedupedVectors: number[][] = [];
+      const dedupedRecords: ConnectorRecord[] = [];
+
+      for (let j = 0; j < batch.length; j++) {
+        const vector = vectors[j];
+        if (!vector || vector.length === 0) {
+          result.chunksSkipped++;
+          continue;
+        }
+        if (!options.noDedup) {
+          const decision = await dedupCheck(store, vector, texts[j], options.llm);
+          recordDedupDecision(result, decision);
+          if (decision.secondaryDeletes?.length) {
+            await executeSecondaryDeletes(store, decision.secondaryDeletes);
+          }
+          if (decision.action === "skip") continue;
+        }
+        dedupedTexts.push(texts[j]);
+        dedupedVectors.push(vector);
+        dedupedRecords.push(batch[j]);
+      }
+
+      if (dedupedTexts.length === 0) continue;
+
+      // --- extract + build entries ---
+      const extractions = await smartExtractBatch(dedupedTexts, options.llm);
+      const coreSummaries = await generateCoreSummaries(dedupedTexts, options.llm);
+      const toStore: Array<{
+        text: string;
+        vector: number[];
+        category: string;
+        scope: string;
+        importance: number;
+        metadata: string;
+      }> = [];
+
+      for (let j = 0; j < dedupedTexts.length; j++) {
+        const record = dedupedRecords[j];
+        const entry = buildIngestedEntry({
+          source: `connector:${source}`,
+          scope,
+          text: dedupedTexts[j],
+          vector: dedupedVectors[j],
+          extraction: extractions[j],
+          file: record.id,
+          heading: record.title,
+          coreSummary: coreSummaries[j],
+        });
+
+        // Merge connector-specific metadata
+        const meta = JSON.parse(entry.metadata);
+        if (record.tags?.length) meta.connectorTags = record.tags;
+        if (record.contentHash) meta.contentHash = record.contentHash;
+        if (record.sourceMetadata) meta.sourceMetadata = record.sourceMetadata;
+        entry.metadata = JSON.stringify(meta);
+
+        // Respect categoryHint / importanceHint from connector
+        if (record.categoryHint) {
+          entry.category = record.categoryHint;
+        }
+        if (record.importanceHint !== undefined) {
+          entry.importance = record.importanceHint;
+        }
+
+        toStore.push(entry);
+      }
+
+      if (toStore.length > 0) {
+        await store.storeBatch(toStore);
+        result.chunksIngested += toStore.length;
+      }
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      result.errors.push(`Connector batch error: ${msg}`);
+    }
+  }
+
+  if (options.verbose) {
+    console.log(`  connector:${source}: ${records.length} records → ${result.chunksIngested} stored`);
+  }
+
+  // GB-3: Write source heartbeat after connector ingest
+  try {
+    const { writeHeartbeat } = await import("./source-heartbeat.js");
+    writeHeartbeat(source, result.chunksIngested, result.errors);
+  } catch {
+    // Heartbeat write is best-effort — don't break ingest on failure
+  }
+
+  return result;
+}
+
+// ============================================================================
+// Obsidian Vault Ingest (GB-1)
+// ============================================================================
+
+/**
+ * Scan an Obsidian vault and ingest its markdown files through the connector-v1 pipeline.
+ *
+ * Wrapper that:
+ * 1. Validates the path is an Obsidian vault (.obsidian/ exists)
+ * 2. Calls scanVault() to produce a ConnectorOutputV1 payload
+ * 3. Feeds the payload to ingestConnectorFile()
+ */
+export async function ingestObsidianVault(
+  store: MemoryStore,
+  embedder: Embedder,
+  vaultPath: string,
+  options: {
+    verbose?: boolean;
+    noDedup?: boolean;
+    llm?: LLMClient | null;
+    scopePrefix?: string;
+  } = {},
+): Promise<IngestResult> {
+  const resolved = expandHome(vaultPath);
+
+  if (!isObsidianVault(resolved)) {
+    return {
+      source: "obsidian",
+      filesProcessed: 0,
+      chunksIngested: 0,
+      chunksSkipped: 0,
+      chunksDeduped: 0,
+      dedupReasonCounts: createDedupReasonCounts(),
+      errors: [`Not an Obsidian vault (missing .obsidian/ directory): ${resolved}`],
+    };
+  }
+
+  const output = scanVault(resolved, { scopePrefix: options.scopePrefix });
+  const content = JSON.stringify(output);
+
+  if (options.verbose) {
+    console.log(`  obsidian: scanned ${output.records.length} notes from ${resolved}`);
+  }
+
+  return ingestConnectorFile(store, embedder, content, options);
+}