witt3rd/zk-memory/ingest

ingest — agent-study cycle

Z13: the library never authors the thought. You do. Repo AGENTS.md (Ingest + CLI) is the mechanism. Authoring/maintenance skills in this folder are how a note is shaped and how the tree is kept.

This cycle was proven on a large docs tree (2026-08). The sequence is the reusable part; the product names are not.

Gotchas

• `--embed-model` is a parent flag — before the subcommand, or

argparse rejects it.

• `ingest start` replaces `job.json`. Cursors for earlier docs

remain under .zk/ingest/docs/; status shows the current job.

• Doc id is the relative-path slug. Two AGENTS.md files smash.

Glob a unique file (--from principles --glob vision.md).

• Heading-id skip loops miss. Unit ids are truncated headings, not

Decision. If a glob-skip eats the only load-bearing window, write / merge by hand and say so.

• Search over-ranks the identity note. Don't --merge into it

because it ranked first. Merge into the thought.

• Vector recall is not `--backend faiss`. Parent --embed-model

(plus base/key or ZK_MEMORY_EMBED_*) builds hybrid search. Pin: <root>/.zk/index/vector/meta.json. Wrong model/dims → EmbedderMismatch unless --rebuild-index.

• Sources whose path contains a `.`-component are skipped

(.meta/). Write those by hand.

Cycle

isolate → chart → one file → next / accept|skip → pin search → commit

Isolate. Empty --root. Sources stay in --from. Sidecar and .archive/ stay inside the root.

Chart. Write <sources>/.zk_audit.md (do not ingest it). Order top-down: orientation → what we are → who we work with → thesis → shape → spine → modules → surfaces → ops. Skip archive, generated status, uncited piles. Who the notes are for changes the chart (people in the room are not optional if the corpus is a being's).

One file per wave.

zk-memory --root <zk> ingest start --from <dir> --glob <unique-file>
zk-memory --root <zk> ingest next
zk-memory --root <zk> ingest accept --doc … --unit … --title … --body …
# or: ingest skip --doc … --unit … --reason …

--keep for another thought in the same window. --merge UUID only for entity_update. decision never merges. Do not start the whole tree.

Write. Own words, one thought. Past writes change later writes — that is the cycle. Patterns:

Library merit remains prefer create on the careful-write path. Ingest entity_update is the named exception.

Pin after the wave. One hybrid search rebuilds unchanged+new vectors. Mid-wave you may use remembered UUIDs if you are sure.

Commit the corpus dir (notes ± sidecar, per that corpus's policy). Don't sweep unrelated dirty files.

Don't

• Don't let retain draft an ingest body.
• Don't start two files that slug to the same doc id.
• Don't rebuild the vector pin with a different embedder.
• Don't ingest the chart file, archive, or generated status.