@factlayer/adapter-zep 0.6.0

package/README.md

@@ -0,0 +1,23 @@
+# @factlayer/adapter-zep
+
+A [FactLayer](https://github.com/Rubber-Duck-Screaming/factlayer) adapter for [Zep](https://www.getzep.com): pulls a user's graph facts, maps them to FactLayer facts, persists them locally (keyed by Zep's own edge uuid), and checks each one for freshness.
+
+## Install
+
+```bash
+bun add @factlayer/adapter-zep
+```
+
+## Usage
+
+```ts
+import { createZepClient, scanZep } from "@factlayer/adapter-zep";
+
+const client = createZepClient(process.env.ZEP_API_KEY!);
+const results = await scanZep(client, "alice");
+// each result: { fact, result: { status: "fresh" | "needs-verification", ... } }
+```
+
+Zep's bi-temporal fact model can flag an edge as no longer current via `invalidAt` or `expiredAt`. When either is present, this adapter maps it straight to the fact's `expiresAt`, so `check()` reports `needs-verification` immediately -- it never runs the category half-life math on a fact Zep has already flagged as outdated itself.
+
+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 { ZepClient } from "./types.ts";
+export declare function createZepClient(apiKey: string): ZepClient;

package/dist/client.js

@@ -0,0 +1,13 @@
+import { ZepClient as RealZepClient } from "@getzep/zep-cloud";
+// Wraps the real @getzep/zep-cloud ZepClient so it satisfies the minimal
+// ZepClient shape scanZep() depends on. Keeping scan.ts decoupled from the
+// real SDK client is what lets the automated test suite inject a fake
+// client instead of making real network calls (see scan.test.ts). This file
+// is exercised only by a manual smoke test against the live Zep API, not by
+// `bun test`.
+export function createZepClient(apiKey) {
+    const client = new RealZepClient({ apiKey });
+    return {
+        getByUserId: (userId, request) => client.graph.edge.getByUserId(userId, request),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { ZepClient, ZepEntityEdge, ZepGraphEdgesRequest } from "./types.ts";
+export { toFact } from "./mapper";
+export { scanZep } from "./scan";
+export type { ScannedFact } from "./scan.ts";
+export { createZepClient } from "./client";

package/dist/index.js

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

package/dist/mapper.d.ts

@@ -0,0 +1,3 @@
+import type { Fact } from "@factlayer/core";
+import type { ZepEntityEdge } from "./types.ts";
+export declare function toFact(edge: ZepEntityEdge, now?: number): Promise<Fact>;

package/dist/mapper.js

@@ -0,0 +1,41 @@
+import { classify } from "@factlayer/core";
+function toMs(value, fallback) {
+    if (!value)
+        return fallback;
+    const ms = Date.parse(value);
+    return Number.isNaN(ms) ? fallback : ms;
+}
+// Earliest of invalidAt/expiredAt that parses -- either one is Zep's own
+// bi-temporal signal that the fact is no longer current, so whichever fired
+// first is when the fact actually went stale.
+function earliestInvalidation(edge) {
+    const candidates = [edge.invalidAt, edge.expiredAt]
+        .map((value) => (value ? Date.parse(value) : NaN))
+        .filter((ms) => !Number.isNaN(ms));
+    return candidates.length > 0 ? Math.min(...candidates) : null;
+}
+// Converts a Zep entity edge (Zep's unit of stored knowledge -- effectively
+// "the fact") into a factlayer Fact.
+//
+// - storedAt prefers validAt (when the fact became true in the real world)
+//   and falls back to createdAt (when Zep's graph recorded the edge) when
+//   validAt is absent. lastVerifiedAt matches whichever one was used. Zep
+//   has no separate "last verified" concept.
+// - category always comes from classify() on the fact text -- Zep doesn't
+//   expose a comparable freeform category on edges.
+// - When Zep has already flagged the edge via invalidAt or expiredAt (its
+//   own bi-temporal signal that the fact is no longer current), that maps
+//   straight to expiresAt so check() reports needs-verification
+//   immediately, without running the category half-life math at all.
+export async function toFact(edge, now = Date.now()) {
+    const text = edge.fact;
+    const storedAt = toMs(edge.validAt, toMs(edge.createdAt, now));
+    return {
+        id: edge.uuid,
+        text,
+        category: await classify(text),
+        storedAt,
+        lastVerifiedAt: storedAt,
+        expiresAt: earliestInvalidation(edge),
+    };
+}

package/dist/scan.d.ts

@@ -0,0 +1,7 @@
+import type { CheckResult, Fact } from "@factlayer/core";
+import type { ZepClient } from "./types.ts";
+export interface ScannedFact {
+    fact: Fact;
+    result: CheckResult;
+}
+export declare function scanZep(client: ZepClient, userId: string, now?: number): Promise<ScannedFact[]>;

package/dist/scan.js

@@ -0,0 +1,17 @@
+import { addFact, check } from "@factlayer/core";
+import { toFact } from "./mapper";
+// Pulls facts (Zep's "entity edges") for a user via graph.edge.getByUserId()
+// -- a direct listing, not a relevance-ranked search -- maps each to a
+// Fact, persists it locally (upserted via addFact, keyed by Zep's own edge
+// uuid so the two systems share one id space), and runs factlayer's
+// check() on it. Never writes anything back to Zep itself -- only to
+// factlayer's local store, which is what lets mark_verified act on
+// Zep-sourced facts afterward.
+export async function scanZep(client, userId, now = Date.now()) {
+    const edges = await client.getByUserId(userId, {});
+    return Promise.all(edges.map(async (edge) => {
+        const fact = await toFact(edge, now);
+        await addFact(fact);
+        return { fact, result: check(fact, now) };
+    }));
+}

package/dist/types.d.ts

@@ -0,0 +1,15 @@
+export interface ZepEntityEdge {
+    uuid: string;
+    fact: string;
+    createdAt: string;
+    validAt?: string;
+    invalidAt?: string;
+    expiredAt?: string;
+}
+export interface ZepGraphEdgesRequest {
+    cursor?: string;
+    limit?: number;
+}
+export interface ZepClient {
+    getByUserId(userId: string, request: ZepGraphEdgesRequest): Promise<ZepEntityEdge[]>;
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@factlayer/adapter-zep",
+  "version": "0.6.0",
+  "description": "Zep adapter for FactLayer: scans, persists, and checks Zep graph facts for freshness.",
+  "keywords": ["ai", "agent-memory", "llm", "freshness", "zep", "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",
+    "@getzep/zep-cloud": "^3.28.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  }
+}