MCP DuckDB Knowledge Graph Memory Server

Instructions

Implementation Reference

• src/manager.ts:335-407 (handler)

  Main handler function that executes the tool logic: adds new observations to existing entities, filters duplicates, uses database transactions, and updates search index.

  async addObservations(
    observations: Array<Observation>
  ): Promise<Observation[]> {
    const addedObservations: Observation[] = [];
  
    using conn = await this.getConn();
  
    try {
      // Begin transaction
      await conn.execute("BEGIN TRANSACTION");
  
      // Process each observation
      for (const observation of observations) {
        // Check if entity exists
        const entityReader = await conn.executeAndReadAll(
          "SELECT name FROM entities WHERE name = ?",
          [observation.entityName as string]
        );
        const entityRows = entityReader.getRows();
        // Confirm existence by row count
  
        // If entity exists
        if (entityRows.length > 0) {
          // Get existing observations
          const existingObservationsReader = await conn.executeAndReadAll(
            "SELECT content FROM observations WHERE entityName = ?",
            [observation.entityName as string]
          );
          const existingObservationsData = existingObservationsReader.getRows();
          const contentColumnIndex = 0; // content column is the first column
          const existingObservations = new Set(
            existingObservationsData.map(
              (row: any) => row[contentColumnIndex] as string
            )
          );
  
          // Filter new observations
          const newContents = observation.contents.filter(
            (content) => !existingObservations.has(content)
          );
  
          // Insert new observations
          if (newContents.length > 0) {
            for (const content of newContents) {
              await conn.execute(
                "INSERT INTO observations (entityName, content) VALUES (?, ?)",
                [observation.entityName, content]
              );
            }
  
            addedObservations.push({
              entityName: observation.entityName,
              contents: newContents,
            });
          }
        }
      }
  
      // Commit transaction
      await conn.execute("COMMIT");
  
      // Update Fuse.js index
      const allEntities = await this.getAllEntities();
      this.fuse.setCollection(allEntities);
  
      return addedObservations;
    } catch (error: unknown) {
      // Rollback in case of error
      await conn.execute("ROLLBACK");
      this.logger.error("Error adding observations", extractError(error));
      throw error;
    }
  }

• src/server.ts:66-86 (registration)

  Registers the 'add_observations' tool with MCP server, defining schema and delegating to KnowledgeGraphManager.

  server.tool(
    "add_observations",
    "Add new observations to existing entities in the knowledge graph",
    {
      observations: z
        .array(ObservationObject)
        .describe("An array of observations to add"),
    },
    async ({ observations }) => ({
      content: [
        {
          type: "text",
          text: JSON.stringify(
            await knowledgeGraphManager.addObservations(observations),
            null,
            2
          ),
        },
      ],
    })
  );

• src/types.ts:34-42 (schema)

  Zod schema for Observation used in the tool input (array of this). Defines input validation for entityName and contents.

  export const ObservationObject = z.object({
    entityName: z
      .string()
      .describe("The name of the entity to add the observations to"),
    contents: z
      .array(z.string())
      .describe("An array of observation contents to add"),
  });
  export type Observation = z.infer<typeof ObservationObject>;

• src/types.ts:58-58 (schema)

  TypeScript interface definition for the addObservations method in KnowledgeGraphManagerInterface.

  addObservations(observations: Array<Observation>): Promise<Observation[]>;