@phren/cli 0.0.54 → 0.0.56

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

@@ -7,10 +7,10 @@ import { handleExtractMemories } from "./extract.js";
 import { handleGovernMemories, handlePruneMemories, handleConsolidateMemories, handleMaintain, handleBackgroundMaintenance, } from "./govern.js";
 import { handleConfig, handleIndexPolicy, handleRetentionPolicy, handleWorkflowPolicy, } from "./config.js";
 import { parseSearchArgs } from "./search.js";
-import { handleDetectSkills, handleFindingNamespace, handleHooksNamespace, handleProjectsNamespace, handleSkillsNamespace, handleSkillList, handlePromoteNamespace, handleStoreNamespace, handleTaskNamespace, } from "./namespaces.js";
+import { handleDetectSkills, handleFindingNamespace, handleHooksNamespace, handleProfileNamespace, handleProjectsNamespace, handleSkillsNamespace, handleSkillList, handlePromoteNamespace, handleReviewNamespace, handleStoreNamespace, handleTaskNamespace, } from "./namespaces.js";
 import { handleTeamNamespace } from "./team.js";
 import { handleTaskView, handleSessionsView, handleQuickstart, handleDebugInjection, handleInspectIndex, } from "./ops.js";
-import { handleAddFinding, handleDoctor, handleFragmentSearch, handleMemoryUi, handleTruths, handlePinCanonical, handleQualityFeedback, handleRelatedDocs, handleReview, handleConsolidationStatus, handleSessionContext, handleSearch, handleShell, handleStatus, handleUpdate, } from "./actions.js";
+import { handleAddFinding, handleDoctor, handleFragmentSearch, handleMemoryUi, handleTruths, handlePinCanonical, handleQualityFeedback, handleRelatedDocs, handleConsolidationStatus, handleSessionContext, handleSearch, handleShell, handleStatus, handleUpdate, } from "./actions.js";
 import { handleGraphNamespace } from "./graph.js";
 import { resolveRuntimeProfile } from "../runtime-profile.js";
 // ── CLI router ───────────────────────────────────────────────────────────────
@@ -103,7 +103,7 @@ export async function runCliCommand(command, args) {
         case "graph":
             return handleGraphNamespace(args);
         case "review":
-            return handleReview(args);
+            return handleReviewNamespace(args);
         case "consolidation-status":
             return handleConsolidationStatus(args);
         case "session-context":
@@ -112,10 +112,22 @@ export async function runCliCommand(command, args) {
             return handleTruths(args[0]);
         case "store":
             return handleStoreNamespace(args);
+        case "profile":
+            return handleProfileNamespace(args);
         case "team":
             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}/cli/namespaces.js

@@ -1771,6 +1771,82 @@ export async function handleStoreNamespace(args) {
     printStoreUsage();
     process.exit(1);
 }
+// ── Profile namespace ────────────────────────────────────────────────────────
+function printProfileUsage() {
+    console.log("Usage:");
+    console.log("  phren profile list                  List all available profiles");
+    console.log("  phren profile switch <name>         Switch to an active profile");
+}
+export function handleProfileNamespace(args) {
+    const subcommand = args[0];
+    if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+        printProfileUsage();
+        return;
+    }
+    const phrenPath = getPhrenPath();
+    if (subcommand === "list") {
+        const { listProfiles } = require("../profile-store.js");
+        const result = listProfiles(phrenPath);
+        if (!result.ok) {
+            console.error(`Failed to list profiles: ${result.error}`);
+            process.exit(1);
+        }
+        const profiles = result.data || [];
+        if (profiles.length === 0) {
+            console.log("No profiles available.");
+            return;
+        }
+        const { listMachines } = require("../profile-store.js");
+        const machinesResult = listMachines(phrenPath);
+        const machines = machinesResult.ok ? machinesResult.data : {};
+        const { getMachineName } = require("../machine-identity.js");
+        const currentMachine = getMachineName();
+        const activeProfile = machines[currentMachine];
+        console.log(`${profiles.length} profile(s):\n`);
+        for (const profile of profiles) {
+            const isCurrent = profile.name === activeProfile ? " (current)" : "";
+            const projectCount = profile.projects?.length ?? 0;
+            console.log(`  ${profile.name}${isCurrent}`);
+            console.log(`    projects: ${projectCount}`);
+            console.log();
+        }
+        return;
+    }
+    if (subcommand === "switch") {
+        const profileName = args[1];
+        if (!profileName) {
+            console.error("Usage: phren profile switch <name>");
+            process.exit(1);
+        }
+        const { setMachineProfile, getDefaultMachineAlias, listProfiles } = require("../profile-store.js");
+        // Validate that profile exists
+        const listResult = listProfiles(phrenPath);
+        if (!listResult.ok) {
+            console.error(`Failed to list profiles: ${listResult.error}`);
+            process.exit(1);
+        }
+        const profiles = listResult.data || [];
+        if (!profiles.some((p) => p.name === profileName)) {
+            console.error(`Profile not found: "${profileName}"`);
+            console.log("Available profiles:");
+            for (const p of profiles) {
+                console.log(`  - ${p.name}`);
+            }
+            process.exit(1);
+        }
+        const machineAlias = getDefaultMachineAlias();
+        const result = setMachineProfile(phrenPath, machineAlias, profileName);
+        if (!result.ok) {
+            console.error(`Failed to switch profile: ${result.error}`);
+            process.exit(1);
+        }
+        console.log(`Switched to profile: ${profileName} (machine: ${machineAlias})`);
+        return;
+    }
+    console.error(`Unknown profile subcommand: ${subcommand}`);
+    printProfileUsage();
+    process.exit(1);
+}
 // ── Promote namespace ────────────────────────────────────────────────────────
 export async function handlePromoteNamespace(args) {
     if (!args[0] || args[0] === "--help" || args[0] === "-h") {
@@ -1836,6 +1912,50 @@ export async function handlePromoteNamespace(args) {
     console.log(`Promoted to ${toStore}/${project}:`);
     console.log(`  "${match.text.slice(0, 120)}${match.text.length > 120 ? "..." : ""}"`);
 }
+// ── Review namespace ────────────────────────────────────────────────────────
+export async function handleReviewNamespace(args) {
+    const subcommand = args[0];
+    if (!subcommand || subcommand === "--help" || subcommand === "-h") {
+        console.log("Usage:");
+        console.log("  phren review [project]                       Show review queue items");
+        console.log("  phren review approve <project> <text>        Approve and remove item");
+        console.log("  phren review reject <project> <text>         Reject and remove item");
+        console.log("");
+        console.log("Examples:");
+        console.log('  phren review myproject');
+        console.log('  phren review approve myproject "Always validate input"');
+        console.log('  phren review reject myproject "Avoid async in loops"');
+        return;
+    }
+    // Handle "approve" and "reject" subcommands
+    if (subcommand === "approve" || subcommand === "reject") {
+        const action = subcommand;
+        const project = args[1];
+        const lineText = args.slice(2).join(" ");
+        if (!project || !lineText) {
+            console.error(`Usage: phren review ${action} <project> <text>`);
+            process.exit(1);
+        }
+        if (!isValidProjectName(project)) {
+            console.error(`Invalid project name: "${project}".`);
+            process.exit(1);
+        }
+        const phrenPath = getPhrenPath();
+        const { approveQueueItem, rejectQueueItem } = await import("../data/access.js");
+        const result = action === "approve"
+            ? approveQueueItem(phrenPath, project, lineText)
+            : rejectQueueItem(phrenPath, project, lineText);
+        if (!result.ok) {
+            console.error(`Failed to ${action} item: ${result.error ?? "Unknown error"}`);
+            process.exit(1);
+        }
+        console.log(`${action === "approve" ? "✓ Approved" : "✗ Rejected"}: ${lineText.slice(0, 100)}${lineText.length > 100 ? "..." : ""}`);
+        return;
+    }
+    // Default: show review queue (first arg is project name if not a subcommand)
+    const { handleReview } = await import("./actions.js");
+    return handleReview(args);
+}
 function countStoreProjects(store) {
     if (!fs.existsSync(store.path))
         return 0;

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([