@contextableai/openclaw-memory-graphiti 0.1.1 → 0.2.0

package/README.md

@@ -1,4 +1,4 @@
-# @openclaw/memory-graphiti
+# @contextableai/openclaw-memory-graphiti
 
 Two-layer memory plugin for OpenClaw: **SpiceDB** for authorization, **Graphiti** for knowledge graph storage.
 
@@ -30,7 +30,21 @@ Agents remember conversations as structured entities and facts in a knowledge gr
 
 **SpiceDB** determines which `group_id`s a subject (agent or person) can access, then **Graphiti** searches or stores memories scoped to those groups.
 
-## Quick Start
+## Installation
+
+```bash
+openclaw plugins install @contextableai/openclaw-memory-graphiti
+```
+
+Or with npm:
+
+```bash
+npm install @contextableai/openclaw-memory-graphiti
+```
+
+Then restart the gateway. On first start, the plugin automatically:
+- Writes the SpiceDB authorization schema (if not already present)
+- Creates group membership for the configured agent in the default group
 
 ### Prerequisites
 
@@ -43,45 +57,26 @@ Agents remember conversations as structured entities and facts in a knowledge gr
 cd docker
 cp .env.example .env
 # Edit .env — set OPENAI_API_KEY at minimum
-docker compose up -d falkordb graphiti-mcp spicedb
+docker compose up -d
 ```
 
 This starts:
 - **FalkorDB** on port 6379 (graph database, web UI on port 3000)
 - **Graphiti MCP Server** on port 8000 (knowledge graph API)
+- **PostgreSQL** on port 5432 (persistent datastore for SpiceDB)
 - **SpiceDB** on port 50051 (authorization engine)
 
-### 2. Configure the Plugin
-
-Add to your OpenClaw plugin configuration:
-
-```json
-{
-  "spicedb": {
-    "endpoint": "localhost:50051",
-    "token": "dev_token",
-    "insecure": true
-  },
-  "graphiti": {
-    "endpoint": "http://localhost:8000",
-    "defaultGroupId": "main"
-  },
-  "subjectId": "my-agent"
-}
-```
-
-### 3. Initialize SpiceDB Schema
+### 2. Restart the Gateway
 
 ```bash
-openclaw graphiti-mem schema-write
+openclaw gateway restart
 ```
 
-### 4. Add Group Membership
+The plugin auto-initializes on startup — no manual `schema-write` or `add-member` needed for basic use. The SpiceDB schema is written automatically on first run, and the configured `subjectId` is added to the `defaultGroupId`.
 
-```bash
-# Add the agent to a group
-openclaw graphiti-mem add-member main my-agent --type agent
+### 3. (Optional) Add More Group Members
 
+```bash
 # Add people to groups
 openclaw graphiti-mem add-member family mom --type person
 openclaw graphiti-mem add-member family dad --type person
@@ -258,6 +253,56 @@ All commands are under `graphiti-mem`:
 | `graphiti-mem add-member <group-id> <subject-id>` | Add a subject to a group. Options: `--type` |
 | `graphiti-mem import` | Import workspace markdown files into Graphiti. Options: `--workspace`, `--include-sessions`, `--session-dir`, `--group`, `--dry-run` |
 
+### Standalone CLI
+
+For development and testing, commands can be run directly without a full OpenClaw gateway:
+
+```bash
+# Via npm script
+npm run cli -- status
+npm run cli -- search "some query"
+npm run cli -- import --workspace /path/to/files --dry-run
+
+# Via npx
+npx tsx bin/graphiti-mem.ts cleanup --dry-run
+```
+
+**Configuration** is loaded from (highest priority first):
+
+1. **Environment variables** — `SPICEDB_TOKEN`, `SPICEDB_ENDPOINT`, `GRAPHITI_ENDPOINT`, or prefixed variants (`GRAPHITI_MEM_SPICEDB_TOKEN`, etc.)
+2. **JSON config file** — `--config <path>`, or auto-discovered from `./graphiti-mem.config.json` or `~/.config/graphiti-mem/config.json`
+3. **Built-in defaults** (see [Configuration Reference](#configuration-reference))
+
+Example config file (`graphiti-mem.config.json`):
+
+```json
+{
+  "spicedb": {
+    "endpoint": "localhost:50051",
+    "token": "dev_token",
+    "insecure": true
+  },
+  "graphiti": {
+    "endpoint": "http://localhost:8000",
+    "defaultGroupId": "main"
+  },
+  "subjectType": "agent",
+  "subjectId": "my-agent"
+}
+```
+
+| Environment Variable | Config Equivalent |
+|---------------------|-------------------|
+| `SPICEDB_TOKEN` | `spicedb.token` |
+| `SPICEDB_ENDPOINT` | `spicedb.endpoint` |
+| `GRAPHITI_ENDPOINT` | `graphiti.endpoint` |
+| `GRAPHITI_MEM_SPICEDB_INSECURE` | `spicedb.insecure` |
+| `GRAPHITI_MEM_DEFAULT_GROUP_ID` | `graphiti.defaultGroupId` |
+| `GRAPHITI_MEM_SUBJECT_TYPE` | `subjectType` |
+| `GRAPHITI_MEM_SUBJECT_ID` | `subjectId` |
+
+The plugin-registered CLI (`openclaw graphiti-mem ...`) remains the primary interface for end users. The standalone CLI is a developer convenience.
+
 ## Docker Compose
 
 The `docker/` directory contains a full-stack Docker Compose configuration:
@@ -271,16 +316,16 @@ The `docker/` directory contains a full-stack Docker Compose configuration:
 | `spicedb` | 50051, 8443, 9090 | Authorization engine (gRPC, HTTP, metrics) |
 | `openclaw-gateway` | 18789, 18790 | OpenClaw gateway (optional) |
 
-### Infrastructure Only
+### Infrastructure (default)
 
 ```bash
-docker compose up -d falkordb graphiti-mcp postgres spicedb-migrate spicedb
+docker compose up -d
 ```
 
-### Full Stack (Gateway + Infrastructure)
+### With OpenClaw Gateway
 
 ```bash
-docker compose up -d
+docker compose --profile gateway up -d
 ```
 
 When running inside Docker Compose, use service hostnames in the plugin config:
@@ -399,6 +444,7 @@ OPENCLAW_LIVE_TEST=1 npm run test:e2e
 
 ```
 ├── index.ts                  # Plugin entry: tools, hooks, CLI, service
+├── cli.ts                    # Shared CLI commands (used by plugin + standalone)
 ├── config.ts                 # Config schema and validation
 ├── graphiti.ts               # Graphiti MCP HTTP client (JSON-RPC/SSE)
 ├── spicedb.ts                # SpiceDB gRPC client wrapper
@@ -407,6 +453,8 @@ OPENCLAW_LIVE_TEST=1 npm run test:e2e
 ├── schema.zed                # SpiceDB authorization schema
 ├── openclaw.plugin.json      # Plugin manifest
 ├── package.json
+├── bin/
+│   └── graphiti-mem.ts       # Standalone CLI entry point
 ├── docker/
 │   ├── docker-compose.yml    # Full infrastructure stack
 │   └── .env.example          # Environment variable template
@@ -416,6 +464,7 @@ OPENCLAW_LIVE_TEST=1 npm run test:e2e
 │   ├── dev-stop.sh           # Stop dev services
 │   └── dev-status.sh         # Check service status
 ├── index.test.ts             # Plugin integration tests
+├── cli.test.ts               # CLI module tests
 ├── authorization.test.ts     # Authorization unit tests
 ├── search.test.ts            # Search unit tests
 ├── graphiti.test.ts          # Graphiti client tests

package/authorization.ts

@@ -7,7 +7,7 @@
  * - Checking delete permissions
  */
 
-import type { SpiceDbClient, RelationshipTuple } from "./spicedb.js";
+import type { SpiceDbClient, RelationshipTuple, ConsistencyMode } from "./spicedb.js";
 
 // ============================================================================
 // Types
@@ -25,6 +25,14 @@ export type FragmentRelationships = {
   involves?: Subject[];
 };
 
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function tokenConsistency(zedToken?: string): ConsistencyMode | undefined {
+  return zedToken ? { mode: "at_least_as_fresh", token: zedToken } : undefined;
+}
+
 // ============================================================================
 // Authorization Operations
 // ============================================================================
@@ -36,12 +44,14 @@ export type FragmentRelationships = {
 export async function lookupAuthorizedGroups(
   spicedb: SpiceDbClient,
   subject: Subject,
+  zedToken?: string,
 ): Promise<string[]> {
   return spicedb.lookupResources({
     resourceType: "group",
     permission: "access",
     subjectType: subject.type,
     subjectId: subject.id,
+    consistency: tokenConsistency(zedToken),
   });
 }
 
@@ -52,12 +62,14 @@ export async function lookupAuthorizedGroups(
 export async function lookupViewableFragments(
   spicedb: SpiceDbClient,
   subject: Subject,
+  zedToken?: string,
 ): Promise<string[]> {
   return spicedb.lookupResources({
     resourceType: "memory_fragment",
     permission: "view",
     subjectType: subject.type,
     subjectId: subject.id,
+    consistency: tokenConsistency(zedToken),
   });
 }
 
@@ -72,7 +84,7 @@ export async function lookupViewableFragments(
 export async function writeFragmentRelationships(
   spicedb: SpiceDbClient,
   params: FragmentRelationships,
-): Promise<void> {
+): Promise<string | undefined> {
   const tuples: RelationshipTuple[] = [
     {
       resourceType: "memory_fragment",
@@ -102,48 +114,21 @@ export async function writeFragmentRelationships(
     }
   }
 
-  await spicedb.writeRelationships(tuples);
+  return spicedb.writeRelationships(tuples);
 }
 
 /**
  * Remove all authorization relationships for a memory fragment.
- * Called when deleting a memory.
+ * Uses filter-based deletion — no need to know the group, sharer, or involved parties.
  */
 export async function deleteFragmentRelationships(
   spicedb: SpiceDbClient,
   fragmentId: string,
-  params: FragmentRelationships,
-): Promise<void> {
-  const tuples: RelationshipTuple[] = [
-    {
-      resourceType: "memory_fragment",
-      resourceId: fragmentId,
-      relation: "source_group",
-      subjectType: "group",
-      subjectId: params.groupId,
-    },
-    {
-      resourceType: "memory_fragment",
-      resourceId: fragmentId,
-      relation: "shared_by",
-      subjectType: params.sharedBy.type,
-      subjectId: params.sharedBy.id,
-    },
-  ];
-
-  if (params.involves) {
-    for (const person of params.involves) {
-      tuples.push({
-        resourceType: "memory_fragment",
-        resourceId: fragmentId,
-        relation: "involves",
-        subjectType: person.type,
-        subjectId: person.id,
-      });
-    }
-  }
-
-  await spicedb.deleteRelationships(tuples);
+): Promise<string | undefined> {
+  return spicedb.deleteRelationshipsByFilter({
+    resourceType: "memory_fragment",
+    resourceId: fragmentId,
+  });
 }
 
 /**
@@ -153,6 +138,7 @@ export async function canDeleteFragment(
   spicedb: SpiceDbClient,
   subject: Subject,
   fragmentId: string,
+  zedToken?: string,
 ): Promise<boolean> {
   return spicedb.checkPermission({
     resourceType: "memory_fragment",
@@ -160,6 +146,7 @@ export async function canDeleteFragment(
     permission: "delete",
     subjectType: subject.type,
     subjectId: subject.id,
+    consistency: tokenConsistency(zedToken),
   });
 }
 
@@ -171,6 +158,7 @@ export async function canWriteToGroup(
   spicedb: SpiceDbClient,
   subject: Subject,
   groupId: string,
+  zedToken?: string,
 ): Promise<boolean> {
   return spicedb.checkPermission({
     resourceType: "group",
@@ -178,6 +166,7 @@ export async function canWriteToGroup(
     permission: "contribute",
     subjectType: subject.type,
     subjectId: subject.id,
+    consistency: tokenConsistency(zedToken),
   });
 }
 
@@ -189,8 +178,8 @@ export async function ensureGroupMembership(
   spicedb: SpiceDbClient,
   groupId: string,
   member: Subject,
-): Promise<void> {
-  await spicedb.writeRelationships([
+): Promise<string | undefined> {
+  return spicedb.writeRelationships([
     {
       resourceType: "group",
       resourceId: groupId,

package/bin/graphiti-mem.ts

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * Standalone CLI entry point for graphiti-mem commands.
+ *
+ * Reads config from environment variables and/or a JSON config file,
+ * instantiates SpiceDB + Graphiti clients, and exposes the same commands
+ * as the OpenClaw plugin — without requiring a running gateway.
+ *
+ * Usage:
+ *   npx tsx bin/graphiti-mem.ts <command> [options]
+ *   npm run cli -- <command> [options]
+ */
+
+import { Command } from "commander";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { homedir } from "node:os";
+import { graphitiMemoryConfigSchema } from "../config.js";
+import { GraphitiClient } from "../graphiti.js";
+import { SpiceDbClient } from "../spicedb.js";
+import { registerCommands } from "../cli.js";
+
+// ============================================================================
+// Config loading
+// ============================================================================
+
+function loadConfigFile(configPath?: string): Record<string, unknown> | null {
+  const candidates = configPath
+    ? [resolve(configPath)]
+    : [
+        resolve("graphiti-mem.config.json"),
+        join(homedir(), ".config", "graphiti-mem", "config.json"),
+      ];
+  for (const path of candidates) {
+    if (existsSync(path)) {
+      try {
+        return JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
+      } catch (err) {
+        console.error(`Failed to parse config file ${path}: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+      }
+    }
+  }
+  return null;
+}
+
+function loadConfigFromEnv(): Record<string, unknown> {
+  const env = process.env;
+  const config: Record<string, unknown> = {};
+
+  // SpiceDB config
+  const spicedb: Record<string, unknown> = {};
+  if (env.GRAPHITI_MEM_SPICEDB_TOKEN ?? env.SPICEDB_TOKEN)
+    spicedb.token = env.GRAPHITI_MEM_SPICEDB_TOKEN ?? env.SPICEDB_TOKEN;
+  if (env.GRAPHITI_MEM_SPICEDB_ENDPOINT ?? env.SPICEDB_ENDPOINT)
+    spicedb.endpoint = env.GRAPHITI_MEM_SPICEDB_ENDPOINT ?? env.SPICEDB_ENDPOINT;
+  if (env.GRAPHITI_MEM_SPICEDB_INSECURE)
+    spicedb.insecure = env.GRAPHITI_MEM_SPICEDB_INSECURE !== "false";
+  if (Object.keys(spicedb).length > 0) config.spicedb = spicedb;
+
+  // Graphiti config
+  const graphiti: Record<string, unknown> = {};
+  if (env.GRAPHITI_MEM_GRAPHITI_ENDPOINT ?? env.GRAPHITI_ENDPOINT)
+    graphiti.endpoint = env.GRAPHITI_MEM_GRAPHITI_ENDPOINT ?? env.GRAPHITI_ENDPOINT;
+  if (env.GRAPHITI_MEM_DEFAULT_GROUP_ID)
+    graphiti.defaultGroupId = env.GRAPHITI_MEM_DEFAULT_GROUP_ID;
+  if (Object.keys(graphiti).length > 0) config.graphiti = graphiti;
+
+  // Top-level config
+  if (env.GRAPHITI_MEM_SUBJECT_TYPE) config.subjectType = env.GRAPHITI_MEM_SUBJECT_TYPE;
+  if (env.GRAPHITI_MEM_SUBJECT_ID) config.subjectId = env.GRAPHITI_MEM_SUBJECT_ID;
+
+  return config;
+}
+
+function deepMerge(
+  base: Record<string, unknown>,
+  override: Record<string, unknown>,
+): Record<string, unknown> {
+  const result = { ...base };
+  for (const key of Object.keys(override)) {
+    if (
+      typeof result[key] === "object" && result[key] !== null && !Array.isArray(result[key]) &&
+      typeof override[key] === "object" && override[key] !== null && !Array.isArray(override[key])
+    ) {
+      result[key] = deepMerge(
+        result[key] as Record<string, unknown>,
+        override[key] as Record<string, unknown>,
+      );
+    } else {
+      result[key] = override[key];
+    }
+  }
+  return result;
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+const program = new Command()
+  .name("graphiti-mem")
+  .description("Standalone CLI for Graphiti + SpiceDB memory management")
+  .option("--config <path>", "Path to config JSON file");
+
+// Extract --config before subcommand parsing
+const configIdx = process.argv.indexOf("--config");
+const configPath = configIdx !== -1 ? process.argv[configIdx + 1] : undefined;
+
+const fileConfig = loadConfigFile(configPath);
+const envConfig = loadConfigFromEnv();
+
+// Merge: env vars override file config, both override defaults
+const mergedConfig = fileConfig
+  ? deepMerge(fileConfig, envConfig)
+  : envConfig;
+
+let cfg;
+try {
+  cfg = graphitiMemoryConfigSchema.parse(mergedConfig);
+} catch (err) {
+  console.error(`Invalid configuration: ${err instanceof Error ? err.message : String(err)}`);
+  console.error("\nProvide config via environment variables or a JSON config file.");
+  console.error("Required: SPICEDB_TOKEN (or --config with spicedb.token)");
+  process.exit(1);
+}
+
+const graphiti = new GraphitiClient(cfg.graphiti.endpoint);
+const spicedb = new SpiceDbClient(cfg.spicedb);
+const currentSubject = { type: cfg.subjectType, id: cfg.subjectId } as const;
+
+registerCommands(program, {
+  graphiti,
+  spicedb,
+  cfg,
+  currentSubject,
+  getLastWriteToken: () => undefined,
+});
+
+await program.parseAsync(process.argv);