@hadooppei/hwcode 1.0.6 → 1.0.8

package/.pi/lib/knowledge/extractor.ts

@@ -0,0 +1,35 @@
+import { createHash } from "node:crypto";
+
+import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.ts";
+
+export const KNOWLEDGE_EXTRACTION_SYSTEM_PROMPT = `You are HWCode's background knowledge reviewer.
+Review only the supplied conversation delta. Return strict JSON and no markdown.
+Persist only knowledge that is likely to be useful in future sessions:
+- explicit user corrections or stable preferences;
+- verified engineering rules, successful procedures, or expensive failed approaches;
+- reusable architecture, testing, debugging, deployment, or operational knowledge.
+Do not persist task summaries, guesses, temporary IDs, credentials, secrets, private data, or facts recoverable by simply reading the repository.
+Use storageHint "rule" only for short, precise, high-value instructions. Use "topic" for multi-step SOPs and detailed experience.
+Use action "revise" only when the delta explicitly corrects prior knowledge; otherwise use "add" or "reinforce".
+Scope may be "global" only for an explicit user directive intended across projects; otherwise use "project".
+Return: {"candidates":[{"key":"stable semantic key","title":"...","summary":"...","keywords":["..."],"scope":"global|project","body":"markdown body","evidence":["verified evidence"],"confidence":0.0,"storageHint":"rule|topic","action":"add|reinforce|revise","explicitUserDirective":false}]}
+Return {"candidates":[]} when nothing meets the threshold.`;
+
+export function buildKnowledgeExtractionPrompt(projectRoot: string, delta: string): string {
+  return `Project root: ${projectRoot}\n\n<conversation_delta>\n${delta}\n</conversation_delta>`;
+}
+
+export function parseCandidateEnvelope(text: string): unknown[] {
+  const trimmed = text.trim();
+  const unfenced = trimmed.replace(/^```(?:json)?\s*/iu, "").replace(/\s*```$/u, "");
+  const start = unfenced.indexOf("{");
+  const end = unfenced.lastIndexOf("}");
+  if (start < 0 || end <= start) throw new Error("Knowledge reviewer did not return a JSON object");
+  const parsed = JSON.parse(unfenced.slice(start, end + 1)) as { candidates?: unknown };
+  if (!Array.isArray(parsed.candidates)) throw new Error("Knowledge reviewer response is missing candidates[]");
+  return parsed.candidates.slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxCandidates);
+}
+
+export function knowledgeDeltaDigest(delta: string): string {
+  return createHash("sha256").update(delta).digest("hex");
+}

package/.pi/lib/knowledge/matcher.ts

@@ -0,0 +1,122 @@
+import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.ts";
+import type { KnowledgeCatalog, KnowledgeCatalogEntry } from "./types.ts";
+
+const MAX_QUERY_TERMS = 64;
+const HAN_RUN = /^\p{Script=Han}+$/u;
+
+interface SearchField {
+  compact: string;
+  terms: Set<string>;
+}
+
+function normalizeSearchText(value: string): string {
+  return value
+    .normalize("NFKC")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, " ")
+    .trim()
+    .replace(/\s+/gu, " ");
+}
+
+function searchTerms(value: string): string[] {
+  const normalized = normalizeSearchText(value);
+  const terms = new Set<string>();
+  for (const segment of normalized.match(/\p{Script=Han}+|[\p{L}\p{N}]+/gu) ?? []) {
+    if (segment.length < 2) continue;
+    terms.add(segment);
+    if (HAN_RUN.test(segment) && segment.length > 2) {
+      for (let index = 0; index < segment.length - 1; index += 1) {
+        terms.add(segment.slice(index, index + 2));
+      }
+    }
+    if (terms.size >= MAX_QUERY_TERMS) break;
+  }
+  return [...terms].slice(0, MAX_QUERY_TERMS);
+}
+
+function searchField(value: string): SearchField {
+  const normalized = normalizeSearchText(value);
+  return {
+    compact: normalized.replace(/\s+/gu, ""),
+    terms: new Set(searchTerms(normalized)),
+  };
+}
+
+function supportsPartialMatch(term: string): boolean {
+  return HAN_RUN.test(term) ? term.length >= 2 : term.length >= 3;
+}
+
+function fieldMatch(term: string, field: SearchField): "exact" | "partial" | undefined {
+  if (field.terms.has(term)) return "exact";
+  if (!supportsPartialMatch(term)) return undefined;
+  if (field.compact.includes(term)) return "partial";
+  for (const candidate of field.terms) {
+    if (!supportsPartialMatch(candidate)) continue;
+    if (term.includes(candidate) || candidate.includes(term)) return "partial";
+  }
+  return undefined;
+}
+
+function containsSearchPhrase(container: string, phrase: string): boolean {
+  return supportsPartialMatch(phrase) && container.includes(phrase);
+}
+
+function phraseScore(query: string, title: SearchField, summary: SearchField, keywords: SearchField[]): number {
+  if (query.length < 2) return 0;
+  if (keywords.some((keyword) => keyword.compact === query)) return 18;
+  if (title.compact === query) return 14;
+  if (keywords.some((keyword) => (
+    containsSearchPhrase(keyword.compact, query) || containsSearchPhrase(query, keyword.compact)
+  ))) return 10;
+  if (containsSearchPhrase(title.compact, query) || containsSearchPhrase(query, title.compact)) return 8;
+  if (containsSearchPhrase(summary.compact, query)) return 4;
+  return 0;
+}
+
+/**
+ * Cheaply recalls plausible catalog entries. The agent sees these entries and
+ * remains responsible for deciding whether a detailed topic is actually relevant.
+ */
+export function matchKnowledge(
+  query: string,
+  catalog: KnowledgeCatalog,
+  limit = KNOWLEDGE_RUNTIME_DEFAULTS.storage.maxLookupResults,
+): KnowledgeCatalogEntry[] {
+  const normalizedQuery = normalizeSearchText(query);
+  const compactQuery = normalizedQuery.replace(/\s+/gu, "");
+  const terms = searchTerms(normalizedQuery);
+  if (terms.length === 0 || limit <= 0) return [];
+
+  return catalog.items
+    .map((item) => {
+      const title = searchField(item.title);
+      const summary = searchField(item.summary);
+      const keywords = item.keywords.map(searchField);
+      let score = phraseScore(compactQuery, title, summary, keywords);
+      let matchedTerms = 0;
+
+      for (const term of terms) {
+        const keywordMatch = keywords.some((keyword) => fieldMatch(term, keyword) === "exact")
+          ? "exact"
+          : keywords.some((keyword) => fieldMatch(term, keyword) === "partial") ? "partial" : undefined;
+        const titleMatch = fieldMatch(term, title);
+        const summaryMatch = fieldMatch(term, summary);
+        const termScore = Math.max(
+          keywordMatch === "exact" ? 10 : keywordMatch === "partial" ? 7 : 0,
+          titleMatch === "exact" ? 7 : titleMatch === "partial" ? 5 : 0,
+          summaryMatch === "exact" ? 3 : summaryMatch === "partial" ? 1 : 0,
+        );
+        if (termScore > 0) {
+          score += termScore;
+          matchedTerms += 1;
+        }
+      }
+
+      score += (matchedTerms / terms.length) * 6;
+      return { item, score };
+    })
+    .filter(({ score }) => score > 0)
+    .sort((left, right) => right.score - left.score || right.item.updatedAt.localeCompare(left.item.updatedAt))
+    .slice(0, limit)
+    .map(({ item }) => item);
+}

package/.pi/lib/knowledge/review-worker.ts

@@ -0,0 +1,64 @@
+import { parentPort } from "node:worker_threads";
+
+import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.ts";
+import { parseCandidateEnvelope } from "./extractor.ts";
+import { persistKnowledgeCandidates } from "./store.ts";
+import type { KnowledgeWorkerInput, KnowledgeWorkerOutput } from "./worker-protocol.ts";
+
+if (!parentPort) throw new Error("Knowledge review worker requires a parent port");
+
+let sessionId = "";
+let projectKey = "";
+let dirty = false;
+let settled = false;
+let reviewing = false;
+let activeRequestId = "";
+
+function send(message: KnowledgeWorkerOutput): void {
+  parentPort!.postMessage(message);
+}
+
+function checkForReview(): void {
+  if (!sessionId || !projectKey || !dirty || !settled || reviewing) return;
+  reviewing = true;
+  activeRequestId = `${sessionId}-${Date.now()}`;
+  send({ type: "review_due", requestId: activeRequestId });
+}
+
+const timer = setInterval(checkForReview, KNOWLEDGE_RUNTIME_DEFAULTS.review.intervalMs);
+timer.unref();
+
+parentPort.on("message", (message: KnowledgeWorkerInput) => {
+  if (message.type === "configure") {
+    sessionId = message.sessionId;
+    projectKey = message.projectKey;
+    dirty = message.dirty;
+    settled = true;
+    reviewing = false;
+    activeRequestId = "";
+    return;
+  }
+  if (message.type === "activity") {
+    settled = message.state === "settled";
+    if (message.dirty !== undefined) dirty = message.dirty;
+    return;
+  }
+  if (message.type === "review_result") {
+    if (!reviewing || message.requestId !== activeRequestId) return;
+    try {
+      if (message.error || message.raw === undefined) throw new Error(message.error || "Knowledge review returned no content");
+      const candidates = parseCandidateEnvelope(message.raw);
+      const result = persistKnowledgeCandidates(candidates, projectKey);
+      dirty = false;
+      send({ type: "review_saved", requestId: message.requestId, result });
+    } catch (error) {
+      send({ type: "review_failed", requestId: message.requestId, error: error instanceof Error ? error.message : String(error) });
+    } finally {
+      reviewing = false;
+      activeRequestId = "";
+    }
+    return;
+  }
+  clearInterval(timer);
+  process.exit(0);
+});

package/.pi/lib/knowledge/sanitize.ts

@@ -0,0 +1,26 @@
+const PRIVATE_KEY_RE = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/giu;
+const BEARER_RE = /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/giu;
+const JWT_RE = /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/gu;
+const SECRET_ASSIGNMENT_RE = /\b(access[_-]?key|secret(?:[_-]?(?:access|key))?|password|passwd|token|credential|client[_-]?secret)\b(\s*[:=]\s*)[^\s,;]+/giu;
+const URL_CREDENTIAL_RE = /(https?:\/\/)[^\s/@:]+:[^\s/@]+@/giu;
+
+export function sanitizeKnowledgeText(value: string): string {
+  return value
+    .replace(PRIVATE_KEY_RE, "<redacted-private-key>")
+    .replace(BEARER_RE, "Bearer <redacted>")
+    .replace(JWT_RE, "<redacted-jwt>")
+    .replace(SECRET_ASSIGNMENT_RE, (_match, key: string, separator: string) => `${key}${separator}<redacted>`)
+    .replace(URL_CREDENTIAL_RE, "$1<redacted>@")
+    .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/giu, "<runtime-uuid>")
+    .replace(/\b(?:\d{1,3}\.){3}\d{1,3}\b/gu, "<runtime-ip>")
+    .replace(/\b(vpc|subnet|secgroup|sg|vol|snap|img|inst|eip)-[0-9a-zA-Z]+/gu, "<$1-runtime-id>")
+    .replace(/\/(?:Users|home)\/[a-zA-Z0-9_-]+/gu, "~");
+}
+
+export function compactKnowledgeText(value: string, maxChars: number): string {
+  return sanitizeKnowledgeText(value)
+    .replace(/\r\n/gu, "\n")
+    .replace(/[ \t]+$/gmu, "")
+    .trim()
+    .slice(0, maxChars);
+}

package/.pi/lib/knowledge/store.ts

@@ -0,0 +1,251 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve, sep } from "node:path";
+
+import { KNOWLEDGE_RUNTIME_DEFAULTS } from "../runtime/defaults.ts";
+import { userRuntimePaths } from "../runtime/paths.ts";
+import { compactKnowledgeText, sanitizeKnowledgeText } from "./sanitize.ts";
+import type {
+  KnowledgeCandidate, KnowledgeCatalog, KnowledgeCatalogEntry, KnowledgeScope,
+  KnowledgeSnapshot, KnowledgeTrack, PersistKnowledgeResult,
+} from "./types.ts";
+
+const STORAGE = KNOWLEDGE_RUNTIME_DEFAULTS.storage;
+const EMPTY_CATALOG = (): KnowledgeCatalog => ({ version: 2, updatedAt: new Date().toISOString(), items: [] });
+const SAFE_ID_RE = /^[a-z0-9][a-z0-9-]{0,79}$/u;
+
+function ensureDirectory(path: string): void {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  chmodSync(path, 0o700);
+}
+
+function atomicWrite(path: string, content: string): void {
+  ensureDirectory(dirname(path));
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  writeFileSync(temporary, content, { encoding: "utf8", mode: 0o600 });
+  renameSync(temporary, path);
+  chmodSync(path, 0o600);
+}
+
+export function ensureKnowledgeDirectories(home = homedir()): void {
+  const paths = userRuntimePaths(home);
+  for (const path of [paths.knowledge, paths.knowledgeRules, paths.knowledgeTopics, paths.knowledgePending]) {
+    ensureDirectory(path);
+  }
+}
+
+export function projectKnowledgeKey(projectRoot: string): string {
+  return createHash("sha256").update(resolve(projectRoot)).digest("hex").slice(0, 16);
+}
+
+export function loadKnowledgeCatalog(home = homedir()): KnowledgeCatalog {
+  const path = userRuntimePaths(home).knowledgeCatalog;
+  if (!existsSync(path)) return EMPTY_CATALOG();
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as KnowledgeCatalog;
+    if (parsed.version === 2 && Array.isArray(parsed.items)) return parsed;
+  } catch {
+    // The active schema never falls back to legacy index.json or records/ data.
+  }
+  return EMPTY_CATALOG();
+}
+
+function saveCatalog(catalog: KnowledgeCatalog, home: string): void {
+  catalog.updatedAt = new Date().toISOString();
+  atomicWrite(userRuntimePaths(home).knowledgeCatalog, `${JSON.stringify(catalog, null, 2)}\n`);
+}
+
+function normalizeSlug(value: string): string {
+  return value.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/gu, "-")
+    .replace(/^-+|-+$/gu, "").slice(0, STORAGE.slugMaxChars) || "knowledge";
+}
+
+function normalizedFingerprint(candidate: KnowledgeCandidate): string {
+  return createHash("sha256").update(`${candidate.scope}\0${candidate.key.trim().toLowerCase()}`).digest("hex");
+}
+
+function contentHash(candidate: KnowledgeCandidate): string {
+  return createHash("sha256").update(`${candidate.title}\0${candidate.summary}\0${candidate.body}`).digest("hex");
+}
+
+function asStringArray(value: unknown, maxItems: number): string[] {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.filter((item): item is string => typeof item === "string")
+    .map((item) => compactKnowledgeText(item, 240)).filter(Boolean))].slice(0, maxItems);
+}
+
+function normalizeCandidate(value: unknown, projectKey: string): KnowledgeCandidate | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const raw = value as Record<string, unknown>;
+  if (typeof raw.key !== "string" || typeof raw.title !== "string" || typeof raw.summary !== "string"
+    || typeof raw.body !== "string" || typeof raw.confidence !== "number") return undefined;
+  if (raw.confidence < KNOWLEDGE_RUNTIME_DEFAULTS.review.minimumConfidence) return undefined;
+  const storageHint: KnowledgeTrack = raw.storageHint === "rule" ? "rule" : "topic";
+  const explicitUserDirective = raw.explicitUserDirective === true;
+  const requestedScope = raw.scope === "global" ? "global" : `project:${projectKey}`;
+  const scope: KnowledgeScope = requestedScope === "global" && explicitUserDirective ? "global" : `project:${projectKey}`;
+  const body = compactKnowledgeText(raw.body, 20_000);
+  const evidence = asStringArray(raw.evidence, 8);
+  if (!body || evidence.length === 0) return undefined;
+  const ruleEligible = body.length <= STORAGE.maxRuleChars
+    && body.split("\n").length <= STORAGE.maxRuleFileLines
+    && (explicitUserDirective || raw.confidence >= 0.9);
+  return {
+    key: compactKnowledgeText(raw.key, 160),
+    title: compactKnowledgeText(raw.title, STORAGE.maxTitleChars),
+    summary: compactKnowledgeText(raw.summary, STORAGE.maxSummaryChars),
+    keywords: asStringArray(raw.keywords, STORAGE.maxKeywordCount).map((keyword) => keyword.toLowerCase()),
+    scope,
+    body,
+    evidence,
+    confidence: Math.min(1, raw.confidence),
+    storageHint: storageHint === "rule" && ruleEligible ? "rule" : "topic",
+    action: raw.action === "revise" ? "revise" : raw.action === "reinforce" ? "reinforce" : "add",
+    explicitUserDirective,
+  };
+}
+
+function renderKnowledgeFile(candidate: KnowledgeCandidate): string {
+  if (candidate.storageHint === "rule") return `# ${candidate.title}\n\n${candidate.body}\n`;
+  return [
+    `# ${candidate.title}`,
+    "",
+    candidate.summary,
+    "",
+    `Keywords: ${candidate.keywords.join(", ")}`,
+    "",
+    candidate.body,
+    "",
+    "## Evidence",
+    "",
+    ...candidate.evidence.map((item) => `- ${item}`),
+    "",
+  ].join("\n");
+}
+
+function storedRuleCharacters(home: string): number {
+  const directory = userRuntimePaths(home).knowledgeRules;
+  if (!existsSync(directory)) return 0;
+  return readdirSync(directory, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+    .reduce((total, entry) => total + readFileSync(join(directory, entry.name), "utf8").length, 0);
+}
+
+function savePending(candidate: KnowledgeCandidate, reason: string, home: string): void {
+  const paths = userRuntimePaths(home);
+  const name = `${Date.now()}-${normalizeSlug(candidate.title)}-${randomUUID().slice(0, 8)}.json`;
+  atomicWrite(join(paths.knowledgePending, name), `${JSON.stringify({ reason, candidate, createdAt: new Date().toISOString() }, null, 2)}\n`);
+}
+
+function generateMemory(catalog: KnowledgeCatalog, projectKey?: string): string {
+  const lines = [
+    "# HWCode Knowledge Index",
+    "",
+    "Detailed topics are loaded only through hwcode_knowledge_lookup. Search by ID or keywords.",
+    "",
+  ];
+  const topics = catalog.items.filter((item) => item.track === "topic" && (!projectKey || applicable(item, projectKey)))
+    .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+  for (const item of topics) {
+    const scope = item.scope === "global" ? "global" : "project";
+    const line = `- [${item.id}] (${scope}; ${item.keywords.join(", ")}) ${item.title}: ${item.summary}`;
+    if (lines.length + 1 >= STORAGE.maxMemoryLines || [...lines, line].join("\n").length > STORAGE.maxMemoryChars) {
+      lines.push("- Additional topics remain searchable through hwcode_knowledge_lookup(query: \"keywords\").");
+      break;
+    }
+    lines.push(line);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function writeMemory(catalog: KnowledgeCatalog, home: string): void {
+  atomicWrite(userRuntimePaths(home).knowledgeMemory, generateMemory(catalog));
+}
+
+export function persistKnowledgeCandidates(
+  values: unknown[],
+  projectKey: string,
+  home = homedir(),
+): PersistKnowledgeResult {
+  ensureKnowledgeDirectories(home);
+  const catalog = loadKnowledgeCatalog(home);
+  const result: PersistKnowledgeResult = { saved: 0, updated: 0, pending: 0, skipped: 0 };
+  for (const value of values.slice(0, KNOWLEDGE_RUNTIME_DEFAULTS.review.maxCandidates)) {
+    const candidate = normalizeCandidate(value, projectKey);
+    if (!candidate) { result.skipped++; continue; }
+    const fingerprint = normalizedFingerprint(candidate);
+    const hash = contentHash(candidate);
+    const existingIndex = catalog.items.findIndex((item) => item.fingerprint === fingerprint);
+    const existing = existingIndex >= 0 ? catalog.items[existingIndex] : undefined;
+    if (existing?.contentHash === hash) {
+      existing.evidenceCount += candidate.evidence.length;
+      existing.updatedAt = new Date().toISOString();
+      result.updated++;
+      continue;
+    }
+    if (existing && !(candidate.action === "revise" && (candidate.explicitUserDirective || candidate.confidence >= 0.92))) {
+      savePending(candidate, "conflicting-or-ambiguous-update", home);
+      result.pending++;
+      continue;
+    }
+    if (!existing && candidate.storageHint === "rule"
+      && storedRuleCharacters(home) + renderKnowledgeFile(candidate).length > STORAGE.maxRulesPromptChars) {
+      candidate.storageHint = "topic";
+    }
+    const now = new Date().toISOString();
+    const id = existing?.id ?? `${normalizeSlug(candidate.title)}-${fingerprint.slice(0, 8)}`;
+    const track = existing?.track ?? candidate.storageHint;
+    candidate.storageHint = track;
+    const relativeFile = `${track === "rule" ? "rules" : "topics"}/${id}.md`;
+    const absoluteFile = join(userRuntimePaths(home).knowledge, relativeFile);
+    atomicWrite(absoluteFile, renderKnowledgeFile(candidate));
+    const entry: KnowledgeCatalogEntry = {
+      id, fingerprint, contentHash: hash, title: candidate.title, summary: candidate.summary,
+      keywords: candidate.keywords, scope: candidate.scope, track, file: relativeFile,
+      evidenceCount: (existing?.evidenceCount ?? 0) + candidate.evidence.length,
+      createdAt: existing?.createdAt ?? now, updatedAt: now,
+    };
+    if (existingIndex >= 0) { catalog.items[existingIndex] = entry; result.updated++; }
+    else { catalog.items.push(entry); result.saved++; }
+  }
+  saveCatalog(catalog, home);
+  writeMemory(catalog, home);
+  return result;
+}
+
+function applicable(entry: KnowledgeCatalogEntry, projectKey: string): boolean {
+  return entry.scope === "global" || entry.scope === `project:${projectKey}`;
+}
+
+function readCatalogFile(entry: KnowledgeCatalogEntry, home: string): string | undefined {
+  if (!SAFE_ID_RE.test(entry.id) || basename(entry.file) !== `${entry.id}.md`) return undefined;
+  const root = resolve(userRuntimePaths(home).knowledge);
+  const path = resolve(root, entry.file);
+  if (!path.startsWith(`${root}${sep}`) || !existsSync(path)) return undefined;
+  return sanitizeKnowledgeText(readFileSync(path, "utf8"));
+}
+
+export function loadKnowledgeSnapshot(projectKey: string, home = homedir()): KnowledgeSnapshot {
+  ensureKnowledgeDirectories(home);
+  const catalog = loadKnowledgeCatalog(home);
+  const ruleParts: string[] = [];
+  const paths = userRuntimePaths(home);
+  for (const file of readdirSync(paths.knowledgeRules, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md")).sort((left, right) => left.name.localeCompare(right.name))) {
+    const relativeFile = `rules/${file.name}`;
+    const entry = catalog.items.find((item) => item.file === relativeFile);
+    if (entry && !applicable(entry, projectKey)) continue;
+    ruleParts.push(sanitizeKnowledgeText(readFileSync(join(paths.knowledgeRules, file.name), "utf8")).trim());
+  }
+  const memoryPrompt = generateMemory(catalog, projectKey);
+  return { rulesPrompt: ruleParts.join("\n\n"), memoryPrompt, catalog };
+}
+
+export function loadKnowledgeById(id: string, projectKey: string, home = homedir()): { entry: KnowledgeCatalogEntry; content: string } | undefined {
+  if (!SAFE_ID_RE.test(id)) return undefined;
+  const entry = loadKnowledgeCatalog(home).items.find((item) => item.id === id && applicable(item, projectKey));
+  if (!entry) return undefined;
+  const content = readCatalogFile(entry, home);
+  return content ? { entry, content } : undefined;
+}

package/.pi/lib/knowledge/types.ts

@@ -0,0 +1,59 @@
+export type KnowledgeTrack = "rule" | "topic";
+export type KnowledgeScope = "global" | `project:${string}`;
+export type KnowledgeAction = "add" | "reinforce" | "revise";
+
+export interface KnowledgeCandidate {
+  key: string;
+  title: string;
+  summary: string;
+  keywords: string[];
+  scope: KnowledgeScope;
+  body: string;
+  evidence: string[];
+  confidence: number;
+  storageHint: KnowledgeTrack;
+  action: KnowledgeAction;
+  explicitUserDirective: boolean;
+}
+
+export interface KnowledgeCatalogEntry {
+  id: string;
+  fingerprint: string;
+  contentHash: string;
+  title: string;
+  summary: string;
+  keywords: string[];
+  scope: KnowledgeScope;
+  track: KnowledgeTrack;
+  file: string;
+  evidenceCount: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface KnowledgeCatalog {
+  version: 2;
+  updatedAt: string;
+  items: KnowledgeCatalogEntry[];
+}
+
+export interface KnowledgeSnapshot {
+  rulesPrompt: string;
+  memoryPrompt: string;
+  catalog: KnowledgeCatalog;
+}
+
+export interface KnowledgeReviewState {
+  version: 1;
+  lastReviewedEntryId?: string;
+  lastReviewedAt?: string;
+  lastDeltaDigest?: string;
+  lastResult?: "saved" | "noop";
+}
+
+export interface PersistKnowledgeResult {
+  saved: number;
+  updated: number;
+  pending: number;
+  skipped: number;
+}

package/.pi/lib/knowledge/worker-protocol.ts

@@ -0,0 +1,12 @@
+import type { PersistKnowledgeResult } from "./types.ts";
+
+export type KnowledgeWorkerInput =
+  | { type: "configure"; sessionId: string; projectKey: string; dirty: boolean }
+  | { type: "activity"; state: "busy" | "settled"; dirty?: boolean }
+  | { type: "review_result"; requestId: string; raw?: string; error?: string }
+  | { type: "stop" };
+
+export type KnowledgeWorkerOutput =
+  | { type: "review_due"; requestId: string }
+  | { type: "review_saved"; requestId: string; result: PersistKnowledgeResult }
+  | { type: "review_failed"; requestId: string; error: string };

package/.pi/lib/runtime/defaults.ts

@@ -18,3 +18,31 @@ export const CLOUD_RUNTIME_DEFAULTS = Object.freeze({
   templates: Object.freeze({ slugMaxLength: 48, nameMaxLength: 80 }),
   terraform: Object.freeze({ executable: "terraform", planFile: "hwcode.tfplan" }),
 });
+
+/**
+ * Defaults for the cross-workflow knowledge base (`~/.hwcode/knowledge/`).
+ *
+ * A Worker checks settled sessions on a fixed interval. Short rules are loaded
+ * in full; detailed topics are routed through a bounded MEMORY.md index so the
+ * prompt cost stays stable as the complete machine catalog grows.
+ */
+export const KNOWLEDGE_RUNTIME_DEFAULTS = Object.freeze({
+  review: Object.freeze({
+    intervalMs: 60_000,
+    maxDeltaChars: 30_000,
+    maxCandidates: 3,
+    minimumConfidence: 0.72,
+  }),
+  storage: Object.freeze({
+    maxRuleChars: 600,
+    maxRuleFileLines: 40,
+    maxRulesPromptChars: 12_000,
+    maxMemoryChars: 25_000,
+    maxMemoryLines: 200,
+    maxSummaryChars: 180,
+    maxTitleChars: 100,
+    maxKeywordCount: 12,
+    maxLookupResults: 5,
+    slugMaxChars: 64,
+  }),
+});