Mesh

The Mesh is your thinking space - a folder of interconnected markdown files where ideas, tasks, and knowledge live.

Purpose

Every Flint has a Mesh/ folder at its heart. This is where you write notes, track projects, and develop ideas. Unlike flat file storage, the Mesh treats your notes as a connected knowledge graph. Link notes with [wiki-style](/wiki-style) references, and those connections become navigable.

The Mesh module provides:

• Indexing - Every note gets a unique ID for reliable linking
• Organization - Typed prefixes organize documents by purpose
• Linking - Wiki-style links create a knowledge graph
• Archiving - Move completed work to archive with proper tagging

Structure

Notes live in the Mesh/ folder. You can organize them flat or in subfolders:

Mesh/
├── (System) Flint Init.md       # Entry point for agents
├── (Dashboard) Backlog.md       # Project overview
├── (Task) Current Work.md       # Active work item
├── Architecture Notes.md        # Regular note
├── Plans/                       # Subfolder for plans
│   └── (Plan) Q1 Roadmap.md
└── Archive/                     # Completed/historical items
    └── Tasks/
        └── (Task) Old Work.md

Typed Documents

Flint uses a (Type) Name.md naming convention to categorize notes. The type prefix helps both humans and tools understand what a note represents.

Common Types

Notes without a type prefix are regular concept notes.

Type Extraction

When archiving, the type is extracted from the filename and routes the note to the appropriate archive subfolder if it exists:

(Task) Old Work.md → Archive/Tasks/(Task) Old Work.md
(Plan) Old Plan.md → Archive/Plans/(Plan) Old Plan.md

Frontmatter

Every note can have YAML frontmatter for metadata. The indexer ensures each note has a unique id.

Basic Structure

---
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
tags:
  - "#project/alpha"
  - "#status/active"
status: in-progress
priority: high
---

# Note Title

Content here...

Common Fields

The id field is required for reliable linking and is automatically added by flint index.

Tags

Tags can appear in frontmatter or inline in content:

tags:
  - "#project/alpha"
  - "#ld/living"

Or inline: This note is about #project/alpha.

Frontmatter tags are indexed. Use hierarchical tags like #project/alpha or #status/done for organization.

Living Documents

The Living Documents system uses tags to track note lifecycle:

When archiving a note, the system:

1. Adds #archived tag
2. Replaces #ld/living with #ld/dead
3. Moves the file to Mesh/Archive/

Indexing

The indexer scans your Mesh and ensures every note has a unique ID.

Running the Indexer

# Index all files
flint index

# Preview changes without modifying files
flint index --dry-run

# See each file processed
flint index --verbose

What Indexing Does

1. Scans all .md files in Mesh/ (skips symlinks)
2. Adds id field to frontmatter if missing
3. Extracts tags from frontmatter
4. Writes index to .flint/index/files.json

Index Structure

The index at .flint/index/files.json:

{
  "version": 1,
  "indexed": "2025-01-15T10:00:00.000Z",
  "files": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "path": "Mesh/Architecture Notes.md",
      "tags": ["#project/alpha", "#ld/living"],
      "modified": "2025-01-15T09:30:00.000Z"
    }
  ]
}

Excluded Directories

The scanner automatically skips:

• .obsidian/ - Obsidian configuration
• .git/ - Git repository data
• node_modules/ - Package dependencies
• Hidden directories (starting with .)
• Symlinks (Workspace/, Imports/ often contain symlinks)

Wiki-Links

Notes connect through wiki-style links:

Basic Links

See [Related Concept](/related-concept) for more details.

Aliased Links

See [this concept](/related-concept) for more details.

Transclusion (Embedding)

![Embedded Note](/embedded-note)

Transclusion embeds the content of another note inline. This is used by the export system to compile documents.

Section Links

See [Related Concept#Specific Section](/related-concept-specific-section).

Plugin Interaction

Plugins read from and write to the Mesh:

Projects Plugin

Creates and manages task notes:

Mesh/Tasks/(Task) Fix Bug.md

With frontmatter:

status: todo
priority: high

Increments Plugin

Creates versioned work stream notes:

Mesh/Increments/(Increment) 1.2.0 - Feature X.md

Notepad Plugin

Creates temporary working notes:

Mesh/(Notepad) 2025-01-15 Session.md

Plan Plugin

Creates and tracks plans:

Mesh/Plans/(Plan) Q1 Roadmap.md

Plugins use the Mesh/ folder as their workspace, following the typed document conventions.

Best Practices

Organization

Start with an entry point. Create (System) Flint Init.md as your main index. Link to key areas.

Use consistent naming. Pick a convention and stick with it. Type prefixes help categorization.

Link liberally. The power of Mesh comes from connections. When you mention a concept, link it: [that concept](/that-concept).

Archive, don't delete. Move completed notes to Archive/ rather than deleting. History is valuable.

Keep notes atomic. One concept per note. Link related concepts rather than cramming everything together.

Tags

Use hierarchical tags. #project/alpha, #status/done, #type/task - structure helps organization.

Mark living documents. Use #ld/living for active notes, let archiving handle #ld/dead.

Be consistent. Decide on tag naming conventions early. #status/active or #active? Pick one.

Avoid

• Giant monolithic notes - Split them up and link the pieces
• Forgetting to index - Run flint index after adding files externally
• Duplicate concepts - Search before creating; link instead of copying
• Deep nesting - Keep folder structure shallow; use links for relationships

Related

• Module - Exports - Compile Mesh notes for sharing
• Module - Imports - Bring external content into Mesh
• Module - Plugins & Mods - Extend Mesh with plugins
• Reference - CLI Commands - Full CLI reference