memento-mcp

Instructions

Implementation Reference

• src/server/handlers/listToolsHandler.ts:446-460 (registration)

  Tool registration and schema definition for get_graph_at_time in the list of temporal tools

  {
    name: 'get_graph_at_time',
    description:
      'Get your Memento MCP knowledge graph memory as it existed at a specific point in time',
    inputSchema: {
      type: 'object',
      properties: {
        timestamp: {
          type: 'number',
          description: 'The timestamp (in milliseconds since epoch) to query the graph at',
        },
      },
      required: ['timestamp'],
    },
  },

• src/server/handlers/callToolHandler.ts:129-138 (handler)

  MCP tool handler switch case that executes get_graph_at_time by calling KnowledgeGraphManager.getGraphAtTime

  case 'get_graph_at_time':
    try {
      const graph = await knowledgeGraphManager.getGraphAtTime(args.timestamp);
      return { content: [{ type: 'text', text: JSON.stringify(graph, null, 2) }] };
    } catch (error: Error | unknown) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      return {
        content: [{ type: 'text', text: `Error retrieving graph at time: ${errorMessage}` }],
      };
    }

• src/KnowledgeGraphManager.ts:1204-1210 (helper)

  KnowledgeGraphManager method that delegates getGraphAtTime to the storage provider

  async getGraphAtTime(timestamp: number): Promise<KnowledgeGraph> {
    if (!this.storageProvider || typeof this.storageProvider.getGraphAtTime !== 'function') {
      throw new Error('Storage provider does not support temporal graph operations');
    }
  
    return this.storageProvider.getGraphAtTime(timestamp);
  }

• src/storage/neo4j/Neo4jStorageProvider.ts:1541-1597 (handler)

  Core implementation of getGraphAtTime in Neo4jStorageProvider using temporal queries on validFrom/validTo fields

  async getGraphAtTime(timestamp: number): Promise<KnowledgeGraph> {
    try {
      const startTime = Date.now();
  
      // Query for entities valid at timestamp
      const entityQuery = `
        MATCH (e:Entity)
        WHERE e.validFrom <= $timestamp
        AND (e.validTo IS NULL OR e.validTo > $timestamp)
        RETURN e
      `;
  
      // Execute entity query
      const entityResult = await this.connectionManager.executeQuery(entityQuery, { timestamp });
  
      // Convert nodes to entities
      const entities = entityResult.records.map((record) => {
        const node = record.get('e').properties;
        return this.nodeToEntity(node);
      });
  
      // Query for relations valid at timestamp
      const relationQuery = `
        MATCH (from:Entity)-[r:RELATES_TO]->(to:Entity)
        WHERE r.validFrom <= $timestamp
        AND (r.validTo IS NULL OR r.validTo > $timestamp)
        RETURN r, from.name AS fromName, to.name AS toName
      `;
  
      // Execute relation query
      const relationResult = await this.connectionManager.executeQuery(relationQuery, {
        timestamp,
      });
  
      // Convert relationships to relations
      const relations = relationResult.records.map((record) => {
        const rel = record.get('r').properties;
        const fromName = record.get('fromName');
        const toName = record.get('toName');
  
        return this.relationshipToRelation(rel, fromName, toName);
      });
  
      const timeTaken = Date.now() - startTime;
  
      // Return the graph state at the timestamp
      return {
        entities,
        relations,
        total: entities.length,
        timeTaken,
      };
    } catch (error) {
      logger.error(`Error retrieving graph state at timestamp ${timestamp} from Neo4j`, error);
      throw error;
    }
  }