@factlayer/adapter-cognee 0.7.0

package/README.md

@@ -0,0 +1,31 @@
+# @factlayer/adapter-cognee
+
+A [FactLayer](https://github.com/Rubber-Duck-Screaming/factlayer) adapter for [Cognee](https://www.cognee.ai): pulls a dataset's ingested source records, maps them to FactLayer facts, persists them locally (keyed by Cognee's own data id), and checks each one for freshness.
+
+Cognee is different from Mem0 and Zep in one important way: it's self-hosted, not a hosted service you just read from. *You* run the Cognee instance and configure your own LLM provider (any OpenAI-compatible endpoint) to do the ingestion and knowledge-graph extraction. This adapter doesn't provide an LLM and doesn't run extraction itself — it only reads records you've already fed into your own Cognee instance, tracking the freshness of that ingested source material.
+
+## Install
+
+```bash
+bun add @factlayer/adapter-cognee
+```
+
+## Usage
+
+```ts
+import { createCogneeClient, scanCognee } from "@factlayer/adapter-cognee";
+
+const client = await createCogneeClient({
+  llmModel: "your-model-id",
+  llmApiKey: process.env.YOUR_LLM_KEY,
+  // llmEndpoint: process.env.YOUR_LLM_ENDPOINT, // only needed for a non-OpenAI, OpenAI-compatible provider
+});
+
+// datasetId is Cognee's own dataset UUID, not the dataset name you passed
+// to Cognee's add()/remember() calls -- look it up via the underlying
+// @cognee/cognee-ts SDK's datasets.list() if you only have the name.
+const results = await scanCognee(client, datasetId);
+// each result: { fact, result: { status: "fresh" | "needs-verification", ... } }
+```
+
+See the [main repo](https://github.com/Rubber-Duck-Screaming/factlayer) for the full architecture, the freshness model, and how this adapter fits alongside `@factlayer/core`, `@factlayer/cli`, and `@factlayer/mcp-server`.

package/dist/client.d.ts

@@ -0,0 +1,2 @@
+import type { CogneeClient } from "./types.ts";
+export declare function createCogneeClient(settings?: object | string): Promise<CogneeClient>;

package/dist/client.js

@@ -0,0 +1,32 @@
+import { Cognee, init } from "@cognee/cognee-ts";
+let initialized = false;
+// Boots the Rust async runtime that every Cognee pipeline call depends on
+// (Cognee's own usage notes call this out as required once per process,
+// before any async op). Guarded here rather than left to callers, so
+// createCogneeClient can be called more than once -- e.g. once per scan --
+// without re-initializing the runtime.
+function ensureInit() {
+    if (!initialized) {
+        init();
+        initialized = true;
+    }
+}
+// Wraps the real @cognee/cognee-ts Cognee class so it satisfies the minimal
+// CogneeClient shape scanCognee() depends on. Keeping scan.ts decoupled
+// from the real SDK class is what lets the automated test suite inject a
+// fake client instead of making real (LLM/embedding-backed) calls (see
+// scan.test.ts). This file is exercised only by a manual smoke test
+// against a real Cognee instance, not by `bun test`.
+//
+// Async (unlike adapter-mem0/adapter-zep's sync client factories) because
+// Cognee's own docs require warm() -- which builds the embedding/LLM
+// engines and resolves the default user -- to run once after construction
+// and before any other call.
+export async function createCogneeClient(settings) {
+    ensureInit();
+    const client = new Cognee(settings);
+    await client.warm();
+    return {
+        listData: (datasetId) => client.datasets.listData(datasetId),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { CogneeClient, CogneeDataRecord } from "./types.ts";
+export { toFact } from "./mapper";
+export type { CogneeFact } from "./mapper.ts";
+export { scanCognee } from "./scan";
+export type { ScannedFact } from "./scan.ts";
+export { createCogneeClient } from "./client";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { toFact } from "./mapper";
+export { scanCognee } from "./scan";
+export { createCogneeClient } from "./client";

package/dist/mapper.d.ts

@@ -0,0 +1,6 @@
+import type { Fact } from "@factlayer/core";
+import type { CogneeDataRecord } from "./types.ts";
+export interface CogneeFact extends Fact {
+    importanceWeight?: number | null;
+}
+export declare function toFact(record: CogneeDataRecord, now?: number): Promise<CogneeFact>;

package/dist/mapper.js

@@ -0,0 +1,83 @@
+// Design note: Cognee's search()/recall() -- its extracted knowledge-graph
+// facts -- carry no timestamp fields in @cognee/cognee-ts's current types
+// (CogneeSearchItem is just `{ id, score, payload }`; CogneeRecallItem is
+// just `{ source, content, score }`), making them unusable as a freshness
+// source. This adapter instead uses datasets.listData(datasetId), which
+// returns pre-extraction raw ingested records (CogneeDataRecord) that do
+// carry real timestamps. This means the Cognee adapter tracks freshness of
+// ingested source material, not extracted graph facts -- a real scope
+// difference from adapter-mem0 and adapter-zep, documented here rather
+// than hidden.
+//
+// A second consequence of that same choice: CogneeDataRecord has no inline
+// text-content field. `name` looked like a plausible stand-in at first, but
+// live output against a real Cognee instance confirmed it's actually an
+// internal hash-based filename (e.g.
+// "text_b746e53fca48a4c932a25ac28fbdb0c2"), not the fact's content -- using
+// it as `text` would have made the adapter report gibberish instead of
+// facts. The real content lives at `raw_data_location`, a `file://` URI
+// pointing at a local file on disk, so toFact() reads that file directly.
+//
+// Assumption, not a guarantee: this only works when the FactLayer process
+// can read Cognee's local storage on the same filesystem -- true for our
+// current self-hosted setup (both run on one machine), but it would break
+// if Cognee and FactLayer ever ran on separate machines without a shared
+// mount. Documented here rather than silently assumed.
+import { readFile } from "node:fs/promises";
+import { classify } from "@factlayer/core";
+const FILE_URI_PREFIX = "file://";
+// Cognee's raw_data_location is a `file://` URI, but on Windows the path
+// after the scheme keeps its native backslashes instead of being
+// forward-slash-encoded like a spec-compliant file URI would be (a real
+// one is "file:///C:/Users/...", three slashes, forward-slash-separated;
+// Cognee's own output is "file://C:\\Users\\...\\text_....txt", two
+// slashes, backslash-separated). Parsing that with `new URL()` /
+// `fileURLToPath()` would treat "C:" as the URL's host and silently drop
+// it from the resulting path, corrupting the drive letter. So this strips
+// the "file://" prefix as a plain string instead of URL-parsing it, and
+// hands the remainder to fs as-is -- Node's fs accepts either slash
+// direction on Windows.
+function fileUriToPath(uri) {
+    return uri.startsWith(FILE_URI_PREFIX) ? uri.slice(FILE_URI_PREFIX.length) : uri;
+}
+function toMs(value, fallback) {
+    if (!value)
+        return fallback;
+    const ms = Date.parse(value);
+    return Number.isNaN(ms) ? fallback : ms;
+}
+// Converts a Cognee data record (a pre-extraction ingested item, not an
+// extracted graph fact -- see the module comment above) into a factlayer
+// Fact.
+//
+// - storedAt comes from created_at (when the item was ingested).
+// - lastVerifiedAt comes from updated_at, falling back to created_at when
+//   updated_at is null. Deliberately NOT last_accessed: that field is an
+//   access-frequency signal (how often Cognee's own code read the record),
+//   not a truth-verification signal -- treating "read recently" as "still
+//   true" is exactly the mistake factlayer exists to catch.
+// - text is read from the file at raw_data_location (see the module
+//   comment above for why, and the same-filesystem assumption this
+//   depends on) -- NOT record.name, which is an internal hash-based
+//   filename, not fact content.
+// - category always comes from classify() on that file content -- Cognee
+//   doesn't expose a comparable freeform category on data records.
+// - expiresAt is always null: CogneeDataRecord has no expiration-style
+//   field, so check() always falls through to the category half-life math.
+// - importanceWeight passes through record.importance_weight as-is
+//   (undocumented and nullable in Cognee's own types) for callers who want
+//   it, without factoring into check() at all.
+export async function toFact(record, now = Date.now()) {
+    const text = (await readFile(fileUriToPath(record.raw_data_location), "utf-8")).trim();
+    const storedAt = toMs(record.created_at, now);
+    const lastVerifiedAt = toMs(record.updated_at, storedAt);
+    return {
+        id: record.id,
+        text,
+        category: await classify(text),
+        storedAt,
+        lastVerifiedAt,
+        expiresAt: null,
+        importanceWeight: record.importance_weight,
+    };
+}

package/dist/scan.d.ts

@@ -0,0 +1,8 @@
+import type { CheckResult } from "@factlayer/core";
+import type { CogneeFact } from "./mapper.ts";
+import type { CogneeClient } from "./types.ts";
+export interface ScannedFact {
+    fact: CogneeFact;
+    result: CheckResult;
+}
+export declare function scanCognee(client: CogneeClient, datasetId: string, now?: number): Promise<ScannedFact[]>;

package/dist/scan.js

@@ -0,0 +1,17 @@
+import { addFact, check } from "@factlayer/core";
+import { toFact } from "./mapper";
+// Pulls raw ingested records for a dataset via datasets.listData() -- see
+// mapper.ts's design note for why this is source material, not extracted
+// graph facts -- maps each to a Fact, persists it locally (upserted via
+// addFact, keyed by Cognee's own data id so the two systems share one id
+// space), and runs factlayer's check() on it. Never writes anything back to
+// Cognee itself -- only to factlayer's local store, which is what lets
+// mark_verified act on Cognee-sourced facts afterward.
+export async function scanCognee(client, datasetId, now = Date.now()) {
+    const records = await client.listData(datasetId);
+    return Promise.all(records.map(async (record) => {
+        const fact = await toFact(record, now);
+        await addFact(fact);
+        return { fact, result: check(fact, now) };
+    }));
+}

package/dist/types.d.ts

@@ -0,0 +1,12 @@
+export interface CogneeDataRecord {
+    id: string;
+    name: string;
+    raw_data_location: string;
+    created_at: string;
+    updated_at: string | null;
+    last_accessed: string | null;
+    importance_weight: number | null;
+}
+export interface CogneeClient {
+    listData(datasetId: string): Promise<CogneeDataRecord[]>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@factlayer/adapter-cognee",
+  "version": "0.7.0",
+  "description": "Cognee adapter for FactLayer: scans, persists, and checks freshness of Cognee-ingested source records.",
+  "keywords": ["ai", "agent-memory", "llm", "freshness", "cognee", "factlayer"],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test",
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "bun run ../../scripts/check-publish-ready.ts"
+  },
+  "dependencies": {
+    "@factlayer/core": "0.6.0",
+    "@cognee/cognee-ts": "^0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  }
+}