fix(pi): add session summary project fallback

Author: Alan-TheGentleman

CHANGELOG.md

@@ -9,6 +9,7 @@ This project follows [Conventional Commits](https://www.conventionalcommits.org/
 Full release notes with changelogs per version live on the **[GitHub Releases page](https://github.com/Gentleman-Programming/engram/releases)**.
 
 GoReleaser generates them automatically from commits, filtering by type:
+
 - `feat:` / `fix:` / `refactor:` / `chore:` commits appear in the release notes
 - `docs:` / `test:` / `ci:` commits are excluded from the generated changelog
 
@@ -22,6 +23,8 @@ Breaking changes are always marked with a `type:breaking-change` label and docum
 
 ### Pi package (`pi-engram`)
 
+- **fix(plugin):** allow `mem_session_summary` to accept an explicit `project` fallback when automatic project detection is unavailable.
+- **fix(plugin):** fall back to local `.engram/config.json` and surface a clearer version-mismatch diagnostic when the running Engram server lacks `/project/current`.
 - **feat(plugin):** add `gentle-engram` package for Pi marketplace installs, with HTTP event capture, Memory Protocol prompt injection, safe `engram mcp` launcher config, and `pi-engram init` setup helper.
 
 ### Cloud dashboard visual parity (`cloud-dashboard-visual-parity`)
@@ -63,6 +66,7 @@ The `project` argument has been removed from the JSON schemas of 7 MCP write too
 **After:** the project is auto-detected from the server's working directory (cwd). Any `project` argument sent by the LLM is silently discarded.
 
 **Migration:**
+
 - Remove `project` from write tool calls in your agent's memory protocol.
 - Use `mem_current_project` (new tool) to inspect which project Engram will use before writing.
 - If the cwd is ambiguous (multiple git repos), Engram returns a structured error with `available_projects`. Navigate to one of the repos before writing.

docs/AGENT-SETUP.md

@@ -35,12 +35,12 @@ Install Engram's Pi package, the MCP adapter, and Pi MCP config:
 engram setup pi
 ```
 
-`engram setup pi` runs `pi install npm:gentle-engram@0.1.5` and `pi install npm:pi-mcp-adapter`, then ensures Pi settings contain both packages and writes `mcpServers.engram` in the Pi agent MCP config when no Engram server is already configured. Existing `mcpServers.engram` entries are preserved.
+`engram setup pi` runs `pi install npm:gentle-engram@0.1.7` and `pi install npm:pi-mcp-adapter`, then ensures Pi settings contain both packages and writes `mcpServers.engram` in the Pi agent MCP config when no Engram server is already configured. Existing `mcpServers.engram` entries are preserved.
 
 Manual equivalent:
 
 ```bash
-pi install npm:gentle-engram@0.1.5
+pi install npm:gentle-engram@0.1.7
 pi install npm:pi-mcp-adapter
 pi-engram init
 ```

internal/setup/setup.go

@@ -77,7 +77,7 @@ const claudeCodeMarketplace = "Gentleman-Programming/engram"
 
 const openCodeSubagentStatuslinePlugin = "opencode-subagent-statusline"
 
-const piGentleEngramPackage = "npm:gentle-engram@0.1.5"
+const piGentleEngramPackage = "npm:gentle-engram@0.1.7"
 const piMCPAdapterPackage = "npm:pi-mcp-adapter"
 
 // claudeCodeMCPTools are the MCP tool permission names for the agent profile

internal/setup/setup_test.go

@@ -315,7 +315,7 @@ func TestInstallPiInstallsPackagesAndWritesConfig(t *testing.T) {
 	if result.Agent != "pi" || result.Destination != agentDir || result.Files != 2 {
 		t.Fatalf("unexpected install result: %#v", result)
 	}
-	wantCommands := []string{"pi install npm:gentle-engram@0.1.5", "pi install npm:pi-mcp-adapter"}
+	wantCommands := []string{"pi install npm:gentle-engram@0.1.7", "pi install npm:pi-mcp-adapter"}
 	if !reflect.DeepEqual(commands, wantCommands) {
 		t.Fatalf("unexpected pi install commands: got %#v want %#v", commands, wantCommands)
 	}
@@ -330,7 +330,7 @@ func TestInstallPiInstallsPackagesAndWritesConfig(t *testing.T) {
 	if err := json.Unmarshal(settingsRaw, &settings); err != nil {
 		t.Fatalf("parse settings: %v", err)
 	}
-	for _, pkg := range []string{"npm:gentle-engram@0.1.5", "npm:pi-mcp-adapter"} {
+	for _, pkg := range []string{"npm:gentle-engram@0.1.7", "npm:pi-mcp-adapter"} {
 		if !slices.Contains(settings.Packages, pkg) {
 			t.Fatalf("expected settings packages to include %q, got %#v", pkg, settings.Packages)
 		}
@@ -398,7 +398,7 @@ func TestInstallPiPreservesExistingEngramMCPServer(t *testing.T) {
 	if err != nil {
 		t.Fatalf("read settings after install: %v", err)
 	}
-	if !strings.Contains(string(settingsRaw), "npm:existing") || !strings.Contains(string(settingsRaw), "npm:gentle-engram@0.1.5") || !strings.Contains(string(settingsRaw), "npm:pi-mcp-adapter") {
+	if !strings.Contains(string(settingsRaw), "npm:existing") || !strings.Contains(string(settingsRaw), "npm:gentle-engram@0.1.7") || !strings.Contains(string(settingsRaw), "npm:pi-mcp-adapter") {
 		t.Fatalf("expected settings packages to be preserved and extended, got %s", settingsRaw)
 	}
 }
@@ -409,7 +409,7 @@ func TestInstallPiCommandFailure(t *testing.T) {
 		return []byte("boom"), errors.New("exit 1")
 	}
 	_, err := Install("pi")
-	if err == nil || !strings.Contains(err.Error(), "install npm:gentle-engram@0.1.5") {
+	if err == nil || !strings.Contains(err.Error(), "install npm:gentle-engram@0.1.7") {
 		t.Fatalf("expected pi install error, got %v", err)
 	}
 }

plugin/pi/README.md

@@ -78,7 +78,7 @@ Engram includes a terminal UI for browsing sessions, observations, prompts, proj
 ## Quick start
 
 ```bash
-pi install npm:gentle-engram@0.1.5
+pi install npm:gentle-engram@0.1.7
 pi install npm:pi-mcp-adapter
 pi-engram init
 ```
@@ -189,7 +189,7 @@ If the binary is missing, Pi keeps running and memory degrades instead of crashi
 
 `pi-engram init` writes Pi-owned config in the Pi agent directory:
 
-- `settings.json`: ensures `npm:pi-mcp-adapter` and `npm:gentle-engram@0.1.5` are declared.
+- `settings.json`: ensures `npm:pi-mcp-adapter` and `npm:gentle-engram@0.1.7` are declared.
 - `mcp.json`: adds an `engram` MCP server that launches `engram mcp --tools=agent` through a safe Node wrapper with `directTools: false`, so MCP remains available through the gateway without duplicating Pi-native `mem_*` tools.
 
 Existing `mcpServers.engram` entries are preserved unless you pass `--force`:
@@ -210,7 +210,7 @@ The HTTP event-capture path mirrors Engram's normal project detection order as c
 4. single child git repo name
 5. current directory basename
 
-MCP tool calls still use Engram core's canonical project resolver at call time. For critical repos or monorepos, prefer an explicit `.engram/config.json`:
+MCP tool calls still use Engram core's canonical project resolver at call time. Pi-native tool calls ask the Engram HTTP server for `/project/current`; if that route is missing on an older running server, the adapter falls back to the nearest local `.engram/config.json` and returns a version-mismatch warning. For critical repos or monorepos, prefer an explicit `.engram/config.json`:
 
 ```json
 {
@@ -220,12 +220,14 @@ MCP tool calls still use Engram core's canonical project resolver at call time.
 
 ## Troubleshooting
 
-| Symptom                                   | Fix                                                              |
-| ----------------------------------------- | ---------------------------------------------------------------- |
-| `mem_*` tools are missing                 | Install `pi-mcp-adapter`, run `pi-engram init`, then restart Pi. |
-| Pi cannot find `engram`                   | Set `ENGRAM_BIN=/absolute/path/to/engram`.                       |
-| Session capture should use another server | Set `ENGRAM_URL=http://host:7437`.                               |
-| Existing MCP config was not replaced      | Run `pi-engram init --force`.                                    |
+| Symptom                                                      | Fix                                                                                                                                                  |
+| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mem_*` tools are missing                                    | Install `pi-mcp-adapter`, run `pi-engram init`, then restart Pi.                                                                                     |
+| Pi cannot find `engram`                                      | Set `ENGRAM_BIN=/absolute/path/to/engram`.                                                                                                           |
+| Session capture should use another server                    | Set `ENGRAM_URL=http://host:7437`.                                                                                                                   |
+| Existing MCP config was not replaced                         | Run `pi-engram init --force`.                                                                                                                        |
+| `mem_current_project` reports `/project/current` unsupported | Restart or upgrade the running `engram serve`; check `ENGRAM_URL`/`ENGRAM_BIN`. If `.engram/config.json` exists, Pi uses it as a temporary fallback. |
+| `mem_session_summary` cannot detect a project                | Ask the user which project should receive the summary, then retry `mem_session_summary` with `project: "name"`.                                      |
 
 ## Next steps
 

plugin/pi/cli.js

@@ -3,7 +3,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
-const PACKAGE_NAME = "npm:gentle-engram@0.1.5";
+const PACKAGE_NAME = "npm:gentle-engram@0.1.7";
 const MCP_ADAPTER_PACKAGE = "npm:pi-mcp-adapter";
 const HELP = `pi-engram
 
@@ -12,7 +12,7 @@ Usage:
 
 Creates Pi's Engram MCP config in the Pi agent dir and ensures pi-mcp-adapter
 is declared in settings.json. The Pi extension itself is loaded by installing
-the package with: pi install npm:gentle-engram@0.1.5
+the package with: pi install npm:gentle-engram@0.1.7
 `;
 
 const MCP_LAUNCHER =

plugin/pi/index.ts

@@ -7,8 +7,8 @@
  */
 
 import { spawn, type ChildProcess } from "node:child_process";
-import { existsSync } from "node:fs";
-import { basename, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
@@ -78,6 +78,8 @@ call \`mem_search\`, then \`mem_get_observation\` for full content.
 
 Before ending a session or saying "done", call \`mem_session_summary\`
 with Goal, Instructions, Discoveries, Accomplished, Next Steps, and Relevant Files.
+If \`mem_session_summary\` fails because Engram cannot detect a project, ask the user
+which project should receive the summary, then retry with \`project: "<name>"\`.
 
 ### AFTER COMPACTION
 
@@ -116,6 +118,9 @@ interface MigrationBody {
 
 interface CurrentProjectResponse {
   project?: string;
+  project_source?: string;
+  project_path?: string;
+  cwd?: string;
   available_projects?: string[] | null;
   warning?: string;
   error_hint?: string;
@@ -186,6 +191,46 @@ async function bestEffortEngramFetch<TResponse = unknown>(path: string, opts: Fe
   }
 }
 
+function detectLocalConfigProject(cwd: string): CurrentProjectResponse | undefined {
+  let current = resolve(cwd || ".");
+  while (true) {
+    const configPath = `${current}/.engram/config.json`;
+    if (existsSync(configPath)) {
+      try {
+        const parsed = JSON.parse(readFileSync(configPath, "utf8")) as { project_name?: unknown };
+        const projectName = typeof parsed.project_name === "string" ? parsed.project_name.trim() : "";
+        if (projectName) {
+          return {
+            project: projectName,
+            project_source: "config",
+            project_path: current,
+            cwd,
+            warning: `Engram server at ${ENGRAM_URL} does not support /project/current; using ${configPath}. Upgrade or restart Engram for canonical project detection.`,
+          };
+        }
+        return {
+          cwd,
+          error_hint: `${configPath} exists but project_name is missing or empty. Fix the config or pass project explicitly.`,
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { cwd, error_hint: `Could not read ${configPath}: ${message}` };
+      }
+    }
+
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+function projectCurrentUnsupportedError(cwd: string): CurrentProjectResponse {
+  return {
+    cwd,
+    error_hint: `Engram server at ${ENGRAM_URL} does not support /project/current. Upgrade or restart the running Engram server, verify ENGRAM_URL/ENGRAM_BIN, or pass project explicitly to project-capable memory tools.`,
+  };
+}
+
 async function ensureSessionBestEffort(sessionId: string, sessionProject = project): Promise<void> {
   try {
     await ensureSession(sessionId, sessionProject);
@@ -273,8 +318,14 @@ async function ensureSession(sessionId: string, sessionProject = project): Promi
 
 async function detectServerProject(cwd: string): Promise<CurrentProjectResponse | undefined> {
   for (let attempt = 0; attempt < 5; attempt += 1) {
-    const detected = await bestEffortEngramFetch<CurrentProjectResponse>(`/project/current${queryString({ cwd })}`);
-    if (detected) return detected;
+    try {
+      const detected = await engramFetch<CurrentProjectResponse>(`/project/current${queryString({ cwd })}`);
+      if (detected) return detected;
+    } catch (error) {
+      if (error instanceof EngramHttpError && error.status === 404) {
+        return detectLocalConfigProject(cwd) || projectCurrentUnsupportedError(cwd);
+      }
+    }
     if (attempt < 4) await wait(200);
   }
   return undefined;
@@ -394,6 +445,7 @@ const MEMORY_TOOL_SCHEMAS: Record<string, ReturnType<typeof Type.Object>> = {
   mem_session_summary: Type.Object({
     content: Type.String({ description: "Full session summary" }),
     session_id: optionalString("Session ID"),
+    project: optionalString("Optional project to use when automatic detection is unavailable"),
   }),
   mem_context: Type.Object({
     project: optionalString("Filter by project"),
@@ -534,16 +586,16 @@ async function callMemoryTool(toolName: string, params: Record<string, unknown>,
         body: { session_id: activeSessionId, content: params.content, project: activeProject },
       });
     case "mem_session_summary":
-      requireResolvedProject();
-      await ensureSession(activeSessionId);
+      if (!requestedProject) requireResolvedProject();
+      await ensureSession(activeSessionId, activeProject);
       return engramFetch("/observations", {
         method: "POST",
         body: {
           session_id: activeSessionId,
           type: "session_summary",
           title: "Session summary",
           content: params.content,
-          project,
+          project: activeProject,
           scope: "project",
         },
       });
@@ -558,8 +610,17 @@ async function callMemoryTool(toolName: string, params: Record<string, unknown>,
         method: "POST",
         body: { summary: params.summary || "" },
       });
-    case "mem_current_project":
-      return engramFetch(`/project/current${queryString({ cwd: params.cwd || ctx.cwd })}`);
+    case "mem_current_project": {
+      const cwd = String(params.cwd || ctx.cwd);
+      try {
+        return await engramFetch(`/project/current${queryString({ cwd })}`);
+      } catch (error) {
+        if (error instanceof EngramHttpError && error.status === 404) {
+          return detectLocalConfigProject(cwd) || projectCurrentUnsupportedError(cwd);
+        }
+        throw error;
+      }
+    }
     case "mem_doctor":
       return engramFetch(`/doctor${queryString({ project: params.project, check: params.check, cwd: params.project ? undefined : ctx.cwd })}`);
     case "mem_capture_passive":

plugin/pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-engram",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Persistent memory for Pi agents — one local-or-cloud brain shared across sessions, compactions, and MCP agents",
   "type": "module",
   "license": "MIT",

plugin/pi/test/index-source.test.mjs

@@ -0,0 +1,17 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+
+const source = readFileSync(new URL("../index.ts", import.meta.url), "utf8");
+
+test("mem_session_summary accepts explicit project fallback", () => {
+  assert.match(source, /mem_session_summary: Type\.Object\(\{[\s\S]*project: optionalString\("Optional project to use when automatic detection is unavailable"\)/);
+  assert.match(source, /case "mem_session_summary":[\s\S]*if \(!requestedProject\) requireResolvedProject\(\);[\s\S]*ensureSession\(activeSessionId, activeProject\)[\s\S]*project: activeProject/);
+});
+
+test("project detection 404 falls back to local config or diagnostic", () => {
+  assert.match(source, /function detectLocalConfigProject\(cwd: string\)/);
+  assert.match(source, /project_name/);
+  assert.match(source, /error\.status === 404[\s\S]*detectLocalConfigProject\(cwd\) \|\| projectCurrentUnsupportedError\(cwd\)/);
+  assert.match(source, /does not support \/project\/current/);
+});