Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

23.0 KB
Raw Blame
#!/usr/bin/env node

import { InMemoryKV } from "./in-memory-kv.js";
import { createStdioTransport } from "./transport.js";
import { getAllTools } from "./tools-registry.js";
import { getAgentId, getStandalonePersistPath, isAgentScopeIsolated } from "../config.js";
import { isSearchLayer, type SearchLayer } from "../state/search-layer.js";
import { memoryToObservation } from "../state/memory-utils.js";
import { buildRecallResponse } from "../functions/recall-response.js";
import { parseSearchExpansionIds, type SearchExpansionId } from "./search-arguments.js";
import { parseSessionArguments } from "./session-arguments.js";
import { pageAfterCursor, sortByKeyDesc } from "../state/list-query.js";
import type { Memory, SearchResult, Session } from "../types.js";
import { VERSION } from "../version.js";
import { generateId } from "../state/schema.js";
import { queryAudit } from "../functions/audit.js";
import {
  resolveHandle,
  invalidateHandle,
  isProxyRequired,
  ProxyCallError,
  type Handle,
  type ProxyHandle,
} from "./rest-proxy.js";

const IMPLEMENTED_TOOLS = new Set([
  "memory_save",
  "memory_recall",
  "memory_smart_search",
  "memory_sessions",
  "memory_export",
  "memory_audit",
  "memory_governance_delete",
]);

const SUPPORTED_PROTOCOL_VERSIONS = [
  "2025-11-25",
  "2025-06-18",
  "2025-03-26",
  "2024-11-05",
];

const SERVER_INFO = {
  name: "agentmemory",
  version: VERSION,
};

const kv = new InMemoryKV(getStandalonePersistPath());
let modeAnnounced = false;

function displayAgentmemoryUrl(): string {
  // Match the literal-placeholder guard in rest-proxy.ts so log lines
  // don't show `${AGENTMEMORY_URL}` when an MCP host passed the
  // placeholder through unexpanded.
  const raw = process.env["AGENTMEMORY_URL"];
  if (!raw || (raw.startsWith("${") && raw.endsWith("}"))) {
    return "http://localhost:3111";
  }
  return raw;
}

function announceMode(handle: Handle): void {
  if (modeAnnounced) return;
  modeAnnounced = true;
  if (handle.mode === "proxy") {
    process.stderr.write(
      `[@agentmemory/mcp] proxying to agentmemory server at ${handle.baseUrl}\n`,
    );
  } else {
    const fullToolCount = getAllTools().length;
    process.stderr.write(
      `[@agentmemory/mcp] no server reachable at ${displayAgentmemoryUrl()}; running reduced LOCAL FALLBACK with ${IMPLEMENTED_TOOLS.size} of ${fullToolCount} tools. Start 'npx @agentmemory/agentmemory' (and point AGENTMEMORY_URL at it) to unlock all ${fullToolCount} tools.\n`,
    );
  }
}

function normalizeList(value: unknown): string[] {
  if (!value) return [];
  if (Array.isArray(value)) {
    return value
      .map((v) => (typeof v === "string" ? v.trim() : ""))
      .filter((v) => v.length > 0);
  }
  if (typeof value === "string") {
    return value
      .split(",")
      .map((s) => s.trim())
      .filter((s) => s.length > 0);
  }
  return [];
}

const DEFAULT_LIMIT = 10;
const MAX_LIMIT = 100;
function parseLimit(raw: unknown, fallback = DEFAULT_LIMIT): number {
  if (typeof raw !== "number" && typeof raw !== "string") return fallback;
  const n = Number(raw);
  if (!Number.isFinite(n) || n <= 0) return fallback;
  return Math.min(Math.floor(n), MAX_LIMIT);
}

function textResponse(payload: unknown, pretty = false): {
  content: Array<{ type: string; text: string }>;
} {
  return {
    content: [
      { type: "text", text: JSON.stringify(payload, null, pretty ? 2 : 0) },
    ],
  };
}

function isAuthenticationError(error: unknown): boolean {
  return error instanceof ProxyCallError && (error.status === 401 || error.status === 403);
}

interface Validated {
  tool: string;
  content?: string;
  type?: string;
  concepts?: string[];
  files?: string[];
  project?: string;
  agentId?: string;
  query?: string;
  limit?: number;
  format?: "full" | "compact" | "narrative";
  tokenBudget?: number;
  targetLayer?: SearchLayer;
  cwd?: string;
  expandIds?: SearchExpansionId[];
  sessionId?: string;
  source?: string;
  includeLessons?: boolean;
  memoryIds?: string[];
  reason?: string;
  exportQuery?: string;
  sessionQuery?: Record<string, string>;
}

function validate(toolName: string, args: Record<string, unknown>): Validated {
  if (!IMPLEMENTED_TOOLS.has(toolName)) {
    throw new Error(`Unknown tool: ${toolName}`);
  }
  const v: Validated = { tool: toolName };
  switch (toolName) {
    case "memory_save": {
      const content = args["content"];
      if (typeof content !== "string" || !content.trim()) {
        throw new Error("content is required");
      }
      v.content = content;
      v.type = (args["type"] as string) || "fact";
      v.concepts = normalizeList(args["concepts"]);
      v.files = normalizeList(args["files"]);
      // The tool schema exposes project (and now agentId); dropping them
      // here silently broke project/agent scoping through the stdio
      // package specifically.
      if (typeof args["project"] === "string" && args["project"].trim()) {
        v.project = args["project"].trim();
      }
      if (typeof args["agentId"] === "string" && args["agentId"].trim()) {
        v.agentId = args["agentId"].trim();
      }
      return v;
    }
    case "memory_recall":
    case "memory_smart_search": {
      if (args.targetLayer !== undefined && !isSearchLayer(args.targetLayer)) {
        throw new Error("targetLayer must be one of: all, memory, observation");
      }
      v.targetLayer = args.targetLayer ?? "all";
      for (const field of ["project", "cwd", "agentId", "sessionId", "source"] as const) {
        if (args[field] !== undefined && typeof args[field] !== "string") {
          throw new Error(`${field} must be a string`);
        }
        if (typeof args[field] === "string" && args[field].trim()) v[field] = args[field].trim();
      }
      if (toolName === "memory_smart_search") {
        v.expandIds = parseSearchExpansionIds(args.expandIds);
        if (typeof args.includeLessons === "boolean") v.includeLessons = args.includeLessons;
      }
      const query = args["query"];
      if (typeof query !== "string" || !query.trim()) {
        if (!v.expandIds?.length) throw new Error("query is required unless expandIds is provided");
      } else {
        v.query = query.trim();
      }
      v.limit = parseLimit(args["limit"]);
      if (toolName === "memory_recall") {
        const format = typeof args.format === "string" ? args.format.trim().toLowerCase() : args.format ?? "full";
        if (format !== "full" && format !== "compact" && format !== "narrative") {
          throw new Error("format must be one of: full, compact, narrative");
        }
        v.format = format;
        if (args.token_budget !== undefined) {
          const budget = typeof args.token_budget === "string" ? Number(args.token_budget) : args.token_budget;
          if (typeof budget !== "number" || !Number.isInteger(budget) || budget < 1) {
            throw new Error("token_budget must be a positive integer");
          }
          v.tokenBudget = budget;
        }
      }
      return v;
    }
    case "memory_sessions": {
      v.sessionQuery = parseSessionArguments(args);
      return v;
    }
    case "memory_governance_delete": {
      const ids = normalizeList(args["memoryIds"]);
      if (ids.length === 0) throw new Error("memoryIds is required");
      v.memoryIds = ids;
      v.reason = (args["reason"] as string) || "plugin skill request";
      return v;
    }
    case "memory_export": {
      const query = new URLSearchParams();
      for (const key of ["maxSessions", "offset", "collectionLimit", "collectionOffset"]) {
        const n = Number(args[key]);
        const min = key === "maxSessions" || key === "collectionLimit" ? 1 : 0;
        if (args[key] !== undefined && Number.isInteger(n) && n >= min) query.set(key, String(n));
      }
      if (typeof args["collections"] === "string") query.set("collections", args["collections"]);
      v.exportQuery = query.toString();
      return v;
    }
    case "memory_audit": {
      v.limit = parseLimit(args["limit"], 50);
      return v;
    }
    default:
      throw new Error(`Unknown tool: ${toolName}`);
  }
}

async function handleProxy(
  v: Validated,
  handle: ProxyHandle,
): Promise<{ content: Array<{ type: string; text: string }> }> {
  switch (v.tool) {
    case "memory_save": {
      const result = await handle.call("/agentmemory/remember", {
        method: "POST",
        body: JSON.stringify({
          content: v.content,
          type: v.type,
          concepts: v.concepts,
          files: v.files,
          ...(v.project !== undefined && { project: v.project }),
          ...(v.agentId !== undefined && { agentId: v.agentId }),
        }),
      });
      return textResponse(result);
    }
    case "memory_recall": {
      const body: Record<string, unknown> = {
        query: v.query,
        limit: v.limit,
        format: v.format ?? "full",
        targetLayer: v.targetLayer,
        project: v.project,
        cwd: v.cwd,
        agentId: v.agentId,
      };
      if (v.tokenBudget != null) body["token_budget"] = v.tokenBudget;
      const result = await handle.call("/agentmemory/search", {
        method: "POST",
        body: JSON.stringify(body),
      });
      return textResponse(result, true);
    }
    case "memory_smart_search": {
      const body: Record<string, unknown> = {
        query: v.query,
        limit: v.limit,
        targetLayer: v.targetLayer,
        project: v.project,
        agentId: v.agentId,
        expandIds: v.expandIds,
        sessionId: v.sessionId,
        source: v.source,
        includeLessons: v.includeLessons,
      };
      const result = await handle.call("/agentmemory/smart-search", {
        method: "POST",
        body: JSON.stringify(body),
      });
      return textResponse(result, true);
    }
    case "memory_sessions": {
      const result = await handle.call(
        `/agentmemory/sessions?${new URLSearchParams(v.sessionQuery)}`,
        { method: "GET" },
      );
      return textResponse(result, true);
    }
    case "memory_governance_delete": {
      const result = await handle.call("/agentmemory/governance/memories", {
        method: "DELETE",
        body: JSON.stringify({ memoryIds: v.memoryIds, reason: v.reason }),
      });
      return textResponse(result);
    }
    case "memory_export": {
      try {
        const result = await handle.call(
          `/agentmemory/export${v.exportQuery ? `?${v.exportQuery}` : ""}`,
          { method: "GET" },
        );
        return textResponse(result, true);
      } catch (err) {
        if (
          err instanceof ProxyCallError &&
          err.status === 413 &&
          err.body != null &&
          typeof err.body === "object" &&
          (err.body as { oversized?: boolean }).oversized === true
        ) {
          return textResponse(err.body, true);
        }
        throw err;
      }
    }
    case "memory_audit": {
      const result = await handle.call(
        `/agentmemory/audit?limit=${v.limit}`,
        { method: "GET" },
      );
      return textResponse(result, true);
    }
    default:
      throw new Error(`Unknown tool: ${v.tool}`);
  }
}

function localFallbackNotice(persisted: boolean) {
  const store = persisted
    ? "the local fallback file, which the server does not read"
    : "this process's in-memory fallback store, which is lost when the process exits";
  return {
    storage: "local",
    warning: `agentmemory server at ${displayAgentmemoryUrl()} did not confirm this call, so it ran against ${store}.`,
  };
}

async function handleLocal(
  v: Validated,
  kvInstance: InMemoryKV,
): Promise<{ content: Array<{ type: string; text: string }> }> {
  switch (v.tool) {
    case "memory_save": {
      const id = generateId("mem");
      const isoNow = new Date().toISOString();
      await kvInstance.set("mem:memories", id, {
        id,
        type: v.type,
        title: (v.content || "").slice(0, 80),
        content: v.content,
        concepts: v.concepts,
        files: v.files,
        createdAt: isoNow,
        updatedAt: isoNow,
        strength: 7,
        version: 1,
        isLatest: true,
        sessionIds: [],
        ...(v.project !== undefined && { project: v.project }),
        ...((v.agentId ?? getAgentId()) !== undefined && { agentId: v.agentId ?? getAgentId() }),
      });
      const persisted = kvInstance.persist();
      return textResponse({ saved: id, ...localFallbackNotice(persisted) });
    }

    case "memory_recall":
    case "memory_smart_search": {
      const isolated = isAgentScopeIsolated();
      const agentId = v.agentId === "*" ? undefined : v.agentId ?? (isolated ? getAgentId() : undefined);
      if (isolated && v.agentId !== "*" && !agentId) {
        throw new Error("AGENTMEMORY_AGENT_SCOPE=isolated requires an agentId; pass '*' to read across agents");
      }
      const query = (v.query || "").toLowerCase();
      const limit = v.limit ?? DEFAULT_LIMIT;
      const all = v.targetLayer === "observation" ? [] : await kvInstance.list<Memory>("mem:memories");
      const sessions = v.project || v.cwd ? await kvInstance.list<Session>("mem:sessions") : [];
      const sessionsById = new Map(sessions.map((session) => [session.id, session]));
      const scoped = all.filter((memory) => {
        if (memory.isLatest === false || (agentId && memory.agentId !== agentId)) return false;
        const linkedSessions = (memory.sessionIds ?? []).map((id) => sessionsById.get(id));
        if (v.project && (memory.project ? memory.project !== v.project : !linkedSessions.some((session) => session?.project === v.project))) return false;
        if (v.cwd && !linkedSessions.some((session) => session?.cwd === v.cwd)) return false;
        return true;
      });
      if (v.tool === "memory_smart_search" && v.expandIds?.length) {
        const ids = v.expandIds.map((entry) => typeof entry === "string" ? entry : entry.obsId);
        const byId = new Map(scoped.map((memory) => [memory.id, memory]));
        const eligible = ids.filter((id) => byId.has(id));
        const results = eligible.slice(0, 20).map((id) => {
          const observation = memoryToObservation(byId.get(id)!);
          return { obsId: id, sessionId: observation.sessionId, observation, layer: "memory" };
        });
        return textResponse({ mode: "expanded", results, truncated: eligible.length > 20 }, true);
      }
      const results = scoped.filter((memory) => {
        const text = [memory.title, memory.content, ...(memory.files ?? []), ...(memory.concepts ?? []), ...(memory.sessionIds ?? []), memory.id]
          .join(" ").toLowerCase();
        return query.split(/\s+/).every((word) => text.includes(word));
      }).slice(0, limit);
      if (v.tool === "memory_recall") {
        const matches: SearchResult[] = results.map((memory) => {
          const observation = memoryToObservation(memory);
          return { sessionId: observation.sessionId, observation, score: 1, layer: "memory" };
        });
        return textResponse(buildRecallResponse(matches, v.format ?? "full", v.tokenBudget), true);
      }
      return textResponse({ mode: "compact", results: results.map((memory) => ({
        ...memory, obsId: memory.id, sessionId: memory.sessionIds?.[0] ?? "memory", layer: "memory",
      })) }, true);
    }

    case "memory_sessions": {
      const query = v.sessionQuery!;
      const agentId = query.agentId === "*" ? undefined : query.agentId ?? (isAgentScopeIsolated() ? getAgentId() : undefined);
      const sessions = (await kvInstance.list<Session>("mem:sessions"))
        .filter((session) => session && typeof session.id === "string" && session.id.length > 0)
        .filter((session) => !query.project || session.project === query.project)
        .filter((session) => !agentId || session.agentId === agentId);
      const key = (session: Session) => session.startedAt || "";
      const { page, nextCursor } = pageAfterCursor(
        sortByKeyDesc(sessions, key, (session) => session.id), key,
        (session) => session.id, query.cursor, Number(query.limit),
      );
      const withSummary = await Promise.all(page.map(async (session) => {
        const summary = await kvInstance.get("mem:summaries", session.id);
        return summary ? { ...session, summary } : session;
      }));
      return textResponse({ sessions: withSummary, nextCursor }, true);
    }

    case "memory_governance_delete": {
      let deleted = 0;
      for (const id of v.memoryIds || []) {
        const existing = await kvInstance.get("mem:memories", id);
        if (existing) {
          await kvInstance.delete("mem:memories", id);
          deleted++;
        }
      }
      const persisted = kvInstance.persist();
      return textResponse({
        deleted,
        requested: (v.memoryIds || []).length,
        reason: v.reason,
        ...localFallbackNotice(persisted),
      });
    }

    case "memory_export": {
      const memories = await kvInstance.list("mem:memories");
      const sessions = await kvInstance.list("mem:sessions");
      return textResponse({ version: VERSION, memories, sessions }, true);
    }

    case "memory_audit": {
      const result = await queryAudit(kvInstance as never, {
        limit: v.limit ?? 50,
      });
      return textResponse(result, true);
    }

    default:
      throw new Error(`Unknown tool: ${v.tool}`);
  }
}

async function handleProxyGeneric(
  toolName: string,
  args: Record<string, unknown>,
  handle: ProxyHandle,
): Promise<{ content: Array<{ type: string; text: string }> }> {
  // Forward to the server's full MCP surface so non-Claude clients can
  // reach all 54 tools (lessons, sentinels, slots, signals, graph, …)
  // instead of being capped at the 7 IMPLEMENTED_TOOLS set baked into
  // this shim. The server validates arguments per tool.
  const result = (await handle.call("/agentmemory/mcp/call", {
    method: "POST",
    body: JSON.stringify({ name: toolName, arguments: args }),
  })) as { content?: Array<{ type: string; text: string }> } | null;
  if (result && Array.isArray(result.content)) {
    return { content: result.content };
  }
  return textResponse(result, true);
}

export async function handleToolCall(
  toolName: string,
  args: Record<string, unknown>,
  kvInstance: InMemoryKV = kv,
): Promise<{ content: Array<{ type: string; text: string }> }> {
  const handle = await resolveHandle();
  announceMode(handle);

  if (!IMPLEMENTED_TOOLS.has(toolName)) {
    if (handle.mode === "proxy") {
      try {
        return await handleProxyGeneric(toolName, args, handle);
      } catch (err) {
        process.stderr.write(
          `[@agentmemory/mcp] proxy call failed for ${toolName}: ${err instanceof Error ? err.message : String(err)}\n`,
        );
        invalidateHandle();
        throw err;
      }
    }
    throw new Error(
      `Unknown tool: ${toolName} (local fallback supports only ${[...IMPLEMENTED_TOOLS].join(", ")}; start an agentmemory server and set AGENTMEMORY_URL to use the full tool set)`,
    );
  }

  const validated = validate(toolName, args);
  if (handle.mode === "proxy") {
    try {
      return await handleProxy(validated, handle);
    } catch (err) {
      if (toolName === "memory_sessions" || isAuthenticationError(err) || isProxyRequired()) {
        invalidateHandle();
        throw err;
      }
      process.stderr.write(
        `[@agentmemory/mcp] proxy call failed for ${toolName}: ${err instanceof Error ? err.message : String(err)}; invalidating handle and falling back to local KV\n`,
      );
      invalidateHandle();
    }
  }
  return handleLocal(validated, kvInstance);
}

export async function handleToolsList(): Promise<{ tools: unknown[] }> {
  const debug = process.env["AGENTMEMORY_DEBUG"] === "1" || process.env["AGENTMEMORY_DEBUG"] === "true";
  const handle = await resolveHandle();
  announceMode(handle);
  if (debug) {
    process.stderr.write(
      `[@agentmemory/mcp] tools/list: handle.mode=${handle.mode}${handle.mode === "proxy" ? ` baseUrl=${handle.baseUrl}` : ""}\n`,
    );
  }
  if (handle.mode === "proxy") {
    try {
      const remote = (await handle.call("/agentmemory/mcp/tools", {
        method: "GET",
      })) as { tools?: unknown } | null;
      if (debug) {
        const shape = remote === null
          ? "null"
          : typeof remote !== "object"
            ? typeof remote
            : `keys=${Object.keys(remote as object).join(",")} toolsType=${Array.isArray((remote as { tools?: unknown }).tools) ? `array(len=${((remote as { tools: unknown[] }).tools).length})` : typeof (remote as { tools?: unknown }).tools}`;
        process.stderr.write(
          `[@agentmemory/mcp] tools/list: remote response shape: ${shape}\n`,
        );
      }
      if (remote && Array.isArray(remote.tools)) {
        if (debug) {
          process.stderr.write(
            `[@agentmemory/mcp] tools/list: returning ${remote.tools.length} tools from server\n`,
          );
        }
        return { tools: remote.tools };
      }
      if (isProxyRequired()) throw new Error("AgentMemory returned an invalid tool inventory");
      process.stderr.write(
        `[@agentmemory/mcp] tools/list: server returned unexpected shape (no .tools array); falling back to local IMPLEMENTED_TOOLS list. Set AGENTMEMORY_DEBUG=1 to inspect response.\n`,
      );
    } catch (err) {
      invalidateHandle();
      if (isAuthenticationError(err) || isProxyRequired()) throw err;
      process.stderr.write(
        `[@agentmemory/mcp] tools/list proxy failed: ${err instanceof Error ? err.message : String(err)}; falling back to local list\n`,
      );
    }
  }
  const fallback = getAllTools().filter((t) => IMPLEMENTED_TOOLS.has(t.name));
  if (debug) {
    process.stderr.write(
      `[@agentmemory/mcp] tools/list: returning ${fallback.length} local fallback tools (${fallback.map((t) => t.name).join(",")})\n`,
    );
  }
  return { tools: fallback };
}

const transport = createStdioTransport(async (method, params) => {
  switch (method) {
    case "initialize": {
      const requested = (params as { protocolVersion?: unknown } | undefined)
        ?.protocolVersion;
      const protocolVersion =
        typeof requested === "string" &&
        SUPPORTED_PROTOCOL_VERSIONS.includes(requested)
          ? requested
          : SUPPORTED_PROTOCOL_VERSIONS[0];
      return {
        protocolVersion,
        capabilities: { tools: { listChanged: false } },
        serverInfo: {
          name: SERVER_INFO.name,
          version: SERVER_INFO.version,
        },
      };
    }

    case "notifications/initialized":
      return {};

    case "tools/list":
      return handleToolsList();

    case "tools/call": {
      const toolName = params.name as string;
      const toolArgs = (params.arguments as Record<string, unknown>) || {};
      try {
        return await handleToolCall(toolName, toolArgs);
      } catch (err) {
        return {
          content: [
            {
              type: "text",
              text: `Error: ${err instanceof Error ? err.message : String(err)}`,
            },
          ],
          isError: true,
        };
      }
    }

    default:
      throw new Error(`Unknown method: ${method}`);
  }
});

process.stderr.write(
  `[@agentmemory/mcp] Standalone MCP server v${SERVER_INFO.version} starting...\n`,
);
transport.start();

process.on("SIGINT", () => {
  kv.persist();
  process.exit(0);
});
process.on("SIGTERM", () => {
  kv.persist();
  process.exit(0);
});