dsh-hypatia-auto-memory 0.1.0

package/skills/hypatia-dream/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: hypatia-dream
+description: "Run an incremental Hypatia graph-consolidation pass at a work-period boundary, like sleep-time knowledge organization. Trigger only for an explicit batch closeout or dream-time review, not ordinary knowledge CRUD, a one-off triple, or a lookup. Without an explicit --mode, these mean apply: '下班了', '收工了', '今天先到这', '本阶段结束', '阶段性收尾', '做个好梦', '睡前整理一下', 'done for the day', 'wrapping up', 'call it a night'. These mean report-only: '先整理看看', '做个梦看看', '睡前审阅一下', '看看知识之间的关系', '只出报告', '先别修改', 'just show me first', 'do not change anything yet'. Statement triples are the primary evidence; Knowledge bodies only disambiguate."
+user-invocable: true
+allowed-tools: Bash, Read, Grep, Glob
+argument-hint: "[shelf] [--mode report|apply]"
+---
+
+# Hypatia Dream
+
+Perform an incremental, relationship-focused consolidation pass over one Hypatia shelf. The purpose is to make the graph more coherent after new knowledge arrives, not to summarize, rewrite, delete, or otherwise curate the knowledge nodes themselves.
+
+Treat the graph as a personal knowledge base: inspect its whole available relationship topology rather than imposing a small relationship window. Keep the analysis disciplined by treating Statement triples as the primary evidence. Knowledge bodies may clarify entity identity or resolve an apparent contradiction, but they are not a license to invent weak associations.
+
+## Trigger And Mode Resolution
+
+Trigger this skill only for a deliberate batch consolidation at a work-period boundary or an explicitly requested dream-time review. Do not trigger it for ordinary knowledge CRUD, a direct one-off triple request, an entity lookup, a relationship query, or automatic conversation-memory extraction; those belong to `hypatia` or `hypatia-memory`.
+
+Interpret the optional shelf name from the request; use `default` when it is omitted.
+
+Resolve the mode in this order:
+
+1. An explicit `--mode report` or `--mode apply` always wins.
+2. Without an explicit mode, treat these closeout signals and clear equivalents as `apply`: `下班了`, `收工了`, `今天先到这`, `本阶段结束`, `阶段性收尾`, `做个好梦`, `睡前整理一下`, `done for the day`, `wrapping up`, and `call it a night`.
+3. Without an explicit mode, treat these preview signals and clear equivalents as `report`: `先整理看看`, `做个梦看看`, `睡前审阅一下`, `看看知识之间的关系`, `只出报告`, `先别修改`, `just show me first`, and `do not change anything yet`.
+4. If both signal classes appear in one request, ask the user to choose a mode. Do not assume `apply`.
+5. A direct but otherwise unspecified invocation defaults to `report`.
+
+The modes have these effects:
+
+- `report` reads the shelf and returns a structured report. It creates no state marker and changes no knowledge or statement.
+- `apply` may add a missing statement or replace an explicitly contradicted statement. It never creates, edits, or deletes a regular Knowledge entry.
+
+Before every Hypatia CLI command, briefly state the goal, the exact command, why that query or mutation is appropriate, and the expected result. Use one-shot commands only; do not use `hypatia repl`.
+
+## Hypatia Conventions To Preserve
+
+Use the actual Statement fields and CLI terminology: `head`, `relation`, and `tail`. Do not describe them as fields named `subject`, `predicate`, or `object` in commands or reports.
+
+Prefer the relationship vocabulary already established by Hypatia's semantic-memory design:
+
+- `is_a` for a clear category relationship.
+- `refines` for a more precise form of an existing concept.
+- `extends` for an addition that builds on an existing concept.
+- `supersedes` for an explicit replacement of an older concept or decision.
+- `derivedFrom` for a clear provenance relationship.
+
+Preserve existing predicate spellings. `belongTo` and `summary` are operational relationships maintained by the memory system; do not reinterpret, delete, replace, or add semantic links to their message/session/summary endpoints. Likewise, do not reorganize archive metadata relationships such as `is_a archive`.
+
+Do not use a vague catch-all relationship such as `related_to` merely because two entries share words or a topic. Omit uncertain candidates.
+
+## Resolve The CLI And Snapshot Boundary
+
+1. Resolve the binary in this order: `hypatia` on `PATH`, `./target/debug/hypatia`, then `./target/release/hypatia`. Stop and report a concrete blocker if none exists.
+2. Set `SHELF` to the requested shelf or `default`, then confirm that shelf is connected before doing anything else:
+
+```bash
+hypatia list
+```
+
+Every Hypatia command fails when the target shelf is not connected, and the whole CLI fails at startup when any registered shelf uses the legacy DuckDB layout. Both are blockers to report, not conditions to work around.
+
+3. Record a UTC run-start timestamp before reading graph data:
+
+```bash
+date -u '+%Y-%m-%d %H:%M:%S'
+```
+
+SQLite's `'now'` is UTC, so this is the same clock Hypatia stamps with. Hypatia writes `created_at` as `%Y-%m-%d %H:%M:%f`, so stored values carry milliseconds (`2026-09-02 08:50:08.790`) and compare as TEXT. A second-resolution boundary is therefore slightly conservative, deliberately so: `created_at <= "2026-09-02 08:50:08"` excludes `2026-09-02 08:50:08.790`, and because the watermark is written at the same resolution, the next run's `created_at > "2026-09-02 08:50:08"` picks that row back up. Do not pad the boundary with `.999` and do not truncate stored values to close the apparent gap — either one reintroduces a real gap.
+
+4. Query the latest successful apply marker in the same shelf:
+
+```bash
+hypatia query '{"$knowledge":[["$contains","tags","hypatia-dream-run"]],"limit":1}' -s "<SHELF>"
+```
+
+Query results are ordered by `created_at DESC`, so `limit:1` returns the most recent marker. A marker is a system-tagged Knowledge entry created by this skill after a successful `apply`. Its content contains a `processed_through` timestamp. Read that value, not the marker entry's `created_at`: a run can create statements after its snapshot begins, and using the marker creation time could skip concurrent new information.
+
+5. Define the collection interval as follows:
+
+- If a valid marker exists, use `processed_through < created_at <= run_started_at`.
+- If there is no valid marker, this is the first consolidation pass. Collect all pre-snapshot triples and knowledge entries.
+- A malformed marker is not a reason to guess. Report it and treat the run as a first pass unless the user supplies an explicit baseline.
+
+`report` mode must not advance this watermark. This lets a later `apply` reconsider the same proposed changes. Only a completed `apply` writes a marker.
+
+## Gather The Working Set
+
+Retrieve the complete pre-snapshot relationship graph. Use a large, explicit limit because the shelf is personal and the user requested no relationship-range cap:
+
+```bash
+hypatia query '{"$statement":[["$lte","created_at","<RUN_STARTED_AT>"]],"limit":10000}' -s "<SHELF>"
+```
+
+Retrieve the newly created triples with the collection interval. For a first pass, omit the lower-bound condition:
+
+```bash
+hypatia query '{"$statement":[["$and",["$gt","created_at","<BASELINE>"],["$lte","created_at","<RUN_STARTED_AT>"]]],"limit":10000}' -s "<SHELF>"
+```
+
+Also retrieve new Knowledge entries from the same interval. Exclude internal log, session, summary, and dream-marker entries by tag. For a first pass, omit the lower-bound condition:
+
+```bash
+hypatia query '{"$knowledge":[["$and",["$gt","created_at","<BASELINE>"],["$lte","created_at","<RUN_STARTED_AT>"],["$not",["$or",["$contains","tags","message"],["$contains","tags","session"],["$contains","tags","summary"],["$contains","tags","hypatia-dream-run"]]]]],"limit":10000}' -s "<SHELF>"
+```
+
+`limit` is a hard cap, not a promise. Compare the returned row count with the limit for each of the three queries above. If they are equal, the result was truncated by `ORDER BY created_at DESC` and the graph in hand is incomplete. Stop, report the truncation as a blocker, and apply nothing: a relation can only be judged contradicted, duplicate, or missing against the whole graph, and a truncated read would let this skill "correct" a relationship whose supporting evidence was simply cut off.
+
+The new Knowledge set can include an unlinked node. It is eligible for one well-supported relationship to an older graph node, but only after its body and the prospective target's body have been read for disambiguation. Do not manufacture a relation solely to make an isolated node connected.
+
+For each potentially affected node, fetch its Knowledge entry by exact name and inspect its one-hop incident triples from the full graph. Read only the bodies needed to explain an entity match, source lineage, category, refinement, extension, supersession, or direct contradiction. Never use conversation text, session summaries, or system markers as semantic evidence.
+
+## Reason About Relationships
+
+Work from the newly added triples and eligible new Knowledge nodes toward the full existing graph. For every candidate, identify:
+
+- The exact new evidence: triple or Knowledge entry name and the relevant wording.
+- The supporting old graph context: exact triples and, when needed, the old node body.
+- The proposed triple in `(head, relation, tail)` form.
+- A confidence level and a short explanation of why that relation is more precise than its alternatives.
+
+Classify each outcome as exactly one of these:
+
+1. **Add**: a missing, non-duplicate triple is directly supported by the new evidence and the existing graph vocabulary.
+2. **Replace**: a specific old triple is directly contradicted by newer, unambiguous evidence. Name both triples. Prefer adding `supersedes` when the old idea remains historically useful; delete and replace only when the old relation itself is false.
+3. **No change**: evidence is duplicate, weak, ambiguous, historical rather than contradictory, or depends on a protected/system relation.
+
+A candidate must be high confidence before it may be applied. Similarity, shared tags, or lexical overlap alone are never high confidence.
+
+Before a replacement, inspect the old statement's `content`, `tr_start`, and `tr_end`. A query result omits NULL columns entirely, so an absent `tr_start` or `tr_end` key means the statement has no temporal bound — not that the information is unavailable.
+
+`statement-create` accepts only `--data`, `--synonyms`, and `--scopes`. It cannot set `tags`, cannot set `format`, cannot set `figures`, and cannot recreate a temporal bound. Report instead of replacing whenever the source statement has any of these:
+
+- a populated `tr_start` or `tr_end`;
+- a non-empty `content.tags`;
+- a `content.format` other than `markdown`;
+- a non-empty `content.figures`.
+
+Otherwise the statement is eligible, and the replacement must carry over `content.data`, positional `content.synonyms`, and `content.scopes` from the source.
+
+## Apply Changes
+
+In `report` mode, stop after producing the report. Do not write a marker.
+
+In `apply` mode, execute this sequence only after the analysis identifies high-confidence changes:
+
+1. Re-query every proposed old and new triple immediately before mutating. Use the exact-key form, which matches on the `triple` primary key:
+
+```bash
+hypatia query '{"$statement":[["$triple","<HEAD>","<RELATION>","<TAIL>"]],"limit":1}' -s "<SHELF>"
+```
+
+Skip a stale plan, an addition that already exists, and a replacement whose source triple no longer matches the reviewed evidence.
+
+A replacement whose new triple already exists needs one more check, because `statement-create` never overwrites an existing triple. Compare that triple's `data`, `synonyms`, and `scopes` with the source triple's. Treat an absent field and an empty list or object as equal, and compare `scopes` as a set.
+
+- If they are equal, an earlier run created it and stopped before the delete. Mark the replacement **delete-only** and count it as replaced. Do not delete anything yet: step 4 runs the delete after step 2's backup.
+- If they differ, skip the replacement. List it under No Change with the reason `target already exists with different metadata; a person must decide`, do not delete the source, and leave both triples out of step 5's verification.
+
+2. If the run plans any replacement, export the shelf to a timestamped backup directory before the first replacement step and report the destination. `export` creates the destination directory itself, so do not pre-create it, and pass the shelf name as the first argument:
+
+```bash
+hypatia export "<SHELF>" "<BACKUP_DIR>"
+```
+
+3. For an addition, create only the exact reviewed triple. Do not create supporting nodes or generic fallback links.
+
+```bash
+hypatia statement-create "<HEAD>" "<RELATION>" "<TAIL>" -s "<SHELF>"
+```
+
+`statement-create` is idempotent. Creating a triple that already exists exits 0 and prints `Statement already exists: (<HEAD>, <RELATION>, <TAIL>)` instead of `Created statement: ...`, and leaves the stored triple and its metadata unchanged. That means the relationship is already recorded: count it as skipped and continue. It is not a run failure.
+
+4. For a replacement, **create the new triple first, verify it, and only then delete the source triple.** A replacement changes at least one of `head`, `relation`, and `tail`, so the two triples have different primary keys and can coexist for the moment in between. This ordering has no window in which the old relationship is already gone and the new one does not yet exist. Never delete first. For a delete-only replacement from step 1, skip the create and run only the `statement-delete`.
+
+```bash
+hypatia statement-create "<NEW_HEAD>" "<NEW_RELATION>" "<NEW_TAIL>" \
+  -d "<SOURCE_DATA>" --synonyms '<SOURCE_SYNONYMS_JSON>' --scopes "<SOURCE_SCOPES>" -s "<SHELF>"
+hypatia statement-delete "<OLD_HEAD>" "<OLD_RELATION>" "<OLD_TAIL>" -s "<SHELF>"
+```
+
+Carry the source metadata across exactly, and omit any flag whose source value is empty — `--synonyms ""` is a hard parse error, not an empty value. `--synonyms` takes the positional form `{"head":[...],"relation":[...],"tail":[...]}`. `--scopes` is comma-separated and a trailing comma means global scope, so source scopes `["project-a",""]` are reproduced as `--scopes "project-a,"` and `[""]` as `--scopes ","`.
+
+If the create fails, nothing has been lost: report it and leave the source triple untouched. If the create prints `Statement already exists`, the new triple appeared after step 1's re-query and may not carry the source metadata. Do not delete the source yet: apply step 1's already-exists check to it now. If the create succeeds but the delete fails, stop and report both triples as present — the graph is consistent but now carries a duplicate relationship, and a person must decide.
+
+5. Re-query each created triple and every intended removal with the same `$triple` form. For a delete-only replacement, also re-query its target: it must still come back. A created triple must come back; a removed triple must return `No results found.` Note that `statement-delete` exits non-zero with `not found` when the triple is already gone; that is an already-applied removal rather than a failure, but confirm it by query before continuing. If any verification fails, stop, report the partial outcome and the backup location, and do not create a watermark.
+
+After all intended changes verify, write one run marker in the same shelf:
+
+```bash
+hypatia knowledge-create "hypatia-dream-run-<UTC_COMPACT_TIMESTAMP>" \
+  -d "schema: 1
+mode: apply
+processed_through: <RUN_STARTED_AT>
+added: <COUNT>
+replaced: <COUNT>
+report: Hypatia Dream completed successfully" \
+  -t "system,hypatia-dream-run" \
+  -s "<SHELF>"
+```
+
+The marker is operational metadata, not semantic knowledge. Never attach a Statement triple to it or use it as relationship evidence.
+
+A marker is still an ordinary Knowledge entry: it is full-text indexed and vector-embedded like any other, so it will surface in the user's own `hypatia search` and `hypatia similar` results. Keep the body to the fields above for that reason — never store report prose, analysis, or candidate lists in it. This skill never deletes an old marker; only the most recent one is ever read.
+
+If no high-confidence graph changes exist, `apply` may still write the marker after reporting a verified no-op. This records that the interval has been reviewed without falsely claiming a graph mutation.
+
+## Required Report
+
+Return the report in this structure, in the user's language:
+
+```markdown
+# Hypatia Dream Report
+
+## Scope
+- Shelf: `<name>`
+- Mode: `report` or `apply`
+- Baseline: first pass, or `<processed_through>`
+- Snapshot boundary: `<run_started_at>`
+- Reviewed: `<new knowledge count>` Knowledge entries and `<new statement count>` new triples against `<total statement count>` existing triples
+- Graph read: `<returned row count>` of `<limit>` rows, complete or truncated
+
+## Relationship Findings
+### Add
+- `(head, relation, tail)` [high confidence]
+  Evidence: ...
+  Existing context: ...
+
+### Replace
+- `(old head, old relation, old tail)` -> `(new head, new relation, new tail)` [high confidence]
+  Evidence: ...
+  Rationale: ...
+
+### No Change
+- Item: ...
+  Reason: duplicate, insufficient evidence, protected system relation, metadata/temporal safety restriction, or target already exists with different metadata.
+
+## Outcome
+- Planned or applied additions: `<count>`
+- Planned or applied replacements: `<count>`
+- Skipped candidates: `<count>`
+- Backup: `<path>` or `not needed`
+- Watermark: `<processed_through>` written only after a verified `apply`, otherwise `unchanged`
+```
+
+Be concise but include every command that changed state and every exact triple it affected. Do not claim a relationship was corrected unless its post-mutation query verified the result.

package/skills/hypatia-dream/evals/evals.json

@@ -0,0 +1,92 @@
+{
+  "skill_name": "hypatia-dream",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "在名为 research 的 Hypatia shelf 上做一次知识图谱睡眠整理。不要改动任何数据，只给我报告。这个 shelf 没有 hypatia-dream 水位；其中新增节点 'JSE Query Planner' 明确说明它细化了 'JSE Query Engine'，但目前缺少两者之间的关系。还包含一条 msg-123-4 belongTo session-123。",
+      "expected_output": "Resolve report mode, treat the run as a first pass, inspect the full statement graph and relevant Knowledge bodies, exclude the message/session operational relationship, and report a high-confidence candidate `(JSE Query Planner, refines, JSE Query Engine)` without executing any create, delete, export, or marker command.",
+      "files": [],
+      "expectations": [
+        "Defaults to report mode and schedules no state-changing command or watermark.",
+        "Treats the missing marker as a first pass with a fixed snapshot boundary.",
+        "Proposes (JSE Query Planner, refines, JSE Query Engine) with explicit evidence.",
+        "Excludes the belongTo message/session relationship from semantic consolidation."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "对默认 shelf 运行 hypatia-dream --mode apply。上次成功水位为 2026-03-01 09:00:00。新知识明确规定 'SQLite Storage' 已取代 'DuckDB Storage' 作为唯一结构化存储；图中仍有 `(Hypatia, uses, DuckDB Storage)`，该旧三元组没有时间范围，且 scopes 和 data 为空。请修正关系。",
+      "expected_output": "Use the marker's processed_through value and a fixed snapshot boundary, identify an explicit contradiction rather than a merely related concept, re-query the reviewed triple with the $triple exact-key form before mutation, export a backup before the replacement, create `(Hypatia, uses, SQLite Storage)` first and verify it, only then delete `(Hypatia, uses, DuckDB Storage)`, verify the removal, create a successful apply marker, and return the required report with exact changes and backup path.",
+      "files": [],
+      "expectations": [
+        "Uses the marker's processed_through value rather than its creation time.",
+        "Re-queries the exact old triple and exports a backup before the replacement.",
+        "Creates (Hypatia, uses, SQLite Storage) BEFORE deleting (Hypatia, uses, DuckDB Storage), never the reverse order.",
+        "Verifies both the creation and the removal, and writes a successful apply marker only after verification."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "帮我做梦整理默认知识库，模式 report。新条目 'Database Notes' 和旧条目 'Distributed Systems' 都提到了 consistency，但没有明确的来源、分类、细化、扩展或替代关系；图中还存在一个时间范围不为空的 `(Storage, uses, DuckDB)` 三元组。",
+      "expected_output": "Report no semantic change for the lexical overlap, avoid adding a vague related_to triple, and explain that a time-bounded statement is not eligible for replacement through the current CLI because statement-create cannot recreate temporal bounds. Note that the CLI itself never sets tr_start/tr_end, so this guard exists for statements written by other Hypatia clients.",
+      "files": [],
+      "expectations": [
+        "Does not add a related_to or other semantic triple from lexical overlap alone.",
+        "Does not replace the time-bounded Storage uses DuckDB triple.",
+        "Keeps report mode read-only and leaves the watermark unchanged."
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "下班了。请对默认 Hypatia shelf 做个好梦。",
+      "expected_output": "Treat the two closeout signals as an explicit request for apply mode even though --mode is omitted; begin the safe apply workflow rather than returning a report-only plan.",
+      "files": [],
+      "expectations": [
+        "Selects apply mode without asking for confirmation.",
+        "Explains that the closeout wording is the mode signal, then follows the normal preflight, backup, verification, and watermark rules."
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "先整理看看默认知识库，看看知识之间的关系；先别修改。",
+      "expected_output": "Treat the preview wording as report mode and make no graph or watermark mutation.",
+      "files": [],
+      "expectations": [
+        "Selects report mode from the preview signals.",
+        "Does not schedule statement mutations or watermark creation."
+      ]
+    },
+    {
+      "id": 6,
+      "prompt": "本阶段结束了，但先别修改，帮我做个好梦。",
+      "expected_output": "Detect the conflicting apply and report signals, ask the user to choose a mode, and make no state change.",
+      "files": [],
+      "expectations": [
+        "Does not prioritize the closeout signal over the preview signal.",
+        "Requests a mode choice and performs no graph mutation or watermark update."
+      ]
+    },
+    {
+      "id": 7,
+      "prompt": "下班了，对默认 shelf 做个好梦。这个 shelf 很大：完整关系图查询返回的行数正好等于 10000 条上限。",
+      "expected_output": "Detect that the returned row count equals the query limit, treat the graph read as truncated rather than complete, and stop with a blocker report instead of applying any addition or replacement against a partial graph.",
+      "files": [],
+      "expectations": [
+        "Compares the returned row count against the limit and identifies the read as truncated.",
+        "Applies no statement mutation and writes no watermark.",
+        "Reports the truncation as a concrete blocker rather than proceeding on the rows it did receive."
+      ]
+    },
+    {
+      "id": 8,
+      "prompt": "对默认 shelf 运行 hypatia-dream --mode apply。新知识明确说明 'Parquet Export' 已取代 'CSV Export'；旧三元组 `(Pipeline, emits, CSV Export)` 没有时间范围，但它的 content.tags 是 [\"pipeline\",\"legacy\"]。",
+      "expected_output": "Recognize the contradiction but refuse to apply the replacement, because statement-create has no tags flag and the source statement's tags would be silently dropped. Report the candidate under No Change with the metadata-preservation reason and leave the graph unchanged.",
+      "files": [],
+      "expectations": [
+        "Does not delete or replace (Pipeline, emits, CSV Export).",
+        "Names the non-empty content.tags as the reason the statement is ineligible for replacement.",
+        "Reports the candidate rather than silently dropping it or silently losing the tags."
+      ]
+    }
+  ]
+}

package/skills/hypatia-memory/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: hypatia-memory
+description: Long-term memory for DSH via hypatia. Conversation logging and background consolidation run automatically; retrieval is yours to drive. Use when the task touches past decisions, project conventions, prior bugs, or anything the user expects you to already know — and whenever the user says "read hypatia", "查一下 hypatia", "记住", "忘记".
+user-invocable: false
+allowed-tools: Bash, Read, Grep, Glob
+---
+
+# Hypatia Memory (DSH auto-memory variant)
+
+The `dsh-hypatia-auto-memory` plugin is active. It handles the **write** side of
+memory in the background. The **read** side is yours.
+
+## What runs without you
+
+Do not do these by hand — you would only create duplicates:
+
+- **Conversation logging.** Every human message and every assistant message
+  becomes a `msg-<sessionId>-<N>` entry (`N` is a dense per-session message
+  ordinal), redacted, with relative dates rewritten to absolute ones and a tool
+  ledger attached. Spans are cut at turn boundaries.
+- **Span summaries.** `sum-*` entries tagged `summary`, linked to the messages
+  they cover with `summary` statements.
+- **Work units.** `wu-*` entries tagged `memory,work-unit` for lessons worth
+  keeping, with `is_a` / `derivedFrom` statements.
+- **Session seed.** Project and global entries tagged `rule` or `taboo` are
+  injected into your context at session start. Nothing else is pushed to you.
+
+## Which shelf
+
+The plugin writes to one hypatia shelf, chosen in its settings. When that is
+not `default`, the session seed says so: *"Memory lives on the hypatia shelf
+`<SHELF>`"*. Then add `--shelf <SHELF>` to **every** command below — reads and
+writes alike — or you will search a shelf the plugin never wrote to and store
+rules the seed will never load. When the seed names no shelf, leave the flag off.
+
+## What you own: retrieval
+
+Rules and taboos are pushed because you cannot know to ask for them. Everything
+else you must **pull**, when you judge you need it — including part-way through
+a task, once you discover what the task is actually about.
+
+Search when the task touches prior decisions, project conventions, a bug that
+smells familiar, an unfamiliar internal name, or when the user implies you
+should already know something. Searching costs one subprocess; not searching
+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 5
+```
+
+Write the query as the *idea* you are looking for, not the user's words verbatim.
+Rows come back as `{"name", "content" (object), "distance"}`; lower `distance` is
+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.
+
+### Keyword search — for exact identifiers
+
+```bash
+hypatia search "<exact symbol, error code, file name>" -c knowledge --limit 5
+```
+
+Rows come back as `{"id", "catalog", "key", "content" (**JSON-encoded string**),
+"rank"}`. Note the shape differs from `similar`: the name is `key`, not `name`,
+and `content` must be parsed before use.
+
+### Structured queries
+
+```bash
+# This project's rules (and global ones)
+hypatia query '["$knowledge", ["$contains","tags","rule"],
+  ["$or", ["$contains","scopes","<PROJECT>"], ["$contains","scopes",""]]]'
+
+# Everything derived from one work unit, two hops out
+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.
+
+### Always exclude the operational layer
+
+Raw logs and bookkeeping entries are indexed for full-text and vector search,
+so they *will* come back in results. They are not knowledge — skip rows whose
+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.
+
+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.
+
+## Explicit writes
+
+### Remember
+
+When the user states a durable rule, taboo, or correction — "以后都记住：……",
+"always use tabs", "never commit to main" — write it immediately. The background
+extractor only produces work units; it never invents rules or taboos, so an
+unwritten rule is a lost rule.
+
+```bash
+hypatia knowledge-create "<short-kebab-name>" \
+  --data="<the fact, as an imperative>" \
+  --tags "rule" \
+  --scopes "<PROJECT>"
+```
+
+- `--tags rule` for conventions to follow, `taboo` for never-do items,
+  `memory` for durable facts.
+- **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
+  not be found by the session seed.
+- Check with `knowledge-get <name>` first. A new name gets `knowledge-create`.
+  An existing entry the user wants reworded, retagged or rescoped gets
+  `knowledge-update`, **never** delete + create:
+
+  ```bash
+  hypatia knowledge-update "<exact-name>" --data="<the corrected fact>"
+  ```
+
+  Only the fields you pass change. The entry keeps its `created_at`, and its
+  vector is regenerated on the next flush. An update that changes nothing
+  prints `Knowledge unchanged: <name>` and writes nothing. Updating a missing
+  entry exits 1.
+- Pass only the fields you mean to change. `--scopes` **replaces** the stored
+  scopes, with the syntax above: leave off the trailing comma and a global rule
+  drops out of the session seed. `--tags ""` clears every tag, and an entry
+  that is no longer tagged `rule` or `taboo` is not seeded either.
+- An update is not how you record a contradiction; that is `supersedes`, below.
+- A hypatia older than #20 has no `knowledge-update` and exits 2 with
+  `unrecognized subcommand`. Then leave the entry alone unless the user asks:
+  delete + create loses its creation time.
+- Creating a name that already exists exits 1 with `UNIQUE constraint failed`.
+  That is a collision, not a crash.
+
+Relate it to what is already there when the relationship is clear:
+
+```bash
+hypatia statement-create "<new>" "supersedes" "<old>" --scopes "<PROJECT>"
+```
+
+Use `refines`, `extends`, `supersedes`, `derivedFrom`, `is_a`. When new
+knowledge **contradicts** old, record `supersedes` and leave the old entry in
+place — the memory system must never quietly forget what it once believed. Do
+not invent a vague `related_to` edge just because two entries share a topic.
+
+### Forget
+
+```bash
+hypatia search "<keywords>" -c knowledge --limit 10
+hypatia knowledge-delete "<exact-name>"
+```
+
+Deleting a missing entry exits 1. Statements referencing the entry are not
+cascade-deleted; remove them with `hypatia statement-delete <head> <relation>
+<tail>` when they would otherwise dangle. Deleted memories stay deleted — the
+collector's watermark has already moved past them.
+
+## Known gaps in the automatic layer
+
+Say so plainly if a user's expectation depends on one of these:
+
+- **No topic-shift detection.** Spans are cut on turn boundaries and token
+  thresholds, not on the conversation changing subject. A session covering three
+  unrelated topics summarises them together.
+- **No `session-<id>` node** unless the host produced a session title or a
+  compaction summary to build it from.
+- **Summary names are mechanical** (`sum-<session>-<from>-<to>`), not descriptive.
+  The descriptive title is the first heading inside the entry.
+- **Work-unit dedup is best-effort** and degrades to "no relationship" whenever
+  the shelf has no embedding model.

package/src/auto-approve.js

@@ -0,0 +1,133 @@
+/**
+ * Auto-approval for the agent's own `hypatia` calls.
+ *
+ * This plugin's own writes never need it: they go through the subprocess
+ * service as argv arrays, with no shell and no approval in the path. It exists
+ * for the other half of the protocol — the agent running `hypatia …` through
+ * bash to retrieve, remember or forget — which otherwise stops on an approval
+ * prompt every single time and, in practice, stops the agent from retrieving at
+ * all.
+ *
+ * The matcher is narrow on purpose: a bash call whose executable word is a
+ * trusted basename AND that contains no shell composition outside quotes. A
+ * command that pipes, redirects, chains or substitutes is a command that can do
+ * something other than talk to hypatia, so it goes to the human.
+ *
+ * Ported from `dsh-hypatia`'s auto-approve (same repository, MIT), which this
+ * plugin replaces — see README.
+ *
+ * @module dsh-hypatia-auto-memory/auto-approve
+ */
+
+/**
+ * True when the command's executable word (after env assignments) is trusted.
+ * @param {string} command
+ * @param {string[]} binaries - trusted basenames, e.g. `['hypatia']`.
+ */
+export function invokesTrustedBinary(command, binaries) {
+  let rest = command.trimStart()
+  // Skip leading KEY=VALUE environment assignments (e.g. HYPATIA_BIN=...).
+  for (;;) {
+    const assignment = /^[A-Za-z_][A-Za-z0-9_]*=\S+\s+/.exec(rest)
+    if (assignment === null) break
+    rest = rest.slice(assignment[0].length).trimStart()
+  }
+  const word = /^([^\s"']+)/.exec(rest)?.[1]
+  if (word === undefined) return false
+  return binaries.some((binary) => word === binary || word.endsWith(`/${binary}`))
+}
+
+/**
+ * True when the command contains shell composition OUTSIDE quotes.
+ *
+ * Quote tracking matters: a JSE query argument routinely contains `|` or `>`
+ * inside a quoted string (`'["$knowledge",[["$gt","x",1]]]'`), and treating
+ * those as composition would send every structured query to the human.
+ * @param {string} command
+ */
+export function hasShellComposition(command) {
+  let single = false
+  let double = false
+  let escaped = false
+  for (let index = 0; index < command.length; index += 1) {
+    const char = command[index]
+    if (escaped) {
+      escaped = false
+      continue
+    }
+    if (single === false && char === '\\') {
+      escaped = true
+      continue
+    }
+    if (double === false && char === "'") {
+      single = single === false
+      continue
+    }
+    if (single === false && char === '"') {
+      double = double === false
+      continue
+    }
+    if (single || double) continue
+    if (char === '&' || char === ';' || char === '|' || char === '<' || char === '>' || char === '`' || char === '\n') {
+      return true
+    }
+    if (char === '$' && command[index + 1] === '(') return true
+  }
+  return false
+}
+
+/**
+ * True when this tool execution is a plain call to a trusted binary.
+ * @param {{name?: string, arguments?: {command?: unknown}}} exec
+ * @param {string[]} binaries
+ */
+export function isPureTrustedCall(exec, binaries) {
+  if (exec?.name !== 'bash') return false
+  const command = exec.arguments?.command
+  if (typeof command !== 'string') return false
+  return invokesTrustedBinary(command, binaries) && hasShellComposition(command) === false
+}
+
+/**
+ * Answer approval requests for the agent's pure hypatia calls.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx - context injecting `approval` and `tools`.
+ * @param {{getBinaries: () => string[], status: import('./status.js').StatusLog}} deps
+ */
+export function createAutoApprove(ctx, { getBinaries, status }) {
+  /** callIds of in-flight bash calls that qualify for automatic approval. */
+  const pending = new Set()
+
+  const binaries = () => {
+    const configured = getBinaries()
+    return Array.isArray(configured) && configured.length > 0 ? configured : ['hypatia']
+  }
+
+  ctx.on('tools/pre-execute', (exec, next) => {
+    try {
+      if (isPureTrustedCall(exec, binaries())) pending.add(exec.callId)
+    } catch {
+      // A matcher bug must never block the tool pipeline; fall through to ask.
+    }
+    return next()
+  })
+
+  // Whether the call asked for approval or not, drop the marker once it settles.
+  ctx.on('tools/result', (exec) => {
+    pending.delete(exec?.callId)
+  })
+
+  // PREPEND: the waterfall runs outermost-first and a handler that skips next()
+  // vetoes the rest — the host's api-proxy publishes the approval to the UI and
+  // blocks on the human without calling next(), so a plain registration would
+  // sit behind it and never run. Non-hypatia calls fall through unchanged.
+  ctx.on('approval/request', (request, next) => {
+    if (request?.callId !== undefined && pending.delete(request.callId)) {
+      status.count('autoApproved')
+      return 'allowed-once'
+    }
+    return next()
+  }, { prepend: true })
+
+  return { pendingSize: () => pending.size }
+}