keywordgraph-mcp-server 1.7.4 → 1.8.4

package/dist/utils/learnings.js

@@ -0,0 +1,337 @@
+/**
+ * Project learnings: an append-only, per-project graph (`learn-<slug>`) where
+ * the calling LLM saves what it learned about operating in a project, so the
+ * next session — on any client — can retrieve it.
+ *
+ * Consent model (see docs/drafts/project-learnings-graph.md): the graph only
+ * exists if the user explicitly asked for it via `enable_project_learnings`.
+ * `add_project_learnings` refuses when the graph is missing and never creates
+ * one. Statements carry their `type-*` label as plain per-statement metadata
+ * (`categories`), deliberately WITHOUT `categoriesAsMentions`: with that
+ * flag each label becomes a [[label]] mention node linked to every statement
+ * of that type, which in testing made the labels the most central nodes of
+ * the graph. As metadata the labels are returned with each statement and
+ * filterable, while the graph's nodes stay the real entities.
+ */
+import { makeInfraNodusRequest } from "../api/client.js";
+import { READ_ATTEMPTS, errorText, findGraphByName, firstPositive, } from "./graphLookup.js";
+export const GRAPH_PREFIX = "learn-";
+export const MAX_GRAPH_NAME_LENGTH = 28;
+export const MARKER_CATEGORY = "learnings-enabled";
+export const LEARNING_TYPES = [
+    "location",
+    "trap",
+    "convention",
+    "decision",
+    "workflow",
+    "question",
+    "approach",
+];
+export const TYPE_CATEGORY_PREFIX = "type-";
+export const SOURCE_CATEGORY_PREFIX = "source-";
+/** Near-duplicate threshold on word-set Jaccard similarity. */
+export const DEDUPE_THRESHOLD = 0.6;
+export const MAX_STATEMENT_LENGTH = 400;
+export function slugify(input) {
+    return input
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-{2,}/g, "-");
+}
+export function learningsGraphName(project) {
+    const slug = slugify(project) || "project";
+    const room = MAX_GRAPH_NAME_LENGTH - GRAPH_PREFIX.length;
+    return GRAPH_PREFIX + slug.slice(0, room).replace(/-+$/g, "");
+}
+/**
+ * Not attached to statements any more: a per-client label links every
+ * statement of that client and became the most central node of the graph in
+ * testing. Kept so `toStoredLearning` can still read graphs written before
+ * that change.
+ */
+export function sourceCategory(clientName) {
+    return SOURCE_CATEGORY_PREFIX + (slugify(clientName ?? "") || "unknown");
+}
+export function typeCategory(type) {
+    return TYPE_CATEGORY_PREFIX + type;
+}
+// ---------------------------------------------------------------------------
+// Redaction lint
+// ---------------------------------------------------------------------------
+const SECRET_PATTERNS = [
+    /\bsk-[A-Za-z0-9_-]{8,}/, // OpenAI/Anthropic-style keys
+    /\bAKIA[0-9A-Z]{16}\b/, // AWS access key id
+    /\bbearer\s+[A-Za-z0-9._~+/=-]{12,}/i,
+    /\bapi[_-]?key\s*[:=]\s*['"]?[A-Za-z0-9._-]{8,}/i,
+    /\b(?:password|passwd|secret|token)\s*[:=]\s*['"]?\S{6,}/i,
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+    /:\/\/[^\s/@]+:[^\s/@]+@/, // user:pass@host in a URL
+    /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/, // JWT
+];
+/** Returns the indices (never the content) of statements that must not be stored. */
+export function redactionIssues(statements) {
+    const issues = [];
+    statements.forEach((statement, index) => {
+        if (!statement || !statement.trim()) {
+            issues.push({ index, reason: "empty" });
+            return;
+        }
+        if (statement.length > MAX_STATEMENT_LENGTH) {
+            issues.push({ index, reason: "too-long" });
+            return;
+        }
+        if (SECRET_PATTERNS.some((pattern) => pattern.test(statement))) {
+            issues.push({ index, reason: "secret-like" });
+        }
+    });
+    return issues;
+}
+// ---------------------------------------------------------------------------
+// Dedupe
+// ---------------------------------------------------------------------------
+const STOPWORDS = new Set([
+    "the", "and", "for", "that", "this", "with", "from", "are", "was", "were",
+    "has", "have", "not", "but", "its", "into", "when", "which", "also", "than",
+    "then", "there", "their", "they", "them", "been", "being", "use", "used",
+    "confirmed", "again",
+]);
+export function tokenize(statement) {
+    const words = statement
+        .toLowerCase()
+        .replace(/\[\[|\]\]/g, " ")
+        .split(/[^a-z0-9._/-]+/)
+        .map((word) => word.replace(/^[._/-]+|[._/-]+$/g, ""))
+        .filter((word) => word.length >= 3 && !STOPWORDS.has(word));
+    return new Set(words);
+}
+export function jaccard(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const word of a)
+        if (b.has(word))
+            intersection += 1;
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+/**
+ * Compare candidates against what the graph already holds. A near-duplicate
+ * is not dropped — it is rewritten as a short "Confirmed again" statement so
+ * the repeat still raises the weight of the same entity links (that is how
+ * frequently re-learned things become central) without duplicating the text.
+ */
+export function dedupeAgainstExisting(candidates, existing, threshold = DEDUPE_THRESHOLD) {
+    const existingTokens = existing.map((statement) => ({
+        statement,
+        tokens: tokenize(statement),
+    }));
+    const accepted = [];
+    return candidates.map((candidate) => {
+        const tokens = tokenize(candidate);
+        let best = null;
+        for (const entry of existingTokens) {
+            const similarity = jaccard(tokens, entry.tokens);
+            if (similarity >= threshold && (!best || similarity > best.similarity)) {
+                best = { statement: entry.statement, similarity };
+            }
+        }
+        // Also collapse duplicates within the same batch.
+        if (!best) {
+            for (const prior of accepted) {
+                if (jaccard(tokens, prior) >= threshold) {
+                    best = { statement: "(earlier statement in this batch)", similarity: 1 };
+                    break;
+                }
+            }
+        }
+        accepted.push(tokens);
+        if (best) {
+            return {
+                statement: best.statement.startsWith("(")
+                    ? candidate
+                    : `Confirmed again: ${stripConfirmedPrefix(best.statement)}`,
+                status: "reinforced",
+                matches: best.statement,
+                similarity: Number(best.similarity.toFixed(2)),
+            };
+        }
+        return { statement: candidate, status: "new" };
+    });
+}
+function stripConfirmedPrefix(statement) {
+    return statement.replace(/^(?:confirmed again:\s*)+/i, "");
+}
+// The retrying lookup and the error-envelope normaliser live in
+// graphLookup.ts (shared with delete_statements); re-exported here so the
+// existing imports and tests keep working.
+export { READ_ATTEMPTS, errorText };
+/** Exact-name lookup through /listGraphs (read-only; never creates anything). */
+export async function findLearningsGraph(graphName) {
+    const found = await findGraphByName(graphName);
+    if (!found)
+        return { exists: false, categoriesOn: false };
+    return {
+        exists: true,
+        categoriesOn: found.textProcessingSettings?.categoriesAsMentions === true,
+        id: found.id,
+        url: found.defaultRevisionUrl ?? undefined,
+        createdAt: found.createdAt,
+    };
+}
+export function toStoredLearning(statement) {
+    if (!statement.content)
+        return null;
+    const categories = statement.categories ?? [];
+    return {
+        content: statement.content,
+        types: categories
+            .filter((category) => category.startsWith(TYPE_CATEGORY_PREFIX))
+            .map((category) => category.slice(TYPE_CATEGORY_PREFIX.length)),
+        source: categories
+            .find((category) => category.startsWith(SOURCE_CATEGORY_PREFIX))
+            ?.slice(SOURCE_CATEGORY_PREFIX.length),
+        categories,
+        createdAt: statement.createdAt,
+    };
+}
+export function isMarkerStatement(statement) {
+    return ((statement.categories ?? []).includes(MARKER_CATEGORY) ||
+        (statement.content ?? "").includes(`[[${MARKER_CATEGORY}]]`));
+}
+/**
+ * Read every statement of the graph (doNotSave; the graph must already exist —
+ * a missing name errors and is never created). "Select an existing graph
+ * context" on a graph that does exist means the request hit an instance
+ * with a stale contexts list (see firstPositive), not a parameter problem.
+ */
+export async function fetchLearningsGraph(graphName) {
+    const queryParams = new URLSearchParams({
+        doNotSave: "true",
+        addStats: "true",
+        includeStatements: "true",
+        includeGraphSummary: "false",
+        extendedGraphSummary: "true",
+        includeGraph: "false",
+        compactGraph: "true",
+        compactStatements: "false",
+        aiTopics: "false",
+    });
+    let lastError = "Graph not found";
+    const response = await firstPositive(async (n) => {
+        try {
+            const result = await makeInfraNodusRequest(`/graphAndStatements?${queryParams.toString()}`, { name: graphName, aiTopics: "false", attempt: n });
+            if (result.error) {
+                lastError = errorText(result.error);
+                return null;
+            }
+            return result;
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+            return null;
+        }
+    });
+    if (!response)
+        throw new Error(lastError);
+    return { statements: response.statements ?? [], response };
+}
+/**
+ * Resolve whether learnings are enabled for a graph name: the graph exists
+ * and holds the marker statement written by `createLearningsGraph`. The
+ * listing supplies url/createdAt; reading by name is authoritative for
+ * existence (a missing graph errors and is never created) and is also what
+ * catches a graph the listing does not show yet (see firstPositive).
+ */
+export async function checkEnabled(graphName) {
+    const info = await findLearningsGraph(graphName);
+    let statements;
+    try {
+        ({ statements } = await fetchLearningsGraph(graphName));
+    }
+    catch {
+        return { enabled: false, info, reason: "missing" };
+    }
+    if (statements.some(isMarkerStatement)) {
+        return { enabled: true, info: { ...info, exists: true } };
+    }
+    return {
+        enabled: false,
+        info: { ...info, exists: true },
+        reason: "not-a-learnings-graph",
+    };
+}
+/**
+ * Append statements (with parallel categories/timestamps) to an existing
+ * graph. Sent as a plain statements payload — NOT via prepareStatementsPayload,
+ * which would switch `categoriesAsMentions` on and turn the labels into nodes.
+ */
+export async function appendLearnings(params) {
+    const payload = {
+        text: "",
+        statements: params.statements,
+        categories: params.categories,
+        timestamps: params.timestamps,
+    };
+    const queryParams = new URLSearchParams({
+        doNotSave: "false",
+        addStats: "false",
+        includeStatements: "false",
+        includeGraphSummary: "false",
+        extendedGraphSummary: "false",
+        includeGraph: "false",
+        compactGraph: "true",
+        compactStatements: "true",
+        aiTopics: "false",
+    });
+    // An instance with a stale contexts list (see firstPositive) treats an
+    // append to an existing graph as a create and the engine rejects it with
+    // "Context with this name already exists". That error is the only one
+    // worth retrying: it means the graph exists and another instance will
+    // append correctly.
+    let lastError = "Append failed";
+    for (let n = 0; n < READ_ATTEMPTS; n++) {
+        const response = await makeInfraNodusRequest(`/graphAndStatements?${queryParams.toString()}`, {
+            name: params.graphName,
+            aiTopics: "false",
+            contextType: "memory",
+            ...payload,
+            ...(n > 0 ? { attempt: n } : {}),
+        });
+        if (!response.error) {
+            return {
+                graphName: response.graphName ?? params.graphName,
+                graphUrl: response.graphUrl,
+                response,
+            };
+        }
+        lastError = errorText(response.error);
+        if (!/already exists/i.test(lastError))
+            break;
+    }
+    throw new Error(lastError);
+}
+/**
+ * Create the learnings graph. The marker statement (and its
+ * `learnings-enabled` category) is what `checkEnabled` looks for.
+ */
+export async function createLearningsGraph(params) {
+    const now = new Date().toISOString();
+    const client = params.clientName?.trim() || "unknown client";
+    return appendLearnings({
+        graphName: params.graphName,
+        statements: [
+            `[[${MARKER_CATEGORY}]] Project [[${params.slug}]] learnings enabled on ${now.slice(0, 10)} from ${client}. Append-only graph of what agents learned about operating in this project.`,
+        ],
+        categories: [[MARKER_CATEGORY]],
+        timestamps: [now],
+    });
+}
+export function newestFirst(items) {
+    return [...items].sort((a, b) => {
+        const ta = a.createdAt ? Date.parse(a.createdAt) : 0;
+        const tb = b.createdAt ? Date.parse(b.createdAt) : 0;
+        return tb - ta;
+    });
+}
+//# sourceMappingURL=learnings.js.map

package/dist/utils/learnings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"learnings.js","sourceRoot":"","sources":["../../src/utils/learnings.ts"],"names":[],"mappings":"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"}

package/llms-full.infranodus.txt

@@ -37,7 +37,7 @@ Get API key at: https://infranodus.com/api-access
 7. **Comparing texts**: `overlap_between_texts` (similarities), `difference_between_texts` (what's missing in first text), `merged_graph_from_texts` (combined overview).
 8. **SEO/content optimization**: `generate_seo_report` (comprehensive, ~90s timeout needed) or run `analyze_google_search_results` → `analyze_related_search_queries` → `search_queries_vs_search_results` individually.
 9. **Memory**: `memory_add_relations` to persist knowledge graphs, `memory_get_relations` to retrieve. Use `[[wikilinks]]` for entity marking.
-10. **Graph management**: `list_graphs` to discover existing graphs, `search` + `fetch` for content retrieval.
+10. **Graph management**: `list_graphs` to discover existing graphs, `search` + `fetch` for content retrieval, `delete_statements` to remove statements from your own graph by filter and `update_statements` to edit them in place (both dry run unless `confirm: true`; irreversible).
 
 ---
 
@@ -321,6 +321,44 @@ Fetch specific statements from a search result using the ID from `search`.
 
 ---
 
+### delete_statements
+
+Delete statements from a graph in the user's own account, selected by one filter the server resolves. Irreversible once confirmed. Dry run by default: the response reports the matched count, a sample of the matched statements, and a per-category breakdown, and nothing is removed until the same filter is sent again with `confirm: true` (clients with MCP elicitation ask the user directly in the same call). A filter that matches nothing returns `deleted: 0` without asking. Never called on the assistant's own initiative.
+
+**Parameters** (exactly one selector besides `graphName`):
+- `graphName` (string, required): Graph in the user's own account (must exist; there is no `userName`)
+- `categories` (string[]): Statements carrying any of these labels — everything from one source (a file path, page name, or `[[label]]` parent)
+- `statements` (string[]): Exact statement text
+- `query` (string): Case-insensitive substring, or `/regex/flags`
+- `before`, `after` (ISO 8601): Time window; together they count as one selector
+- `deleteAll` (boolean): Empty the graph but keep it (name, URL, settings survive)
+- `statementIds` (number[]): Advanced; foreign ids are reported as `ignoredIds`
+- `confirm` (boolean, default false): Perform the deletion
+
+**Returns**: dry run — `dryRun: true`, `matchedCount`, `matched` (id, content, categories, timestamp), `matchedByCategory`, `filter`, `nextStep`; after confirmation — `deleted`, `removedIds`, `ignoredIds`, `remaining`, `graphName`, `graphUrl`.
+
+**Typical use**: replace one source's statements after it changed (`delete_statements` with its category, then `create_knowledge_graph` to the same `graphName`), or rebuild a graph in place (`deleteAll`, then `create_knowledge_graph`).
+
+---
+
+### update_statements
+
+Edit statements of a graph in the user's own account IN PLACE — their content, categories, or timestamp — keeping each statement's id, date, and position (unlike deleting and re-creating it). Irreversible once confirmed: the previous text survives only in the dry-run output. Dry run by default: the response reports the matched count and the before → after of every change, and nothing is written until the same arguments are sent again with `confirm: true` (clients with MCP elicitation ask the user directly in the same call). A request that matches nothing returns `updated: 0` without asking. New content is capped at 1000 characters — for longer text use `delete_statements` then `create_knowledge_graph`. Never called on the assistant's own initiative.
+
+**Parameters** (one mode per call, besides `graphName`):
+- `graphName` (string, required): Graph in the user's own account (must exist; there is no `userName`)
+- Mode A — `edits` (array): one item per statement to rewrite, each with exactly one of `match` (its exact current text, e.g. from `analyze_existing_graph_by_name` with `includeStatements`) or `statementId`, and at least one of `content`, `categories` (full replacement), `timestamp` (ISO 8601). Items that match nothing are reported as `unmatched`
+- Mode B — exactly one selector: `categories` (string[]), `statements` (string[]), `query` (substring or `/regex/flags`), `before`/`after` (ISO 8601 window), `all` (boolean), `statementIds` (number[]) — plus at least one of:
+  - `set` (object): `addCategories`, `removeCategories`, `categories` (full replacement; exclusive with add/remove), `timestamp`
+  - `replace` (object): `{ pattern, with }` — substring or `/regex/flags`, applied to the text of every selected statement (e.g. rename a `[[concept]]` or a source path everywhere)
+- `confirm` (boolean, default false): Perform the update
+
+**Returns**: dry run — `dryRun: true`, `matchedCount`, `updatedCount` (how many would change), `changes` (id, before, after; capped at 50), `unchanged`, `unmatched`, `rejected`, `mode`, `filter`, `nextStep`; after confirmation — `updated`, `changes`, `unchanged`, `unmatched`, `rejected`, `graphName`, `graphUrl` (plus a `note` when the write's count differs from the preview).
+
+**Typical use**: fix a wrong statement without losing its place (`edits` with `match` and the new `content`), relabel a batch (`categories` selector with `set.addCategories`), or rename a concept or a source path across a graph (`all: true` with `replace`).
+
+---
+
 ### memory_add_relations
 
 Add relations to a knowledge graph memory. Creates the graph if it doesn't exist. By default uses `extractEntitiesOnly` for automatic entity detection, creating a high-level concept graph.

package/llms-full.txt

@@ -37,7 +37,7 @@ Get API key at: https://infranodus.com/api-access
 7. **Comparing texts**: `overlap_between_texts` (similarities), `difference_between_texts` (what's missing in first text), `merged_graph_from_texts` (combined overview).
 8. **SEO/content optimization**: `generate_seo_report` (comprehensive, ~90s timeout needed) or run `analyze_google_search_results` → `analyze_related_search_queries` → `search_queries_vs_search_results` individually.
 9. **Memory**: `memory_add_relations` to persist knowledge graphs, `memory_get_relations` to retrieve. Use `[[wikilinks]]` for entity marking.
-10. **Graph management**: `list_graphs` to discover existing graphs, `search` + `fetch` for content retrieval.
+10. **Graph management**: `list_graphs` to discover existing graphs, `search` + `fetch` for content retrieval, `delete_statements` to remove statements from your own graph by filter and `update_statements` to edit them in place (both dry run unless `confirm: true`; irreversible).
 
 ---
 
@@ -321,6 +321,44 @@ Fetch specific statements from a search result using the ID from `search`.
 
 ---
 
+### delete_statements
+
+Delete statements from a graph in the user's own account, selected by one filter the server resolves. Irreversible once confirmed. Dry run by default: the response reports the matched count, a sample of the matched statements, and a per-category breakdown, and nothing is removed until the same filter is sent again with `confirm: true` (clients with MCP elicitation ask the user directly in the same call). A filter that matches nothing returns `deleted: 0` without asking. Never called on the assistant's own initiative.
+
+**Parameters** (exactly one selector besides `graphName`):
+- `graphName` (string, required): Graph in the user's own account (must exist; there is no `userName`)
+- `categories` (string[]): Statements carrying any of these labels — everything from one source (a file path, page name, or `[[label]]` parent)
+- `statements` (string[]): Exact statement text
+- `query` (string): Case-insensitive substring, or `/regex/flags`
+- `before`, `after` (ISO 8601): Time window; together they count as one selector
+- `deleteAll` (boolean): Empty the graph but keep it (name, URL, settings survive)
+- `statementIds` (number[]): Advanced; foreign ids are reported as `ignoredIds`
+- `confirm` (boolean, default false): Perform the deletion
+
+**Returns**: dry run — `dryRun: true`, `matchedCount`, `matched` (id, content, categories, timestamp), `matchedByCategory`, `filter`, `nextStep`; after confirmation — `deleted`, `removedIds`, `ignoredIds`, `remaining`, `graphName`, `graphUrl`.
+
+**Typical use**: replace one source's statements after it changed (`delete_statements` with its category, then `create_knowledge_graph` to the same `graphName`), or rebuild a graph in place (`deleteAll`, then `create_knowledge_graph`).
+
+---
+
+### update_statements
+
+Edit statements of a graph in the user's own account IN PLACE — their content, categories, or timestamp — keeping each statement's id, date, and position (unlike deleting and re-creating it). Irreversible once confirmed: the previous text survives only in the dry-run output. Dry run by default: the response reports the matched count and the before → after of every change, and nothing is written until the same arguments are sent again with `confirm: true` (clients with MCP elicitation ask the user directly in the same call). A request that matches nothing returns `updated: 0` without asking. New content is capped at 1000 characters — for longer text use `delete_statements` then `create_knowledge_graph`. Never called on the assistant's own initiative.
+
+**Parameters** (one mode per call, besides `graphName`):
+- `graphName` (string, required): Graph in the user's own account (must exist; there is no `userName`)
+- Mode A — `edits` (array): one item per statement to rewrite, each with exactly one of `match` (its exact current text, e.g. from `analyze_existing_graph_by_name` with `includeStatements`) or `statementId`, and at least one of `content`, `categories` (full replacement), `timestamp` (ISO 8601). Items that match nothing are reported as `unmatched`
+- Mode B — exactly one selector: `categories` (string[]), `statements` (string[]), `query` (substring or `/regex/flags`), `before`/`after` (ISO 8601 window), `all` (boolean), `statementIds` (number[]) — plus at least one of:
+  - `set` (object): `addCategories`, `removeCategories`, `categories` (full replacement; exclusive with add/remove), `timestamp`
+  - `replace` (object): `{ pattern, with }` — substring or `/regex/flags`, applied to the text of every selected statement (e.g. rename a `[[concept]]` or a source path everywhere)
+- `confirm` (boolean, default false): Perform the update
+
+**Returns**: dry run — `dryRun: true`, `matchedCount`, `updatedCount` (how many would change), `changes` (id, before, after; capped at 50), `unchanged`, `unmatched`, `rejected`, `mode`, `filter`, `nextStep`; after confirmation — `updated`, `changes`, `unchanged`, `unmatched`, `rejected`, `graphName`, `graphUrl` (plus a `note` when the write's count differs from the preview).
+
+**Typical use**: fix a wrong statement without losing its place (`edits` with `match` and the new `content`), relabel a batch (`categories` selector with `set.addCategories`), or rename a concept or a source path across a graph (`all: true` with `replace`).
+
+---
+
 ### memory_add_relations
 
 Add relations to a knowledge graph memory. Creates the graph if it doesn't exist. By default uses `extractEntitiesOnly` for automatic entity detection, creating a high-level concept graph.

package/llms.infranodus.txt

@@ -56,6 +56,8 @@
 - list_graphs: List all graphs with filtering by name, type, date, language
 - search: Search through existing InfraNodus graphs
 - fetch: Fetch specific search results from a graph
+- delete_statements: Delete statements from your own graph by one filter (categories, statements, query, before/after, deleteAll, statementIds); dry run unless confirm: true; irreversible
+- update_statements: Edit statements of your own graph in place (content, categories, timestamp) keeping id and position — specific statements by exact text or id (edits), or one selector with set/replace for bulk relabelling and find-and-replace; dry run showing before → after unless confirm: true; irreversible
 
 ## Optional
 

package/llms.txt

@@ -56,6 +56,8 @@
 - list_graphs: List all graphs with filtering by name, type, date, language
 - search: Search through existing InfraNodus graphs
 - fetch: Fetch specific search results from a graph
+- delete_statements: Delete statements from your own graph by one filter (categories, statements, query, before/after, deleteAll, statementIds); dry run unless confirm: true; irreversible
+- update_statements: Edit statements of your own graph in place (content, categories, timestamp) keeping id and position — specific statements by exact text or id (edits), or one selector with set/replace for bulk relabelling and find-and-replace; dry run showing before → after unless confirm: true; irreversible
 
 ## Optional
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "keywordgraph-mcp-server",
-	"version": "1.7.4",
+	"version": "1.8.4",
 	"description": "KeywordGraph MCP server - A Model Context Protocol server for network thinking and graph analysis",
 	"type": "module",
 	"module": "src/index.ts",
@@ -52,7 +52,8 @@
 		"deploy:exalt": "fly deploy -c fly.exaltgrowth.toml",
 		"publish:in": "npm run build:inspect && node scripts/publish-brand.mjs infranodus",
 		"publish:kg": "npm run build:inspect && node scripts/publish-brand.mjs keywordgraph",
-		"prepublishOnly": "npm run build:inspect"
+		"prepublishOnly": "npm run build:inspect",
+		"test": "npm run build:inspect && node --test 'test/**/*.test.mjs'"
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.18.0",