bikky 0.4.3 → 0.4.4

package/README.md

@@ -2,48 +2,69 @@
 
 <p align="center"><b>Persistent memory for AI coding agents — built for teams and multi-agent engineering workflows.</b></p>
 
-bikky gives AI coding agents (GitHub Copilot, Claude Code, Cursor, and other MCP clients) long-term memory that persists across sessions, across tools, and across your whole team. When multiple engineers, agents, or repos need to build on the same knowledge base, bikky captures what's learned *during* sessions so future sessions start smarter.
-
-### Who it's for
-
-- 👥 **Teams & software factories** — What one engineer's agent learns today, every agent on the team can recall tomorrow. Shared memory turns institutional knowledge into something queryable instead of tribal — onboarding accelerates, conventions stop drifting, and the same lesson never gets re-learned twice.
-- 🤖 **Multi-agent engineering workflows** — Multiple Cursor / Claude Code / Copilot sessions can share codebase context, conventions, and recent decisions instead of re-learning them from scratch.
-
 <p align="center">
   <img src="https://raw.githubusercontent.com/bikky-dev/bikky/main/docs/diagrams/team-memory.svg" alt="Memory — facts flow from individual sessions into a self-curating knowledge store shared across your team" width="720" />
 </p>
 
-<p align="center"><i>Knowledge flows from every session into a store that curates itself over time — deduplicating, distilling, and decaying stale facts — so every future session starts smarter across the team.</i></p>
+<p align="center"><i>Selected knowledge flows from supported sessions into a store that curates itself over time — deduplicating, distilling, and decaying stale facts — so future sessions can start with more context.</i></p>
 
----
+bikky provides long-term memory for MCP-capable AI coding agents. It exposes memory tools over the Model Context Protocol (MCP), stores facts in Qdrant, and can run a local daemon that extracts durable facts from supported transcript sources. Teams can share memory across tools, repos, and engineers without treating chat history or closed PRs as the source of truth.
 
-### The problem
+### Who it's for
+
+- 👥 **Teams & software factories** — What one engineer's agent learns today can be recalled by other agents on the team tomorrow. Shared memory makes institutional knowledge queryable, helps onboarding, and reduces convention drift and repeated rediscovery.
+- 🤖 **Multi-agent engineering workflows** — Multiple MCP-capable agent sessions can share codebase context, conventions, and recent decisions instead of re-learning them from scratch.
 
-The most valuable things you and your agents learn — why a config value exists, which deploy step matters, what broke last quarter, the convention you settled on yesterday — happen *during* sessions. And then they vanish when the session closes. Across teams, repos, and tools, knowledge still lives in heads, chat threads, and closed PRs, and every new agent session has to learn it from scratch. Hand-written docs drift the moment they're published.
+---
 
-### How bikky solves it
+### How bikky works
 
-bikky gives your agent memory tools and runs a small background service after `bikky setup`. You keep working normally; bikky captures useful facts, organizes them, recalls them in future sessions, and keeps the store tidy over time.
+bikky gives your agent memory tools and runs a small background service after `bikky setup`. You keep working normally; bikky captures useful facts from supported transcript sources, organizes them, recalls them in future sessions, and keeps the store tidy over time.
 
-- **Capture** — Facts are extracted automatically from session transcripts; no manual docs to write.
-- **Classify** — Memories are grouped as **engineering**, **product**, **human**, or **system** so they stay easy to browse and filter.
-- **Recall** — Every new session, yours or a teammate's, recalls from the same store via semantic search.
+- **Capture** — Facts are extracted automatically from supported session transcripts without requiring manual notes for every fact.
+- **Classify** — Memories are grouped as **engineering**, **product**, or **system** so they stay easy to browse and filter.
+- **Recall** — New sessions can recall from the same store via semantic search.
 - **Curate** — bikky merges duplicates, fades stale facts, resolves contradictions, distills recurring patterns, and builds an entity graph over time.
-- **Compound** — Session 50 is dramatically better than session 1 because memory accumulates.
+- **Compound** — Later sessions can start with more context because memory accumulates.
 - **Route** — Optionally keep team, client, or environment-specific memory in separate Qdrant destinations from one install. See [separate memory stores](#optional-separate-memory-stores).
 
 Subtypes keep recall precise without making setup harder:
 
-- **Engineering** — codebase maps, architecture decisions, infra topology, access patterns, operational procedures, troubleshooting gotchas, and conventions.
+- **Engineering** — codebase maps, architecture decisions, infra topology, access patterns, operational procedures, troubleshooting gotchas, conventions, preferences, person/ownership context, working agreements, and durable activity events.
 - **Product** — domain rules, product decisions, requirements, user workflows, roadmap items, success metrics, and market insights.
-- **Human** — preferences, person profiles, ownership notes, working agreements, and activity events.
 - **System** — session indexes, episodes, workstreams, and feedback signals.
 
 ---
 
+## Supported integrations
+
+bikky has two integration surfaces: MCP tool access for agents and optional background transcript capture. Tool access is broader than transcript capture.
+
+### Coding agents and MCP clients
+
+| Client or agent | MCP tool access | `bikky setup` registration | Background transcript capture |
+| --- | --- | --- | --- |
+| GitHub Copilot | Supported | Supported via `~/.copilot/mcp-config.json` | Supported from `~/.copilot/session-state` |
+| Claude Code | Supported | Supported via the `claude` CLI or `~/.claude.json` fallback | Supported from `~/.claude/projects` |
+| Cursor and other stdio MCP clients | Standard MCP server is available via `npx -y bikky mcp` | Not auto-configured today | No built-in watcher today |
+
+If your client can launch a stdio MCP server, it can use bikky's memory tools after manual configuration. bikky does not currently ship Cursor-specific setup or transcript parsing. Automatic transcript ingestion is implemented for GitHub Copilot and Claude Code.
+
+### Storage and model providers
+
+| Component | Supported today | Notes |
+| --- | --- | --- |
+| Vector store | Qdrant | Local Docker, Qdrant Cloud, or self-hosted Qdrant. Qdrant is required. |
+| `embedding.provider` | `ollama`, `openai`, `bedrock`, `portkey` | Used to embed memories for semantic search. |
+| `llm.provider` | `ollama`, `openai`, `bedrock`, `portkey` | Used for extraction, curation, distillation, and relation inference. |
+
+Portkey support means bikky talks to Portkey as the configured gateway; upstream model availability, routing, and fallbacks are controlled by your Portkey configuration. Providers not listed above are not built in today, but the provider registry is designed to make additions small and reviewable.
+
+---
+
 ## Quick start
 
-This is the fastest path to a working memory store: Qdrant runs locally, while hosted embeddings and LLM calls provide strong extraction and recall quality without running local models.
+This is the fastest path to a working memory store: Qdrant runs locally, while hosted embeddings and LLM calls handle extraction and recall without running local models.
 
 ```bash
 # 1. Pull and run Qdrant (vector store)
@@ -60,7 +81,7 @@ cat > ~/.bikky/config.json <<'JSON'
   "embedding": {
     "provider": "openai",
     "model": "text-embedding-3-small",
-    "dimensions": 1536,
+    "dimensions": 1024,
     "api_key": "sk-..."
   },
   "llm": {
@@ -73,19 +94,19 @@ JSON
 # qdrant_api_key is optional; leave it empty or omit it for local Qdrant.
 # Prefer env vars? Omit api_key above and set OPENAI_API_KEY instead.
 
-# 3. Register bikky with your editor and start the background service
-bikky setup            # writes MCP config for Copilot + Claude Code, then starts the daemon
+# 3. Register bikky with supported clients and start the background service
+bikky setup            # writes MCP config for GitHub Copilot + Claude Code, then starts the daemon
 ```
 
 `npm install -g bikky` runs a best-effort postinstall setup hook for convenience. It never fails the install, and you should still run `bikky setup` after writing your config to make setup explicit and repeatable.
 
-Restart your editor. The memory tools appear automatically in supported MCP clients.
+Restart your editor. The memory tools appear automatically in GitHub Copilot and Claude Code; configure other stdio MCP clients manually with `npx -y bikky mcp`.
 
 ```bash
 bikky status           # confirms Qdrant, embeddings, daemon, and UI health
 ```
 
-That's it. You can keep Qdrant local forever, or move the vector store to Qdrant Cloud later for a shared team setup.
+At this point, you can continue with local Qdrant or move the vector store to Qdrant Cloud later for a shared team setup.
 
 For other deployment shapes — fully hosted, 100% local, or hosted Qdrant with local models — see [Setup options](#setup-options).
 
@@ -105,18 +126,18 @@ bikky supports four common setup shapes. Pick based on where you want Qdrant to
 | **LLM**                 | One provider                   | Portkey · OpenAI · Ollama · Bedrock                                                     |
 | **Docker** *(optional)* | Only if you run Qdrant locally | Docker Desktop, OrbStack, colima, etc.                                                   |
 
-Both `embedding.provider` and `llm.provider` accept the same values: `ollama`, `openai`, `bedrock`, or `portkey`. **Portkey is the easiest cloud option** — one API key, any upstream provider, with built-in routing/fallbacks. Bikky's canonical embedding dimension is **1024**, portable across every modern provider.
+Both `embedding.provider` and `llm.provider` accept the same values: `ollama`, `openai`, `bedrock`, or `portkey`. Portkey can be used as a hosted gateway when you want one configured provider in bikky and upstream routing/fallbacks managed outside bikky. The documented examples use **1024-dimensional embeddings** because that size works across the built-in provider examples. Some providers expose larger native dimensions (for example OpenAI `text-embedding-3-small` can return 1536), but using 1024 keeps the documented setup portable without rebuilding every collection.
 
 > ⚠️ **Qdrant Cloud free tier does not include automatic backups.** Deleted collections cannot be recovered. If your memory data is valuable, use a paid Qdrant Cloud plan (which includes daily backups), run Qdrant locally with your own backup strategy, or periodically export snapshots via the [Qdrant snapshots API](https://qdrant.tech/documentation/concepts/snapshots/).
 
 ### Choose a setup
 
-| Setup                            | Best for                                                       | Config                                                                    |
-| -------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| **Fully hosted**                 | Best performance and teams; managed vector storage and models  | [Fully hosted config][fully-hosted-config]                              |
-| **Local Qdrant + hosted models** | Local vector storage with hosted extraction and embedding      | [Hosted models config][hosted-models-config]                            |
-| **Local and free**               | Local evaluation; quality depends on local models              | [Local config guide][local-config]                                      |
-| **Hosted Qdrant + local Ollama** | Shared vector storage while keeping model calls local          | [Hosted Qdrant + local models][hosted-qdrant-local-models-config]       |
+| Setup                            | Use when                                                       | Config                                                                  |
+| -------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| **Fully hosted**                 | Teams want managed vector storage and hosted models            | [Fully hosted config][fully-hosted-config]                              |
+| **Local Qdrant + hosted models** | You want local vector storage with hosted extraction/embedding | [Hosted models config][hosted-models-config]                            |
+| **Local and free**               | You are evaluating locally and can accept local-model quality  | [Local config guide][local-config]                                      |
+| **Hosted Qdrant + local Ollama** | You want shared vectors while keeping model calls local        | [Hosted Qdrant + local models][hosted-qdrant-local-models-config]       |
 
 ### Configuration basics
 
@@ -196,9 +217,9 @@ bikky-ui              # opens http://localhost:1422
 <p align="center"><i>Dashboard — memory stats, category breakdown, and recent facts at a glance</i></p>
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/bikky-dev/bikky/main/docs/screenshots/memory.png" alt="Memory browser — search, filter, and browse all stored facts" width="720" />
+  <img src="https://raw.githubusercontent.com/bikky-dev/bikky/main/docs/screenshots/memory.png" alt="Memory browser — search, filter, and browse current user-facing memories" width="720" />
 </p>
-<p align="center"><i>Memory browser — search, filter by category/kind/origin, and browse all stored facts</i></p>
+<p align="center"><i>Memory browser — search, filter by category, subtype, entity, usefulness, date, and sort order</i></p>
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/bikky-dev/bikky/main/docs/screenshots/graph.png" alt="Entity graph — interactive visualization of entity relationships" width="720" />
@@ -207,11 +228,15 @@ bikky-ui              # opens http://localhost:1422
 
 The UI reads from your existing `~/.bikky/config.json` (or `BIKKY_HOME/config.json`) — no extra configuration required.
 
+By default, the dashboard, memory list, and search results show current user-facing memories only. Internal telemetry, system lifecycle summaries (`session_index`, `episode`, `workstream`), entity sidecars, and superseded archive records are hidden from the main views so counts match what you normally mean by "memories." Diagnostic API queries can still request those records explicitly, including superseded records with `include_superseded=true`.
+
+Memory cards and detail pages also surface provenance from canonical `origin` metadata: the configured user, origin surface/operation, agent, last operation, repo, branch, workstream, task, session, and episode when present. Older records that only have legacy `source`, `actor_id`, or `metadata.actor_label` still display useful fallback labels.
+
 ## CLI
 
 ```bash
 bikky mcp       # start MCP server (stdio) — used by editors
-bikky setup     # install MCP configs for Copilot + Claude Code, then start the daemon
+bikky setup     # install MCP configs for GitHub Copilot + Claude Code, then start the daemon
 bikky start     # alias for setup
 bikky stop      # stop the background daemon
 bikky daemon    # run the daemon in the foreground

package/dist/config.d.ts

@@ -61,6 +61,10 @@ export interface DaemonConfig {
     entity_typing_enabled: boolean;
     entity_typing_interval_sec: number;
     entity_typing_max_entities_per_run: number;
+    memory_quality_rollups_enabled: boolean;
+    memory_quality_rollups_interval_sec: number;
+    memory_quality_rollups_low_confidence_threshold: number;
+    memory_quality_rollups_max_scopes_per_run: number;
     staleness_threshold_days: number;
 }
 export interface QdrantClientConfig {
@@ -168,7 +172,7 @@ export interface ConfigFileDiagnostics {
     issues: ConfigIssue[];
 }
 declare const DEFAULTS: BikkyConfig;
-export declare const CONFIG_ENV_KEYS: readonly ["QDRANT_URL", "QDRANT_API_KEY", "BIKKY_COLLECTION", "EMBEDDING_PROVIDER", "EMBEDDING_MODEL", "EMBEDDING_BASE_URL", "EMBEDDING_DIMENSIONS", "OPENAI_API_KEY", "PORTKEY_API_KEY", "LLM_PROVIDER", "LLM_MODEL", "LLM_BASE_URL", "LLM_FALLBACK_PROVIDER", "AWS_PROFILE", "AWS_BEDROCK_REGION", "AWS_REGION", "QDRANT_TIMEOUT_MS", "QDRANT_RETRIES", "QDRANT_RETRY_BASE_DELAY_MS", "BIKKY_EMBEDDING_TIMEOUT_MS", "BIKKY_EMBEDDING_RETRIES", "BIKKY_EMBEDDING_RETRY_BASE_DELAY_MS", "BIKKY_LLM_TIMEOUT_MS", "BIKKY_LLM_RETRIES", "BIKKY_LLM_RETRY_BASE_DELAY_MS", "BIKKY_DAEMON_RELATION_INFERENCE_ENABLED", "BIKKY_DAEMON_RELATION_INFERENCE_INTERVAL_SEC", "BIKKY_DAEMON_RELATION_INFERENCE_MAX_PAIRS_PER_RUN", "BIKKY_DAEMON_ENTITY_TYPING_ENABLED", "BIKKY_DAEMON_ENTITY_TYPING_INTERVAL_SEC", "BIKKY_DAEMON_ENTITY_TYPING_MAX_ENTITIES_PER_RUN", "BIKKY_USER_ID", "BIKKY_USER_NAME", "BIKKY_AGENT_ID", "BIKKY_AGENT_NAME", "BIKKY_ACTOR_ID", "BIKKY_ACTOR_LABEL"];
+export declare const CONFIG_ENV_KEYS: readonly ["QDRANT_URL", "QDRANT_API_KEY", "BIKKY_COLLECTION", "EMBEDDING_PROVIDER", "EMBEDDING_MODEL", "EMBEDDING_BASE_URL", "EMBEDDING_DIMENSIONS", "OPENAI_API_KEY", "PORTKEY_API_KEY", "LLM_PROVIDER", "LLM_MODEL", "LLM_BASE_URL", "LLM_FALLBACK_PROVIDER", "AWS_PROFILE", "AWS_BEDROCK_REGION", "AWS_REGION", "QDRANT_TIMEOUT_MS", "QDRANT_RETRIES", "QDRANT_RETRY_BASE_DELAY_MS", "BIKKY_EMBEDDING_TIMEOUT_MS", "BIKKY_EMBEDDING_RETRIES", "BIKKY_EMBEDDING_RETRY_BASE_DELAY_MS", "BIKKY_LLM_TIMEOUT_MS", "BIKKY_LLM_RETRIES", "BIKKY_LLM_RETRY_BASE_DELAY_MS", "BIKKY_DAEMON_RELATION_INFERENCE_ENABLED", "BIKKY_DAEMON_RELATION_INFERENCE_INTERVAL_SEC", "BIKKY_DAEMON_RELATION_INFERENCE_MAX_PAIRS_PER_RUN", "BIKKY_DAEMON_ENTITY_TYPING_ENABLED", "BIKKY_DAEMON_ENTITY_TYPING_INTERVAL_SEC", "BIKKY_DAEMON_ENTITY_TYPING_MAX_ENTITIES_PER_RUN", "BIKKY_DAEMON_MEMORY_QUALITY_ROLLUPS_ENABLED", "BIKKY_DAEMON_MEMORY_QUALITY_ROLLUPS_INTERVAL_SEC", "BIKKY_DAEMON_MEMORY_QUALITY_ROLLUPS_LOW_CONFIDENCE_THRESHOLD", "BIKKY_DAEMON_MEMORY_QUALITY_ROLLUPS_MAX_SCOPES_PER_RUN", "BIKKY_USER_ID", "BIKKY_USER_NAME", "BIKKY_AGENT_ID", "BIKKY_AGENT_NAME", "BIKKY_ACTOR_ID", "BIKKY_ACTOR_LABEL"];
 export declare function validateConfigObject(raw: unknown): ConfigIssue[];
 export declare function inspectConfigFile(configPath?: string): ConfigFileDiagnostics;
 export declare function getActiveConfigEnvOverrides(env?: NodeJS.ProcessEnv): string[];

package/dist/config.js

@@ -92,6 +92,10 @@ const DEFAULTS = {
         entity_typing_enabled: true,
         entity_typing_interval_sec: 900,
         entity_typing_max_entities_per_run: 5,
+        memory_quality_rollups_enabled: true,
+        memory_quality_rollups_interval_sec: 3600,
+        memory_quality_rollups_low_confidence_threshold: 0.6,
+        memory_quality_rollups_max_scopes_per_run: 100,
         staleness_threshold_days: 30,
     },
     identity: {
@@ -142,6 +146,10 @@ export const CONFIG_ENV_KEYS = [
     "BIKKY_DAEMON_ENTITY_TYPING_ENABLED",
     "BIKKY_DAEMON_ENTITY_TYPING_INTERVAL_SEC",
     "BIKKY_DAEMON_ENTITY_TYPING_MAX_ENTITIES_PER_RUN",
+    "BIKKY_DAEMON_MEMORY_QUALITY_ROLLUPS_ENABLED",
+    "BIKKY_DAEMON_MEMORY_QUALITY_ROLLUPS_INTERVAL_SEC",
+    "BIKKY_DAEMON_MEMORY_QUALITY_ROLLUPS_LOW_CONFIDENCE_THRESHOLD",
+    "BIKKY_DAEMON_MEMORY_QUALITY_ROLLUPS_MAX_SCOPES_PER_RUN",
     "BIKKY_USER_ID",
     "BIKKY_USER_NAME",
     "BIKKY_AGENT_ID",
@@ -190,6 +198,10 @@ const daemonConfigFileSchema = z.object({
     entity_typing_enabled: z.boolean().optional(),
     entity_typing_interval_sec: nonNegativeInt.optional(),
     entity_typing_max_entities_per_run: nonNegativeInt.optional(),
+    memory_quality_rollups_enabled: z.boolean().optional(),
+    memory_quality_rollups_interval_sec: nonNegativeInt.optional(),
+    memory_quality_rollups_low_confidence_threshold: z.number().min(0).max(1).optional(),
+    memory_quality_rollups_max_scopes_per_run: positiveInt.optional(),
     staleness_threshold_days: nonNegativeInt.optional(),
 }).passthrough();
 const watcherConfigFileSchema = z.object({
@@ -696,6 +708,22 @@ export function loadConfig() {
     const entityTypingMax = positiveInt(process.env.BIKKY_DAEMON_ENTITY_TYPING_MAX_ENTITIES_PER_RUN);
     if (entityTypingMax !== null)
         config.daemon.entity_typing_max_entities_per_run = entityTypingMax;
+    const qualityRollupsEnabled = booleanEnv(process.env.BIKKY_DAEMON_MEMORY_QUALITY_ROLLUPS_ENABLED);
+    if (qualityRollupsEnabled !== null)
+        config.daemon.memory_quality_rollups_enabled = qualityRollupsEnabled;
+    const qualityRollupsInterval = positiveInt(process.env.BIKKY_DAEMON_MEMORY_QUALITY_ROLLUPS_INTERVAL_SEC);
+    if (qualityRollupsInterval !== null)
+        config.daemon.memory_quality_rollups_interval_sec = qualityRollupsInterval;
+    const qualityRollupsThresholdRaw = process.env.BIKKY_DAEMON_MEMORY_QUALITY_ROLLUPS_LOW_CONFIDENCE_THRESHOLD;
+    if (qualityRollupsThresholdRaw) {
+        const threshold = Number.parseFloat(qualityRollupsThresholdRaw);
+        if (Number.isFinite(threshold) && threshold >= 0 && threshold <= 1) {
+            config.daemon.memory_quality_rollups_low_confidence_threshold = threshold;
+        }
+    }
+    const qualityRollupsMaxScopes = positiveInt(process.env.BIKKY_DAEMON_MEMORY_QUALITY_ROLLUPS_MAX_SCOPES_PER_RUN);
+    if (qualityRollupsMaxScopes !== null)
+        config.daemon.memory_quality_rollups_max_scopes_per_run = qualityRollupsMaxScopes;
     if (process.env.BIKKY_USER_ID)
         config.identity.user_id = process.env.BIKKY_USER_ID;
     if (process.env.BIKKY_USER_NAME)

package/dist/daemon/capture-policy.js

@@ -105,7 +105,6 @@ export const CAPTURE_KIND_SUBTYPES = {
 export const FACT_CATEGORY_TO_SUBTYPE = {
     engineering: "codebase_map",
     product: "domain_rule",
-    human: "preference",
     system: "codebase_map",
 };
 export const DEFAULT_CAPTURE_CONTEXT = {

package/dist/daemon/consolidation.js

@@ -360,7 +360,6 @@ const formatHealthReport = (report) => {
 const CATEGORY_TO_HEADING = {
     engineering: "Engineering",
     product: "Product",
-    human: "Human",
     system: "System",
     // Legacy stored categories remain readable before any data migration.
     codebase: "Engineering",
@@ -371,9 +370,10 @@ const CATEGORY_TO_HEADING = {
     projects: "System",
     observation: "Engineering",
     observations: "Engineering",
-    preferences: "Human",
-    people: "Human",
-    team: "Human",
+    human: "Engineering",
+    preferences: "Engineering",
+    people: "Engineering",
+    team: "Engineering",
 };
 const generateMemoryBrief = async (_config) => {
     if (!qdrant.isReady())

package/dist/daemon/extraction.d.ts

@@ -10,7 +10,7 @@ import type { BikkyConfig } from "../config.js";
 import type { LogFn } from "./qdrant.js";
 import { type TranscriptSource } from "./transcript-sources.js";
 export declare const setLogger: (fn: LogFn) => void;
-export declare const DEFAULT_EXTRACTION_PROMPT = "You are Bikky's memory extraction agent for open-source coding agents. Extract durable, reusable facts that help a future agent continue work without rereading the whole transcript.\n\n## Core rule\nExtract fewer, sharper memories. A candidate fact must be independently useful after the session is gone.\n\n## Quality gate\nEvery fact must pass at least one gate:\n1. GREPPABLE: names a file path, package, symbol, config key, CLI flag, issue/PR, service, or API a future agent can search for.\n2. RUNNABLE: contains a command, URL, setting, port, or procedure that can be executed or checked.\n3. NAVIGABLE: tells a future agent where to look and what that location means.\n4. DECISIVE: records a durable decision, rationale, constraint, convention, or preference.\n5. DIAGNOSTIC: captures a repeatable failure mode, root cause, or troubleshooting gotcha.\n\n## Ontology\n- domain is the activity profile. For coding-agent captures use \"software_engineering\".\n- category is subject matter: engineering | product | human | system.\n- kind is object shape. For this prompt, emit only kind=\"fact\".\n- memory_subtype must be one of:\n  codebase_map | architecture_decision | infra_topology | access_pattern | operational_procedure | domain_rule | product_decision | product_requirement | user_workflow | roadmap_item | success_metric | market_insight | troubleshooting_gotcha | preference | person_profile | ownership_note | working_agreement | activity_event.\n\n## Examples\nGOOD:\n- \"The UI smoke tests live in packages/ui/tests/smoke.spec.ts and run through npm run test:e2e with mocked /api/memory/* responses.\"\n- \"Use workspace_id as the tenancy/access boundary; domain is reserved for activity profile such as software_engineering.\"\n- \"If Qdrant order_by fails with a missing index error, create a datetime payload index for the sorted field before retrying.\"\n- \"The memory page should show categories and concrete subtype chips directly; a sub-tab layer makes the ontology harder to understand.\"\n- \"Saber prefers Node's built-in test runner for root tests; do not add Jest just for daemon unit tests.\"\n- \"Saber merged PR #85 after approving the subtype UX copy changes.\"\n\nBAD:\n- \"The tests were fixed.\" (status only)\n- \"We reviewed the code.\" (session narration)\n- \"The deployment succeeded.\" (transient and not reusable)\n- \"The agent used npm.\" (tool narration)\n- \"There was an error.\" (no root cause or reusable detail)\n\n## Output format\nReturn strict JSON:\n{\"facts\":[\n  {\n    \"content\":\"One self-contained durable fact.\",\n    \"category\":\"engineering\",\n    \"memory_subtype\":\"codebase_map\",\n    \"action_actor\":\"optional actor for activity_event only\",\n    \"action_type\":\"optional action verb for activity_event only\",\n    \"action_object\":\"optional durable object for activity_event only\",\n    \"action_outcome\":\"optional durable outcome for activity_event only\",\n    \"entities\":[\"repo-or-tool\",\"specific-module\"],\n    \"confidence\":0.9,\n    \"importance\":0.7,\n    \"quality_score\":0.8,\n    \"confidence_reason\":\"Explicitly stated in the transcript.\",\n    \"repo\":\"optional/repo-or-package\",\n    \"branch\":\"optional-branch\",\n    \"task_key\":\"optional issue/PR/task key\",\n    \"workstream_key\":\"optional stable workstream key\"\n  }\n]}\n\nScoring:\n- confidence: 0.9 explicit, 0.7 strong inference, 0.55 weak but useful inference.\n- importance: 0.8+ for decisions, infra, procedures, access, recurring failures, product requirements, ownership, and state-changing activity events; 0.6+ for useful codebase maps/preferences.\n- quality_score: 0.8+ passes multiple gates, 0.6+ passes one strong gate, below 0.6 should usually be omitted.\n\nIf nothing passes the quality gate, return {\"facts\":[]}.";
+export declare const DEFAULT_EXTRACTION_PROMPT = "You are Bikky's memory extraction agent for open-source coding agents. Extract durable, reusable facts that help a future agent continue work without rereading the whole transcript.\n\n## Core rule\nExtract fewer, sharper memories. A candidate fact must be independently useful after the session is gone.\n\n## Quality gate\nEvery fact must pass at least one gate:\n1. GREPPABLE: names a file path, package, symbol, config key, CLI flag, issue/PR, service, or API a future agent can search for.\n2. RUNNABLE: contains a command, URL, setting, port, or procedure that can be executed or checked.\n3. NAVIGABLE: tells a future agent where to look and what that location means.\n4. DECISIVE: records a durable decision, rationale, constraint, convention, or preference.\n5. DIAGNOSTIC: captures a repeatable failure mode, root cause, or troubleshooting gotcha.\n\n## Ontology\n- domain is the activity profile. For coding-agent captures use \"software_engineering\".\n- category is subject matter: engineering | product | system.\n- kind is object shape. For this prompt, emit only kind=\"fact\".\n- memory_subtype must be one of:\n  codebase_map | architecture_decision | infra_topology | access_pattern | operational_procedure | domain_rule | product_decision | product_requirement | user_workflow | roadmap_item | success_metric | market_insight | troubleshooting_gotcha | preference | person_profile | ownership_note | working_agreement | activity_event.\n\n## Examples\nGOOD:\n- \"The UI smoke tests live in packages/ui/tests/smoke.spec.ts and run through npm run test:e2e with mocked /api/memory/* responses.\"\n- \"Use workspace_id as the tenancy/access boundary; domain is reserved for activity profile such as software_engineering.\"\n- \"If Qdrant order_by fails with a missing index error, create a datetime payload index for the sorted field before retrying.\"\n- \"The memory page should show categories and concrete subtype chips directly; a sub-tab layer makes the ontology harder to understand.\"\n- \"Saber prefers Node's built-in test runner for root tests; do not add Jest just for daemon unit tests.\"\n- \"Saber merged PR #85 after approving the subtype UX copy changes.\"\n\nBAD:\n- \"The tests were fixed.\" (status only)\n- \"We reviewed the code.\" (session narration)\n- \"The deployment succeeded.\" (transient and not reusable)\n- \"The agent used npm.\" (tool narration)\n- \"There was an error.\" (no root cause or reusable detail)\n\n## Output format\nReturn strict JSON:\n{\"facts\":[\n  {\n    \"content\":\"One self-contained durable fact.\",\n    \"category\":\"engineering\",\n    \"memory_subtype\":\"codebase_map\",\n    \"action_actor\":\"optional actor for activity_event only\",\n    \"action_type\":\"optional action verb for activity_event only\",\n    \"action_object\":\"optional durable object for activity_event only\",\n    \"action_outcome\":\"optional durable outcome for activity_event only\",\n    \"entities\":[\"repo-or-tool\",\"specific-module\"],\n    \"confidence\":0.9,\n    \"importance\":0.7,\n    \"quality_score\":0.8,\n    \"confidence_reason\":\"Explicitly stated in the transcript.\",\n    \"repo\":\"optional/repo-or-package\",\n    \"branch\":\"optional-branch\",\n    \"task_key\":\"optional issue/PR/task key\",\n    \"workstream_key\":\"optional stable workstream key\"\n  }\n]}\n\nScoring:\n- confidence: 0.9 explicit, 0.7 strong inference, 0.55 weak but useful inference.\n- importance: 0.8+ for decisions, infra, procedures, access, recurring failures, product requirements, ownership, and state-changing activity events; 0.6+ for useful codebase maps/preferences.\n- quality_score: 0.8+ passes multiple gates, 0.6+ passes one strong gate, below 0.6 should usually be omitted.\n\nIf nothing passes the quality gate, return {\"facts\":[]}.";
 export type Volatility = "stable" | "evolving" | "transient" | "ephemeral";
 export interface ExtractedFact {
     content: string;

package/dist/daemon/extraction.js

@@ -43,7 +43,7 @@ Every fact must pass at least one gate:
 
 ## Ontology
 - domain is the activity profile. For coding-agent captures use "software_engineering".
-- category is subject matter: engineering | product | human | system.
+- category is subject matter: engineering | product | system.
 - kind is object shape. For this prompt, emit only kind="fact".
 - memory_subtype must be one of:
   codebase_map | architecture_decision | infra_topology | access_pattern | operational_procedure | domain_rule | product_decision | product_requirement | user_workflow | roadmap_item | success_metric | market_insight | troubleshooting_gotcha | preference | person_profile | ownership_note | working_agreement | activity_event.
@@ -210,8 +210,8 @@ export const factQualitySignals = (fact) => {
     const isPreferenceLike = subtype === "preference" || subtype === "domain_rule" || subtype === "working_agreement";
     const isDecisionLike = subtype === "architecture_decision" || subtype === "product_decision" || subtype === "troubleshooting_gotcha";
     const isProductLike = subtype === "product_requirement" || subtype === "user_workflow" || subtype === "roadmap_item" || subtype === "success_metric" || subtype === "market_insight";
-    const isHumanLike = subtype === "person_profile" || subtype === "ownership_note" || subtype === "activity_event";
-    const shortUseful = wordCount >= 7 && wordCount <= 22 && (isPreferenceLike || isDecisionLike || isProductLike || isHumanLike) && (entities.length > 0 || durableAnchor);
+    const isCollaborationLike = subtype === "person_profile" || subtype === "ownership_note" || subtype === "activity_event";
+    const shortUseful = wordCount >= 7 && wordCount <= 22 && (isPreferenceLike || isDecisionLike || isProductLike || isCollaborationLike) && (entities.length > 0 || durableAnchor);
     let score = 0.25;
     if (wordCount >= 8)
         score += 0.1;
@@ -219,7 +219,7 @@ export const factQualitySignals = (fact) => {
         score += 0.1;
     if (durableAnchor)
         score += 0.25;
-    if (isPreferenceLike || isDecisionLike || isProductLike || isHumanLike)
+    if (isPreferenceLike || isDecisionLike || isProductLike || isCollaborationLike)
         score += 0.15;
     if ((fact.confidence ?? 0) >= 0.75)
         score += 0.1;
@@ -254,8 +254,16 @@ const subtypeForRawCategoryHint = (rawCategory, category) => {
         return "operational_procedure";
     if (hint.includes("decision"))
         return "architecture_decision";
-    if (hint.includes("people") || hint.includes("preference") || hint.includes("owner"))
+    if (hint.includes("preference"))
         return "preference";
+    if (hint.includes("owner"))
+        return "ownership_note";
+    if (hint.includes("agreement"))
+        return "working_agreement";
+    if (hint.includes("activity") || hint.includes("actor"))
+        return "activity_event";
+    if (hint.includes("people") || hint.includes("person") || hint.includes("team"))
+        return "person_profile";
     if (hint.includes("product") || hint.includes("domain"))
         return "domain_rule";
     return subtypeForCategory(normalizeCategory(category));

package/dist/daemon/loop.js

@@ -11,6 +11,7 @@ import { tick as extractionTick, setLogger as setExtractionLogger } from "./extr
 import { tick as consolidationTick, setLogger as setConsolidationLogger } from "./consolidation.js";
 import { tick as relationsTick, setLogger as setRelationsLogger } from "./relations.js";
 import { tick as entityTypingTick, setLogger as setEntityTypingLogger } from "./entity-typing.js";
+import { tick as qualityRollupsTick, setLogger as setQualityRollupsLogger } from "./quality-rollups.js";
 import { scanStaleFacts, setLogger as setStalenessLogger } from "./staleness.js";
 import { inspectWatcherPaths, formatIssue } from "./watcher-health.js";
 // createLogger returns (LogLevel, ...args) but daemon modules accept (string, ...args).
@@ -34,6 +35,7 @@ export async function startDaemon() {
     setConsolidationLogger(log);
     setRelationsLogger(log);
     setEntityTypingLogger(log);
+    setQualityRollupsLogger(log);
     setStalenessLogger(log);
     // Initialize LLM client from config
     initLLM({
@@ -107,6 +109,12 @@ export async function startDaemon() {
         catch (e) {
             log("ERROR", `Entity typing tick failed: ${e.message}`);
         }
+        try {
+            await qualityRollupsTick(cfg);
+        }
+        catch (e) {
+            log("ERROR", `Memory quality rollups tick failed: ${e.message}`);
+        }
         // Staleness scans every 1000 ticks (~83 min at 5s interval)
         if (tickCount % 1000 === 0) {
             try {

package/dist/daemon/maintenance-state.d.ts

@@ -1,6 +1,6 @@
 import type { LogFn } from "./qdrant.js";
 export declare const MAINTENANCE_STATE_PATH: string;
-export type MaintenanceJobName = "relation_inference" | "entity_typing";
+export type MaintenanceJobName = "relation_inference" | "entity_typing" | "memory_quality_rollups";
 export interface MaintenanceRunSummary {
     job: MaintenanceJobName;
     ran_at: string;

package/dist/daemon/maintenance-state.js

@@ -13,6 +13,7 @@ export const defaultMaintenanceState = () => ({
     jobs: {
         relation_inference: defaultJobState(),
         entity_typing: defaultJobState(),
+        memory_quality_rollups: defaultJobState(),
     },
 });
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -42,6 +43,7 @@ export const readMaintenanceState = (log = () => { }) => {
             jobs: {
                 relation_inference: coerceJobState(jobs.relation_inference),
                 entity_typing: coerceJobState(jobs.entity_typing),
+                memory_quality_rollups: coerceJobState(jobs.memory_quality_rollups),
             },
         };
     }

package/dist/daemon/qdrant.js

@@ -15,6 +15,7 @@ import { buildResolver } from "../routing.js";
 import { DEFAULT_DOMAIN, QDRANT_INDEXES, categoryForMemorySubtype, layerForMemorySubtype, normalizeCategory, normalizeDomain, normalizeKind, validateMemorySubtype, } from "../mcp/taxonomy.js";
 import { combineRedactions, redactStorageText, } from "../privacy/redaction.js";
 import { buildOperationOrigin } from "../provenance/origin.js";
+import { buildMemoryRoutingInput, mergeRoutingInputs } from "../routing-context.js";
 // ---------------------------------------------------------------------------
 // State
 // ---------------------------------------------------------------------------
@@ -56,10 +57,8 @@ const pathForDestination = (urlPath, destination) => {
         return urlPath;
     return urlPath.replace(/^\/collections\/[^/]+/, `/collections/${destination.collection}`);
 };
-const routingInputForFact = (fact, normalizedContent, normalizedEntities, extraMetadata = {}) => ({
-    content: normalizedContent,
-    entities: normalizedEntities,
-    metadata: {
+const routingInputForFact = (fact, normalizedContent, normalizedEntities, extraMetadata = {}) => {
+    const metadata = {
         ...(fact.metadata ?? {}),
         ...extraMetadata,
         category: fact.category,
@@ -75,8 +74,31 @@ const routingInputForFact = (fact, normalizedContent, normalizedEntities, extraM
         ...(fact.repo ? { repo: fact.repo } : {}),
         ...(fact.branch ? { branch: fact.branch } : {}),
         ...(fact.surface ? { surface: fact.surface } : {}),
-    },
-});
+        ...(fact.issue_id ? { issue_id: fact.issue_id } : {}),
+        ...(fact.pr_id ? { pr_id: fact.pr_id } : {}),
+        ...(fact.source_event_ids ? { source_event_ids: fact.source_event_ids } : {}),
+        ...(fact.source_fact_ids ? { source_fact_ids: fact.source_fact_ids } : {}),
+        ...(fact.source_episode_ids ? { source_episode_ids: fact.source_episode_ids } : {}),
+        ...(fact.prompt_version ? { prompt_version: fact.prompt_version } : {}),
+        ...(fact.capture_policy_version ? { capture_policy_version: fact.capture_policy_version } : {}),
+        ...(fact.review_status ? { review_status: fact.review_status } : {}),
+        ...(fact.volatility ? { volatility: fact.volatility } : {}),
+        ...(fact.valid_from ? { valid_from: fact.valid_from } : {}),
+        ...(fact.expires_at ? { expires_at: fact.expires_at } : {}),
+        ...(fact.confidence_reason ? { confidence_reason: fact.confidence_reason } : {}),
+        ...(fact.relation ? {
+            from_entity: fact.relation.from,
+            relation_type: fact.relation.type,
+            to_entity: fact.relation.to,
+        } : {}),
+    };
+    return buildMemoryRoutingInput({
+        content: normalizedContent,
+        entities: normalizedEntities,
+        metadata,
+        extraContent: [fact.origin, fact.last_operation_origin, fact.relation],
+    });
+};
 // ---------------------------------------------------------------------------
 // Init — reads credentials from loadConfig()
 // ---------------------------------------------------------------------------
@@ -373,12 +395,12 @@ const storeFact = async (fact, routeInput) => {
     if (redaction.redacted) {
         payload.redaction = redaction;
     }
-    const destination = resolveDestination(routeInput ?? routingInputForFact(fact, redactedContent.text, payload.entities, {
+    const destination = resolveDestination(mergeRoutingInputs(routingInputForFact(fact, redactedContent.text, payload.entities, {
         category: normalizedCategory,
         domain: normalizedDomain,
         kind: normalizedKind,
         ...(normalizedSubtype ? { memory_subtype: normalizedSubtype } : {}),
-    }));
+    }), routeInput));
     const vector = await embed(redactedContent.text);
     await qdrantRequest("PUT", `/collections/${destination.collection}/points`, {
         points: [{ id, vector, payload }],

package/dist/daemon/quality-rollups.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Backend aggregation for memory quality telemetry.
+ */
+import type { BikkyConfig, Destination } from "../config.js";
+import type { FactPayload } from "../mcp/types.js";
+import type { LogFn } from "./qdrant.js";
+export type QualityScopeType = "destination" | "repo" | "workstream_key" | "task_key" | "entity" | "origin_user" | "origin_agent";
+export interface QualityPoint {
+    id: string;
+    destination: string;
+    payload: Partial<FactPayload>;
+}
+export interface QualityRollup {
+    destination: string;
+    scope_type: QualityScopeType;
+    scope_value: string;
+    active_fact_count: number;
+    recall_count: number;
+    useful_count: number;
+    misleading_count: number;
+    wrong_count: number;
+    stale_count: number;
+    low_confidence_count: number;
+    generated_at: string;
+    source_fact_ids: string[];
+    source_event_ids: string[];
+}
+export interface QualityRollupResult {
+    destinations_seen: number;
+    facts_seen: number;
+    events_seen: number;
+    rollups_upserted: number;
+    scopes_capped: boolean;
+}
+export interface QualityRollupDeps {
+    isReady: () => boolean;
+    activeDestinations: () => Destination[];
+    qdrantRequest: (method: string, urlPath: string, body?: unknown, destinationRef?: Destination | string | null) => Promise<Record<string, unknown>>;
+    embed: (text: string) => Promise<number[]>;
+}
+export declare const setLogger: (fn: LogFn) => void;
+export declare const buildQualityRollups: (input: {
+    facts: QualityPoint[];
+    events?: QualityPoint[];
+    generatedAt?: Date;
+    staleThresholdDays?: number;
+    lowConfidenceThreshold?: number;
+}) => QualityRollup[];
+export declare const aggregateMemoryQualitySignals: (config: BikkyConfig, deps?: QualityRollupDeps) => Promise<QualityRollupResult>;
+export declare const tick: (config: BikkyConfig, deps?: QualityRollupDeps) => Promise<void>;
+//# sourceMappingURL=quality-rollups.d.ts.map