@contextableai/openclaw-memory-rebac 0.1.0 → 0.1.2

package/backends/graphiti.test.ts

@@ -1,292 +0,0 @@
-import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
-
-vi.mock("node:crypto", async (importOriginal) => {
-  const mod = await importOriginal<typeof import("node:crypto")>();
-  return { ...mod, randomUUID: vi.fn(() => "test-uuid-000") };
-});
-
-import { GraphitiBackend } from "./graphiti.js";
-import type { GraphitiConfig } from "./graphiti.js";
-
-const defaultConfig: GraphitiConfig = {
-  endpoint: "http://localhost:8000",
-  defaultGroupId: "main",
-  uuidPollIntervalMs: 100,
-  uuidPollMaxAttempts: 5,
-  requestTimeoutMs: 5000,
-};
-
-// Mock global fetch
-const mockFetch = vi.fn();
-global.fetch = mockFetch as unknown as typeof fetch;
-
-/** Helper to create a mock JSON response */
-function jsonResponse(body: unknown, status = 200) {
-  return {
-    ok: status >= 200 && status < 300,
-    status,
-    headers: new Map([["content-type", "application/json"]]),
-    json: vi.fn().mockResolvedValue(body),
-    text: vi.fn().mockResolvedValue(JSON.stringify(body)),
-  };
-}
-
-describe("GraphitiBackend", () => {
-  beforeEach(() => {
-    mockFetch.mockReset();
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  test("has correct name", () => {
-    const backend = new GraphitiBackend(defaultConfig);
-    expect(backend.name).toBe("graphiti");
-  });
-
-  describe("store", () => {
-    test("returns StoreResult with fragmentId Promise", async () => {
-      const backend = new GraphitiBackend(defaultConfig);
-
-      // Mock POST /messages (202 Accepted)
-      mockFetch.mockResolvedValueOnce(
-        jsonResponse({ message: "Messages accepted", success: true }, 202),
-      );
-
-      // Mock GET /episodes polling (return episode on first poll)
-      mockFetch.mockResolvedValueOnce(
-        jsonResponse([
-          { uuid: "real-uuid-123", name: "memory_test-uuid-000", group_id: "main", created_at: "2026-03-01" },
-        ]),
-      );
-
-      const result = await backend.store({
-        content: "Test memory",
-        groupId: "main",
-      });
-
-      expect(result.fragmentId).toBeInstanceOf(Promise);
-      const uuid = await result.fragmentId;
-      expect(uuid).toBe("real-uuid-123");
-
-      // Verify POST /messages was called
-      const storeCall = mockFetch.mock.calls[0];
-      expect(storeCall[0]).toBe("http://localhost:8000/messages");
-      const body = JSON.parse(storeCall[1].body as string);
-      expect(body.group_id).toBe("main");
-      expect(body.messages).toHaveLength(1);
-      expect(body.messages[0].content).toBe("Test memory");
-      expect(body.messages[0].uuid).toBeUndefined();
-      expect(body.messages[0].name).toBe("memory_test-uuid-000");
-      expect(body.messages[0].timestamp).toBeDefined();
-    });
-
-    test("passes customPrompt in message content with instructions wrapper", async () => {
-      const backend = new GraphitiBackend(defaultConfig);
-
-      // Mock POST /messages
-      mockFetch.mockResolvedValueOnce(
-        jsonResponse({ message: "Accepted", success: true }, 202),
-      );
-
-      await backend.store({
-        content: "Important fact",
-        groupId: "main",
-        customPrompt: "Extract only names",
-      });
-
-      const storeCall = mockFetch.mock.calls[0];
-      const body = JSON.parse(storeCall[1].body as string);
-      expect(body.messages[0].content).toContain("[Extraction Instructions]");
-      expect(body.messages[0].content).toContain("Extract only names");
-      expect(body.messages[0].content).toContain("[End Instructions]");
-      expect(body.messages[0].content).toContain("Important fact");
-    });
-  });
-
-  describe("searchGroup", () => {
-    test("calls POST /search and returns facts as SearchResult[]", async () => {
-      const backend = new GraphitiBackend(defaultConfig);
-
-      mockFetch.mockResolvedValueOnce(
-        jsonResponse({
-          facts: [
-            {
-              uuid: "f1",
-              name: "WORKS_AT",
-              fact: "Mark works at Acme",
-              valid_at: null,
-              invalid_at: null,
-              created_at: "2026-01-16",
-              expired_at: null,
-            },
-          ],
-        }),
-      );
-
-      const results = await backend.searchGroup({
-        query: "Mark work",
-        groupId: "g1",
-        limit: 10,
-      });
-
-      expect(results).toHaveLength(1);
-      expect(results[0]).toMatchObject({
-        type: "fact",
-        uuid: "f1",
-        group_id: "g1",
-        summary: "Mark works at Acme",
-        context: "WORKS_AT",
-        created_at: "2026-01-16",
-      });
-
-      // Verify POST /search was called with correct body
-      const searchCall = mockFetch.mock.calls[0];
-      expect(searchCall[0]).toBe("http://localhost:8000/search");
-      const body = JSON.parse(searchCall[1].body as string);
-      expect(body.group_ids).toEqual(["g1"]);
-      expect(body.query).toBe("Mark work");
-      expect(body.max_facts).toBe(10);
-    });
-
-    test("returns empty array when no facts found", async () => {
-      const backend = new GraphitiBackend(defaultConfig);
-
-      mockFetch.mockResolvedValueOnce(jsonResponse({ facts: [] }));
-
-      const results = await backend.searchGroup({
-        query: "nothing",
-        groupId: "g1",
-        limit: 10,
-      });
-
-      expect(results).toEqual([]);
-    });
-  });
-
-  describe("healthCheck", () => {
-    test("returns true when /healthcheck responds ok", async () => {
-      const backend = new GraphitiBackend(defaultConfig);
-      mockFetch.mockResolvedValueOnce({ ok: true });
-
-      const healthy = await backend.healthCheck();
-      expect(healthy).toBe(true);
-      expect(mockFetch).toHaveBeenCalledWith(
-        "http://localhost:8000/healthcheck",
-        expect.objectContaining({ signal: expect.any(AbortSignal) }),
-      );
-    });
-
-    test("returns false when /healthcheck fails", async () => {
-      const backend = new GraphitiBackend(defaultConfig);
-      mockFetch.mockResolvedValueOnce({ ok: false });
-
-      const healthy = await backend.healthCheck();
-      expect(healthy).toBe(false);
-    });
-
-    test("returns false when /healthcheck throws", async () => {
-      const backend = new GraphitiBackend(defaultConfig);
-      mockFetch.mockRejectedValueOnce(new Error("Network error"));
-
-      const healthy = await backend.healthCheck();
-      expect(healthy).toBe(false);
-    });
-  });
-
-  describe("getStatus", () => {
-    test("returns status object with backend name and healthy flag", async () => {
-      const backend = new GraphitiBackend(defaultConfig);
-      mockFetch.mockResolvedValueOnce({ ok: true });
-
-      const status = await backend.getStatus();
-      expect(status.backend).toBe("graphiti");
-      expect(status.endpoint).toBe("http://localhost:8000");
-      expect(status.healthy).toBe(true);
-    });
-
-    test("reports unhealthy when health check fails", async () => {
-      const backend = new GraphitiBackend(defaultConfig);
-      mockFetch.mockRejectedValueOnce(new Error("Down"));
-
-      const status = await backend.getStatus();
-      expect(status.healthy).toBe(false);
-    });
-  });
-
-  describe("deleteFragment", () => {
-    test("calls DELETE /episode/{uuid}", async () => {
-      const backend = new GraphitiBackend(defaultConfig);
-
-      mockFetch.mockResolvedValueOnce(
-        jsonResponse({ message: "Deleted", success: true }),
-      );
-
-      const result = await backend.deleteFragment?.("episode-uuid-123");
-      expect(result).toBe(true);
-
-      const deleteCall = mockFetch.mock.calls[0];
-      expect(deleteCall[0]).toBe("http://localhost:8000/episode/episode-uuid-123");
-      expect(deleteCall[1].method).toBe("DELETE");
-    });
-  });
-
-  describe("deleteGroup", () => {
-    test("calls DELETE /group/{groupId}", async () => {
-      const backend = new GraphitiBackend(defaultConfig);
-
-      mockFetch.mockResolvedValueOnce(
-        jsonResponse({ message: "Cleared", success: true }),
-      );
-
-      await backend.deleteGroup("old-group");
-
-      const deleteCall = mockFetch.mock.calls[0];
-      expect(deleteCall[0]).toBe("http://localhost:8000/group/old-group");
-      expect(deleteCall[1].method).toBe("DELETE");
-    });
-  });
-
-  describe("listGroups", () => {
-    test("returns empty array (not implemented)", async () => {
-      const backend = new GraphitiBackend(defaultConfig);
-      const groups = await backend.listGroups();
-      expect(groups).toEqual([]);
-    });
-  });
-
-  describe("getConversationHistory", () => {
-    test("maps getEpisodes to ConversationTurn[]", async () => {
-      const backend = new GraphitiBackend(defaultConfig);
-
-      mockFetch.mockResolvedValueOnce(
-        jsonResponse([
-          { uuid: "e1", name: "Turn 1", content: "User: Hi\nAssistant: Hello", created_at: "2026-01-15" },
-          { uuid: "e2", name: "Turn 2", content: "User: Bye\nAssistant: Goodbye", created_at: "2026-01-16" },
-        ]),
-      );
-
-      const turns = await backend.getConversationHistory("session-123", 10);
-      expect(turns).toHaveLength(2);
-      expect(turns[0]).toMatchObject({
-        query: "Turn 1",
-        answer: "User: Hi\nAssistant: Hello",
-        created_at: "2026-01-15",
-      });
-
-      // Verify GET /episodes/session-session-123 was called
-      const episodesCall = mockFetch.mock.calls[0];
-      expect(episodesCall[0]).toBe("http://localhost:8000/episodes/session-session-123?last_n=10");
-      expect(episodesCall[1].method).toBe("GET");
-    });
-
-    test("returns empty array on error", async () => {
-      const backend = new GraphitiBackend(defaultConfig);
-      mockFetch.mockRejectedValueOnce(new Error("Fail"));
-
-      const turns = await backend.getConversationHistory("session-123");
-      expect(turns).toEqual([]);
-    });
-  });
-});

package/backends/graphiti.ts

@@ -1,345 +0,0 @@
-/**
- * GraphitiBackend — MemoryBackend implementation backed by the Graphiti FastAPI REST server.
- *
- * Graphiti communicates via standard HTTP REST endpoints.
- * Episodes are processed asynchronously by Graphiti's LLM pipeline;
- * the real server-side UUID is discovered by polling GET /episodes/{group_id}.
- *
- * store() returns immediately; fragmentId resolves once Graphiti finishes
- * processing and the UUID becomes visible in the episodes list.
- */
-
-import { randomUUID } from "node:crypto";
-import type { Command } from "commander";
-import type {
-  MemoryBackend,
-  SearchResult,
-  StoreResult,
-  ConversationTurn,
-  BackendDataset,
-} from "../backend.js";
-
-// ============================================================================
-// Types (Graphiti REST API)
-// ============================================================================
-
-/** Matches the server's Message schema (from /openapi.json). */
-type GraphitiMessage = {
-  content: string;
-  role_type: "user" | "assistant" | "system";
-  role: string | null;
-  name?: string;
-  timestamp?: string;
-  source_description?: string;
-};
-
-type AddMessagesRequest = {
-  group_id: string;
-  messages: GraphitiMessage[];
-};
-
-type GraphitiEpisode = {
-  uuid: string;
-  name: string;
-  content: string;
-  source_description: string;
-  group_id: string;
-  created_at: string;
-};
-
-type FactResult = {
-  uuid: string;
-  name: string;
-  fact: string;
-  valid_at: string | null;
-  invalid_at: string | null;
-  created_at: string;
-  expired_at: string | null;
-};
-
-type SearchRequest = {
-  group_ids: string[];
-  query: string;
-  max_facts?: number;
-};
-
-type SearchResults = {
-  facts: FactResult[];
-};
-
-type GraphitiResult = {
-  message: string;
-  success: boolean;
-};
-
-// ============================================================================
-// GraphitiBackend
-// ============================================================================
-
-export type GraphitiConfig = {
-  endpoint: string;
-  defaultGroupId: string;
-  uuidPollIntervalMs: number;
-  uuidPollMaxAttempts: number;
-  requestTimeoutMs?: number;
-  customInstructions: string;
-};
-
-export class GraphitiBackend implements MemoryBackend {
-  readonly name = "graphiti";
-
-  readonly uuidPollIntervalMs: number;
-  readonly uuidPollMaxAttempts: number;
-  private readonly requestTimeoutMs: number;
-
-  constructor(private readonly config: GraphitiConfig) {
-    this.uuidPollIntervalMs = config.uuidPollIntervalMs;
-    this.uuidPollMaxAttempts = config.uuidPollMaxAttempts;
-    this.requestTimeoutMs = config.requestTimeoutMs ?? 30000;
-  }
-
-  // --------------------------------------------------------------------------
-  // REST transport
-  // --------------------------------------------------------------------------
-
-  private async restCall<T>(
-    method: "GET" | "POST" | "DELETE",
-    path: string,
-    body?: unknown,
-  ): Promise<T> {
-    const url = `${this.config.endpoint}${path}`;
-    const opts: RequestInit = {
-      method,
-      headers: { "Content-Type": "application/json" },
-      signal: AbortSignal.timeout(this.requestTimeoutMs),
-    };
-    if (body !== undefined) {
-      opts.body = JSON.stringify(body);
-    }
-    const response = await fetch(url, opts);
-    if (!response.ok) {
-      const text = await response.text().catch(() => "");
-      throw new Error(`Graphiti REST ${method} ${path} failed: ${response.status} ${text}`);
-    }
-    const ct = response.headers.get("content-type") ?? "";
-    if (ct.includes("application/json")) {
-      return (await response.json()) as T;
-    }
-    return {} as T;
-  }
-
-  // --------------------------------------------------------------------------
-  // MemoryBackend implementation
-  // --------------------------------------------------------------------------
-
-  async store(params: {
-    content: string;
-    groupId: string;
-    sourceDescription?: string;
-    customPrompt?: string;
-  }): Promise<StoreResult> {
-    const episodeName = `memory_${randomUUID()}`;
-    let effectiveBody = params.content;
-    if (params.customPrompt) {
-      effectiveBody = `[Extraction Instructions]\n${params.customPrompt}\n[End Instructions]\n\n${params.content}`;
-    }
-
-    const request: AddMessagesRequest = {
-      group_id: params.groupId,
-      messages: [
-        {
-          name: episodeName,
-          content: effectiveBody,
-          timestamp: new Date().toISOString(),
-          role_type: "user",
-          role: "user",
-          source_description: params.sourceDescription,
-        },
-      ],
-    };
-
-    await this.restCall<GraphitiResult>("POST", "/messages", request);
-
-    // POST /messages returns 202 (async processing).
-    // Poll GET /episodes until the episode appears, then return its real UUID.
-    const fragmentId = this.resolveEpisodeUuid(episodeName, params.groupId);
-    fragmentId.catch(() => {}); // Prevent unhandled rejection if caller drops it
-
-    return { fragmentId };
-  }
-
-  private async resolveEpisodeUuid(name: string, groupId: string): Promise<string> {
-    for (let i = 0; i < this.uuidPollMaxAttempts; i++) {
-      await new Promise((r) => setTimeout(r, this.uuidPollIntervalMs));
-      try {
-        const episodes = await this.getEpisodes(groupId, 50);
-        const match = episodes.find((ep) => ep.name === name);
-        if (match) return match.uuid;
-      } catch {
-        // Transient error — keep polling
-      }
-    }
-    throw new Error(`Timed out resolving episode UUID for "${name}" in group "${groupId}"`);
-  }
-
-  async searchGroup(params: {
-    query: string;
-    groupId: string;
-    limit: number;
-    sessionId?: string;
-  }): Promise<SearchResult[]> {
-    const { query, groupId, limit } = params;
-
-    const searchRequest: SearchRequest = {
-      group_ids: [groupId],
-      query,
-      max_facts: limit,
-    };
-
-    const response = await this.restCall<SearchResults>("POST", "/search", searchRequest);
-    const facts = response.facts ?? [];
-
-    return facts.map((f) => ({
-      type: "fact" as const,
-      uuid: f.uuid,
-      group_id: groupId,
-      summary: f.fact,
-      context: f.name,
-      created_at: f.created_at,
-    }));
-  }
-
-  async getConversationHistory(sessionId: string, lastN = 10): Promise<ConversationTurn[]> {
-    const sessionGroup = `session-${sessionId.replace(/[^a-zA-Z0-9_-]/g, "-")}`;
-    try {
-      const episodes = await this.getEpisodes(sessionGroup, lastN);
-      return episodes.map((ep) => ({
-        query: ep.name,
-        answer: ep.content,
-        created_at: ep.created_at,
-      }));
-    } catch {
-      return [];
-    }
-  }
-
-  async healthCheck(): Promise<boolean> {
-    try {
-      const response = await fetch(`${this.config.endpoint}/healthcheck`, {
-        signal: AbortSignal.timeout(5000),
-      });
-      return response.ok;
-    } catch {
-      return false;
-    }
-  }
-
-  async getStatus(): Promise<Record<string, unknown>> {
-    return {
-      backend: "graphiti",
-      endpoint: this.config.endpoint,
-      healthy: await this.healthCheck(),
-    };
-  }
-
-  async deleteGroup(groupId: string): Promise<void> {
-    await this.restCall<GraphitiResult>(
-      "DELETE",
-      `/group/${encodeURIComponent(groupId)}`,
-    );
-  }
-
-  async listGroups(): Promise<BackendDataset[]> {
-    // Graphiti has no list-groups API; the CLI can query SpiceDB for this
-    return [];
-  }
-
-  async deleteFragment(uuid: string): Promise<boolean> {
-    await this.restCall<GraphitiResult>(
-      "DELETE",
-      `/episode/${encodeURIComponent(uuid)}`,
-    );
-    return true;
-  }
-
-  // --------------------------------------------------------------------------
-  // Graphiti-specific helpers (used by CLI commands and UUID polling)
-  // --------------------------------------------------------------------------
-
-  async getEpisodes(groupId: string, lastN: number): Promise<GraphitiEpisode[]> {
-    return this.restCall<GraphitiEpisode[]>(
-      "GET",
-      `/episodes/${encodeURIComponent(groupId)}?last_n=${lastN}`,
-    );
-  }
-
-  async getEntityEdge(uuid: string): Promise<FactResult> {
-    return this.restCall<FactResult>(
-      "GET",
-      `/entity-edge/${encodeURIComponent(uuid)}`,
-    );
-  }
-
-  // --------------------------------------------------------------------------
-  // Backend-specific CLI commands
-  // --------------------------------------------------------------------------
-
-  registerCliCommands(cmd: Command): void {
-    cmd
-      .command("episodes")
-      .description("[graphiti] List recent episodes for a group")
-      .option("--last <n>", "Number of episodes", "10")
-      .option("--group <id>", "Group ID")
-      .action(async (opts: { last: string; group?: string }) => {
-        const groupId = opts.group ?? this.config.defaultGroupId;
-        const episodes = await this.getEpisodes(groupId, parseInt(opts.last));
-        console.log(JSON.stringify(episodes, null, 2));
-      });
-
-    cmd
-      .command("fact")
-      .description("[graphiti] Get a specific fact (entity edge) by UUID")
-      .argument("<uuid>", "Fact UUID")
-      .action(async (uuid: string) => {
-        try {
-          const fact = await this.getEntityEdge(uuid);
-          console.log(JSON.stringify(fact, null, 2));
-        } catch (err) {
-          console.error(`Failed to get fact: ${err instanceof Error ? err.message : String(err)}`);
-        }
-      });
-
-    cmd
-      .command("clear-graph")
-      .description("[graphiti] Clear graph data for a group (destructive!)")
-      .option("--group <id...>", "Group ID(s)")
-      .option("--confirm", "Required safety flag", false)
-      .action(async (opts: { group?: string[]; confirm: boolean }) => {
-        if (!opts.confirm) {
-          console.log("Destructive operation. Pass --confirm to proceed.");
-          return;
-        }
-        const groups = opts.group ?? [];
-        if (groups.length === 0) {
-          console.log("No groups specified. Use --group <id> to specify groups.");
-          return;
-        }
-        for (const g of groups) {
-          await this.deleteGroup(g);
-          console.log(`Cleared group: ${g}`);
-        }
-      });
-  }
-}
-
-// ============================================================================
-// Backend module exports (used by backends/registry.ts)
-// ============================================================================
-
-import graphitiDefaults from "./graphiti.defaults.json" with { type: "json" };
-
-export const defaults: Record<string, unknown> = graphitiDefaults;
-
-export function create(config: Record<string, unknown>): MemoryBackend {
-  return new GraphitiBackend(config as GraphitiConfig);
-}

package/backends/registry.ts

@@ -1,36 +0,0 @@
-/**
- * Backend registry — loaded dynamically from backends.json.
- *
- * Call initRegistry() once (e.g. at the start of register()) before using
- * backendRegistry or createBackend(). No backend names appear in this file.
- *
- * To add a new backend:
- *   1. Create backends/<name>.ts  (exports `defaults` and `create`)
- *   2. Create backends/<name>.defaults.json
- *   3. Add `"<name>": "./<name>.js"` to backends/backends.json
- *   No TypeScript changes needed anywhere else.
- */
-
-import backendsJson from "./backends.json" with { type: "json" };
-import type { MemoryBackend } from "../backend.js";
-
-export type BackendModule = {
-  create: (config: Record<string, unknown>) => MemoryBackend;
-  defaults: Record<string, unknown>;
-};
-
-// Mutable backing store — populated by initRegistry().
-// backendRegistry is a live reference to the same object.
-const _registry: Record<string, BackendModule> = {};
-
-export async function initRegistry(): Promise<void> {
-  if (Object.keys(_registry).length > 0) return;
-  for (const [name, modulePath] of Object.entries(backendsJson as Record<string, string>)) {
-    const url = new URL(modulePath, import.meta.url);
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const mod = await import(url.href) as any;
-    _registry[name] = mod as BackendModule;
-  }
-}
-
-export const backendRegistry: Readonly<Record<string, BackendModule>> = _registry;