mnemosyne-core 2.0.0

package/README.md

@@ -0,0 +1,176 @@
+<p align="center">
+  <img src="logo.png" width="120" alt="Mnemosyne logo">
+</p>
+
+<h1 align="center">Mnemosyne</h1>
+
+<p align="center">
+  <strong>An open-source exocortex for humans and AI.</strong>
+</p>
+
+Your knowledge. One SQLite file. Accessible to you and your agents.
+
+```bash
+npm install -g mnemosyne-core
+mnemosyne init
+mnemosyne start
+# Open http://localhost:7321/dashboard
+```
+
+---
+
+## What is Mnemosyne?
+
+Mnemosyne is an **exocortex** — an external brain that belongs to you.
+
+**For humans:** A spatial canvas + table view to store ideas, files, and connections. Dark mode. Fast. Local. SQLite-backed.
+
+**For AI agents:** A memory system agents can safely read and write to via [MCP](https://modelcontextprotocol.io/) (Model Context Protocol). Agents remember context across conversations.
+
+---
+
+## Features
+
+| Feature | What it does |
+|---------|-------------|
+| 🕸️ **Graph + Table views** | Spatial canvas and structured database in one |
+| 🔍 **Semantic search** | Find ideas by meaning, not just keywords (sqlite-vec) |
+| 📎 **File intelligence** | Drop PDFs/images, auto-summarized for agents |
+| 🤖 **Agent collaboration** | Claude, Cursor, custom agents via MCP stdio/SSE |
+| 🔒 **Checkout system** | Agents lock atoms while editing, queue when busy |
+| 📝 **Suggestion mode** | Agents propose edits, you approve or reject |
+| ⏳ **Time travel** | Every change is logged. Rewind to any version. |
+| 📤 **Portable** | Your entire brain in one SQLite file: `data/nexus.db` |
+
+---
+
+## Install
+
+**One-line global install:**
+
+```bash
+npm install -g mnemosyne-core
+mnemosyne init
+mnemosyne start
+```
+
+**Or in your project:**
+
+```bash
+npm install mnemosyne-core
+npx mnemosyne init
+npx mnemosyne start
+```
+
+**Requirements:** Node.js 20+
+
+---
+
+## Agent Setup
+
+### Claude Desktop (stdio — no server needed)
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mnemosyne": {
+      "command": "npx",
+      "args": ["mnemosyne-core", "start", "--mcp-transport", "stdio"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop → Settings → MCP → Mnemosyne appears with all tools.
+
+### Cursor (SSE — server mode)
+
+```bash
+mnemosyne start --port 7321
+```
+
+Then in Cursor: Settings → MCP → Add server → `http://localhost:7321/mcp/manifest`
+
+### Programmatic (SDK)
+
+```typescript
+import { MnemosyneClient } from 'mnemosyne-core/sdk';
+
+const client = new MnemosyneClient({ baseUrl: 'http://localhost:7321' });
+const atoms = await client.searchSemantic('server setup', { limit: 5 });
+```
+
+### Embedded (your own app)
+
+```typescript
+import { Mnemosyne, ApiRouter, McpServer } from 'mnemosyne-core';
+
+const brain = new Mnemosyne();
+await brain.init();
+
+const api = new ApiRouter(brain.store);
+const mcp = new McpServer(brain.store);
+
+// Mount in your own HTTP server
+server.on('request', (req, res) => api.handle(req, res));
+```
+
+---
+
+## Architecture
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  Human      │     │   Agent     │     │   Your App  │
+│  Dashboard  │     │  (Claude)   │     │  (Express)  │
+└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
+       │                   │                   │
+       └───────────────────┼───────────────────┘
+                           │
+              ┌────────────┴────────────┐
+              │    mnemosyne-core      │
+              │  ┌─────────────────┐    │
+              │  │  Mnemosyne      │    │
+              │  │  (SQLite + vec) │    │
+              │  └─────────────────┘    │
+              │  ┌─────────────────┐    │
+              │  │  REST API       │    │
+              │  │  MCP (stdio/SSE)│    │
+              │  │  WebSocket      │    │
+              │  └─────────────────┘    │
+              └─────────────────────────┘
+```
+
+- **Storage:** SQLite (better-sqlite3) + WAL mode + FTS5 full-text search + sqlite-vec embeddings
+- **API:** Raw Node.js HTTP (no Express dependency)
+- **MCP:** JSON-RPC 2.0 over stdio (Claude Desktop) or SSE (Cursor/web)
+- **WebSocket:** Real-time atom updates and broadcasts
+
+---
+
+## Documentation
+
+- **[Getting Started](docs/getting-started.md)** — Install, first project, search, export
+- **[Agent Setup](docs/agent-setup.md)** — Claude Desktop, Cursor, SDK, permissions
+- **[API Reference](docs/04-developer-guide/api-reference.md)** — REST endpoints
+- **[Architecture](docs/04-developer-guide/architecture.md)** — Database schema, design decisions
+
+---
+
+## CLI Commands
+
+```bash
+mnemosyne init          # Scaffold data/ directory + config.yaml + SQLite DB
+mnemosyne start         # Start server (API + dashboard + MCP SSE)
+mnemosyne start --mcp-transport stdio   # Stdio mode for Claude Desktop
+mnemosyne migrate --from v1.json --to data/nexus.db   # v1.0 → v2.0
+mnemosyne export --project "Work" --format markdown   # Export project
+```
+
+---
+
+## License
+
+MIT

package/dist/Store-N3j0Vaj6.d.mts

@@ -0,0 +1,320 @@
+import Database from 'better-sqlite3';
+
+type PermissionLevel = "none" | "view" | "suggest" | "edit" | "create" | "admin";
+type Action = "create" | "read" | "write" | "update" | "delete" | "lock" | "manage_queue" | "force_release" | "peek" | "export" | "import" | "suggest";
+type AssistantRole = "owner" | "admin" | "manager" | "lead" | "developer" | "worker" | "reviewer" | "observer" | "bot" | "guest";
+interface Project {
+    id: string;
+    name: string;
+    description: string | null;
+    icon: string;
+    color: string;
+    created_at: number;
+    updated_at: number;
+    owner: string;
+    metadata: Record<string, any>;
+}
+interface Atom {
+    id: string;
+    project_id: string;
+    parent_id: string | null;
+    title: string;
+    summary: string | null;
+    icon: string;
+    color: string | null;
+    x: number | null;
+    y: number | null;
+    created_at: number;
+    updated_at: number;
+    version: number;
+    locked_by: string | null;
+    locked_at: number | null;
+    locked_reason: string | null;
+    owner: string;
+    status: string;
+    metadata: Record<string, any>;
+    auto_path?: string;
+    path_overridden?: boolean;
+    status_updated_at?: number;
+    block_count?: number;
+    bond_count?: number;
+    template_id?: string | null;
+    embedding_status?: string | null;
+}
+interface Block {
+    id: string;
+    atom_id: string;
+    type: string;
+    content: string | null;
+    order_index: number;
+    created_at: number;
+    updated_at: number;
+    metadata: Record<string, any>;
+}
+interface Bond {
+    id: string;
+    source_id: string;
+    target_id: string;
+    label: string;
+    color: string | null;
+    created_at: number;
+}
+interface Assistant {
+    id: string;
+    name: string;
+    role: AssistantRole;
+    permissions: Record<string, any>;
+    status: string;
+    provider: string | null;
+    connected_at: number;
+    last_seen: number;
+    metadata: Record<string, any>;
+}
+interface QueueEntry {
+    id: string;
+    atom_id: string;
+    assistant_id: string;
+    requested_at: number;
+    priority: number;
+    status: string;
+    reason: string | null;
+}
+interface EventLogEntry {
+    id: string;
+    timestamp: number;
+    event_type: string;
+    project_id: string | null;
+    atom_id: string | null;
+    block_id: string | null;
+    bond_id: string | null;
+    actor: string;
+    actor_type: string;
+    diff: string | null;
+    trigger: string | null;
+    metadata: Record<string, any>;
+}
+interface Config {
+    server: {
+        port: number;
+        host: string;
+        version: string;
+    };
+    database: {
+        path: string;
+        wal_mode: boolean;
+        vec_extension_path: string;
+    };
+    storage: {
+        files_dir: string;
+        max_file_size_mb: number;
+        backups_dir: string;
+        backup_interval_hours: number;
+        max_backups: number;
+    };
+    limits: {
+        max_atoms_per_project: number;
+        rate_limit_requests: number;
+        rate_limit_window_ms: number;
+    };
+    embeddings: {
+        model: string;
+        dimension: number;
+        max_text_length: number;
+    };
+    features: {
+        mcp_enabled: boolean;
+        auto_index_enabled: boolean;
+        file_processing_enabled: boolean;
+    };
+    index: {
+        debounce_ms: number;
+    };
+    search: {
+        semantic_weight: number;
+        fts_weight: number;
+    };
+    bonds: {
+        default_type: string;
+    };
+}
+
+/**
+ * Mnemosyne Store Engine
+ * SQLite-backed replacement for the in-memory JSON system.
+ *
+ * Naming:
+ *   Project  (was Memory)   → projects table
+ *   Atom     → atoms table
+ *   Block    → blocks table
+ *   Bond     (new)          → bonds table
+ *   Assistant (was Agent)   → assistants table
+ */
+
+declare class EventEmitter {
+    private listeners;
+    on(event: string, cb: (...args: any[]) => void): void;
+    emit(event: string, ...args: any[]): void;
+}
+declare class Store extends EventEmitter {
+    private db;
+    config: Config;
+    vecEnabled: boolean;
+    private backupInterval;
+    private dbPath;
+    private backupDir;
+    private backupIntervalMs;
+    private maxBackups;
+    constructor(db: Database.Database, config: Config, vecEnabled?: boolean);
+    shutdown(): void;
+    private ensureBackup;
+    private stmt;
+    private tx;
+    private now;
+    private parseMeta;
+    private logEvent;
+    can(role: AssistantRole, action: Action, atomId?: string, assistantId?: string): boolean;
+    private levelAllowsAction;
+    setAtomPermission(atomId: string, assistantId: string, level: PermissionLevel, grantedBy?: string): void;
+    getAtomPermission(atomId: string, assistantId: string): {
+        id: string;
+        atom_id: string;
+        assistant_id: string;
+        level: PermissionLevel;
+        granted_by: string | null;
+        granted_at: number;
+    } | undefined;
+    getAtomPermissions(atomId: string): any[];
+    removeAtomPermission(atomId: string, assistantId: string): boolean;
+    resolvePermission(atomId: string, assistantId: string): PermissionLevel;
+    createProject(name: string, description?: string): Project;
+    getProject(id: string): Project | undefined;
+    getProjectByName(name: string): Project | undefined;
+    getProjects(): Project[];
+    createAtom(projectId: string, title: string, type: string, createdBy: string, opts?: {
+        parentId?: string;
+        summary?: string;
+        tags?: string[];
+        path_overridden?: boolean;
+        auto_path?: string;
+        template?: string;
+        status?: string;
+    }): Atom;
+    getAtom(id: string): Atom | undefined;
+    getAtomsByProject(projectId: string): Atom[];
+    getAtomChildren(atomId: string): Atom[];
+    updateAtomParent(id: string, parentId: string | null, updatedBy: string): Atom | null;
+    updateAtom(id: string, fields: {
+        title?: string;
+        summary?: string;
+        tags?: string[];
+        status?: string;
+        auto_path?: string;
+        path_overridden?: boolean;
+    }, updatedBy: string): Atom | null;
+    deleteAtom(id: string, deletedBy: string): boolean;
+    createBlock(atomId: string, type: string, content: string, createdBy: string, opts?: {
+        order?: number;
+        tags?: string[];
+    }): Block;
+    getBlock(id: string): Block | undefined;
+    getBlocksByAtom(atomId: string): Block[];
+    updateBlock(id: string, content: string, updatedBy: string): Block | null;
+    deleteBlock(id: string, deletedBy: string): boolean;
+    createBond(sourceId: string, targetId: string, label: string, color?: string): Bond;
+    getBond(id: string): Bond | undefined;
+    getBondsByAtom(atomId: string): {
+        outgoing: Bond[];
+        incoming: Bond[];
+    };
+    updateBond(id: string, fields: {
+        label?: string;
+        color?: string;
+    }): Bond | null;
+    deleteBond(id: string): boolean;
+    checkout(atomId: string, assistantId: string, mode: "exclusive" | "shared", reason: string): {
+        success: boolean;
+        queuePosition?: number;
+    };
+    releaseCheckout(atomId: string, assistantId: string): boolean;
+    forceRelease(atomId: string, _by: string): boolean;
+    getQueueStatus(atomId: string): {
+        atomId: string;
+        queue: QueueEntry[];
+    } | undefined;
+    grantQueueItem(atomId: string, queueEntryId: string): boolean;
+    rejectQueueItem(atomId: string, queueEntryId: string): boolean;
+    bumpQueueItem(atomId: string, queueEntryId: string): boolean;
+    registerAssistant(a: {
+        id?: string;
+        name: string;
+        role: AssistantRole;
+        capabilities?: string[];
+        description?: string;
+        provider?: string;
+        instructions?: string;
+        config?: Record<string, any>;
+    }): Assistant;
+    updateAssistant(id: string, fields: {
+        name?: string;
+        role?: AssistantRole;
+        description?: string;
+        provider?: string;
+        instructions?: string;
+        config?: Record<string, any>;
+        capabilities?: string[];
+        status?: string;
+    }): Assistant | null;
+    deleteAssistant(id: string): boolean;
+    getAssistant(id: string): Assistant | undefined;
+    getAllAssistants(): Assistant[];
+    heartbeat(id: string): void;
+    search(projectId: string, q: string, limit: number): any[];
+    embedAtom(atomId: string): Promise<void>;
+    searchSemantic(projectId: string, queryEmbedding: number[], limit: number): any[];
+    searchHybrid(projectId: string, q: string, queryEmbedding: number[], limit: number): any[];
+    private embedQueue;
+    scheduleEmbed(atomId: string, priority?: 2): void;
+    importMnemosyneZip(zipBuffer: Buffer, importedBy: string): {
+        success: boolean;
+        atomsRestored: number;
+        error?: string;
+    };
+    importMarkdown(mdText: string, projectId: string, createdBy: string, opts?: {
+        title?: string;
+    }): {
+        success: boolean;
+        atomId?: string;
+        bondsCreated?: number;
+        error?: string;
+    };
+    private cascadePathChange;
+    private indexTimers;
+    private indexAtomTimers;
+    scheduleProjectIndexUpdate(projectId: string): void;
+    scheduleProjectIndexAtomUpdate(projectId: string): void;
+    regenerateProjectIndex(projectId: string): void;
+    getProjectIndexAtom(projectId: string): Atom | undefined;
+    private getOrCreateProjectIndexAtom;
+    regenerateProjectIndexAtom(projectId: string): void;
+    getGraph(projectId: string): {
+        atoms: Atom[];
+        bonds: Bond[];
+    };
+    createAttachment(fileHash: string, fileName: string, fileSize: number, mimeType: string): any;
+    getAttachmentByHash(fileHash: string): any | undefined;
+    processFileBlock(atomId: string, blockContent: string): Promise<void>;
+    getAtomHistory(atomId: string): any[];
+    exportSnapshot(): any;
+    importSnapshot(snapshot: any, importedBy: string): void;
+    getEvents(since: number, projectId?: string, limit?: number): EventLogEntry[];
+    getEventsByAtom(atomId: string, limit?: number): EventLogEntry[];
+    getStats(): {
+        projects: number;
+        atoms: number;
+        blocks: number;
+        bonds: number;
+        assistants: number;
+    };
+}
+
+export { type Atom as A, type Config as C, type Project as P, Store as S };