@wappy_ai/connector-cognee 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 csr1010
+
+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/dist/client.d.ts

@@ -0,0 +1,57 @@
+/**
+ * A hand-rolled TypeScript REST client for Cognee's real API — no official Node.js/TypeScript SDK
+ * exists (confirmed via real research: Cognee's primary SDK is Python; the REST API is the actual
+ * integration surface for this ecosystem), so this follows the same pattern already proven in
+ * `@wappy_ai/connector-google`'s `oauth.ts` (a plain `fetch`-based client, injectable `fetchImpl` for
+ * testing, no SDK dependency).
+ *
+ * Every request/response shape here was confirmed against a REAL, locally-booted Cognee server
+ * (v1.6.2) — its own live OpenAPI spec (`GET /openapi.json`) plus real `curl` round-trips (register →
+ * login → create an API key → add → cognify → search → delete), not just read from docs. Concretely
+ * confirmed, not assumed:
+ * - `POST /api/v1/add` is `multipart/form-data`, fields `raw_data` (string) + `datasetName` — a JSON
+ *   body is rejected.
+ * - `POST /api/v1/cognify` is JSON `{ datasets: [name] }`.
+ * - `POST /api/v1/search` is JSON `{ query, searchType, topK? }`. `searchType` matters a lot —
+ *   the default (`HYBRID_COMPLETION`) returns an LLM-composed answer, not scored chunks; `"CHUNKS"`
+ *   is what returns a flat array of `{ id, text, score, document_id, document_name, ... }` objects,
+ *   which is the shape this client maps onto `Knowledge`'s `RecalledChunk`.
+ * - Self-hosted auth (when enabled) uses `X-Api-Key: <key>`, NOT `Authorization: Bearer`.
+ * - `DELETE /api/v1/datasets` (no path segment) deletes **every** dataset the caller can see,
+ *   confirmed by a real call — there is no "delete by name in the body" variant. Deleting one
+ *   dataset requires looking its id up by name via `GET /api/v1/datasets` first, then
+ *   `DELETE /api/v1/datasets/{id}`.
+ */
+export type FetchImpl = typeof fetch;
+export interface CogneeClientOptions {
+    /** Your own Cognee instance — self-hosted (e.g. "http://localhost:8000") or Cognee Cloud. */
+    baseUrl: string;
+    /** Only needed for Cognee Cloud or an auth-enabled self-hosted instance. Sent as
+     * `X-Api-Key: {apiKey}`; omitted entirely for an unauthenticated self-hosted instance. */
+    apiKey?: string;
+    fetchImpl?: FetchImpl;
+}
+export interface CogneeChunk {
+    id?: string;
+    text?: string;
+    score?: number;
+    document_id?: string;
+    document_name?: string;
+    [key: string]: unknown;
+}
+export interface CogneeClient {
+    /** Ingests raw text into the dataset named `datasetName` (Cognee's own "dataset" concept — used
+     * here as the equivalent of `Knowledge`'s `sourceId`). Data added this way isn't searchable until
+     * `cognify()` runs on it. */
+    add(datasetName: string, text: string): Promise<void>;
+    /** Triggers Cognee's entity/relationship extraction pipeline over previously-`add`ed data for
+     * `datasetName`. Must run after `add`, before that data is searchable via `search()`. */
+    cognify(datasetName: string): Promise<void>;
+    /** Semantic search across ingested data, using Cognee's "CHUNKS" search type so results come back
+     * as scored passages rather than an LLM-composed answer. */
+    search(query: string, topK?: number): Promise<CogneeChunk[]>;
+    /** Removes the dataset named `datasetName` entirely. A no-op if no dataset with that name exists
+     * (never falls back to Cognee's bare `DELETE /datasets`, which deletes everything). */
+    removeDataset(datasetName: string): Promise<void>;
+}
+export declare function createCogneeClient(opts: CogneeClientOptions): CogneeClient;

package/dist/client.js

@@ -0,0 +1,117 @@
+/**
+ * A hand-rolled TypeScript REST client for Cognee's real API — no official Node.js/TypeScript SDK
+ * exists (confirmed via real research: Cognee's primary SDK is Python; the REST API is the actual
+ * integration surface for this ecosystem), so this follows the same pattern already proven in
+ * `@wappy_ai/connector-google`'s `oauth.ts` (a plain `fetch`-based client, injectable `fetchImpl` for
+ * testing, no SDK dependency).
+ *
+ * Every request/response shape here was confirmed against a REAL, locally-booted Cognee server
+ * (v1.6.2) — its own live OpenAPI spec (`GET /openapi.json`) plus real `curl` round-trips (register →
+ * login → create an API key → add → cognify → search → delete), not just read from docs. Concretely
+ * confirmed, not assumed:
+ * - `POST /api/v1/add` is `multipart/form-data`, fields `raw_data` (string) + `datasetName` — a JSON
+ *   body is rejected.
+ * - `POST /api/v1/cognify` is JSON `{ datasets: [name] }`.
+ * - `POST /api/v1/search` is JSON `{ query, searchType, topK? }`. `searchType` matters a lot —
+ *   the default (`HYBRID_COMPLETION`) returns an LLM-composed answer, not scored chunks; `"CHUNKS"`
+ *   is what returns a flat array of `{ id, text, score, document_id, document_name, ... }` objects,
+ *   which is the shape this client maps onto `Knowledge`'s `RecalledChunk`.
+ * - Self-hosted auth (when enabled) uses `X-Api-Key: <key>`, NOT `Authorization: Bearer`.
+ * - `DELETE /api/v1/datasets` (no path segment) deletes **every** dataset the caller can see,
+ *   confirmed by a real call — there is no "delete by name in the body" variant. Deleting one
+ *   dataset requires looking its id up by name via `GET /api/v1/datasets` first, then
+ *   `DELETE /api/v1/datasets/{id}`.
+ */
+function jsonHeaders(apiKey) {
+    return {
+        "content-type": "application/json",
+        ...(apiKey ? { "x-api-key": apiKey } : {}),
+    };
+}
+function authHeaders(apiKey) {
+    return apiKey ? { "x-api-key": apiKey } : {};
+}
+async function parseJsonOrThrow(res, action) {
+    const text = await res.text();
+    let json;
+    try {
+        json = text ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new Error(`Cognee API (${action}): non-JSON response (status ${res.status}): ${text.slice(0, 200)}`);
+    }
+    if (!res.ok) {
+        const message = typeof json === "object" && json && "detail" in json ? String(json.detail) : res.statusText;
+        throw new Error(`Cognee API (${action}): ${message} (status ${res.status})`);
+    }
+    return json;
+}
+export function createCogneeClient(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const base = opts.baseUrl.replace(/\/$/, "");
+    async function findDatasetId(name) {
+        const res = await fetchImpl(`${base}/api/v1/datasets`, {
+            method: "GET",
+            headers: authHeaders(opts.apiKey),
+        });
+        const json = await parseJsonOrThrow(res, "findDatasetId");
+        const datasets = Array.isArray(json) ? json : [];
+        return datasets.find((d) => d.name === name)?.id ?? null;
+    }
+    return {
+        async add(datasetName, text) {
+            const form = new FormData();
+            form.append("raw_data", text);
+            form.append("datasetName", datasetName);
+            const res = await fetchImpl(`${base}/api/v1/add`, {
+                method: "POST",
+                headers: authHeaders(opts.apiKey),
+                body: form,
+            });
+            await parseJsonOrThrow(res, "add");
+        },
+        async cognify(datasetName) {
+            const res = await fetchImpl(`${base}/api/v1/cognify`, {
+                method: "POST",
+                headers: jsonHeaders(opts.apiKey),
+                body: JSON.stringify({ datasets: [datasetName], runInBackground: false }),
+            });
+            await parseJsonOrThrow(res, "cognify");
+        },
+        async search(query, topK) {
+            const res = await fetchImpl(`${base}/api/v1/search`, {
+                method: "POST",
+                headers: jsonHeaders(opts.apiKey),
+                body: JSON.stringify({ query, searchType: "CHUNKS", ...(topK !== undefined ? { topK } : {}) }),
+            });
+            const json = await parseJsonOrThrow(res, "search");
+            // Confirmed live, against TWO real server configurations that return genuinely different
+            // shapes for the exact same CHUNKS search: a single-user/no-auth instance
+            // (ENABLE_BACKEND_ACCESS_CONTROL=false) returns a bare array of chunk objects directly; the
+            // default auth-enabled/multi-tenant instance wraps results per dataset instead —
+            // `[{ dataset_id, dataset_name, search_result: [...chunks] }]` — and the default mode is the
+            // one anyone self-hosting without extra config will actually hit. Missing this wrapper meant
+            // every chunk silently vanished (fell through to the "unanticipated shape" fallback) on a real
+            // auth-enabled server, confirmed by comparing the server's own log ("Found 1 chunks from vector
+            // search") against this client returning `[]`. Both shapes are handled here; an empty/no-data
+            // dataset throws a 4xx with a `detail` string instead (handled by parseJsonOrThrow's !res.ok
+            // path above).
+            if (!Array.isArray(json))
+                return [];
+            if (json.length > 0 && typeof json[0] === "object" && json[0] !== null && "search_result" in json[0]) {
+                return json.flatMap((envelope) => (Array.isArray(envelope.search_result) ? envelope.search_result : []));
+            }
+            return json;
+        },
+        async removeDataset(datasetName) {
+            const id = await findDatasetId(datasetName);
+            if (!id)
+                return; // nothing to remove — never falls back to delete-everything
+            const res = await fetchImpl(`${base}/api/v1/datasets/${id}`, {
+                method: "DELETE",
+                headers: authHeaders(opts.apiKey),
+            });
+            await parseJsonOrThrow(res, "removeDataset");
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export declare const packageName = "@wappy_ai/connector-cognee";
+export * from "./client.js";
+export * from "./knowledge.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export const packageName = "@wappy_ai/connector-cognee";
+export * from "./client.js";
+export * from "./knowledge.js";

package/dist/knowledge.d.ts

@@ -0,0 +1,17 @@
+import type { Knowledge } from "@wappy_ai/harness";
+import { type CogneeClientOptions } from "./client.js";
+/**
+ * A real `Knowledge` implementation backed by Cognee instead of `@wappy_ai/harness`'s own local
+ * (LibSQL/BM25) one — same interface, different backend, following the exact "pluggable, no change
+ * to the consuming code" pattern `Knowledge` was already designed for. Cognee's real model (a
+ * self-hosted or cloud knowledge-graph service — extracts entities/relationships, described as
+ * self-correcting over repeated ingests) is a natural fit for this interface's `ingest`/`recall`
+ * shape, unlike `@wappy_ai/core`'s `Memory` (raw per-contact turn history, which this package
+ * deliberately does NOT touch — see the plan this was built from).
+ *
+ * The response mapping below was confirmed against a real, locally-booted Cognee server (ingest a
+ * sentence, cognify it, search for it, read back the exact `{id, text, score, document_id,
+ * document_name}` shape) — see client.ts's own module doc comment for the full confirmed contract.
+ */
+export type CogneeKnowledgeOptions = CogneeClientOptions;
+export declare function createCogneeKnowledge(opts: CogneeKnowledgeOptions): Knowledge;

package/dist/knowledge.js

@@ -0,0 +1,60 @@
+import { createCogneeClient } from "./client.js";
+function toRecalledChunk(index, chunk) {
+    // Confirmed live: a CHUNKS search result carries `document_id`/`document_name`, not the dataset
+    // name it was ingested under — there is no field in the real response that round-trips the
+    // `sourceId` passed to `ingest()`. `document_id` is the closest stable identifier Cognee actually
+    // returns, so it's used here; it won't equal the original `sourceId`, by design, not by bug.
+    const sourceId = typeof chunk.document_id === "string" ? chunk.document_id : "cognee";
+    // Confirmed live, and the opposite of what the field name suggests: Cognee's CHUNKS `score` is a
+    // vector DISTANCE (lower = closer match) — verified by ingesting 3 distinct facts and querying
+    // each; in every case the obviously-correct chunk came back with the LOWEST score, not the
+    // highest. `@wappy_ai/harness`'s own local vector path already normalizes this exact way
+    // (`score: 1 - r.dist`, see its knowledge.ts) — mirrored here so `scoreFloor`/sorting behave the
+    // same (higher = better) regardless of which Knowledge backend is plugged in.
+    const score = typeof chunk.score === "number" ? 1 - chunk.score : 0;
+    return {
+        id: typeof chunk.id === "string" ? chunk.id : `${sourceId}:${index}`,
+        sourceId,
+        text: typeof chunk.text === "string" ? chunk.text : JSON.stringify(chunk),
+        score,
+    };
+}
+export function createCogneeKnowledge(opts) {
+    const client = createCogneeClient(opts);
+    return {
+        // `chunkOptions` (maxChunkChars/overlapChars) has no server-side analog here — Cognee does its
+        // own chunking/extraction as part of `cognify()`, so a caller-specified chunk size can't be
+        // honored. Deliberately ignored, not silently misapplied, and documented here rather than
+        // pretending to support it.
+        async ingest(sourceId, text, chunkOptions) {
+            void chunkOptions; // intentionally unused — see the comment above
+            if (!text.trim())
+                return 0;
+            // `ingest()` REPLACES a source's prior content, it does not accrete alongside it — the same
+            // contract `@wappy_ai/harness`'s own local Knowledge enforces (it deletes a sourceId's old
+            // chunks before inserting new ones). Confirmed live that Cognee itself does NOT do this on its
+            // own: calling add() twice under the same dataset name creates two separate documents, and a
+            // CHUNKS search then returns both the old and new text side by side — e.g. a stale "budget
+            // $2000" chunk kept surfacing alongside a newer "budget $2800" one. So this client removes any
+            // existing dataset for `sourceId` first; `removeDataset` is already a no-op when none exists.
+            await client.removeDataset(sourceId);
+            await client.add(sourceId, text);
+            await client.cognify(sourceId);
+            // Cognee's cognify response doesn't give a confirmed "chunk count" equivalent (see client.ts's
+            // own honest-unknown note) — `1` honestly means "one source successfully ingested," not a
+            // literal chunk count the way the local BM25 implementation's return value is.
+            return 1;
+        },
+        async remove(sourceId) {
+            await client.removeDataset(sourceId);
+        },
+        async recall(query, opts) {
+            const results = await client.search(query, opts?.topK);
+            const scoreFloor = opts?.scoreFloor ?? 0;
+            return results
+                .map((r, i) => toRecalledChunk(i, r))
+                .filter((chunk) => chunk.score > scoreFloor)
+                .sort((a, b) => b.score - a.score);
+        },
+    };
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@wappy_ai/connector-cognee",
+  "version": "0.1.0",
+  "description": "Bring-your-own Cognee (self-hosted or cloud): a real Knowledge/RAG backend for @wappy_ai/harness, backed by Cognee's knowledge-graph API instead of local BM25.",
+  "keywords": [
+    "whatsapp",
+    "ai-agent",
+    "productivity",
+    "cognee",
+    "knowledge-graph",
+    "rag",
+    "typescript"
+  ],
+  "homepage": "https://github.com/csr1010/wappy-kit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/csr1010/wappy-kit.git",
+    "directory": "packages/connector-cognee"
+  },
+  "bugs": "https://github.com/csr1010/wappy-kit/issues",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.1"
+  },
+  "dependencies": {
+    "@wappy_ai/harness": "0.1.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}