bikky 0.4.2 → 0.4.4

package/dist/status.js

@@ -235,13 +235,18 @@ function collectMaintenanceStatus() {
             last_summary: job.last_summary,
         };
     };
-    const summaries = [state.jobs.relation_inference.last_summary, state.jobs.entity_typing.last_summary];
+    const summaries = [
+        state.jobs.relation_inference.last_summary,
+        state.jobs.entity_typing.last_summary,
+        state.jobs.memory_quality_rollups.last_summary,
+    ];
     const hasError = summaries.some((summary) => summary?.status === "error");
     return {
         status: hasError ? "warn" : "ok",
         state_path: MAINTENANCE_STATE_PATH,
         relation_inference: jobStatus("relation_inference"),
         entity_typing: jobStatus("entity_typing"),
+        memory_quality_rollups: jobStatus("memory_quality_rollups"),
     };
 }
 async function collectUiStatus(opts) {
@@ -368,6 +373,7 @@ export function formatStatusReport(report) {
     lines.push(`Daemon:   ${icon(report.daemon.status)} ${report.daemon.running ? `running (PID ${report.daemon.pid})` : "stopped"}`);
     lines.push(`Maint:    ${icon(report.maintenance.status)} ${maintenanceJobSummary("relations", report.maintenance.relation_inference)}`);
     lines.push(`          ${maintenanceJobSummary("entity typing", report.maintenance.entity_typing)}`);
+    lines.push(`          ${maintenanceJobSummary("quality rollups", report.maintenance.memory_quality_rollups)}`);
     lines.push(`UI:       ${icon(report.ui.status)} ${report.ui.checked ? report.ui.url : "not checked"}${report.ui.error ? ` — ${report.ui.error}` : ""}`);
     lines.push(`MCP:      ${icon(report.mcp.status)} ${report.mcp.message}`);
     return lines.join("\n");

package/docs/config/fully-hosted.md

@@ -1,16 +1,16 @@
 # Fully hosted config
 
-Best for performance and teams. This setup uses Qdrant Cloud for managed vector storage and OpenAI-compatible hosted models for extraction, curation, and recall.
+Best for performance and teams. This setup uses Qdrant Cloud for managed vector storage and a hosted gateway/provider for extraction, curation, and recall.
 
 ## What you need
 
 - A Qdrant Cloud cluster URL.
 - A Qdrant API key.
-- An OpenAI API key, or another hosted provider configured in the full configuration guide.
+- A Portkey API key (recommended) — one key, many upstream providers, with built-in routing, fallbacks, and observability. Get one at [portkey.ai](https://portkey.ai). Or use OpenAI / Bedrock directly.
 
-For both `embedding.provider` and `llm.provider`, possible values are `openai`, `bedrock`, or `portkey` for hosted models. `ollama` is also supported when you want local model calls.
+For both `embedding.provider` and `llm.provider`, possible values are `portkey`, `openai`, or `bedrock` for hosted models. `ollama` is also supported when you want local model calls.
 
-## Config
+## Config (recommended: Portkey)
 
 Save this as `~/.bikky/config.json`:
 
@@ -18,10 +18,36 @@ Save this as `~/.bikky/config.json`:
 {
   "qdrant_url": "https://your-cluster.cloud.qdrant.io:6333",
   "qdrant_api_key": "your-qdrant-api-key",
+  "embedding": {
+    "provider": "portkey",
+    "model": "@openai/text-embedding-3-small",
+    "dimensions": 1024
+  },
+  "llm": {
+    "provider": "portkey",
+    "model": "@anthropic/claude-sonnet-4"
+  }
+}
+```
+
+Then export the gateway key:
+
+```bash
+export PORTKEY_API_KEY="pk-..."
+```
+
+bikky uses **1024-dimensional embeddings** as the canonical default. This is portable across modern providers (OpenAI 3-small/3-large via Matryoshka truncation, Cohere v3, Voyage, Mistral, Bedrock Titan v2, BGE/E5) so you can switch providers later without re-embedding.
+
+`qdrant_api_key` is optional only for unauthenticated self-hosted Qdrant. Qdrant Cloud usually requires it.
+
+## Alternative: OpenAI directly
+
+```json
+{
   "embedding": {
     "provider": "openai",
     "model": "text-embedding-3-small",
-    "dimensions": 1536,
+    "dimensions": 1024,
     "api_key": "sk-..."
   },
   "llm": {
@@ -32,13 +58,7 @@ Save this as `~/.bikky/config.json`:
 }
 ```
 
-`qdrant_api_key` is optional only for unauthenticated self-hosted Qdrant. Qdrant Cloud usually requires it.
-
-Prefer not to store hosted model keys in the config file? Omit `api_key` above and set:
-
-```bash
-export OPENAI_API_KEY="sk-..."
-```
+Or set `OPENAI_API_KEY` in the environment instead of the config file.
 
 ## Check it
 
@@ -54,4 +74,4 @@ bikky stop && bikky start
 
 Then restart your editor so its MCP process reloads.
 
-For Bedrock, Portkey, custom base URLs, or model-specific dimensions, see the [full configuration guide](https://github.com/bikky-dev/bikky/blob/main/docs/configuration.md).
+For Bedrock, custom base URLs, or model-specific dimensions, see the [full configuration guide](https://github.com/bikky-dev/bikky/blob/main/docs/configuration.md).

package/docs/config/hosted-models.md

@@ -1,15 +1,15 @@
 # Local Qdrant + hosted models config
 
-This setup keeps Qdrant local while hosted embeddings and LLM calls handle extraction, curation, and recall.
+This setup keeps Qdrant local while a hosted gateway/provider handles extraction, curation, and recall.
 
 ## What you need
 
 - Qdrant running locally, usually with Docker.
-- An OpenAI API key, or another hosted provider configured in the full configuration guide.
+- A Portkey API key (recommended) — one key, many upstream providers, with built-in routing, fallbacks, and observability. Get one at [portkey.ai](https://portkey.ai). Or use OpenAI / Bedrock directly.
 
-For both `embedding.provider` and `llm.provider`, possible values are `openai`, `bedrock`, or `portkey` for hosted models. `ollama` is also supported when you want local model calls.
+For both `embedding.provider` and `llm.provider`, possible values are `portkey`, `openai`, or `bedrock` for hosted models. `ollama` is also supported when you want local model calls.
 
-## Config
+## Config (recommended: Portkey)
 
 Save this as `~/.bikky/config.json`:
 
@@ -17,10 +17,36 @@ Save this as `~/.bikky/config.json`:
 {
   "qdrant_url": "http://localhost:6333",
   "qdrant_api_key": "",
+  "embedding": {
+    "provider": "portkey",
+    "model": "@openai/text-embedding-3-small",
+    "dimensions": 1024
+  },
+  "llm": {
+    "provider": "portkey",
+    "model": "@anthropic/claude-sonnet-4"
+  }
+}
+```
+
+Then export the gateway key:
+
+```bash
+export PORTKEY_API_KEY="pk-..."
+```
+
+bikky uses **1024-dimensional embeddings** as the canonical default. This is portable across modern providers (OpenAI 3-small/3-large via Matryoshka truncation, Cohere v3, Voyage, Mistral, Bedrock Titan v2, BGE/E5) so you can switch providers later without re-embedding.
+
+`qdrant_api_key` is optional. Leave it empty or omit it for local or unauthenticated self-hosted Qdrant.
+
+## Alternative: OpenAI directly
+
+```json
+{
   "embedding": {
     "provider": "openai",
     "model": "text-embedding-3-small",
-    "dimensions": 1536,
+    "dimensions": 1024,
     "api_key": "sk-..."
   },
   "llm": {
@@ -31,13 +57,7 @@ Save this as `~/.bikky/config.json`:
 }
 ```
 
-`qdrant_api_key` is optional. Leave it empty or omit it for local or unauthenticated self-hosted Qdrant.
-
-Prefer not to store hosted model keys in the config file? Omit `api_key` above and set:
-
-```bash
-export OPENAI_API_KEY="sk-..."
-```
+Or set `OPENAI_API_KEY` in the environment instead of the config file.
 
 ## Check it
 
@@ -47,4 +67,4 @@ bikky status
 
 If you started from a fresh install, run `bikky setup` after writing the config, then restart your editor so its MCP process reloads.
 
-For Bedrock, Portkey, custom base URLs, or model-specific dimensions, see the [full configuration guide](https://github.com/bikky-dev/bikky/blob/main/docs/configuration.md).
+For Bedrock, custom base URLs, or model-specific dimensions, see the [full configuration guide](https://github.com/bikky-dev/bikky/blob/main/docs/configuration.md).

package/docs/config/hosted-qdrant-local-models.md

@@ -8,6 +8,7 @@ Use this path when you want memory shared across machines, but you still want em
 - A Qdrant API key.
 - Ollama installed locally.
 - The default embedding model pulled with `ollama pull qwen3-embedding:0.6b`.
+- The default LLM model pulled with `ollama pull qwen2.5:7b`.
 
 ## Config
 

package/docs/config/local.md

@@ -9,6 +9,7 @@ This setup is best for private/free testing rather than long-term team use. Extr
 - Qdrant running locally, usually with Docker.
 - Ollama installed locally.
 - The default embedding model pulled with `ollama pull qwen3-embedding:0.6b`.
+- The default LLM model pulled with `ollama pull qwen2.5:7b`.
 
 ## Config
 

package/docs/configuration.md

@@ -11,7 +11,7 @@ cat > ~/.bikky/config.json <<'JSON'
   "embedding": {
     "provider": "openai",
     "model": "text-embedding-3-small",
-    "dimensions": 1536,
+    "dimensions": 1024,
     "api_key": "sk-..."
   },
   "llm": {
@@ -24,7 +24,21 @@ JSON
 bikky status
 ```
 
-Config lives at `~/.bikky/config.json`, or at `BIKKY_HOME/config.json` when `BIKKY_HOME` is set. Environment variables override the config file.
+Config lives at `~/.bikky/config.json`, or at `BIKKY_HOME/config.json` when `BIKKY_HOME` is set. Environment variables can supply or override most scalar settings. Provider API key env vars such as `OPENAI_API_KEY` and `PORTKEY_API_KEY` are fallback values when the matching `api_key` field is omitted from config; remove the config value when you want key rotation through the environment.
+
+## Origin identity
+
+New memory writes store canonical `origin` metadata. `origin.user` is the configured human identity, `origin.agent` is the automated actor or local surface, `origin.interface` is the entry point (`mcp`, `daemon`, `ui`, `api`, `cli`, or `system`), and `origin.operation` records the create/update/delete/verify/forget/review/correct/reinforce/supersede/feedback action.
+
+`bikky setup` provisions `identity.user_id` and `identity.user_name` if they are missing. It never overwrites an existing configured user. Runtime detection uses this order:
+
+1. `identity.user_id` / `identity.user_name` from config
+2. `BIKKY_USER_ID` / `BIKKY_USER_NAME`
+3. Git config (`user.name`, `user.email`; email-like identifiers are hashed)
+4. Shell/OS username
+5. Hostname fallback
+
+MCP callers cannot pass `origin` or override the human user. Use `BIKKY_AGENT_ID` / `BIKKY_AGENT_NAME` only when you need to label the local automated agent process explicitly; otherwise bikky labels the daemon/UI/MCP surface from the hostname.
 
 ## Common setups
 
@@ -50,7 +64,7 @@ Best for performance and teams. Qdrant Cloud stores vectors, and hosted embeddin
   "embedding": {
     "provider": "openai",
     "model": "text-embedding-3-small",
-    "dimensions": 1536,
+    "dimensions": 1024,
     "api_key": "sk-..."
   },
   "llm": {
@@ -74,7 +88,7 @@ Best for local vector storage with hosted extraction and embedding quality.
   "embedding": {
     "provider": "openai",
     "model": "text-embedding-3-small",
-    "dimensions": 1536,
+    "dimensions": 1024,
     "api_key": "sk-..."
   },
   "llm": {
@@ -85,7 +99,7 @@ Best for local vector storage with hosted extraction and embedding quality.
 }
 ```
 
-`qdrant_api_key` is optional. Leave it empty or omit it for local or unauthenticated self-hosted Qdrant. Prefer env vars for hosted model auth? Omit `api_key` above and set `OPENAI_API_KEY` instead.
+`qdrant_api_key` is optional. Leave it empty or omit it for local or unauthenticated self-hosted Qdrant. Prefer env vars for hosted model auth? Omit `api_key` above and set `OPENAI_API_KEY` or `PORTKEY_API_KEY` for the selected provider instead.
 
 ### Local and free
 
@@ -134,11 +148,17 @@ export QDRANT_API_KEY="..."  # only needed for Qdrant Cloud or authenticated sel
 
 Useful basics:
 
-| Env var          | Config field     | Notes                                                                       |
-| ---------------- | ---------------- | --------------------------------------------------------------------------- |
-| `QDRANT_URL`     | `qdrant_url`     | Required unless set in config                                               |
-| `QDRANT_API_KEY` | `qdrant_api_key` | Optional for local/unauthenticated Qdrant; usually needed for Qdrant Cloud  |
-| `BIKKY_HOME`     | —                | Moves the config/log/state directory from `~/.bikky`                        |
+| Env var            | Config field          | Notes                                                                                   |
+| ------------------ | --------------------- | --------------------------------------------------------------------------------------- |
+| `QDRANT_URL`       | `qdrant_url`          | Required unless set in config                                                           |
+| `QDRANT_API_KEY`   | `qdrant_api_key`      | Optional for local/unauthenticated Qdrant; usually needed for Qdrant Cloud              |
+| `OPENAI_API_KEY`   | `embedding.api_key` / `llm.api_key` | Fallback key for `openai` when `api_key` is omitted from config              |
+| `PORTKEY_API_KEY`  | `embedding.api_key` / `llm.api_key` | Fallback key for `portkey` when `api_key` is omitted from config             |
+| `BIKKY_HOME`       | —                     | Moves the config/log/state directory from `~/.bikky`                                    |
+| `BIKKY_USER_ID`    | `identity.user_id`    | Explicit human user id for origin provisioning                                          |
+| `BIKKY_USER_NAME`  | `identity.user_name`  | Human-readable human user name for origin provisioning                                  |
+| `BIKKY_AGENT_ID`   | —                     | Optional local automated-agent id stored in `origin.agent`                              |
+| `BIKKY_AGENT_NAME` | —                     | Optional local automated-agent label stored in `origin.agent`                           |
 
 ## Provider options
 
@@ -149,7 +169,7 @@ Use these exact values in `embedding.provider` and `llm.provider`. Both fields a
 | `ollama`       | Yes                  | Yes           | Local and free defaults              | None                              |
 | `openai`       | Yes                  | Yes           | Simple hosted models                 | `OPENAI_API_KEY` or `api_key`     |
 | `bedrock`      | Yes                  | Yes           | AWS-managed models                   | AWS credentials or IAM role       |
-| `portkey`      | Yes                  | Yes           | Gateway/routing over other providers | Portkey API key                   |
+| `portkey`      | Yes                  | Yes           | Gateway/routing over other providers | `PORTKEY_API_KEY` or `api_key`    |
 
 ## Advanced configuration
 
@@ -175,7 +195,7 @@ These sections are optional references for custom providers, tuning, scoping, an
 | `embedding.model`      | `EMBEDDING_MODEL`      | `qwen3-embedding:0.6b`   | Embedding model name                            |
 | `embedding.dimensions` | `EMBEDDING_DIMENSIONS` | `1024`                   | Must match the selected model output            |
 | `embedding.base_url`   | `EMBEDDING_BASE_URL`   | `http://localhost:11434` | Used by local or OpenAI-compatible providers    |
-| `embedding.api_key`    | `OPENAI_API_KEY`       | —                        | Provider API key; can also be set in config     |
+| `embedding.api_key`    | `OPENAI_API_KEY` / `PORTKEY_API_KEY` | —             | Provider API key; env vars are fallback when omitted from config |
 
 Common model dimensions:
 
@@ -187,7 +207,7 @@ Common model dimensions:
 | `openai`  | `text-embedding-3-large`         | `3072`     |
 | `bedrock` | `amazon.titan-embed-text-v2:0`   | `1024`     |
 
-If you change the embedding model, make sure `embedding.dimensions` matches the model output.
+bikky's examples use `1024` because that is the portable default across supported providers. OpenAI 3-series embedding models can return their larger native dimensions above, but they also support shorter outputs; if you change `embedding.dimensions`, make sure the selected model and every Qdrant collection use the same dimension.
 
 #### LLM
 
@@ -198,7 +218,7 @@ The LLM is used by background maintenance features. Ollama is the default.
 | `llm.provider`     | `LLM_PROVIDER`                       | `ollama`                 | One of `ollama`, `openai`, `bedrock`, `portkey` |
 | `llm.model`        | `LLM_MODEL`                          | `qwen2.5:7b`             | LLM model name                               |
 | `llm.base_url`     | `LLM_BASE_URL`                       | `http://localhost:11434` | Used by local or OpenAI-compatible providers |
-| `llm.api_key`      | `OPENAI_API_KEY`                     | —                        | Provider API key; can also be set in config  |
+| `llm.api_key`      | `OPENAI_API_KEY` / `PORTKEY_API_KEY` | —                        | Provider API key; env vars are fallback when omitted from config |
 | `llm.extra.region` | `AWS_BEDROCK_REGION` / `AWS_REGION`  | `us-east-1`              | AWS Bedrock region                           |
 
 #### Timeouts and retries
@@ -225,7 +245,7 @@ Retries use jittered exponential backoff for transient errors, rate limits, and
   "embedding": {
     "provider": "portkey",
     "model": "@openai/text-embedding-3-small",
-    "dimensions": 1536,
+    "dimensions": 1024,
     "api_key": "pk-..."
   },
   "llm": {
@@ -264,7 +284,7 @@ Most users only need one Qdrant destination. Use `destinations[]` when you want
 
 Each destination has its own Qdrant credentials and collection. Add `description` when you have more than one destination; MCP tools expose those descriptions so LLM clients can pick the right search scope.
 
-Writes still target one destination. A destination can include a `match` block with JavaScript `RegExp` strings for `cwd`, `entity`, `content`, or `metadata`. Destinations are evaluated in array order; the first destination with any matching pattern wins. If no pattern matches, bikky uses the destination marked `default: true`, or the first destination.
+Writes still target one destination. A destination can include a `match` block with JavaScript `RegExp` strings for `cwd`, `entity`, `content`, or `metadata`. For memory writes, `content` matching uses a flattened routing view of the full memory context: stored content, entities, repo, branch, task/workstream keys, metadata, origin, relation fields, and other stored payload fields. Destinations are evaluated in array order; the first destination with any matching pattern wins. If no pattern matches, bikky uses the destination marked `default: true`, or the first destination.
 
 Read tools (`memory_recall`, `memory_entity`, and `memory_relations`) can search one destination, the routed destination, or multiple destinations. Configure `default_search_scope` to control the default read behavior:
 
@@ -280,7 +300,7 @@ MCP clients can override this per call with `search_scope`. The value accepts `"
   "embedding": {
     "provider": "openai",
     "model": "text-embedding-3-small",
-    "dimensions": 1536
+    "dimensions": 1024
   },
   "llm": {
     "provider": "openai",
@@ -333,6 +353,7 @@ MCP clients can override this per call with `search_scope`. The value accepts `"
 Matching details:
 
 - `match.cwd`, `match.entity`, and `match.content` are lists of JavaScript `RegExp` strings.
+- On memory writes, `match.content` sees the full flattened memory context, so a pattern can match values such as `repo`, `branch`, `task_key`, origin fields, metadata values, or relation endpoints even when the visible memory text does not contain that term.
 - `match.metadata` maps metadata keys to lists of JavaScript `RegExp` strings matched against that key's value.
 - Matching uses OR logic across fields and within each list; any matching pattern selects the destination.
 - Put the most specific destinations first because first match wins.
@@ -361,6 +382,10 @@ You normally do not need to tune these. `bikky setup` starts the daemon and regi
 | `daemon.consolidation_enabled`       | `true`  | Consolidate summaries into durable patterns      |
 | `daemon.relation_inference_enabled`  | `true`  | Infer entity relationships                       |
 | `daemon.entity_typing_enabled`       | `true`  | Classify entities for UI/graph filtering         |
+| `daemon.memory_quality_rollups_enabled` | `true` | Aggregate recall, feedback, stale, and confidence quality signals |
+| `daemon.memory_quality_rollups_interval_sec` | `3600` | Seconds between memory quality rollup runs |
+| `daemon.memory_quality_rollups_low_confidence_threshold` | `0.6` | Effective confidence below this value is counted as low-confidence |
+| `daemon.memory_quality_rollups_max_scopes_per_run` | `100` | Maximum rollup scopes written per destination per run |
 | `daemon.staleness_threshold_days`    | `30`    | Days before a fact is flagged as stale           |
 
 #### Watcher settings

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bikky",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Shared memory for AI coding sessions — MCP server + background daemon",
   "type": "module",
   "license": "AGPL-3.0-or-later",
@@ -60,7 +60,7 @@
     "@aws-sdk/client-bedrock-runtime": "^3.1006.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "pino": "^10.3.1",
-    "zod": "^3.24.0"
+    "zod": "^4.4.1"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",