@phren/cli 0.0.53 → 0.0.55

package/README.md

@@ -10,7 +10,7 @@
 </p>
 
 <p align="center">
-Every time you start a new session, your AI agent forgets everything it learned. Phren fixes that. Findings, decisions, and patterns persist as markdown in a git repo you control. No database, no hosted service, no vendor lock-in.
+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>
 
 ---
@@ -21,63 +21,108 @@ Every time you start a new session, your AI agent forgets everything it learned.
 npx @phren/cli init
 ```
 
-That single command creates `~/.phren`, wires up MCP, installs hooks, and gives your agents a memory they can actually keep. Re-running on a new machine with an existing remote picks up right where you left off.
+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.
 
-## What phren tracks
+---
 
-- **Findings**: bugs hit, patterns discovered, decisions and their reasoning. Tagged by type (`[pattern]`, `[decision]`, `[pitfall]`, `[observation]`) with per-type decay rates
-- **Fragments**: named concepts (auth, build, React) that connect findings across projects. Search for a topic and phren pulls in everything linked to that fragment
-- **Tasks**: work items that persist across sessions with priority, pinning, and GitHub issue linking
-- **Sessions**: conversation boundaries with summaries and checkpoints, so the next session picks up where the last one left off
-- **Skills**: reusable slash commands you teach phren. Drop them in `~/.phren/global/skills/` and they work everywhere
+## What actually happens
 
-## How it works
+**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
 
-- **Surfaces relevant context on every prompt** via hooks. Agents build on what they know instead of starting fresh
-- **Trust scores decay over time.** Old findings lose confidence. Decisions never decay. Observations expire in 14 days
-- **Syncs across machines** through git push/pull. No coordination service
-- **Works with Claude Code, Copilot, Cursor, and Codex.** One store, every agent
-- **Shell and web UI** for browsing, searching, and triaging (`phren` or `phren web-ui`)
+**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
 
-## Quick start
+**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
 
-```bash
-npx @phren/cli init          # set up phren (interactive walkthrough)
-```
+**Tasks:**
+- Add with priority/section. Pin across sessions. Link to GitHub issues.
+- Track completions and cross-project rollups.
 
-Init detects your tools, registers MCP servers, and installs lifecycle hooks. After it finishes, open a prompt in any tracked project. Phren is already injecting context.
+---
 
-To add a project later, run `phren add` from that directory. To browse what phren knows, run `phren` to open the interactive shell.
+## Key features
 
-## Team stores
+### 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.
 
-Phren supports shared team knowledge repos alongside your personal store. A team store is a separate git repo that multiple people push to. Findings, tasks, and skills saved there are visible to everyone on the team.
+### 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"
 
-Create a team store:
+Helps you reason about contradictions instead of hiding them.
 
-```bash
-phren team init my-team --remote git@github.com:org/phren-team.git
-phren team add-project my-team my-project
-```
+### 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.
+
+### Review queue
+Mark findings as needing review (`[Review]` section). Phren surfaces review items on every session start. Approve, reject, or edit in place.
 
-Join an existing team store:
+### Governance & policies
+Per-project retention policies. Confidence decay curves. Access control. Audit logs. Configure with `phren config` or the web UI.
 
+### Store subscriptions
+Subscribe to specific projects in a team store — others stay hidden from search and context injection:
 ```bash
-phren team join git@github.com:org/phren-team.git
+phren store subscribe team-store arc intranet
+phren store unsubscribe team-store legacy-projects
 ```
 
-Each team store syncs independently. Run `phren team list` to see all registered stores.
+### 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.
 
-### Filtering Team Store Projects
+### 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.
+
+---
 
-Subscribe to only the projects you care about:
+## CLI quick reference
 
 ```bash
-phren store subscribe qualus-shared arc intranet ogrid
-phren store unsubscribe qualus-shared dendron powergrid-api
+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
 ```
 
-Unsubscribed projects still exist in the store but won't appear in search, UI, or context injection.
+See full CLI docs at [alaarab.github.io/phren](https://alaarab.github.io/phren/).
+
+---
+
+## Team stores
+
+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.
+
+Each team store can be configured with per-project subscriptions so people only see what they care about.
+
+---
+
+## Platforms
+
+- **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
+
+All use the same phren store. No vendor lock-in.
 
 ---
 

package/mcp/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,6 +112,8 @@ 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":

package/mcp/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;