Ben
50 lines
3.6 KiB
Markdown
50 lines
3.6 KiB
Markdown
# Homefoam Wiki Architecture & Automation Rules
|
|
|
|
This vault is a shared cognitive workspace for both human and agent. It is maintained by background LLM orchestration and semantic indexing, utilizing the QMD search engine.
|
|
|
|
## 1. Vault Organization
|
|
The vault uses a hybrid hierarchy. Do not create folders with numeric prefixes if they don't already exist unless listed below.
|
|
- `00-inbox/` - Unprocessed human notes.
|
|
- `00-inbox/agent/` - Raw, timestamped agent insights (memory store).
|
|
- `01-journal/` - Daily notes and chronologies.
|
|
- `02-projects/` - Active projects.
|
|
- `03-areas/` - Life and maintenance areas.
|
|
- `04-knowledge/topics/` - Canonical topic pages.
|
|
- `04-knowledge/entities/` - Canonical entity pages (people, organizations, etc).
|
|
- `04-knowledge/synthesis/` - Cross-topic conclusions and multi-source answers.
|
|
- `04-knowledge/hypotheses/` - Speculative connections generated by the Dreaming Cycle.
|
|
- `05-sources/` - External ingested materials, packaged as `sources/<slug>-<hash>/`.
|
|
- `system/` - System records, rules (this file), claim ledgers, and run logs.
|
|
|
|
## 2. Memory & Cognitive Cycles
|
|
- **Store**: Agents must write new insights as timestamped markdown files in `00-inbox/agent/`. Do not bypass the inbox to write unstructured facts directly into canonical pages.
|
|
- **Recall/Reflect**: Use standard file reads and QMD CLI/MCP tools.
|
|
- **Distillation Cycle (Nightly 03:30)**:
|
|
1. Process `00-inbox/` (human and agent) into formal claims.
|
|
2. Compact and deduplicate the existing claim graph.
|
|
3. Re-evaluate dependent claims for modified sources.
|
|
- **Dreaming Cycle (Weekly)**: Traverse the QMD graph, synthesize non-obvious connections, and write speculative notes to `04-knowledge/hypotheses/`.
|
|
|
|
## 3. Evidence & Formal Claims
|
|
- **Location**: Per-page Markdown sidecars in `system/claims/`.
|
|
- **Identity**: Globally stable, opaque IDs (e.g., `clm-a1b2c3`).
|
|
- **Locators**: Exact locators (headings, line numbers, timestamps) are required.
|
|
- **Authored Notes**: For notes the human authors directly, cite the Git path and baseline commit (e.g., `path/to/note.md@commit`). Do not duplicate human notes into `05-sources/`.
|
|
- **Status Lifecycle**: `supported`, `inferred`, `conflicted`, `superseded`, `retracted`.
|
|
- **Confidence**: `high`, `medium`, `low`.
|
|
- **Contradictions**: Preserved as `conflicted`; the agent must not silently force a winner.
|
|
|
|
## 4. Editing Rules & Automation Guardrails
|
|
- **Privacy (.wikiignore)**: Paths in `.wikiignore` are strictly excluded from remote LLM/web processing.
|
|
- **Protected Markers**:
|
|
- `<!-- wiki:private:start -->` ... `<!-- wiki:private:end -->` : Content inside is never sent to the LLM or indexed.
|
|
- `<!-- wiki:protected:start -->` ... `<!-- wiki:protected:end -->` : Content inside may be read/indexed, but the agent must never rewrite it.
|
|
- **Rewrite Authority**: The agent may freely rewrite semantic content in eligible Markdown notes (unless protected). It must never overwrite, move, or delete raw source binaries, assets, attachments, or editor config files.
|
|
- **Failures & Recovery**: Operational failures (network, locks) can be retried. Semantic/content conflicts during automated sync must halt the job and leave `main` untouched; never attempt to force a Git conflict resolution on knowledge content.
|
|
|
|
## 5. QMD Search
|
|
- **Corpus**: Knowledge, sources, extracted text, and claim sidecars. (Exclude `system/runs`, `system/migration`, and raw binaries).
|
|
- **Tooling**: CLI and Stdio MCP.
|
|
- **Artifacts**: QMD config is committed. SQLite indexes and model caches must remain untracked.
|
|
- **Index Refresh**: Only run after a successful batch that actually altered indexable content.
|