Find and read a record

Start with the identity and type of the thing you need, then inspect the current value and its evidence.

Source: docs/topics/interfaces/read-search.md · Read Markdown · 08598d0

Search or a stable identifier locates an entity; a structured read verifies its current fields.

Narrow the question

If you have a returned entity ID, retrieve that exact entity first. If you have a stable identifier, use identifier retrieval. For a category question, search with an entity type and bounded result count. A broad text query is useful for discovery, but matching words do not establish that two hits are the same entity.

What you know	Good first read	Check next
Exact entity ID	Entity snapshot or `entities get`	Type, fields, and observation context
An identifier	Identifier retrieval or `entities search`	Which entity the identifier resolved to
A type and a few fields	Filtered entity query or `entities list --type`	User scope and pagination
A person or organization described several ways	Multi-signal identification	Candidate identities before a write

For terminal work, neotoma schemas list and neotoma entities list --type task --limit 5 illustrate the read shape without changing data. The type must exist in the selected instance. For HTTP clients, OpenAPI defines POST /entities/query and the snapshot routes. MCP clients expose retrieval tools on the configured instance. Interfaces helps choose a client path.

Verify an empty result

A zero can mean the query used the wrong type or field, the instance or user scope is different, a page of results was missed, or there is genuinely no match. Before reporting absence, read an entity known to exist through the same connection. Then inspect the schema and broaden the query carefully. A known-positive result validates the path; it does not prove every possible search mode is complete.

When text search follows a recent write, use the exact returned entity ID for read-back. A search index may lag the write path; the entity snapshot is the right place to verify the immediate result. The search subsystem reference explains indexing and filters.

Read beyond the answer

The snapshot is the current view, not the full chain of claims. For a disputed value, list its observations and inspect field provenance. A source-backed observation may point to a file and interpretation; a direct fact may have no separate file. Inspect a change gives the comparison path, and Sources and provenance explains what the trace can establish.