Hypatia

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

Archive Files

Archive files (images, PDFs, data, etc.) are stored in the shelf's archives/ directory and referenced via archive:// paths.

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:

hypatia query '["$knowledge", ["$contains", "tags", "archive"]]'
hypatia query '["$knowledge", ["$content", {"mime_type": "image/png"}]]'

To reference an archive when creating knowledge:

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.

# 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,"

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:

# 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.

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" [--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.

Read

hypatia knowledge-get <name>

Update

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.

Delete

hypatia knowledge-delete <name>

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>" [--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

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:

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:

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:

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:

Combined Queries

For rich retrieval, combine graph traversal with content filtering:

# 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

Vector Similarity Search

Semantic search using embedding vectors. Finds entries with similar meaning, even when keywords don't match.

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

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:

["$knowledge", condition1, condition2, ...]
["$statement", condition1, condition2, ...]

No conditions means "return all":

["$knowledge"]

Operator Reference