GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Proposal: optional `durability: durable | volatile` frontmatter field for GC/compaction hints
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## Proposal
Optional frontmatter field `durability: durable | volatile`.
## Meaning
- **`durable`** — concept should persist across bundle cleanups. Fundamental facts, standing decisions, invariants.
- **`volatile`** — concept is time-boxed; safe to prune during garbage collection or context compaction. Session summaries, migration notes, in-flight state.
- **absent** — no assertion; consumers treat as durable by default (backward-compatible).
## Why not covered by existing fields
- **`confidence` (#151)** — epistemic grade. Orthogonal: a `high` confidence fact can still be `volatile` (correct-but-time-boxed).
- **`lifecycle` from #160** — describes verification transitions (`proposed → active → expired`). Orthogonal: a `volatile` concept can be `active` its entire lifetime.
- **`status: active|deprecated|draft`** — describes publication state. Orthogonal.
- **`timestamp`** — records when written; consumers can't distinguish "old but durable" from "old and expired."
## Concrete gap
An agent doing context compaction over a bundle needs to answer: "if I evict this concept, do I lose institutional knowledge or ephemeral state?" Currently the only signal is guessing from `type` / path / age.
## Adopter data
828 concept files at [chirag127/workspace/knowledge/](https://github.com/chirag127/workspace/tree/main/knowledge) ship this field optionally as of 2026-07-03. Public bundle: [knowledge.oriz.in](https://knowledge.oriz.in).
## Proposed SPEC.md addition (§4.1 Frontmatter, Extensions block)
```yaml
durability: durable | volatile # optional; controls GC/compaction eligibility. Absent = durable.
```
Backwards-compatible — no existing bundle breaks. Consumers ignoring the field keep prior behavior.
## Not-in-scope
- Prescribing WHEN to run GC.
- Prescribing tooling to detect volatility.
- Overlapping with lifecycle (#160) — orthogonal axes.
Thanks for the great work on OKF!
Contributor guide
Research direction
Start with SPEC.md §4.1, especially the Frontmatter and Extensions sections, and review the issue's distinctions from confidence, lifecycle, status, and timestamp. Done means the proposal has a maintainer-approved specification for the optional field, its default behavior, and its relationship to GC/compaction without expanding the stated scope.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100