@hasna/mementos 0.14.39 → 0.14.40

package/dist/sdk/index.d.ts

@@ -0,0 +1,760 @@
+/**
+ * @hasna/mementos/sdk — Zero-dependency TypeScript client for @hasna/mementos REST API.
+ *
+ * Import: `import { MementosClient } from "@hasna/mementos/sdk"`
+ *
+ * Works in Node.js, Bun, Deno, and browsers. No external dependencies beyond fetch.
+ */
+export type MemoryScope = "global" | "shared" | "private" | "working";
+export type MemoryCategory = "preference" | "fact" | "knowledge" | "history" | "procedural" | "resource";
+export type MemorySource = "user" | "agent" | "system" | "auto" | "imported";
+export type MemoryStatus = "active" | "archived" | "expired";
+export type EntityType = "person" | "place" | "thing" | "concept" | "project" | "agent" | "file" | "url";
+export type RelationType = "uses" | "knows" | "depends_on" | "created_by" | "related_to" | "contradicts" | "part_of" | "implements" | "happened_before" | "happened_after" | "caused_by" | "resulted_in" | "supersedes" | "version_of";
+export type EntityRole = "subject" | "object" | "context" | "author" | "target";
+export type TaskStatus = "pending" | "in_progress" | "completed" | "failed" | "cancelled";
+export type TaskPriority = "critical" | "high" | "medium" | "low";
+export interface Task {
+    id: string;
+    subject: string;
+    description: string;
+    status: TaskStatus;
+    priority: TaskPriority;
+    tags: string[];
+    assigned_agent_id: string | null;
+    project_id: string | null;
+    session_id: string | null;
+    parent_task_id: string | null;
+    metadata: Record<string, unknown>;
+    progress: number;
+    due_at: string | null;
+    started_at: string | null;
+    completed_at: string | null;
+    failed_at: string | null;
+    error: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface TaskComment {
+    id: string;
+    task_id: string;
+    agent_id: string | null;
+    body: string;
+    created_at: string;
+}
+export interface CreateTaskInput {
+    subject: string;
+    description?: string;
+    priority?: TaskPriority;
+    tags?: string[];
+    assigned_agent_id?: string;
+    project_id?: string;
+    session_id?: string;
+    parent_task_id?: string;
+    metadata?: Record<string, unknown>;
+    due_at?: string;
+}
+export interface UpdateTaskInput {
+    subject?: string;
+    description?: string;
+    status?: TaskStatus;
+    priority?: TaskPriority;
+    tags?: string[];
+    assigned_agent_id?: string | null;
+    metadata?: Record<string, unknown>;
+    progress?: number;
+    due_at?: string | null;
+    error?: string | null;
+}
+export interface TaskStats {
+    total: number;
+    by_status: Record<TaskStatus, number>;
+    by_priority: Record<TaskPriority, number>;
+    overdue: number;
+}
+export interface Memory {
+    id: string;
+    key: string;
+    value: string;
+    category: MemoryCategory;
+    scope: MemoryScope;
+    summary: string | null;
+    tags: string[];
+    importance: number;
+    source: MemorySource;
+    status: MemoryStatus;
+    pinned: boolean;
+    agent_id: string | null;
+    project_id: string | null;
+    session_id: string | null;
+    metadata: Record<string, unknown>;
+    access_count: number;
+    version: number;
+    expires_at: string | null;
+    created_at: string;
+    updated_at: string;
+    accessed_at: string | null;
+}
+export interface MemoryVersion {
+    id: string;
+    memory_id: string;
+    version: number;
+    value: string;
+    importance: number;
+    scope: MemoryScope;
+    category: MemoryCategory;
+    tags: string[];
+    summary: string | null;
+    pinned: boolean;
+    status: MemoryStatus;
+    created_at: string;
+}
+export interface Agent {
+    id: string;
+    name: string;
+    role: string | null;
+    description: string | null;
+    active_project_id?: string | null;
+    created_at: string;
+    last_seen_at: string | null;
+}
+export interface Project {
+    id: string;
+    name: string;
+    path: string | null;
+    description: string | null;
+    memory_prefix: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface Entity {
+    id: string;
+    name: string;
+    type: EntityType;
+    description: string | null;
+    metadata: Record<string, unknown>;
+    project_id: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface Relation {
+    id: string;
+    source_entity_id: string;
+    target_entity_id: string;
+    relation_type: RelationType;
+    weight: number;
+    metadata: Record<string, unknown>;
+    created_at: string;
+}
+export type ResourceType = "project" | "memory" | "entity" | "agent" | "connector" | "file";
+export type LockType = "advisory" | "exclusive";
+export interface ResourceLock {
+    id: string;
+    resource_type: ResourceType;
+    resource_id: string;
+    agent_id: string;
+    lock_type: LockType;
+    locked_at: string;
+    expires_at: string;
+}
+export interface AcquireLockInput {
+    agent_id: string;
+    resource_type: ResourceType;
+    resource_id: string;
+    lock_type?: LockType;
+    ttl_seconds?: number;
+}
+export interface MemoryStats {
+    total: number;
+    by_scope: Record<MemoryScope, number>;
+    by_category: Record<MemoryCategory, number>;
+    by_status: Record<MemoryStatus, number>;
+    by_agent: Record<string, number>;
+    pinned_count: number;
+    expired_count: number;
+}
+export interface CreateMemoryInput {
+    key: string;
+    value: string;
+    category?: MemoryCategory;
+    scope?: MemoryScope;
+    summary?: string;
+    tags?: string[];
+    importance?: number;
+    source?: MemorySource;
+    agent_id?: string;
+    project_id?: string;
+    session_id?: string;
+    metadata?: Record<string, unknown>;
+    expires_at?: string;
+    ttl?: string;
+}
+export interface UpdateMemoryInput {
+    value?: string;
+    category?: MemoryCategory;
+    scope?: MemoryScope;
+    summary?: string | null;
+    tags?: string[];
+    importance?: number;
+    pinned?: boolean;
+    status?: MemoryStatus;
+    metadata?: Record<string, unknown>;
+    expires_at?: string | null;
+    version?: number;
+}
+export interface ListMemoriesFilter {
+    scope?: MemoryScope;
+    category?: MemoryCategory;
+    tags?: string[];
+    min_importance?: number;
+    pinned?: boolean;
+    agent_id?: string;
+    project_id?: string;
+    session_id?: string;
+    namespace?: string;
+    status?: MemoryStatus;
+    limit?: number;
+    offset?: number;
+    fields?: string[];
+}
+export interface SearchMemoriesInput {
+    query: string;
+    scope?: MemoryScope;
+    category?: MemoryCategory;
+    tags?: string[];
+    session_id?: string;
+    namespace?: string;
+    limit?: number;
+}
+export interface ExportMemoriesInput {
+    scope?: MemoryScope;
+    category?: MemoryCategory;
+    agent_id?: string;
+    project_id?: string;
+    tags?: string[];
+    limit?: number;
+}
+export interface ImportMemoriesInput {
+    memories: Partial<Memory>[];
+    overwrite?: boolean;
+}
+export interface CreateEntityInput {
+    name: string;
+    type: EntityType;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    project_id?: string;
+}
+export interface UpdateEntityInput {
+    name?: string;
+    type?: EntityType;
+    description?: string | null;
+    metadata?: Record<string, unknown>;
+}
+export interface CreateRelationInput {
+    source_entity_id: string;
+    target_entity_id: string;
+    relation_type: RelationType;
+    weight?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface ListTasksFilter {
+    status?: TaskStatus;
+    priority?: TaskPriority;
+    assigned_agent_id?: string;
+    project_id?: string;
+    session_id?: string;
+    parent_task_id?: string | null;
+    tags?: string[];
+    limit?: number;
+    offset?: number;
+}
+export interface MementosClientConfig {
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+}
+export declare class MementosError extends Error {
+    readonly status: number;
+    readonly details?: unknown | undefined;
+    constructor(message: string, status: number, details?: unknown | undefined);
+}
+export interface AutoMemoryQueueStats {
+    pending: number;
+    processing: number;
+    processed: number;
+    failed: number;
+    dropped: number;
+}
+export interface AutoMemoryConfig {
+    provider: "anthropic" | "openai" | "cerebras" | "grok";
+    model?: string;
+    enabled: boolean;
+    minImportance: number;
+    autoEntityLink: boolean;
+    fallback?: Array<"anthropic" | "openai" | "cerebras" | "grok">;
+}
+export interface SdkExtractedMemory {
+    content: string;
+    category: "preference" | "fact" | "knowledge" | "history";
+    importance: number;
+    tags: string[];
+    suggestedScope: "private" | "shared" | "global";
+    reasoning?: string;
+}
+export interface SdkHook {
+    id: string;
+    type: string;
+    blocking: boolean;
+    priority: number;
+    builtin: boolean;
+    agentId?: string;
+    projectId?: string;
+    description?: string;
+}
+export interface SdkWebhook {
+    id: string;
+    type: string;
+    handlerUrl: string;
+    priority: number;
+    blocking: boolean;
+    agentId?: string;
+    projectId?: string;
+    description?: string;
+    enabled: boolean;
+    createdAt: string;
+    invocationCount: number;
+    failureCount: number;
+}
+export interface SynthesisRun {
+    id: string;
+    triggered_by: string;
+    project_id: string | null;
+    agent_id: string | null;
+    corpus_size: number;
+    proposals_generated: number;
+    proposals_accepted: number;
+    proposals_rejected: number;
+    status: "pending" | "running" | "completed" | "failed" | "rolled_back";
+    error: string | null;
+    started_at: string;
+    completed_at: string | null;
+}
+export interface SynthesisResult {
+    run: SynthesisRun;
+    proposals: unknown[];
+    executed: number;
+    metrics: {
+        corpusReduction: number;
+        deduplicationRate: number;
+    } | null;
+    dryRun: boolean;
+}
+export interface SessionMemoryJob {
+    id: string;
+    session_id: string;
+    agent_id: string | null;
+    project_id: string | null;
+    source: string;
+    status: "pending" | "processing" | "completed" | "failed";
+    transcript: string;
+    chunk_count: number;
+    memories_extracted: number;
+    error: string | null;
+    metadata: Record<string, unknown>;
+    created_at: string;
+    started_at: string | null;
+    completed_at: string | null;
+}
+export declare class MementosClient {
+    private baseUrl;
+    private _fetch;
+    constructor(config?: MementosClientConfig);
+    static fromEnv(overrides?: Partial<MementosClientConfig>): MementosClient;
+    private request;
+    private get;
+    private post;
+    private patch;
+    private delete;
+    listMemories(filter?: ListMemoriesFilter): Promise<{
+        memories: Memory[];
+        count: number;
+    }>;
+    getStats(): Promise<MemoryStats>;
+    getHealth(): Promise<{
+        status: "ok" | "warn";
+        version: string;
+        profile: string;
+        db_path: string;
+        hostname: string;
+        memories: {
+            total: number;
+            expired: number;
+            pinned: number;
+        };
+        agents: number;
+        projects: number;
+    }>;
+    getReport(options?: {
+        days?: number;
+        project_id?: string;
+        agent_id?: string;
+    }): Promise<{
+        total: number;
+        pinned: number;
+        days: number;
+        recent: {
+            total: number;
+            activity: {
+                date: string;
+                memories_created: number;
+            }[];
+        };
+        by_scope: Record<string, number>;
+        by_category: Record<string, number>;
+        top_memories: {
+            id: string;
+            key: string;
+            value: string;
+            importance: number;
+            scope: string;
+            category: string;
+        }[];
+        top_agents: {
+            agent_id: string;
+            c: number;
+        }[];
+    }>;
+    getStaleMemories(options?: {
+        days?: number;
+        project_id?: string;
+        agent_id?: string;
+        limit?: number;
+    }): Promise<{
+        memories: Memory[];
+        count: number;
+        days: number;
+    }>;
+    getActivity(options?: {
+        days?: number;
+        scope?: MemoryScope;
+        agent_id?: string;
+        project_id?: string;
+    }): Promise<{
+        activity: {
+            date: string;
+            memories_created: number;
+            global_count: number;
+            shared_count: number;
+            private_count: number;
+            avg_importance: number;
+        }[];
+        days: number;
+        total: number;
+    }>;
+    searchMemories(input: SearchMemoriesInput | string): Promise<{
+        results: Memory[];
+        count: number;
+    }>;
+    exportMemories(input?: ExportMemoriesInput): Promise<{
+        memories: Memory[];
+        count: number;
+    }>;
+    importMemories(input: ImportMemoriesInput): Promise<{
+        imported: number;
+        errors: string[];
+        total: number;
+    }>;
+    cleanExpired(): Promise<{
+        cleaned: number;
+    }>;
+    extractFromSession(input: {
+        session_id: string;
+        title?: string;
+        project?: string;
+        model?: string;
+        messages?: number;
+        key_topics?: string[];
+        summary?: string;
+        agent_id?: string;
+        project_id?: string;
+        memories?: Partial<CreateMemoryInput>[];
+    }): Promise<{
+        created: number;
+        memory_ids: string[];
+        errors: string[];
+        session_id: string;
+    }>;
+    saveMemory(input: CreateMemoryInput): Promise<Memory>;
+    getMemory(id: string): Promise<Memory>;
+    getMemoryVersions(id: string): Promise<{
+        versions: MemoryVersion[];
+        count: number;
+        current_version: number;
+    }>;
+    updateMemory(id: string, input: UpdateMemoryInput): Promise<Memory>;
+    deleteMemory(id: string): Promise<{
+        deleted: boolean;
+    }>;
+    listAgents(): Promise<{
+        agents: Agent[];
+    }>;
+    registerAgent(input: {
+        name: string;
+        role?: string;
+        description?: string;
+    }): Promise<Agent>;
+    getAgent(idOrName: string): Promise<Agent>;
+    updateAgent(idOrName: string, updates: {
+        name?: string;
+        role?: string;
+        description?: string;
+        metadata?: Record<string, unknown>;
+        active_project_id?: string | null;
+    }): Promise<Agent>;
+    listAgentsByProject(projectId: string): Promise<{
+        agents: Agent[];
+        count: number;
+    }>;
+    listProjects(): Promise<{
+        projects: Project[];
+    }>;
+    registerProject(input: {
+        name: string;
+        path?: string;
+        description?: string;
+        memory_prefix?: string;
+    }): Promise<Project>;
+    getProject(idOrName: string): Promise<Project>;
+    getProjectAgents(idOrName: string): Promise<{
+        agents: Agent[];
+        count: number;
+    }>;
+    listEntities(filter?: {
+        type?: EntityType;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        entities: Entity[];
+        count: number;
+    }>;
+    createEntity(input: CreateEntityInput): Promise<Entity>;
+    mergeEntities(input: {
+        source_id: string;
+        target_id: string;
+    }): Promise<Entity>;
+    getEntity(id: string): Promise<Entity>;
+    updateEntity(id: string, input: UpdateEntityInput): Promise<Entity>;
+    deleteEntity(id: string): Promise<{
+        deleted: boolean;
+    }>;
+    getEntityMemories(entityId: string): Promise<{
+        memories: Memory[];
+        count: number;
+    }>;
+    linkEntityMemory(entityId: string, input: {
+        memory_id: string;
+        role?: EntityRole;
+    }): Promise<{
+        linked: boolean;
+    }>;
+    unlinkEntityMemory(entityId: string, memoryId: string): Promise<{
+        unlinked: boolean;
+    }>;
+    getEntityRelations(entityId: string, filter?: {
+        relation_type?: RelationType;
+        direction?: "from" | "to" | "both";
+    }): Promise<{
+        relations: Relation[];
+    }>;
+    createRelation(input: CreateRelationInput): Promise<Relation>;
+    getRelation(id: string): Promise<Relation>;
+    deleteRelation(id: string): Promise<{
+        deleted: boolean;
+    }>;
+    getGraph(entityId: string, options?: {
+        depth?: number;
+        relation_types?: RelationType[];
+    }): Promise<{
+        nodes: Entity[];
+        edges: Relation[];
+    }>;
+    findPath(fromId: string, toId: string): Promise<{
+        path: Entity[];
+        found: boolean;
+    }>;
+    getGraphStats(): Promise<{
+        entity_count: number;
+        relation_count: number;
+        by_type: Record<string, number>;
+    }>;
+    acquireLock(input: AcquireLockInput): Promise<ResourceLock | null>;
+    checkLock(resourceType: ResourceType, resourceId: string, lockType?: LockType): Promise<ResourceLock[]>;
+    releaseLock(lockId: string, agentId: string): Promise<{
+        released: boolean;
+    }>;
+    listAgentLocks(agentId: string): Promise<ResourceLock[]>;
+    releaseAllAgentLocks(agentId: string): Promise<{
+        released: number;
+    }>;
+    cleanExpiredLocks(): Promise<{
+        cleaned: number;
+    }>;
+    /** Create a task. */
+    createTask(input: CreateTaskInput): Promise<Task>;
+    /** List tasks with optional filters. */
+    listTasks(filter?: ListTasksFilter): Promise<{
+        tasks: Task[];
+        count: number;
+    }>;
+    /** Get task stats (by status, priority, overdue). */
+    getTaskStats(options?: {
+        project_id?: string;
+        agent_id?: string;
+    }): Promise<TaskStats>;
+    /** Get a task by ID. */
+    getTask(id: string): Promise<Task>;
+    /** Update a task. */
+    updateTask(id: string, input: UpdateTaskInput): Promise<Task>;
+    /** Delete a task. */
+    deleteTask(id: string): Promise<{
+        deleted: boolean;
+    }>;
+    /** List comments on a task. */
+    listTaskComments(taskId: string): Promise<{
+        comments: TaskComment[];
+        count: number;
+    }>;
+    /** Add a comment to a task. */
+    addTaskComment(taskId: string, body: string, agentId?: string): Promise<TaskComment>;
+    /** Delete a task comment. */
+    deleteTaskComment(taskId: string, commentId: string): Promise<{
+        deleted: boolean;
+    }>;
+    getContext(options?: {
+        agent_id?: string;
+        project_id?: string;
+        max_tokens?: number;
+        format?: "xml" | "markdown" | "compact" | "json";
+    }): Promise<{
+        context: string;
+        memories_count: number;
+    }>;
+    processConversationTurn(turn: string, context?: {
+        agent_id?: string;
+        project_id?: string;
+        session_id?: string;
+    }): Promise<{
+        queued: boolean;
+        queue: AutoMemoryQueueStats;
+    }>;
+    getAutoMemoryStatus(): Promise<{
+        queue: AutoMemoryQueueStats;
+        config: AutoMemoryConfig;
+        providers: Record<string, {
+            available: boolean;
+            model: string;
+        }>;
+    }>;
+    configureAutoMemory(config: Partial<AutoMemoryConfig> & {
+        min_importance?: number;
+        auto_entity_link?: boolean;
+    }): Promise<{
+        updated: boolean;
+        config: AutoMemoryConfig;
+    }>;
+    testExtraction(turn: string, options?: {
+        provider?: "anthropic" | "openai" | "cerebras" | "grok";
+        agent_id?: string;
+        project_id?: string;
+    }): Promise<{
+        provider: string;
+        model: string;
+        extracted: SdkExtractedMemory[];
+        count: number;
+        note: string;
+    }>;
+    listHooks(type?: string): Promise<SdkHook[]>;
+    getHookStats(): Promise<{
+        total: number;
+        byType: Record<string, number>;
+        blocking: number;
+        nonBlocking: number;
+    }>;
+    listWebhooks(filter?: {
+        type?: string;
+        enabled?: boolean;
+    }): Promise<SdkWebhook[]>;
+    createWebhook(input: {
+        type: string;
+        handler_url: string;
+        priority?: number;
+        blocking?: boolean;
+        agent_id?: string;
+        project_id?: string;
+        description?: string;
+    }): Promise<SdkWebhook>;
+    getWebhook(id: string): Promise<SdkWebhook>;
+    updateWebhook(id: string, updates: {
+        enabled?: boolean;
+        priority?: number;
+        description?: string;
+    }): Promise<SdkWebhook>;
+    deleteWebhook(id: string): Promise<void>;
+    enableWebhook(id: string): Promise<SdkWebhook>;
+    disableWebhook(id: string): Promise<SdkWebhook>;
+    runSynthesis(options?: {
+        project_id?: string;
+        agent_id?: string;
+        dry_run?: boolean;
+        max_proposals?: number;
+        provider?: string;
+    }): Promise<SynthesisResult>;
+    listSynthesisRuns(filter?: {
+        project_id?: string;
+        limit?: number;
+    }): Promise<{
+        runs: SynthesisRun[];
+        count: number;
+    }>;
+    getSynthesisStatus(options?: {
+        project_id?: string;
+        run_id?: string;
+    }): Promise<{
+        lastRun: SynthesisRun | null;
+        recentRuns: SynthesisRun[];
+    }>;
+    rollbackSynthesis(runId: string): Promise<{
+        rolled_back: number;
+        errors: string[];
+    }>;
+    ingestSession(input: {
+        transcript: string;
+        session_id: string;
+        agent_id?: string;
+        project_id?: string;
+        source?: "claude-code" | "codex" | "manual" | "open-sessions";
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        job_id: string;
+        status: string;
+        message: string;
+    }>;
+    getSessionJob(jobId: string): Promise<SessionMemoryJob>;
+    listSessionJobs(filter?: {
+        agent_id?: string;
+        project_id?: string;
+        status?: string;
+        limit?: number;
+    }): Promise<{
+        jobs: SessionMemoryJob[];
+        count: number;
+    }>;
+    getSessionQueueStats(): Promise<{
+        pending: number;
+        processing: number;
+        completed: number;
+        failed: number;
+    }>;
+}
+export default MementosClient;
+//# sourceMappingURL=index.d.ts.map