Files
waggle-os/apps/web/src/lib/brain-health.ts
Oleg Maslov 0c3e2ead3b
Some checks failed
Installer Smoke / installer-smoke (push) Has been cancelled
moving
2026-09-02 10:10:29 +02:00

105 lines
3.6 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* Brain Health metric — weighted saturation score across memory stats.
*
* Surfaces a single 0-100 signal answering "how much of my brain is
* populated?". Weights reflect relative signal value per dimension:
* - frames (raw captured memory) carries the most quantity (40%)
* - entities (distilled KG nouns) carries mid (30%)
* - relations (KG edges) carries mid (30%)
*
* Each dimension saturates at its target count so no single dimension
* can push the overall score above 100%. Targets are tuned against
* observed counts on a "mature" personal.mind and can be revisited.
*
* Divergence from the M-27 backlog spec:
* The backlog's original formula was (frames × 0.3) + (concepts ×
* 0.4) + (entities × 0.3). `concept_mastery` exists in MindDB schema
* but ConceptTracker isn't wired into the cognify pipeline yet, so
* counting concepts would produce a constant zero. Until that lands,
* we swap the concepts term for relations (which is emitted by the
* KG and already flows through /api/memory/stats). When concepts
* ship, update `BrainHealthCounts` + the formula to match the spec.
*/
export interface BrainHealthCounts {
frames: number;
entities: number;
relations: number;
}
/** Target counts that correspond to 100% saturation per dimension. */
export const HEALTH_TARGETS = {
frames: 10_000,
entities: 500,
relations: 500,
} as const;
/** Weights per dimension — sum to 1. */
export const HEALTH_WEIGHTS = {
frames: 0.4,
entities: 0.3,
relations: 0.3,
} as const;
export type BrainHealthTier = 'empty' | 'sparse' | 'growing' | 'healthy' | 'mature';
export const TIER_LABELS: Record<BrainHealthTier, string> = {
empty: 'Empty',
sparse: 'Sparse',
growing: 'Growing',
healthy: 'Healthy',
mature: 'Mature',
};
/**
* Compute a 0-100 integer Brain Health score from memory counts.
* Negative inputs clamp to 0; counts above the dimension target cap
* that dimension's contribution at its weight.
*/
export function computeBrainHealth(counts: BrainHealthCounts): number {
const frames = Math.max(0, counts.frames ?? 0);
const entities = Math.max(0, counts.entities ?? 0);
const relations = Math.max(0, counts.relations ?? 0);
const framesRatio = Math.min(1, frames / HEALTH_TARGETS.frames);
const entitiesRatio = Math.min(1, entities / HEALTH_TARGETS.entities);
const relationsRatio = Math.min(1, relations / HEALTH_TARGETS.relations);
const score =
framesRatio * HEALTH_WEIGHTS.frames +
entitiesRatio * HEALTH_WEIGHTS.entities +
relationsRatio * HEALTH_WEIGHTS.relations;
return Math.round(score * 100);
}
/** Qualitative tier label for a given score. */
export function brainHealthTier(score: number): BrainHealthTier {
if (score < 5) return 'empty';
if (score < 25) return 'sparse';
if (score < 50) return 'growing';
if (score < 80) return 'healthy';
return 'mature';
}
/**
* Per-dimension contribution breakdown (rounded integers summing to
* the final score). Useful for tooltips that show "why" a score is
* low — the user can see which dimension is lagging.
*/
export function brainHealthBreakdown(counts: BrainHealthCounts): {
frames: number;
entities: number;
relations: number;
} {
const frames = Math.max(0, counts.frames ?? 0);
const entities = Math.max(0, counts.entities ?? 0);
const relations = Math.max(0, counts.relations ?? 0);
return {
frames: Math.round(Math.min(1, frames / HEALTH_TARGETS.frames) * HEALTH_WEIGHTS.frames * 100),
entities: Math.round(Math.min(1, entities / HEALTH_TARGETS.entities) * HEALTH_WEIGHTS.entities * 100),
relations: Math.round(Math.min(1, relations / HEALTH_TARGETS.relations) * HEALTH_WEIGHTS.relations * 100),
};
}