@raviolelabs/engram-mcp 0.2.3 → 0.4.3

package/dist/server/api/types.d.ts

@@ -1,3 +1,8 @@
 import { Router } from 'express';
 export declare function typesApi(): Router;
+/**
+ * Helper exported for `recall` and `list` callers — returns the set of type ids
+ * the user wants HIDDEN from default queries.
+ */
+export declare function getDisabledTypes(): Set<string>;
 //# sourceMappingURL=types.d.ts.map

package/dist/server/api/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/server/api/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAIjC,wBAAgB,QAAQ,IAAI,MAAM,CAcjC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/server/api/types.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAA+B,MAAM,SAAS,CAAC;AAgD9D,wBAAgB,QAAQ,IAAI,MAAM,CA6DjC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,GAAG,CAAC,MAAM,CAAC,CAE9C"}

package/dist/server/api/types.js

@@ -1,20 +1,108 @@
 // src/webapp/api/types.ts
 import { Router } from 'express';
+import { z } from 'zod';
 import { moduleRegistry } from '../../memory/core/module-registry.js';
 import { listCustomTypes } from '../../memory/modules/_custom/persistence.js';
+import { getDb } from '../../db/index.js';
+// ── Disabled types persistence (uses the existing `settings` table) ──────────
+//
+// Key: 'disabled_types' → JSON array of type names that are hidden from default
+// recall/list operations. Disabling a type does NOT delete its memories — they
+// stay in the store, just grayed out in the visualization and excluded from
+// `recall()` calls unless `include_disabled=true` is passed.
+const DISABLED_TYPES_KEY = 'disabled_types';
+function loadDisabledTypes() {
+    const row = getDb()
+        .prepare('SELECT value_json FROM settings WHERE key = ?')
+        .get(DISABLED_TYPES_KEY);
+    if (!row)
+        return new Set();
+    try {
+        const parsed = JSON.parse(row.value_json);
+        if (Array.isArray(parsed))
+            return new Set(parsed.filter((x) => typeof x === 'string'));
+    }
+    catch {
+        /* fall through */
+    }
+    return new Set();
+}
+function saveDisabledTypes(disabled) {
+    getDb()
+        .prepare('INSERT OR REPLACE INTO settings (key, value_json, updated_at) VALUES (?, ?, ?)')
+        .run(DISABLED_TYPES_KEY, JSON.stringify([...disabled]), Date.now());
+}
+function countMemoriesByType() {
+    const rows = getDb()
+        .prepare('SELECT type, COUNT(*) as cnt FROM memories GROUP BY type')
+        .all();
+    const out = {};
+    for (const r of rows)
+        out[r.type] = r.cnt;
+    return out;
+}
+const PatchTypeBody = z.object({ disabled: z.boolean() });
 export function typesApi() {
     const r = Router();
+    // GET /api/types — list every known type with counts + disabled flag
     r.get('/', (_req, res) => {
-        const builtins = moduleRegistry.list()
+        const disabled = loadDisabledTypes();
+        const counts = countMemoriesByType();
+        const builtins = moduleRegistry
+            .list()
             .filter((m) => !m.isCustom)
-            .map((m) => ({ id: m.id, display_name: m.displayName, is_custom: false }));
+            .map((m) => ({
+            id: m.id,
+            display_name: m.displayName,
+            is_custom: false,
+            count: counts[m.id] ?? 0,
+            disabled: disabled.has(m.id),
+        }));
         const customs = listCustomTypes().map((d) => ({
             id: d.type_name,
             display_name: d.display_name,
             is_custom: true,
+            count: counts[d.type_name] ?? 0,
+            disabled: disabled.has(d.type_name),
         }));
         res.json([...builtins, ...customs]);
     });
+    // GET /api/types/disabled — convenience: just the list of disabled type ids
+    r.get('/disabled', (_req, res) => {
+        res.json({ disabled: [...loadDisabledTypes()] });
+    });
+    // PATCH /api/types/:typeName  body: { disabled: boolean }
+    //   Toggle a type's visibility in the dashboard / brain viz.
+    //   No memories are deleted — the toggle is purely a UI/recall filter.
+    r.patch('/:typeName', (req, res) => {
+        const parsed = PatchTypeBody.safeParse(req.body);
+        if (!parsed.success) {
+            res.status(400).json({ error: 'invalid_body', issues: parsed.error.issues });
+            return;
+        }
+        const typeNameParam = req.params.typeName;
+        const typeName = Array.isArray(typeNameParam) ? typeNameParam[0] : typeNameParam;
+        if (!typeName || typeof typeName !== 'string') {
+            res.status(400).json({ error: 'type_name_required' });
+            return;
+        }
+        const disabled = loadDisabledTypes();
+        if (parsed.data.disabled) {
+            disabled.add(typeName);
+        }
+        else {
+            disabled.delete(typeName);
+        }
+        saveDisabledTypes(disabled);
+        res.json({ id: typeName, disabled: parsed.data.disabled });
+    });
     return r;
 }
+/**
+ * Helper exported for `recall` and `list` callers — returns the set of type ids
+ * the user wants HIDDEN from default queries.
+ */
+export function getDisabledTypes() {
+    return loadDisabledTypes();
+}
 //# sourceMappingURL=types.js.map

package/dist/server/api/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/server/api/types.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAE9E,MAAM,UAAU,QAAQ;IACtB,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC;IACnB,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;QACvB,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,EAAE;aACnC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;aAC1B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC,WAAW,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QAC7E,MAAM,OAAO,GAAG,eAAe,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC5C,EAAE,EAAE,CAAC,CAAC,SAAS;YACf,YAAY,EAAE,CAAC,CAAC,YAAY;YAC5B,SAAS,EAAE,IAAI;SAChB,CAAC,CAAC,CAAC;QACJ,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,QAAQ,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,CAAC;AACX,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/server/api/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@raviolelabs/engram-mcp",
-  "version": "0.2.3",
-  "description": "EngramMCP — local-first semantic memory layer for AI agents",
+  "version": "0.4.3",
+  "mcpName": "io.github.RavioleLabs/engram-mcp",
+  "description": "EngramMCP \u2014 local-first semantic memory layer for AI agents",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -34,52 +35,52 @@
     "@lancedb/lancedb": "0.27.1",
     "@modelcontextprotocol/sdk": "1.28.0",
     "@notionhq/client": "2.3.0",
-    "@tanstack/react-query": "^5.50.0",
-    "@types/multer": "^2.1.0",
-    "better-sqlite3": "^12.8.0",
-    "cytoscape": "^3.33.3",
-    "cytoscape-fcose": "^2.2.0",
-    "express": "^5.0.0",
-    "fast-xml-parser": "^5.8.0",
+    "@tanstack/react-query": "5.59.0",
+    "@types/multer": "2.1.0",
+    "better-sqlite3": "12.8.0",
+    "cytoscape": "3.33.3",
+    "cytoscape-fcose": "2.2.0",
+    "express": "5.0.0",
+    "fast-xml-parser": "5.8.0",
     "googleapis": "144.0.0",
-    "libsodium-wrappers": "^0.8.4",
-    "multer": "^2.1.1",
+    "libsodium-wrappers": "0.8.4",
+    "multer": "2.1.1",
     "node-cron": "3.0.3",
-    "nodejs-whisper": "^0.2.4",
-    "pdf-parse": "^2.4.5",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "react-router-dom": "^7.0.0",
-    "secrets.js-grempe": "^2.0.0",
+    "nodejs-whisper": "0.2.4",
+    "pdf-parse": "2.4.5",
+    "react": "19.0.0",
+    "react-dom": "19.0.0",
+    "react-router-dom": "7.0.0",
+    "secrets.js-grempe": "2.0.0",
     "ulid": "2.4.0",
-    "ws": "^8.18.0",
+    "ws": "8.18.0",
     "zod": "3.25.76"
   },
   "devDependencies": {
-    "@tailwindcss/postcss": "^4.3.0",
-    "@types/better-sqlite3": "^7.6.13",
-    "@types/cytoscape": "^3.21.9",
-    "@types/express": "^5.0.0",
-    "@types/libsodium-wrappers": "^0.7.14",
-    "@types/node": "^22.0.0",
+    "@tailwindcss/postcss": "4.3.0",
+    "@types/better-sqlite3": "7.6.13",
+    "@types/cytoscape": "3.21.9",
+    "@types/express": "5.0.0",
+    "@types/libsodium-wrappers": "0.7.14",
+    "@types/node": "22.0.0",
     "@types/node-cron": "3.0.11",
-    "@types/pdf-parse": "^1.1.5",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "@types/ws": "^8.5.0",
-    "@typescript-eslint/eslint-plugin": "^8.59.3",
-    "@typescript-eslint/parser": "^8.59.3",
-    "@vitejs/plugin-react": "^4.3.0",
-    "@yao-pkg/pkg": "^5.12.0",
-    "autoprefixer": "^10.4.0",
-    "eslint": "^9.0.0",
-    "postcss": "^8.4.0",
-    "prettier": "^3.0.0",
-    "tailwindcss": "^4.0.0",
-    "tsx": "^4.0.0",
-    "typescript": "^5.7.0",
-    "vite": "^5.4.0",
-    "vitest": "^2.0.0"
+    "@types/pdf-parse": "1.1.5",
+    "@types/react": "19.0.0",
+    "@types/react-dom": "19.0.0",
+    "@types/ws": "8.5.0",
+    "@typescript-eslint/eslint-plugin": "8.59.3",
+    "@typescript-eslint/parser": "8.59.3",
+    "@vitejs/plugin-react": "4.3.0",
+    "@yao-pkg/pkg": "5.12.0",
+    "autoprefixer": "10.4.0",
+    "eslint": "9.0.0",
+    "postcss": "8.4.0",
+    "prettier": "3.0.0",
+    "tailwindcss": "4.0.0",
+    "tsx": "4.0.0",
+    "typescript": "5.7.3",
+    "vite": "5.4.0",
+    "vitest": "2.0.0"
   },
   "engines": {
     "node": ">=22"

package/CLAUDE.md

@@ -1,232 +0,0 @@
-# EngramMCP
-
-> Local-first semantic memory layer for AI agents.
-
-EngramMCP exposes a Model Context Protocol (MCP) server that lets any AI agent (Claude Code, Cursor, custom Claude/GPT runtimes) capture, search, and enrich memory across multiple typed sources (notes, conversations, Drive, Notion, YouTube, Obsidian, audio, plus user-defined custom types).
-
-Forked from Argos. Local-first: vectors + content live on the user's machine; embeddings via local Ollama by default; no cloud required for Phase 1.
-
----
-
-## Instructions for Claude Code
-
-Tu es le stagiaire technique d'EngramMCP. Sois **proactif**, **force de proposition**, et **autonome**.
-
-### Comportement attendu
-
-- **Lis le code existant** avant de modifier — comprends le pattern en place
-- **Respecte les conventions** (voir ci-dessous)
-- **Pense modularité** — chaque memory type est un MemoryModule indépendant
-- **Sois concis** — pas de blabla, va droit au but, montre le code
-- **Challenge les décisions** sous-optimales avec arguments
-- **No mocks** pour les intégrations externes — tests E2E avec Ollama/LanceDB/SQLite/API réels
-
-### Quand tu travailles sur EngramMCP
-
-1. Lis toujours le code existant avant de modifier
-2. Respecte la convention ES modules avec extensions `.js` dans les imports
-3. Property extraction est **off par défaut** — l'agent appelant (toi) fournit `title`/`tags` directement
-4. Vector store dimension est hardcoded à 768 (nomic-embed-text). Voyage (1024)/OpenAI (1536) requiert un fix dans `src/vector/store.ts`
-5. Tool descriptions doivent être agent-friendly (mention WHEN to call, WHAT inputs help retrieval)
-6. **v0.2 surface**: 10 public tools only. Admin tools behind `--admin` flag. See SKILL.md for agent usage guide.
-
----
-
-## Quick Reference
-
-### Commands
-
-```bash
-npm run dev              # tsx watch src/scripts/serve.ts
-npm run build            # tsc → dist/
-npm run build:client     # Vite → src/client/dist/
-npm run build:all        # client + server
-npm start                # node dist/scripts/serve.js
-npm run reindex          # re-embed all memories after provider change
-npm run install:wizard   # interactive first-time setup (tsx)
-npm run pair             # interactive pairing wizard (engram-mcp-pair)
-npm run rebuild          # rebuild SQLite+LanceDB from ops_log (engram-mcp rebuild)
-npm test                 # vitest run
-npm run lint             # eslint src/
-```
-
-### Tech Stack
-
-| Layer | Tech |
-|---|---|
-| Runtime | Node.js >= 22, TypeScript 5.7 strict, ESM |
-| MCP | `@modelcontextprotocol/sdk@1.28` (stdio + StreamableHTTP) |
-| Vector | LanceDB (`@lancedb/lancedb@0.27`) per-type tables |
-| SQL | better-sqlite3 + FTS5 |
-| Embeddings | OpenAI-compat dispatch → ollama / engram / voyage / openai / openai-compatible |
-| Audio | nodejs-whisper (whisper.cpp) |
-| YouTube | watch-page scrape + yt-dlp fallback |
-| Web | Express 5, ws, React 19, Vite 5, Tailwind v4, react-query |
-| Validation | Zod everywhere |
-| IDs | ULID |
-
-### Key conventions
-
-- **Module pattern**: `"type": "module"`, imports with `.js` extension
-- **Config**: Zod schema in `src/config/schema.ts`, loaded from `~/.engram/config.json` or env (`ENGRAM_CONFIG_DIR`, `DATA_DIR`)
-- **DB**: `getDb()` singleton, prepared statements only
-- **Logging**: `createLogger(scope)` from `src/logger.ts`
-- **Tool descriptions**: agent-facing — explain WHEN to use the tool and what title/tags improve retrieval
-- **Tests**: real services (Ollama, LanceDB, Notion sandbox, etc.). No mocks. Real-API tests use ephemeral tmpdirs.
-
----
-
-## Architecture (Phase 1)
-
-```
-                ┌─ stdio  ─┐
-agent runtime ──┤          ├──▶ MCP server (engram-mcp)
-                └─ HTTP    ─┘         │
-                                      ▼
-                            ┌─ ToolRouter ─┐
-                            │ 10 tools     │  (+18 admin with --admin flag)
-                            └──────┬───────┘
-                                   ▼
-                            ┌─ ModuleRegistry ─┐
-                            │  notes           │
-                            │  conversations   │
-                            │  drive (OAuth)   │
-                            │  notion (OAuth)  │
-                            │  youtube         │
-                            │  audio (Whisper) │
-                            │  obsidian        │
-                            │  <custom types>  │
-                            └────────┬─────────┘
-                                     ▼
-                              ┌─ MemoryStore ─┐
-                              │  insert       │  ──▶ chunk + embed (Ollama)
-                              │  search       │  ──▶ LanceDB per-type tables
-                              │  getById      │  ──▶ SQLite + FTS5
-                              │  delete       │
-                              │  findRelated  │
-                              │  setProperties│
-                              └────────┬──────┘
-                                       │ events: memory.added/deleted/updated
-                                       ▼
-                                  WebSocket /ws ──▶ dashboard React UI
-```
-
-Cloud bits (Phase 2 — Plan K): `engram-mcp pair` CLI activates cloud transit poller (node-cron,
-5 min), Bridge Relay WSS client, and E2E encrypted blob dispatch from the Engram cloud inbox.
-Set ENGRAM_PASSPHRASE env var for the transit poller to start automatically at server boot.
-Mobile app, billing, and Engram-hosted embeddings server are in separate Plans (I, J, M).
-
-Phase 3 — Plan N (ops-log sync): Every local write (insert/delete/setProperties) is logged as a
-signed, AES-256-GCM-encrypted op in `ops_log` (SQLite). A `ChannelClient` pushes pending ops to
-the cloud `UserSyncChannel` Durable Object (engram-cloud) and receives ops from other devices.
-The `ReplayApplier` decrypts, verifies ed25519 signatures, and applies ops with LWW + union
-conflict resolution. `engram-mcp rebuild` drops SQLite+LanceDB and replays all ops from scratch.
-Enable via `config.json: {"sync": {"enabled": true, "cloudBaseUrl": "..."}}` + ENGRAM_PASSPHRASE.
-Full multi-PC sync requires Plan O cloud worker deployed (see RUNBOOK.md).
-
----
-
-## Project Structure
-
-```
-src/
-├── types.ts                          # MemoryItem schema (Zod) + interfaces
-├── logger.ts                         # createLogger
-├── index.ts                          # (stub — entry is src/scripts/serve.ts)
-├── config/{schema,index}.ts          # Zod config + loader
-├── db/index.ts                       # SQLite init + 3 migrations
-├── embeddings/
-│   ├── index.ts                      # dispatcher
-│   └── providers/{ollama,engram,voyage,openai,openai-compat}.ts
-├── vector/store.ts                   # LanceDB per-type tables
-├── memory/
-│   ├── core/{chunker,wikilinks,module-interface,module-registry,
-│   │         store,source-registry,property-extractor,reindex}.ts
-│   ├── modules/
-│   │   ├── notes/                    # add_note, search_notes
-│   │   ├── conversations/            # remember_exchange, search_conversations
-│   │   ├── drive/                    # OAuth + watcher + ingest/list/watch tools
-│   │   ├── notion/                   # OAuth + watcher + ingest/list/watch tools
-│   │   ├── audio/                    # Whisper.cpp + add_audio_file/search_audio
-│   │   ├── youtube/                  # transcript fetcher + add_youtube_url/search
-│   │   ├── obsidian/                 # vault reader + fs.watch + tools
-│   │   └── _custom/                  # generic-module factory + create/list/delete
-│   ├── public/tools.ts               # 10 public tools: remember, recall, get, update,
-│   │                                 #   forget, relate, list_types, recent, ingest,
-│   │                                 #   suggest_properties
-│   └── admin/tools.ts                # ~18 admin tools behind --admin flag:
-├── core/                             # LOW-LEVEL UTILITIES (canonical)
-│   ├── logger.ts                     # createLogger (was src/logger.ts)
-│   ├── db/index.ts                   # SQLite init + migrations (was src/db/index.ts)
-│   └── server/
-│       ├── mcp-handler.ts            # buildEngramRuntime + startStdioMcpServer
-│       ├── tool-router.ts            # ToolRouter
-│       ├── http.ts                   # Express bootstrap (was src/webapp/server.ts)
-│       ├── mcp-http.ts               # StreamableHTTP MCP transport
-│       └── websocket.ts              # WS broadcaster for memory.* events
-├── tools/                            # Top-level tool registry (mirrors predmcp pattern)
-│   └── index.ts                      # registerAllTools + dynamic private import
-├── private/                          # GITIGNORED — premium extensions (hosted Engram only)
-│   ├── index.ts                      # registerPrivateExtensions (no-op placeholder)
-│   ├── README.md                     # Explains what goes here
-│   ├── tools/                        # Premium MCP tools
-│   ├── algorithms/                   # Advanced algorithm overrides
-│   └── prompts/                      # Tuned LLM prompts (IP)
-├── server/                           # Engram-specific HTTP routes
-│   ├── index.ts                      # Re-exports from core/server/http.ts
-│   └── api/{memories,sources,types,views,daily,settings,reindex,sync-status,graph}.ts
-├── mcp-server/                       # Re-export shims (→ core/server/)
-│   ├── server.ts                     # shim → core/server/mcp-handler.ts
-│   └── tool-router.ts                # shim → core/server/tool-router.ts
-├── webapp/                           # Re-export shims (→ core/server/)
-│   ├── server.ts                     # shim → core/server/http.ts
-│   ├── mcp-http.ts                   # shim → core/server/mcp-http.ts
-│   ├── websocket.ts                  # shim → core/server/websocket.ts
-│   └── api/                          # original api handlers (not shimmed — used by tests)
-├── client/                           # React/Vite/Tailwind dashboard
-│   ├── vite.config.ts
-│   ├── tsconfig.json (separate)
-│   └── src/{App,main,api,ws,index.css}.{ts,tsx,css}
-└── scripts/{serve,install,install-ollama,reindex}.ts
-```
-
----
-
-## Database Schema
-
-SQLite at `<dataDir>/engram.db` (WAL mode, FOREIGN KEYS ON):
-
-| Table | Purpose |
-|---|---|
-| `memories` | id, type, source_id, content, content_hash, properties_json, wikilinks_json, related_ids_json, embedding_model, created_at |
-| `memories_fts` | FTS5 virtual table on content/title/tags |
-| `custom_types` | type_name, display_name, schema_json, created_at |
-| `oauth_tokens` | provider, access_token, refresh_token, expires_at, extra_json |
-| `module_state` | (module_id, key) → value_json |
-| `watched_sources` | id, module_id, external_id, display_name, config_json, last_synced_at, last_modified_remote, last_error, enabled |
-| `saved_views` | id, name, description, definition_json, pinned, created_at, updated_at |
-| `settings` | key → value_json |
-
-Vector tables: `memories_<type>` per memory type in LanceDB (id, source_id, chunk_index, content, created_at, field1-4, vector 768-d).
-
----
-
-## Pricing (planned)
-
-- **Free**: full local — Ollama embeddings, all modules, ~36 MCP tools
-- **Pro $9/mo** (Phase 2): mobile app, cloud transit, share-by-email, Engram hosted embeddings, multi-PC encrypted sync, online dashboard
-- **BYO premium embeddings** at any tier: Voyage / OpenAI / OAI-compatible
-
----
-
-## Phase status
-
-- [x] **Phase 1** — local MCP server with all memory types (DONE — see docs/superpowers/plans/)
-- [ ] **Phase 2** — Mobile + cloud transit + billing + hosted Engram embeddings server
-- [ ] **Phase 3** — Bidirectional multi-PC sync (ops-log + cloud saves) + recovery shards
-
----
-
-## License
-
-MIT