@phren/cli 0.2.7 → 0.2.9

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.
@@ -91,6 +91,31 @@ export interface ProjectSummary {
91
91
  }
92
92
  /** Summarize every topic file of a project and refresh the "What phren knows" block in summary.md. */
93
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
+ };
94
119
  /** The "What phren knows" block of a project, for the hook to inject; null when absent. */
95
120
  export declare function readKnowsBlock(phrenPath: string, project: string): {
96
121
  path: string;
@@ -365,6 +365,47 @@ export async function summarizeProject(phrenPath, project, opts = {}) {
365
365
  atomicWriteText(summaryPath, next);
366
366
  return { project, topics: results, summaryPath, summaryUpdated: changed };
367
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
+ }
368
409
  /** The "What phren knows" block of a project, for the hook to inject; null when absent. */
369
410
  export function readKnowsBlock(phrenPath, project) {
370
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.7",
3
+ "version": "0.2.9",
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.