dsh-hypatia-auto-memory 0.1.1 → 0.3.0

package/lib/client.js

@@ -108,46 +108,46 @@ window.__ModuleLoader__.load({
 			document.head.appendChild(tag);
 		}
 		var SettingsCard_module_css_default = {
-			"headText": "YVNYya_headText",
-			"chevronOpen": "YVNYya_chevronOpen",
-			"chevron": "YVNYya_chevron",
+			"limitsTitle": "YVNYya_limitsTitle",
+			"modelGroup": "YVNYya_modelGroup",
 			"model": "YVNYya_model",
+			"headText": "YVNYya_headText",
+			"card": "YVNYya_card",
+			"readOnly": "YVNYya_readOnly",
+			"cardOpen": "YVNYya_cardOpen",
+			"hint": "YVNYya_hint",
+			"group": "YVNYya_group",
+			"label": "YVNYya_label",
+			"providerName": "YVNYya_providerName",
 			"catalogError": "YVNYya_catalogError",
-			"groupTitle": "YVNYya_groupTitle",
+			"chevronOpen": "YVNYya_chevronOpen",
+			"pending": "YVNYya_pending",
+			"unavailable": "YVNYya_unavailable",
 			"input": "YVNYya_input",
-			"header": "YVNYya_header",
-			"group": "YVNYya_group",
-			"advancedHint": "YVNYya_advancedHint",
-			"hint": "YVNYya_hint",
-			"modelSelection": "YVNYya_modelSelection",
-			"switch": "YVNYya_switch",
-			"readOnly": "YVNYya_readOnly",
-			"fieldHead": "YVNYya_fieldHead",
-			"switchOn": "YVNYya_switchOn",
 			"reset": "YVNYya_reset",
+			"description": "YVNYya_description",
 			"select": "YVNYya_select",
-			"card": "YVNYya_card",
-			"body": "YVNYya_body",
-			"cardOpen": "YVNYya_cardOpen",
-			"modelName": "YVNYya_modelName",
-			"limitsTitle": "YVNYya_limitsTitle",
-			"label": "YVNYya_label",
-			"pairedFields": "YVNYya_pairedFields",
-			"switchThumb": "YVNYya_switchThumb",
-			"status": "YVNYya_status",
-			"notice": "YVNYya_notice",
 			"field": "YVNYya_field",
-			"models": "YVNYya_models",
-			"providerName": "YVNYya_providerName",
+			"switchOn": "YVNYya_switchOn",
+			"advancedHint": "YVNYya_advancedHint",
 			"name": "YVNYya_name",
-			"description": "YVNYya_description",
-			"error": "YVNYya_error",
-			"warning": "YVNYya_warning",
+			"status": "YVNYya_status",
+			"switchThumb": "YVNYya_switchThumb",
 			"route": "YVNYya_route",
-			"unavailable": "YVNYya_unavailable",
+			"models": "YVNYya_models",
+			"groupTitle": "YVNYya_groupTitle",
+			"error": "YVNYya_error",
+			"modelSelection": "YVNYya_modelSelection",
 			"footer": "YVNYya_footer",
-			"pending": "YVNYya_pending",
-			"modelGroup": "YVNYya_modelGroup"
+			"pairedFields": "YVNYya_pairedFields",
+			"body": "YVNYya_body",
+			"modelName": "YVNYya_modelName",
+			"switch": "YVNYya_switch",
+			"chevron": "YVNYya_chevron",
+			"notice": "YVNYya_notice",
+			"header": "YVNYya_header",
+			"fieldHead": "YVNYya_fieldHead",
+			"warning": "YVNYya_warning"
 		};
 		//#endregion
 		//#region src/client/locales.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-hypatia-auto-memory",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Event-driven Hypatia memory for DSH: automatic conversation logging via session events, queued background consolidation (span summaries + work-unit extraction) with a dedicated model route, and recall injection — zero per-call model work in the main session.",
   "type": "module",
   "main": "src/index.js",
@@ -45,13 +45,13 @@
     "node": "^22.19.0 || >=24.0.0"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
-    "@deepseek-ai/dsh-storage-domain": "^0.1.2-rc.1",
     "@deepseek-ai/schemastery": "^3.18.2",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.2-rc.1",
     "react": "^18.2.0"
   },
   "devDependencies": {
@@ -64,6 +64,8 @@
     "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-rc.1",
     "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.2-rc.1",
     "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.2-rc.1",
     "@types/react": "^18.2.0",
     "lightningcss": "^1.32.0",
     "react": "^18.2.0",

package/skills/hypatia/SKILL.md

@@ -68,6 +68,38 @@ hypatia knowledge-create "prefer immutable" -d "always create new objects" --tag
 hypatia knowledge-create "no mock DB" -d "never mock database in tests" --tags "taboo" --scopes "my-project,"
 ```
 
+### Listing the scopes and tags already in use
+
+A scope or tag you invent is not an error — the entry is stored, and every later
+lookup by the value you meant misses it. Check before you write:
+
+```bash
+# What this shelf already uses, with how many entries carry each
+hypatia scope list --count
+hypatia tag list --count
+
+# Exact values, when you are going to write one back
+hypatia scope list --json      # [{"value":"","entries":12},{"value":"my-project",…}]
+
+# Confirm one spelling; exit 0 if in use, 1 if not
+hypatia tag exists rule
+hypatia scope exists my-project
+hypatia scope exists ""        # the global scope
+```
+
+The plain listing prints the global scope as `(global)`. That is a label for the
+terminal, not the value — the value is the empty string, and `--json` and
+`exists` both give it back verbatim. Never copy `(global)` into `--scopes`.
+
+Both cover knowledge and statements. An entry that declares no scopes at all is
+not listed as global.
+
+| User says | Command |
+|---|---|
+| "what scopes/projects are in here?" | `hypatia scope list --count` |
+| "what tags exist?" / "which labels are used?" | `hypatia tag list --count` |
+| "is there already a `rule` tag?" | `hypatia tag exists rule` |
+
 ## Knowledge CRUD
 
 Knowledge entries are independent information points with a name, content, and tags.
@@ -75,14 +107,17 @@ Knowledge entries are independent information points with a name, content, and t
 ### Create
 
 ```
-hypatia knowledge-create <name> -d "<data>" -t "<tag1,tag2>" --figures "archive://path/to/file"
+hypatia knowledge-create <name> -d "<data>" -t "<tag1,tag2>" --figures "archive://path/to/file" [--no-embed]
 ```
 
+`--no-embed` keeps the entry out of the vector index: it is still stored and still found by `search` and `query`, but it is never embedded, so it costs no model call on the way in and is not a `similar` result. Use it for raw session logs and other bulk that carries no distilled knowledge. A shelf can skip whole tags instead, with `embedding.skip_tags` in `shelf.toml`.
+
 | User says | Command |
 |---|---|
 | "remember Rust as a systems programming language" | `hypatia knowledge-create "Rust" -d "systems programming language" -t "language,compiled"` |
 | "save knowledge about Go with tags language and compiled" | `hypatia knowledge-create "Go" -d "" -t "language,compiled"` |
 | "store that Python is a scripting language, tag it as dynamic" | `hypatia knowledge-create "Python" -d "scripting language" -t "dynamic"` |
+| "log this turn but don't make it searchable by meaning" | `hypatia knowledge-create "msg-42" -d "<turn>" -t "message" --no-embed` |
 
 ### Read
 
@@ -97,9 +132,11 @@ hypatia knowledge-get <name>
 ### Update
 
 ```
-hypatia knowledge-update <name> [-d "<data>"] [-t "<tags>"] [--synonyms "<csv>"] [--figures "<refs>"] [--scopes "<scopes>"]
+hypatia knowledge-update <name> [-d "<data>"] [-t "<tags>"] [--synonyms "<csv>"] [--figures "<refs>"] [--scopes "<scopes>"] [--no-embed | --embed]
 ```
 
+`--no-embed` takes the entry out of the vector index and discards the vector it had; `--embed` puts it back, and it is embedded on the next flush. The two are mutually exclusive. `--embed` does not override the shelf's `embedding.skip_tags`: an entry can ask for less indexing than its shelf, never more.
+
 Only the fields you pass change. An omitted field keeps its stored value, and exactly `""` clears a field, such as `-t ""`; for tags, `","` or `" "` would store blank tags instead. `--scopes` replaces the stored scopes and is parsed as on create: end the list with a comma, such as `"q,"`, to include the global scope, or the entry drops out of global lookups. The entry keeps its `created_at`. Its old vector is discarded, and a new one is generated on the next flush, as after `knowledge-create`. Updating an entry that does not exist is an error. An update that changes nothing prints `Knowledge unchanged: <name>` and writes nothing.
 
 | User says | Command |
@@ -129,9 +166,11 @@ When the user asks to store or remember information, **always create statements
 **Pattern**: After creating a knowledge entry, identify entities mentioned in the content and create `$triple` relationships between them. At minimum, create one `is_a` statement for every new knowledge entry.
 
 ```
-hypatia statement-create <head> <relation> <tail> -d "<data>"
+hypatia statement-create <head> <relation> <tail> -d "<data>" [--no-embed]
 ```
 
+`--no-embed` works as it does on `knowledge-create`: the triple is still stored and still traversable, but gets no vector. Two differences: statements carry no tags, so a shelf's `embedding.skip_tags` cannot reach them and bulk links must say `--no-embed` themselves; and there is no `statement-update`, so the choice is made once at creation.
+
 ### Triple Extraction Patterns
 
 | User says | head | relation | tail |
@@ -341,19 +380,25 @@ hypatia search <query> [-c <catalog>] [--limit N] [--offset N]
 Semantic search using embedding vectors. Finds entries with similar meaning, even when keywords don't match.
 
 ```
-hypatia similar <query> [--limit N]
+hypatia similar <query> [--limit N] [-t knowledge|statement|both] [--tags <a,b>] [--exclude-tags <a,b>] [--where '<JSE condition>']
 ```
 
+`--tags` keeps entries carrying at least one of the tags, `--exclude-tags` drops entries carrying any of them, and `--where` takes a JSE condition such as `["$contains", "scopes", "project-a"]` (`$eq`, `$like`, `$contains`, `$and`/`$or`/`$not` and the other filters `$knowledge` takes, but not `$search`, `$similar` or `$k-hop`). They narrow the entries before ranking, so `--limit N` still returns N entries whenever that many qualify. `--exclude-tags message,summary,session` keeps the session-log layer from crowding out the knowledge distilled from it. With the default target `both` the filter applies to statements too, so a condition on `name` needs `-t knowledge`.
+
 Requires an embedding model configured in `shelf.toml` (default: BAAI/bge-m3).
 
 Entries are embedded in batches after they are written or updated. With a remote embedding API, `similar` can miss entries changed in the last minute; `search` finds them at once.
 
+Entries written with `--no-embed`, and entries carrying a tag the shelf lists in `embedding.skip_tags`, are never embedded and so are never `similar` results. `search` and `query` still find them. Each entry keeps the answer it was written with, so after changing `skip_tags` run `hypatia backfill` once to settle what is already stored.
+
 ### Examples
 
 | User says | Command |
 |---|---|
 | "find similar to distributed systems" | `hypatia similar "distributed systems"` |
 | "semantic search for memory management" | `hypatia similar "memory management" --limit 5` |
+| "what do we know about auth, not the chat logs" | `hypatia similar "auth" --exclude-tags message,summary,session` |
+| "rules like this one for project-a" | `hypatia similar "<rule text>" -t knowledge --tags rule --where '["$contains", "scopes", "project-a"]'` |
 
 ## JSE Query Translation
 
@@ -559,15 +604,17 @@ even read-only SQLite needs to create WAL/journal temp files next to the databas
 go straight to the immutable read-only URI, which needs no journal and no directory writes:
 
 ```bash
-sqlite3 "file:$HOME/.hypatia/default/hypatia.sqlite?mode=ro&immutable=1" "SELECT count(*) FROM knowledge;"
+sqlite3 "file:<shelf-dir>/hypatia.sqlite?mode=ro&immutable=1" "SELECT count(*) FROM knowledge;"
 ```
 
 - Use only for **reads** (SELECT). Never write through this path — `immutable=1` tells SQLite the
   file never changes, so writes would corrupt state or be lost.
-- Adjust the shelf path for non-default shelves (`~/.hypatia/<shelf>/<db>.sqlite`).
-- First, locate the actual DB file: `ls ~/.hypatia/*/` (also check `-wal`/`-shm` siblings; if a
-  WAL exists and is non-empty, `immutable=1` may miss recent un-checkpointed rows — in that case
-  prefer requesting wider sandbox permissions for a normal read instead).
+- First, get `<shelf-dir>` from `hypatia list`, which prints the directory each shelf is open at.
+  Do not assume `~/.hypatia/<shelf>/`: any shelf, `default` included, can be registered elsewhere.
+  If the CLI itself cannot run, read the paths from `~/.hypatia/shelves.json`.
+- Then check the `-wal`/`-shm` siblings; if a WAL exists and is non-empty, `immutable=1` may miss
+  recent un-checkpointed rows — in that case prefer requesting wider sandbox permissions for a
+  normal read instead.
 - Schema hints: tables include `knowledge` and `statement`; statement triples are stored in
   `head` / `relation` / `tail` columns.
 

package/skills/hypatia-memory/SKILL.md

@@ -25,6 +25,11 @@ Do not do these by hand — you would only create duplicates:
 - **Session seed.** Project and global entries tagged `rule` or `taboo` are
   injected into your context at session start. Nothing else is pushed to you.
 
+The log layer — `msg-*`, `session-*`, and the `belongTo` / `summary` edges —
+is written **without vectors** (`--no-embed`) on a hypatia that has the flag.
+It is stored and full-text searchable, but `similar` does not rank it. Entries
+logged before that, or by an older hypatia, still carry vectors.
+
 ## Which shelf
 
 The plugin writes to one hypatia shelf, chosen in its settings. When that is
@@ -47,7 +52,8 @@ costs a wrong answer that contradicts a decision already made.
 ### Semantic search — the default
 
 ```bash
-hypatia similar "<what you actually want to know>" -t knowledge --limit 20
+hypatia similar "<what you actually want to know>" -t knowledge --limit 5 \
+  --exclude-tags message,summary,session,hypatia-dream-run
 ```
 
 Write the query as the *idea* you are looking for, not the user's words verbatim.
@@ -55,8 +61,11 @@ Rows come back as `{"name", "content" (object), "distance"}`; lower `distance` i
 closer. If it exits non-zero with `model unavailable` / `no embedding provider`,
 this shelf has no embedding model — fall back to `search` and carry on.
 
-The limit is deliberately about four times the rows you want: most of what comes
-back will be the operational layer, which you then drop (see below).
+`--exclude-tags` leaves the operational layer out *before* ranking, so five rows
+asked for are five rows of knowledge. Add `--where '["$contains","scopes","<PROJECT>"]'`
+to stay inside this project. If the flag is rejected as an `unexpected argument`,
+the hypatia is older than #35: drop it, ask for `--limit 20`, and discard the
+operational rows yourself (see below).
 
 ### Keyword search — for exact identifiers
 
@@ -79,10 +88,21 @@ hypatia query '["$knowledge", ["$contains","tags","rule"],
 hypatia query '["$statement", ["$k-hop", "<entry-name>", "$*", 2]]'
 ```
 
-`<PROJECT>` is the basename of the workspace's git root (of the workspace
-itself outside git), written as the plugin writes it: commas become `_`,
-surrounding whitespace is dropped, and the filesystem root is `/`. Written raw,
-a name with a comma would be split into two scopes.
+`<PROJECT>` is the scope the plugin writes this workspace under: the basename
+of its git root (of the workspace itself outside git), with commas turned into
+`_`, surrounding whitespace dropped, and the filesystem root written `/`. You
+do not have to derive it — the plugin has already logged this session under it,
+so it is on the shelf:
+
+```bash
+hypatia scope list --count      # every scope in use, with how many entries carry it
+hypatia scope exists "<PROJECT>" # exit 0 if in use, 1 if not
+```
+
+The plain listing prints the global scope as `(global)`; that is a label, the
+value is `""`. Use `--json` when you will write a value back. Both need hypatia
+#30; an older one answers `unrecognized subcommand`, and then the rule above is
+all there is.
 
 ### Always exclude the operational layer
 
@@ -92,13 +112,14 @@ name starts with `msg-`, `sum`, `session-`, or `hypatia-dream-run-`, and rows
 tagged `message`, `session`, `summary`, or `hypatia-dream-run`. Read `wu-*`,
 `rule`, `taboo`, and ordinary named entries.
 
-Neither `similar` nor `search` can filter by name or tag, and that layer is most
-of the shelf — every message is logged. It also matches well: a raw `msg-*`
-holds the very words of the conversation you are asking about. Measured on a
-live shelf, 7 of the 10 nearest `similar` rows were operational, so a
-`--limit 5` search filtered afterwards leaves one row or none. Hence `--limit 20`. If too few rows
-survive the filter, search again with a larger limit or a different wording
-before concluding that nothing is stored.
+That layer is most of the shelf — every message is logged — and it matches
+well: a raw `msg-*` holds the very words of the conversation you are asking
+about. Measured on a live shelf, 7 of the 10 nearest `similar` rows were
+operational. `similar --exclude-tags` handles it; `search` has no such flag, and
+neither can see an operational entry that lost its tags, so still check names.
+Whenever you filter after the fact, ask for `--limit 20`, and if too few rows
+survive, search again with a larger limit or a different wording before
+concluding that nothing is stored.
 
 Reach into `msg-*` only when the user asks what was literally said, and prefer
 reaching it by walking `summary` statements down from a `sum-*` entry.
@@ -119,8 +140,14 @@ hypatia knowledge-create "<short-kebab-name>" \
   --scopes "<PROJECT>"
 ```
 
+- **Write the scope the plugin uses**, exactly. The session seed loads rules by
+  that spelling; a rule under `my-app` is invisible to a plugin that logs under
+  `my_app`. `hypatia scope list --count` shows it — the scope this project's
+  `msg-*` entries carry — and `hypatia scope exists "<PROJECT>"` confirms it
+  before you write.
 - `--tags rule` for conventions to follow, `taboo` for never-do items,
-  `memory` for durable facts.
+  `memory` for durable facts. Beyond those three, reuse what `hypatia tag list`
+  already shows before inventing a label.
 - **Scope syntax matters.** `--scopes "<PROJECT>"` is project-only.
   `--scopes "<PROJECT>,"` — with a *trailing comma* — also marks it global.
   `--scopes ""` writes no scope at all, which is not the same as global and will

package/src/cascade.js

@@ -179,8 +179,12 @@ export function createCascade({ cli, llm, selectRoute, getConfig, status }) {
       // under a different name and the first entry keeps only its partial set.
       // Nothing is lost — every member still ends up archived exactly once — but
       // the grouping boundary is not the one the first attempt intended.
+      // The archive entry is embedded — it is distilled knowledge, and the entry
+      // point for drilling down. Its edges are not: they are for the traversal
+      // and for `$not-summaried`, and nobody looks for a `summary` edge by
+      // meaning (see writer.js `writeSummary`).
       for (const member of members) {
-        await cli.statementCreate(name, 'summary', member, { scopes: [task.project] })
+        await cli.statementCreate(name, 'summary', member, { scopes: [task.project], embed: false })
       }
       status.info(`cascade: tier ${level} archived ${members.length} entries as ${name}`)
     }

package/src/collector.js

@@ -59,6 +59,26 @@ const RECORDED_TYPES = new Set([
   'tool/result',
 ])
 
+/**
+ * Whether an assistant/message event carries anything worth logging on its own.
+ *
+ * A turn that only issued tool calls (no text, no reasoning, no interruption
+ * marker) adds nothing to the conversation record — the tool outcomes already
+ * live in the session log if needed. Skipping these avoids msg-* entries whose
+ * entire body would be `(tool calls only)` or an empty placeholder.
+ *
+ * @param {any} event
+ * @returns {boolean}
+ */
+function hasAssistantContent(event) {
+  const blocks = event.data?.message?.content ?? []
+  for (const block of blocks) {
+    if (block.type === 'text' && String(block.text ?? '').trim() !== '') return true
+    if (block.type === 'image') return true
+  }
+  return false
+}
+
 /**
  * Whether this event becomes one `msg-*` entry.
  *
@@ -66,11 +86,17 @@ const RECORDED_TYPES = new Set([
  * output) are excluded: they are not things the human said, and re-logging them
  * would let memory amplify into itself.
  *
+ * Assistant turns whose only content is tool calls are also excluded: they have
+ * no substantive message to remember.
+ *
  * @param {any} event
  * @returns {boolean}
  */
 export function isLoggableMessage(event) {
-  if (event?.type === 'assistant/message') return true
+  if (event?.type === 'assistant/message') {
+    const interrupted = event.data?.interrupted === true
+    return interrupted || hasAssistantContent(event)
+  }
   return event?.type === 'user/message' && event.data?.source?.kind === 'user'
 }
 

package/src/config.js

@@ -35,7 +35,11 @@ export const DEFAULTS = {
     // User messages were never capped, so a pasted log went into hypatia whole.
     // Generous, because what the user typed is the part most worth keeping.
     maxUserChars: 32000,
-    toolLedger: true,
+    // Tool-call ledgers (name / count / success / duration) are intentionally
+    // off by default: they still reveal which tools were used and when, and the
+    // user has asked to avoid writing any tool-call-derived data to hypatia.
+    // Set this to true to restore the previous behavior.
+    toolLedger: false,
   },
   consolidation: {
     enabled: true,

package/src/consolidator.js

@@ -14,7 +14,7 @@
  * @module dsh-hypatia-auto-memory/consolidator
  */
 
-import { absolutizeDates, blocksToText, eventDate, flattenToolResult, redactSecrets } from './content-policy.js'
+import { absolutizeDates, blocksToText, eventDate, redactSecrets } from './content-policy.js'
 import { countLoggableMessages, isCompactionReplacement, isLoggableMessage } from './collector.js'
 import { messageName, summaryName } from './writer.js'
 import { EMPTY_PROGRESS, advanceProgress } from './progress.js'
@@ -178,8 +178,11 @@ export function buildTranscript(events, config, now = new Date(), { before } = {
       const callId = event.data?.message?.source?.callId
       const name = toolNames.get(callId) ?? 'tool'
       const ok = event.data?.error === undefined
-      const first = clean(flattenToolResult(event), event).split('\n')[0] ?? ''
-      entries.push({ seq: event.seq, line: `T: ${name} ${ok ? '✅' : '❌'} ${first}`.trimEnd() })
+      // Tool outputs are intentionally kept out of the consolidation transcript.
+      // The model only sees that a tool was called and whether it succeeded;
+      // the actual result text never reaches the remote model or the summaries
+      // and work units derived from it.
+      entries.push({ seq: event.seq, line: `T: ${name} ${ok ? '✅' : '❌'}` })
     }
   }
 

package/src/content-policy.js

@@ -277,7 +277,11 @@ export function blocksToText(blocks) {
   for (const block of blocks ?? []) {
     if (block.type === 'text') parts.push(block.text)
     else if (block.type === 'image') parts.push('[image]')
-    else if (block.type === 'thinking') parts.push(`[thinking: ${String(block.text ?? '').slice(0, 200)}]`)
+    // Thinking / reasoning blocks are internal monologue, not something the
+    // assistant said to the user. Including them created `[reasoning]`
+    // placeholder entries with no substantive content; skip them so only the
+    // final text / image output reaches the log.
+    else if (block.type === 'thinking' || block.type === 'reasoning') continue
     else if (block.type === 'tool-result') parts.push(blocksToText(block.content ?? []))
     // A tool-call block is the model asking for a tool, not something it said.
     // Rendered as `[tool-call]` it filled the content of half the stored

package/src/hypatia-cli.js

@@ -172,6 +172,56 @@ export function createHypatiaCli(ctx, config) {
     }
   }
 
+  /**
+   * What this binary can do beyond the baseline every call relies on.
+   *
+   * Read off `--help`, the one place clap states a flag's existence: an older
+   * binary answers an unknown flag with a usage error (exit 2) *instead of*
+   * running the command, so a write that guessed at `--no-embed` would fail
+   * outright on a binary from before hypatia #26, and a `similar` guessing at
+   * `--exclude-tags` on one from before #35. Both write commands are asked
+   * about `--no-embed` — they gained it together, but the answer is only worth
+   * having if it is true of each command it gates.
+   *
+   * @returns {Promise<{noEmbed: boolean, similarFilters: boolean}>}
+   */
+  async function probeFeatures() {
+    const [knowledge, statement, similar] = await Promise.all([
+      run(['knowledge-create', '--help']),
+      run(['statement-create', '--help']),
+      run(['similar', '--help']),
+    ])
+    for (const result of [knowledge, statement, similar]) {
+      if (result.exitCode !== 0) {
+        throw new HypatiaCliError(`hypatia --help exited ${result.exitCode}`, {
+          code: 'NONZERO_EXIT',
+          stderr: result.stderr.trim().slice(0, 500),
+          exitCode: result.exitCode,
+        })
+      }
+    }
+    return {
+      noEmbed: knowledge.stdout.includes('--no-embed') && statement.stdout.includes('--no-embed'),
+      similarFilters: similar.stdout.includes('--exclude-tags'),
+    }
+  }
+
+  /** The probe's answer, kept for the life of the client; a probe that failed is asked again. */
+  let featuresProbe
+
+  function features() {
+    if (featuresProbe === undefined) {
+      featuresProbe = probeFeatures().catch(() => {
+        // A binary that cannot even print its help fails the next real call
+        // with its own error; the answer here only decides which flags that
+        // call carries, and the conservative answer is none.
+        featuresProbe = undefined
+        return { noEmbed: false, similarFilters: false }
+      })
+    }
+    return featuresProbe
+  }
+
   /**
    * Whether stdout is hypatia's empty-result sentinel.
    *
@@ -196,6 +246,7 @@ export function createHypatiaCli(ctx, config) {
   return {
     run,
     runOk,
+    features,
 
     /**
      * Read one knowledge entry. Missing entries are a normal result, not an
@@ -211,7 +262,11 @@ export function createHypatiaCli(ctx, config) {
     },
 
     /**
-     * @param {{data: string, tags?: string[], scopes?: string[], shelf?: string}} entry
+     * `embed: false` keeps the entry out of the vector index (hypatia #26); on
+     * a binary without the flag it is dropped, and the entry is embedded as it
+     * always was.
+     *
+     * @param {{data: string, tags?: string[], scopes?: string[], embed?: boolean, shelf?: string}} entry
      * @returns {Promise<boolean>} true when this call created the entry.
      */
     async knowledgeCreate(name, entry) {
@@ -222,11 +277,15 @@ export function createHypatiaCli(ctx, config) {
       if (entry.data) argv.push(`--data=${fitDataArgument(entry.data)}`)
       if (entry.tags && entry.tags.length > 0) argv.push('--tags', entry.tags.join(','))
       if (entry.scopes && entry.scopes.length > 0) argv.push('--scopes', entry.scopes.join(','))
+      if (entry.embed === false && (await features()).noEmbed) argv.push('--no-embed')
       return runCreate(argv)
     },
 
     /**
-     * @param {{data?: string, scopes?: string[], shelf?: string}} [entry]
+     * `embed: false` as on `knowledgeCreate`. A statement has no update
+     * command, so the choice is made once, here.
+     *
+     * @param {{data?: string, scopes?: string[], embed?: boolean, shelf?: string}} [entry]
      * @returns {Promise<boolean>} true when this call created the triple.
      */
     async statementCreate(head, relation, tail, entry = {}) {
@@ -239,6 +298,7 @@ export function createHypatiaCli(ctx, config) {
       // expose to clap's flag parsing.
       if (entry.data) argv.push(`--data=${fitDataArgument(entry.data)}`)
       if (entry.scopes && entry.scopes.length > 0) argv.push('--scopes', entry.scopes.join(','))
+      if (entry.embed === false && (await features()).noEmbed) argv.push('--no-embed')
       return runCreate(argv)
     },
 
@@ -258,10 +318,18 @@ export function createHypatiaCli(ctx, config) {
     /**
      * Vector-similarity search — the recall path's primary ranking tool.
      * NOTE the flag is `-t/--target` (unlike keyword search's `-c`).
+     *
+     * `excludeTags` leaves entries carrying any of those tags out BEFORE the
+     * ranking (hypatia #35), so `limit` rows come back whenever that many
+     * qualify. A binary without the flag ranks everything; the caller reads
+     * `features()` to know whether it must over-fetch and filter instead.
+     *
      * @returns {Promise<any[]>}
      */
-    async similar(query, { target = 'knowledge', limit = 5, shelf = shelfOf() } = {}) {
-      const { stdout } = await runOk(['similar', query, '-t', target, '--limit', String(limit), '--shelf', shelf])
+    async similar(query, { target = 'knowledge', limit = 5, shelf = shelfOf(), excludeTags = [] } = {}) {
+      const argv = ['similar', query, '-t', target, '--limit', String(limit), '--shelf', shelf]
+      if (excludeTags.length > 0 && (await features()).similarFilters) argv.push('--exclude-tags', excludeTags.join(','))
+      const { stdout } = await runOk(argv)
       if (isEmptyResult(stdout)) return []
       const parsed = parseJson(stdout, 'similar')
       return Array.isArray(parsed) ? parsed : []

package/src/hypatia-client.js

@@ -54,7 +54,21 @@ export function createHypatiaClient(ctx, config, { status, connection }) {
     }
   }
 
+  /** Logged once, so the profile log says which flags this run's writes carry. */
+  let announced = false
+  async function features() {
+    const found = await via('features', [])
+    if (!announced) {
+      announced = true
+      const yes = (flag) => (flag ? 'yes' : 'no')
+      status.info?.(`hypatia over ${usesMcp() ? 'mcp' : 'cli'}: no-embed ${yes(found.noEmbed)}, similar filters ${yes(found.similarFilters)}`)
+    }
+    return found
+  }
+
   return {
+    /** What the binary can do beyond the baseline (see hypatia-cli.js `features`). */
+    features,
     knowledgeGet: (...args) => via('knowledgeGet', args),
     knowledgeCreate: (...args) => via('knowledgeCreate', args),
     statementCreate: (...args) => via('statementCreate', args),