portable-agent-layer 0.92.0 → 0.94.0

package/README.md

@@ -208,7 +208,9 @@ PAL ships with built-in skills that extend your agent's capabilities:
 | `presentation` | Build branded slide decks from outlines |
 | `projects` | Look up, resume, register, or manage tracked projects |
 | `reflect` | Diagnose why a PAL behavior didn't trigger |
-| `rule-review` | Approve or deny the rules PAL drafted from your corrections || `telos` | Inspect or update goals, beliefs, strategies, narratives |
+| `research-entity` | Research a company or person on the web: links, registry entry, recent news |
+| `rule-review` | Approve or deny the rules PAL drafted from your corrections |
+| `telos` | Inspect or update goals, beliefs, strategies, narratives |
 | `think` | Structured first-pass reasoning on a problem |
 
 ---

package/assets/schema/pal-settings.schema.json

@@ -98,6 +98,18 @@
           "type": "boolean",
           "description": "Let the rules you approved from your past corrections steer the agent: a rule triggered by your prompt is injected before the agent answers, and a reply that matches a rule's trigger is sent back to the agent once at stop. Each firing is logged to memory/adaptation/rule-events.jsonl. Set false to switch every rule off. Reply-side rules do not run on Cursor, whose stop payload carries no reply text, or on opencode, whose plugin does not run the stop check."
         },
+        "entityCards": {
+          "type": "boolean",
+          "description": "When a prompt names a person or company from the knowledge store, inject a short card about them before the agent answers. Reads files only; no model call."
+        },
+        "entityExtraction": {
+          "type": "boolean",
+          "description": "After a session stops, ask a background model which people and companies your own messages mentioned, and write clear matches and new full names to the knowledge store with the message as source. A name that could be more than one entry, or a first name alone, waits for `pal cli knowledge review` instead."
+        },
+        "entityResearch": {
+          "type": "boolean",
+          "description": "Opt-in, off by default. When extraction creates a company, or a person with a known organization, research it on the web through the active agent (up to three per stop): website, LinkedIn, social accounts, the company registry entry, recent news, each with its source. A profile the model is sure of waits in `pal cli knowledge review`; accepting writes it to the entry. The name and what you said about it reach the agent's web search. Claude Code, Codex and Copilot only. Needs entityExtraction."
+        },
         "steeringTestReport": { "type": "boolean", "description": "When true, the assistant notes to the user which steering self-check fired. For the dual-live test period; ships false." }
       }
     },

package/assets/skills/research-entity/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: research-entity
+license: MIT
+description: "Research one company or person on the web and build a sourced profile: official website, LinkedIn, social accounts, the company registry entry (cégjegyzék for Hungarian companies), and recent news or statements. Use when the user asks to research, look up, profile, or background-check a specific company or person, or to enrich a knowledge-store entry."
+argument-hint: <company or person name> [what you know about them]
+metadata:
+  source: portable-agent-layer
+  triggers:
+    - "research-entity"
+    - "research entity"
+    - "research this company"
+    - "research this person"
+    - "look up the company"
+    - "company background"
+    - "background check"
+    - "cégjegyzék"
+---
+
+Research the company or person named in $ARGUMENTS and show a sourced profile. The research runs through `pal cli knowledge research`, which picks the active agent's web search and limits it to searching and reading pages. Never research with your own tools instead: the command is what keeps the result in the same shape on every agent.
+
+## Workflow
+
+1. Work out from $ARGUMENTS and the conversation:
+   - the exact name;
+   - whether it is a company or a person;
+   - for a person, where they work;
+   - one sentence of what the user said about them.
+   If you cannot tell a company from a person, ask.
+2. Run the research. For a company:
+   ```bash
+   pal cli knowledge research "<name>" --context "<what the user said>"
+   ```
+   For a person, add `--person` and, when known, `--organization "<employer>"`:
+   ```bash
+   pal cli knowledge research "<name>" --person --organization "<employer>" --context "<what the user said>"
+   ```
+   It takes one to several minutes. Add `--queue` when the user wants the profile saved; it then waits in the review queue.
+3. If the command exits 1, tell the user the reason it printed. Usual reasons:
+   - the model found only namesakes (`match: unsure`): ask for something that tells them apart, such as an employer, a city or a website, and run it again with that in `--context` or `--organization`;
+   - nothing was found (`match: none`);
+   - the active agent cannot search the web yet.
+4. If it succeeds, show the profile it printed as it is. Do not add facts it did not print.
+5. If you queued it, tell the user the review command it printed: `pal cli knowledge review accept <id>` writes the profile to the entry, and `pal cli knowledge review reject <id>` drops it.
+
+## Output format
+
+The profile as printed: summary, links, registry, news and sources. Then one line saying whether it was queued for review, with the accept command.
+
+## When to use
+
+- The user names a specific company or person and wants to know who they are, or their website, LinkedIn, accounts, registry data or recent news.
+- The user wants an entry in the knowledge store filled in from the web.
+
+## Do NOT use
+
+- To pull every person and company out of an article, video or paste. Use `entities` for that.
+- For a broad topic, market or question rather than one named entity. Use `deep-research` for that.

package/assets/templates/pal-settings.json

@@ -33,6 +33,9 @@
     "claimCheck": true,
     "claimCheckBlocks": false,
     "adaptationRules": true,
+    "entityCards": true,
+    "entityExtraction": true,
+    "entityResearch": false,
     "steeringTestReport": false
   },
   "steering": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.92.0",
+  "version": "0.94.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/infer.ts

@@ -18,6 +18,7 @@ interface InferValues {
   schema?: string;
   timeout?: string;
   caller?: string;
+  web?: boolean;
 }
 
 type Infer = typeof inference;
@@ -81,6 +82,7 @@ function requestFrom(values: InferValues, stdin: string): Parameters<Infer>[0] {
     tier: tierOf(values.tier),
     timeout: timeoutMs(values.timeout),
     caller: values.caller ?? "cli-infer",
+    web: values.web ?? false,
   };
 }
 
@@ -137,6 +139,10 @@ export const inferCommand = leaf({
       value: "<label>",
       description: "Label for PAL's debug log",
     },
+    web: {
+      type: "boolean",
+      description: "Let the model search and read the web (Claude, Codex, Copilot)",
+    },
   },
   run: async ({ values }) => inferFromCli(values, await Bun.stdin.text()),
 });

package/src/cli/knowledge-research.ts

@@ -0,0 +1,93 @@
+/**
+ * pal cli knowledge research — research one person or company on the web through
+ * the active agent, print the profile, and optionally queue it for review.
+ */
+
+import { loadKnownEntities, loadNameIndex } from "../hooks/lib/entity-cards";
+import { queueForReview } from "../hooks/lib/entity-extraction";
+import { lookupName } from "../hooks/lib/entity-names";
+import {
+  type ResearchDeps,
+  type ResearchTarget,
+  renderProfile,
+  researchEntity,
+  researchItem,
+} from "../hooks/lib/entity-research";
+import { inference } from "../hooks/lib/inference";
+import { identity } from "../hooks/lib/settings";
+import { leaf, UsageError } from "../tools/lib/command";
+
+interface ResearchValues {
+  person?: boolean;
+  organization?: string;
+  context?: string;
+  queue?: boolean;
+  json?: boolean;
+}
+
+function storedSlug(name: string, kind: ResearchTarget["kind"]): string {
+  const domain = kind === "person" ? "People" : "Companies";
+  const { entities, exact } = lookupName(name, loadNameIndex(loadKnownEntities()));
+  const matches = entities.filter((e) => e.domain === domain);
+  return exact && matches.length === 1 ? matches[0].slug : "";
+}
+
+function targetFrom(name: string, values: ResearchValues): ResearchTarget {
+  const kind = values.person ? "person" : "company";
+  return {
+    kind,
+    name,
+    slug: storedSlug(name, kind),
+    organization: values.organization ?? "",
+    fact: values.context ?? "",
+  };
+}
+
+export async function researchFromCli(
+  name: string | undefined,
+  values: ResearchValues,
+  deps: ResearchDeps = { principal: identity().principal.name, infer: inference }
+): Promise<number> {
+  if (!name?.trim()) throw new UsageError("name the person or company to research");
+  const target = targetFrom(name.trim(), values);
+  const outcome = await researchEntity(target, deps);
+  if (!outcome.found) {
+    console.error(`Nothing kept for "${target.name}": ${outcome.reason}`);
+    return 1;
+  }
+  console.log(
+    values.json
+      ? JSON.stringify(outcome.profile, null, 2)
+      : renderProfile(outcome.profile)
+  );
+  if (values.queue) {
+    const item = researchItem(target, outcome.profile);
+    queueForReview([item]);
+    console.log(`\nQueued for review: pal cli knowledge review accept ${item.id}`);
+  }
+  return 0;
+}
+
+export const researchCommand = leaf({
+  summary: "Research a company (or --person) on the web: links, registry, news",
+  args: "<name>",
+  options: {
+    person: { type: "boolean", description: "Research a person, not a company" },
+    organization: {
+      type: "string",
+      value: "<name>",
+      description: "Where the person works, to tell namesakes apart",
+    },
+    context: {
+      type: "string",
+      value: "<text>",
+      description: "What you know about them, to tell namesakes apart",
+    },
+    queue: {
+      type: "boolean",
+      description: "Also queue the profile for `pal cli knowledge review`",
+    },
+    json: { type: "boolean", description: "Print the profile as JSON" },
+  },
+  run: ({ positionals, values }) => researchFromCli(positionals.join(" "), values),
+});

package/src/cli/knowledge.ts

@@ -6,6 +6,14 @@
  */
 
 import { readFileSync } from "node:fs";
+import type { ReviewItem } from "../hooks/lib/entity-extraction";
+import { renderProfile } from "../hooks/lib/entity-research";
+import {
+  type AcceptChoice,
+  acceptReview,
+  pendingReviews,
+  rejectReview,
+} from "../hooks/lib/entity-review";
 import { toPath } from "../hooks/lib/paths";
 import { buildGraph, resolveSlug, stats, traverse } from "../tools/knowledge/graph";
 import {
@@ -27,6 +35,7 @@ import {
   type Status,
 } from "../tools/knowledge/lib";
 import { group, leaf, runCommand, UsageError } from "../tools/lib/command";
+import { researchCommand } from "./knowledge-research";
 
 const VOCABULARY = `Domains: ${DOMAINS.join(", ")}
 Relation types: ${RELATION_TYPES.join(", ")}`;
@@ -113,6 +122,37 @@ export const knowledgeCommand = group({
       },
       run: ({ values }) => cmdIngest(values.source ?? "manual", values.file),
     }),
+    research: researchCommand,
+    review: group({
+      summary: "People and companies the background extractor would not guess",
+      fallback: "list",
+      commands: {
+        list: leaf({ summary: "Show what waits for an answer", run: cmdReviewList }),
+        accept: leaf({
+          summary: "Write an item, to an existing entry (--as) or a new one",
+          args: "<id>",
+          options: {
+            as: {
+              type: "string",
+              value: "<slug>",
+              description: "Existing entry to update",
+            },
+            name: {
+              type: "string",
+              value: "<name>",
+              description: "Name for a new entry (default: as extracted)",
+            },
+          },
+          run: ({ positionals, values }) =>
+            cmdReviewAccept(positionals[0], { as: values.as, name: values.name }),
+        }),
+        reject: leaf({
+          summary: "Drop an item without writing it",
+          args: "<id>",
+          run: ({ positionals }) => cmdReviewReject(positionals[0]),
+        }),
+      },
+    }),
   },
   details: VOCABULARY,
 });
@@ -578,3 +618,73 @@ async function cmdIngest(sourceId: string, file: string | undefined): Promise<nu
   console.log(JSON.stringify(summary, null, 2));
   return 0;
 }
+
+// ── review ─────────────────────────────────────────────────────────
+
+function reviewReason(reason: ReviewItem["reason"]): string {
+  const reasons: Record<ReviewItem["reason"], string> = {
+    ambiguous: "could be more than one known entry",
+    "unknown-existing": "named an entry the store does not have",
+    "first-name-only": "first name only",
+    "web-profile": "found on the web",
+  };
+  return reasons[reason];
+}
+
+function reviewDetails(item: ReviewItem): string[] {
+  if (item.profile)
+    return [
+      item.entity.existing ? `for ${item.entity.existing}` : "as a new entry",
+      ...renderProfile(item.profile).split("\n"),
+    ];
+  const candidates =
+    item.candidates.length > 0 ? [`could be: ${item.candidates.join(", ")}`] : [];
+  return [item.entity.fact, ...candidates, `from ${item.source}`];
+}
+
+function reviewLines(item: ReviewItem): string[] {
+  const { kind, name } = item.entity;
+  return [
+    `  ${item.id}  ${kind} "${name}" — ${reviewReason(item.reason)}`,
+    ...reviewDetails(item)
+      .filter(Boolean)
+      .map((line) => `            ${line}`),
+  ];
+}
+
+function cmdReviewList(): number {
+  const items = pendingReviews();
+  if (items.length === 0) {
+    console.log("Nothing waits for review.");
+    return 0;
+  }
+  console.log(`\n${items.length} waiting for review\n`);
+  for (const item of items) console.log(reviewLines(item).join("\n"));
+  console.log(
+    "\nAccept: pal cli knowledge review accept <id> [--as <slug>] [--name <name>]\nReject: pal cli knowledge review reject <id>\n"
+  );
+  return 0;
+}
+
+function acceptOrExplain(id: string, choice: AcceptChoice) {
+  try {
+    return acceptReview(id, choice);
+  } catch (err) {
+    throw new UsageError(err instanceof Error ? err.message : String(err));
+  }
+}
+
+function cmdReviewAccept(id: string, choice: AcceptChoice): number {
+  const accepted = acceptOrExplain(id, choice);
+  if (!accepted) throw new UsageError(`no review item "${id}"`);
+  const verb = accepted.created ? "Created" : "Updated";
+  console.log(`${verb} ${accepted.slug} from "${accepted.item.entity.name}".`);
+  return 0;
+}
+
+function cmdReviewReject(id: string): number {
+  const rejected = rejectReview(id);
+  if (!rejected) throw new UsageError(`no review item "${id}"`);
+  console.log(`Dropped "${rejected.entity.name}".`);
+  return 0;
+}

package/src/hooks/handlers/entity-extraction.ts

@@ -0,0 +1,92 @@
+/**
+ * Stop handler: learn the people and companies the user mentioned since the last
+ * stop, so the prompt-time cards know them next time, and research the new ones on
+ * the web for review. Runs detached; one extraction call, only when the new text
+ * names someone, and one web research call per new entry.
+ */
+
+import { ingestEntities } from "../../tools/knowledge/ingest";
+import { excludedNames, loadKnownEntities, loadNameIndex } from "../lib/entity-cards";
+import {
+  extractionSchema,
+  extractionSystem,
+  extractionUser,
+  markSeen,
+  parseExtraction,
+  planExtraction,
+  queueForReview,
+  seenCount,
+  unseenUserText,
+  worthExtracting,
+} from "../lib/entity-extraction";
+import { newResearchTargets, researchNewEntities } from "../lib/entity-research";
+import { canInfer, inference } from "../lib/inference";
+import { logDebug, logError } from "../lib/log";
+import { identity, isEnabled, isOptedIn } from "../lib/settings";
+import { logTokenUsage } from "../lib/token-usage";
+import { parseMessages } from "../lib/transcript";
+
+function sourceId(sessionId: string, count: number): string {
+  return `chat ${new Date().toISOString().slice(0, 10)} ${sessionId.slice(0, 8)} #${count}`;
+}
+
+/** @lintignore exercised directly by test/entity-extraction.test.ts */
+export async function extractSessionEntities(
+  transcript: string,
+  sessionId?: string
+): Promise<void> {
+  if (!sessionId || !isEnabled("entityExtraction")) return;
+  const seen = seenCount(sessionId);
+  const { text, count } = unseenUserText(parseMessages(transcript), seen);
+  if (count <= seen) return;
+
+  const index = loadNameIndex(loadKnownEntities());
+  const excluded = excludedNames();
+  markSeen(sessionId, count);
+  if (!worthExtracting(text, index, excluded) || !canInfer()) return;
+
+  const id = identity();
+  const result = await inference({
+    system: extractionSystem(id.principal.name, id.ai.name),
+    user: extractionUser(text, index),
+    tier: "medium",
+    maxTokens: 900,
+    timeout: 90000,
+    jsonSchema: extractionSchema(),
+    caller: "entity-extraction",
+    sessionId,
+  });
+  if (result.usage) logTokenUsage("entity-extraction", result.usage);
+  if (!result.success || !result.output) return;
+
+  const source = sourceId(sessionId, count);
+  const plan = planExtraction(parseExtraction(result.output), index, excluded, source);
+  const written = ingestEntities(plan.ingest, source);
+  queueForReview(plan.review);
+  logDebug(
+    "entity-extraction",
+    `${written.people.length} people, ${written.companies.length} companies, ${plan.review.length} for review`
+  );
+  if (isOptedIn("entityResearch"))
+    await researchNewEntities(newResearchTargets(plan.ingest, written), {
+      principal: id.principal.name,
+      infer: inference,
+    });
+}
+
+if (process.argv[2] === "--run") {
+  const sid = process.argv[3];
+  const transcriptPath = process.argv[4];
+  if (transcriptPath) {
+    const { readFile, unlink } = await import("node:fs/promises");
+    try {
+      const transcript = await readFile(transcriptPath, "utf-8");
+      await extractSessionEntities(transcript, sid === "" ? undefined : sid);
+    } catch (err) {
+      logError("entity-extraction:run", err);
+    } finally {
+      await unlink(transcriptPath).catch(() => {});
+    }
+  }
+  process.exit(0);
+}

package/src/hooks/handlers/inject-retrieval.ts

@@ -10,6 +10,7 @@
 import { promptRulesReminder } from "../lib/adaptation-steering";
 import { promptContextResponse } from "../lib/agent";
 import { dueNudgeReminder } from "../lib/daily-nudge";
+import { getEntityReminder } from "../lib/entity-cards";
 import { observeTurn } from "../lib/interaction";
 import { logDebug, logError } from "../lib/log";
 import { parkPromptContext } from "../lib/parked-context";
@@ -91,6 +92,9 @@ export async function getPromptContext(
     withinBudget(() => dueNudgeReminder(), BUDGET_MS),
     userText && getSteeringReminder(userText),
     userText && getSkillReminder(userText),
+    userText &&
+      isEnabled("entityCards") &&
+      withinBudget(() => getEntityReminder(userText), BUDGET_MS),
     userText && (await getRetrievalReminder(userText)),
   ].filter((p): p is string => Boolean(p));
 

package/src/hooks/lib/daily-nudge.ts

@@ -3,9 +3,10 @@ import { resolve } from "node:path";
 import { loadReflectNudge } from "../handlers/reflect-trigger";
 import { loadAlgorithmReviewNudge } from "./algorithm-review";
 import { loadAnalyzeNudge } from "./analyze-nudge";
+import { loadEntityReviewNudge } from "./entity-review";
 import { ensureDir, paths } from "./paths";
 import { loadReactionAuditNudge } from "./reaction-audit";
-import { isOptedIn } from "./settings";
+import { isEnabled, isOptedIn } from "./settings";
 import { localDay } from "./wall-clock";
 
 type ShownOn = Record<string, string>;
@@ -14,6 +15,7 @@ interface DueNudge {
   key: string;
   command: string;
   load: () => string;
+  enabled?: () => boolean;
 }
 
 const DUE_NUDGES: DueNudge[] = [
@@ -27,6 +29,27 @@ const DUE_NUDGES: DueNudge[] = [
   { key: "analyze", command: "/pal-analyze", load: loadAnalyzeNudge },
 ];
 
+function entityReviewNudge(): DueNudge {
+  return {
+    key: "entity-review",
+    command: "pal cli knowledge review",
+    load: loadEntityReviewNudge,
+    enabled: () => isEnabled("entityExtraction"),
+  };
+}
+
+function dueNudges(): DueNudge[] {
+  return [...DUE_NUDGES, entityReviewNudge()];
+}
+
+function dueRemindersOn(): boolean {
+  return isOptedIn("dueReminders");
+}
+
+function isSwitchedOn(nudge: DueNudge): boolean {
+  return (nudge.enabled ?? dueRemindersOn)();
+}
+
 function shownPath(): string {
   return resolve(ensureDir(paths.state()), "nudges-shown.json");
 }
@@ -53,7 +76,7 @@ export function pendingToday(
 }
 
 export function acknowledgeMentioned(reply: string, now: Date = new Date()): void {
-  const mentioned = DUE_NUDGES.filter((nudge) => reply.includes(nudge.command));
+  const mentioned = dueNudges().filter((nudge) => reply.includes(nudge.command));
   if (!mentioned.length) return;
   const today = localDay(now);
   const shownOn = readShownOn();
@@ -62,10 +85,10 @@ export function acknowledgeMentioned(reply: string, now: Date = new Date()): voi
 }
 
 export function dueNudgeSections(now: Date = new Date()): string[] {
-  if (!isOptedIn("dueReminders")) return [];
-  return DUE_NUDGES.map((nudge) => pendingToday(nudge.key, nudge.load(), now)).filter(
-    Boolean
-  );
+  return dueNudges()
+    .filter(isSwitchedOn)
+    .map((nudge) => pendingToday(nudge.key, nudge.load(), now))
+    .filter(Boolean);
 }
 
 export function dueNudgeReminder(now: Date = new Date()): string | null {

package/src/hooks/lib/entity-cards.ts

@@ -0,0 +1,112 @@
+/**
+ * Prompt-time cards for the people and companies a prompt names, so the user
+ * never has to re-explain who someone is. Reads files only; no model call.
+ */
+
+import { type Entity, list } from "../../tools/knowledge/lib";
+import {
+  buildNameIndex,
+  entityKey,
+  findMentions,
+  type Mention,
+  type NamedEntity,
+  type NameIndex,
+} from "./entity-names";
+import { identity } from "./settings";
+
+const MAX_CARDS = 3;
+const MAX_LATEST = 160;
+
+function stringList(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((v): v is string => typeof v === "string")
+    : [];
+}
+
+function textField(entity: Entity, key: string): string {
+  const value = entity.frontmatter[key];
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function namedEntity(entity: Entity): NamedEntity {
+  return {
+    slug: entity.slug,
+    domain: entity.domain === "Companies" ? "Companies" : "People",
+    title: entity.frontmatter.title,
+    aliases: stringList(entity.frontmatter.aliases),
+    domainName: textField(entity, "domain_name") || undefined,
+  };
+}
+
+export function loadKnownEntities(rootDir?: string): Entity[] {
+  return [...list("People", rootDir), ...list("Companies", rootDir)];
+}
+
+export function excludedNames(): string[] {
+  const id = identity();
+  return [id.principal.name, id.ai.name];
+}
+
+export function loadNameIndex(entities: Entity[]): NameIndex {
+  return buildNameIndex(entities.map(namedEntity), excludedNames());
+}
+
+function isSourceLine(line: string): boolean {
+  return (
+    line.startsWith("### ") ||
+    line.startsWith("<!--") ||
+    /^(?:role|importance|mentioned_as|sentiment): /.test(line)
+  );
+}
+
+/** The newest thing the store learned about this entity, in a sentence or two. */
+export function latestNote(body: string): string {
+  const sections = body.split(/\n(?=### )/);
+  const text = (sections.at(-1) ?? "")
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l && !isSourceLine(l))
+    .join(" ")
+    .replace(/\*\*/g, "");
+  return text.length > MAX_LATEST ? `${text.slice(0, MAX_LATEST - 1)}…` : text;
+}
+
+function describe(entity: Entity): string {
+  const fields =
+    entity.domain === "People"
+      ? [
+          textField(entity, "position") || textField(entity, "role"),
+          textField(entity, "company"),
+        ]
+      : [textField(entity, "industry")];
+  const facts = [...fields, textField(entity, "relation")].filter(
+    (f) => f && f !== "subject"
+  );
+  const latest = latestNote(entity.body);
+  return [facts.join(", "), latest].filter(Boolean).join(". ");
+}
+
+function card(mention: Mention, bySlug: Map<string, Entity>): string {
+  if (mention.entities.length > 1) {
+    const names = mention.entities.map((e) => e.title).join(", ");
+    return `- "${mention.said}" could be: ${names}. Ask which one if it matters.`;
+  }
+  const entity = bySlug.get(entityKey(mention.entities[0]));
+  const summary = entity ? describe(entity) : "";
+  const name = `- **${mention.entities[0].title}**`;
+  return summary ? `${name}: ${summary}` : name;
+}
+
+export function entityReminder(prompt: string, entities: Entity[]): string | null {
+  const mentions = findMentions(prompt, loadNameIndex(entities)).slice(0, MAX_CARDS);
+  if (mentions.length === 0) return null;
+  const bySlug = new Map(entities.map((e) => [entityKey(e), e]));
+  return [
+    "**Known people and companies in this message** (PAL knowledge store):",
+    ...mentions.map((m) => card(m, bySlug)),
+  ].join("\n");
+}
+
+export function getEntityReminder(prompt: string): string | null {
+  return entityReminder(prompt, loadKnownEntities());
+}