Skip to main content
Concept · core

Use when

You look for what a project says or knows, before you read, cite, answer or extract.

Looking for something else?

A File by its name or ID (card File). Everything about one topic as a packet (card Context). Walking relationships from a known entity (card Relationship).

​
For

Search reads two places. File search returns passages: pieces of the text extracted from a File’s current version. Each passage comes with the File, the version and the passage ID. Graph search returns entities saved in the Graph, with their type and ID. Search is how a job moves from Files to answers. Search finds a passage, you open and cite it, and an entity can then hold the fact with that citation. Search the Graph before you extract or capture, so you reuse an entity that already exists. A result is either a passage or a File. Passages are the default. To choose among many Files, ask for the Files that matched. Each File comes with its synopsis (card Synopsis), so you open the few that matter and cite their passages. The steps are search, then open, then cite. A new edition of a File takes over in search once its version is ready (card file). Every File search reports the mode that ran and how much of the project it covered. Read that report before you decide that something is not there.

​
Use when

  • You need passages to answer a question or to cite.
  • You must choose which of many Files to open, before you read any of them.
  • You look for an entity by name, description or property before you create one.
  • You must tell the person what the project holds on a topic.
  • A result says it ran in a different mode than you asked for.

​
Not this

  • A File by name when you know it: use penumbra files find (card File).
  • All you know about one topic, bundled for an agent: use card Context.
  • Entities one relationship away from a known entity: use card Relationship.

​
Rules

  1. search.1 Choose the mode on purpose. Lexical mode matches words and works as soon as a version is searchable. Semantic mode matches meaning. Hybrid mode does both. Your job: the defaults differ by door. penumbra files search uses hybrid, and penumbra graph search uses lexical. The command penumbra search uses each side’s own default, unless you pass --mode. The MCP tool omnisearch and the program method penumbra.search use hybrid for both. The MCP tool file_gallery starts in a text mode that does not use meaning.
  2. search.2 The result states the mode that ran. Your job: read it. A hybrid search runs as lexical, with a warning, in three cases. No version has finished embedding. Meaning search is unavailable. The query is too long for it. A semantic search with no embedded version returns nothing and warns. If meaning search is unavailable, it fails with semantic_unavailable.
  3. search.3 File search covers only the current version of each live File. Enforced: older versions, trashed Files and versions that are still processing never appear. While a new edition processes, search still returns the old edition.
  4. search.4 Meaning search trails word search. A version is searchable by words first and by meaning after embedding. Your job: when a new File is missing from a meaning search, run penumbra files inspect on it and read the lexical and semantic status. Search by words in the meantime.
  5. search.5 Filters narrow a File search: File IDs, collection IDs, tags and media types. Enforced: an unknown or trashed File ID, or a File or collection ID from another project, refuses the whole search with search_filter_not_found. It does not say which ID was wrong. Filters never narrow the Graph side.
  6. search.6 penumbra search runs the File search and the Graph search together. Your job: read each side’s own mode and warnings. One side can fail while the other answers, and the command exits non-zero only when every side fails. The limit is per side, so the lists share no ranking. With --results files, the Files side also reads the Files that matched. If that read fails, the Files side fails.
  7. search.7 Graph search finds only entities that are in the Graph. Staged items in a workspace are not found. Your job: after a submit returns applied, an entity can still be missing for a moment, so search again or open it by ID.
  8. search.8 Search has no filter or order by source date, and a File row carries none. Your job: read the source date from the version listing with penumbra files versions, and order the results yourself.
  9. search.9 Every File result carries the File ID, the version ID and the passage ID. An audio or video result carries a moment ID in place of the passage ID. Your job: keep all three with each fact you use. A citation needs them, and the person can reopen the passage with them (card Passage and citation).
  10. search.10 Zero results does not mean the project lacks the fact. Lexical mode needs every plain word to match, and quoted phrases and or work. Your job: try hybrid mode, a shorter query and the coverage report. A View can also hide items, which then look missing.
  11. search.11 Each door sets its own limits. Enforced: penumbra search takes a query of up to 8,192 characters and 1 to 50 results per side. Its entity side takes up to 512 characters: a longer query still searches passages, and the entity side fails with invalid_input. The MCP tool omnisearch and penumbra.search take a query of up to 2,048 characters and 1 to 20 results per catalog. They take up to 100 collections and up to 20 tags, media types or File references. A request outside the limit is refused as invalid.
  12. search.12 Choose what one result is. Enforced: results:'passages' is the default and returns passages. results:'files' returns one row for each File that matched. A row has its name, type, tags, collections, best-matching page, whether it is searchable by words and meaning, and its synopsis (card Synopsis). A row carries no source date yet. Your job: ask for Files when you must choose, then read the few that matter and cite their passages. The command is penumbra search --results files. --no-synopsis and synopsis:false leave the synopses out.
  13. search.13 The filters combine in one way. Enforced: a File must be in at least one of the collections you name. It must carry every tag you name. It must match one of the media types and be one of the File references. The tool omnisearch and penumbra.search refuse a filter when catalogs leaves out files. Your job: name collections by ID, and check them in project_overview first.
  14. search.14 A search can read one catalog or both. Enforced: catalogs takes files, graph or both. Without it, the search reads every catalog the connection can read. A catalog it cannot read is refused with catalog_unavailable. The command penumbra search uses --only for the same choice.

​
Failure signs

​
Doors

The MCP tool search_graph defaults to lexical mode and takes 1 to 100 results. The CLI command penumbra graph search takes the same range.

​
The CLI word

The CLI calls a passage a chunk.

​
HTTP reference

​
Keep going

File · Passage and citation · Entity · Collection · Synopsis · Search returns nothing