@coopah/bentley-store-postgres

PostgreSQL storage backend for Bentley workspace memory with pgvector support for efficient semantic search.

Install

pnpm add @coopah/bentley-store-postgres

Make sure your PostgreSQL instance has the pgvector extension installed if you want semantic search.

Dependencies

• @coopah/bentley-core
• pg ^8.16.0

Usage

import { createBentley } from "@coopah/bentley-core";
import { bentleyPostgresPlugin } from "@coopah/bentley-store-postgres";

const bentley = createBentley({
  plugins: [
    bentleyPostgresPlugin({
      connectionString: process.env.DATABASE_URL!,
    }),
  ],
});

With Embeddings (Semantic Search via pgvector)

import { embed } from "ai";
import { openai } from "@ai-sdk/openai";

bentleyPostgresPlugin({
  connectionString: process.env.DATABASE_URL!,
  embedder: async (text) => {
    const { embedding } = await embed({ model: openai.embedding("text-embedding-3-small"), value: text });
    return embedding;
  },
});

When an embedder is provided, semantic search uses pgvector's <=> (cosine distance) operator for fast similarity queries instead of brute-force scanning.

Running Migrations

import { BentleyPostgresStore } from "@coopah/bentley-store-postgres";

const store = new BentleyPostgresStore({ connectionString: process.env.DATABASE_URL! });
await store.migrate(); // Creates tables and pgvector extension

API

• bentleyPostgresPlugin(config) — BentleyPlugin that registers PostgreSQL as the workspace memory backend
• BentleyPostgresStore — Implements BentleyWorkspaceMemory from core
• MIGRATIONS — Database migration scripts

Configuration

interface PostgresStoreConfig {
  connectionString: string;                          // PostgreSQL connection URI
  embedder?: (text: string) => Promise<number[]>;    // Optional embedding function for semantic search
}

BentleyPostgresStore Methods

Implements the full BentleyWorkspaceMemory interface:

| Method | Description | |--------|-------------| | getSoul(shellId) | Get shell identity (SOUL.md equivalent) | | updateSoul(shellId, content) | Update shell identity | | getMemory(shellId) | Retrieve long-term memory facts | | appendMemory(shellId, fact) | Add a memory fact | | getRecentMessages(shellId, threadId, limit?) | Get conversation history | | addMessage(shellId, threadId, message) | Store a message | | semanticSearch(shellId, query, topK?) | pgvector similarity search | | getRecentMessagesWithStrategy() | Memory reduction with configurable strategies | | getHeartbeatChecklist(shellId) | Recurring task state | | migrate() | Run schema migrations (creates tables + pgvector extension) | | close() | Close the connection pool |

Database Tables

• bentley_souls — Shell identity
• bentley_memories — Long-term facts with timestamps
• bentley_messages — Conversation history by shell/thread
• bentley_heartbeats — Task runner state
• bentley_embeddings — Vector embeddings (pgvector type) for semantic search

Related Packages

| Package | Role | |---------|------| | @coopah/bentley-core | Core runtime (required) | | @coopah/bentley-store-sqlite | SQLite backend (simpler, no pgvector) |

License

MIT