@phren/cli 0.0.55 → 0.0.57

package/README.md

@@ -1,19 +1,22 @@
-<p align="center"><img src="docs/phren-transparent.png" width="180" alt="phren"></p>
+# phren MCP server
 
-<h3 align="center">Your agents forget everything. Phren doesn't.</h3>
+MCP server that indexes your personal phren and exposes it to AI agents via full-text search.
 
-<p align="center">
-  <a href="https://www.npmjs.com/package/@phren/cli"><img src="https://img.shields.io/npm/v/%40phren%2Fcli?style=flat&labelColor=0D0D0D&color=7C3AED" alt="npm version"></a>
-  <a href="https://github.com/alaarab/phren/blob/main/LICENSE"><img src="https://img.shields.io/github/license/alaarab/phren?style=flat&labelColor=0D0D0D&color=7C3AED" alt="license"></a>
-  <a href="https://alaarab.github.io/phren/"><img src="https://img.shields.io/badge/docs-alaarab.github.io%2Fphren-7C3AED?style=flat&labelColor=0D0D0D" alt="docs"></a>
-  <a href="https://alaarab.github.io/phren/whitepaper.pdf"><img src="https://img.shields.io/badge/whitepaper-PDF-7C3AED?style=flat&labelColor=0D0D0D" alt="whitepaper"></a>
-</p>
+On startup it walks your phren directory, reads all `.md` files, and builds an in-memory SQLite FTS5 index.
 
-<p align="center">
-Persistent memory for AI agents. Findings, tasks, and patterns live in markdown files in a git repo you control. No database, no vendor lock-in. Works with Claude, Copilot, Cursor, and Codex.
-</p>
+Public surface: 53 MCP tools across 12 modules (search, tasks, findings, memory, data, graph, sessions, ops/review, skills, hooks, config, extraction).
 
----
+Notable shipped capabilities:
+- finding lifecycle tools: `supersede_finding`, `retract_finding`, `resolve_contradiction`, `get_contradictions`
+- finding provenance: `add_finding.source` (`human|agent|hook|extract|consolidation|unknown`)
+- cross-session continuity: task checkpoints + `session_history`
+- finding impact scoring from injected-context outcomes
+- skill registry behavior: scope precedence, alias-collision handling, visibility gating, generated `skill-manifest.json`
+- lifecycle penalties: superseded 0.25×, retracted 0.1×, contradicted 0.4× confidence in retrieval
+- inactive findings stripped from FTS index (superseded/retracted findings cannot appear in search)
+- auto-tagging: findings without type tags are inferred from content at write time
+- session context diff: `session_start` reports new findings since last session
+- decay resistance: confirmed findings decay 3× slower when repeatedly useful
 
 ## Install
 
@@ -21,109 +24,84 @@ Persistent memory for AI agents. Findings, tasks, and patterns live in markdown
 npx @phren/cli init
 ```
 
-One command. Sets up `~/.phren`, wires up MCP for your tools, installs hooks. Next time you open a project, context starts flowing automatically. On a new machine? Re-run init and you're back in sync.
+This sets up phren without needing `sudo` or a global install. On Windows, use `npm install -g @phren/cli` if `npx` isn't available.
 
----
+Or add manually to Claude Code:
 
-## What actually happens
-
-**When you open a prompt:**
-- Hooks extract keywords from your question
-- Phren searches findings across projects (FTS5 full-text with semantic fallback)
-- Relevant snippets inject into your prompt before you hit send
-- You ask; Claude already knows the gotchas
-
-**When you discover something:**
-- `phren add-finding <project> "finding text"` captures it with optional tags (`[decision]`, `[pattern]`, `[pitfall]`, `[bug]`)
-- Trust scores decay over time; decisions never do; observations expire in 14 days
-- Findings link to fragments (named concepts like "auth" or "build") that connect knowledge across projects
+```bash
+claude mcp add phren -- phren ~/.phren
+```
 
-**Sessions:**
-- Mark boundaries with `session_start` / `session_end`
-- Next session sees your prior summary, active tasks, recent findings, and where you left off
-- Checkpoints track edited files and failing tests so you can resume exactly where you stopped
+## Environment variables
 
-**Tasks:**
-- Add with priority/section. Pin across sessions. Link to GitHub issues.
-- Track completions and cross-project rollups.
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PHREN_PATH` | `~/.phren` | Path to your phren instance |
+| `PHREN_PROFILE` | *(none)* | Active profile name. When unset, phren uses `machines.yaml` when available and otherwise falls back to an unscoped view |
+| `PHREN_ACTOR` | OS user / env | Actor identity used in governance/audit RBAC checks |
 
----
+## Tools
 
-## Key features
+See [docs/api-reference.md](../docs/api-reference.md) for the full API reference.
 
-### Fragment graph
-Explore connections visually. Drag nodes to reorganize; graph auto-settles. Click a fragment to see every finding linked to it across all projects.
+## Integration model
 
-### Finding lifecycle
-- **Supersede**: "Finding X is obsoleted by finding Y"
-- **Retract**: "We were wrong about this; here's why"
-- **Contradict**: "We have two findings that conflict; this is why"
+- Claude: full native lifecycle hooks (`SessionStart`, `UserPromptSubmit`, `Stop`, `PostToolUse`) + MCP
+- Copilot CLI / Cursor / Codex: MCP + generated hook config + session wrapper binaries
 
-Helps you reason about contradictions instead of hiding them.
+## Governance and security highlights
 
-### Multi-agent support
-Same store works with Claude Code, Copilot, Cursor, and Codex. Agents tag findings with their tool, so you see who discovered what.
+- RBAC uses `.config/access-control.json` and `.runtime/access-control.local.json`
+- Web UI binds loopback-only, uses per-run auth token, enforces CSRF for mutations, and sets CSP headers
+- Telemetry is opt-in only (`phren config telemetry on`) and stored locally in `.runtime/telemetry.json`
 
-### Review queue
-Mark findings as needing review (`[Review]` section). Phren surfaces review items on every session start. Approve, reject, or edit in place.
+### search_knowledge
 
-### Governance & policies
-Per-project retention policies. Confidence decay curves. Access control. Audit logs. Configure with `phren config` or the web UI.
+Full-text search across all indexed markdown files with synonym expansion.
 
-### Store subscriptions
-Subscribe to specific projects in a team store — others stay hidden from search and context injection:
-```bash
-phren store subscribe team-store arc intranet
-phren store unsubscribe team-store legacy-projects
 ```
-
-### Progressive disclosure
-Enable `PHREN_FEATURE_PROGRESSIVE_DISCLOSURE=1` to get compact memory indices instead of full snippets. Call `get_memory_detail(id)` to expand only what you need.
-
-### Semantic dedup & conflict detection
-Optional: enable LLM-based duplicate detection and contradiction flagging on `add_finding`. Prevents near-duplicate entries and catches "always use X" vs "never use X" contradictions.
-
-### Skills & hooks
-Drop custom slash commands into `~/.phren/global/skills/`. Hooks run on user prompt, tool use, and session events — wire phren into your own workflows.
-
----
-
-## CLI quick reference
-
-```bash
-phren                                   Interactive shell (explore/search)
-phren search <query>                    Full-text search with FTS5
-phren add-finding <project> "insight"   Capture a finding
-phren task add <project> "item"         Add a task
-phren session_start <project>           Start a session
-phren store list                        List personal + team stores
-phren team init <name> --remote <url>   Create a team store
-phren team join <url>                   Join a team store
-phren web-ui [--port 3499]              Launch the web UI
-phren doctor                            Health check & auto-fix
+query: string              - FTS5 query (supports AND, OR, NOT, "phrase matching")
+limit?: number             - Max results, 1-20, default 5
+type?: string              - Filter: "claude", "findings", "reference", "summary", "task", "skill"
+project?: string           - Filter to a specific project
+tag?: string               - Filter findings by type tag: decision, pitfall, pattern, tradeoff, architecture, bug
+since?: string             - Filter findings by date: "7d", "30d", "YYYY-MM", "YYYY-MM-DD"
+status?: string            - Filter by lifecycle status: active, superseded, contradicted, stale, invalid_citation, retracted
+include_history?: boolean  - Include superseded/retracted findings (default false)
+synthesize?: boolean       - Generate a synthesis paragraph from top results using an LLM
 ```
 
-See full CLI docs at [alaarab.github.io/phren](https://alaarab.github.io/phren/).
+### get_project_summary
 
----
+Returns a project's summary.md content, path to its CLAUDE.md, and a list of indexed files.
 
-## Team stores
+```
+name: string      - Project name (e.g. "my-app", "backend")
+```
 
-Shared knowledge repos for teams. One person creates with `phren team init`, others join with `phren team join`. Findings, tasks, and skills sync across team members.
+### list_projects
 
-Each team store can be configured with per-project subscriptions so people only see what they care about.
+Lists all projects in the active profile with a brief description and which docs exist.
 
----
+No parameters.
 
-## Platforms
+## How it works
 
-- **Claude Code** (VS Code, Web, Desktop) — MCP hooks + CLI
-- **Copilot** (VS Code, GitHub.com) — MCP hooks
-- **Cursor** (IDE) — MCP hooks + built-in skill system
-- **Codex** (Claude Agent SDK) — MCP tools + hooks
+1. Reads `PHREN_PATH` (or defaults to `~/.phren`)
+2. Resolves the active profile from `PHREN_PROFILE`, or from `machines.yaml` when the env var is unset
+3. If no active profile can be resolved yet, falls back to an unscoped view of top-level project directories
+4. Walks each project directory, reads `.md` files, classifies them by filename
+5. Builds an in-memory SQLite FTS5 index with Porter stemming
+6. Serves tools over stdio using the MCP protocol
 
-All use the same phren store. No vendor lock-in.
+File types are derived from filenames: `CLAUDE.md` -> "claude", `summary.md` -> "summary", `FINDINGS.md` -> "findings", `tasks.md` -> "task", files under `reference/` -> "reference", files under `skills/` -> "skill".
 
----
+## Development
 
-MIT License. Made by [Ala Arab](https://github.com/alaarab).
+```bash
+cd ~/phren
+npm install
+npm run build    # Compile TypeScript
+npm run dev      # Run with tsx (hot reload)
+npm test         # Run all tests
+```

package/{mcp/dist → dist}/cli/cli.js

@@ -118,6 +118,16 @@ export async function runCliCommand(command, args) {
             return handleTeamNamespace(args);
         case "promote":
             return handlePromoteNamespace(args);
+        case "agent": {
+            try {
+                const { runAgentCli } = await import("@phren/agent");
+                return runAgentCli(args);
+            }
+            catch {
+                console.error("@phren/agent is not installed. Install it with: npm i -g @phren/agent");
+                process.exit(1);
+            }
+        }
         default:
             console.error(`Unknown command: ${command}\nRun 'phren --help' for available commands.`);
             process.exit(1);

package/{mcp/dist → dist}/cli/hooks-session.js

@@ -13,6 +13,8 @@ import { isTaskFileName, TASKS_FILENAME } from "../data/tasks.js";
 import { buildIndex, queryRows, } from "../shared/index.js";
 import { filterTaskByPriority } from "../shared/retrieval.js";
 import { logger } from "../logger.js";
+import * as crypto from "crypto";
+import { sessionFileForId, readSessionStateFile, writeSessionStateFile, } from "../session/utils.js";
 const SYNC_LOCK_STALE_MS = 10 * 60 * 1000; // 10 minutes
 const MAINTENANCE_LOCK_STALE_MS = 2 * 60 * 60 * 1000; // 2 hours
 export { buildHookContext, handleGuardSkip } from "./hooks-context.js";
@@ -671,6 +673,51 @@ export async function handleHookSessionStart() {
     catch (err) {
         debugLog(`session-start onboarding detection failed: ${errorMessage(err)}`);
     }
+    // ── Bridge: create a real session record so session_history tracks hook sessions ──
+    // Uses a file lock to prevent concurrent SessionStart hooks from racing on
+    // the active-hook-session pointer (read previous ID, end it, write new ID).
+    try {
+        const activeSessionFile = runtimeFile(phrenPath, "active-hook-session");
+        withFileLock(activeSessionFile, () => {
+            // Retroactively end the previous hook session (if any)
+            try {
+                const prevId = fs.readFileSync(activeSessionFile, "utf-8").trim();
+                if (prevId) {
+                    const prevFile = sessionFileForId(phrenPath, prevId);
+                    const prevState = readSessionStateFile(prevFile);
+                    if (prevState && !prevState.endedAt) {
+                        writeSessionStateFile(prevFile, { ...prevState, endedAt: startedAt });
+                    }
+                }
+            }
+            catch (err) {
+                // ENOENT is expected on the very first session — only log other errors
+                if (err.code !== "ENOENT") {
+                    debugLog(`session-bridge end-previous failed: ${errorMessage(err)}`);
+                }
+            }
+            // Create new session record
+            const sessionId = crypto.randomUUID();
+            const sessionState = {
+                sessionId,
+                project: activeProject || undefined,
+                startedAt,
+                findingsAdded: 0,
+                tasksCompleted: 0,
+                hookCreated: true,
+            };
+            writeSessionStateFile(sessionFileForId(phrenPath, sessionId), sessionState);
+            // Write active session ID atomically so other hooks (stop, tool) can reference it.
+            // Plain text format (not JSON) because the reader uses readFileSync + trim.
+            const tmpPath = `${activeSessionFile}.${process.pid}.${Date.now()}.tmp`;
+            fs.writeFileSync(tmpPath, sessionId + "\n");
+            fs.renameSync(tmpPath, activeSessionFile);
+            debugLog(`session-bridge created session ${sessionId.slice(0, 8)} for hook-driven session`);
+        });
+    }
+    catch (err) {
+        debugLog(`session-bridge failed: ${errorMessage(err)}`);
+    }
 }
 // ── Q21: Conversation memory capture ─────────────────────────────────────────
 const INSIGHT_KEYWORDS = [

package/{mcp/dist → dist}/entrypoint.js

@@ -18,6 +18,8 @@ const HELP_TEXT = `phren - persistent knowledge for your agents
   phren web-ui              Open the knowledge graph
   phren tasks               Cross-project task view
   phren graph               Fragment knowledge graph
+  phren agent <task>        Run the coding agent
+  phren agent -i            Interactive agent TUI
 
   phren store list              List registered stores
   phren team init <name>        Create a team store
@@ -187,6 +189,7 @@ const CLI_COMMANDS = [
     "store",
     "team",
     "promote",
+    "agent",
 ];
 async function flushTopLevelOutput() {
     await Promise.all([

package/{mcp/dist → dist}/package-metadata.js

@@ -2,7 +2,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { fileURLToPath } from "url";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-export const ROOT = path.join(__dirname, "..", "..");
+export const ROOT = path.join(__dirname, "..");
 const PACKAGE_JSON_PATH = path.join(ROOT, "package.json");
 function readPackageJson() {
     return JSON.parse(fs.readFileSync(PACKAGE_JSON_PATH, "utf8"));

package/{mcp/dist → dist}/session/utils.js

@@ -11,12 +11,35 @@ export function atomicWriteJson(filePath, data) {
     fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n");
     fs.renameSync(tmpPath, filePath);
 }
+export function sessionsDir(phrenPath) {
+    const dir = path.join(phrenPath, ".runtime", "sessions");
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export function sessionFileForId(phrenPath, sessionId) {
+    return path.join(sessionsDir(phrenPath), `session-${sessionId}.json`);
+}
+export function readSessionStateFile(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf-8"));
+    }
+    catch (err) {
+        // ENOENT is expected for missing files — only log other errors
+        if (err.code !== "ENOENT") {
+            debugError("readSessionStateFile", err);
+        }
+        return null;
+    }
+}
+export function writeSessionStateFile(file, state) {
+    atomicWriteJson(file, state);
+}
 /**
  * Log an error to stderr when PHREN_DEBUG is enabled.
  * Centralises the repeated `if (PHREN_DEBUG) stderr.write(...)` pattern.
  */
 export function debugError(scope, err) {
-    if ((process.env.PHREN_DEBUG)) {
+    if (process.env.PHREN_DEBUG) {
         process.stderr.write(`[phren] ${scope}: ${errorMessage(err)}\n`);
     }
 }

package/dist/shell/render-api.js

@@ -0,0 +1,101 @@
+import { listProjectCards } from "../data/access.js";
+import { renderShell } from "./view.js";
+import { getListItems } from "./input.js";
+// ── View cycling order (same as the shell tab bar) ──────────────────────────
+const VIEW_ORDER = [
+    "Projects", "Tasks", "Findings", "Review Queue", "Skills", "Hooks",
+];
+// ── Render ──────────────────────────────────────────────────────────────────
+/** Render a full shell frame for the given state. Read-only, no mutations. */
+export async function renderMenuFrame(phrenPath, profile, state) {
+    const shellState = {
+        version: 3,
+        view: state.view,
+        project: state.project,
+        filter: state.filter,
+    };
+    const ctx = {
+        phrenPath,
+        profile,
+        state: shellState,
+        currentCursor: () => state.cursor,
+        currentScroll: () => state.scroll,
+        setScroll: () => { },
+    };
+    const stubDoctor = async () => ({
+        ok: true,
+        checks: [],
+    });
+    const output = await renderShell(ctx, "navigate", // always navigate mode (no input mode in agent menu)
+    "", // no inputCtx
+    "", // no inputBuf
+    false, // no help
+    "Tab: Chat  ←→: Views  ↑↓: Navigate  Enter: Select  /: Filter  Esc: Back", stubDoctor, null, // subsectionsCache
+    () => { }, // setHealthLineCount
+    () => { });
+    const listCount = getListItems(phrenPath, profile, shellState, 0).length;
+    return { output, listCount };
+}
+// ── Navigation (pure function) ──────────────────────────────────────────────
+/**
+ * Apply a key to the menu state. Returns a new state, or null to signal
+ * "exit menu mode" (Tab or Escape at top level).
+ */
+export function handleMenuKey(state, keyName, listCount, phrenPath, profile) {
+    switch (keyName) {
+        // Exit menu
+        case "tab":
+        case "q":
+            return null;
+        // View cycling
+        case "left": {
+            const idx = VIEW_ORDER.indexOf(state.view);
+            const next = idx <= 0 ? VIEW_ORDER[VIEW_ORDER.length - 1] : VIEW_ORDER[idx - 1];
+            return { ...state, view: next, cursor: 0, scroll: 0, filter: undefined };
+        }
+        case "right": {
+            const idx = VIEW_ORDER.indexOf(state.view);
+            const next = idx >= VIEW_ORDER.length - 1 ? VIEW_ORDER[0] : VIEW_ORDER[idx + 1];
+            return { ...state, view: next, cursor: 0, scroll: 0, filter: undefined };
+        }
+        // Cursor movement
+        case "up":
+            return { ...state, cursor: Math.max(0, state.cursor - 1) };
+        case "down":
+            return { ...state, cursor: Math.min(Math.max(0, listCount - 1), state.cursor + 1) };
+        // Enter: drill into project (Projects view only)
+        case "return": {
+            if (state.view === "Projects" && phrenPath && profile) {
+                const cards = listProjectCards(phrenPath, profile);
+                const filtered = state.filter
+                    ? cards.filter((c) => `${c.name} ${c.summary} ${c.docs.join(" ")}`.toLowerCase().includes(state.filter.toLowerCase()))
+                    : cards;
+                const selected = filtered[state.cursor];
+                if (selected) {
+                    return { ...state, view: "Tasks", project: selected.name, cursor: 0, scroll: 0 };
+                }
+            }
+            // Escape from sub-view back to Projects
+            if (state.view !== "Projects" && state.project) {
+                return state; // no-op for non-projects views on enter
+            }
+            return state;
+        }
+        // Escape: clear filter, or go back to projects, or exit
+        case "escape": {
+            if (state.filter)
+                return { ...state, filter: undefined, cursor: 0, scroll: 0 };
+            if (state.view !== "Projects" && state.project) {
+                return { ...state, view: "Projects", project: undefined, cursor: 0, scroll: 0 };
+            }
+            return null; // exit menu
+        }
+        // Health shortcut
+        case "h":
+            if (state.view === "Health")
+                return { ...state, view: "Projects", cursor: 0, scroll: 0 };
+            return { ...state, view: "Health", cursor: 0, scroll: 0 };
+        default:
+            return state;
+    }
+}

package/{mcp/dist → dist}/test-global-setup.js

@@ -17,8 +17,8 @@ import * as path from "path";
 import { fileURLToPath } from "url";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-const REPO_ROOT = path.resolve(__dirname, "../..");
-const CLI_PATH = path.join(REPO_ROOT, "mcp", "dist", "index.js");
+const REPO_ROOT = path.resolve(__dirname, "../../..");
+const CLI_PATH = path.join(REPO_ROOT, "packages", "cli", "dist", "index.js");
 export async function setup() {
     if (fs.existsSync(CLI_PATH)) {
         // Dist already present — skip build. This is the common path when
@@ -26,8 +26,8 @@ export async function setup() {
         // re-runs where the artifact is still fresh.
         return;
     }
-    process.stdout.write("[test-global-setup] mcp/dist missing — building...\n");
-    execFileSync("npm", ["run", "build"], {
+    process.stdout.write("[test-global-setup] packages/cli/dist missing — building...\n");
+    execFileSync("pnpm", ["build"], {
         cwd: REPO_ROOT,
         stdio: "inherit",
         timeout: 60_000,

package/{mcp/dist → dist}/tools/session.js

@@ -4,7 +4,7 @@ import * as fs from "fs";
 import * as path from "path";
 import * as crypto from "crypto";
 import { execFileSync } from "child_process";
-import { debugLog, isMemoryScopeVisible, normalizeMemoryScope } from "../shared.js";
+import { debugLog, getProjectDirs, isMemoryScopeVisible, normalizeMemoryScope } from "../shared.js";
 import { withFileLock } from "../shared/governance.js";
 import { isValidProjectName, errorMessage } from "../utils.js";
 import { runCustomHooks } from "../hooks.js";
@@ -12,11 +12,10 @@ import { readExtractedFacts } from "./extract-facts.js";
 import { resolveFindingSessionId } from "../finding/context.js";
 import { readTasks } from "../data/tasks.js";
 import { readFindings } from "../data/access.js";
-import { getProjectDirs } from "../shared.js";
 import { getActiveTaskForSession } from "../task/lifecycle.js";
 import { listTaskCheckpoints, writeTaskCheckpoint } from "../session/checkpoints.js";
 import { markImpactEntriesCompletedForSession } from "../finding/impact.js";
-import { atomicWriteJson, debugError, scanSessionFiles } from "../session/utils.js";
+import { atomicWriteJson, debugError, scanSessionFiles, sessionsDir, sessionFileForId, readSessionStateFile, writeSessionStateFile, } from "../session/utils.js";
 import { getRuntimeHealth } from "../governance/policy.js";
 import { getProjectSourcePath, readProjectConfig } from "../project-config.js";
 const STALE_SESSION_MS = 24 * 60 * 60 * 1000; // 24 hours
@@ -94,28 +93,6 @@ function extractResumptionHint(summary, fallbackNextStep, fallbackLastAttempt) {
 /** Per-connection session map keyed by arbitrary connection ID (if provided). */
 const MAX_SESSION_MAP_ENTRIES = 200;
 const _sessionMap = new Map();
-function sessionsDir(phrenPath) {
-    const dir = path.join(phrenPath, ".runtime", "sessions");
-    fs.mkdirSync(dir, { recursive: true });
-    return dir;
-}
-function sessionFileForId(phrenPath, sessionId) {
-    return path.join(sessionsDir(phrenPath), `session-${sessionId}.json`);
-}
-function readSessionStateFile(file) {
-    if (!fs.existsSync(file))
-        return null;
-    try {
-        return JSON.parse(fs.readFileSync(file, "utf-8"));
-    }
-    catch (err) {
-        debugError("readSessionStateFile", err);
-        return null;
-    }
-}
-function writeSessionStateFile(file, state) {
-    atomicWriteJson(file, state);
-}
 /** Find the most recent *active* (not ended) session file by mtime. */
 function findMostRecentSession(phrenPath) {
     const dir = sessionsDir(phrenPath);
@@ -157,11 +134,7 @@ function lastSummaryPath(phrenPath) {
 /** Write the last summary for fast retrieval by next session_start. */
 function writeLastSummary(phrenPath, summary, sessionId, project) {
     try {
-        const data = { summary, sessionId, project, endedAt: new Date().toISOString() };
-        const summaryFile = lastSummaryPath(phrenPath);
-        const tmpPath = `${summaryFile}.tmp-${crypto.randomUUID()}`;
-        fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2));
-        fs.renameSync(tmpPath, summaryFile);
+        atomicWriteJson(lastSummaryPath(phrenPath), { summary, sessionId, project, endedAt: new Date().toISOString() });
     }
     catch (err) {
         debugError("writeLastSummary", err);
@@ -176,15 +149,15 @@ export function findMostRecentSummary(phrenPath) {
 function findMostRecentSummaryWithProject(phrenPath) {
     // Fast path: read from dedicated last-summary file
     try {
-        const fastPath = lastSummaryPath(phrenPath);
-        if (fs.existsSync(fastPath)) {
-            const data = JSON.parse(fs.readFileSync(fastPath, "utf-8"));
-            if (data.summary)
-                return { summary: data.summary, project: data.project, endedAt: data.endedAt };
-        }
+        const data = JSON.parse(fs.readFileSync(lastSummaryPath(phrenPath), "utf-8"));
+        if (data.summary)
+            return { summary: data.summary, project: data.project, endedAt: data.endedAt };
     }
     catch (err) {
-        debugError("findMostRecentSummaryWithProject fastPath", err);
+        // ENOENT is expected when no summary has been written yet
+        if (err.code !== "ENOENT") {
+            debugError("findMostRecentSummaryWithProject fastPath", err);
+        }
     }
     // Slow path: scan all session files
     const dir = sessionsDir(phrenPath);

package/package.json

@@ -1,18 +1,36 @@
 {
   "name": "@phren/cli",
-  "version": "0.0.55",
-  "description": "Knowledge layer for AI agents. Phren learns and recalls.",
+  "version": "0.0.57",
+  "description": "Knowledge layer for AI agents — CLI, MCP server, and data layer",
   "type": "module",
   "bin": {
-    "phren": "mcp/dist/index.js"
+    "phren": "dist/index.js"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./paths": "./dist/phren-paths.js",
+    "./runtime-profile": "./dist/runtime-profile.js",
+    "./shared": "./dist/shared/index.js",
+    "./shared/retrieval": "./dist/shared/retrieval.js",
+    "./data/access": "./dist/data/access.js",
+    "./data/tasks": "./dist/data/tasks.js",
+    "./core/finding": "./dist/core/finding.js",
+    "./session/utils": "./dist/session/utils.js",
+    "./shell/render-api": "./dist/shell/render-api.js"
   },
   "files": [
-    "mcp/dist",
-    "icon.svg",
+    "dist",
     "starter",
     "skills",
     "scripts/preuninstall.mjs"
   ],
+  "scripts": {
+    "build": "node ../../scripts/build.mjs",
+    "dev": "tsx src/index.ts",
+    "lint": "biome lint --config-path ../../biome.json src/",
+    "test": "echo 'Run tests from repo root: pnpm -w test'",
+    "preuninstall": "node scripts/preuninstall.mjs"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.28.0",
     "chalk": "^5.6.2",
@@ -25,33 +43,6 @@
     "sql.js-fts5": "^1.4.0",
     "zod": "^4.3.6"
   },
-  "devDependencies": {
-    "@playwright/test": "^1.58.2",
-    "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.5.0",
-    "@biomejs/biome": "^2.1.0",
-    "@vitest/coverage-v8": "^4.1.2",
-    "esbuild": "^0.27.4",
-    "tsx": "^4.21.0",
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.2"
-  },
-  "scripts": {
-    "build": "node scripts/build.mjs",
-    "dev": "tsx mcp/src/index.ts",
-    "lint": "biome lint mcp/src/",
-    "validate-docs": "bash scripts/validate-docs.sh",
-    "pretest": "npm run build",
-    "test": "vitest run",
-    "test:e2e": "npm run build && playwright test",
-    "test:e2e:install": "playwright install chromium",
-    "bench": "tsx mcp/bench/locomo-runner.ts --sessions 3",
-    "bench:retrieval": "tsx scripts/bench-retrieval-modes.ts",
-    "bench:retrieval:synthetic": "tsx scripts/bench-retrieval-synthetic.ts",
-    "preuninstall": "node scripts/preuninstall.mjs",
-    "install-hooks": "cp scripts/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit",
-    "prepublishOnly": "npm run build && npm test"
-  },
   "engines": {
     "node": ">=20.0.0"
   },
@@ -66,11 +57,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/alaarab/phren.git"
-  },
-  "homepage": "https://github.com/alaarab/phren#readme",
-  "overrides": {
-    "flatted": "^3.4.2",
-    "undici": "^7.10.0"
+    "url": "git+https://github.com/alaarab/phren.git",
+    "directory": "packages/cli"
   }
 }