Thalo

Quick start workflow

• Initialize a knowledge base with thalo init to generate entities.thalo, AGENTS.md, and personal-bio.md.
• Add or edit entries in *.thalo files or fenced code blocks inside Markdown (lang: thalo).
• Validate after changes with thalo check to catch schema, link, and syntax issues.
• Format with thalo format when preparing a commit or cleanup (or use Prettier with the plugin)
• Run thalo actualize to materialize syntheses (queries + prompt) for LLM use.

Entry syntax

Follow this structure:

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

  # Section
  {content}

Guidelines:

• Use ISO 8601 local time with timezone, e.g. 2026-01-05T15:30Z.
• Use create for new entries and update for modifications.
• Provide a stable ^link-id when you want to reference the entry elsewhere.
• Put all content inside sections; required sections are defined in entities.thalo.
• Entities are typically journal, opinion, reference, or lore (see entities.thalo).

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: ^my-other-entry
• Dates: published: 2023-03-16
• Date ranges: date: 2020 ~ 2021

Sections

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

Defining entities

Define or update entities in entities.thalo using define-entity blocks. Each entity specifies:

• Metadata fields with types (string, link, datetime, date-range, enums, arrays, unions).
• Sections that determine required/optional content.

After editing or adding entries or entities, generally run thalo check to validate.

If you need the default entity templates, load references/entities.thalo.txt.

Syntheses

Syntheses are queries plus prompts that let you generate structured summaries or narratives.

• Create with define-synthesis blocks.
• Use sources: to select entries by entity, tag, or metadata filters.
• Run thalo actualize to output the sources and prompt for downstream LLM use.

Working in Markdown

Thalo can live inside Markdown files. The fenced code block language SHOULD be thalo (don’t use it in this file as an example because it would be parsed):

```text
...entries...
```

The CLI and LSP will parse fenced thalo blocks in .md files.

Installation

If thalo is not available, install via the user’s package manager (local or global):

# Local (recommended for repo tooling)
npm install --save-dev @rejot-dev/thalo-cli

# Or with your preferred PM:
pnpm add -D @rejot-dev/thalo-cli
yarn add -D @rejot-dev/thalo-cli

# Global (optional)
npm install -g @rejot-dev/thalo-cli

Prettier integration

This repo uses the Thalo Prettier plugin. The config is in prettier.config.mjs and includes:

plugins: ["@rejot-dev/thalo-prettier"];

Use thalo format for CLI formatting, or run Prettier normally and it will format Thalo/Markdown with the plugin enabled.

CLI reference (condensed)

• thalo init [directory] (options: --dry-run, --force) creates entities.thalo, AGENTS.md, personal-bio.md.
• thalo check [paths...] validates syntax, metadata, sections, links, enums. Options include --format, --severity, --max-warnings, --rule, --watch, --file-type.
• thalo format [paths...] formats .thalo and .md (options: --check, --write, --file-type).
• thalo actualize [links...] outputs pending synthesis updates and prompts. Supports -i for custom instructions templates. Tracks changes via git or timestamps.
• thalo query "<query>" [paths...] filters by entity, tags, links, metadata. Options: --format, --limit.
• thalo rules list shows validation rules (filter by --severity, --category, --json).
• thalo lsp starts the language server (stdio).
• Global: --help, --version.

References

• Use references/entities.thalo.txt for the default entity definitions from thalo init.
• Use references/example-entries.thalo.txt for sample entries.
• Use references/scripting-api.md for the scripting API summary.
• Use date -u +"%Y-%m-%dT%H:%MZ" to generate timestamps quickly.