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.
- package/.mixgram/index.db +0 -0
- package/.mixgram/test-esm.db +0 -0
- package/.mixgram/test-index.db +0 -0
- package/.mixgram/test-stage1.db +0 -0
- package/README.md +335 -0
- package/bin/mixgram.js +309 -0
- package/index.js +9 -0
- package/package.json +51 -0
- package/projects/castlebravo/memory/decisions/decision--architecture/sqlite-derived-index.md +17 -0
- package/projects/test/memory/decisions/decision--architecture/sqlite-derived-index.md +17 -0
- package/spec/fixtures/realistic-content.js +97 -0
- package/spec/reporter.js +127 -0
- package/spec/run-tests-runner.js +40 -0
- package/spec/run-tests.js +160 -0
- package/spec/scenarios/scenarios.js +520 -0
- package/spec/sdd.md +1002 -0
- package/spec/tdd.md +1237 -0
- package/src/config.js +56 -0
- package/src/core/documents/documents.js +207 -0
- package/src/core/embeddings/embedder.js +58 -0
- package/src/core/embeddings/queue.js +118 -0
- package/src/core/embeddings/vectorStore.js +127 -0
- package/src/core/embeddings/worker.js +27 -0
- package/src/core/indexing/indexer.js +131 -0
- package/src/core/indexing/parser.js +78 -0
- package/src/core/indexing/reindex.js +101 -0
- package/src/core/prompts/prompts.js +15 -0
- package/src/core/search/search.js +223 -0
- package/src/core/sessions/sessions.js +27 -0
- package/src/db/migrations/001_initial.sql +86 -0
- package/src/db/sqlite.js +39 -0
- package/src/fs/paths.js +79 -0
- package/src/fs/watcher.js +49 -0
- package/src/mcp/cli-adapter.js +118 -0
- package/src/mcp/server.js +47 -0
- package/src/mcp/tool-registry.js +138 -0
- package/src/mcp/tools.js +159 -0
- package/src/utils/hash.js +6 -0
- package/src/utils/ids.js +22 -0
- 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();
|