Knowledge

The learning loop's visible surface. As the engine works, it captures experience; the lessons distilled from it live in a plain-text insight store beside your model, which you own and can read without us. A deterministic model fingerprint surfaces the relevant lessons when you open a model of the same shape. Capture and recall are free.

#In the Studio

The Knowledge pane has three sections. Insights lists both scopes with kind and scope pills, match-key chips, and score, retrievals and uses counters, with expandable provenance and inline upvote, downvote, edit and delete, plus a pending-approval subsection. Learned workflows shows the playbooks distilled from successful runs, each with a Check button that runs the admission dry-run. Recall preview is a query box that runs recall against the open model and shows the ranked candidates and the model fingerprint card. A scoped purge (review the count, then confirm) rounds it out.

#Over MCP

All of the knowledge tools are free. The typical loop is recall before starting, record a lesson after.

recall_experience query="..."         # ranked prior lessons for THIS model's shape
get_model_fingerprint                  # the deterministic fingerprint (no embeddings)
add_insight text="..." keys=[...]      # record one actionable lesson (lands pending)
approve_insight <id>                   # release it so recall can surface it
list_insights                          # the live set with counters + provenance
upvote_insight / downvote_insight      # the importance counter (you judge, engine counts)
edit_insight / purge_knowledge         # refine one, or scoped one-op purge (dry-run first)

#The insight store is yours

Insights are your own data: a plain text log (JSONL) in .semanticus/knowledge/insights.jsonl for the project scope and ~/.semanticus/knowledge/ for the global scope. The store is readable without Semanticus and is never rewritten: every change (an edit, a downvote, a purge) is a delta appended to the file, which is the constraint against context collapse. Every record carries provenance (who, when, which session and source runs).

#A write-gate, counters, and clean removal

add_insight lands an insight as pending; approve_insight releases it so recall_experience can surface it. Each insight carries a score, a uses count and a retrievals count. upvote_insight and downvote_insight move the importance counter (you judge, the engine counts); when a score falls to zero the insight is materialized out of the live set while the delta trail is kept. Nothing is ever erased in place.

#Fingerprint recall, no inference

get_model_fingerprint computes the open model's deterministic fingerprint: table, measure and column counts, source types, fact and dimension classification, a naming-convention hash and the top domain-word tokens. There are no embeddings and no inference. recall_experience reads both scopes' approved insights and returns a deterministically ranked candidate set (key-term overlap with your query, a same-shape bonus, importance and temporal decay), each with the keys it matched on. It is retrieval, not judgment: the assistant does the semantic ranking over the candidates and decides what applies, and the engine says so plainly when there is no prior experience for a shape.

#Purge on your terms

purge_knowledge is the scoped one-op safety valve. It is dry-run by default: with confirm=false it reports how many live insights would be erased and changes nothing; confirm=true appends a purge marker so everything before it in that scope becomes invisible on replay. As with everything here, the file itself is not rewritten.