joshuaswarren/remnic/remnic-entities

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

1. Extract the entity name from the user's message. Preserve original capitalization unless ambiguous.
2. Call remnic_entity_get with that name.
3. If the entity is found, present its facts and relationships in a short structured view (facts, relations, last updated).
4. If the entity is missing, say so and offer to create one via remnic-remember with the user's permission.
5. When multiple candidates match, list them briefly and ask which the user meant.

Efficiency plan

• Do not call remnic_entity_get speculatively 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-recall when 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_get was 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_get alias was not preferred over remnic_entity_get.

Tool names: canonical name is remnic_entity_get. The legacy engram_entity_get alias remains accepted during v1.x.