elizaos--eliza/plugins/plugin-relationships/README.md

@elizaos/plugin-relationships

Entity and relationship knowledge graph for Eliza agents.

Provides the ENTITY umbrella action (person / organization / place / project / concept CRUD with identity claims, typed relationships, and merge), an ENTITY_GRAPH context provider for the planner, and a drizzle pgSchema('app_relationships') with entities and relationships tables.

Status

Scaffolded — decomposition in progress. Action and provider handlers are stubs that return a TODO marker. The real EntityStore, identity merge engine, voice-observer-bridge, and RelationshipStore still live in @elizaos/plugin-personal-assistant; they will move here in a follow-up pass.

Migration mapping from @elizaos/plugin-personal-assistant

Source under plugins/plugin-personal-assistant/src/	Will move to
actions/entity.ts (ENTITY action)	plugins/plugin-relationships/src/actions/entity.ts
lifeops/entities/store.ts (EntityStore)	plugins/plugin-relationships/src/services/entity-store.ts
lifeops/entities/merge.ts (identity merge engine)	plugins/plugin-relationships/src/services/merge.ts
lifeops/entities/voice-observer-bridge.ts	plugins/plugin-relationships/src/services/voice-observer-bridge.ts
lifeops/entities/voice-observer.ts	plugins/plugin-relationships/src/services/voice-observer.ts
lifeops/entities/voice-attribution.ts	plugins/plugin-relationships/src/services/voice-attribution.ts
lifeops/entities/types.ts (Entity, registries)	folded into plugins/plugin-relationships/src/types.ts
lifeops/relationships/store.ts (RelationshipStore)	plugins/plugin-relationships/src/services/relationship-store.ts
lifeops/relationships/extraction.ts	plugins/plugin-relationships/src/services/relationship-extraction.ts
lifeops/relationships/types.ts (Relationship, registries)	folded into plugins/plugin-relationships/src/types.ts
LifeOps lifeops provider — entity / relationship sections	plugins/plugin-relationships/src/providers/entity-graph.ts

DB rows currently live in the LifeOps schema (app_lifeops.life_entities, life_entity_identities, life_entity_attributes, life_relationships). The new plugin owns the dedicated app_relationships schema with two minimal tables; the rich identity + attribute + edge-state shapes from lifeops will land in a follow-up migration.

Plugin surface

Action

• ENTITY (src/actions/entity.ts) — umbrella op dispatch. Accepted ops: create, read, list, log_interaction, set_identity, set_relationship, merge. Contexts: people, contacts, relationships. STUB returns a TODO marker.

Provider

• ENTITY_GRAPH (src/providers/entity-graph.ts) — injects a projection of the owner's known entities and ego-network edges into the planner. STUB returns an empty projection.

Schema

• relationshipsSchema / entitiesTable / relationshipsTable (src/db/schema.ts) — pgSchema("app_relationships"). Registered via the plugin object's schema field so the elizaOS runtime handles migrations.

Layout

src/
  index.ts                       Public exports + default Plugin export
  plugin.ts                      Plugin object (action + provider + schema)
  types.ts                       Entity / Relationship interfaces + constants
  actions/
    entity.ts                    ENTITY umbrella action (STUB)
  providers/
    entity-graph.ts              ENTITY_GRAPH provider (STUB)
  db/
    schema.ts                    drizzle pgSchema + entities + relationships tables
    index.ts                     re-export schema

Commands

bun run --cwd plugins/plugin-relationships build       # bun build → dist/ + tsc types
bun run --cwd plugins/plugin-relationships dev         # hot-rebuild via build.ts
bun run --cwd plugins/plugin-relationships test        # vitest run
bun run --cwd plugins/plugin-relationships typecheck   # tsgo --noEmit
bun run --cwd plugins/plugin-relationships check       # typecheck + test
bun run --cwd plugins/plugin-relationships clean       # rm -rf dist .turbo

Conventions / gotchas

• @elizaos/plugin-sql must be loaded first. The plugin declares this in dependencies: ["@elizaos/plugin-sql"]; the runtime registers DB migrations for app_relationships automatically.
• SELF_ENTITY_ID = "self" is the canonical id of the owner. All ego-network edges originate from self.
• relationshipType is open-string. The lifeops RelationshipTypeRegistry carries the built-in set (follows, colleague_of, partner_of, manages, …) and will be ported alongside the store.
• Stubs only. Do not rely on ENTITY or ENTITY_GRAPH returning real data yet — both intentionally return a TODO / empty result while the port is in progress.