Knowledge retrieval and dates

Keyword search, exact identity lookup, and date queries. Part of the Knowledge plugin guide.

Knowledge has no embeddings, remote search services, query expansion, answer synthesis, or regex search. knowledge_records is the exhaustive inventory; ranked search never proves that an inventory is complete.

Query contract

Queries accept 1–64 word tokens within 500 characters. Punctuation separates tokens; OR, NOT, column syntax, and quotes are not executed as FTS syntax. Matching is case- and diacritic-insensitive. There is no stemming, prefix search, or language-specific segmentation, so unsegmented CJK substrings may not match.

Exact lookup accepts up to 200 characters. IDs are case-sensitive; names and aliases are normalized (NFKC, lowercase, trimmed, whitespace collapsed) but never fuzzy-matched. Ambiguity is computed across all matches, not from one returned hit.

Defaults cover all active saved records. Invalid and duplicate IDs, withdrawn records, and records whose structured dependencies, endpoints, or entities are unavailable are excluded in every mode. Authored prose without declared dependencies cannot be redacted automatically.

Results and citations

Each hit has a summary, lifecycle, matched fields, attribution and assertion origin, and the stable ID, path, revision, and SHA-256 of the observed Markdown.

• Snippets are at most 480 UTF-16 characters with zero-based start/end offsets. Body snippets also carry one-based Markdown line ranges, counting frontmatter lines.
• At most three verified evidence locators are included. evidenceTruncated points to knowledge_record for more.
• For bodies over 64 KiB, the snippet is an opening excerpt, not the match location (snippet.matchLocated: false).
• Citation hashes identify the searched revision. Compare hashes before relying on a later read.

BM25 weights are title 8, aliases 6, body 1. Scores are positive and only comparable within one query, filter set, and corpus snapshot. Scope and filters are applied before corpus statistics, so other scopes cannot affect rank, counts, or snippets.

Index behavior

Markdown is authoritative. Each search first runs the scoped scan and validation, then reconciles a per-scope FTS5 projection in the store's state.sqlite. These tables are not shared with memory-core or other plugins.

• A publication receipt's indexed: false means indexing is pending until the next search, not a failed save.
• index.state: "ready" with lag: false means the projection matches this query's snapshot. Compare snapshot across pages and restart if it changes.
• index.state: "unavailable" with total: null is a failed retrieval. Retry; exact lookup and knowledge_records do not depend on FTS5.
• Authority, identity, publication-conflict, and scan-limit failures reject the operation instead of returning an empty or partial search.
• Validation issues set coverage.complete: false.

There is no background indexing worker.

What is rebuildable

The keyword_fts_v1_* tables, keyword_state_v1, and the temporal tables are projections. Missing tables or changed fingerprints are rebuilt on the next query.

Do not drop state.sqlite to rebuild search. It also holds store identity, receipts, history, Git checkpoints, session activity, and withdrawal and supersession safeguards (keyword_withdrawals_v1, lifecycle_guards_v1). Those safeguards stop a stale active file from resurrecting a withdrawn or superseded record, and cannot be rebuilt from Markdown or Git.

Dates and Chronicle

Knowledge projects validated structured dates and entity associations into scoped SQLite tables. Each date query reconciles its authorized snapshot first. Dates written only in page prose, such as Timeline bullets, do not create structured records.

Unknown dates stay absent; recording time never stands in for occurrence. Bounds accept a real YYYY-MM-DD or an ISO timestamp with seconds and an explicit time zone. The host resolves relative dates. Bounds are inclusive, and a date-only upper bound includes the whole UTC day. Date-only records match overlapping ranges without claiming an exact instant.

• To find recently recorded or updated records, query knowledge_timeline with timeField: "recorded_at" or "updated_at". This is a current-record query, not a change cursor; use history for audit.
• A shared event claim with source_event: true represents its source meeting. On occurrence timelines it replaces the meeting page row; a kind: "meeting" query still returns the page.
• Entity filters use explicit entities, owner, endpoints, and source associations, not co-mentions.
• A mention does not prove attendance or contact. No match does not prove absence.
• eligibility: "include_inactive" adds superseded and expired assertions, never withdrawn ones. It is not a snapshot of what Knowledge knew at a past time.
• includeSources: true adds deduplicated source summaries within the same 24 KiB response budget.
• Follow nextOffset with unchanged filters and the returned snapshot.

Query responses report freshness.queriedAt, freshness.scannedAt, and, for keyword queries, freshness.indexedAt. An older scannedAt means the scan was reused while files were unchanged, not that results are stale.