@coreidentitylabs/open-graph-memory-mcp 1.0.1

package/src/llm/openai-provider.ts

@@ -0,0 +1,208 @@
+// =============================================================================
+// OpenAI-Compatible LLM Provider
+// =============================================================================
+// Works with: OpenAI, Azure OpenAI, Ollama (OpenAI-compat mode), and any
+// provider exposing the OpenAI chat completions & embeddings API.
+// =============================================================================
+
+import type {
+  LLMProvider,
+  ExtractionResult,
+  ExtractedEntity,
+  ExtractedRelation,
+} from "../types.js";
+import {
+  getExtractionSystemPrompt,
+  getExtractionUserPrompt,
+} from "./prompts.js";
+
+interface ChatMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+interface ChatCompletionResponse {
+  choices: Array<{
+    message: {
+      content: string;
+    };
+  }>;
+}
+
+interface EmbeddingResponse {
+  data: Array<{
+    embedding: number[];
+  }>;
+}
+
+export class OpenAIProvider implements LLMProvider {
+  private apiKey: string;
+  private baseUrl: string;
+  private chatModel: string;
+  private embeddingModel: string;
+
+  constructor(
+    apiKey: string,
+    baseUrl: string,
+    chatModel: string,
+    embeddingModel: string,
+  ) {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/$/, ""); // strip trailing slash
+    this.chatModel = chatModel;
+    this.embeddingModel = embeddingModel;
+  }
+
+  /**
+   * Extract entities and relationships from text using the chat model.
+   */
+  async extractEntitiesAndRelations(
+    text: string,
+    existingEntities: string[],
+  ): Promise<ExtractionResult> {
+    const messages: ChatMessage[] = [
+      { role: "system", content: getExtractionSystemPrompt(existingEntities) },
+      { role: "user", content: getExtractionUserPrompt(text) },
+    ];
+
+    const responseText = await this.chatCompletion(messages);
+
+    try {
+      // Clean response — strip markdown code fences if present
+      let cleaned = responseText.trim();
+      if (cleaned.startsWith("```")) {
+        cleaned = cleaned
+          .replace(/^```(?:json)?\s*\n?/, "")
+          .replace(/\n?```\s*$/, "");
+      }
+
+      const parsed = JSON.parse(cleaned) as {
+        entities?: unknown[];
+        relations?: unknown[];
+      };
+
+      const entities: ExtractedEntity[] = (parsed.entities ?? [])
+        .map((e: unknown) => {
+          const entity = e as Record<string, unknown>;
+          return {
+            name: String(entity.name ?? ""),
+            type: validateNodeType(String(entity.type ?? "entity")),
+            description: String(entity.description ?? ""),
+            metadata: (entity.metadata as Record<string, unknown>) ?? {},
+          };
+        })
+        .filter((e) => e.name.length > 0);
+
+      const relations: ExtractedRelation[] = (parsed.relations ?? [])
+        .map((r: unknown) => {
+          const rel = r as Record<string, unknown>;
+          return {
+            source: String(rel.source ?? ""),
+            target: String(rel.target ?? ""),
+            relation: String(rel.relation ?? "related_to"),
+            description: rel.description ? String(rel.description) : undefined,
+            weight: typeof rel.weight === "number" ? rel.weight : 0.8,
+          };
+        })
+        .filter((r) => r.source.length > 0 && r.target.length > 0);
+
+      return { entities, relations };
+    } catch (parseError) {
+      console.error(
+        `[open-memory] Failed to parse LLM extraction response:`,
+        parseError,
+      );
+      console.error(`[open-memory] Raw response:`, responseText);
+      return { entities: [], relations: [] };
+    }
+  }
+
+  /**
+   * Generate a single embedding vector.
+   */
+  async generateEmbedding(text: string): Promise<number[]> {
+    const result = await this.embeddingRequest([text]);
+    return result[0] ?? [];
+  }
+
+  /**
+   * Generate embeddings for multiple texts in a single batch.
+   */
+  async generateEmbeddingBatch(texts: string[]): Promise<number[][]> {
+    return this.embeddingRequest(texts);
+  }
+
+  // ---------------------------------------------------------------------------
+  // HTTP Helpers
+  // ---------------------------------------------------------------------------
+
+  private async chatCompletion(messages: ChatMessage[]): Promise<string> {
+    const url = `${this.baseUrl}/chat/completions`;
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: this.chatModel,
+        messages,
+        temperature: 0.1,
+        max_tokens: 4096,
+      }),
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.text();
+      throw new Error(
+        `LLM chat completion failed (${response.status}): ${errorBody}`,
+      );
+    }
+
+    const data = (await response.json()) as ChatCompletionResponse;
+    return data.choices[0]?.message?.content ?? "";
+  }
+
+  private async embeddingRequest(inputs: string[]): Promise<number[][]> {
+    const url = `${this.baseUrl}/embeddings`;
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: this.embeddingModel,
+        input: inputs,
+      }),
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.text();
+      throw new Error(
+        `LLM embedding request failed (${response.status}): ${errorBody}`,
+      );
+    }
+
+    const data = (await response.json()) as EmbeddingResponse;
+    return data.data.map((d) => d.embedding);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function validateNodeType(type: string): ExtractedEntity["type"] {
+  const valid = [
+    "entity",
+    "concept",
+    "event",
+    "code_pattern",
+    "decision",
+    "conversation",
+  ];
+  return valid.includes(type) ? (type as ExtractedEntity["type"]) : "entity";
+}

package/src/llm/prompts.ts

@@ -0,0 +1,66 @@
+// =============================================================================
+// Extraction Prompts — Optimized for developer conversations
+// =============================================================================
+
+/**
+ * System prompt for entity and relationship extraction from developer conversations.
+ * Instructs the LLM to return structured JSON with entities and relations.
+ */
+export function getExtractionSystemPrompt(existingEntities: string[]): string {
+  const existingList =
+    existingEntities.length > 0
+      ? `\n\nKnown entities already in memory (use these exact names for entity resolution):\n${existingEntities.map((e) => `- ${e}`).join("\n")}`
+      : "";
+
+  return `You are a specialized entity and relationship extraction system for developer conversations.
+
+Your task is to extract structured entities and relationships from the given text.
+
+## Entity Types
+- **entity**: People, teams, organizations, tools, libraries, frameworks, services, APIs, databases
+- **concept**: Abstract ideas, design patterns, paradigms, methodologies
+- **event**: Meetings, deployments, incidents, releases, decisions made at a point in time
+- **code_pattern**: Recurring code structures, architectural patterns, implementation approaches
+- **decision**: Technical decisions with rationale (e.g., "chose React Query over SWR because...")
+- **conversation**: Conversation summaries or session references
+
+## Extraction Rules
+1. Extract SPECIFIC entities, not generic terms (e.g., "React Query" not "library")
+2. For each entity, provide a concise but informative description
+3. For relationships, use clear verb-based relation types (uses, depends_on, replaced_by, decided_to, part_of, implements, configures, deployed_to, etc.)
+4. If an entity matches one of the known entities below, use the EXACT same name
+5. Capture temporal information when present (e.g., "decided last week" → include in metadata)
+6. Focus on information a developer would want to recall later
+${existingList}
+
+## Output Format
+Return ONLY valid JSON in this exact format:
+{
+  "entities": [
+    {
+      "name": "EntityName",
+      "type": "entity|concept|event|code_pattern|decision",
+      "description": "Concise description of what this entity is and its relevance",
+      "metadata": { "optional": "key-value pairs for extra context" }
+    }
+  ],
+  "relations": [
+    {
+      "source": "SourceEntityName",
+      "target": "TargetEntityName",
+      "relation": "verb_based_relation",
+      "description": "Brief description of this relationship"
+    }
+  ]
+}
+
+Return an empty arrays if no meaningful entities or relationships can be extracted.
+Do NOT include markdown code fences or any text outside the JSON.`;
+}
+
+/**
+ * Build the user message for extraction.
+ */
+export function getExtractionUserPrompt(text: string): string {
+  return `Extract entities and relationships from the following text:\n\n${text}`;
+}

package/src/llm/provider.ts

@@ -0,0 +1,37 @@
+// =============================================================================
+// LLM Provider — Interface & Factory
+// =============================================================================
+// Optional: only loaded if LLM_API_KEY is configured.
+// Powers the memory_encode_text tool for server-side entity extraction.
+// =============================================================================
+
+import type { LLMProvider } from "../types.js";
+import { ENV_KEYS } from "../constants.js";
+import { OpenAIProvider } from "./openai-provider.js";
+
+/**
+ * Create an LLM provider if configured, or return null.
+ * The LLM provider is OPTIONAL — the agent-driven flow works without it.
+ */
+export function createLLMProvider(): LLMProvider | null {
+  const apiKey = process.env[ENV_KEYS.LLM_API_KEY];
+
+  if (!apiKey) {
+    console.error(
+      "[open-memory] No LLM_API_KEY configured. Server-side encoding (memory_encode_text) disabled.",
+    );
+    return null;
+  }
+
+  const baseUrl =
+    process.env[ENV_KEYS.LLM_BASE_URL] ?? "https://api.openai.com/v1";
+  const chatModel = process.env[ENV_KEYS.LLM_CHAT_MODEL] ?? "gpt-4o-mini";
+  const embeddingModel =
+    process.env[ENV_KEYS.LLM_EMBEDDING_MODEL] ?? "text-embedding-3-small";
+
+  console.error(
+    `[open-memory] LLM provider enabled: ${baseUrl} (chat: ${chatModel}, embed: ${embeddingModel})`,
+  );
+
+  return new OpenAIProvider(apiKey, baseUrl, chatModel, embeddingModel);
+}

package/src/resources/context-resource.ts

@@ -0,0 +1,74 @@
+// =============================================================================
+// MCP Resource — Auto-injectable recent memory context
+// =============================================================================
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { StorageBackend } from "../types.js";
+
+/**
+ * Register MCP resources for automatic context injection.
+ * Agents can read these resources to get relevant context without explicit tool calls.
+ */
+export function registerMemoryResources(
+  server: McpServer,
+  store: StorageBackend,
+): void {
+  // Recent entities resource
+  server.registerResource(
+    "recent_entities",
+    "memory://entities/recent",
+    {
+      description: "Most recently updated entities in the memory graph",
+      mimeType: "application/json",
+    },
+    async () => {
+      const { nodes } = await store.getAllNodes(20, 0);
+      const sorted = nodes
+        .sort(
+          (a, b) =>
+            new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime(),
+        )
+        .slice(0, 20);
+
+      const content = sorted.map((n) => ({
+        name: n.name,
+        type: n.type,
+        description: n.description.substring(0, 200),
+        updatedAt: n.updatedAt,
+      }));
+
+      return {
+        contents: [
+          {
+            uri: "memory://entities/recent",
+            mimeType: "application/json",
+            text: JSON.stringify(content, null, 2),
+          },
+        ],
+      };
+    },
+  );
+
+  // Graph stats resource
+  server.registerResource(
+    "graph_stats",
+    "memory://stats",
+    {
+      description:
+        "Current memory graph statistics (node counts, edge counts, backend type)",
+      mimeType: "application/json",
+    },
+    async () => {
+      const stats = await store.getStats();
+      return {
+        contents: [
+          {
+            uri: "memory://stats",
+            mimeType: "application/json",
+            text: JSON.stringify(stats, null, 2),
+          },
+        ],
+      };
+    },
+  );
+}

package/src/retrieval/search.ts

@@ -0,0 +1,203 @@
+// =============================================================================
+// Hybrid Retrieval Engine — Semantic + Graph + Text Search
+// =============================================================================
+
+import type {
+  StorageBackend,
+  MemoryNode,
+  MemoryEdge,
+  ScoredNode,
+  SearchResult,
+  NodeType,
+} from "../types.js";
+import {
+  generateLocalEmbedding,
+  cosineSimilarity,
+} from "../encoding/embedder.js";
+import { DEFAULT_TOP_K, DEFAULT_TRAVERSAL_DEPTH } from "../constants.js";
+
+export interface SearchOptions {
+  query: string;
+  topK?: number;
+  type?: NodeType;
+  timeRange?: {
+    after?: string;
+    before?: string;
+  };
+  traversalDepth?: number;
+}
+
+/**
+ * Hybrid retrieval combining:
+ * 1. Text match on node names and descriptions
+ * 2. Cosine similarity on embeddings (semantic anchors)
+ * 3. Graph traversal from top anchors (2-hop neighborhood)
+ * 4. Ranking by: score = α·semantic + β·textMatch + γ·recency + δ·accessFreq
+ */
+export async function hybridSearch(
+  store: StorageBackend,
+  options: SearchOptions,
+): Promise<SearchResult> {
+  const {
+    query,
+    topK = DEFAULT_TOP_K,
+    type,
+    timeRange,
+    traversalDepth = DEFAULT_TRAVERSAL_DEPTH,
+  } = options;
+
+  const queryLower = query.toLowerCase();
+  const queryEmbedding = generateLocalEmbedding(query);
+
+  // Step 1: Get all candidate nodes
+  const { nodes: allNodes } = await store.getAllNodes(10000, 0);
+
+  // Step 2: Score each node
+  const scored: ScoredNode[] = [];
+
+  for (const node of allNodes) {
+    // Apply type filter
+    if (type && node.type !== type) continue;
+
+    // Apply time range filter
+    if (timeRange?.after && node.createdAt < timeRange.after) continue;
+    if (timeRange?.before && node.createdAt > timeRange.before) continue;
+
+    let totalScore = 0;
+    let matchType: ScoredNode["matchType"] = "text";
+
+    // Text match scoring
+    const nameMatch = node.name.toLowerCase().includes(queryLower) ? 0.6 : 0;
+    const descMatch = node.description.toLowerCase().includes(queryLower)
+      ? 0.4
+      : 0;
+
+    // Partial word matching
+    const queryWords = queryLower.split(/\s+/).filter((w) => w.length > 2);
+    let wordMatchScore = 0;
+    for (const word of queryWords) {
+      if (node.name.toLowerCase().includes(word)) wordMatchScore += 0.15;
+      if (node.description.toLowerCase().includes(word)) wordMatchScore += 0.1;
+    }
+
+    const textScore = Math.min(1, nameMatch + descMatch + wordMatchScore);
+
+    // Semantic similarity scoring
+    let semanticScore = 0;
+    if (node.embedding && node.embedding.length > 0) {
+      semanticScore = cosineSimilarity(queryEmbedding, node.embedding);
+      if (semanticScore > textScore) matchType = "semantic";
+    }
+
+    // Recency boost (decays over 30 days)
+    const ageMs = Date.now() - new Date(node.updatedAt).getTime();
+    const ageDays = ageMs / (1000 * 60 * 60 * 24);
+    const recencyBoost = Math.max(0, 1 - ageDays / 30) * 0.1;
+
+    // Access frequency boost (capped)
+    const accessBoost = Math.min(node.accessCount / 100, 0.1);
+
+    // Weighted combination
+    totalScore =
+      0.4 * semanticScore +
+      0.4 * textScore +
+      0.1 * recencyBoost +
+      0.1 * accessBoost;
+
+    if (totalScore > 0.05) {
+      scored.push({ node, score: totalScore, matchType });
+    }
+  }
+
+  // Step 3: Sort by score, take top K
+  scored.sort((a, b) => b.score - a.score);
+  const topResults = scored.slice(0, topK);
+
+  // Step 4: Graph traversal from top anchors to find related context
+  const relatedEdgesMap = new Map<string, MemoryEdge>();
+  const graphNodeIds = new Set(topResults.map((r) => r.node.id));
+
+  // Traverse from top 3 anchors
+  const anchors = topResults.slice(0, 3);
+  for (const anchor of anchors) {
+    const neighborhood = await store.getNeighborhood(
+      anchor.node.id,
+      traversalDepth,
+    );
+
+    for (const edge of neighborhood.edges) {
+      relatedEdgesMap.set(edge.id, edge);
+    }
+
+    // Add graph-discovered nodes that aren't already in results
+    for (const neighbor of neighborhood.nodes) {
+      if (!graphNodeIds.has(neighbor.id)) {
+        graphNodeIds.add(neighbor.id);
+        topResults.push({
+          node: neighbor,
+          score: anchor.score * 0.5, // Discounted score for graph neighbors
+          matchType: "graph",
+        });
+      }
+    }
+  }
+
+  // Step 5: Update access counts for returned nodes
+  for (const result of topResults) {
+    await store.updateNode(result.node.id, {
+      accessCount: result.node.accessCount + 1,
+      lastAccessedAt: new Date().toISOString(),
+    });
+  }
+
+  // Re-sort after adding graph neighbors
+  topResults.sort((a, b) => b.score - a.score);
+
+  return {
+    nodes: topResults.slice(0, topK),
+    relatedEdges: Array.from(relatedEdgesMap.values()),
+    totalNodes: scored.length,
+  };
+}
+
+/**
+ * Get context for a specific topic, formatted for prompt injection.
+ */
+export async function getContextForTopic(
+  store: StorageBackend,
+  topic: string,
+  maxTokens: number = 2000,
+): Promise<string> {
+  const results = await hybridSearch(store, {
+    query: topic,
+    topK: 10,
+    traversalDepth: 1,
+  });
+
+  const lines: string[] = [];
+  let estimatedTokens = 0;
+
+  lines.push(`## Relevant Memory Context: "${topic}"\n`);
+
+  for (const { node, score } of results.nodes) {
+    if (estimatedTokens > maxTokens) break;
+
+    const entry = `### ${node.name} (${node.type})\n${node.description}\n`;
+    estimatedTokens += entry.length / 4; // rough token estimate
+    lines.push(entry);
+  }
+
+  if (results.relatedEdges.length > 0) {
+    lines.push(`### Relationships\n`);
+    for (const edge of results.relatedEdges.slice(0, 10)) {
+      const fromNode = results.nodes.find((n) => n.node.id === edge.source);
+      const toNode = results.nodes.find((n) => n.node.id === edge.target);
+      const fromName = fromNode?.node.name ?? edge.source;
+      const toName = toNode?.node.name ?? edge.target;
+      lines.push(`- ${fromName} **${edge.relation}** ${toName}`);
+      if (edge.description) lines.push(`  _${edge.description}_`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/storage/factory.ts

@@ -0,0 +1,48 @@
+// =============================================================================
+// Storage Backend Factory
+// =============================================================================
+
+import type { StorageBackend } from "../types.js";
+import { JsonStore } from "./json-store.js";
+import { Neo4jStore } from "./neo4j-store.js";
+import { ENV_KEYS, DEFAULT_MEMORY_STORE_PATH } from "../constants.js";
+
+export type StorageType = "json" | "neo4j";
+
+/**
+ * Create a storage backend based on environment configuration.
+ *
+ * STORAGE_BACKEND=json  → Local JSON file (default, zero-config)
+ * STORAGE_BACKEND=neo4j → Neo4j graph database
+ */
+export function createStorageBackend(): StorageBackend {
+  const backendType = (
+    process.env[ENV_KEYS.STORAGE_BACKEND] ?? "json"
+  ).toLowerCase() as StorageType;
+
+  switch (backendType) {
+    case "neo4j": {
+      const uri = process.env[ENV_KEYS.NEO4J_URI];
+      const user = process.env[ENV_KEYS.NEO4J_USER];
+      const password = process.env[ENV_KEYS.NEO4J_PASSWORD];
+
+      if (!uri || !user || !password) {
+        console.error(
+          `[open-memory] ERROR: Neo4j requires NEO4J_URI, NEO4J_USER, and NEO4J_PASSWORD environment variables.`,
+        );
+        process.exit(1);
+      }
+
+      console.error(`[open-memory] Using Neo4j storage backend at ${uri}`);
+      return new Neo4jStore(uri, user, password);
+    }
+
+    case "json":
+    default: {
+      const filePath =
+        process.env[ENV_KEYS.MEMORY_STORE_PATH] ?? DEFAULT_MEMORY_STORE_PATH;
+      console.error(`[open-memory] Using JSON storage backend at ${filePath}`);
+      return new JsonStore(filePath);
+    }
+  }
+}