How Do I Query Data in My Evolutionary Neural Memory?

Querying an ENM uses the same AIP Intents as writes: primarily GetEvent and GetEventsForTags.

Query via the Dashboard

The Evolutionary Neural Memory Explorer is the fastest way to explore data interactively: select your ENM, compose a query, and execute.

Query via the SDK

Connect to the gateway TCP endpoint and set GatewayActorName to the gateway FQN you dialed (see Add data).

GetEvent — retrieve one event by unique id

Event is the record you want. NeuralMemory.GetEvent is how much of it to return. Set GetLinks to include adjacency.

msg := &message.Message{
    Envelope: message.Envelope{
        To:         "Foobar@zeroth.example.com",
        From:       client.FromAddress(),
        Intent:     message.IntentType.GetEvent,
        ClientName: client.ClientName(),
    },
    Event: &message.EventFields{UniqueId: "person-alice"},
    NeuralMemory: &message.NeuralMemoryFields{
        GetEvent: &message.GetEventOptions{
            GetLinks:      true,
            GetLinkTags:   true,
            GetTargetTags: true,
        },
    },
}
resp, err := client.SendMessage(ctx, msg)

GetEventsForTags — search by tag clause

msg := &message.Message{
    Envelope: message.Envelope{
        To:         "Foobar@zeroth.example.com",
        From:       client.FromAddress(),
        Intent:     message.IntentType.GetEventsForTags,
        ClientName: client.ClientName(),
    },
    Payload: &message.PayloadFields{
        Data: "clause_type:S\tboolean:or\tlow:name=Alice",
    },
    NeuralMemory: &message.NeuralMemoryFields{
        GetEventsForTags: &message.GetEventsForTagsOptions{
            BufferResults: true,
        },
    },
}
resp, err := client.SendMessage(ctx, msg)

Use CountOnly: true in GetEventsForTags options for health-style probes that only need a count.

Pagination and relevance (end_result)

start_result / end_result slice results in storage order, not relevance order. They are not a top-K by match quality. For ranking, fetch the full candidate set (or disable pagination) and re-rank client-side.

Interpreting _hits

_hits counts matched tag values including stored frequency (a term stored with frequency 6 contributes 6). It is a match count, not a relevance score. Re-rank on distinct matched keys, then IDF-weighted frequency — do not sort on _hits alone.

Concurrency

Keep roughly 8–10 concurrent ENM requests in flight per actor connection. Higher fan-out can cause silent timeouts; retry serially if a small batch returns empty.

Verify with podos

podos get --host <gateway-host> --port 62312 \
  --connection-gateway zeroth.example.com \
  --actor Foobar@zeroth.example.com \
  --unique-id person-alice --data --tags

podos search --host <gateway-host> --connection-gateway zeroth.example.com \
  --actor Foobar@zeroth.example.com --tag name=Alice

Reading links

A link is always seen from the object you retrieved or that a search returned. Strength is that object toward its neighbor. The other direction is another Linked row from a Get or search of the neighbor.

One StoreBatchLinks or LinkEvent stores both directions. That write uses LinkFields (unique_id_a, unique_id_b, strength_a, strength_b). The read type is Linked. It has one strength and no A/B pair. NeuralMemory.Link and BatchLinks[].Link stay LinkFields.

Ask for links on the request:

GetLinkTags / GetTargetTags (and the same names in each SDK) fill tags and target_tags.

Decoded rows are on the event records:

for _, event := range resp.Response.EventRecords {
    for _, link := range event.Links {
        fmt.Println(link.SourceUniqueId, "->", link.TargetUniqueId, link.Strength, link.Category)
    }
}

for event in response.response.event_records:
    for link in event.links:
        print(link.source_unique_id, "->", link.target_unique_id, link.strength, link.category)

Linked fields

GetEvent

Wire records are tab-separated. The samples below use spaces so they can be read.

The _link line does not carry the source. The SDK sets source_id and source_unique_id from the event you asked for (Event.Id / Event.UniqueId). Header _event_id / _unique_id are used only when those request fields are empty.

_link=+1  unique_id=lk_a_to_x  target_event=evt_x  target_unique_id=eo_nbr_x  strength=0.750000  category=supplies_to
_link=+2  unique_id=lk_b_to_a  target_event=evt_b  target_unique_id=eo_nbr_b  strength=0.250000  category=supplies_to

Both rows have source_unique_id of the object you got (eo_seed_a). The first neighbor is eo_nbr_x at 0.75. The second is eo_nbr_b at 0.25. The second row is still the returned object's view of that neighbor.

GetEventsForTags

The hit's view is already on the line: source, source_unique_id, target, target_unique_id, strength. If source_unique_id is empty, the SDK fills it from the parent hit's unique id.

_event_id=evt_a  unique_id=eo_seed_a
_link=+1  unique_id=lk_a_to_x  source=evt_a  source_unique_id=eo_seed_a  target=evt_x  target_unique_id=eo_nbr_x  strength=0.750000  category=supplies_to

That row is the same Linked shape as the first GetEvent row above.

Dashboard query JSON

POST /podos/neural-memory/query returns the same adjacency. Each link object has source_id, source_unique_id, target_id, target_unique_id, strength, and category. Link tags are tags. Neighbor tags are target_tags. Set get_event_get_links or get_events_for_tags_get_match_links on the request.

Next: How do I structure data in my ENM? — modeling events, tags, and links as a graph.