harper-kb 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nathan Heskew
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,288 @@
+# harper-kb
+
+Knowledge base for [Harper](https://harper.fast/), built on Harper, with MCP server integration.
+
+A Harper plugin that provides searchable, scoped knowledge entries with vector embeddings for semantic search. Exposes a REST API and MCP endpoint.
+
+## Consumers
+
+- **Support team** — finding solutions, patterns, gotchas, customer edge cases
+- **DX lab "Harper expert"** — backing knowledge for the AI expert role in Gas Town labs
+- **Claude Code / IDE assistants** — Harper context via MCP without per-project CLAUDE.md files
+- **Any MCP client** — Cursor, VS Code + Copilot, JetBrains, ChatGPT, Gemini, etc.
+
+## Quick Start
+
+### Prerequisites
+
+- [Harper](https://harper.fast/) >= 4.7.0
+- Node.js >= 22
+
+### Install
+
+```bash
+npm install harper-kb
+```
+
+### Configure
+
+Add to your application's `config.yaml`:
+
+```yaml
+'harper-kb':
+  package: 'harper-kb'
+  embeddingModel: nomic-embed-text # default
+```
+
+### Run
+
+```bash
+harperdb dev .
+```
+
+## Embeddings
+
+Vector embeddings for semantic search run locally on CPU using [Nomic](https://huggingface.co/nomic-ai) embedding models via llama.cpp. Two backends are supported:
+
+| Backend                                                                        | Install                              | Use case                                 |
+| ------------------------------------------------------------------------------ | ------------------------------------ | ---------------------------------------- |
+| [harper-fabric-embeddings](https://github.com/heskew/harper-fabric-embeddings) | Optional dependency (auto-installed) | Production on Fabric (linux-x64, ~19 MB) |
+| [node-llama-cpp](https://github.com/withcatai/node-llama-cpp)                  | `npm install node-llama-cpp`         | Local development on any platform        |
+
+The plugin tries `harper-fabric-embeddings` first and falls back to `node-llama-cpp`. If neither is available, semantic search is skipped and keyword search still works.
+
+### Models
+
+| Config key                   | Model                                                                                        | Parameters | Dimensions |
+| ---------------------------- | -------------------------------------------------------------------------------------------- | ---------- | ---------- |
+| `nomic-embed-text` (default) | [nomic-embed-text-v1.5-GGUF](https://huggingface.co/nomic-ai/nomic-embed-text-v1.5-GGUF)     | 137M       | 768        |
+| `nomic-embed-text-v2-moe`    | [nomic-embed-text-v2-moe-GGUF](https://huggingface.co/nomic-ai/nomic-embed-text-v2-moe-GGUF) | 475M (MoE) | 768        |
+
+```yaml
+'harper-kb':
+  package: 'harper-kb'
+  embeddingModel: nomic-embed-text # v1.5 (default)
+  # embeddingModel: nomic-embed-text-v2-moe  # v2 MoE — better quality, larger
+```
+
+## Architecture
+
+```
+harper-kb
+├── src/
+│   ├── index.ts              ← plugin entry: handleApplication()
+│   ├── hooks.ts              ← extensibility hooks (onAccessCheck, loginPath)
+│   ├── http-utils.ts         ← request body reading, header helpers
+│   ├── types.ts              ← shared types + Harper global declarations
+│   ├── core/                 ← shared logic
+│   │   ├── embeddings.ts     ← model download, init, vector generation
+│   │   ├── entries.ts        ← CRUD + relationship management
+│   │   ├── history.ts        ← edit history audit log
+│   │   ├── knowledge-base.ts ← KB registry (multi-tenant)
+│   │   ├── search.ts         ← keyword / semantic / hybrid search
+│   │   ├── tags.ts           ← tag registry with counts
+│   │   ├── triage.ts         ← webhook intake queue
+│   │   └── webhook-endpoints.ts ← webhook secret management
+│   ├── resources/            ← REST Resource classes
+│   │   ├── HistoryResource.ts
+│   │   ├── KnowledgeBaseResource.ts
+│   │   ├── KnowledgeEntryResource.ts
+│   │   ├── MeResource.ts
+│   │   ├── QueryLogResource.ts
+│   │   ├── ServiceKeyResource.ts
+│   │   ├── TagResource.ts
+│   │   ├── TriageResource.ts
+│   │   └── WebhookEndpointResource.ts
+│   ├── mcp/                  ← MCP server (JSON-RPC over HTTP)
+│   │   ├── protocol.ts       ← JSON-RPC dispatcher
+│   │   ├── server.ts         ← HTTP middleware (auth, KB scoping)
+│   │   └── tools.ts          ← tool definitions + handlers
+│   ├── oauth/                ← OAuth 2.1 authorization server
+│   │   ├── authorize.ts
+│   │   ├── init.ts
+│   │   ├── keys.ts
+│   │   ├── metadata.ts
+│   │   ├── middleware.ts
+│   │   ├── register.ts
+│   │   ├── token.ts
+│   │   └── validate.ts
+│   └── webhooks/             ← webhook intake (GitHub)
+│       ├── github.ts
+│       ├── middleware.ts
+│       └── types.ts
+├── schema/
+│   ├── knowledge.graphql     ← table definitions (database: "kb")
+│   └── oauth.graphql         ← OAuth tables
+├── config.yaml
+├── package.json
+└── test/
+```
+
+Both REST and MCP run in the Harper process, both call the same core functions with zero overhead.
+
+## REST API
+
+| Endpoint                | Method          | Auth       | Description               |
+| ----------------------- | --------------- | ---------- | ------------------------- |
+| `/KnowledgeBase/`       | GET             | Public     | List knowledge bases      |
+| `/KnowledgeBase/<id>`   | GET             | Public     | Get KB by ID              |
+| `/KnowledgeBase/`       | POST/PUT/DELETE | Team       | Manage knowledge bases    |
+| `/Knowledge/<id>`       | GET             | Public     | Get entry by ID           |
+| `/Knowledge/?query=...` | GET             | Public     | Search entries            |
+| `/Knowledge/`           | POST            | Required   | Create entry              |
+| `/Knowledge/<id>`       | PUT             | Required   | Update entry              |
+| `/Knowledge/<id>`       | DELETE          | Team       | Deprecate entry           |
+| `/KnowledgeTag/`        | GET             | Public     | List all tags             |
+| `/Triage/`              | GET             | Team       | List pending triage items |
+| `/Triage/`              | POST            | Service/AI | Submit triage item        |
+| `/Triage/<id>`          | PUT             | Team       | Process triage item       |
+| `/QueryLog/`            | GET             | Team       | Search analytics          |
+| `/ServiceKey/`          | GET/POST/DELETE | Team       | API key management        |
+| `/WebhookEndpoint/`     | GET/POST/DELETE | Team       | Webhook endpoint secrets  |
+| `/History/<entryId>`    | GET             | Public     | Edit history for an entry |
+| `/Me/`                  | GET             | Public     | Current user/session info |
+
+### Search Parameters
+
+```
+GET /Knowledge/?query=MQTT+auth&tags=mqtt,config&limit=10&mode=keyword&context={"harper":"5.0","storageEngine":"lmdb"}
+```
+
+- `query` — search text (required)
+- `tags` — comma-separated tag filter
+- `limit` — max results (default 10)
+- `mode` — `keyword`, `semantic`, or `hybrid` (default)
+- `context` — JSON applicability context for result boosting
+
+## MCP Endpoint
+
+Each knowledge base gets its own MCP endpoint at `/mcp/<kbId>`. Connect any MCP-compatible client:
+
+```json
+{
+	"mcpServers": {
+		"harper-kb": {
+			"url": "https://kb.harper.fast:9926/mcp/my-kb-id"
+		}
+	}
+}
+```
+
+### Tools
+
+| Tool                  | Description                                                       |
+| --------------------- | ----------------------------------------------------------------- |
+| `knowledge_search`    | Search with keyword/semantic/hybrid modes + applicability context |
+| `knowledge_add`       | Add a new entry (auto-tagged `ai-generated`)                      |
+| `knowledge_get`       | Get entry by ID with full relationship chain                      |
+| `knowledge_update`    | Update an entry with edit history tracking                        |
+| `knowledge_related`   | Find related entries (explicit + semantic similarity)             |
+| `knowledge_list_tags` | List all tags with counts                                         |
+| `knowledge_triage`    | Submit to triage queue for review                                 |
+| `knowledge_history`   | Get edit history for an entry (who changed what, when, why)       |
+| `knowledge_reindex`   | Backfill missing embeddings                                       |
+| `knowledge_link`      | Create related/sibling relationships between entries              |
+
+## Schema
+
+Tables in the `kb` database:
+
+- **KnowledgeBase** — KB registry (multi-tenant)
+- **KnowledgeEntry** — core entries with HNSW vector index, `@relationship` directives for supersession/siblings/related, `@createdTime`/`@updatedTime`
+- **KnowledgeEntryEdit** — append-only edit history audit log
+- **TriageItem** — webhook intake queue (7-day TTL)
+- **KnowledgeTag** — tag name as primary key with entry counts
+- **QueryLog** — search analytics (30-day TTL)
+- **ServiceKey** — API keys with scrypt-hashed secrets
+- **WebhookEndpoint** — per-KB webhook secrets
+- **WebhookDelivery** — delivery ID dedup across workers (1-hour TTL)
+- **OAuthClient** — dynamic client registrations (RFC 7591)
+- **OAuthCode** — authorization codes (5-minute TTL)
+- **OAuthRefreshToken** — refresh tokens (30-day TTL)
+- **OAuthSigningKey** — RSA key pair for JWT signing
+
+### Applicability Scoping
+
+Entries carry an `appliesTo` scope:
+
+```json
+{
+	"harper": ">=4.0 <5.0",
+	"storageEngine": "lmdb",
+	"node": ">=22",
+	"platform": "linux"
+}
+```
+
+Search results are boosted or demoted (never hidden) based on the caller's context.
+
+### Entry Relationships
+
+- **Supersedes** — "This replaces that for newer versions"
+- **Siblings** — "Same topic, different config" (e.g., LMDB vs RocksDB behavior)
+- **Related** — loose "see also" association
+
+## Auth Model
+
+| Role              | Read | Write                        | Review | Manage |
+| ----------------- | ---- | ---------------------------- | ------ | ------ |
+| `team`            | Yes  | Yes                          | Yes    | Yes    |
+| `ai_agent`        | Yes  | Yes (flagged `ai-generated`) | No     | No     |
+| `service_account` | Yes  | Triage queue only            | No     | No     |
+
+MCP uses OAuth 2.1 with PKCE for authentication. MCP clients discover auth requirements via `/.well-known/oauth-protected-resource`, register dynamically, and authenticate through a browser-based login flow (GitHub OAuth primary, Harper credentials fallback). The web UI uses GitHub OAuth via `@harperfast/oauth` with Harper credentials as fallback.
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Run tests (414 tests)
+npm test
+
+# Test with coverage
+npm run test:coverage
+
+# Watch mode
+npm run dev
+
+# For local semantic search, install node-llama-cpp
+npm install node-llama-cpp
+```
+
+### Testing
+
+Tests use Node.js built-in test runner (`node:test`) with mock Harper globals (in-memory tables). Tests run against compiled output in `dist/`.
+
+```bash
+npm test
+```
+
+## Fabric Deployment
+
+For deploying to Harper Fabric, `harper-fabric-embeddings` is installed automatically as an optional dependency — no node-llama-cpp trimming or special build steps needed.
+
+```dockerfile
+# Dockerfile.build
+FROM --platform=linux/amd64 node:22-slim AS build
+WORKDIR /build
+
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+
+# Remove harperdb (provided by Fabric runtime)
+RUN rm -rf node_modules/harperdb node_modules/.bin/harperdb
+
+COPY config.yaml ./
+COPY .env ./
+
+FROM --platform=linux/amd64 node:22-slim AS package
+WORKDIR /out
+COPY --from=build /build /out/app
+RUN tar czf /out/app.tar.gz -C /out app
+```
+
+## License
+
+MIT

package/config.yaml

@@ -0,0 +1,13 @@
+# Knowledge Base Plugin Configuration
+# This file defines the plugin entry point and default settings
+# All settings can be overridden in your application's config.yaml
+
+# Plugin entry point (required by Harper)
+pluginModule: 'dist/index.js'
+
+# GraphQL schema for knowledge base tables
+graphqlSchema:
+  files: 'schema/*.graphql'
+
+# Default settings (optional - these are used if not specified in app config)
+embeddingModel: 'nomic-embed-text'

package/dist/core/embeddings.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Embedding Model Management
+ *
+ * Generates vector embeddings for semantic search. Supports two backends:
+ *
+ *   1. harper-fabric-embeddings — Minimal native wrapper (~19 MB).
+ *      Preferred on Fabric. Requires a pre-staged model file.
+ *
+ *   2. node-llama-cpp — Full-featured wrapper (~250 MB+).
+ *      Fallback for local dev. Downloads the model on first run.
+ *
+ * The backend is selected automatically: fabric-llama-embeddings is tried
+ * first, and node-llama-cpp is used if it's not available.
+ */
+/**
+ * Initialize the embedding model.
+ * Tries fabric-llama-embeddings first, then falls back to node-llama-cpp.
+ */
+export declare function initEmbeddingModel(config: {
+    embeddingModel: string;
+    componentDir: string;
+}): Promise<void>;
+/**
+ * Generate an embedding vector for the given text.
+ */
+export declare function generateEmbedding(text: string): Promise<number[]>;
+/**
+ * Clean up embedding model resources.
+ */
+export declare function dispose(): Promise<void>;
+//# sourceMappingURL=embeddings.d.ts.map

package/dist/core/embeddings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddings.d.ts","sourceRoot":"","sources":["../../src/core/embeddings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAiCH;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBhH;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAKvE;AAED;;GAEG;AACH,wBAAsB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAM7C"}

package/dist/core/embeddings.js

@@ -0,0 +1,199 @@
+/**
+ * Embedding Model Management
+ *
+ * Generates vector embeddings for semantic search. Supports two backends:
+ *
+ *   1. harper-fabric-embeddings — Minimal native wrapper (~19 MB).
+ *      Preferred on Fabric. Requires a pre-staged model file.
+ *
+ *   2. node-llama-cpp — Full-featured wrapper (~250 MB+).
+ *      Fallback for local dev. Downloads the model on first run.
+ *
+ * The backend is selected automatically: fabric-llama-embeddings is tried
+ * first, and node-llama-cpp is used if it's not available.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { writeFile, readFile, unlink, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+let backend = null;
+// ─── Model configuration ───────────────────────────────────────────────────
+const MODEL_CONFIGS = {
+    'nomic-embed-text': {
+        repo: 'nomic-ai/nomic-embed-text-v1.5-GGUF',
+        file: 'nomic-embed-text-v1.5.Q4_K_M.gguf',
+    },
+    'nomic-embed-text-v2-moe': {
+        repo: 'nomic-ai/nomic-embed-text-v2-moe-GGUF',
+        file: 'nomic-embed-text-v2-moe.Q4_K_M.gguf',
+    },
+};
+// Module-level models directory, set during initEmbeddingModel
+let modelsDir = null;
+// ─── Public API ─────────────────────────────────────────────────────────────
+/**
+ * Initialize the embedding model.
+ * Tries fabric-llama-embeddings first, then falls back to node-llama-cpp.
+ */
+export async function initEmbeddingModel(config) {
+    if (backend) {
+        logger?.debug?.('Embedding model already initialized');
+        return;
+    }
+    const modelName = config.embeddingModel || 'nomic-embed-text';
+    modelsDir = path.join(config.componentDir, 'models');
+    // Try fabric-llama-embeddings first (lightweight, Fabric-optimized)
+    try {
+        backend = await initFabricBackend(modelName);
+        logger?.info?.(`Embedding model "${modelName}" loaded via fabric-llama-embeddings`);
+        return;
+    }
+    catch (err) {
+        logger?.debug?.('fabric-llama-embeddings not available, trying node-llama-cpp:', err.message);
+    }
+    // Fall back to node-llama-cpp (full-featured, handles downloads)
+    backend = await initNodeLlamaCppBackend(modelName);
+    logger?.info?.(`Embedding model "${modelName}" loaded via node-llama-cpp`);
+}
+/**
+ * Generate an embedding vector for the given text.
+ */
+export async function generateEmbedding(text) {
+    if (!backend) {
+        throw new Error('Embedding model not initialized. Call initEmbeddingModel() first.');
+    }
+    return backend.generateEmbedding(text);
+}
+/**
+ * Clean up embedding model resources.
+ */
+export async function dispose() {
+    if (backend) {
+        await backend.dispose();
+        backend = null;
+    }
+    logger?.info?.('Embedding model disposed');
+}
+// ─── fabric-llama-embeddings backend ────────────────────────────────────────
+async function initFabricBackend(modelName) {
+    const fabricPkg = 'harper-fabric-embeddings';
+    const fabricModule = (await import(__rewriteRelativeImportExtension(fabricPkg)));
+    // Pass modelsDir so the fabric backend can find or download the model
+    await fabricModule.init({ modelsDir: modelsDir, modelName });
+    return {
+        generateEmbedding: (text) => fabricModule.embed(text),
+        dispose: () => fabricModule.dispose(),
+    };
+}
+async function initNodeLlamaCppBackend(modelName) {
+    const modelPath = await downloadModelIfNeeded(modelName);
+    // @ts-expect-error — node-llama-cpp is an optional manual install, not a declared dependency
+    const { getLlama } = (await import('node-llama-cpp'));
+    const llama = await getLlama({ progressLogs: false, build: 'never' });
+    const model = await llama.loadModel({ modelPath });
+    const ctx = await model.createEmbeddingContext({ contextSize: 'auto' });
+    return {
+        async generateEmbedding(text) {
+            const result = await ctx.getEmbeddingFor(text);
+            return Array.from(result.vector);
+        },
+        async dispose() {
+            if (ctx && !ctx.disposed)
+                await ctx.dispose();
+            await model.dispose();
+            await llama.dispose();
+        },
+    };
+}
+// ─── Model download (node-llama-cpp only) ───────────────────────────────────
+function getModelUri(modelName) {
+    const config = MODEL_CONFIGS[modelName];
+    if (!config) {
+        throw new Error(`Unknown embedding model: ${modelName}. Supported: ${Object.keys(MODEL_CONFIGS).join(', ')}`);
+    }
+    return `hf:${config.repo}/${config.file}`;
+}
+function getLockFilePath(modelName) {
+    return path.join(modelsDir, `${modelName}.lock`);
+}
+async function acquireDownloadLock(modelName) {
+    const lockPath = getLockFilePath(modelName);
+    try {
+        if (existsSync(lockPath)) {
+            const lockContent = await readFile(lockPath, 'utf-8');
+            const lockTime = parseInt(lockContent, 10);
+            if (!isNaN(lockTime) && Date.now() - lockTime < 10 * 60 * 1000) {
+                return false;
+            }
+        }
+        await writeFile(lockPath, String(Date.now()), { flag: 'wx' }).catch(async () => {
+            await writeFile(lockPath, String(Date.now()));
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function releaseDownloadLock(modelName) {
+    const lockPath = getLockFilePath(modelName);
+    try {
+        await unlink(lockPath);
+    }
+    catch {
+        // Already removed
+    }
+}
+async function waitForDownload(modelName, modelPath) {
+    const lockPath = getLockFilePath(modelName);
+    const maxWait = 10 * 60 * 1000;
+    const pollInterval = 2000;
+    const start = Date.now();
+    while (Date.now() - start < maxWait) {
+        if (existsSync(modelPath) && !existsSync(lockPath)) {
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+    throw new Error(`Timed out waiting for model download: ${modelName}`);
+}
+async function downloadModelIfNeeded(modelName) {
+    const modelUri = getModelUri(modelName);
+    const dir = modelsDir;
+    await mkdir(dir, { recursive: true });
+    const { createModelDownloader } = 
+    // @ts-expect-error — node-llama-cpp is an optional manual install, not a declared dependency
+    (await import('node-llama-cpp'));
+    const downloader = await createModelDownloader({
+        modelUri,
+        dirPath: dir,
+        skipExisting: true,
+    });
+    const modelPath = downloader.entrypointFilePath;
+    if (existsSync(modelPath)) {
+        return modelPath;
+    }
+    const acquired = await acquireDownloadLock(modelName);
+    if (!acquired) {
+        logger?.info?.(`Another thread is downloading ${modelName}, waiting...`);
+        await waitForDownload(modelName, modelPath);
+        return modelPath;
+    }
+    try {
+        logger?.info?.(`Downloading embedding model: ${modelName} from ${modelUri}`);
+        const resultPath = await downloader.download();
+        logger?.info?.(`Model ${modelName} downloaded successfully to ${resultPath}`);
+        return resultPath;
+    }
+    finally {
+        await releaseDownloadLock(modelName);
+    }
+}
+//# sourceMappingURL=embeddings.js.map

package/dist/core/embeddings.js.map

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

package/dist/core/entries.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Knowledge Entry Management
+ *
+ * CRUD operations for knowledge base entries. Handles embedding generation,
+ * tag synchronization, and relationship management.
+ */
+import type { KnowledgeEntry, KnowledgeEntryInput, KnowledgeEntryUpdate } from '../types.ts';
+/**
+ * Strip embedding vectors from an entry to keep responses compact.
+ * Embeddings are large float arrays not useful in API responses.
+ *
+ * NOTE: Harper database records use non-enumerable properties, so
+ * object spread ({...record}) produces an empty object. We must
+ * explicitly read each field.
+ */
+export declare function stripEmbedding(entry: any): Omit<KnowledgeEntry, 'embedding'>;
+/**
+ * Create a new knowledge entry.
+ *
+ * Generates an embedding from title + content, synchronizes tags,
+ * and stores the entry. A UUID is generated if no id is provided.
+ *
+ * @param data - Entry data to create
+ * @returns The created knowledge entry
+ */
+export declare function createEntry(data: KnowledgeEntryInput): Promise<KnowledgeEntry>;
+/**
+ * Get a knowledge entry by ID.
+ *
+ * @param id - Entry ID
+ * @returns The entry, or null if not found
+ */
+export declare function getEntry(id: string): Promise<KnowledgeEntry | null>;
+/**
+ * Update an existing knowledge entry.
+ *
+ * Merges the update data with the existing entry. If title or content changed,
+ * regenerates the embedding. Synchronizes tag counts if tags changed.
+ * Optionally logs the edit to the history table.
+ *
+ * @param id - ID of the entry to update
+ * @param data - Fields to update
+ * @param options - Optional edit tracking metadata
+ * @returns The updated entry
+ * @throws Error if the entry does not exist
+ */
+export declare function updateEntry(id: string, data: KnowledgeEntryUpdate, options?: {
+    editedBy?: string;
+    editSummary?: string;
+}): Promise<KnowledgeEntry>;
+/**
+ * Mark an entry as deprecated.
+ *
+ * @param id - ID of the entry to deprecate
+ * @throws Error if the entry does not exist
+ */
+export declare function deprecateEntry(id: string): Promise<void>;
+/**
+ * Link a new entry as superseding an old entry.
+ *
+ * Sets newEntry.supersedesId = oldId and oldEntry.supersededById = newId.
+ *
+ * @param newId - ID of the new (superseding) entry
+ * @param oldId - ID of the old (superseded) entry
+ * @throws Error if either entry does not exist
+ */
+export declare function linkSupersedes(newId: string, oldId: string): Promise<void>;
+/**
+ * Link multiple entries as siblings.
+ *
+ * For each entry, adds all other entry IDs to its siblingIds array (deduplicated).
+ *
+ * @param ids - IDs of entries to link as siblings
+ * @throws Error if any entry does not exist
+ */
+export declare function linkSiblings(ids: string[]): Promise<void>;
+/**
+ * Reindex embeddings for all entries missing them.
+ *
+ * Iterates every KnowledgeEntry, generates embeddings for any that
+ * don't have one yet, and writes them back. Returns counts of
+ * processed, updated, and failed entries.
+ */
+export declare function reindexEmbeddings(kbId: string): Promise<{
+    total: number;
+    updated: number;
+    failed: number;
+    skipped: number;
+}>;
+/**
+ * Link two entries as related.
+ *
+ * Adds relatedId to the entry's relatedIds array (deduplicated).
+ * This is a one-directional link; call twice for bidirectional.
+ *
+ * @param id - ID of the entry to add a related link to
+ * @param relatedId - ID of the related entry
+ * @throws Error if the entry does not exist
+ */
+export declare function linkRelated(id: string, relatedId: string): Promise<void>;
+//# sourceMappingURL=entries.d.ts.map

package/dist/core/entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entries.d.ts","sourceRoot":"","sources":["../../src/core/entries.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAE7F;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI,CAAC,cAAc,EAAE,WAAW,CAAC,CAyB5E;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CAuCpF;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAGzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAChC,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,oBAAoB,EAC1B,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD,OAAO,CAAC,cAAc,CAAC,CA+CzB;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAW9D;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBhF;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAkC/D;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CAChB,CAAC,CAmCD;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAe9E"}