@shadowforge0/aquifer-memory 0.4.1 → 0.6.0

package/README.md

@@ -4,7 +4,7 @@
 
 **PG-native long-term memory for AI agents**
 
-*Turn-level embedding, hybrid RRF ranking, trust scoring, entity intersection, knowledge graph — all on PostgreSQL + pgvector.*
+*Turn-level embedding, hybrid RRF ranking, trust scoring, entity intersection, knowledge graph, entity scoping — all on PostgreSQL + pgvector.*
 
 [![npm version](https://img.shields.io/npm/v/@shadowforge0/aquifer-memory)](https://www.npmjs.com/package/@shadowforge0/aquifer-memory)
 [![PostgreSQL 15+](https://img.shields.io/badge/PostgreSQL-15%2B-336791)](https://www.postgresql.org/)
@@ -68,19 +68,19 @@ npm install @shadowforge0/aquifer-memory
 const { createAquifer } = require('@shadowforge0/aquifer-memory');
 
 const aquifer = createAquifer({
+  db: 'postgresql://user:pass@localhost:5432/mydb',  // connection string or pg.Pool
   schema: 'memory',                    // PG schema name (default: 'aquifer')
-  pg: {
-    connectionString: 'postgresql://user:pass@localhost:5432/mydb',
-  },
-  embedder: {
-    baseURL: 'http://localhost:11434/v1',   // Ollama
-    model: 'bge-m3',
-    apiKey: 'ollama',
+  tenantId: 'default',                 // multi-tenant isolation
+  embed: {
+    fn: async (texts) => embeddings,   // your embedding function
+    dim: 1024,                         // optional dimension hint
   },
   llm: {
-    baseURL: 'https://api.openai.com/v1',
-    model: 'gpt-4o-mini',
-    apiKey: process.env.OPENAI_API_KEY,
+    fn: async (prompt) => text,        // your LLM function (for built-in summarize)
+  },
+  entities: {
+    enabled: true,
+    scope: 'my-app',                   // entity namespace (default: 'default')
   },
 });
 
@@ -88,26 +88,36 @@ const aquifer = createAquifer({
 await aquifer.migrate();
 ```
 
-### Ingest a session
+### Write path: commit + enrich
 
 ```javascript
-await aquifer.ingest({
-  sessionId: 'conv-001',
+// 1. Store the session
+await aquifer.commit('conv-001', [
+  { role: 'user', content: 'Let me tell you about our new auth approach...' },
+  { role: 'assistant', content: 'Got it. So the plan is...' },
+], { agentId: 'main' });
+
+// 2. Enrich: summarize + embed turns + extract entities
+const result = await aquifer.enrich('conv-001', {
   agentId: 'main',
-  messages: [
-    { role: 'user', content: 'Let me tell you about our new auth approach...' },
-    { role: 'assistant', content: 'Got it. So the plan is...' },
-  ],
+  // Optional: bring your own summarize pipeline
+  summaryFn: async (msgs) => ({ summaryText, structuredSummary, entityRaw }),
+  entityParseFn: (text) => [{ name, normalizedName, type, aliases }],
+  // Optional: post-commit hook for downstream processing
+  postProcess: async (ctx) => {
+    // ctx contains session, summary, embedding, parsedEntities, etc.
+  },
 });
-// Stores session → generates summary → creates turn embeddings → extracts entities
 ```
 
-### Recall
+### Read path: recall
 
 ```javascript
 const results = await aquifer.recall('auth middleware decision', {
   agentId: 'main',
   limit: 5,
+  entities: ['auth-middleware'],       // optional: entity-aware search
+  entityMode: 'all',                   // 'any' (boost) or 'all' (hard filter)
 });
 // Returns ranked sessions with scores, using 3-way RRF fusion
 ```
@@ -257,109 +267,150 @@ Pass `schema: 'my_app'` to `createAquifer()` and all tables live under that Post
 
 ### `createAquifer(config)`
 
-Returns an Aquifer instance with the following methods:
+Returns an Aquifer instance. Config:
+
+```javascript
+{
+  db,          // pg connection string or Pool instance (required)
+  schema,      // PG schema name (default: 'aquifer')
+  tenantId,    // multi-tenant key (default: 'default')
+  embed: { fn, dim },      // embedding function (required for recall)
+  llm: { fn },             // LLM function (required for built-in summarize)
+  entities: {
+    enabled,               // enable KG (default: false)
+    scope,                 // entity namespace (default: 'default')
+    mergeCall,             // merge entity extraction into summary LLM call (default: true)
+  },
+  rank: { rrf, timeDecay, access, entityBoost },  // weight overrides
+}
+```
 
 #### `aquifer.migrate()`
 
-Runs SQL migrations (idempotent). Creates tables, indexes, and extensions.
+Runs SQL migrations (idempotent). Creates tables, indexes, triggers, and extensions.
 
-#### `aquifer.ingest(options)`
+#### `aquifer.commit(sessionId, messages, opts)`
 
-Ingests a session: stores messages, generates summary, creates turn embeddings, extracts entities.
+Stores a session. Returns `{ id, sessionId, isNew }`.
 
 ```javascript
-await aquifer.ingest({
-  sessionId: 'unique-id',
+await aquifer.commit('session-001', messages, {
   agentId: 'main',
-  source: 'api',                // optional, default 'api'
-  messages: [{ role, content }],
-  tenantId: 'default',          // optional
-  model: 'gpt-4o',             // optional metadata
-  tokensIn: 1500,              // optional
-  tokensOut: 800,              // optional
+  source: 'api',
+  sessionKey: 'optional-key',
+  model: 'gpt-4o',
+  tokensIn: 1500,
+  tokensOut: 800,
+  startedAt: isoString,
+  lastMessageAt: isoString,
 });
 ```
 
-#### `aquifer.recall(query, options)`
+#### `aquifer.enrich(sessionId, opts)`
 
-Hybrid search across sessions.
+Enriches a committed session: summarize, embed turns, extract entities. Uses optimistic locking with stale-reclaim (sessions stuck processing > 10 min are reclaimable).
+
+```javascript
+const result = await aquifer.enrich('session-001', {
+  agentId: 'main',
+  summaryFn,          // custom summarize pipeline (bypasses built-in LLM)
+  entityParseFn,      // custom entity parser
+  postProcess,        // async callback after tx commit
+  model: 'override',  // model metadata override
+  skipSummary: false,
+  skipTurnEmbed: false,
+  skipEntities: false,
+});
+// Returns: { summary, turnsEmbedded, entitiesFound, warnings, effectiveModel, postProcessError }
+```
+
+**postProcess hook**: runs after transaction commit, receives full context (session, summary, embedding, parsedEntities, etc.). Best-effort, at-most-once.
+
+#### `aquifer.recall(query, opts)`
+
+Hybrid search across sessions using 3-way RRF.
 
 ```javascript
 const results = await aquifer.recall('search query', {
   agentId: 'main',
-  limit: 10,                    // max results
-  entities: ['postgres', 'migration'],  // optional: explicit entity names
+  limit: 10,
+  entities: ['postgres', 'migration'],
   entityMode: 'all',            // 'any' (default) or 'all'
-  weights: {                    // optional: override ranking weights
-    rrf: 0.65,
-    timeDecay: 0.25,
-    access: 0.10,
-    entityBoost: 0.18,
-    openLoop: 0.08,
-  },
+  weights: { rrf, timeDecay, access, entityBoost },
 });
 // Returns: [{ sessionId, score, trustScore, summaryText, matchedTurnText, _debug, ... }]
 ```
 
-#### `aquifer.feedback(sessionId, options)`
+#### `aquifer.feedback(sessionId, opts)`
 
-Records explicit trust feedback on a session.
+Records trust feedback. Returns `{ trustBefore, trustAfter, verdict }`.
 
 ```javascript
 await aquifer.feedback('session-id', {
   verdict: 'helpful',   // or 'unhelpful'
-  agentId: 'main',      // optional
-  note: 'reason',       // optional
+  agentId: 'main',
+  note: 'reason',
 });
-// Returns: { trustBefore, trustAfter, verdict }
 ```
 
-#### `aquifer.enrich(sessionId, options)`
-
-Re-processes an existing session: regenerate summary, embeddings, and entities.
-
 #### `aquifer.close()`
 
-Closes the PostgreSQL connection pool.
+Closes the PostgreSQL connection pool (only if Aquifer created it).
 
 ---
 
 ## Configuration
 
+Aquifer takes a `db` connection (string or `pg.Pool`), plus optional `embed` and `llm` functions:
+
 ```javascript
 createAquifer({
-  // PostgreSQL schema name (all tables created under this schema)
-  schema: 'aquifer',
-
-  // PostgreSQL connection
-  pg: {
-    connectionString: 'postgresql://...',
-    // or individual: host, port, database, user, password
-    max: 10,  // pool size
-  },
-
-  // Embedding provider (any OpenAI-compatible API)
-  embedder: {
-    baseURL: 'http://localhost:11434/v1',
-    model: 'bge-m3',
-    apiKey: 'ollama',
-    dimensions: 1024,           // optional
-    timeout: 30000,             // ms, default 30s
+  db: 'postgresql://user:pass@localhost/mydb',  // or an existing pg.Pool
+  schema: 'aquifer',           // PG schema (default: 'aquifer')
+  tenantId: 'default',         // multi-tenant key
+  embed: {
+    fn: myEmbedFn,             // async (texts: string[]) => number[][]
+    dim: 1024,                 // optional dimension hint
   },
-
-  // LLM for summarization & entity extraction
   llm: {
-    baseURL: 'https://api.openai.com/v1',
-    model: 'gpt-4o-mini',
-    apiKey: process.env.OPENAI_API_KEY,
-    timeout: 60000,             // ms, default 60s
+    fn: myLlmFn,               // async (prompt: string) => string
+  },
+  entities: {
+    enabled: true,             // enable KG (default: false)
+    scope: 'my-app',           // entity namespace — decoupled from agentId
+    mergeCall: true,           // merge entity extraction into summary prompt
+  },
+  rank: {
+    rrf: 0.65,                 // FTS + embedding fusion weight
+    timeDecay: 0.25,           // recency weight
+    access: 0.10,              // access frequency weight
+    entityBoost: 0.18,         // entity match boost
   },
-
-  // Tenant isolation
-  tenantId: 'default',
 });
 ```
 
+### Entity Scope
+
+`entities.scope` defines the namespace for entity identity. The unique constraint is `(tenant_id, normalized_name, entity_scope)` — the same entity name in different scopes creates separate entities. This decouples entity identity from `agentId`, allowing multiple agents to share an entity namespace.
+
+Fallback chain: `config.entities.scope` → `'default'`.
+
+### Consumers (CLI, MCP, OpenClaw plugin)
+
+For consumer-based setup using environment variables instead of code:
+
+```bash
+export DATABASE_URL="postgresql://..."
+export AQUIFER_EMBED_BASE_URL="http://localhost:11434/v1"
+export AQUIFER_EMBED_MODEL="bge-m3"
+export AQUIFER_ENTITIES_ENABLED=true
+
+aquifer migrate
+aquifer recall "search query" --limit 5
+aquifer backfill --concurrency 3
+aquifer stats --json
+```
+
 ---
 
 ## Database Schema
@@ -378,12 +429,12 @@ Key indexes: GIN on messages, GiST on `tsvector`, ivfflat on embeddings, B-tree
 
 | Table | Purpose |
 |-------|---------|
-| `entities` | Normalized named entities with type, aliases, frequency, optional embedding |
+| `entities` | Normalized named entities with type, aliases, frequency, entity_scope, optional embedding |
 | `entity_mentions` | Entity × session join with mention count and context |
 | `entity_relations` | Co-occurrence edges (undirected, `CHECK src < dst`) |
 | `entity_sessions` | Entity-session association for boost scoring |
 
-Key indexes: trigram on entity names, GiST on embeddings, composite on tenant/agent.
+Key indexes: trigram on entity names, GiST on embeddings, unique on `(tenant_id, normalized_name, entity_scope)`.
 
 ### 003-trust-feedback.sql
 

package/consumers/cli.js

@@ -344,7 +344,12 @@ Options:
   }
 }
 
-main().catch(err => {
-  console.error(`aquifer: ${err.message}`);
-  process.exit(1);
-});
+// Export for testing; execute only when run directly
+module.exports = { parseArgs };
+
+if (require.main === module) {
+  main().catch(err => {
+    console.error(`aquifer: ${err.message}`);
+    process.exit(1);
+  });
+}

package/consumers/mcp.js

@@ -69,7 +69,7 @@ async function main() {
 
   const server = new McpServer({
     name: 'aquifer-memory',
-    version: '0.3.1',
+    version: '0.6.0',
   });
 
   server.tool(

package/core/aquifer.js

@@ -79,6 +79,7 @@ function createAquifer(config) {
   let entitiesEnabled = config.entities && config.entities.enabled === true;
   const mergeCall = config.entities && config.entities.mergeCall !== undefined ? config.entities.mergeCall : true;
   const entityPromptFn = config.entities && config.entities.prompt ? config.entities.prompt : null;
+  const entityScope = (config.entities && config.entities.scope) || 'default';
 
   // Rank weights
   const rankWeights = {
@@ -259,12 +260,19 @@ function createAquifer(config) {
       const customSummaryFn = opts.summaryFn || null;      // async (messages) => { summaryText, structuredSummary, entityRaw?, extra? }
       const customEntityParseFn = opts.entityParseFn || null; // (text) => [{ name, normalizedName, aliases, type }]
 
+      // Post-commit hook: runs after tx commit + client release. Best-effort, at-most-once.
+      const postProcess = opts.postProcess || null;  // async (ctx) => void
+      const optModel = 'model' in opts ? opts.model : undefined; // undefined = no override
+
       // 1. Optimistic lock: claim session for processing
+      //    Also reclaim stale 'processing' sessions (stuck > 10 min = likely killed process)
+      const STALE_MINUTES = 10;
       const claimResult = await pool.query(
         `UPDATE ${qi(schema)}.sessions
-        SET processing_status = 'processing'
+        SET processing_status = 'processing', processing_started_at = NOW()
         WHERE session_id = $1 AND agent_id = $2 AND tenant_id = $3
-          AND processing_status IN ('pending', 'failed')
+          AND (processing_status IN ('pending', 'failed')
+               OR (processing_status = 'processing' AND (processing_started_at IS NULL OR processing_started_at < NOW() - INTERVAL '${STALE_MINUTES} minutes')))
         RETURNING *`,
         [sessionId, agentId, tenantId]
       );
@@ -361,7 +369,7 @@ function createAquifer(config) {
             schema, tenantId, agentId, sessionId,
             summaryText: summaryResult.summaryText,
             structuredSummary: summaryResult.structuredSummary,
-            model: session.model || null, sourceHash: null,
+            model: (optModel !== undefined ? optModel : session.model) || null, sourceHash: null,
             msgCount: normalized.length,
             userCount: turns.length,
             assistantCount: normalized.filter(m => m.role === 'assistant').length,
@@ -394,6 +402,7 @@ function createAquifer(config) {
                 aliases: ent.aliases,
                 type: ent.type,
                 agentId,
+                entityScope,
                 createdBy: 'aquifer',
                 occurredAt: session.started_at ? new Date(session.started_at).toISOString() : null,
               });
@@ -453,6 +462,41 @@ function createAquifer(config) {
         client.release();
       }
 
+      // Post-commit hook: best-effort, at-most-once, no retry.
+      // Runs after tx commit + client release. Failure does not affect session status.
+      const effectiveModel = (optModel !== undefined ? optModel : session.model) || null;
+      let postProcessError = null;
+      if (postProcess) {
+        try {
+          await postProcess({
+            session: {
+              id: session.id,
+              sessionId,
+              agentId,
+              model: session.model || null,
+              source: session.source || null,
+              startedAt: session.started_at || null,
+              endedAt: session.ended_at || null,
+            },
+            effectiveModel,
+            summary: summaryResult
+              ? { summaryText: summaryResult.summaryText, structuredSummary: summaryResult.structuredSummary }
+              : null,
+            embedding: summaryEmbedding,
+            turnVectors,
+            extra,
+            normalized,
+            parsedEntities,
+            skipped: { summary: skipSummary, entities: skipEntities, turns: skipTurnEmbed },
+            turnsEmbedded,
+            entitiesFound,
+            warnings: [...warnings],  // defensive copy — caller cannot mutate enrich warnings
+          });
+        } catch (e) {
+          postProcessError = e;
+        }
+      }
+
       return {
         summary: summaryResult ? summaryResult.summaryText : null,
         structuredSummary: summaryResult ? summaryResult.structuredSummary : null,
@@ -460,6 +504,15 @@ function createAquifer(config) {
         entitiesFound,
         warnings,
         extra,
+        session: {
+          id: session.id,
+          sessionId,
+          agentId,
+          model: session.model || null,
+          source: session.source || null,
+        },
+        effectiveModel,
+        postProcessError,
       };
     },
 
@@ -501,7 +554,7 @@ function createAquifer(config) {
       if (explicitEntities && explicitEntities.length > 0) {
 
         const resolved = await entity.resolveEntities(pool, {
-          schema, tenantId, names: explicitEntities, agentId,
+          schema, tenantId, names: explicitEntities, entityScope,
         });
 
         if (resolved.length === 0) return [];
@@ -546,7 +599,7 @@ function createAquifer(config) {
         // No explicit entities: existing query-text-based entity boost
         try {
           const matchedEntities = await entity.searchEntities(pool, {
-            schema, tenantId, query, agentId, limit: 10,
+            schema, tenantId, query, entityScope, limit: 10,
           });
 
           if (matchedEntities.length > 0) {

package/core/entity.js

@@ -141,21 +141,23 @@ async function upsertEntity(pool, {
   type = 'other',
   status = 'active',
   agentId = 'main',
+  entityScope,
   createdBy,
   metadata = {},
   embedding,
   occurredAt,
 }) {
+  const scope = entityScope || agentId || 'default';
   const normalizedAliases = aliases.map(a => normalizeEntityName(a)).filter(Boolean);
   const embStr = embedding ? vecToStr(embedding) : null;
   const ts = occurredAt || new Date().toISOString();
 
   const result = await pool.query(
     `INSERT INTO ${qi(schema)}.entities
-      (tenant_id, name, normalized_name, aliases, type, status, agent_id,
+      (tenant_id, name, normalized_name, aliases, type, status, agent_id, entity_scope,
        created_by, metadata, embedding, first_seen_at, last_seen_at, frequency)
-    VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9::jsonb, $10::vector, $11, $11, 1)
-    ON CONFLICT (tenant_id, normalized_name, agent_id) DO UPDATE SET
+    VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10::jsonb, $11::vector, $12, $12, 1)
+    ON CONFLICT (tenant_id, normalized_name, entity_scope) DO UPDATE SET
       frequency    = ${qi(schema)}.entities.frequency + 1,
       aliases      = ARRAY(SELECT DISTINCT unnest(${qi(schema)}.entities.aliases || EXCLUDED.aliases)),
       last_seen_at = GREATEST(${qi(schema)}.entities.last_seen_at, EXCLUDED.last_seen_at),
@@ -164,7 +166,7 @@ async function upsertEntity(pool, {
     RETURNING id, (xmax = 0) AS is_new`,
     [
       tenantId, name, normalizedName, normalizedAliases,
-      type, status, agentId,
+      type, status, agentId, scope,
       createdBy || null,
       JSON.stringify(metadata),
       embStr,
@@ -276,6 +278,7 @@ async function searchEntities(pool, {
   tenantId,
   query,
   agentId,
+  entityScope,
   limit = 10,
   similarityThreshold = 0.1,
 }) {
@@ -284,11 +287,13 @@ async function searchEntities(pool, {
   if (!normQ) return [];
 
   const escaped = _escapeIlike(normQ);
+  // Use entityScope if provided, fall back to agentId for backward compat
+  const scopeFilter = entityScope || agentId || null;
 
   const result = await pool.query(
     `SELECT
       id, name, normalized_name, aliases, type, status, frequency, agent_id,
-      last_seen_at, metadata,
+      entity_scope, last_seen_at, metadata,
       similarity(normalized_name, $1) AS name_sim
     FROM ${qi(schema)}.entities
     WHERE status = 'active'
@@ -298,10 +303,10 @@ async function searchEntities(pool, {
         OR normalized_name ILIKE '%' || $4 || '%' ESCAPE '\\'
         OR $5 = ANY(aliases)
       )
-      AND ($6::text IS NULL OR agent_id = $6)
+      AND ($6::text IS NULL OR entity_scope = $6)
     ORDER BY name_sim DESC, frequency DESC
     LIMIT $7`,
-    [normQ, tenantId, similarityThreshold, escaped, normQ, agentId || null, clampedLimit]
+    [normQ, tenantId, similarityThreshold, escaped, normQ, scopeFilter, clampedLimit]
   );
 
   return result.rows;
@@ -353,9 +358,12 @@ async function resolveEntities(pool, {
   tenantId,
   names,
   agentId = null,
+  entityScope,
   threshold = 0.1,
 }) {
   if (!names || names.length === 0) return [];
+  // Use entityScope if provided, fall back to agentId for backward compat
+  const scopeFilter = entityScope || agentId || null;
 
   const seen = new Map();
   const results = [];
@@ -376,10 +384,10 @@ async function resolveEntities(pool, {
           OR normalized_name = $2
           OR $2 = ANY(aliases)
         )
-        AND ($4::text IS NULL OR agent_id = $4)
+        AND ($4::text IS NULL OR entity_scope = $4)
       ORDER BY similarity(normalized_name, $2) DESC, frequency DESC
       LIMIT 1`,
-      [tenantId, normQ, threshold, agentId || null]
+      [tenantId, normQ, threshold, scopeFilter]
     );
 
     if (result.rows[0]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shadowforge0/aquifer-memory",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "PG-native long-term memory for AI agents. Turn-level embedding, hybrid RRF ranking, optional knowledge graph. Includes CLI, MCP server, and OpenClaw plugin.",
   "main": "index.js",
   "files": [

package/schema/001-base.sql

@@ -24,10 +24,11 @@ CREATE TABLE IF NOT EXISTS ${schema}.sessions (
   started_at         TIMESTAMPTZ,
   ended_at           TIMESTAMPTZ,
   last_message_at    TIMESTAMPTZ,
-  processing_status  TEXT         NOT NULL DEFAULT 'pending',
-  processed_at       TIMESTAMPTZ,
-  processing_error   TEXT,
-  created_at         TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  processing_status    TEXT         NOT NULL DEFAULT 'pending',
+  processing_started_at TIMESTAMPTZ,
+  processed_at         TIMESTAMPTZ,
+  processing_error     TEXT,
+  created_at           TIMESTAMPTZ  NOT NULL DEFAULT now(),
   UNIQUE (tenant_id, agent_id, session_id)
 );
 

package/schema/002-entities.sql

@@ -20,16 +20,28 @@ CREATE TABLE IF NOT EXISTS ${schema}.entities (
                     CHECK (status IN ('active','merged','deleted')),
   frequency       INT          NOT NULL DEFAULT 1,
   agent_id        TEXT         NOT NULL DEFAULT 'main',
+  entity_scope    TEXT         NOT NULL DEFAULT 'default',
   created_by      TEXT,
   metadata        JSONB        NOT NULL DEFAULT '{}',
   embedding       vector,
   first_seen_at   TIMESTAMPTZ  NOT NULL DEFAULT now(),
-  last_seen_at    TIMESTAMPTZ  NOT NULL DEFAULT now(),
-  UNIQUE (tenant_id, normalized_name, agent_id)
+  last_seen_at    TIMESTAMPTZ  NOT NULL DEFAULT now()
 );
 
-CREATE INDEX IF NOT EXISTS idx_entities_tenant_agent
-  ON ${schema}.entities (tenant_id, agent_id);
+-- Migration: add entity_scope if missing (idempotent)
+-- For upgrades: backfill from agent_id so existing data keeps its scope
+ALTER TABLE ${schema}.entities ADD COLUMN IF NOT EXISTS entity_scope TEXT DEFAULT 'default';
+UPDATE ${schema}.entities SET entity_scope = agent_id WHERE entity_scope IS NULL OR entity_scope = 'default';
+ALTER TABLE ${schema}.entities ALTER COLUMN entity_scope SET NOT NULL;
+
+-- Unique constraint: entity identity is (tenant, name, scope)
+-- Drop legacy agent-based constraint if it exists
+DROP INDEX IF EXISTS ${schema}.idx_entities_tenant_name_agent;
+CREATE UNIQUE INDEX IF NOT EXISTS idx_entities_tenant_name_scope
+  ON ${schema}.entities (tenant_id, normalized_name, entity_scope);
+
+CREATE INDEX IF NOT EXISTS idx_entities_tenant_scope
+  ON ${schema}.entities (tenant_id, entity_scope);
 
 CREATE INDEX IF NOT EXISTS idx_entities_type
   ON ${schema}.entities (type);
@@ -44,7 +56,7 @@ CREATE INDEX IF NOT EXISTS idx_entities_aliases
   ON ${schema}.entities USING GIN (aliases);
 
 CREATE INDEX IF NOT EXISTS idx_entities_active
-  ON ${schema}.entities (tenant_id, agent_id, frequency DESC)
+  ON ${schema}.entities (tenant_id, entity_scope, frequency DESC)
   WHERE status = 'active';
 
 -- =========================================================================