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

⚡ How Routing Works

When you click Analyze in the browser, NutEgg's AI reads your _index.md and determines which egg (if any) matches the content. If no existing egg matches, NutEgg offers to automatically create a new egg seeded from the page's topic!

Egg File Anatomy

Egg files use Obsidian callout blocks to instruct the AI on scope, formatting, and relevance:

---
topic: "AI Architecture & Agent Systems"
status: "active"
---

> [!abstract]- Instructions:
> **Scope:** Multi-agent architectures, tool calling, memory layers, and LLM evaluation.
> **Action Guide:** Focus on actionable design patterns and real failure modes.
> **Key Questions:** How are agent loops bounded? What memory buffers are used?
> **Rejection Criteria:** Discard generic beginner tutorials or high-level sales pitches.

# Knowledge
## Agent Memory
- Bounded replay buffers are required to prevent token window overflow.
    - Ephemeral short-term memory expires after session goals terminate.

# Unprocessed
(Newly hatched entries accumulate here until auto-merged)

Auto-Merging Knowledge

When you click 🥚 Hatch Egg, incoming insights are appended to the egg's # Unprocessed section. Once 20 or more entries accumulate, NutEgg's AI runs an automated background synthesis that reorganizes and nests those entries into your main # Knowledge branch tree, keeping your notes clean and scalable.