homefoam/AGENTS.md

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.