interface IDatabaseAdapter<DB extends object = object> {
db: DB;
// Initialization
initialize(config?: Record<string, string | number | boolean | null>): Promise<void>;
init(): Promise<void>;
isReady(): Promise<boolean>;
close(): Promise<void>;
getConnection(): Promise<DB>;
// Migration methods
runPluginMigrations?(
plugins: Array<{ name: string; schema?: Record<string, JsonValue | object> }>,
options?: { verbose?: boolean; force?: boolean; dryRun?: boolean }
): Promise<void>;
runMigrations?(migrationsPaths?: string[]): Promise<void>;
// Entity context for RLS
withEntityContext?<T>(
entityId: UUID | null,
callback: () => Promise<T>
): Promise<T>;
// Agent management
getAgent(agentId: UUID): Promise<Agent | null>;
getAgents(): Promise<Partial<Agent>[]>;
createAgent(agent: Partial<Agent>): Promise<boolean>;
updateAgent(agentId: UUID, agent: Partial<Agent>): Promise<boolean>;
deleteAgent(agentId: UUID): Promise<boolean>;
// Entity management
getEntitiesByIds(entityIds: UUID[]): Promise<Entity[] | null>;
getEntitiesForRoom(roomId: UUID, includeComponents?: boolean): Promise<Entity[]>;
createEntities(entities: Entity[]): Promise<boolean>;
updateEntity(entity: Entity): Promise<void>;
// Component management
getComponent(entityId: UUID, type: string, worldId?: UUID, sourceEntityId?: UUID): Promise<Component | null>;
getComponents(entityId: UUID, worldId?: UUID, sourceEntityId?: UUID): Promise<Component[]>;
createComponent(component: Component): Promise<boolean>;
updateComponent(component: Component): Promise<void>;
deleteComponent(componentId: UUID): Promise<void>;
// Memory operations
ensureEmbeddingDimension(dimension: number): Promise<void>;
getMemories(params: {
entityId?: UUID;
agentId?: UUID;
count?: number;
offset?: number;
unique?: boolean;
tableName: string;
start?: number;
end?: number;
roomId?: UUID;
worldId?: UUID;
}): Promise<Memory[]>;
getMemoryById(id: UUID): Promise<Memory | null>;
getMemoriesByIds(ids: UUID[], tableName?: string): Promise<Memory[]>;
getMemoriesByRoomIds(params: {
tableName: string;
roomIds: UUID[];
limit?: number;
}): Promise<Memory[]>;
getMemoriesByWorldId(params: {
worldId: UUID;
count?: number;
tableName?: string;
}): Promise<Memory[]>;
getCachedEmbeddings(params: {
query_table_name: string;
query_threshold: number;
query_input: string;
query_field_name: string;
query_field_sub_name: string;
query_match_count: number;
}): Promise<{ embedding: number[]; levenshtein_score: number }[]>;
searchMemories(params: {
embedding: number[];
match_threshold?: number;
count?: number;
unique?: boolean;
tableName: string;
query?: string;
roomId?: UUID;
worldId?: UUID;
entityId?: UUID;
}): Promise<Memory[]>;
createMemory(memory: Memory, tableName: string, unique?: boolean): Promise<UUID>;
updateMemory(memory: Partial<Memory> & { id: UUID; metadata?: MemoryMetadata }): Promise<boolean>;
deleteMemory(memoryId: UUID): Promise<void>;
deleteManyMemories(memoryIds: UUID[]): Promise<void>;
deleteAllMemories(roomId: UUID, tableName: string): Promise<void>;
countMemories(roomId: UUID, unique?: boolean, tableName?: string): Promise<number>;
// Logging
log(params: { body: LogBody; entityId: UUID; roomId: UUID; type: string }): Promise<void>;
getLogs(params: {
entityId?: UUID;
roomId?: UUID;
type?: string;
count?: number;
offset?: number;
}): Promise<Log[]>;
deleteLog(logId: UUID): Promise<void>;
getAgentRunSummaries?(params: {
limit?: number;
roomId?: UUID;
status?: RunStatus | "all";
from?: number;
to?: number;
entityId?: UUID;
}): Promise<AgentRunSummaryResult>;
// World and Room management
createWorld(world: World): Promise<UUID>;
getWorld(id: UUID): Promise<World | null>;
removeWorld(id: UUID): Promise<void>;
getAllWorlds(): Promise<World[]>;
updateWorld(world: World): Promise<void>;
getRoomsByIds(roomIds: UUID[]): Promise<Room[] | null>;
createRooms(rooms: Room[]): Promise<UUID[]>;
deleteRoom(roomId: UUID): Promise<void>;
deleteRoomsByWorldId(worldId: UUID): Promise<void>;
updateRoom(room: Room): Promise<void>;
getRoomsForParticipant(entityId: UUID): Promise<UUID[]>;
getRoomsForParticipants(userIds: UUID[]): Promise<UUID[]>;
getRoomsByWorld(worldId: UUID): Promise<Room[]>;
// Participant management
removeParticipant(entityId: UUID, roomId: UUID): Promise<boolean>;
getParticipantsForEntity(entityId: UUID): Promise<Participant[]>;
getParticipantsForRoom(roomId: UUID): Promise<UUID[]>;
isRoomParticipant(roomId: UUID, entityId: UUID): Promise<boolean>;
addParticipantsRoom(entityIds: UUID[], roomId: UUID): Promise<boolean>;
getParticipantUserState(roomId: UUID, entityId: UUID): Promise<"FOLLOWED" | "MUTED" | null>;
setParticipantUserState(roomId: UUID, entityId: UUID, state: "FOLLOWED" | "MUTED" | null): Promise<void>;
// Relationship management
createRelationship(params: {
sourceEntityId: UUID;
targetEntityId: UUID;
tags?: string[];
metadata?: Metadata;
}): Promise<boolean>;
updateRelationship(relationship: Relationship): Promise<void>;
getRelationship(params: {
sourceEntityId: UUID;
targetEntityId: UUID;
}): Promise<Relationship | null>;
getRelationships(params: {
entityId: UUID;
tags?: string[];
}): Promise<Relationship[]>;
// Cache operations
getCache<T>(key: string): Promise<T | undefined>;
setCache<T>(key: string, value: T): Promise<boolean>;
deleteCache(key: string): Promise<boolean>;
// Task management
createTask(task: Task): Promise<UUID>;
getTasks(params: { roomId?: UUID; tags?: string[]; entityId?: UUID }): Promise<Task[]>;
getTask(id: UUID): Promise<Task | null>;
getTasksByName(name: string): Promise<Task[]>;
updateTask(id: UUID, task: Partial<Task>): Promise<void>;
deleteTask(id: UUID): Promise<void>;
// Pairing (DM access control)
getPairingRequests(channel: PairingChannel, agentId: UUID): Promise<PairingRequest[]>;
createPairingRequest(request: PairingRequest): Promise<UUID>;
updatePairingRequest(request: PairingRequest): Promise<void>;
deletePairingRequest(id: UUID): Promise<void>;
getPairingAllowlist(channel: PairingChannel, agentId: UUID): Promise<PairingAllowlistEntry[]>;
createPairingAllowlistEntry(entry: PairingAllowlistEntry): Promise<UUID>;
deletePairingAllowlistEntry(id: UUID): Promise<void>;
}