Graph Weaken

Instructions

Implementation Reference

• src/mcp-server/index.ts:368-395 (registration)

  Registration of the graph_weaken tool on the MCP server with its input schema (from_name, to_name, relation, amount, reason) and handler.

  server.registerTool("graph_weaken", {
    title: "Graph Weaken",
    description:
      "Decrease an edge's weight when the user corrects a recalled fact. Call this when the user says 'no', 'that's wrong', or corrects something from the graph. Persists immediately; weight clamps at 0.0. Returns an error if the edge doesn't exist — use graph_delete to remove an entity outright. To replace a fact rather than weaken it, prefer graph_relate with the new fact and SUPERSEDES.",
    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"),
      amount: z.number().optional().default(0.3).describe("Weaken amount (default: 0.3)"),
      reason: z.string().optional().describe("Why weakening"),
    },
    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.weaken(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 },
        pruned: result.new_weight <= 0.05,
      });
    } catch (err) {
      return toolError(`graph_weaken failed: ${err instanceof Error ? err.message : String(err)}`);
    }
  });

• src/mcp-server/index.ts:380-395 (handler)

  Handler function for graph_weaken: resolves entity IDs by name, calls client.weaken() to reduce edge weight, and returns previous/new weight plus whether the edge was pruned.

  }, 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.weaken(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 },
        pruned: result.new_weight <= 0.05,
      });
    } catch (err) {
      return toolError(`graph_weaken failed: ${err instanceof Error ? err.message : String(err)}`);
    }
  });

• src/shared/neo4j-client.ts:534-559 (helper)

  Neo4jClient.weaken() method that executes the Cypher query to decrement edge weight, clamps at 0.0, and returns old/new weight values.

  async weaken(
    tenantId: string,
    fromId: string,
    toId: string,
    type: RelationshipType,
    amount?: number,
  ): Promise<{ previous_weight: number; new_weight: number }> {
    const config = getConfig();
    const weakenAmount = amount ?? config.weights.weaken_on_correct;
    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 < 0.0 THEN 0.0 ELSE r.weight - $amount END,
          r.last_confirmed = datetime()
      RETURN old_weight, r.weight AS new_weight
      `,
      { tenantId, fromId, toId, amount: weakenAmount },
    );
    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"]),
    };
  }

• src/shared/config.ts:60-62 (helper)

  Default weaken amount (0.3) defined in the config schema under weights.weaken_on_correct.

    weaken_on_correct: 0.3,
    project_context_boost: 0.1,
  },