bikky 0.3.1 → 0.3.3

package/dist/mcp/index.js

@@ -1,14 +1,20 @@
 /**
- * bikky MCP Server — episodic memory via Qdrant Cloud.
+ * bikky MCP Server — episodic memory via Qdrant (Cloud, Docker, or self-hosted).
  *
  * Provides persistent memory across AI coding sessions. All facts, relations,
  * and entity context live as Qdrant points with vector embeddings + structured
  * payloads. Config stored in ~/.bikky/config.json.
+ *
+ * Boot resilience: every initialisation step is wrapped so a misconfigured
+ * provider, missing key, or unreachable Qdrant cluster surfaces as a
+ * `setup_required` status (with an actionable reason) instead of crashing the
+ * MCP stdio transport. The MCP server always comes up; tools then degrade
+ * gracefully via `requireReady()`.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { QDRANT_INDEXES } from "./taxonomy.js";
-import { log, setQdrantUrl, setQdrantApiKey, setReady, setCollection, ensureCollection, initEmbedding, } from "./api.js";
+import { log, setQdrantUrl, setQdrantApiKey, setReady, setCollection, setSetupError, ensureCollection, initEmbedding, } from "./api.js";
 import { registerTools } from "./tools.js";
 import { loadConfig } from "../config.js";
 export async function startMcpServer() {
@@ -20,38 +26,57 @@ export async function startMcpServer() {
     setQdrantUrl(qUrl);
     setQdrantApiKey(qKey);
     setCollection(cfg.collection);
-    // Initialize embedding provider
-    const embCfg = initEmbedding({
-        provider: cfg.embedding.provider,
-        baseUrl: cfg.embedding.base_url,
-        model: cfg.embedding.model,
-        dimensions: cfg.embedding.dimensions,
-        apiKey: cfg.embedding.api_key ?? null,
-    });
-    log("INFO", `Embedding: ${embCfg.provider}/${embCfg.model} (${embCfg.dimensions}d) @ ${embCfg.baseUrl || "(sdk)"}`);
-    if (qUrl && qKey) {
+    // Initialize embedding provider — wrapped so an unknown provider name or
+    // misconfiguration produces a setup_required status instead of crashing the
+    // MCP stdio transport. The server always comes up; tools degrade via
+    // requireReady().
+    try {
+        const embCfg = initEmbedding({
+            provider: cfg.embedding.provider,
+            baseUrl: cfg.embedding.base_url,
+            model: cfg.embedding.model,
+            dimensions: cfg.embedding.dimensions,
+            apiKey: cfg.embedding.api_key ?? null,
+            extra: cfg.embedding.extra ?? {},
+            timeoutMs: cfg.embedding.timeout_ms,
+            retries: cfg.embedding.retries,
+            retryBaseDelayMs: cfg.embedding.retry_base_delay_ms,
+        });
+        log("INFO", `Embedding: ${embCfg.provider}/${embCfg.model} (${embCfg.dimensions}d) @ ${embCfg.baseUrl || "(sdk)"}`);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        setSetupError(`Embedding init failed: ${msg}`);
+        log("ERROR", `Embedding init failed: ${msg}`);
+        // Continue — server will report setup_required for memory tools.
+    }
+    if (qUrl) {
         try {
             await ensureCollection(QDRANT_INDEXES);
             setReady(true);
-            log("INFO", "Memory system ready ✓");
+            log("INFO", `Memory system ready ✓ (Qdrant ${qKey ? "with" : "without"} api-key auth)`);
         }
         catch (e) {
-            log("ERROR", `Failed to initialize collection: ${e instanceof Error ? e.message : String(e)}`);
+            const msg = e instanceof Error ? e.message : String(e);
+            setSetupError(`Qdrant initialization failed: ${msg}`);
+            log("ERROR", `Failed to initialize collection: ${msg}`);
         }
     }
     else {
-        const missing = [];
-        if (!qUrl)
-            missing.push("qdrant-url");
-        if (!qKey)
-            missing.push("qdrant-api-key");
-        log("INFO", `Memory not configured — missing: ${missing.join(", ")}. Use get_setup_status + configure_credentials.`);
+        log("INFO", "Memory not configured — missing: qdrant-url. Use get_setup_status + configure_credentials.");
     }
     const mcp = new McpServer({
         name: "bikky",
         version: "0.1.0",
     }, {
-        instructions: "Shared memory tools for AI coding sessions. Store and recall facts, entities, and relationships across sessions.",
+        instructions: [
+            "Bikky provides persistent memory across AI coding sessions. Use it as a working loop, not a database:",
+            "  • STORE when you learn something durable (a service detail, a decision, a workaround, a user preference). Call memory_store with one atomic fact per call — dedup is automatic, so don't pre-check.",
+            "  • RECALL before acting. At session start, call memory_recall with a broad briefing query. For each new user prompt about an unfamiliar topic, recall again with a focused query. Recall before storing too, to surface conflicts.",
+            "  • VERIFY when stale. memory_heartbeat surfaces stale fact IDs every ~3 calls; confirm them with memory_verify, retire them with memory_forget, or replace them with memory_store(supersedes: <id>).",
+            "  • ENTITY-FIRST queries. When the user asks 'tell me about X', prefer memory_entity over memory_recall.",
+            "If the system is not configured, call get_setup_status for guidance.",
+        ].join("\n"),
     });
     registerTools(mcp);
     const transport = new StdioServerTransport();

package/dist/mcp/index.js.map

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

package/dist/mcp/taxonomy.d.ts

@@ -1,38 +1,258 @@
 /**
- * Memory Taxonomy — Single source of truth for all classification axes.
+ * Bikky memory ontology.
  *
- * Four orthogonal axes classify every fact:
- *   category — topic/subject matter (what the fact is about)
- *   domain   — life scope (work vs personal context)
- *   kind     — epistemic type (how the knowledge exists)
- *   source   — provenance (who/what created this fact)
+ * Ontology v2 separates ownership boundaries from semantic meaning:
+ * workspace -> domain -> repo/project/surface -> workstream -> episode -> memory objects.
  */
-import type { AxisDef, CategoryDef, QdrantIndex } from "./types.js";
-export declare const CATEGORIES: Record<string, CategoryDef>;
-export declare const DOMAINS: Record<string, AxisDef>;
-export declare const DEFAULT_DOMAIN = "work";
-export declare const KINDS: Record<string, AxisDef>;
-export declare const DEFAULT_KIND = "fact";
-export declare const SOURCES: Record<string, AxisDef>;
-export declare const DEFAULT_SOURCE = "agent";
-export declare const DECAY_DEFAULT_HALF_LIFE = 90;
-export declare function getDecayHalfLife(opts?: {
-    kind?: string;
-    category?: string;
-    domain?: string;
-}): number | null;
-export declare const DECAY_HALF_LIFE: Record<string, number | null>;
+export declare const CATEGORIES: {
+    readonly codebase: {
+        readonly description: "Repository structure, modules, important files, APIs, build/test commands, and code navigation knowledge.";
+        readonly examples: readonly ["The auth middleware lives in src/server/auth.ts.", "Run npm test -- --runInBand for flaky integration tests."];
+    };
+    readonly infrastructure: {
+        readonly description: "Cloud, deployment, runtime, secrets, queues, databases, CI/CD, and environment topology.";
+        readonly examples: readonly ["Production runs on a Qdrant cluster (Cloud or self-hosted) for vector storage.", "Deployments are promoted through GitHub Actions."];
+    };
+    readonly operations: {
+        readonly description: "Runbooks, incident handling, maintenance procedures, debugging steps, and operational gotchas.";
+        readonly examples: readonly ["Restart the worker after changing queue visibility timeout.", "If migrations hang, check the advisory lock table first."];
+    };
+    readonly decisions: {
+        readonly description: "Architecture, product, process, and technical decisions with durable rationale.";
+        readonly examples: readonly ["Use workspace_id as the access boundary instead of overloading domain.", "Keep telemetry out of normal semantic recall."];
+    };
+    readonly product_domain: {
+        readonly description: "Product concepts, business rules, user workflows, domain vocabulary, and market assumptions.";
+        readonly examples: readonly ["A workstream is the durable continuity unit for long-running tasks.", "Recall quality should be measured by downstream usefulness, not just similarity."];
+    };
+    readonly projects: {
+        readonly description: "Project goals, milestones, current state, open questions, blockers, and active workstreams.";
+        readonly examples: readonly ["The capture-policy RPI is implementing ontology v2 first.", "The UI smoke suite is tracked in bikky-dev/bikky#13."];
+    };
+    readonly people: {
+        readonly description: "Ownership, roles, collaboration patterns, responsibilities, and team preferences.";
+        readonly examples: readonly ["Saber prefers concise implementation plans before code changes.", "The platform team owns the deploy workflow."];
+    };
+    readonly preferences: {
+        readonly description: "User, team, or workspace preferences about style, tooling, defaults, and interaction patterns.";
+        readonly examples: readonly ["Prefer Node's built-in test runner for this repo.", "Default new memory captures to software_engineering."];
+    };
+    readonly observations: {
+        readonly description: "Validated observations, troubleshooting evidence, behavioral notes, and learned facts that do not fit a narrower category.";
+        readonly examples: readonly ["The current ESLint config is incompatible with ESLint v9.", "The dashboard shows stale facts separately from verified current facts."];
+    };
+};
+export type Category = keyof typeof CATEGORIES;
+export declare const DEFAULT_CATEGORY: Category;
+export declare const DOMAINS: {
+    readonly software_engineering: {
+        readonly description: "Coding-agent work: repositories, code changes, architecture, infrastructure, debugging, tests, CI, and developer workflow.";
+        readonly defaultCategories: readonly ["codebase", "infrastructure", "operations", "decisions", "projects", "preferences", "observations"];
+    };
+    readonly product_strategy: {
+        readonly description: "Product direction, positioning, roadmap tradeoffs, customer problems, metrics, and market learning.";
+        readonly defaultCategories: readonly ["product_domain", "decisions", "projects", "people", "preferences", "observations"];
+    };
+    readonly business_operations: {
+        readonly description: "Business process, vendors, finance, legal/admin operations, recurring procedures, and ownership.";
+        readonly defaultCategories: readonly ["operations", "decisions", "projects", "people", "preferences", "observations"];
+    };
+    readonly research: {
+        readonly description: "Research questions, sources, hypotheses, experiment findings, synthesis, and reusable insights.";
+        readonly defaultCategories: readonly ["product_domain", "decisions", "projects", "preferences", "observations"];
+    };
+    readonly personal_productivity: {
+        readonly description: "Individual productivity, habits, planning preferences, reminders, and personal operating context.";
+        readonly defaultCategories: readonly ["operations", "projects", "people", "preferences", "observations"];
+    };
+};
+export type Domain = keyof typeof DOMAINS;
+export declare const DEFAULT_DOMAIN: Domain;
+export declare const LAYERS: {
+    readonly workspace: {
+        readonly description: "Ownership, tenancy, access policy, sharing, redaction, retention, and quotas.";
+    };
+    readonly domain: {
+        readonly description: "Semantic profile that controls vocabulary, prompts, categories, ranking, and capture policy.";
+    };
+    readonly surface: {
+        readonly description: "Concrete operating surface such as a repo, project, package, service, branch, or channel.";
+    };
+    readonly workstream: {
+        readonly description: "Primary durable continuity key for a long-running objective or task.";
+    };
+    readonly episode: {
+        readonly description: "Coherent segment of activity within a session or transcript.";
+    };
+    readonly memory_object: {
+        readonly description: "A fact, summary, distilled learning, relation, or telemetry object.";
+    };
+};
+export type Layer = keyof typeof LAYERS;
+export declare const KINDS: {
+    readonly fact: {
+        readonly description: "Atomic, durable memory that should be retrievable independently.";
+        readonly examples: readonly ["The daemon stores extracted coding-agent observations in Qdrant.", "The UI package uses Vite and Node's built-in test runner."];
+    };
+    readonly summary: {
+        readonly description: "Compressed representation of a session index, coherent episode, or current workstream state.";
+        readonly examples: readonly ["Episode summary of a coherent implementation task.", "Current-state summary for a workstream."];
+    };
+    readonly distilled: {
+        readonly description: "Pattern, convention, failure mode, or reusable learning synthesized from multiple memories.";
+        readonly examples: readonly ["Prefer explicit workspace filters for scoped team memory.", "Missing Qdrant payload indexes surface as query failures."];
+    };
+    readonly relation: {
+        readonly description: "Typed edge between entities; relation_type carries the edge label.";
+        readonly examples: readonly ["bikky -> uses -> qdrant", "workspace_id -> represents -> access boundary"];
+    };
+    readonly telemetry: {
+        readonly description: "Memory-use, feedback, or outcome metadata used for product quality and operations; excluded from normal semantic recall.";
+        readonly examples: readonly ["A recall event returned three facts for session abc.", "A user marked a fact useful."];
+    };
+};
+export type Kind = keyof typeof KINDS;
+export declare const MEMORY_SUBTYPES: {
+    readonly fact: readonly ["codebase_map", "architecture_decision", "infra_topology", "access_pattern", "deployment_procedure", "operational_procedure", "domain_rule", "troubleshooting_gotcha", "preference", "ownership"];
+    readonly summary: readonly ["session_index", "episode", "workstream"];
+    readonly distilled: readonly ["runbook_candidate", "failure_mode", "convention", "architecture_pattern", "product_insight"];
+    readonly relation: readonly [];
+    readonly telemetry: readonly ["recall_event", "feedback_event", "outcome_event", "aggregate_rollup"];
+};
+export type MemorySubtype = (typeof MEMORY_SUBTYPES)[Kind][number];
+export declare const DEFAULT_MEMORY_SUBTYPE_BY_KIND: {
+    readonly fact: "codebase_map";
+    readonly summary: "episode";
+    readonly distilled: "convention";
+    readonly relation: null;
+    readonly telemetry: "recall_event";
+};
+export declare const MEMORY_SUBTYPE_DEFAULT_CATEGORY: {
+    readonly codebase_map: "codebase";
+    readonly architecture_decision: "decisions";
+    readonly infra_topology: "infrastructure";
+    readonly access_pattern: "infrastructure";
+    readonly deployment_procedure: "operations";
+    readonly operational_procedure: "operations";
+    readonly domain_rule: "product_domain";
+    readonly troubleshooting_gotcha: "operations";
+    readonly preference: "preferences";
+    readonly ownership: "people";
+    readonly session_index: "projects";
+    readonly episode: "projects";
+    readonly workstream: "projects";
+    readonly runbook_candidate: "operations";
+    readonly failure_mode: "operations";
+    readonly convention: "observations";
+    readonly architecture_pattern: "decisions";
+    readonly product_insight: "product_domain";
+    readonly recall_event: "observations";
+    readonly feedback_event: "observations";
+    readonly outcome_event: "observations";
+    readonly aggregate_rollup: "observations";
+};
+export declare const MEMORY_SUBTYPE_DEFAULT_LAYER: {
+    readonly codebase_map: "surface";
+    readonly architecture_decision: "surface";
+    readonly infra_topology: "surface";
+    readonly access_pattern: "surface";
+    readonly deployment_procedure: "surface";
+    readonly operational_procedure: "surface";
+    readonly domain_rule: "domain";
+    readonly troubleshooting_gotcha: "surface";
+    readonly preference: "domain";
+    readonly ownership: "surface";
+    readonly session_index: "episode";
+    readonly episode: "episode";
+    readonly workstream: "workstream";
+    readonly runbook_candidate: "workstream";
+    readonly failure_mode: "workstream";
+    readonly convention: "domain";
+    readonly architecture_pattern: "domain";
+    readonly product_insight: "domain";
+    readonly recall_event: "memory_object";
+    readonly feedback_event: "memory_object";
+    readonly outcome_event: "memory_object";
+    readonly aggregate_rollup: "workspace";
+};
+export declare const SOURCES: {
+    readonly agent: {
+        readonly description: "Captured from an interactive agent tool call.";
+    };
+    readonly daemon: {
+        readonly description: "Captured automatically by the local Bikky daemon.";
+    };
+    readonly system: {
+        readonly description: "Generated by Bikky maintenance, migration, or lifecycle code.";
+    };
+    readonly user: {
+        readonly description: "Created or corrected directly by a user.";
+    };
+    readonly docs: {
+        readonly description: "Imported from documentation or explicit source material.";
+    };
+};
+export type Source = keyof typeof SOURCES;
+export declare const DEFAULT_KIND: Kind;
+export declare const DEFAULT_SOURCE: Source;
 export declare const STALENESS_DAYS = 30;
+export declare const DECAY_DEFAULT_HALF_LIFE = 90;
 export declare const THRESHOLD_DUPLICATE = 0.92;
 export declare const THRESHOLD_RELATED = 0.8;
-export declare const QDRANT_INDEXES: QdrantIndex[];
-export declare const SOURCE_MIGRATION: Record<string, string>;
-export declare function normalizeCategory(cat: string): string;
-export declare function normalizeDomain(d: string | undefined): string;
-export declare function normalizeKind(k: string | undefined): string;
-export declare function normalizeSource(s: string | undefined): string;
-export declare const categoryValues: () => [string, ...string[]];
-export declare const domainValues: () => [string, ...string[]];
-export declare const kindValues: () => [string, ...string[]];
-export declare const sourceValues: () => [string, ...string[]];
+export declare const DECAY_HALF_LIFE: Record<string, number>;
+export declare const QDRANT_INDEXES: Array<{
+    field_name: string;
+    field_schema: string;
+}>;
+type NonEmptyStringArray = [string, ...string[]];
+export declare function normalizeText(text: string): string;
+export declare function normalizeCategory(category: string | null | undefined): Category;
+export declare function normalizeDomain(domain: string | null | undefined): Domain;
+export declare function normalizeKind(kind: string | null | undefined): Kind;
+export declare function normalizeSource(source: string | null | undefined): Source;
+export declare function normalizeLayer(layer: string | null | undefined): Layer | null;
+export declare function normalizeMemorySubtype(kind: string | null | undefined, subtype: string | null | undefined): MemorySubtype | null;
+export declare function validateMemorySubtype(kind: string | null | undefined, subtype: string | null | undefined): MemorySubtype | null;
+export declare function defaultMemorySubtypeForKind(kind: string | null | undefined): MemorySubtype | null;
+export declare function categoryForMemorySubtype(subtype: string | null | undefined): Category | null;
+export declare function layerForMemorySubtype(subtype: string | null | undefined): Layer | null;
+export declare function normalizeEntities(entities: string[]): string[];
+export declare function inferEntities(content: string): string[];
+export declare function getDecayHalfLife(input: {
+    category?: string | null;
+    domain?: string | null;
+    kind?: string | null;
+}): number | null;
+export declare function categoryValues(): NonEmptyStringArray;
+export declare function canonicalCategoryValues(): NonEmptyStringArray;
+export declare function domainValues(): NonEmptyStringArray;
+export declare function canonicalDomainValues(): NonEmptyStringArray;
+export declare function kindValues(): NonEmptyStringArray;
+export declare function layerValues(): NonEmptyStringArray;
+/**
+ * Render the documentation block for a single category — used inside LLM prompts
+ * so the model sees the same description and examples that taxonomy.ts declares
+ * as canonical. Keeps prompts and code in sync.
+ */
+export declare function categoryPromptSection(category: string): string;
+/** Render every category section back-to-back. */
+export declare function allCategoryPromptSections(): string;
+/** Render the `category` enum description for memory_store / memory_recall. */
+export declare function categoryEnumDescription(): string;
+/** Render the `domain` enum description. */
+export declare function domainEnumDescription(): string;
+/** Render the `kind` enum description. Telemetry is daemon-only — excluded. */
+export declare function kindEnumDescription(): string;
+/**
+ * Render the `memory_subtype` enum description, grouped by kind so the agent
+ * knows which subtypes pair with which kind (the runtime enforces this via
+ * validateMemorySubtype).
+ */
+export declare function memorySubtypeEnumDescription(): string;
+/** Render the `source` enum description for memory_store. */
+export declare function sourceEnumDescription(): string;
+export declare function memorySubtypeValues(): NonEmptyStringArray;
+export declare function memorySubtypeValuesForKind(kind: string | null | undefined): string[];
+export declare function sourceValues(): NonEmptyStringArray;
+export {};
 //# sourceMappingURL=taxonomy.d.ts.map

package/dist/mcp/taxonomy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"taxonomy.d.ts","sourceRoot":"","sources":["../../src/mcp/taxonomy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAIpE,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAwDlD,CAAC;AAIF,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAG3C,CAAC;AAEF,eAAO,MAAM,cAAc,SAAS,CAAC;AAIrC,eAAO,MAAM,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAKzC,CAAC;AAEF,eAAO,MAAM,YAAY,SAAS,CAAC;AAInC,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAM3C,CAAC;AAEF,eAAO,MAAM,cAAc,UAAU,CAAC;AAgBtC,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,wBAAgB,gBAAgB,CAAC,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,MAAM,GAAG,IAAI,CAehH;AAGD,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAWzD,CAAC;AAIF,eAAO,MAAM,cAAc,KAAK,CAAC;AAIjC,eAAO,MAAM,mBAAmB,OAAO,CAAC;AACxC,eAAO,MAAM,iBAAiB,MAAO,CAAC;AAItC,eAAO,MAAM,cAAc,EAAE,WAAW,EAcvC,CAAC;AAIF,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAMnD,CAAC;AAIF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAcrD;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAM7D;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAQ3D;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAO7D;AAID,eAAO,MAAM,cAAc,QAAO,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CACJ,CAAC;AAEnD,eAAO,MAAM,YAAY,QAAO,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CACL,CAAC;AAEhD,eAAO,MAAM,UAAU,QAAO,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CACL,CAAC;AAE9C,eAAO,MAAM,YAAY,QAAO,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CACL,CAAC"}
+{"version":3,"file":"taxonomy.d.ts","sourceRoot":"","sources":["../../src/mcp/taxonomy.ts"],"names":[],"mappings":"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"}