NAME

kb-concept — manage concepts

SYNOPSIS

kb concept add NAME DESCRIPTION [–identifier-type T –identifier-value V]

kb concept list

kb concept show NAME [–limit N]

kb concept recall [TEXT… | -] [–concept NAME,…] [–project NAME] [–limit N]

kb concept rename OLD NEW

kb concept delete NAME [–force] [–dry-run]

kb concept suggest [–project NAME] [–limit N]

DESCRIPTION

A concept is a named idea or term that can be linked to projects and observations (see kb-link(1)). Names are unique.

add on an existing name updates that concept rather than creating a second one, which is also how a concept’s description is corrected – there is no separate set-description here, unlike kb-project(1). An omitted or empty DESCRIPTION preserves the stored one rather than clearing it, so running add just to assert a concept exists cannot lose text. The same holds for –identifier-type and –identifier-value.

A concept may also represent a scholarly entity — a paper, person, institution, or funder — by setting –identifier-type (e.g. doi, orcid, ror, fundref) and –identifier-value (the normalized identifier).

show

read-only: one concept’s description, identifier if set, and what links to it. Per kind (projects, observations, records, document sections) it prints the full count and up to –limit items, newest first (default 10; –limit 0 prints counts only). NAME must match exactly, including case, as delete does; a miss is exit 1, and when a name differing only in case exists it is offered (“did you mean”). A NAME that looks like a flag is passed after –. --json gives one object: name, description, identifier_type, identifier_value, counts, and a list per kind. This is how to judge whether a kb concept suggest candidate is already covered, without raw SQL. See DR-0051 (knowledge/decisions/).

recall

read-only: find the concepts named in some text, then list the observations, records and document sections linked to them. Text comes from the arguments, or from stdin when the argument is -. –concept NAME,… names concepts directly (case-insensitive; an unknown name is skipped); given with text, the two are unioned. –project NAME restricts hits to one project (workspace-tier records are then excluded; an unknown project is exit 1). –limit N caps the hits (default 10). Output starts with a matched concepts: line, then one line per hit: kind, id, project, the matched concepts it links to, and an excerpt. Ranking is the number of matched concepts descending, then recency. Projects linked to a matched concept are listed on a projects: line, apart from the hits. Text that matches no concept says so and exits 1; no text and no –concept is exit 2. A document section’s excerpt is its summary only once reviewed. --json gives matched, hits (kind, id, project, concepts, excerpt) and projects. Nothing is written and no concept is created. It shares its ranking with the library’s RecallByConceptNames, which is unchanged and adds no project filter or per-hit concepts. See DR-0051 (knowledge/decisions/).

rename

rename a concept and reindex it for search. Refuses only if NEW already names another concept – unlike kb-project(1)’s rename, a concept has no corpus of external files to desync, since every link to it (record_concepts, observation_concepts, project_concepts, document_section_concepts) is a foreign key, never a name matched from a file. See DR-0024 (knowledge/decisions/).

delete

remove a concept, its links, and its search entry. NAME must match exactly, including case. A concept still linked to a project, observation, record or document section is refused (exit 1, the current state forbids it), with the counts, and nothing changes; –force unlinks it from all of them and deletes it (the projects, observations, records and documents themselves are untouched, only the links go). –dry-run reports what would happen and changes nothing. A NAME that looks like a flag (—, -x) is passed after –, as everywhere else. The concepts most worth deleting are junk ones minted from a documentation example, so this exists to remove them. See DR-0038 (knowledge/decisions/). Two things delete does not do, and prints a note about each. It does not touch files: a record or document that still contains [Name], or lists the name in tags or keywords, recreates the concept when that file is next ingested after it changes (an unchanged file is skipped) or when the database is rebuilt from the files, so remove the mention too. And it does not propagate: a database that still holds the concept brings it back on the next kb-merge(1) or kb-import(1) into this one, so delete it there as well.

suggest

read-only: scans every record body and document section body (scoped to one project with –project) and prints candidate new concepts, ranked by corpus-wide distinctiveness – a term mentioned several times but confined to relatively few items, rather than spread evenly across nearly all of them (not distinctive) or mentioned only once anywhere (too weak a signal alone). Code spans and fenced code blocks are excluded, a name already naming an existing concept is never suggested again, and a bare record reference (dr-0013, adr-0004) is filtered outright rather than scored. –limit caps the number printed (default 20). Never writes anything – a suggestion becomes a real concept only when a human runs concept add. See DR-0028 (knowledge/decisions/). Spelling variants of the same underlying term (chunking/ chunkings/chunked) are merged into one candidate before scoring, not after – individually each might fall below the occurrence or distinctiveness floor even though the combined mentions clearly signal one real concept. The merged candidate’s name is its highest- occurrence spelling; other spellings are printed inline, chunking (+chunkings, chunked). Always on, no flag. A candidate term that’s instead a fuzzy near-miss of an already-known concept is excluded from candidacy outright – that’s fuzzy-tag’s job, not this command’s – and reported separately in a trailing near-existing (excluded from candidates): section, printed only when non-empty. --json carries both: {"candidates": [...], "near_existing": [...]}. See DR-0034 (knowledge/decisions/).

CAVEATS

A description or name edited on two machines now reconciles: both kb-merge(1) and kb-import(1) adopt whichever side’s updated_at is later (DR-0025, generalized to name by DR-0026), so a concept renamed on one machine and left untouched on another arrives as one renamed concept, not two, regardless of merge/import order.

A deleted concept is not remembered. Deletion is local to one database: there is no tombstone, so kb-merge(1) and kb-import(1) treat a concept the other side still has as new and add it back. Under the authoritative agents/knowledge.jsonl flow (each machine rebuilds its database from the committed export) a deletion travels with the next export, provided every machine rebuilds before it exports.

EXIT STATUS

The workspace convention, as described in kb(1). For concept show and concept recall: 0 success; 1 no such concept (show), or no concept matched or no such project (recall); 2 a missing, surplus or malformed argument, an unknown flag, a negative or non-numeric –limit, or no text and no –concept; 66 no workspace here; 74 stdin could not be read.

SEE ALSO

kb-link(1), kb-project(1)