@everme/pi 0.6.2

package/README.md

@@ -0,0 +1,94 @@
+# @everme/pi
+
+EverMe long-term memory for the [Pi coding agent](https://pi.dev): profile and
+recall injection, automatic turn capture, and four memory tools.
+
+Verified against **pi 0.80.10**. Requires **pi >= 0.80.4** — the
+`agent_settled` event this extension uploads on was added in that release.
+
+## Install
+
+```bash
+evercli plugin install pi
+```
+
+That provisions the credentials (`~/.pi/agent/everme.env`, mode 0600) and runs
+`pi install npm:@everme/pi`, which records the package in the `packages` array
+of `~/.pi/agent/settings.json`. Start a new pi session afterwards.
+
+To install the package without evercli and provide credentials yourself:
+
+```bash
+pi install npm:@everme/pi
+printf 'EVERME_AGENT_ID=agt_...\nEVERME_AGENT_TOKEN=evt_...\n' > ~/.pi/agent/everme.env
+chmod 600 ~/.pi/agent/everme.env
+```
+
+`/everme` prints the status: which agent, which credential file, whether the
+profile was injected, how many turns were saved, and the last error if any.
+
+## What it does
+
+| pi event | what the extension does |
+|---|---|
+| `session_start` | resets per-session state; on resume/reload/fork checks whether this session already carries the profile |
+| `before_agent_start` | injects `<everme_profile>` (once per session) and `<everme_recall>` (every turn) as a `custom_message` — model context, not TUI output |
+| `agent_end` | buffers that run's messages |
+| `agent_settled` | uploads the buffered turn (no flush: the gateway extracts on its own, and waiting for it is ~30x slower) |
+
+Tools: `mem_search`, `mem_context`, `mem_save_fact`, `mem_save_turn`. The
+`everme` skill tells the model when to reach for them.
+
+### Why the buffer
+
+`agent_end` is the only event that carries messages, and it can fire several
+times for one user turn — pi may auto-retry, auto-compact and retry, or run a
+queued follow-up. `agent_settled` is the guarantee that nothing more will run
+automatically, but **its payload is empty** (verified in pi's own type
+declarations: `{ type: "agent_settled" }` and nothing else). So the transcript
+is collected at `agent_end` and uploaded at `agent_settled`.
+
+### Failure policy
+
+Recall and profile injection are best-effort and bounded by their own
+deadlines (6s / 8s), well inside anything a user would wait for. On timeout or
+error the turn proceeds with no injection: a memory lookup must never be the
+reason a prompt hangs. pi's own provider layer can already stall — an
+`openai-codex` OAuth refresh was observed hanging a whole run — and this
+extension refuses to add to that.
+
+Saves are reported, never faked. A failed upload surfaces in `/everme` and in
+the tool result; nothing is silently queued or dropped.
+
+## Notes for maintainers
+
+- The extension is plain ESM JavaScript, like every other package here. pi's
+  loader accepts `.js` and `.ts` equally; `.js` needs no jiti transform and
+  keeps this package consistent with the rest of `plugins/`.
+- `typebox` is a **peer** dependency: pi validates tool parameters with its own
+  copy, and bundling a second one is what pi's packaging docs warn against.
+  It is also a devDependency so the tests can build schemas.
+- The SDK's `runHook()` is deliberately **not** used. It arms a watchdog that
+  calls `process.exit(0)` near the host's kill deadline, which is right for a
+  hook process and fatal inside the long-lived pi TUI. This package uses the
+  SDK primitives (client, `runInject`, `saveAgentMemory`, rune caps,
+  redaction) and owns its own deadlines.
+- Nothing is written to `process.env`. pi spawns tools and user bash commands
+  from the same environment, so an agent token placed there would leak into
+  every child process.
+- Cold-start import for pi sessions lives in evercli
+  (`evercli import conversations run --platform pi`), which reads
+  `~/.pi/agent/sessions/**` directly. The extension does not backfill history.
+
+## Tests
+
+```bash
+npm test --workspace @everme/pi     # from plugins/
+```
+
+The extension tests drive the real event chain through a stand-in `pi` object
+against a local HTTP backend, asserting the injected block shapes and the
+upload body. The install path itself was verified on a real pi 0.80.10:
+`pi install <path>` is headless, `pi list` shows the package, `pi remove`
+restores `settings.json` byte-for-byte, and a live run reached
+`/mem/context`, `/mem/search` and `/mem/agent-memory` in that order.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@everme/pi",
+  "version": "0.6.2",
+  "type": "module",
+  "description": "EverMe long-term memory for the Pi coding agent: profile and recall injection, automatic turn capture, and four memory tools.",
+  "license": "Apache-2.0",
+  "files": [
+    "src/",
+    "skills/",
+    "LICENSE",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/extension.js"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test tests/credentials.test.js tests/extension.test.js"
+  },
+  "keywords": [
+    "pi-package",
+    "evermind",
+    "everme",
+    "pi",
+    "memory"
+  ],
+  "homepage": "https://everme.evermind.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EverMind-AI/EverMe.git",
+    "directory": "plugins/pi"
+  },
+  "bugs": {
+    "url": "https://github.com/EverMind-AI/EverMe/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@everme/agent-sdk": "^0.6.2"
+  },
+  "peerDependencies": {
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "typebox": "^1.0.0"
+  }
+}

package/skills/everme/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: everme
+description: |
+  Use EverMe long-term memory when the user refers to previous
+  conversations, earlier decisions, "last time", "remember when", existing
+  project conventions, or previously solved errors, and save durable user
+  preferences, habits, and decisions the moment they are stated. This
+  package's extension already injects a profile at session start and a
+  recall block before each turn, and saves the whole turn when the agent
+  settles — so do not repeat work the injected blocks already did.
+---
+
+# What this package gives you
+
+`@everme/pi` installs a pi extension that does three things without being
+asked, plus four tools you call yourself.
+
+Automatic, via extension events:
+
+| when | what happens |
+|---|---|
+| session start | the user's durable Profile is injected as `<everme_profile>` |
+| before each agent turn | relevant memories are injected as `<everme_recall>` |
+| after the agent settles | the whole turn (messages + tool calls) is saved |
+
+Tools, for the cases the automatic path does not cover:
+
+| tool | input | output |
+|---|---|---|
+| `mem_context` | `{ forceRefresh? }` | the durable Profile only — never a search |
+| `mem_search` | `{ query, topK? }` | search results across all memory buckets |
+| `mem_save_fact` | `{ fact }` | `{ saved, accepted, status, extracted, profileUpdated }` |
+| `mem_save_turn` | `{ role, text }` or `{ messages }` | `{ saved, accepted, status, messageCount, flushed }` |
+
+# When to call the tools
+
+**Call them autonomously when a trigger fires — not only when the user says
+"remember" or "recall".**
+
+**Check the injected blocks first.** When a non-empty, relevant
+`<everme_recall>` block is already in your context this turn, do not
+re-fetch the same thing with `mem_search`. Injection can fail silently
+(network, revoked credentials): recall is best-effort by design, because a
+memory lookup must never block the user's turn. So when the block is
+missing or clearly unrelated and the task depends on history, search.
+
+- **`mem_search`** — the user points back at earlier conversations,
+  decisions, conventions, or previously solved problems ("what did we
+  decide about X", "like last time", "did we fix this before"), and the
+  injected recall did not already answer it. Keep `query` SHORT: a few
+  keywords naming the topic, never the whole conversation. Do not repeat an
+  identical query in the same turn.
+- **`mem_context`** — only when no `<everme_profile>` block was injected
+  this session. It returns the Profile alone; it is not a way to recall
+  past decisions or task context, which is `mem_search`'s job. Once per
+  session; `forceRefresh: true` only when the user explicitly asks.
+- **`mem_save_fact`** — the user states something true about themselves
+  that should outlive this conversation (a preference, habit, trait,
+  long-term goal, or decision). Only `extracted: true` /
+  `profileUpdated: true` means it reached the Profile; on
+  `status: "no_extraction"` say so plainly, do not auto-retry, and do not
+  claim it was remembered.
+- **`mem_save_turn`** — a conclusion worth reusing that the automatic save
+  would not capture as such. The turn is already saved for you when the
+  agent settles, so this is for deliberate, self-contained records, not for
+  re-saving the conversation.
+
+Rows returned under "Recent unextracted transcript" are provisional — not
+yet extracted — so never quote them as established facts.
+
+# Errors
+
+Tools fail with a short message: `auth` (credentials revoked or expired —
+re-run `evercli plugin install pi`), `network` (backend unreachable, retry
+with backoff), `upstream` (backend returned a non-zero status; the message
+carries the requestId for support). A failed save is reported as a failure;
+there is no fake success and no local queue that silently drops.
+
+Cold-start memory — everything the user already had before installing —
+is loaded by `evercli import conversations run`, which reads pi's own
+session files. You do not need to re-upload history from inside the agent.

package/src/credentials.js

@@ -0,0 +1,86 @@
+/**
+ * Credential loading for the Pi extension.
+ *
+ * `evercli plugin install pi` writes ~/.pi/agent/everme.env at 0600 with the
+ * standard three keys. The extension runs inside the pi process, so it must
+ * NOT mutate process.env: pi spawns tools and user bash commands from the
+ * same environment, and injecting an agent token there would leak it into
+ * every child process. The file is read into a plain object instead and
+ * handed to the SDK explicitly.
+ */
+
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const KEYS = ["EVERME_API_BASE", "EVERME_AGENT_ID", "EVERME_AGENT_TOKEN"];
+
+export function piAgentHome(env = process.env) {
+  return env.EVERCLI_PI_CONFIG_DIR || join(homedir(), ".pi", "agent");
+}
+
+export function envFilePath(env = process.env) {
+  return env.EVERME_ENV_FILE_PATH || join(piAgentHome(env), "everme.env");
+}
+
+/**
+ * Parse a dotenv-style file. Tolerates `export VAR=`, surrounding quotes and
+ * comment lines — the same shapes evercli's own reader accepts, so a file a
+ * user hand-edited behaves the same on both sides.
+ */
+export function parseEnvFile(text) {
+  const out = {};
+  for (const rawLine of String(text || "").split("\n")) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    if (line.startsWith("export ")) line = line.slice("export ".length).trim();
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    const key = line.slice(0, eq).trim();
+    if (!KEYS.includes(key)) continue;
+    out[key] = line.slice(eq + 1).trim().replace(/^["']|["']$/g, "");
+  }
+  return out;
+}
+
+/**
+ * Load the credentials.
+ *
+ * Returns { configured, agentId, agentToken, apiBase, path, reason }.
+ * `configured` false is a normal state, not an error: a user who installed
+ * the pi package from npm without running `evercli plugin install pi` has no
+ * env file yet. Events skip silently in that state and the tools return the
+ * install instruction, so nothing about the failure is guessed at.
+ */
+export async function loadCredentials(env = process.env) {
+  const path = envFilePath(env);
+  let parsed = {};
+  let reason = "";
+  try {
+    parsed = parseEnvFile(await readFile(path, "utf8"));
+  } catch (error) {
+    reason = error?.code === "ENOENT" ? "missing" : "unreadable";
+  }
+  // Explicit process env wins over the file: that is how a CI smoke run or a
+  // `pi -e` trial run points the extension at a test backend without writing
+  // a credential file onto the machine.
+  const agentId = env.EVERME_AGENT_ID || parsed.EVERME_AGENT_ID || "";
+  const agentToken = env.EVERME_AGENT_TOKEN || parsed.EVERME_AGENT_TOKEN || "";
+  const apiBase = env.EVERME_API_BASE || parsed.EVERME_API_BASE || "";
+  if (!reason && !(agentId && agentToken)) reason = "incomplete";
+  return {
+    configured: Boolean(agentId && agentToken),
+    agentId,
+    agentToken,
+    apiBase,
+    path,
+    reason: agentId && agentToken ? "" : reason || "missing",
+  };
+}
+
+export function notConfiguredMessage(credentials) {
+  const detail = credentials?.reason === "unreadable"
+    ? `could not be read at ${credentials.path}`
+    : `is missing or incomplete at ${credentials?.path || envFilePath()}`;
+  return `EverMe is not configured for pi: the credential file ${detail}. Run \`evercli plugin install pi\` to provision it, then start a new pi session.`;
+}

package/src/extension.js

@@ -0,0 +1,444 @@
+/**
+ * EverMe memory extension for the Pi coding agent.
+ *
+ * Verified against pi 0.80.10. Event contract (from pi's own type
+ * declarations, not inferred):
+ *
+ *   session_start        { reason: "startup"|"reload"|"new"|"resume"|"fork" }
+ *   before_agent_start   { prompt, systemPrompt, ... } -> may return
+ *                        { message: { customType, content, display } }
+ *                        which pi persists as a `custom_message` entry AND
+ *                        sends to the model. This is the injection channel.
+ *   agent_end            { messages }  <- the ONLY event carrying messages
+ *   agent_settled        { }           <- no payload at all
+ *
+ * That split is the whole reason this file buffers: pi may auto-retry,
+ * auto-compact, or run queued follow-ups after agent_end, so agent_end can
+ * fire several times for one user turn. agent_settled is the guarantee that
+ * nothing more runs automatically — but it carries no messages, so the
+ * transcript has to be collected at agent_end and uploaded at agent_settled.
+ * (Reading it back from ctx.sessionManager at settle time was the
+ * alternative; buffering keeps exactly the messages of this turn instead of
+ * re-deriving a branch.)
+ *
+ * Failure policy: recall and profile injection are best-effort and never
+ * block a turn — a memory lookup that cannot answer must not stop the user
+ * from working. Saves report their failure (through /everme and the tool
+ * result), never a fake success.
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { Type } from "typebox";
+import { loadCredentials, notConfiguredMessage, piAgentHome } from "./credentials.js";
+import {
+  describeFailure,
+  fetchProfileBlock,
+  fetchRecallBlock,
+  profile,
+  saveFact,
+  saveTurn,
+  search,
+} from "./memory.js";
+
+// Marks a session as already carrying the profile block. Persisted as a pi
+// `custom` entry, which survives a reload/resume and does NOT enter the LLM
+// context — exactly what a bookkeeping flag should be.
+const PROFILE_MARK = "everme-profile-injected";
+const MESSAGE_TYPE = "everme-memory";
+
+export default function evermeExtension(pi) {
+  const state = {
+    // pi AgentMessages collected from every agent_end of the current turn.
+    pending: [],
+    profileInjected: false,
+    lastSave: null,
+    lastError: "",
+    saves: 0,
+    // Turns whose upload failed and were written to disk instead of being
+    // dropped. Never auto-resent — see the agent_settled handler.
+    spooled: 0,
+    lastSpoolPath: "",
+    // Turns whose save timed out. Counted separately from failures: the
+    // gateway had already stored them (see the agent_settled handler).
+    unconfirmed: 0,
+    lastUnconfirmed: null,
+  };
+
+  const credentialsOnce = memoize(() => loadCredentials());
+
+  pi.on("session_start", async (event, ctx) => {
+    state.pending = [];
+    state.profileInjected = false;
+    // A resumed or reloaded session may already carry the profile from its
+    // first run; re-injecting it would duplicate a block the model can
+    // already see in its own transcript.
+    if (event?.reason === "resume" || event?.reason === "reload" || event?.reason === "fork") {
+      state.profileInjected = hasProfileMark(ctx);
+    }
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    const credentials = await credentialsOnce();
+    if (!credentials.configured) return undefined;
+
+    const blocks = [];
+    if (!state.profileInjected) {
+      const block = await attempt(state, () => fetchProfileBlock(credentials));
+      if (block) {
+        blocks.push(block);
+        state.profileInjected = true;
+        try {
+          pi.appendEntry(PROFILE_MARK, { at: new Date().toISOString() });
+        } catch {
+          // The mark is an optimization; failing to persist it only costs a
+          // duplicate profile fetch on the next resume.
+        }
+      }
+    }
+    const recall = await attempt(state, () => fetchRecallBlock(credentials, event?.prompt || ""));
+    if (recall) blocks.push(recall);
+    if (!blocks.length) return undefined;
+
+    return {
+      message: {
+        customType: MESSAGE_TYPE,
+        content: blocks.join("\n\n"),
+        // Not shown in the TUI: this is context for the model, and printing
+        // the user's whole profile above their own prompt is noise.
+        display: false,
+      },
+    };
+  });
+
+  // Every agent_end of the turn contributes its messages; a retry or an
+  // auto-compaction adds another batch rather than replacing this one.
+  pi.on("agent_end", (event) => {
+    const messages = Array.isArray(event?.messages) ? event.messages : [];
+    if (messages.length) state.pending.push(...messages);
+  });
+
+  pi.on("agent_settled", async (_event, ctx) => {
+    const messages = state.pending;
+    state.pending = [];
+    if (!messages.length) return;
+    const credentials = await credentialsOnce();
+    if (!credentials.configured) return;
+    const conversationId = conversationIdOf(ctx);
+    if (!conversationId) return;
+    try {
+      // flush:false deliberately. A flushing write blocks on the upstream
+      // extraction: measured 29.8s against a real backend versus 0.9s for
+      // the same payload without it, which is past every hook budget here
+      // and made EVERY turn report a failure it had not actually suffered.
+      // The server promotes an un-flushed session on its own (verified: a
+      // session written with flush:false and never flushed successfully was
+      // extracted into an episode ~100s later), so nothing is lost by
+      // letting it do that instead of waiting.
+      const result = await saveTurn(credentials, {
+        conversationId,
+        messages,
+        flush: false,
+        timeoutMs: saveTimeoutMs(),
+      });
+      state.saves += 1;
+      state.lastSave = {
+        at: new Date().toISOString(),
+        messages: messages.length,
+        status: result?.status || "",
+        requestId: result?.requestId || "",
+      };
+      state.lastError = "";
+    } catch (error) {
+      // A timeout is NOT a failed save. The gateway adds the messages before
+      // it flushes, and nothing on that path detaches the request context,
+      // so by the time a client-side deadline fires the messages are already
+      // stored — verified against two real timed-out sessions, both present
+      // and extracted server-side afterwards. Spooling those would keep a
+      // duplicate of data that is already saved, and reporting them as
+      // failures is a lie in the conservative direction.
+      if (error?.type === "timeout") {
+        state.unconfirmed += 1;
+        state.lastUnconfirmed = {
+          at: new Date().toISOString(),
+          messages: messages.length,
+          detail: describeFailure(error),
+        };
+        return;
+      }
+      state.lastError = describeFailure(error);
+      // A real failure is different: the request was refused, rejected or
+      // never arrived, so the turn IS gone unless it is kept here.
+      //
+      // No automatic resend: a POST that died mid-flight may already have
+      // been applied upstream, and the write path carries no
+      // idempotency key, so re-sending the same turn can double-ingest it.
+      //
+      // No silent discard either: `evercli import` excludes every session
+      // started inside this platform's install-mark window, because the
+      // live extension is supposed to own that era. A turn dropped here is
+      // therefore NOT recoverable by a later cold-start import - it is gone.
+      //
+      // So the turn is written to disk as an explicit, recoverable artifact
+      // and reported by /everme. Replaying it is a deliberate act.
+      const spoolPath = await spoolFailedTurn(conversationId, messages, state.lastError);
+      if (spoolPath) {
+        state.spooled += 1;
+        state.lastSpoolPath = spoolPath;
+      } else {
+        // The spool write failed too (read-only home, full disk). Say so
+        // rather than leaving the user believing the turn was kept.
+        state.lastError += " (and the failed turn could not be spooled)";
+      }
+    }
+  });
+
+  pi.registerTool({
+    name: "mem_search",
+    label: "EverMe search",
+    description:
+      "Search the user's EverMe long-term memory. Use when the user refers to earlier conversations, decisions, conventions, or previously solved problems and the injected <everme_recall> block did not already answer it. Keep the query short - a few keywords naming the topic, never the whole conversation.",
+    promptSnippet: "mem_search - search the user's long-term memory",
+    // TypeBox, not a hand-written JSON Schema: pi validates tool arguments
+    // through typebox's compiler, which keys off the Kind symbol its own
+    // builders attach. typebox is a peer dependency so pi's copy is used.
+    parameters: Type.Object({
+      query: Type.String({ description: "Short keyword query naming the topic." }),
+      topK: Type.Optional(Type.Integer({ description: "Maximum results (default 10)." })),
+    }),
+    async execute(_toolCallId, params) {
+      const credentials = await requireCredentials(credentialsOnce);
+      const result = await search(credentials, { query: params?.query || "", topK: params?.topK });
+      return textResult(renderSearch(result));
+    },
+  });
+
+  pi.registerTool({
+    name: "mem_context",
+    label: "EverMe profile",
+    description:
+      "Return the user's durable EverMe profile. Only needed when no <everme_profile> block was injected this session. This is NOT a search: it never returns past decisions or task context - use mem_search for that.",
+    promptSnippet: "mem_context - read the user's durable profile",
+    parameters: Type.Object({
+      forceRefresh: Type.Optional(
+        Type.Boolean({ description: "Rebuild the profile instead of using the cached one." }),
+      ),
+    }),
+    async execute(_toolCallId, params) {
+      const credentials = await requireCredentials(credentialsOnce);
+      const result = await profile(credentials, { forceRefresh: Boolean(params?.forceRefresh) });
+      return textResult(result?.context || "(no profile stored yet)");
+    },
+  });
+
+  pi.registerTool({
+    name: "mem_save_fact",
+    label: "EverMe save fact",
+    description:
+      "Save one durable fact about the user (a preference, habit, trait, long-term goal, or decision) to their profile. Call it as soon as such a fact is stated, without waiting to be asked. Only an extracted/profileUpdated result means the profile actually changed.",
+    promptSnippet: "mem_save_fact - remember a durable fact about the user",
+    parameters: Type.Object({
+      fact: Type.String({ description: "The fact, as one self-contained sentence." }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const credentials = await requireCredentials(credentialsOnce);
+      const fact = String(params?.fact || "").trim();
+      if (!fact) throw new Error("fact must not be empty");
+      const conversationId = conversationIdOf(ctx) || `pi-${Date.now()}`;
+      const result = await saveFact(credentials, { fact, conversationId });
+      return textResult(JSON.stringify({
+        saved: Boolean(result),
+        status: result?.status || "",
+        extracted: result?.extracted ?? null,
+        profileUpdated: result?.profileUpdated ?? null,
+        requestId: result?.requestId || "",
+      }));
+    },
+  });
+
+  pi.registerTool({
+    name: "mem_save_turn",
+    label: "EverMe save turn",
+    description:
+      "Save a conversation turn to EverMe. The extension already saves each turn automatically when the agent settles, so use this only for a deliberate, self-contained record worth reusing - not to re-save the conversation.",
+    promptSnippet: "mem_save_turn - record a reusable trajectory",
+    parameters: Type.Object({
+      // A plain string rather than an enum on purpose: Type.Union/Type.Literal
+      // does not survive Google's tool schema, and pi's StringEnum helper
+      // would add a second peer dependency for two values.
+      role: Type.Optional(Type.String({ description: "user or assistant (default assistant)." })),
+      text: Type.String({ description: "The content to save." }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const credentials = await requireCredentials(credentialsOnce);
+      const text = String(params?.text || "").trim();
+      if (!text) throw new Error("text must not be empty");
+      const role = params?.role === "user" ? "user" : "assistant";
+      const conversationId = conversationIdOf(ctx) || `pi-${Date.now()}`;
+      const result = await saveTurn(credentials, {
+        conversationId,
+        messages: [{ role, content: text, timestamp: Date.now() }],
+        flush: true,
+      });
+      return textResult(JSON.stringify({
+        saved: Boolean(result),
+        status: result?.status || "",
+        flushed: Boolean(result?.flushed),
+        requestId: result?.requestId || "",
+      }));
+    },
+  });
+
+  pi.registerCommand("everme", {
+    description: "EverMe memory status for this session",
+    async handler(_args, ctx) {
+      const credentials = await credentialsOnce();
+      const lines = [];
+      if (!credentials.configured) {
+        lines.push(notConfiguredMessage(credentials));
+      } else {
+        lines.push(`agent: ${credentials.agentId}`);
+        lines.push(`credentials: ${credentials.path}`);
+        lines.push(`conversation: ${conversationIdOf(ctx) || "(none yet)"}`);
+        lines.push(`profile injected: ${state.profileInjected ? "yes" : "no"}`);
+        lines.push(`turns saved: ${state.saves}`);
+        if (state.lastSave) {
+          lines.push(
+            `last save: ${state.lastSave.at} messages=${state.lastSave.messages}` +
+              ` status=${state.lastSave.status || "-"} requestId=${state.lastSave.requestId || "-"}`,
+          );
+        }
+      }
+      if (state.unconfirmed) {
+        lines.push(
+          `turns awaiting confirmation: ${state.unconfirmed}` +
+            (state.lastUnconfirmed ? ` (latest ${state.lastUnconfirmed.at})` : "") +
+            " - the gateway stored them; only the response timed out",
+        );
+      }
+      if (state.spooled) {
+        lines.push(
+          `turns spooled after a failed save: ${state.spooled}` +
+            ` (latest: ${state.lastSpoolPath}) - not resent automatically`,
+        );
+      }
+      if (state.lastError) lines.push(`last error: ${state.lastError}`);
+      lines.push(`pi home: ${piAgentHome()}`);
+      pi.sendMessage({
+        customType: MESSAGE_TYPE + "-status",
+        content: lines.join("\n"),
+        // The user asked, so this one IS shown.
+        display: true,
+      });
+    },
+  });
+}
+
+/**
+ * pi's session id is the conversation id on the EverMe side. When the session
+ * is ephemeral (`--no-session`) there is none, and an invented id would
+ * scatter one conversation across many — so the caller skips instead.
+ */
+// spoolFailedTurn persists one unsaved turn under the pi agent home so a
+// backend failure cannot silently lose it. Returns the path, or "" when even
+// this could not be written. 0600 / 0700: the transcript is user content.
+async function spoolFailedTurn(conversationId, messages, reason) {
+  try {
+    const dir = path.join(piAgentHome(), "everme-unsaved-turns");
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const file = path.join(dir, `${stamp}-${sanitizeForFilename(conversationId)}.json`);
+    await writeFile(
+      file,
+      JSON.stringify({ conversationId, failedAt: new Date().toISOString(), reason, messages }, null, 2),
+      { mode: 0o600 },
+    );
+    return file;
+  } catch {
+    return "";
+  }
+}
+
+function sanitizeForFilename(value) {
+  return String(value || "session").replace(/[^\w.-]/g, "_").slice(0, 80);
+}
+
+// saveTimeoutMs lets an operator (and the tests) move the write deadline
+// without a release. The default lives in memory.js.
+function saveTimeoutMs() {
+  const raw = Number(process.env.EVERME_PI_SAVE_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : undefined;
+}
+
+function conversationIdOf(ctx) {
+  try {
+    return ctx?.sessionManager?.getSessionId?.() || "";
+  } catch {
+    return "";
+  }
+}
+
+function hasProfileMark(ctx) {
+  try {
+    const entries = ctx?.sessionManager?.getEntries?.() || [];
+    return entries.some((entry) => entry?.type === "custom" && entry?.customType === PROFILE_MARK);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run a best-effort memory read. A failure is recorded for /everme and
+ * swallowed: the user's turn proceeds either way.
+ */
+async function attempt(state, operation) {
+  try {
+    return await operation();
+  } catch (error) {
+    state.lastError = describeFailure(error);
+    return "";
+  }
+}
+
+async function requireCredentials(credentialsOnce) {
+  const credentials = await credentialsOnce();
+  if (!credentials.configured) throw new Error(notConfiguredMessage(credentials));
+  return credentials;
+}
+
+function textResult(text) {
+  return { content: [{ type: "text", text }], details: undefined };
+}
+
+function renderSearch(result) {
+  const memories = result?.memories || [];
+  const profiles = result?.profiles || [];
+  const cases = result?.agentMemory?.cases || [];
+  const skills = result?.agentMemory?.skills || [];
+  const raw = result?.rawMessages || [];
+  if (!memories.length && !profiles.length && !cases.length && !skills.length && !raw.length) {
+    return "(no matching memories)";
+  }
+  const lines = [];
+  const section = (title, rows, render) => {
+    if (!rows.length) return;
+    lines.push(`## ${title}`);
+    for (const row of rows) lines.push(`- ${render(row)}`);
+  };
+  section("Episodes", memories, (m) => m?.summary || m?.content || JSON.stringify(m));
+  section("Profile", profiles, (p) => p?.description || p?.evidence || JSON.stringify(p));
+  section("Cases", cases, (c) => c?.title || c?.summary || JSON.stringify(c));
+  section("Skills", skills, (s) => s?.title || s?.summary || JSON.stringify(s));
+  // Provisional: not extracted yet, so it is labelled rather than presented
+  // as established fact.
+  section("Recent unextracted transcript", raw, (r) => `${r?.role || "?"}: ${r?.content || ""}`);
+  return lines.join("\n");
+}
+
+function memoize(factory) {
+  let promise;
+  return () => {
+    if (!promise) promise = factory();
+    return promise;
+  };
+}

package/src/memory.js

@@ -0,0 +1,171 @@
+/**
+ * EverMe operations for the Pi extension, over @everme/agent-sdk.
+ *
+ * Why the SDK's runHook() is NOT used here, even though every other native
+ * plugin does: runHook is built for a hook PROCESS. It arms a watchdog that
+ * calls process.exit(0) when the host's kill deadline nears, which is correct
+ * for a short-lived hook and fatal here — this code runs inside the long-lived
+ * pi TUI, and exiting would take the user's session down mid-turn. So the
+ * lower-level SDK primitives are used directly and this module owns its own
+ * deadlines. Everything the SDK does own is still reused: the wire protocol,
+ * rune caps, redaction, the recall query sanitizer, and the block renderers.
+ */
+
+import {
+  createClient,
+  getContext,
+  redactError,
+  renderProfileBlock,
+  resolveConfig,
+  runInject,
+  saveAgentMemory,
+  savePersonalMemory,
+  searchMemory,
+} from "@everme/agent-sdk";
+
+// Recall and profile are best-effort decorations on the user's turn, so they
+// get their own short deadlines rather than the SDK's 30s default. A memory
+// lookup must never be the reason a prompt feels stuck — and pi's own
+// provider layer can already hang (an openai-codex OAuth refresh was observed
+// hanging a whole run), so this layer refuses to add to that.
+export const RECALL_TIMEOUT_MS = 6000;
+export const PROFILE_TIMEOUT_MS = 8000;
+// Saves are worth waiting longer for: losing the turn is worse than a pause
+// after the agent already finished answering.
+export const SAVE_TIMEOUT_MS = 20000;
+
+const noopLog = { info() {}, warn() {} };
+
+export function buildConfig(credentials) {
+  return resolveConfig({
+    ...(credentials.apiBase ? { apiBase: credentials.apiBase } : {}),
+    agentId: credentials.agentId,
+    agentToken: credentials.agentToken,
+  });
+}
+
+export function buildClient(credentials, log = noopLog) {
+  const config = buildConfig(credentials);
+  return { client: createClient(config, log), config };
+}
+
+/**
+ * Race an operation against a deadline. The SDK client has its own timeout,
+ * but it is per-request and longer than a turn should ever wait; this bounds
+ * the whole operation including a retry inside the client.
+ */
+export async function withDeadline(promise, ms, label) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          // Tagged, not just worded: callers have to tell a deadline apart
+          // from a real failure, because the two mean opposite things for a
+          // write. A timeout says "we stopped waiting" - the gateway adds
+          // the messages before it flushes and does not detach the request
+          // context, so the turn is already stored. A refused or rejected
+          // request says the turn never landed. Matching on the message text
+          // would break the moment the wording changed.
+          const err = new Error(`${label} exceeded ${ms}ms`);
+          err.type = "timeout";
+          reject(err);
+        }, ms);
+        timer.unref?.();
+      }),
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * The durable profile block, or "" when there is nothing to inject.
+ */
+export async function fetchProfileBlock(credentials, log = noopLog) {
+  const { client } = buildClient(credentials, log);
+  const { context } = await withDeadline(getContext(client, "", {}, log), PROFILE_TIMEOUT_MS, "mem/context");
+  // getContext returns the server-rendered markdown when it has one; the
+  // profile object path is what renderProfileBlock exists for. Either way the
+  // block is wrapped so the model sees the same tag as on every other host.
+  if (typeof context === "string" && context.trim()) {
+    return context.trim().startsWith("<everme_profile>")
+      ? context.trim()
+      : `<everme_profile>\n${context.trim()}\n</everme_profile>`;
+  }
+  return "";
+}
+
+/**
+ * The recall block for one prompt, or "" when nothing is relevant. Reuses the
+ * SDK's runInject so query sanitization, topK, the min-score filter and the
+ * block layout are identical to the hook-based hosts.
+ */
+export async function fetchRecallBlock(credentials, prompt, log = noopLog) {
+  const { client, config } = buildClient(credentials, log);
+  const { block } = await withDeadline(
+    runInject({ input: { prompt }, client, config, search: searchMemory, log }),
+    RECALL_TIMEOUT_MS,
+    "mem/search",
+  );
+  return block || "";
+}
+
+/**
+ * Upload a turn. `messages` are pi AgentMessages, which the SDK's converter
+ * already understands: role user/assistant/toolResult, content as a string or
+ * as text/toolCall blocks, toolCallId on results. Thinking blocks are dropped
+ * by the converter, which is what we want — reasoning is not memory.
+ */
+export async function saveTurn(
+  credentials,
+  { conversationId, messages, flush = false, timeoutMs = SAVE_TIMEOUT_MS },
+  log = noopLog,
+) {
+  const { client } = buildClient(credentials, log);
+  return withDeadline(
+    saveAgentMemory(client, { conversationId, messages, flush }, log),
+    timeoutMs,
+    "mem/agent-memory",
+  );
+}
+
+/**
+ * Write a durable fact to the profile. conversationId is REQUIRED: the SDK
+ * returns null without one, which would look like a silent success at the
+ * call site.
+ */
+export async function saveFact(credentials, { fact, conversationId }, log = noopLog) {
+  if (!conversationId) throw new Error("saveFact requires a conversationId");
+  const { client } = buildClient(credentials, log);
+  return withDeadline(
+    savePersonalMemory(client, { conversationId, messages: [{ role: "user", content: fact }], flush: true }, log),
+    SAVE_TIMEOUT_MS,
+    "mem/personal",
+  );
+}
+
+export async function search(credentials, { query, topK }, log = noopLog) {
+  const { client, config } = buildClient(credentials, log);
+  return withDeadline(
+    searchMemory(client, { query, topK: topK || config.topK }, log),
+    RECALL_TIMEOUT_MS,
+    "mem/search",
+  );
+}
+
+export async function profile(credentials, { forceRefresh = false } = {}, log = noopLog) {
+  const { client } = buildClient(credentials, log);
+  return withDeadline(getContext(client, "", { forceRefresh }, log), PROFILE_TIMEOUT_MS, "mem/context");
+}
+
+/**
+ * A one-line, credential-free description of a failure, for the /everme
+ * command and for tool errors.
+ */
+export function describeFailure(error) {
+  return redactError(error).replace(/\s+/g, " ").trim();
+}
+
+export { renderProfileBlock };