design.md

Mycelium — Design Document

Problem

Personal knowledge is broken at the retrieval end, not the capture end.

People save articles, take screenshots, bookmark links, and write notes constantly. The tooling for capture is abundant — browsers, notes apps, read-later lists. The problem is that nothing brings it back. Saved things become graveyards. The forgetting curve wins. When bored, the path of least resistance is algorithmic feeds that optimise for engagement, not for your actual interests.

The result: you know less than you've learned, you act on less than you've saved, and your attention is rented to platforms rather than invested in yourself.

Three specific failures:

1. Scattered capture — text in Keep, links in Pocket, screenshots in Camera Roll, long-form in Obsidian. No single place, no unified signal.
2. No recall — nothing surfaces saved content at the right time, in the right mood, with the right context.
3. No connections — two related ideas captured months apart never meet. Patterns in your own knowledge are invisible.

---

Solution

Mycelium is a local-first personal knowledge agent. Like mycelium — the underground fungal network that connects trees and surfaces nutrients where they're needed — it sits beneath your daily attention, quietly connecting what you've captured and surfacing it back when it matters.

Core loop:

Capture → Enrich → Store → Connect → Surface → Feedback → (back to Enrich)

It is not a notes app. It does not replace Obsidian or Keep. It is the active layer on top — the thing that reads what you've saved and decides what to do with it.

Design principles:

• Local-first. Your knowledge stays on your machine.
• Capture everything, surface selectively.
• Bad enrichment is worse than no enrichment — quality gates matter.
• The system should get smarter from use, not just from configuration.

---

Architecture

flowchart TD
    subgraph Input
        A1[Text / Note]
        A2[Link / URL]
        A3[Screenshot / Image]
        A4[Import\nObsidian · Keep · Notion]
    end

    subgraph Capture
        B[Capture Layer\nreceives + deduplicates]
    end

    subgraph Enrichment
        C0[Pre-filter\ndedup · length · language]
        C2[Summary]
        C3[Concepts]
        C4[Labels]
        C5[Intent]
        C6[Embeddings]
        C7[Post-filter\nquality gate]
    end

    subgraph Storage
        D1[(SQLite\nmetadata · enrichment · events)]
        D2[/filesystem\ncontent · images/]
    end

    subgraph Connections
        E[Semantic Similarity\nfind related captures]
    end

    subgraph Surface
        F[Surface Engine\npick right item · right time]
        F1[Spaced Repetition]
        F2[Daily Brief]
        F3[Digest]
        F4[Export]
    end

    subgraph Feedback
        G[Signal Layer\nexplicit + implicit]
    end

    CTX[Context\ntime · mood · activity]
    LCM[Lifecycle Management\narchival · decay · graduation]

    A1 & A2 & A3 & A4 --> B
    CTX --> B
    B --> C0 --> C2 --> C3 --> C4 --> C5 --> C6 --> C7
    C7 --> D1
    C7 --> D2
    D1 --> E
    E --> D1
    D1 --> LCM
    LCM --> D1
    D1 & E --> F
    CTX --> F
    F --> F1 & F2 & F3 & F4
    F --> G
    G --> F
    G -.->|re-enrichment trigger| C5

---

Components

Capture

Responsibility: Receive raw input across modalities. Store original material to filesystem immediately.
Inputs: Text, URL, image file, import batch
Outputs: Raw capture record + original material stored to filesystem
Failure mode: Duplicate captures inflate the KB; noisy captures degrade enrichment quality
Key decision: Capture is permissive — let everything in. Filtration happens in Enrichment, not here.

---

Extraction & Enrichment

Responsibility: Transform raw captures into structured knowledge. The most critical component — bad output here corrupts everything downstream.

Two-stage filtration wraps enrichment:

Stage 1 — Pre-filter (no LLM, cheap):

• Dedup fingerprint check (URL hash + content hash + embedding similarity)
• Minimum length / language check
• Obvious spam rejection

Stage 2 — Enrichment (LLM):

Sub-component	What it produces	Failure mode
Summary	1-2 sentence distillation	Too generic → useless for search and connections
Concepts	Abstract ideas that span captures	Hallucination; derive from clustering, not per-capture generation
Labels	Broad user-visible categories	Model drift from user's own taxonomy
Intent	learn / act / reference / ephemeral	Wrong classification = item permanently misrouted
Embeddings	Semantic vector (model-versioned)	Incompatible across model changes

Stage 3 — Post-filter (quality gate):

• Reject if summary is empty or generic
• Reject if intent confidence is below threshold
• Flag for manual review rather than silent drop

Intent is the most consequential field. A learn item classified as ephemeral is gone. Must be correctable.

---

Storage

Responsibility: Single source of truth. Persist everything.

SQLite (mind.db)
├── captures     metadata, enrichment fields, lifecycle state
├── events       append-only signal log (surfaced, skipped, done, dwell)
└── concepts     concept vocabulary table (grows from tag clustering)

filesystem (storage/)
├── content/     {capture_id}.txt  — page text, OCR output
└── images/      {capture_id}.ext  — managed image files

Key decisions:

• SQLite for structured data and query flexibility; filesystem for raw material. No DB blobs.
• Concepts get their own table — not a JSON field — to enable querying.
• Orphan prevention: capture deletion must clean both DB and filesystem.
• raw text is not stored in DB for links/images — content_path points to filesystem.

---

Connections

Responsibility: Find semantic relationships between captures using embedding similarity.
Inputs: New capture embedding + all existing embeddings
Outputs: related_ids list stored on each capture
Failure mode: Surface-level similarity without conceptual link (false connections); vocabulary mismatch misses real connections
Scale limit: Per-pair cosine scan degrades beyond ~1000 captures → migrate to sqlite-vec at that point.

---

Context

Responsibility: Provide situational signal to Capture and Surface.
Signals: Time of day, day of week, self-reported mood (optional dropdown)
Used by: Surface (pick mood-appropriate items); Capture (timestamp context stored with capture)
Mood capture: Optional dropdown in UI — no selection = no context signal. Time-of-day inferred automatically.

---

Surface

Responsibility: Pick the right item at the right time and deliver it.

Scoring inputs: intent weight · time since last surfaced · novelty · context · feedback history
Outputs:

Mode	What it does
Spaced Repetition	learn items resurface at growing intervals
Daily Brief	Morning digest of act items + one learn
Digest	Weekly summary of what was captured and what's aging
Export	Push to Obsidian / markdown file

Invariant: Surface must never return empty. If all items are below threshold, return best available.

---

Feedback / Signal

Responsibility: Capture user behaviour and propagate it back into the system.

Explicit signals:

• done — item completed or learned
• skip — not now
• correct — user overrides intent/summary

Implicit signals:

Signal	Threshold	Action
Dwell time < 2s + skip	—	Wrong item entirely
Dwell time > 15s + skip	—	Right content, wrong time
Skip streak	3×	Trigger intent re-evaluation
Done on first surface	—	May have been wrong act; flag

Storage: Raw events in events table. Aggregates computed on read.
Re-enrichment: Skip streak ≥ 3 → re-run intent classification with behavioural context appended to prompt.

---

Lifecycle Management

Responsibility: Manage how captures age, graduate, and retire.

stateDiagram-v2
    [*] --> Active : captured
    Active --> Active : surfaced
    Active --> Done : marked done
    Active --> Archived : decayed / manually archived
    Done --> Archived : after retention period
    Archived --> [*]

Decay rules (proposed):

• ephemeral → auto-archive after 7 days
• act → surface daily; flag as stale after 30 days without done
• learn → spaced repetition; never auto-archive
• reference → surface on demand; archive after 1 year without access

---

Correction

Responsibility: Allow explicit user override of enrichment fields.
What can be corrected: intent, summary, labels, concepts
When: At any point post-capture
Effect: Updates Storage; resets feedback counters; re-runs embedding if summary changed

---

Data Model

erDiagram
    captures {
        int id PK
        text type
        text source_url
        text content_path
        text summary
        text intent
        text labels
        text embedding
        text embedding_model
        text related_ids
        text lifecycle_state
        text created_at
        text last_surfaced_at
        int reviewed
    }

    events {
        int id PK
        int capture_id FK
        text event
        text value
        text created_at
    }

    concepts {
        int id PK
        text name
        text description
        int capture_count
        text created_at
    }

    capture_concepts {
        int capture_id FK
        int concept_id FK
    }

    captures ||--o{ events : "has"
    captures ||--o{ capture_concepts : "tagged with"
    concepts ||--o{ capture_concepts : "applied to"

---

Pipeline Flow

sequenceDiagram
    participant U as User
    participant C as Capture
    participant PF as Pre-filter
    participant E as Enrichment
    participant QG as Quality Gate
    participant S as Storage
    participant CN as Connections
    participant SF as Surface

    U->>C: text / link / image
    C->>S: store raw content to filesystem
    C->>PF: check dedup · length · language
    PF-->>C: reject if duplicate or noise
    PF->>E: pass if clean
    E->>E: summary · labels · intent · embed
    E->>QG: check summary quality · intent confidence
    QG-->>E: reject or flag if low confidence
    QG->>S: structured capture metadata
    S->>CN: new embedding
    CN->>CN: cosine similarity vs all
    CN->>S: update related_ids

    U->>SF: "what should I look at?"
    SF->>S: get surfaceable captures
    SF->>SF: score by intent · recency · context
    SF->>U: top-n with related
    U->>SF: done / skip (+ dwell time)
    SF->>S: log event
    SF->>E: re-enrich if skip streak ≥ 3

---

Appendix: Key Tradeoffs and Decisions

Embedding model versioning

Decision: Store embedding_model alongside every embedding vector.
Why: Embeddings from different models live in incompatible vector spaces — cosine similarity across models is meaningless. When model changes, re-embed all captures.
Tradeoff: Re-embedding is expensive but unavoidable. Mixing model versions silently would corrupt connections.

Filtration gate placement (two-stage)

Decision: Pre-filter (cheap, no LLM) before enrichment; post-filter (quality gate) after enrichment.
Why: Can't filter on quality without understanding content, but shouldn't waste LLM compute on obvious garbage.
Tradeoff: Two passes adds complexity. The alternative (single gate after enrichment) wastes compute on noise; single gate before enrichment misses quality failures.

Raw content storage (filesystem, not DB)

Decision: Page text and images go to storage/content/ and storage/images/, not SQLite.
Why: Page content can be 50k+ characters. Inline in DB means every query drags that weight. SQLite is the hot path for scoring, surfacing, and feed queries.
Tradeoff: Orphan risk on deletion. Mitigated by a single delete_capture() function that cleans both.

Concepts: derive, don't generate

Decision: Don't extract concepts per-capture. Start with tag clustering (Option C); graduate to constrained vocabulary (Option B) as KB grows.
Why: Per-capture concept extraction hallucinates. LLM has no grounding when looking at one item in isolation. Clustering over real accumulated data reduces hallucination surface significantly.
Tradeoff: Concepts are unavailable until enough tags accumulate. Acceptable — wrong concepts are worse than no concepts.

Deduplication fingerprint

Decision: Three-layer check — URL hash (exact) + content hash (exact) + embedding similarity threshold (fuzzy).
Why: URL hash misses same content at different URLs. Content hash misses paraphrases. Embedding similarity catches near-duplicates but needs the other two to avoid false positives.
Tradeoff: Three checks add latency at capture time. Worth it — duplicates degrade KB quality permanently.

SQLite over specialised stores

Decision: SQLite for all structured data until query patterns are known.
Why: Query patterns are unknown early. SQLite is flexible, requires no infrastructure, and handles the expected load.
Migration trigger: Embedding cosine scan degrades beyond ~1000 captures → add sqlite-vec extension. Schema stays the same, scan becomes indexed.

Mood/context capture

Decision: Optional dropdown in UI. No selection = no context signal. Time-of-day inferred automatically.
Why: Forced mood capture adds friction and will be skipped. Optional preserves signal quality — only captured when user is willing.
Tradeoff: Sparse signal early. Time-of-day inference compensates until enough explicit mood data accumulates.