Repository navigation
Feature: Knowledge library — persistent team-wide storage for research and analysis #413
Description
Problem statement
Squad has four storage tiers: history.md (personal, compacted), decisions.md (team, choices only), skills/ (team, structured patterns), and wisdom.md (team, manual curation). Each serves a specific purpose and has constraints that preserve its focus.
When agents produce substantial work products — architecture redesigns, research reports, competitive analyses, deep audits — those documents get lost over time. A 10KB architecture analysis gets compacted to 3 sentences in history.md. A multi-session research effort vanishes when the session ends. Product docs get rewritten as the product evolves, erasing the original rationale. The team lacks long-term storage for substantial knowledge artifacts that survive compaction, session endings, and documentation rewrites.
Community member @sturlath identified the same pain in #370: "distributed knowledge that is hard to consolidate and read." That issue requests ADRs (architecture decision records) — a valuable use case, but part of a broader need for persistent team-wide knowledge storage.
Proposed solution
Add a .squad/knowledge/ directory as long-term storage for substantial team documents:
- Preserves large work products — research reports, architecture proposals, deep audits, and contextual analysis that would otherwise be lost to compaction or session death
- File naming:
{author}-{topic-slug}.md(e.g.,pao-docs-architecture.md,flight-deployment-patterns.md) - Never compacted — deprecated rather than deleted (prepend
[DEPRECATED YYYY-MM-DD]if obsolete) - Not a dumping ground — minimum ~2KB threshold; small notes belong in history.md or session artifacts
- Brownfield-aware — agents discover where the repo already keeps its documentation and operate there for short-term content;
.squad/knowledge/is only for substantial documents that don't fit anywhere existing - Cold storage, not active memory — files are not loaded at spawn time; agents access them when needed
Relationship to existing features
- Complements (doesn't replace) wisdom.md, skills/, decisions.md — each has a distinct purpose; knowledge library fills the gap for substantial team-relevant analysis
- Keep ADR for historical overview? #370 (ADRs) is one use case — knowledge library is the generalized answer that enables ADRs plus other research/analysis artifacts
- Pluggable Backends for Tasks, History, and Decisions #162 (pluggable backends) — future consideration if squad backends become pluggable
- Decision lifecycle management and archival system #85 (decision lifecycle) — knowledge library prevents
decisions.mdpollution by providing a home for analysis that isn't a decision
Key design decisions
- Long-term storage, not active documentation — product docs, guides, and references belong in the repo's existing docs location; knowledge library is for preserving substantial research and analysis
- Framework convention — provides where/how to store knowledge, not what to store
- Opt-in — empty directory unless team uses it; no forced workflows
- Trust-based — no quality gates on initial write (add later if needed)
- Discovery before creation — agents must discover where the repo already keeps documentation and check existing knowledge sources before writing to avoid duplication
- Substantial work only — research reports, architecture proposals, deep audits, competitive analyses; not small notes or status updates
References
This proposal generalizes the ADR concept requested in #370 into a broader knowledge library that can store ADRs, research findings, analysis, and contextual knowledge. Full proposal: knowledge-library-proposal.md in the project-squad working directory.
Activity
diberry commentedon Mar 15, 2026
@bradygaster Knowledge Library proposal is ready for your review — covers long-term persistence for analysis, research, and architecture work that agents produce. See the full proposal in the issue description. — squad obo dina
bradygaster commentedon Mar 16, 2026
If we can prove this won't cause context bloat in the day-to-day usage I'm cool with it. Basically a knowledge base the Squad could pull from when they need deeper knowledge. Part of me feels like that's GitHub (or "git provider") issues but files-on-disk is fine as well. No objections if we can have the Squad demonstrate/prove it won't negatively impact usability or accuracy.
Visual polish: separators, help, status, agents, thinking indicator (g…
diberry commentedon Mar 16, 2026
Context Bloat Analysis — Knowledge Library
@bradygaster Your concern is valid. Here's what the team found after analyzing the spawn pipeline:
Current State
Squad already loads ~360 KB per agent spawn (charter ~2 KB, history ~24 KB, decisions ~333 KB, skills variable). That's 45-70% of available context budget before any work begins.
The Risk (if done wrong)
Naive loading of knowledge files at spawn would hit catastrophic failure at ~25 files (50 KB). By 80 files, agents would fail on large PRs. By 150 files, the system would be unusable. Silent degradation — the nightmare scenario.
Recommended: Pure On-Demand Loading (Zero Spawn Impact)
How it works:
read_knowledgetool/skillContext budget:
One-liner proof: "If no agent ever requests knowledge, the system behaves identically to today."
On Your GitHub Issues Idea
Hybrid approach works: files as source of truth (fast, offline, version-controlled), optional
squad knowledge publishto sync to Issues for web discoverability. Best of both worlds.Proposed Demo (Hard Numbers, Not Promises)
We're building a PR with the implementation and metrics tests so you can verify yourself. Will link it here when ready.
— squad obo dina
feat: Knowledge library - cold storage with zero spawn impact
feat: Knowledge library - cold storage with zero spawn impact
diberry commentedon Mar 16, 2026
Related: PR #436 adds the extensibility guide which covers how features like the knowledge library should be built as extensions (Layer 2) rather than Squad core. The building extensions guide in the same PR provides the practical tutorial for authoring extensions.
github-actions commentedon Mar 18, 2026
📋 Assigned to Flight (Lead)
Issue: #413 — Feature: Knowledge library — persistent team-wide storage for research and analysis
Flight will pick this up in the next Copilot session.
github-actions commentedon Mar 18, 2026
🏗️ Squad Triage — Flight (Lead)
Issue: #413 — Feature: Knowledge library — persistent team-wide storage for research and analysis
Assigned to: DSKY (TUI Engineer)
Reason: Issue relates to frontend/UI work
@copilot evaluation: 🔴 Not suitable — issue involves work outside the coding agent's capability profile.
Team roster:
squad:flightsquad:proceduressquad:eecomsquad:fidosquad:paosquad:capcomsquad:controlsquad:surgeonsquad:boostersquad:gncsquad:networksquad:retrosquad:incosquad:guidosquad:telemetrysquad:voxsquad:dskysquad:simssquad:handbooksquad:ralphsquad:copilotdiberry commentedon Mar 23, 2026
Closing — not a Squad product addition
This feature (persistent team-wide knowledge storage) isn't an addition to Squad the product. If a user needs knowledge library functionality, it would be built as a user-specific extension — a Squad skill, plugin, or standalone tool tailored to their workflow — not baked into the core framework.
Squad's philosophy is to keep the core lean and let specific capabilities emerge from user needs via the extensibility surface (skills, plugins, MCP integrations).
squad obo dina