Your knowledge. One SQLite file. Accessible to you and your agents.

npm install -g mnemosyne-core
mnemosyne init --data-dir ./data
mnemosyne start --data-dir ./data
# 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 (Model Context Protocol). Agents remember context across conversations.

Naming Guide

| Term | Everyday Meaning | |---|---| | Project | A folder or workspace (e.g. "Work", "Personal") | | Atom | A note, idea, or document | | Block | A paragraph, snippet, or file attachment inside an atom | | Bond | A link or relationship between two atoms |

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:

npm install -g mnemosyne-core
mnemosyne init --data-dir ./data
mnemosyne start --data-dir ./data

Or in your project:

npm install mnemosyne-core
npx mnemosyne init --data-dir ./data
npx mnemosyne start --data-dir ./data

Requirements: Node.js 20+

Agent Setup

Claude Desktop (stdio — no server needed)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "mnemosyne": {
      "command": "npx",
      "args": ["mnemosyne-core", "start", "--data-dir", "./data", "--mcp-transport", "stdio"]
    }
  }
}

Restart Claude Desktop → Settings → MCP → Mnemosyne appears with all tools.

Cursor (SSE — server mode)

mnemosyne start --data-dir ./data --port 7321

Then in Cursor: Settings → MCP → Add server → http://localhost:7321/mcp/manifest

Programmatic (SDK)

import { MnemosyneClient } from 'mnemosyne-core/sdk';

const client = new MnemosyneClient({ baseUrl: 'http://localhost:7321' });

// Create a project
const project = await client.createProject({ name: 'Work Notes' });

// Create an atom (a note)
const atom = await client.createAtom({
  project_id: project.id,
  title: 'Meeting Notes',
  type: 'text',
});

// Search by keyword
const results = await client.searchKeyword('meeting');
console.log(`Found ${results.count} results`);

See WORKING_EXAMPLE.md for a complete runnable walkthrough.

Embedded (your own app)

import { Mnemosyne, ApiRouter, McpServer } from 'mnemosyne-core';

const brain = new Mnemosyne({ dbPath: './data/nexus.db' });

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

CLI Commands

mnemosyne init --data-dir ./data          # Scaffold data/ + config.yaml + DB
mnemosyne start --data-dir ./data         # Start server (API + dashboard + MCP SSE)
mnemosyne start --data-dir ./data --mcp-transport stdio   # Stdio for Claude Desktop
mnemosyne doctor --data-dir ./data        # Diagnostics: deps, config, DB health
mnemosyne migrate --from v1.json --to data/nexus.db       # v1.0 → v2.0
mnemosyne export --project "Work" --format markdown       # Export project

License

MIT