@phren/cli 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -8,4 +8,9 @@ export declare function handleGovernMemories(projectArg?: string, silent?: boole
8
8
  export declare function handlePruneMemories(args?: string[]): Promise<void>;
9
9
  export declare function handleConsolidateMemories(args?: string[]): Promise<void>;
10
10
  export declare function handleMaintain(args: string[]): Promise<void | GovernanceSummary>;
11
+ /**
12
+ * `phren maintain summarize [project] [--llm] [--force]`: write the "## Now"
13
+ * block at the top of every topic file and "What phren knows" in summary.md.
14
+ */
15
+ export declare function handleSummarize(args: string[]): Promise<void>;
11
16
  export declare function handleBackgroundMaintenance(projectArg?: string): Promise<void>;
@@ -10,6 +10,8 @@ import { FINDINGS_FILENAME } from "../data/access.js";
10
10
  import { logger } from "../logger.js";
11
11
  import { compactFindingJournals } from "../finding/journal.js";
12
12
  import { resolveRuntimeProfile } from "../runtime-profile.js";
13
+ import { summarizeProject } from "../content/summarize.js";
14
+ import { tidyDoneTasks } from "../data/tasks.js";
13
15
  // ── Shared helpers ───────────────────────────────────────────────────────────
14
16
  function targetProjects(projectArg) {
15
17
  const profile = resolveRuntimeProfile(getPhrenPath());
@@ -303,6 +305,8 @@ export async function handleMaintain(args) {
303
305
  }
304
306
  case "prune":
305
307
  return handlePruneMemories(rest);
308
+ case "summarize":
309
+ return handleSummarize(rest);
306
310
  case "consolidate":
307
311
  return handleConsolidateMemories(rest);
308
312
  case "extract":
@@ -387,12 +391,73 @@ async function handleRestoreBackup(args) {
387
391
  appendAuditLog(getPhrenPath(), "restore_backup", `project=${projectArg} files=${projectBackups.length}`);
388
392
  }
389
393
  // ── Background maintenance ───────────────────────────────────────────────────
394
+ /**
395
+ * `phren maintain summarize [project] [--llm] [--force]`: write the "## Now"
396
+ * block at the top of every topic file and "What phren knows" in summary.md.
397
+ */
398
+ export async function handleSummarize(args) {
399
+ let projectArg;
400
+ let llm = false;
401
+ let force = false;
402
+ for (const arg of args) {
403
+ if (arg === "--llm") {
404
+ llm = true;
405
+ continue;
406
+ }
407
+ if (arg === "--force") {
408
+ force = true;
409
+ continue;
410
+ }
411
+ if (arg.startsWith("-")) {
412
+ console.error(`Unknown summarize flag: ${arg}`);
413
+ console.error("Usage: phren maintain summarize [project] [--llm] [--force]");
414
+ process.exit(1);
415
+ }
416
+ projectArg = arg;
417
+ }
418
+ const phrenPath = getPhrenPath();
419
+ const projects = targetProjects(projectArg);
420
+ let topics = 0;
421
+ let updated = 0;
422
+ for (const project of projects) {
423
+ const result = await summarizeProject(phrenPath, project, { llm, force });
424
+ topics += result.topics.length;
425
+ updated += result.topics.filter((t) => t.updated).length + (result.summaryUpdated ? 1 : 0);
426
+ const split = result.topics.filter((t) => t.split).map((t) => path.basename(t.split));
427
+ console.log(`${project}: ${result.topics.length} topic file(s), ${result.topics.filter((t) => t.updated).length} refreshed${result.summaryUpdated ? ", summary.md updated" : ""}${split.length ? `, split: ${split.join(", ")}` : ""}`);
428
+ }
429
+ console.log(`Summarized ${projects.length} project(s): ${topics} topic file(s), ${updated} file(s) written${llm ? " (LLM prose where a model answered)" : ""}.`);
430
+ appendAuditLog(phrenPath, "summarize", `projects=${projects.length} topics=${topics} updated=${updated} llm=${llm}`);
431
+ }
390
432
  export async function handleBackgroundMaintenance(projectArg) {
391
433
  const markers = qualityMarkers(getPhrenPath());
392
434
  const startedAt = new Date().toISOString();
393
435
  try {
394
436
  const compacted = compactFindingJournals(getPhrenPath(), projectArg);
395
437
  const governance = await handleGovernMemories(projectArg, true);
438
+ // Done tasks past thirty move to .config/task-archive, and topic files get
439
+ // their "## Now" block refreshed when they changed. Both structural and
440
+ // cheap; a model is only consulted from `phren maintain summarize --llm`.
441
+ let tidied = 0;
442
+ let summarized = 0;
443
+ for (const project of targetProjects(projectArg)) {
444
+ try {
445
+ const tidy = tidyDoneTasks(getPhrenPath(), project, 30);
446
+ if (tidy.ok && tidy.data.startsWith("Tidied"))
447
+ tidied++;
448
+ }
449
+ catch (err) {
450
+ logger.debug("maintenance", `tidy ${project}: ${errorMessage(err)}`);
451
+ }
452
+ try {
453
+ const summary = await summarizeProject(getPhrenPath(), project, {});
454
+ if (summary.topics.some((t) => t.updated) || summary.summaryUpdated)
455
+ summarized++;
456
+ }
457
+ catch (err) {
458
+ logger.debug("maintenance", `summarize ${project}: ${errorMessage(err)}`);
459
+ }
460
+ }
396
461
  const pruneResult = pruneDeadMemories(getPhrenPath(), projectArg);
397
462
  const pruneMsg = pruneResult.ok ? pruneResult.data.message.replace(/\n+/g, " ") : pruneResult.error;
398
463
  if (!pruneResult.ok) {
@@ -414,7 +479,7 @@ export async function handleBackgroundMaintenance(projectArg) {
414
479
  detail: `journal_added=${compacted.added} journal_skipped=${compacted.skipped} journal_failed=${compacted.failed}; projects=${governance.projects} stale=${governance.staleCount} conflicts=${governance.conflictCount} review=${governance.reviewCount}; ${pruneMsg}`,
415
480
  },
416
481
  });
417
- appendAuditLog(getPhrenPath(), "background_maintenance", `status=ok journal_added=${compacted.added} journal_skipped=${compacted.skipped} journal_failed=${compacted.failed} projects=${governance.projects} stale=${governance.staleCount} conflicts=${governance.conflictCount} review=${governance.reviewCount}`);
482
+ appendAuditLog(getPhrenPath(), "background_maintenance", `status=ok journal_added=${compacted.added} journal_skipped=${compacted.skipped} journal_failed=${compacted.failed} projects=${governance.projects} stale=${governance.staleCount} conflicts=${governance.conflictCount} review=${governance.reviewCount} tasks_tidied=${tidied} summarized=${summarized}`);
418
483
  }
419
484
  catch (err) {
420
485
  const errMsg = errorMessage(err);
package/dist/cli/hooks.js CHANGED
@@ -31,13 +31,14 @@ export { buildHookOutput, } from "./hooks-output.js";
31
31
  // Session
32
32
  export { handleHookSessionStart, handleHookStop, handleBackgroundSync, handleHookContext, handleHookTool, trackSessionMetrics, filterConversationInsightsForProactivity, extractToolFindings, filterToolFindingsForProactivity, resolveSubprocessArgs, } from "./hooks-session.js";
33
33
  // ── Imports for the orchestrator ─────────────────────────────────────────────
34
- import { searchDocumentsAsync, applyTrustFilter, rankResults, applyRelevanceFloor, DEFAULT_MIN_QUERY_RELEVANCE, selectSnippets, detectTaskIntent, } from "../shared/retrieval.js";
34
+ import { searchDocumentsAsync, applyTrustFilter, rankResults, applyRelevanceFloor, DEFAULT_MIN_QUERY_RELEVANCE, selectSnippets, detectTaskIntent, wantsTasks } from "../shared/retrieval.js";
35
35
  import { buildHookOutput } from "./hooks-output.js";
36
36
  import { getGitContext, trackSessionMetrics, } from "./hooks-session.js";
37
37
  import { approximateTokens, SNIPPET_OVERHEAD_TOKENS } from "../shared/retrieval.js";
38
38
  import { resolveRuntimeProfile } from "../runtime-profile.js";
39
39
  import { handleTaskPromptLifecycle } from "../task/lifecycle.js";
40
40
  import { bestFindingNodeId } from "../finding-graph-id.js";
41
+ import { readKnowsBlock } from "../content/summarize.js";
41
42
  // Auto-learn from prompts was removed — it learned conversational noise ("bro", "idk", typos)
42
43
  // as synonyms for high-frequency terms. Manual `phren config synonyms add` still works.
43
44
  // Future: finding-based co-occurrence mining (phren maintain command, not live hook).
@@ -152,6 +153,9 @@ export async function handleHookPrompt() {
152
153
  // Notes are intentionally available to explicit search, but are personal scratch
153
154
  // context and should never be injected into an agent prompt automatically.
154
155
  rows = rows.filter((row) => row.type !== "notes");
156
+ // Tasks are a backlog, not memory: only when the prompt is about the work.
157
+ if (!wantsTasks(prompt, intent))
158
+ rows = rows.filter((row) => row.type !== "task");
155
159
  stage.trustMs = Date.now() - tTrust0;
156
160
  if (!rows.length)
157
161
  process.exit(0);
@@ -194,10 +198,30 @@ export async function handleHookPrompt() {
194
198
  safeTokenBudget = Math.min(Math.floor(safeTokenBudget * 1.3), parseInt(process.env.PHREN_MAX_INJECT_TOKENS ?? '2000', 10));
195
199
  }
196
200
  const tSelect0 = Date.now();
197
- const { selected, usedTokens } = selectSnippets(rows, keywords, safeTokenBudget, safeLineBudget, safeCharBudget);
201
+ let { selected, usedTokens } = selectSnippets(rows, keywords, safeTokenBudget, safeLineBudget, safeCharBudget);
198
202
  stage.selectMs = Date.now() - tSelect0;
199
203
  if (!selected.length)
200
204
  process.exit(0);
205
+ // Once per session per project: the "What phren knows" paragraph from
206
+ // summary.md, so the agent gets the shape of a project's archive before
207
+ // individual bullets. Written by `phren maintain summarize`; absent until then.
208
+ if (detectedProject && sessionId) {
209
+ const knowsMarker = sessionMarker(getPhrenPath(), `knows-${sessionId}-${detectedProject}`);
210
+ if (!fs.existsSync(knowsMarker)) {
211
+ const knows = readKnowsBlock(getPhrenPath(), detectedProject);
212
+ if (knows) {
213
+ const text = knows.text.length > 520 ? `${knows.text.slice(0, 519)}…` : knows.text;
214
+ selected = [{ doc: { project: detectedProject, filename: "summary.md", type: "summary", content: knows.text, path: knows.path }, snippet: text, key: `knows:${detectedProject}` }, ...selected.filter((s) => s.key !== `knows:${detectedProject}`)];
215
+ usedTokens += approximateTokens(text) + SNIPPET_OVERHEAD_TOKENS;
216
+ try {
217
+ fs.writeFileSync(knowsMarker, "");
218
+ }
219
+ catch (err) {
220
+ debugLog(`knows marker: ${errorMessage(err)}`);
221
+ }
222
+ }
223
+ }
224
+ }
201
225
  // Injection budget: cap total injected tokens across all content
202
226
  const maxInjectTokens = clampInt(process.env.PHREN_MAX_INJECT_TOKENS, 2000, 200, 20000);
203
227
  let budgetSelected = selected;
@@ -100,6 +100,7 @@ const MAINTAIN_SUBCOMMANDS = [
100
100
  { name: "govern", usage: "phren maintain govern [project]", summary: "Queue stale memories for review" },
101
101
  { name: "prune", usage: "phren maintain prune [project]", summary: "Delete expired entries" },
102
102
  { name: "consolidate", usage: "phren maintain consolidate [project]", summary: "Deduplicate findings" },
103
+ { name: "summarize", usage: "phren maintain summarize [project] [--llm] [--force]", summary: "Write what each topic archive amounts to, and what phren knows per project" },
103
104
  { name: "extract", usage: "phren maintain extract [project]", summary: "Mine git/GitHub signals" },
104
105
  ];
105
106
  const STORE_SUBCOMMANDS = [
@@ -0,0 +1,83 @@
1
+ /**
2
+ * Give the archive a shape.
3
+ *
4
+ * Findings age out of FINDINGS.md into reference/topics/<topic>.md, append-only,
5
+ * grouped under "## Archived <date>" headings. A store a year old carries
6
+ * hundreds of thousands of words there, reachable only by keyword: search finds
7
+ * bullet 312, and nothing says what the topic amounts to. This writes a "## Now"
8
+ * block at the top of each topic file — structural by default (counts, tags,
9
+ * what is mentioned most, the newest headlines), a prose paragraph when an LLM
10
+ * is configured — and a "What phren knows" block at the end of summary.md that
11
+ * the prompt hook injects once per session for the project at hand. Both live
12
+ * between markers, so re-running replaces rather than accumulates. Nothing in
13
+ * the archive itself is rewritten; a topic file past a size cap is split, oldest
14
+ * sections first, into <topic>.older.md.
15
+ */
16
+ export declare const NOW_START = "<!-- phren:now:start -->";
17
+ export declare const NOW_END = "<!-- phren:now:end -->";
18
+ export declare const KNOWS_START = "<!-- phren:knows:start -->";
19
+ export declare const KNOWS_END = "<!-- phren:knows:end -->";
20
+ /** Bullets a topic file may hold before the oldest sections move to <topic>.older.md. */
21
+ export declare const TOPIC_SPLIT_AT = 400;
22
+ export interface ArchivedBullet {
23
+ date: string;
24
+ tag: string;
25
+ text: string;
26
+ }
27
+ export interface TopicDigest {
28
+ slug: string;
29
+ file: string;
30
+ bullets: number;
31
+ tags: Record<string, number>;
32
+ first: string;
33
+ last: string;
34
+ mentioned: string[];
35
+ headlines: string[];
36
+ }
37
+ /** Every "- " bullet under an "## Archived <date>" heading (or before any heading, for legacy files). */
38
+ export declare function parseTopicBullets(content: string): ArchivedBullet[];
39
+ /** Names the bullets keep coming back to: backticked identifiers and CamelCase words. ALLCAPS is emphasis, not a name. */
40
+ export declare function mostMentioned(bullets: ArchivedBullet[], limit?: number): string[];
41
+ export declare function digestTopic(slug: string, file: string, bullets: ArchivedBullet[]): TopicDigest;
42
+ /** The paragraph that can always be written, no model required. */
43
+ export declare function structuralNow(d: TopicDigest): string;
44
+ /** A prose paragraph over the newest bullets, when a model is configured; "" otherwise. */
45
+ export declare function proseNow(d: TopicDigest, bullets: ArchivedBullet[], signal?: AbortSignal): Promise<string>;
46
+ /** Insert or replace a marked block. Topic files: before the first section; summary: at the end. */
47
+ export declare function upsertBlock(content: string, start: string, end: string, rendered: string, where: "top" | "bottom"): string;
48
+ /** The stamp inside an existing block, so unchanged files are not rewritten. */
49
+ export declare function blockStamp(content: string, start: string): string | null;
50
+ export interface SummarizeOptions {
51
+ /** Ask a configured model for prose; falls back to structural when none answers. */
52
+ llm?: boolean;
53
+ /** Re-summarize even when the file has not changed since the last block. */
54
+ force?: boolean;
55
+ now?: () => Date;
56
+ }
57
+ export interface TopicResult {
58
+ slug: string;
59
+ file: string;
60
+ bullets: number;
61
+ updated: boolean;
62
+ split?: string;
63
+ now: string;
64
+ }
65
+ /**
66
+ * Move whole "## Archived <date>" sections, oldest first, into <topic>.older.md
67
+ * until the file is under the cap. Returns the older file's path if anything moved.
68
+ */
69
+ export declare function splitTopicFile(filePath: string, maxBullets?: number): string | null;
70
+ export declare function summarizeTopicFile(filePath: string, slug: string, opts?: SummarizeOptions): Promise<TopicResult>;
71
+ export interface ProjectSummary {
72
+ project: string;
73
+ topics: TopicResult[];
74
+ summaryPath: string | null;
75
+ summaryUpdated: boolean;
76
+ }
77
+ /** Summarize every topic file of a project and refresh the "What phren knows" block in summary.md. */
78
+ export declare function summarizeProject(phrenPath: string, project: string, opts?: SummarizeOptions): Promise<ProjectSummary>;
79
+ /** The "What phren knows" block of a project, for the hook to inject; null when absent. */
80
+ export declare function readKnowsBlock(phrenPath: string, project: string): {
81
+ path: string;
82
+ text: string;
83
+ } | null;
@@ -0,0 +1,298 @@
1
+ /**
2
+ * Give the archive a shape.
3
+ *
4
+ * Findings age out of FINDINGS.md into reference/topics/<topic>.md, append-only,
5
+ * grouped under "## Archived <date>" headings. A store a year old carries
6
+ * hundreds of thousands of words there, reachable only by keyword: search finds
7
+ * bullet 312, and nothing says what the topic amounts to. This writes a "## Now"
8
+ * block at the top of each topic file — structural by default (counts, tags,
9
+ * what is mentioned most, the newest headlines), a prose paragraph when an LLM
10
+ * is configured — and a "What phren knows" block at the end of summary.md that
11
+ * the prompt hook injects once per session for the project at hand. Both live
12
+ * between markers, so re-running replaces rather than accumulates. Nothing in
13
+ * the archive itself is rewritten; a topic file past a size cap is split, oldest
14
+ * sections first, into <topic>.older.md.
15
+ */
16
+ import * as fs from "fs";
17
+ import * as path from "path";
18
+ import { callLlm } from "./dedup.js";
19
+ import { readProjectTopics, topicReferencePath } from "../project-topics.js";
20
+ import { storeAwareProjectPath } from "../store-routing.js";
21
+ import { atomicWriteText, debugLog } from "../phren-paths.js";
22
+ import { errorMessage } from "../utils.js";
23
+ export const NOW_START = "<!-- phren:now:start -->";
24
+ export const NOW_END = "<!-- phren:now:end -->";
25
+ export const KNOWS_START = "<!-- phren:knows:start -->";
26
+ export const KNOWS_END = "<!-- phren:knows:end -->";
27
+ /** Bullets a topic file may hold before the oldest sections move to <topic>.older.md. */
28
+ export const TOPIC_SPLIT_AT = 400;
29
+ /** Every "- " bullet under an "## Archived <date>" heading (or before any heading, for legacy files). */
30
+ export function parseTopicBullets(content) {
31
+ const out = [];
32
+ let date = "";
33
+ let inNow = false;
34
+ for (const raw of content.split("\n")) {
35
+ if (raw.startsWith(NOW_START)) {
36
+ inNow = true;
37
+ continue;
38
+ }
39
+ if (raw.startsWith(NOW_END)) {
40
+ inNow = false;
41
+ continue;
42
+ }
43
+ if (inNow)
44
+ continue;
45
+ const heading = /^## Archived (\d{4}-\d{2}-\d{2})/.exec(raw);
46
+ if (heading) {
47
+ date = heading[1];
48
+ continue;
49
+ }
50
+ if (raw.startsWith("## ")) {
51
+ continue;
52
+ }
53
+ if (!raw.startsWith("- "))
54
+ continue;
55
+ const body = raw.slice(2).replace(/<!--.*?-->/g, "").trim();
56
+ const tagMatch = /^\[([a-z][a-z-]*)(?::[^\]]*)?\]\s*/.exec(body);
57
+ out.push({ date, tag: tagMatch ? tagMatch[1] : "untagged", text: tagMatch ? body.slice(tagMatch[0].length) : body });
58
+ }
59
+ return out;
60
+ }
61
+ const STOP = new Set(["The", "This", "That", "When", "Then", "There", "These", "Those", "With", "Without", "After", "Before", "Also", "Note", "Never", "Always", "Every", "Each", "Only", "Both", "Some", "Most", "Many", "Much", "More", "Less", "Use", "Used", "Using", "Run", "Runs", "Make", "Made", "Keep", "Kept", "Set", "Sets", "Got", "Get", "Gets", "Does", "Did", "Not", "For", "And", "But", "Any", "All", "Its", "Our", "Your", "Their", "One", "Two", "Three", "First", "Last", "New", "Old", "Fix", "Fixed", "Add", "Added", "Remove", "Removed", "Check", "Rails", "Node", "React", "Python", "TypeScript", "JSON", "YAML", "HTML", "CSS", "API", "URL", "ID", "OK", "TODO", "NOTE", "DO", "NOT"]);
62
+ /** Names the bullets keep coming back to: backticked identifiers and CamelCase words. ALLCAPS is emphasis, not a name. */
63
+ export function mostMentioned(bullets, limit = 6) {
64
+ const counts = new Map();
65
+ for (const b of bullets) {
66
+ const seen = new Set();
67
+ for (const m of b.text.matchAll(/`([A-Za-z_][\w./-]{2,40})`|\b([A-Z][a-z]+(?:[A-Z][a-z0-9]+)+)\b/g)) {
68
+ const term = (m[1] ?? m[2] ?? "").trim();
69
+ if (/^[A-Z0-9_]+$/.test(term))
70
+ continue;
71
+ if (!term || STOP.has(term) || seen.has(term))
72
+ continue;
73
+ seen.add(term);
74
+ counts.set(term, (counts.get(term) ?? 0) + 1);
75
+ }
76
+ }
77
+ return [...counts.entries()].filter(([, n]) => n >= 2).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, limit).map(([t]) => t);
78
+ }
79
+ function headline(text, max = 100) {
80
+ const flat = text.replace(/\s+/g, " ").trim();
81
+ const cut = flat.search(/[.;:](\s|$)/);
82
+ const s = cut > 30 && cut < max ? flat.slice(0, cut) : flat;
83
+ return s.length > max ? `${s.slice(0, max - 1)}…` : s;
84
+ }
85
+ export function digestTopic(slug, file, bullets) {
86
+ const tags = {};
87
+ for (const b of bullets)
88
+ tags[b.tag] = (tags[b.tag] ?? 0) + 1;
89
+ const dates = bullets.map((b) => b.date).filter(Boolean).sort();
90
+ const newest = [...bullets].reverse().filter((b) => b.date).slice(0, 5);
91
+ return {
92
+ slug,
93
+ file,
94
+ bullets: bullets.length,
95
+ tags,
96
+ first: dates[0] ?? "",
97
+ last: dates[dates.length - 1] ?? "",
98
+ mentioned: mostMentioned(bullets),
99
+ headlines: newest.map((b) => headline(b.text)),
100
+ };
101
+ }
102
+ function plural(n, word) {
103
+ if (word === "context")
104
+ return `${n} context note${n === 1 ? "" : "s"}`;
105
+ return `${n} ${word}${n === 1 ? "" : "s"}`;
106
+ }
107
+ /** The paragraph that can always be written, no model required. */
108
+ export function structuralNow(d) {
109
+ if (!d.bullets)
110
+ return "Nothing archived under this topic yet.";
111
+ const span = d.first && d.last ? (d.first === d.last ? `archived on ${d.first}` : `archived between ${d.first} and ${d.last}`) : "";
112
+ const tagLine = Object.entries(d.tags).filter(([t]) => t !== "untagged").sort((a, b) => b[1] - a[1]).slice(0, 4).map(([t, n]) => plural(n, t)).join(", ");
113
+ const parts = [`${plural(d.bullets, "finding")}${span ? `, ${span}` : ""}${tagLine ? `: ${tagLine}` : ""}.`];
114
+ if (d.mentioned.length)
115
+ parts.push(`Keeps coming back to ${d.mentioned.join(", ")}.`);
116
+ if (d.headlines.length)
117
+ parts.push(`Newest: ${d.headlines.map((h, i) => `(${i + 1}) ${h}`).join(" ")}`);
118
+ return parts.join(" ");
119
+ }
120
+ /** A prose paragraph over the newest bullets, when a model is configured; "" otherwise. */
121
+ export async function proseNow(d, bullets, signal) {
122
+ const newest = [...bullets].reverse().slice(0, 60).map((b) => `- [${b.tag}] ${b.text}`).join("\n");
123
+ const prompt = `These are archived engineering findings for the topic "${d.slug}" of one software project, newest first. Write one paragraph of 4 to 6 plain sentences stating what is currently known: the standing decisions, the pitfalls that still apply, and the patterns in use. Be concrete, name the components involved, no preamble, no bullet points.\n\n${newest}`;
124
+ try {
125
+ const text = (await callLlm(prompt, signal, 320)).trim();
126
+ return text.length > 40 ? text : "";
127
+ }
128
+ catch (err) {
129
+ debugLog(`summarize: llm failed: ${errorMessage(err)}`);
130
+ return "";
131
+ }
132
+ }
133
+ function block(start, end, heading, body, stamp) {
134
+ return `${start.replace("-->", `at=${stamp} -->`)}\n${heading}\n\n${body}\n${end}`;
135
+ }
136
+ /** Insert or replace a marked block. Topic files: before the first section; summary: at the end. */
137
+ export function upsertBlock(content, start, end, rendered, where) {
138
+ const startRe = new RegExp(`${start.replace("-->", "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[^\\n]*-->`);
139
+ const s = content.search(startRe);
140
+ const e = content.indexOf(end);
141
+ if (s !== -1 && e !== -1 && e > s) {
142
+ return `${content.slice(0, s)}${rendered}${content.slice(e + end.length)}`;
143
+ }
144
+ if (where === "top") {
145
+ const firstSection = content.search(/^## /m);
146
+ if (firstSection === -1)
147
+ return `${content.trimEnd()}\n\n${rendered}\n`;
148
+ return `${content.slice(0, firstSection).trimEnd()}\n\n${rendered}\n\n${content.slice(firstSection)}`;
149
+ }
150
+ return `${content.trimEnd()}\n\n${rendered}\n`;
151
+ }
152
+ /** The stamp inside an existing block, so unchanged files are not rewritten. */
153
+ export function blockStamp(content, start) {
154
+ const m = new RegExp(`${start.replace("-->", "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}at=([^ ]+) -->`).exec(content);
155
+ return m ? m[1] : null;
156
+ }
157
+ /**
158
+ * Move whole "## Archived <date>" sections, oldest first, into <topic>.older.md
159
+ * until the file is under the cap. Returns the older file's path if anything moved.
160
+ */
161
+ export function splitTopicFile(filePath, maxBullets = TOPIC_SPLIT_AT) {
162
+ const content = fs.readFileSync(filePath, "utf8");
163
+ if (parseTopicBullets(content).length <= maxBullets)
164
+ return null;
165
+ const lines = content.split("\n");
166
+ // Section boundaries: every "## Archived <date>" line, in file order (which is oldest first).
167
+ const starts = [];
168
+ for (let i = 0; i < lines.length; i++)
169
+ if (/^## Archived \d{4}-\d{2}-\d{2}/.test(lines[i]))
170
+ starts.push(i);
171
+ if (starts.length < 2)
172
+ return null;
173
+ const sections = starts.map((s, i) => lines.slice(s, i + 1 < starts.length ? starts[i + 1] : lines.length));
174
+ const head = lines.slice(0, starts[0]);
175
+ let keep = sections.slice();
176
+ const moved = [];
177
+ const count = (secs) => secs.reduce((n, sec) => n + sec.filter((l) => l.startsWith("- ")).length, 0);
178
+ while (keep.length > 1 && count(keep) > maxBullets)
179
+ moved.push(keep.shift());
180
+ if (!moved.length)
181
+ return null;
182
+ const olderPath = filePath.replace(/\.md$/, ".older.md");
183
+ const title = head.find((l) => l.startsWith("# ")) ?? "# archive";
184
+ const prior = fs.existsSync(olderPath) ? fs.readFileSync(olderPath, "utf8").trimEnd() + "\n\n" : `${title} (older archive)\n\nSections moved here from ${path.basename(filePath)} once it passed ${maxBullets} bullets. Still indexed; still searchable.\n\n`;
185
+ atomicWriteText(olderPath, prior + moved.map((sec) => sec.join("\n").trimEnd()).join("\n\n") + "\n");
186
+ atomicWriteText(filePath, [...head, ...keep.flat()].join("\n").trimEnd() + "\n");
187
+ return olderPath;
188
+ }
189
+ export async function summarizeTopicFile(filePath, slug, opts = {}) {
190
+ const split = splitTopicFile(filePath);
191
+ const content = fs.readFileSync(filePath, "utf8");
192
+ const stat = fs.statSync(filePath);
193
+ const stamp = (opts.now ?? (() => new Date()))().toISOString();
194
+ const prev = blockStamp(content, NOW_START);
195
+ const bullets = parseTopicBullets(content);
196
+ const digest = digestTopic(slug, filePath, bullets);
197
+ // The block records when it was written; a file untouched since then is left alone.
198
+ if (!opts.force && prev && !split && new Date(prev).getTime() >= stat.mtimeMs - 1000) {
199
+ const existing = content.slice(content.indexOf(NOW_START.replace("-->", "")), content.indexOf(NOW_END));
200
+ return { slug, file: filePath, bullets: bullets.length, updated: false, now: existing.split("\n").slice(2).join("\n").trim() };
201
+ }
202
+ let now = "";
203
+ if (opts.llm)
204
+ now = await proseNow(digest, bullets, AbortSignal.timeout(25_000));
205
+ if (!now)
206
+ now = structuralNow(digest);
207
+ const next = upsertBlock(content, NOW_START, NOW_END, block(NOW_START, NOW_END, "## Now", now, stamp), "top");
208
+ if (next !== content)
209
+ atomicWriteText(filePath, next);
210
+ return { slug, file: filePath, bullets: bullets.length, updated: next !== content, split: split ?? undefined, now };
211
+ }
212
+ function countActiveFindingsIn(findingsPath) {
213
+ try {
214
+ let inArchive = false;
215
+ let n = 0;
216
+ for (const line of fs.readFileSync(findingsPath, "utf8").split("\n")) {
217
+ if (/<!--\s*phren:archive:start/.test(line) || line.startsWith("<details"))
218
+ inArchive = true;
219
+ if (/<!--\s*phren:archive:end/.test(line) || line.startsWith("</details"))
220
+ inArchive = false;
221
+ if (!inArchive && line.startsWith("- "))
222
+ n++;
223
+ }
224
+ return n;
225
+ }
226
+ catch {
227
+ return 0;
228
+ }
229
+ }
230
+ function countOpenTasks(tasksPath) {
231
+ try {
232
+ return fs.readFileSync(tasksPath, "utf8").split("\n").filter((l) => /^- \[ \]/.test(l)).length;
233
+ }
234
+ catch {
235
+ return 0;
236
+ }
237
+ }
238
+ /** Summarize every topic file of a project and refresh the "What phren knows" block in summary.md. */
239
+ export async function summarizeProject(phrenPath, project, opts = {}) {
240
+ const topics = readProjectTopics(phrenPath, project).topics;
241
+ const results = [];
242
+ const seen = new Set();
243
+ for (const topic of topics) {
244
+ const file = topicReferencePath(phrenPath, project, topic.slug);
245
+ if (!file || seen.has(file) || !fs.existsSync(file))
246
+ continue;
247
+ seen.add(file);
248
+ results.push(await summarizeTopicFile(file, topic.slug, opts));
249
+ }
250
+ // Topic files that exist but are not in the configured topic list still count.
251
+ const topicsDir = storeAwareProjectPath(phrenPath, project, "reference", "topics");
252
+ if (topicsDir && fs.existsSync(topicsDir)) {
253
+ for (const entry of fs.readdirSync(topicsDir)) {
254
+ if (!entry.endsWith(".md") || entry.endsWith(".older.md"))
255
+ continue;
256
+ const file = path.join(topicsDir, entry);
257
+ if (seen.has(file))
258
+ continue;
259
+ seen.add(file);
260
+ results.push(await summarizeTopicFile(file, entry.replace(/\.md$/, ""), opts));
261
+ }
262
+ }
263
+ const summaryPath = storeAwareProjectPath(phrenPath, project, "summary.md");
264
+ if (!summaryPath)
265
+ return { project, topics: results, summaryPath: null, summaryUpdated: false };
266
+ const findingsPath = storeAwareProjectPath(phrenPath, project, "FINDINGS.md");
267
+ const tasksPath = storeAwareProjectPath(phrenPath, project, "tasks.md");
268
+ const active = findingsPath ? countActiveFindingsIn(findingsPath) : 0;
269
+ const archived = results.reduce((n, r) => n + r.bullets, 0);
270
+ const open = tasksPath ? countOpenTasks(tasksPath) : 0;
271
+ const lines = [`- ${plural(active, "active finding")}, ${archived} archived across ${plural(results.filter((r) => r.bullets > 0).length, "topic")}, ${plural(open, "open task")}.`];
272
+ for (const r of results.filter((r) => r.bullets > 0).sort((a, b) => b.bullets - a.bullets)) {
273
+ const first = r.now.split(/(?<=\.)\s/)[0] ?? r.now;
274
+ lines.push(`- **${r.slug}** — ${first}`);
275
+ }
276
+ const stamp = (opts.now ?? (() => new Date()))().toISOString();
277
+ const rendered = block(KNOWS_START, KNOWS_END, "## What phren knows", lines.join("\n"), stamp);
278
+ const existing = fs.existsSync(summaryPath) ? fs.readFileSync(summaryPath, "utf8") : `# ${project}\n`;
279
+ const next = upsertBlock(existing, KNOWS_START, KNOWS_END, rendered, "bottom");
280
+ const stripStamp = (s) => s.replace(/ at=[^ ]+ -->/g, " -->");
281
+ const changed = stripStamp(next) !== stripStamp(existing);
282
+ if (changed)
283
+ atomicWriteText(summaryPath, next);
284
+ return { project, topics: results, summaryPath, summaryUpdated: changed };
285
+ }
286
+ /** The "What phren knows" block of a project, for the hook to inject; null when absent. */
287
+ export function readKnowsBlock(phrenPath, project) {
288
+ const summaryPath = storeAwareProjectPath(phrenPath, project, "summary.md");
289
+ if (!summaryPath || !fs.existsSync(summaryPath))
290
+ return null;
291
+ const content = fs.readFileSync(summaryPath, "utf8");
292
+ const s = content.indexOf(KNOWS_START.replace("-->", ""));
293
+ const e = content.indexOf(KNOWS_END);
294
+ if (s === -1 || e === -1)
295
+ return null;
296
+ const inner = content.slice(s, e).split("\n").slice(1).join("\n").trim();
297
+ return inner ? { path: summaryPath, text: inner } : null;
298
+ }
@@ -24,6 +24,8 @@ import { claudeProjectKey } from "./context.js";
24
24
  import { getProjectOwnershipMode, readProjectConfig } from "../project-config.js";
25
25
  import { readInstallPreferences } from "../init/preferences.js";
26
26
  import { logger } from "../logger.js";
27
+ import { CONTEXT_COST_LIMITS, medianHookInjectionTokens, storeWeight } from "../store-weight.js";
28
+ import { resolveMcpProfile } from "../mcp/profile.js";
27
29
  // ── Doctor ──────────────────────────────────────────────────────────────────
28
30
  function isWrapperActive(tool) {
29
31
  const isWindows = process.platform === "win32";
@@ -542,6 +544,30 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
542
544
  runtime = null;
543
545
  }
544
546
  }
547
+ // What an agent pays before it says a word, and per prompt after. None of
548
+ // the tidying stays done unless this is visible.
549
+ try {
550
+ const weight = storeWeight(phrenPath);
551
+ const profile = resolveMcpProfile(phrenPath);
552
+ const injection = medianHookInjectionTokens(phrenPath);
553
+ const problems = [];
554
+ if (weight.globalClaude > CONTEXT_COST_LIMITS.globalClaudeWords)
555
+ problems.push(`global CLAUDE.md is ${weight.globalClaude} words (aim under ${CONTEXT_COST_LIMITS.globalClaudeWords})`);
556
+ if (profile === "full")
557
+ problems.push("MCP profile is full (59 tools, ~53k chars of schema per session); `phren config mcp-profile core` is ~17k");
558
+ if (injection.medianTokens > CONTEXT_COST_LIMITS.medianInjectionTokens)
559
+ problems.push(`median hook injection is ${injection.medianTokens} tokens over the last ${injection.prompts} prompts`);
560
+ checks.push({
561
+ name: "context-cost",
562
+ ok: problems.length === 0,
563
+ detail: problems.length
564
+ ? problems.join("; ")
565
+ : `global CLAUDE.md ${weight.globalClaude} words · MCP profile ${profile} (${profile === "core" ? "10 tools, ~17k chars" : "59 tools, ~53k chars"})${injection.prompts ? ` · median injection ${injection.medianTokens} tokens over ${injection.prompts} prompts` : ""} · store: findings ${weight.findings.toLocaleString("en-US")} words, archive ${weight.reference.toLocaleString("en-US")}, tasks ${weight.tasks.toLocaleString("en-US")}, skills ${weight.skills.toLocaleString("en-US")}`,
566
+ });
567
+ }
568
+ catch (err) {
569
+ logger.debug("doctor", `context-cost: ${errorMessage(err)}`);
570
+ }
545
571
  checks.push({
546
572
  name: "runtime-health-file",
547
573
  ok: Boolean(runtime),
@@ -19,6 +19,12 @@ export declare const SNIPPET_OVERHEAD_TOKENS = 24;
19
19
  * recall. Cross-project docs face a higher bar. Tunable via
20
20
  * PHREN_MIN_QUERY_RELEVANCE (0 disables the floor). */
21
21
  declare const DEFAULT_MIN_QUERY_RELEVANCE = 0.12;
22
+ /**
23
+ * Tasks are a backlog, not memory: a to-do list injected into a debugging
24
+ * question is noise that costs findings their budget. They go in only when the
25
+ * prompt is about building or asks about the work itself.
26
+ */
27
+ export declare function wantsTasks(prompt: string, intent: ReturnType<typeof detectTaskIntent>): boolean;
22
28
  export declare function detectTaskIntent(prompt: string): "debug" | "review" | "build" | "docs" | "skill" | "general";
23
29
  export declare function fileRelevanceBoost(filePath: string, changedFiles: Set<string>): number;
24
30
  export declare function branchMatchBoost(content: string, branch: string | undefined): number;
@@ -59,6 +59,15 @@ const INTENT_DEBUG_RE = /(bug|error|fix|broken|regression|fail|stack trace)/;
59
59
  const INTENT_REVIEW_RE = /(review|audit|pr|pull request|nit|refactor)/;
60
60
  const INTENT_BUILD_RE = /(build|deploy|release|ci|workflow|pipeline|test)/;
61
61
  const INTENT_DOCS_RE = /\b(doc|docs|readme|explain|guide|instructions?)\b/;
62
+ const WANTS_TASKS_RE = /\b(tasks?|todos?|backlog|queue|what'?s (left|next|remaining)|what is (left|next|remaining)|next up|remaining work|priorit(y|ies))\b/i;
63
+ /**
64
+ * Tasks are a backlog, not memory: a to-do list injected into a debugging
65
+ * question is noise that costs findings their budget. They go in only when the
66
+ * prompt is about building or asks about the work itself.
67
+ */
68
+ export function wantsTasks(prompt, intent) {
69
+ return intent === "build" || WANTS_TASKS_RE.test(prompt);
70
+ }
62
71
  export function detectTaskIntent(prompt) {
63
72
  const p = prompt.toLowerCase();
64
73
  if (INTENT_SKILL_CMD_RE.test(p) || INTENT_SKILL_KW_RE.test(p))
package/dist/status.js CHANGED
@@ -14,6 +14,7 @@ import { assessSyncOutage } from "./shared/governance.js";
14
14
  import { resolveRuntimeProfile } from "./runtime-profile.js";
15
15
  import { renderPhrenArt } from "./phren-art.js";
16
16
  import { RESET, BOLD, DIM, GREEN, YELLOW, RED, CYAN } from "./shell/render.js";
17
+ import { storeWeight } from "./store-weight.js";
17
18
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
18
19
  function readPackageVersion() {
19
20
  try {
@@ -100,6 +101,14 @@ export async function runStatus() {
100
101
  // Phren path and config
101
102
  console.log(` ${DIM}path${RESET} ${phrenPath}`);
102
103
  console.log(` ${DIM}mode${RESET} ${manifest?.installMode || "unknown"}`);
104
+ try {
105
+ const w = storeWeight(phrenPath, profile);
106
+ const k = (n) => (n >= 1000 ? `${(n / 1000).toFixed(n >= 10000 ? 0 : 1)}k` : String(n));
107
+ console.log(` ${DIM}weight${RESET} ${k(w.findings)} words of findings · ${k(w.reference)} archived · ${k(w.tasks)} in tasks · ${k(w.skills)} in skills · CLAUDE.md ${w.globalClaude} words`);
108
+ }
109
+ catch (err) {
110
+ logger.debug("status", `weight: ${errorMessage(err)}`);
111
+ }
103
112
  if (manifest?.workspaceRoot) {
104
113
  console.log(` ${DIM}workspace${RESET} ${manifest.workspaceRoot}`);
105
114
  }
@@ -0,0 +1,28 @@
1
+ /**
2
+ * How much text a store carries, by kind. None of the tidying phren does stays
3
+ * done unless the weight is visible, so `phren status` prints this and doctor
4
+ * warns when the parts an agent pays for every session have grown.
5
+ */
6
+ import { homePath } from "./phren-paths.js";
7
+ export interface StoreWeight {
8
+ projects: number;
9
+ /** Words in FINDINGS.md files (active findings). */
10
+ findings: number;
11
+ /** Words under reference/, the archive. */
12
+ reference: number;
13
+ tasks: number;
14
+ skills: number;
15
+ /** Words in the global CLAUDE.md every session loads. */
16
+ globalClaude: number;
17
+ }
18
+ export declare function storeWeight(phrenPath: string, profile?: string): StoreWeight;
19
+ /** Median tokens the prompt hook injected per prompt, from the live lookup log's hook events. */
20
+ export declare function medianHookInjectionTokens(phrenPath: string, lastPrompts?: number): {
21
+ prompts: number;
22
+ medianTokens: number;
23
+ };
24
+ export declare const CONTEXT_COST_LIMITS: {
25
+ globalClaudeWords: number;
26
+ medianInjectionTokens: number;
27
+ };
28
+ export { homePath };
@@ -0,0 +1,80 @@
1
+ /**
2
+ * How much text a store carries, by kind. None of the tidying phren does stays
3
+ * done unless the weight is visible, so `phren status` prints this and doctor
4
+ * warns when the parts an agent pays for every session have grown.
5
+ */
6
+ import * as fs from "fs";
7
+ import * as path from "path";
8
+ import { getProjectDirs, homePath } from "./phren-paths.js";
9
+ function words(file) {
10
+ try {
11
+ return fs.readFileSync(file, "utf8").split(/\s+/).filter(Boolean).length;
12
+ }
13
+ catch {
14
+ return 0;
15
+ }
16
+ }
17
+ function walkWords(dir, match) {
18
+ let total = 0;
19
+ const stack = [dir];
20
+ while (stack.length) {
21
+ const current = stack.pop();
22
+ let entries = [];
23
+ try {
24
+ entries = fs.readdirSync(current, { withFileTypes: true });
25
+ }
26
+ catch {
27
+ continue;
28
+ }
29
+ for (const e of entries) {
30
+ if (e.name === ".git" || e.name === "node_modules")
31
+ continue;
32
+ const full = path.join(current, e.name);
33
+ if (e.isDirectory())
34
+ stack.push(full);
35
+ else if (e.isFile() && match(e.name))
36
+ total += words(full);
37
+ }
38
+ }
39
+ return total;
40
+ }
41
+ export function storeWeight(phrenPath, profile = "") {
42
+ const projectDirs = getProjectDirs(phrenPath, profile).filter((d) => path.basename(d) !== "global");
43
+ const w = { projects: projectDirs.length, findings: 0, reference: 0, tasks: 0, skills: 0, globalClaude: words(path.join(phrenPath, "global", "CLAUDE.md")) };
44
+ for (const dir of projectDirs) {
45
+ w.findings += words(path.join(dir, "FINDINGS.md"));
46
+ w.tasks += words(path.join(dir, "tasks.md"));
47
+ w.reference += walkWords(path.join(dir, "reference"), (n) => n.endsWith(".md"));
48
+ w.skills += walkWords(path.join(dir, "skills"), (n) => n.endsWith(".md"));
49
+ }
50
+ w.skills += walkWords(path.join(phrenPath, "global", "skills"), (n) => n.endsWith(".md"));
51
+ return w;
52
+ }
53
+ /** Median tokens the prompt hook injected per prompt, from the live lookup log's hook events. */
54
+ export function medianHookInjectionTokens(phrenPath, lastPrompts = 100) {
55
+ const log = path.join(phrenPath, ".runtime", "lookup-events.jsonl");
56
+ let lines = [];
57
+ try {
58
+ lines = fs.readFileSync(log, "utf8").trim().split("\n").filter(Boolean);
59
+ }
60
+ catch {
61
+ return { prompts: 0, medianTokens: 0 };
62
+ }
63
+ const perPrompt = new Map();
64
+ for (const line of lines.slice(-2000)) {
65
+ try {
66
+ const e = JSON.parse(line);
67
+ if (e.source !== "hook" || !e.at)
68
+ continue;
69
+ const key = `${e.session ?? ""}@${e.at}`;
70
+ perPrompt.set(key, (perPrompt.get(key) ?? 0) + Math.ceil(((e.snippet ?? "").length + 40) / 4));
71
+ }
72
+ catch { /* skip a torn line */ }
73
+ }
74
+ const sizes = [...perPrompt.values()].slice(-lastPrompts).sort((a, b) => a - b);
75
+ if (!sizes.length)
76
+ return { prompts: 0, medianTokens: 0 };
77
+ return { prompts: sizes.length, medianTokens: sizes[Math.floor(sizes.length / 2)] };
78
+ }
79
+ export const CONTEXT_COST_LIMITS = { globalClaudeWords: 600, medianInjectionTokens: 1500 };
80
+ export { homePath };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@phren/cli",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "Knowledge layer for AI agents — CLI, MCP server, and data layer",
5
5
  "type": "module",
6
6
  "bin": {