lithtrix_memory_search

Instructions

Implementation Reference

• tools/memory.js:168-218 (registration)

  Registration of the lithtrix_memory_search tool via server.tool() in the registerMemoryTools function.

  server.tool(
    "lithtrix_memory_search",
    "Semantic search over your memories (GET /v1/memory/search). " +
      "Requires LITHTRIX_API_KEY and server-side vector + embedding configuration. " +
      "Returns ranked results with similarity scores.",
    {
      q: z
        .string()
        .min(1)
        .max(500)
        .describe("Natural-language search query"),
      limit: z
        .number()
        .int()
        .min(1)
        .max(20)
        .optional()
        .describe("Max results (1–20, default 5)"),
      importance: importanceSchema,
      threshold: z
        .number()
        .min(0)
        .max(1)
        .optional()
        .describe("Minimum similarity 0–1 (default 0.7 on API)"),
    },
    async ({ q, limit, importance, threshold }) => {
      const apiKey = process.env.LITHTRIX_API_KEY;
      if (!apiKey) return missingApiKeyResponse();
  
      const url = new URL("/v1/memory/search", LITHTRIX_API_URL);
      url.searchParams.set("q", q);
      if (limit !== undefined) url.searchParams.set("limit", String(limit));
      if (importance !== undefined) url.searchParams.set("importance", importance);
      if (threshold !== undefined)
        url.searchParams.set("threshold", String(threshold));
  
      let response;
      try {
        response = await fetch(url.toString(), {
          headers: {
            Authorization: `Bearer ${apiKey}`,
            "Content-Type": "application/json",
          },
        });
      } catch (err) {
        return networkErrorResponse(err);
      }
      return apiJsonResponse(response);
    }
  );

• tools/memory.js:194-217 (handler)

  Handler function that executes the semantic memory search: builds a GET /v1/memory/search URL with query params (q, limit, importance, threshold), calls the Lithtrix API, and returns the response.

  async ({ q, limit, importance, threshold }) => {
    const apiKey = process.env.LITHTRIX_API_KEY;
    if (!apiKey) return missingApiKeyResponse();
  
    const url = new URL("/v1/memory/search", LITHTRIX_API_URL);
    url.searchParams.set("q", q);
    if (limit !== undefined) url.searchParams.set("limit", String(limit));
    if (importance !== undefined) url.searchParams.set("importance", importance);
    if (threshold !== undefined)
      url.searchParams.set("threshold", String(threshold));
  
    let response;
    try {
      response = await fetch(url.toString(), {
        headers: {
          Authorization: `Bearer ${apiKey}`,
          "Content-Type": "application/json",
        },
      });
    } catch (err) {
      return networkErrorResponse(err);
    }
    return apiJsonResponse(response);
  }

• tools/memory.js:173-193 (schema)

  Input schema for the tool using Zod: 'q' (required string 1-500 chars), 'limit' (optional int 1-20), 'importance' (optional enum from importanceSchema), and 'threshold' (optional number 0-1).

  {
    q: z
      .string()
      .min(1)
      .max(500)
      .describe("Natural-language search query"),
    limit: z
      .number()
      .int()
      .min(1)
      .max(20)
      .optional()
      .describe("Max results (1–20, default 5)"),
    importance: importanceSchema,
    threshold: z
      .number()
      .min(0)
      .max(1)
      .optional()
      .describe("Minimum similarity 0–1 (default 0.7 on API)"),
  },

• tools/memory.js:15-19 (helper)

  Shared Zod schema for the 'importance' parameter, reused by lithtrix_memory_search and other memory tools.

    .describe(
      "Memory key (1–128 chars: letters, digits, hyphen, underscore, dot, colon)"
    );
  
  const importanceSchema = z

• tools/memory.js:24-81 (helper)

  Helper function that returns an error response when the API key is missing, used by the handler.

  function missingApiKeyResponse() {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            error:
              "LITHTRIX_API_KEY environment variable is not set. " +
              "Register at https://lithtrix.ai and use lithtrix_register, then set the key.",
          }),
        },
      ],
      isError: true,
    };
  }
  
  function networkErrorResponse(err) {
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            error: `Network error contacting Lithtrix API: ${err.message}`,
          }),
        },
      ],
      isError: true,
    };
  }
  
  async function apiJsonResponse(response) {
    let body;
    try {
      body = await response.json();
    } catch {
      body = { message: `Invalid JSON (HTTP ${response.status})` };
    }
  
    if (!response.ok) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              error: body.message ?? `Lithtrix API error (HTTP ${response.status})`,
              error_code: body.error_code ?? "UNKNOWN",
              status: body.status,
            }),
          },
        ],
        isError: true,
      };
    }
  
    return {
      content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
    };
  }