note

Documentation

Overview

Package note provides the core Note type, ID generation, and frontmatter parsing/serialisation for the nn Zettelkasten CLI.

Index

• Variables
• func BM25IDF(notes []*Note, terms []string) map[string]float64
• func BM25RRFPerField(candidates []*Note, fidf FieldIDF, query string, inbound map[string][]string) map[string]float64
• func BM25RRFPerFieldForCorpus(corpus, candidates []*Note, fidf FieldIDF, query string, ...) map[string]float64
• func BM25Scores(notes []*Note, query string, inbound map[string][]string) map[string]float64
• func BM25ScoresTyped(notes []*Note, query string, inbound map[string][]TypedAnnotation) map[string]float64
• func BM25ScoresWithIDF(candidates []*Note, idf map[string]float64, query string, ...) map[string]float64
• func BM25ScoresWithPropagation(notes []*Note, query string, inbound map[string][]string, ...) map[string]float64
• func GenerateID() string
• func HasCheckbox(body string) bool
• func IsDone(body string) bool
• func IsKnownLinkType(t string) bool
• func Tokenize(s string) []string
• func ValidTypes() []string
• type CorpusScorer
  • func NewCorpusScorer(corpus []*Note, fidf FieldIDF, inbound, outbound map[string][]string) *CorpusScorer
  • func (s *CorpusScorer) Score(candidates []*Note, query string) map[string]float64
• type FieldIDF
  • func BM25FieldIDF(notes []*Note, inbound map[string][]string) FieldIDF
• type Link
• type Note
  • func Parse(data []byte) (*Note, error)
  • func (n *Note) Filename() string
  • func (n *Note) Marshal() ([]byte, error)
• type Status
  • func (s Status) IsValid() bool
• type Type
  • func (t Type) IsValid() bool
• type TypedAnnotation

Variables

var KnownLinkTypes = map[string]bool{
	"refines":     true,
	"contradicts": true,
	"source-of":   true,
	"extends":     true,
	"supports":    true,
	"questions":   true,
	"governs":     true,
	"requires":    true,
	"grounded-by": true,
}

KnownLinkTypes is the canonical set of link relationship types. nn link --type warns when the type is not in this set.

var LinkTypeDescriptions = map[string]string{
	"refines":     "The source sharpens or narrows the target's claim without replacing it — use when adding precision or a sub-case.",
	"contradicts": "The source directly opposes the target's claim — use when two notes cannot both be true.",
	"source-of":   "The target is derived from or authored by the source — use for evidence, citations, or origin relationships.",
	"extends":     "The source adds structure or scope to the target without replacing it — use when building on top of an existing model.",
	"supports":    "The source corroborates the target's claim — use for independent evidence that strengthens but is not constitutive of the target.",
	"questions":   "The source raises an unresolved challenge to the target — use when the target's claim is uncertain or contested.",
	"governs":     "The source is an operating protocol that constrains how the target (or its domain) is acted on — use only for protocol notes.",
	"requires":    "The source cannot be acted on until the target is complete — use for task dependency, not conceptual dependency.",
	"grounded-by": "The source claim depends on the target observation as its evidential basis — use when removing the target would make the source claim ungrounded (stronger than supports, which is corroborative only).",
}

LinkTypeDescriptions gives a one-line semantic definition for each known link type. Use these to choose the correct type before calling nn link.

var LinkTypeOrder = []string{
	"refines", "contradicts", "source-of", "extends", "supports", "grounded-by", "questions", "governs", "requires",
}

LinkTypeOrder is the canonical display order for link types.

var LinkTypeWarnings = map[string]string{
	"governs":  "governs creates a binding operating constraint visible at session start — only use when you intend the source note to act as an active protocol that governs LLM behavior",
	"requires": "confirm both notes are action-bearing (have checkboxes or represent a work item) before linking",
}

LinkTypeWarnings gives a confirmation requirement for link types with semantic hazards. Empty string means no warning.

Functions

func BM25IDF

func BM25IDF(notes []*Note, terms []string) map[string]float64

BM25IDF computes inverse document frequency for the given terms over the corpus.

func BM25RRFPerField

func BM25RRFPerField(candidates []*Note, fidf FieldIDF, query string, inbound map[string][]string) map[string]float64

BM25RRFPerField preserves the original four-field scorer for callers that intentionally use one slice as both the statistics corpus and candidate set.

func BM25RRFPerFieldForCorpus

func BM25RRFPerFieldForCorpus(corpus, candidates []*Note, fidf FieldIDF, query string, inbound, outbound map[string][]string) map[string]float64

BM25RRFPerFieldForCorpus scores candidates while deriving document-length statistics and outbound query-term IDF from the full corpus.

func BM25Scores

func BM25Scores(notes []*Note, query string, inbound map[string][]string) map[string]float64

BM25Scores returns BM25 scores for each note against the query terms. inbound maps note ID to annotation strings from notes that link to it. IDF is computed over the same corpus as candidates (correct when corpus==candidates). For filtered candidate sets, prefer BM25IDF + BM25ScoresWithIDF.

func BM25ScoresTyped

func BM25ScoresTyped(notes []*Note, query string, inbound map[string][]TypedAnnotation) map[string]float64

BM25ScoresTyped scores notes using link-type-weighted inbound annotations.

func BM25ScoresWithIDF

func BM25ScoresWithIDF(candidates []*Note, idf map[string]float64, query string, inbound map[string][]string) map[string]float64

BM25ScoresWithIDF scores candidates using a pre-computed IDF map. IDF should be computed over the full corpus via BM25IDF; candidates may be a subset.

func BM25ScoresWithPropagation

func BM25ScoresWithPropagation(notes []*Note, query string, inbound map[string][]string, links map[string][]string) map[string]float64

BM25ScoresWithPropagation scores notes then propagates scores 1 hop through links. links maps source note ID to slice of target note IDs.

func GenerateID

func GenerateID() string

GenerateID returns a unique note ID in the format <14-digit-timestamp>-<4-digit-random>. crypto/rand provides the suffix. A process-local set detects and retries on the rare within-process collision (e.g. 200 concurrent goroutines in the same second).

func HasCheckbox

func HasCheckbox(body string) bool

HasCheckbox reports whether body contains any real checkbox line (checked or unchecked).

func IsDone

func IsDone(body string) bool

IsDone reports whether a note body is considered complete. A note is done when it has no checkboxes (vacuously) or all checkboxes are checked.

func IsKnownLinkType

func IsKnownLinkType(t string) bool

IsKnownLinkType reports whether t is in the canonical link type set.

func Tokenize

func Tokenize(s string) []string

Tokenize splits text into lowercase tokens. Exported for use in match-reason computation.

func ValidTypes

func ValidTypes() []string

ValidTypes returns the list of recognised note type strings.

Types

type CorpusScorer

type CorpusScorer struct {
	// contains filtered or unexported fields
}

CorpusScorer scores many queries against a fixed corpus while reusing tokenization across queries. Tokenization of a note's fields is a pure function of the note content, so it is memoized once per corpus and shared by every Score call.

func NewCorpusScorer

func NewCorpusScorer(corpus []*Note, fidf FieldIDF, inbound, outbound map[string][]string) *CorpusScorer

NewCorpusScorer builds a scorer over the given corpus and BM25 inputs.

func (*CorpusScorer) Score

func (s *CorpusScorer) Score(candidates []*Note, query string) map[string]float64

Score ranks candidates for query. Results are identical to BM25RRFPerFieldForCorpus over the same inputs; only the redundant per-query tokenization of the corpus is avoided.

type FieldIDF

type FieldIDF struct {
	Title   map[string]float64
	Body    map[string]float64
	Tags    map[string]float64
	Inbound map[string]float64
}

FieldIDF holds per-field IDF maps, each computed over only that field's token corpus. Using field-specific IDF ensures BM25 scores within each field are self-consistent.

func BM25FieldIDF

func BM25FieldIDF(notes []*Note, inbound map[string][]string) FieldIDF

BM25FieldIDF computes per-field IDF maps for the given notes corpus and query terms. inbound maps note ID to annotation strings from notes that link to it.

type Link

type Link struct {
	TargetID   string
	Annotation string
	Type       string // optional relationship type, e.g. "refines", "contradicts"
	Status     string // "draft" or "reviewed"; empty = reviewed (backward-compat for old links)
}

Link is an annotated outgoing link from one note to another.

type Note

type Note struct {
	// Frontmatter fields
	ID             string
	Title          string
	Type           Type
	Status         Status
	Tags           []string
	AppliesWhen    string
	Representation string
	ExpiresWhen    string
	Expires        *time.Time
	Created        time.Time
	Modified       time.Time

	// Body is the Markdown content between the frontmatter and the ## Links section.
	Body string

	// Links are parsed from the ## Links section.
	Links []Link
}

Note is the in-memory representation of a single Zettelkasten note.

func Parse

func Parse(data []byte) (*Note, error)

Parse reads a Markdown file (with YAML frontmatter) and returns a Note. Returns an error if the frontmatter is invalid, the type is missing, or a bare link (without annotation) is found in the ## Links section.

func (*Note) Filename

func (n *Note) Filename() string

Filename returns the canonical filename for this note: <id>-<slug>.md

func (*Note) Marshal

func (n *Note) Marshal() ([]byte, error)

Marshal serialises the note back to Markdown with YAML frontmatter.

type Status

type Status string

Status is the review status of a note.

const (
	StatusDraft     Status = "draft"
	StatusReviewed  Status = "reviewed"
	StatusPermanent Status = "permanent"
)

func (Status) IsValid

func (s Status) IsValid() bool

IsValid reports whether s is one of the recognised note statuses.

type Type

type Type string

Type classifies the intellectual content of a note.

const (
	TypeConcept     Type = "concept"
	TypeArgument    Type = "argument"
	TypeModel       Type = "model"
	TypeHypothesis  Type = "hypothesis"
	TypeObservation Type = "observation"
	TypeQuestion    Type = "question"
	TypeProtocol    Type = "protocol"
)

func (Type) IsValid

func (t Type) IsValid() bool

IsValid reports whether t is one of the recognised note types.

type TypedAnnotation

type TypedAnnotation struct {
	Text     string
	LinkType string
}

TypedAnnotation pairs an annotation string with the link type that produced it.