GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Proposal: optional `durability: durable | volatile` frontmatter field for GC/compaction hints

Open
#172 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.