dsh-hypatia-auto-memory 0.1.0

package/skills/hypatia/SKILL.md

@@ -0,0 +1,585 @@
+---
+name: hypatia
+description: "Interact with the Hypatia AI memory system using natural language. Translate user requests into hypatia CLI commands for knowledge CRUD, statement (RDF triple) management, JSE queries, full-text search, and shelf management. Trigger when: user mentions memories, knowledge bases, knowledge graphs, triples, statements, relationships, shelves, or asks to store, recall, remember, record, save, find, or search information in hypatia. Also trigger when user wants to create or explore relationships between concepts, query existing knowledge, or manage shelves. Examples: 'remember that Rust is a systems language', 'find everything about Alice', 'record that Alice knows Bob', 'search for programming', 'show all knowledge', 'list shelves'."
+user-invocable: true
+allowed-tools: Bash, Read, Grep, Glob
+argument-hint: <natural-language instruction>
+---
+
+# Hypatia Query Skill
+
+You are operating the Hypatia CLI — an AI-oriented memory management system. Translate the user's natural language request into the appropriate `hypatia` CLI command and execute it via Bash.
+
+## Binary Location
+
+First check which binary is available:
+
+1. `hypatia` — if installed on PATH
+2. `./target/debug/hypatia` — debug build in current project
+3. `./target/release/hypatia` — release build in current project
+
+Use the first one found. All examples below use `hypatia` for brevity.
+
+## Shelf Management
+
+| User says | Command |
+|---|---|
+| "list shelves" / "show connected shelves" | `hypatia list` |
+| "connect shelf at PATH" / "open data at PATH" | `hypatia connect <path> [-n <name>]` |
+| "disconnect shelf NAME" / "close shelf NAME" | `hypatia disconnect <name>` |
+| "export shelf NAME to DEST" | `hypatia export <name> <dest>` |
+
+## Archive Files
+
+Archive files (images, PDFs, data, etc.) are stored in the shelf's `archives/` directory and referenced via `archive://` paths.
+
+| User says | Command |
+|---|---|
+| "store this image" / "add figure fig.png" | `hypatia archive-store <file> -n <dest_path>` |
+| "get archive fig.png" / "show image path" | `hypatia archive-get <name>` |
+| "copy archive to /tmp" | `hypatia archive-get <name> -o /tmp/output.png` |
+| "list archives" / "show all files" | `hypatia archive-list` |
+
+`archive-store` automatically creates a knowledge entry with file metadata (size, MIME type) and an `is_a archive` statement. Archive files can be queried via JSE:
+
+```bash
+hypatia query '["$knowledge", ["$contains", "tags", "archive"]]'
+hypatia query '["$knowledge", ["$content", {"mime_type": "image/png"}]]'
+```
+
+To reference an archive when creating knowledge:
+
+```bash
+hypatia knowledge-create "Euclid Prop 1" -d "equilateral triangle" --figures "archive://euclid/fig1.png"
+```
+
+### Scopes
+
+Use `--scopes` to assign project or global scope to knowledge and statements. The value is comma-separated. **Global scope is stored as an empty-string entry, and only a trailing comma writes it**: `--scopes ","` is global only, and `--scopes "my-project,"` is both. `--scopes ""` stores no scope at all, so global lookups such as `["$has", "scopes", ""]` will never find the entry.
+
+```bash
+# Project-scoped only
+hypatia knowledge-create "API convention" -d "REST endpoints use kebab-case" --tags "rule" --scopes "my-project"
+
+# Global scope only (trailing comma; `--scopes ""` would store no scope)
+hypatia knowledge-create "prefer immutable" -d "always create new objects" --tags "rule" --scopes ","
+
+# Both project and global (trailing comma)
+hypatia knowledge-create "no mock DB" -d "never mock database in tests" --tags "taboo" --scopes "my-project,"
+```
+
+## Knowledge CRUD
+
+Knowledge entries are independent information points with a name, content, and tags.
+
+### Create
+
+```
+hypatia knowledge-create <name> -d "<data>" -t "<tag1,tag2>" --figures "archive://path/to/file"
+```
+
+| 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"` |
+
+### Read
+
+```
+hypatia knowledge-get <name>
+```
+
+| User says | Command |
+|---|---|
+| "show me knowledge about Rust" / "get Rust entry" | `hypatia knowledge-get "Rust"` |
+
+### Update
+
+```
+hypatia knowledge-update <name> [-d "<data>"] [-t "<tags>"] [--synonyms "<csv>"] [--figures "<refs>"] [--scopes "<scopes>"]
+```
+
+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 |
+|---|---|
+| "update Rust's description to mention memory safety" | `hypatia knowledge-update "Rust" -d "systems programming language with memory safety"` |
+| "retag Go as language and google" | `hypatia knowledge-update "Go" -t "language,google"` |
+| "remove all tags from Python" | `hypatia knowledge-update "Python" -t ""` |
+
+### Delete
+
+```
+hypatia knowledge-delete <name>
+```
+
+| User says | Command |
+|---|---|
+| "delete knowledge Rust" / "remove the Rust entry" | `hypatia knowledge-delete "Rust"` |
+
+## Statement Creation — Proactive Graph Building
+
+Statements are RDF-style triples: `(head, relation, tail)`. They form the edges of the knowledge graph.
+
+### Key Principle: Always Enrich with Relationships
+
+When the user asks to store or remember information, **always create statements alongside knowledge entries** to build graph connectivity. The goal is a rich, traversable knowledge graph, not isolated data points.
+
+**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>"
+```
+
+### Triple Extraction Patterns
+
+| User says | head | relation | tail |
+|---|---|---|---|
+| "record that Alice knows Bob" | Alice | knows | Bob |
+| "X is a Y" / "X is an Y" | X | is_a | Y |
+| "X belongs to Y" / "X is part of Y" | X | belongs_to | Y |
+| "X works for Y" | X | works_for | Y |
+| "X is related to Y" | X | related_to | Y |
+| "X depends on Y" | X | depends_on | Y |
+| "X uses Y" | X | uses | Y |
+| "X contains Y" | X | contains | Y |
+| "X created Y" | X | created_by | Y (reversed) |
+
+Normalize relations to `snake_case`. Common relations: `is_a`, `knows`, `related_to`, `works_for`, `belongs_to`, `depends_on`, `uses`, `contains`, `created_by`.
+
+### Proactive Creation Examples
+
+When the user says **"remember that Rust is a systems programming language"**, execute BOTH:
+
+```bash
+hypatia knowledge-create "Rust" -d "systems programming language" -t "language,compiled"
+hypatia statement-create "Rust" "is_a" "systems programming language"
+```
+
+When the user says **"remember that PostgreSQL is a relational database used by the API"**, execute:
+
+```bash
+hypatia knowledge-create "PostgreSQL" -d "relational database" -t "database,relational"
+hypatia statement-create "PostgreSQL" "is_a" "relational database"
+hypatia statement-create "API" "depends_on" "PostgreSQL" -d "primary data store"
+```
+
+When the user says **"note that Alice is a senior engineer on the Backend team"**, execute:
+
+```bash
+hypatia knowledge-create "Alice" -d "senior engineer on Backend team" -t "person,engineer"
+hypatia statement-create "Alice" "is_a" "senior engineer"
+hypatia statement-create "Alice" "works_for" "Backend team"
+```
+
+### Auto-linking Rules
+
+When creating knowledge entries, automatically extract and create statements for:
+1. **Category**: `"X" is_a "<category>"` — every entity has a type
+2. **Dependencies**: if the content mentions tools, frameworks, or systems X depends on → `X depends_on Y`
+3. **Relationships**: if the content mentions other entities → link them with appropriate relations
+4. **Containment**: if X is part of Y → `X belongs_to Y`
+
+## Thinking Aloud Protocol
+
+**Every query execution MUST be preceded by a brief explanation.** Before running any hypatia command, output a thinking block in this format:
+
+```
+**Step N: <goal>**
+
+> `hypatia <command>`
+
+为什么用这个查询：<1-2 sentence explanation of why this operator/strategy was chosen>
+预期结果：<what kind of results to expect>
+```
+
+Then execute the command. After results come back, briefly interpret them before deciding the next step.
+
+### Example Walkthrough
+
+User asks: *"查找与 Alice 相关的所有知识，以及她的关系网络"*
+
+```
+**Step 1: 直接获取 Alice 的知识条目**
+
+> `hypatia knowledge-get "Alice"`
+
+为什么用这个查询：用户提到了明确的实体名 "Alice"，先尝试直接 lookup 获取完整条目。
+预期结果：如果存在，返回 Alice 的知识条目（content, tags, figures 等）。
+```
+
+(执行... 得到结果或 "not found")
+
+```
+**Step 2: 查找 Alice 参与的所有三元组关系**
+
+> `hypatia query '["$statement", ["$triple", "Alice", "$*", "$*"]]'`
+
+为什么用这个查询：用 $triple 对 head 位精确匹配 "Alice"，wildcard relation 和 tail，
+这样可以拿到 Alice 作为主语的所有关系（knows, is_a, works_for 等），$triple 走索引，比 $search 更快更精确。
+预期结果：返回所有 Alice 作为 head 的 statement triples。
+```
+
+(执行... 得到结果)
+
+```
+**Step 3: 查找指向 Alice 的关系（Alice 作为 tail）**
+
+> `hypatia query '["$statement", ["$triple", "$*", "$*", "Alice"]]'`
+
+为什么用这个查询：上一步只查了 Alice 作为 head 的关系，但其他人可能指向 Alice（如 "Bob knows Alice"），
+需要查 tail 位 = Alice 的三元组才能得到完整的关系网络。
+预期结果：返回所有以 Alice 为宾语的 statement triples。
+```
+
+(执行... 得到结果)
+
+```
+**Step 4: 2-hop 图遍历，探索 Alice 的更远关系**
+
+> `hypatia query '["$statement", ["$k-hop", "Alice", "$*", 2]]'`
+
+为什么用这个查询：前两步只查了 Alice 的直接关系，用户问的是"关系网络"，需要通过 2-hop 递归遍历
+发现 Alice → Bob → Charlie 这样的间接关系。$k-hop 用递归 CTE 实现，适合图探索。
+预期结果：返回 Alice 的 2-hop 邻域内所有 statement triples。
+```
+
+### Rules for Thinking Aloud
+
+1. **Always explain before executing** — never run a query silently
+2. **Explain the "why"** — which operator was chosen and why, not just what it does
+3. **Keep it concise** — 1-2 sentences for explanation, 1 sentence for expected results
+4. **Interpret results** — after each step, briefly note what was found before deciding next steps
+5. **Multi-step reasoning** — for complex requests, show the decomposition into steps and explain the strategy
+6. **Empty results are informative** — if a query returns nothing, explain what that tells us and adjust strategy
+
+## Search Strategy — Graph-First Retrieval
+
+When searching for information, prefer precise graph operators over broad FTS search. Use the following decision tree:
+
+### Search Decision Tree
+
+For each step, include the thinking aloud explanation before executing.
+
+```
+1. User mentions a specific entity name?
+   → knowledge-get (direct lookup)
+
+2. User asks about relationships involving a known entity?
+   → $triple operator (fastest, indexed)
+
+3. User asks about a type of relationship (e.g., "who works for X")?
+   → $triple with wildcard on entity positions
+
+4. User wants to explore graph neighborhood (e.g., "who can X reach in 2 hops")?
+   → $k-hop operator (graph traversal)
+
+5. User wants semantic/similarity search (e.g., "find similar concepts")?
+   → hypatia similar (vector search)
+
+6. User wants to match a pattern (e.g., "names starting with X")?
+   → $like operator
+
+7. User wants to filter by content attributes (e.g., "markdown entries", "entries with specific format")?
+   → $content operator
+
+8. User asks about a specific entity's relationships?
+   → $triple + knowledge-get combined
+
+9. Broad/ambiguous query?
+   → $search (FTS fallback)
+```
+
+### Prefer $triple over $search for entity queries
+
+When the query involves a known entity (person, tool, concept), use `$triple` for precise, indexed lookups instead of FTS:
+
+| Instead of | Use |
+|---|---|
+| `["$statement", ["$search", "Alice"]]` | `["$statement", ["$triple", "Alice", "$*", "$*"]]` |
+| `["$statement", ["$search", "manages"]]` | `["$statement", ["$triple", "$*", "manages", "$*"]]` |
+| `["$statement", ["$contains", "triple", "Alice"]]` | `["$statement", ["$triple", "Alice", "$*", "$*"]]` |
+
+### Combined Queries
+
+For rich retrieval, combine graph traversal with content filtering:
+
+```bash
+# Find all relationships involving Alice, created after a date
+hypatia query '["$statement", ["$and", ["$triple", "Alice", "$*", "$*"], ["$gt", "created_at", "2025-01-01"]]]'
+
+# Find all knowledge entries in markdown format about a topic
+hypatia query '["$knowledge", ["$and", ["$content", {"format": "markdown"}], ["$search", "database"]]]'
+
+# Find all people (entities that are_a "engineer")
+hypatia query '["$statement", ["$triple", "$*", "is_a", "engineer"]]'
+```
+
+## Full-text Search
+
+Search is the fallback for broad or ambiguous queries. It covers both knowledge and statements.
+
+```
+hypatia search <query> [-c <catalog>] [--limit N] [--offset N]
+```
+
+- `-c knowledge` — search only knowledge entries
+- `-c statement` — search only statements
+- No `-c` — search everything
+
+### Examples
+
+| User says | Command |
+|---|---|
+| "search for programming" / "find everything about programming" | `hypatia search "programming"` |
+| "search knowledge for rust" | `hypatia search "rust" -c knowledge` |
+| "what do you know about databases?" | `hypatia search "databases"` |
+
+## Vector Similarity Search
+
+Semantic search using embedding vectors. Finds entries with similar meaning, even when keywords don't match.
+
+```
+hypatia similar <query> [--limit N]
+```
+
+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.
+
+### Examples
+
+| User says | Command |
+|---|---|
+| "find similar to distributed systems" | `hypatia similar "distributed systems"` |
+| "semantic search for memory management" | `hypatia similar "memory management" --limit 5` |
+
+## JSE Query Translation
+
+JSE (JSON Search Expression) enables precise queries against the knowledge or statement tables.
+
+```
+hypatia query '<JSE-JSON>' [-s <shelf>]
+```
+
+### Query Structure
+
+The top-level operator is always `$knowledge` or `$statement`:
+
+```json
+["$knowledge", condition1, condition2, ...]
+["$statement", condition1, condition2, ...]
+```
+
+No conditions means "return all":
+
+```json
+["$knowledge"]
+```
+
+### Operator Reference
+
+| Operator | Purpose | Syntax |
+|---|---|---|
+| `$eq` | Equals | `["$eq", "field", "value"]` |
+| `$ne` | Not equals | `["$ne", "field", "value"]` |
+| `$gt` | Greater than | `["$gt", "field", "value"]` |
+| `$lt` | Less than | `["$lt", "field", "value"]` |
+| `$gte` | Greater than or equal | `["$gte", "field", "value"]` |
+| `$lte` | Less than or equal | `["$lte", "field", "value"]` |
+| `$like` | SQL LIKE pattern match | `["$like", "field", "pattern"]` |
+| `$contains` | Substring match in content JSON | `["$contains", "field", "value"]` |
+| `$content` | Match content JSON key-value pairs | `["$content", {"key": "value"}]` |
+| `$search` | Full-text search (FTS) | `["$search", "query text"]` |
+| `$and` | Logical AND | `["$and", cond1, cond2, ...]` |
+| `$or` | Logical OR | `["$or", cond1, cond2, ...]` |
+| `$not` | Logical NOT | `["$not", condition]` |
+| `$triple` | Triple position match | `["$triple", "Alice", "$*", "Bob"]` |
+| `$k-hop` | K-hop graph traversal (statement only) | `["$k-hop", "head", "relation", depth]` |
+| `$has` | Exact membership in a JSON field (arrays: element; scalars: equality; array value = any-of) — indexed | `["$has", "tags", "rust"]` |
+| `$json-contains` | Structural containment (PG `@>`) — indexed recall + exact recheck | `["$json-contains", {"tags": ["rust"]}]` |
+
+### Critical Syntax Rules
+
+1. **`$and` and `$or` take multiple operands directly**, NOT a nested array:
+   - CORRECT: `["$and", ["$eq", "name", "rust"], ["$contains", "tags", "systems"]]`
+   - WRONG: `["$and", [["$eq", "name", "rust"], ["$contains", "tags", "systems"]]]`
+
+2. **`$search` must be inside `$knowledge` or `$statement`**, never top-level. When inside `$knowledge`, it searches FTS with catalog=knowledge. When inside `$statement`, it searches with catalog=statement.
+
+3. **Field names** like `"name"`, `"triple"` are used as plain strings. For content JSON sub-fields (e.g., tags), `$contains` uses `json_extract_string` automatically.
+
+4. **Available fields for knowledge**: `name`, `created_at`, plus any content JSON field via `$contains`.
+
+5. **Available fields for statement**: `triple` (CSV-formatted head,relation,tail), `head`, `relation`, `tail`, `created_at`, `tr_start`, `tr_end`, plus content JSON fields via `$has`/`$contains`. For position-based triple matching, prefer `$triple` over `$contains`.
+
+6. **New in 0.3**: `$has` is the exact-membership operator (indexed; use it for tags/scopes lookups). `$contains` on array fields (`tags`/`scopes`/`figures`) routes to exact membership too; on other fields it stays substring. `$json-contains` matches whole-document containment (PG `@>`), e.g. `["$json-contains", {"tags": ["rust"]}]`.
+
+### `$triple` Operator
+
+The `$triple` operator provides position-based matching on statement triples. Each argument corresponds to head, relation, or tail. Use `"$*"` as a wildcard to match any value.
+
+```
+["$triple", <head_pattern>, <relation_pattern>, <tail_pattern>]
+```
+
+| Pattern | Meaning |
+|---------|---------|
+| `"Alice"` | Exact match |
+| `"$*"` | Wildcard — match any value |
+
+**Behavior**:
+- All 3 specified (no wildcards): uses `triple = ?` (primary key lookup, fastest)
+- Partial match: generates conditions on individual columns (`head = ? AND tail = ?`, etc.)
+- At least one non-wildcard required — all wildcards is an error
+- Arguments must be exactly 3
+
+| User says | JSE | Command |
+|---|---|---|
+| "find all relationships where Alice is the head" | `["$statement", ["$triple", "Alice", "$*", "$*"]]` | `hypatia query '["$statement", ["$triple", "Alice", "$*", "$*"]]'` |
+| "find all knows relationships" | `["$statement", ["$triple", "$*", "knows", "$*"]]` | `hypatia query '["$statement", ["$triple", "$*", "knows", "$*"]]'` |
+| "find everything related to Bob as tail" | `["$statement", ["$triple", "$*", "$*", "Bob"]]` | `hypatia query '["$statement", ["$triple", "$*", "$*", "Bob"]]'` |
+| "find the exact Alice knows Bob triple" | `["$statement", ["$triple", "Alice", "knows", "Bob"]]` | `hypatia query '["$statement", ["$triple", "Alice", "knows", "Bob"]]'` |
+| "Alice's relationships with Bob, combined with date filter" | `["$statement", ["$and", ["$triple", "Alice", "$*", "Bob"], ["$gt", "created_at", "2025-01-01"]]]` | `hypatia query '["$statement", ["$and", ["$triple", "Alice", "$*", "Bob"], ["$gt", "created_at", "2025-01-01"]]]'` |
+
+### `$like` Operator
+
+SQL LIKE pattern matching with user-defined wildcards (`%` = any chars, `_` = single char).
+
+```
+["$like", "field", "pattern"]
+```
+
+| User says | JSE | Command |
+|---|---|---|
+| "find entries whose name starts with Rust" | `["$knowledge", ["$like", "name", "Rust%"]]` | `hypatia query '["$knowledge", ["$like", "name", "Rust%"]]'` |
+| "find entries created in January 2025" | `["$knowledge", ["$like", "created_at", "2025-01-%"]]` | `hypatia query '["$knowledge", ["$like", "created_at", "2025-01-%"]]'` |
+| "find statements with head matching pattern" | `["$statement", ["$like", "head", "Alice%"]]` | `hypatia query '["$statement", ["$like", "head", "Alice%"]]'` |
+
+### `$content` Operator
+
+Match key-value pairs inside the `content` JSON column. Checks exact string equality for each specified key.
+
+```
+["$content", {"key1": "value1", "key2": "value2"}]
+```
+
+| User says | JSE | Command |
+|---|---|---|
+| "find all markdown-format entries" | `["$knowledge", ["$content", {"format": "markdown"}]]` | `hypatia query '["$knowledge", ["$content", {"format": "markdown"}]]'` |
+| "find json-format statements" | `["$statement", ["$content", {"format": "json"}]]` | `hypatia query '["$statement", ["$content", {"format": "json"}]]'` |
+| "find entries with specific data and format" | `["$knowledge", ["$content", {"format": "markdown", "data": "hello"}]]` | `hypatia query '["$knowledge", ["$content", {"format": "markdown", "data": "hello"}]]'` |
+
+### `$k-hop` Operator
+
+K-hop graph traversal on statement triples using recursive CTE. Explores entity neighborhoods and relationship paths.
+
+```
+["$k-hop", "head", "relation", depth]
+```
+
+- `"head"` — starting entity (required)
+- `"relation"` — filter by relation, or use `"$*"` for any
+- `depth` — number of hops (positive integer)
+
+| User says | JSE | Command |
+|---|---|---|
+| "who can Alice reach in 2 hops?" | `["$statement", ["$k-hop", "Alice", "$*", 2]]` | `hypatia query '["$statement", ["$k-hop", "Alice", "$*", 2]]'` |
+| "what's reachable from Alice via knows in 3 hops?" | `["$statement", ["$k-hop", "Alice", "knows", 3]]` | `hypatia query '["$statement", ["$k-hop", "Alice", "knows", 3]]'` |
+| "explore the graph around PostgreSQL" | `["$statement", ["$k-hop", "PostgreSQL", "$*", 2]]` | `hypatia query '["$statement", ["$k-hop", "PostgreSQL", "$*", 2]]'` |
+
+### Natural Language to JSE Examples
+
+| User says | JSE | Command |
+|---|---|---|
+| "find knowledge named rust" | `["$knowledge", ["$eq", "name", "rust"]]` | `hypatia query '["$knowledge", ["$eq", "name", "rust"]]'` |
+| "find all relationships involving Alice" | `["$statement", ["$triple", "Alice", "$*", "$*"]]` | `hypatia query '["$statement", ["$triple", "Alice", "$*", "$*"]]'` |
+| "who does Alice know?" | `["$statement", ["$triple", "Alice", "knows", "$*"]]` | `hypatia query '["$statement", ["$triple", "Alice", "knows", "$*"]]'` |
+| "what type of things relate to Bob?" | `["$statement", ["$triple", "$*", "$*", "Bob"]]` | `hypatia query '["$statement", ["$triple", "$*", "$*", "Bob"]]'` |
+| "find knowledge named rust that contains 'systems' in tags" | `["$knowledge", ["$and", ["$eq", "name", "rust"], ["$contains", "tags", "systems"]]]` | `hypatia query '["$knowledge", ["$and", ["$eq", "name", "rust"], ["$contains", "tags", "systems"]]]'` |
+| "find knowledge NOT named rust" | `["$knowledge", ["$not", ["$eq", "name", "rust"]]]` | `hypatia query '["$knowledge", ["$not", ["$eq", "name", "rust"]]]'` |
+| "find all is_a relationships" | `["$statement", ["$triple", "$*", "is_a", "$*"]]` | `hypatia query '["$statement", ["$triple", "$*", "is_a", "$*"]]'` |
+| "find entries whose name starts with 'Al'" | `["$knowledge", ["$like", "name", "Al%"]]` | `hypatia query '["$knowledge", ["$like", "name", "Al%"]]'` |
+| "show all knowledge" | `["$knowledge"]` | `hypatia query '["$knowledge"]'` |
+| "find knowledge created after 2025-01-01" | `["$knowledge", ["$gt", "created_at", "2025-01-01"]]` | `hypatia query '["$knowledge", ["$gt", "created_at", "2025-01-01"]]'` |
+| "find knowledge containing 'language' in data" | `["$knowledge", ["$contains", "data", "language"]]` | `hypatia query '["$knowledge", ["$contains", "data", "language"]]'` |
+
+### Options (limit, offset, catalog)
+
+Use object form for the top-level operator to pass options:
+
+```json
+{"$knowledge": [["$search", "rust"]], "limit": 10, "offset": 0}
+```
+
+Command: `hypatia query '{"$knowledge": [["$search", "rust"]], "limit": 10}'`
+
+## Disambiguation Rules
+
+When the user's request is ambiguous, follow this priority:
+
+1. **Exact name mentioned** ("get Rust", "show Alice") → `knowledge-get` for direct lookup
+2. **Explicit type** ("find knowledge about X" / "find statements about X") → JSE query with the corresponding top-level operator
+3. **Relationship language** ("who does Alice know?", "what is Rust related to?", "relationships of X") → JSE `$statement` query with `$triple` operator
+4. **Graph exploration** ("who can Alice reach?", "what's connected to X", "neighborhood of X") → JSE with `$k-hop` operator
+5. **Semantic/similarity** ("find similar to X", "things like X", "semantically related") → `hypatia similar` (vector search)
+6. **Pattern matching** ("names starting with X", "entries from January") → JSE with `$like` operator
+7. **Content filtering** ("markdown entries", "entries with format X") → JSE with `$content` operator
+8. **Broad/ambiguous** ("find everything about X", "what do you know about X") → `hypatia search` (covers both knowledge and statements)
+9. **Create/store/remember** → knowledge-create + statement-create (always create relationships alongside knowledge entries)
+
+## Shell Escaping
+
+Always wrap JSE JSON in **single quotes** to prevent shell interpretation of `$`, `"`, `!`, etc.:
+
+```bash
+hypatia query '["$knowledge", ["$eq", "name", "rust"]]'
+```
+
+If the content contains single quotes, escape them:
+
+```bash
+hypatia query '["$knowledge", ["$eq", "name", "Alice'\''s project"]]'
+```
+
+## Output Format
+
+- **Knowledge entries**: `{"name": "...", "content": {"format": "...", "data": "...", "tags": [...]}, "created_at": "..."}`
+- **Statements**: `{"triple": "head,relation,tail", "head": "...", "relation": "...", "tail": "...", "content": {...}, "created_at": "...", "tr_start": "...", "tr_end": "..."}`
+- **Search results**: `{"id": N, "catalog": "...", "key": "...", "content": "...", "rank": N.N}`
+- **Empty results**: prints "No results found."
+
+## Sandboxed / Read-Only Direct Access (known workaround)
+
+When running inside a sandboxed harness (e.g. DSH `workspace-write`), the hypatia CLI and plain
+`sqlite3 ~/.hypatia/...` may both fail with SQLite error 14 (`unable to open database file`):
+even read-only SQLite needs to create WAL/journal temp files next to the database, and
+`~/.hypatia` lies outside the writable workspace. **Do not retry the same failing command** —
+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;"
+```
+
+- 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).
+- Schema hints: tables include `knowledge` and `statement`; statement triples are stored in
+  `head` / `relation` / `tail` columns.
+
+This fallback was validated: the same query fails at error 14 without the URI params and returns
+correctly with them.
+
+## Important Notes
+
+- There is no `statement-get` CLI command. Use JSE queries (`$statement` with conditions) to find statements. `statement-delete` is available for deletion.
+- The `-s` / `--shelf` flag defaults to `"default"` for all commands.
+- The REPL mode (`hypatia repl`) is interactive and should NOT be used from this skill. Always use one-shot CLI commands.
+- Content (`-d`) is stored as a string in the content JSON's `data` field.
+- Tags (`-t`) are comma-separated strings.
+- **Always create statements alongside knowledge entries** to maintain graph connectivity. Every knowledge entry should have at least one corresponding `is_a` statement.
+- **Normalize relative temporal expressions to absolute dates/times before storing.** When content contains "明天", "下周一", "三小时后", "tonight", etc., rewrite them using the current date/time as the reference point. Example: "明天提醒我备份数据" → store "2026年8月29日提醒我备份数据". A relative date is meaningless when the memory is recalled later.