@arephan/clawdbot-memory-supabase 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arephan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+# clawdbot-memory-supabase
+
+A Clawdbot plugin that logs **every conversation** to Supabase/PostgreSQL. Never forget anything.
+
+## What it does
+
+- 📝 Logs every message (user + assistant) with timestamps
+- 🔍 Query by date: "What did we talk about on January 15th?"
+- 📅 Query by range: "What did we discuss last week?"
+- 🔎 Search by keyword across all history
+- 🐘 Elephant memory — complete conversation recall
+
+## Quick Start
+
+### 1. Set up Supabase
+
+**Local (recommended for development):**
+```bash
+# Install Supabase CLI
+brew install supabase/tap/supabase
+
+# In your project directory
+supabase init
+supabase start
+```
+
+**Or use Supabase Cloud:** Create a project at [supabase.com](https://supabase.com)
+
+### 2. Run migrations
+
+Copy the `migrations/` folder to your Supabase project:
+
+```bash
+cp -r migrations/ your-project/supabase/migrations/
+cd your-project
+supabase db reset  # Local
+# or
+supabase db push   # Cloud
+```
+
+### 3. Install the plugin
+
+**Option A: Copy to extensions folder**
+```bash
+cp -r plugin/ ~/.clawdbot/extensions/memory-supabase/
+# or for workspace-specific:
+cp -r plugin/ your-workspace/.clawdbot/extensions/memory-supabase/
+```
+
+**Option B: Install from npm** (coming soon)
+```bash
+clawdbot plugins install @arephan/clawdbot-memory-supabase
+```
+
+### 4. Configure Clawdbot
+
+Add to your `clawdbot.json`:
+
+```json
+{
+  "plugins": {
+    "slots": {
+      "memory": "memory-supabase"
+    },
+    "entries": {
+      "memory-supabase": {
+        "enabled": true,
+        "config": {
+          "supabase": {
+            "url": "http://127.0.0.1:54321",
+            "anonKey": "your-supabase-key"
+          },
+          "agentId": "my-agent"
+        }
+      }
+    }
+  }
+}
+```
+
+### 5. Restart Clawdbot
+
+```bash
+clawdbot gateway restart
+```
+
+## Tools Available
+
+Once installed, your agent gets these tools:
+
+| Tool | Description |
+|------|-------------|
+| `recall_conversation` | Get messages from a specific date |
+| `recall_date_range` | Get messages across a date range |
+| `search_history` | Search all messages by keyword |
+| `memory_stats` | Show logging statistics |
+
+## CLI Commands
+
+```bash
+clawdbot supamem stats          # Show stats
+clawdbot supamem recall 2026-01-15   # Get messages from date
+clawdbot supamem search "iPad"  # Search by keyword
+```
+
+## Database Schema
+
+The plugin uses these tables:
+
+- `sessions` — Conversation sessions with metadata
+- `messages` — Every message with role, content, timestamp
+- `memories` — (Optional) Long-term memories with embeddings
+- `entities` — (Optional) Knowledge graph entries
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `supabase.url` | string | required | Supabase project URL |
+| `supabase.anonKey` | string | required | Supabase anon/service key |
+| `agentId` | string | "default" | Agent identifier for multi-agent setups |
+
+## How it works
+
+1. **Session start**: Creates a new session when conversation begins
+2. **Message logging**: Captures every user and assistant message
+3. **Session end**: Closes session when conversation ends
+4. **Recall**: SQL queries for date/keyword-based retrieval
+
+No embeddings or vector search required — just simple, reliable PostgreSQL queries.
+
+## Future Plans
+
+- [ ] Vector search with pgvector (semantic similarity)
+- [ ] Auto-summarization of long conversations
+- [ ] Entity extraction (people, places, things)
+- [ ] npm package for easy installation
+
+## License
+
+MIT
+
+## Author
+
+Built by an AI agent for [Clawdbot](https://github.com/clawdbot/clawdbot).

package/migrations/001_initial.sql

@@ -0,0 +1,153 @@
+-- OpenClaw Memory - Initial Schema
+-- Run this in your Supabase SQL editor
+
+-- Enable vector extension for semantic search
+CREATE EXTENSION IF NOT EXISTS vector;
+
+-- Sessions: Every conversation gets a session
+CREATE TABLE IF NOT EXISTS sessions (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  agent_id TEXT NOT NULL,
+  user_id TEXT,
+  channel TEXT,
+  started_at TIMESTAMPTZ DEFAULT NOW(),
+  ended_at TIMESTAMPTZ,
+  summary TEXT,
+  metadata JSONB DEFAULT '{}'
+);
+
+CREATE INDEX IF NOT EXISTS sessions_agent_id_idx ON sessions(agent_id);
+CREATE INDEX IF NOT EXISTS sessions_user_id_idx ON sessions(user_id);
+CREATE INDEX IF NOT EXISTS sessions_started_at_idx ON sessions(started_at DESC);
+
+-- Messages: Every message in every session
+CREATE TABLE IF NOT EXISTS messages (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  session_id UUID REFERENCES sessions(id) ON DELETE CASCADE,
+  role TEXT NOT NULL CHECK (role IN ('user', 'assistant', 'system', 'tool')),
+  content TEXT NOT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  token_count INT,
+  metadata JSONB DEFAULT '{}'
+);
+
+CREATE INDEX IF NOT EXISTS messages_session_id_idx ON messages(session_id);
+CREATE INDEX IF NOT EXISTS messages_created_at_idx ON messages(created_at);
+
+-- Memories: Long-term memories extracted from sessions
+CREATE TABLE IF NOT EXISTS memories (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  agent_id TEXT NOT NULL,
+  user_id TEXT,
+  category TEXT,
+  content TEXT NOT NULL,
+  importance FLOAT DEFAULT 0.5 CHECK (importance >= 0 AND importance <= 1),
+  source_session_id UUID REFERENCES sessions(id),
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW(),
+  expires_at TIMESTAMPTZ,
+  embedding VECTOR(1536),
+  metadata JSONB DEFAULT '{}'
+);
+
+CREATE INDEX IF NOT EXISTS memories_agent_id_idx ON memories(agent_id);
+CREATE INDEX IF NOT EXISTS memories_user_id_idx ON memories(user_id);
+CREATE INDEX IF NOT EXISTS memories_category_idx ON memories(category);
+CREATE INDEX IF NOT EXISTS memories_importance_idx ON memories(importance DESC);
+CREATE INDEX IF NOT EXISTS memories_created_at_idx ON memories(created_at DESC);
+
+-- Vector similarity index (for semantic search)
+CREATE INDEX IF NOT EXISTS memories_embedding_idx ON memories 
+  USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
+
+-- Entities: People, places, things the agent knows about
+CREATE TABLE IF NOT EXISTS entities (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  agent_id TEXT NOT NULL,
+  entity_type TEXT NOT NULL,
+  name TEXT NOT NULL,
+  aliases TEXT[],
+  description TEXT,
+  properties JSONB DEFAULT '{}',
+  first_seen_at TIMESTAMPTZ DEFAULT NOW(),
+  last_seen_at TIMESTAMPTZ DEFAULT NOW(),
+  mention_count INT DEFAULT 1,
+  embedding VECTOR(1536),
+  
+  UNIQUE(agent_id, entity_type, name)
+);
+
+CREATE INDEX IF NOT EXISTS entities_agent_id_idx ON entities(agent_id);
+CREATE INDEX IF NOT EXISTS entities_type_idx ON entities(entity_type);
+CREATE INDEX IF NOT EXISTS entities_name_idx ON entities(name);
+
+-- Tasks: Persistent task tracking
+CREATE TABLE IF NOT EXISTS tasks (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  agent_id TEXT NOT NULL,
+  user_id TEXT,
+  title TEXT NOT NULL,
+  description TEXT,
+  status TEXT DEFAULT 'pending' CHECK (status IN ('pending', 'in_progress', 'blocked', 'done')),
+  priority INT DEFAULT 0,
+  due_at TIMESTAMPTZ,
+  completed_at TIMESTAMPTZ,
+  source_session_id UUID REFERENCES sessions(id),
+  parent_task_id UUID REFERENCES tasks(id),
+  metadata JSONB DEFAULT '{}',
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS tasks_agent_id_idx ON tasks(agent_id);
+CREATE INDEX IF NOT EXISTS tasks_user_id_idx ON tasks(user_id);
+CREATE INDEX IF NOT EXISTS tasks_status_idx ON tasks(status);
+CREATE INDEX IF NOT EXISTS tasks_priority_idx ON tasks(priority DESC);
+CREATE INDEX IF NOT EXISTS tasks_due_at_idx ON tasks(due_at);
+
+-- Learnings: Self-improvement records
+CREATE TABLE IF NOT EXISTS learnings (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  agent_id TEXT NOT NULL,
+  category TEXT NOT NULL CHECK (category IN ('error', 'correction', 'improvement', 'capability_gap')),
+  trigger TEXT NOT NULL,
+  lesson TEXT NOT NULL,
+  action TEXT,
+  severity TEXT DEFAULT 'info' CHECK (severity IN ('info', 'warning', 'critical')),
+  source_session_id UUID REFERENCES sessions(id),
+  applied_count INT DEFAULT 0,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  metadata JSONB DEFAULT '{}'
+);
+
+CREATE INDEX IF NOT EXISTS learnings_agent_id_idx ON learnings(agent_id);
+CREATE INDEX IF NOT EXISTS learnings_category_idx ON learnings(category);
+CREATE INDEX IF NOT EXISTS learnings_severity_idx ON learnings(severity);
+
+-- Function to update updated_at timestamp
+CREATE OR REPLACE FUNCTION update_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.updated_at = NOW();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+-- Triggers for updated_at
+CREATE TRIGGER memories_updated_at
+  BEFORE UPDATE ON memories
+  FOR EACH ROW
+  EXECUTE FUNCTION update_updated_at();
+
+CREATE TRIGGER tasks_updated_at
+  BEFORE UPDATE ON tasks
+  FOR EACH ROW
+  EXECUTE FUNCTION update_updated_at();
+
+-- Row Level Security (optional - enable if using Supabase auth)
+-- ALTER TABLE sessions ENABLE ROW LEVEL SECURITY;
+-- ALTER TABLE messages ENABLE ROW LEVEL SECURITY;
+-- ALTER TABLE memories ENABLE ROW LEVEL SECURITY;
+-- ALTER TABLE entities ENABLE ROW LEVEL SECURITY;
+-- ALTER TABLE tasks ENABLE ROW LEVEL SECURITY;
+-- ALTER TABLE learnings ENABLE ROW LEVEL SECURITY;

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';