Skip to content

vouch import-md: markdown-folder importer (first slice of #612) #744

Description

@galuis116

What you're trying to do

#612 asks for note-vault importers (Obsidian, Joplin, Notes/Keep, plain
markdown folders) behind a unified vouch import <kind> surface — a big,
multi-format track the issue itself flags as having real open questions
("scale is the real question... a triage view over 'everything from this
import' is probably a precondition"). This is a first, narrow slice: just
the plain-markdown-folder case, landed as its own command rather than
waiting on the full multi-format surface design.

People arrive with years of notes already written; a fresh KB has nothing
to say to them until someone does enough work in it by hand.

What you've tried

  • vouch ingest <file> — works per-file, no folder walk, no idempotent
    re-run tracking.
  • The inbox folder drop — registers and proposes per file, but dropping a
    large vault into it isn't a migration story (no recursive walk, no
    content-hash dedup across re-runs).
  • vouch import-chatgpt — the closest existing shape to copy: a folder/
    export walked once, filed as review-gated proposals, safe to re-run.

Suggested shape

vouch import-md <folder> (flat command, matching the existing
import-chatgpt naming convention rather than introducing a new vouch import <kind> subcommand group unilaterally — that grouping question
belongs to #612 as a whole, once the other formats it names are ready to
land alongside it):

  • Recursively walks folder for *.md files; each becomes a source via
    the existing extract.ingest_source (the same mechanical ingest vouch ingest runs on one file), receipt-backed claims filed and auto-approved
    under the existing review.auto_approve_on_receipt gate.
  • Re-running is idempotent for unchanged files: a per-file content
    hash is tracked in .vouch/, so re-running against the same vault next
    week is a no-op for anything that hasn't changed.
  • An edited file is fully re-ingested — this is a real, documented
    limitation rather than a silent gap: ingest_source has no way to diff
    against what a prior version of the same file already contributed, so a
    changed note files a fresh batch of claims for its current content, on
    top of what's already there. True claim-level diffing is a harder
    problem the full feat(import): note-vault importers — obsidian, joplin, notes, keep, markdown folders #612 track can take on later.
  • --max-claims/--budget-chars reuse the existing density-selection
    knobs so a large vault doesn't produce ten thousand pending claims.
  • Everything lands PENDING (or durable-via-receipt, same as vouch ingest) — an import is a proposal firehose, never a bypass.

Compatibility considerations

Purely additive: one new CLI command, one new module, no kb.* method (an
import is a deliberate human action, same reasoning as kb.import_apply
staying CLI-only), no on-disk shape change beyond a new
.vouch/md_import_state.json bookkeeping file. No VEP.

Alternatives

Waiting for #612's full multi-format surface to land as one PR — rejected
for the same reason splitting big work usually wins: markdown-folder
import stands alone as a complete, useful slice (many vaults, including
exported Obsidian ones with wikilinks stripped, are already plain
markdown folders), and doesn't need Joplin/Notes/Keep-specific parsing to
be worth shipping.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions