@phren/cli 0.0.3 → 0.0.5

package/mcp/dist/query-correlation.js

@@ -0,0 +1,147 @@
+// query-correlation.ts — Lightweight query-to-finding correlation tracker.
+// Tracks which queries led to which documents being selected (and later rated "helpful"),
+// then uses that data to pre-warm results for recurring query patterns.
+//
+// Gated behind PHREN_FEATURE_QUERY_CORRELATION env var (disabled by default).
+// Storage: JSONL append to .runtime/query-correlations.jsonl, last-500 window.
+import * as fs from "fs";
+import { runtimeFile, debugLog } from "./shared.js";
+import { isFeatureEnabled, errorMessage } from "./utils.js";
+const CORRELATION_FILENAME = "query-correlations.jsonl";
+const RECENT_WINDOW = 500;
+const MIN_TOKEN_OVERLAP = 2;
+const MIN_TOKEN_LENGTH = 3;
+/**
+ * Check if query correlation feature is enabled via env var.
+ */
+export function isQueryCorrelationEnabled() {
+    return isFeatureEnabled("PHREN_FEATURE_QUERY_CORRELATION", false);
+}
+/**
+ * Log query-to-finding correlations after snippet selection.
+ * Called from handleHookPrompt after selectSnippets.
+ */
+export function logCorrelations(phrenPath, keywords, selected, sessionId) {
+    if (!isQueryCorrelationEnabled())
+        return;
+    if (!selected.length || !keywords.trim())
+        return;
+    try {
+        const correlationFile = runtimeFile(phrenPath, CORRELATION_FILENAME);
+        const lines = [];
+        for (const sel of selected) {
+            const entry = {
+                timestamp: new Date().toISOString(),
+                keywords: keywords.slice(0, 200),
+                project: sel.doc.project,
+                filename: sel.doc.filename,
+                sessionId,
+            };
+            lines.push(JSON.stringify(entry));
+        }
+        fs.appendFileSync(correlationFile, lines.join("\n") + "\n");
+    }
+    catch (err) {
+        debugLog(`query-correlation log failed: ${errorMessage(err)}`);
+    }
+}
+/**
+ * Mark correlations from a session as "helpful" when positive feedback is received.
+ * This retroactively stamps entries so that future correlation lookups weight them higher.
+ */
+export function markCorrelationsHelpful(phrenPath, sessionId, docKey) {
+    if (!isQueryCorrelationEnabled())
+        return;
+    try {
+        const correlationFile = runtimeFile(phrenPath, CORRELATION_FILENAME);
+        if (!fs.existsSync(correlationFile))
+            return;
+        const raw = fs.readFileSync(correlationFile, "utf8");
+        const lines = raw.split("\n").filter(Boolean);
+        let modified = false;
+        const updated = lines.map((line) => {
+            try {
+                const entry = JSON.parse(line);
+                if (entry.sessionId === sessionId &&
+                    `${entry.project}/${entry.filename}` === docKey &&
+                    !entry.helpful) {
+                    entry.helpful = true;
+                    modified = true;
+                    return JSON.stringify(entry);
+                }
+            }
+            catch {
+                // keep original line
+            }
+            return line;
+        });
+        if (modified) {
+            fs.writeFileSync(correlationFile, updated.join("\n") + "\n");
+        }
+    }
+    catch (err) {
+        debugLog(`query-correlation mark-helpful failed: ${errorMessage(err)}`);
+    }
+}
+/**
+ * Tokenize a keyword string for overlap comparison.
+ */
+function tokenize(text) {
+    return new Set(text
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((w) => w.length >= MIN_TOKEN_LENGTH));
+}
+/**
+ * Find documents that historically correlate with the given query keywords.
+ * Returns doc keys (project/filename) sorted by correlation strength.
+ *
+ * Only looks at the last RECENT_WINDOW entries for performance.
+ * Entries marked "helpful" get a 2x weight boost.
+ */
+export function getCorrelatedDocs(phrenPath, keywords, limit = 3) {
+    if (!isQueryCorrelationEnabled())
+        return [];
+    try {
+        const correlationFile = runtimeFile(phrenPath, CORRELATION_FILENAME);
+        if (!fs.existsSync(correlationFile))
+            return [];
+        const raw = fs.readFileSync(correlationFile, "utf8");
+        const lines = raw.split("\n").filter(Boolean);
+        // Only look at last RECENT_WINDOW entries to keep it fast
+        const recent = lines.slice(-RECENT_WINDOW);
+        const queryTokens = tokenize(keywords);
+        if (queryTokens.size === 0)
+            return [];
+        const docScores = new Map();
+        for (const line of recent) {
+            try {
+                const entry = JSON.parse(line);
+                const entryTokens = tokenize(entry.keywords);
+                // Calculate overlap between current query and past query
+                let overlap = 0;
+                for (const t of queryTokens) {
+                    if (entryTokens.has(t))
+                        overlap++;
+                }
+                if (overlap >= MIN_TOKEN_OVERLAP) {
+                    const key = `${entry.project}/${entry.filename}`;
+                    // Helpful entries get a 2x weight boost
+                    const weight = entry.helpful ? overlap * 2 : overlap;
+                    docScores.set(key, (docScores.get(key) ?? 0) + weight);
+                }
+            }
+            catch {
+                // skip malformed lines
+            }
+        }
+        return [...docScores.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, limit)
+            .map(([key]) => key);
+    }
+    catch (err) {
+        debugLog(`query-correlation lookup failed: ${errorMessage(err)}`);
+        return [];
+    }
+}

package/mcp/dist/shared-content.js

@@ -4,5 +4,5 @@ export { filterTrustedFindings, filterTrustedFindingsDetailed, } from "./content
 export { scanForSecrets, resolveCoref, isDuplicateFinding, detectConflicts, extractDynamicEntities, checkSemanticDedup, checkSemanticConflicts, } from "./content-dedup.js";
 export { countActiveFindings, autoArchiveToReference, } from "./content-archive.js";
 export { upsertCanonical, addFindingToFile, addFindingsToFile, } from "./content-learning.js";
-export { FINDING_LIFECYCLE_STATUSES, parseFindingLifecycle, buildLifecycleComments, isInactiveFindingLine, } from "./finding-lifecycle.js";
+export { FINDING_LIFECYCLE_STATUSES, FINDING_TYPE_DECAY, extractFindingType, parseFindingLifecycle, buildLifecycleComments, isInactiveFindingLine, } from "./finding-lifecycle.js";
 export { METADATA_REGEX, parseStatus, parseStatusField, parseSupersession, parseSupersedesRef, parseContradiction, parseAllContradictions, parseFindingId, parseCreatedDate, isCitationLine, isArchiveStart, isArchiveEnd, stripLifecycleMetadata, stripRelationMetadata, stripAllMetadata, stripComments, addMetadata, } from "./content-metadata.js";

package/mcp/dist/shared-index.js

@@ -81,8 +81,8 @@ const FILE_TYPE_MAP = {
     "reference.md": "reference",
     "tasks.md": "task",
     "changelog.md": "changelog",
-    "canonical_memories.md": "canonical",
-    "memory_queue.md": "memory-queue",
+    "truths.md": "canonical",
+    "review.md": "review-queue",
 };
 function pathHasSegment(relPath, segment) {
     const parts = relPath.replace(/\\/g, "/").split("/").filter(Boolean);
@@ -282,7 +282,7 @@ function computePhrenHash(phrenPath, profile, preGlobbed) {
             }
         }
     }
-    // Include manual entity links so graph changes invalidate the cache
+    // Include manual fragment links so graph changes invalidate the cache
     const manualLinksPath = runtimeFile(phrenPath, "manual-links.json");
     if (fs.existsSync(manualLinksPath)) {
         try {
@@ -598,7 +598,7 @@ export function updateFileInIndex(db, filePath, phrenPath) {
         const type = classifyFile(filename, relFile);
         const entry = { fullPath: resolvedPath, project, filename, type, relFile };
         if (insertFileIntoIndex(db, entry, phrenPath, { scheduleEmbeddings: true })) {
-            // Re-extract entities for finding files
+            // Re-extract fragments for finding files
             if (type === "findings") {
                 try {
                     const content = fs.readFileSync(resolvedPath, "utf-8");
@@ -687,7 +687,7 @@ function isSentinelFresh(phrenPath, sentinel) {
     return true;
 }
 /**
- * Attempt to restore the entity graph (entities, entity_links, global_entities) from a
+ * Attempt to restore the fragment graph (entities, entity_links, global_entities) from a
  * previously persisted JSON snapshot. Returns true if the graph was loaded, false if the
  * caller must run full extraction instead.
  */
@@ -723,7 +723,7 @@ function loadCachedEntityGraph(db, graphPath, allFiles, phrenPath) {
             // is not empty after a cached-graph rebuild path.
             if (Array.isArray(graph.globalEntities)) {
                 for (const [entity, project, docKey] of graph.globalEntities) {
-                    // Skip global entities whose source doc no longer exists
+                    // Skip global fragments whose source doc no longer exists
                     if (docKey && !validDocKeys.has(docKey))
                         continue;
                     try {
@@ -736,7 +736,7 @@ function loadCachedEntityGraph(db, graphPath, allFiles, phrenPath) {
                 }
             }
             else {
-                // Older cache without globalEntities: re-derive from entity_links + entities
+                // Older cache without globalEntities: re-derive from entity_links + entities tables
                 try {
                     const rows = db.exec(`SELECT e.name, el.source_doc FROM entity_links el
              JOIN entities e ON el.target_id = e.id
@@ -769,7 +769,7 @@ function loadCachedEntityGraph(db, graphPath, allFiles, phrenPath) {
     }
     return false;
 }
-/** Merge manual entity links (written by link_findings tool) into the live DB. Always runs on
+/** Merge manual fragment links (written by link_findings tool) into the live DB. Always runs on
  * every build so hand-authored links survive a full index rebuild. */
 function mergeManualLinks(db, phrenPath) {
     const manualLinksPath = runtimeFile(phrenPath, 'manual-links.json');
@@ -1001,7 +1001,7 @@ async function buildIndexImpl(phrenPath, profile) {
                                             extractAndLinkFragments(db, content, getEntrySourceDocKey(entry, phrenPath), phrenPath);
                                         }
                                         catch (err) {
-                                            debugLog(`entity extraction failed: ${errorMessage(err)}`);
+                                            debugLog(`fragment extraction failed: ${errorMessage(err)}`);
                                         }
                                     }
                                 }
@@ -1063,15 +1063,15 @@ async function buildIndexImpl(phrenPath, profile) {
       tokenize = "porter unicode61"
     );
   `);
-        // Entity graph tables for lightweight reference graph
+        // Fragment graph tables for lightweight reference graph
         db.run(`CREATE TABLE IF NOT EXISTS entities (id INTEGER PRIMARY KEY, name TEXT NOT NULL, type TEXT NOT NULL, first_seen_at TEXT, UNIQUE(name, type))`);
         db.run(`CREATE TABLE IF NOT EXISTS entity_links (source_id INTEGER REFERENCES entities(id), target_id INTEGER REFERENCES entities(id), rel_type TEXT NOT NULL, source_doc TEXT, PRIMARY KEY (source_id, target_id, rel_type))`);
-        // Q20: Cross-project entity index
+        // Q20: Cross-project fragment index
         ensureGlobalEntitiesTable(db);
         const allFiles = globResult.entries;
         const newHashes = {};
         let fileCount = 0;
-        // Try loading cached entity graph
+        // Try loading cached fragment graph
         const graphPath = runtimeFile(phrenPath, 'entity-graph.json');
         const entityGraphLoaded = loadCachedEntityGraph(db, graphPath, allFiles, phrenPath);
         for (const entry of allFiles) {
@@ -1084,19 +1084,19 @@ async function buildIndexImpl(phrenPath, profile) {
             }
             if (insertFileIntoIndex(db, entry, phrenPath, { scheduleEmbeddings: true })) {
                 fileCount++;
-                // Extract entities from finding files (if not loaded from cache)
+                // Extract fragments from finding files (if not loaded from cache)
                 if (!entityGraphLoaded && entry.type === "findings") {
                     try {
                         const content = fs.readFileSync(entry.fullPath, "utf-8");
                         extractAndLinkFragments(db, content, getEntrySourceDocKey(entry, phrenPath), phrenPath);
                     }
                     catch (err) {
-                        debugLog(`entity extraction failed: ${errorMessage(err)}`);
+                        debugLog(`fragment extraction failed: ${errorMessage(err)}`);
                     }
                 }
             }
         }
-        // Persist entity graph for next build
+        // Persist fragment graph for next build
         if (!entityGraphLoaded) {
             try {
                 const entityRows = db.exec("SELECT id, name, type FROM entities")[0]?.values ?? [];

package/mcp/dist/shared-retrieval.js

@@ -12,6 +12,7 @@ import { vectorFallback } from "./shared-search-fallback.js";
 import { getOllamaUrl, getCloudEmbeddingUrl } from "./shared-ollama.js";
 import { keywordFallbackSearch } from "./core-search.js";
 import { debugLog } from "./shared.js";
+import { getCorrelatedDocs } from "./query-correlation.js";
 // ── Scoring constants ─────────────────────────────────────────────────────────
 /** Number of docs sampled for token-overlap semantic fallback search. */
 const SEMANTIC_FALLBACK_SAMPLE_LIMIT = 100;
@@ -31,6 +32,8 @@ const LOW_FOCUS_SNIPPET_CHAR_FRACTION = 0.55;
 const TASK_RESCUE_MIN_OVERLAP = 0.3;
 const TASK_RESCUE_OVERLAP_MARGIN = 0.12;
 const TASK_RESCUE_SCORE_MARGIN = 0.6;
+/** Boost applied to docs that correlate with recurring query patterns. */
+const CORRELATION_BOOST = 1.5;
 /** Fraction of bullets that must be low-value before applying the low-value penalty. */
 const LOW_VALUE_BULLET_FRACTION = 0.5;
 // ── Intent and scoring helpers ───────────────────────────────────────────────
@@ -605,6 +608,8 @@ export function rankResults(rows, intent, gitCtx, detectedProject, phrenPathLoca
         }
     }
     const getRecentDate = (doc) => recentDateCache.get(doc.path || `${doc.project}/${doc.filename}`) ?? "0000-00-00";
+    // Query correlation: pre-warm docs that historically correlated with similar queries
+    const correlatedDocKeys = query ? new Set(getCorrelatedDocs(phrenPathLocal, query, 5)) : new Set();
     // Precompute per-doc ranking metadata once — avoids recomputing inside sort comparator.
     const changedFiles = gitCtx?.changedFiles || new Set();
     const FILE_MATCH_BOOST = 1.5;
@@ -626,6 +631,8 @@ export function rankResults(rows, intent, gitCtx, detectedProject, phrenPathLoca
             && queryOverlap < WEAK_CROSS_PROJECT_OVERLAP_MAX
             ? WEAK_CROSS_PROJECT_OVERLAP_PENALTY
             : 0;
+        const correlationKey = `${doc.project}/${doc.filename}`;
+        const correlationBoost = correlatedDocKeys.has(correlationKey) ? CORRELATION_BOOST : 0;
         const score = Math.round((intentBoost(intent, doc.type) +
             fileRel +
             branchMat +
@@ -633,7 +640,8 @@ export function rankResults(rows, intent, gitCtx, detectedProject, phrenPathLoca
             qualityMult +
             entity +
             queryOverlap * queryOverlapWeight +
-            recencyBoost(doc.type, date) -
+            recencyBoost(doc.type, date) +
+            correlationBoost -
             weakCrossProjectPenalty -
             lowValuePenalty(doc.content, doc.type)) * crossProjectAgeMultiplier(doc, detectedProject, date) * 10000) / 10000;
         const fileMatch = fileRel > 0 || branchMat > 0;
@@ -698,6 +706,24 @@ export function rankResults(rows, intent, gitCtx, detectedProject, phrenPathLoca
     }
     return ranked;
 }
+/** Annotate snippet lines that carry contradiction metadata with visible markers. */
+export function annotateContradictions(snippet) {
+    return snippet.split('\n').map(line => {
+        const conflictMatch = line.match(/<!-- conflicts_with: "(.*?)" -->/);
+        const contradictMatch = line.match(/<!-- phren:contradicts "(.*?)" -->/);
+        const statusMatch = line.match(/phren:status "contradicted"/);
+        if (conflictMatch) {
+            return line.replace(conflictMatch[0], '') + ` [CONTRADICTED — conflicts with: "${conflictMatch[1]}"]`;
+        }
+        if (contradictMatch) {
+            return line.replace(contradictMatch[0], '') + ` [CONTRADICTED — see: "${contradictMatch[1]}"]`;
+        }
+        if (statusMatch) {
+            return line + ' [CONTRADICTED]';
+        }
+        return line;
+    }).join('\n');
+}
 /** Mark snippet lines with stale citations (cited file missing or line content changed). */
 export function markStaleCitations(snippet) {
     const lines = snippet.split("\n");
@@ -759,6 +785,8 @@ export function selectSnippets(rows, keywords, tokenBudget, lineBudget, charBudg
         if (TRUST_FILTERED_TYPES.has(doc.type)) {
             snippet = markStaleCitations(snippet);
         }
+        // Surface contradiction metadata as visible annotations
+        snippet = annotateContradictions(snippet);
         let focusScore = queryTokens.length > 0
             ? overlapScore(queryTokens, `${doc.filename}\n${snippet}`)
             : 1;

package/mcp/dist/shell-entry.js

@@ -3,7 +3,8 @@
  * Extracted from shell.ts to keep the orchestrator under 300 lines.
  */
 import { PhrenShell } from "./shell.js";
-import { style, clearScreen, clearToEnd, shellStartupFrames } from "./shell-render.js";
+import { style, clearScreen, clearToEnd, shellStartupFrames, gradient, badge } from "./shell-render.js";
+import { createPhrenAnimator } from "./phren-art.js";
 import { errorMessage } from "./utils.js";
 import { computePhrenLiveStateToken } from "./shared.js";
 import { VERSION } from "./init-shared.js";
@@ -59,13 +60,55 @@ async function playStartupIntro(phrenPath, plan = resolveStartupIntroPlan(phrenP
             await sleep(160);
         }
     }
-    renderIntroFrame(frames[frames.length - 1], renderHint);
+    // Start animated phren during loading
+    const animator = createPhrenAnimator({ facing: "right" });
+    animator.start();
+    const cols = process.stdout.columns || 80;
+    const tagline = style.dim("local memory for working agents");
+    const versionBadge = badge(`v${VERSION}`, style.boldBlue);
+    const logoLines = [
+        "██████╗ ██╗  ██╗██████╗ ███████╗███╗   ██╗",
+        "██╔══██╗██║  ██║██╔══██╗██╔════╝████╗  ██║",
+        "██████╔╝███████║██████╔╝█████╗  ██╔██╗ ██║",
+        "██╔═══╝ ██╔══██║██╔══██╗██╔══╝  ██║╚██╗██║",
+        "██║     ██║  ██║██║  ██║███████╗██║ ╚████║",
+        "╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═══╝",
+    ].map(l => gradient(l));
+    const infoLine = `${gradient("◆")} ${style.bold("phren")}  ${versionBadge}  ${tagline}`;
+    function renderAnimatedFrame(hint) {
+        const phrenLines = animator.getFrame();
+        const rightSide = ["", "", ...logoLines, "", infoLine];
+        const charWidth = 26;
+        const maxLines = Math.max(phrenLines.length, rightSide.length);
+        const merged = [""];
+        for (let i = 0; i < maxLines; i++) {
+            const left = (i < phrenLines.length ? phrenLines[i] : "").padEnd(charWidth);
+            const right = i < rightSide.length ? rightSide[i] : "";
+            merged.push(left + right);
+        }
+        if (hint)
+            merged.push("", `  ${hint}`);
+        merged.push("");
+        renderIntroFrame(merged.join("\n"));
+    }
+    // Animate during dwell/loading period
     if (plan.holdForKeypress) {
+        const animInterval = setInterval(() => renderAnimatedFrame(renderHint), 200);
+        renderAnimatedFrame(renderHint);
         await waitForAnyKeypress();
+        clearInterval(animInterval);
     }
     else if (plan.dwellMs > 0) {
-        await sleep(plan.dwellMs);
+        const startTime = Date.now();
+        while (Date.now() - startTime < plan.dwellMs) {
+            renderAnimatedFrame(renderHint);
+            await sleep(200);
+        }
+    }
+    else {
+        renderAnimatedFrame(renderHint);
     }
+    animator.stop();
     if (plan.markSeen) {
         markStartupIntroSeen(phrenPath);
     }

package/mcp/dist/shell-render.js

@@ -219,17 +219,36 @@ export function shellStartupFrames(version) {
     const cols = process.stdout.columns || 80;
     const tagline = style.dim("local memory for working agents");
     const versionBadge = badge(`v${version}`, style.boldBlue);
+    if (cols >= 72) {
+        // Side-by-side: phren character on left, logo text on right
+        const phrenLines = PHREN_STARTUP;
+        const logoLines = PHREN_LOGO.map(line => gradient(line));
+        const infoLine = `${gradient("◆")} ${style.bold("phren")}  ${versionBadge}  ${tagline}`;
+        // Logo is 6 lines, pad to align vertically with character center
+        const rightSide = [
+            "", "", ...logoLines, "", infoLine,
+        ];
+        // Merge side by side: character left (26 cols), logo right
+        const charWidth = 26;
+        const maxLines = Math.max(phrenLines.length, rightSide.length);
+        const merged = [""];
+        for (let i = 0; i < maxLines; i++) {
+            const left = (i < phrenLines.length ? phrenLines[i] : "").padEnd(charWidth);
+            const right = i < rightSide.length ? rightSide[i] : "";
+            merged.push(left + right);
+        }
+        merged.push("");
+        return [
+            // Frame 1: Logo with character side by side immediately
+            merged.join("\n"),
+        ];
+    }
     if (cols >= 56) {
+        // Medium terminal: stacked but compact
         const logo = PHREN_LOGO.map(line => "  " + gradient(line));
-        const phren = PHREN_STARTUP.map(line => "  " + line);
         const sep = gradient("━".repeat(Math.min(52, cols)));
         return [
-            // Frame 1: Phren appears
-            ["", ...phren, "", `  ${versionBadge}  ${tagline}`, ""].join("\n"),
-            // Frame 2: Full logo materializes with phren
-            ["", ...phren, "", ...logo, "", `  ${versionBadge}  ${tagline}`, ""].join("\n"),
-            // Frame 3: Complete with brand separator
-            ["", ...phren, "", ...logo, `  ${sep}`, `  ${gradient("◆")} ${style.bold("phren")}  ${versionBadge}  ${tagline}`, ""].join("\n"),
+            ["", ...logo, `  ${sep}`, `  ${gradient("◆")} ${style.bold("phren")}  ${versionBadge}  ${tagline}`, ""].join("\n"),
         ];
     }
     // Narrow terminal: progressive text reveal with gradient

package/mcp/dist/status.js

@@ -39,7 +39,7 @@ function countBullets(filePath) {
     return content.split("\n").filter((l) => l.startsWith("- ")).length;
 }
 function countQueueItems(phrenPath, project) {
-    const queueFile = path.join(phrenPath, project, "MEMORY_QUEUE.md");
+    const queueFile = path.join(phrenPath, project, "review.md");
     return countBullets(queueFile);
 }
 function runGit(cwd, args) {

package/mcp/dist/tool-registry.js

@@ -7,7 +7,7 @@ const CATEGORY_BY_MODULE = {
     "mcp-finding": "Finding capture",
     "mcp-memory": "Memory quality",
     "mcp-data": "Data management",
-    "mcp-graph": "Entities and graph",
+    "mcp-graph": "Fragments and graph",
     "mcp-session": "Session management",
     "mcp-ops": "Operations and review",
     "mcp-skills": "Skills management",

package/mcp/dist/utils.js

@@ -222,7 +222,7 @@ export function safeProjectPath(base, ...segments) {
     }
     return resolved;
 }
-const QUEUE_FILENAME = "MEMORY_QUEUE.md";
+const QUEUE_FILENAME = "review.md";
 export function queueFilePath(phrenPath, project) {
     if (!isValidProjectName(project)) {
         throw new Error(`Invalid project name: ${project}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@phren/cli",
-  "version": "0.0.3",
-  "description": "Long-term memory for AI agents. Stored as markdown in a git repo you own.",
+  "version": "0.0.5",
+  "description": "Knowledge layer for AI agents. Claude remembers you. Phren remembers your work.",
   "type": "module",
   "bin": {
     "phren": "mcp/dist/index.js"