When to use
Use when the user names a specific project, person, service, or concept and asks what is known about it. Entities are the graph-shaped view of memory — structured facts and relationships rather than free text.
Triggers:
- "Tell me about the entity …"
- "Look up …"
- "What do we know about project/service/tool X?"
- Any reference to a named thing that could have linked facts.
Inputs
name(required) — canonical entity name, ideally as the user wrote it.- Optional: entity type hint (project, person, service, tool).
Procedure
- Extract the entity name from the user's message. Preserve original capitalization unless ambiguous.
- Call
remnic_entity_getwith that name. - If the entity is found, present its facts and relationships in a short structured view (facts, relations, last updated).
- If the entity is missing, say so and offer to create one via
remnic-rememberwith the user's permission. - When multiple candidates match, list them briefly and ask which the user meant.
Efficiency plan
- Do not call
remnic_entity_getspeculatively for every proper noun — only when the user asked or the task depends on it. - Cache the entity payload within the current turn; do not re-fetch for the same name.
- Pair with
remnic-recallwhen unstructured context would round out the entity view.
Pitfalls and fixes
- Pitfall: Guessing entity names. Fix: Use the user's wording; disambiguate rather than inventing.
- Pitfall: Dumping the full entity payload. Fix: Summarize into a compact facts/relations/last-updated block.
- Pitfall: Treating a missing entity as a bug. Fix: Missing just means the graph has not captured it yet — offer to create it.
Verification checklist
-
remnic_entity_getwas called with a user-supplied or user-confirmed name. - Output shows facts, relationships, and timestamps in a compact view.
- Missing entities are acknowledged plainly with an offer to create.
- Legacy
engram_entity_getalias was not preferred overremnic_entity_get.
Tool names: canonical name is
remnic_entity_get. The legacyengram_entity_getalias remains accepted during v1.x.