Pi Agent Plugin

Copyexport default function mem0Extension(pi: ExtensionAPI): void {
  const config = loadConfig();
 
  if (!config.apiKey) {
    console.warn("[mem0] No API key found. Set MEM0_API_KEY or add apiKey to ~/.pi/agent/mem0-config.json. Extension disabled.");
    return;
  }

Copyexport function resolveUserId(configUserId: string): string {
  if (configUserId) return configUserId;
  if (process.env.USER) return process.env.USER;
  if (process.env.USERNAME) return process.env.USERNAME;
  try { return os.userInfo().username; } catch { return "default"; }
}

Copyconst mem0 = new MemoryClient({ apiKey: config.apiKey });
// Every path below shares this client: automatic recall, capture, the memory
// tools and deletion as well as the slash commands. Attribution belongs here
// rather than on individual calls, or everything except the commands reports
// as generic SDK traffic.
applySurfaceHeaders(mem0);
 
const scopeCtx: ScopeContext = {
  userId: resolveUserId(config.userId),
  appId: "",
  runId: "unknown",
};
 
function getScopeCtx(): ScopeContext {
  return scopeCtx;
}
 
const telemetryCtx = { apiKey: config.apiKey };
const lifecycle = createMemoryLifecycle();
 
// ── Register tool + commands + auto-capture ─────────────────────────
registerMemoryTool(pi, mem0, config, getScopeCtx, telemetryCtx);
registerCommands(pi, mem0, config, getScopeCtx, telemetryCtx);
setupAutoCapture(pi, mem0, config, getScopeCtx, telemetryCtx, lifecycle);
 
captureEvent("pi.plugin.registered", {
  auto_capture: config.autoCapture,
  default_scope: config.defaultScope,
}, telemetryCtx);
 

Copy// ── session_start: detect project + session, reconstruct scope ──────
pi.on("session_start", async (_event, ctx) => {
  lifecycle.beginSession();
  scopeCtx.appId = detectAppId(ctx.cwd);
 
  const sessionFile = ctx.sessionManager?.getSessionFile?.();
  scopeCtx.runId = detectRunId(sessionFile);
 
  if (config.userId) {
    scopeCtx.userId = config.userId;
  }
 
  captureEvent("pi.session.start", {}, telemetryCtx);
});
 
// ── before_agent_start: append memory policy and recall ─────────────
pi.on("before_agent_start", async (event, _ctx) => {
  let extra = MEMORY_POLICY;
 
  // Guaranteed retrieval: prefetch memories relevant to this prompt so the
  // agent always has them, rather than depending on it to call the tool.
  const recall = await lifecycle.recall(
    event.prompt ?? "",
    config.contextInjection,
    (q) => mem0.search(q, { filters: resolveSearchFilters("project", scopeCtx) }),
  );
  if (recall) extra += "\n\n" + recall;
 
  return {
    systemPrompt: (event.systemPrompt ?? "") + "\n\n" + extra,
  };
});
 
// ── session_shutdown ────────────────────────────────────────────────
pi.on("session_shutdown", async () => {
  captureEvent("pi.session.stop", {}, telemetryCtx);
});

Copyexport const PLATFORM_SOURCE = "PI_AGENT";
 
/** Host app the plugin runs inside. Allowlisted server-side. */
export const PLATFORM_APPLICATION = "pi";
 
const PLUGIN_VERSION = (() => {
  try {
    return JSON.parse(
      fs.readFileSync(new URL("../package.json", import.meta.url), "utf-8"),
    ).version as string;
  } catch {
    return "unknown";
  }
})();

Copyexport function applySurfaceHeaders(client: MemoryClient): void {
  const headers = client.headers as Record<string, string>;
  if (!headers["X-Mem0-Source"]?.trim()) headers["X-Mem0-Source"] = PLATFORM_SOURCE;
  if (!headers["X-Application"]?.trim()) headers["X-Application"] = PLATFORM_APPLICATION;
 
  const existing = (headers["X-Mem0-Client"] ?? "")
    .split(",")
    .map((part) => part.trim())
    .filter(Boolean);
  headers["X-Mem0-Client"] = boundedStack(existing, `mem0-pi-agent/${PLUGIN_VERSION}`);
}

Copypi.registerCommand("mem0-remember", {
  description: "Store a memory verbatim (no inference)",
  handler: async (args, ctx) => {
    const text = args?.trim();
    if (!text) {
      ctx.ui.notify("Usage: /mem0-remember <text>", "warning");
      return;
    }
 
    const addParams = resolveAddParams(config.defaultScope, getScopeCtx());
    const result = await mem0.add(
      [{ role: "user", content: text }],
      { ...addParams, customCategories: DEFAULT_CUSTOM_CATEGORIES, infer: false, source: PLATFORM_SOURCE },
    );
    captureCommandEvent("mem0-remember", {}, telemetryCtx);
 
    const storedItems = (Array.isArray(result) ? result : [])
      .map((m) => (m as { memory?: string }).memory)
      .filter((m): m is string => Boolean(m));
    const items = storedItems.length > 0 ? storedItems : [text];
    sendFeedback(
      "mem0-remember",
      [`**Stored to ${config.defaultScope} memory**`, ...items.map((m) => `- ${m}`)].join("\n"),
    );
  },
});

Copypi.registerCommand("mem0-forget", {
  description: "Delete memories matching a natural language query",
  handler: async (args, ctx) => {
    const query = args?.trim();
    if (!query) {
      ctx.ui.notify("Usage: /mem0-forget <query>", "warning");
      return;
    }
 
    const memories = await searchMemories(query, config.defaultScope);
 
    if (memories.length === 0) {
      captureCommandEvent("mem0-forget", { result_count: 0 }, telemetryCtx);
      sendFeedback("mem0-forget", `**No matches for "${query}"** — nothing to forget.`);
      return;
    }
 
    const forgotten = (mem: Parameters<typeof formatMemoryCompact>[0]) => {
      captureCommandEvent("mem0-forget", { deleted_count: 1 }, telemetryCtx);
      sendFeedback(
        "mem0-forget",
        [`**Forgotten from ${config.defaultScope} memory**`, `- ${formatMemoryCompact(mem)}`].join("\n"),
      );
    };
 
    if (memories.length === 1) {
      const target = memories[0];
      const confirmed = await ctx.ui.confirm("Delete this memory?", formatMemoryCompact(target));
      if (!confirmed) {
        sendFeedback("mem0-forget", "**Cancelled** — no memories deleted.");
        return;
      }
      await mem0.delete(target.id);
      forgotten(target);
      return;
    }
 
    const labels = memories.map((m) => formatMemoryCompact(m));
    const selected = await ctx.ui.select(
      `Found ${pluralize(memories.length, "match", "matches")} for "${query}" — which should I delete?`,
      labels,
    );
    if (!selected) {
      sendFeedback("mem0-forget", "**Cancelled** — no memories deleted.");
      return;
    }
    const idx = labels.indexOf(selected);
    if (idx < 0) return;
    const target = memories[idx];
    await mem0.delete(target.id);
    forgotten(target);
  },
});

Copypi.registerCommand("mem0-tour", {
  description: "Browse all memories grouped by category",
  handler: async (args, ctx) => {
    const raw = args?.trim().toLowerCase();
    const validScopes: Scope[] = ["project", "session", "global"];
    if (raw && !validScopes.includes(raw as Scope)) {
      ctx.ui.notify(`Invalid scope "${raw}". Must be one of: ${validScopes.join(", ")}`, "warning");
      return;
    }
    const scope: Scope = (raw as Scope) || config.defaultScope;
    const filters = resolveSearchFilters(scope, getScopeCtx());
    const result = await mem0.getAll({ filters });
    const memories = result.results ?? [];
 
    if (memories.length === 0) {
      captureCommandEvent("mem0-tour", { memory_count: 0, scope }, telemetryCtx);

Copyparameters: Type.Object({
  action: StringEnum(
    [
      "search",
      "add",
      "get_all",
      "update",
      "delete",
      "delete_all",
    ] as const,
    {
      description:
        "Memory operation to run: \"search\" (semantic recall of earlier work in this repository), \"add\" (save a new fact/preference/decision), \"get_all\" (list everything in scope, no query needed), \"update\" (replace an existing memory's text by id), \"delete\" (remove one memory by id), \"delete_all\" (wipe every memory in the scope -- destructive, only on explicit request).",
    },
  ),
  query: Type.Optional(
    Type.String({
      description:
        `Search text -- required for action "search". ${SEARCH_QUERY_DESCRIPTION}`,
    }),
  ),
  content: Type.Optional(
    Type.String({
      description:
        "Memory text -- required for action \"add\" (the fact to store) and \"update\" (the replacement text).",
    }),
  ),
  memory_id: Type.Optional(
    Type.String({
      description:
        "Target memory's ID -- required for \"update\" and \"delete\". Use an ID returned by a prior \"search\" or \"get_all\".",
    }),
  ),
  scope: Type.Optional(
    StringEnum(["project", "session", "global"] as const, {
      description:
        "Where to read/write: \"project\" (default -- this repo), \"session\" (this run only), or \"global\" (across ALL projects; only when the user explicitly wants cross-project recall). Omit for normal queries.",
    }),
  ),
}),

Copyconst MAX_OUTPUT_LINES = 200;
const MAX_OUTPUT_BYTES = 50_000;
 
function normalizeMemoryId(id: string): string {
  return id.replace(/^\[?mem0:([0-9a-f-]{36})\]?$/i, "$1");
}
 
function truncateOutput(text: string): string {
  const lines = text.split("\n");
  if (lines.length <= MAX_OUTPUT_LINES && text.length <= MAX_OUTPUT_BYTES) {
    return text;
  }
 
  const kept = lines.slice(0, MAX_OUTPUT_LINES);
  let result = kept.join("\n");
  if (result.length > MAX_OUTPUT_BYTES) {
    result = result.slice(0, MAX_OUTPUT_BYTES);
  }
 
  const dropped = lines.length - kept.length;
  if (dropped > 0 || text.length > MAX_OUTPUT_BYTES) {
    result += `\n\n[Output truncated: showing ${kept.length} of ${lines.length} lines]`;
  }
  return result;
}

Copyfunction normalizeMemoryId(id: string): string {
  return id.replace(/^\[?mem0:([0-9a-f-]{36})\]?$/i, "$1");
}

Copyexport const MEMORY_POLICY = `<mem0-memory-policy>
You have persistent semantic memory via the mem0_memory tool, powered by Mem0. Relevant memories may be auto-injected under <mem0-relevant-memories>.
 
Use mem0_memory with action "search" ${SEARCH_WHEN}.
 
Be proactive about saving:
- Save important facts, preferences, goals, decisions, lessons learned, identity, relationships, and routines the user shares.
 
Scope (do not change unless explicitly asked):
- "project" (default): memories for this project — use for all normal queries
- "session": memories from this session only
- "global": all memories across projects — ONLY when the user explicitly asks for cross-project search
 
Memory persists across sessions and devices via Mem0's cloud.
</mem0-memory-policy>`;

Copy"Always use the default project scope unless the user EXPLICITLY asks to search across all projects — only after the user selects /mem0-scope global use scope \"global\"",
"Do NOT pass scope at all for normal queries — omitting it uses the project default automatically",

Copyexport {
  formatAge,
  formatMemoryCompact,
  formatMemoryList,
  groupByCategory,
} from "../../../agent-plugin-core/typescript/src/formatting.ts";

Copyimport { formatMemoryList, formatMemoryCompact, groupByCategory } from "./memory/formatting.ts";