@elizaos/agent 2.0.0-beta.1 → 2.0.11-beta.5

package/services/knowledge-graph/entity-store.js

@@ -0,0 +1,509 @@
+/**
+ * EntityStore — persistence + business-logic surface for the runtime
+ * knowledge-graph node primitive.
+ *
+ * Backed by `app_lifeops.life_entities` + `life_entity_identities` +
+ * `life_entity_attributes`. The store is per-agent (multi-tenant by
+ * agentId); the special `entityId === "self"` row is bootstrapped on first
+ * use.
+ */
+import crypto from "node:crypto";
+import { AUTO_MERGE_CONFIDENCE_THRESHOLD, decideIdentityOutcome, findIdentityMatches, foldIdentity, mergeEntities, SELF_ENTITY_ID, } from "@elizaos/shared";
+import { executeRawSql, parseJsonArray, parseJsonValue, sqlInteger, sqlJson, sqlNumber, sqlQuote, sqlText, toBoolean, toNumber, toText, } from "./sql.js";
+function isoNow() {
+    return new Date().toISOString();
+}
+function entityRowToEntity(args) {
+    const { row, identities, attributes } = args;
+    const state = {};
+    if (row.state_last_observed_at) {
+        state.lastObservedAt = toText(row.state_last_observed_at);
+    }
+    if (row.state_last_inbound_at) {
+        state.lastInboundAt = toText(row.state_last_inbound_at);
+    }
+    if (row.state_last_outbound_at) {
+        state.lastOutboundAt = toText(row.state_last_outbound_at);
+    }
+    if (row.state_last_interaction_platform) {
+        state.lastInteractionPlatform = toText(row.state_last_interaction_platform);
+    }
+    const fullName = row.full_name ? toText(row.full_name) : undefined;
+    return {
+        entityId: toText(row.entity_id),
+        type: toText(row.type),
+        preferredName: toText(row.preferred_name),
+        ...(fullName ? { fullName } : {}),
+        identities,
+        ...(Object.keys(attributes).length > 0 ? { attributes } : {}),
+        state,
+        tags: parseJsonArray(row.tags_json),
+        visibility: toText(row.visibility, "owner_agent_admin"),
+        createdAt: toText(row.created_at),
+        updatedAt: toText(row.updated_at),
+    };
+}
+function identityRowToIdentity(row) {
+    const evidence = parseJsonArray(row.evidence_json);
+    const displayName = row.display_name ? toText(row.display_name) : undefined;
+    return {
+        platform: toText(row.platform),
+        handle: toText(row.handle),
+        ...(displayName ? { displayName } : {}),
+        verified: toBoolean(row.verified),
+        confidence: toNumber(row.confidence, 0),
+        addedAt: toText(row.added_at),
+        addedVia: toText(row.added_via, "platform_observation"),
+        evidence,
+    };
+}
+function attributeRowToAttribute(row) {
+    return {
+        key: toText(row.key),
+        attribute: {
+            value: parseJsonValue(row.value_json, null),
+            confidence: toNumber(row.confidence, 0),
+            evidence: parseJsonArray(row.evidence_json),
+            updatedAt: toText(row.updated_at),
+        },
+    };
+}
+export class EntityStore {
+    runtime;
+    agentId;
+    constructor(runtime, agentId) {
+        this.runtime = runtime;
+        this.agentId = agentId;
+    }
+    /**
+     * Bootstrap the special `self` entity if it does not exist. Idempotent.
+     * Called on first store init for an agent.
+     */
+    async ensureSelf() {
+        const existing = await this.get(SELF_ENTITY_ID);
+        if (existing)
+            return existing;
+        return this.upsertInternal({
+            entityId: SELF_ENTITY_ID,
+            type: "person",
+            preferredName: "self",
+            identities: [],
+            tags: [],
+            visibility: "owner_only",
+            state: {},
+        });
+    }
+    async upsert(input) {
+        return this.upsertInternal(input);
+    }
+    async upsertInternal(input) {
+        const now = isoNow();
+        const entityId = input.entityId ?? `ent_${crypto.randomUUID()}`;
+        const existing = await this.get(entityId);
+        const createdAt = existing?.createdAt ?? now;
+        await executeRawSql(this.runtime, `INSERT INTO app_lifeops.life_entities (
+         entity_id, agent_id, type, preferred_name, full_name, tags_json,
+         visibility, state_last_observed_at, state_last_inbound_at,
+         state_last_outbound_at, state_last_interaction_platform,
+         created_at, updated_at
+       ) VALUES (
+         ${sqlQuote(entityId)},
+         ${sqlQuote(this.agentId)},
+         ${sqlQuote(input.type)},
+         ${sqlQuote(input.preferredName)},
+         ${sqlText(input.fullName ?? null)},
+         ${sqlJson(input.tags)},
+         ${sqlQuote(input.visibility)},
+         ${sqlText(input.state.lastObservedAt ?? null)},
+         ${sqlText(input.state.lastInboundAt ?? null)},
+         ${sqlText(input.state.lastOutboundAt ?? null)},
+         ${sqlText(input.state.lastInteractionPlatform ?? null)},
+         ${sqlQuote(createdAt)},
+         ${sqlQuote(now)}
+       )
+       ON CONFLICT (agent_id, entity_id) DO UPDATE SET
+         type = EXCLUDED.type,
+         preferred_name = EXCLUDED.preferred_name,
+         full_name = EXCLUDED.full_name,
+         tags_json = EXCLUDED.tags_json,
+         visibility = EXCLUDED.visibility,
+         state_last_observed_at = EXCLUDED.state_last_observed_at,
+         state_last_inbound_at = EXCLUDED.state_last_inbound_at,
+         state_last_outbound_at = EXCLUDED.state_last_outbound_at,
+         state_last_interaction_platform = EXCLUDED.state_last_interaction_platform,
+         updated_at = EXCLUDED.updated_at`);
+        // Replace identity rows wholesale — caller passes the canonical list.
+        await executeRawSql(this.runtime, `DELETE FROM app_lifeops.life_entity_identities
+        WHERE agent_id = ${sqlQuote(this.agentId)}
+          AND entity_id = ${sqlQuote(entityId)}`);
+        for (const identity of input.identities) {
+            await this.persistIdentity(entityId, identity);
+        }
+        // Replace attribute rows wholesale.
+        await executeRawSql(this.runtime, `DELETE FROM app_lifeops.life_entity_attributes
+        WHERE agent_id = ${sqlQuote(this.agentId)}
+          AND entity_id = ${sqlQuote(entityId)}`);
+        for (const [key, attr] of Object.entries(input.attributes ?? {})) {
+            await this.persistAttribute(entityId, key, attr);
+        }
+        const fetched = await this.get(entityId);
+        if (!fetched) {
+            throw new Error(`[EntityStore] failed to read back upserted entity ${entityId}`);
+        }
+        return fetched;
+    }
+    async persistIdentity(entityId, identity) {
+        await executeRawSql(this.runtime, `INSERT INTO app_lifeops.life_entity_identities (
+         id, agent_id, entity_id, platform, handle, display_name,
+         verified, confidence, added_at, added_via, evidence_json
+       ) VALUES (
+         ${sqlQuote(`eid_${crypto.randomUUID()}`)},
+         ${sqlQuote(this.agentId)},
+         ${sqlQuote(entityId)},
+         ${sqlQuote(identity.platform)},
+         ${sqlQuote(identity.handle)},
+         ${sqlText(identity.displayName ?? null)},
+         ${identity.verified ? "TRUE" : "FALSE"},
+         ${sqlNumber(identity.confidence)},
+         ${sqlQuote(identity.addedAt)},
+         ${sqlQuote(identity.addedVia)},
+         ${sqlJson(identity.evidence)}
+       )
+       ON CONFLICT (agent_id, entity_id, platform, handle) DO UPDATE SET
+         display_name = EXCLUDED.display_name,
+         verified = EXCLUDED.verified,
+         confidence = EXCLUDED.confidence,
+         added_via = EXCLUDED.added_via,
+         evidence_json = EXCLUDED.evidence_json`);
+    }
+    async persistAttribute(entityId, key, attribute) {
+        await executeRawSql(this.runtime, `INSERT INTO app_lifeops.life_entity_attributes (
+         id, agent_id, entity_id, key, value_json, confidence,
+         evidence_json, updated_at
+       ) VALUES (
+         ${sqlQuote(`ea_${crypto.randomUUID()}`)},
+         ${sqlQuote(this.agentId)},
+         ${sqlQuote(entityId)},
+         ${sqlQuote(key)},
+         ${sqlJson(attribute.value)},
+         ${sqlNumber(attribute.confidence)},
+         ${sqlJson(attribute.evidence)},
+         ${sqlQuote(attribute.updatedAt)}
+       )
+       ON CONFLICT (agent_id, entity_id, key) DO UPDATE SET
+         value_json = EXCLUDED.value_json,
+         confidence = EXCLUDED.confidence,
+         evidence_json = EXCLUDED.evidence_json,
+         updated_at = EXCLUDED.updated_at`);
+    }
+    async get(entityId) {
+        const rows = await executeRawSql(this.runtime, `SELECT * FROM app_lifeops.life_entities
+        WHERE agent_id = ${sqlQuote(this.agentId)}
+          AND entity_id = ${sqlQuote(entityId)}
+        LIMIT 1`);
+        const row = rows[0];
+        if (!row)
+            return null;
+        const identities = await this.loadIdentities([entityId]);
+        const attributes = await this.loadAttributes([entityId]);
+        return entityRowToEntity({
+            row,
+            identities: identities.get(entityId) ?? [],
+            attributes: attributes.get(entityId) ?? {},
+        });
+    }
+    async list(filter) {
+        const clauses = [`e.agent_id = ${sqlQuote(this.agentId)}`];
+        if (filter?.type) {
+            clauses.push(`e.type = ${sqlQuote(filter.type)}`);
+        }
+        if (filter?.tag) {
+            // tags_json is a JSON array — use LIKE on the serialized form for
+            // portability across PG / PGLite. The string form `"<tag>"` is
+            // safe because tags are validated as plain strings on write.
+            clauses.push(`e.tags_json LIKE ${sqlQuote(`%"${filter.tag}"%`)}`);
+        }
+        if (filter?.nameContains) {
+            const needle = sqlQuote(`%${filter.nameContains.toLowerCase()}%`);
+            clauses.push(`(LOWER(e.preferred_name) LIKE ${needle} OR LOWER(COALESCE(e.full_name, '')) LIKE ${needle})`);
+        }
+        if (filter?.hasPlatform) {
+            const platform = sqlQuote(filter.hasPlatform.toLowerCase());
+            clauses.push(`EXISTS (SELECT 1 FROM app_lifeops.life_entity_identities i
+                  WHERE i.agent_id = e.agent_id
+                    AND i.entity_id = e.entity_id
+                    AND LOWER(i.platform) = ${platform})`);
+        }
+        const limitClause = typeof filter?.limit === "number" && Number.isFinite(filter.limit)
+            ? `LIMIT ${sqlInteger(filter.limit)}`
+            : "";
+        const rows = await executeRawSql(this.runtime, `SELECT e.* FROM app_lifeops.life_entities e
+        WHERE ${clauses.join(" AND ")}
+        ORDER BY e.preferred_name ASC
+        ${limitClause}`);
+        if (rows.length === 0)
+            return [];
+        const ids = rows.map((row) => toText(row.entity_id));
+        const identities = await this.loadIdentities(ids);
+        const attributes = await this.loadAttributes(ids);
+        return rows.map((row) => {
+            const id = toText(row.entity_id);
+            return entityRowToEntity({
+                row,
+                identities: identities.get(id) ?? [],
+                attributes: attributes.get(id) ?? {},
+            });
+        });
+    }
+    async loadIdentities(entityIds) {
+        if (entityIds.length === 0)
+            return new Map();
+        const idList = entityIds.map((id) => sqlQuote(id)).join(", ");
+        const rows = await executeRawSql(this.runtime, `SELECT * FROM app_lifeops.life_entity_identities
+        WHERE agent_id = ${sqlQuote(this.agentId)}
+          AND entity_id IN (${idList})
+        ORDER BY added_at ASC`);
+        const grouped = new Map();
+        for (const row of rows) {
+            const id = toText(row.entity_id);
+            const list = grouped.get(id) ?? [];
+            list.push(identityRowToIdentity(row));
+            grouped.set(id, list);
+        }
+        return grouped;
+    }
+    async loadAttributes(entityIds) {
+        if (entityIds.length === 0)
+            return new Map();
+        const idList = entityIds.map((id) => sqlQuote(id)).join(", ");
+        const rows = await executeRawSql(this.runtime, `SELECT * FROM app_lifeops.life_entity_attributes
+        WHERE agent_id = ${sqlQuote(this.agentId)}
+          AND entity_id IN (${idList})`);
+        const grouped = new Map();
+        for (const row of rows) {
+            const id = toText(row.entity_id);
+            const bag = grouped.get(id) ?? {};
+            const { key, attribute } = attributeRowToAttribute(row);
+            bag[key] = attribute;
+            grouped.set(id, bag);
+        }
+        return grouped;
+    }
+    /**
+     * Observe a `(platform, handle)` claim. Decision tree:
+     *   - no candidate: create a new entity with this identity.
+     *   - exactly one candidate AND confidence >= AUTO_MERGE: fold in.
+     *   - exactly one candidate, low confidence: create a conflict outcome.
+     *   - multiple candidates: create a conflict outcome.
+     *
+     * Returns the resulting entity (the existing one in merge cases, the
+     * newly-created one in create cases). For conflicts, the FIRST candidate
+     * is returned and `mergedFrom` lists the conflicting candidate ids; the
+     * caller surfaces the conflict via the ScheduledTask approval queue.
+     */
+    async observeIdentity(obs) {
+        const all = await this.list();
+        const candidates = findIdentityMatches(all, {
+            platform: obs.platform,
+            handle: obs.handle,
+            confidence: obs.confidence,
+        });
+        const outcome = decideIdentityOutcome({
+            candidates,
+            newConfidence: obs.confidence,
+        });
+        const now = isoNow();
+        const newIdentity = {
+            platform: obs.platform,
+            handle: obs.handle,
+            ...(obs.displayName ? { displayName: obs.displayName } : {}),
+            verified: false,
+            confidence: obs.confidence,
+            addedAt: now,
+            addedVia: "platform_observation",
+            evidence: [...obs.evidence],
+        };
+        if (outcome.kind === "create") {
+            const entity = await this.upsertInternal({
+                type: obs.suggestedType ?? "person",
+                preferredName: obs.displayName ?? obs.handle,
+                identities: [newIdentity],
+                tags: [],
+                visibility: "owner_agent_admin",
+                state: { lastObservedAt: now },
+            });
+            return { entity };
+        }
+        if (outcome.kind === "merge") {
+            const target = candidates.find((c) => c.entityId === outcome.targetEntityId);
+            if (!target) {
+                throw new Error("[EntityStore] merge target disappeared mid-observe");
+            }
+            const folded = foldIdentity(target.identities, newIdentity);
+            const updated = await this.upsertInternal({
+                ...target,
+                identities: folded,
+                state: { ...target.state, lastObservedAt: now },
+            });
+            return { entity: updated, mergedFrom: [target.entityId] };
+        }
+        // conflict: store on the highest-confidence existing match (first
+        // one — list is name-ordered, but for this purpose the runtime treats
+        // any candidate as the "best guess" and the approval task surfaces
+        // the rest). We do NOT auto-merge.
+        const first = candidates[0];
+        if (!first) {
+            throw new Error("[EntityStore] conflict outcome with no candidates");
+        }
+        return {
+            entity: first,
+            mergedFrom: outcome.candidateEntityIds,
+            conflict: true,
+        };
+    }
+    /**
+     * Resolve an entity by name, identity, or type. Returns ranked candidates
+     * (highest confidence first). `safeToSend` is `true` when the entity has
+     * at least one verified identity on a sendable platform.
+     */
+    async resolve(query) {
+        const filters = {};
+        if (query.type)
+            filters.type = query.type;
+        if (query.name)
+            filters.nameContains = query.name;
+        if (query.identity)
+            filters.hasPlatform = query.identity.platform;
+        let entities = await this.list(filters);
+        if (query.identity) {
+            const platformKey = query.identity.platform.toLowerCase();
+            const handleKey = query.identity.handle.toLowerCase();
+            entities = entities.filter((entity) => entity.identities.some((identity) => identity.platform.toLowerCase() === platformKey &&
+                identity.handle.toLowerCase() === handleKey));
+        }
+        return entities
+            .map((entity) => {
+            const evidence = [];
+            let confidence = 0;
+            let safeToSend = false;
+            if (query.identity) {
+                const match = entity.identities.find((identity) => identity.platform.toLowerCase() ===
+                    query.identity?.platform.toLowerCase() &&
+                    identity.handle.toLowerCase() ===
+                        query.identity.handle.toLowerCase());
+                if (match) {
+                    confidence = match.confidence;
+                    evidence.push(...match.evidence);
+                    safeToSend = match.verified;
+                }
+            }
+            if (query.name && entity.preferredName) {
+                const exact = entity.preferredName.toLowerCase() === query.name.toLowerCase();
+                confidence = Math.max(confidence, exact ? 0.9 : 0.55);
+            }
+            if (entity.identities.some((id) => id.verified)) {
+                safeToSend = true;
+            }
+            return { entity, confidence, evidence, safeToSend };
+        })
+            .sort((a, b) => b.confidence - a.confidence);
+    }
+    /**
+     * Record an interaction against an entity. Updates `state.lastInboundAt`
+     * or `lastOutboundAt`, plus `lastObservedAt` and
+     * `lastInteractionPlatform`. Caller is responsible for also calling
+     * `RelationshipStore.observe` to strengthen the per-edge state where
+     * applicable.
+     */
+    async recordInteraction(entityId, interaction) {
+        const directionColumn = interaction.direction === "inbound"
+            ? "state_last_inbound_at"
+            : "state_last_outbound_at";
+        await executeRawSql(this.runtime, `UPDATE app_lifeops.life_entities
+          SET ${directionColumn} = ${sqlQuote(interaction.occurredAt)},
+              state_last_observed_at = ${sqlQuote(interaction.occurredAt)},
+              state_last_interaction_platform = ${sqlQuote(interaction.platform)},
+              updated_at = ${sqlQuote(isoNow())}
+        WHERE agent_id = ${sqlQuote(this.agentId)}
+          AND entity_id = ${sqlQuote(entityId)}`);
+        // Summary is an audit trail concern. The repo relationship-interactions
+        // table provides per-edge history; for entity-only recordings the
+        // observation-id list captured on the next identity / relationship
+        // observe call is the canonical home. We keep this method narrow
+        // rather than duplicating audit logging.
+    }
+    /**
+     * Explicit merge: fold N source entities into a target. Identities,
+     * attributes, and tags survive. Source rows are deleted. Returns the
+     * merged target.
+     */
+    async merge(targetId, sourceIds) {
+        if (sourceIds.length === 0) {
+            const existing = await this.get(targetId);
+            if (!existing) {
+                throw new Error(`[EntityStore.merge] target ${targetId} not found`);
+            }
+            return existing;
+        }
+        const target = await this.get(targetId);
+        if (!target) {
+            throw new Error(`[EntityStore.merge] target ${targetId} not found`);
+        }
+        const sources = [];
+        for (const id of sourceIds) {
+            if (id === targetId)
+                continue;
+            const source = await this.get(id);
+            if (source)
+                sources.push(source);
+        }
+        const now = isoNow();
+        const merged = mergeEntities({ target, sources, now });
+        const persisted = await this.upsertInternal({
+            ...merged,
+            identities: merged.identities,
+        });
+        // Rewrite any relationships that reference sources to point at target,
+        // then delete the source rows. The relationships rewrite is part of
+        // the merge contract; do it before source deletion so audit events
+        // can still resolve.
+        for (const source of sources) {
+            const rewriteSql = (column) => `UPDATE app_lifeops.life_relationships_v2
+            SET ${column} = ${sqlQuote(targetId)},
+                updated_at = ${sqlQuote(now)}
+          WHERE agent_id = ${sqlQuote(this.agentId)}
+            AND ${column} = ${sqlQuote(source.entityId)}`;
+            await executeRawSql(this.runtime, rewriteSql("from_entity_id"));
+            await executeRawSql(this.runtime, rewriteSql("to_entity_id"));
+            await executeRawSql(this.runtime, `DELETE FROM app_lifeops.life_entity_identities
+          WHERE agent_id = ${sqlQuote(this.agentId)}
+            AND entity_id = ${sqlQuote(source.entityId)}`);
+            await executeRawSql(this.runtime, `DELETE FROM app_lifeops.life_entity_attributes
+          WHERE agent_id = ${sqlQuote(this.agentId)}
+            AND entity_id = ${sqlQuote(source.entityId)}`);
+            await executeRawSql(this.runtime, `DELETE FROM app_lifeops.life_entities
+          WHERE agent_id = ${sqlQuote(this.agentId)}
+            AND entity_id = ${sqlQuote(source.entityId)}`);
+        }
+        return persisted;
+    }
+    /**
+     * Test-only helper for removing an entity. Production callers should use
+     * `merge` to consolidate or simply leave entities in place.
+     */
+    async deleteForTest(entityId) {
+        if (entityId === SELF_ENTITY_ID) {
+            throw new Error("[EntityStore] cannot delete self entity");
+        }
+        await executeRawSql(this.runtime, `DELETE FROM app_lifeops.life_entity_identities
+        WHERE agent_id = ${sqlQuote(this.agentId)}
+          AND entity_id = ${sqlQuote(entityId)}`);
+        await executeRawSql(this.runtime, `DELETE FROM app_lifeops.life_entity_attributes
+        WHERE agent_id = ${sqlQuote(this.agentId)}
+          AND entity_id = ${sqlQuote(entityId)}`);
+        await executeRawSql(this.runtime, `DELETE FROM app_lifeops.life_entities
+        WHERE agent_id = ${sqlQuote(this.agentId)}
+          AND entity_id = ${sqlQuote(entityId)}`);
+    }
+}
+export { AUTO_MERGE_CONFIDENCE_THRESHOLD };

package/services/knowledge-graph/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Runtime knowledge-graph: entity nodes + typed relationship edges.
+ *
+ * The DB-backed stores and their schema are owned by `@elizaos/agent` (the
+ * runtime) and surfaced through the registered {@link KnowledgeGraphService}.
+ * Pure KG types and the identity-merge engine live in `@elizaos/shared`.
+ */
+export { EntityStore } from "./entity-store.ts";
+export { RelationshipStore } from "./relationship-store.ts";
+export { knowledgeGraphSchema } from "./schema.ts";
+export { KNOWLEDGE_GRAPH_SERVICE, KnowledgeGraphService, resolveKnowledgeGraphService, } from "./service.ts";
+//# sourceMappingURL=index.d.ts.map

package/services/knowledge-graph/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/knowledge-graph/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,4BAA4B,GAC7B,MAAM,cAAc,CAAC"}

package/services/knowledge-graph/index.js

@@ -0,0 +1,11 @@
+/**
+ * Runtime knowledge-graph: entity nodes + typed relationship edges.
+ *
+ * The DB-backed stores and their schema are owned by `@elizaos/agent` (the
+ * runtime) and surfaced through the registered {@link KnowledgeGraphService}.
+ * Pure KG types and the identity-merge engine live in `@elizaos/shared`.
+ */
+export { EntityStore } from "./entity-store.js";
+export { RelationshipStore } from "./relationship-store.js";
+export { knowledgeGraphSchema } from "./schema.js";
+export { KNOWLEDGE_GRAPH_SERVICE, KnowledgeGraphService, resolveKnowledgeGraphService, } from "./service.js";

package/services/knowledge-graph/relationship-store.d.ts

@@ -0,0 +1,58 @@
+/**
+ * RelationshipStore — typed-edge persistence + observation API.
+ *
+ * Backed by `app_lifeops.life_relationships_v2`; soft-delete via the
+ * `status` column with audit rows in `life_relationship_audit_events`.
+ *
+ * `observe` is the canonical entry point for "ingest extraction-time
+ * evidence into the graph" — it strengthens an existing matching edge
+ * (adds evidence, bumps interactionCount, updates state.lastInteractionAt)
+ * instead of duplicating; only creates a new edge if no matching
+ * `(from, to, type)` exists.
+ */
+import type { IAgentRuntime } from "@elizaos/core";
+import type { Relationship, RelationshipFilter, RelationshipSource, RelationshipStatus } from "@elizaos/shared";
+export declare class RelationshipStore {
+    private readonly runtime;
+    private readonly agentId;
+    constructor(runtime: IAgentRuntime, agentId: string);
+    upsert(input: Omit<Relationship, "relationshipId" | "createdAt" | "updatedAt" | "status"> & {
+        relationshipId?: string;
+        status?: RelationshipStatus;
+    }): Promise<Relationship>;
+    get(relationshipId: string): Promise<Relationship | null>;
+    list(filter?: RelationshipFilter): Promise<Relationship[]>;
+    /**
+     * Strengthen-or-create. If an active edge with the same
+     * `(from, to, type)` exists, fold the new evidence in, bump
+     * `interactionCount`, advance `state.lastInteractionAt`, and (per spec)
+     * pick the higher confidence between old and new. If the matching edge
+     * is RETIRED, log the new evidence on the retired record but DO NOT
+     * flip its state — return the retired edge unchanged. If no edge
+     * exists, create a fresh one.
+     */
+    observe(obs: {
+        fromEntityId: string;
+        toEntityId: string;
+        type: string;
+        metadataPatch?: Record<string, unknown>;
+        evidence: string[];
+        confidence: number;
+        occurredAt?: string;
+        source?: RelationshipSource;
+    }): Promise<Relationship>;
+    /**
+     * Soft-delete with audit. The edge stays queryable via
+     * `list({ includeRetired: true })` but is filtered out by default and
+     * never strengthened by new evidence.
+     */
+    retire(relationshipId: string, reason: string): Promise<void>;
+    listAuditEvents(relationshipId: string): Promise<Array<{
+        id: string;
+        kind: string;
+        details: Record<string, unknown>;
+        createdAt: string;
+    }>>;
+    private appendAudit;
+}
+//# sourceMappingURL=relationship-store.d.ts.map

package/services/knowledge-graph/relationship-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-store.d.ts","sourceRoot":"","sources":["../../../src/services/knowledge-graph/relationship-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAElB,kBAAkB,EAElB,kBAAkB,EACnB,MAAM,iBAAiB,CAAC;AAwEzB,qBAAa,iBAAiB;IAE1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,MAAM;IAG5B,MAAM,CACV,KAAK,EAAE,IAAI,CACT,YAAY,EACZ,gBAAgB,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CACxD,GAAG;QACF,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,MAAM,CAAC,EAAE,kBAAkB,CAAC;KAC7B,GACA,OAAO,CAAC,YAAY,CAAC;IA+DlB,GAAG,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAYzD,IAAI,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAiEhE;;;;;;;;OAQG;IACG,OAAO,CAAC,GAAG,EAAE;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACxC,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,kBAAkB,CAAC;KAC7B,GAAG,OAAO,CAAC,YAAY,CAAC;IAoEzB;;;;OAIG;IACG,MAAM,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB7D,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CACpD,KAAK,CAAC;QACJ,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjC,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC,CACH;YAgBa,WAAW;CAmB1B"}