@maximalabs/dev-mcp-suite 0.0.0-stage → 3.6.1
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/.env.example +69 -0
- package/CHANGELOG.md +281 -0
- package/CODEX_DEV_MCP_GUIDE.md +297 -0
- package/LICENSE +21 -0
- package/README.md +193 -2
- package/armada/package.json +14 -0
- package/armada/server.js +329 -0
- package/backfill-sessions-v2.mjs +288 -0
- package/bin/_meta.mjs +73 -0
- package/bin/armada-mcp.mjs +12 -0
- package/bin/checkpoint.mjs +9 -0
- package/bin/context-pack.mjs +9 -0
- package/bin/devjournal.mjs +9 -0
- package/bin/init.mjs +25 -0
- package/bin/project-memory.mjs +10 -0
- package/bin/provider-smoke.mjs +278 -0
- package/bin/prune.mjs +158 -0
- package/bin/stats.mjs +101 -0
- package/bin/ui.mjs +5 -0
- package/checkpoint/package.json +14 -0
- package/checkpoint/server.js +318 -0
- package/context-pack/package.json +14 -0
- package/context-pack/server.js +747 -0
- package/devjournal/compress.js +75 -0
- package/devjournal/env.js +3 -0
- package/devjournal/package.json +14 -0
- package/devjournal/provider-chain.js +109 -0
- package/devjournal/rerank.js +120 -0
- package/devjournal/server.js +415 -0
- package/docs/ROADMAP.md +77 -0
- package/docs/clients/antigravity.md +52 -0
- package/docs/clients/claude-code.md +46 -0
- package/docs/clients/codex.md +39 -0
- package/docs/clients/generic-mcp.md +45 -0
- package/docs/clients/hermes.md +48 -0
- package/docs/configuration.md +123 -0
- package/docs/privacy.md +39 -0
- package/docs/providers.md +13 -0
- package/docs/superpowers/plans/2026-06-15-hardening-v1-2-implementation.md +60 -0
- package/docs/superpowers/plans/2026-06-15-provider-chain-v1-1-implementation.md +65 -0
- package/docs/superpowers/plans/2026-06-15-provider-client-agnostic-config.md +41 -0
- package/docs/superpowers/plans/2026-06-15-trust-release-implementation.md +62 -0
- package/docs/superpowers/plans/2026-06-18-v1-5-0-knowledge-graph.md +792 -0
- package/docs/superpowers/specs/2026-06-15-provider-chain-v1-1-design.md +89 -0
- package/docs/superpowers/specs/2026-06-15-trust-release-design.md +164 -0
- package/docs/superpowers/specs/2026-06-18-dev-mcp-suite-v1-5-0-knowledge-graph-design.md +386 -0
- package/docs/superpowers/specs/2026-07-22-v2-0-0-peak-intelligence.md +50 -0
- package/docs/superpowers/specs/2026-07-22-v3-0-0-god-tier.md +32 -0
- package/lib/init-wizard.js +120 -0
- package/lib/provider-smoke.js +234 -0
- package/lib/prune.js +114 -0
- package/lib/stats.js +269 -0
- package/lib/ui-server.js +151 -0
- package/lib/update-check.js +125 -0
- package/package.json +71 -4
- package/project-memory/auto-indexer.js +152 -0
- package/project-memory/dedup.js +49 -0
- package/project-memory/embedding.js +174 -0
- package/project-memory/env.js +3 -0
- package/project-memory/global-index.js +46 -0
- package/project-memory/graph.js +93 -0
- package/project-memory/local-embed.js +92 -0
- package/project-memory/package.json +14 -0
- package/project-memory/provider-chain.js +109 -0
- package/project-memory/rerank.js +120 -0
- package/project-memory/server.js +931 -0
- package/project-memory/swarm.js +56 -0
- package/run-tests.mjs +54 -0
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Autonomous Background Git, Mtime & Session Watchdog Observer for project-memory.
|
|
3
|
+
* Inspects recent git commits, modified file mtimes, and chat session transcripts
|
|
4
|
+
* to auto-derive project notes, extract architectural decisions, and update the
|
|
5
|
+
* Obsidian knowledge vault without manual prompts.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import fs from "fs/promises";
|
|
9
|
+
import path from "path";
|
|
10
|
+
import { execSync } from "child_process";
|
|
11
|
+
|
|
12
|
+
async function scanSessionLogs(root, customSessionDir) {
|
|
13
|
+
const decisions = [];
|
|
14
|
+
const candidateDirs = customSessionDir
|
|
15
|
+
? [path.resolve(root, customSessionDir)]
|
|
16
|
+
: [
|
|
17
|
+
path.join(root, ".codex", "sessions"),
|
|
18
|
+
path.join(root, ".codex"),
|
|
19
|
+
path.join(root, ".gemini", "logs"),
|
|
20
|
+
path.join(root, ".gemini"),
|
|
21
|
+
path.join(root, ".agents", "logs"),
|
|
22
|
+
path.join(root, "logs"),
|
|
23
|
+
];
|
|
24
|
+
|
|
25
|
+
const filesToScan = [];
|
|
26
|
+
for (const d of candidateDirs) {
|
|
27
|
+
try {
|
|
28
|
+
const stat = await fs.stat(d);
|
|
29
|
+
if (stat.isFile() && (d.endsWith(".jsonl") || d.endsWith(".log") || d.endsWith(".json"))) {
|
|
30
|
+
filesToScan.push(d);
|
|
31
|
+
continue;
|
|
32
|
+
}
|
|
33
|
+
if (stat.isDirectory()) {
|
|
34
|
+
const entries = await fs.readdir(d, { withFileTypes: true });
|
|
35
|
+
for (const e of entries) {
|
|
36
|
+
if (e.isFile() && (e.name.endsWith(".jsonl") || e.name.endsWith(".log") || e.name.endsWith(".json") || e.name.includes("history"))) {
|
|
37
|
+
filesToScan.push(path.join(d, e.name));
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
} catch {}
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
const fileStats = [];
|
|
45
|
+
for (const f of filesToScan) {
|
|
46
|
+
try {
|
|
47
|
+
const s = await fs.stat(f);
|
|
48
|
+
fileStats.push({ file: f, mtime: s.mtimeMs });
|
|
49
|
+
} catch {}
|
|
50
|
+
}
|
|
51
|
+
fileStats.sort((a, b) => b.mtime - a.mtime);
|
|
52
|
+
const topFiles = fileStats.slice(0, 5).map((x) => x.file);
|
|
53
|
+
|
|
54
|
+
const keywordRegex = /\b(v1|v2|v3|vs|versus|architecture|arsitektur|migration|migrasi|decision|keputusan|strategy|strategi|refactor|database|schema|tradeoff|perbedaan|kesimpulan|monolith|microservice)\b/i;
|
|
55
|
+
|
|
56
|
+
for (const file of topFiles) {
|
|
57
|
+
try {
|
|
58
|
+
const raw = await fs.readFile(file, "utf8");
|
|
59
|
+
const lines = raw.split("\n").filter((l) => l.trim());
|
|
60
|
+
for (const line of lines) {
|
|
61
|
+
let text = "";
|
|
62
|
+
let role = "unknown";
|
|
63
|
+
try {
|
|
64
|
+
const parsed = JSON.parse(line);
|
|
65
|
+
text = typeof parsed === "string" ? parsed : parsed.content || parsed.text || parsed.message || JSON.stringify(parsed);
|
|
66
|
+
role = parsed.type || parsed.role || parsed.source || "log";
|
|
67
|
+
} catch {
|
|
68
|
+
text = line;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
if (typeof text !== "string" || text.length < 20) continue;
|
|
72
|
+
|
|
73
|
+
const match = text.match(keywordRegex);
|
|
74
|
+
if (match) {
|
|
75
|
+
const keyword = match[0].toLowerCase();
|
|
76
|
+
const cleanText = text.replace(/\s+/g, " ").trim();
|
|
77
|
+
const snippet = cleanText.length > 300 ? cleanText.substring(0, 300) + "..." : cleanText;
|
|
78
|
+
decisions.push({
|
|
79
|
+
keyword,
|
|
80
|
+
role: String(role),
|
|
81
|
+
snippet,
|
|
82
|
+
file: path.relative(root, file) || path.basename(file),
|
|
83
|
+
});
|
|
84
|
+
if (decisions.length >= 10) break;
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
} catch {}
|
|
88
|
+
if (decisions.length >= 10) break;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
return decisions;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
export async function runAutoIndexer(projectDir, { dryRun = false, scanSessions = true, sessionDir = null } = {}) {
|
|
95
|
+
const root = path.resolve(projectDir || process.cwd());
|
|
96
|
+
const notesCreated = [];
|
|
97
|
+
|
|
98
|
+
// 1. Inspect recent git commits
|
|
99
|
+
let gitLogs = [];
|
|
100
|
+
try {
|
|
101
|
+
const raw = execSync('git log -n 3 --pretty=format:"%h %s (%an)"', { cwd: root, encoding: "utf8" });
|
|
102
|
+
gitLogs = raw.split("\n").filter(Boolean);
|
|
103
|
+
} catch {}
|
|
104
|
+
|
|
105
|
+
// 2. Inspect git branch
|
|
106
|
+
let branch = "main";
|
|
107
|
+
try {
|
|
108
|
+
branch = execSync("git branch --show-current", { cwd: root, encoding: "utf8" }).trim();
|
|
109
|
+
} catch {}
|
|
110
|
+
|
|
111
|
+
// 3. Inspect recent session transcripts / chat logs if enabled
|
|
112
|
+
let sessionDecisions = [];
|
|
113
|
+
if (scanSessions) {
|
|
114
|
+
sessionDecisions = await scanSessionLogs(root, sessionDir);
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
const summaryLines = [
|
|
118
|
+
`# Auto-Derived Knowledge Snapshot: ${path.basename(root)}`,
|
|
119
|
+
`Active Branch: \`${branch}\``,
|
|
120
|
+
`Inspected At: ${new Date().toISOString()}`,
|
|
121
|
+
``,
|
|
122
|
+
`## 📜 Recent Git Activity`,
|
|
123
|
+
...(gitLogs.length ? gitLogs.map((l) => `- \`${l}\``) : ["- No git history found"]),
|
|
124
|
+
];
|
|
125
|
+
|
|
126
|
+
if (sessionDecisions.length > 0) {
|
|
127
|
+
summaryLines.push(``, `## 💬 Session Conversation Digest (Watchdog)`);
|
|
128
|
+
const seenKeywords = new Set();
|
|
129
|
+
for (const d of sessionDecisions) {
|
|
130
|
+
summaryLines.push(`- **[${d.keyword.toUpperCase()}]** (${d.file}): ${d.snippet}`);
|
|
131
|
+
if (!seenKeywords.has(d.keyword)) {
|
|
132
|
+
seenKeywords.add(d.keyword);
|
|
133
|
+
notesCreated.push({
|
|
134
|
+
title: `Session Digest: ${d.keyword.toUpperCase()} Discussion (${new Date().toISOString().substring(0, 10)})`,
|
|
135
|
+
content: `# Session Digest: ${d.keyword.toUpperCase()} Discussion\n\nExtracted from conversation watchdog on branch \`${branch}\` (Source: \`${d.file}\`).\n\n## Discussion Context\n\n- **Role (${d.role})**: ${d.snippet}\n`,
|
|
136
|
+
tags: ["session-digest", "watchdog", d.keyword.toLowerCase()],
|
|
137
|
+
});
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
const summary = summaryLines.join("\n");
|
|
143
|
+
|
|
144
|
+
return {
|
|
145
|
+
projectDir: root,
|
|
146
|
+
branch,
|
|
147
|
+
recentCommits: gitLogs,
|
|
148
|
+
sessionDecisions,
|
|
149
|
+
summaryText: summary,
|
|
150
|
+
notesCreated,
|
|
151
|
+
};
|
|
152
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
function jaccard(left, right) {
|
|
2
|
+
const leftSet = new Set(left.filter(Boolean));
|
|
3
|
+
const rightSet = new Set(right.filter(Boolean));
|
|
4
|
+
const intersection = [...leftSet].filter((item) => rightSet.has(item)).length;
|
|
5
|
+
const union = new Set([...leftSet, ...rightSet]).size || 1;
|
|
6
|
+
return intersection / union;
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
function tokenizeBody(text) {
|
|
10
|
+
return String(text || "").toLowerCase().split(/\W+/).filter(Boolean);
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
export function scoreDuplicatePair({ a, b, aBody, bBody }) {
|
|
14
|
+
const reasons = [];
|
|
15
|
+
let score = 0;
|
|
16
|
+
|
|
17
|
+
if (String(a.title || "").trim().toLowerCase() === String(b.title || "").trim().toLowerCase()) {
|
|
18
|
+
score += 0.5;
|
|
19
|
+
reasons.push("exact normalized title match");
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
const bodyScore = jaccard(tokenizeBody(aBody), tokenizeBody(bBody));
|
|
23
|
+
score += bodyScore * 0.4;
|
|
24
|
+
if (bodyScore >= 0.75) reasons.push("strong content overlap");
|
|
25
|
+
|
|
26
|
+
const linkScore = jaccard((a.links || []).map((link) => `${link.project || ""}:${link.ref || ""}`), (b.links || []).map((link) => `${link.project || ""}:${link.ref || ""}`));
|
|
27
|
+
score += linkScore * 0.1;
|
|
28
|
+
if (linkScore >= 0.75 && (a.links || []).length && (b.links || []).length) reasons.push("similar link neighborhood");
|
|
29
|
+
|
|
30
|
+
return { score: Math.min(1, score), reasons };
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
export function findDuplicateCandidates({ rows, threshold }) {
|
|
34
|
+
const out = [];
|
|
35
|
+
for (let i = 0; i < rows.length; i += 1) {
|
|
36
|
+
for (let j = i + 1; j < rows.length; j += 1) {
|
|
37
|
+
const result = scoreDuplicatePair({
|
|
38
|
+
a: rows[i].note,
|
|
39
|
+
b: rows[j].note,
|
|
40
|
+
aBody: rows[i].body,
|
|
41
|
+
bBody: rows[j].body,
|
|
42
|
+
});
|
|
43
|
+
if (result.score >= threshold) {
|
|
44
|
+
out.push({ left: rows[i], right: rows[j], score: result.score, reasons: result.reasons });
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
return out.sort((a, b) => b.score - a.score);
|
|
49
|
+
}
|
|
@@ -0,0 +1,174 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Embedding helper for any OpenAI-compatible /v1/embeddings endpoint,
|
|
3
|
+
* with first-class support for Cloudflare Workers AI (REST-only, non-OpenAI).
|
|
4
|
+
*
|
|
5
|
+
* Degrades gracefully: returns null/[] on any failure so callers fall back
|
|
6
|
+
* to keyword search. Never throws.
|
|
7
|
+
*
|
|
8
|
+
* Endpoint formats:
|
|
9
|
+
* - OpenAI-compatible: POST {base}/v1/embeddings body: {model, input:[...]}
|
|
10
|
+
* response: {data:[{embedding:[...], index}]}
|
|
11
|
+
* - Cloudflare Workers: POST {base}/{model} body: {text:[...]}
|
|
12
|
+
* response: {result:{data:[[...]], shape:[n,dim]}}
|
|
13
|
+
*
|
|
14
|
+
* Cloudflare is auto-detected by URL pattern (contains "api.cloudflare.com/client/v4/accounts").
|
|
15
|
+
* To use it: set MCP_EMBED_BASE_URL=https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai/run/
|
|
16
|
+
* and MCP_EMBED_MODEL=@cf/baai/bge-base-en-v1.5
|
|
17
|
+
*/
|
|
18
|
+
import http from "http";
|
|
19
|
+
import https from "https";
|
|
20
|
+
import { URL } from "url";
|
|
21
|
+
import { deterministicEnabled } from "./env.js";
|
|
22
|
+
import { generateLocalVectors } from "./local-embed.js";
|
|
23
|
+
|
|
24
|
+
/** Read env at runtime (not module-load time) so tests can override and config is dynamic). */
|
|
25
|
+
function readEnv() {
|
|
26
|
+
return {
|
|
27
|
+
base: process.env.MCP_EMBED_BASE_URL || process.env.MCP_LLM_BASE_URL || process.env.LLM_BASE_URL || process.env.EMBED_URL || process.env.NINEROUTER_URL || "http://localhost:20128",
|
|
28
|
+
key: process.env.MCP_EMBED_API_KEY || process.env.MCP_LLM_API_KEY || process.env.LLM_API_KEY || process.env.EMBED_KEY || process.env.NINEROUTER_KEY || "",
|
|
29
|
+
model: process.env.MCP_EMBED_MODEL || process.env.EMBED_MODEL || "bm/baai/bge-m3",
|
|
30
|
+
timeoutMs: Number(process.env.EMBED_TIMEOUT_MS || 15000),
|
|
31
|
+
};
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
export function localEmbedEnabled() {
|
|
35
|
+
return process.env.MCP_LOCAL_EMBED === "true" || process.env.LOCAL_EMBED === "true";
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Resolve what retrieval mode memory_recall will use, given current env.
|
|
40
|
+
* Returns one of: "deterministic" | "semantic" | "keyword".
|
|
41
|
+
* Independent of MCP_RERANK_ENABLED (rerank layers on top of either).
|
|
42
|
+
*/
|
|
43
|
+
export function recallMode() {
|
|
44
|
+
if (deterministicEnabled()) return "deterministic";
|
|
45
|
+
const { key } = readEnv();
|
|
46
|
+
if (key) return "semantic";
|
|
47
|
+
if (localEmbedEnabled()) return "semantic (local)";
|
|
48
|
+
return "keyword";
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export function embeddingConfig() {
|
|
52
|
+
const { base, key, model } = readEnv();
|
|
53
|
+
const isLocal = !key && localEmbedEnabled();
|
|
54
|
+
return {
|
|
55
|
+
base: key ? base : (isLocal ? "local-offline" : base),
|
|
56
|
+
model: key ? model : (isLocal ? "local-384d-tf-ngram" : model),
|
|
57
|
+
enabled: Boolean(key || isLocal) && !deterministicEnabled(),
|
|
58
|
+
deterministic: deterministicEnabled(),
|
|
59
|
+
endpoint: key ? (isCloudflareURL(base) ? "cloudflare" : "openai-compatible") : (isLocal ? "local-offline" : "none"),
|
|
60
|
+
mode: recallMode(),
|
|
61
|
+
};
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** Detect Cloudflare Workers AI by URL pattern. */
|
|
65
|
+
export function isCloudflareURL(urlStr) {
|
|
66
|
+
return typeof urlStr === "string" && urlStr.includes("api.cloudflare.com/client/v4/accounts");
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* POST a JSON body to an absolute URL with Bearer auth. Returns:
|
|
71
|
+
* { status: 200, body: <parsed JSON> } on success
|
|
72
|
+
* { status: <code>, body: <raw text> } on non-200
|
|
73
|
+
* null on network/timeout/parse error
|
|
74
|
+
* Caller is responsible for building the full URL (we don't append /v1/embeddings etc).
|
|
75
|
+
*/
|
|
76
|
+
function httpPostJson(urlStr, payload) {
|
|
77
|
+
return new Promise((resolve) => {
|
|
78
|
+
let u;
|
|
79
|
+
try { u = new URL(urlStr); } catch { return resolve(null); }
|
|
80
|
+
const data = Buffer.from(JSON.stringify(payload));
|
|
81
|
+
const { key, timeoutMs } = readEnv();
|
|
82
|
+
const lib = u.protocol === "https:" ? https : http;
|
|
83
|
+
const req = lib.request(
|
|
84
|
+
{
|
|
85
|
+
hostname: u.hostname,
|
|
86
|
+
port: u.port || (u.protocol === "https:" ? 443 : 80),
|
|
87
|
+
path: u.pathname + (u.search || ""),
|
|
88
|
+
method: "POST",
|
|
89
|
+
headers: {
|
|
90
|
+
"Content-Type": "application/json",
|
|
91
|
+
"Content-Length": data.length,
|
|
92
|
+
...(key ? { Authorization: `Bearer ${key}` } : {}),
|
|
93
|
+
},
|
|
94
|
+
timeout: timeoutMs,
|
|
95
|
+
},
|
|
96
|
+
(res) => {
|
|
97
|
+
let body = "";
|
|
98
|
+
res.on("data", (c) => (body += c));
|
|
99
|
+
res.on("end", () => {
|
|
100
|
+
if (res.statusCode !== 200) return resolve({ status: res.statusCode, body });
|
|
101
|
+
try { resolve({ status: 200, body: JSON.parse(body) }); } catch { resolve({ status: res.statusCode, body }); }
|
|
102
|
+
});
|
|
103
|
+
}
|
|
104
|
+
);
|
|
105
|
+
req.on("error", () => resolve(null));
|
|
106
|
+
req.on("timeout", () => { req.destroy(); resolve(null); });
|
|
107
|
+
req.write(data);
|
|
108
|
+
req.end();
|
|
109
|
+
});
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
async function embedOpenAI(inputs) {
|
|
113
|
+
const { base, key, model } = readEnv();
|
|
114
|
+
if (!key) return [];
|
|
115
|
+
try {
|
|
116
|
+
const res = await httpPostJson(`${base.replace(/\/$/, "")}/v1/embeddings`, { model, input: inputs });
|
|
117
|
+
if (!res || res.status !== 200 || !res.body || !Array.isArray(res.body.data)) return [];
|
|
118
|
+
const json = res.body;
|
|
119
|
+
const sorted = [...json.data].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
|
|
120
|
+
return sorted.map((d) => d.embedding).filter(Boolean);
|
|
121
|
+
} catch { return []; }
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
async function embedCloudflare(inputs) {
|
|
125
|
+
const { base: rawBase, key, model } = readEnv();
|
|
126
|
+
if (!key) return [];
|
|
127
|
+
// Cloudflare: model is in URL path; do NOT URL-encode ("@" and "/" must stay literal).
|
|
128
|
+
const base = rawBase.replace(/\/$/, "");
|
|
129
|
+
const url = `${base}/${model}`;
|
|
130
|
+
try {
|
|
131
|
+
const res = await httpPostJson(url, { text: inputs });
|
|
132
|
+
if (!res || res.status !== 200 || !res.body || !res.body.result) return [];
|
|
133
|
+
const data = res.body.result.data;
|
|
134
|
+
if (!Array.isArray(data)) return [];
|
|
135
|
+
return data.filter((v) => Array.isArray(v));
|
|
136
|
+
} catch { return []; }
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* Embed an array of strings (or a single string) and return an array of
|
|
141
|
+
* numeric vectors. Returns [] when no API key is configured, deterministic
|
|
142
|
+
* mode is on, or the endpoint fails.
|
|
143
|
+
*/
|
|
144
|
+
export async function embed(inputs) {
|
|
145
|
+
if (deterministicEnabled()) return [];
|
|
146
|
+
const { base, key } = readEnv();
|
|
147
|
+
const arr = Array.isArray(inputs) ? inputs : [inputs];
|
|
148
|
+
if (!key) {
|
|
149
|
+
if (localEmbedEnabled()) return generateLocalVectors(arr);
|
|
150
|
+
return [];
|
|
151
|
+
}
|
|
152
|
+
try {
|
|
153
|
+
const res = isCloudflareURL(base) ? await embedCloudflare(arr) : await embedOpenAI(arr);
|
|
154
|
+
if (res && res.length) return res;
|
|
155
|
+
} catch { /* fallback to local if enabled */ }
|
|
156
|
+
if (localEmbedEnabled()) return generateLocalVectors(arr);
|
|
157
|
+
return [];
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
export async function embedOne(text) {
|
|
161
|
+
const v = await embed([text]);
|
|
162
|
+
return v[0] || null;
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
export function cosine(a, b) {
|
|
166
|
+
if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return 0;
|
|
167
|
+
let dot = 0, na = 0, nb = 0;
|
|
168
|
+
for (let i = 0; i < a.length; i++) {
|
|
169
|
+
const x = a[i], y = b[i];
|
|
170
|
+
dot += x * y; na += x * x; nb += y * y;
|
|
171
|
+
}
|
|
172
|
+
const denom = Math.sqrt(na) * Math.sqrt(nb);
|
|
173
|
+
return denom === 0 ? 0 : dot / denom;
|
|
174
|
+
}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import fs from "fs/promises";
|
|
2
|
+
import path from "path";
|
|
3
|
+
|
|
4
|
+
export async function listProjects(vaultRoot) {
|
|
5
|
+
let slugs = [];
|
|
6
|
+
try {
|
|
7
|
+
slugs = await fs.readdir(vaultRoot);
|
|
8
|
+
} catch {
|
|
9
|
+
slugs = [];
|
|
10
|
+
}
|
|
11
|
+
return slugs.map((slug) => ({
|
|
12
|
+
slug,
|
|
13
|
+
projectDir: path.join(vaultRoot, slug),
|
|
14
|
+
indexFile: path.join(vaultRoot, slug, "index.json"),
|
|
15
|
+
}));
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export async function loadGlobalNotes(vaultRoot) {
|
|
19
|
+
const projects = await listProjects(vaultRoot);
|
|
20
|
+
const rows = [];
|
|
21
|
+
for (const project of projects) {
|
|
22
|
+
try {
|
|
23
|
+
const raw = await fs.readFile(project.indexFile, "utf8");
|
|
24
|
+
const index = JSON.parse(raw);
|
|
25
|
+
for (const note of Object.values(index.notes || {})) rows.push({ slug: project.slug, note });
|
|
26
|
+
} catch {
|
|
27
|
+
// ignore invalid or incomplete project index
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
return rows;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
export async function findGlobalCandidates({ vaultRoot, currentSlug, query }) {
|
|
34
|
+
const q = String(query || "").toLowerCase();
|
|
35
|
+
const rows = await loadGlobalNotes(vaultRoot);
|
|
36
|
+
return rows
|
|
37
|
+
.filter(({ note }) =>
|
|
38
|
+
String(note.title || "").toLowerCase().includes(q) ||
|
|
39
|
+
(note.keywords || []).some((keyword) => String(keyword).toLowerCase().includes(q))
|
|
40
|
+
)
|
|
41
|
+
.sort((a, b) => {
|
|
42
|
+
const ap = a.slug === currentSlug ? 0 : 1;
|
|
43
|
+
const bp = b.slug === currentSlug ? 0 : 1;
|
|
44
|
+
return ap - bp || (a.note.created < b.note.created ? 1 : -1);
|
|
45
|
+
});
|
|
46
|
+
}
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
import fs from "fs/promises";
|
|
2
|
+
import path from "path";
|
|
3
|
+
import { parseFrontmatter } from "./server.js";
|
|
4
|
+
|
|
5
|
+
export function extractWikiLinks(body) {
|
|
6
|
+
const out = [];
|
|
7
|
+
const re = /\[\[([^\]]+)\]\]/g;
|
|
8
|
+
let match;
|
|
9
|
+
while ((match = re.exec(String(body || "")))) {
|
|
10
|
+
const raw = match[0];
|
|
11
|
+
const inner = match[1].trim();
|
|
12
|
+
const colon = inner.indexOf(":");
|
|
13
|
+
const project = colon > 0 ? inner.slice(0, colon).trim() : null;
|
|
14
|
+
const ref = colon > 0 ? inner.slice(colon + 1).trim() : inner;
|
|
15
|
+
const kind = /^[0-9A-Za-z_-]{6,}$/.test(ref) && !/\s/.test(ref) ? "id" : "title";
|
|
16
|
+
out.push({ raw, ref, project, kind });
|
|
17
|
+
}
|
|
18
|
+
return out;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
export async function loadNoteBody(projectDir, file) {
|
|
22
|
+
const raw = await fs.readFile(path.join(projectDir, file), "utf8");
|
|
23
|
+
return parseFrontmatter(raw).body;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export async function ensureGraphState({ vaultRoot, projectDir, slug, index, noteLoader }) {
|
|
27
|
+
void vaultRoot;
|
|
28
|
+
void slug;
|
|
29
|
+
let changed = false;
|
|
30
|
+
const backlinks = new Map();
|
|
31
|
+
for (const note of Object.values(index.notes || {})) {
|
|
32
|
+
const body = await noteLoader(projectDir, note.file);
|
|
33
|
+
const links = extractWikiLinks(body).map((link) => ({
|
|
34
|
+
raw: link.raw,
|
|
35
|
+
ref: link.ref,
|
|
36
|
+
project: link.project,
|
|
37
|
+
kind: link.kind,
|
|
38
|
+
}));
|
|
39
|
+
const next = JSON.stringify(links);
|
|
40
|
+
const prev = JSON.stringify(note.links || []);
|
|
41
|
+
if (next !== prev) {
|
|
42
|
+
note.links = links;
|
|
43
|
+
changed = true;
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
for (const note of Object.values(index.notes || {})) {
|
|
47
|
+
for (const link of note.links || []) {
|
|
48
|
+
if (link.project || link.kind !== "id") continue;
|
|
49
|
+
const arr = backlinks.get(link.ref) || [];
|
|
50
|
+
arr.push({ id: note.id, title: note.title });
|
|
51
|
+
backlinks.set(link.ref, arr);
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
for (const note of Object.values(index.notes || {})) {
|
|
55
|
+
const next = backlinks.get(note.id) || [];
|
|
56
|
+
if (JSON.stringify(next) !== JSON.stringify(note.backlinks || [])) {
|
|
57
|
+
note.backlinks = next;
|
|
58
|
+
changed = true;
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
return { index, changed };
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
export async function resolveLink({ vaultRoot, currentSlug, ref, project, kind }) {
|
|
65
|
+
const targetSlug = project || currentSlug;
|
|
66
|
+
const indexFile = path.join(vaultRoot, targetSlug, "index.json");
|
|
67
|
+
let index;
|
|
68
|
+
try {
|
|
69
|
+
index = JSON.parse(await fs.readFile(indexFile, "utf8"));
|
|
70
|
+
} catch {
|
|
71
|
+
return { status: "missing" };
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
const notes = Object.values(index.notes || {});
|
|
75
|
+
let candidates;
|
|
76
|
+
if (kind === "id") {
|
|
77
|
+
candidates = notes.filter((note) => note.id === ref);
|
|
78
|
+
} else {
|
|
79
|
+
const target = String(ref || "").trim().toLowerCase();
|
|
80
|
+
candidates = notes.filter((note) => {
|
|
81
|
+
if (String(note.title || "").trim().toLowerCase() === target) return true;
|
|
82
|
+
// Obsidian-style alias match
|
|
83
|
+
if (Array.isArray(note.aliases)) {
|
|
84
|
+
return note.aliases.some((a) => String(a).trim().toLowerCase() === target);
|
|
85
|
+
}
|
|
86
|
+
return false;
|
|
87
|
+
});
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
if (candidates.length === 0) return { status: "missing" };
|
|
91
|
+
if (candidates.length === 1) return { status: "resolved", match: candidates[0] };
|
|
92
|
+
return { status: "ambiguous", candidates };
|
|
93
|
+
}
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Local offline vector embedding engine (384-dimensional term-frequency hashing vector).
|
|
3
|
+
* Zero external dependencies, zero network calls, sub-millisecond execution.
|
|
4
|
+
*
|
|
5
|
+
* Provides a reliable fallback for semantic search when no remote API keys
|
|
6
|
+
* (OpenAI/Cloudflare/Gemini/Ollama) are available.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
const VECTOR_DIM = 384;
|
|
10
|
+
|
|
11
|
+
/** Simple hash function for N-gram string to integer bucket [0, VECTOR_DIM-1] */
|
|
12
|
+
function hashNgram(ngram) {
|
|
13
|
+
let hash = 5381;
|
|
14
|
+
for (let i = 0; i < ngram.length; i++) {
|
|
15
|
+
hash = ((hash << 5) + hash) + ngram.charCodeAt(i);
|
|
16
|
+
hash = hash & hash; // Convert to 32bit integer
|
|
17
|
+
}
|
|
18
|
+
return Math.abs(hash) % VECTOR_DIM;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Generate a 384-dimensional L2-normalized vector for a text string.
|
|
23
|
+
* @param {string} text
|
|
24
|
+
* @returns {number[]} Array of 384 float numbers
|
|
25
|
+
*/
|
|
26
|
+
export function generateLocalVector(text) {
|
|
27
|
+
if (!text || typeof text !== "string") {
|
|
28
|
+
return new Array(VECTOR_DIM).fill(0);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
const normalized = text.toLowerCase().trim();
|
|
32
|
+
if (!normalized) {
|
|
33
|
+
return new Array(VECTOR_DIM).fill(0);
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
const vec = new Array(VECTOR_DIM).fill(0);
|
|
37
|
+
|
|
38
|
+
// Extract word tokens and character 3-grams
|
|
39
|
+
const words = normalized.split(/\s+/).filter(Boolean);
|
|
40
|
+
|
|
41
|
+
// 1. Process words (higher weight)
|
|
42
|
+
for (const word of words) {
|
|
43
|
+
const cleanWord = word.replace(/[^a-z0-9]/g, "");
|
|
44
|
+
if (!cleanWord) continue;
|
|
45
|
+
|
|
46
|
+
const idx = hashNgram(cleanWord);
|
|
47
|
+
vec[idx] += 2.0;
|
|
48
|
+
|
|
49
|
+
// 2. Process character 3-grams for fuzzy matching
|
|
50
|
+
if (cleanWord.length >= 3) {
|
|
51
|
+
for (let i = 0; i <= cleanWord.length - 3; i++) {
|
|
52
|
+
const sub = cleanWord.substring(i, i + 3);
|
|
53
|
+
const subIdx = hashNgram(sub);
|
|
54
|
+
vec[subIdx] += 1.0;
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
// 3. Sublinear term-frequency scaling (1 + log(tf))
|
|
60
|
+
for (let i = 0; i < VECTOR_DIM; i++) {
|
|
61
|
+
if (vec[i] > 0) {
|
|
62
|
+
vec[i] = 1 + Math.log(vec[i]);
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
// 4. L2 Normalization (unit length vector)
|
|
67
|
+
let normSq = 0;
|
|
68
|
+
for (let i = 0; i < VECTOR_DIM; i++) {
|
|
69
|
+
normSq += vec[i] * vec[i];
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
if (normSq === 0) {
|
|
73
|
+
return vec;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
const norm = Math.sqrt(normSq);
|
|
77
|
+
for (let i = 0; i < VECTOR_DIM; i++) {
|
|
78
|
+
vec[i] = vec[i] / norm;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
return vec;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Generate vectors for an array of strings.
|
|
86
|
+
* @param {string[]} inputs
|
|
87
|
+
* @returns {number[][]}
|
|
88
|
+
*/
|
|
89
|
+
export function generateLocalVectors(inputs) {
|
|
90
|
+
const arr = Array.isArray(inputs) ? inputs : [inputs];
|
|
91
|
+
return arr.map((t) => generateLocalVector(t));
|
|
92
|
+
}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "project-memory-mcp",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "Per-directory memory + indexing MCP server (Obsidian-style vault + Context7-style recall)",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "server.js",
|
|
7
|
+
"scripts": {
|
|
8
|
+
"start": "node server.js",
|
|
9
|
+
"test": "node test.mjs"
|
|
10
|
+
},
|
|
11
|
+
"dependencies": {
|
|
12
|
+
"@modelcontextprotocol/sdk": "^1.0.0"
|
|
13
|
+
}
|
|
14
|
+
}
|