@elizaos/plugin-rolodex 2.0.0-alpha.3

package/dist/providers/contacts.d.ts

@@ -0,0 +1,2 @@
+import { type Provider } from "@elizaos/core";
+export declare const contactsProvider: Provider;

package/dist/providers/facts.d.ts

@@ -0,0 +1,10 @@
+import { type Provider } from "@elizaos/core";
+/**
+ * Function to get key facts that the agent knows.
+ * @param {IAgentRuntime} runtime - The runtime environment for the agent.
+ * @param {Memory} message - The message object containing relevant information.
+ * @param {State} [_state] - Optional state information.
+ * @returns {Object} An object containing values, data, and text related to the key facts.
+ */
+declare const factsProvider: Provider;
+export { factsProvider };

package/dist/providers/followUps.d.ts

@@ -0,0 +1,2 @@
+import { type Provider } from "@elizaos/core";
+export declare const followUpsProvider: Provider;

package/dist/providers/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./contacts";
+export * from "./facts";
+export * from "./followUps";
+export * from "./relationships";

package/dist/providers/relationships.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Relationships Provider — enriched with entity links and decay.
+ *
+ * Injects relationship context into the agent's state, including:
+ *  - Relationships sorted by decayed strength
+ *  - Cross-platform identity links
+ *  - Relationship evolution history
+ */
+import type { Provider } from "@elizaos/core";
+declare const relationshipsProvider: Provider;
+export { relationshipsProvider };

package/dist/services/EntityResolutionService.d.ts

@@ -0,0 +1,76 @@
+/**
+ * EntityResolutionService — cross-platform identity resolution.
+ *
+ * The "ultimate goal" of the rolodex: figuring out that Dave on Discord
+ * is the same person as @dave_codes on Twitter.
+ *
+ * Architecture follows a small-world graph approach:
+ *   1. Trigger-based, not scan-based — we resolve when new evidence arrives
+ *   2. Local neighborhood first — only compare against entities within
+ *      2 hops in the social graph (small-world networks cover the
+ *      relevant cluster in 2-3 hops)
+ *   3. Multi-signal scoring — name similarity, handle correlation,
+ *      shared connections, project affinity, self-identification
+ *   4. Merge tasks — when confidence is above threshold, create a task
+ *      for verification rather than auto-merging
+ *
+ * This service is intentionally conservative. It's better to miss a
+ * connection than to incorrectly merge two different people.
+ */
+import { type Entity, type IAgentRuntime, Service, type UUID } from "@elizaos/core";
+import type { EntityLink } from "../types/index";
+export declare class EntityResolutionService extends Service {
+    static serviceType: "entity_resolution";
+    capabilityDescription: string;
+    /** In-memory index: normalized name/handle -> entity IDs */
+    private nameIndex;
+    initialize(runtime: IAgentRuntime): Promise<void>;
+    stop(): Promise<void>;
+    static start(runtime: IAgentRuntime): Promise<Service>;
+    /**
+     * Trigger resolution for an entity. Called when:
+     *  - A new platform identity is added
+     *  - A new entity is created
+     *  - Someone mentions a name that matches existing entities
+     *
+     * Uses small-world graph traversal to limit the search space.
+     */
+    resolveEntity(entityId: UUID): Promise<EntityLink[]>;
+    /**
+     * Look up an entity by name or handle, using the in-memory index
+     * for O(1) lookup instead of scanning all entities.
+     */
+    findByNameOrHandle(entity: Entity): Set<UUID>;
+    /**
+     * Register a new entity or new names/handles in the index.
+     * Called when entities are created or updated.
+     */
+    indexEntity(entity: Entity): void;
+    /**
+     * Get all existing entity links for an entity.
+     */
+    getLinks(entityId: UUID): Promise<EntityLink[]>;
+    /**
+     * Confirm a proposed link (admin or agent verification).
+     */
+    confirmLink(linkId: UUID, confirmedBy: UUID): Promise<boolean>;
+    rejectLink(linkId: UUID, rejectedBy: UUID): Promise<boolean>;
+    private computeSignals;
+    /**
+     * Score a set of signals into a single confidence value.
+     *
+     * Uses weighted combination with diminishing returns for multiple
+     * signals of the same type.
+     */
+    private scoreCandidate;
+    private getExistingLink;
+    private createLink;
+    private updateLink;
+    /**
+     * Create a merge task that stays open until verified.
+     */
+    private createMergeTask;
+    private findLinkComponent;
+    private getPlatformIdentities;
+    private rebuildNameIndex;
+}

package/dist/services/FollowUpService.d.ts

@@ -0,0 +1,37 @@
+import { type IAgentRuntime, Service, type Task, type UUID } from "@elizaos/core";
+import type { ContactInfo, FollowUpSuggestion } from "../types/index";
+export interface FollowUpTask {
+    entityId: UUID;
+    reason: string;
+    message?: string;
+    priority: "high" | "medium" | "low";
+    metadata?: Record<string, any>;
+}
+export declare class FollowUpService extends Service {
+    static serviceType: "follow_up";
+    capabilityDescription: string;
+    private rolodexService;
+    constructor(runtime?: IAgentRuntime);
+    initialize(runtime: IAgentRuntime): Promise<void>;
+    stop(): Promise<void>;
+    static start(runtime: IAgentRuntime): Promise<Service>;
+    scheduleFollowUp(entityId: UUID, scheduledAt: Date, reason: string, priority?: "high" | "medium" | "low", message?: string): Promise<Task>;
+    getUpcomingFollowUps(days?: number, includeOverdue?: boolean): Promise<Array<{
+        task: Task;
+        contact: ContactInfo;
+    }>>;
+    completeFollowUp(taskId: UUID, notes?: string): Promise<void>;
+    snoozeFollowUp(taskId: UUID, newDate: Date): Promise<void>;
+    getFollowUpSuggestions(): Promise<FollowUpSuggestion[]>;
+    private registerFollowUpWorker;
+    private registerRecurringCheckInWorker;
+    private generateFollowUpReason;
+    private generateFollowUpMessage;
+    scheduleMultipleFollowUps(followUps: Array<{
+        entityId: UUID;
+        scheduledAt: Date;
+        reason: string;
+        priority?: "high" | "medium" | "low";
+        message?: string;
+    }>): Promise<Task[]>;
+}

package/dist/services/RolodexService.d.ts

@@ -0,0 +1,73 @@
+/**
+ * RolodexService — the core CRM service for the agent.
+ *
+ * Manages contacts, information claims (with provenance), relationship
+ * analytics, and categories. This is the single source of truth for
+ * "what do I know about this person?"
+ */
+import { type Entity, type IAgentRuntime, type Metadata, Service, type UUID } from "@elizaos/core";
+import type { ClaimScope, ClaimSourceContext, ContactCategory, ContactInfo, ContactPreferences, Corroboration, InformationTier, RelationshipAnalytics } from "../types/index";
+export declare class RolodexService extends Service {
+    static serviceType: "rolodex";
+    capabilityDescription: string;
+    private contactInfoCache;
+    private analyticsCache;
+    private categoriesCache;
+    initialize(runtime: IAgentRuntime): Promise<void>;
+    stop(): Promise<void>;
+    static start(runtime: IAgentRuntime): Promise<Service>;
+    addContact(entityId: UUID, categories?: string[], preferences?: ContactPreferences, customFields?: Record<string, string>): Promise<ContactInfo>;
+    updateContact(entityId: UUID, updates: Partial<ContactInfo>): Promise<ContactInfo | null>;
+    getContact(entityId: UUID): Promise<ContactInfo | null>;
+    removeContact(entityId: UUID): Promise<boolean>;
+    searchContacts(criteria: {
+        categories?: string[];
+        tags?: string[];
+        searchTerm?: string;
+        privacyLevel?: string;
+    }): Promise<ContactInfo[]>;
+    /**
+     * Store a new information claim about an entity.
+     */
+    addClaim(params: {
+        entityId: UUID;
+        field: string;
+        value: string;
+        tier: InformationTier;
+        confidence: number;
+        sourceEntityId: UUID;
+        sourceContext: ClaimSourceContext;
+        scope?: ClaimScope;
+    }): Promise<void>;
+    /**
+     * Get all claims about an entity, with time-decayed confidence.
+     */
+    getClaims(entityId: UUID, field?: string): Promise<Array<{
+        claim: Metadata;
+        decayedConfidence: number;
+    }>>;
+    /**
+     * Add a corroboration to an existing claim.
+     */
+    corroborateClaim(entityId: UUID, componentId: UUID, corroboration: Corroboration): Promise<void>;
+    analyzeRelationship(sourceEntityId: UUID, targetEntityId: UUID): Promise<RelationshipAnalytics | null>;
+    getRelationshipInsights(entityId: UUID): Promise<{
+        strongestRelationships: Array<{
+            entity: Entity;
+            analytics: RelationshipAnalytics;
+        }>;
+        needsAttention: Array<{
+            entity: Entity;
+            daysSinceContact: number;
+        }>;
+        recentInteractions: Array<{
+            entity: Entity;
+            lastInteraction: string;
+        }>;
+    }>;
+    getCategories(): Promise<ContactCategory[]>;
+    addCategory(category: ContactCategory): Promise<void>;
+    setContactPrivacy(entityId: UUID, privacyLevel: "public" | "private" | "restricted"): Promise<boolean>;
+    canAccessContact(requestingEntityId: UUID, targetEntityId: UUID): Promise<boolean>;
+    private loadContactInfoFromComponents;
+}

package/dist/services/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./EntityResolutionService";
+export * from "./FollowUpService";
+export * from "./RolodexService";

package/dist/tests/ConversationSimulator.d.ts

@@ -0,0 +1,71 @@
+import { type ChannelType, type Entity, type IAgentRuntime, type Memory, type Room } from "@elizaos/core";
+export interface UserProfile {
+    name: string;
+    roles?: string[];
+    metadata?: Record<string, any>;
+}
+export interface ConversationStep {
+    from: string;
+    content: string;
+    delay?: number;
+}
+export interface ConversationScript {
+    name: string;
+    description: string;
+    room: {
+        name: string;
+        type: ChannelType;
+    };
+    participants: UserProfile[];
+    steps: ConversationStep[];
+}
+export interface SimulatedUser {
+    entity: Entity;
+    profile: UserProfile;
+}
+export declare class ConversationSimulator {
+    private runtime;
+    private users;
+    private rooms;
+    private world;
+    constructor(runtime: IAgentRuntime);
+    /**
+     * Creates a test user entity
+     */
+    createUser(profile: UserProfile): Promise<Entity>;
+    /**
+     * Creates or gets a test room
+     */
+    getOrCreateRoom(roomConfig: {
+        name: string;
+        type: ChannelType;
+    }): Promise<Room>;
+    /**
+     * Simulates sending a message from a user
+     */
+    sendMessage(from: Entity, content: string, room: Room): Promise<Memory>;
+    /**
+     * Executes a multi-turn conversation script
+     */
+    runConversation(script: ConversationScript): Promise<void>;
+    /**
+     * Processes a message through the runtime's evaluation pipeline
+     */
+    private processMessage;
+    /**
+     * Waits for all evaluators to complete processing
+     */
+    waitForEvaluators(timeout?: number): Promise<void>;
+    /**
+     * Gets a user by name
+     */
+    getUser(name: string): SimulatedUser | undefined;
+    /**
+     * Gets all created users
+     */
+    getAllUsers(): SimulatedUser[];
+    /**
+     * Cleans up test data
+     */
+    cleanup(): Promise<void>;
+}

package/dist/tests/ScenarioVerifier.d.ts

@@ -0,0 +1,59 @@
+import { type IAgentRuntime, type UUID } from "@elizaos/core";
+export interface EntityExpectations {
+    names?: string[];
+    hasMetadata?: string[];
+    platformIdentities?: Array<{
+        platform: string;
+        handle: string;
+        verified?: boolean;
+    }>;
+    trustMetrics?: {
+        minHelpfulness?: number;
+        maxSuspicionLevel?: number;
+    };
+}
+export interface RelationshipExpectations {
+    exists: boolean;
+    type?: string;
+    sentiment?: "positive" | "negative" | "neutral";
+    minStrength?: number;
+    hasIndicators?: boolean;
+}
+export interface DisputeExpectations {
+    exists: boolean;
+    disputedField?: string;
+    disputer?: string;
+    count?: number;
+}
+export interface PrivacyExpectations {
+    hasPrivateData: boolean;
+    sharingRestrictions?: string[];
+}
+export declare class ScenarioVerifier {
+    private runtime;
+    constructor(runtime: IAgentRuntime);
+    /**
+     * Verifies entity creation and metadata
+     */
+    verifyEntity(entityId: UUID, expected: EntityExpectations): Promise<void>;
+    /**
+     * Verifies relationship creation and properties
+     */
+    verifyRelationship(entityA: UUID, entityB: UUID, expected: RelationshipExpectations): Promise<void>;
+    /**
+     * Verifies dispute logging
+     */
+    verifyDispute(entityId: UUID, expected: DisputeExpectations): Promise<void>;
+    /**
+     * Verifies privacy boundaries
+     */
+    verifyPrivacy(entityId: UUID, expected: PrivacyExpectations): Promise<void>;
+    /**
+     * Helper method to verify component existence
+     */
+    verifyComponent(entityId: UUID, componentType: string, shouldExist: boolean): Promise<void>;
+    /**
+     * Verifies that a mentioned person was created as an entity
+     */
+    verifyMentionedPerson(personName: string, mentionedBy: UUID): Promise<void>;
+}

package/dist/tests/e2e.test.d.ts

@@ -0,0 +1,2 @@
+import { type TestSuite } from "@elizaos/core";
+export declare const rolodexE2ETests: TestSuite;

package/dist/tests/entity-graph.test.d.ts

@@ -0,0 +1,2 @@
+import { type TestSuite } from "@elizaos/core";
+export declare const entityGraphTestSuite: TestSuite;

package/dist/tests/index.d.ts

@@ -0,0 +1,6 @@
+import type { TestSuite } from "@elizaos/core";
+import { entityGraphTestSuite } from "./entity-graph.test";
+import { rolodexScenarioTests } from "./scenarios.test";
+export declare const rolodexTests: TestSuite;
+export declare const e2eTestSuite: TestSuite;
+export { rolodexScenarioTests, entityGraphTestSuite };

package/dist/tests/scenarios.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Realistic Benchmark Scenarios for the Rolodex Plugin
+ *
+ * Each scenario simulates a real-world situation the agent needs to handle.
+ * These are designed to test the full pipeline: extraction -> storage ->
+ * resolution -> querying.
+ */
+import { type TestSuite } from "@elizaos/core";
+export declare const rolodexScenarioTests: TestSuite;

package/dist/types/index.d.ts

@@ -0,0 +1,281 @@
+/**
+ * plugin-rolodex shared types
+ *
+ * All types used across the rolodex plugin are defined here so that
+ * services, evaluators, providers, actions, and tests share a single
+ * source of truth.
+ */
+import type { UUID } from "@elizaos/core";
+/**
+ * The four tiers of information confidence.
+ *
+ *  ground_truth  – came from a platform API or verified source
+ *  self_reported – the person said it about themselves, in a specific context
+ *  hearsay       – someone else said it about them
+ *  inferred      – the agent figured it out from evidence
+ */
+export type InformationTier = "ground_truth" | "self_reported" | "hearsay" | "inferred";
+/**
+ * Where a claim is considered valid.
+ *
+ *  global   – universally true  (e.g. a verified wallet address)
+ *  platform – true on the platform where it was stated
+ *  room     – true only in the room it was mentioned
+ */
+export type ClaimScope = "global" | "platform" | "room";
+/**
+ * The context in which a claim was made.
+ */
+export interface ClaimSourceContext {
+    platform: string;
+    roomId: UUID;
+    messageId?: UUID;
+    timestamp: number;
+}
+/**
+ * A corroboration is someone else confirming the same claim.
+ */
+export interface Corroboration {
+    entityId: UUID;
+    timestamp: number;
+    context: string;
+}
+/**
+ * A dispute is someone contradicting a claim.
+ */
+export interface ClaimDispute {
+    entityId: UUID;
+    alternativeValue: string;
+    timestamp: number;
+    context: string;
+    resolved: boolean;
+    resolution?: "accepted" | "rejected";
+}
+/**
+ * An InformationClaim is the atomic unit of knowledge the agent stores
+ * about entities. Every piece of information has provenance, confidence,
+ * scope, and a decay half-life.
+ */
+export interface InformationClaim {
+    id: UUID;
+    /** The entity this claim is *about* */
+    entityId: UUID;
+    /** What kind of information (e.g. 'twitter_handle', 'birthday', 'role') */
+    field: string;
+    /** The actual value */
+    value: string;
+    /** Knowledge tier */
+    tier: InformationTier;
+    /** Current confidence 0-1, decays over time */
+    confidence: number;
+    /** Base confidence before decay (set when created/corroborated) */
+    baseConfidence: number;
+    /** Who provided this information */
+    sourceEntityId: UUID;
+    /** Where/when it was provided */
+    sourceContext: ClaimSourceContext;
+    /** Others who confirmed it – each corroboration doubles the half-life */
+    corroborations: Corroboration[];
+    /** Others who disputed it */
+    disputes: ClaimDispute[];
+    /** Where this claim is considered valid */
+    scope: ClaimScope;
+    /** Half-life in milliseconds – confidence halves after this duration */
+    halfLifeMs: number;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * A signal that contributes to the confidence that two entities are the
+ * same person.
+ */
+export interface ResolutionSignal {
+    type: ResolutionSignalType;
+    weight: number;
+    evidence: string;
+    timestamp: number;
+}
+export type ResolutionSignalType = "name_match" | "handle_correlation" | "project_affinity" | "shared_connections" | "temporal_proximity" | "self_identification" | "admin_confirmation" | "llm_inference";
+/**
+ * A link between two entities that the agent believes (with some
+ * confidence) are the same person.
+ */
+export interface EntityLink {
+    id: UUID;
+    entityA: UUID;
+    entityB: UUID;
+    confidence: number;
+    status: EntityLinkStatus;
+    signals: ResolutionSignal[];
+    /** Who or what created this link */
+    proposedBy: "system" | UUID;
+    confirmedBy?: UUID;
+    rejectedBy?: UUID;
+    /** The merge task ID if one was created */
+    mergeTaskId?: UUID;
+    createdAt: number;
+    updatedAt: number;
+}
+export type EntityLinkStatus = "proposed" | "confirmed" | "rejected" | "merged";
+/**
+ * A candidate pair returned by the candidate generator.
+ */
+export interface ResolutionCandidate {
+    entityA: UUID;
+    entityB: UUID;
+    /** Raw signals before scoring */
+    signals: ResolutionSignal[];
+    /** Combined score 0-1 */
+    score: number;
+}
+/**
+ * Relationship types the agent can detect.
+ */
+export type RelationshipType = "friend" | "colleague" | "family" | "community" | "acquaintance" | "mentor" | "adversarial";
+/**
+ * A snapshot of a relationship at a point in time, used to track
+ * evolution.
+ */
+export interface RelationshipSnapshot {
+    type: RelationshipType;
+    strength: number;
+    sentiment: "positive" | "negative" | "neutral";
+    timestamp: number;
+}
+/**
+ * Extended relationship metadata tracked by the rolodex.
+ */
+export interface RolodexRelationshipMetadata {
+    relationshipType: RelationshipType;
+    sentiment: "positive" | "negative" | "neutral";
+    strength: number;
+    interactionCount: number;
+    lastInteractionAt: string;
+    /** Snapshots for evolution tracking */
+    history: RelationshipSnapshot[];
+    /** Half-life for decay in ms (default 30 days) */
+    decayHalfLifeMs: number;
+    /** Base strength before decay */
+    baseStrength: number;
+    /** When strength was last recalculated */
+    lastDecayAt: number;
+    autoDetected: boolean;
+}
+/**
+ * What the LLM returns when analyzing a conversation for relationships.
+ */
+export interface ExtractionResult {
+    platformIdentities: ExtractedIdentity[];
+    relationships: ExtractedRelationship[];
+    mentionedPeople: ExtractedMention[];
+    disputes: ExtractedDispute[];
+    privacyBoundaries: ExtractedPrivacy[];
+    trustSignals: ExtractedTrustSignal[];
+}
+export interface ExtractedIdentity {
+    platform: string;
+    handle: string;
+    /** Who this identity belongs to (name or reference to speaker) */
+    belongsTo: string;
+    /** How confident the LLM is */
+    confidence: number;
+    /** 'self' if the person said it about themselves, 'other' if someone else */
+    reportedBy: "self" | "other";
+}
+export interface ExtractedRelationship {
+    personA: string;
+    personB: string;
+    type: RelationshipType;
+    sentiment: "positive" | "negative" | "neutral";
+    confidence: number;
+    evidence: string;
+}
+export interface ExtractedMention {
+    name: string;
+    context: string;
+    attributes: Record<string, string>;
+    /** Whether this person is a participant or a third party */
+    isParticipant: boolean;
+}
+export interface ExtractedDispute {
+    /** Who is disputing */
+    disputer: string;
+    /** Whose information is being disputed */
+    about: string;
+    /** What field is being disputed */
+    field: string;
+    /** The existing value being challenged */
+    existingValue: string;
+    /** The proposed replacement */
+    proposedValue: string;
+    confidence: number;
+}
+export interface ExtractedPrivacy {
+    /** Who requested privacy */
+    requestedBy: string;
+    /** What should be kept private */
+    content: string;
+    /** Who it should be hidden from ('everyone', a specific name, etc.) */
+    hiddenFrom: string;
+    confidence: number;
+}
+export interface ExtractedTrustSignal {
+    entityName: string;
+    signal: "helpful" | "suspicious" | "authoritative" | "deceptive" | "neutral";
+    evidence: string;
+    severity: number;
+}
+export interface ContactCategory {
+    id: string;
+    name: string;
+    description?: string;
+    color?: string;
+}
+export interface ContactPreferences {
+    preferredCommunicationChannel?: string;
+    timezone?: string;
+    language?: string;
+    contactFrequency?: "daily" | "weekly" | "monthly" | "quarterly";
+    doNotDisturb?: boolean;
+    notes?: string;
+}
+export interface ContactInfo {
+    entityId: UUID;
+    categories: string[];
+    tags: string[];
+    preferences: ContactPreferences;
+    customFields: Record<string, string>;
+    privacyLevel: "public" | "private" | "restricted";
+    lastModified: string;
+}
+export interface RelationshipAnalytics {
+    strength: number;
+    interactionCount: number;
+    lastInteractionAt?: string;
+    averageResponseTime?: number;
+    sentimentScore?: number;
+    topicsDiscussed: string[];
+}
+export interface FollowUpSuggestion {
+    entityId: UUID;
+    entityName: string;
+    reason: string;
+    daysSinceLastContact: number;
+    relationshipStrength: number;
+    suggestedMessage?: string;
+}
+/** Default half-lives per information tier (in milliseconds) */
+export declare const DEFAULT_HALF_LIVES: Record<InformationTier, number>;
+/** Default half-life for relationship decay (30 days) */
+export declare const DEFAULT_RELATIONSHIP_DECAY_MS: number;
+/** Confidence thresholds for entity resolution */
+export declare const RESOLUTION_THRESHOLDS: {
+    /** Below this, discard the candidate */
+    readonly DISCARD: 0.15;
+    /** Above this, create a merge task for review */
+    readonly PROPOSE: 0.25;
+    /** Above this, auto-confirm the link (still creates a task for record) */
+    readonly AUTO_CONFIRM: 0.85;
+};
+/** Weights for each resolution signal type */
+export declare const SIGNAL_WEIGHTS: Record<ResolutionSignalType, number>;