knott

A local, file-first knowledge layer for AI agents.

Markdown files are the source of truth. Knott adds structure (typed entities), semantics (relations between them), and validation, without turning your notes into an opaque database. A Knott vault stays useful without Knott: browse it in a file manager, read it in any editor, open it in Obsidian, diff it in Git.

Install

uvx knott --help        # run without installing
uv add knott            # or add it to a project

Requires Python 3.12+.

Quick start

mkdir my-vault && knott init my-vault

Define a type in my-vault/.knott/schemas/script.yaml:

type: script
description: A script for a recorded episode.
attributes:
  title:
    type: string
    required: true

and one that relates to it, .knott/schemas/transcript.yaml:

type: transcript
relations:
  derived_from:
    target: script

Write entities as ordinary Markdown with frontmatter, anywhere in the vault:

---
type: transcript
title: Episode 42 transcript
derived_from: "[Episode 42](../scripts/foo.md)"
---
# Transcript

Then validate:

$ knott validate
✓ 2 schemas
✓ 2 entities
✓ 1 relation
✓ vault is valid

Commands

Exit codes: 0 valid, 1 validation issues, 2 usage or configuration error.

Schemas

Schemas live in .knott/schemas/**/*.yaml, one type per file. Attribute types: string, integer, number, boolean, date, datetime, plus list, object and map built from them and nested to any depth. Typing is strict: an unquoted no is a boolean, not a string. Relations name a target type and are stored only on the source entity.

Structured attributes are checked at every level, and problems name their exact location, e.g. senses[1].ru:

attributes:
  senses:
    type: list
    required: true
    items:
      type: object
      fields:
        id: {type: string, required: true}
        ru: {type: string, required: true}

Relations

A relation value is a relative path or a quoted Markdown link, or a list of them, resolved relative to the containing file:

derived_from: ../scripts/episode-42.md
derived_from: "[Episode 42 script](../scripts/episode-42.md)"

Wikilinks, URLs, #fragments, and absolute paths are rejected. Matching is case-sensitive on every OS.

Stable identity

knott validate --fix gives every entity a kid, a knott-managed UUID that survives moves and renames. A relation can then refer to it as kid:<uuid>. A schema can require one with kid: required. Markdown links stay the recommended form; use kid: where a reference must survive renames.

kid: 3f2b8c1e-9d4a-4c2e-b7f1-0a6d5e9c8b21
includes:
  - kid:0192f4a1-7c3e-4b2a-9f10-3d5e8c2b4a61

Obsidian

Markdown links in properties are clickable in Obsidian 1.11+ and are updated on rename. Use these settings:

• Files & links → New link format: Relative path to file
• Use [[Wikilinks]]: off

Python API

from knott import Knott

vault = Knott.open(".")              # walks up to the vault root
result = vault.validate()            # or vault.validate(["transcripts/foo.md"])
result.ok, result.issues, result.stats
vault.types()                        # ["script", "transcript"]
vault.ontology()                     # Ontology(vault, types, schema_issues)

Validation problems come back as data; only usage errors raise (KnottError subclasses).

For agents

Knott ships an Agent Skill describing how to read schemas, write entities and relations, and validate (SKILL.md). Install it into a project:

knott skill install            # pick targets interactively
knott skill install --claude   # .claude/skills/knott/ (Claude Code)
knott skill install --agents   # .agents/skills/knott/ (Codex and other agents)

Development

uv sync
uv run pytest
uv run ruff check src tests
uv run mypy