Query Neotoma Memory

When to use

When the user asks about previously stored information, wants to recall facts, explore relationships, or view a timeline of events.

Retrieval strategy

Start with narrow, targeted queries and expand only on ambiguity or low confidence.

By identifier (names, emails, specific items)

Use retrieve_entity_by_identifier first:

• Fast lookup by name, email, tax_id, or any canonical identifier.
• Optionally scope to a specific entity_type.

By type or category

Use retrieve_entities with filters:

• entity_type: filter to a specific type (task, contact, event, transaction).
• search: free-text semantic search across all fields.
• published_after/published_before: date range filters.
• sort_by/sort_order: control ordering.
• limit/offset: pagination.

By time

Use list_timeline_events for chronological queries:

• Filter by event type, date range, or source.
• Returns events derived from date fields in stored data.

By relationships

Use retrieve_related_entities to traverse the entity graph:

• Start from a known entity and follow relationship links.
• Control direction (inbound, outbound, both) and hop count.

Use retrieve_graph_neighborhood for a full picture:

• Returns related entities, relationships, sources, and events around a node.

Entity details

Use retrieve_entity_snapshot for the full current state of a single entity with provenance. Use list_observations to see the complete history of changes. Use retrieve_field_provenance to trace a specific field back to its source.

Response format

When displaying retrieved entities, show a Markdown table per entity with all substantive fields. Use human-readable property names (snake_case to Title Case). Omit opaque internal IDs.

Do not

• Run broad unfiltered queries when a specific identifier is available.
• Invent or hallucinate memory-backed claims when retrieval finds nothing.
• Skip the relationship graph when the user asks about connections between entities.