@coreidentitylabs/open-graph-memory-mcp 1.0.1

package/src/types.ts

@@ -0,0 +1,207 @@
+// =============================================================================
+// Open-Memory MCP Server — Core Type Definitions
+// =============================================================================
+
+/**
+ * Node types in the memory graph.
+ * - entity: People, tools, libraries, services
+ * - concept: Abstract ideas, patterns, paradigms
+ * - event: Something that happened (meeting, deployment, decision)
+ * - code_pattern: Recurring code structures, architectures
+ * - decision: Technical decisions and their rationale
+ * - conversation: Raw conversation history snapshot
+ */
+export type NodeType =
+  | "entity"
+  | "concept"
+  | "event"
+  | "code_pattern"
+  | "decision"
+  | "conversation";
+
+// -----------------------------------------------------------------------------
+// Memory Graph Nodes & Edges
+// -----------------------------------------------------------------------------
+
+export interface MemoryNode {
+  id: string;
+  name: string;
+  type: NodeType;
+  description: string;
+  embedding?: number[];
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+  /** Bi-temporal: when the fact became true in the real world */
+  validFrom?: string;
+  /** Bi-temporal: when the fact ceased to be true */
+  validUntil?: string;
+  /** Origin of this memory */
+  source?: string;
+  /** Number of times this node was retrieved */
+  accessCount: number;
+  /** Last time this node was accessed */
+  lastAccessedAt?: string;
+}
+
+export interface MemoryEdge {
+  id: string;
+  /** Source node ID */
+  source: string;
+  /** Target node ID */
+  target: string;
+  /** Relationship type, e.g. "uses", "depends_on", "decided_to" */
+  relation: string;
+  /** Natural language description of the relationship */
+  description: string;
+  /** Confidence/strength weight (0-1) */
+  weight: number;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+}
+
+// -----------------------------------------------------------------------------
+// Search & Retrieval Types
+// -----------------------------------------------------------------------------
+
+export interface ScoredNode {
+  node: MemoryNode;
+  score: number;
+  matchType: "semantic" | "text" | "graph";
+}
+
+export interface Subgraph {
+  nodes: MemoryNode[];
+  edges: MemoryEdge[];
+}
+
+export interface SearchResult {
+  nodes: ScoredNode[];
+  relatedEdges: MemoryEdge[];
+  totalNodes: number;
+}
+
+export interface NodeFilter {
+  type?: NodeType;
+  source?: string;
+  createdAfter?: string;
+  createdBefore?: string;
+  nameContains?: string;
+}
+
+// -----------------------------------------------------------------------------
+// Graph Statistics
+// -----------------------------------------------------------------------------
+
+export interface GraphStats {
+  totalNodes: number;
+  totalEdges: number;
+  nodesByType: Record<string, number>;
+  storageBackend: string;
+  lastConsolidated?: string;
+  memoryFilePath?: string;
+}
+
+// -----------------------------------------------------------------------------
+// Storage Backend Interface
+// -----------------------------------------------------------------------------
+
+export interface StorageBackend {
+  initialize(): Promise<void>;
+
+  // Node operations
+  addNode(node: MemoryNode): Promise<void>;
+  updateNode(
+    id: string,
+    updates: Partial<MemoryNode>,
+  ): Promise<MemoryNode | null>;
+  deleteNode(id: string): Promise<boolean>;
+  getNode(id: string): Promise<MemoryNode | null>;
+  getNodeByName(name: string): Promise<MemoryNode | null>;
+  findNodes(filter: NodeFilter): Promise<MemoryNode[]>;
+  getAllNodes(
+    limit: number,
+    offset: number,
+  ): Promise<{ nodes: MemoryNode[]; total: number }>;
+  findNodesByEmbedding(
+    embedding: number[],
+    topK: number,
+  ): Promise<ScoredNode[]>;
+
+  // Edge operations
+  addEdge(edge: MemoryEdge): Promise<void>;
+  updateEdge(
+    id: string,
+    updates: Partial<MemoryEdge>,
+  ): Promise<MemoryEdge | null>;
+  deleteEdge(id: string): Promise<boolean>;
+  getEdge(id: string): Promise<MemoryEdge | null>;
+  getEdgesForNode(
+    nodeId: string,
+    direction?: "in" | "out" | "both",
+  ): Promise<MemoryEdge[]>;
+  getEdgesBetween(sourceId: string, targetId: string): Promise<MemoryEdge[]>;
+
+  // Graph traversal
+  getNeighborhood(nodeId: string, depth: number): Promise<Subgraph>;
+
+  // Stats & lifecycle
+  getStats(): Promise<GraphStats>;
+  close(): Promise<void>;
+}
+
+// -----------------------------------------------------------------------------
+// Encoding / Extraction Types
+// -----------------------------------------------------------------------------
+
+export interface ExtractedEntity {
+  name: string;
+  type: NodeType;
+  description: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ExtractedRelation {
+  source: string;
+  target: string;
+  relation: string;
+  description?: string;
+  weight?: number;
+}
+
+export interface ExtractionResult {
+  entities: ExtractedEntity[];
+  relations: ExtractedRelation[];
+}
+
+// -----------------------------------------------------------------------------
+// LLM Provider Interface (Optional)
+// -----------------------------------------------------------------------------
+
+export interface LLMProvider {
+  extractEntitiesAndRelations(
+    text: string,
+    existingEntities: string[],
+  ): Promise<ExtractionResult>;
+  generateEmbedding(text: string): Promise<number[]>;
+  generateEmbeddingBatch(texts: string[]): Promise<number[][]>;
+}
+
+// -----------------------------------------------------------------------------
+// Consolidation Types
+// -----------------------------------------------------------------------------
+
+export interface ConsolidationResult {
+  mergedNodes: number;
+  resolvedConflicts: number;
+  inferredEdges: number;
+  prunedNodes: number;
+  duration: number;
+}
+
+export type ConsolidationStrategy =
+  | "full"
+  | "merge_only"
+  | "prune_only"
+  | "infer_only";

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}