Central Intelligence

Instructions

Implementation Reference

• packages/mcp-server/src/index.ts:211-283 (handler)

  MCP server handler for the 'context' tool. Receives current_context, agent_id, user_id, max_memories parameters, calls the API endpoint /memories/context, formats the results and returns relevant memories with relevance scores.

  // Tool 4: context
  server.tool(
    "context",
    `Load relevant memories for the current task, designed for session bootstrapping. This is a read-only operation identical to recall internally, but optimized for broad context loading rather than specific questions. Call context at the start of every conversation, passing a description of what you are working on, to retrieve past decisions, preferences, and project knowledge. Also call when switching topics mid-session. Use context (not recall) for "what do I need to know about X?" and recall for "what specifically was decided about Y?". Returns up to max_memories results ranked by relevance. Costs 1 operation. Returns empty list (not error) if no relevant memories exist.`,
    {
      current_context: z
        .string()
        .describe(
          "Description of what you are currently working on. Be specific: 'refactoring the authentication middleware in the Express API' retrieves better context than 'working on auth'. This is the search query for memory retrieval.",
        ),
      agent_id: z
        .string()
        .default("default")
        .describe("Agent instance identifier. Must match the agent_id used when storing memories. Default: 'default'."),
      user_id: z
        .string()
        .optional()
        .describe("User identifier. When provided, also retrieves user-scoped memories shared by other agents."),
      max_memories: z
        .number()
        .int()
        .min(1)
        .max(20)
        .default(5)
        .describe("Maximum memories to return, 1-20. Default 5. Use 10-15 at session start for broad context loading, 3-5 for topic switches."),
    },
    async ({ current_context, agent_id, user_id, max_memories }) => {
      const result = await apiCall("/memories/context", "POST", {
        agent_id,
        user_id,
        current_context,
        max_memories,
      });
  
      const memories = (
        result as {
          memories: Array<{
            id: string;
            content: string;
            relevance_score: number;
            scope: string;
          }>;
        }
      ).memories;
  
      if (memories.length === 0) {
        return {
          content: [
            {
              type: "text" as const,
              text: "No relevant past context found. This appears to be a new topic.",
            },
          ],
        };
      }
  
      const formatted = memories
        .map(
          (m, i) =>
            `[${i + 1}] (relevance: ${(m.relevance_score * 100).toFixed(1)}%)\n${m.content}`,
        )
        .join("\n\n");
  
      return {
        content: [
          {
            type: "text" as const,
            text: `Loaded ${memories.length} relevant memories from past sessions:\n\n${formatted}`,
          },
        ],
      };
    },
  );

• packages/api/src/routes/memories.ts:114-139 (handler)

  API route handler for POST /memories/context. Validates input using Zod schema, calls memoriesService.recall() with broader scope (org > user > agent), and returns matching memories.

  app.post("/context", async (c) => {
    const body = await c.req.json();
    const parsed = contextSchema.safeParse(body);
    if (!parsed.success) {
      return c.json({ error: "Invalid request", details: parsed.error.issues }, 400);
    }
  
    const { agent_id, user_id, current_context, max_memories } = parsed.data;
    const apiKeyId = c.get("apiKeyId");
    const orgId = c.get("orgId");
    const rawApiKey = c.get("rawApiKey");
  
    // Recall with broader scope to get max context
    const memories = await memoriesService.recall({
      apiKeyId,
      rawApiKey,
      agentId: agent_id,
      userId: user_id,
      orgId,
      query: current_context,
      scope: orgId ? "org" : user_id ? "user" : "agent",
      limit: max_memories,
    });
  
    return c.json({ memories });
  });

• packages/mcp-server/src/index.ts:214-236 (schema)

  Zod input schema definition for the 'context' tool in the MCP server. Defines current_context (required string), agent_id (default 'default'), user_id (optional), and max_memories (default 5, max 20).

  `Load relevant memories for the current task, designed for session bootstrapping. This is a read-only operation identical to recall internally, but optimized for broad context loading rather than specific questions. Call context at the start of every conversation, passing a description of what you are working on, to retrieve past decisions, preferences, and project knowledge. Also call when switching topics mid-session. Use context (not recall) for "what do I need to know about X?" and recall for "what specifically was decided about Y?". Returns up to max_memories results ranked by relevance. Costs 1 operation. Returns empty list (not error) if no relevant memories exist.`,
  {
    current_context: z
      .string()
      .describe(
        "Description of what you are currently working on. Be specific: 'refactoring the authentication middleware in the Express API' retrieves better context than 'working on auth'. This is the search query for memory retrieval.",
      ),
    agent_id: z
      .string()
      .default("default")
      .describe("Agent instance identifier. Must match the agent_id used when storing memories. Default: 'default'."),
    user_id: z
      .string()
      .optional()
      .describe("User identifier. When provided, also retrieves user-scoped memories shared by other agents."),
    max_memories: z
      .number()
      .int()
      .min(1)
      .max(20)
      .default(5)
      .describe("Maximum memories to return, 1-20. Default 5. Use 10-15 at session start for broad context loading, 3-5 for topic switches."),
  },

• packages/api/src/routes/memories.ts:106-112 (schema)

  Zod validation schema for the POST /memories/context API endpoint. Validates agent_id, user_id, current_context, and max_memories with constraints.

  // POST /memories/context
  const contextSchema = z.object({
    agent_id: z.string().min(1).max(200),
    user_id: z.string().max(200).optional(),
    current_context: z.string().min(1).max(5000),
    max_memories: z.number().int().min(1).max(20).default(5),
  });

• packages/api/src/index.ts:211-220 (registration)

  MCP manifest registration for the 'context' tool. Defines the tool name, description, endpoint URLs, and input schema for discovery.

  {
    name: "context",
    description: "Auto-load relevant memories for the current task. Describe what you're working on, get back everything relevant.",
    endpoint: "POST /memories/context",
    x402_endpoint: "POST /x402/context",
    input: {
      agent_id: { type: "string", required: true },
      query: { type: "string", required: true, description: "Current task description" },
    },
  },