@elizaos/plugin-relationships 2.0.3-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# @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
+
+```bash
+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.

package/assets/hero.svg

@@ -0,0 +1,75 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" width="1024" height="1024" role="img" aria-label="Relationships">
+  <defs>
+    <linearGradient id="bg-relationships" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#241528"/>
+      <stop offset="1" stop-color="#190b19"/>
+    </linearGradient>
+    <radialGradient id="blobA-relationships" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0" stop-color="#b22fda" stop-opacity="0.55"/>
+      <stop offset="1" stop-color="#b22fda" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="blobB-relationships" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0" stop-color="#c3289f" stop-opacity="0.5"/>
+      <stop offset="1" stop-color="#c3289f" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="vig-relationships" cx="0.5" cy="0.42" r="0.75">
+      <stop offset="0" stop-color="#000000" stop-opacity="0"/>
+      <stop offset="0.72" stop-color="#000000" stop-opacity="0"/>
+      <stop offset="1" stop-color="#000000" stop-opacity="0.5"/>
+    </radialGradient>
+    <linearGradient id="label-relationships" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#000000" stop-opacity="0"/>
+      <stop offset="1" stop-color="#000000" stop-opacity="0.55"/>
+    </linearGradient>
+    <filter id="soft-relationships" x="-30%" y="-30%" width="160%" height="160%">
+      <feGaussianBlur stdDeviation="46"/>
+    </filter>
+    <filter id="iglow-relationships" x="-40%" y="-40%" width="180%" height="180%">
+      <feDropShadow dx="0" dy="0" stdDeviation="14" flood-color="#c645ed" flood-opacity="0.45"/>
+    </filter>
+  </defs>
+
+  <rect width="1024" height="1024" fill="url(#bg-relationships)"/>
+
+  <g opacity="0.9">
+    <circle cx="232" cy="220" r="300" fill="url(#blobA-relationships)" filter="url(#soft-relationships)"/>
+    <circle cx="840" cy="800" r="340" fill="url(#blobB-relationships)" filter="url(#soft-relationships)"/>
+  </g>
+
+  <g stroke="#e5d7ea" stroke-width="1.4" opacity="0.06">
+    <line x1="0" y1="256" x2="1024" y2="256"/>
+    <line x1="0" y1="512" x2="1024" y2="512"/>
+    <line x1="0" y1="768" x2="1024" y2="768"/>
+    <line x1="256" y1="0" x2="256" y2="1024"/>
+    <line x1="512" y1="0" x2="512" y2="1024"/>
+    <line x1="768" y1="0" x2="768" y2="1024"/>
+  </g>
+
+  <g opacity="0.5">
+    <path d="M120 470 A 400 400 0 0 1 904 470" fill="none" stroke="#c645ed" stroke-width="3" opacity="0.35"/>
+  </g>
+
+  <g transform="translate(512 432)" filter="url(#iglow-relationships)"
+     color="#e5d7ea" stroke="#e5d7ea" stroke-width="20"
+     stroke-linecap="round" stroke-linejoin="round" fill="none">
+    <line x1="-110" y1="-96" x2="0" y2="0"/>
+    <line x1="120" y1="-110" x2="0" y2="0"/>
+    <line x1="-130" y1="86" x2="0" y2="0"/>
+    <line x1="110" y1="104" x2="0" y2="0"/>
+    <circle cx="0" cy="0" r="30" fill="currentColor" stroke-width="0"/>
+    <circle cx="0" cy="0" r="30"/>
+    <circle cx="-110" cy="-96" r="22"/>
+    <circle cx="120" cy="-110" r="22"/>
+    <circle cx="-130" cy="86" r="22"/>
+    <circle cx="110" cy="104" r="22"/>
+  </g>
+
+  <rect x="0" y="784" width="1024" height="240" fill="url(#label-relationships)"/>
+  <text x="512" y="892" text-anchor="middle"
+        font-family="system-ui, -apple-system, Segoe UI, Roboto, sans-serif"
+        font-size="76" font-weight="600" letter-spacing="0.5"
+        fill="#e5d7ea">Relationships</text>
+  <rect x="460" y="924" width="104" height="6" rx="3" fill="#c645ed"/>
+
+  <rect width="1024" height="1024" fill="url(#vig-relationships)"/>
+</svg>

package/package.json

@@ -0,0 +1,112 @@
+{
+  "name": "@elizaos/plugin-relationships",
+  "version": "2.0.3-beta.2",
+  "description": "Entity and relationship knowledge graph for Eliza agents. Provides the ENTITY umbrella action (person/org/place/project/concept CRUD), EntityStore with identity merge engine, RelationshipStore for typed edges, voice-observer-bridge, and an entity-graph context provider. Backed by drizzle pgSchema('app_relationships').",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elizaos/eliza.git"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "eliza-source": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "eliza-source": {
+        "types": "./src/*.ts",
+        "import": "./src/*.ts",
+        "default": "./src/*.ts"
+      },
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    }
+  },
+  "files": [
+    "assets",
+    "dist"
+  ],
+  "keywords": [
+    "eliza",
+    "plugin",
+    "relationships",
+    "entities",
+    "knowledge-graph",
+    "agent"
+  ],
+  "author": "elizaOS",
+  "license": "MIT",
+  "dependencies": {
+    "@elizaos/agent": "2.0.3-beta.2",
+    "@elizaos/app-core": "2.0.3-beta.2",
+    "@elizaos/core": "2.0.3-beta.2",
+    "@elizaos/shared": "2.0.3-beta.2",
+    "@elizaos/ui": "2.0.3-beta.2",
+    "drizzle-orm": "^0.45.1"
+  },
+  "peerDependencies": {
+    "@elizaos/plugin-sql": "2.0.3-beta.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@types/node": "^25.0.3",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.0",
+    "vitest": "^4.0.0"
+  },
+  "scripts": {
+    "build": "bun run build:js && bun run build:views && bun run build:types",
+    "build:js": "tsup --config ../tsup.plugin-packages.shared.ts",
+    "build:views": "bunx --bun vite build --config vite.config.views.ts",
+    "build:types": "tsc --noCheck -p tsconfig.build.json",
+    "clean": "rm -rf dist .turbo",
+    "test": "bunx vitest run --config ./vitest.config.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "lint": "bunx @biomejs/biome check src/",
+    "lint:check": "bun run lint",
+    "check": "bun run typecheck && bun run test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "elizaos": {
+    "app": {
+      "displayName": "Relationships",
+      "category": "personal"
+    }
+  },
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0",
+    "pluginParameters": {}
+  },
+  "eliza": {
+    "platforms": [
+      "node"
+    ],
+    "runtime": "node",
+    "platformDetails": {
+      "node": "Default export (Node.js)"
+    }
+  },
+  "gitHead": "82fe0f44215954c2417328203f5bd6510985c1fc"
+}