Graph Boost

Instructions

Implementation Reference

• src/mcp-server/index.ts:338-364 (registration)

  Registers the graph_boost MCP tool in the server. Defines input schema (from_name, to_name, relation, amount, reason) and calls client.boost() with resolved entity IDs.

  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/mcp-server/index.ts:350-364 (handler)

  Handler for graph_boost. Resolves entity names to IDs (via findEntityIdByName or slugify fallback), then delegates to client.boost() to increase edge weight.

  }, 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:342-349 (schema)

  Input schema for graph_boost tool: from_name (string), to_name (string), relation (string), amount (number, default 0.15), reason (optional string).

  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 },

• src/shared/neo4j-client.ts:507-532 (helper)

  Core boost logic in Neo4jClient. Executes a Cypher MATCH on the edge, increments weight clamped at 1.0, updates last_confirmed, and returns previous/new weights. Falls back to config.weights.boost_on_confirm (0.15) if no amount provided.

  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"]),
    };
  }