@gtrabanco/pi-agentic-workflow 0.30.0 → 0.31.0

package/README.md

@@ -213,6 +213,47 @@ notification. `requirements` is keyed by phase state (`pre-freeze`, `post-freeze
 matching `path-protection-records@1` `justification` row in the unit's
 `decisions.md`.
 
+## Memory substrate — Engram (optional, ask-first)
+
+The workflow's units save and recall their decisions through Engram, the memory
+layer its skills document. This package can register Engram's MCP server for the
+session, and it does so **only when you say so**:
+
+```json
+{
+  "memory": { "engram": true }
+}
+```
+
+Registration goes through Pi's own `registerMcpServer`, which is
+**session-scoped and not persisted** — the package registers on every session
+start, so nothing outlives the session and nothing is written to your `mcp.json`
+behind your back. Five rules decide the outcome, and the package reports it
+verbatim:
+
+| Situation | What happens |
+|---|---|
+| no `memory.engram` opt-in (the shipped default is `false`) | nothing is registered and nothing is said (the opt-out stays quiet) |
+| no readable opt-in — the file exists but does not validate | nothing is registered; you are told the config is invalid, because unreadable consent is never read as a refusal you made |
+| no `engram` binary on `PATH` | nothing is registered; you are told the install route |
+| you already declared `engram` in a `mcp.json` Pi reads — your user file, or `<cwd>/.pi/mcp.json` in a trusted project | nothing is registered — your declaration takes precedence |
+| binary present, opted in | the server is registered and the notification states exactly what was written |
+
+Install Engram with:
+
+```sh
+pi install npm:gentle-engram@latest
+```
+
+That is the only documented route on purpose: the CLI's own setup subcommand
+pins whatever version ran it and keeps serving that version until it is run
+again, so an updated binary can sit unused behind a stale registration.
+
+An older Pi host whose `ExtensionAPI` has no `registerMcpServer` is reported
+instead of failing the session. The workflow-side protocol — when units save,
+the recall order, the degraded path — lives in `unit-lane`'s memory reference,
+not here.
+
 ## When a configured model is unavailable
 
 Default: the command **refuses to start** and tells you why — the model is not in

package/dist/config/defaults.js

@@ -17,6 +17,9 @@ export const DEFAULT_CONFIG = {
     // Feature 63 — model profiles: recommended built-in profiles, empty
     // named profiles, empty order (default-only), and default demotion policy.
     recommendedModels: true,
+    // Feature 66 — the memory substrate is ask-first: nothing is provisioned
+    // until the operator opts in.
+    memory: { engram: false },
     profiles: {},
     profileOrder: [],
     profileFallback: { ...DEFAULT_PROFILE_FALLBACK },

package/dist/config/merge.js

@@ -127,6 +127,11 @@ export function mergeConfigs(globalFile = {}, projectFile = {}) {
         pathProtection: intersectPathPolicy(SHIPPED_PATH_POLICY, mergePathProtectionOverrides(globalFile.pathProtection, projectFile.pathProtection)),
         // Feature 63 — model profiles.
         recommendedModels: pick(true, projectFile.recommendedModels, globalFile.recommendedModels),
+        // Feature 66 — the consent switch resolves like any other boolean knob:
+        // project wins, then global, then the shipped "no".
+        memory: {
+            engram: pick(false, projectFile.memory?.engram, globalFile.memory?.engram) === true,
+        },
         profiles: mergeProfiles(globalFile.profiles, projectFile.profiles),
         profileOrder: pick([], projectFile.profileOrder, globalFile.profileOrder),
         profileFallback: mergeProfileFallback(globalFile.profileFallback, projectFile.profileFallback),

package/dist/config/schema.d.ts

@@ -13,9 +13,4 @@ export type ParseResult = {
     ok: false;
     issues: ConfigIssue[];
 };
-/**
- * Parse and validate one config file's text. A blank file is an empty config so
- * the loader can treat "nothing declared" like "nothing present" without a
- * second read.
- */
 export declare function parseConfigFile(text: string): ParseResult;

package/dist/config/schema.js

@@ -20,6 +20,7 @@ const ROOT_KEYS = new Set([
     "profiles",
     "profileOrder",
     "profileFallback",
+    "memory",
 ]);
 const ROUTE_KEYS = new Set(["model", "thinking"]);
 const COMMAND_NAME = /^[a-z0-9][a-z0-9._-]*$/u;
@@ -331,7 +332,7 @@ function validateConfig(value) {
         if (!ROOT_KEYS.has(key)) {
             issues.push({
                 path: `$.${displayKey(key)}`,
-                message: `unknown config key "${key}" (allowed: default, commands, onUnavailableRoute, onSettle, pathProtection, advance, recommendedModels, profiles, profileOrder, profileFallback)`,
+                message: `unknown config key "${key}" (allowed: default, commands, onUnavailableRoute, onSettle, pathProtection, advance, recommendedModels, profiles, profileOrder, profileFallback, memory)`,
             });
         }
     }
@@ -401,6 +402,11 @@ function validateConfig(value) {
             config.recommendedModels = value.recommendedModels;
         }
     }
+    if (value.memory !== undefined) {
+        const memory = checkMemory(value.memory, "$.memory", issues);
+        if (memory)
+            config.memory = memory;
+    }
     if (value.profiles !== undefined) {
         if (!isRecord(value.profiles)) {
             issues.push({ path: "$.profiles", message: "must be an object mapping profile names to profile definitions" });
@@ -436,6 +442,30 @@ function validateConfig(value) {
  * the loader can treat "nothing declared" like "nothing present" without a
  * second read.
  */
+/** Strict validator for the `memory` consent block (feature 66, AC3). */
+function checkMemory(value, path, issues) {
+    if (!isRecord(value)) {
+        issues.push({ path, message: `must be a JSON object, got ${describe(value)}` });
+        return undefined;
+    }
+    let unknown = false;
+    for (const key of Object.keys(value)) {
+        if (key !== "engram") {
+            unknown = true;
+            issues.push({ path: `${path}.${displayKey(key)}`, message: `unknown memory key "${key}" (allowed: engram)` });
+        }
+    }
+    const out = {};
+    if (value.engram !== undefined) {
+        if (typeof value.engram !== "boolean") {
+            issues.push({ path: `${path}.engram`, message: `must be a boolean, got ${describe(value.engram)}` });
+        }
+        else {
+            out.engram = value.engram;
+        }
+    }
+    return unknown ? undefined : out;
+}
 export function parseConfigFile(text) {
     if (text.trim() === "")
         return { ok: true, config: {} };

package/dist/config/types.d.ts

@@ -75,6 +75,9 @@ export interface ConfigFile {
     /** When true (default), the built-in provider profiles are included in the
      *  resolution chain (feature 63, AC1). */
     recommendedModels?: boolean;
+    /** Feature 66 (AC3/D3): the memory-substrate consent surface — Engram's MCP
+     *  registration is ask-first, so nothing is provisioned unless this says so. */
+    memory?: MemoryConfigFile;
     /** Named user profiles keyed by profile name (feature 63, AC5). */
     profiles?: Record<string, ProfileFile>;
     /** Ordered list of profile names to probe; empty means ["default"] only
@@ -92,6 +95,16 @@ export type UnavailableRoutePolicy = "stop" | "inherit";
  */
 export type SettlePolicy = "keep" | "restore";
 /** One rejected field inside one config file, addressed by a JSON-path-ish string. */
+/** What an operator WRITES under `memory` (feature 66). */
+export interface MemoryConfigFile {
+    /** Opt in to the package registering the Engram MCP server when its binary
+     *  resolves. Absent or `false` registers nothing. */
+    engram?: boolean;
+}
+/** What the extension READS: every `memory` knob resolved (feature 66). */
+export interface MemoryConfig {
+    engram: boolean;
+}
 export interface ConfigIssue {
     path: string;
     message: string;
@@ -118,6 +131,8 @@ export interface EffectiveConfig {
     profileOrder: string[];
     /** The effective profile-fallback demotion policy (feature 63). */
     profileFallback: ProfileFallbackConfig;
+    /** Feature 66: the memory-substrate consent surface. */
+    memory: MemoryConfig;
     /** Feature 63: declaredness of the implicit `default` profile. */
     declared: {
         default: RouteDeclaration;

package/dist/extension/engram.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Engram MCP provisioning (feature 66, P4 — AC3, decision D3).
+ *
+ * The memory substrate's registration is **ask-first and reversible**, which is
+ * why it goes through Pi's own consent surface instead of writing a
+ * machine-global `mcp.json` behind the operator's back:
+ *
+ *  - `pi.registerMcpServer(name, config)` is session-scoped and NOT persisted
+ *    (Pi's contract), so the package registers on every session start and nothing
+ *    outlives the session unless the operator asks for it.
+ *  - Registration happens only when the `engram` binary actually resolves — a
+ *    registered-but-broken server would surface as an extension error on every
+ *    session, which is a worse default than not registering.
+ *  - A server the operator already declared in an `mcp.json` Pi reads — the
+ *    user file or, for a trusted project, `<cwd>/.pi/mcp.json` — wins (Pi gives
+ *    it precedence), so the package reports that and does not shadow it.
+ *  - The operator's `memory.engram` config key is the consent switch: absent or
+ *    `false` registers nothing. This module never provisions without it.
+ *
+ * Every outcome is reported verbatim — "exactly what was written" is the rule
+ * the sibling `init-workspace` consent flow already follows, and a
+ * provisioning step the operator cannot read back is one they cannot trust.
+ *
+ * The install route is `pi install npm:gentle-engram@latest`. The CLI's own
+ * setup subcommand is deliberately NOT the documented route: it pins whatever
+ * version it ran with and keeps serving it until it is run again, so an updated
+ * binary can sit unused behind a stale registration.
+ *
+ * Pi-free by construction — the binary lookup, the environment, the "already
+ * declared" names and the register callback are all injected, so every branch
+ * is tested with no Pi session, no PATH and no real binary.
+ */
+/** The name the server is registered under, and what `mcp.json` would declare. */
+export declare const ENGRAM_SERVER_NAME = "engram";
+/** The argv the workflow's runners use (pi's own registration, measured). */
+export declare const ENGRAM_ARGS: readonly ["mcp", "--tools=agent"];
+/** The one documented install route (D3). */
+export declare const ENGRAM_INSTALL_ROUTE = "pi install npm:gentle-engram@latest";
+export type EngramStatus = "registered" | "not-consented" | "config-invalid" | "binary-missing" | "already-declared" | "unsupported-host";
+export interface EngramServerConfig {
+    command: string;
+    args: string[];
+}
+export interface EngramProvisionInput {
+    /** The operator's consent: `config.memory.engram`. Absent means no. */
+    consented: boolean;
+    /** True when the package's config file exists but does not parse or validate.
+     *  Consent is then UNKNOWN, not refused: `loadConfig` fails closed to the
+     *  shipped default, so reading `consented` off that default would tell an
+     *  opted-in operator to opt in — `config/load.ts` calls a present-but-invalid
+     *  file a problem, never a silent default, and `dispatch.ts` refuses on the
+     *  same flag. Checked before consent. */
+    configInvalid?: boolean;
+    /** Absolute path of the resolved `engram` binary, or null when not found. */
+    binaryPath: string | null;
+    /** Server names the operator already declared (a `mcp.json` name wins), read
+     *  from every scope Pi itself reads — see `declaredMcpServerPaths`. */
+    declaredNames: readonly string[];
+    /** Pi's registrar, injected so this module never imports Pi. `null` when the
+     *  host's ExtensionAPI predates `registerMcpServer` — the package's peer floor
+     *  is a range, so an older host degrades instead of throwing. */
+    register: ((name: string, config: EngramServerConfig) => void) | null;
+}
+export interface EngramReport {
+    status: EngramStatus;
+    /** Present only when `status === "registered"`: exactly what was written. */
+    server?: {
+        name: string;
+    } & EngramServerConfig;
+    /** One line an operator can read back; states what was written or why not. */
+    message: string;
+}
+/**
+ * The server names an operator already declared in an `mcp.json` file. Pi gives
+ * a declared server precedence over an extension registration, so the caller
+ * passes this in and the module reports rather than shadows. Unreadable or
+ * malformed JSON yields `[]`: a file this module cannot parse is not evidence
+ * of a declaration, and refusing to register on it would be a silent gap.
+ */
+export declare function readDeclaredServerNames(path: string): string[];
+/**
+ * The union of the names declared across the `mcp.json` files Pi reads. One
+ * file's declaration is not evidence about the other's.
+ */
+export declare function readDeclaredServerNamesFrom(paths: readonly string[]): string[];
+/**
+ * The `mcp.json` files Pi reads for one session: the user-level file, and — for
+ * a trusted project only — `<cwd>/.pi/mcp.json`, whose entry replaces a
+ * same-named user entry (Pi's `mcp.md`: project configuration is read only after
+ * trust is granted, and "a project entry replaces a user-level entry with the
+ * same name"). The anti-shadow guard has to consult the same surface the host
+ * applies: reading only the user file let a project declaration slip past it, so
+ * the package registered anyway and then reported precedence over a file it had
+ * never opened.
+ */
+export declare function declaredMcpServerPaths({ agentDir, cwd, projectTrusted, }: {
+    agentDir: string;
+    cwd: string;
+    projectTrusted: boolean;
+}): string[];
+/**
+ * Resolve `engram` on `PATH` without a shell, honouring `PATHEXT` on Windows.
+ * Injected `exists`/`env` keep the lookup testable; the production caller takes
+ * the defaults.
+ */
+export declare function resolveEngramBinary({ env, exists, platform, }?: {
+    env?: Record<string, string | undefined>;
+    exists?: (path: string) => boolean;
+    platform?: NodeJS.Platform;
+}): string | null;
+/**
+ * Decide and perform the registration, in the order that makes the outcome
+ * truthful: a config that cannot be read first (its consent is unknown, never
+ * refused), then consent (never provision unasked), then the binary (never
+ * register a server that cannot start), then the operator's own declaration
+ * (never shadow it). Returns the report; it never throws and never mutates
+ * anything beyond the injected `register` call.
+ */
+export declare function provisionEngram(input: EngramProvisionInput): EngramReport;

package/dist/extension/engram.js

@@ -0,0 +1,187 @@
+/**
+ * Engram MCP provisioning (feature 66, P4 — AC3, decision D3).
+ *
+ * The memory substrate's registration is **ask-first and reversible**, which is
+ * why it goes through Pi's own consent surface instead of writing a
+ * machine-global `mcp.json` behind the operator's back:
+ *
+ *  - `pi.registerMcpServer(name, config)` is session-scoped and NOT persisted
+ *    (Pi's contract), so the package registers on every session start and nothing
+ *    outlives the session unless the operator asks for it.
+ *  - Registration happens only when the `engram` binary actually resolves — a
+ *    registered-but-broken server would surface as an extension error on every
+ *    session, which is a worse default than not registering.
+ *  - A server the operator already declared in an `mcp.json` Pi reads — the
+ *    user file or, for a trusted project, `<cwd>/.pi/mcp.json` — wins (Pi gives
+ *    it precedence), so the package reports that and does not shadow it.
+ *  - The operator's `memory.engram` config key is the consent switch: absent or
+ *    `false` registers nothing. This module never provisions without it.
+ *
+ * Every outcome is reported verbatim — "exactly what was written" is the rule
+ * the sibling `init-workspace` consent flow already follows, and a
+ * provisioning step the operator cannot read back is one they cannot trust.
+ *
+ * The install route is `pi install npm:gentle-engram@latest`. The CLI's own
+ * setup subcommand is deliberately NOT the documented route: it pins whatever
+ * version it ran with and keeps serving it until it is run again, so an updated
+ * binary can sit unused behind a stale registration.
+ *
+ * Pi-free by construction — the binary lookup, the environment, the "already
+ * declared" names and the register callback are all injected, so every branch
+ * is tested with no Pi session, no PATH and no real binary.
+ */
+import { accessSync, constants, readFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
+/** The directory a project keeps its own agent config in — Pi's `.pi/`. */
+const PROJECT_DIR = ".pi";
+/** The name the server is registered under, and what `mcp.json` would declare. */
+export const ENGRAM_SERVER_NAME = "engram";
+/** The argv the workflow's runners use (pi's own registration, measured). */
+export const ENGRAM_ARGS = ["mcp", "--tools=agent"];
+/** The one documented install route (D3). */
+export const ENGRAM_INSTALL_ROUTE = "pi install npm:gentle-engram@latest";
+/**
+ * The server names an operator already declared in an `mcp.json` file. Pi gives
+ * a declared server precedence over an extension registration, so the caller
+ * passes this in and the module reports rather than shadows. Unreadable or
+ * malformed JSON yields `[]`: a file this module cannot parse is not evidence
+ * of a declaration, and refusing to register on it would be a silent gap.
+ */
+export function readDeclaredServerNames(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed !== "object" || parsed === null)
+            return [];
+        const servers = parsed.mcpServers;
+        if (typeof servers !== "object" || servers === null)
+            return [];
+        return Object.keys(servers);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The union of the names declared across the `mcp.json` files Pi reads. One
+ * file's declaration is not evidence about the other's.
+ */
+export function readDeclaredServerNamesFrom(paths) {
+    const names = new Set();
+    for (const path of paths) {
+        for (const name of readDeclaredServerNames(path))
+            names.add(name);
+    }
+    return [...names];
+}
+/**
+ * The `mcp.json` files Pi reads for one session: the user-level file, and — for
+ * a trusted project only — `<cwd>/.pi/mcp.json`, whose entry replaces a
+ * same-named user entry (Pi's `mcp.md`: project configuration is read only after
+ * trust is granted, and "a project entry replaces a user-level entry with the
+ * same name"). The anti-shadow guard has to consult the same surface the host
+ * applies: reading only the user file let a project declaration slip past it, so
+ * the package registered anyway and then reported precedence over a file it had
+ * never opened.
+ */
+export function declaredMcpServerPaths({ agentDir, cwd, projectTrusted, }) {
+    const paths = [join(agentDir, "mcp.json")];
+    if (projectTrusted)
+        paths.push(join(cwd, PROJECT_DIR, "mcp.json"));
+    return paths;
+}
+/**
+ * Resolve `engram` on `PATH` without a shell, honouring `PATHEXT` on Windows.
+ * Injected `exists`/`env` keep the lookup testable; the production caller takes
+ * the defaults.
+ */
+export function resolveEngramBinary({ env = process.env, exists = isExecutable, platform = process.platform, } = {}) {
+    const pathValue = env.PATH ?? env.Path ?? "";
+    if (pathValue === "")
+        return null;
+    const extensions = platform === "win32" ? splitExtensions(env.PATHEXT) : [""];
+    for (const dir of pathValue.split(delimiter)) {
+        if (dir === "")
+            continue;
+        for (const extension of extensions) {
+            const candidate = join(dir, `${ENGRAM_SERVER_NAME}${extension}`);
+            if (exists(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+function splitExtensions(pathext) {
+    const raw = (pathext ?? ".EXE;.CMD;.BAT;.COM").split(";").filter((value) => value !== "");
+    return [...raw, ""];
+}
+function isExecutable(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Decide and perform the registration, in the order that makes the outcome
+ * truthful: a config that cannot be read first (its consent is unknown, never
+ * refused), then consent (never provision unasked), then the binary (never
+ * register a server that cannot start), then the operator's own declaration
+ * (never shadow it). Returns the report; it never throws and never mutates
+ * anything beyond the injected `register` call.
+ */
+export function provisionEngram(input) {
+    const { consented, configInvalid, binaryPath, declaredNames, register } = input;
+    if (configInvalid === true) {
+        return {
+            status: "config-invalid",
+            message: `pi-agentic-workflow: Engram not registered — the package's config file is invalid, so ` +
+                `its consent could not be read and nothing was written (fix the reported problems and ` +
+                `the next session reads the switch again).`,
+        };
+    }
+    if (!consented) {
+        return {
+            status: "not-consented",
+            message: `pi-agentic-workflow: Engram not registered — set "memory": { "engram": true } in ` +
+                `pi-agentic-workflow.json to opt in (nothing was written).`,
+        };
+    }
+    if (binaryPath === null) {
+        return {
+            status: "binary-missing",
+            message: `pi-agentic-workflow: Engram not registered — no "engram" binary on PATH, so ` +
+                `nothing was written. Install it with: ${ENGRAM_INSTALL_ROUTE}`,
+        };
+    }
+    if (register === null) {
+        return {
+            status: "unsupported-host",
+            message: `pi-agentic-workflow: Engram not registered — this Pi host exposes no ` +
+                `registerMcpServer, so the server was not added (nothing was written).`,
+        };
+    }
+    if (declaredNames.includes(ENGRAM_SERVER_NAME)) {
+        return {
+            status: "already-declared",
+            message: `pi-agentic-workflow: Engram not registered — "${ENGRAM_SERVER_NAME}" is already ` +
+                `declared in an mcp.json Pi reads, which takes precedence (nothing was written).`,
+        };
+    }
+    const config = { command: binaryPath, args: [...ENGRAM_ARGS] };
+    register(ENGRAM_SERVER_NAME, config);
+    return {
+        status: "registered",
+        server: { name: ENGRAM_SERVER_NAME, ...config },
+        message: `pi-agentic-workflow: registered MCP server "${ENGRAM_SERVER_NAME}" → ` +
+            `${binaryPath} ${ENGRAM_ARGS.join(" ")} (session-scoped; Pi does not persist it)`,
+    };
+}

package/dist/extension/index.js

@@ -9,6 +9,7 @@ import { readGitStatusBounded } from "./receipt-guard.js";
 import { createPickerComponent, PICKER_MAX_VISIBLE, pagedSelect } from "../settings/picker.js";
 import { createHintStore, createSerenaReadinessStore, stateFilePath } from "../routing/state.js";
 import { createSerenaReadinessGate, readInitWorkspaceRevision } from "../routing/serena-readiness.js";
+import { provisionEngram, readDeclaredServerNamesFrom, resolveEngramBinary, declaredMcpServerPaths } from "./engram.js";
 import { runSettingsConsole } from "../settings/console.js";
 import { readConfigFile, writeConfigFile } from "../settings/store.js";
 import { SETTINGS_COMMAND } from "../routing/types.js";
@@ -172,6 +173,48 @@ function resolveExistingPrefix(target) {
         }
     }
 }
+/**
+ * Pi's MCP registrar, read structurally rather than imported: the package's
+ * peer floor is a range, and a host older than `registerMcpServer` must degrade
+ * (the provisioning module reports `unsupported-host`) instead of throwing at
+ * load.
+ */
+function mcpRegistrar(pi) {
+    const candidate = pi.registerMcpServer;
+    if (typeof candidate !== "function")
+        return null;
+    return (name, config) => {
+        candidate.call(pi, name, config);
+    };
+}
+/**
+ * The server names the operator already has declared — the set the anti-shadow
+ * guard is judged against. Both surfaces are unioned: Pi's own `getMcpServers()`
+ * (read structurally for the same peer-floor reason as the registrar; it is the
+ * merged view the host applies), and the `mcp.json` files Pi reads for this
+ * session, user file and trusted project file alike. Either one answering is
+ * enough to refuse; reading only the user file was the F6 defect, which
+ * registered over a project declaration and then reported precedence over a
+ * file it had never opened.
+ */
+function declaredServerNames(pi, agentDir, ctx) {
+    const names = new Set(readDeclaredServerNamesFrom(declaredMcpServerPaths({ agentDir, cwd: ctx.cwd, projectTrusted: ctx.isProjectTrusted() })));
+    const candidate = pi.getMcpServers;
+    if (typeof candidate === "function") {
+        try {
+            const listed = candidate.call(pi);
+            if (Array.isArray(listed)) {
+                for (const server of listed)
+                    if (typeof server?.name === "string")
+                        names.add(server.name);
+            }
+        }
+        catch {
+            // A host that cannot answer is not a declaration: the file reads stand.
+        }
+    }
+    return [...names];
+}
 export default function extension(pi) {
     const agentDir = getAgentDir();
     const hint = createHintStore({ path: stateFilePath(agentDir) });
@@ -214,13 +257,37 @@ export default function extension(pi) {
             writeFile: writeConfigFile,
         }),
     });
-    // The readiness nudge's first chance (AC9): a session that opens here hears
-    // it, and the gate latches so the command path never repeats it. Soft by
-    // construction — the gate swallows a broken read and a failed latch.
+    // One `session_start` listener carries both first chances, in this order.
+    //
+    // The readiness nudge (AC9) hears the session here, and the gate latches so
+    // the command path never repeats it — soft by construction, because the gate
+    // swallows a broken read and a failed latch.
+    //
+    // Memory substrate (feature 66, AC3) comes second: ask-first,
+    // registrable-not-persisted. Registration runs on the session rather than at
+    // load so an older Pi host is reported instead of throwing, and so the
+    // operator reads back exactly what was written. Nothing is provisioned
+    // without the `memory.engram` opt-in, and a config file that does not parse
+    // is never read as one: its consent is unknown, and the refusal says so
+    // instead of telling an opted-in operator to opt in.
     pi.on("session_start", (_event, ctx) => {
         const message = serenaReadiness.check(ctx.cwd);
         if (message)
             ctx.ui.notify(message, "warning");
+        const projectTrusted = ctx.isProjectTrusted();
+        const loaded = loadConfig({ agentDir, cwd: ctx.cwd, projectTrusted });
+        const report = provisionEngram({
+            consented: loaded.config.memory?.engram === true,
+            configInvalid: !loaded.ok,
+            binaryPath: resolveEngramBinary(),
+            declaredNames: declaredServerNames(pi, agentDir, ctx),
+            register: mcpRegistrar(pi),
+        });
+        // The opt-out stays silent; every other outcome is stated once, in the
+        // module's own words (it already says what was written, or why not).
+        if (report.status !== "not-consented") {
+            ctx.ui.notify(report.message, report.status === "registered" ? "info" : "warning");
+        }
     });
     pi.on("model_select", (event) => router.noteModelSelect(event.model));
     pi.on("thinking_level_select", (event) => router.noteThinkingLevelSelect(event.level));

package/dist/settings/console.js

@@ -650,38 +650,84 @@ function describeRouting(file) {
     ];
     return routes.join(" · ");
 }
+/**
+ * The canonical write order for a config file. `dirty()` compares the cleaned
+ * draft against the cleaned file as JSON text, so the order is part of the
+ * contract: the same keys written in a different order would read as an edit.
+ * Keys outside this list are appended in the draft's own order, so a key the
+ * console never prompts for still survives the save (F4).
+ */
+const KEY_ORDER = [
+    "default",
+    "commands",
+    "onUnavailableRoute",
+    "onSettle",
+    "pathProtection",
+    "advance",
+    "recommendedModels",
+    "memory",
+    "profiles",
+    "profileOrder",
+    "profileFallback",
+];
 /**
  * Keep everything the file held or the operator set; drop only what says nothing
  * (an empty route). Eliding by VALUE — treating an explicit `inherit` or `stop` as
  * absent because a shipped default happens to agree — silently discards the only
  * two moves that matter at project scope: switching a command off under a global
  * route, and re-arming fail-closed over a global `inherit` (F4).
+ *
+ * The copy is driven by the draft's OWN keys, not by a list of the keys this
+ * console edits. Enumerating them silently deleted every valid key the console
+ * never prompts for — `memory` (the Engram consent switch, feature 66 AC3),
+ * `pathProtection` and `advance` — so an opt-in written by hand vanished on the
+ * next save with no message and no error (F4/VF-4). A key the parser accepted is
+ * never a key this function may drop.
  */
 function clean(draft) {
-    const file = {};
-    if (draft.default && Object.keys(draft.default).length > 0)
-        file.default = { ...draft.default };
-    const commands = {};
-    for (const [name, route] of Object.entries(draft.commands ?? {})) {
-        if (Object.keys(route).length > 0)
-            commands[name] = { ...route };
-    }
-    if (Object.keys(commands).length > 0)
-        file.commands = commands;
-    if (draft.onUnavailableRoute)
-        file.onUnavailableRoute = draft.onUnavailableRoute;
-    if (draft.onSettle)
-        file.onSettle = draft.onSettle;
-    if (draft.recommendedModels !== undefined)
-        file.recommendedModels = draft.recommendedModels;
-    if (draft.profiles && Object.keys(draft.profiles).length > 0) {
-        file.profiles = structuredClone(draft.profiles);
+    const kept = {};
+    for (const [key, value] of Object.entries(draft)) {
+        if (value === undefined)
+            continue;
+        if (key === "commands") {
+            const commands = {};
+            for (const [name, route] of Object.entries((value ?? {}))) {
+                if (route && Object.keys(route).length > 0)
+                    commands[name] = { ...route };
+            }
+            if (Object.keys(commands).length > 0)
+                kept.commands = commands;
+            continue;
+        }
+        if (key === "profiles") {
+            const profiles = {};
+            for (const [name, profile] of Object.entries((value ?? {}))) {
+                if (profile && Object.keys(profile).length > 0)
+                    profiles[name] = structuredClone(profile);
+            }
+            if (Object.keys(profiles).length > 0)
+                kept.profiles = profiles;
+            continue;
+        }
+        if (Array.isArray(value)) {
+            // `profileOrder` is the only list at this level: an empty order says
+            // nothing, so it is elided exactly as the empty route was.
+            if (value.length > 0)
+                kept[key] = [...value];
+            continue;
+        }
+        if (typeof value === "object" && value !== null && Object.keys(value).length === 0)
+            continue;
+        kept[key] = typeof value === "object" && value !== null ? structuredClone(value) : value;
     }
-    if (draft.profileOrder && draft.profileOrder.length > 0) {
-        file.profileOrder = [...draft.profileOrder];
+    const file = {};
+    for (const key of KEY_ORDER) {
+        if (key in kept)
+            file[key] = kept[key];
     }
-    if (draft.profileFallback && Object.keys(draft.profileFallback).length > 0) {
-        file.profileFallback = { ...draft.profileFallback };
+    for (const key of Object.keys(kept)) {
+        if (!(key in file))
+            file[key] = kept[key];
     }
     return file;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtrabanco/pi-agentic-workflow",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Pi package: canonical agentic-workflow skills, friendly slash commands, and per-command model routing.",
   "keywords": [
     "pi-package",

package/skills/execute-phase/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: execute-phase
 user-invocable: true
-version: 6.1.0
+version: 6.2.1
 argument-hint: <NN-slug> [P<k>|step] [--max-attempts N] [--force]
 allowed-tools: [Bash, Read, Edit, Write, MultiEdit]
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
@@ -44,6 +44,8 @@ done:
 ✓ Evidence rows updated (command → exit/digest → output → verified-by)
 ✓ Progress log updated with a dated `YYYY-MM-DD HH:MM` entry that names the
   phase id (what, commit, next)
+✓ Memory boundary ran — the phase's outcome saved under `unit/<NN-slug>/doc`,
+  or the mirror marked pending when the layer is degraded
 ✓ Diff guard passed (on implement steps) — see `diff-guard` in PREFLIGHT.md
 ✓ → Next: block printed as the absolute last output
 ```
@@ -136,7 +138,14 @@ names before implementation), then green. UI/adapter glue may test after.
    output (≤2 lines) | verified-by |`. Append to the Evidence section.
 3. **Progress log**: append a dated entry —
    `YYYY-MM-DD HH:MM — <what was done> → <commit sha> — next: <what is next>`.
-4. **Commit**: `git add <changed files>` then `git commit -m "<type>(<scope>):
+4. **Memory boundary** — this step is a phase transition. Follow
+   [the memory protocol](../unit-lane/references/MEMORY.md): before the first
+   memory read run `agentic-workflow memory probe` once and record its verdict
+   in Evidence; after the step, save the phase id, what it changed, its Evidence
+   outcome and any discovery under `topic_key: "unit/<NN-slug>/doc"`, an explicit
+   `project` and explicit session attribution (§5). A `degraded` verdict is
+   recorded and the mirror marked pending — it never blocks the step.
+5. **Commit**: `git add <changed files>` then `git commit -m "<type>(<scope>):
    <step-summary>"` — run it, paste the SHA.
 
 ### 6. Red gate (repair loop)

package/skills/init-workspace/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: init-workspace
 user-invocable: true
-version: 4.1.0
+version: 4.2.0
 argument-hint: <target-dir>
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -78,7 +78,7 @@ Inspect the target dir (`[target-dir]`, default cwd) before touching anything:
 
 ## Progressive loading — bootstrap or upgrade, never both
 
-The reference allowlist is exactly the five linked paths below. Never invent or
+The reference allowlist is exactly the six linked paths below. Never invent or
 read another `references/` path. Step 0 selects exactly one route:
 
 **Hard rule for an existing Claude Code, Cursor, Copilot, or OpenCode
@@ -95,6 +95,10 @@ or portability unless the runtime platform has no named adapter at all.
   only. Its additive-only rule is absolute; do not replay bootstrap.
   The upgrade route loads [SERENA language servers](references/SERENA.md)
   for the additive provisioning step.
+- Provisioning Engram on a host with no pi package: read
+  [Engram provisioning](references/ENGRAM.md) — detect, ask, register or
+  instruct, report. Loaded by the bootstrap write route only (the pi package
+  provisions itself, feature 66).
 - No named adapter exists for the detected runtime platform: add
   [portability](references/PORTABILITY.md) only for that fallback. Claude Code,
   Cursor, Copilot, and OpenCode are named supported adapters; a missing adapter
@@ -133,6 +137,13 @@ loads exactly upgrade and skips bootstrap plus portability.
   auto-detected), a listed server that fails to start must be removed (one
   failure disables every server in the project), and LSP evidence stays
   TypeScript/JavaScript-only. Document verification is a script's job.
+- **Engram provisioning is ask-first, never assumed (feature 66).** Detect the
+  `engram` binary, ask before writing any host MCP config, write the absolute
+  path with the exact `mcp --tools=agent` argv, and report exactly what was
+  written. An existing `engram` declaration is never overwritten, and an absent
+  binary is a recorded residual — the documented install route is
+  `pi install npm:gentle-engram@latest`, never the CLI's own setup subcommand,
+  which keeps serving whatever version ran it until it is re-run.
 - **Retrieval index scaffold and git hooks are consent-gated (AC22).** The
   index surface — the committed `.agentic-workflow/index.json` config plus the
   three freshness hooks (`post-merge`, `post-checkout`, `post-rewrite`, all

package/skills/init-workspace/references/BOOTSTRAP_WRITE.md

@@ -34,7 +34,13 @@
    health check and render the fixed provisioning report. When no installer is
    available, offer only what the machine can perform and record the residual
    with its reason — the run completes either way.
-9. **Install accepted agent safety hooks.** Keep the canonical policy and
+9. **Offer Engram provisioning.** Load [ENGRAM](ENGRAM.md), detect the binary
+   and ask consent: register the `engram` MCP server (absolute path, exact
+   `mcp --tools=agent` argv) when the host has one, leave an existing
+   declaration untouched, and report exactly what was written. An absent binary
+   becomes a residual with the documented install route — never a failed run.
+   Skip this step when the pi package provisions the host itself.
+10. **Install accepted agent safety hooks.** Keep the canonical policy and
    fullauto wrapper at `.agentic-workflow/hooks/`. Seed the shipped
    path-protection policy at `.agentic-workflow/path-policy.json` and its doc
    page at `.agentic-workflow/path-protection.md`, beside the hooks — the
@@ -47,10 +53,10 @@
    an unknown payload, or an existing customized hook file becomes a residual,
    never a silent overwrite. Direct merges remain blocked; do not create a
    `.automerge` exception.
-10. **Offer the workflow skills.** Propose installing them:
+11. **Offer the workflow skills.** Propose installing them:
    `npx skills add gtrabanco/agentic-workflow` (note the SSH/local-path variant if
    the source is private). Don't install without a yes.
-11. **State that reviews are self-contained; offer optional extras.** The
+12. **State that reviews are self-contained; offer optional extras.** The
    workflow ships its **own internal review pack** (`review-code`,
    `review-security`, `review-verify`, `review-debt`, `review-design`,
    `review-a11y`, `review-brand`, `review-perf`, `review-seo`) — it installs
@@ -60,7 +66,7 @@
    under a short "Optional review extras" note so `review-change` and
    `product-audit` run them **in addition** — never as a dependency. Don't
    install anything without a yes.
-12. **Seed the urgency labels (feature 15, injection-safe urgency).** Create the
+13. **Seed the urgency labels (feature 15, injection-safe urgency).** Create the
    two capability-gated GitHub labels `triage-issue` owns and applies
    (`skills/triage-issue/SKILL.md` is the sole owner of the name/color
    vocabulary — this step only seeds it, never redefines it):
@@ -73,7 +79,7 @@
    forge is unavailable or the user declines forge setup, skip this step and
    list the two labels as a residual for the user to create manually later
    (never fail the whole scaffold on it).
-13. **Report.** List what was created, which placeholders still need human input,
+14. **Report.** List what was created, which placeholders still need human input,
    the companion skills recorded/installed, the urgency labels seeded (or
    skipped, with reason), and the next step:
    `discover-repository-state` → `/unit-lane` (or `workflow-status`) → catalog

package/skills/init-workspace/references/ENGRAM.md

@@ -0,0 +1,107 @@
+## Why this step exists
+
+The workflow's units save what they learned into Engram, the cross-session
+memory layer its memory protocol documents. On a host whose agent has no `pi`
+package to provision it (the pi package registers the server itself, feature
+66 P4), the target project has no memory layer at all unless this step offers
+one — so Engram provisioning is a **parity obligation**, not an optional extra:
+feature 66's approval is that the pi path registers it and every other host is
+offered the same thing ask-first.
+
+## What this file owns
+
+The **non-pi** half of Engram provisioning. It owns exactly four moves —
+detect, ask, provision-or-instruct, report — and nothing else. The workflow-side
+protocol (when units save, the recall order, the degraded path) is **not** here;
+it lives in `unit-lane`'s memory reference, which the skills that run units
+already load.
+
+## 1. Detect
+
+Look for the `engram` binary on `PATH` (`command -v engram`) and read its
+version (`engram --version`). Two outcomes matter:
+
+- **Present** — record the resolved path and the version fingerprint.
+- **Absent** — record it as a residual, and go to step 2 with the install
+  guidance below rather than silently skipping the step.
+
+Never write an MCP registration file for a binary that does not resolve: a
+registered-but-unstartable server fails every session after it, which is a worse
+default than an honest gap.
+
+## 2. Ask, then do exactly what was agreed
+
+This is a **consent-gated install** like every other in this skill. Ask one
+question — "register Engram as the project's memory layer?" — and act on the
+answer:
+
+| Answer | What you do |
+|---|---|
+| yes | write the MCP registration named in step 3 and report it verbatim |
+| no | write nothing, record it as a residual, finish the run normally |
+| not installed | offer the install route below, and provision **only** if the user then says yes |
+
+**The install route is `pi install npm:gentle-engram@latest`.** The CLI's own
+setup subcommand is **not** the documented route and must never be printed as an
+instruction: it pins whatever version ran it and keeps serving that version
+until it is re-run, so an updated binary can sit unused behind a stale
+registration (decision D3, 2026-10-21).
+
+## 3. What "register" means on a non-pi host
+
+There is no `pi.registerMcpServer` here, so the registration is a **declared
+file** the host agent reads. Write the server into that host's own MCP config
+(the agent's documented MCP surface), never into a file the host does not read:
+
+```json
+{
+  "mcpServers": {
+    "engram": { "command": "<absolute path to engram>", "args": ["mcp", "--tools=agent"] }
+  }
+}
+```
+
+**Rules:**
+
+- **Absolute path, never a bare name** — the host's `PATH` at load time is not
+  the shell's.
+- **Args are exactly** `mcp` `--tools=agent`. A different argv changes which
+  tools the server exposes.
+- **Never overwrite a server the user already declared** under the name
+  `engram` — a declared server wins over anything this step would add. Report
+  that you found it and left it alone.
+- **Additive and idempotent** — a second run with the same content writes
+  nothing and says so.
+
+## 4. Report exactly what was written
+
+Every outcome ends in a report the user can read back:
+
+- **Registered** — the file path, the server name, and the exact `command` +
+  `args` written.
+- **Declined** — that nothing was written, and that the run continued.
+- **Binary missing** — that nothing was written, the install route verbatim, and
+  that it is recorded as a residual.
+- **Already declared** — the file that already carries it, and that it was left
+  untouched.
+
+"Report exactly what was written" is the same contract the Serena step follows;
+a provisioning step the user cannot read back is one they cannot trust.
+
+## Checklist (pass only if)
+
+- [ ] `engram` presence **and** version were detected (or absence recorded)
+- [ ] Consent was asked before any file was written — never assumed
+- [ ] The written server uses the absolute binary path and the exact argv
+- [ ] An existing `engram` declaration was left untouched and reported
+- [ ] A second run is a no-op
+- [ ] The closing report states what was written — or that nothing was
+
+## Forbidden
+
+- Never print the CLI's own setup subcommand as the install route
+- Never write an MCP config for an unresolved binary
+- Never overwrite an operator's existing `engram` declaration
+- Never let a memory gap fail the run — record it as a residual and continue
+- Never restate the unit-boundary save/recall protocol here; that is the lane's
+  memory reference

package/skills/log-session/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: log-session
 user-invocable: true
-version: 2.2.1
+version: 2.3.0
 argument-hint: "[note to prepend to the entry]"
 author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
 license: MIT
@@ -124,6 +124,22 @@ the HEAD sha and start time at session open.
    open a PR just for a log entry, and never `git add -A` here — a concurrent
    conversation's work must not be swept into a log commit.
 
+## The canonical split — this skill's half (feature 66, D2)
+
+Two writers exist on purpose; neither mirrors the other:
+
+- **`docs/LOGS.md` (this skill)** is the **human/team journal** — what a session
+  set out to do, what it decided, where to resume. It travels with git, so a
+  teammate or a fresh clone reads it with no local state.
+- **Engram (`mem_session_summary`, and the lane's `unit/<NN-slug>/doc` topic)**
+  is **local decision and gotcha recall keyed by unit id**, written by
+  `unit-lane` and `execute-phase` at unit boundaries. It stays on the machine.
+
+Engram never mirrors this log, and this log never mirrors Engram: team memory
+travels with git, agent recall stays local. Write the journal half here; the
+protocol half (boundaries, recall order, degradation) lives in the lane's
+memory reference, `../unit-lane/references/MEMORY.md`.
+
 ## Guardrails
 
 - **Never use an expensive model for this.** It's summarization; `qwen3.6`

package/skills/unit-lane/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: unit-lane
 user-invocable: true
-version: 2.3.0
+version: 2.4.1
 argument-hint: <NN-slug | "<idea>"> [--retriage] | --fix <issue-number> | --from-issue <issue-number>
 description: >
   One-shot lane conductor for a delivery unit: triage, implement, evidence, and
@@ -39,6 +39,8 @@ done:
   on BREACH: re-triage or record exception, never shrink the diff
 ✓ Unit doc's Evidence rows updated (command → exit/digest → output → verified-by)
   and Progress log updated (dated entry) before every commit
+✓ Memory boundaries ran — probe verdict once, saves at unit start / each phase
+  transition / close under `unit/<NN-slug>/doc`, degradation recorded as pending
 ✓ → Next: block printed as the absolute last output
 ```
 
@@ -167,6 +169,20 @@ Before every commit:
 - **Progress log**: `YYYY-MM-DD HH:MM — <what was done> → <commit sha> — next:
   <what is next>`
 
+### 5b. Memory boundaries
+
+Engram is the required memory substrate; a down layer never blocks a unit —
+follow [the memory protocol](references/MEMORY.md).
+
+- **Probe once**, before the first memory read: `agentic-workflow memory probe`
+  → paste the verdict into Evidence; `degraded` is recorded and said once.
+- **Save at unit start, each phase transition, and close** under
+  `topic_key: "unit/<NN-slug>/doc"`, with explicit `project` and explicit
+  session attribution (§5 names what carries it on each write surface).
+- **Recall** `mem_context` → scoped search → one explicit `all_projects: true`
+  retry → `mem_get_observation` → the unit doc wins. A miss is keyword-bound,
+  never proof nothing was saved; an unavailable mirror is marked pending.
+
 ### 6. Close the unit — the close-out ladder
 
 When all triaged steps are done, in order:

package/skills/unit-lane/references/MEMORY.md

@@ -0,0 +1,179 @@
+# Memory protocol — save and recall at unit boundaries
+
+Engram is this workflow's required cross-session memory substrate (owner
+decision 2026-09-24, feature 66). **Required substrate is not a hard
+dependency:** the committed docs stay authoritative, and a memory layer that is
+down is reported once and recorded — it never blocks a unit.
+
+This file is the protocol's single home. `execute-phase` and `log-session` carry
+a thin instruction plus a pointer here; they never restate it.
+
+## 1. Probe before the first memory read
+
+Run the bounded health probe once per session, before the first read:
+
+```sh
+agentic-workflow memory probe        # human block
+agentic-workflow memory probe --json # memory-probe@1 verdict
+```
+
+It is bounded (4 s / 10 s per check, 30 s ceiling), writes nothing, issues no
+MCP tool call, and **always exits 0**. Paste its verdict into the unit doc's
+Evidence section — one row, `verified-by` naming the session:
+
+- `ok` → memory is trustworthy for this session.
+- `degraded` → say **once** which checks failed, record the verdict, and keep
+  working. Never re-probe in a loop, never ask the user to fix it first.
+
+A `degraded` verdict is an answer, not a blocker: the degraded path in §7 is the
+documented response.
+
+## 2. Boundary saves — what, when, and under which key
+
+Save at **three boundaries**, always under a stable per-unit topic key:
+
+| Boundary | topic_key | Payload |
+|---|---|---|
+| unit start (after triage) | `unit/<NN-slug>/doc` | goal, the numbered acceptance criteria verbatim, the triaged step list |
+| each phase transition | `unit/<NN-slug>/doc` | the phase id, what it changed, its Evidence outcome, new discoveries |
+| unit close | `unit/<NN-slug>/doc` | final Evidence outcomes, decisions taken, the gotchas worth recalling |
+
+One payload, four parts — the same four a later session needs to resume without
+re-reading the docs:
+
+```text
+memory-payload@1
+goal:    <one line — the unit's objective>
+ac:      1. <numbered AC verbatim, one per line>
+evidence: <phase> <command> → <exit/digest> → <outcome>
+learned: <gotcha, edge case, or decision a fresh session would get wrong>
+```
+
+Call `mem_save` with `topic_key: "unit/<NN-slug>/doc"` and an explicit
+`project`; on a write surface that exposes `session_id`, pass it too (§5). Later
+boundaries reuse the same `topic_key` so the record **upserts** instead of
+fragmenting into one row per phase.
+
+**What is saved is a summary for recall, never the artifact.** The unit doc, its
+Evidence rows and `docs/LOGS.md` stay authoritative; a memory record that
+disagrees with them is wrong by definition.
+
+## 3. Recall — the fixed order
+
+Resume in this order, and stop as soon as the unit is reconstructable:
+
+1. **`mem_context`** — scoped explicitly (`project: "<name>"`, and `scope` when
+   you mean one).
+2. **`mem_search`** — a scoped search with an **explicit `project`**. Never rely
+   on an omitted selector for a global read; a default is not a decision.
+3. **One retry** — if the project-scoped search misses, retry **once** with
+   **`all_projects: true`** passed explicitly. A second miss is a miss.
+4. **`mem_get_observation`** — fetch the full untruncated body of the hit that
+   matters.
+5. **Read the unit doc** and reconcile: the file wins on every conflict, and the
+   difference is worth recording as a discovery (§2 `learned:`).
+
+Only when `mem_context` and both searches miss does a fresh session fall back to
+reading the docs cold — and that fallback is recorded, because it means the
+recall path failed, not that nothing was ever saved.
+
+When the cwd is ambiguous (several repos under it), call **`mem_current_project`**
+and navigate by its `available_projects`: pick the matching project explicitly
+rather than letting an ambiguous cwd decide. An ambiguous answer is never
+resolved by guessing.
+
+## 4. Keyword-bound recall — the disclosed ceiling
+
+Engram's recall is **keyword-bound** (FTS5 over stored text, no vectors). Two
+consequences are obligations, not trivia:
+
+- **A miss is not evidence that knowledge was never saved.** It means the query
+  did not hit the stored terms. Rephrase with the unit's own vocabulary (slug,
+  AC wording, file paths) before concluding anything is absent.
+- **What you save must be searchable later.** Save the words a future session
+  will search for — the unit slug, the phase id, the failing command, the file
+  path — not a paraphrase.
+
+Hybrid FTS5+vector recall is Engram's own direction (#192), never built here.
+
+## 5. Session attribution — explicit on every write, on the surface that carries it
+
+Every write must be **attributed to one known session**, never to whichever
+session a machine happens to resolve. On a box with several active runtime
+sessions an unresolved attribution fails closed and the write is lost — the one
+outcome this protocol exists to prevent (the health probe's
+`session-ambiguity` check reads exactly this signal, §1).
+
+Which parameter carries that attribution depends on the surface in front of you:
+
+| Write surface | How the session is carried | What you do |
+|---|---|---|
+| Engram's own MCP server (`engram mcp --tools=agent`) | its `mem_save`, `mem_save_prompt`, `mem_session_summary` and `mem_capture_passive` take a `session_id` argument | open the session (`mem_session_start`) and pass that id on **every** write |
+| a host whose memory tools expose no `session_id` (Pi's Engram provider binds the runtime session itself) | the provider stamps the session from the live runtime session and **refuses** when that identity is ambiguous or disagrees with the project | never write before the session is open, always pass an explicit `project` (and `cwd` when the directory could match more than one project), and treat an attribution refusal as a failed write — record it (§7), do not retry blind |
+
+On both surfaces the obligation is the same and the check is the same: **a write
+that cannot say which session it belongs to is a write that did not happen**.
+
+- `mem_session_start` opens the id (or the runtime session the provider binds to)
+  at unit start; the boundaries in §2 reuse it, and nothing is written before it.
+- **`mem_session_end` runs only on confirmed-stale ids** — ids you opened yourself
+  and know are finished. Never end an id a live session may still hold.
+- When `mem_session_summary` cannot resolve the project, the explicit
+  **project fallback** is the documented escape hatch: pass `project` by name
+  and the summary lands instead of being refused. Record the fallback when you
+  use it.
+- Passing a `session_id` to a tool that does not declare it is not "explicit
+  attribution", it is an invalid call. Read the tool's own parameter list when
+  the host offers more than one memory surface, and record which surface you used.
+
+## 6. The canonical split (D2)
+
+Both writers exist on purpose; neither mirrors the other.
+
+| Writer | Owns | Travels |
+|---|---|---|
+| `docs/LOGS.md` (`log-session`) | the human/team journal: what happened, for people | with git |
+| `mem_session_summary` / `unit/<NN-slug>/doc` | local decision and gotcha recall keyed by unit id | local only |
+
+Team memory travels with git; agent recall stays local. A double-write on
+purpose, recorded here so it is never mistaken for an accident.
+
+## 7. Degradation — recorded, never silent
+
+When the probe says `degraded` or a write fails:
+
+- **Local progress is preserved.** The unit doc, Evidence rows and commit are
+  the record; they never depend on memory.
+- **The mirror is marked pending explicitly** — one line in the Progress entry
+  or Evidence row saying the memory write is pending, so a later session knows
+  the gap exists and is not a "nothing was saved" conclusion.
+- **Unrelated safe work continues.** Never stop a unit for a mirror failure.
+- **Sync resumes when the layer answers** — retry the pending write at the next
+  boundary, not in a loop.
+- **Read both sides back.** After a write, read the file and the mirror; when
+  the versions are irreconcilable, keep both and surface the difference rather
+  than silently picking one.
+
+## Checklist (pass only if)
+
+- [ ] The probe ran once and its verdict is in Evidence (§1)
+- [ ] A save happened at unit start, at each phase transition, and at close (§2)
+- [ ] Every save was explicitly attributed: a `session_id` on a surface that
+  accepts one, otherwise an open session plus an explicit `project` — and it
+  named the unit's `topic_key` (§2, §5)
+- [ ] Recall followed the fixed order, with an explicit `project` and at most
+  one explicit `all_projects: true` retry (§3)
+- [ ] Any miss was treated as keyword-bound, not as absence (§4)
+- [ ] Any degradation was recorded as pending — never silent (§7)
+
+## Forbidden
+
+- Never let a memory verdict block a unit, or re-probe in a loop
+- Never rely on an omitted selector for a global read
+- Never write with unresolved session attribution — pass the `session_id` where
+  the surface takes one, and where it does not, never write before the session is
+  open (§5)
+- Never call `mem_session_end` on an id you did not open or cannot confirm stale
+- Never mirror `docs/LOGS.md` verbatim — the split is deliberate (§6)
+- Never treat a recall miss as proof nothing was saved
+- Never let a memory record override the committed artifact