@shadowforge0/aquifer-memory 0.7.0 → 0.9.0

package/README.md

@@ -32,7 +32,7 @@ Sessions, summaries, turn-level embeddings, entity graph — all live in one dat
 | **Ranking** | 3-way RRF: FTS + session embedding + turn embedding | Single vector similarity |
 | **Knowledge graph** | Built-in entity extraction & co-occurrence | Usually separate system |
 | **Multi-tenant** | `tenant_id` on every table, day-1 | Often an afterthought |
-| **Dependencies** | Just `pg` | Multiple SDKs |
+| **Dependencies** | `pg` + MCP SDK | Multiple SDKs |
 
 ### Before and after
 
@@ -48,97 +48,177 @@ Sessions, summaries, turn-level embeddings, entity graph — all live in one dat
 
 ---
 
-## Quick Start
+## Requirements
 
-### Prerequisites
+| Component | Required? | Purpose | Example |
+|-----------|-----------|---------|---------|
+| Node.js >= 18 | Yes | Runtime | — |
+| PostgreSQL 15+ | Yes | Storage for sessions, summaries, entities | Local, Docker, or managed |
+| pgvector extension | Yes | Vector similarity search | `CREATE EXTENSION vector;` (included in `pgvector/pgvector` Docker image) |
+| Embedding endpoint | Yes (for recall) | Turn + session embedding | Ollama `bge-m3`, OpenAI `text-embedding-3-small`, any OpenAI-compatible API |
+| LLM endpoint | Optional | Built-in summarization during `enrich` | Ollama, OpenRouter, OpenAI — or provide your own `summaryFn` |
+| `@modelcontextprotocol/sdk` + `zod` | Yes (for MCP server) | MCP protocol runtime | Included in dependencies — installed automatically |
 
-- Node.js >= 18
-- PostgreSQL 15+ with [pgvector](https://github.com/pgvector/pgvector) extension
-- An embedding API (OpenAI, Ollama, or any OpenAI-compatible endpoint)
+---
+
+## Quick Start (MCP Server)
+
+This gets you from zero to a working MCP memory server. For library API usage, see [API Reference](#api-reference) below.
 
-### Install
+### 1. Start the stack
+
+```bash
+docker compose up -d
+# Starts PostgreSQL 16 + pgvector and Ollama with bge-m3 (auto-pulled).
+# First run takes a few minutes while Ollama downloads the model.
+```
+
+Already have PostgreSQL + pgvector and an embedding endpoint? Skip this step.
+
+### 2. Install
 
 ```bash
 npm install @shadowforge0/aquifer-memory
 ```
 
-### Initialize
+### 3. Configure + verify
 
-```javascript
-const { createAquifer } = require('@shadowforge0/aquifer-memory');
+```bash
+export DATABASE_URL="postgresql://aquifer:aquifer@localhost:5432/aquifer"
+export AQUIFER_EMBED_BASE_URL="http://localhost:11434/v1"
+export AQUIFER_EMBED_MODEL="bge-m3"
 
-const aquifer = createAquifer({
-  db: 'postgresql://user:pass@localhost:5432/mydb',  // connection string or pg.Pool
-  schema: 'memory',                    // PG schema name (default: 'aquifer')
-  tenantId: 'default',                 // multi-tenant isolation
-  embed: {
-    fn: async (texts) => embeddings,   // your embedding function
-    dim: 1024,                         // optional dimension hint
-  },
-  llm: {
-    fn: async (prompt) => text,        // your LLM function (for built-in summarize)
-  },
-  entities: {
-    enabled: true,
-    scope: 'my-app',                   // entity namespace (default: 'default')
-  },
-});
+npx aquifer quickstart
+```
+
+`quickstart` runs migrations, commits a test session, embeds it, recalls it, and cleans up. If it prints `✓ Aquifer is working`, you're done.
 
-// Run migrations (safe to call multiple times)
-await aquifer.migrate();
+### 4. Start the MCP server
+
+```bash
+npx aquifer mcp
 ```
 
-### Write path: commit + enrich
+See [.env.example](.env.example) for all env vars, or [docs/setup.md](docs/setup.md) for the full setup guide.
 
-```javascript
-// 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',
-  // 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.
-  },
-});
+---
+
+## Environment Variables
+
+| Variable | Required? | Purpose | Example |
+|----------|-----------|---------|---------|
+| `DATABASE_URL` | Yes | PostgreSQL connection string | `postgresql://user:pass@localhost:5432/mydb` |
+| `AQUIFER_SCHEMA` | No | PG schema name (default: `aquifer`) | `memory` |
+| `AQUIFER_TENANT_ID` | No | Multi-tenant key (default: `default`) | `my-app` |
+| `AQUIFER_EMBED_BASE_URL` | Yes (for recall) | Embedding API base URL | `http://localhost:11434/v1` |
+| `AQUIFER_EMBED_MODEL` | Yes (for recall) | Embedding model name | `bge-m3` |
+| `AQUIFER_EMBED_API_KEY` | Provider-dependent | API key for hosted embedding providers | `sk-...` |
+| `AQUIFER_EMBED_DIM` | No | Embedding dimension override (auto-detected) | `1024` |
+| `AQUIFER_LLM_BASE_URL` | No | LLM API base URL (for built-in summarization) | `http://localhost:11434/v1` |
+| `AQUIFER_LLM_MODEL` | No | LLM model name | `llama3.1` |
+| `AQUIFER_LLM_API_KEY` | Provider-dependent | API key for hosted LLM providers | `sk-...` |
+| `AQUIFER_ENTITIES_ENABLED` | No | Enable knowledge graph (default: `false`) | `true` |
+| `AQUIFER_ENTITY_SCOPE` | No | Entity namespace (default: `default`) | `my-app` |
+| `AQUIFER_RERANK_ENABLED` | No | Enable cross-encoder reranking | `true` |
+| `AQUIFER_RERANK_PROVIDER` | No | Reranker provider: `tei`, `jina`, `openrouter` | `tei` |
+| `AQUIFER_RERANK_BASE_URL` | No | Reranker endpoint | `http://localhost:8080` |
+| `AQUIFER_AGENT_ID` | No | Default agent ID | `main` |
+
+Full env-to-config mapping is in [consumers/shared/config.js](consumers/shared/config.js).
+
+---
+
+## Host Integration
+
+MCP is the primary integration surface. Agent hosts connect to the Aquifer MCP server, which exposes four tools: `session_recall`, `session_feedback`, `memory_stats`, `memory_pending`.
+
+| Integration | Route | Status | When to use |
+|-------------|-------|--------|-------------|
+| MCP server | `consumers/mcp.js` | Primary | Claude Code, OpenClaw, Codex, any MCP-capable host |
+| Library API | `createAquifer()` | Primary | Backend apps, custom pipelines, direct Node.js usage |
+| CLI | `consumers/cli.js` | Secondary | Operations, debugging, manual recall/backfill |
+| OpenClaw plugin | `consumers/openclaw-plugin.js` | Compatibility only | Session capture via `before_reset` — not for tool delivery |
+
+### Claude Code
+
+Add to your project's `.claude.json` or user-level MCP config:
+
+```json
+{
+  "mcpServers": {
+    "aquifer": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/aquifer/consumers/mcp.js"],
+      "env": {
+        "DATABASE_URL": "postgresql://...",
+        "AQUIFER_EMBED_BASE_URL": "http://localhost:11434/v1",
+        "AQUIFER_EMBED_MODEL": "bge-m3"
+      }
+    }
+  }
+}
 ```
 
-### Read path: recall
+Tools appear as `mcp__aquifer__session_recall`, `mcp__aquifer__session_feedback`, etc.
 
-```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
+### OpenClaw
+
+Add to `openclaw.json` under `mcp.servers`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "aquifer": {
+        "command": "node",
+        "args": ["/path/to/aquifer/consumers/mcp.js"],
+        "env": {
+          "DATABASE_URL": "postgresql://...",
+          "AQUIFER_EMBED_BASE_URL": "http://localhost:11434/v1",
+          "AQUIFER_EMBED_MODEL": "bge-m3"
+        }
+      }
+    }
+  }
+}
 ```
 
+Tools materialize as `aquifer__session_recall`, `aquifer__session_feedback`, `aquifer__memory_stats`, `aquifer__memory_pending` (server name prefix added by the host).
+
+The OpenClaw plugin (`consumers/openclaw-plugin.js`) is retained for session capture via `before_reset` but is **not** the recommended tool delivery path. Use MCP.
+
+### Other MCP-capable hosts
+
+Any host that supports MCP stdio can connect the same way — point it at `node consumers/mcp.js` with the required env vars. The MCP server is the canonical external contract.
+
 ---
 
 ## Architecture
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│                    createAquifer (entry)                     │
-│         Config · Migration · Ingest · Recall · Enrich       │
-└────────┬──────────┬──────────┬──────────┬───────────────────┘
+┌──────────────────────────────────────────────────────────────┐
+│                     Agent Hosts                              │
+│   Claude Code · OpenClaw · Codex · OpenCode · ...            │
+└──────────────────────┬───────────────────────────────────────┘
+                       │ MCP (stdio or HTTP)
+┌──────────────────────▼───────────────────────────────────────┐
+│              Aquifer MCP Server (canonical API)               │
+│   session_recall · session_feedback · memory_stats · ...     │
+└──────────────────────┬───────────────────────────────────────┘
+                       │
+┌──────────────────────▼───────────────────────────────────────┐
+│                    createAquifer (engine)                     │
+│         Config · Migration · Ingest · Recall · Enrich        │
+└────────┬──────────┬──────────┬──────────┬────────────────────┘
          │          │          │          │
     ┌────▼───┐ ┌────▼────┐ ┌──▼───┐ ┌───▼──────────┐
     │storage │ │hybrid-  │ │entity│ │   pipeline/   │
     │  .js   │ │rank.js  │ │ .js  │ │summarize.js   │
     └────────┘ └─────────┘ └──────┘ │embed.js       │
          │                     │    │extract-ent.js │
-    ┌────▼───────────┐    ┌───▼──┐  └───────────────┘
-    │  PostgreSQL     │    │ LLM  │
+    ┌────▼───────────┐    ┌───▼──┐  │rerank.js      │
+    │  PostgreSQL     │    │ LLM  │  └───────────────┘
     │  + pgvector     │    │ API  │
     └────────────────┘    └──────┘
 
@@ -155,7 +235,7 @@ const results = await aquifer.recall('auth middleware decision', {
 
 | File | Purpose |
 |------|---------|
-| `index.js` | Entry point — exports `createAquifer`, `createEmbedder` |
+| `index.js` | Entry point — exports `createAquifer`, `createEmbedder`, `createReranker`, `normalizeSession` |
 | `core/aquifer.js` | Main facade: `migrate()`, `ingest()`, `recall()`, `enrich()` |
 | `core/storage.js` | Session/summary/turn CRUD, FTS search, embedding search |
 | `core/entity.js` | Entity upsert, mention tracking, relation graph, normalization |
@@ -163,6 +243,8 @@ const results = await aquifer.recall('auth middleware decision', {
 | `pipeline/summarize.js` | LLM-powered session summarization with structured output |
 | `pipeline/embed.js` | Embedding client (any OpenAI-compatible API) |
 | `pipeline/extract-entities.js` | LLM-powered entity extraction (12 types) |
+| `pipeline/rerank.js` | Cross-encoder reranking (TEI, Jina, OpenRouter) |
+| `pipeline/normalize/` | Session normalization for Claude Code / gateway noise |
 | `schema/001-base.sql` | DDL: sessions, summaries, turn_embeddings, FTS indexes |
 | `schema/002-entities.sql` | DDL: entities, mentions, relations, entity_sessions |
 | `schema/003-trust-feedback.sql` | DDL: trust_score column, session_feedback audit trail |
@@ -361,7 +443,9 @@ 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:
+Aquifer resolves config from three sources in priority order: config file → environment variables → programmatic overrides. See [consumers/shared/config.js](consumers/shared/config.js) for the full env-to-config mapping.
+
+Config file is auto-discovered at `aquifer.config.json` in the working directory, or set `AQUIFER_CONFIG=/path/to/config.json`.
 
 ```javascript
 createAquifer({
@@ -395,22 +479,6 @@ createAquifer({
 
 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
@@ -425,6 +493,8 @@ aquifer stats --json
 
 Key indexes: GIN on messages, GiST on `tsvector`, ivfflat on embeddings, B-tree on tenant/agent/timestamps.
 
+Note: the schema uses basic ivfflat indexes suitable for development and moderate-scale use. For large deployments (100k+ embeddings), consider adding HNSW indexes — this is a future optimization area, not included out of the box.
+
 ### 002-entities.sql
 
 | Table | Purpose |
@@ -446,15 +516,29 @@ Also adds `trust_score` column to `session_summaries` (default 0.5, range 0–1)
 
 ---
 
+## Troubleshooting
+
+**`error: type "vector" does not exist`** — pgvector extension is not installed. Run `CREATE EXTENSION IF NOT EXISTS vector;` as a superuser, or use the `pgvector/pgvector` Docker image which includes it.
+
+**`aquifer mcp requires @modelcontextprotocol/sdk and zod`** — These are now regular dependencies and should be installed automatically. If you see this error, run `npm install` again to ensure all deps are present.
+
+**Recall returns no results** — Make sure you've run `enrich` after `commit`. Raw sessions are not searchable until enriched (summarized + embedded). Check `aquifer stats` to see if summaries and turn embeddings exist.
+
+**OpenClaw tools not visible** — Use `mcp.servers.aquifer` in `openclaw.json`, not the plugin. Tools appear as `aquifer__session_recall` etc. The plugin (`consumers/openclaw-plugin.js`) is for session capture only.
+
+**Embedding provider connection refused** — Verify your `AQUIFER_EMBED_BASE_URL` is reachable. For local Ollama, make sure the server is running and the model is pulled (`ollama pull bge-m3`).
+
+---
+
 ## Dependencies
 
 | Package | Purpose |
 |---------|---------|
 | `pg` ≥ 8.13 | PostgreSQL client |
+| `@modelcontextprotocol/sdk` ≥ 1.29 | MCP server protocol |
+| `zod` ≥ 3.25 | Schema validation (MCP tools) |
 
-That's it. Aquifer has **one runtime dependency**.
-
-LLM and embedding calls use raw HTTP — no SDK required.
+LLM and embedding calls use raw HTTP — no additional SDK required.
 
 ---
 

package/consumers/cli.js

@@ -5,6 +5,7 @@
  * Aquifer CLI
  *
  * Usage:
+ *   aquifer quickstart                  Verify end-to-end setup
  *   aquifer migrate                     Run database migrations
  *   aquifer recall <query> [options]    Search sessions
  *   aquifer backfill [options]          Enrich pending sessions
@@ -14,7 +15,6 @@
  */
 
 const { createAquiferFromConfig } = require('./shared/factory');
-const { loadConfig } = require('./shared/config');
 
 // ---------------------------------------------------------------------------
 // Argument parser (minimal, no deps)
@@ -120,30 +120,12 @@ async function cmdBackfill(aquifer, args) {
   const skipTurnEmbed = !!args.flags['skip-turn-embed'];
   const skipEntities = !!args.flags['skip-entities'];
 
-  const config = aquifer._config || {};
-  const schema = config.schema || 'aquifer';
-  const tenantId = config.tenantId || 'default';
-  const pool = aquifer._pool;
-
-  if (!pool) {
-    console.error('Backfill requires direct pool access.');
-    process.exit(1);
-  }
+  const pending = await aquifer.getPendingSessions({ limit });
 
-  const qi = (id) => `"${id}"`;
-  const { rows } = await pool.query(`
-    SELECT session_id, agent_id, processing_status
-    FROM ${qi(schema)}.sessions
-    WHERE tenant_id = $1
-      AND processing_status IN ('pending', 'failed')
-    ORDER BY started_at DESC
-    LIMIT $2
-  `, [tenantId, limit]);
-
-  console.log(`Found ${rows.length} sessions to backfill${dryRun ? ' (dry-run)' : ''}`);
+  console.log(`Found ${pending.length} sessions to backfill${dryRun ? ' (dry-run)' : ''}`);
 
   let enriched = 0, failed = 0;
-  for (const row of rows) {
+  for (const row of pending) {
     if (dryRun) {
       console.log(`  [dry-run] ${row.session_id} (${row.agent_id}) status=${row.processing_status}`);
       continue;
@@ -164,40 +146,12 @@ async function cmdBackfill(aquifer, args) {
     }
   }
 
-  console.log(`\nDone. enriched=${enriched} failed=${failed} total=${rows.length}`);
+  console.log(`\nDone. enriched=${enriched} failed=${failed} total=${pending.length}`);
   if (failed > 0) process.exitCode = 2;
 }
 
 async function cmdStats(aquifer, args) {
-  const config = aquifer._config || {};
-  const schema = config.schema || 'aquifer';
-  const tenantId = config.tenantId || 'default';
-  const pool = aquifer._pool;
-
-  if (!pool) {
-    console.error('Stats requires direct pool access.');
-    process.exit(1);
-  }
-
-  const qi = (id) => `"${id}"`;
-  const [sessions, summaries, turns, entities] = await Promise.all([
-    pool.query(`SELECT processing_status, COUNT(*)::int as count FROM ${qi(schema)}.sessions WHERE tenant_id = $1 GROUP BY processing_status`, [tenantId]),
-    pool.query(`SELECT COUNT(*)::int as count FROM ${qi(schema)}.session_summaries WHERE tenant_id = $1`, [tenantId]),
-    pool.query(`SELECT COUNT(*)::int as count FROM ${qi(schema)}.turn_embeddings WHERE tenant_id = $1`, [tenantId]),
-    pool.query(`SELECT COUNT(*)::int as count FROM ${qi(schema)}.entities WHERE tenant_id = $1`, [tenantId]).catch(() => ({ rows: [{ count: 0 }] })),
-  ]);
-
-  const timeRange = await pool.query(`SELECT MIN(started_at) as earliest, MAX(started_at) as latest FROM ${qi(schema)}.sessions WHERE tenant_id = $1`, [tenantId]);
-
-  const stats = {
-    sessions: Object.fromEntries(sessions.rows.map(r => [r.processing_status, r.count])),
-    sessionTotal: sessions.rows.reduce((s, r) => s + r.count, 0),
-    summaries: summaries.rows[0]?.count || 0,
-    turnEmbeddings: turns.rows[0]?.count || 0,
-    entities: entities.rows[0]?.count || 0,
-    earliest: timeRange.rows[0]?.earliest || null,
-    latest: timeRange.rows[0]?.latest || null,
-  };
+  const stats = await aquifer.getStats();
 
   if (args.flags.json) {
     console.log(JSON.stringify(stats, null, 2));
@@ -210,35 +164,73 @@ async function cmdStats(aquifer, args) {
   }
 }
 
-async function cmdExport(aquifer, args) {
-  const config = aquifer._config || {};
-  const schema = config.schema || 'aquifer';
-  const tenantId = config.tenantId || 'default';
-  const pool = aquifer._pool;
-  const output = args.flags.output || null;
-  const limit = parseInt(args.flags.limit || '1000', 10);
+async function cmdQuickstart(aquifer) {
+  console.log('Aquifer quickstart — verifying end-to-end setup.\n');
 
-  if (!pool) {
-    console.error('Export requires direct pool access.');
-    process.exit(1);
-  }
+  // 1. Migrate
+  console.log('1/5  Running migrations...');
+  await aquifer.migrate();
+  console.log('     OK\n');
+
+  // 2. Commit
+  const sessionId = `quickstart-${Date.now()}`;
+  console.log('2/5  Committing test session...');
+  await aquifer.commit(sessionId, [
+    { role: 'user', content: 'We decided to use PostgreSQL with pgvector for the AI memory store instead of a separate vector database.' },
+    { role: 'assistant', content: 'Good choice. PG gives us ACID transactions, full-text search, and vector similarity all in one place.' },
+    { role: 'user', content: 'The main advantage is turn-level embedding — we can find the exact moment a decision was made.' },
+  ], { agentId: 'quickstart', source: 'quickstart' });
+  console.log('     OK\n');
+
+  // 3. Enrich (skip summary — LLM may not be configured)
+  console.log('3/5  Enriching (turn embeddings)...');
+  const enrichResult = await aquifer.enrich(sessionId, {
+    agentId: 'quickstart',
+    skipSummary: true,
+    skipEntities: true,
+  });
+  console.log(`     OK — ${enrichResult.turnsEmbedded} turns embedded\n`);
 
-  const qi = (id) => `"${id}"`;
-  const where = [`s.tenant_id = $1`];
-  const params = [tenantId];
+  // 4. Recall
+  console.log('4/5  Recalling "PostgreSQL memory store"...');
+  const results = await aquifer.recall('PostgreSQL memory store', { limit: 3 });
+  if (results.length === 0) {
+    console.error('     FAIL — no results returned. Check your embedding config.');
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`     OK — ${results.length} result(s), top score: ${results[0].score?.toFixed(3)}`);
+  if (results[0].matchedTurnText) {
+    console.log(`     Matched: "${results[0].matchedTurnText.slice(0, 100)}..."`);
+  }
+  console.log();
+
+  // 5. Cleanup
+  console.log('5/5  Cleaning up test data...');
+  const { Pool } = require('pg');
+  const { loadConfig } = require('./shared/config');
+  const config = loadConfig();
+  const pool = new Pool({ connectionString: config.db.url });
+  const schema = config.schema || 'aquifer';
+  await pool.query(`DELETE FROM ${schema}.turn_embeddings WHERE session_id IN (SELECT id FROM ${schema}.sessions WHERE session_id = $1)`, [sessionId]);
+  await pool.query(`DELETE FROM ${schema}.session_summaries WHERE session_id IN (SELECT id FROM ${schema}.sessions WHERE session_id = $1)`, [sessionId]);
+  await pool.query(`DELETE FROM ${schema}.sessions WHERE session_id = $1`, [sessionId]);
+  await pool.end();
+  console.log('     OK\n');
+
+  console.log('✓ Aquifer is working. You can now start the MCP server:');
+  console.log('  npx aquifer mcp');
+}
 
-  if (args.flags['agent-id']) { params.push(args.flags['agent-id']); where.push(`s.agent_id = $${params.length}`); }
-  if (args.flags.source) { params.push(args.flags.source); where.push(`s.source = $${params.length}`); }
-  params.push(limit);
+async function cmdExport(aquifer, args) {
+  const output = args.flags.output || null;
+  const limit = parseInt(args.flags.limit || '1000', 10);
 
-  const { rows } = await pool.query(`
-    SELECT s.*, ss.summary_text, ss.structured_summary
-    FROM ${qi(schema)}.sessions s
-    LEFT JOIN ${qi(schema)}.session_summaries ss ON ss.session_row_id = s.id
-    WHERE ${where.join(' AND ')}
-    ORDER BY s.started_at DESC
-    LIMIT $${params.length}
-  `, params);
+  const rows = await aquifer.exportSessions({
+    agentId: args.flags['agent-id'],
+    source: args.flags.source,
+    limit,
+  });
 
   const stream = output ? require('fs').createWriteStream(output) : process.stdout;
   for (const row of rows) {
@@ -268,6 +260,7 @@ async function main() {
     console.log(`Usage: aquifer <command> [options]
 
 Commands:
+  quickstart                  Verify end-to-end setup (migrate → commit → enrich → recall)
   migrate                     Run database migrations
   recall <query>              Search sessions (requires embed config)
   feedback                    Record trust feedback on a session
@@ -317,6 +310,9 @@ Options:
 
   try {
     switch (command) {
+      case 'quickstart':
+        await cmdQuickstart(aquifer);
+        break;
       case 'migrate':
         await cmdMigrate(aquifer);
         break;
@@ -340,7 +336,7 @@ Options:
         process.exit(1);
     }
   } finally {
-    if (aquifer._pool) await aquifer._pool.end();
+    await aquifer.close();
   }
 }