memorix 1.3.3 → 1.3.4

package/dist/index.d.ts

@@ -1 +1,514 @@
 #!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Entity, Relation, KnowledgeGraph } from './types.js';
+
+/**
+ * These sources describe how Memorix learned a workspace binding. They are
+ * product facts, intentionally separate from any MCP transport session ID.
+ */
+type ProjectBindingSource = 'startup-cwd' | 'mcp-roots' | 'explicit-project-root';
+interface ProjectBindingSnapshot {
+    projectRoot: string;
+    source: ProjectBindingSource;
+    explicit: boolean;
+    projectId?: string;
+}
+interface MemorixRequestContext extends ProjectBindingSnapshot {
+    actorId?: string;
+}
+/**
+ * One connection may keep this object today, while a future stateless adapter
+ * can construct it from fixed server configuration. No HTTP session identifier
+ * is accepted or stored here.
+ */
+declare class ProjectBindingController {
+    private current;
+    constructor(projectRoot: string);
+    snapshot(): ProjectBindingSnapshot;
+    requestContext(actorId?: string): MemorixRequestContext;
+    isExplicit(): boolean;
+    /** Roots are advisory and may never overwrite an explicit user binding. */
+    bindFromRoots(projectRoot: string): boolean;
+    bindExplicit(projectRoot: string): void;
+    bindStartup(projectRoot: string): void;
+    /** Set only after the caller has verified the path maps to a real project. */
+    recordResolvedProject(projectId: string, projectRoot?: string): void;
+    private replace;
+}
+
+/**
+ * TeamEventBus — Process-local typed event emitter for team coordination.
+ *
+ * Phase 4b: Provides push-based acceleration within a single process.
+ * NOT a cross-process mechanism — the orchestrator uses SQLite polling.
+ *
+ * Architectural boundary (B1): This is process-local fanout only.
+ * No persistence, no cross-process delivery, no durability guarantees.
+ * If no listeners are registered, events are silently dropped.
+ */
+interface TeamEventMap {
+    'task:created': {
+        taskId: string;
+        projectId: string;
+        description: string;
+    };
+    'task:claimed': {
+        taskId: string;
+        projectId: string;
+        agentId: string;
+    };
+    'task:completed': {
+        taskId: string;
+        projectId: string;
+        agentId: string;
+        result?: string;
+    };
+    'task:failed': {
+        taskId: string;
+        projectId: string;
+        agentId: string;
+        result?: string;
+    };
+    'task:released': {
+        taskId: string;
+        projectId: string;
+        agentId: string;
+    };
+    'agent:joined': {
+        agentId: string;
+        projectId: string;
+        agentType: string;
+    };
+    'agent:left': {
+        agentId: string;
+        projectId: string;
+    };
+    'agent:stale': {
+        agentId: string;
+        projectId: string;
+        releasedTasks: number;
+    };
+    'handoff:created': {
+        observationId: number;
+        projectId: string;
+        fromAgent: string;
+        toAgent?: string;
+        taskId?: string;
+    };
+}
+type TeamEventName = keyof TeamEventMap;
+declare class TeamEventBus {
+    private emitter;
+    constructor();
+    /**
+     * Emit a typed event. Non-blocking, best-effort.
+     * If no listeners are registered, the event is silently dropped.
+     */
+    emit<K extends TeamEventName>(event: K, data: TeamEventMap[K]): void;
+    /** Subscribe to a typed event. Returns unsubscribe function. */
+    on<K extends TeamEventName>(event: K, listener: (data: TeamEventMap[K]) => void): () => void;
+    /** Subscribe to a typed event, fire only once. */
+    once<K extends TeamEventName>(event: K, listener: (data: TeamEventMap[K]) => void): void;
+    /** Remove all listeners for a specific event, or all events if none specified. */
+    removeAllListeners(event?: TeamEventName): void;
+    /** Current listener count for a specific event. */
+    listenerCount(event: TeamEventName): number;
+}
+
+/**
+ * TeamStore - SQLite-backed persistence for orchestration coordination state.
+ *
+ * Phase 4a: Replaces the file-based team-state.json persistence with
+ * SQLite prepared statements on the shared DB handle (memorix.db).
+ *
+ * Provides:
+ *   - Singleton init/get/reset pattern (same as SessionStore)
+ *   - Shared DB handle via getDatabase()
+ *   - One-time migration from team-state.json
+ *   - Prepared statements for all team CRUD operations
+ *
+ * All team modules (registry, messages, tasks, locks) delegate to this store.
+ */
+
+interface TeamAgentRow {
+    agent_id: string;
+    project_id: string;
+    agent_type: string;
+    instance_id: string;
+    name: string;
+    role: string | null;
+    capabilities: string | null;
+    status: 'active' | 'inactive';
+    joined_at: number;
+    last_heartbeat: number;
+    left_at: number | null;
+    last_seen_obs_generation: number;
+}
+interface TeamMessageRow {
+    id: string;
+    project_id: string;
+    sender_agent_id: string;
+    recipient_agent_id: string | null;
+    type: string;
+    content: string;
+    payload: string | null;
+    task_id: string | null;
+    read_at: number | null;
+    created_at: number;
+    to_role: string | null;
+    handoff_status: string | null;
+}
+interface TeamTaskRow {
+    task_id: string;
+    project_id: string;
+    description: string;
+    status: 'pending' | 'in_progress' | 'completed' | 'failed';
+    assignee_agent_id: string | null;
+    result: string | null;
+    metadata: string | null;
+    created_by: string | null;
+    created_at: number;
+    updated_at: number;
+    required_role: string | null;
+    preferred_role: string | null;
+}
+interface TeamLockRow {
+    file: string;
+    project_id: string;
+    locked_by: string;
+    locked_at: number;
+    expires_at: number;
+}
+interface TeamRoleRow {
+    role_id: string;
+    project_id: string;
+    label: string;
+    description: string | null;
+    preferred_agent_types: string;
+    max_concurrent: number;
+    created_at: number;
+}
+declare class TeamStore {
+    private db;
+    private dataDir;
+    /** Optional event bus for same-process lifecycle notifications.
+     *  Set via setEventBus(). Emit failures never block TeamStore writes. */
+    private eventBus;
+    setEventBus(bus: TeamEventBus): void;
+    getEventBus(): TeamEventBus | null;
+    private stmtAgentUpsert;
+    private stmtAgentFindByInstance;
+    private stmtAgentFindById;
+    private stmtAgentListByProject;
+    private stmtAgentUpdateHeartbeat;
+    private stmtAgentLeave;
+    private stmtAgentUpdateWatermark;
+    private stmtMsgInsert;
+    private stmtMsgInbox;
+    private stmtMsgMarkRead;
+    private stmtMsgMarkAllRead;
+    private stmtMsgUnreadCount;
+    private stmtMsgPruneRead;
+    private stmtMsgClearInbox;
+    private stmtMsgById;
+    private stmtTaskInsert;
+    private stmtTaskClaim;
+    private stmtTaskReClaim;
+    private stmtTaskComplete;
+    private stmtTaskFail;
+    private stmtTaskRelease;
+    private stmtTaskReleaseByAgent;
+    private stmtTaskById;
+    private stmtTaskListByProject;
+    private stmtTaskAvailable;
+    private stmtTaskDepInsert;
+    private stmtTaskDepsByTask;
+    private stmtTaskUnmetDeps;
+    private stmtLockUpsert;
+    private stmtLockGet;
+    private stmtLockDelete;
+    private stmtLockListByProject;
+    private stmtLockListByAgent;
+    private stmtLockDeleteByAgent;
+    private stmtLockDeleteExpired;
+    private stmtRoleInsert;
+    private stmtRoleDelete;
+    private stmtRoleListByProject;
+    private stmtRoleGetById;
+    private stmtRoleCountByProject;
+    init(dataDir: string): Promise<void>;
+    private prepareAgentStatements;
+    private prepareMessageStatements;
+    private prepareTaskStatements;
+    private prepareLockStatements;
+    /**
+     * Register or reactivate an agent.
+     * If an agent with the same (project_id, agent_type, instance_id) exists,
+     * reactivate it (preserving agent_id). Otherwise create a new one.
+     */
+    registerAgent(input: {
+        projectId: string;
+        agentType: string;
+        instanceId?: string;
+        name?: string;
+        role?: string;
+        capabilities?: string[];
+    }): TeamAgentRow;
+    getAgent(agentId: string): TeamAgentRow | undefined;
+    getAgentByInstance(projectId: string, agentType: string, instanceId: string): TeamAgentRow | undefined;
+    listAgents(projectId: string, filter?: {
+        status?: 'active' | 'inactive';
+    }): TeamAgentRow[];
+    /** List agents across all projects (for global scope) */
+    listAllAgents(): TeamAgentRow[];
+    /** List locks across all projects (for global scope) */
+    listAllLocks(): TeamLockRow[];
+    /** List tasks across all projects (for global scope) */
+    listAllTasks(filter?: {
+        available?: boolean;
+    }): TeamTaskRow[];
+    heartbeat(agentId: string): boolean;
+    leaveAgent(agentId: string): boolean;
+    updateWatermark(agentId: string, generation: number): void;
+    /**
+     * Detect and mark stale agents. Returns list of stale agent IDs whose tasks/locks were released.
+     */
+    detectAndMarkStale(projectId: string, staleTtlMs: number): string[];
+    getActiveCount(projectId: string): number;
+    sendMessage(input: {
+        projectId: string;
+        senderAgentId: string;
+        recipientAgentId?: string | null;
+        type: string;
+        content: string;
+        payload?: Record<string, unknown>;
+        taskId?: string;
+        toRole?: string | null;
+        handoffStatus?: string | null;
+    }): TeamMessageRow | {
+        error: string;
+    };
+    getInbox(projectId: string, agentId: string): TeamMessageRow[];
+    getUnreadCount(projectId: string, agentId: string): number;
+    markMessageRead(messageId: string): boolean;
+    markAllRead(projectId: string, agentId: string): number;
+    pruneReadMessages(projectId: string, olderThanMs: number): number;
+    clearInbox(projectId: string, agentId: string): number;
+    getMessageById(messageId: string): TeamMessageRow | undefined;
+    createTask(input: {
+        projectId: string;
+        description: string;
+        deps?: string[];
+        metadata?: Record<string, unknown>;
+        createdBy?: string;
+        requiredRole?: string | null;
+        preferredRole?: string | null;
+    }): TeamTaskRow;
+    getTask(taskId: string): TeamTaskRow | undefined;
+    getTaskDeps(taskId: string): string[];
+    /**
+     * Atomic task claim with dependency check.
+     * Uses BEGIN IMMEDIATE to serialize the dep check + claim atomically.
+     * Returns { success, task, reason? }.
+     */
+    claimTask(taskId: string, agentId: string): {
+        success: boolean;
+        task?: TeamTaskRow;
+        reason?: string;
+        hint?: string;
+    };
+    completeTask(taskId: string, agentId: string, result?: string): {
+        success: boolean;
+        reason?: string;
+    };
+    failTask(taskId: string, agentId: string, result?: string): {
+        success: boolean;
+        reason?: string;
+    };
+    releaseTask(taskId: string, agentId: string): {
+        success: boolean;
+        reason?: string;
+    };
+    releaseTasksByAgent(agentId: string): number;
+    listTasks(projectId: string, filter?: {
+        status?: string;
+        assignee?: string;
+        available?: boolean;
+    }): TeamTaskRow[];
+    /**
+     * List available tasks for a specific agent, sorted by role affinity.
+     * Tasks whose preferred_role matches the agent's role come first,
+     * then tasks whose required_role matches, then role-agnostic tasks.
+     * Tasks whose required_role does NOT match the agent's role are excluded.
+     */
+    listTasksForAgent(projectId: string, agentId: string): TeamTaskRow[];
+    private readonly DEFAULT_LOCK_TTL_MS;
+    acquireLock(projectId: string, file: string, agentId: string, ttlMs?: number): {
+        success: boolean;
+        lockedBy: string;
+    };
+    releaseLock(projectId: string, file: string, agentId: string): boolean;
+    getLockStatus(projectId: string, file: string): TeamLockRow | null;
+    listLocks(projectId: string, agentId?: string): TeamLockRow[];
+    releaseAllLocks(agentId: string): number;
+    cleanExpiredLocks(projectId: string): number;
+    private migrateFromJsonIfNeeded;
+    private prepareRoleStatements;
+    /**
+     * Seed default roles for a project if none exist yet.
+     * Uses projectId derived from the dataDir path.
+     */
+    private seedDefaultRoles;
+    addRole(projectId: string, input: {
+        roleId: string;
+        label: string;
+        description?: string;
+        preferredAgentTypes?: string[];
+        maxConcurrent?: number;
+    }): TeamRoleRow;
+    removeRole(projectId: string, roleId: string): boolean;
+    listRoles(projectId: string): TeamRoleRow[];
+    getRole(roleId: string): TeamRoleRow | undefined;
+    /**
+     * Get role occupancy: for each role, how many active agents currently fill it.
+     */
+    getRoleOccupancy(projectId: string): Array<{
+        role: TeamRoleRow;
+        activeAgents: TeamAgentRow[];
+        vacant: number;
+    }>;
+    /**
+     * Get handoff messages for a project, optionally filtered by role or status.
+     */
+    listHandoffs(projectId: string, filter?: {
+        toRole?: string;
+        status?: string;
+    }): TeamMessageRow[];
+    /**
+     * Update handoff status for a message.
+     */
+    updateHandoffStatus(messageId: string, status: string): boolean;
+    getDb(): any;
+}
+
+/**
+ * Knowledge Graph Manager
+ *
+ * Manages the Entity-Relation knowledge graph.
+ * Source: MCP Official Memory Server v0.6.3 (complete rewrite with same API).
+ *
+ * Key differences from official implementation:
+ * - Uses per-project JSONL files (official uses single file)
+ * - Async initialization with persistence layer
+ * - Project-scoped operations
+ */
+
+declare class KnowledgeGraphManager {
+    private entities;
+    private relations;
+    private projectDir;
+    private initialized;
+    /** Index: lowercase entity name → Entity for O(1) lookups */
+    private entityIndex;
+    constructor(projectDir: string);
+    /** Rebuild the entity name index */
+    private rebuildIndex;
+    /** Load graph from SQLite on first access */
+    init(): Promise<void>;
+    /** Find entity by name (case-insensitive, O(1)) */
+    findEntityByName(name: string): Entity | undefined;
+    /** Get all entity names as a Set (lowercase, for fast membership checks) */
+    getEntityNameSet(): Set<string>;
+    /** Persist current state to SQLite */
+    private save;
+    /** Create new entities (skip duplicates by name) */
+    createEntities(entities: Entity[]): Promise<Entity[]>;
+    /** Create new relations (skip duplicates) */
+    createRelations(relations: Relation[]): Promise<Relation[]>;
+    /** Add observations to existing entities */
+    addObservations(observations: {
+        entityName: string;
+        contents: string[];
+    }[]): Promise<{
+        entityName: string;
+        addedObservations: string[];
+    }[]>;
+    /** Delete entities and their associated relations */
+    deleteEntities(entityNames: string[]): Promise<void>;
+    /** Delete specific observations from entities */
+    deleteObservations(deletions: {
+        entityName: string;
+        observations: string[];
+    }[]): Promise<void>;
+    /** Delete specific relations */
+    deleteRelations(relations: Relation[]): Promise<void>;
+    /** Get all entity names (for Formation Pipeline entity resolution) */
+    getEntityNames(): string[];
+    /** Read the entire graph */
+    readGraph(): Promise<KnowledgeGraph>;
+    /** Search nodes by query string (upgraded from official's basic includes) */
+    searchNodes(query: string): Promise<KnowledgeGraph>;
+    /** Open specific nodes by name */
+    openNodes(names: string[]): Promise<KnowledgeGraph>;
+}
+
+/**
+ * Tool Profile System — Progressive Disclosure for MCP tools
+ *
+ * The full Memorix tool set contains 40+ tools, but most users only ever
+ * use a small subset (store / search / detail). Exposing all of them at
+ * tools/list time causes cognitive overload.
+ *
+ * We provide four profiles:
+ *   - "micro" (stdio default): Agent-ready project context + bounded recovery/media controls — 9 tools.
+ *     Suitable for normal MCP clients where every tool schema costs context tokens.
+ *   - "lite": Core memory CRUD, sessions, reasoning, retention, backup — 18 tools.
+ *     Suitable for solo users who want the full memory surface without team tools.
+ *   - "team" (HTTP default): lite + orchestration coordination tools, dashboard, and Knowledge Workspace — 26 tools.
+ *     Suitable when an operator explicitly wants task/message/lock surfaces.
+ *   - "full": Everything, including niche / advanced tools (consolidate, dedup,
+ *     formation metrics, skills, rules/workspace sync, KG-official, image ingest).
+ *     Opt in via `MEMORIX_MODE=full` or `--mode full`.
+ *
+ * Users can override at any time via the `MEMORIX_MODE` env var, the `--mode`
+ * CLI flag, or programmatically via `createMemorixServer({ toolProfile: ... })`.
+ */
+type ToolProfile = 'micro' | 'lite' | 'team' | 'full';
+
+/**
+ * Create and configure the Memorix MCP Server.
+ */
+/** Optional shared TeamStore — passed by serve-http so all sessions share state */
+interface SharedTeamInstances {
+    teamStore: TeamStore;
+}
+interface CreateMemorixServerOptions {
+    allowUntrackedFallback?: boolean;
+    deferProjectInitUntilBound?: boolean;
+    /**
+     * Register tools and return before loading the full project memory runtime.
+     * Intended for stdio clients and registries where MCP initialize/tools/list must
+     * complete quickly even when the local memory corpus is large.
+     */
+    deferProjectRuntimeInit?: boolean;
+    dashboardMode?: 'standalone' | 'control-plane';
+    dashboardPort?: number;
+    toolProfile?: ToolProfile;
+    /**
+     * Product-scoped project binding. HTTP transports may keep it beside a
+     * legacy session adapter today; no project operation reads session headers.
+     */
+    projectBinding?: ProjectBindingController;
+}
+declare function createMemorixServer(cwd?: string, existingServer?: McpServer, sharedTeam?: SharedTeamInstances, options?: CreateMemorixServerOptions): Promise<{
+    server: McpServer;
+    graphManager: KnowledgeGraphManager;
+    projectId: string;
+    deferredInit: () => Promise<void>;
+    switchProject: (newCwd: string) => Promise<boolean>;
+    isExplicitlyBound: () => boolean;
+    getRequestContext: () => MemorixRequestContext;
+    handleTransportClose: () => void;
+}>;
+
+export { type CreateMemorixServerOptions, createMemorixServer };