oh-memos-mcp 2.0.0 → 2.1.0

package/dist/graph-provenance.js

@@ -0,0 +1,175 @@
+/**
+ * Provenance helpers shared by memory-graph responses and the Graphify
+ * node-link importer.
+ *
+ * Graphify calls the categorical edge field `confidence` while oh-memos
+ * memory records historically use `confidence`, `source` and `sources` for
+ * several different purposes.  This module deliberately normalizes at the
+ * boundary instead of changing old Neo4j properties in place.
+ */
+export const EVIDENCE_KINDS = ["EXTRACTED", "INFERRED", "AMBIGUOUS", "UNKNOWN"];
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function firstString(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "string" && value.trim())
+            return value.trim();
+    }
+    return undefined;
+}
+function normalizeKind(value) {
+    if (typeof value !== "string")
+        return "UNKNOWN";
+    const normalized = value.trim().toUpperCase();
+    return EVIDENCE_KINDS.includes(normalized)
+        ? normalized
+        : "UNKNOWN";
+}
+function normalizeScore(...values) {
+    for (const value of values) {
+        if (typeof value === "string" && EVIDENCE_KINDS.includes(value.trim().toUpperCase())) {
+            continue;
+        }
+        const score = Number(value);
+        if (!Number.isFinite(score))
+            continue;
+        return Math.max(0, Math.min(1, score));
+    }
+    return undefined;
+}
+function addRef(refs, value) {
+    if (typeof value !== "string")
+        return;
+    const ref = value.trim();
+    if (ref && !refs.includes(ref))
+        refs.push(ref);
+}
+function collectRefs(record, sourceFile, sourceLocation) {
+    const refs = [];
+    const rawRefs = record.evidence_refs ?? record.evidenceRefs ?? record.sources;
+    if (Array.isArray(rawRefs)) {
+        for (const item of rawRefs) {
+            if (typeof item === "string") {
+                addRef(refs, item);
+            }
+            else {
+                const nested = asRecord(item);
+                const nestedFile = firstString(nested, ["source_file", "sourceFile", "file", "path"]);
+                const nestedLocation = firstString(nested, ["source_location", "sourceLocation", "location", "line"]);
+                if (nestedFile && nestedLocation)
+                    addRef(refs, `${nestedFile}:${nestedLocation}`);
+                else
+                    addRef(refs, nestedFile ?? firstString(nested, ["ref", "uri", "source_ref"]));
+            }
+        }
+    }
+    addRef(refs, record.source_ref);
+    addRef(refs, record.sourceRef);
+    // An explicit evidence_refs/source_ref is authoritative.  Only synthesize
+    // a file anchor when legacy data has no explicit reference at all; this
+    // keeps output compact while retaining useful provenance for old records.
+    if (refs.length === 0) {
+        if (sourceFile && sourceLocation)
+            addRef(refs, `${sourceFile}:${sourceLocation}`);
+        else if (sourceFile)
+            addRef(refs, sourceFile);
+    }
+    return refs;
+}
+/** Normalize old memory/Neo4j/Graphify fields without making provenance claims. */
+export function normalizeProvenance(value) {
+    const record = asRecord(value);
+    const nested = asRecord(record.provenance);
+    const merged = { ...nested, ...record };
+    const sourceFile = firstString(merged, ["source_file", "sourceFile"]);
+    const sourceLocation = firstString(merged, ["source_location", "sourceLocation"]);
+    const sourceRef = firstString(merged, ["source_ref", "sourceRef"]);
+    const kind = normalizeKind(merged.evidence_kind
+        ?? merged.evidenceKind
+        ?? (typeof merged.confidence === "string" ? merged.confidence : undefined)
+        ?? merged.kind
+        ?? merged.provenance_kind);
+    const score = normalizeScore(merged.confidence_score, merged.confidence, merged.weight);
+    const result = {
+        evidence_kind: kind,
+        evidence_refs: collectRefs(merged, sourceFile, sourceLocation),
+    };
+    if (score !== undefined)
+        result.confidence_score = score;
+    if (sourceFile)
+        result.source_file = sourceFile;
+    if (sourceLocation)
+        result.source_location = sourceLocation;
+    if (sourceRef)
+        result.source_ref = sourceRef;
+    const extractorVersion = firstString(merged, ["extractor_version", "extractorVersion"]);
+    const lastVerifiedAt = firstString(merged, ["last_verified_at", "lastVerifiedAt"]);
+    if (extractorVersion)
+        result.extractor_version = extractorVersion;
+    if (lastVerifiedAt)
+        result.last_verified_at = lastVerifiedAt;
+    return result;
+}
+/** Render a compact, deterministic explanation suitable for MCP Markdown. */
+export function formatProvenance(value) {
+    const provenance = normalizeProvenance(value);
+    const parts = [`evidence=${provenance.evidence_kind}`];
+    if (provenance.confidence_score !== undefined) {
+        parts.push(`confidence=${provenance.confidence_score.toFixed(2)}`);
+    }
+    const source = provenance.source_file
+        ? provenance.source_location
+            ? `${provenance.source_file}:${provenance.source_location}`
+            : provenance.source_file
+        : provenance.source_ref;
+    if (source)
+        parts.push(`source=${source}`);
+    if (provenance.evidence_refs.length > 0)
+        parts.push(`refs=${provenance.evidence_refs.join(",")}`);
+    if (provenance.extractor_version)
+        parts.push(`extractor=${provenance.extractor_version}`);
+    if (provenance.last_verified_at)
+        parts.push(`verified=${provenance.last_verified_at}`);
+    return parts.join("; ");
+}
+/**
+ * Normalize a project-relative path for a stable code-symbol identity.
+ * Absolute paths and traversal segments are rejected before they can enter a
+ * graph ID or an import plan.
+ */
+export function normalizeProjectRelativePath(value) {
+    const raw = value.trim().replaceAll("\\", "/");
+    if (!raw || raw.startsWith("/") || /^[A-Za-z]:\//.test(raw) || raw.startsWith("//")) {
+        throw new Error("source path must be project-relative, not absolute");
+    }
+    const parts = [];
+    for (const part of raw.split("/")) {
+        if (!part || part === ".")
+            continue;
+        if (part === "..")
+            throw new Error("source path must be project-relative and must not contain traversal segments");
+        parts.push(part);
+    }
+    if (parts.length === 0)
+        throw new Error("source path must be a non-empty project-relative path");
+    return parts.join("/");
+}
+function slug(value) {
+    const normalized = value.normalize("NFKC").toLocaleLowerCase("en-US");
+    return normalized
+        .replace(/[^\p{L}\p{N}]+/gu, "_")
+        .replace(/^_+|_+$/g, "") || "unknown";
+}
+/** Stable, portable ID for a code node imported from an external graph. */
+export function stableCodeNodeId(projectRelativePath, language, symbol, signature) {
+    const path = normalizeProjectRelativePath(projectRelativePath);
+    const parts = [path, language, symbol];
+    if (signature?.trim())
+        parts.push(signature);
+    return `code:${parts.map(slug).join(":")}`;
+}
+//# sourceMappingURL=graph-provenance.js.map

package/dist/graphify-import.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Pure Graphify node-link importer boundary.
+ *
+ * This module intentionally produces a dry-run plan only.  A later adapter
+ * may apply the plan to Neo4j, but parsing and safety checks must be testable
+ * without a database or a filesystem write.
+ */
+import { type NormalizedProvenance } from "./graph-provenance.js";
+export interface GraphifyNode {
+    id: string;
+    label?: string;
+    file_type?: string;
+    language?: string;
+    source_file?: string;
+    source_location?: string;
+    community?: number | string;
+    [key: string]: unknown;
+}
+export interface GraphifyLink {
+    source?: string;
+    target?: string;
+    _src?: string;
+    _tgt?: string;
+    relation?: string;
+    type?: string;
+    confidence?: string | number;
+    confidence_score?: number;
+    source_file?: string;
+    source_location?: string;
+    weight?: number;
+    [key: string]: unknown;
+}
+export interface GraphImportOptions {
+    projectKey?: string;
+    maxNodes?: number;
+    maxEdges?: number;
+}
+export interface GraphImportNode {
+    external_id: string;
+    stable_id: string;
+    label: string;
+    node_type: "CODE_SYMBOL" | "DOCUMENT" | "CODE_NODE";
+    file_type?: string;
+    source_file?: string;
+    source_location?: string;
+    community?: number | string;
+    provenance: NormalizedProvenance;
+}
+export interface GraphImportEdge {
+    source_id: string;
+    target_id: string;
+    relation: string;
+    weight?: number;
+    provenance: NormalizedProvenance;
+}
+export interface GraphImportPlan {
+    version: "graphify-node-link/v1";
+    project_key: string;
+    nodes: GraphImportNode[];
+    edges: GraphImportEdge[];
+    warnings: string[];
+    stats: {
+        nodes: number;
+        edges: number;
+        warnings: number;
+    };
+}
+/** Validate and convert a Graphify node-link JSON value into a dry-run plan. */
+export declare function buildGraphImportPlan(input: unknown, options?: GraphImportOptions): GraphImportPlan;
+/** Render a human-auditable plan; this function never performs a write. */
+export declare function renderGraphImportPlan(plan: GraphImportPlan): string;
+//# sourceMappingURL=graphify-import.d.ts.map

package/dist/graphify-import.js

@@ -0,0 +1,194 @@
+/**
+ * Pure Graphify node-link importer boundary.
+ *
+ * This module intentionally produces a dry-run plan only.  A later adapter
+ * may apply the plan to Neo4j, but parsing and safety checks must be testable
+ * without a database or a filesystem write.
+ */
+import { normalizeProjectRelativePath, normalizeProvenance, stableCodeNodeId, } from "./graph-provenance.js";
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function requiredString(value, label) {
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`${label} must be a non-empty string`);
+    return value.trim();
+}
+function safeCount(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || value < 1)
+        throw new Error("import limits must be positive integers");
+    return value;
+}
+function normalizeRelation(value) {
+    const raw = typeof value === "string" && value.trim() ? value.trim() : "RELATED_TO";
+    return raw.normalize("NFKC").toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "") || "RELATED_TO";
+}
+function languageForNode(node, sourceFile) {
+    if (typeof node.language === "string" && node.language.trim())
+        return node.language.trim();
+    const fileType = typeof node.file_type === "string" ? node.file_type.trim() : "";
+    if (fileType && fileType.toLowerCase() !== "code")
+        return fileType;
+    const extension = sourceFile?.split(".").pop();
+    return extension || "code";
+}
+function nodeTypeFor(node) {
+    const fileType = String(node.file_type ?? "code").toLowerCase();
+    if (fileType === "document" || fileType === "doc" || fileType === "pdf")
+        return "DOCUMENT";
+    if (fileType === "code" || fileType === "source")
+        return "CODE_SYMBOL";
+    return "CODE_NODE";
+}
+/** Validate and convert a Graphify node-link JSON value into a dry-run plan. */
+export function buildGraphImportPlan(input, options = {}) {
+    const root = asRecord(input);
+    if (!Array.isArray(root.nodes) || root.nodes.length === 0) {
+        throw new Error("nodes must be a non-empty array");
+    }
+    const hasLinks = root.links !== undefined;
+    const hasEdges = root.edges !== undefined;
+    const rawEdges = hasLinks ? root.links : root.edges;
+    if (rawEdges !== undefined && !Array.isArray(rawEdges)) {
+        throw new Error("links/edges must be an array");
+    }
+    const links = (rawEdges ?? []);
+    const maxNodes = safeCount(options.maxNodes, 50_000);
+    const maxEdges = safeCount(options.maxEdges, 100_000);
+    if (root.nodes.length > maxNodes)
+        throw new Error(`graph has too many nodes (max ${maxNodes})`);
+    if (links.length > maxEdges)
+        throw new Error(`graph has too many edges (max ${maxEdges})`);
+    const projectKey = requiredString(options.projectKey ?? "project", "projectKey");
+    const warnings = [];
+    if (hasLinks && hasEdges)
+        warnings.push("both links and edges were supplied; links took precedence");
+    const seenIds = new Set();
+    const nodes = [];
+    const nodeByExternalId = new Map();
+    for (const rawNode of root.nodes) {
+        const node = asRecord(rawNode);
+        const externalId = requiredString(node.id, "node id");
+        if (seenIds.has(externalId))
+            throw new Error(`duplicate node id '${externalId}'`);
+        seenIds.add(externalId);
+        const sourceFile = node.source_file === undefined
+            ? undefined
+            : normalizeProjectRelativePath(requiredString(node.source_file, `source_file for '${externalId}'`));
+        const label = typeof node.label === "string" && node.label.trim() ? node.label.trim() : externalId;
+        const stableId = stableCodeNodeId(sourceFile ?? externalId, languageForNode(node, sourceFile), label, externalId);
+        const provenance = normalizeProvenance({
+            ...node,
+            source_file: sourceFile,
+            source_location: node.source_location,
+        });
+        const imported = {
+            external_id: externalId,
+            stable_id: stableId,
+            label,
+            node_type: nodeTypeFor(node),
+            provenance,
+        };
+        if (typeof node.file_type === "string" && node.file_type.trim())
+            imported.file_type = node.file_type.trim();
+        if (sourceFile)
+            imported.source_file = sourceFile;
+        if (typeof node.source_location === "string" && node.source_location.trim())
+            imported.source_location = node.source_location.trim();
+        if (typeof node.community === "number" || typeof node.community === "string")
+            imported.community = node.community;
+        nodes.push(imported);
+        nodeByExternalId.set(externalId, imported);
+    }
+    const seenEdges = new Set();
+    const edges = [];
+    for (const rawLink of links) {
+        const link = asRecord(rawLink);
+        const source = requiredString(link.source ?? link._src, "edge source");
+        const target = requiredString(link.target ?? link._tgt, "edge target");
+        if (!nodeByExternalId.has(source))
+            throw new Error(`unknown source node '${source}'`);
+        if (!nodeByExternalId.has(target))
+            throw new Error(`unknown target node '${target}'`);
+        const relation = normalizeRelation(link.relation ?? link.type);
+        const edgeKey = `${source}\u0000${target}\u0000${relation}`;
+        if (seenEdges.has(edgeKey))
+            throw new Error(`duplicate edge '${source}' -> '${target}' (${relation})`);
+        seenEdges.add(edgeKey);
+        const provenance = normalizeProvenance(link);
+        const edge = {
+            source_id: nodeByExternalId.get(source).stable_id,
+            target_id: nodeByExternalId.get(target).stable_id,
+            relation,
+            provenance,
+        };
+        const weight = Number(link.weight);
+        if (Number.isFinite(weight))
+            edge.weight = weight;
+        edges.push(edge);
+    }
+    // Stable ordering makes review diffs and future cache keys reproducible.
+    nodes.sort((a, b) => a.stable_id.localeCompare(b.stable_id));
+    edges.sort((a, b) => `${a.source_id}:${a.relation}:${a.target_id}`.localeCompare(`${b.source_id}:${b.relation}:${b.target_id}`));
+    return {
+        version: "graphify-node-link/v1",
+        project_key: projectKey,
+        nodes,
+        edges,
+        warnings,
+        stats: { nodes: nodes.length, edges: edges.length, warnings: warnings.length },
+    };
+}
+function oneLine(value, max = 100) {
+    const flattened = value.replace(/[\r\n]+/g, " ").trim();
+    return flattened.length > max ? `${flattened.slice(0, max - 1)}…` : flattened;
+}
+/** Render a human-auditable plan; this function never performs a write. */
+export function renderGraphImportPlan(plan) {
+    const lines = [
+        "## Graphify Import Plan (dry-run)",
+        "",
+        `Project: \`${plan.project_key}\``,
+        `Version: \`${plan.version}\``,
+        `Nodes: **${plan.stats.nodes}** · Edges: **${plan.stats.edges}** · Warnings: **${plan.stats.warnings}**`,
+        "",
+        "> No Neo4j, Qdrant, or memory-cube data was written.",
+        "",
+    ];
+    if (plan.warnings.length > 0) {
+        lines.push("### Warnings", ...plan.warnings.map((warning) => `- ${oneLine(warning)}`), "");
+    }
+    if (plan.nodes.length > 0) {
+        lines.push("### Node preview");
+        for (const node of plan.nodes.slice(0, 8)) {
+            const location = node.source_file
+                ? ` (${node.source_file}${node.source_location ? `:${node.source_location}` : ""})`
+                : "";
+            lines.push(`- \`${node.stable_id}\` — ${oneLine(node.label)}${location}`);
+        }
+        if (plan.nodes.length > 8)
+            lines.push(`- … ${plan.nodes.length - 8} more node(s)`);
+        lines.push("");
+    }
+    if (plan.edges.length > 0) {
+        lines.push("### Edge preview");
+        for (const edge of plan.edges.slice(0, 8)) {
+            lines.push(`- \`${edge.relation}\`: \`${edge.source_id}\` → \`${edge.target_id}\` (${formatProvenanceForPlan(edge.provenance)})`);
+        }
+        if (plan.edges.length > 8)
+            lines.push(`- … ${plan.edges.length - 8} more edge(s)`);
+    }
+    return lines.join("\n");
+}
+function formatProvenanceForPlan(provenance) {
+    const score = provenance.confidence_score === undefined ? "n/a" : provenance.confidence_score.toFixed(2);
+    const source = provenance.source_file
+        ? `${provenance.source_file}${provenance.source_location ? `:${provenance.source_location}` : ""}`
+        : "no source";
+    return `${provenance.evidence_kind}, confidence ${score}, ${source}`;
+}
+//# sourceMappingURL=graphify-import.js.map

package/dist/handlers/admin.d.ts

@@ -5,6 +5,7 @@
  * memos_admin(action="validate_cubes"), memos_delete
  */
 import type { TextContent } from "../types.js";
+export declare function handleMemosCapabilities(): TextContent[];
 export declare function handleMemosListCubes(arguments_: Record<string, unknown>): Promise<TextContent[]>;
 export declare function handleMemosRegisterCube(arguments_: Record<string, unknown>): Promise<TextContent[]>;
 export declare function handleMemosCreateUser(arguments_: Record<string, unknown>): Promise<TextContent[]>;

package/dist/handlers/admin.js

@@ -11,6 +11,24 @@ import { fetchWithTimeout } from "../api-client.js";
 import { ensureCubeDirectory, ensureCubeRegistered, getCubePath, getCubesBaseDir, getLocalCubesBaseDir, listAvailableCubes, validateAndFixCubeConfig, verifyCubeLoaded, } from "../cube-manager.js";
 import { ERR_CUBE_NOT_FOUND, ERR_DELETE_DISABLED, ERR_PARAM_MISSING, apiErrorResponse, cubeRegistrationError, errorResponse, getCubeIdFromArgs, } from "./utils.js";
 // ============================================================================
+// memos_admin(action="capabilities")
+// ============================================================================
+export function handleMemosCapabilities() {
+    const mode = process.env.MEMOS_MODE?.toLowerCase() === "lite" ? "lite" : "full";
+    return [{ type: "text", text: [
+                "## MemOS capabilities",
+                "",
+                `**Mode**: ${mode}`,
+                mode === "lite"
+                    ? "Lite reuses the configured HTTP API and cube storage; it lowers search limits and filters auto-capture. It is a noise/resource policy, not an offline SQLite backend."
+                    : "Full exposes API, graph, vector, BM25, Wiki round-trip, canvas, and skill lifecycle tools.",
+                "",
+                "**tree_text update**: in-place update is unsupported; the API now fails explicitly instead of silently succeeding. Use versioned writes.",
+                "**Skill install**: requires an approved candidate and writes only to `.claude/skills/<slug>/SKILL.md`.",
+                "**Auto-capture**: disabled by default; Lite keeps it disabled.",
+            ].join("\n") }];
+}
+// ============================================================================
 // memos_admin(action="list_cubes")
 // ============================================================================
 export async function handleMemosListCubes(arguments_) {

package/dist/handlers/canvas.d.ts

@@ -0,0 +1,40 @@
+/**
+ * memos_canvas — symbolic short-term task memory.
+ *
+ * The long-term side of this server (memories, graph, wiki) answers "what do we
+ * know". The canvas answers "where was I", which is a different question with a
+ * different lifetime: it changes several times an hour, it is worthless a week
+ * later, and it must survive exactly one event — context compaction.
+ *
+ * Why a Mermaid file rather than more memories:
+ *
+ * - A memory costs an LLM extraction and an embedding on write. A status flip
+ *   from doing→done deserves neither.
+ * - The value of the canvas is its *topology* — which step follows which, and
+ *   which one is stuck. Flat memory rows lose exactly that.
+ * - `node_id` is greppable, so a node can be cited from a commit message or a
+ *   memory body and still be found later.
+ *
+ * The `ref` field is where the two halves meet: a node points at durable
+ * evidence with `mem:<uuid>` (a memory in the graph), `file:<path>` (a file the
+ * harness already offloaded), or `note:<text>`. Abstraction stays cheap, and the
+ * path back to evidence stays open.
+ *
+ * One thing this deliberately does not do: claim a token saving. That claim
+ * belongs to designs that intercept and replace tool output before the model
+ * sees it, which a Claude Code hook cannot do — PostToolUse can add context but
+ * not rewrite a result. What is on offer here is task state that survives
+ * compaction, and anchors that make a summary checkable.
+ */
+import type { TextContent } from "../types.js";
+export declare function handleMemosCanvas(arguments_: Record<string, unknown>): Promise<TextContent[]>;
+/**
+ * Active-canvas digest for `memos_context_resume`.
+ *
+ * Headlines only — a few dozen tokens for the whole index. Injecting canvas
+ * bodies here would rebuild the context bloat the canvas exists to avoid; the
+ * model opens what it needs with `show`. Never throws: this runs during session
+ * recovery, and a canvas problem must not break that.
+ */
+export declare function summarizeActiveCanvases(cubeId: string, limit?: number): string[];
+//# sourceMappingURL=canvas.d.ts.map