How it works

The answer path

The READ side. When the agent layer gets a question, it calls one endpoint — /retrieve — and gets back matching knowledge plus the principal's reasoning patterns. This path never writes knowledge.

Question to response

When the agent layer calls POST /retrieve with {question, asker, top_n}:

  1. Embed the question with the same local model used at ingestion, so query and stored knowledge live in the same vector space.

  2. Semantic search. A cosine-similarity scan over active, public entries returns the closest top_n, each with a relevance_score in [0,1].

  3. Re-rank. Raw similarity is not the whole story. Each result is rescored as a weighted blend — relevance 0.6, type 0.15, confidence 0.15, freshness 0.10 — so a transferable framework can outrank a one-off reaction that happens to be slightly more similar.

  4. Strong-match verdict. If the best relevance is at or above 0.68, strong_match = true (a near-direct answer exists — the agent can quote it). If below, strong_match = false, and the agent switches to extrapolation mode: reason from patterns instead of quoting.

  5. Attach reasoning patterns. The 4-or-fewer patterns most relevant to this question (not the whole set), each with its context variants.

  6. Log the interaction (for the daily report and thumbs up/down feedback) and return.

The strong_match flag drives agent behavior

strong_match What it means What the agent does
true A direct, high-confidence hit exists. Answer confidently, grounded in the entries' position + reasoning.
false No strong direct match. Switch to extrapolation mode — reason in the principal's style from reasoning_patterns (check each pattern's variants[] for one matching the asker's situation first). A good place to hedge or offer to check with the principal.

Why 0.68 and not something like 0.82

The local embedding model's cosine similarity tops out around 0.70 even for a dead-on match, so a higher bar was literally unreachable. 0.68 is a deliberately-tuned placeholder, to be locked precisely with a reference-question sweep later.

For the exact request and response shapes, see the API reference.

← Previous
Reasoning patterns