mixgram 1.0.2 → 1.0.4

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/README.md CHANGED
@@ -9,7 +9,7 @@ MCP memory server compatible with [Engram](https://github.com/gentleman-programm
9
9
  ### Advantages over Engram
10
10
 
11
11
  - **Visible, editable docs** — As you advance with agentic development you see the actual documentation files on disk. You can open them, read them, and edit them manually; the agent’s memory is not hidden in a black box.
12
- - **Versioned** — Memory lives in Markdown under your repo (e.g. `projects/<name>/memory/` or `home/memory/`). Commit, branch, and diff as with any other docs.
12
+ - **Versioned** — Memory lives in Markdown under your repo (e.g. `mixgram/<type>/` for project scope) or in a shared home (e.g. `home/memory/` for cross-project). Commit, branch, and diff as with any other docs.
13
13
  - **No semantic deps required** — Core experience is text-only (FTS5). No need to install embeddings or vector libs unless you opt in.
14
14
 
15
15
  ---
@@ -56,8 +56,9 @@ Arguments are passed as `--key value`. Booleans use `--flag` or `--no-flag`. Arr
56
56
  | `--config <path>` | `MIXGRAM_CONFIG` | Config file (default: `./.mixgram/config.json` or `~/.mixgram/config.json`). |
57
57
  | `--embeddings` | `MIXGRAM_EMBEDDINGS_ENABLED` | Enable optional semantic (hybrid) search. |
58
58
  | `--watch` | `MIXGRAM_WATCH` | Watch files and reindex on change. |
59
- | `--home <path>` | `MIXGRAM_HOME` | Home memory root. |
60
- | `--projects <path>` | `MIXGRAM_PROJECTS` | Projects root. |
59
+ | `--home <path>` | `MIXGRAM_HOME` | Home memory root (cross-project). |
60
+ | `--project-memory <path>` | `MIXGRAM_PROJECT_MEMORY` | Project memory root (default: `./mixgram`, relative to repo). |
61
+ | `--projects <path>` | `MIXGRAM_PROJECTS` | Projects root (legacy). |
61
62
  | `--sqlite-path <path>` | `MIXGRAM_SQLITE_PATH` | SQLite index path. |
62
63
 
63
64
  **Example — Cursor**
@@ -80,7 +81,7 @@ With embeddings and custom paths via args:
80
81
  ```json
81
82
  "mixgram": {
82
83
  "command": "mixgram",
83
- "args": ["mcp", "--embeddings", "--home", "/data/memory", "--projects", "/data/projects"]
84
+ "args": ["mcp", "--embeddings", "--home", "/data/memory", "--project-memory", "./mixgram"]
84
85
  }
85
86
  ```
86
87
 
@@ -114,7 +115,7 @@ Example **`.mixgram/config.json`** (project or home):
114
115
  ```json
115
116
  {
116
117
  "homeMemoryRoot": "./home/memory",
117
- "projectsRoot": "./projects",
118
+ "projectMemoryRoot": "./mixgram",
118
119
  "sqlitePath": "./.mixgram/index.db",
119
120
  "watch": false,
120
121
  "embeddings": {
@@ -123,12 +124,12 @@ Example **`.mixgram/config.json`** (project or home):
123
124
  }
124
125
  ```
125
126
 
126
- 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:
127
+ Paths in the config file are relative to the config file’s directory (project) or to the current directory when using `~/.mixgram/config.json`. **Project memory** is resolved relative to the current working directory (repo) when you use a global config, so docs stay in the repo. Defaults:
127
128
 
128
129
  | Option | Default | Description |
129
130
  |--------|---------|-------------|
130
131
  | `homeMemoryRoot` | `./home/memory` | Cross-project memory (Markdown files). |
131
- | `projectsRoot` | `./projects` | Project roots; each project may have `memory/` under it. |
132
+ | `projectMemoryRoot` | `./mixgram` | Project memory in the current repo (e.g. `mixgram/architecture/`, `mixgram/decisions/`). |
132
133
  | `sqlitePath` | `./.mixgram/index.db` | SQLite index (FTS5 + optional vectors). |
133
134
  | `watch` | `false` | Watch files and reindex on change. |
134
135
  | `indexing.reindexOnStartup` | `true` | Full reindex when server starts. |
@@ -143,7 +144,7 @@ import { run } from 'mixgram/src/mcp/server.js';
143
144
 
144
145
  await run({
145
146
  homeMemoryRoot: '/data/memory',
146
- projectsRoot: '/data/projects',
147
+ projectMemoryRoot: '/path/to/repo/mixgram',
147
148
  sqlitePath: '/data/.mixgram/index.db',
148
149
  watch: true
149
150
  });
@@ -169,8 +170,8 @@ Core flow: save Markdown-backed documents, search with FTS5, get context.
169
170
  }
170
171
  ```
171
172
 
172
- - **scope** `project` → file under `projects/<project>/memory/...`
173
- - **scope** `home` → file under `home/memory/...`
173
+ - **scope** `project` → file under `<repo>/mixgram/<type>/...` (e.g. `mixgram/architecture/`, `mixgram/decisions/`).
174
+ - **scope** `home` → file under `home/memory/...` (cross-project).
174
175
  - Same `topic_key` + scope + project → **update** existing doc; otherwise create.
175
176
 
176
177
  ### Search
@@ -238,12 +239,12 @@ Useful after cloning a repo or editing Markdown by hand:
238
239
  { "full": true }
239
240
  ```
240
241
 
241
- - `full: true` — rebuild entire index from `home/**/*.md` and `projects/**/memory/**/*.md`.
242
+ - `full: true` — rebuild entire index from `home/**/*.md` and `mixgram/**/*.md` (project memory in repo).
242
243
  - `full: false` (default) — incremental (by mtime).
243
244
 
244
245
  Manual edit example:
245
246
 
246
- 1. Edit a `.md` file under `home/memory` or `projects/<project>/memory`.
247
+ 1. Edit a `.md` file under `home/memory` or `mixgram/<type>/` in your repo.
247
248
  2. Call `mem_reindex({ full: true })` (or run with `watch: true` so changes are picked up).
248
249
  3. `mem_search` and `mem_get_observation` reflect the new content.
249
250
 
package/bin/mixgram.js CHANGED
@@ -31,6 +31,8 @@ function parseMcpArgs() {
31
31
  out._configPath = args[++i];
32
32
  } else if (a === '--home' && args[i + 1]) {
33
33
  out.homeMemoryRoot = args[++i];
34
+ } else if (a === '--project-memory' && args[i + 1]) {
35
+ out.projectMemoryRoot = args[++i];
34
36
  } else if (a === '--projects' && args[i + 1]) {
35
37
  out.projectsRoot = args[++i];
36
38
  } else if (a === '--sqlite-path' && args[i + 1]) {
@@ -81,6 +83,7 @@ function loadCliConfig() {
81
83
  envOverrides.embeddings = { ...(fileConfig.embeddings || {}), enabled: true };
82
84
  }
83
85
  if (process.env.MIXGRAM_HOME) envOverrides.homeMemoryRoot = process.env.MIXGRAM_HOME;
86
+ if (process.env.MIXGRAM_PROJECT_MEMORY) envOverrides.projectMemoryRoot = process.env.MIXGRAM_PROJECT_MEMORY;
84
87
  if (process.env.MIXGRAM_PROJECTS) envOverrides.projectsRoot = process.env.MIXGRAM_PROJECTS;
85
88
  if (process.env.MIXGRAM_SQLITE_PATH) envOverrides.sqlitePath = process.env.MIXGRAM_SQLITE_PATH;
86
89
  if (process.env.MIXGRAM_WATCH === '1' || process.env.MIXGRAM_WATCH === 'true') envOverrides.watch = true;
@@ -91,7 +94,8 @@ function loadCliConfig() {
91
94
  if (argvRest.embeddings && typeof merged.embeddings === 'object') {
92
95
  merged.embeddings = { ...merged.embeddings, ...argvRest.embeddings };
93
96
  }
94
- return { overrides: merged, baseDir };
97
+ const projectBaseDir = process.cwd();
98
+ return { overrides: merged, baseDir, projectBaseDir };
95
99
  }
96
100
 
97
101
  const MIXGRAM_ENTRY = {
@@ -216,11 +220,12 @@ mcp options (and env / config file):
216
220
  --embeddings Enable semantic search (or embeddings.enabled in config)
217
221
  --watch Watch files and reindex on change
218
222
  --home <path> Home memory root (default: ./home/memory)
223
+ --project-memory <path> Project memory root (default: ./mixgram, relative to repo)
219
224
  --projects <path> Projects root (default: ./projects)
220
225
  --sqlite-path <path> SQLite index path (default: ./.mixgram/index.db)
221
226
 
222
- Env: MIXGRAM_CONFIG, MIXGRAM_EMBEDDINGS_ENABLED, MIXGRAM_HOME, MIXGRAM_PROJECTS,
223
- MIXGRAM_SQLITE_PATH, MIXGRAM_WATCH
227
+ Env: MIXGRAM_CONFIG, MIXGRAM_EMBEDDINGS_ENABLED, MIXGRAM_HOME, MIXGRAM_PROJECT_MEMORY,
228
+ MIXGRAM_PROJECTS, MIXGRAM_SQLITE_PATH, MIXGRAM_WATCH
224
229
 
225
230
  Setup targets:
226
231
  cursor Cursor IDE
@@ -237,8 +242,8 @@ Config file: .mixgram/config.json or ~/.mixgram/config.json
237
242
 
238
243
  async function main() {
239
244
  if (SUBCOMMAND === 'mcp') {
240
- const { overrides, baseDir } = loadCliConfig();
241
- await run(overrides, baseDir)
245
+ const { overrides, baseDir, projectBaseDir } = loadCliConfig();
246
+ await run(overrides, baseDir, projectBaseDir)
242
247
  .then(() => {})
243
248
  .catch((err) => {
244
249
  console.error(err);
@@ -287,8 +292,8 @@ async function main() {
287
292
  }
288
293
  const toolDef = getToolByName(SUBCOMMAND);
289
294
  const args = parseToolArgs(toolDef, toolArgv);
290
- const { overrides, baseDir } = loadCliConfig();
291
- const config = loadConfig(overrides, baseDir);
295
+ const { overrides, baseDir, projectBaseDir } = loadCliConfig();
296
+ const config = loadConfig(overrides, baseDir, projectBaseDir);
292
297
  const handlers = createToolHandlers(config);
293
298
  try {
294
299
  const result = await handlers[SUBCOMMAND](args);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mixgram",
3
- "version": "1.0.2",
3
+ "version": "1.0.4",
4
4
  "description": "MCP memory server with Markdown source of truth and SQLite FTS5.",
5
5
  "keywords": [
6
6
  "mcp",
package/spec/run-tests.js CHANGED
@@ -17,10 +17,10 @@ import * as reporter from './reporter.js';
17
17
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mixgram-test-'));
18
18
  const config = loadConfig({
19
19
  homeMemoryRoot: path.join(tmpDir, 'home', 'memory'),
20
+ projectMemoryRoot: path.join(tmpDir, 'mixgram'),
20
21
  projectsRoot: path.join(tmpDir, 'projects'),
21
22
  sqlitePath: path.join(tmpDir, '.mixgram', 'index.db')
22
23
  });
23
- fs.mkdirSync(path.join(tmpDir, 'projects', 'castlebravo', 'memory'), { recursive: true });
24
24
  fs.mkdirSync(path.dirname(config.sqlitePath), { recursive: true });
25
25
 
26
26
  const h = createToolHandlers(config);
@@ -53,6 +53,7 @@ async function runScenarios() {
53
53
  if (scenario.name === 'Semantic / embeddings (save and search)' && !ctx.hSemantic) {
54
54
  const configSemantic = loadConfig({
55
55
  homeMemoryRoot: config.homeMemoryRoot,
56
+ projectMemoryRoot: config.projectMemoryRoot,
56
57
  projectsRoot: config.projectsRoot,
57
58
  sqlitePath: config.sqlitePath,
58
59
  embeddings: { enabled: true }
@@ -78,6 +79,7 @@ async function runLegacySemanticKnn() {
78
79
  const configSemantic = ctx.hSemantic
79
80
  ? loadConfig({
80
81
  homeMemoryRoot: config.homeMemoryRoot,
82
+ projectMemoryRoot: config.projectMemoryRoot,
81
83
  projectsRoot: config.projectsRoot,
82
84
  sqlitePath: config.sqlitePath,
83
85
  embeddings: { enabled: true }
@@ -43,6 +43,7 @@ export const scenarios = [
43
43
  reporter.step('mem_save', { title: decisionSqliteIndex.title, topic_key: decisionSqliteIndex.topic_key }, { id: s1.id, path: s1.path, created: s1.created });
44
44
  ok(s1.success && s1.id && s1.created === true, 'save success');
45
45
  ok(fs.existsSync(s1.path), 'file created');
46
+ ok(s1.path.includes('mixgram') || s1.path.replace(/\\/g, '/').includes('mixgram'), 'project doc under mixgram');
46
47
 
47
48
  const search1 = await h.mem_search({ query: 'derived SQLite index', project: PROJECT_NAME });
48
49
  const search1Parsed = parseRes(search1);
package/src/config.js CHANGED
@@ -2,6 +2,7 @@ import path from 'path';
2
2
 
3
3
  const DEFAULT_CONFIG = {
4
4
  homeMemoryRoot: './home/memory',
5
+ projectMemoryRoot: './mixgram',
5
6
  projectsRoot: './projects',
6
7
  sqlitePath: './.mixgram/index.db',
7
8
  watch: false,
@@ -38,19 +39,21 @@ const DEFAULT_CONFIG = {
38
39
  }
39
40
  };
40
41
 
41
- function resolvePaths(config, baseDir) {
42
+ function resolvePaths(config, baseDir, projectBaseDir = null) {
42
43
  const base = baseDir || process.cwd();
44
+ const projectBase = projectBaseDir ?? base;
43
45
  return {
44
46
  ...config,
45
47
  homeMemoryRoot: path.resolve(base, config.homeMemoryRoot),
48
+ projectMemoryRoot: path.resolve(projectBase, config.projectMemoryRoot ?? './mixgram'),
46
49
  projectsRoot: path.resolve(base, config.projectsRoot),
47
50
  sqlitePath: path.resolve(base, config.sqlitePath)
48
51
  };
49
52
  }
50
53
 
51
- function loadConfig(overrides = {}, baseDir) {
54
+ function loadConfig(overrides = {}, baseDir, projectBaseDir = null) {
52
55
  const config = { ...DEFAULT_CONFIG, ...overrides };
53
- return resolvePaths(config, baseDir);
56
+ return resolvePaths(config, baseDir, projectBaseDir);
54
57
  }
55
58
 
56
59
  export { DEFAULT_CONFIG, loadConfig, resolvePaths };
@@ -95,12 +95,20 @@ function indexDocument(config, docPath, rawContent, fileMtimeMs = null) {
95
95
 
96
96
  if (config?.embeddings?.enabled) {
97
97
  const newChunkIds = Array.from({ length: chunks.length }, (_, idx) => chunkId(id, idx));
98
- import('../embeddings/queue.js').then(({ enqueueChunks, markStale }) => {
99
- if (oldChunkIds.length) markStale(config, oldChunkIds);
100
- enqueueChunks(config, newChunkIds);
101
- });
98
+ import('../embeddings/queue.js')
99
+ .then(({ enqueueChunks, markStale }) => {
100
+ if (oldChunkIds.length) markStale(config, oldChunkIds);
101
+ enqueueChunks(config, newChunkIds);
102
+ })
103
+ .catch((err) => {
104
+ if (typeof process !== 'undefined' && process.stderr) {
105
+ process.stderr.write(`[mixgram] embeddings queue error: ${err?.message ?? err}\n`);
106
+ }
107
+ });
102
108
  if (oldChunkIds.length) {
103
- import('../embeddings/vectorStore.js').then(({ removeChunks }) => removeChunks(config, oldChunkIds).catch(() => {}));
109
+ import('../embeddings/vectorStore.js')
110
+ .then(({ removeChunks }) => removeChunks(config, oldChunkIds))
111
+ .catch(() => {});
104
112
  }
105
113
  }
106
114
 
@@ -111,8 +119,16 @@ function removeDocumentFromIndex(config, documentId) {
111
119
  const db = getDb(config);
112
120
  const chunkIds = db.prepare('SELECT id FROM document_chunks WHERE document_id = ?').all(documentId).map((r) => r.id);
113
121
  if (config?.embeddings?.enabled && chunkIds.length) {
114
- import('../embeddings/queue.js').then(({ markStale }) => markStale(config, chunkIds));
115
- import('../embeddings/vectorStore.js').then(({ removeChunks }) => removeChunks(config, chunkIds).catch(() => {}));
122
+ import('../embeddings/queue.js')
123
+ .then(({ markStale }) => markStale(config, chunkIds))
124
+ .catch((err) => {
125
+ if (typeof process !== 'undefined' && process.stderr) {
126
+ process.stderr.write(`[mixgram] embeddings markStale error: ${err?.message ?? err}\n`);
127
+ }
128
+ });
129
+ import('../embeddings/vectorStore.js')
130
+ .then(({ removeChunks }) => removeChunks(config, chunkIds))
131
+ .catch(() => {});
116
132
  }
117
133
  for (const cid of chunkIds) {
118
134
  db.prepare('DELETE FROM embedding_jobs WHERE chunk_id = ?').run(cid);
@@ -5,19 +5,19 @@ import { getDb } from '../../db/sqlite.js';
5
5
  import { indexDocument, removeDocumentFromIndex } from './indexer.js';
6
6
 
7
7
  /**
8
- * List all Markdown file paths under home and projects memory roots (absolute).
8
+ * List all Markdown file paths under home (cross-project) and project memory root (repo-local).
9
9
  */
10
10
  function listMarkdownPaths(config) {
11
11
  const homeRoot = config.homeMemoryRoot;
12
- const projectsRoot = config.projectsRoot;
12
+ const projectRoot = config.projectMemoryRoot;
13
13
  const out = [];
14
14
  if (fs.existsSync(homeRoot)) {
15
15
  const homeFiles = globSync('**/*.md', { cwd: homeRoot });
16
16
  out.push(...homeFiles.map((p) => path.join(homeRoot, p)));
17
17
  }
18
- if (fs.existsSync(projectsRoot)) {
19
- const projectFiles = globSync('**/memory/**/*.md', { cwd: projectsRoot });
20
- out.push(...projectFiles.map((p) => path.join(projectsRoot, p)));
18
+ if (projectRoot && fs.existsSync(projectRoot)) {
19
+ const projectFiles = globSync('**/*.md', { cwd: projectRoot });
20
+ out.push(...projectFiles.map((p) => path.join(projectRoot, p)));
21
21
  }
22
22
  return out;
23
23
  }
package/src/fs/paths.js CHANGED
@@ -42,13 +42,13 @@ function documentPath(config, { scope, project, type, topic_key, id }) {
42
42
  return path.join(root, typeDir, baseName);
43
43
  }
44
44
 
45
- if (scope === 'project' && project) {
46
- const root = path.join(config.projectsRoot, project, 'memory');
45
+ if (scope === 'project') {
46
+ const root = config.projectMemoryRoot;
47
47
  return path.join(root, typeDir, baseName);
48
48
  }
49
49
 
50
- const root = config.projectsRoot;
51
- return path.join(root, '_default', 'memory', typeDir, baseName);
50
+ const root = config.projectMemoryRoot;
51
+ return path.join(root, typeDir, baseName);
52
52
  }
53
53
 
54
54
  function ensureDir(filePath) {
package/src/fs/watcher.js CHANGED
@@ -5,17 +5,17 @@ import { indexDocument, removeDocumentFromIndex } from '../core/indexing/indexer
5
5
  import { getDocumentIdByPath } from '../core/indexing/reindex.js';
6
6
 
7
7
  /**
8
- * Start watching home and projects memory roots for .md changes.
8
+ * Start watching home (cross-project) and project memory root (repo-local) for .md changes.
9
9
  * On add/change: index the file. On unlink: remove from index by path.
10
10
  * @param {object} config - resolved config
11
11
  * @returns {import('chokidar').FSWatcher} watcher instance (call .close() to stop)
12
12
  */
13
13
  function startWatcher(config) {
14
14
  const homeRoot = config.homeMemoryRoot;
15
- const projectsRoot = config.projectsRoot;
15
+ const projectRoot = config.projectMemoryRoot;
16
16
  const patterns = [];
17
17
  if (homeRoot) patterns.push(path.join(homeRoot, '**/*.md'));
18
- if (projectsRoot) patterns.push(path.join(projectsRoot, '**/memory/**/*.md'));
18
+ if (projectRoot) patterns.push(path.join(projectRoot, '**/*.md'));
19
19
  if (patterns.length === 0) return null;
20
20
 
21
21
  const watcher = chokidar.watch(patterns, {
@@ -39,8 +39,10 @@ function startWatcher(config) {
39
39
  } catch (_) {}
40
40
  })
41
41
  .on('unlink', (filePath) => {
42
- const id = getDocumentIdByPath(config, filePath);
43
- if (id) removeDocumentFromIndex(config, id);
42
+ try {
43
+ const id = getDocumentIdByPath(config, filePath);
44
+ if (id) removeDocumentFromIndex(config, id);
45
+ } catch (_) {}
44
46
  });
45
47
 
46
48
  return watcher;
package/src/mcp/server.js CHANGED
@@ -4,8 +4,8 @@ import { loadConfig } from '../config.js';
4
4
  import { createToolHandlers } from './tools.js';
5
5
  import { getToolDefinitions } from './tool-registry.js';
6
6
 
7
- function createServer(configOverrides = {}, baseDir = null) {
8
- const config = loadConfig(configOverrides, baseDir);
7
+ function createServer(configOverrides = {}, baseDir = null, projectBaseDir = null) {
8
+ const config = loadConfig(configOverrides, baseDir, projectBaseDir);
9
9
  const mcpServer = new McpServer(
10
10
  { name: 'mixgram', version: '1.0.0' },
11
11
  { capabilities: { tools: { listChanged: true } } }
@@ -26,19 +26,46 @@ function createServer(configOverrides = {}, baseDir = null) {
26
26
  return { mcpServer, config };
27
27
  }
28
28
 
29
- async function run(configOverrides = {}, baseDir = null) {
30
- const { mcpServer, config } = createServer(configOverrides, baseDir);
29
+ async function run(configOverrides = {}, baseDir = null, projectBaseDir = null) {
30
+ if (typeof process !== 'undefined') {
31
+ process.on('unhandledRejection', (reason, promise) => {
32
+ if (process.stderr) {
33
+ process.stderr.write(`[mixgram] unhandledRejection: ${reason}\n`);
34
+ }
35
+ });
36
+ }
37
+
38
+ const { mcpServer, config } = createServer(configOverrides, baseDir, projectBaseDir);
39
+
31
40
  if (config.indexing?.reindexOnStartup) {
32
- const { fullReindex } = await import('../core/indexing/reindex.js');
33
- fullReindex(config);
41
+ try {
42
+ const { fullReindex } = await import('../core/indexing/reindex.js');
43
+ fullReindex(config);
44
+ } catch (err) {
45
+ if (typeof process !== 'undefined' && process.stderr) {
46
+ process.stderr.write(`[mixgram] reindex on startup failed: ${err?.message ?? err}\n`);
47
+ }
48
+ }
34
49
  }
35
50
  if (config.watch) {
36
- const { startWatcher } = await import('../fs/watcher.js');
37
- startWatcher(config);
51
+ try {
52
+ const { startWatcher } = await import('../fs/watcher.js');
53
+ startWatcher(config);
54
+ } catch (err) {
55
+ if (typeof process !== 'undefined' && process.stderr) {
56
+ process.stderr.write(`[mixgram] watcher start failed: ${err?.message ?? err}\n`);
57
+ }
58
+ }
38
59
  }
39
60
  if (config.embeddings?.enabled) {
40
- const { startWorker } = await import('../core/embeddings/worker.js');
41
- startWorker(config);
61
+ try {
62
+ const { startWorker } = await import('../core/embeddings/worker.js');
63
+ startWorker(config);
64
+ } catch (err) {
65
+ if (typeof process !== 'undefined' && process.stderr) {
66
+ process.stderr.write(`[mixgram] embeddings worker start failed: ${err?.message ?? err}\n`);
67
+ }
68
+ }
42
69
  }
43
70
  const transport = new StdioServerTransport();
44
71
  await mcpServer.connect(transport);