@contextableai/openclaw-memory-graphiti 0.1.1

package/openclaw.plugin.json

@@ -0,0 +1,91 @@
+{
+  "id": "memory-graphiti",
+  "kind": "memory",
+  "uiHints": {
+    "spicedb.endpoint": {
+      "label": "SpiceDB Endpoint",
+      "placeholder": "localhost:50051",
+      "help": "SpiceDB gRPC endpoint (host:port)"
+    },
+    "spicedb.token": {
+      "label": "SpiceDB Token",
+      "sensitive": true,
+      "placeholder": "dev_token",
+      "help": "SpiceDB pre-shared key (or use ${SPICEDB_TOKEN})"
+    },
+    "spicedb.insecure": {
+      "label": "Insecure Connection",
+      "help": "Allow insecure gRPC to localhost (dev mode)"
+    },
+    "graphiti.endpoint": {
+      "label": "Graphiti MCP Endpoint",
+      "placeholder": "http://localhost:8000",
+      "help": "Graphiti MCP server HTTP base URL"
+    },
+    "graphiti.defaultGroupId": {
+      "label": "Default Group ID",
+      "placeholder": "main",
+      "help": "Default Graphiti group_id for memory isolation"
+    },
+    "subjectType": {
+      "label": "Subject Type",
+      "placeholder": "agent",
+      "help": "SpiceDB subject object type (agent or person)",
+      "advanced": true
+    },
+    "subjectId": {
+      "label": "Subject ID",
+      "placeholder": "${OPENCLAW_AGENT_ID}",
+      "help": "SpiceDB subject ID for the current agent/person"
+    },
+    "autoCapture": {
+      "label": "Auto-Capture",
+      "help": "Automatically capture important information from conversations"
+    },
+    "autoRecall": {
+      "label": "Auto-Recall",
+      "help": "Automatically inject relevant memories into context"
+    },
+    "customInstructions": {
+      "label": "Custom Extraction Instructions",
+      "help": "Natural language rules for what Graphiti should extract from conversations",
+      "advanced": true
+    },
+    "maxCaptureMessages": {
+      "label": "Max Capture Messages",
+      "help": "Maximum number of recent messages to include in auto-capture (default: 10)",
+      "advanced": true
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "spicedb": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "endpoint": { "type": "string" },
+          "token": { "type": "string" },
+          "insecure": { "type": "boolean" }
+        },
+        "required": ["token"]
+      },
+      "graphiti": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "endpoint": { "type": "string" },
+          "defaultGroupId": { "type": "string" }
+        }
+      },
+      "subjectType": { "type": "string", "enum": ["agent", "person"] },
+      "subjectId": { "type": "string" },
+      "autoCapture": { "type": "boolean" },
+      "autoRecall": { "type": "boolean" },
+      "customInstructions": { "type": "string" },
+      "maxCaptureMessages": { "type": "integer", "minimum": 1, "maximum": 50 }
+    },
+    "required": ["spicedb"]
+  }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@contextableai/openclaw-memory-graphiti",
+  "version": "0.1.1",
+  "description": "OpenClaw two-layer memory plugin: SpiceDB authorization + Graphiti knowledge graph",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Contextable/openclaw-memory-graphiti.git"
+  },
+  "keywords": [
+    "openclaw",
+    "memory",
+    "graphiti",
+    "spicedb",
+    "knowledge-graph",
+    "authorization"
+  ],
+  "files": [
+    "index.ts",
+    "config.ts",
+    "authorization.ts",
+    "graphiti.ts",
+    "search.ts",
+    "spicedb.ts",
+    "openclaw.plugin.json",
+    "schema.zed",
+    "docker/",
+    "scripts/"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "OPENCLAW_LIVE_TEST=1 vitest run --config vitest.e2e.config.ts"
+  },
+  "dependencies": {
+    "@authzed/authzed-node": "^1.2.0",
+    "@sinclair/typebox": "0.34.48"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/schema.zed

@@ -0,0 +1,23 @@
+definition person {}
+
+definition agent {
+    relation owner: person
+    permission act_as = owner
+}
+
+definition group {
+    relation member: person | agent
+    permission access = member
+    permission contribute = member
+}
+
+definition memory_fragment {
+    relation source_group: group
+    relation involves: person | agent
+    relation shared_by: person | agent
+
+    // Can view if: directly involved, shared it, or have access to the source group
+    permission view = involves + shared_by + source_group->access
+    // Can delete if: you shared it (owner-level control)
+    permission delete = shared_by
+}

package/scripts/dev-setup.sh

@@ -0,0 +1,146 @@
+#!/usr/bin/env bash
+# -------------------------------------------------------------------
+# dev-setup.sh — One-time installation of native dev services
+#
+# Installs:
+#   Redis 8.x        from packages.redis.io (>= 7.2 required by FalkorDB)
+#   FalkorDB module   prebuilt .so from GitHub releases
+#   SpiceDB           prebuilt binary from GitHub releases
+#   Graphiti MCP      cloned from GitHub, deps via uv
+#
+# Everything goes into .dev/ (project-local, gitignored) except
+# Redis which is installed system-wide via apt.
+#
+# Requirements: curl, git, python3 (>= 3.10), sudo (for apt)
+# -------------------------------------------------------------------
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+DEV_DIR="$PROJECT_DIR/.dev"
+
+SPICEDB_VERSION="${SPICEDB_VERSION:-1.49.0}"
+FALKORDB_VERSION="${FALKORDB_VERSION:-4.16.3}"
+
+# Detect architecture
+ARCH="$(uname -m)"
+case "$ARCH" in
+  aarch64|arm64) ARCH_SUFFIX="arm64"; FALKOR_ARCH="arm64v8" ;;
+  x86_64|amd64)  ARCH_SUFFIX="amd64"; FALKOR_ARCH="x64" ;;
+  *) echo "Unsupported architecture: $ARCH"; exit 1 ;;
+esac
+
+echo "==> Setting up dev environment in $DEV_DIR"
+mkdir -p "$DEV_DIR/bin" "$DEV_DIR/lib" "$DEV_DIR/data/falkordb" "$DEV_DIR/logs" "$DEV_DIR/pids"
+
+# -------------------------------------------------------------------
+# 1. Redis (system-wide via apt — FalkorDB needs >= 7.2)
+# -------------------------------------------------------------------
+REDIS_OK=false
+if command -v redis-server &>/dev/null; then
+  REDIS_MAJOR="$(redis-server --version | grep -oP 'v=\K[0-9]+')"
+  if [ "$REDIS_MAJOR" -ge 8 ] 2>/dev/null; then
+    REDIS_OK=true
+    echo "==> Redis already installed: $(redis-server --version | grep -oP 'v=\S+')"
+  fi
+fi
+
+if [ "$REDIS_OK" = false ]; then
+  echo "==> Installing Redis >= 7.2 from packages.redis.io..."
+  curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg 2>/dev/null
+  echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs 2>/dev/null || echo bookworm) main" \
+    | sudo tee /etc/apt/sources.list.d/redis.list >/dev/null
+  sudo apt-get update -qq 2>&1 | tail -1
+  sudo apt-get install -y -qq redis-server libgomp1 2>&1 | tail -3
+  echo "    Installed: $(redis-server --version | grep -oP 'v=\S+')"
+fi
+
+# Ensure libgomp1 is present (FalkorDB dependency)
+dpkg -l libgomp1 >/dev/null 2>&1 || sudo apt-get install -y -qq libgomp1
+
+# -------------------------------------------------------------------
+# 2. FalkorDB module (.so)
+# -------------------------------------------------------------------
+if [ -f "$DEV_DIR/lib/falkordb.so" ]; then
+  echo "==> FalkorDB module already downloaded"
+else
+  echo "==> Downloading FalkorDB v${FALKORDB_VERSION} module (${FALKOR_ARCH})..."
+  curl -fsSL -o "$DEV_DIR/lib/falkordb.so" \
+    "https://github.com/FalkorDB/FalkorDB/releases/download/v${FALKORDB_VERSION}/falkordb-${FALKOR_ARCH}.so"
+  chmod +x "$DEV_DIR/lib/falkordb.so"
+  echo "    Downloaded: $DEV_DIR/lib/falkordb.so"
+fi
+
+# -------------------------------------------------------------------
+# 3. PostgreSQL (optional — persistent datastore for SpiceDB)
+# -------------------------------------------------------------------
+if command -v pg_isready &>/dev/null; then
+  echo "==> PostgreSQL already installed: $(psql --version 2>/dev/null | head -1)"
+else
+  echo "==> Installing PostgreSQL..."
+  sudo apt-get update -qq 2>&1 | tail -1
+  sudo apt-get install -y -qq postgresql postgresql-client 2>&1 | tail -3
+  echo "    Installed: $(psql --version 2>/dev/null | head -1)"
+fi
+
+# -------------------------------------------------------------------
+# 4. SpiceDB
+# -------------------------------------------------------------------
+if [ -x "$DEV_DIR/bin/spicedb" ]; then
+  echo "==> SpiceDB already installed: $("$DEV_DIR/bin/spicedb" version 2>/dev/null || echo 'unknown')"
+else
+  echo "==> Downloading SpiceDB v${SPICEDB_VERSION} (${ARCH_SUFFIX})..."
+  SPICEDB_URL="https://github.com/authzed/spicedb/releases/download/v${SPICEDB_VERSION}/spicedb_${SPICEDB_VERSION}_linux_${ARCH_SUFFIX}.tar.gz"
+  curl -fsSL "$SPICEDB_URL" | tar xz -C "$DEV_DIR/bin" spicedb
+  chmod +x "$DEV_DIR/bin/spicedb"
+  echo "    Installed: $("$DEV_DIR/bin/spicedb" version 2>/dev/null || echo "v${SPICEDB_VERSION}")"
+fi
+
+# -------------------------------------------------------------------
+# 5. uv (Python package manager)
+# -------------------------------------------------------------------
+if command -v uv &>/dev/null; then
+  echo "==> uv already installed: $(uv --version)"
+elif [ -x "$HOME/.local/bin/uv" ]; then
+  echo "==> uv already installed at ~/.local/bin/uv"
+  export PATH="$HOME/.local/bin:$PATH"
+else
+  echo "==> Installing uv (Python package manager)..."
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+  export PATH="$HOME/.local/bin:$PATH"
+  echo "    Installed: $(uv --version)"
+fi
+
+# -------------------------------------------------------------------
+# 6. Graphiti MCP Server
+# -------------------------------------------------------------------
+GRAPHITI_DIR="$DEV_DIR/graphiti"
+if [ -d "$GRAPHITI_DIR/mcp_server" ]; then
+  echo "==> Graphiti repo already cloned, pulling latest..."
+  git -C "$GRAPHITI_DIR" pull --ff-only 2>/dev/null || echo "    (pull skipped — detached or dirty)"
+else
+  echo "==> Cloning Graphiti repo..."
+  git clone --depth 1 https://github.com/getzep/graphiti.git "$GRAPHITI_DIR"
+fi
+
+echo "==> Installing Graphiti MCP server dependencies..."
+cd "$GRAPHITI_DIR/mcp_server"
+if command -v uv &>/dev/null; then
+  uv sync 2>&1 | tail -3
+else
+  "$HOME/.local/bin/uv" sync 2>&1 | tail -3
+fi
+cd "$PROJECT_DIR"
+
+# -------------------------------------------------------------------
+# Done
+# -------------------------------------------------------------------
+echo ""
+echo "==> Dev environment ready!"
+echo ""
+echo "    Redis:    $(redis-server --version | grep -oP 'v=\S+')"
+echo "    FalkorDB: $DEV_DIR/lib/falkordb.so (v${FALKORDB_VERSION})"
+echo "    SpiceDB:  $DEV_DIR/bin/spicedb"
+echo "    Graphiti: $GRAPHITI_DIR/mcp_server/"
+echo ""
+echo "    Next: run ./scripts/dev-start.sh to start services"

package/scripts/dev-start.sh

@@ -0,0 +1,236 @@
+#!/usr/bin/env bash
+# -------------------------------------------------------------------
+# dev-start.sh — Start FalkorDB + SpiceDB + Graphiti MCP server
+#
+# Services run in the background; logs go to .dev/logs/.
+# PID files are written to .dev/pids/.
+#
+# Environment variables (all optional):
+#   OPENAI_API_KEY        Required by Graphiti for entity extraction
+#   SPICEDB_TOKEN         Pre-shared key (default: dev_token)
+#   SPICEDB_PORT          gRPC port (default: 50051)
+#   SPICEDB_DATASTORE     "memory" (default) or "postgres"
+#   SPICEDB_DB_URI        Postgres connection URI (when SPICEDB_DATASTORE=postgres)
+#   FALKORDB_PORT         Redis port (default: 6379)
+#   GRAPHITI_PORT         HTTP port (default: 8000)
+# -------------------------------------------------------------------
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+DEV_DIR="$PROJECT_DIR/.dev"
+
+# Load .env if present
+if [ -f "$PROJECT_DIR/.env" ]; then
+  set -a
+  # shellcheck disable=SC1091
+  source "$PROJECT_DIR/.env"
+  set +a
+fi
+
+SPICEDB_TOKEN="${SPICEDB_TOKEN:-dev_token}"
+SPICEDB_PORT="${SPICEDB_PORT:-50051}"
+SPICEDB_DATASTORE="${SPICEDB_DATASTORE:-memory}"
+SPICEDB_DB_URI="${SPICEDB_DB_URI:-postgres://spicedb:spicedb_dev@127.0.0.1:5432/spicedb?sslmode=disable}"
+FALKORDB_PORT="${FALKORDB_PORT:-6379}"
+GRAPHITI_PORT="${GRAPHITI_PORT:-8000}"
+
+mkdir -p "$DEV_DIR/logs" "$DEV_DIR/pids" "$DEV_DIR/data/falkordb"
+
+# Ensure uv is on PATH
+export PATH="$HOME/.local/bin:$DEV_DIR/bin:$PATH"
+
+# -------------------------------------------------------------------
+# Helper: check if a process is already running
+# -------------------------------------------------------------------
+is_running() {
+  local pidfile="$1"
+  if [ -f "$pidfile" ]; then
+    local pid
+    pid=$(cat "$pidfile")
+    if kill -0 "$pid" 2>/dev/null; then
+      return 0
+    fi
+    rm -f "$pidfile"
+  fi
+  return 1
+}
+
+# -------------------------------------------------------------------
+# 1. FalkorDB (Redis + module)
+# -------------------------------------------------------------------
+if is_running "$DEV_DIR/pids/falkordb.pid"; then
+  echo "==> FalkorDB already running (pid $(cat "$DEV_DIR/pids/falkordb.pid"))"
+else
+  echo "==> Starting FalkorDB on port $FALKORDB_PORT..."
+  redis-server \
+    --loadmodule "$DEV_DIR/lib/falkordb.so" \
+    --port "$FALKORDB_PORT" \
+    --dir "$DEV_DIR/data/falkordb" \
+    --daemonize no \
+    --save "" \
+    --appendonly no \
+    --loglevel notice \
+    > "$DEV_DIR/logs/falkordb.log" 2>&1 &
+  echo $! > "$DEV_DIR/pids/falkordb.pid"
+  echo "    PID: $(cat "$DEV_DIR/pids/falkordb.pid") — log: .dev/logs/falkordb.log"
+
+  # Wait for FalkorDB to be ready
+  echo -n "    Waiting for FalkorDB..."
+  for i in $(seq 1 30); do
+    if redis-cli -p "$FALKORDB_PORT" PING 2>/dev/null | grep -q PONG; then
+      echo " ready!"
+      break
+    fi
+    if [ "$i" -eq 30 ]; then
+      echo " timeout! Check .dev/logs/falkordb.log"
+      exit 1
+    fi
+    sleep 0.5
+    echo -n "."
+  done
+fi
+
+# -------------------------------------------------------------------
+# 2. PostgreSQL (when SPICEDB_DATASTORE=postgres)
+# -------------------------------------------------------------------
+if [ "$SPICEDB_DATASTORE" = "postgres" ]; then
+  if pg_isready -q 2>/dev/null; then
+    echo "==> PostgreSQL already running"
+  else
+    echo "==> Starting PostgreSQL..."
+    sudo pg_ctlcluster 15 main start 2>&1
+    echo -n "    Waiting for PostgreSQL..."
+    for i in $(seq 1 20); do
+      if pg_isready -q 2>/dev/null; then
+        echo " ready!"
+        break
+      fi
+      if [ "$i" -eq 20 ]; then
+        echo " timeout!"
+        exit 1
+      fi
+      sleep 0.5
+      echo -n "."
+    done
+  fi
+
+  # Ensure database and user exist (idempotent)
+  sudo su - postgres -c "psql -tc \"SELECT 1 FROM pg_roles WHERE rolname='spicedb'\" | grep -q 1" 2>/dev/null \
+    || sudo su - postgres -c "psql -c \"CREATE USER spicedb WITH PASSWORD 'spicedb_dev';\"" 2>/dev/null
+  sudo su - postgres -c "psql -tc \"SELECT 1 FROM pg_database WHERE datname='spicedb'\" | grep -q 1" 2>/dev/null \
+    || sudo su - postgres -c "psql -c \"CREATE DATABASE spicedb OWNER spicedb;\"" 2>/dev/null
+
+  # Run SpiceDB migrations
+  echo "==> Running SpiceDB migrations..."
+  "$DEV_DIR/bin/spicedb" migrate head \
+    --datastore-engine=postgres \
+    "--datastore-conn-uri=$SPICEDB_DB_URI" \
+    > "$DEV_DIR/logs/spicedb-migrate.log" 2>&1
+  echo "    Migrations complete"
+fi
+
+# -------------------------------------------------------------------
+# 3. SpiceDB
+# -------------------------------------------------------------------
+if is_running "$DEV_DIR/pids/spicedb.pid"; then
+  echo "==> SpiceDB already running (pid $(cat "$DEV_DIR/pids/spicedb.pid"))"
+else
+  SPICEDB_ARGS=(
+    serve
+    "--grpc-preshared-key=$SPICEDB_TOKEN"
+    "--grpc-addr=:$SPICEDB_PORT"
+    "--datastore-engine=$SPICEDB_DATASTORE"
+    --http-enabled=true
+  )
+  if [ "$SPICEDB_DATASTORE" = "postgres" ]; then
+    SPICEDB_ARGS+=("--datastore-conn-uri=$SPICEDB_DB_URI")
+  fi
+
+  echo "==> Starting SpiceDB on port $SPICEDB_PORT (datastore: $SPICEDB_DATASTORE)..."
+  "$DEV_DIR/bin/spicedb" "${SPICEDB_ARGS[@]}" \
+    > "$DEV_DIR/logs/spicedb.log" 2>&1 &
+  echo $! > "$DEV_DIR/pids/spicedb.pid"
+  echo "    PID: $(cat "$DEV_DIR/pids/spicedb.pid") — log: .dev/logs/spicedb.log"
+
+  # Wait for SpiceDB to be ready
+  echo -n "    Waiting for SpiceDB..."
+  for i in $(seq 1 30); do
+    if curl -sf http://localhost:8443/healthz >/dev/null 2>&1; then
+      echo " ready!"
+      break
+    fi
+    if [ "$i" -eq 30 ]; then
+      echo " timeout! Check .dev/logs/spicedb.log"
+      exit 1
+    fi
+    sleep 0.5
+    echo -n "."
+  done
+fi
+
+# -------------------------------------------------------------------
+# 4. Graphiti MCP Server (FalkorDB backend)
+# -------------------------------------------------------------------
+if is_running "$DEV_DIR/pids/graphiti.pid"; then
+  echo "==> Graphiti MCP server already running (pid $(cat "$DEV_DIR/pids/graphiti.pid"))"
+else
+  if [ -z "${OPENAI_API_KEY:-}" ]; then
+    echo ""
+    echo "WARNING: OPENAI_API_KEY is not set."
+    echo "Graphiti needs it for entity extraction and embeddings."
+    echo "Set it in .env or export it before running this script."
+    echo ""
+  fi
+
+  echo "==> Starting Graphiti MCP server on port $GRAPHITI_PORT..."
+
+  GRAPHITI_DIR="$DEV_DIR/graphiti/mcp_server"
+
+  # Set environment for Graphiti
+  export OPENAI_API_KEY="${OPENAI_API_KEY:-}"
+  export FALKORDB_URI="redis://localhost:$FALKORDB_PORT"
+
+  cd "$GRAPHITI_DIR"
+  uv run main.py \
+    --transport http \
+    --port "$GRAPHITI_PORT" \
+    > "$DEV_DIR/logs/graphiti.log" 2>&1 &
+  echo $! > "$DEV_DIR/pids/graphiti.pid"
+  cd "$PROJECT_DIR"
+
+  echo "    PID: $(cat "$DEV_DIR/pids/graphiti.pid") — log: .dev/logs/graphiti.log"
+
+  # Wait for Graphiti to be ready
+  echo -n "    Waiting for Graphiti..."
+  for i in $(seq 1 60); do
+    if curl -sf "http://localhost:$GRAPHITI_PORT/health" >/dev/null 2>&1; then
+      echo " ready!"
+      break
+    fi
+    if [ "$i" -eq 60 ]; then
+      echo " timeout! Check .dev/logs/graphiti.log"
+      exit 1
+    fi
+    sleep 1
+    echo -n "."
+  done
+fi
+
+# -------------------------------------------------------------------
+# Summary
+# -------------------------------------------------------------------
+echo ""
+echo "==> All services running:"
+echo "    FalkorDB:        localhost:$FALKORDB_PORT (Redis protocol)"
+echo "    SpiceDB gRPC:    localhost:$SPICEDB_PORT (datastore: $SPICEDB_DATASTORE)"
+echo "    SpiceDB HTTP:    localhost:8443"
+echo "    Graphiti MCP:    http://localhost:$GRAPHITI_PORT"
+echo "    Graphiti health: http://localhost:$GRAPHITI_PORT/health"
+echo ""
+echo "    Stop with: ./scripts/dev-stop.sh"
+echo "    Status:    ./scripts/dev-status.sh"
+echo "    Logs:      tail -f .dev/logs/*.log"
+echo ""
+echo "    Run e2e tests:"
+echo "      OPENCLAW_LIVE_TEST=1 pnpm vitest run e2e.test.ts"

package/scripts/dev-status.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# -------------------------------------------------------------------
+# dev-status.sh — Check status of dev services
+# -------------------------------------------------------------------
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+DEV_DIR="$(cd "$SCRIPT_DIR/.." && pwd)/.dev"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m' # No Color
+
+check_service() {
+  local name="$1"
+  local pidfile="$DEV_DIR/pids/${name}.pid"
+  local health_url="$2"
+
+  printf "  %-20s" "$name:"
+
+  # Check PID
+  if [ -f "$pidfile" ]; then
+    local pid
+    pid=$(cat "$pidfile")
+    if kill -0 "$pid" 2>/dev/null; then
+      printf "${GREEN}running${NC} (pid %s)" "$pid"
+    else
+      printf "${RED}dead${NC} (stale pid %s)" "$pid"
+      rm -f "$pidfile"
+      echo ""
+      return
+    fi
+  else
+    printf "${RED}stopped${NC}"
+    echo ""
+    return
+  fi
+
+  # Check health endpoint
+  if [ -n "$health_url" ]; then
+    if curl -sf "$health_url" >/dev/null 2>&1; then
+      printf "  ${GREEN}healthy${NC}"
+    else
+      printf "  ${RED}unhealthy${NC}"
+    fi
+  fi
+
+  echo ""
+}
+
+echo ""
+echo "Dev service status:"
+echo ""
+check_service "falkordb" ""
+check_service "spicedb"  "http://localhost:8443/healthz"
+check_service "graphiti" "http://localhost:8000/health"
+echo ""

package/scripts/dev-stop.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# -------------------------------------------------------------------
+# dev-stop.sh — Stop all dev services
+# -------------------------------------------------------------------
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+DEV_DIR="$(cd "$SCRIPT_DIR/.." && pwd)/.dev"
+
+stop_service() {
+  local name="$1"
+  local pidfile="$DEV_DIR/pids/${name}.pid"
+
+  if [ -f "$pidfile" ]; then
+    local pid
+    pid=$(cat "$pidfile")
+    if kill -0 "$pid" 2>/dev/null; then
+      echo "==> Stopping $name (pid $pid)..."
+      kill "$pid"
+      # Wait up to 5 seconds for graceful shutdown
+      for _ in $(seq 1 10); do
+        if ! kill -0 "$pid" 2>/dev/null; then
+          break
+        fi
+        sleep 0.5
+      done
+      # Force kill if still running
+      if kill -0 "$pid" 2>/dev/null; then
+        echo "    Force-killing $name..."
+        kill -9 "$pid" 2>/dev/null || true
+      fi
+      echo "    $name stopped."
+    else
+      echo "==> $name not running (stale pid file)."
+    fi
+    rm -f "$pidfile"
+  else
+    echo "==> $name not running (no pid file)."
+  fi
+}
+
+stop_service "graphiti"
+stop_service "spicedb"
+stop_service "falkordb"
+
+echo ""
+echo "==> All services stopped."