@hasna/hook-knowledge-context 0.1.5 → 0.1.6

package/README.md

@@ -34,7 +34,9 @@ text from that pack and emits Codewith-native
 `hookSpecificOutput.additionalContext` with the same event name. Citation-only
 packs are expanded into progressive context lines with bounded previews and a
 single `knowledge get --id <item_id> --json` hint so agents can decide which
-full items are worth opening.
+full items are worth opening. Items that mark themselves as
+historical/reference-only or not suitable for auto-loading are filtered out by
+default, because they are not useful ambient context for normal agent work.
 
 Example injected context:
 
@@ -55,7 +57,8 @@ bad stdin, or empty packs return `{"continue":true}` without context.
 export HOOKS_KNOWLEDGE_CONTEXT_DISABLE=1    # Kill switch
 export HOOKS_KNOWLEDGE_COMMAND=knowledge    # CLI command/path
 export HOOKS_KNOWLEDGE_TIMEOUT_MS=5000      # Per-call timeout
-export HOOKS_KNOWLEDGE_MAX_ITEMS=3          # Context pack item budget
+export HOOKS_KNOWLEDGE_MAX_ITEMS=3          # Rendered item budget
+export HOOKS_KNOWLEDGE_CANDIDATE_ITEMS=12   # Internal candidate budget before filtering
 export HOOKS_KNOWLEDGE_MAX_TOKENS=1200      # Context pack token budget
 export HOOKS_KNOWLEDGE_REQUIRE_HIGH_SIGNAL=1
 export HOOKS_KNOWLEDGE_MIN_PROMPT_CHARS=6

package/dist/hook.d.ts

@@ -31,6 +31,7 @@ export interface KnowledgeContextConfig {
     command: string;
     timeoutMs: number;
     maxItems: number;
+    candidateItems: number;
     maxTokens: number;
     minPromptChars: number;
     minSignalScore: number;
@@ -54,7 +55,11 @@ export declare function buildQuery(input: HookInput, config: KnowledgeContextCon
 export declare function buildKnowledgeArgs(query: string, config: KnowledgeContextConfig): string[];
 export declare function spawnKnowledgeContextPack(query: string, config: KnowledgeContextConfig): Promise<KnowledgeExecResult>;
 export declare function truncate(text: string, max: number): string;
-export declare function extractContextText(pack: unknown): string | null;
+interface ExtractContextOptions {
+    maxItems?: number;
+    includeHistorical?: boolean;
+}
+export declare function extractContextText(pack: unknown, options?: ExtractContextOptions): string | null;
 export declare function formatAdditionalContext(event: KnowledgeContextEvent, context: string, config: KnowledgeContextConfig): string;
 export declare function buildHookOutput(input: HookInput | null, executor?: KnowledgeExecutor, env?: NodeJS.ProcessEnv): Promise<HookOutput>;
 export declare function run(): Promise<void>;

package/dist/hook.js

@@ -41,10 +41,12 @@ function commandFromEnv(raw) {
   return "knowledge";
 }
 function getConfig(env = process.env) {
+  const maxItems = boundedNumber(env.HOOKS_KNOWLEDGE_MAX_ITEMS, DEFAULT_MAX_ITEMS, 1, 20);
   return {
     command: commandFromEnv(env.HOOKS_KNOWLEDGE_COMMAND),
     timeoutMs: boundedNumber(env.HOOKS_KNOWLEDGE_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, 100, 1e4),
-    maxItems: boundedNumber(env.HOOKS_KNOWLEDGE_MAX_ITEMS, DEFAULT_MAX_ITEMS, 1, 20),
+    maxItems,
+    candidateItems: boundedNumber(env.HOOKS_KNOWLEDGE_CANDIDATE_ITEMS, Math.min(20, Math.max(maxItems, maxItems * 4)), maxItems, 20),
     maxTokens: boundedNumber(env.HOOKS_KNOWLEDGE_MAX_TOKENS, DEFAULT_MAX_TOKENS, 100, 8000),
     minPromptChars: boundedNumber(env.HOOKS_KNOWLEDGE_MIN_PROMPT_CHARS, DEFAULT_MIN_PROMPT_CHARS, 0, 4000),
     minSignalScore: boundedNumber(env.HOOKS_KNOWLEDGE_MIN_SIGNAL_SCORE, DEFAULT_MIN_SIGNAL_SCORE, 1, 10),
@@ -147,7 +149,7 @@ function buildKnowledgeArgs(query, config) {
     "--from",
     "search",
     "--max-items",
-    String(config.maxItems),
+    String(config.candidateItems),
     "--max-tokens",
     String(config.maxTokens),
     "--json"
@@ -232,13 +234,24 @@ function knowledgeItemId(source) {
   const legacyPath = source?.match(/(?:^|\/)(k_[A-Za-z0-9]+_[A-Za-z0-9]+)(?:[?#].*)?$/);
   return legacyPath?.[1] ?? null;
 }
-function formatPackItems(items) {
+var NON_AUTOLOADABLE_HISTORY_RE = /\b(historical\/reference only|historical reference only|should not be auto-?loaded|do not auto-?load|not an active startup instruction|brain orchestration startup files)\b/i;
+var ARCHIVED_STARTUP_RE = /^Archived on \d{4}-\d{2}-\d{2}\b.*\b(startup context|startup files|CLAUDE\.md)\b/i;
+function shouldSuppressKnowledgeItem(text, options) {
+  if (options.includeHistorical)
+    return false;
+  const compact = compactText(text);
+  return NON_AUTOLOADABLE_HISTORY_RE.test(compact) || ARCHIVED_STARTUP_RE.test(compact);
+}
+function formatPackItems(items, options = {}) {
   const lines = [];
   let hasKnowledgeItems = false;
+  const maxItems = options.maxItems ?? DEFAULT_MAX_ITEMS;
   for (const [index, item] of items.entries()) {
+    if (lines.length >= maxItems)
+      break;
     if (typeof item === "string" && item.trim()) {
       const text = cleanStringItem(item);
-      if (text)
+      if (text && !shouldSuppressKnowledgeItem(text, options))
         lines.push(`- ${truncate(text, 900)}`);
       continue;
     }
@@ -263,6 +276,9 @@ function formatPackItems(items) {
     ]);
     if (!body && !source)
       continue;
+    const itemText = [title, body, source].filter(Boolean).join(" ");
+    if (shouldSuppressKnowledgeItem(itemText, options))
+      continue;
     if (itemId) {
       hasKnowledgeItems = true;
       const labelParts = [`item_id=${itemId}`];
@@ -291,12 +307,19 @@ function formatPackItems(items) {
   ].join(`
 `);
 }
-function extractContextText(pack) {
+function shouldIncludeHistoricalItems(input) {
+  const prompt = `${stringField(input, "prompt")} ${stringField(input, "user_prompt")}`;
+  return /\b(archive|archived|historical|history|reference-only|reference only|old startup|startup files|CLAUDE\.md)\b/i.test(prompt);
+}
+function extractContextText(pack, options = {}) {
   if (typeof pack === "string") {
-    return cleanLegacyEmptyBullet(pack.trim()) || null;
+    const text = cleanLegacyEmptyBullet(pack.trim());
+    if (!text || shouldSuppressKnowledgeItem(text, options))
+      return null;
+    return text;
   }
   if (Array.isArray(pack)) {
-    return formatPackItems(pack);
+    return formatPackItems(pack, options);
   }
   if (!pack || typeof pack !== "object") {
     return null;
@@ -304,15 +327,15 @@ function extractContextText(pack) {
   const obj = pack;
   const direct = firstString(obj, ["additionalContext", "context", "markdown", "content", "text", "summary"]);
   if (direct)
-    return direct;
+    return shouldSuppressKnowledgeItem(direct, options) ? null : direct;
   for (const key of ["pack", "contextPack", "context_pack", "data", "result"]) {
     const nested = obj[key];
-    const text = extractContextText(nested);
+    const text = extractContextText(nested, options);
     if (text)
       return text;
   }
   const items = firstArray(obj, ["items", "results", "sources", "citations"]);
-  return items ? formatPackItems(items) : null;
+  return items ? formatPackItems(items, options) : null;
 }
 function formatAdditionalContext(event, context, config) {
   const header = `[hook-knowledge-context] Knowledge matches (${event}; top ${config.maxItems}, deterministic search):`;
@@ -346,7 +369,10 @@ async function buildHookOutput(input, executor = spawnKnowledgeContextPack, env
       return { continue: true };
     }
     const parsed = JSON.parse(result.stdout);
-    const context = extractContextText(parsed);
+    const context = extractContextText(parsed, {
+      maxItems: config.maxItems,
+      includeHistorical: shouldIncludeHistoricalItems(input)
+    });
     if (!context) {
       return { continue: true };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hook-knowledge-context",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Codewith hook that injects deterministic Knowledge context packs into lifecycle events",
   "type": "module",
   "main": "./dist/hook.js",