Knowledge Structuring & Eggs

Learn how NutEgg organizes your Obsidian vault, matches web content to topics using _index.md, and merges accumulated entries into knowledge trees.

The nutegg/ Vault Layout

All NutEgg content is confined to a clean, isolated nutegg/ folder in your Obsidian vault:

vault/
└── nutegg/
    ├── _raw/                          # Captured nuts (raw web content + metadata)
    │   └── 2026-09-06-14-30-youtube-author-title.md
    ├── _index.md                      # Topic routing guide
    ├── ai_architecture.md             # Knowledge egg
    ├── invest_strategy.md             # Knowledge egg
    └── productivity.md                # Knowledge egg

The Routing Guide: _index.md

The _index.md file tells NutEgg which egg notes you maintain and what domains they cover. Each line maps a relative file path to keywords and descriptions:

nutegg/ai_architecture.md: LLMs, multi-agent systems, prompt engineering, RAG, embeddings
nutegg/invest_strategy.md: value investing, index funds, asset allocation, macroeconomic indicators
nutegg/productivity.md: deep work, time blocking, habits, personal knowledge management

Egg File Anatomy & How Instructions Work

An Egg file (stored under nutegg/*.md) serves two crucial roles: it is both your curated, evolving knowledge repository for a domain and an active prompt specification that steers NutEgg's AI pipeline whenever content touches that topic.

1. Structural Blueprint

Every egg file combines YAML metadata, an Obsidian callout block with instructions, a curated knowledge tree, and an unprocessed staging buffer:

---
topic: "AI Architecture & Multi-Agent Systems"
status: "active"
last_updated: "2026-09-10"
---

> [!abstract]- Instructions:
> **Scope:** Multi-agent architectures, tool calling, memory layers, and LLM evaluation.
> **Action Guide:** Focus on actionable design patterns, scalability tradeoffs, and real failure modes.
> **Key Questions:**
> 1. How are agent memory loops bounded to prevent context window overflow?
> 2. What coordination mechanism is used between subagents?
> **Worth Reading If:**
> - Practical examples and substantive explanations.
> **Skip If:**
> - Ignore basic beginner tutorials or high-level sales pitches without technical substance.
> - Discard speculative claims lacking empirical benchmarks or code evidence.
> **Formatting Rules:**
> - Prefix each insight with a bracketed tag: `[concept]`, `[architecture]`, `[method]`, `[benchmark]`, `[explain]`, `[fact]`, `[example]`.
> - Use the structure: `- [tag] **Concept Name**` followed by an indented explanation and concrete examples (`- 🎯 Example:`).

# Knowledge
## Agent Memory
- [architecture] **Bounded Replay Buffers**
    - Ephemeral short-term memory expires after session goals terminate to conserve token budget.
    - 🎯 Example: Tool calling trace logs stored in vector stores with sliding window eviction.

# Unprocessed
(Newly hatched insights land here from captures until auto-merged)

2. How to Write Egg Instructions

The > [!abstract]- Instructions: callout contains six specialized fields. Each one guides a specific stage of the AI pipeline:

3. Curated Knowledge Tree vs. Unprocessed Queue

NutEgg protects your knowledge base from AI pollution by separating curated knowledge from new captures:

• # Knowledge (Curated Tree): Structured with markdown headings and nested bullet points. Only merge reads this tree, consolidating equivalent claims while preserving distinct examples, caveats, disagreements, and sources. Stage 2 follows instructions without comparing against the tree.
• # Unprocessed (Staging Queue): When you click 🥚 Hatch Egg in the browser, approved entries and supported answers are safely appended to # Unprocessed rather than directly touching your curated hierarchy.

4. How Each Part is Used in the Workflow

Here is how web content flows through your egg instructions from initial capture to final synthesis:

[Captured Web Content]
          │
Stage 1   ▼   _index.md (Topic routing guide)
─────────────────────────────────────────────────────────────
• Uses content-task-default.md
• Generates Title Verdict, 3-Bullet Summary, Mind Map
• egg-routing.md matches target eggs via Stage 1 summary
          │
          ▼
User Review: Confirm or select target eggs in popup
          │
Stage 2   ▼   Target Egg File (nutegg/*.md)
─────────────────────────────────────────────────────────────
• Scope, Key Questions, Formatting Rules ──► egg-analysis.md
  (Extracts candidate knowledge entries and answers questions)
• Worth Reading If / Skip If guide the reading recommendation
  (Full, highlights, summary, skip, or uncertain; no tree comparison)
          │
          ▼
Hatch Egg: Approved entries and supported answers appended to # Unprocessed
          │
Merge Cycle (20+ entries or manual button)
─────────────────────────────────────────────────────────────
• merge-unprocessed.md nests and integrates entries into # Knowledge

Auto-Merging Knowledge

When 20 or more entries accumulate in # Unprocessed (or when you click Merge in the Obsidian reading view widget), NutEgg's AI runs an automated background synthesis using merge-unprocessed.md. It categorizes, deduplicates, and nests pending entries under the appropriate parent concepts in # Knowledge, keeping your knowledge graph perpetually organized.