| name | forgetful-entities |
| description | Model the things knowledge attaches to — people, organisations, devices, products, system components. Use when a new thing surfaces that memories will reference, when relationships between things need recording (owns, depends on, part of), or when another skill routes a pointable thing here. Litmus: an entity is a noun you could point at; knowledge about it stays a memory. |
| license | MIT |
| tags | ["entities","knowledge-graph","relationships","modelling"] |
| allowed-tools | ["mcp__forgetful__discover_forgetful_tools","mcp__forgetful__how_to_use_forgetful_tool","mcp__forgetful__execute_forgetful_tool","Bash(forgetful:*)"] |
Modelling entities in Forgetful
Entities are the graph's nouns. Model the thing once, then let knowledge accrue to it
through links — that is what makes get_entity_memories a useful reverse lookup later.
Invoking operations
Operations are named by registry name (create_entity, link_entity_to_memory, ...).
Invoke via whichever surface this agent has:
- MCP:
execute_forgetful_tool(tool_name="create_entity", arguments={...})
- CLI:
forgetful call create_entity --args '{"name": "..."}' --json
Get any operation's schema at runtime: how_to_use_forgetful_tool (MCP) or
forgetful tools info <operation> (CLI) — schemas are deliberately not repeated here.
Step 1 — Apply the litmus, then dedupe
Can you point at it? "Sarah Chen" is an entity; "Sarah is great at debugging async issues"
is a memory linked to her. The fact stays a memory (forgetful-remember); the thing it is
about becomes the entity.
Before creating, search_entities for the thing under its likely names — it matches both
name and aka. Set aka at creation time for any alternative names the thing goes by, so
a later dedupe search under a different name still finds it.
Done when: the thing either already exists (use it) or is confirmed new.
Step 2 — Create with a type
create_entity with a name and type: Organization, Individual, Team, Device, System, or
Other (custom_type required when Other). Stored Title-case; matched case-insensitively on
input. Check list_entities for the types already in use and match them — a graph where
servers are sometimes typed "Device" and sometimes "System" fragments reverse lookups.
Done when: the entity exists once, typed consistently with the existing graph.
Step 3 — Link knowledge and projects as they accrue
link_entity_to_memory whenever a memory is about the entity — done at capture time,
this is one line; done later, it is an archaeology project.link_entity_to_project when the entity belongs to a project's world.
Done when: knowledge about the thing is reachable from the thing (get_entity_memories).
Step 4 — Record relationships between entities
create_entity_relationship with a direction and a type. Keep the vocabulary small and
consistent — owns, depends_on, part_of, uses, created_by cover most structure.
Check get_entity_relationships on either entity first and reuse the types already in the
graph before coining new ones. Direction carries meaning: A depends_on B is a statement
about A.
Done when: the relationships that answer real questions (impact, structure, responsibility)
are recorded, and none duplicate an existing edge.
