@phren/cli 0.0.52 → 0.0.54

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,52 +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.
+
+### 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"
 
-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.
+Helps you reason about contradictions instead of hiding them.
 
-Create a team store:
+### 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.
+
+### 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 init my-team --remote git@github.com:org/phren-team.git
-phren team add-project my-team my-project
+phren store subscribe team-store arc intranet
+phren store unsubscribe team-store legacy-projects
 ```
 
-Join an existing team store:
+### 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 team join git@github.com:org/phren-team.git
+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
 ```
 
-Each team store syncs independently. Run `phren team list` to see all registered stores.
+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/namespaces.js

@@ -1535,6 +1535,8 @@ function printStoreUsage() {
     console.log("  phren store remove <name>               Remove a store (local only)");
     console.log("  phren store sync                        Pull all stores");
     console.log("  phren store activity [--limit N]         Recent team findings");
+    console.log("  phren store subscribe <name> <project...>   Subscribe store to projects");
+    console.log("  phren store unsubscribe <name> <project...> Unsubscribe store from projects");
 }
 export async function handleStoreNamespace(args) {
     const subcommand = args[0];
@@ -1669,7 +1671,8 @@ export async function handleStoreNamespace(args) {
         for (const store of teamStores) {
             if (!fs.existsSync(store.path))
                 continue;
-            const projectDirs = getProjectDirs(store.path);
+            const { getStoreProjectDirs } = await import("../store-registry.js");
+            const projectDirs = getStoreProjectDirs(store);
             for (const dir of projectDirs) {
                 const projectName = path.basename(dir);
                 const journalEntries = readTeamJournalEntries(store.path, projectName);
@@ -1728,6 +1731,42 @@ export async function handleStoreNamespace(args) {
         }
         return;
     }
+    if (subcommand === "subscribe") {
+        const storeName = args[1];
+        const projects = args.slice(2);
+        if (!storeName || projects.length === 0) {
+            console.error("Usage: phren store subscribe <store-name> <project1> [project2...]");
+            process.exit(1);
+        }
+        try {
+            const { subscribeStoreProjects } = await import("../store-registry.js");
+            subscribeStoreProjects(phrenPath, storeName, projects);
+            console.log(`Added ${projects.length} project(s) to "${storeName}"`);
+        }
+        catch (err) {
+            console.error(`Failed to subscribe: ${errorMessage(err)}`);
+            process.exit(1);
+        }
+        return;
+    }
+    if (subcommand === "unsubscribe") {
+        const storeName = args[1];
+        const projects = args.slice(2);
+        if (!storeName || projects.length === 0) {
+            console.error("Usage: phren store unsubscribe <store-name> <project1> [project2...]");
+            process.exit(1);
+        }
+        try {
+            const { unsubscribeStoreProjects } = await import("../store-registry.js");
+            unsubscribeStoreProjects(phrenPath, storeName, projects);
+            console.log(`Removed ${projects.length} project(s) from "${storeName}"`);
+        }
+        catch (err) {
+            console.error(`Failed to unsubscribe: ${errorMessage(err)}`);
+            process.exit(1);
+        }
+        return;
+    }
     console.error(`Unknown store subcommand: ${subcommand}`);
     printStoreUsage();
     process.exit(1);
@@ -1801,7 +1840,8 @@ function countStoreProjects(store) {
     if (!fs.existsSync(store.path))
         return 0;
     try {
-        return getProjectDirs(store.path).length;
+        const storeRegistry = require("../store-registry.js");
+        return storeRegistry.getStoreProjectDirs(store).length;
     }
     catch {
         return 0;

package/mcp/dist/content/validate.js

@@ -7,6 +7,7 @@ import { errorMessage } from "../utils.js";
 import { countActiveFindings } from "./archive.js";
 import { isTaskFileName } from "../data/tasks.js";
 import { METADATA_REGEX } from "./metadata.js";
+import { getNonPrimaryStores, getStoreProjectDirs } from "../store-registry.js";
 /** Maximum allowed length for a single finding entry (token budget protection). */
 export const MAX_FINDING_LENGTH = 2000;
 function safeParseDate(s) {
@@ -76,12 +77,10 @@ export function checkConsolidationNeeded(phrenPath, profile) {
     }
     // Include projects from team stores
     try {
-        const storeRegistry = require("../store-registry.js");
-        const { getNonPrimaryStores } = storeRegistry;
         for (const store of getNonPrimaryStores(phrenPath)) {
             if (!fs.existsSync(store.path))
                 continue;
-            for (const dir of getProjectDirs(store.path)) {
+            for (const dir of getStoreProjectDirs(store)) {
                 const status = getProjectConsolidationStatus(dir);
                 if (status && status.recommended) {
                     results.push(status);

package/mcp/dist/data/access.js

@@ -12,6 +12,7 @@ import { parseCitationComment, parseSourceComment, } from "../content/citation.j
 import { parseFindingLifecycle, } from "../finding/lifecycle.js";
 import { METADATA_REGEX, isCitationLine, isArchiveStart, isArchiveEnd, parseFindingId, parseAllContradictions, stripComments, normalizeFindingText, } from "../content/metadata.js";
 import { withSafeLock, ensureProject } from "../shared/data-utils.js";
+import { getNonPrimaryStores, getStoreProjectDirs } from "../store-registry.js";
 export { readTasks, readTasksAcrossProjects, resolveTaskItem, addTask, addTasks, completeTasks, completeTask, removeTask, removeTasks, updateTask, linkTaskIssue, pinTask, unpinTask, workNextTask, tidyDoneTasks, taskMarkdown, appendChildFinding, promoteTask, TASKS_FILENAME, TASK_FILE_ALIASES, canonicalTaskFilePath, resolveTaskFilePath, isTaskFileName, } from "./tasks.js";
 export { addProjectToProfile, listMachines, listProfiles, listProjectCards, removeProjectFromProfile, setMachineProfile, } from "../profile-store.js";
 export { loadShellState, resetShellState, saveShellState, } from "../shell/state-store.js";
@@ -570,12 +571,10 @@ export function readReviewQueueAcrossProjects(phrenPath, profile) {
     }
     // Include projects from team stores
     try {
-        const storeRegistry = require("../store-registry.js");
-        const { getNonPrimaryStores } = storeRegistry;
         for (const store of getNonPrimaryStores(phrenPath)) {
             if (!fs.existsSync(store.path))
                 continue;
-            const storeDirs = getProjectDirs(store.path)
+            const storeDirs = getStoreProjectDirs(store)
                 .map((d) => path.basename(d))
                 .filter((p) => p !== "global");
             for (const storeProject of storeDirs) {

package/mcp/dist/data/tasks.js

@@ -5,6 +5,7 @@ import { phrenErr, PhrenError, phrenOk, forwardErr, getProjectDirs, } from "../s
 import { validateTaskFormat } from "../shared/content.js";
 import { safeProjectPath } from "../utils.js";
 import { withSafeLock, ensureProject } from "../shared/data-utils.js";
+import { getNonPrimaryStores, getStoreProjectDirs } from "../store-registry.js";
 const ACTIVE_HEADINGS = new Set(["active", "in progress", "in-progress", "current", "wip"]);
 const QUEUE_HEADINGS = new Set(["queue", "queued", "task", "todo", "upcoming", "next"]);
 const DONE_HEADINGS = new Set(["done", "completed", "finished", "archived"]);
@@ -368,11 +369,10 @@ export function readTasksAcrossProjects(phrenPath, profile) {
     }
     // Non-primary store projects (no profile — team stores don't have profiles)
     try {
-        const { getNonPrimaryStores } = require("../store-registry.js");
         for (const store of getNonPrimaryStores(phrenPath)) {
             if (!fs.existsSync(store.path))
                 continue;
-            const storeProjects = getProjectDirs(store.path).map((dir) => path.basename(dir));
+            const storeProjects = getStoreProjectDirs(store).map((dir) => path.basename(dir));
             for (const project of storeProjects) {
                 if (seen.has(project))
                     continue;