knowledges trained

how the local topic bank behaves under real searches: keyword lookups, type filters, and the vector index.

mental model

The topic tree holds typed topic files. Single-file topics are <slug>.md; topics with assets or references use <slug>/TOPIC.md. The search CLI reads both by keyword or regex directly; semantic search embeds source chunks and queries with Ollama's /api/embed, then searches their vectors in LanceDB. The topic layout, type filter, ranking weights, and freshness manifest are this bank's own procedure, not LanceDB or Ollama features.

examples

pnpm --dir <knowledges references folder> run search --keyword 'turborepo pipeline' --type procedure
pnpm --dir <knowledges references folder> run status

best practices

Open the returned topic file before using its claims. Keep the type filter when the task calls for one topic kind.

strengths

Keyword search works on the source tree without first building a vector index. That is a property of the local lexical path; LanceDB vector search is the separate path for similarity retrieval.

weaknesses / pain points

Semantic search needs a current index and a running Ollama service with the configured embedding model. The local embedding path posts batched text to Ollama; its API returns vectors, while this bank decides how to chunk, filter, and display them. A successful vector match is a lead to a file, not proof of its claims.

gotchas

The topic bank has both flat files and multi-file topic folders below category folders such as topics/procedures/; search must collect both shapes. With pnpm 11.15.1, pnpm run search -- --keyword ... exits successfully with no result; pass --keyword directly after search. The CLI normalizes one separator, but the observed pnpm invocation still fails to dispatch the search action. When a topic's only reference becomes a flat file in the topic folder, approve it in the index policy or it disappears from the semantic corpus.

known bugs

No external dependency defect is known.

troubleshooting

The search CLI indexes only this guru's references/assets folder and the categorized references/topics tree. A topic living anywhere else is invisible to both keyword and semantic search.

practiced cases

  • On pnpm 11.15.1, a procedure-filtered keyword search for 'turborepo pipeline' returns the setup-turborepo-pipeline procedure first; the same invocation with -- after search exits successfully and prints nothing. This verifies retrieval, not the accuracy of every topic claim.
  • An index built with the locally installed nomic-embed-text model holds 377 chunks from 91 topic files, and a semantic procedure search returns the same turborepo topic first. The status script reports that freshness before any search is trusted.
  • When a one-file reference folder is folded into its topic folder, a reindex that skips the unapproved file finds 90 files and 374 chunks. Adding the filename to approvedL3.files restores the full 91 files and 377 chunks, and the flat topic stays retrievable by keyword. This is an index-coverage check, not a source-quality review.

Read the knowledges skill.

search pages

go to any page