bc-knowledge-manager

Caution

KNOWLEDGE.jsonl grows with every task. Duplicate entries, similar patterns across different wordings, and low-priority noise accumulate quickly — the file bloats, compaction at handoff slows, and the most important ❌ entries get buried. The pre-compact.mjs hook fires before every auto-compact, but it can’t help if the file is already in poor shape.

Tip

bc-knowledge-manager runs automatically. The bc-coordinator spawns it before handoff and whenever duplicates are reported. You can also trigger it manually via Task tool with an explicit knowledgePath and mode. It never loses ❌ entries unless they are exact duplicates.

Quick reference

FieldValue
Modelhaiku
ToolsRead, Write
Permission modeacceptEdits
Spawned bybc-coordinator (via Task tool)
TriggersBefore handoff, when duplicates reported by coordinator

When to use

  • Before a session handoff — compact KNOWLEDGE.jsonl so the next session starts with a clean, prioritized file
  • After /brewcode:rules export — run prune-rules mode to strip ❌/✅ entries that have been promoted to rules files
  • When coordinator reports duplicates — deduplicate-only pass with mode: dedupe to keep the file clean mid-task
  • When the file exceeds 100 entries — full compaction removes excess, prioritizing ❌ over ✅ over ℹ️

Examples

# KNOWLEDGE.jsonl entry format
{"ts":"2026-04-17T10:00:00Z","t":"❌","txt":"Avoid SELECT * in queries — causes N+1 on large tables","src":"developer"}
{"ts":"2026-04-17T10:01:00Z","t":"✅","txt":"Use Read then Write (not Edit) for full file rewrites","src":"bc-coordinator"}
{"ts":"2026-04-17T10:02:00Z","t":"ℹ️","txt":"Project uses PostgreSQL 15 with pgvector extension","src":"architect"}
# Spawn via Task tool (full compaction)
Task: bc-knowledge-manager
Prompt: knowledgePath=/abs/path/.claude/tasks/20260417_example_task/KNOWLEDGE.jsonl mode=full maxEntries=100

# Output
Knowledge compaction complete:
- Before: 134 entries
- After: 87 entries
- Removed: 12 duplicates, 21 merged, 14 truncated
- By type: ❌ 31, ✅ 28, ℹ️ 28
- Size: 18420 bytes
# Prune after rules export (prune-rules mode)
Task: bc-knowledge-manager
Prompt: knowledgePath=/abs/path/KNOWLEDGE.jsonl mode=prune-rules

# Output
Pruned 59 entries (❌/✅), kept 28 entries (ℹ️)

Flow

  1. Read

    Reads KNOWLEDGE.jsonl at knowledgePath. File not found or empty — reports and exits without writing.

  2. Parse

    Parses every line as JSON. Malformed lines are skipped and counted separately — they do not halt processing.

  3. Deduplicate & merge

    Removes entries with identical txt. Then merges entries whose txt matches case-insensitively on the first 100 characters — keeps the higher-priority type (❌ wins over ✅ wins over ℹ️).

  4. Sort & truncate

    Sorts by priority (❌ → ✅ → ℹ️), then by timestamp descending. If the entry count exceeds maxEntries (default 100), lowest-priority and oldest entries are dropped first. ❌ entries are never removed unless they were exact duplicates.

  5. Write

    Rewrites the file using Read then Write (never Edit). One valid JSON object per line, original timestamps preserved.

  6. Report

    Returns a statistics block: before/after counts, removed breakdown (duplicates / merged / truncated), by-type counts, and final file size in bytes.

Priority & dedup rules

Entry types (priority order)

TypePriorityMeaning
❌1 — highestAvoid: mistakes, failures, known anti-patterns
✅2Best practice: what works reliably
ℹ️3 — lowestInfo: neutral facts, architecture notes

Dedup matching

Exact match on txt field → remove the lower-priority copy (or older if same priority).

Similar match on first 100 characters of txt (case-insensitive) → merge into one entry, keep higher-priority t value and newer ts.

Merge mode: prune-rules

After /brewcode:rules exports ❌/✅ entries to .claude/rules/ files, run prune-rules to strip them from KNOWLEDGE.jsonl. Only ℹ️ entries survive. This prevents double-loading the same knowledge as both KNOWLEDGE and rules.

Rules frontmatter note

When rules are exported via /brewcode:rules, use paths (array of glob strings) in frontmatter — globs and alwaysApply are not supported. Rules without paths load always; path-specific rules should load lazily (Bug #16299 causes all to load at session start regardless).

🤖

bc-coordinator

Spawns bc-knowledge-manager before handoff and after duplicate reports.

🚀

brewcode:start

Infinite execution skill — triggers compaction via pre-compact.mjs hook at context limit.

🔗

GitHub source

Agent definition and compaction logic.

📄

Brewcode overview

All brewcode skills, agents, and hooks in one place.

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.