Good entity candidates:

• People you mention more than twice. Customers, contractors, journalists, contacts.
• Projects with their own context. Repo + stack + decisions.
• Servers / infrastructure you reference by name. Prod, dev2, customer-server.
• Customers in a multi-tenant setup.
• Products / services you sell.

Bad entity candidates:

• One-off facts. "We chose Vite over Webpack." That is nex_decide, not an entity.
• Things mentioned exactly once. Promote to entity later if it comes up again.
• Anything that already lives in your CRM / database. Memory should reference the database, not duplicate it.

Create entity: type=person, name="Max Mueller", category="press-contact"
Add observations:
- works at PR-Netzwerk Hamburg
- knows the editor-in-chief at FAZ Wirtschaft
- competent but very direct in conversation
- prefers email over phone

Claude calls nex_entity_create then nex_entity_observe four times. The entity has a stable id, the observations append to it.

You can update later:

Add observation to "Max Mueller": pitched our MCP launch to FAZ on April 15, no response yet.

nex_entity_observe adds the new fact. Old ones stay. The entity history is the timeline.

Relations are typed edges. Common types: KNOWS, WORKS_AT, USES, PART_OF, DEPENDS_ON, OWNS.

Create entity: type=organization, name="FAZ Wirtschaft"
Relate "Max Mueller" KNOWS "FAZ Wirtschaft" (with note: "via editor-in-chief")

nex_entity_relate writes the edge. Now a graph traversal can answer "who do I know at FAZ?" by walking the KNOWS edges from FAZ back to people.

For a project-style entity:

Create entity: type=project, name="ProjectAcme", category="customer-project"
Add observations:
- Stack: Next.js 16 + Postgres + Docker
- Deployed on: prod-server (46.225.14.141)
- Customer contact: Customer-A
Relate "ProjectAcme" USES "Postgres"
Relate "ProjectAcme" DEPLOYS_TO "prod-server"
Relate "Customer-A" OWNS "ProjectAcme"

Now you can walk the graph: "Customer-A → owns ProjectAcme → uses Postgres". Or in reverse: "what projects use Postgres? → ProjectAcme → owned by Customer-A".

Three core read operations:

• nex_entity_search — fuzzy search by entity name or observation content. Returns matching entities ranked by relevance.
• nex_entity_open — full detail on one entity: all observations, all relations, history.
• nex_entity_graph — return an N-hop subgraph around an entity. Default depth 1 (entity + immediate neighbors). Increase depth for "show me everything two steps away from Customer-A".

Examples in practice:

Search the graph for "FAZ"

Returns the FAZ Wirtschaft entity plus any others that mention FAZ in observations.

Open "ProjectAcme"

Full detail: observations, relations to Postgres + prod-server + Customer-A, history of every change.

Show the graph around Customer-A, depth 2

Customer-A → owns ProjectAcme → uses Postgres + deploys to prod-server. Plus any other customers they relate to.

Run aiguide_validate_step. The validator confirms a memory MCP is active.

When the graph beats flat search

• Multi-hop questions. "Which customers run on which servers?" — flat search cannot follow the chain. The graph can.
• Aggregation by relationship. "All projects that USE Postgres." — one graph traversal vs trying to remember every project name.
• Timeline of one thing. "How has Customer-A's situation changed over the last 3 months?" — entity history is ordered, observations stay attached to the entity.
• Resolving ambiguity. "Max" alone is unclear. "Max Mueller (press-contact)" vs "Max Schmidt (developer)" — entities have stable ids, search by id is unambiguous.

When flat search is better

• One-off facts. "What was that postgres connection string?" — search beats graph for ad-hoc lookup.
• Decisions and rationale. nex_decide is the right tool for "we chose X over Y because Z".
• Patterns and standing rules. Just nex_learn them.

The mental model: flat learnings are notes, the graph is a Rolodex + a CRM + a server inventory rolled into one. Use the right tool for the shape of the thing you are saving.

Bonus — entity templates

When you find yourself creating the same entity shape over and over (people with the same fields, projects with the same stack questions), tell Claude in CLAUDE.md what the template looks like:

## Memory: entity templates

For new `person` entities always observe: company, role, how I know them, preferred contact, last interaction date.

For new `project` entities always observe: stack, deploy target, customer (if any), production URL.

Claude reads that on session start and uses it as a checklist when creating entities. Reduces "wait, what else should I save about this person?" thinking.