Syntax & Concepts

Thalo is a structured plain-text language for capturing knowledge. This guide covers the core syntax and concepts.

Entry Structure

Every Thalo entry follows this structure:

{timestamp} {directive} {entity} "Title" [^link-id] [#tags...]
  {metadata-key}: {value}
  ...

  # Section Name
  Content goes here...

Header Line

The header line contains:

Element	Pattern	Required	Example
Timestamp	`YYYY-MM-DDTHH:MM` or `YYYY-MM-DDTHH:MMZ`	Yes	`2026-01-08T14:30Z`
Directive	`create` or `update`	Yes	`create`
Entity	Entity type name	Yes	`opinion`, `journal`, `reference`, `lore`
Title	Quoted string	Yes	`"My Entry Title"`
Link ID	`^` + identifier	No	`^my-entry-id`
Tags	`#` + identifier	No	`#programming #books`

Example

2026-01-08T14:30Z create opinion "TypeScript enums should be avoided" ^ts-enums #typescript
  confidence: "high"
  related: ^clean-code

  # Claim
  TypeScript enums should be replaced with `as const` objects.

  # Reasoning
  - Enums generate runtime code
  - `as const` provides the same type safety with zero overhead
  - Better tree-shaking support

Metadata

Metadata fields are indented key-value pairs. Values can be:

Strings: author: "Jane Doe" or unquoted author: Jane Doe
Links: subject: ^self or related: ^other-entry
Arrays: tags: #programming, #books
Dates: published: 2023-03-16
Date ranges: date: 2020 ~ 2021
Enums: confidence: "high" (must match schema definition)

Sections

Content sections start with # SectionName (indented). All content must be within a section. Each entity type defines which sections are required or optional.

2026-01-08T14:30Z create journal "Daily reflection" ^daily-2026-01-08
  subject: ^self
  type: "reflection"
  mood: "contemplative"

  # Entry
  Today I learned about the importance of plain text formats
  for knowledge management. The simplicity is powerful.

Links

Links use the ^ prefix and allow you to cross-reference entries:

# Reference another entry
related: ^clean-code

# Self-reference
subject: ^self

# Multiple links
related: ^entry-one, ^entry-two

Link IDs are defined in the header line with ^identifier. If omitted, Thalo generates one automatically.

Entity Definitions

Before creating entries, you need to define entity schemas:

2026-01-07T11:40Z define-entity opinion "Formed stances on topics"
  # Metadata
  confidence: "high" | "medium" | "low"
  supersedes?: link ; "Reference to previous stance"
  related?: link[] ; "Related entries"

  # Sections
  Claim ; "Core opinion in 1-2 sentences"
  Reasoning ; "Bullet points supporting the claim"
  Caveats? ; "Edge cases, limitations, exceptions"

The schema defines:

Required and optional metadata fields
Field types and constraints
Required and optional sections

Syntheses

Syntheses define queries over your knowledge base:

2026-01-08T14:30Z define-synthesis "My Programming Philosophy" ^prog-philosophy #programming
  sources: opinion where #programming, lore where #insights

  # Prompt
  Synthesize my programming opinions and insights into a coherent philosophy.
  Note any contradictions or evolution in my thinking.

Syntheses allow you to:

Query multiple entry types
Filter by tags or metadata
Generate AI prompts for synthesis

Comments

Add comments with //:

// This is a comment

2026-01-08T14:30Z create opinion "Example" ^example
  // Metadata comment
  confidence: "high"

  # Claim
  // Inline comment
  This is the claim.

Markdown Integration

Thalo entries can be embedded in Markdown files using fenced code blocks:

# My Document

Some markdown content here.

```thalo
2026-01-05T18:00Z create lore "An insight" #example
  type: "insight"
  subject: ^self

  # Description
  This thalo entry lives inside a markdown file.
```

More markdown content.

The Prettier plugin automatically formats Thalo code blocks in Markdown files.

Best Practices

Use descriptive link IDs: ^clean-code-book is better than ^cc1
Tag consistently: Establish tag conventions early
Link related entries: Build a web of connected knowledge
Run thalo check regularly: Catch errors early
Start simple: Add complexity as your knowledge base grows

Next Steps

Learn about defining entities
Explore the CLI commands
See real-world examples

Syntax & Concepts

On this page