Ingest: How to organise a project's knowledge for AI coding agent and an engineer

Type: types/ingest-report.md

Classification

This is a practitioner report in the form of a design guide. The author says it is how they run project knowledge bases on consulting projects. It gives a complete folder layout, workflows and a decision guide. It reports no outcomes from the author's own use: no project counts, failure cases or measurements. All quantitative support is relayed from cited papers and vendor posts. Most of these are 2026 arXiv preprints that the KB has not ingested. Author: @sermakarevich, an X account with no prior ingest in this KB. The thread is long and structured, which signals a considered practice. The credibility signal is the coherence of the design, not an established track record.

Summary

The source describes one Markdown tree per project with three folders that are never mixed. raw holds sources as captured, facts holds the same sources made readable, and artifacts holds everything a model wrote. A fact is one chunk that ends at a complete thought. It stores the original span word for word beside a self-standing rewrite with resolved references and transcribed tables, at the same information density. Artifacts come in three kinds. Summaries live in generated per-folder indexes: chunk, then source, then project. Views are a digest, a user view, a developer view and on-request feature views. Specs are written from a view when an engineer decides a feature is to be implemented. Every artifact statement cites a fact, and these links are the only dependency record. Two guardrails check each page as it is written. A script checks that links resolve, then one model call checks that the page says nothing its linked facts do not say. The update step works as follows. When a refetched source's hash changes, its facts are re-sliced and replaced. A script then walks the links backward and rewrites every dependent, nearest first, in the same run. It stops early when a rebuilt page "means the same", using an exact-text match followed by a classifier, and it re-checks each hop. Retrieval is progressive disclosure through the indexes. BM25, embeddings and a graph are added only after logged misses. The root index sits in the harness's always-loaded instruction file. People read top-down or bottom-up, and the design states that "the summary is a map" and a reading path must end at the chunk. The quantitative support is relayed, not reproduced. Examples: rebuilding by recorded inputs against checking by age (Planfence), per-stage gates against a final check, and ClashEval's finding that models adopt wrong retrieved passages.

Quotes

No source quotes have been retained yet.

Connections Found

For the occasion, the source serves as the derivation-only special case of a canvas that Commonplace already spans. Both systems record lineage and check claims against their support. They differ in which kinds of claim they admit. Commitment, not derivation, creates new ground truth draws the first boundary. A derived artifact's claims are recoverable from its source, so the source stays ground truth and re-derivation is the repair. A committed artifact adds content the source does not determine and becomes ground truth for that addition. Superseded choices need a historical witness; refuted beliefs lose subject-matter standing splits the commitment side in two. A residual choice leaves a true event-fact ("the system committed to X at t") and is superseded. An ampliative conjecture remains a belief, and when it is refuted the current text is rewritten. Claim modality is the inference form of the refuter supplies the refutation logic for that conjecture side, including comparative abduction. The source occupies only the derivation row. Its guardrail 2 ("a page must say nothing that the facts it links to do not say") is an admission test for the judgment-checked derivation zone. Automatic rewrite on source change is what commitment-not-derivation prescribes for that zone.

Commonplace's lineage layer corresponds to the source's fact layer. Ingests are tracked analyses of checksum-pinned snapshots, and retained quotes keep exact source wording with a snapshot checksum and an optional line range. Its support checks differ from guardrail 2 in kind. The semantic/grounding-alignment gate asks whether a cited passage supports the claim it is cited for. The semantic/unwarranted-scope gate asks whether a central claim invites reliance beyond the cases its support exercises. It accepts the surplus when the note argues a transfer relation or marks the surplus as conjecture. Guardrail 2 forbids any surplus. The two systems therefore share containment checking; they differ on whether an argued or labelled excess is legitimate. The source has one misfiling under this framing. Its specs fix "what is required to be delivered" by the engineer's decision, which is commitment content, yet they are put under the same automatic rewrite walk as views.

On lineage mechanics, the source is a worked instance of the artifact-side option in source changes should surface downstream review targets. It combines artifact-side links, a script-derived reverse map and a hash-triggered change surface. Unlike that note's review worklist, it takes the human out of the loop entirely. It extends link graph plus timestamps enables make-like staleness detection in three ways: it keys on content hash rather than timestamp, it rewrites rather than re-reads and decides, and it answers that note's false-positive problem with a same-meaning early-cutoff rule. In the terms of Build Systems à la Carte, the rebuilder uses verifying traces keyed on source hashes, with a probabilistic rather than exact early cutoff. Criteria edits invalidate verdicts; process edits invalidate artifacts exposes a gap in the source's rebuild key. Changing the slicing, rewrite or view prompts triggers no rebuild, so artifacts made by a superseded method stay "fresh". Freshness architecture is the shipped Commonplace counterpart. It keys freshness on accepted inputs and states that freshness says nothing about truth, while the source merges freshness and rewrite into one step.

On reading and retrieval, the claim that "the summary is a map" reaches the structural rule of an insufficient summary precedes the source rather than replacing it from learning evidence rather than read-cost accounting. The relayed He et al. result is a candidate data point for indexes lower recall when they suppress retrieval that would find more: misleading group summaries stranded the agent, and a keyword search across all indexes was the repair. Against the Karpathy LLM wiki, the source keeps the raw/compiled split and index files. It adds a verbatim-span fact layer, statement-level citations, dependency-driven rewrite and specs.

Extractable Value

1. The occasion's answer: the quoted chain is sound for compiling sources and silent about new knowledge. The design is a compiled, readable view over client documents, with lineage back to them. It is more than an index, because it rewrites chunks and combines facts into pages, so it can distort what it compiles. It guards that step well. Each rewrite sits next to its original span, every statement cites a fact, and per-page checks run as the page is written. All of these make derived claims intersubjectively testable. Its epistemology is justificationist, though. A page is licensed only by what its facts already say, so the design has no place for decisions, explanations, generalizations or criticism of the sources. Source authority is a convention it adopts, not something it can test. Within faithful compilation of documents that are authoritative by contract, this is sound error control. As a general method for knowledge growth it is incomplete. [deep-dive]
2. One canvas: three kinds of claim, each with its own maintenance response. The existing notes already state the split; the source adds an external pole for its first row.

A commitment, once recorded, is a primary record, so the source's pipeline could consume it as a raw document. It could not author one. An abductive conjecture is outside the pipeline altogether. Commonplace is more general because it admits all three rows. The unwarranted-scope gate is where the first and third rows meet. [deep-dive] 3. A worked misfiling: specs under automatic rewrite. The engineer decides what is delivered, so a spec's content is not fully recoverable from facts. Rewriting it automatically can erase a decision silently while guardrail 2 still passes, because the decision is "not in the facts". This is a practitioner instance of the failure that commitment-not-derivation predicts. It also bears on changing requirements conflate genuine change with disambiguation: a hash walk propagates a corrected interpretation as if it were a world change. [quick-win] 4. Commonplace limitation: generality costs automation. Only the derived row can be maintained mechanically. Committed choices and conjectures need judgment on every relevant change. The source's fully automatic maintenance is available to it because it admits only derivation. [just-a-reference] 5. Commonplace limitation: lineage triggers are incomplete for conjectures. A conjecture can be refuted by evidence that touches none of its cited sources, or it can lose to a better rival explanation. No lineage-driven staleness check fires in either case. Commonplace has no systematic search for refuting evidence outside a note's citations. Detection relies on new ingests and connect passes happening to link back. No theory note states this consequence; freshness architecture states only that freshness says nothing about truth. [deep-dive] 6. Commonplace limitation: support verdicts do not go stale when the support changes. A review pair's freshness has exactly two inputs, the note and the criterion, and no third dependency is registered (freshness architecture). A grounding-alignment pass on a note stays fresh after the cited note or ingest is rewritten. The source re-checks every dependent page on each upstream change. Registering cited artifacts as review inputs would close this gap for support gates. [experiment] 7. Commonplace limitation: support checks run after writing, in review sweeps. The semantic gates run when a reviewer selects stale or unreviewed pairs, not when the note is written. A broken support link can persist until the next sweep. The source checks every page as it is produced. [just-a-reference] 8. Commonplace limitation: grounding is selective, not per statement. A retained quote is exact and uniquely locatable: it must occur once in the checksum-pinned snapshot, and it may carry a line range. Quotes are retained only for claims that need source grounding, however, and notes usually cite an ingest or another note rather than a quoted passage. The source gives every artifact statement a pointer to a fact. Commonplace's grounding is equally precise where it exists but covers far fewer claims. [just-a-reference] 9. Commonplace limitation: the derivation/commitment boundary is declared, not detected. Commitment-not-derivation leaves open whether anything checkable distinguishes the relations. Nothing catches a commitment misfiled as a derivation until its first silent mismatch. The source's spec misfiling is the external instance; Commonplace's own lineage vocabulary relies on the same declared labels. [just-a-reference] 10. Gaps in the rebuild key are themselves epistemic gaps. Rebuilds key on source hashes only. Changes to prompts or slicing method, the classifier's "same meaning" judgment, and conflicts between two sources' facts all fall outside it. In each case a page can be "in step with its source" and still wrong. This is a concrete test case for the process-edit note. [quick-win] 11. Same-meaning early cutoff as a concrete stop rule for semantic rebuilds. An exact-text match comes first for free, then a cheap yes/no classifier. If the rebuilt page means the same, propagation upward stops. This answers the false-positive cost of make-like staleness in natural-language KBs, and it applies only to the derived row. It is a candidate refinement for the link-graph staleness note, but the cutoff is fallible, and a false "same" silently stops propagation. [experiment] 12. Facts replaced in place against pinned observations. A changed Commonplace source is a new observation under a new basename. Here, refetching replaces facts in place and leaves history to version control, so an artifact's citation points to "the current fact" rather than a pinned observation. [just-a-reference] 13. Relayed design evidence worth checking at the primary papers. Relayed results include: rebuilding by recorded inputs against checking by age, 30 of 30 against 0 (Planfence); per-stage gates against a final check (Hallucination Snowball); a condensed rewrite losing answers (Filesystem-Based Memory); misleading routing summaries stranding the agent (He et al.); and an always-loaded index against an uninvoked skill (Vercel). These are relevant to freshness, gating and loading notes, but only as second-hand pointers until the papers are ingested. [just-a-reference]

Limitations (our opinion)

What is not visible is the design's track record. The author presents a complete architecture with no report of its own runs. There are no counts of projects, rewrite failures, guardrail false passes, or cases where the same-meaning cutoff was wrong. Survivorship and design-as-ideal bias are likely, because the text describes how the system should behave, not how it did. Every figure is relayed. Many come from 2026 preprints the KB has not ingested, and the snapshot does not show whether the cited setups match this design. For example, Planfence tests plan currency in multi-agent memory, not wiki-page rewriting. Treat the numbers as pointers to primary papers, not as evidence for KB notes.

The central claim, that the store "never holds" an outdated page, holds only relative to the rebuild key. The key omits production-process changes and treats the semantic cutoff and guardrail 2 as reliable, although both are model judgments. The design does not say what happens when two sources' facts conflict, when a source is wrong, or when the engineer's decisions in a spec diverge from a rewritten view. It also assumes client documents are authoritative. That is reasonable on a consulting project, but it does not transfer to its own "research variant", where papers disagree and supersede each other. There the design shrinks to a disagreements view written on request. Its value as a methodology for knowledge growth is therefore bounded to compiling sources whose authority is settled by convention.

Recommended Next Action

Write a theory note in kb/theory/ claiming that lineage-driven staleness cannot detect the refutation of a conjecture, because refuting evidence need not touch any cited source. Ground it in superseded choices need a historical witness; refuted beliefs lose subject-matter standing and claim modality is the inference form of the refuter. Contrast it with link graph plus timestamps enables make-like staleness detection, and cite this ingest as the derivation-only pole where that detection is complete. Before writing, confirm that the link-graph note and freshness architecture do not already state the claim.