bikky 0.1.0

package/README.md

@@ -0,0 +1,323 @@
+# bikky
+
+**Shared persistent memory for AI coding sessions.**
+
+bikky gives your AI coding assistants (GitHub Copilot, Claude Code) long-term memory that persists across sessions. Facts, decisions, architecture knowledge, and entity relationships are stored in a vector database and recalled automatically.
+
+---
+
+## Why bikky exists
+
+Every engineering team builds institutional knowledge — the kind that doesn't live in documentation. Why that config value is what it is. Which deploy steps to run in which order. What broke last quarter and how it was fixed. Who owns what.
+
+This knowledge lives in people's heads, scattered across chat threads, and buried in closed PRs. When someone switches projects or leaves, it's gone. It's the most valuable and least durable asset a technical organisation has.
+
+### AI agents amplify the problem
+
+AI coding agents are a force multiplier — teams ship more, explore more solutions, and touch more of the codebase than ever before. But that also means more decisions, more discoveries, and more institutional knowledge generated per day than any team can track manually. Some teams maintain hand-written knowledge bases to give agents context, but these drift quickly and become another thing to keep up to date. The knowledge that matters most — the things learned *during* sessions — still vanishes when the session closes.
+
+### Knowledge that compounds
+
+bikky captures what agents learn during coding sessions and makes it available to every future session — for every team member — automatically. No manual documentation. No wikis to maintain.
+
+When one engineer's agent figures out a workaround for a tricky edge case, every agent on the team knows it from their next session onward. Each team member is amplified with the experience gathered by every other member. The 50th session on a codebase is dramatically more effective than the 1st — not because of better prompts, but because of accumulated institutional memory.
+
+### Self-curating
+
+Raw accumulation creates noise. bikky curates knowledge automatically:
+
+- **Deduplication** — identical or near-identical facts are merged, not duplicated
+- **Confidence decay** — old facts gradually lose weight and surface for review instead of being treated as gospel
+- **Contradiction detection** — new facts that conflict with existing ones replace them, not silently coexist
+- **Distillation** — recurring patterns across sessions are consolidated into higher-level insights
+- **Entity graph** — relationships between concepts are inferred automatically for richer recall
+
+### Zero maintenance
+
+bikky is not a wiki you have to write. Facts are captured as a natural byproduct of engineering work. The curation pipeline runs autonomously. Install once, and every session gets smarter.
+
+---
+
+## How it works
+
+```mermaid
+graph TD
+    A["🤖 Copilot / Claude Code"] <-->|MCP stdio| B["bikky MCP Server"]
+    C["📁 Session logs<br/>~/.copilot/"] -->|events.jsonl| D["bikky Daemon<br/>(background)"]
+    B -->|store / recall| E[("🔮 Qdrant Cloud<br/>vector DB")]
+    D -->|embed + store| E
+```
+
+**MCP Server** — 12 memory tools your AI assistant can call directly:
+- `memory_store` / `memory_recall` — store and search facts
+- `memory_entity` / `memory_relations` — entity knowledge graph
+- `memory_forget` / `memory_verify` — lifecycle management
+- `memory_session_summary` / `memory_distill` — session consolidation
+- `memory_heartbeat` — periodic reflection nudges
+
+**Daemon** — background process that passively reads session logs:
+- Watches `~/.copilot/session-state/` for new events
+- Extracts facts via LLM from conversation transcripts
+- Runs consolidation (distillation, contradiction detection)
+- Infers entity relationships from co-occurring facts
+- Scans for stale facts that need verification
+
+## Quick start
+
+```bash
+# Install globally
+npm install -g bikky
+
+# Add to your editor's MCP config
+bikky install
+
+# That's it — restart your editor and the memory tools appear
+```
+
+### Prerequisites
+
+1. **Qdrant Cloud** (free tier: 1GB, no credit card)
+   - Sign up at [cloud.qdrant.io](https://cloud.qdrant.io)
+   - Create a cluster → copy the REST URL and API key
+
+2. **Embedding provider** (one of):
+   - **Ollama** (default, runs locally, free) — `brew install ollama && ollama pull qwen3-embedding:0.6b`
+   - **OpenAI** — set `OPENAI_API_KEY` env var
+   - **AWS Bedrock** — configure AWS credentials
+
+### Setup
+
+After installing, configure your Qdrant credentials. You can either:
+
+**Option A** — Let your AI assistant do it:
+```
+> Call configure_credentials with my Qdrant URL and API key
+```
+
+**Option B** — Edit config directly:
+```bash
+cat > ~/.bikky/config.json << 'EOF'
+{
+  "qdrant_url": "https://your-cluster.cloud.qdrant.io:6333",
+  "qdrant_api_key": "your-api-key-here"
+}
+EOF
+```
+
+**Option C** — Environment variables:
+```bash
+export QDRANT_URL="https://your-cluster.cloud.qdrant.io:6333"
+export QDRANT_API_KEY="your-api-key-here"
+```
+
+## Configuration
+
+Config lives at `~/.bikky/config.json`. Resolution order: **defaults → config file → env vars** (highest wins).
+
+### Qdrant (required)
+
+| Setting | Env var | Default | Description |
+|---------|---------|---------|-------------|
+| `qdrant_url` | `QDRANT_URL` | *none — must be set* | Qdrant REST URL, e.g. `https://abc123.cloud.qdrant.io:6333` |
+| `qdrant_api_key` | `QDRANT_API_KEY` | *none — must be set* | Qdrant API key from cluster dashboard |
+| `collection` | `BIKKY_COLLECTION` | `bikky` | Collection name. Change only if running multiple instances |
+
+### Embedding & LLM providers
+
+Both `embedding.provider` and `llm.provider` accept exactly one of three values:
+
+| Value | What it is | Auth needed | `base_url` used? |
+|-------|-----------|-------------|-----------------|
+| `ollama` | Local Ollama server | None | ✅ default `http://localhost:11434` |
+| `openai` | OpenAI-compatible API | `api_key` or `OPENAI_API_KEY` | ✅ default `https://api.openai.com/v1` |
+| `bedrock` | AWS Bedrock | AWS credentials (env or IAM role) | ❌ uses AWS SDK |
+
+> **⚠️ Only these three values are valid.** Any other value will cause a silent fallback to Ollama.
+
+### Embedding config
+
+| Setting | Env var | Default |
+|---------|---------|---------|
+| `embedding.provider` | `EMBEDDING_PROVIDER` | `ollama` |
+| `embedding.model` | `EMBEDDING_MODEL` | `qwen3-embedding:0.6b` |
+| `embedding.dimensions` | `EMBEDDING_DIMENSIONS` | `1024` |
+| `embedding.base_url` | `EMBEDDING_BASE_URL` | `http://localhost:11434` |
+| `embedding.api_key` | `OPENAI_API_KEY` | — |
+
+**Models by provider:**
+
+| Provider | Recommended models | Dimensions |
+|----------|-------------------|------------|
+| `ollama` | `qwen3-embedding:0.6b`, `nomic-embed-text` | `1024`, `768` |
+| `openai` | `text-embedding-3-small`, `text-embedding-3-large` | `1536`, `3072` |
+| `bedrock` | `amazon.titan-embed-text-v2:0` | `1024` |
+
+> **⚠️ `dimensions` must match your model's output.** Mismatched dimensions will cause Qdrant insert errors. If you change the model, update dimensions too.
+
+### LLM config (used by daemon for extraction & consolidation)
+
+| Setting | Env var | Default |
+|---------|---------|---------|
+| `llm.provider` | `LLM_PROVIDER` | `ollama` |
+| `llm.model` | `LLM_MODEL` | `qwen2.5:7b` |
+| `llm.base_url` | `LLM_BASE_URL` | `http://localhost:11434` |
+| `llm.api_key` | `OPENAI_API_KEY` | — |
+| `llm.bedrock_region` | `AWS_BEDROCK_REGION` | `us-east-1` |
+
+**Models by provider:**
+
+| Provider | Recommended models |
+|----------|-------------------|
+| `ollama` | `qwen2.5:7b`, `llama3.1:8b`, or any local model |
+| `openai` | `gpt-4.1-mini`, `gpt-4.1` |
+| `bedrock` | `anthropic.claude-3-5-haiku-20241022-v1:0` |
+
+> `llm.bedrock_region` falls back to `AWS_REGION` if `AWS_BEDROCK_REGION` is not set.
+
+### Provider auth quick-reference
+
+| Provider | What to set |
+|----------|------------|
+| `ollama` | Nothing — just have Ollama running locally (`ollama serve`) |
+| `openai` | `OPENAI_API_KEY` env var **or** `"api_key": "sk-..."` in the embedding/llm config block |
+| `bedrock` | `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` env vars, or an IAM instance role |
+
+### Copy-paste examples
+
+**Ollama (default — zero config):**
+```json
+{
+  "qdrant_url": "https://your-cluster.cloud.qdrant.io:6333",
+  "qdrant_api_key": "your-key"
+}
+```
+
+**OpenAI embeddings + LLM:**
+```json
+{
+  "qdrant_url": "https://your-cluster.cloud.qdrant.io:6333",
+  "qdrant_api_key": "your-key",
+  "embedding": {
+    "provider": "openai",
+    "model": "text-embedding-3-small",
+    "dimensions": 1536,
+    "api_key": "sk-..."
+  },
+  "llm": {
+    "provider": "openai",
+    "model": "gpt-4.1-mini",
+    "api_key": "sk-..."
+  }
+}
+```
+
+**AWS Bedrock:**
+```json
+{
+  "qdrant_url": "https://your-cluster.cloud.qdrant.io:6333",
+  "qdrant_api_key": "your-key",
+  "embedding": {
+    "provider": "bedrock",
+    "model": "amazon.titan-embed-text-v2:0",
+    "dimensions": 1024
+  },
+  "llm": {
+    "provider": "bedrock",
+    "model": "anthropic.claude-3-5-haiku-20241022-v1:0",
+    "bedrock_region": "us-east-1"
+  }
+}
+```
+
+### Daemon settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `daemon.tick_interval_sec` | `5` | Seconds between daemon loop ticks |
+| `daemon.extract_every_sec` | `300` | Seconds between extraction runs |
+| `daemon.extract_min_events` | `5` | Minimum session events before triggering extraction |
+| `daemon.consolidation_enabled` | `true` | Auto-distill session summaries into patterns |
+| `daemon.relation_inference_enabled` | `true` | Infer entity relationships via LLM |
+| `daemon.staleness_threshold_days` | `30` | Days before a fact is flagged as stale |
+
+### Watcher settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `watchers.copilot.enabled` | `true` | Watch GitHub Copilot session logs |
+| `watchers.copilot.path` | `~/.copilot/session-state` | Path to Copilot session directory |
+| `watchers.claude.enabled` | `false` | Watch Claude Code project logs |
+| `watchers.claude.path` | `~/.claude/projects` | Path to Claude Code projects directory |
+
+## CLI Commands
+
+```bash
+bikky mcp       # Start MCP server (stdio) — used by editors
+bikky setup     # Interactive setup wizard
+bikky status    # Check memory system status
+bikky install   # Write MCP config for Copilot + Claude Code
+```
+
+## Memory architecture
+
+### Deduplication
+
+Two-layer dedup prevents bloat:
+
+```mermaid
+flowchart TD
+    A[New fact] --> B{SHA-256<br/>content hash}
+    B -->|exact match| C[Skip — duplicate]
+    B -->|no match| D{Vector<br/>similarity}
+    D -->|"> 0.92"| E["Reinforce existing<br/>(bump count)"]
+    D -->|"> 0.80"| F[Store + flag<br/>as related]
+    D -->|"< 0.80"| G[Store as new]
+```
+
+### Ranking formula
+Facts are ranked using a combined score:
+```
+(vectorScore × 0.55 + freshness × 0.15 + reinforcement × 0.1 + importance × 0.1)
+  × (0.7 + 0.3 × confidenceDecay)
+```
+
+### Entity knowledge graph
+
+Facts mentioning multiple entities build an implicit graph:
+
+```mermaid
+graph LR
+    subgraph "Entity Graph"
+        U(user) -->|owns| P(project-x)
+        U -->|uses| Q(qdrant)
+        P -->|depends-on| Q
+        U -->|prefers| D(dark mode)
+    end
+```
+
+The daemon periodically:
+1. Scrolls all facts → builds entity co-occurrence map
+2. For top pairs by shared-fact count → LLM infers relationship type
+3. Stores typed edges (e.g., `user --[owns]--> project-x`)
+
+### Consolidation pipeline
+
+```mermaid
+flowchart LR
+    A[Session<br/>summaries] --> B{5+ summaries?}
+    B -->|yes| C[Auto-distill]
+    C --> D[Distilled<br/>patterns]
+    E[All facts] --> F[Contradiction<br/>detection]
+    F --> G[Flagged for<br/>review]
+    E --> H[Staleness<br/>scan]
+    H --> I["Stale facts<br/>(30+ days)"]
+```
+
+- **Auto-distill** — merges 5+ session summaries into distilled patterns
+- **Contradiction detection** — flags conflicting facts for review
+- **Category rebalancing** — consolidates oversized categories
+- **Staleness scanning** — surfaces facts that haven't been verified in 30+ days
+
+## License
+
+AGPL-3.0 — see [LICENSE](LICENSE).

package/bin/bikky.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import("../dist/cli.js").catch((e) => {
+  console.error("bikky: failed to load —", e.message);
+  console.error("Run `npm run build` first if developing locally.");
+  process.exit(1);
+});

package/dist/cli.d.ts

@@ -0,0 +1,12 @@
+/**
+ * bikky CLI — setup, start MCP server, manage daemon.
+ *
+ * Usage:
+ *   bikky mcp        — start MCP server (stdio, for editor integration)
+ *   bikky daemon     — start background daemon (extraction, consolidation, etc.)
+ *   bikky setup      — interactive setup wizard
+ *   bikky status     — check memory system status
+ *   bikky install    — write MCP config for Copilot / Claude Code
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/cli.js

@@ -0,0 +1,51 @@
+/**
+ * bikky CLI — setup, start MCP server, manage daemon.
+ *
+ * Usage:
+ *   bikky mcp        — start MCP server (stdio, for editor integration)
+ *   bikky daemon     — start background daemon (extraction, consolidation, etc.)
+ *   bikky setup      — interactive setup wizard
+ *   bikky status     — check memory system status
+ *   bikky install    — write MCP config for Copilot / Claude Code
+ */
+import { startMcpServer } from "./mcp/index.js";
+const command = process.argv[2] ?? "mcp";
+async function main() {
+    switch (command) {
+        case "mcp":
+            await startMcpServer();
+            break;
+        case "daemon": {
+            const daemon = await import("./daemon/index.js");
+            console.log("🧠 bikky daemon starting…");
+            await daemon.startDaemon();
+            process.on("SIGINT", () => {
+                daemon.stopDaemon();
+                process.exit(0);
+            });
+            break;
+        }
+        case "setup":
+            console.log("🧠 bikky setup");
+            console.log("Run `bikky install` to add to your editor's MCP config.");
+            console.log("Then call configure_credentials from your editor to set up Qdrant.");
+            break;
+        case "status":
+            console.log("🧠 bikky status — use get_setup_status via MCP for full details.");
+            break;
+        case "install": {
+            const { writeInstallConfig } = await import("./install.js");
+            await writeInstallConfig();
+            break;
+        }
+        default:
+            console.error(`Unknown command: ${command}`);
+            console.error("Usage: bikky [mcp|daemon|setup|status|install]");
+            process.exit(1);
+    }
+}
+main().catch((e) => {
+    console.error("Fatal:", e instanceof Error ? e.message : String(e));
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC;AAEzC,KAAK,UAAU,IAAI;IACjB,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,KAAK;YACR,MAAM,cAAc,EAAE,CAAC;YACvB,MAAM;QAER,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC;YACjD,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;YACzC,MAAM,MAAM,CAAC,WAAW,EAAE,CAAC;YAC3B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;gBACxB,MAAM,CAAC,UAAU,EAAE,CAAC;gBACpB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC,CAAC,CAAC;YACH,MAAM;QACR,CAAC;QAED,KAAK,OAAO;YACV,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;YAC9B,OAAO,CAAC,GAAG,CAAC,yDAAyD,CAAC,CAAC;YACvE,OAAO,CAAC,GAAG,CAAC,oEAAoE,CAAC,CAAC;YAClF,MAAM;QAER,KAAK,QAAQ;YACX,OAAO,CAAC,GAAG,CAAC,kEAAkE,CAAC,CAAC;YAChF,MAAM;QAER,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,EAAE,kBAAkB,EAAE,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,CAAC;YAC5D,MAAM,kBAAkB,EAAE,CAAC;YAC3B,MAAM;QACR,CAAC;QAED;YACE,OAAO,CAAC,KAAK,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;YAC7C,OAAO,CAAC,KAAK,CAAC,gDAAgD,CAAC,CAAC;YAChE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAU,EAAE,EAAE;IAC1B,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Configuration loader for bikky.
+ *
+ * Resolution order: defaults → ~/.bikky/config.json → env vars.
+ * Config directory: ~/.bikky/
+ */
+export declare const BIKKY_DIR: string;
+export declare const CONFIG_PATH: string;
+export declare const LOG_DIR: string;
+export declare const STATE_DIR: string;
+export interface EmbeddingConfig {
+    provider: "ollama" | "openai" | "bedrock";
+    model: string;
+    dimensions: number;
+    base_url: string;
+    api_key: string | null;
+}
+export interface LLMConfig {
+    provider: "ollama" | "openai" | "bedrock";
+    model: string;
+    base_url: string;
+    api_key: string | null;
+    bedrock_region: string;
+}
+export interface DaemonConfig {
+    tick_interval_sec: number;
+    extract_every_sec: number;
+    extract_min_events: number;
+    consolidation_enabled: boolean;
+    relation_inference_enabled: boolean;
+    staleness_threshold_days: number;
+}
+export interface WatcherConfig {
+    copilot: {
+        enabled: boolean;
+        path: string;
+    };
+    claude: {
+        enabled: boolean;
+        path: string;
+    };
+}
+export interface BikkyConfig {
+    qdrant_url: string | null;
+    qdrant_api_key: string | null;
+    collection: string;
+    embedding: EmbeddingConfig;
+    llm: LLMConfig;
+    daemon: DaemonConfig;
+    watchers: WatcherConfig;
+}
+declare const DEFAULTS: BikkyConfig;
+export declare function loadConfig(): BikkyConfig;
+/** Save config to disk (used by setup command). */
+export declare function saveConfig(config: BikkyConfig): void;
+/** Reset cached config (for testing). */
+export declare function resetConfig(): void;
+export { DEFAULTS as CONFIG_DEFAULTS };
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,eAAO,MAAM,SAAS,QAAoC,CAAC;AAC3D,eAAO,MAAM,WAAW,QAAsC,CAAC;AAC/D,eAAO,MAAM,OAAO,QAA+B,CAAC;AACpD,eAAO,MAAM,SAAS,QAAgC,CAAC;AAMvD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,0BAA0B,EAAE,OAAO,CAAC;IACpC,wBAAwB,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,MAAM,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5C;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,eAAe,CAAC;IAC3B,GAAG,EAAE,SAAS,CAAC;IACf,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,aAAa,CAAC;CACzB;AAMD,QAAA,MAAM,QAAQ,EAAE,WA8Bf,CAAC;AA0BF,wBAAgB,UAAU,IAAI,WAAW,CAgDxC;AAED,mDAAmD;AACnD,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAIpD;AAED,yCAAyC;AACzC,wBAAgB,WAAW,IAAI,IAAI,CAElC;AAED,OAAO,EAAE,QAAQ,IAAI,eAAe,EAAE,CAAC"}

package/dist/config.js

@@ -0,0 +1,141 @@
+/**
+ * Configuration loader for bikky.
+ *
+ * Resolution order: defaults → ~/.bikky/config.json → env vars.
+ * Config directory: ~/.bikky/
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+export const BIKKY_DIR = 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");
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULTS = {
+    qdrant_url: null,
+    qdrant_api_key: null,
+    collection: "bikky",
+    embedding: {
+        provider: "ollama",
+        model: "qwen3-embedding:0.6b",
+        dimensions: 1024,
+        base_url: "http://localhost:11434",
+        api_key: null,
+    },
+    llm: {
+        provider: "ollama",
+        model: "qwen2.5:7b",
+        base_url: "http://localhost:11434",
+        api_key: null,
+        bedrock_region: "us-east-1",
+    },
+    daemon: {
+        tick_interval_sec: 5,
+        extract_every_sec: 300,
+        extract_min_events: 5,
+        consolidation_enabled: true,
+        relation_inference_enabled: true,
+        staleness_threshold_days: 30,
+    },
+    watchers: {
+        copilot: { enabled: true, path: path.join(os.homedir(), ".copilot", "session-state") },
+        claude: { enabled: false, path: path.join(os.homedir(), ".claude", "projects") },
+    },
+};
+// ---------------------------------------------------------------------------
+// Deep merge utility
+// ---------------------------------------------------------------------------
+function deepMerge(base, override) {
+    const result = { ...base };
+    for (const key of Object.keys(override)) {
+        const bVal = base[key];
+        const oVal = override[key];
+        if (bVal && typeof bVal === "object" && !Array.isArray(bVal) && oVal && typeof oVal === "object" && !Array.isArray(oVal)) {
+            result[key] = deepMerge(bVal, oVal);
+        }
+        else if (oVal !== undefined) {
+            result[key] = oVal;
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Load config
+// ---------------------------------------------------------------------------
+let _config = null;
+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 });
+    // Start from defaults
+    let config = structuredClone(DEFAULTS);
+    // Merge config file
+    if (fs.existsSync(CONFIG_PATH)) {
+        try {
+            const fileConfig = JSON.parse(fs.readFileSync(CONFIG_PATH, "utf-8"));
+            config = deepMerge(config, fileConfig);
+        }
+        catch (e) {
+            console.error(`bikky: failed to parse ${CONFIG_PATH}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    // Env var overrides (highest priority)
+    if (process.env.QDRANT_URL)
+        config.qdrant_url = process.env.QDRANT_URL;
+    if (process.env.QDRANT_API_KEY)
+        config.qdrant_api_key = process.env.QDRANT_API_KEY;
+    if (process.env.BIKKY_COLLECTION)
+        config.collection = process.env.BIKKY_COLLECTION;
+    // Embedding env overrides
+    if (process.env.EMBEDDING_PROVIDER)
+        config.embedding.provider = process.env.EMBEDDING_PROVIDER;
+    if (process.env.EMBEDDING_MODEL)
+        config.embedding.model = process.env.EMBEDDING_MODEL;
+    if (process.env.EMBEDDING_BASE_URL)
+        config.embedding.base_url = process.env.EMBEDDING_BASE_URL;
+    if (process.env.EMBEDDING_DIMENSIONS)
+        config.embedding.dimensions = parseInt(process.env.EMBEDDING_DIMENSIONS, 10);
+    if (process.env.OPENAI_API_KEY)
+        config.embedding.api_key = process.env.OPENAI_API_KEY;
+    // LLM env overrides
+    if (process.env.LLM_PROVIDER)
+        config.llm.provider = process.env.LLM_PROVIDER;
+    if (process.env.LLM_MODEL)
+        config.llm.model = process.env.LLM_MODEL;
+    if (process.env.LLM_BASE_URL)
+        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.AWS_BEDROCK_REGION)
+        config.llm.bedrock_region = process.env.AWS_BEDROCK_REGION;
+    if (process.env.AWS_REGION && !process.env.AWS_BEDROCK_REGION)
+        config.llm.bedrock_region = process.env.AWS_REGION;
+    // Strip trailing slashes from URLs
+    if (config.qdrant_url)
+        config.qdrant_url = config.qdrant_url.replace(/\/+$/, "");
+    config.embedding.base_url = config.embedding.base_url.replace(/\/+$/, "");
+    config.llm.base_url = config.llm.base_url.replace(/\/+$/, "");
+    _config = config;
+    return config;
+}
+/** 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");
+    _config = config;
+}
+/** Reset cached config (for testing). */
+export function resetConfig() {
+    _config = null;
+}
+export { DEFAULTS as CONFIG_DEFAULTS };
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/config.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tests for the config system.
+ *
+ * Strategy: we backup/restore ~/.bikky/config.json around file-based tests
+ * and use env var overrides + resetConfig() for env-var tests.
+ */
+export {};
+//# sourceMappingURL=config.test.d.ts.map

package/dist/config.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.test.d.ts","sourceRoot":"","sources":["../src/config.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}