mixgram 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/.mixgram/index.db +0 -0
  2. package/.mixgram/test-esm.db +0 -0
  3. package/.mixgram/test-index.db +0 -0
  4. package/.mixgram/test-stage1.db +0 -0
  5. package/README.md +335 -0
  6. package/bin/mixgram.js +309 -0
  7. package/index.js +9 -0
  8. package/package.json +51 -0
  9. package/projects/castlebravo/memory/decisions/decision--architecture/sqlite-derived-index.md +17 -0
  10. package/projects/test/memory/decisions/decision--architecture/sqlite-derived-index.md +17 -0
  11. package/spec/fixtures/realistic-content.js +97 -0
  12. package/spec/reporter.js +127 -0
  13. package/spec/run-tests-runner.js +40 -0
  14. package/spec/run-tests.js +160 -0
  15. package/spec/scenarios/scenarios.js +520 -0
  16. package/spec/sdd.md +1002 -0
  17. package/spec/tdd.md +1237 -0
  18. package/src/config.js +56 -0
  19. package/src/core/documents/documents.js +207 -0
  20. package/src/core/embeddings/embedder.js +58 -0
  21. package/src/core/embeddings/queue.js +118 -0
  22. package/src/core/embeddings/vectorStore.js +127 -0
  23. package/src/core/embeddings/worker.js +27 -0
  24. package/src/core/indexing/indexer.js +131 -0
  25. package/src/core/indexing/parser.js +78 -0
  26. package/src/core/indexing/reindex.js +101 -0
  27. package/src/core/prompts/prompts.js +15 -0
  28. package/src/core/search/search.js +223 -0
  29. package/src/core/sessions/sessions.js +27 -0
  30. package/src/db/migrations/001_initial.sql +86 -0
  31. package/src/db/sqlite.js +39 -0
  32. package/src/fs/paths.js +79 -0
  33. package/src/fs/watcher.js +49 -0
  34. package/src/mcp/cli-adapter.js +118 -0
  35. package/src/mcp/server.js +47 -0
  36. package/src/mcp/tool-registry.js +138 -0
  37. package/src/mcp/tools.js +159 -0
  38. package/src/utils/hash.js +6 -0
  39. package/src/utils/ids.js +22 -0
  40. package/src/utils/markdown.js +49 -0
Binary file
Binary file
Binary file
Binary file
package/README.md ADDED
@@ -0,0 +1,335 @@
1
+ # Mixgram
2
+
3
+ MCP memory server compatible with [Engram](https://github.com/gentleman-programming/engram): **Markdown as source of truth**, SQLite FTS5 for full-text search, and optional local embeddings.
4
+
5
+ - **Human-readable memory** — All durable memory is stored as Markdown files.
6
+ - **Git-friendly** — Edit files by hand and reindex; the index is derived and rebuildable.
7
+ - **Engram-compatible** — Same MCP tool names and semantics; drop-in replacement.
8
+ - **Optional semantics** — Works fully with text-only; enable embeddings when you need hybrid search.
9
+
10
+ ---
11
+
12
+ ## Installation
13
+
14
+ **Global install (recommended for MCP clients):**
15
+
16
+ ```bash
17
+ npm install -g mixgram
18
+ ```
19
+
20
+ Then use the `mixgram` command in your client config (see below).
21
+
22
+ Embeddings (semantic search) are included; they are off by default. Turn them on via config or `mixgram mcp --embeddings`.
23
+
24
+ ---
25
+
26
+ ## CLI
27
+
28
+ | Command | Description |
29
+ |--------|-------------|
30
+ | `mixgram mcp [options]` | Run the MCP server (stdio). This is what your client runs. |
31
+ | `mixgram setup cursor` | Add Mixgram to Cursor’s MCP config. |
32
+ | `mixgram setup gemini-cli` | Add Mixgram to Gemini CLI settings. |
33
+ | `mixgram setup codex` | Add Mixgram to Codex config. |
34
+ | `mixgram help` | Show usage. |
35
+ | `mixgram help <tool>` | Show options for a specific MCP tool. |
36
+ | `mixgram <tool> [--key value ...]` | Run any MCP tool from the command line (see below). |
37
+
38
+ **MCP tools from the CLI** — Every MCP tool is automatically available as a subcommand. No extra wiring is needed: if a tool is added to the internal registry, it is exposed both to MCP clients and to the CLI. Use `mixgram help` to list tools and `mixgram help <tool>` (or `mixgram <tool> --help`) to see a tool’s options. Examples:
39
+
40
+ ```bash
41
+ mixgram mem_stats
42
+ mixgram mem_search --query "index" --limit 5
43
+ mixgram mem_save --title "My note" --content "Body" --type decision --project my-app
44
+ mixgram mem_reindex --full
45
+ ```
46
+
47
+ Arguments are passed as `--key value`. Booleans use `--flag` or `--no-flag`. Arrays use repeated flags: `--tags a --tags b`.
48
+
49
+ **`mcp` options** (and env / config file):
50
+
51
+ | Option | Env | Description |
52
+ |--------|-----|-------------|
53
+ | `--config <path>` | `MIXGRAM_CONFIG` | Config file (default: `./.mixgram/config.json` or `~/.mixgram/config.json`). |
54
+ | `--embeddings` | `MIXGRAM_EMBEDDINGS_ENABLED` | Enable semantic search. |
55
+ | `--watch` | `MIXGRAM_WATCH` | Watch files and reindex on change. |
56
+ | `--home <path>` | `MIXGRAM_HOME` | Home memory root. |
57
+ | `--projects <path>` | `MIXGRAM_PROJECTS` | Projects root. |
58
+ | `--sqlite-path <path>` | `MIXGRAM_SQLITE_PATH` | SQLite index path. |
59
+
60
+ **Example — Cursor**
61
+
62
+ Add to Cursor’s MCP config (or run `mixgram setup cursor`):
63
+
64
+ ```json
65
+ {
66
+ "mcpServers": {
67
+ "mixgram": {
68
+ "command": "mixgram",
69
+ "args": ["mcp"]
70
+ }
71
+ }
72
+ }
73
+ ```
74
+
75
+ With embeddings and custom paths via args:
76
+
77
+ ```json
78
+ "mixgram": {
79
+ "command": "mixgram",
80
+ "args": ["mcp", "--embeddings", "--home", "/data/memory", "--projects", "/data/projects"]
81
+ }
82
+ ```
83
+
84
+ Or use a config file (see below) and just `"args": ["mcp"]`. Restart Cursor after changing config.
85
+
86
+ ---
87
+
88
+ ## Quick start
89
+
90
+ Run the MCP server (stdio):
91
+
92
+ ```bash
93
+ mixgram mcp
94
+ ```
95
+
96
+ From the repo without global install: `npx mixgram mcp` or `npm start`. Configure your MCP client with `command: "mixgram"`, `args: ["mcp"]` when Mixgram is installed globally.
97
+
98
+ ---
99
+
100
+ ## Configuration
101
+
102
+ When you run `mixgram mcp`, config is merged from (lowest to highest priority):
103
+
104
+ 1. **Defaults** (paths relative to current directory)
105
+ 2. **Config file** — `./.mixgram/config.json` (project) or `~/.mixgram/config.json` (user), or `--config /path`
106
+ 3. **Environment** — `MIXGRAM_*` (see table above)
107
+ 4. **CLI args** — `--embeddings`, `--home`, etc.
108
+
109
+ Example **`.mixgram/config.json`** (project or home):
110
+
111
+ ```json
112
+ {
113
+ "homeMemoryRoot": "./home/memory",
114
+ "projectsRoot": "./projects",
115
+ "sqlitePath": "./.mixgram/index.db",
116
+ "watch": false,
117
+ "embeddings": {
118
+ "enabled": true
119
+ }
120
+ }
121
+ ```
122
+
123
+ Paths in the config file are relative to the config file’s directory (project) or to the current directory when using `~/.mixgram/config.json`. Defaults:
124
+
125
+ | Option | Default | Description |
126
+ |--------|---------|-------------|
127
+ | `homeMemoryRoot` | `./home/memory` | Cross-project memory (Markdown files). |
128
+ | `projectsRoot` | `./projects` | Project roots; each project may have `memory/` under it. |
129
+ | `sqlitePath` | `./.mixgram/index.db` | SQLite index (FTS5 + optional vectors). |
130
+ | `watch` | `false` | Watch files and reindex on change. |
131
+ | `indexing.reindexOnStartup` | `true` | Full reindex when server starts. |
132
+ | `embeddings.enabled` | `false` | Enable async local embeddings and hybrid search. |
133
+ | `search.defaultScopeMode` | `'merged'` | `'project-only'` \| `'home-only'` \| `'merged'`. |
134
+ | `search.ftsWeight` / `search.semanticWeight` | `0.7` / `0.3` | Weights when embeddings are enabled. |
135
+
136
+ Example minimal override:
137
+
138
+ ```js
139
+ import { run } from 'mixgram/src/mcp/server.js';
140
+
141
+ await run({
142
+ homeMemoryRoot: '/data/memory',
143
+ projectsRoot: '/data/projects',
144
+ sqlitePath: '/data/.mixgram/index.db',
145
+ watch: true
146
+ });
147
+ ```
148
+
149
+ ---
150
+
151
+ ## Text-only memory
152
+
153
+ Core flow: save Markdown-backed documents, search with FTS5, get context.
154
+
155
+ ### Save (create or update by topic)
156
+
157
+ ```json
158
+ // mem_save — create or update by topic_key
159
+ {
160
+ "title": "Use SQLite as derived index",
161
+ "type": "decision",
162
+ "scope": "project",
163
+ "project": "my-app",
164
+ "topic_key": "architecture/sqlite-derived-index",
165
+ "content": "SQLite will be the derived index over Markdown documents."
166
+ }
167
+ ```
168
+
169
+ - **scope** `project` → file under `projects/<project>/memory/...`
170
+ - **scope** `home` → file under `home/memory/...`
171
+ - Same `topic_key` + scope + project → **update** existing doc; otherwise create.
172
+
173
+ ### Search
174
+
175
+ ```json
176
+ // mem_search
177
+ {
178
+ "query": "derived SQLite index",
179
+ "scope_mode": "merged",
180
+ "project": "my-app",
181
+ "limit": 10
182
+ }
183
+ ```
184
+
185
+ **scope_mode:**
186
+
187
+ - `project-only` — only project memory.
188
+ - `home-only` — only home memory.
189
+ - `merged` — both; project results ranked first when `project` is set.
190
+
191
+ Response includes `documentId`, `chunkId`, `title`, `topicKey`, `snippet`, `score`, etc.
192
+
193
+ ### Context (for prompts)
194
+
195
+ ```json
196
+ // mem_context — recent or query-based
197
+ {
198
+ "query": "indexing decisions",
199
+ "project": "my-app",
200
+ "limit": 5
201
+ }
202
+ ```
203
+
204
+ Omit `query` or use `*` to get **recent** context only.
205
+
206
+ ### Get / update / delete
207
+
208
+ - **mem_get_observation** `{ "id": "<document-id>" }` — full document content.
209
+ - **mem_update** `{ "id": "<id>", "title": "...", "content": "..." }` — update by id.
210
+ - **mem_delete** `{ "id": "<id>", "hardDelete": false }` — soft or hard delete.
211
+
212
+ ### Helpers
213
+
214
+ - **mem_suggest_topic_key** — suggest a stable `topic_key` from title/content/type.
215
+ - **mem_stats** — counts (documents, sessions, prompts, `embeddings_enabled`).
216
+
217
+ ### Example: one round-trip
218
+
219
+ ```text
220
+ 1. mem_save → { success: true, id: "obs_...", path: "...", created: true }
221
+ 2. mem_search({ query: "SQLite", project: "my-app" }) → { results: [ { title, snippet, ... } ] }
222
+ 3. mem_get_observation({ id: "obs_..." }) → { title, content, type, scope, project, ... }
223
+ ```
224
+
225
+ ---
226
+
227
+ ## Reindex, watch, and sessions
228
+
229
+ ### Reindex from disk
230
+
231
+ Useful after cloning a repo or editing Markdown by hand:
232
+
233
+ ```json
234
+ // mem_reindex
235
+ { "full": true }
236
+ ```
237
+
238
+ - `full: true` — rebuild entire index from `home/**/*.md` and `projects/**/memory/**/*.md`.
239
+ - `full: false` (default) — incremental (by mtime).
240
+
241
+ Manual edit example:
242
+
243
+ 1. Edit a `.md` file under `home/memory` or `projects/<project>/memory`.
244
+ 2. Call `mem_reindex({ full: true })` (or run with `watch: true` so changes are picked up).
245
+ 3. `mem_search` and `mem_get_observation` reflect the new content.
246
+
247
+ ### Watcher
248
+
249
+ Start the server with `watch: true` so that add/change/delete under the memory paths trigger reindex automatically.
250
+
251
+ ### Sessions and prompts
252
+
253
+ - **mem_session_start** `{ "project": "my-app" }` → `{ session_id }`
254
+ - **mem_session_end** `{ "session_id": "..." }`
255
+ - **mem_session_summary** `{ "session_id": "...", "content": "...", "title": "..." }` — persists a summary as a memory document.
256
+ - **mem_save_prompt** `{ "session_id": "...", "content": "..." }` — store a prompt for the session.
257
+ - **mem_timeline** `{ "observation_id": "..." }` — before/focus/after in the same session.
258
+
259
+ ### Scope examples
260
+
261
+ ```json
262
+ // Only project memory
263
+ mem_search({ "query": "reindex", "scope_mode": "project-only", "project": "my-app" })
264
+
265
+ // Only home (cross-project)
266
+ mem_search({ "query": "reindex", "scope_mode": "home-only" })
267
+
268
+ // Both; project first
269
+ mem_search({ "query": "reindex", "scope_mode": "merged", "project": "my-app" })
270
+ ```
271
+
272
+ ---
273
+
274
+ ## Optional semantic layer
275
+
276
+ When `embeddings.enabled` is `true` and optional deps are installed:
277
+
278
+ - **Saves** are durable and searchable by text immediately; embeddings are queued and processed in the background.
279
+ - **Search** becomes **hybrid**: FTS + vector similarity, blended with `search.ftsWeight` and `search.semanticWeight` (e.g. 0.7 and 0.3).
280
+ - A **worker** runs in the background and processes the embedding queue (e.g. every 2 seconds).
281
+
282
+ ### Enable embeddings
283
+
284
+ 1. Install optional deps: `npm install @huggingface/transformers sqlite-vec`
285
+ 2. Configure:
286
+
287
+ ```js
288
+ await run({
289
+ embeddings: {
290
+ enabled: true,
291
+ similarityThreshold: 0.87,
292
+ maxRetries: 3
293
+ },
294
+ search: {
295
+ ftsWeight: 0.7,
296
+ semanticWeight: 0.3
297
+ }
298
+ });
299
+ ```
300
+
301
+ ### Behaviour
302
+
303
+ - **mem_save** / **mem_update** return as soon as the Markdown is written and the text index is updated; they do **not** wait for embeddings.
304
+ - **mem_search** uses FTS only until vectors exist for the matched chunks; then it uses the hybrid blend.
305
+ - If the embedding provider or sqlite-vec is unavailable, save and search still work (text-only).
306
+
307
+ ### Example: hybrid search
308
+
309
+ ```json
310
+ // Same tool; behaviour depends on config and whether vectors exist
311
+ mem_search({
312
+ "query": "persistir índices derivados",
313
+ "scope_mode": "merged",
314
+ "project": "my-app",
315
+ "limit": 5
316
+ })
317
+ ```
318
+
319
+ With embeddings enabled and vectors ready, results combine literal matches (FTS) and semantic similarity (e.g. paraphrases).
320
+
321
+ ---
322
+
323
+ ## Tests
324
+
325
+ ```bash
326
+ npm test
327
+ ```
328
+
329
+ Runs black-box scenario tests for text-only memory, reindex/sessions/scope, and semantic fallback and error handling. Use `npm run test:visual` to see a narrative per scenario (inputs, outputs, snippets, and checks) for human review.
330
+
331
+ ---
332
+
333
+ ## License
334
+
335
+ MIT
package/bin/mixgram.js ADDED
@@ -0,0 +1,309 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Mixgram CLI: mcp server and MCP auto-registration for clients.
4
+ * Usage:
5
+ * mixgram mcp [options] — run MCP server (stdio)
6
+ * mixgram setup <client> — add Mixgram to Cursor / Gemini CLI / Codex config
7
+ */
8
+ import { run } from '../src/mcp/server.js';
9
+ import { loadConfig } from '../src/config.js';
10
+ import { createToolHandlers } from '../src/mcp/tools.js';
11
+ import { getToolByName, listToolNames, parseToolArgs, formatToolHelp } from '../src/mcp/cli-adapter.js';
12
+ import fs from 'fs';
13
+ import path from 'path';
14
+ import os from 'os';
15
+
16
+ const SUBCOMMAND = process.argv[2];
17
+ const ARG = process.argv[3];
18
+
19
+ /** Parse options after "mcp": --config, --embeddings, --watch, --home, --projects, --sqlite-path */
20
+ function parseMcpArgs() {
21
+ const args = process.argv.slice(3);
22
+ const out = {};
23
+ for (let i = 0; i < args.length; i++) {
24
+ const a = args[i];
25
+ if (a === '--embeddings') {
26
+ out.embeddings = out.embeddings ?? {};
27
+ out.embeddings.enabled = true;
28
+ } else if (a === '--watch') {
29
+ out.watch = true;
30
+ } else if (a === '--config' && args[i + 1]) {
31
+ out._configPath = args[++i];
32
+ } else if (a === '--home' && args[i + 1]) {
33
+ out.homeMemoryRoot = args[++i];
34
+ } else if (a === '--projects' && args[i + 1]) {
35
+ out.projectsRoot = args[++i];
36
+ } else if (a === '--sqlite-path' && args[i + 1]) {
37
+ out.sqlitePath = args[++i];
38
+ }
39
+ }
40
+ return out;
41
+ }
42
+
43
+ /** Resolve config file path: --config, MIXGRAM_CONFIG, ./.mixgram/config.json, ~/.mixgram/config.json */
44
+ function resolveConfigPath(explicitPath) {
45
+ if (explicitPath) return path.resolve(explicitPath);
46
+ const envPath = process.env.MIXGRAM_CONFIG;
47
+ if (envPath) return path.resolve(envPath);
48
+ const cwd = process.cwd();
49
+ const local = path.join(cwd, '.mixgram', 'config.json');
50
+ if (fs.existsSync(local)) return local;
51
+ const global = path.join(os.homedir(), '.mixgram', 'config.json');
52
+ if (fs.existsSync(global)) return global;
53
+ return null;
54
+ }
55
+
56
+ /** baseDir for path resolution: project root when config is in .mixgram/config.json, else config dir. */
57
+ function getBaseDir(configPath) {
58
+ if (!configPath) return process.cwd();
59
+ const dir = path.dirname(configPath);
60
+ return path.basename(dir) === '.mixgram' ? path.dirname(dir) : dir;
61
+ }
62
+
63
+ /** Load config from file + env + argv. */
64
+ function loadCliConfig() {
65
+ const argvOverrides = parseMcpArgs();
66
+ const configPath = resolveConfigPath(argvOverrides._configPath);
67
+ const baseDir = getBaseDir(configPath);
68
+
69
+ let fileConfig = {};
70
+ if (configPath) {
71
+ try {
72
+ fileConfig = JSON.parse(fs.readFileSync(configPath, 'utf8'));
73
+ } catch (e) {
74
+ console.error('Could not read config from', configPath, e.message);
75
+ process.exit(1);
76
+ }
77
+ }
78
+
79
+ const envOverrides = {};
80
+ if (process.env.MIXGRAM_EMBEDDINGS_ENABLED === '1' || process.env.MIXGRAM_EMBEDDINGS_ENABLED === 'true') {
81
+ envOverrides.embeddings = { ...(fileConfig.embeddings || {}), enabled: true };
82
+ }
83
+ if (process.env.MIXGRAM_HOME) envOverrides.homeMemoryRoot = process.env.MIXGRAM_HOME;
84
+ if (process.env.MIXGRAM_PROJECTS) envOverrides.projectsRoot = process.env.MIXGRAM_PROJECTS;
85
+ if (process.env.MIXGRAM_SQLITE_PATH) envOverrides.sqlitePath = process.env.MIXGRAM_SQLITE_PATH;
86
+ if (process.env.MIXGRAM_WATCH === '1' || process.env.MIXGRAM_WATCH === 'true') envOverrides.watch = true;
87
+
88
+ const { _configPath, ...argvRest } = argvOverrides;
89
+ const merged = { ...fileConfig, ...envOverrides };
90
+ Object.assign(merged, argvRest);
91
+ if (argvRest.embeddings && typeof merged.embeddings === 'object') {
92
+ merged.embeddings = { ...merged.embeddings, ...argvRest.embeddings };
93
+ }
94
+ return { overrides: merged, baseDir };
95
+ }
96
+
97
+ const MIXGRAM_ENTRY = {
98
+ command: 'mixgram',
99
+ args: ['mcp']
100
+ };
101
+
102
+ function cursorMcpPath() {
103
+ const home = os.homedir();
104
+ if (process.platform === 'win32') {
105
+ return path.join(process.env.APPDATA || path.join(home, 'AppData', 'Roaming'), 'Cursor', 'mcp.json');
106
+ }
107
+ if (process.platform === 'linux') {
108
+ return path.join(home, '.config', 'cursor', 'mcp.json');
109
+ }
110
+ return path.join(home, '.cursor', 'mcp.json');
111
+ }
112
+
113
+ function geminiSettingsPath() {
114
+ return path.join(os.homedir(), '.gemini', 'settings.json');
115
+ }
116
+
117
+ function codexConfigPath() {
118
+ return path.join(os.homedir(), '.codex', 'config.toml');
119
+ }
120
+
121
+ function setupCursor() {
122
+ const filePath = cursorMcpPath();
123
+ const dir = path.dirname(filePath);
124
+ let data = { mcpServers: {} };
125
+ if (fs.existsSync(filePath)) {
126
+ try {
127
+ data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
128
+ } catch (e) {
129
+ console.error('Could not parse existing Cursor mcp.json:', e.message);
130
+ process.exit(1);
131
+ }
132
+ if (!data.mcpServers) data.mcpServers = {};
133
+ } else {
134
+ try {
135
+ fs.mkdirSync(dir, { recursive: true });
136
+ } catch (e) {
137
+ console.error('Could not create config directory:', e.message);
138
+ process.exit(1);
139
+ }
140
+ }
141
+ data.mcpServers.mixgram = MIXGRAM_ENTRY;
142
+ fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8');
143
+ console.log('Cursor: added mixgram to', filePath);
144
+ console.log('Restart Cursor to load the MCP server.');
145
+ }
146
+
147
+ function setupGeminiCli() {
148
+ const filePath = geminiSettingsPath();
149
+ const dir = path.dirname(filePath);
150
+ let data = {};
151
+ if (fs.existsSync(filePath)) {
152
+ try {
153
+ data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
154
+ } catch (e) {
155
+ console.error('Could not parse existing Gemini settings.json:', e.message);
156
+ process.exit(1);
157
+ }
158
+ } else {
159
+ try {
160
+ fs.mkdirSync(dir, { recursive: true });
161
+ } catch (e) {
162
+ console.error('Could not create .gemini directory:', e.message);
163
+ process.exit(1);
164
+ }
165
+ }
166
+ if (!data.mcpServers) data.mcpServers = {};
167
+ data.mcpServers.mixgram = MIXGRAM_ENTRY;
168
+ fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf8');
169
+ console.log('Gemini CLI: added mixgram to', filePath);
170
+ }
171
+
172
+ function setupCodex() {
173
+ const filePath = codexConfigPath();
174
+ const dir = path.dirname(filePath);
175
+ const section = `[mcp_servers.mixgram]
176
+ command = "mixgram"
177
+ args = ["mcp"]
178
+ `;
179
+ let content = '';
180
+ if (fs.existsSync(filePath)) {
181
+ content = fs.readFileSync(filePath, 'utf8');
182
+ const re = /\[mcp_servers\.mixgram\][\s\S]*?(?=\n\[|$)/;
183
+ if (re.test(content)) {
184
+ content = content.replace(re, section.trimEnd());
185
+ } else {
186
+ content = content.trimEnd() + '\n\n' + section;
187
+ }
188
+ } else {
189
+ try {
190
+ fs.mkdirSync(dir, { recursive: true });
191
+ } catch (e) {
192
+ console.error('Could not create .codex directory:', e.message);
193
+ process.exit(1);
194
+ }
195
+ content = section;
196
+ }
197
+ fs.writeFileSync(filePath, content, 'utf8');
198
+ console.log('Codex: added mixgram to', filePath);
199
+ }
200
+
201
+ function printHelp() {
202
+ const toolList = listToolNames();
203
+ const toolLines = toolList.length ? ` ${toolList.join(', ')}\n\n` : '';
204
+ console.log(`
205
+ Usage: mixgram <command> [options]
206
+
207
+ Commands:
208
+ mcp [options] Run the MCP server (stdio). Use this in your client config.
209
+ setup <client> Register Mixgram with an MCP client.
210
+ help [tool] Show help; with optional tool name, show options for that tool.
211
+ <tool> [options] Run an MCP tool by name. Tools:
212
+ ${toolLines}
213
+
214
+ mcp options (and env / config file):
215
+ --config <path> Config file (default: ./.mixgram/config.json or ~/.mixgram/config.json)
216
+ --embeddings Enable semantic search (or embeddings.enabled in config)
217
+ --watch Watch files and reindex on change
218
+ --home <path> Home memory root (default: ./home/memory)
219
+ --projects <path> Projects root (default: ./projects)
220
+ --sqlite-path <path> SQLite index path (default: ./.mixgram/index.db)
221
+
222
+ Env: MIXGRAM_CONFIG, MIXGRAM_EMBEDDINGS_ENABLED, MIXGRAM_HOME, MIXGRAM_PROJECTS,
223
+ MIXGRAM_SQLITE_PATH, MIXGRAM_WATCH
224
+
225
+ Setup targets:
226
+ cursor Cursor IDE
227
+ gemini-cli Gemini CLI
228
+ codex Codex
229
+
230
+ Example (Cursor): "mixgram": { "command": "mixgram", "args": ["mcp"] }
231
+ With embeddings: "args": ["mcp", "--embeddings"]
232
+ Config file: .mixgram/config.json or ~/.mixgram/config.json
233
+
234
+ npm install -g mixgram
235
+ `);
236
+ }
237
+
238
+ async function main() {
239
+ if (SUBCOMMAND === 'mcp') {
240
+ const { overrides, baseDir } = loadCliConfig();
241
+ await run(overrides, baseDir)
242
+ .then(() => {})
243
+ .catch((err) => {
244
+ console.error(err);
245
+ process.exit(1);
246
+ });
247
+ return;
248
+ }
249
+
250
+ if (SUBCOMMAND === 'setup') {
251
+ if (!ARG) {
252
+ console.error('Usage: mixgram setup <cursor|gemini-cli|codex>');
253
+ process.exit(1);
254
+ }
255
+ switch (ARG) {
256
+ case 'cursor':
257
+ setupCursor();
258
+ break;
259
+ case 'gemini-cli':
260
+ setupGeminiCli();
261
+ break;
262
+ case 'codex':
263
+ setupCodex();
264
+ break;
265
+ default:
266
+ console.error('Unknown target. Use: cursor, gemini-cli, or codex');
267
+ process.exit(1);
268
+ }
269
+ return;
270
+ }
271
+
272
+ if (SUBCOMMAND === 'help' || SUBCOMMAND === '-h' || SUBCOMMAND === '--help' || !SUBCOMMAND) {
273
+ if (ARG && getToolByName(ARG)) {
274
+ console.log(formatToolHelp(getToolByName(ARG)));
275
+ } else {
276
+ printHelp();
277
+ }
278
+ return;
279
+ }
280
+
281
+ const toolNames = listToolNames();
282
+ if (toolNames.includes(SUBCOMMAND)) {
283
+ const toolArgv = process.argv.slice(3);
284
+ if (toolArgv[0] === '--help' || toolArgv[0] === '-h') {
285
+ console.log(formatToolHelp(getToolByName(SUBCOMMAND)));
286
+ return;
287
+ }
288
+ const toolDef = getToolByName(SUBCOMMAND);
289
+ const args = parseToolArgs(toolDef, toolArgv);
290
+ const { overrides, baseDir } = loadCliConfig();
291
+ const config = loadConfig(overrides, baseDir);
292
+ const handlers = createToolHandlers(config);
293
+ try {
294
+ const result = await handlers[SUBCOMMAND](args);
295
+ const text = result?.content?.[0]?.text;
296
+ if (text != null) console.log(text);
297
+ } catch (err) {
298
+ console.error(err);
299
+ process.exit(1);
300
+ }
301
+ return;
302
+ }
303
+
304
+ console.error('Unknown command:', SUBCOMMAND);
305
+ printHelp();
306
+ process.exit(1);
307
+ }
308
+
309
+ main();
package/index.js ADDED
@@ -0,0 +1,9 @@
1
+ #!/usr/bin/env node
2
+ import { run } from './src/mcp/server.js';
3
+
4
+ run()
5
+ .then(() => {})
6
+ .catch((err) => {
7
+ console.error(err);
8
+ process.exit(1);
9
+ });