@coreidentitylabs/open-graph-memory-mcp 1.0.1

package/src/encoding/embedder.ts

@@ -0,0 +1,93 @@
+// =============================================================================
+// Embedding Service — Lightweight text-to-vector without external dependencies
+// =============================================================================
+// Uses character n-gram hashing for offline, zero-dependency embeddings.
+// If an LLM provider is configured, it can be used for higher-quality embeddings.
+// =============================================================================
+
+const EMBEDDING_DIM = 256;
+
+/**
+ * Generate a lightweight embedding from text using character n-gram hashing.
+ * This is a simple, deterministic approach that works offline without any API.
+ * Quality is lower than neural embeddings but sufficient for basic similarity.
+ */
+export function generateLocalEmbedding(text: string): number[] {
+  const normalized = text.toLowerCase().trim();
+  const vector = new Float64Array(EMBEDDING_DIM).fill(0);
+
+  // Character trigram hashing
+  for (let i = 0; i < normalized.length - 2; i++) {
+    const trigram = normalized.substring(i, i + 3);
+    const hash = hashString(trigram);
+    const index = Math.abs(hash) % EMBEDDING_DIM;
+    // Random-ish sign based on hash
+    const sign = hash > 0 ? 1 : -1;
+    vector[index] += sign;
+  }
+
+  // Word-level hashing for broader semantic signals
+  const words = normalized.split(/\s+/).filter((w) => w.length > 0);
+  for (const word of words) {
+    const hash = hashString(word);
+    const index = Math.abs(hash) % EMBEDDING_DIM;
+    vector[index] += hash > 0 ? 0.5 : -0.5;
+  }
+
+  // Word bigram hashing for phrase-level patterns
+  for (let i = 0; i < words.length - 1; i++) {
+    const bigram = `${words[i]} ${words[i + 1]}`;
+    const hash = hashString(bigram);
+    const index = Math.abs(hash) % EMBEDDING_DIM;
+    vector[index] += hash > 0 ? 0.3 : -0.3;
+  }
+
+  // L2 normalize
+  return l2Normalize(Array.from(vector));
+}
+
+/**
+ * Compute cosine similarity between two vectors.
+ * Returns a value between -1 and 1 (1 = identical, 0 = orthogonal).
+ */
+export function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length || a.length === 0) return 0;
+
+  let dotProduct = 0;
+  let normA = 0;
+  let normB = 0;
+
+  for (let i = 0; i < a.length; i++) {
+    dotProduct += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+
+  const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+  if (denominator === 0) return 0;
+
+  return dotProduct / denominator;
+}
+
+/**
+ * L2 normalize a vector (unit length).
+ */
+function l2Normalize(vector: number[]): number[] {
+  let norm = 0;
+  for (const v of vector) norm += v * v;
+  norm = Math.sqrt(norm);
+  if (norm === 0) return vector;
+  return vector.map((v) => v / norm);
+}
+
+/**
+ * Simple deterministic string hash (djb2 variant).
+ */
+function hashString(str: string): number {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    // hash * 33 + char
+    hash = ((hash << 5) + hash + str.charCodeAt(i)) | 0;
+  }
+  return hash;
+}

package/src/encoding/pipeline.ts

@@ -0,0 +1,197 @@
+// =============================================================================
+// Encoding Pipeline — Server-Side Entity Extraction + Storage
+// =============================================================================
+// Orchestrates: LLM extraction → entity resolution → embedding → storage
+// Only available when LLM_API_KEY is configured.
+// =============================================================================
+
+import { v4 as uuidv4 } from "uuid";
+import type {
+  StorageBackend,
+  LLMProvider,
+  MemoryNode,
+  MemoryEdge,
+  ExtractionResult,
+  NodeType,
+} from "../types.js";
+import { generateLocalEmbedding } from "./embedder.js";
+
+export interface EncodingResult {
+  entitiesCreated: number;
+  entitiesUpdated: number;
+  relationsCreated: number;
+  details: {
+    entities: { id: string; name: string; status: string }[];
+    relations: {
+      source: string;
+      target: string;
+      relation: string;
+      status: string;
+    }[];
+  };
+}
+
+/**
+ * Full server-side encoding pipeline:
+ * 1. Extract entities + relations from text using LLM
+ * 2. Resolve entities against existing graph (avoid duplicates)
+ * 3. Generate embeddings (LLM embeddings if available, local fallback)
+ * 4. Store nodes and edges
+ */
+export async function encodeText(
+  text: string,
+  store: StorageBackend,
+  llm: LLMProvider,
+): Promise<EncodingResult> {
+  const result: EncodingResult = {
+    entitiesCreated: 0,
+    entitiesUpdated: 0,
+    relationsCreated: 0,
+    details: { entities: [], relations: [] },
+  };
+
+  // Step 1: Get existing entity names for resolution
+  const { nodes: existingNodes } = await store.getAllNodes(10000, 0);
+  const existingNames = existingNodes.map((n) => n.name);
+
+  // Step 2: Extract entities and relations via LLM
+  let extraction: ExtractionResult;
+  try {
+    extraction = await llm.extractEntitiesAndRelations(text, existingNames);
+  } catch (error) {
+    console.error("[open-memory] LLM extraction failed:", error);
+    throw new Error(
+      `LLM extraction failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  if (extraction.entities.length === 0 && extraction.relations.length === 0) {
+    return result;
+  }
+
+  // Step 3: Store entities (with resolution)
+  const entityNameToId = new Map<string, string>();
+
+  // Pre-populate with existing entities
+  for (const node of existingNodes) {
+    entityNameToId.set(node.name.toLowerCase(), node.id);
+  }
+
+  for (const entity of extraction.entities) {
+    const nameLower = entity.name.toLowerCase();
+    const existingNode = await store.getNodeByName(entity.name);
+
+    // Generate embedding — try LLM first, fall back to local
+    let embedding: number[];
+    try {
+      embedding = await llm.generateEmbedding(
+        `${entity.name}: ${entity.description}`,
+      );
+    } catch {
+      embedding = generateLocalEmbedding(
+        `${entity.name} ${entity.description}`,
+      );
+    }
+
+    if (existingNode) {
+      // Update existing entity with richer description
+      const mergedDescription =
+        existingNode.description.length >= entity.description.length
+          ? existingNode.description
+          : entity.description;
+
+      await store.updateNode(existingNode.id, {
+        description: mergedDescription,
+        embedding,
+        metadata: { ...existingNode.metadata, ...entity.metadata },
+      });
+
+      entityNameToId.set(nameLower, existingNode.id);
+      result.entitiesUpdated++;
+      result.details.entities.push({
+        id: existingNode.id,
+        name: entity.name,
+        status: "updated",
+      });
+    } else {
+      // Create new entity
+      const now = new Date().toISOString();
+      const node: MemoryNode = {
+        id: uuidv4(),
+        name: entity.name,
+        type: entity.type as NodeType,
+        description: entity.description,
+        embedding,
+        metadata: entity.metadata ?? {},
+        createdAt: now,
+        updatedAt: now,
+        source: "llm_extraction",
+        accessCount: 0,
+      };
+
+      await store.addNode(node);
+      entityNameToId.set(nameLower, node.id);
+      result.entitiesCreated++;
+      result.details.entities.push({
+        id: node.id,
+        name: entity.name,
+        status: "created",
+      });
+    }
+  }
+
+  // Step 4: Store relations
+  for (const rel of extraction.relations) {
+    const sourceId = entityNameToId.get(rel.source.toLowerCase()) ?? null;
+    const targetId = entityNameToId.get(rel.target.toLowerCase()) ?? null;
+
+    if (!sourceId || !targetId) {
+      result.details.relations.push({
+        source: rel.source,
+        target: rel.target,
+        relation: rel.relation,
+        status: `skipped: ${!sourceId ? `source '${rel.source}' not found` : `target '${rel.target}' not found`}`,
+      });
+      continue;
+    }
+
+    // Avoid duplicate edges
+    const existingEdges = await store.getEdgesBetween(sourceId, targetId);
+    const duplicate = existingEdges.find((e) => e.relation === rel.relation);
+
+    if (duplicate) {
+      result.details.relations.push({
+        source: rel.source,
+        target: rel.target,
+        relation: rel.relation,
+        status: "skipped: duplicate",
+      });
+      continue;
+    }
+
+    const now = new Date().toISOString();
+    const edge: MemoryEdge = {
+      id: uuidv4(),
+      source: sourceId,
+      target: targetId,
+      relation: rel.relation,
+      description:
+        rel.description ?? `${rel.source} ${rel.relation} ${rel.target}`,
+      weight: rel.weight ?? 0.8,
+      metadata: {},
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    await store.addEdge(edge);
+    result.relationsCreated++;
+    result.details.relations.push({
+      source: rel.source,
+      target: rel.target,
+      relation: rel.relation,
+      status: "created",
+    });
+  }
+
+  return result;
+}

package/src/evolution/consolidator.ts

@@ -0,0 +1,281 @@
+// =============================================================================
+// Memory Evolution Engine — Consolidation, Dedup, Inference, Pruning
+// =============================================================================
+
+import type {
+  StorageBackend,
+  MemoryNode,
+  MemoryEdge,
+  ConsolidationResult,
+  ConsolidationStrategy,
+} from "../types.js";
+import { cosineSimilarity } from "../encoding/embedder.js";
+import {
+  DUPLICATE_SIMILARITY_THRESHOLD,
+  MIN_EDGE_WEIGHT,
+  STALE_NODE_AGE_DAYS,
+} from "../constants.js";
+
+/**
+ * Run memory consolidation to keep the graph healthy.
+ *
+ * Strategies:
+ * - full: runs all operations
+ * - merge_only: only merge duplicates
+ * - prune_only: only prune stale nodes
+ * - infer_only: only infer transitive edges
+ */
+export async function consolidateMemory(
+  store: StorageBackend,
+  strategy: ConsolidationStrategy = "full",
+): Promise<ConsolidationResult> {
+  const startTime = Date.now();
+  const result: ConsolidationResult = {
+    mergedNodes: 0,
+    resolvedConflicts: 0,
+    inferredEdges: 0,
+    prunedNodes: 0,
+    duration: 0,
+  };
+
+  if (strategy === "full" || strategy === "merge_only") {
+    const mergeResult = await mergeDuplicates(store);
+    result.mergedNodes = mergeResult.merged;
+    result.resolvedConflicts = mergeResult.conflicts;
+  }
+
+  if (strategy === "full" || strategy === "infer_only") {
+    result.inferredEdges = await inferTransitiveEdges(store);
+  }
+
+  if (strategy === "full" || strategy === "prune_only") {
+    result.prunedNodes = await pruneStaleNodes(store);
+  }
+
+  result.duration = Date.now() - startTime;
+  return result;
+}
+
+// -----------------------------------------------------------------------------
+// Duplicate Merging
+// -----------------------------------------------------------------------------
+
+async function mergeDuplicates(
+  store: StorageBackend,
+): Promise<{ merged: number; conflicts: number }> {
+  const { nodes } = await store.getAllNodes(10000, 0);
+  let merged = 0;
+  let conflicts = 0;
+  const processedIds = new Set<string>();
+
+  for (let i = 0; i < nodes.length; i++) {
+    if (processedIds.has(nodes[i].id)) continue;
+
+    for (let j = i + 1; j < nodes.length; j++) {
+      if (processedIds.has(nodes[j].id)) continue;
+
+      const nodeA = nodes[i];
+      const nodeB = nodes[j];
+
+      // Check name similarity
+      const nameMatch =
+        nodeA.name.toLowerCase() === nodeB.name.toLowerCase() ||
+        levenshteinSimilarity(
+          nodeA.name.toLowerCase(),
+          nodeB.name.toLowerCase(),
+        ) > 0.85;
+
+      // Check embedding similarity if both have embeddings
+      let embeddingSimilar = false;
+      if (
+        nodeA.embedding &&
+        nodeB.embedding &&
+        nodeA.embedding.length > 0 &&
+        nodeB.embedding.length > 0
+      ) {
+        const sim = cosineSimilarity(nodeA.embedding, nodeB.embedding);
+        embeddingSimilar = sim > DUPLICATE_SIMILARITY_THRESHOLD;
+      }
+
+      if (nameMatch || embeddingSimilar) {
+        // Merge B into A (keep the older/more accessed node)
+        const keepNode = nodeA.accessCount >= nodeB.accessCount ? nodeA : nodeB;
+        const removeNode = keepNode === nodeA ? nodeB : nodeA;
+
+        // Merge descriptions
+        const mergedDescription =
+          keepNode.description.length >= removeNode.description.length
+            ? keepNode.description
+            : `${keepNode.description} | ${removeNode.description}`;
+
+        // Re-point edges from removeNode to keepNode
+        const edges = await store.getEdgesForNode(removeNode.id);
+        for (const edge of edges) {
+          const newEdge: MemoryEdge = {
+            ...edge,
+            source: edge.source === removeNode.id ? keepNode.id : edge.source,
+            target: edge.target === removeNode.id ? keepNode.id : edge.target,
+            updatedAt: new Date().toISOString(),
+          };
+          // Skip self-loops
+          if (newEdge.source === newEdge.target) continue;
+
+          // Check if we already have this edge
+          const existing = await store.getEdgesBetween(
+            newEdge.source,
+            newEdge.target,
+          );
+          const duplicate = existing.find(
+            (e) => e.relation === newEdge.relation,
+          );
+          if (!duplicate) {
+            await store.addEdge(newEdge);
+          }
+        }
+
+        // Update kept node and delete merged node
+        await store.updateNode(keepNode.id, {
+          description: mergedDescription,
+          accessCount: keepNode.accessCount + removeNode.accessCount,
+        });
+        await store.deleteNode(removeNode.id);
+
+        processedIds.add(removeNode.id);
+        merged++;
+
+        // Check for temporal conflicts
+        if (
+          keepNode.validUntil &&
+          removeNode.validFrom &&
+          keepNode.validUntil < removeNode.validFrom
+        ) {
+          conflicts++;
+        }
+      }
+    }
+  }
+
+  return { merged, conflicts };
+}
+
+// -----------------------------------------------------------------------------
+// Transitive Edge Inference
+// -----------------------------------------------------------------------------
+
+async function inferTransitiveEdges(store: StorageBackend): Promise<number> {
+  const { nodes } = await store.getAllNodes(10000, 0);
+  let inferred = 0;
+
+  for (const node of nodes) {
+    const outEdges = await store.getEdgesForNode(node.id, "out");
+
+    for (const edgeAB of outEdges) {
+      // A -> B, now look for B -> C
+      const nextEdges = await store.getEdgesForNode(edgeAB.target, "out");
+
+      for (const edgeBC of nextEdges) {
+        // Skip if A == C (no self-loops)
+        if (edgeBC.target === node.id) continue;
+
+        // Check if A -> C edge already exists
+        const existing = await store.getEdgesBetween(node.id, edgeBC.target);
+        if (existing.length > 0) continue;
+
+        // Only infer for certain relationship types
+        if (
+          edgeAB.relation === edgeBC.relation &&
+          isTransitiveRelation(edgeAB.relation)
+        ) {
+          const { v4: uuidv4 } = await import("uuid");
+          const now = new Date().toISOString();
+          await store.addEdge({
+            id: uuidv4(),
+            source: node.id,
+            target: edgeBC.target,
+            relation: edgeAB.relation,
+            description: `Inferred: transitive ${edgeAB.relation}`,
+            weight: Math.min(edgeAB.weight, edgeBC.weight) * 0.8,
+            metadata: { inferred: true },
+            createdAt: now,
+            updatedAt: now,
+          });
+          inferred++;
+        }
+      }
+    }
+  }
+
+  return inferred;
+}
+
+function isTransitiveRelation(relation: string): boolean {
+  const transitiveRelations = [
+    "depends_on",
+    "part_of",
+    "belongs_to",
+    "contains",
+    "extends",
+    "imports",
+  ];
+  return transitiveRelations.includes(relation);
+}
+
+// -----------------------------------------------------------------------------
+// Stale Node Pruning
+// -----------------------------------------------------------------------------
+
+async function pruneStaleNodes(store: StorageBackend): Promise<number> {
+  const { nodes } = await store.getAllNodes(10000, 0);
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - STALE_NODE_AGE_DAYS);
+  const cutoffStr = cutoff.toISOString();
+  let pruned = 0;
+
+  for (const node of nodes) {
+    // Don't prune conversations or decisions (high-value types)
+    if (node.type === "conversation" || node.type === "decision") continue;
+
+    // Prune if never accessed and old
+    const lastActivity = node.lastAccessedAt ?? node.updatedAt;
+    if (lastActivity < cutoffStr && node.accessCount === 0) {
+      await store.deleteNode(node.id);
+      pruned++;
+    }
+  }
+
+  return pruned;
+}
+
+// -----------------------------------------------------------------------------
+// Utilities
+// -----------------------------------------------------------------------------
+
+function levenshteinSimilarity(a: string, b: string): number {
+  const maxLen = Math.max(a.length, b.length);
+  if (maxLen === 0) return 1;
+  return 1 - levenshteinDistance(a, b) / maxLen;
+}
+
+function levenshteinDistance(a: string, b: string): number {
+  const m = a.length;
+  const n = b.length;
+  const dp: number[][] = Array.from({ length: m + 1 }, () =>
+    Array(n + 1).fill(0),
+  );
+
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i][j] = Math.min(
+        dp[i - 1][j] + 1,
+        dp[i][j - 1] + 1,
+        dp[i - 1][j - 1] + cost,
+      );
+    }
+  }
+
+  return dp[m][n];
+}

package/src/index.ts

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// =============================================================================
+// Open-Memory MCP Server — Entry Point
+// =============================================================================
+// Graph-based agent memory for AI coding assistants.
+// Extends context window by storing entities, relationships, and decisions
+// in a persistent knowledge graph accessible via MCP tools.
+// =============================================================================
+
+import dotenv from "dotenv";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createStorageBackend } from "./storage/factory.js";
+import { registerMemoryTools } from "./tools/memory-tools.js";
+import { registerMemoryResources } from "./resources/context-resource.js";
+import { createLLMProvider } from "./llm/provider.js";
+import { SERVER_NAME, SERVER_VERSION } from "./constants.js";
+
+// Load environment variables
+dotenv.config();
+
+async function main(): Promise<void> {
+  console.error(`[open-memory] Starting ${SERVER_NAME} v${SERVER_VERSION}...`);
+
+  // 1. Initialize storage backend
+  const store = createStorageBackend();
+  await store.initialize();
+
+  // 2. Initialize optional LLM provider
+  const llm = createLLMProvider();
+
+  // 3. Create MCP server
+  const server = new McpServer({
+    name: SERVER_NAME,
+    version: SERVER_VERSION,
+  });
+
+  // 4. Register tools and resources
+  registerMemoryTools(server, store, llm);
+  registerMemoryResources(server, store);
+
+  const toolCount = llm ? 12 : 11;
+  console.error(`[open-memory] Registered ${toolCount} tools and 2 resources`);
+
+  // 5. Connect via stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  console.error(
+    `[open-memory] Server running via stdio. Ready for connections.`,
+  );
+
+  // Graceful shutdown
+  const shutdown = async () => {
+    console.error(`[open-memory] Shutting down...`);
+    await store.close();
+    process.exit(0);
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
+main().catch((error) => {
+  console.error(`[open-memory] Fatal error:`, error);
+  process.exit(1);
+});