dsh-hypatia-auto-memory 0.1.1 → 0.2.0

package/README.md

@@ -24,7 +24,12 @@ ships here: auto-approval for the agent's own bash `hypatia` calls, and its
 
 Prerequisite: `hypatia` CLI on PATH (or add its basename to `binaries`). A
 build with the `mcp` subcommand (hypatia #20) is used over MCP; an older one
-works through the CLI instead, with one warning at the first call.
+works through the CLI instead, with one warning at the first call. Two later
+additions are used when the binary has them and skipped when it does not:
+`--no-embed` (hypatia #26) keeps the log layer out of the vector index, and
+`similar --exclude-tags` (#35) keeps it out of the work-unit candidate search.
+The first call logs which the binary offers
+(`hypatia over mcp: no-embed yes, similar filters yes`).
 
 ```bash
 # from a local checkout (development)
@@ -129,6 +134,19 @@ agent/session-start ──▶ rules/taboos inject()
   `(tool calls only)`. Plugin-sourced
   messages are skipped — no feedback loops.
 
+- **The log layer is not embedded.** `msg-*` and `session-*` entries and the
+  `belongTo` / `summary` edges are written `embed: false` (hypatia #26): stored,
+  full-text indexed and reachable by JSE, but given no vector. The protocol has
+  precise recall drill down from a summary along `summary` edges rather than
+  hit raw messages by meaning, and embedded, a raw message outranks the
+  knowledge distilled from it because it holds the very words. On the shelf
+  this was measured on the layer was 85% of entries and 77% of statements, each
+  costing a forward pass on the conversation's hot path. Summaries and work
+  units are embedded as before. Statements have no tags, so a shelf's
+  `embedding.skip_tags` could not have reached the edges; the plugin says so per
+  write. On a binary without the flag the transport drops it and everything is
+  embedded as it always was.
+
   Spans are cut at `turn/end`, and — for a turn that outlasts `flushWindowMs` —
   at `step/end`, never at an arbitrary moment. DSH appends `assistant/message`
   *before* running the tools it requested and `step/end` only after they have
@@ -164,8 +182,10 @@ agent/session-start ──▶ rules/taboos inject()
   previous tier already distilled.
 
 - **Work units** are adjudicated, not guessed. Candidates come from `similar`
-  (the only search that reports a distance), filtered by a distance ceiling and
-  by an exclusion list for the operational layer, then a small model call
+  (the only search that reports a distance), with the operational layer left
+  out — in the query, by `--exclude-tags`, on a binary that has it (hypatia
+  #35); by fetching four times as many rows and dropping them on one that does
+  not — and filtered by a distance ceiling, then a small model call
   decides `duplicate | refines | extends | supersedes | contradicts | unrelated`.
   A contradiction keeps **both** entries and records `supersedes` — a memory
   system must not quietly forget what it once believed.
@@ -335,7 +355,12 @@ changes. No card claims it, so it renders nowhere; nothing ever writes to it.
    (get-before-create); uncovered ranges are re-enqueued from watermarks.
 4. To check the route warning: consolidation with no selected `models`
    logs a one-time warning and otherwise stays silent.
-5. Uninstall: `dsh plugin --profile web remove dsh-hypatia-auto-memory` —
+5. `hypatia backfill --status` reports the shelf's embedding debt. With a
+   current hypatia, logging a turn adds nothing to it; only summaries and work
+   units are pending until the next flush. `hypatia scope list --count` shows
+   the scopes in use — the one this project's `msg-*` entries carry is the one
+   the session seed reads.
+6. Uninstall: `dsh plugin --profile web remove dsh-hypatia-auto-memory` —
    hypatia entries themselves are left in `~/.hypatia/`.
 
 ## Failure modes
@@ -347,7 +372,8 @@ changes. No card claims it, so it renders nowhere; nothing ever writes to it.
 | Entries appear only after a turn finishes | By design: spans are cut at `turn/end`, or at the first `step/end` once a turn has run longer than `flushWindowMs`, so an entry never lacks its own tool results |
 | Logging works, no summaries | `consolidation.models` is empty or invalid — one warning at first trigger |
 | Summaries but no `sum2-*` | Fewer than `cascade.batchSize` unarchived tier-1 summaries in that project yet |
-| Work units have no relationships | No embedding model on the shelf (`similar` fails), or every candidate was beyond `dedupMaxDistance` |
+| Work units have no relationships | No embedding model on the shelf (`similar` fails), or every candidate was beyond `dedupMaxDistance`. Since hypatia #19 the local model is looked up in `~/.hypatia/models/<org>/<name>` (or the Hugging Face cache), no longer beside the shelf: a shelf that used to answer `similar` and now says `is not installed` needs `hypatia model install <model>`, or `hypatia model register <model> <dir>` pointing at the files it already has |
+| `similar` still returns `msg-*` rows | They were written before this plugin opted the log layer out of embedding, or by a hypatia without `--no-embed`. Retract the knowledge vectors once with `embedding.skip_tags = ["message", "session"]` in the shelf's `shelf.toml` followed by `hypatia backfill` (a binary older than the key refuses to open the shelf, so upgrade every binary sharing it first). Statements have no tags and no update command, so `belongTo` / `summary` edges written before keep their vectors |
 | Task in `deferred` state | Neither the live store nor persistence could supply its session. Not an error: it spends no attempts and runs as soon as one of them can. Normally storage answers immediately — the state persists only when `sessionPersistence` is absent from the composition, or its read failed (look for `could not be read` in the log) |
 | Task in `failed` state | A hypatia or model error persisted after `maxAttempts`. Failed `log-message` records are pruned at the next startup, since the watermark re-derives their range; other kinds are kept for inspection — delete one to let the next trigger re-create it |
 | Watermark says logged, but the shelf has no entries | The shelf was reset or switched after logging. Handled at startup: `housekeeping.reconcileOnStartup` resets any row whose session has no `msg-*` left, and that session is re-logged — and re-consolidated — from the start on its next activity. A shelf query that fails leaves the row untouched. A session whose messages were all deleted on purpose is indistinguishable and is logged again; turn the switch off if that matters |
@@ -359,7 +385,7 @@ changes. No card claims it, so it renders nowhere; nothing ever writes to it.
 | The agent's own `hypatia` write still asks for approval | `autoApprove: false` (needs a profile reload to change), the command pipes/redirects/chains outside quotes, or its first word is not one of `binaries` — only plain calls are answered, by design. Reads never reach approval at all, so nothing to fix there |
 | The agent got a memory protocol that tells it to log messages by hand | Another plugin registered `hypatia-memory` first (`dsh-hypatia` still in the profile), or a `hypatia-memory` exists on disk — typically `~/.agents/skills/hypatia-memory`, written by `hypatia skill install --agent codex`. Agent presets load disk skills in a layer nearer than plugins, so it wins in sessions even though the skill center may list this plugin. Remove the copy the startup warning names |
 | Startup warnings never appear in the terminal | `dsh web` mounts no log exporter, so plugin log lines of any level go nowhere; the console exporter's default threshold would also drop warnings (warn is level 2, above info's 1). Mount a logger such as `dsh-logbook` or `dsh-boot-doctor` temporarily to read them |
-| Project scope looks wrong | Scope = basename of the session cwd's git top level (`git rev-parse --show-toplevel`), or of the cwd itself when git finds no work tree or cannot answer (not installed, a repo it refuses as unsafe). A `rev-parse` slower than 3 s leaves that one session on the cwd's own name. Two same-named checkouts share a scope by design; a linked worktree is scoped by its own directory, not the main checkout's; git resolves symlinks, so a checkout opened through a link named differently from its target gets the target's name. A name hypatia would rewrite is normalized first: a session at `/` is scoped `/`, commas become `_`, surrounding whitespace goes. Entries written before these fixes stay where they were stored: a subdirectory session's under that directory's name (`repo/src` wrote under `src` — the git root was never read), a session at `/` with no scope, `a,b` under both `a` and `b`, `foo,` under `foo` and global. Padded names were stored trimmed, which is what the query now asks for. Nothing migrates them; `knowledge-update --scopes` moves one entry and keeps its `created_at` |
+| Project scope looks wrong | Scope = basename of the session cwd's git top level (`git rev-parse --show-toplevel`), or of the cwd itself when git finds no work tree or cannot answer (not installed, a repo it refuses as unsafe). A `rev-parse` slower than 3 s leaves that one session on the cwd's own name. Two same-named checkouts share a scope by design; a linked worktree is scoped by its own directory, not the main checkout's; git resolves symlinks, so a checkout opened through a link named differently from its target gets the target's name. A name hypatia would rewrite is normalized first: a session at `/` is scoped `/`, commas become `_`, surrounding whitespace goes. Entries written before these fixes stay where they were stored: a subdirectory session's under that directory's name (`repo/src` wrote under `src` — the git root was never read), a session at `/` with no scope, `a,b` under both `a` and `b`, `foo,` under `foo` and global. Padded names were stored trimmed, which is what the query now asks for. Nothing migrates them; `knowledge-update --scopes` moves one entry and keeps its `created_at`. `hypatia scope list --count` (hypatia #30) shows every spelling in use and how many entries each holds |
 
 ## Known limitations
 
@@ -392,6 +418,12 @@ Deliberate, and worth knowing before you rely on them:
   exits 0 with `Statement already exists`); on an older binary the same
   error-text path covers it. The matching is confined to one function, and
   `test/integration` accepts either statement behaviour.
+- **What was embedded stays embedded.** The log layer opts out of the vector
+  index at write time, so entries and edges written before this version, or by
+  a hypatia without `--no-embed`, keep their vectors and keep surfacing in
+  `similar`. `skip_tags` + `backfill` retracts the knowledge entries' (see
+  *Failure modes*); the edges have no retraction path short of deleting and
+  recreating them, which the plugin does not do.
 - **Adjudication and dedup need an embedding model.** On a shelf without one,
   `similar` fails outright and work units are stored with no relationship —
   never dropped.

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",
-			"model": "YVNYya_model",
-			"catalogError": "YVNYya_catalogError",
-			"groupTitle": "YVNYya_groupTitle",
-			"input": "YVNYya_input",
-			"header": "YVNYya_header",
-			"group": "YVNYya_group",
-			"advancedHint": "YVNYya_advancedHint",
 			"hint": "YVNYya_hint",
-			"modelSelection": "YVNYya_modelSelection",
-			"switch": "YVNYya_switch",
+			"field": "YVNYya_field",
 			"readOnly": "YVNYya_readOnly",
-			"fieldHead": "YVNYya_fieldHead",
-			"switchOn": "YVNYya_switchOn",
-			"reset": "YVNYya_reset",
 			"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",
+			"pairedFields": "YVNYya_pairedFields",
+			"fieldHead": "YVNYya_fieldHead",
+			"modelName": "YVNYya_modelName",
 			"status": "YVNYya_status",
+			"switchOn": "YVNYya_switchOn",
+			"headText": "YVNYya_headText",
+			"chevron": "YVNYya_chevron",
+			"footer": "YVNYya_footer",
+			"unavailable": "YVNYya_unavailable",
+			"modelSelection": "YVNYya_modelSelection",
+			"chevronOpen": "YVNYya_chevronOpen",
+			"body": "YVNYya_body",
+			"error": "YVNYya_error",
+			"modelGroup": "YVNYya_modelGroup",
+			"card": "YVNYya_card",
+			"warning": "YVNYya_warning",
+			"switch": "YVNYya_switch",
 			"notice": "YVNYya_notice",
-			"field": "YVNYya_field",
+			"limitsTitle": "YVNYya_limitsTitle",
+			"reset": "YVNYya_reset",
+			"description": "YVNYya_description",
+			"group": "YVNYya_group",
+			"name": "YVNYya_name",
+			"advancedHint": "YVNYya_advancedHint",
 			"models": "YVNYya_models",
+			"catalogError": "YVNYya_catalogError",
+			"label": "YVNYya_label",
 			"providerName": "YVNYya_providerName",
-			"name": "YVNYya_name",
-			"description": "YVNYya_description",
-			"error": "YVNYya_error",
-			"warning": "YVNYya_warning",
-			"route": "YVNYya_route",
-			"unavailable": "YVNYya_unavailable",
-			"footer": "YVNYya_footer",
+			"cardOpen": "YVNYya_cardOpen",
 			"pending": "YVNYya_pending",
-			"modelGroup": "YVNYya_modelGroup"
+			"route": "YVNYya_route",
+			"groupTitle": "YVNYya_groupTitle",
+			"model": "YVNYya_model",
+			"input": "YVNYya_input",
+			"header": "YVNYya_header"
 		};
 		//#endregion
 		//#region src/client/locales.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-hypatia-auto-memory",
-  "version": "0.1.1",
+  "version": "0.2.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/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),

package/src/hypatia-mcp.js

@@ -50,6 +50,27 @@ export const REQUIRED_TOOLS = Object.freeze([
   'query',
 ])
 
+/**
+ * What a server can do beyond REQUIRED_TOOLS, read off the schemas in its
+ * `tools/list`. Every tool declares `additionalProperties: false`, so an
+ * argument a server does not list fails the call as a validation error rather
+ * than being ignored — which is why the plugin asks first instead of trying.
+ * The names mirror hypatia-cli.js's `features()`.
+ *
+ * @param {Array<{name?: string, inputSchema?: {properties?: object}}>} tools
+ * @returns {{noEmbed: boolean, similarFilters: boolean}}
+ */
+export function featuresOf(tools) {
+  const accepts = (name, argument) => Object.hasOwn(
+    tools.find((tool) => tool?.name === name)?.inputSchema?.properties ?? {},
+    argument,
+  )
+  return {
+    noEmbed: accepts('knowledge_create', 'embed') && accepts('statement_create', 'embed'),
+    similarFilters: accepts('similar', 'exclude_tags'),
+  }
+}
+
 /**
  * One request line. A lone UTF-16 surrogate — what a `.slice()` through an
  * emoji leaves behind — is written by `JSON.stringify` as a bare `\ud83d`
@@ -255,11 +276,13 @@ export function createMcpConnection(ctx, options) {
       }, handshakeTimeoutMs)
       conn.handle.stdin.write(encode({ jsonrpc: '2.0', method: 'notifications/initialized' }))
       const listed = await request(conn, 'tools/list', {}, handshakeTimeoutMs)
-      const names = new Set((listed?.tools ?? []).map((tool) => tool?.name))
+      const tools = listed?.tools ?? []
+      const names = new Set(tools.map((tool) => tool?.name))
       const missing = REQUIRED_TOOLS.filter((name) => !names.has(name))
       if (missing.length > 0) {
         throw new HypatiaCliError(`hypatia mcp lacks ${missing.join(', ')}`, { code: 'MCP_UNAVAILABLE' })
       }
+      conn.features = featuresOf(tools)
     } catch (error) {
       kill(conn, error)
       if (!isUnavailable(error)) throw error
@@ -282,6 +305,37 @@ export function createMcpConnection(ctx, options) {
     idleTimer.unref?.()
   }
 
+  /**
+   * Run `step` against a live, handshaken process, after the steps before it.
+   * @template T
+   * @param {(conn: object) => Promise<T>} step
+   * @returns {Promise<T>}
+   */
+  function withProcess(step) {
+    const run = async () => {
+      if (disposed) throw new HypatiaCliError('hypatia mcp connection disposed', { code: 'MCP_CLOSED' })
+      if (unavailable !== undefined) throw unavailable
+      clearTimeout(idleTimer)
+      try {
+        if (current === undefined || current.closed) {
+          const conn = await open()
+          // Disposed during the handshake: nothing else would close it.
+          if (disposed) {
+            close(conn)
+            throw new HypatiaCliError('hypatia mcp connection disposed', { code: 'MCP_CLOSED' })
+          }
+          current = conn
+        }
+        return await step(current)
+      } finally {
+        if (!disposed) armIdle()
+      }
+    }
+    const result = chain.then(run, run)
+    chain = result.catch(() => {})
+    return result
+  }
+
   return {
     /**
      * One `tools/call`, after the calls before it.
@@ -290,31 +344,21 @@ export function createMcpConnection(ctx, options) {
      * @returns {Promise<any>} the MCP `CallToolResult`, `isError` included.
      */
     call(name, args) {
-      const run = async () => {
-        if (disposed) throw new HypatiaCliError('hypatia mcp connection disposed', { code: 'MCP_CLOSED' })
-        if (unavailable !== undefined) throw unavailable
-        clearTimeout(idleTimer)
-        try {
-          if (current === undefined || current.closed) {
-            const conn = await open()
-            // Disposed during the handshake: nothing else would close it.
-            if (disposed) {
-              close(conn)
-              throw new HypatiaCliError('hypatia mcp connection disposed', { code: 'MCP_CLOSED' })
-            }
-            current = conn
-          }
-          // An error quotes what this call made the process write, not what
-          // earlier calls did. The handshake's errors quote everything.
-          current.stderrMark = current.handle.collected.stderr?.readFrom(0).nextOffset ?? 0
-          return await request(current, 'tools/call', { name, arguments: args }, timeoutMs)
-        } finally {
-          if (!disposed) armIdle()
-        }
-      }
-      const result = chain.then(run, run)
-      chain = result.catch(() => {})
-      return result
+      return withProcess((conn) => {
+        // An error quotes what this call made the process write, not what
+        // earlier calls did. The handshake's errors quote everything.
+        conn.stderrMark = conn.handle.collected.stderr?.readFrom(0).nextOffset ?? 0
+        return request(conn, 'tools/call', { name, arguments: args }, timeoutMs)
+      })
+    },
+
+    /**
+     * What the server can do beyond REQUIRED_TOOLS (see `featuresOf`), from
+     * the handshake — starting the process if none is running.
+     * @returns {Promise<{noEmbed: boolean, similarFilters: boolean}>}
+     */
+    features() {
+      return withProcess((conn) => Promise.resolve(conn.features))
     },
 
     /** Drop the process; the next call starts a fresh one. */
@@ -438,23 +482,32 @@ export function createHypatiaMcp(connection, config) {
       }
     },
 
+    features: () => connection.features(),
+
     /**
-     * @param {{data: string, tags?: string[], scopes?: string[], shelf?: string}} entry
+     * `embed: false` keeps the entry out of the vector index (hypatia #26); a
+     * server whose `knowledge_create` does not list the argument would reject
+     * it, so there it is dropped and the entry is embedded as before.
+     *
+     * @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) {
       const args = { name, shelf: entry.shelf ?? shelfOf() }
       if (entry.data) args.data = entry.data
+      if (entry.embed === false && (await connection.features()).noEmbed) args.embed = false
       return (await create('knowledge_create', lists(args, entry))) !== undefined
     },
 
     /**
-     * @param {{data?: string, scopes?: string[], shelf?: string}} [entry]
+     * `embed: false` as on `knowledgeCreate`.
+     * @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 = {}) {
       const args = { head, relation, tail, shelf: entry.shelf ?? shelfOf() }
       if (entry.data) args.data = entry.data
+      if (entry.embed === false && (await connection.features()).noEmbed) args.embed = false
       const outcome = await create('statement_create', lists(args, { scopes: entry.scopes }))
       return outcome !== undefined && outcome.created !== false
     },
@@ -464,9 +517,17 @@ export function createHypatiaMcp(connection, config) {
       return rowsOf(await invoke('search', { query, catalog, limit, shelf }))
     },
 
-    /** Vector-similarity search; rows as the CLI prints them. */
-    async similar(query, { target = 'knowledge', limit = 5, shelf = shelfOf() } = {}) {
-      return rowsOf(await invoke('similar', { query, target, limit, shelf }))
+    /**
+     * Vector-similarity search; rows as the CLI prints them. `excludeTags`
+     * narrows the entries before they are ranked (hypatia #35) and is dropped
+     * on a server that does not list it, as on the CLI.
+     */
+    async similar(query, { target = 'knowledge', limit = 5, shelf = shelfOf(), excludeTags = [] } = {}) {
+      const args = { query, target, limit, shelf }
+      if (excludeTags.length > 0 && (await connection.features()).similarFilters) {
+        args.exclude_tags = asCliList(excludeTags)
+      }
+      return rowsOf(await invoke('similar', args))
     },
 
     /** Raw JSE query; `jse` is the JSON text the CLI would take as its argument. */

package/src/writer.js

@@ -29,11 +29,19 @@ const OPERATIONAL_PREFIXES = ['msg-', 'sum', 'session-', 'hypatia-dream-run-']
 const OPERATIONAL_TAGS = new Set(['message', 'session', 'hypatia-dream-run'])
 
 /**
- * How many rows to ask `similar` for per candidate actually wanted.
+ * The same layer as tags `similar` can be told to leave out (hypatia #35).
+ * `summary` alone covers every summary tier: each carries it beside its
+ * `summary <N>` tag.
+ */
+export const EXCLUDED_TAGS = Object.freeze([...OPERATIONAL_TAGS, 'summary'])
+
+/**
+ * How many rows to ask `similar` for per candidate actually wanted, on a
+ * binary whose `similar` cannot exclude tags.
  *
- * The operational layer cannot be excluded in the query (see `findCandidates`),
- * outnumbers knowledge on an active shelf, and ranks nearer, so the fetch has
- * to absorb it. Four covers the measured 7-in-10 ratio with room to spare.
+ * There the operational layer is ranked along with everything else, outnumbers
+ * knowledge on an active shelf, and ranks nearer, so the fetch has to absorb
+ * it. Four covers the measured 7-in-10 ratio with room to spare.
  */
 const CANDIDATE_OVERSAMPLE = 4
 
@@ -113,6 +121,13 @@ export function createWriter(cli, { status, adjudicate }) {
    * from a replayed task) are counted and skipped — the watermark must still
    * advance past them, which the queue does based on the resolved range.
    *
+   * Written with `embed: false`: the log layer is not on the retrieval hot
+   * path — `docs/memory-nolinear.md` has precise recall drill down from a
+   * summary along `summary` edges — and embedded, a raw message outranks the
+   * knowledge distilled from it, because it holds the very words. It stays
+   * stored and full-text searchable; only the vector is not made. On a binary
+   * without `--no-embed` the flag is dropped by the transport.
+   *
    * @param {{sessionId: string, index: number, markdown: string, project: string}} entry
    */
   async function writeMessage({ sessionId, index, markdown, project }) {
@@ -122,7 +137,7 @@ export function createWriter(cli, { status, adjudicate }) {
       status.count('duplicate')
       return { name, written: false }
     }
-    await cli.knowledgeCreate(name, { data: markdown, tags: ['message'], scopes: [project] })
+    await cli.knowledgeCreate(name, { data: markdown, tags: ['message'], scopes: [project], embed: false })
     status.count('written')
     return { name, written: true }
   }
@@ -147,6 +162,11 @@ export function createWriter(cli, { status, adjudicate }) {
    *   permanent. `statementCreate` swallows primary-key collisions, so
    *   re-asserting an existing edge is free.
    *
+   * The summary itself is embedded — it is distilled knowledge and the entry
+   * point for drilling down. Its edges are written `embed: false`: they exist
+   * for the traversal and for `$not-summaried`, and statements carry no tags,
+   * so a shelf's `embedding.skip_tags` could not reach them.
+   *
    * @param {{sessionId: string, fromSeq: number, toSeq: number, markdown: string,
    *          project: string, items?: readonly string[], level?: number}} entry
    * `level` is the archive tier this summary sits at (1 = summarises messages).
@@ -168,7 +188,7 @@ export function createWriter(cli, { status, adjudicate }) {
       status.count('written')
     }
     for (const item of items) {
-      await cli.statementCreate(name, 'summary', item, { scopes: [project] })
+      await cli.statementCreate(name, 'summary', item, { scopes: [project], embed: false })
     }
     return { name, written: existing.found === false, links: items.length }
   }
@@ -184,6 +204,10 @@ export function createWriter(cli, { status, adjudicate }) {
    * hypatia has no `knowledge-update`, so a second title cannot replace the
    * first; the original stands and the caller is told nothing was written.
    *
+   * Node and `belongTo` edges are written `embed: false`, as the messages are:
+   * the node is bookkeeping for the traversal, and its title is what
+   * `session/title` already gave DSH.
+   *
    * @param {{sessionId: string, markdown: string, project: string,
    *          linkFrom: number, linkTo: number}} entry - `[linkFrom, linkTo)` is
    * the half-open range of message ordinals still needing a `belongTo` edge.
@@ -200,11 +224,11 @@ export function createWriter(cli, { status, adjudicate }) {
       // it absent and drop the edges with it.
       return { name, written: false, links: 0 }
     } else {
-      await cli.knowledgeCreate(name, { data: markdown, tags: ['session'], scopes: [project] })
+      await cli.knowledgeCreate(name, { data: markdown, tags: ['session'], scopes: [project], embed: false })
       status.count('written')
     }
     for (let index = linkFrom; index < linkTo; index += 1) {
-      await cli.statementCreate(messageName(sessionId, index), 'belongTo', name, { scopes: [project] })
+      await cli.statementCreate(messageName(sessionId, index), 'belongTo', name, { scopes: [project], embed: false })
     }
     return { name, written: existing.found === false, links: Math.max(0, linkTo - linkFrom) }
   }
@@ -220,19 +244,24 @@ export function createWriter(cli, { status, adjudicate }) {
    */
   async function findCandidates(unit, name, { maxDistance, limit }) {
     try {
-      // OVERSAMPLED, because the exclusion below cannot be pushed into the
-      // query: `hypatia similar` takes only target/limit/shelf, no tag or scope
-      // filter. The operational layer is the majority of an active shelf (101
-      // of 183 knowledge entries on the profile this was measured on) and it
-      // scores CLOSER than real knowledge — a raw `msg-*` holds the very words
-      // of the conversation the unit was extracted from. Measured: 7 of the
-      // nearest 10 rows were operational, so asking for 5 and filtering
-      // afterwards left one candidate, often none, and adjudication silently
-      // degraded to "no relationship" on every write.
+      // The operational layer is excluded IN the query where the binary allows
+      // it (hypatia #35), and over-fetched around where it does not. It is the
+      // majority of an active shelf (101 of 183 knowledge entries on the
+      // profile this was measured on) and it scores CLOSER than real knowledge
+      // — a raw `msg-*` holds the very words of the conversation the unit was
+      // extracted from. Measured: 7 of the nearest 10 rows were operational, so
+      // asking for 5 and filtering afterwards left one candidate, often none,
+      // and adjudication silently degraded to "no relationship" on every write.
+      // Entries this plugin now writes `embed: false` are not ranked at all,
+      // but a shelf holds what earlier versions and other writers embedded.
+      const { similarFilters } = await cli.features()
       const rows = await cli.similar(`${unit.title}\n${unit.content}`.slice(0, 500), {
         target: 'knowledge',
-        limit: Math.min(limit * CANDIDATE_OVERSAMPLE, CANDIDATE_FETCH_CEILING),
+        limit: similarFilters ? limit : Math.min(limit * CANDIDATE_OVERSAMPLE, CANDIDATE_FETCH_CEILING),
+        excludeTags: EXCLUDED_TAGS,
       })
+      // The name-prefix half of `isOperationalRow` still applies: a tag filter
+      // cannot see an operational entry that lost its tags.
       return rows
         .filter((row) => rowName(row) !== name)
         .filter((row) => !isOperationalRow(row))