bikky 0.4.2 → 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
 
-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.
+- 👥 **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.
 
-### 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).
 
@@ -101,22 +122,22 @@ bikky supports four common setup shapes. Pick based on where you want Qdrant to
 | ----------------------- | ------------------------------ | ---------------------------------------------------------------------------------------- |
 | **Node.js**             | ≥ 20                           | `nvm install 20` or your package manager                                                 |
 | **Vector store**        | Qdrant                         | Local Docker · [Qdrant Cloud](https://cloud.qdrant.io) · Self-hosted                     |
-| **Embeddings**          | One provider                   | OpenAI · Ollama · Bedrock · Portkey                                                     |
-| **LLM**                 | One provider                   | OpenAI · Ollama · Bedrock · Portkey                                                     |
+| **Embeddings**          | One provider                   | Portkey · OpenAI · Ollama · Bedrock                                                     |
+| **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`.
+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
 
@@ -128,6 +149,8 @@ Pick the setup guide above for the copy-paste config. All setup shapes use the s
 
 Config lives at `~/.bikky/config.json`, or at `BIKKY_HOME/config.json` when `BIKKY_HOME` is set. You can keep credentials out of the file with environment variables such as `QDRANT_URL`, `QDRANT_API_KEY`, and provider API keys.
 
+`bikky setup` also provisions `identity.user_id` / `identity.user_name` when they are missing. New memory writes store canonical `origin` metadata with the configured human user, the acting agent or daemon/UI surface, the interface, and the operation. MCP clients cannot supply or spoof `origin.user`; if config, env, Git, and shell identity detection all fail, bikky falls back to the local hostname.
+
 For hosted models, custom providers, multiple profiles, or advanced tuning, use the full configuration guide.
 
 > 📖 **Full configuration guide:** [docs/configuration.md][configuration-guide]
@@ -194,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/source, 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" />
@@ -205,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

@@ -4,6 +4,12 @@
  * Resolution order: defaults → ~/.bikky/config.json → env vars.
  * Config directory: ~/.bikky/
  */
+export declare function getBikkyDir(): string;
+export declare function getConfigPath(): string;
+export declare function getLogDir(): string;
+export declare function getStateDir(): string;
+export declare function getPidPath(): string;
+export declare function getExtractionHealthPath(): string;
 export declare const BIKKY_DIR: string;
 export declare const CONFIG_PATH: string;
 export declare const LOG_DIR: string;
@@ -55,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 {
@@ -63,7 +73,11 @@ export interface QdrantClientConfig {
     retry_base_delay_ms: number;
 }
 export interface IdentityConfig {
+    user_id: string | null;
+    user_name: string | null;
+    /** @deprecated Use origin.user.id instead. */
     actor_id: string | null;
+    /** @deprecated Use origin.user.name / origin.agent.name instead. */
     actor_label: string | null;
 }
 export interface WatcherConfig {
@@ -158,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", "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_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

@@ -12,15 +12,41 @@ import { z } from "zod";
 // Paths
 // ---------------------------------------------------------------------------
 // BIKKY_HOME env var lets tests (and advanced users) override the config dir
-// without touching the real ~/.bikky/. Tests MUST set this to an isolated
-// tempdir before importing this module — otherwise saveConfig() will write to
-// the user's real config file.
-export const BIKKY_DIR = process.env.BIKKY_HOME ?? path.join(os.homedir(), ".bikky");
-export const CONFIG_PATH = path.join(BIKKY_DIR, "config.json");
-export const LOG_DIR = path.join(BIKKY_DIR, "logs");
-export const STATE_DIR = path.join(BIKKY_DIR, "state");
-export const PID_PATH = path.join(STATE_DIR, "daemon.pid");
-export const EXTRACTION_HEALTH_PATH = path.join(STATE_DIR, "extraction-health.json");
+// without touching the real ~/.bikky/. The getter functions below re-read the
+// env var on every call, so changing BIKKY_HOME at runtime (e.g. in a test
+// setup hook) takes effect for all subsequent saveConfig()/loadConfig() calls.
+//
+// The legacy `BIKKY_DIR` / `CONFIG_PATH` / etc. exports are kept for
+// backward-compatibility, but they capture the env state at module load
+// time and should NOT be relied on for safe writes. Internal callers — and
+// any test that wants sandboxing — should call the getter functions instead.
+export function getBikkyDir() {
+    return process.env.BIKKY_HOME ?? path.join(os.homedir(), ".bikky");
+}
+export function getConfigPath() {
+    return path.join(getBikkyDir(), "config.json");
+}
+export function getLogDir() {
+    return path.join(getBikkyDir(), "logs");
+}
+export function getStateDir() {
+    return path.join(getBikkyDir(), "state");
+}
+export function getPidPath() {
+    return path.join(getStateDir(), "daemon.pid");
+}
+export function getExtractionHealthPath() {
+    return path.join(getStateDir(), "extraction-health.json");
+}
+// Legacy constant exports — captured at module load. Prefer the getter
+// functions above when you need fresh values (e.g. inside tests, or after
+// mutating BIKKY_HOME at runtime).
+export const BIKKY_DIR = getBikkyDir();
+export const CONFIG_PATH = getConfigPath();
+export const LOG_DIR = getLogDir();
+export const STATE_DIR = getStateDir();
+export const PID_PATH = getPidPath();
+export const EXTRACTION_HEALTH_PATH = getExtractionHealthPath();
 // ---------------------------------------------------------------------------
 // Defaults
 // ---------------------------------------------------------------------------
@@ -66,9 +92,15 @@ 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: {
+        user_id: null,
+        user_name: null,
         actor_id: null,
         actor_label: null,
     },
@@ -91,6 +123,7 @@ export const CONFIG_ENV_KEYS = [
     "EMBEDDING_BASE_URL",
     "EMBEDDING_DIMENSIONS",
     "OPENAI_API_KEY",
+    "PORTKEY_API_KEY",
     "LLM_PROVIDER",
     "LLM_MODEL",
     "LLM_BASE_URL",
@@ -113,6 +146,14 @@ 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",
+    "BIKKY_AGENT_NAME",
     "BIKKY_ACTOR_ID",
     "BIKKY_ACTOR_LABEL",
 ];
@@ -122,7 +163,7 @@ const CONFIG_ENV_PREFIXES = [
 ];
 const nonNegativeInt = z.number().int().nonnegative();
 const positiveInt = z.number().int().positive();
-const stringRecord = z.record(z.string());
+const stringRecord = z.record(z.string(), z.string());
 const embeddingConfigFileSchema = z.object({
     provider: z.string().optional(),
     model: z.string().optional(),
@@ -157,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({
@@ -175,6 +220,8 @@ const qdrantClientConfigFileSchema = z.object({
     retry_base_delay_ms: nonNegativeInt.optional(),
 }).passthrough();
 const identityConfigFileSchema = z.object({
+    user_id: z.string().nullable().optional(),
+    user_name: z.string().nullable().optional(),
     actor_id: z.string().nullable().optional(),
     actor_label: z.string().nullable().optional(),
 }).passthrough();
@@ -183,7 +230,7 @@ const destinationMatchSchema = z.object({
     cwd: regexArrayField,
     entity: regexArrayField,
     content: regexArrayField,
-    metadata: z.record(z.array(z.string())).optional(),
+    metadata: z.record(z.string(), z.array(z.string())).optional(),
 }).passthrough();
 const destinationFileSchema = z.object({
     name: z.string().min(1),
@@ -442,7 +489,7 @@ export function validateConfigObject(raw) {
         validateUrlLike(llm.base_url, "llm.base_url", issues);
     return issues;
 }
-export function inspectConfigFile(configPath = CONFIG_PATH) {
+export function inspectConfigFile(configPath = getConfigPath()) {
     if (!fs.existsSync(configPath)) {
         return { path: configPath, exists: false, parse_error: null, issues: [] };
     }
@@ -490,21 +537,41 @@ export function loadConfig() {
     if (_config)
         return _config;
     // Ensure dirs exist
-    fs.mkdirSync(BIKKY_DIR, { recursive: true });
-    fs.mkdirSync(LOG_DIR, { recursive: true });
-    fs.mkdirSync(STATE_DIR, { recursive: true });
+    fs.mkdirSync(getBikkyDir(), { recursive: true });
+    fs.mkdirSync(getLogDir(), { recursive: true });
+    fs.mkdirSync(getStateDir(), { recursive: true });
     // Start from defaults
     let config = structuredClone(DEFAULTS);
     // Merge config file
-    if (fs.existsSync(CONFIG_PATH)) {
+    const configPath = getConfigPath();
+    let fileConfig = {};
+    if (fs.existsSync(configPath)) {
         try {
-            const fileConfig = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf-8"));
+            fileConfig = JSON.parse(fs.readFileSync(configPath, "utf-8"));
             config = deepMerge(config, fileConfig);
         }
         catch (e) {
-            console.error(`bikky: failed to parse ${CONFIG_PATH}: ${e instanceof Error ? e.message : String(e)}`);
+            console.error(`bikky: failed to parse ${configPath}: ${e instanceof Error ? e.message : String(e)}`);
         }
     }
+    // Provider/base_url consistency (issue #131): the DEFAULTS.embedding.base_url
+    // is the ollama localhost URL, baked in for the default ollama provider. If
+    // the user picks a different provider (portkey/openai/bedrock) but doesn't
+    // set an explicit base_url, drop the inherited ollama URL so initEmbedding()
+    // can apply the provider's own default — otherwise we'd POST every embedding
+    // request to localhost:11434 and Ollama would reject the foreign model name.
+    const fileEmbedding = (fileConfig.embedding ?? {});
+    if (config.embedding.provider !== DEFAULTS.embedding.provider
+        && typeof fileEmbedding.base_url !== "string"
+        && !process.env.EMBEDDING_BASE_URL) {
+        config.embedding.base_url = "";
+    }
+    const fileLlm = (fileConfig.llm ?? {});
+    if (config.llm.provider !== DEFAULTS.llm.provider
+        && typeof fileLlm.base_url !== "string"
+        && !process.env.LLM_BASE_URL) {
+        config.llm.base_url = "";
+    }
     // Env var overrides (highest priority)
     if (process.env.QDRANT_URL)
         config.qdrant_url = process.env.QDRANT_URL;
@@ -526,6 +593,12 @@ export function loadConfig() {
     }
     if (process.env.OPENAI_API_KEY)
         config.embedding.api_key = process.env.OPENAI_API_KEY;
+    // Portkey users can supply their gateway key via PORTKEY_API_KEY without
+    // needing to repurpose OPENAI_API_KEY. Only applied when the embedding
+    // provider is Portkey, so non-Portkey setups remain untouched.
+    if (process.env.PORTKEY_API_KEY && config.embedding.provider === "portkey") {
+        config.embedding.api_key = process.env.PORTKEY_API_KEY;
+    }
     // Generic provider-extras: BIKKY_EMBEDDING_EXTRA_<KEY>=value
     config.embedding.extra = config.embedding.extra ?? {};
     for (const [k, v] of Object.entries(process.env)) {
@@ -542,6 +615,9 @@ export function loadConfig() {
         config.llm.base_url = process.env.LLM_BASE_URL;
     if (process.env.OPENAI_API_KEY && !config.llm.api_key)
         config.llm.api_key = process.env.OPENAI_API_KEY;
+    if (process.env.PORTKEY_API_KEY && config.llm.provider === "portkey" && !config.llm.api_key) {
+        config.llm.api_key = process.env.PORTKEY_API_KEY;
+    }
     if (process.env.LLM_FALLBACK_PROVIDER)
         config.llm.fallback_provider = process.env.LLM_FALLBACK_PROVIDER;
     if (process.env.AWS_PROFILE)
@@ -632,6 +708,26 @@ 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)
+        config.identity.user_name = process.env.BIKKY_USER_NAME;
     if (process.env.BIKKY_ACTOR_ID)
         config.identity.actor_id = process.env.BIKKY_ACTOR_ID;
     if (process.env.BIKKY_ACTOR_LABEL)
@@ -679,8 +775,8 @@ export function getEffectiveDestinations(config = loadConfig()) {
 }
 /** Save config to disk (used by setup command). */
 export function saveConfig(config) {
-    fs.mkdirSync(BIKKY_DIR, { recursive: true });
-    fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + "\n");
+    fs.mkdirSync(getBikkyDir(), { recursive: true });
+    fs.writeFileSync(getConfigPath(), JSON.stringify(config, null, 2) + "\n");
     _config = config;
 }
 /** Reset cached config (for testing). */

package/dist/daemon/capture-policy.d.ts

@@ -86,7 +86,6 @@ export declare const CAPTURE_KIND_SUBTYPES: {
 export declare const FACT_CATEGORY_TO_SUBTYPE: Record<Category, MemorySubtype>;
 export declare const DEFAULT_CAPTURE_CONTEXT: {
     readonly domain: "software_engineering" | "product_strategy" | "business_operations" | "research" | "personal_productivity";
-    readonly source: "system";
     readonly reviewStatus: "candidate";
     readonly volatility: "evolving";
 };

package/dist/daemon/capture-policy.js

@@ -105,12 +105,10 @@ 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 = {
     domain: DEFAULT_DOMAIN,
-    source: "system",
     reviewStatus: "candidate",
     // Default fallback volatility when the LLM does not self-judge. Storage path
     // overrides this with the LLM's value (or the volatility verifier's

package/dist/daemon/consolidation.d.ts

@@ -51,6 +51,7 @@ declare const detectContradiction: (fact: {
 }, _config: BikkyConfig, telemetry?: {
     sessionId?: string;
     workstreamKey?: string;
+    destination?: string;
 }) => Promise<ContradictionResult>;
 /**
  * Main consolidation tick — called from daemon tick loop.
@@ -58,6 +59,6 @@ declare const detectContradiction: (fact: {
  */
 declare const tick: (config: BikkyConfig, opts?: ConsolidationTickOptions) => Promise<void>;
 /** Reset state (for testing). */
-declare const _reset: () => void;
+declare const _reset: (tickCount?: number) => void;
 export { detectContradiction, tick, setLogger, _reset, };
 //# sourceMappingURL=consolidation.d.ts.map