memorix 1.0.7 → 1.0.8

package/dist/sdk.d.ts

@@ -0,0 +1,677 @@
+import { Entity, Relation, KnowledgeGraph, ProjectInfo, DetectionResult, ObservationType, ObservationStatus, ProgressInfo, Observation, IndexEntry } from './types.js';
+export { AgentTarget, DEFAULT_CONFIG, DetectionFailure, DetectionFailureReason, DocumentType, KnowledgeLayer, MCPConfigAdapter, MCPServerEntry, MemorixConfig, MemorixDocument, MemoryRef, MiniSkill, OBSERVATION_ICONS, ObservationRef, RuleFormatAdapter, RuleSource, SearchOptions, Session, SkillConflict, SkillEntry, SnapshotObservation, SourceSnapshot, TOPIC_KEY_FAMILIES, TimelineContext, UnifiedRule, WorkflowEntry, WorkspaceSyncResult } from './types.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * 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 autonomous Agent Team 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 30+ 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 three profiles:
+ *   - "lite" (stdio default): Core memory CRUD, sessions, reasoning, retention,
+ *     backup — 13 tools. Suitable for solo users who just want cross-agent memory.
+ *   - "team" (HTTP default): lite + autonomous agent team tools + dashboard — 20 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 = '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;
+    dashboardMode?: 'standalone' | 'control-plane';
+    dashboardPort?: number;
+    toolProfile?: ToolProfile;
+}
+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;
+    handleTransportClose: () => void;
+}>;
+
+/**
+ * Project Detector
+ *
+ * Strict .git-based project detection.
+ * No .git = not a project. No fallbacks, no accommodations.
+ *
+ * ID strategy:
+ *   - .git + remote → normalizeGitRemote(remote)  (globally unique, e.g. "user/repo")
+ *   - .git + no remote → "local/<dirname>"         (local git repo, no remote yet)
+ *   - no .git → null                               (not a project)
+ */
+
+/**
+ * Detect the current project identity from Git.
+ * Returns null if no .git directory is found — caller must handle this.
+ * @param cwd - Working directory to detect from (defaults to process.cwd())
+ */
+declare function detectProject(cwd?: string): ProjectInfo | null;
+/**
+ * Detect project with full diagnostic info.
+ * Returns both the project (if found) and a failure descriptor (if not).
+ * Callers can use failure.reason to produce actionable error messages.
+ */
+declare function detectProjectWithDiagnostics(cwd?: string): DetectionResult;
+
+/**
+ * Memorix SDK — Programmatic API for embedding Memorix into your own projects.
+ *
+ * Usage:
+ *   import { createMemoryClient } from 'memorix/sdk';
+ *
+ *   const client = await createMemoryClient({ projectRoot: '/path/to/repo' });
+ *   await client.store({ entityName: 'auth', type: 'decision', title: '...', narrative: '...' });
+ *   const results = await client.search('auth decisions');
+ *   await client.close();
+ *
+ * For MCP server embedding:
+ *   import { createMemorixServer } from 'memorix/sdk';
+ *
+ *   const { server, projectId } = await createMemorixServer('/path/to/repo');
+ *   // Connect to your own transport
+ */
+
+/** Options for creating a MemoryClient */
+interface MemoryClientOptions {
+    /** Absolute path to a Git project root. Required. */
+    projectRoot: string;
+    /**
+     * If true, suppress console.error diagnostic logs during initialization.
+     * Default: false.
+     */
+    silent?: boolean;
+}
+/** Input for storing an observation */
+interface StoreInput {
+    entityName: string;
+    type: ObservationType;
+    title: string;
+    narrative: string;
+    facts?: string[];
+    filesModified?: string[];
+    concepts?: string[];
+    topicKey?: string;
+    sessionId?: string;
+    progress?: ProgressInfo;
+    source?: 'agent' | 'git' | 'manual';
+    commitHash?: string;
+    relatedCommits?: string[];
+    relatedEntities?: string[];
+    sourceDetail?: 'explicit' | 'hook' | 'git-ingest';
+    valueCategory?: 'core' | 'contextual' | 'ephemeral';
+}
+/** Result from storing an observation */
+interface StoreResult {
+    observation: Observation;
+    upserted: boolean;
+}
+/** Options for searching */
+interface ClientSearchOptions {
+    query: string;
+    /** Filter by observation type */
+    type?: ObservationType;
+    /** Filter by observation source */
+    source?: 'agent' | 'git' | 'manual';
+    /** Filter by status. Default: 'active' */
+    status?: ObservationStatus | 'all';
+    /** Maximum results. Default: 20 */
+    limit?: number;
+}
+/** Result from resolving observations */
+interface ResolveResult {
+    resolved: number[];
+    notFound: number[];
+}
+/**
+ * A lightweight, self-contained memory client for reading and writing
+ * Memorix observations without MCP overhead.
+ *
+ * Each client initializes its own SQLite backend and Orama search index,
+ * scoped to a single project. Call `close()` when done to release resources.
+ */
+declare class MemoryClient {
+    private _projectId;
+    private _projectRoot;
+    private _dataDir;
+    private _closed;
+    private _observations;
+    private _oramaStore;
+    private _obsStore;
+    private _freshness;
+    /** @internal — use createMemoryClient() instead */
+    constructor(projectId: string, projectRoot: string, dataDir: string);
+    /** The canonical project ID (derived from Git remote or local path) */
+    get projectId(): string;
+    /** The project root path */
+    get projectRoot(): string;
+    /** The Memorix data directory for this project */
+    get dataDir(): string;
+    /**
+     * @internal Initialize stores and search index.
+     * Called by createMemoryClient(). Do not call directly.
+     */
+    _init(silent: boolean): Promise<void>;
+    private _ensureOpen;
+    /**
+     * Store a new observation (or upsert if topicKey matches an existing one).
+     *
+     * @example
+     * ```ts
+     * const { observation } = await client.store({
+     *   entityName: 'auth-module',
+     *   type: 'decision',
+     *   title: 'Use JWT for API auth',
+     *   narrative: 'Chose JWT over session cookies for stateless API authentication.',
+     *   facts: ['Token expiry: 1h', 'Refresh token: 7d'],
+     * });
+     * ```
+     */
+    store(input: StoreInput): Promise<StoreResult>;
+    /**
+     * Search observations using full-text and optional vector search.
+     *
+     * @example
+     * ```ts
+     * const results = await client.search({ query: 'authentication decisions' });
+     * for (const r of results) {
+     *   console.log(`${r.title} (score: ${r.score})`);
+     * }
+     * ```
+     */
+    search(options: ClientSearchOptions): Promise<IndexEntry[]>;
+    /**
+     * Get a single observation by ID.
+     */
+    get(id: number): Promise<Observation | undefined>;
+    /**
+     * Get all observations for this project.
+     */
+    getAll(): Promise<Observation[]>;
+    /**
+     * Get the total observation count for this project.
+     */
+    count(): Promise<number>;
+    /**
+     * Mark observations as resolved or archived.
+     *
+     * Resolved observations are hidden from default search but recoverable.
+     * Archived observations are permanently hidden.
+     *
+     * @example
+     * ```ts
+     * await client.resolve([1, 2, 3]);
+     * await client.resolve([4], 'archived');
+     * ```
+     */
+    resolve(ids: number[], status?: ObservationStatus): Promise<ResolveResult>;
+    /**
+     * Release resources (close SQLite handle, reset index).
+     * The client cannot be used after calling close().
+     */
+    close(): Promise<void>;
+}
+/**
+ * Create a new MemoryClient for a project.
+ *
+ * This initializes SQLite, loads observations, and prepares the search index.
+ * Each client is independent — you can have multiple clients for different projects.
+ *
+ * @example
+ * ```ts
+ * import { createMemoryClient } from 'memorix/sdk';
+ *
+ * const client = await createMemoryClient({ projectRoot: '/home/user/my-project' });
+ *
+ * // Store a memory
+ * await client.store({
+ *   entityName: 'api-gateway',
+ *   type: 'gotcha',
+ *   title: 'Rate limiter resets on deploy',
+ *   narrative: 'In-memory rate limiter state is lost on every deploy...',
+ * });
+ *
+ * // Search memories
+ * const results = await client.search({ query: 'rate limiter' });
+ *
+ * // Clean up
+ * await client.close();
+ * ```
+ */
+declare function createMemoryClient(options: MemoryClientOptions): Promise<MemoryClient>;
+
+export { type ClientSearchOptions, type CreateMemorixServerOptions, DetectionResult, Entity, IndexEntry, KnowledgeGraph, MemoryClient, type MemoryClientOptions, Observation, ObservationStatus, ObservationType, ProgressInfo, ProjectInfo, Relation, type ResolveResult, type StoreInput, type StoreResult, createMemorixServer, createMemoryClient, detectProject, detectProjectWithDiagnostics };