Search by Meaning, Keep the Boundaries

Find a thought without losing its boundaries

Keyword search is excellent when I remember the exact noun, error string, tag, or function name I used. It is much less helpful when I remember only the meaning of a long journal entry, the shape of an abandoned idea, or what a piece of code was trying to accomplish. ProjectMan's search work began with that mismatch: personal notes contain prose, metadata, source blocks, decisions, and half-formed language, while literal retrieval assumes the query and the note already share a vocabulary.

Keep the durable data plane small

The tempting answer was to add a vector database or a large search service. At ProjectMan's scale, that would have created more operational machinery than useful capability. The implementation instead keeps MariaDB as the durable data plane. A privacy-safe Gold projection feeds MariaDB full-text and bounded literal retrieval; the same approved chunks are encoded locally and stored as rebuildable vectors. Semantic queries run exact cosine search over a disposable in-process NumPy matrix. There is no approximate-nearest-neighbor index, external vector service, or second database to back up and reconcile.

That simplicity depends on drawing the privacy boundary before retrieval. Search workers never embed unrestricted heading text. They consume only materialized safe titles, paths, metadata, tags, and chunks. A restricted heading receives no searchable document or vector, and privacy or tree changes invalidate affected state in the same transaction as the canonical change. Queries accept only current rows under the current policy epoch. If materialization is incomplete, the system fails closed instead of searching stale content and filtering afterward.

Search stays inside the boundary

Only privacy-safe material enters the index. Queries require current content and policy state before returning results.

flowchart TD
    Safe[Privacy-safe projection] --> Index[Lexical index and local vectors]
    Index --> Current[Require current content and policy]
    Query[Search query] --> Current
    Current --> Rank[Retrieve and combine ranks]
    Rank --> Results[Allowed headings with provenance]

Build privacy into the index contract

Chunking respects the structure already present in Org. Headings remain the result identity, while source, example, quote, and prose regions become deterministic match locators. Long notes can contribute several chunks without monopolizing the result list because each retrieval channel collapses back to one rank per heading. Chunker versions, content hashes, model identity, and policy epochs are part of the derived-state contract, so an old worker cannot publish a vector for text that changed while it was running.

The local encoder was selected rather than assumed. ProjectMan evaluated two pinned small English retrieval models with immutable artifact manifests and no remote model code. Both cleared the quality and memory gates; intfloat/e5-small-v2 won the declared latency tie-breaker. It runs through ONNX Runtime on CPU, produces normalized 384-dimensional vectors, and uses explicit query and passage templates. Warm query embedding measured about 12 milliseconds at the median and under 60 milliseconds at p95 in the recorded evaluation, while exact vector scoring remained only a few milliseconds at the current scale.

Measure the ranking policy

Lexical and semantic evidence are combined with weighted reciprocal-rank fusion. Literal identifiers, code tokens, properties, and error strings retain their strength, while semantic rank receives more weight for paraphrase and memory-style questions. The selected policy uses a fixed fusion constant and deterministic ties rather than presenting an unstable raw similarity score as truth. On both the synthetic and private evaluation corpora, hybrid search improved semantic nDCG without regressing exact-query recall, negative-query behavior, privacy sentinels, or duplicate-heading checks.

Ship derived state in reviewable slices

Delivery was split into five independently reviewed slices: the privacy-safe projection and fenced work queues; lexical retrieval and the read-only tool contract; local embeddings and exact semantic search; evaluated hybrid ranking with incremental invalidation; and finally complete-item retrieval, observability, recovery, and rollout. Ordinary note changes now preserve unchanged documents and vectors and rebuild only materially changed headings. Full rebuilds remain available for bootstrap, privacy-policy changes, version upgrades, and ambiguous diffs, but the design does not carry a side-by-side generation system that the present workload does not need.

The production lesson was pleasantly unglamorous: measured limits beat speculative architecture. The worker uses bounded claims, conservative provider batches, durable leases, and content-free health reporting. Search can be disabled without affecting capture, review, workflow operations, or Org export. Model artifacts are prefetched and verified explicitly, MariaDB backups contain everything required to reconstruct the index, and the runtime matrix is treated as a cache. The result is semantic search that feels native to ProjectMan: useful across the workbench, REST, CLI, and local MCP surfaces, but still subordinate to provenance, privacy, portability, and human control.