bikky 0.3.13 → 0.4.1

package/dist/mcp/types.d.ts

@@ -67,7 +67,6 @@ export interface FactPayload {
     kind?: string;
     layer?: string | null;
     memory_subtype?: string | null;
-    workspace_id?: string;
     actor_id?: string;
     entities: string[];
     source?: string;
@@ -141,8 +140,6 @@ export interface FilterParams {
     domain?: string;
     kind?: string;
     memory_subtype?: string;
-    workspace_id?: string;
-    includeLegacyWorkspace?: boolean;
     actor_id?: string;
     entity?: string;
     session_id?: string;

package/dist/routing.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Pure destination routing.
+ *
+ * Resolves which `Destination` a memory operation should target based on
+ * caller-supplied input (entities, content, metadata) and the current cwd.
+ *
+ * Resolution order:
+ *   1. Explicit override — if `input.destination` is set, the destination with
+ *      that name is returned. Throws if no such destination exists.
+ *   2. Match scan — destinations are walked in array order. For each, ANY
+ *      regex matching ANY field in the destination's `match` block wins
+ *      (OR semantics). First matching destination wins.
+ *   3. Default fallback — destination with `default: true`, else the first
+ *      destination in the array.
+ *
+ * Pure: no I/O, no globals. Easy to unit test.
+ */
+import type { Destination } from "./config.js";
+export interface RoutingInput {
+    /** Explicit destination name override. Throws if it doesn't match a destination. */
+    destination?: string | null;
+    /** Current working directory. Defaults to `process.cwd()` if omitted by caller. */
+    cwd?: string;
+    /** Entity names mentioned by the operation. */
+    entities?: ReadonlyArray<string>;
+    /** Free-text content (e.g. memory_store content, memory_recall query). */
+    content?: string | null;
+    /** Caller-provided metadata map. */
+    metadata?: Record<string, unknown> | null;
+}
+export declare class DestinationNotFoundError extends Error {
+    readonly name: string;
+    readonly available: string[];
+    constructor(name: string, available: string[]);
+}
+export declare class NoDestinationsConfiguredError extends Error {
+    constructor();
+}
+/**
+ * Resolve a destination from caller input + a (pre-loaded) list of destinations.
+ *
+ * Throws `NoDestinationsConfiguredError` if `destinations` is empty.
+ * Throws `DestinationNotFoundError` if `input.destination` doesn't match a
+ * configured destination.
+ */
+export declare function resolveDestination(input: RoutingInput, destinations: ReadonlyArray<Destination>): Destination;
+/**
+ * Pre-compile a routing table for hot paths (e.g. per-tick in the daemon).
+ * Returns a closure that resolves a destination from input without recompiling
+ * regexes on every call.
+ */
+export declare function buildResolver(destinations: ReadonlyArray<Destination>): (input: RoutingInput) => Destination;
+//# sourceMappingURL=routing.d.ts.map

package/dist/routing.js

@@ -0,0 +1,129 @@
+export class DestinationNotFoundError extends Error {
+    name;
+    available;
+    constructor(name, available) {
+        super(`Unknown destination '${name}'. Configured destinations: ${available.length > 0 ? available.join(", ") : "(none)"}`);
+        this.name = name;
+        this.available = available;
+        this.name = "DestinationNotFoundError";
+    }
+}
+export class NoDestinationsConfiguredError extends Error {
+    constructor() {
+        super("No destinations configured. Set top-level qdrant_url or destinations[] in ~/.bikky/config.json.");
+        this.name = "NoDestinationsConfiguredError";
+    }
+}
+function compileArray(patterns) {
+    if (!patterns || patterns.length === 0)
+        return [];
+    return patterns.map((p) => new RegExp(p));
+}
+function compileMatch(match) {
+    const m = { cwd: [], entity: [], content: [], metadata: {} };
+    if (!match)
+        return m;
+    m.cwd = compileArray(match.cwd);
+    m.entity = compileArray(match.entity);
+    m.content = compileArray(match.content);
+    if (match.metadata) {
+        for (const [k, v] of Object.entries(match.metadata)) {
+            m.metadata[k] = compileArray(v);
+        }
+    }
+    return m;
+}
+function compileDestinations(destinations) {
+    return destinations.map((destination) => ({
+        destination,
+        compiled: compileMatch(destination.match),
+    }));
+}
+function anyMatches(value, patterns) {
+    if (patterns.length === 0)
+        return false;
+    return patterns.some((re) => re.test(value));
+}
+function destinationMatches(compiled, input) {
+    const cwd = input.cwd ?? "";
+    if (cwd && anyMatches(cwd, compiled.cwd))
+        return true;
+    if (input.entities && input.entities.length > 0 && compiled.entity.length > 0) {
+        for (const entity of input.entities) {
+            if (anyMatches(entity, compiled.entity))
+                return true;
+        }
+    }
+    if (input.content && compiled.content.length > 0 && anyMatches(input.content, compiled.content)) {
+        return true;
+    }
+    if (input.metadata && Object.keys(compiled.metadata).length > 0) {
+        for (const [key, patterns] of Object.entries(compiled.metadata)) {
+            const raw = input.metadata[key];
+            if (raw === undefined || raw === null)
+                continue;
+            const value = typeof raw === "string" ? raw : String(raw);
+            if (anyMatches(value, patterns))
+                return true;
+        }
+    }
+    return false;
+}
+function pickFallback(destinations) {
+    const explicit = destinations.find((d) => d.default === true);
+    if (explicit)
+        return explicit;
+    return destinations[0];
+}
+/**
+ * Resolve a destination from caller input + a (pre-loaded) list of destinations.
+ *
+ * Throws `NoDestinationsConfiguredError` if `destinations` is empty.
+ * Throws `DestinationNotFoundError` if `input.destination` doesn't match a
+ * configured destination.
+ */
+export function resolveDestination(input, destinations) {
+    if (destinations.length === 0)
+        throw new NoDestinationsConfiguredError();
+    if (input.destination && input.destination.trim() !== "") {
+        const wanted = input.destination.trim();
+        const found = destinations.find((d) => d.name === wanted);
+        if (!found) {
+            throw new DestinationNotFoundError(wanted, destinations.map((d) => d.name));
+        }
+        return found;
+    }
+    const compiled = compileDestinations(destinations);
+    for (const entry of compiled) {
+        if (destinationMatches(entry.compiled, input))
+            return entry.destination;
+    }
+    return pickFallback(destinations);
+}
+/**
+ * Pre-compile a routing table for hot paths (e.g. per-tick in the daemon).
+ * Returns a closure that resolves a destination from input without recompiling
+ * regexes on every call.
+ */
+export function buildResolver(destinations) {
+    if (destinations.length === 0) {
+        return () => { throw new NoDestinationsConfiguredError(); };
+    }
+    const compiled = compileDestinations(destinations);
+    return (input) => {
+        if (input.destination && input.destination.trim() !== "") {
+            const wanted = input.destination.trim();
+            const found = destinations.find((d) => d.name === wanted);
+            if (!found) {
+                throw new DestinationNotFoundError(wanted, destinations.map((d) => d.name));
+            }
+            return found;
+        }
+        for (const entry of compiled) {
+            if (destinationMatches(entry.compiled, input))
+                return entry.destination;
+        }
+        return pickFallback(destinations);
+    };
+}
+//# sourceMappingURL=routing.js.map

package/dist/search-scope.d.ts

@@ -0,0 +1,24 @@
+import type { BikkyConfig, Destination, SearchScopeTarget } from "./config.js";
+import { type RoutingInput } from "./routing.js";
+export type SearchScopeInput = SearchScopeTarget | null | undefined;
+export interface AvailableSearchScope {
+    name: string;
+    description: string;
+    destinations: "routed" | "all" | string[];
+    default: boolean;
+    source: "builtin" | "destination" | "config";
+}
+export interface ResolvedSearchScope {
+    name: string;
+    description: string;
+    requested: SearchScopeTarget;
+    destinations: Destination[];
+}
+export declare class SearchScopeNotFoundError extends Error {
+    readonly scope: string;
+    readonly available: string[];
+    constructor(scope: string, available: string[]);
+}
+export declare function availableSearchScopes(config: BikkyConfig, destinations: ReadonlyArray<Destination>): AvailableSearchScope[];
+export declare function resolveSearchScope(input: SearchScopeInput, config: BikkyConfig, destinations: ReadonlyArray<Destination>, routing: RoutingInput): ResolvedSearchScope;
+//# sourceMappingURL=search-scope.d.ts.map

package/dist/search-scope.js

@@ -0,0 +1,174 @@
+import { resolveDestination } from "./routing.js";
+export class SearchScopeNotFoundError extends Error {
+    scope;
+    available;
+    constructor(scope, available) {
+        super(`Unknown search scope '${scope}'. Available scopes: ${available.length > 0 ? available.join(", ") : "(none)"}`);
+        this.scope = scope;
+        this.available = available;
+        this.name = "SearchScopeNotFoundError";
+    }
+}
+function normalizeString(value) {
+    return value.trim();
+}
+function normalizeTarget(target) {
+    if (Array.isArray(target)) {
+        const normalized = target.map(normalizeString).filter(Boolean);
+        return normalized.length > 0 ? normalized : null;
+    }
+    if (typeof target === "string") {
+        const trimmed = normalizeString(target);
+        if (!trimmed)
+            return null;
+        if (trimmed.includes(",")) {
+            const names = trimmed.split(",").map(normalizeString).filter(Boolean);
+            if (names.length > 1)
+                return names;
+        }
+        return trimmed;
+    }
+    return null;
+}
+function targetEquals(a, b) {
+    const normalizedA = normalizeTarget(a);
+    const normalizedB = normalizeTarget(b);
+    if (Array.isArray(normalizedA) || Array.isArray(normalizedB)) {
+        if (!Array.isArray(normalizedA) || !Array.isArray(normalizedB))
+            return false;
+        if (normalizedA.length !== normalizedB.length)
+            return false;
+        return normalizedA.every((value, idx) => value === normalizedB[idx]);
+    }
+    return normalizedA === normalizedB;
+}
+function describeTarget(target) {
+    const normalized = normalizeTarget(target) ?? "routed";
+    if (Array.isArray(normalized))
+        return normalized;
+    if (normalized === "routed" || normalized === "all")
+        return normalized;
+    return [normalized];
+}
+function destinationScopeDescription(destination) {
+    return destination.description
+        ?? `Search only the '${destination.name}' destination (collection '${destination.collection}').`;
+}
+export function availableSearchScopes(config, destinations) {
+    const defaultScope = normalizeTarget(config.default_search_scope) ?? "routed";
+    const scopes = [
+        {
+            name: "routed",
+            description: "Search the single destination selected by the routing rules (cwd, query/content, entities, metadata), then default/first destination fallback. This preserves historical behavior and keeps destination boundaries narrow.",
+            destinations: "routed",
+            default: targetEquals(defaultScope, "routed"),
+            source: "builtin",
+        },
+        {
+            name: "all",
+            description: "Search every configured destination and merge/rerank the results. Use for broad recall when relevant context may span multiple memory stores.",
+            destinations: "all",
+            default: targetEquals(defaultScope, "all"),
+            source: "builtin",
+        },
+    ];
+    for (const destination of destinations) {
+        scopes.push({
+            name: destination.name,
+            description: destinationScopeDescription(destination),
+            destinations: [destination.name],
+            default: targetEquals(defaultScope, destination.name),
+            source: "destination",
+        });
+    }
+    for (const scope of config.search_scopes) {
+        scopes.push({
+            name: scope.name,
+            description: scope.description,
+            destinations: describeTarget(scope.destinations),
+            default: targetEquals(defaultScope, scope.name) || targetEquals(defaultScope, scope.destinations),
+            source: "config",
+        });
+    }
+    return scopes;
+}
+function resolveNames(names, destinations) {
+    const byName = new Map(destinations.map((destination) => [destination.name, destination]));
+    const resolved = [];
+    const seen = new Set();
+    for (const rawName of names) {
+        const name = normalizeString(rawName);
+        if (!name || seen.has(name))
+            continue;
+        const destination = byName.get(name);
+        if (!destination)
+            throw new SearchScopeNotFoundError(name, [...byName.keys()]);
+        resolved.push(destination);
+        seen.add(name);
+    }
+    if (resolved.length === 0) {
+        throw new SearchScopeNotFoundError(names.join(","), [...byName.keys()]);
+    }
+    return resolved;
+}
+function resolveTarget(target, config, destinations, routing, depth = 0) {
+    if (depth > 4) {
+        throw new Error("Search scope resolution exceeded maximum nesting depth");
+    }
+    const normalized = normalizeTarget(target) ?? "routed";
+    if (Array.isArray(normalized)) {
+        const resolved = resolveNames(normalized, destinations);
+        return {
+            name: normalized.join(","),
+            description: `Search selected destinations: ${normalized.join(", ")}.`,
+            requested: normalized,
+            destinations: resolved,
+        };
+    }
+    const configuredScope = config.search_scopes.find((scope) => scope.name === normalized);
+    if (configuredScope) {
+        const resolved = resolveTarget(configuredScope.destinations, config, destinations, routing, depth + 1);
+        return {
+            name: configuredScope.name,
+            description: configuredScope.description,
+            requested: normalized,
+            destinations: resolved.destinations,
+        };
+    }
+    if (normalized === "routed" || normalized === "auto") {
+        const destination = resolveDestination(routing, destinations);
+        return {
+            name: "routed",
+            description: "Search the single destination selected by routing rules.",
+            requested: normalized,
+            destinations: [destination],
+        };
+    }
+    if (normalized === "all") {
+        if (destinations.length === 0) {
+            resolveDestination(routing, destinations);
+        }
+        return {
+            name: "all",
+            description: "Search every configured destination.",
+            requested: normalized,
+            destinations: [...destinations],
+        };
+    }
+    const destination = destinations.find((dest) => dest.name === normalized);
+    if (destination) {
+        return {
+            name: destination.name,
+            description: destinationScopeDescription(destination),
+            requested: normalized,
+            destinations: [destination],
+        };
+    }
+    const available = availableSearchScopes(config, destinations).map((scope) => scope.name);
+    throw new SearchScopeNotFoundError(normalized, available);
+}
+export function resolveSearchScope(input, config, destinations, routing) {
+    const target = normalizeTarget(input) ?? normalizeTarget(config.default_search_scope) ?? "routed";
+    return resolveTarget(target, config, destinations, routing);
+}
+//# sourceMappingURL=search-scope.js.map

package/docs/config/fully-hosted.md

@@ -0,0 +1,57 @@
+# 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.
+
+## 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.
+
+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.
+
+## Config
+
+Save this as `~/.bikky/config.json`:
+
+```json
+{
+  "qdrant_url": "https://your-cluster.cloud.qdrant.io:6333",
+  "qdrant_api_key": "your-qdrant-api-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-..."
+  }
+}
+```
+
+`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-..."
+```
+
+## Check it
+
+```bash
+bikky status
+```
+
+After changing Qdrant or provider settings, restart long-running processes:
+
+```bash
+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](../configuration.md).

package/docs/config/hosted-models.md

@@ -0,0 +1,50 @@
+# Local Qdrant + hosted models config
+
+This setup keeps Qdrant local while hosted embeddings and LLM calls handle 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.
+
+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.
+
+## Config
+
+Save this as `~/.bikky/config.json`:
+
+```json
+{
+  "qdrant_url": "http://localhost:6333",
+  "qdrant_api_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-..."
+  }
+}
+```
+
+`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-..."
+```
+
+## Check it
+
+```bash
+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](../configuration.md).

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

@@ -0,0 +1,39 @@
+# Hosted Qdrant + local models
+
+Use this path when you want memory shared across machines, but you still want embeddings and background curation to run through local Ollama.
+
+## What you need
+
+- A Qdrant Cloud cluster URL.
+- A Qdrant API key.
+- Ollama installed locally.
+- The default embedding model pulled with `ollama pull qwen3-embedding:0.6b`.
+
+## Config
+
+Save this as `~/.bikky/config.json`:
+
+```json
+{
+  "qdrant_url": "https://your-cluster.cloud.qdrant.io:6333",
+  "qdrant_api_key": "your-qdrant-api-key"
+}
+```
+
+bikky will store memory in hosted Qdrant and keep model calls local through Ollama.
+
+`qdrant_api_key` is optional only for unauthenticated self-hosted Qdrant. Qdrant Cloud usually requires it.
+
+## Check it
+
+```bash
+bikky status
+```
+
+After changing Qdrant settings, restart long-running processes:
+
+```bash
+bikky stop && bikky start
+```
+
+Then restart your editor so its MCP process reloads.

package/docs/config/local.md

@@ -0,0 +1,34 @@
+# Local and free config
+
+Use this path if you want a private, free setup: Qdrant runs on your machine, and Ollama handles local models.
+
+This setup is best for private/free testing rather than long-term team use. Extraction, embedding, and curation performance depends on the local models and hardware you run.
+
+## What you need
+
+- Qdrant running locally, usually with Docker.
+- Ollama installed locally.
+- The default embedding model pulled with `ollama pull qwen3-embedding:0.6b`.
+
+## Config
+
+Save this as `~/.bikky/config.json`:
+
+```json
+{
+  "qdrant_url": "http://localhost:6333",
+  "qdrant_api_key": ""
+}
+```
+
+That's the whole config. bikky uses local Ollama defaults for embeddings and background curation.
+
+`qdrant_api_key` is optional. Leave it empty or omit it for local or unauthenticated self-hosted Qdrant.
+
+## Check it
+
+```bash
+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.