feat: TTL-cached team-knowledge index (no clone required)#63
Merged
Conversation
Makes the session-start awareness ping (and a future /knowledge consult) work for anyone with gh auth, not just people who cloned the repo and set KNOWLEDGE_REPO_PATH. Mirrors the codex-verdict cache pattern: - src/lib/knowledge-index.ts: refreshKnowledgeIndex() fetches the corpus listing via gh api at most once per 6h TTL, writes ~/.claude/tmp/knowledge-index.json; readKnowledgeIndex() reads it instantly. Fully fail-open — no gh / network error returns the existing cache, never clobbers good data, never throws. - src/scripts/refresh-knowledge-index.ts: detached entrypoint session-start spawns fire-and-forget (TTL-gated internally, so it only calls gh when stale). - teamKnowledgeAwareness() now prefers the cache (no clone needed); an explicit repoPath still uses the local clone, so it falls back for offline/no-gh users. No second source of truth, no cross-repo token, no vendored index — the cache is per-user, self-refreshing, and never drifts. parseContentsListing + isStale are pure and unit-tested (no network in tests).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
Follow-up to #62. That PR's session-start ping only worked if you'd cloned
team-knowledgeand setKNOWLEDGE_REPO_PATH— which almost nobody does, so for most people it stayed dark. This makes it work for anyone withghauth, no clone and no setup.Instead of vendoring a copy of the index into this repo (which would be a second source of truth that drifts, and would need a cross-repo write token), it caches the corpus listing the same way the Codex bridge caches its verdict: fetch via
gh apiat most once every 6 hours into~/.claude/tmp/knowledge-index.json, read it instantly at session start. The cache is per-user, self-refreshing, and can't drift from the source.Verified end-to-end against the live repo — the refresh populated the cache with the real note set on first run.
Summary
src/lib/knowledge-index.ts—refreshKnowledgeIndex()(TTL-gated, fetchesgh api repos/$KNOWLEDGE_REPO/contentsonly when stale, fail-open: any gh/network/parse error returns the existing cache and never clobbers good data or throws),readKnowledgeIndex(), and pureparseContentsListing/isStalehelpers.src/scripts/refresh-knowledge-index.ts— detached entrypoint that session-start fire-and-forgets (same pattern as the MCP-auth prune); cheap when fresh because the TTL gate lives in the refresh.teamKnowledgeAwareness()now prefers the cache; an explicitrepoPathstill uses a local clone, so offline / no-ghusers withKNOWLEDGE_REPO_PATHkeep working.KNOWLEDGE_REPOenv overrides the defaultdarkroomengineering/team-knowledge.Why not a committed/vendored index
Vendoring would add a derived artifact that drifts from the source (the same bug class as the
MANAGED_SKILLSdrift fixed in #61), and a push-from-team-knowledge sync would need a write credential into this repo. The cache gets the same "every install has the index" benefit with none of that.Test Plan
bun run typecheck— cleanbun test tests/knowledge-index.test.ts tests/team-knowledge.test.ts— 21/21 (pure parse + staleness; existing clone cases preserved)bun test— 615 pass / 0 failbun run lint— cleanbun src/scripts/refresh-knowledge-index.tspopulated the cache with the live corpus listingBranches off
main(has #61 + #62). Standalone.