@mycontxt/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,720 @@
+/**
+ * Core type definitions for MemoCore
+ */
+/**
+ * Memory entry types
+ */
+type MemoryEntryType = 'decision' | 'pattern' | 'context' | 'document' | 'session';
+/**
+ * Memory entry status
+ */
+type MemoryEntryStatus = 'active' | 'draft' | 'archived' | 'stale';
+/**
+ * User tier levels
+ */
+type UserTier = 'free' | 'pro';
+/**
+ * Core memory entry
+ */
+interface MemoryEntry {
+    id: string;
+    projectId: string;
+    type: MemoryEntryType;
+    title: string;
+    content: string;
+    metadata: Record<string, any>;
+    embedding?: number[];
+    branch: string;
+    version: number;
+    status: MemoryEntryStatus;
+    isSynced: boolean;
+    isArchived: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Project configuration
+ */
+interface Project {
+    id: string;
+    userId?: string;
+    name: string;
+    path: string;
+    stack?: string[];
+    config: ProjectConfig;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Project configuration options
+ */
+interface ProjectConfig {
+    defaultBranch: string;
+    maxTokens: number;
+    autoSession: boolean;
+    stackDetection: boolean;
+}
+/**
+ * Branch information
+ */
+interface Branch {
+    id: string;
+    projectId: string;
+    name: string;
+    parentBranch?: string;
+    isActive: boolean;
+    createdAt: Date;
+}
+/**
+ * User profile
+ */
+interface UserProfile {
+    id: string;
+    email?: string;
+    tier: UserTier;
+    createdAt: Date;
+}
+/**
+ * Authentication session
+ */
+interface AuthSession {
+    userId: string;
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: Date;
+}
+/**
+ * Sync operation result
+ */
+interface SyncResult {
+    pushed: number;
+    pulled: number;
+    conflicts: number;
+    errors: string[];
+}
+/**
+ * Entry query filters
+ */
+interface EntryQuery {
+    projectId: string;
+    type?: MemoryEntryType;
+    branch?: string;
+    isArchived?: boolean;
+    search?: string;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Input for creating a new entry
+ */
+interface CreateEntryInput {
+    id?: string;
+    projectId: string;
+    type: MemoryEntryType;
+    title: string;
+    content: string;
+    metadata?: Record<string, any>;
+    branch?: string;
+    status?: MemoryEntryStatus;
+}
+/**
+ * Decision-specific input
+ */
+interface DecisionInput {
+    title: string;
+    rationale: string;
+    alternatives?: string[];
+    consequences?: string[];
+    tags?: string[];
+}
+/**
+ * Pattern-specific input
+ */
+interface PatternInput {
+    title: string;
+    content: string;
+    category?: string;
+    tags?: string[];
+}
+/**
+ * Context-specific input
+ */
+interface ContextInput {
+    feature?: string;
+    blockers?: string[];
+    nextSteps?: string[];
+    activeFiles?: string[];
+}
+/**
+ * Document-specific input
+ */
+interface DocumentInput {
+    title: string;
+    content: string;
+    url?: string;
+    tags?: string[];
+}
+/**
+ * Session-specific input
+ */
+interface SessionInput {
+    feature: string;
+    description?: string;
+}
+/**
+ * Ranked entry for context retrieval
+ */
+interface RankedEntry {
+    entry: MemoryEntry;
+    score: number;
+    reasons: string[];
+}
+/**
+ * Context retrieval options
+ */
+interface SuggestOptions {
+    projectId: string;
+    taskDescription?: string;
+    taskEmbedding?: number[];
+    activeFiles?: string[];
+    branch?: string;
+    maxResults?: number;
+    maxTokens?: number;
+    minRelevance?: number;
+}
+/**
+ * Activity item for the dashboard activity feed.
+ * Derived from memory_entries changes — no separate table needed.
+ */
+interface ActivityItem {
+    id: string;
+    projectId: string;
+    projectName: string;
+    entryId?: string;
+    type: 'push' | 'session' | 'branch' | 'draft' | 'edit' | 'archive';
+    description: string;
+    actor: 'user' | 'auto';
+    createdAt: Date;
+}
+/**
+ * Usage statistics for the sidebar usage meters.
+ */
+interface UsageStats {
+    entries: {
+        used: number;
+        limit: number;
+    };
+    projects: {
+        used: number;
+        limit: number | null;
+    };
+    searches: {
+        used: number;
+        limit: number;
+    };
+}
+/**
+ * Validation error
+ */
+declare class ValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Not found error
+ */
+declare class NotFoundError extends Error {
+    constructor(message: string);
+}
+/**
+ * Conflict error
+ */
+declare class ConflictError extends Error {
+    constructor(message: string);
+}
+/**
+ * Authentication error
+ */
+declare class AuthError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Database interface definitions
+ * These interfaces define the contract between business logic and storage adapters
+ */
+
+/**
+ * Local database interface (SQLite)
+ * This is the source of truth for offline-first architecture
+ */
+interface ILocalDatabase {
+    /**
+     * Initialize the database schema
+     */
+    initialize(): Promise<void>;
+    /**
+     * Close the database connection
+     */
+    close(): Promise<void>;
+    /**
+     * Create or initialize a project
+     */
+    initProject(config: {
+        name: string;
+        path: string;
+        stack?: string[];
+        config?: Partial<ProjectConfig>;
+    }): Promise<Project>;
+    /**
+     * Get a project by ID
+     */
+    getProject(projectId: string): Promise<Project | null>;
+    /**
+     * Get project by path
+     */
+    getProjectByPath(path: string): Promise<Project | null>;
+    /**
+     * Update project configuration
+     */
+    updateProject(projectId: string, updates: Partial<Omit<Project, 'id' | 'createdAt'>>): Promise<Project>;
+    /**
+     * Create a new memory entry
+     */
+    createEntry(input: CreateEntryInput): Promise<MemoryEntry>;
+    /**
+     * Get a single entry by ID
+     */
+    getEntry(id: string): Promise<MemoryEntry | null>;
+    /**
+     * Update an existing entry
+     */
+    updateEntry(id: string, updates: Partial<Omit<MemoryEntry, 'id' | 'projectId' | 'createdAt'>>): Promise<MemoryEntry>;
+    /**
+     * Delete an entry (soft delete by default)
+     */
+    deleteEntry(id: string, hard?: boolean): Promise<void>;
+    /**
+     * List entries with optional filters
+     */
+    listEntries(query: EntryQuery): Promise<MemoryEntry[]>;
+    /**
+     * Count entries matching query
+     */
+    countEntries(query: Omit<EntryQuery, 'limit' | 'offset'>): Promise<number>;
+    /**
+     * Search entries (full-text search)
+     */
+    searchEntries(projectId: string, searchTerm: string, options?: {
+        branch?: string;
+        type?: string;
+        limit?: number;
+    }): Promise<MemoryEntry[]>;
+    /**
+     * Get all unsynced entries for a project
+     */
+    getUnsyncedEntries(projectId: string): Promise<MemoryEntry[]>;
+    /**
+     * Mark entries as synced
+     */
+    markSynced(ids: string[]): Promise<void>;
+    /**
+     * Get entries updated since a timestamp
+     */
+    getEntriesUpdatedSince(projectId: string, timestamp: Date): Promise<MemoryEntry[]>;
+    /**
+     * Update last pull timestamp
+     */
+    updateLastPull(projectId: string, timestamp: Date): Promise<void>;
+    /**
+     * Get last pull timestamp
+     */
+    getLastPull(projectId: string): Promise<Date | null>;
+    /**
+     * Create a new branch
+     */
+    createBranch(projectId: string, name: string, fromBranch: string): Promise<Branch>;
+    /**
+     * Get a branch by name
+     */
+    getBranch(projectId: string, name: string): Promise<Branch | null>;
+    /**
+     * List all branches for a project
+     */
+    listBranches(projectId: string): Promise<Branch[]>;
+    /**
+     * Delete a branch
+     */
+    deleteBranch(projectId: string, name: string): Promise<void>;
+    /**
+     * Get current active branch
+     */
+    getActiveBranch(projectId: string): Promise<string>;
+    /**
+     * Switch to a different branch
+     */
+    switchBranch(projectId: string, branchName: string): Promise<void>;
+    /**
+     * Create a version snapshot of an entry
+     */
+    createVersion(entryId: string, snapshot: MemoryEntry): Promise<void>;
+    /**
+     * Get version history for an entry
+     */
+    getVersionHistory(entryId: string): Promise<MemoryEntry[]>;
+    /**
+     * Restore an entry to a specific version
+     */
+    restoreVersion(entryId: string, version: number): Promise<MemoryEntry>;
+}
+/**
+ * Remote database interface (Supabase/Cloud)
+ * Mirrors ILocalDatabase but for cloud operations
+ */
+interface IRemoteDatabase {
+    /**
+     * Initialize connection to remote database
+     */
+    initialize(): Promise<void>;
+    /**
+     * Close connection
+     */
+    close(): Promise<void>;
+    /**
+     * Sync project to remote
+     */
+    upsertProject(project: Project): Promise<Project>;
+    /**
+     * Get project from remote
+     */
+    getProject(projectId: string): Promise<Project | null>;
+    /**
+     * Push entries to remote
+     */
+    pushEntries(entries: MemoryEntry[]): Promise<void>;
+    /**
+     * Pull entries from remote updated since timestamp
+     */
+    pullEntries(projectId: string, since: Date): Promise<MemoryEntry[]>;
+    /**
+     * Get all entries for a project
+     */
+    listEntries(query: EntryQuery): Promise<MemoryEntry[]>;
+    /**
+     * Perform semantic search using embeddings
+     */
+    semanticSearch(projectId: string, queryEmbedding: number[], options?: {
+        branch?: string;
+        limit?: number;
+        minSimilarity?: number;
+    }): Promise<MemoryEntry[]>;
+    /**
+     * Sync branch to remote
+     */
+    upsertBranch(branch: Branch): Promise<Branch>;
+    /**
+     * Get branches from remote
+     */
+    listBranches(projectId: string): Promise<Branch[]>;
+}
+
+/**
+ * Authentication provider interface
+ */
+
+interface IAuthProvider {
+    /**
+     * Initialize authentication provider
+     */
+    initialize(): Promise<void>;
+    /**
+     * Login with browser OAuth flow
+     */
+    login(): Promise<AuthSession>;
+    /**
+     * Logout and clear session
+     */
+    logout(): Promise<void>;
+    /**
+     * Get current session
+     */
+    getSession(): Promise<AuthSession | null>;
+    /**
+     * Refresh access token
+     */
+    refreshSession(refreshToken: string): Promise<AuthSession>;
+    /**
+     * Get user profile
+     */
+    getUserProfile(userId: string): Promise<UserProfile | null>;
+    /**
+     * Check if user is authenticated
+     */
+    isAuthenticated(): Promise<boolean>;
+}
+
+/**
+ * Embeddings provider interface
+ */
+interface IEmbeddingProvider {
+    /**
+     * Initialize embeddings provider
+     */
+    initialize(): Promise<void>;
+    /**
+     * Generate embedding for a single text
+     */
+    generateEmbedding(text: string): Promise<number[]>;
+    /**
+     * Generate embeddings for multiple texts (batch)
+     */
+    generateEmbeddings(texts: string[]): Promise<number[][]>;
+    /**
+     * Calculate cosine similarity between two embeddings
+     */
+    cosineSimilarity(embedding1: number[], embedding2: number[]): number;
+}
+
+/**
+ * Memory Engine - Core business logic for memory management
+ */
+
+declare class MemoryEngine {
+    private db;
+    constructor(db: ILocalDatabase);
+    addDecision(projectId: string, input: DecisionInput): Promise<MemoryEntry>;
+    listDecisions(projectId: string, branch?: string): Promise<MemoryEntry[]>;
+    getDecision(id: string): Promise<MemoryEntry>;
+    updateDecision(id: string, updates: Partial<DecisionInput>): Promise<MemoryEntry>;
+    addPattern(projectId: string, input: PatternInput): Promise<MemoryEntry>;
+    listPatterns(projectId: string, branch?: string): Promise<MemoryEntry[]>;
+    getPattern(id: string): Promise<MemoryEntry>;
+    updatePattern(id: string, updates: Partial<PatternInput>): Promise<MemoryEntry>;
+    setContext(projectId: string, input: ContextInput): Promise<MemoryEntry>;
+    getContext(projectId: string): Promise<MemoryEntry | null>;
+    addDocument(projectId: string, input: DocumentInput): Promise<MemoryEntry>;
+    listDocuments(projectId: string, branch?: string): Promise<MemoryEntry[]>;
+    getDocument(id: string): Promise<MemoryEntry>;
+    startSession(projectId: string, input: SessionInput): Promise<MemoryEntry>;
+    endSession(projectId: string, summary?: string): Promise<MemoryEntry>;
+    getActiveSession(projectId: string): Promise<MemoryEntry | null>;
+    listSessions(projectId: string, branch?: string): Promise<MemoryEntry[]>;
+    deleteEntry(id: string, hard?: boolean): Promise<void>;
+    searchEntries(projectId: string, searchTerm: string, options?: {
+        branch?: string;
+        type?: string;
+    }): Promise<MemoryEntry[]>;
+    getAllEntries(query: EntryQuery): Promise<MemoryEntry[]>;
+    getEntryCount(projectId: string, branch?: string): Promise<number>;
+}
+
+/**
+ * Relevance Engine - Smart context retrieval scoring
+ */
+
+/**
+ * Calculate relevance score for a memory entry
+ *
+ * Scoring breakdown (when no embeddings available):
+ * - Keyword overlap: 40%
+ * - Recency: 25%
+ * - Type priority: 20%
+ * - File match: 15%
+ *
+ * Total: 1.0 (100%)
+ */
+declare function calculateRelevance(entry: MemoryEntry, options: SuggestOptions): number;
+/**
+ * Generate match reasons for transparency
+ */
+declare function getMatchReasons(entry: MemoryEntry, options: SuggestOptions): string[];
+/**
+ * Rank and filter entries by relevance
+ */
+declare function rankEntries(entries: MemoryEntry[], options: SuggestOptions): RankedEntry[];
+
+/**
+ * Sync Engine - Handles push/pull synchronization
+ * Coordinates between local and remote databases
+ */
+
+interface SyncOptions {
+    /**
+     * Force push even if conflicts exist (last-write-wins)
+     */
+    force?: boolean;
+    /**
+     * Dry run - don't actually sync, just report what would happen
+     */
+    dryRun?: boolean;
+}
+declare class SyncEngine {
+    private local;
+    private remote;
+    constructor(local: ILocalDatabase, remote: IRemoteDatabase);
+    /**
+     * Push local changes to remote
+     */
+    push(projectId: string, options?: SyncOptions): Promise<SyncResult>;
+    /**
+     * Pull remote changes to local
+     */
+    pull(projectId: string, options?: SyncOptions): Promise<SyncResult>;
+    /**
+     * Full bidirectional sync (pull then push)
+     */
+    sync(projectId: string, options?: SyncOptions): Promise<SyncResult>;
+}
+
+/**
+ * Context Builder Engine
+ * Intelligently assembles project context for AI agents
+ */
+
+interface ContextMode {
+    type: 'task' | 'files' | 'all';
+    taskDescription?: string;
+    activeFiles?: string[];
+    includeTypes?: string[];
+}
+interface ContextBuilderOptions extends ContextMode {
+    projectId: string;
+    maxTokens?: number;
+    minRelevance?: number;
+}
+interface ContextResult {
+    context: string;
+    entriesIncluded: number;
+    tokensUsed: number;
+    budget: number;
+}
+/**
+ * Build intelligent context payload for AI agents
+ */
+declare function buildContextPayload(entries: MemoryEntry[], options: ContextBuilderOptions): ContextResult;
+/**
+ * Build a summary of what context is available
+ */
+declare function buildContextSummary(entries: MemoryEntry[]): {
+    totalEntries: number;
+    byType: Record<string, number>;
+    recentActivity: string[];
+    oldestEntry: Date | null;
+    newestEntry: Date | null;
+};
+
+/**
+ * Token counting utilities using tiktoken
+ */
+
+/**
+ * Count tokens in a text string
+ */
+declare function countTokens(text: string): number;
+/**
+ * Count tokens in a memory entry
+ */
+declare function countEntryTokens(entry: MemoryEntry): number;
+/**
+ * Format entry for context (how it will appear in the prompt)
+ */
+declare function formatEntryForContext(entry: MemoryEntry): string;
+/**
+ * Fit ranked entries within a token budget
+ */
+declare function fitToBudget(rankedEntries: RankedEntry[], maxTokens: number): RankedEntry[];
+/**
+ * Build formatted context from ranked entries
+ */
+declare function buildContext(rankedEntries: RankedEntry[], options?: {
+    includeReasons?: boolean;
+    includeStats?: boolean;
+}): string;
+/**
+ * Free tiktoken resources (call on cleanup)
+ */
+declare function cleanup(): void;
+
+/**
+ * Code Comment Scanner
+ * Extracts @decision, @pattern, and @context tags from code comments
+ */
+
+interface ScanComment {
+    tag: 'decision' | 'pattern' | 'context';
+    category?: string;
+    title: string;
+    content: string;
+    fields: Record<string, string>;
+    file: string;
+    line: number;
+    hash: string;
+}
+interface ScanResult {
+    found: ScanComment[];
+    errors: Array<{
+        file: string;
+        line: number;
+        error: string;
+    }>;
+}
+/**
+ * Parse a single file for tagged comments
+ */
+declare function parseFile(content: string, filePath: string): ScanComment[];
+/**
+ * Convert scan comment to memory entry type
+ */
+declare function scanCommentToEntry(comment: ScanComment, projectId: string): {
+    type: MemoryEntryType;
+    title: string;
+    content: string;
+    metadata: Record<string, any>;
+};
+
+/**
+ * Rules File Parser
+ * Parses .contxt/rules.md file into structured memory entries
+ */
+
+interface RulesEntry {
+    type: MemoryEntryType;
+    title: string;
+    content: string;
+    metadata: Record<string, any>;
+}
+interface ParsedRules {
+    stack: string[];
+    decisions: RulesEntry[];
+    patterns: RulesEntry[];
+    context: RulesEntry | null;
+    documents: RulesEntry[];
+}
+/**
+ * Parse rules.md file into structured entries
+ */
+declare function parseRulesFile(content: string): ParsedRules;
+/**
+ * Generate rules.md file from memory entries
+ */
+declare function generateRulesFile(entries: {
+    stack: string[];
+    decisions: Array<{
+        title: string;
+        content: string;
+        metadata: any;
+    }>;
+    patterns: Array<{
+        title: string;
+        content: string;
+        metadata: any;
+    }>;
+    context: Array<{
+        content: string;
+    }>;
+    documents: Array<{
+        title: string;
+        content: string;
+    }>;
+}): string;
+
+export { type ActivityItem, AuthError, type AuthSession, type Branch, ConflictError, type ContextBuilderOptions, type ContextInput, type ContextMode, type ContextResult, type CreateEntryInput, type DecisionInput, type DocumentInput, type EntryQuery, type IAuthProvider, type IEmbeddingProvider, type ILocalDatabase, type IRemoteDatabase, MemoryEngine, type MemoryEntry, type MemoryEntryStatus, type MemoryEntryType, NotFoundError, type ParsedRules, type PatternInput, type Project, type ProjectConfig, type RankedEntry, type RulesEntry, type ScanComment, type ScanResult, type SessionInput, type SuggestOptions, SyncEngine, type SyncOptions, type SyncResult, type UsageStats, type UserProfile, type UserTier, ValidationError, buildContext, buildContextPayload, buildContextSummary, calculateRelevance, cleanup, countEntryTokens, countTokens, fitToBudget, formatEntryForContext, generateRulesFile, getMatchReasons, parseFile, parseRulesFile, rankEntries, scanCommentToEntry };