From 3be167cc15f981f84b7b00996ba3f92ae99fdeba Mon Sep 17 00:00:00 2001 From: axAilotl Date: Tue, 4 Aug 2026 14:04:01 -0400 Subject: [PATCH] Document the universal loop in README and project overview Describe the capture -> compile -> query -> feed-back cycle that makes the wiki compound: wiki-query --write-back curated pages, archivist recompiles on input-manifest changes, digests resurfacing unread material. --- README.md | 11 +++++++++++ docs/project_overview.md | 11 +++++++++++ 2 files changed, 22 insertions(+) diff --git a/README.md b/README.md index 16d8afd..c176d19 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,17 @@ Topic-scoped compilation over selected source folders, types, tags, and terms. 3. Analyst / Agent Higher-cost interactive work over the compiled layer for synthesis, comparison, and refinement. +### The Universal Loop + +The layers are not a one-way pipeline — they form a loop that compounds: + +1. **Capture** — bookmarks, papers, clippings, and transcripts flow in raw. +2. **Compile** — processors and the archivist turn them into cited wiki pages. +3. **Query** — you and agents read the compiled layer. +4. **Feed back** — `wiki-query --write-back` persists curated query results as new wiki pages, the archivist recompiles topics when their input manifest changes, and digests resurface unread material — which drives the next round of capture. + +Each pass makes the wiki a better source for the next one, without raw material ever being rewritten. + ## Quick Start ### Setup diff --git a/docs/project_overview.md b/docs/project_overview.md index 8cec263..feba9b7 100644 --- a/docs/project_overview.md +++ b/docs/project_overview.md @@ -29,6 +29,17 @@ The problem it solves is not capture — it's that captured knowledge rots. Book 2. **Processing** — `core/ingestion_runtime.py` dispatches queued artifacts to `processors/`: tweet/thread enrichment, document processing (papers, PDFs, READMEs), transcription (Whisper/Deepgram), and LLM tasks (tags, summaries, alt-text, translation) via a routed multi-provider `LLMInterface` with caching. 3. **Archivist / Analyst** — Topic-scoped compilation: `archivist_retrieval/` selects sources via full-text + pgvector semantic search, the compiler synthesizes cited wiki pages, and agents query the result through `AgentSurfaceService` (API + MCP). +## The Universal Loop + +The layers are not a one-way pipeline — they form a loop that compounds: + +1. **Capture** — bookmarks, papers, clippings, and transcripts flow in raw. +2. **Compile** — processors and the archivist turn them into cited wiki pages. +3. **Query** — you and agents read the compiled layer. +4. **Feed back** — `wiki-query --write-back` persists curated query results as new wiki pages, the archivist recompiles topics when their input manifest changes (`core/wiki_change_provenance.py`), and digests resurface unread material — which drives the next round of capture. + +Each pass makes the wiki a better source for the next one, without raw material ever being rewritten. + ## Storage contract (the core design rule) - `knowledge_vault/` — synced vault: raw + generated artifacts (`tweets/`, `threads/`, `library/`, `pdfs/`, `repos/`, `transcripts/`, `media/`, `_digests/`).