traverse
Explore an entity's declared relationships and mentions as a graph, tracing connections up to max_hops. Retrieve related entities, their relations, and record references for a chosen entity.
Instructions
The neighbourhood of a declared entity, as a graph: the entity named, its aliases, the entity -> entity relations declared on it and on what they reach, up to max_hops in either direction, and the refs of the records that mention each entity. Only what was declared (declare_associations, or associations on store); nothing is inferred. No record text: expand a ref with get_contents. entity is a name or an alias, compared after normalization; when it names more than one entity this call can read (a project's and the global pool's), all are starts. ORDER: entities by hops, then by the most recently declared relation that reached them, then by id; mentions by record id; relations most recently declared first. limit bounds both the entities returned and the refs listed per entity. Response: {entity, max_hops, limit, entities:[{id, name, hops, aliases?, mentions?, mentions_omitted?}], relations:[{id, subject, predicate, object, declared_by, declared_at, anchor_ref?}] (subject/object are entity ids from entities; a relation is listed when both ends are), entities_omitted?, bounds?:{omitted:[max_hops | limit]}, reason?:'no_such_entity'}. Relation ids are what declare_associations' retract takes. Records are listed only when this call could read them: the project, channel and source_id filters apply as in recall.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum entities returned, and maximum mentioning refs listed per entity. | |
| entity | Yes | A declared entity name or alias. | |
| channel | No | Memory channel filter -- same semantics as in `recall`. | |
| agent_id | Yes | Agent identifier | |
| max_hops | No | Relations to follow from the entity, in either direction. 0 returns the entity alone. | |
| source_id | No | Per-user source filter on the mentioning records -- same semantics as in `recall`. | |
| project_id | No | γ filter -- same semantics as in `recall`. v2.5.1: pass '@auto' to resolve this agent's default from the server's operating context (the resolution is echoed as resolved_project_id; an unmapped agent yields operating_context_warning). bug-186: resolution requires a configured operating context. With none — the default, and equally the outcome of a sidecar that fails to parse — the sentinel is NOT resolved: it is stored and filtered as the literal project_id '@auto', resolved_project_id echoes '@auto', and no warning is raised. Read resolved_project_id before relying on the resolution. |