supaclaw 1.0.0

package/migrations/002_vector_search.sql

@@ -0,0 +1,219 @@
+-- OpenClaw Memory - Vector Search Functions
+-- Run this in your Supabase SQL editor after 001_initial.sql
+
+-- Function: Vector similarity search for memories
+-- Returns memories ranked by cosine similarity to the query embedding
+CREATE OR REPLACE FUNCTION match_memories(
+  query_embedding VECTOR(1536),
+  match_threshold FLOAT DEFAULT 0.7,
+  match_count INT DEFAULT 10,
+  p_agent_id TEXT DEFAULT NULL,
+  p_user_id TEXT DEFAULT NULL,
+  p_category TEXT DEFAULT NULL,
+  p_min_importance FLOAT DEFAULT NULL
+)
+RETURNS TABLE (
+  id UUID,
+  agent_id TEXT,
+  user_id TEXT,
+  category TEXT,
+  content TEXT,
+  importance FLOAT,
+  source_session_id UUID,
+  created_at TIMESTAMPTZ,
+  updated_at TIMESTAMPTZ,
+  expires_at TIMESTAMPTZ,
+  embedding VECTOR(1536),
+  metadata JSONB,
+  similarity FLOAT
+)
+LANGUAGE plpgsql
+AS $$
+BEGIN
+  RETURN QUERY
+  SELECT
+    m.id,
+    m.agent_id,
+    m.user_id,
+    m.category,
+    m.content,
+    m.importance,
+    m.source_session_id,
+    m.created_at,
+    m.updated_at,
+    m.expires_at,
+    m.embedding,
+    m.metadata,
+    1 - (m.embedding <=> query_embedding) AS similarity
+  FROM memories m
+  WHERE 
+    (p_agent_id IS NULL OR m.agent_id = p_agent_id)
+    AND (p_user_id IS NULL OR m.user_id = p_user_id OR m.user_id IS NULL)
+    AND (p_category IS NULL OR m.category = p_category)
+    AND (p_min_importance IS NULL OR m.importance >= p_min_importance)
+    AND (m.expires_at IS NULL OR m.expires_at > NOW())
+    AND m.embedding IS NOT NULL
+    AND 1 - (m.embedding <=> query_embedding) > match_threshold
+  ORDER BY m.embedding <=> query_embedding
+  LIMIT match_count;
+END;
+$$;
+
+-- Function: Hybrid search combining vector similarity and keyword matching
+-- Returns memories ranked by weighted combination of semantic similarity and keyword relevance
+CREATE OR REPLACE FUNCTION hybrid_search_memories(
+  query_embedding VECTOR(1536),
+  query_text TEXT,
+  vector_weight FLOAT DEFAULT 0.7,
+  keyword_weight FLOAT DEFAULT 0.3,
+  match_count INT DEFAULT 10,
+  p_agent_id TEXT DEFAULT NULL,
+  p_user_id TEXT DEFAULT NULL,
+  p_category TEXT DEFAULT NULL,
+  p_min_importance FLOAT DEFAULT NULL
+)
+RETURNS TABLE (
+  id UUID,
+  agent_id TEXT,
+  user_id TEXT,
+  category TEXT,
+  content TEXT,
+  importance FLOAT,
+  source_session_id UUID,
+  created_at TIMESTAMPTZ,
+  updated_at TIMESTAMPTZ,
+  expires_at TIMESTAMPTZ,
+  embedding VECTOR(1536),
+  metadata JSONB,
+  score FLOAT
+)
+LANGUAGE plpgsql
+AS $$
+BEGIN
+  RETURN QUERY
+  WITH vector_scores AS (
+    SELECT
+      m.id,
+      1 - (m.embedding <=> query_embedding) AS vector_similarity
+    FROM memories m
+    WHERE 
+      (p_agent_id IS NULL OR m.agent_id = p_agent_id)
+      AND (p_user_id IS NULL OR m.user_id = p_user_id OR m.user_id IS NULL)
+      AND (p_category IS NULL OR m.category = p_category)
+      AND (p_min_importance IS NULL OR m.importance >= p_min_importance)
+      AND (m.expires_at IS NULL OR m.expires_at > NOW())
+      AND m.embedding IS NOT NULL
+  ),
+  keyword_scores AS (
+    SELECT
+      m.id,
+      ts_rank(to_tsvector('english', m.content), plainto_tsquery('english', query_text)) AS keyword_relevance
+    FROM memories m
+    WHERE 
+      (p_agent_id IS NULL OR m.agent_id = p_agent_id)
+      AND (p_user_id IS NULL OR m.user_id = p_user_id OR m.user_id IS NULL)
+      AND (p_category IS NULL OR m.category = p_category)
+      AND (p_min_importance IS NULL OR m.importance >= p_min_importance)
+      AND (m.expires_at IS NULL OR m.expires_at > NOW())
+      AND to_tsvector('english', m.content) @@ plainto_tsquery('english', query_text)
+  ),
+  combined_scores AS (
+    SELECT
+      COALESCE(v.id, k.id) AS memory_id,
+      (COALESCE(v.vector_similarity, 0) * vector_weight + 
+       COALESCE(k.keyword_relevance, 0) * keyword_weight) AS combined_score
+    FROM vector_scores v
+    FULL OUTER JOIN keyword_scores k ON v.id = k.id
+  )
+  SELECT
+    m.id,
+    m.agent_id,
+    m.user_id,
+    m.category,
+    m.content,
+    m.importance,
+    m.source_session_id,
+    m.created_at,
+    m.updated_at,
+    m.expires_at,
+    m.embedding,
+    m.metadata,
+    cs.combined_score AS score
+  FROM memories m
+  JOIN combined_scores cs ON m.id = cs.memory_id
+  ORDER BY cs.combined_score DESC
+  LIMIT match_count;
+END;
+$$;
+
+-- Function: Find similar memories based on an existing memory
+-- Useful for finding related context or detecting duplicates
+CREATE OR REPLACE FUNCTION find_similar_memories(
+  memory_id UUID,
+  match_threshold FLOAT DEFAULT 0.8,
+  match_count INT DEFAULT 5
+)
+RETURNS TABLE (
+  id UUID,
+  agent_id TEXT,
+  user_id TEXT,
+  category TEXT,
+  content TEXT,
+  importance FLOAT,
+  source_session_id UUID,
+  created_at TIMESTAMPTZ,
+  updated_at TIMESTAMPTZ,
+  expires_at TIMESTAMPTZ,
+  embedding VECTOR(1536),
+  metadata JSONB,
+  similarity FLOAT
+)
+LANGUAGE plpgsql
+AS $$
+DECLARE
+  source_embedding VECTOR(1536);
+  source_agent_id TEXT;
+BEGIN
+  -- Get the embedding of the source memory
+  SELECT m.embedding, m.agent_id INTO source_embedding, source_agent_id
+  FROM memories m
+  WHERE m.id = memory_id;
+
+  IF source_embedding IS NULL THEN
+    RAISE EXCEPTION 'Memory not found or has no embedding';
+  END IF;
+
+  RETURN QUERY
+  SELECT
+    m.id,
+    m.agent_id,
+    m.user_id,
+    m.category,
+    m.content,
+    m.importance,
+    m.source_session_id,
+    m.created_at,
+    m.updated_at,
+    m.expires_at,
+    m.embedding,
+    m.metadata,
+    1 - (m.embedding <=> source_embedding) AS similarity
+  FROM memories m
+  WHERE 
+    m.id != memory_id
+    AND m.agent_id = source_agent_id
+    AND m.embedding IS NOT NULL
+    AND 1 - (m.embedding <=> source_embedding) > match_threshold
+  ORDER BY m.embedding <=> source_embedding
+  LIMIT match_count;
+END;
+$$;
+
+-- Create full-text search index for keyword search optimization
+CREATE INDEX IF NOT EXISTS memories_content_fts_idx ON memories 
+  USING GIN (to_tsvector('english', content));
+
+-- Comments for documentation
+COMMENT ON FUNCTION match_memories IS 'Performs semantic search on memories using vector similarity (cosine distance)';
+COMMENT ON FUNCTION hybrid_search_memories IS 'Combines vector similarity and keyword matching with configurable weights';
+COMMENT ON FUNCTION find_similar_memories IS 'Finds memories similar to a given memory, useful for deduplication and context expansion';

package/migrations/003_entity_relationships.sql

@@ -0,0 +1,143 @@
+-- Migration 003: Entity Relationships
+-- Tracks connections between entities (e.g., "Han works_at MetalBear")
+
+-- Create entity_relationships table
+CREATE TABLE IF NOT EXISTS entity_relationships (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  agent_id TEXT NOT NULL,
+  source_entity_id UUID REFERENCES entities(id) ON DELETE CASCADE,
+  target_entity_id UUID REFERENCES entities(id) ON DELETE CASCADE,
+  relationship_type TEXT NOT NULL,     -- 'works_at', 'knows', 'created', 'located_in', etc.
+  properties JSONB DEFAULT '{}',       -- Additional context (since, strength, etc.)
+  first_seen_at TIMESTAMPTZ DEFAULT NOW(),
+  last_seen_at TIMESTAMPTZ DEFAULT NOW(),
+  mention_count INT DEFAULT 1,
+  confidence FLOAT DEFAULT 0.5,        -- 0-1 confidence in this relationship
+  source_session_id UUID REFERENCES sessions(id),
+  metadata JSONB DEFAULT '{}'
+);
+
+-- Indexes for efficient lookups
+CREATE INDEX IF NOT EXISTS entity_relationships_source_idx 
+  ON entity_relationships(source_entity_id);
+  
+CREATE INDEX IF NOT EXISTS entity_relationships_target_idx 
+  ON entity_relationships(target_entity_id);
+  
+CREATE INDEX IF NOT EXISTS entity_relationships_type_idx 
+  ON entity_relationships(relationship_type);
+
+-- Prevent duplicate relationships
+CREATE UNIQUE INDEX IF NOT EXISTS entity_relationships_unique_idx 
+  ON entity_relationships(agent_id, source_entity_id, target_entity_id, relationship_type);
+
+-- Function to increment relationship mention count
+CREATE OR REPLACE FUNCTION increment_relationship_mentions(rel_id UUID)
+RETURNS entity_relationships AS $$
+DECLARE
+  result entity_relationships;
+BEGIN
+  UPDATE entity_relationships
+  SET mention_count = mention_count + 1,
+      last_seen_at = NOW()
+  WHERE id = rel_id
+  RETURNING * INTO result;
+  
+  RETURN result;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Function to find related entities (graph traversal)
+CREATE OR REPLACE FUNCTION find_related_entities(
+  entity_id UUID,
+  max_depth INT DEFAULT 2,
+  min_confidence FLOAT DEFAULT 0.5
+)
+RETURNS TABLE (
+  entity_id UUID,
+  entity_name TEXT,
+  entity_type TEXT,
+  relationship_path TEXT[],
+  total_confidence FLOAT,
+  depth INT
+) AS $$
+WITH RECURSIVE entity_graph AS (
+  -- Base case: direct relationships
+  SELECT 
+    e.id as entity_id,
+    e.name as entity_name,
+    e.entity_type,
+    ARRAY[r.relationship_type] as relationship_path,
+    r.confidence as total_confidence,
+    1 as depth
+  FROM entity_relationships r
+  JOIN entities e ON e.id = r.target_entity_id
+  WHERE r.source_entity_id = entity_id
+    AND r.confidence >= min_confidence
+  
+  UNION
+  
+  -- Recursive case: indirect relationships
+  SELECT 
+    e.id,
+    e.name,
+    e.entity_type,
+    eg.relationship_path || r.relationship_type,
+    eg.total_confidence * r.confidence,
+    eg.depth + 1
+  FROM entity_graph eg
+  JOIN entity_relationships r ON r.source_entity_id = eg.entity_id
+  JOIN entities e ON e.id = r.target_entity_id
+  WHERE eg.depth < max_depth
+    AND r.confidence >= min_confidence
+    AND NOT e.id = ANY(SELECT unnest(eg.relationship_path::UUID[]))  -- Prevent cycles
+)
+SELECT * FROM entity_graph
+ORDER BY total_confidence DESC, depth ASC;
+$$ LANGUAGE sql;
+
+-- Function to get entity network stats
+CREATE OR REPLACE FUNCTION get_entity_network_stats(agent TEXT)
+RETURNS TABLE (
+  total_entities BIGINT,
+  total_relationships BIGINT,
+  avg_connections_per_entity FLOAT,
+  most_connected_entity_id UUID,
+  most_connected_entity_name TEXT,
+  connection_count BIGINT
+) AS $$
+WITH entity_connections AS (
+  SELECT 
+    source_entity_id as entity_id,
+    COUNT(*) as outgoing_count
+  FROM entity_relationships
+  WHERE agent_id = agent
+  GROUP BY source_entity_id
+),
+most_connected AS (
+  SELECT 
+    ec.entity_id,
+    e.name,
+    ec.outgoing_count
+  FROM entity_connections ec
+  JOIN entities e ON e.id = ec.entity_id
+  ORDER BY ec.outgoing_count DESC
+  LIMIT 1
+)
+SELECT 
+  (SELECT COUNT(*) FROM entities WHERE agent_id = agent)::BIGINT as total_entities,
+  (SELECT COUNT(*) FROM entity_relationships WHERE agent_id = agent)::BIGINT as total_relationships,
+  (SELECT AVG(outgoing_count) FROM entity_connections)::FLOAT as avg_connections_per_entity,
+  mc.entity_id as most_connected_entity_id,
+  mc.name as most_connected_entity_name,
+  mc.outgoing_count::BIGINT as connection_count
+FROM most_connected mc;
+$$ LANGUAGE sql;
+
+-- Comments for documentation
+COMMENT ON TABLE entity_relationships IS 'Tracks relationships between entities (people, places, things)';
+COMMENT ON COLUMN entity_relationships.relationship_type IS 'Type of relationship: works_at, knows, created, located_in, etc.';
+COMMENT ON COLUMN entity_relationships.confidence IS 'Confidence score (0-1) in this relationship';
+COMMENT ON FUNCTION increment_relationship_mentions IS 'Increments mention count and updates last_seen_at for a relationship';
+COMMENT ON FUNCTION find_related_entities IS 'Graph traversal to find entities connected through relationships';
+COMMENT ON FUNCTION get_entity_network_stats IS 'Statistics about the entity relationship network';

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "supaclaw",
+  "version": "1.0.0",
+  "description": "Persistent memory for AI agents using Supabase - sessions, memories, semantic search",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "supaclaw": "dist/cli.js"
+  },
+  "files": [
+    "dist/**/*",
+    "migrations/**/*",
+    "README.md",
+    "LICENSE",
+    "SCHEMA.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "memory",
+    "supabase",
+    "postgres",
+    "vector-search",
+    "semantic-search",
+    "llm",
+    "context-management",
+    "openclaw",
+    "clawdbot",
+    "ai-memory",
+    "conversation-history",
+    "chat-history",
+    "context-window",
+    "rag"
+  ],
+  "author": "Han Kim",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Arephan/supaclaw.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Arephan/supaclaw/issues"
+  },
+  "homepage": "https://github.com/Arephan/supaclaw#readme",
+  "dependencies": {
+    "@supabase/supabase-js": "^2.39.0",
+    "commander": "^14.0.3",
+    "openai": "^6.17.0"
+  },
+  "devDependencies": {
+    "@types/commander": "^2.12.0",
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}