Graph Boost

Instructions

Implementation Reference

• src/mcp-server/index.ts:353-367 (handler)

  The graph_boost tool handler: resolves from/to entity names to IDs (or slugifies them), then calls client.boost() to increase the edge weight, returning previous and new weights.

  }, async (args) => {
    try {
      const tenantId = currentTenant();
      const fromId = (await client.findEntityIdByName(tenantId, args.from_name)) ?? slugify(args.from_name);
      const toId = (await client.findEntityIdByName(tenantId, args.to_name)) ?? slugify(args.to_name);
      const result = await client.boost(tenantId, fromId, toId, args.relation as RelationshipType, args.amount);
      return toolResult({
        previous_weight: result.previous_weight,
        new_weight: result.new_weight,
        edge: { from: fromId, to: toId, type: args.relation },
      });
    } catch (err) {
      return toolError(`graph_boost failed: ${err instanceof Error ? err.message : String(err)}`);
    }
  });

• src/mcp-server/index.ts:345-351 (schema)

  Input schema for graph_boost: requires from_name, to_name, relation; optional amount (default 0.15) and reason.

  inputSchema: {
    from_name: z.string().describe("Source entity name or ID"),
    to_name: z.string().describe("Target entity name or ID"),
    relation: z.string().describe("Relationship type (e.g. WORKS_ON, PREFERS)"),
    amount: z.number().optional().default(0.15).describe("Boost amount (default: 0.15)"),
    reason: z.string().optional().describe("Why boosting"),
  },

• src/mcp-server/index.ts:341-367 (registration)

  Registers the 'graph_boost' tool with the MCP server, setting title, description, input schema, and idempotent annotation.

  server.registerTool("graph_boost", {
    title: "Graph Boost",
    description:
      "Increase an edge's weight when the user confirms recalled information. Call this when the user says 'yes', 'exactly', or confirms something you retrieved from the graph. Persists immediately; weight clamps at 1.0 so repeated boosts saturate rather than overflow. Returns the previous and new weight.",
    inputSchema: {
      from_name: z.string().describe("Source entity name or ID"),
      to_name: z.string().describe("Target entity name or ID"),
      relation: z.string().describe("Relationship type (e.g. WORKS_ON, PREFERS)"),
      amount: z.number().optional().default(0.15).describe("Boost amount (default: 0.15)"),
      reason: z.string().optional().describe("Why boosting"),
    },
    annotations: { idempotentHint: true },
  }, async (args) => {
    try {
      const tenantId = currentTenant();
      const fromId = (await client.findEntityIdByName(tenantId, args.from_name)) ?? slugify(args.from_name);
      const toId = (await client.findEntityIdByName(tenantId, args.to_name)) ?? slugify(args.to_name);
      const result = await client.boost(tenantId, fromId, toId, args.relation as RelationshipType, args.amount);
      return toolResult({
        previous_weight: result.previous_weight,
        new_weight: result.new_weight,
        edge: { from: fromId, to: toId, type: args.relation },
      });
    } catch (err) {
      return toolError(`graph_boost failed: ${err instanceof Error ? err.message : String(err)}`);
    }
  });

• src/shared/neo4j-client.ts:542-567 (helper)

  The Neo4jClient.boost() helper method: executes a Cypher query that increases the edge weight (clamped at 1.0), updates last_confirmed, and returns previous and new weight.

  async boost(
    tenantId: string,
    fromId: string,
    toId: string,
    type: RelationshipType,
    amount?: number,
  ): Promise<{ previous_weight: number; new_weight: number }> {
    const config = getConfig();
    const boostAmount = amount ?? config.weights.boost_on_confirm;
    const rows = await this.run(
      `
      MATCH (a:Entity {tenant_id: $tenantId, id: $fromId})-[r:\`${type}\`]->(b:Entity {tenant_id: $tenantId, id: $toId})
      WITH r, r.weight AS old_weight
      SET r.weight = CASE WHEN r.weight + $amount > 1.0 THEN 1.0 ELSE r.weight + $amount END,
          r.last_confirmed = datetime()
      RETURN old_weight, r.weight AS new_weight
      `,
      { tenantId, fromId, toId, amount: boostAmount },
    );
    const row = rows[0];
    if (!row) throw new Error(`Edge not found: ${fromId} -[${type}]-> ${toId} in tenant ${tenantId}`);
    return {
      previous_weight: Number(row["old_weight"]),
      new_weight: Number(row["new_weight"]),
    };
  }