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 procedurepnpm --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--aftersearchexits successfully and prints nothing. This verifies retrieval, not the accuracy of every topic claim. - An index built with the locally installed
nomic-embed-textmodel holds 377 chunks from 91 topic files, and a semantic procedure search returns the same turborepo topic first. Thestatusscript 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.filesrestores 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.