bikky 0.4.3 → 0.4.4

package/dist/daemon/quality-rollups.js

@@ -0,0 +1,378 @@
+/**
+ * Backend aggregation for memory quality telemetry.
+ */
+import { createHash } from "node:crypto";
+import { contentHash, computeEffectiveConfidence } from "../mcp/helpers.js";
+import { categoryForMemorySubtype, layerForMemorySubtype } from "../mcp/taxonomy.js";
+import { buildOperationOrigin } from "../provenance/origin.js";
+import { readMaintenanceState, recordMaintenanceRun, shouldRunMaintenance, } from "./maintenance-state.js";
+import * as qdrant from "./qdrant.js";
+const SCROLL_LIMIT = 256;
+const ROLLUP_TYPE = "latest";
+const JOB_NAME = "memory_quality_rollups";
+let logFn = () => { };
+const defaultDeps = {
+    isReady: qdrant.isReady,
+    activeDestinations: qdrant.activeDestinations,
+    qdrantRequest: qdrant.qdrantRequest,
+    embed: qdrant.embed,
+};
+export const setLogger = (fn) => {
+    logFn = fn;
+};
+const nonEmptyString = (value) => {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+};
+const numberValue = (value) => (typeof value === "number" && Number.isFinite(value) ? value : 0);
+const stringArray = (value) => (Array.isArray(value)
+    ? value.map((item) => nonEmptyString(item)).filter((item) => item !== null)
+    : []);
+const stableUuid = (input) => {
+    const hash = createHash("sha256").update(input).digest("hex");
+    return [
+        hash.slice(0, 8),
+        hash.slice(8, 12),
+        hash.slice(12, 16),
+        hash.slice(16, 20),
+        hash.slice(20, 32),
+    ].join("-");
+};
+const completePayload = (payload) => ({
+    ...payload,
+    content: payload.content ?? "",
+    category: payload.category ?? "engineering",
+    domain: payload.domain ?? "software_engineering",
+    kind: payload.kind ?? "fact",
+    memory_subtype: payload.memory_subtype ?? null,
+    entities: payload.entities ?? [],
+    confidence: typeof payload.confidence === "number" ? payload.confidence : 0.7,
+    content_hash: payload.content_hash ?? "",
+    reinforcement_count: payload.reinforcement_count ?? 1,
+    last_reinforced_at: payload.last_reinforced_at ?? payload.created_at ?? "",
+    superseded_by: payload.superseded_by ?? null,
+    superseded_at: payload.superseded_at ?? null,
+    created_at: payload.created_at ?? "",
+    updated_at: payload.updated_at ?? payload.created_at ?? "",
+});
+const daysBetween = (now, iso) => {
+    if (!iso)
+        return 0;
+    const timestamp = Date.parse(iso);
+    if (!Number.isFinite(timestamp))
+        return 0;
+    return Math.max(0, (now.getTime() - timestamp) / 86_400_000);
+};
+const isFactStale = (payload, now, thresholdDays) => {
+    const activity = payload.last_verified_at ?? payload.last_reinforced_at ?? payload.created_at;
+    if (!activity)
+        return false;
+    return daysBetween(now, activity) > thresholdDays;
+};
+const scopesForFact = (fact) => {
+    const scopes = [{ type: "destination", value: fact.destination }];
+    const add = (type, value) => {
+        const normalized = nonEmptyString(value);
+        if (normalized)
+            scopes.push({ type, value: normalized });
+    };
+    add("repo", fact.payload.repo);
+    add("workstream_key", fact.payload.workstream_key);
+    add("task_key", fact.payload.task_key);
+    for (const entity of fact.payload.entities ?? [])
+        add("entity", entity);
+    add("origin_user", fact.payload.origin?.user?.id);
+    add("origin_agent", fact.payload.origin?.agent?.id);
+    const seen = new Set();
+    return scopes.filter((scope) => {
+        const key = `${scope.type}\0${scope.value}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+};
+const rollupKey = (destination, scope) => `${destination}\0${scope.type}\0${scope.value}`;
+const getRollup = (rollups, destination, scope, generatedAt) => {
+    const key = rollupKey(destination, scope);
+    const existing = rollups.get(key);
+    if (existing)
+        return existing;
+    const created = {
+        destination,
+        scope_type: scope.type,
+        scope_value: scope.value,
+        active_fact_count: 0,
+        recall_count: 0,
+        useful_count: 0,
+        misleading_count: 0,
+        wrong_count: 0,
+        stale_count: 0,
+        low_confidence_count: 0,
+        generated_at: generatedAt,
+        sourceFactIds: new Set(),
+        sourceEventIds: new Set(),
+    };
+    rollups.set(key, created);
+    return created;
+};
+const addEventSignal = (rollups, scopes, destination, generatedAt, eventId, update) => {
+    for (const scope of scopes) {
+        const rollup = getRollup(rollups, destination, scope, generatedAt);
+        update(rollup);
+        rollup.sourceEventIds.add(eventId);
+    }
+};
+export const buildQualityRollups = (input) => {
+    const now = input.generatedAt ?? new Date();
+    const generatedAt = now.toISOString();
+    const staleThresholdDays = input.staleThresholdDays ?? 30;
+    const lowConfidenceThreshold = input.lowConfidenceThreshold ?? 0.6;
+    const factsById = new Map(input.facts.map((fact) => [fact.id, fact]));
+    const scopesByFactId = new Map(input.facts.map((fact) => [fact.id, scopesForFact(fact)]));
+    const rollups = new Map();
+    for (const fact of input.facts) {
+        const payload = completePayload(fact.payload);
+        const scopes = scopesByFactId.get(fact.id) ?? [];
+        for (const scope of scopes) {
+            const rollup = getRollup(rollups, fact.destination, scope, generatedAt);
+            rollup.active_fact_count++;
+            rollup.recall_count += numberValue(payload.recall_count);
+            rollup.useful_count += numberValue(payload.useful_count ?? payload.useful_feedback_count);
+            if (isFactStale(payload, now, staleThresholdDays))
+                rollup.stale_count++;
+            if (computeEffectiveConfidence(payload) < lowConfidenceThreshold)
+                rollup.low_confidence_count++;
+            rollup.sourceFactIds.add(fact.id);
+        }
+    }
+    for (const event of input.events ?? []) {
+        const subtype = event.payload.memory_subtype;
+        if (subtype === "recall_event") {
+            for (const factId of stringArray(event.payload.returned_fact_ids)) {
+                const fact = factsById.get(factId);
+                if (!fact || typeof fact.payload.recall_count === "number")
+                    continue;
+                addEventSignal(rollups, scopesByFactId.get(factId) ?? [], fact.destination, generatedAt, event.id, (rollup) => { rollup.recall_count++; });
+            }
+            continue;
+        }
+        const targetFactId = nonEmptyString(event.payload.target_fact_id);
+        if (!targetFactId)
+            continue;
+        const targetFact = factsById.get(targetFactId);
+        if (!targetFact)
+            continue;
+        const targetScopes = scopesByFactId.get(targetFactId) ?? [];
+        if (subtype === "feedback_event" && event.payload.feedback_kind === "useful") {
+            if (typeof targetFact.payload.useful_count === "number" || typeof targetFact.payload.useful_feedback_count === "number") {
+                continue;
+            }
+            addEventSignal(rollups, targetScopes, targetFact.destination, generatedAt, event.id, (rollup) => { rollup.useful_count++; });
+            continue;
+        }
+        if (subtype === "outcome_event" && (event.payload.outcome === "misleading" || event.payload.outcome === "wrong")) {
+            addEventSignal(rollups, targetScopes, targetFact.destination, generatedAt, event.id, (rollup) => {
+                if (event.payload.outcome === "misleading")
+                    rollup.misleading_count++;
+                if (event.payload.outcome === "wrong")
+                    rollup.wrong_count++;
+            });
+        }
+    }
+    return [...rollups.values()]
+        .map((rollup) => ({
+        destination: rollup.destination,
+        scope_type: rollup.scope_type,
+        scope_value: rollup.scope_value,
+        active_fact_count: rollup.active_fact_count,
+        recall_count: rollup.recall_count,
+        useful_count: rollup.useful_count,
+        misleading_count: rollup.misleading_count,
+        wrong_count: rollup.wrong_count,
+        stale_count: rollup.stale_count,
+        low_confidence_count: rollup.low_confidence_count,
+        generated_at: rollup.generated_at,
+        source_fact_ids: [...rollup.sourceFactIds].sort().slice(0, 100),
+        source_event_ids: [...rollup.sourceEventIds].sort().slice(0, 100),
+    }))
+        .sort((a, b) => `${a.scope_type}:${a.scope_value}`.localeCompare(`${b.scope_type}:${b.scope_value}`));
+};
+const scrollAllPoints = async (deps, destination, filter) => {
+    const points = [];
+    let offset;
+    do {
+        const body = {
+            filter,
+            limit: SCROLL_LIMIT,
+            with_payload: true,
+            ...(offset !== undefined && offset !== null ? { offset } : {}),
+        };
+        const response = await deps.qdrantRequest("POST", `/collections/${destination.collection}/points/scroll`, body, destination);
+        for (const point of response.result?.points ?? []) {
+            points.push({
+                id: point.id,
+                destination: destination.name,
+                payload: (point.payload ?? {}),
+            });
+        }
+        offset = response.result?.next_page_offset;
+    } while (offset !== undefined && offset !== null);
+    return points;
+};
+const fetchQualityInputs = async (deps, destination) => {
+    const facts = await scrollAllPoints(deps, destination, {
+        must: [{ is_null: { key: "superseded_by" } }],
+        must_not: [{ key: "kind", match: { any: ["telemetry", "entity_type"] } }],
+    });
+    const events = await scrollAllPoints(deps, destination, {
+        must: [
+            { key: "kind", match: { value: "telemetry" } },
+            { key: "memory_subtype", match: { any: ["feedback_event", "outcome_event", "recall_event"] } },
+        ],
+    });
+    return { facts, events };
+};
+const rollupContent = (rollup) => (`Memory quality rollup for ${rollup.scope_type}:${rollup.scope_value}: ` +
+    `${rollup.active_fact_count} active facts, ${rollup.recall_count} recalls, ` +
+    `${rollup.useful_count} useful, ${rollup.misleading_count} misleading, ` +
+    `${rollup.wrong_count} wrong, ${rollup.stale_count} stale, ` +
+    `${rollup.low_confidence_count} low-confidence.`);
+const rollupId = (rollup) => stableUuid(`aggregate_rollup:${ROLLUP_TYPE}:${rollup.destination}:${rollup.scope_type}:${rollup.scope_value}`);
+const rollupPayload = (config, rollup) => {
+    const content = rollupContent(rollup);
+    return {
+        content,
+        category: categoryForMemorySubtype("aggregate_rollup") ?? "system",
+        domain: "software_engineering",
+        kind: "telemetry",
+        memory_subtype: "aggregate_rollup",
+        layer: layerForMemorySubtype("aggregate_rollup") ?? "workspace",
+        entities: rollup.scope_type === "entity" ? [rollup.scope_value.toLowerCase()] : [],
+        origin: buildOperationOrigin({
+            config,
+            interface: "daemon",
+            action: "aggregate",
+            subsystem: "memory_quality_rollups",
+            metadata: {
+                destination: rollup.destination,
+                scope_type: rollup.scope_type,
+                scope_value: rollup.scope_value,
+            },
+        }),
+        confidence: 1.0,
+        importance: 0.4,
+        content_hash: contentHash("aggregate_rollup", `${ROLLUP_TYPE}:${rollup.destination}:${rollup.scope_type}:${rollup.scope_value}`),
+        reinforcement_count: 1,
+        last_reinforced_at: rollup.generated_at,
+        superseded_by: null,
+        superseded_at: null,
+        created_at: rollup.generated_at,
+        updated_at: rollup.generated_at,
+        rollup_type: ROLLUP_TYPE,
+        rollup_generated_at: rollup.generated_at,
+        rollup_window_end: rollup.generated_at,
+        scope_type: rollup.scope_type,
+        scope_value: rollup.scope_value,
+        active_fact_count: rollup.active_fact_count,
+        recall_count: rollup.recall_count,
+        useful_count: rollup.useful_count,
+        misleading_count: rollup.misleading_count,
+        wrong_count: rollup.wrong_count,
+        stale_count: rollup.stale_count,
+        low_confidence_count: rollup.low_confidence_count,
+        source_fact_ids: rollup.source_fact_ids,
+        source_event_ids: rollup.source_event_ids,
+        metadata: {
+            generated_by: "memory_quality_rollups",
+            rollup_type: ROLLUP_TYPE,
+        },
+    };
+};
+const upsertRollup = async (config, deps, destination, rollup) => {
+    const payload = rollupPayload(config, rollup);
+    const vector = await deps.embed(String(payload.content));
+    await deps.qdrantRequest("PUT", `/collections/${destination.collection}/points`, {
+        points: [{ id: rollupId(rollup), vector, payload }],
+    }, destination);
+};
+export const aggregateMemoryQualitySignals = async (config, deps = defaultDeps) => {
+    const destinations = deps.activeDestinations();
+    const generatedAt = new Date();
+    const maxScopes = config.daemon.memory_quality_rollups_max_scopes_per_run ?? 100;
+    let factsSeen = 0;
+    let eventsSeen = 0;
+    let rollupsUpserted = 0;
+    let scopesCapped = false;
+    for (const destination of destinations) {
+        const { facts, events } = await fetchQualityInputs(deps, destination);
+        factsSeen += facts.length;
+        eventsSeen += events.length;
+        const rollups = buildQualityRollups({
+            facts,
+            events,
+            generatedAt,
+            staleThresholdDays: config.daemon.staleness_threshold_days,
+            lowConfidenceThreshold: config.daemon.memory_quality_rollups_low_confidence_threshold,
+        });
+        const selectedRollups = rollups.slice(0, maxScopes);
+        scopesCapped ||= rollups.length > selectedRollups.length;
+        for (const rollup of selectedRollups) {
+            await upsertRollup(config, deps, destination, rollup);
+            rollupsUpserted++;
+        }
+    }
+    return {
+        destinations_seen: destinations.length,
+        facts_seen: factsSeen,
+        events_seen: eventsSeen,
+        rollups_upserted: rollupsUpserted,
+        scopes_capped: scopesCapped,
+    };
+};
+export const tick = async (config, deps = defaultDeps) => {
+    if (!config.daemon.memory_quality_rollups_enabled)
+        return;
+    if (!deps.isReady())
+        return;
+    const now = new Date();
+    const nowIso = now.toISOString();
+    const state = readMaintenanceState(logFn);
+    const job = state.jobs.memory_quality_rollups;
+    const intervalSec = config.daemon.memory_quality_rollups_interval_sec ?? 3600;
+    if (!shouldRunMaintenance(now, job.last_run_at, intervalSec))
+        return;
+    try {
+        const result = await aggregateMemoryQualitySignals(config, deps);
+        recordMaintenanceRun(JOB_NAME, {
+            job: JOB_NAME,
+            ran_at: nowIso,
+            status: result.facts_seen === 0 ? "skipped" : "success",
+            candidates_seen: result.facts_seen + result.events_seen,
+            llm_calls: 0,
+            accepted: result.rollups_upserted,
+            deterministic: result.rollups_upserted,
+            skipped_reason: result.facts_seen === 0
+                ? "no_active_facts"
+                : result.scopes_capped
+                    ? "max_scopes_per_run_reached"
+                    : undefined,
+        }, { cursorUpdatedAt: nowIso }, logFn);
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        logFn("ERROR", `Memory quality rollups failed: ${message}`);
+        recordMaintenanceRun(JOB_NAME, {
+            job: JOB_NAME,
+            ran_at: nowIso,
+            status: "error",
+            candidates_seen: 0,
+            llm_calls: 0,
+            accepted: 0,
+            error: message,
+        }, {}, logFn);
+    }
+};
+//# sourceMappingURL=quality-rollups.js.map

package/dist/daemon/relations.js

@@ -255,7 +255,7 @@ const storeRelation = async (fromEntity, toEntity, relationType, content, candid
     }
     const id = await qdrant.storeFact({
         content,
-        category: "human",
+        category: "engineering",
         domain: DEFAULT_CAPTURE_CONTEXT.domain,
         kind: "relation",
         entities: [fromEntity, toEntity],

package/dist/daemon/staleness.js

@@ -20,7 +20,7 @@ const defaultDeps = {
  */
 export const scanStaleFacts = async (config, deps = defaultDeps) => {
     const threshold = config.daemon.staleness_threshold_days || 30;
-    const categories = ["engineering", "product", "human", "system"];
+    const categories = ["engineering", "product", "system"];
     const limit = 3;
     if (!deps.isReady()) {
         logFn("DEBUG", "Staleness scan: Qdrant client not ready, skipping");

package/dist/lifecycle.js

@@ -7,13 +7,14 @@
  */
 import fs from "node:fs";
 import { spawn } from "node:child_process";
-import { PID_PATH, STATE_DIR } from "./config.js";
+import { getPidPath, getStateDir } from "./config.js";
 // ---------------------------------------------------------------------------
 // PID file helpers
 // ---------------------------------------------------------------------------
 function readPid() {
+    const pidPath = getPidPath();
     try {
-        const raw = fs.readFileSync(PID_PATH, "utf-8").trim();
+        const raw = fs.readFileSync(pidPath, "utf-8").trim();
         const pid = parseInt(raw, 10);
         return Number.isFinite(pid) ? pid : null;
     }
@@ -22,12 +23,13 @@ function readPid() {
     }
 }
 function writePid(pid) {
-    fs.mkdirSync(STATE_DIR, { recursive: true });
-    fs.writeFileSync(PID_PATH, String(pid) + "\n");
+    fs.mkdirSync(getStateDir(), { recursive: true });
+    fs.writeFileSync(getPidPath(), String(pid) + "\n");
 }
 function removePid() {
+    const pidPath = getPidPath();
     try {
-        fs.unlinkSync(PID_PATH);
+        fs.unlinkSync(pidPath);
     }
     catch {
         // already gone

package/dist/mcp/helpers.d.ts

@@ -26,6 +26,9 @@ export interface StructuredFact {
     verification_count?: number;
     useful_count?: number;
     not_useful_count?: number;
+    misleading_count?: number;
+    wrong_count?: number;
+    irrelevant_count?: number;
     redaction?: FactPayload["redaction"];
     metadata?: FactPayload["metadata"];
     workstream_key?: string | null;

package/dist/mcp/helpers.js

@@ -217,6 +217,12 @@ export function formatFact(point) {
         parts.push(`useful: ${p.useful_count}x`);
     if ((p.not_useful_count ?? 0) > 0)
         parts.push(`not useful: ${p.not_useful_count}x`);
+    if ((p.misleading_count ?? 0) > 0)
+        parts.push(`misleading: ${p.misleading_count}x`);
+    if ((p.wrong_count ?? 0) > 0)
+        parts.push(`wrong: ${p.wrong_count}x`);
+    if ((p.irrelevant_count ?? 0) > 0)
+        parts.push(`irrelevant: ${p.irrelevant_count}x`);
     if (p.redaction?.redacted)
         parts.push(`redacted: ${p.redaction.summary}`);
     if (p.metadata && Object.keys(p.metadata).length > 0) {
@@ -268,6 +274,9 @@ export function structuredFact(point) {
         ...(p.verification_count !== undefined ? { verification_count: p.verification_count } : {}),
         ...(p.useful_count !== undefined ? { useful_count: p.useful_count } : {}),
         ...(p.not_useful_count !== undefined ? { not_useful_count: p.not_useful_count } : {}),
+        ...(p.misleading_count !== undefined ? { misleading_count: p.misleading_count } : {}),
+        ...(p.wrong_count !== undefined ? { wrong_count: p.wrong_count } : {}),
+        ...(p.irrelevant_count !== undefined ? { irrelevant_count: p.irrelevant_count } : {}),
         ...(p.redaction ? { redaction: p.redaction } : {}),
         ...(p.metadata && Object.keys(p.metadata).length > 0 ? { metadata: p.metadata } : {}),
         ...(p.workstream_key ? { workstream_key: p.workstream_key } : {}),

package/dist/mcp/taxonomy.d.ts

@@ -13,10 +13,6 @@ export declare const CATEGORIES: {
         readonly description: "Product context: domain rules, product decisions, requirements, user workflows, roadmap, success metrics, and market or community insight.";
         readonly examples: readonly ["Bikky should show categories and concrete subtype chips directly, with no extra sub-tab layer.", "Activation should be measured by whether agents successfully reuse recalled memory."];
     };
-    readonly human: {
-        readonly description: "Human context: explicit preferences, people and roles, ownership, working agreements, and durable actor-action activity events.";
-        readonly examples: readonly ["Saber prefers concise implementation plans before code changes.", "Alex approved PR #85 for merge."];
-    };
     readonly system: {
         readonly description: "System context: Bikky-owned lifecycle memory, session indexes, episodes, workstreams, recall/feedback/outcome telemetry, and aggregate rollups.";
         readonly examples: readonly ["Session indexes are routing/audit artifacts rather than durable project boundaries.", "Recall telemetry is excluded from normal semantic recall."];
@@ -27,15 +23,15 @@ export declare const DEFAULT_CATEGORY: Category;
 export declare const DOMAINS: {
     readonly software_engineering: {
         readonly description: "Coding-agent work: repositories, code changes, architecture, infrastructure, debugging, tests, CI, and developer workflow.";
-        readonly defaultCategories: readonly ["engineering", "product", "human", "system"];
+        readonly defaultCategories: readonly ["engineering", "product", "system"];
     };
     readonly product_strategy: {
         readonly description: "Product direction, positioning, roadmap tradeoffs, customer problems, metrics, and market learning.";
-        readonly defaultCategories: readonly ["product", "human", "system"];
+        readonly defaultCategories: readonly ["product", "engineering", "system"];
     };
     readonly business_operations: {
         readonly description: "Business process, vendors, finance, legal/admin operations, recurring procedures, and ownership.";
-        readonly defaultCategories: readonly ["product", "human", "system"];
+        readonly defaultCategories: readonly ["product", "engineering", "system"];
     };
     readonly research: {
         readonly description: "Research questions, sources, hypotheses, experiment findings, synthesis, and reusable insights.";
@@ -43,7 +39,7 @@ export declare const DOMAINS: {
     };
     readonly personal_productivity: {
         readonly description: "Individual productivity, habits, planning preferences, reminders, and personal operating context.";
-        readonly defaultCategories: readonly ["human", "product", "system"];
+        readonly defaultCategories: readonly ["engineering", "product", "system"];
     };
 };
 export type Domain = keyof typeof DOMAINS;
@@ -121,11 +117,11 @@ export declare const MEMORY_SUBTYPE_DEFAULT_CATEGORY: {
     readonly success_metric: "product";
     readonly market_insight: "product";
     readonly troubleshooting_gotcha: "engineering";
-    readonly preference: "human";
-    readonly person_profile: "human";
-    readonly ownership_note: "human";
-    readonly working_agreement: "human";
-    readonly activity_event: "human";
+    readonly preference: "engineering";
+    readonly person_profile: "engineering";
+    readonly ownership_note: "engineering";
+    readonly working_agreement: "engineering";
+    readonly activity_event: "engineering";
     readonly session_index: "system";
     readonly episode: "system";
     readonly workstream: "system";