@maximalabs/dev-mcp-suite 0.0.0-stage → 3.6.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 (68) hide show
  1. package/.env.example +69 -0
  2. package/CHANGELOG.md +271 -0
  3. package/CODEX_DEV_MCP_GUIDE.md +297 -0
  4. package/LICENSE +21 -0
  5. package/README.md +193 -2
  6. package/armada/package.json +14 -0
  7. package/armada/server.js +329 -0
  8. package/backfill-sessions-v2.mjs +288 -0
  9. package/bin/_meta.mjs +73 -0
  10. package/bin/armada-mcp.mjs +12 -0
  11. package/bin/checkpoint.mjs +9 -0
  12. package/bin/context-pack.mjs +9 -0
  13. package/bin/devjournal.mjs +9 -0
  14. package/bin/init.mjs +25 -0
  15. package/bin/project-memory.mjs +10 -0
  16. package/bin/provider-smoke.mjs +278 -0
  17. package/bin/prune.mjs +158 -0
  18. package/bin/stats.mjs +101 -0
  19. package/bin/ui.mjs +5 -0
  20. package/checkpoint/package.json +14 -0
  21. package/checkpoint/server.js +318 -0
  22. package/context-pack/package.json +14 -0
  23. package/context-pack/server.js +747 -0
  24. package/devjournal/compress.js +75 -0
  25. package/devjournal/env.js +3 -0
  26. package/devjournal/package.json +14 -0
  27. package/devjournal/provider-chain.js +109 -0
  28. package/devjournal/rerank.js +120 -0
  29. package/devjournal/server.js +415 -0
  30. package/docs/ROADMAP.md +77 -0
  31. package/docs/clients/antigravity.md +52 -0
  32. package/docs/clients/claude-code.md +46 -0
  33. package/docs/clients/codex.md +39 -0
  34. package/docs/clients/generic-mcp.md +45 -0
  35. package/docs/clients/hermes.md +48 -0
  36. package/docs/configuration.md +123 -0
  37. package/docs/privacy.md +39 -0
  38. package/docs/providers.md +13 -0
  39. package/docs/superpowers/plans/2026-06-15-hardening-v1-2-implementation.md +60 -0
  40. package/docs/superpowers/plans/2026-06-15-provider-chain-v1-1-implementation.md +65 -0
  41. package/docs/superpowers/plans/2026-06-15-provider-client-agnostic-config.md +41 -0
  42. package/docs/superpowers/plans/2026-06-15-trust-release-implementation.md +62 -0
  43. package/docs/superpowers/plans/2026-06-18-v1-5-0-knowledge-graph.md +792 -0
  44. package/docs/superpowers/specs/2026-06-15-provider-chain-v1-1-design.md +89 -0
  45. package/docs/superpowers/specs/2026-06-15-trust-release-design.md +164 -0
  46. package/docs/superpowers/specs/2026-06-18-dev-mcp-suite-v1-5-0-knowledge-graph-design.md +386 -0
  47. package/docs/superpowers/specs/2026-07-22-v2-0-0-peak-intelligence.md +50 -0
  48. package/docs/superpowers/specs/2026-07-22-v3-0-0-god-tier.md +32 -0
  49. package/lib/init-wizard.js +120 -0
  50. package/lib/provider-smoke.js +234 -0
  51. package/lib/prune.js +114 -0
  52. package/lib/stats.js +269 -0
  53. package/lib/ui-server.js +151 -0
  54. package/lib/update-check.js +125 -0
  55. package/package.json +71 -4
  56. package/project-memory/auto-indexer.js +152 -0
  57. package/project-memory/dedup.js +49 -0
  58. package/project-memory/embedding.js +174 -0
  59. package/project-memory/env.js +3 -0
  60. package/project-memory/global-index.js +46 -0
  61. package/project-memory/graph.js +93 -0
  62. package/project-memory/local-embed.js +92 -0
  63. package/project-memory/package.json +14 -0
  64. package/project-memory/provider-chain.js +109 -0
  65. package/project-memory/rerank.js +120 -0
  66. package/project-memory/server.js +931 -0
  67. package/project-memory/swarm.js +56 -0
  68. package/run-tests.mjs +54 -0
@@ -0,0 +1,415 @@
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * Dev Journal MCP Server for Codex
5
+ *
6
+ * Per-project session timeline + handoff so you never lose your place when a
7
+ * session hits "input too long" / gets compacted / you start fresh.
8
+ *
9
+ * Core idea:
10
+ * - journal_handoff: at end of a work block, store "what I did + open
11
+ * questions + next steps + active files". One canonical resume point.
12
+ * - journal_resume: at start of a new session, get the latest handoff +
13
+ * recent entries, so you (or the agent) can continue immediately.
14
+ *
15
+ * Storage: append-only JSONL per project (default
16
+ * ~/.codex/memories/journal/<project-slug>/journal.jsonl) + a
17
+ * handoff.json for the latest canonical resume state. Human-readable
18
+ * journal.md mirror is also maintained.
19
+ *
20
+ * Tools: journal_log, journal_handoff, journal_resume,
21
+ * journal_timeline, journal_clear_handoff
22
+ */
23
+
24
+ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
25
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
26
+ import {
27
+ CallToolRequestSchema,
28
+ ListToolsRequestSchema,
29
+ } from "@modelcontextprotocol/sdk/types.js";
30
+ import fs from "fs/promises";
31
+ import path from "path";
32
+ import os from "os";
33
+ import crypto from "crypto";
34
+ import { rerank, rerankConfig } from "./rerank.js";
35
+ import { deterministicEnabled } from "./env.js";
36
+ import { compressJournalEntries } from "./compress.js";
37
+
38
+ const ROOT =
39
+ process.env.JOURNAL_DIR ||
40
+ path.join(os.homedir(), ".ai-shared-memory", "journal");
41
+
42
+ const MAX_TEXT = 20_000;
43
+
44
+ function slug(dir) {
45
+ const resolved = path.resolve(dir || process.cwd());
46
+ const base = path.basename(resolved) || "root";
47
+ const hash = crypto.createHash("sha1").update(resolved).digest("hex").slice(0, 8);
48
+ return `${base.replace(/[^a-zA-Z0-9._-]/g, "-").slice(0, 40)}-${hash}`;
49
+ }
50
+ function nowIso() { return new Date().toISOString(); }
51
+ function clip(v, name, max, req = true) {
52
+ const t = String(v ?? "");
53
+ if (req && !t.trim()) throw new Error(`${name} is required`);
54
+ if (t.length > max) throw new Error(`${name} exceeds ${max} chars`);
55
+ return t;
56
+ }
57
+ function asList(v) {
58
+ if (Array.isArray(v)) return v.map((x) => String(x).trim()).filter(Boolean);
59
+ if (typeof v === "string" && v.trim()) return v.split("\n").map((s) => s.replace(/^[-*]\s*/, "").trim()).filter(Boolean);
60
+ return [];
61
+ }
62
+
63
+ class DevJournalServer {
64
+ constructor() {
65
+ this.server = new Server({ name: "devjournal", version: "1.0.0" }, { capabilities: { tools: {} } });
66
+ this.setup();
67
+ }
68
+
69
+ paths(dir) {
70
+ const s = slug(dir);
71
+ const d = path.join(ROOT, s);
72
+ return {
73
+ slug: s,
74
+ root: path.resolve(dir || process.cwd()),
75
+ dir: d,
76
+ jsonl: path.join(d, "journal.jsonl"),
77
+ md: path.join(d, "journal.md"),
78
+ handoff: path.join(d, "handoff.json"),
79
+ };
80
+ }
81
+
82
+ async append(p, entry) {
83
+ await fs.mkdir(p.dir, { recursive: true });
84
+ await fs.appendFile(p.jsonl, JSON.stringify(entry) + "\n");
85
+ const md = `\n## ${entry.ts} — ${entry.type}${entry.title ? `: ${entry.title}` : ""}\n${entry.body || ""}\n`;
86
+ await fs.appendFile(p.md, md);
87
+ }
88
+
89
+ async readEntries(p, limit = 50) {
90
+ try {
91
+ const raw = await fs.readFile(p.jsonl, "utf8");
92
+ const rows = raw.split("\n").filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
93
+ return rows.slice(-limit);
94
+ } catch { return []; }
95
+ }
96
+
97
+ setup() {
98
+ this.server.setRequestHandler(ListToolsRequestSchema, () => ({
99
+ tools: [
100
+ {
101
+ name: "journal_log",
102
+ description: "Append a quick timestamped entry (note/decision/blocker/done) to the project journal.",
103
+ inputSchema: {
104
+ type: "object",
105
+ properties: {
106
+ title: { type: "string", description: "Short summary" },
107
+ body: { type: "string", description: "Details (Markdown ok)" },
108
+ type: { type: "string", description: "note | decision | blocker | done | idea", default: "note" },
109
+ ts: { type: "string", description: "Optional ISO timestamp to backdate the entry" },
110
+ dir: { type: "string", description: "Project directory (defaults to CWD)" },
111
+ },
112
+ required: ["title"],
113
+ },
114
+ },
115
+ {
116
+ name: "journal_handoff",
117
+ description: "Save the canonical resume point for this project: what was done, open questions, next steps, and active files. Call before ending a session or when context is about to be compacted.",
118
+ inputSchema: {
119
+ type: "object",
120
+ properties: {
121
+ summary: { type: "string", description: "What was accomplished this session" },
122
+ next_steps: { type: "array", items: { type: "string" }, description: "Ordered next actions" },
123
+ open_questions: { type: "array", items: { type: "string" }, description: "Unresolved questions" },
124
+ active_files: { type: "array", items: { type: "string" }, description: "Files currently in focus" },
125
+ dir: { type: "string", description: "Project directory (defaults to CWD)" },
126
+ },
127
+ required: ["summary"],
128
+ },
129
+ },
130
+ {
131
+ name: "journal_resume",
132
+ description: "Get the latest handoff plus recent journal entries to resume work in a fresh session. Call this FIRST in a new session instead of re-pasting context.",
133
+ inputSchema: {
134
+ type: "object",
135
+ properties: {
136
+ dir: { type: "string", description: "Project directory (defaults to CWD)" },
137
+ recent: { type: "number", description: "How many recent entries to include", default: 8 },
138
+ },
139
+ },
140
+ },
141
+ {
142
+ name: "journal_timeline",
143
+ description: "Show recent journal entries (newest last) for the project.",
144
+ inputSchema: {
145
+ type: "object",
146
+ properties: {
147
+ dir: { type: "string", description: "Project directory (defaults to CWD)" },
148
+ limit: { type: "number", description: "Max entries", default: 20 },
149
+ type: { type: "string", description: "Filter by type (optional)" },
150
+ },
151
+ },
152
+ },
153
+ {
154
+ name: "journal_search",
155
+ description: "Find the most relevant journal entries for a query. Uses keyword prefilter + LLM rerank (9router Kiro) when available, else keyword scoring. Use to recall what you did about a topic across past sessions.",
156
+ inputSchema: {
157
+ type: "object",
158
+ properties: {
159
+ query: { type: "string", description: "What you're looking for" },
160
+ dir: { type: "string", description: "Project directory (defaults to CWD)" },
161
+ limit: { type: "number", description: "Max entries", default: 5 },
162
+ },
163
+ required: ["query"],
164
+ },
165
+ },
166
+ {
167
+ name: "journal_clear_handoff",
168
+ description: "Clear the current canonical handoff (e.g., after fully resuming).",
169
+ inputSchema: {
170
+ type: "object",
171
+ properties: { dir: { type: "string", description: "Project directory (defaults to CWD)" } },
172
+ },
173
+ },
174
+ {
175
+ name: "journal_daily",
176
+ description: "Read or create today's daily note for the project (Obsidian-style YYYY-MM-DD.md under daily/). Append mode adds a line; read mode returns the note. Great for a vibecoder's daily log that survives compaction.",
177
+ inputSchema: {
178
+ type: "object",
179
+ properties: {
180
+ dir: { type: "string", description: "Project directory (defaults to CWD)" },
181
+ date: { type: "string", description: "Optional YYYY-MM-DD (defaults to today)" },
182
+ append: { type: "string", description: "If provided, append this line to the daily note" },
183
+ },
184
+ },
185
+ },
186
+ {
187
+ name: "initialize_agent_session",
188
+ description: "Initialize the current agent session. Run this ONCE when the agent starts in a new project to perform a handshake and get contextual handoff.",
189
+ inputSchema: {
190
+ type: "object",
191
+ properties: {
192
+ dir: { type: "string", description: "Project directory (defaults to CWD)" },
193
+ },
194
+ },
195
+ },
196
+ {
197
+ name: "journal_standup",
198
+ description: "Generate a formatted developer standup digest (Completed, In Progress, Blockers, Decisions) from recent journal logs and active handoff.",
199
+ inputSchema: {
200
+ type: "object",
201
+ properties: {
202
+ dir: { type: "string", description: "Project directory (defaults to CWD)" },
203
+ sinceHours: { type: "number", description: "Hours to look back (default: 24)", default: 24 },
204
+ },
205
+ },
206
+ },
207
+ {
208
+ name: "journal_compress",
209
+ description: "Compress and summarize verbose journal timeline entries into a ultra-compact (~500 token) snapshot to prevent context window compaction traps.",
210
+ inputSchema: {
211
+ type: "object",
212
+ properties: {
213
+ dir: { type: "string", description: "Project directory (defaults to CWD)" },
214
+ limit: { type: "number", description: "Max entries to process", default: 50 },
215
+ maxTokens: { type: "number", description: "Target max tokens", default: 500 },
216
+ },
217
+ },
218
+ },
219
+ ],
220
+ }));
221
+
222
+ this.server.setRequestHandler(CallToolRequestSchema, async (req) => {
223
+ const { name, arguments: args } = req.params;
224
+ try {
225
+ switch (name) {
226
+ case "journal_log": return await this.log(args || {});
227
+ case "journal_handoff": return await this.doHandoff(args || {});
228
+ case "journal_resume": return await this.resume(args || {});
229
+ case "journal_timeline": return await this.timeline(args || {});
230
+ case "journal_search": return await this.search(args || {});
231
+ case "journal_clear_handoff": return await this.clearHandoff(args || {});
232
+ case "journal_daily": return await this.daily(args || {});
233
+ case "initialize_agent_session": return await this.initializeAgent(args || {});
234
+ case "journal_compress": return await this.compress(args || {});
235
+ default: throw new Error(`Unknown tool: ${name}`);
236
+ }
237
+ } catch (e) {
238
+ return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
239
+ }
240
+ });
241
+ }
242
+
243
+ async log({ title, body, type = "note", dir, ts: tsArg }) {
244
+ title = clip(title, "title", 500);
245
+ body = clip(body, "body", MAX_TEXT, false);
246
+ const p = this.paths(dir);
247
+ const ts = (tsArg && /^\d{4}-\d{2}-\d{2}/.test(String(tsArg))) ? String(tsArg) : nowIso();
248
+ const entry = { ts, type, title, body };
249
+ await this.append(p, entry);
250
+ await this.appendDaily(p, ts.slice(0, 10), `- [${type}] ${title}${body ? ` — ${body.split("\n")[0].slice(0, 160)}` : ""}`);
251
+ return { content: [{ type: "text", text: `Logged [${type}] "${title}" to ${p.slug}` }] };
252
+ }
253
+
254
+ // Obsidian-style daily note: one file per date under daily/. Read or append.
255
+ async appendDaily(p, date, line) {
256
+ const dir = path.join(p.dir, "daily");
257
+ await fs.mkdir(dir, { recursive: true });
258
+ const file = path.join(dir, `${date}.md`);
259
+ const stamp = new Date().toISOString().slice(11, 19);
260
+ await fs.appendFile(file, `- ${stamp} ${line}\n`);
261
+ }
262
+
263
+ async daily({ dir, date, append } = {}) {
264
+ const p = this.paths(dir);
265
+ const day = (date && /^\d{4}-\d{2}-\d{2}$/.test(String(date))) ? String(date) : nowIso().slice(0, 10);
266
+ const dirPath = path.join(p.dir, "daily");
267
+ const file = path.join(dirPath, `${day}.md`);
268
+ if (append && String(append).trim()) {
269
+ await this.appendDaily(p, day, String(append).trim());
270
+ return { content: [{ type: "text", text: `Appended to daily note ${day}.md for ${p.slug}` }] };
271
+ }
272
+ let text;
273
+ try { text = await fs.readFile(file, "utf8"); }
274
+ catch { return { content: [{ type: "text", text: `No daily note for ${day} in ${p.slug} yet.` }] }; }
275
+ return { content: [{ type: "text", text: `# Daily — ${day}\n\n${text}` }] };
276
+ }
277
+
278
+ async doHandoff({ summary, next_steps, open_questions, active_files, dir }) {
279
+ summary = clip(summary, "summary", MAX_TEXT);
280
+ const p = this.paths(dir);
281
+ const handoff = {
282
+ ts: nowIso(),
283
+ summary,
284
+ next_steps: asList(next_steps),
285
+ open_questions: asList(open_questions),
286
+ active_files: asList(active_files),
287
+ };
288
+ await fs.mkdir(p.dir, { recursive: true });
289
+ await fs.writeFile(p.handoff, JSON.stringify(handoff, null, 2));
290
+ await this.append(p, { ts: handoff.ts, type: "handoff", title: "Session handoff", body: summary });
291
+ return { content: [{ type: "text", text: `Handoff saved for ${p.slug}\nNext steps: ${handoff.next_steps.length}, open questions: ${handoff.open_questions.length}, active files: ${handoff.active_files.length}` }] };
292
+ }
293
+
294
+ async resume({ dir, recent = 8 }) {
295
+ const p = this.paths(dir);
296
+ let handoff = null;
297
+ try { handoff = JSON.parse(await fs.readFile(p.handoff, "utf8")); } catch { /* none */ }
298
+ const entries = await this.readEntries(p, Math.max(1, Math.min(50, recent)));
299
+
300
+ if (!handoff && entries.length === 0) {
301
+ return { content: [{ type: "text", text: `No journal for ${p.slug} yet. Use journal_handoff / journal_log to start.` }] };
302
+ }
303
+
304
+ const out = [`# Resume: ${p.slug}`, `Project path: ${p.root}`];
305
+ if (handoff) {
306
+ out.push(`\n## Latest handoff (${handoff.ts})`);
307
+ out.push(handoff.summary);
308
+ if (handoff.next_steps?.length) out.push(`\n### Next steps\n` + handoff.next_steps.map((s, i) => `${i + 1}. ${s}`).join("\n"));
309
+ if (handoff.open_questions?.length) out.push(`\n### Open questions\n` + handoff.open_questions.map((s) => `- ${s}`).join("\n"));
310
+ if (handoff.active_files?.length) out.push(`\n### Active files\n` + handoff.active_files.map((s) => `- ${s}`).join("\n"));
311
+ } else {
312
+ out.push(`\n(No canonical handoff saved — showing recent entries only.)`);
313
+ }
314
+ if (entries.length) {
315
+ out.push(`\n## Recent entries`);
316
+ out.push(entries.map((e) => `- ${e.ts} [${e.type}] ${e.title}`).join("\n"));
317
+ }
318
+ return { content: [{ type: "text", text: out.join("\n") }] };
319
+ }
320
+
321
+ async timeline({ dir, limit = 20, type }) {
322
+ const p = this.paths(dir);
323
+ let entries = await this.readEntries(p, 200);
324
+ if (type) entries = entries.filter((e) => e.type === type);
325
+ entries = entries.slice(-Math.max(1, Math.min(200, limit)));
326
+ if (!entries.length) return { content: [{ type: "text", text: `No journal entries for ${p.slug}${type ? ` of type ${type}` : ""}.` }] };
327
+ const lines = entries.map((e) => `- ${e.ts} [${e.type}] ${e.title}${e.body ? `\n ${e.body.split("\n")[0].slice(0, 120)}` : ""}`);
328
+ return { content: [{ type: "text", text: `Timeline for ${p.slug} (${entries.length}):\n${lines.join("\n")}` }] };
329
+ }
330
+
331
+ async search({ query, dir, limit = 5 }) {
332
+ query = clip(query, "query", 2000);
333
+ const p = this.paths(dir);
334
+ const entries = await this.readEntries(p, 200);
335
+ if (!entries.length) return { content: [{ type: "text", text: `No journal entries for ${p.slug}.` }] };
336
+
337
+ const want = Math.max(1, Math.min(20, limit));
338
+ const q = new Set((query.toLowerCase().match(/[a-z0-9_./-]{2,}/g) || []));
339
+ const score = (e) => {
340
+ let sc = 0;
341
+ const hay = `${e.title || ""} ${e.body || ""} ${e.type || ""}`.toLowerCase();
342
+ const toks = new Set(hay.match(/[a-z0-9_./-]{2,}/g) || []);
343
+ for (const t of q) if (toks.has(t)) sc += 1;
344
+ return sc;
345
+ };
346
+
347
+ let ranked = entries.map((e, i) => ({ e, i, sc: score(e) }))
348
+ .sort((a, b) => b.sc - a.sc || b.i - a.i);
349
+ let pool = ranked.filter((x) => x.sc > 0).slice(0, 20);
350
+ let mode = deterministicEnabled() ? "deterministic" : "keyword";
351
+ if (pool.length === 0 && rerankConfig().enabled) {
352
+ pool = ranked.slice(0, 20); // fall back to recent for semantic-style queries
353
+ }
354
+
355
+ let result = pool.slice(0, want).map((x) => x.e);
356
+ if (rerankConfig().enabled && pool.length > 1) {
357
+ const cands = pool.map((x) => ({ id: String(x.i), title: x.e.title || "(no title)", snippet: x.e.body || x.e.type || "" }));
358
+ const order = await rerank(query, cands, want);
359
+ if (order) {
360
+ mode = "rerank";
361
+ const byId = new Map(pool.map((x) => [String(x.i), x.e]));
362
+ const picked = order.map((id) => byId.get(id)).filter(Boolean).slice(0, want);
363
+ if (picked.length) result = picked;
364
+ }
365
+ }
366
+
367
+ if (!result.length) return { content: [{ type: "text", text: `No relevant journal entries for "${query}" in ${p.slug}.` }] };
368
+ const lines = result.map((e) => `- ${e.ts} [${e.type}] ${e.title}${e.body ? `\n ${e.body.split("\n")[0].slice(0, 160)}` : ""}`);
369
+ return { content: [{ type: "text", text: `Journal search for "${query}" in ${p.slug} [${mode}]:\n${lines.join("\n")}` }] };
370
+ }
371
+
372
+ async clearHandoff({ dir }) {
373
+ const p = this.paths(dir);
374
+ await fs.unlink(p.handoff).catch(() => {});
375
+ return { content: [{ type: "text", text: `Cleared handoff for ${p.slug}` }] };
376
+ }
377
+
378
+ async initializeAgent({ dir }) {
379
+ const agentName = process.env.MCP_AGENT_NAME || 'Unknown-Agent';
380
+ const resumeData = await this.resume({ dir, recent: 5 });
381
+
382
+ let rules = "";
383
+ try {
384
+ const p = this.paths(dir);
385
+ const rulePath = path.join(p.root, ".ai", "AGENTS.md");
386
+ const r = await fs.readFile(rulePath, "utf8");
387
+ rules = `\n\n## Project Rules (.ai/AGENTS.md)\n${r}`;
388
+ } catch {
389
+ try {
390
+ const rootRule = path.join(this.paths(dir).root, "AGENTS.md");
391
+ const rr = await fs.readFile(rootRule, "utf8");
392
+ rules = `\n\n## Project Rules (AGENTS.md)\n${rr}`;
393
+ } catch {}
394
+ }
395
+
396
+ const greeting = `# Universal MCP Handshake\nAgent: ${agentName}\n\n`;
397
+ const content = greeting + resumeData.content[0].text + rules;
398
+
399
+ return { content: [{ type: "text", text: content }] };
400
+ }
401
+
402
+ async compress({ dir, limit = 50, maxTokens = 500 }) {
403
+ const p = this.paths(dir);
404
+ const res = await compressJournalEntries(p.dir, p.slug, { limit, maxTokens });
405
+ return { content: [{ type: "text", text: res.compressedText }] };
406
+ }
407
+
408
+ async run() {
409
+ const t = new StdioServerTransport();
410
+ await this.server.connect(t);
411
+ console.error(`Dev Journal MCP server running on stdio (store: ${ROOT})`);
412
+ }
413
+ }
414
+
415
+ new DevJournalServer().run().catch(console.error);
@@ -0,0 +1,77 @@
1
+ # 🚀 Rencana Kerja & Roadmap Masa Depan — @maximalabs/dev-mcp-suite
2
+
3
+ > **Repository:** [MaximaLabs/dev-mcp-suite](https://github.com/MaximaLabs/dev-mcp-suite)
4
+ > **Versi Terbaru:** `v3.5.0` (Token-Dense Briefing, Standup Digest & Semantic Session Import)
5
+ > **Lisensi:** MIT
6
+
7
+ ---
8
+
9
+ ## 📌 Status Terkini (v3.5.0)
10
+
11
+ Rilis `v3.5.0` telah dirilis & dipublikasikan ke NPMJS dengan pencapaian:
12
+ - ✅ **Token-Dense Briefing (`pack_dense_brief`)**: Overviews ringkas berdensitas tinggi untuk menghemat 30–50% context window token saat inisialisasi sesi.
13
+ - ✅ **Daily Standup Generator (`journal_standup`)**: Ringkasan otomatis handoff, bugfix terbaru, dan blocker lintas sesi.
14
+ - ✅ **Direct Session Log Importer (`memory_import_session`)**: Ekstraksi keputusan arsitektur langsung dari file `.jsonl`/`.log` sesi agent.
15
+ - ✅ **Fast Substring & Task Finder (`pack_find_todos`, `pack_search`)**: Pencarian TODO dan substring konten tanpa spawn proses eksternal.
16
+ - ✅ **Unified Multi-File Checkpoint (`checkpoint_diff`)**: Deteksi perubahan file lokal sebelum refactoring masif.
17
+ - ✅ **Stabilitas & Test**: **113 / 113 unit test (100% PASS)** di seluruh 4 server MCP + utility CLI.
18
+
19
+ ---
20
+
21
+ ## 🎯 Roadmap Pengembangan Kedepan
22
+
23
+ ```mermaid
24
+ graph TD
25
+ v35["v3.5.0 (Current)
26
+ Dense Brief & Standup Digest"] --> v36["v3.6.0 (Q3 2026)
27
+ WASM / ONNX Local Offline Vector Embeddings"]
28
+ v36 --> v37["v3.7.0 (Q4 2026)
29
+ Real-Time SSE Web Dashboard Telemetry"]
30
+ v37 --> v40["v4.0.0 (Q1 2027)
31
+ Autonomous Multi-Agent Swarm Coordinator"]
32
+ ```
33
+
34
+ ---
35
+
36
+ ### 1. 🟢 v3.6.0 — Pure Offline ONNX / WASM Embeddings
37
+ > **Fokus:** Menjadikan semantic search `project-memory` 100% mandiri tanpa ketergantungan API eksternal saat offline.
38
+
39
+ - [ ] **Engine Embedding Lokal (WASM/ONNX)**:
40
+ - Integrasi model ringan (`all-MiniLM-L6-v2` / `bge-small-en-v1.5`) via `@xenova/transformers` / ONNX runtime.
41
+ - Semantic similarity search berjalan mulus saat laptop offline atau di jaringan terbatas.
42
+ - [ ] **Hybrid Search Ranking**:
43
+ - Algoritma gabungan BM25 keyword matching + cosine vector similarity score.
44
+ - [ ] **Zero-Dependency Vector Cache**:
45
+ - Penyimpanan vektor lokal teroptimasi di `.ai-shared-memory/vectors/` tanpa database eksternal.
46
+
47
+ ---
48
+
49
+ ### 2. 🔵 v3.7.0 — Real-Time Live Telemetry Web Dashboard (`mcp-ui`)
50
+ > **Fokus:** Visualisasi interaktif realtime saat subagent dan developer bekerja.
51
+
52
+ - [ ] **Live SSE / WebSocket Event Stream**:
53
+ - Live reload di `http://localhost:3333` saat agent memanggil `checkpoint_create`, `memory_save`, atau `journal_log`.
54
+ - [ ] **Visual 3D Knowledge Graph Explorer**:
55
+ - Tampilan visual relasi antar catatan Obsidian vault dan dependensi project.
56
+ - [ ] **Interactive Checkpoint Rollback**:
57
+ - Kemampuan rollback / restore checkpoint file langsung dari web GUI.
58
+
59
+ ---
60
+
61
+ ### 3. 🟣 v4.0.0 — Autonomous Multi-Agent Swarm Coordinator
62
+ > **Fokus:** Koordinasi tim AI (Antigravity, Hermes, Claude Code, Codex CLI) pada codebase enterprise.
63
+
64
+ - [ ] **Distributed File Lock & Conflict Resolver (`swarm_mutex`)**:
65
+ - Mencegah dua agent mengedit file yang sama secara bersamaan.
66
+ - [ ] **Shared Memory Cross-Linking (`memory_crosslink`)**:
67
+ - Memori dan solusi masalah dari proyek A otomatis dapat di-recall saat menangani proyek B.
68
+ - [ ] **Automated Code Review Agent Hook**:
69
+ - Integrasi pre-commit / pre-push guard yang memvalidasi blast radius sebelum commit dibuat.
70
+
71
+ ---
72
+
73
+ ### 🟡 Peningkatan Berkelanjutan (Ongoing Maintenance)
74
+ - [x] **CI/CD Auto-Publish on Tag**:
75
+ - GitHub Actions workflow (`.github/workflows/publish.yml`) untuk test & auto-publish ke npmjs saat git tag di-push.
76
+ - [x] **Universal Client Detection**:
77
+ - Installer wizard (`npx @maximalabs/dev-mcp-suite init`) mendukung Antigravity, Codex, Claude Code, Cursor, Windsurf, dan Hermes.
@@ -0,0 +1,52 @@
1
+ # Google Antigravity CLI (AGY CLI) Setup
2
+
3
+ `@maximalabs/dev-mcp-suite` connects seamlessly to **Google Antigravity CLI (AGY CLI)** and the AGY SDK agent framework.
4
+
5
+ ## Quick Installation
6
+
7
+ ```bash
8
+ npm install -g @maximalabs/dev-mcp-suite
9
+ ```
10
+
11
+ ## AGY Configuration (`mcp.json` / `settings.json`)
12
+
13
+ Add the suite to your AGY CLI settings or project `mcp.json`:
14
+
15
+ ```json
16
+ {
17
+ "mcpServers": {
18
+ "project-memory": {
19
+ "command": "project-memory-mcp",
20
+ "args": [],
21
+ "env": {
22
+ "MEMORY_VAULT_DIR": "~/.local/share/dev-mcp-suite/memories/vault",
23
+ "MCP_LOCAL_EMBED": "true"
24
+ }
25
+ },
26
+ "devjournal": {
27
+ "command": "devjournal-mcp",
28
+ "args": [],
29
+ "env": {
30
+ "JOURNAL_DIR": "~/.local/share/dev-mcp-suite/memories/journal"
31
+ }
32
+ },
33
+ "checkpoint": {
34
+ "command": "checkpoint-mcp",
35
+ "args": [],
36
+ "env": {
37
+ "CHECKPOINT_DIR": "~/.local/share/dev-mcp-suite/memories/checkpoints"
38
+ }
39
+ },
40
+ "context-pack": {
41
+ "command": "context-pack-mcp",
42
+ "args": []
43
+ }
44
+ }
45
+ }
46
+ ```
47
+
48
+ ## Client Compatibility Highlights
49
+
50
+ - **Stdio Isolation**: Zero stdout noise — all logs and diagnostic messages are routed exclusively to `stderr` or MCP log frames.
51
+ - **Offline Vector Engine**: Automatically uses the built-in 384-d term-frequency hashing vector when no remote embedding API key is set (`MCP_LOCAL_EMBED=true`).
52
+ - **Obsidian Graph Compatibility**: Compatible with `.obsidian` vault structure and `[[WikiLinks]]`.
@@ -0,0 +1,46 @@
1
+ # Claude Code Setup
2
+
3
+ Install globally:
4
+
5
+ ```bash
6
+ npm i -g @maximalabs/dev-mcp-suite
7
+ ```
8
+
9
+ Add MCP servers using your Claude Code MCP configuration flow. Generic JSON shape:
10
+
11
+ ```json
12
+ {
13
+ "mcpServers": {
14
+ "project-memory": {
15
+ "command": "project-memory-mcp",
16
+ "env": {
17
+ "MEMORY_VAULT_DIR": "~/.local/share/dev-mcp-suite/memories/vault",
18
+ "MCP_LLM_BASE_URL": "http://localhost:11434/v1",
19
+ "MCP_LLM_API_KEY": "",
20
+ "MCP_RERANK_MODEL": "llama3.1:8b",
21
+ "MCP_EMBED_MODEL": "nomic-embed-text"
22
+ }
23
+ },
24
+ "devjournal": {
25
+ "command": "devjournal-mcp",
26
+ "env": {
27
+ "JOURNAL_DIR": "~/.local/share/dev-mcp-suite/memories/journal",
28
+ "MCP_LLM_BASE_URL": "http://localhost:11434/v1",
29
+ "MCP_LLM_API_KEY": "",
30
+ "MCP_RERANK_MODEL": "llama3.1:8b"
31
+ }
32
+ },
33
+ "checkpoint": {
34
+ "command": "checkpoint-mcp",
35
+ "env": {
36
+ "CHECKPOINT_DIR": "~/.local/share/dev-mcp-suite/memories/checkpoints"
37
+ }
38
+ },
39
+ "context-pack": {
40
+ "command": "context-pack-mcp"
41
+ }
42
+ }
43
+ }
44
+ ```
45
+
46
+ If you do not configure model env vars, `memory_recall` and `journal_search` still work in offline keyword mode.
@@ -0,0 +1,39 @@
1
+ # Codex CLI Setup
2
+
3
+ Install globally:
4
+
5
+ ```bash
6
+ npm i -g @maximalabs/dev-mcp-suite
7
+ ```
8
+
9
+ Add to `~/.codex/config.toml`:
10
+
11
+ ```toml
12
+ [mcp_servers.project-memory]
13
+ command = "project-memory-mcp"
14
+ [mcp_servers.project-memory.env]
15
+ MEMORY_VAULT_DIR = "~/.codex/memories/vault"
16
+ # Optional model features; omit for offline keyword mode.
17
+ MCP_LLM_BASE_URL = "http://localhost:20128"
18
+ MCP_LLM_API_KEY = "sk-..."
19
+ MCP_RERANK_MODEL = "kr/claude-haiku-4.5"
20
+ MCP_EMBED_MODEL = "bm/baai/bge-m3"
21
+
22
+ [mcp_servers.devjournal]
23
+ command = "devjournal-mcp"
24
+ [mcp_servers.devjournal.env]
25
+ JOURNAL_DIR = "~/.codex/memories/journal"
26
+ MCP_LLM_BASE_URL = "http://localhost:20128"
27
+ MCP_LLM_API_KEY = "sk-..."
28
+ MCP_RERANK_MODEL = "kr/claude-haiku-4.5"
29
+
30
+ [mcp_servers.checkpoint]
31
+ command = "checkpoint-mcp"
32
+ [mcp_servers.checkpoint.env]
33
+ CHECKPOINT_DIR = "~/.codex/memories/checkpoints"
34
+
35
+ [mcp_servers.context-pack]
36
+ command = "context-pack-mcp"
37
+ ```
38
+
39
+ Important: the server name is `project-memory` with a hyphen. `project_memory` is not a configured MCP server name in Codex.
@@ -0,0 +1,45 @@
1
+ # Generic MCP Client Setup
2
+
3
+ Any MCP client that can start stdio servers can use Dev MCP Suite.
4
+
5
+ Install globally:
6
+
7
+ ```bash
8
+ npm i -g @maximalabs/dev-mcp-suite
9
+ ```
10
+
11
+ Generic server definitions:
12
+
13
+ ```json
14
+ {
15
+ "mcpServers": {
16
+ "project-memory": {
17
+ "command": "project-memory-mcp",
18
+ "args": [],
19
+ "env": {
20
+ "MEMORY_VAULT_DIR": "~/.local/share/dev-mcp-suite/memories/vault"
21
+ }
22
+ },
23
+ "devjournal": {
24
+ "command": "devjournal-mcp",
25
+ "args": [],
26
+ "env": {
27
+ "JOURNAL_DIR": "~/.local/share/dev-mcp-suite/memories/journal"
28
+ }
29
+ },
30
+ "checkpoint": {
31
+ "command": "checkpoint-mcp",
32
+ "args": [],
33
+ "env": {
34
+ "CHECKPOINT_DIR": "~/.local/share/dev-mcp-suite/memories/checkpoints"
35
+ }
36
+ },
37
+ "context-pack": {
38
+ "command": "context-pack-mcp",
39
+ "args": []
40
+ }
41
+ }
42
+ }
43
+ ```
44
+
45
+ Optional model configuration can be added to `project-memory` and `devjournal` env blocks. See `docs/configuration.md`.