@phren/cli 0.2.6 → 0.2.8

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.
@@ -41,7 +41,17 @@ export declare function mostMentioned(bullets: ArchivedBullet[], limit?: number)
41
41
  export declare function digestTopic(slug: string, file: string, bullets: ArchivedBullet[]): TopicDigest;
42
42
  /** The paragraph that can always be written, no model required. */
43
43
  export declare function structuralNow(d: TopicDigest): string;
44
- /** A prose paragraph over the newest bullets, when a model is configured; "" otherwise. */
44
+ /**
45
+ * Identifiers a paragraph names that none of the bullets do. A small local
46
+ * model asked to summarise engineering notes will happily invent the stack
47
+ * ("built on argparse" for a TypeScript project); a summary that adds facts
48
+ * is worse than no summary, so any invented identifier fails the paragraph.
49
+ */
50
+ export declare function inventedIdentifiers(prose: string, bullets: ArchivedBullet[]): string[];
51
+ /**
52
+ * A prose paragraph over the newest bullets, when a model is configured; ""
53
+ * otherwise, and "" when the paragraph names things the bullets do not.
54
+ */
45
55
  export declare function proseNow(d: TopicDigest, bullets: ArchivedBullet[], signal?: AbortSignal): Promise<string>;
46
56
  /** Fingerprint of everything in a topic file except its own Now block. */
47
57
  export declare function contentFingerprint(content: string, start: string, end: string): string;
@@ -81,6 +91,31 @@ export interface ProjectSummary {
81
91
  }
82
92
  /** Summarize every topic file of a project and refresh the "What phren knows" block in summary.md. */
83
93
  export declare function summarizeProject(phrenPath: string, project: string, opts?: SummarizeOptions): Promise<ProjectSummary>;
94
+ export interface TopicFile {
95
+ slug: string;
96
+ file: string;
97
+ }
98
+ /** Every markdown file under a project's reference/topics, minus the .older.md spill-over files. */
99
+ export declare function listTopicFiles(phrenPath: string, project: string): TopicFile[];
100
+ /** The current Now text of a topic file and whether it is structural or prose. */
101
+ export declare function readNowBlock(content: string): {
102
+ text: string;
103
+ structural: boolean;
104
+ } | null;
105
+ /**
106
+ * Store a paragraph an agent wrote for a topic, under the same rule a model's
107
+ * paragraph gets: every identifier it names must appear in the bullets.
108
+ * Returns the invented names on refusal.
109
+ */
110
+ export declare function setTopicSummary(filePath: string, text: string, now?: () => Date): {
111
+ ok: true;
112
+ } | {
113
+ ok: false;
114
+ invented: string[];
115
+ } | {
116
+ ok: false;
117
+ error: string;
118
+ };
84
119
  /** The "What phren knows" block of a project, for the hook to inject; null when absent. */
85
120
  export declare function readKnowsBlock(phrenPath: string, project: string): {
86
121
  path: string;
@@ -140,14 +140,48 @@ export function structuralNow(d) {
140
140
  parts.push(`Newest: ${d.headlines.map((h, i) => `(${i + 1}) ${h}`).join(" ")}`);
141
141
  return parts.join(" ");
142
142
  }
143
- /** A prose paragraph over the newest bullets, when a model is configured; "" otherwise. */
143
+ /**
144
+ * Identifiers a paragraph names that none of the bullets do. A small local
145
+ * model asked to summarise engineering notes will happily invent the stack
146
+ * ("built on argparse" for a TypeScript project); a summary that adds facts
147
+ * is worse than no summary, so any invented identifier fails the paragraph.
148
+ */
149
+ export function inventedIdentifiers(prose, bullets) {
150
+ const source = bullets.map((b) => b.text).join("\n").toLowerCase();
151
+ const out = [];
152
+ for (const m of prose.matchAll(/`([^`]{2,60})`|\b([A-Z][a-z]+[A-Z][A-Za-z0-9]+)\b|\b([a-z][a-z0-9]*(?:[_.-][a-z0-9]+)+)\b/g)) {
153
+ const term = (m[1] ?? m[2] ?? m[3] ?? "").trim();
154
+ if (!term || term.length < 3)
155
+ continue;
156
+ if (!source.includes(term.toLowerCase()))
157
+ out.push(term);
158
+ }
159
+ return [...new Set(out)];
160
+ }
161
+ /**
162
+ * A prose paragraph over the newest bullets, when a model is configured; ""
163
+ * otherwise, and "" when the paragraph names things the bullets do not.
164
+ */
144
165
  export async function proseNow(d, bullets, signal) {
145
166
  const newest = [...bullets].reverse().slice(0, 60).map((b) => `- [${b.tag}] ${b.text}`).join("\n");
146
- 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}`;
167
+ const prompt = [
168
+ `Below are archived engineering findings for the topic "${d.slug}" of one software project, newest first.`,
169
+ "Write one paragraph of 4 to 6 plain sentences saying what is currently known: standing decisions, pitfalls that still apply, patterns in use.",
170
+ "Rules: use only facts stated in the findings. Do not name any language, framework, library, file, or component unless a finding names it, and spell such names exactly as the findings do. If the findings do not support a sentence, leave it out. No preamble, no bullet points, no headings.",
171
+ "",
172
+ newest,
173
+ ].join("\n");
147
174
  try {
148
175
  // A paragraph from a local model can take a minute on a laptop; the default ten-second budget is for YES/NO checks.
149
176
  const text = (await callLlm(prompt, signal, 320, 120_000)).trim();
150
- return text.length > 40 ? text : "";
177
+ if (text.length <= 40)
178
+ return "";
179
+ const invented = inventedIdentifiers(text, bullets);
180
+ if (invented.length) {
181
+ debugLog(`summarize: rejected model paragraph for ${d.slug}, names not in the findings: ${invented.slice(0, 5).join(", ")}`);
182
+ return "";
183
+ }
184
+ return text;
151
185
  }
152
186
  catch (err) {
153
187
  debugLog(`summarize: llm failed: ${errorMessage(err)}`);
@@ -225,6 +259,18 @@ export async function summarizeTopicFile(filePath, slug, opts = {}) {
225
259
  const fingerprint = contentFingerprint(content, NOW_START, NOW_END);
226
260
  const bullets = parseTopicBullets(content);
227
261
  const digest = digestTopic(slug, filePath, bullets);
262
+ if (!bullets.length) {
263
+ // A hand-written reference doc that happens to live under reference/topics
264
+ // is not an archive. It gets no block, and loses one it was given before.
265
+ const s = content.indexOf(NOW_START.replace("-->", ""));
266
+ const e = content.indexOf(NOW_END);
267
+ if (s !== -1 && e !== -1 && e > s) {
268
+ const stripped = `${content.slice(0, s)}${content.slice(e + NOW_END.length)}`.replace(/\n{3,}/g, "\n\n");
269
+ atomicWriteText(filePath, stripped);
270
+ return { slug, file: filePath, bullets: 0, updated: true, now: "" };
271
+ }
272
+ return { slug, file: filePath, bullets: 0, updated: false, now: "" };
273
+ }
228
274
  // The block carries a fingerprint of the rest of the file; unchanged bullets
229
275
  // mean an unchanged summary, whatever the clock says.
230
276
  if (!opts.force && prev?.hash === fingerprint && !split) {
@@ -319,6 +365,47 @@ export async function summarizeProject(phrenPath, project, opts = {}) {
319
365
  atomicWriteText(summaryPath, next);
320
366
  return { project, topics: results, summaryPath, summaryUpdated: changed };
321
367
  }
368
+ /** Every markdown file under a project's reference/topics, minus the .older.md spill-over files. */
369
+ export function listTopicFiles(phrenPath, project) {
370
+ const dir = storeAwareProjectPath(phrenPath, project, "reference", "topics");
371
+ if (!dir || !fs.existsSync(dir))
372
+ return [];
373
+ return fs.readdirSync(dir)
374
+ .filter((n) => n.endsWith(".md") && !n.endsWith(".older.md"))
375
+ .sort()
376
+ .map((n) => ({ slug: n.replace(/\.md$/, ""), file: path.join(dir, n) }));
377
+ }
378
+ /** The current Now text of a topic file and whether it is structural or prose. */
379
+ export function readNowBlock(content) {
380
+ const s = content.indexOf(NOW_START.replace("-->", ""));
381
+ const e = content.indexOf(NOW_END);
382
+ if (s === -1 || e === -1 || e <= s)
383
+ return null;
384
+ const text = content.slice(s, e).split("\n").slice(2).join("\n").trim();
385
+ return { text, structural: /^\d+ findings?\b|^Nothing archived/.test(text) };
386
+ }
387
+ /**
388
+ * Store a paragraph an agent wrote for a topic, under the same rule a model's
389
+ * paragraph gets: every identifier it names must appear in the bullets.
390
+ * Returns the invented names on refusal.
391
+ */
392
+ export function setTopicSummary(filePath, text, now = () => new Date()) {
393
+ const paragraph = text.replace(/\s+/g, " ").trim();
394
+ if (paragraph.length < 40)
395
+ return { ok: false, error: "A summary needs at least a couple of sentences." };
396
+ const content = fs.readFileSync(filePath, "utf8");
397
+ const bullets = parseTopicBullets(content);
398
+ if (!bullets.length)
399
+ return { ok: false, error: "This file has no archived bullets; it is a hand-written document, not a topic archive." };
400
+ const invented = inventedIdentifiers(paragraph, bullets);
401
+ if (invented.length)
402
+ return { ok: false, invented };
403
+ const fingerprint = contentFingerprint(content, NOW_START, NOW_END);
404
+ const next = upsertBlock(content, NOW_START, NOW_END, block(NOW_START, NOW_END, "## Now", paragraph, now().toISOString(), fingerprint), "top");
405
+ if (next !== content)
406
+ atomicWriteText(filePath, next);
407
+ return { ok: true };
408
+ }
322
409
  /** The "What phren knows" block of a project, for the hook to inject; null when absent. */
323
410
  export function readKnowsBlock(phrenPath, project) {
324
411
  const summaryPath = storeAwareProjectPath(phrenPath, project, "summary.md");
package/dist/index.js CHANGED
@@ -244,6 +244,7 @@ async function main() {
244
244
  import("./tools/extract.js"),
245
245
  import("./tools/config.js"),
246
246
  import("./tools/notes.js"),
247
+ import("./tools/summaries.js"),
247
248
  ]);
248
249
  for (const mod of toolModules)
249
250
  mod.register(server, ctx);
@@ -554,7 +554,7 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
554
554
  if (weight.globalClaude > CONTEXT_COST_LIMITS.globalClaudeWords)
555
555
  problems.push(`global CLAUDE.md is ${weight.globalClaude} words (aim under ${CONTEXT_COST_LIMITS.globalClaudeWords})`);
556
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");
557
+ problems.push("MCP profile is full (61 tools, ~53k chars of schema per session); `phren config mcp-profile core` is ~17k");
558
558
  if (injection.medianTokens > CONTEXT_COST_LIMITS.medianInjectionTokens)
559
559
  problems.push(`median hook injection is ${injection.medianTokens} tokens over the last ${injection.prompts} prompts`);
560
560
  checks.push({
@@ -562,7 +562,7 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
562
562
  ok: problems.length === 0,
563
563
  detail: problems.length
564
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")}`,
565
+ : `global CLAUDE.md ${weight.globalClaude} words · MCP profile ${profile} (${profile === "core" ? "10 tools, ~17k chars" : "61 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
566
  });
567
567
  }
568
568
  catch (err) {
@@ -0,0 +1,3 @@
1
+ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
+ import { type McpContext } from "./types.js";
3
+ export declare function register(server: McpServer, ctx: McpContext): void;
@@ -0,0 +1,98 @@
1
+ import { z } from "zod";
2
+ import * as fs from "fs";
3
+ import { mcpResponse, resolveStoreForProject } from "./types.js";
4
+ import { listTopicFiles, parseTopicBullets, readNowBlock, setTopicSummary, summarizeProject } from "../content/summarize.js";
5
+ /**
6
+ * Summaries written by the agent itself.
7
+ *
8
+ * phren can write the "## Now" block of a topic archive structurally, and a
9
+ * configured model can write prose. Most people run phren inside an agent
10
+ * that already is a capable model, with no API key and no local runtime: these
11
+ * two tools let that agent do the writing — read the bullets, hand back a
12
+ * paragraph — under the same rule a model's paragraph gets: it may not name
13
+ * anything the bullets do not. The /phren-summarize skill drives them.
14
+ */
15
+ function resolve(ctx, projectInput, mode = "write") {
16
+ try {
17
+ return { ok: true, value: resolveStoreForProject(ctx, projectInput, mode) };
18
+ }
19
+ catch (err) {
20
+ return { ok: false, error: err instanceof Error ? err.message : String(err) };
21
+ }
22
+ }
23
+ export function register(server, ctx) {
24
+ server.registerTool("get_topic_summaries", {
25
+ title: "◆ phren · topic summaries",
26
+ description: "What each topic archive of a project amounts to: every reference/topics file with its bullet count, its current '## Now' text and whether that text is structural or prose. " +
27
+ "Pass `topic` to also get that topic's newest bullets, the raw material for writing its paragraph yourself (see /phren-summarize).",
28
+ inputSchema: z.object({
29
+ project: z.string().describe("Project name, optionally store-qualified."),
30
+ topic: z.string().optional().describe("A topic slug from the list; returns its newest bullets."),
31
+ bullets: z.number().int().min(5).max(200).optional().describe("How many of the newest bullets to return for `topic`. Defaults to 60."),
32
+ }),
33
+ }, async ({ project: projectInput, topic, bullets }) => {
34
+ const target = resolve(ctx, projectInput, "read");
35
+ if (!target.ok)
36
+ return mcpResponse({ ok: false, error: target.error });
37
+ const { phrenPath, project } = target.value;
38
+ const files = listTopicFiles(phrenPath, project);
39
+ const topics = files.map(({ slug, file }) => {
40
+ const content = fs.readFileSync(file, "utf8");
41
+ const parsed = parseTopicBullets(content);
42
+ const now = readNowBlock(content);
43
+ return { topic: slug, bullets: parsed.length, now: now?.text ?? null, structural: now ? now.structural : true, archive: parsed.length > 0 };
44
+ });
45
+ if (!topic) {
46
+ const archives = topics.filter((t) => t.archive);
47
+ return mcpResponse({
48
+ ok: true,
49
+ message: archives.length
50
+ ? `${project}: ${archives.length} topic archive(s), ${archives.filter((t) => !t.structural).length} with a written paragraph.`
51
+ : `${project} has no topic archives yet.`,
52
+ data: { project, topics },
53
+ });
54
+ }
55
+ const chosen = files.find((f) => f.slug === topic);
56
+ if (!chosen)
57
+ return mcpResponse({ ok: false, error: `No topic "${topic}" in ${project}. Topics: ${files.map((f) => f.slug).join(", ") || "none"}.` });
58
+ const parsed = parseTopicBullets(fs.readFileSync(chosen.file, "utf8"));
59
+ const newest = [...parsed].reverse().slice(0, bullets ?? 60).map((b) => ({ date: b.date, tag: b.tag, text: b.text }));
60
+ return mcpResponse({
61
+ ok: true,
62
+ message: `${project}/${topic}: ${parsed.length} archived bullets, newest ${newest.length} below. Write 4–6 plain sentences using only what they state; name nothing they do not name.`,
63
+ data: { project, topic, total: parsed.length, bullets: newest },
64
+ });
65
+ });
66
+ server.registerTool("set_topic_summary", {
67
+ title: "◆ phren · set topic summary",
68
+ description: "Store the paragraph you wrote for a topic archive as its '## Now' block, and refresh the project's 'What phren knows' block. " +
69
+ "Refused if the paragraph names anything the topic's bullets do not (the invented names are returned) — fix the paragraph rather than the check.",
70
+ inputSchema: z.object({
71
+ project: z.string().describe("Project name, optionally store-qualified."),
72
+ topic: z.string().describe("Topic slug, as listed by get_topic_summaries."),
73
+ text: z.string().min(40).describe("Four to six plain sentences. Only facts the bullets state; names spelled as the bullets spell them."),
74
+ }),
75
+ }, async ({ project: projectInput, topic, text }) => {
76
+ const target = resolve(ctx, projectInput, "write");
77
+ if (!target.ok)
78
+ return mcpResponse({ ok: false, error: target.error });
79
+ const { phrenPath, project } = target.value;
80
+ const chosen = listTopicFiles(phrenPath, project).find((f) => f.slug === topic);
81
+ if (!chosen)
82
+ return mcpResponse({ ok: false, error: `No topic "${topic}" in ${project}.` });
83
+ return ctx.withWriteQueue(async () => {
84
+ const result = setTopicSummary(chosen.file, text);
85
+ if (!result.ok) {
86
+ if ("invented" in result)
87
+ return mcpResponse({ ok: false, error: `Refused: the paragraph names things the bullets do not: ${result.invented.join(", ")}. Remove or rename them and try again.`, data: { invented: result.invented } });
88
+ return mcpResponse({ ok: false, error: result.error });
89
+ }
90
+ const summary = await summarizeProject(phrenPath, project, {});
91
+ try {
92
+ ctx.updateFileInIndex(chosen.file);
93
+ }
94
+ catch { /* index refresh is best-effort */ }
95
+ return mcpResponse({ ok: true, message: `Stored the paragraph for ${project}/${topic}${summary.summaryUpdated ? " and refreshed summary.md" : ""}.`, data: { project, topic, summaryUpdated: summary.summaryUpdated } });
96
+ });
97
+ });
98
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@phren/cli",
3
- "version": "0.2.6",
3
+ "version": "0.2.8",
4
4
  "description": "Knowledge layer for AI agents — CLI, MCP server, and data layer",
5
5
  "type": "module",
6
6
  "bin": {
@@ -24,7 +24,7 @@ Worth saving: decisions and why, pitfalls with the fix, patterns that worked, me
24
24
 
25
25
  ## Skills
26
26
 
27
- `/phren-sync`, `/phren-init`, `/phren-discover`, `/phren-consolidate`, `/phren-profiles` manage the store. Your own skills live in `~/.phren/global/skills/` and are listed by `phren skills list`; invoke them by name rather than expecting them to appear as memory.
27
+ `/phren-sync`, `/phren-init`, `/phren-discover`, `/phren-consolidate`, `/phren-profiles`, `/phren-summarize` manage the store. Your own skills live in `~/.phren/global/skills/` and are listed by `phren skills list`; invoke them by name rather than expecting them to appear as memory.
28
28
 
29
29
  ## Team agents
30
30
 
@@ -0,0 +1,23 @@
1
+ ---
2
+ name: phren-summarize
3
+ description: Write the "what we know" paragraph for each topic archive yourself, from the bullets phren hands you, using the model you are already running as. No API key, no local model.
4
+ ---
5
+ # /phren-summarize
6
+
7
+ Findings age out of `FINDINGS.md` into `reference/topics/<topic>.md`, hundreds of bullets per topic. phren keeps a `## Now` block at the top of each file saying what the topic amounts to, and a `What phren knows` block in `summary.md` that the prompt hook injects once per session. phren can write those structurally (counts, tags, newest headlines). This skill has *you* write the prose version, with the model you are already running as.
8
+
9
+ ## What to do
10
+
11
+ 1. Pick the scope: one project (`/phren-summarize <project>`), or every project in this machine's profile (`phren_admin(action: "list_projects")`).
12
+ 2. For each project, `phren_admin(action: "get_topic_summaries", project)`. You get every topic archive with its bullet count, the current `## Now` text, and whether it is structural or already prose.
13
+ 3. For each topic that is structural (or `--force`), `phren_admin(action: "get_topic_summaries", project, topic, bullets: 60)` returns the newest sixty bullets. Read them. Write **one paragraph of four to six plain sentences** saying what is currently known: standing decisions, pitfalls that still apply, patterns in use.
14
+ - Use only facts stated in the bullets. Do not name a language, library, file or component unless a bullet names it, spelled as the bullet spells it. If the bullets do not support a sentence, leave it out.
15
+ - No preamble, no bullet points, no headings. Concrete beats general.
16
+ 4. `phren_admin(action: "set_topic_summary", project, topic, text)`. phren checks every identifier in your paragraph against the bullets and refuses one that names something they do not; fix the paragraph rather than arguing with the check. On success phren also refreshes the project's `What phren knows` block.
17
+ 5. Report per project: topics written, topics skipped (already prose or empty), any refusals and what you changed.
18
+
19
+ ## Notes
20
+
21
+ - Topics with no archived bullets are hand-written reference docs. Leave them alone; phren skips them too.
22
+ - This is idempotent: a topic keeps your paragraph until its bullets change (phren fingerprints the file), then falls back to structural until you run this again.
23
+ - Machines with a GPU and a local model can do the same unattended with `phren maintain summarize --llm`; the same identifier check applies.