diff --git a/.changeset/postgres-readme.md b/.changeset/postgres-readme.md
new file mode 100644
index 000000000..3f8a521eb
--- /dev/null
+++ b/.changeset/postgres-readme.md
@@ -0,0 +1,5 @@
+---
+"@voltagent/postgres": patch
+---
+
+Add README documentation
diff --git a/packages/postgres/README.md b/packages/postgres/README.md
new file mode 100644
index 000000000..91e089d25
--- /dev/null
+++ b/packages/postgres/README.md
@@ -0,0 +1,119 @@
+
+
+
+
+
+
+AI Agent Engineering Platform
+
+
+
+
+
+
+
+[](https://github.com/voltagent/voltagent/issues)
+[](https://github.com/voltagent/voltagent/pulls)
+[](https://opensource.org/licenses/MIT)
+[](https://www.npmjs.com/package/@voltagent/postgres)
+[](https://www.npmjs.com/package/@voltagent/postgres)
+[](https://s.voltagent.dev/discord)
+
+
+
+## @voltagent/postgres
+
+PostgreSQL adapters for VoltAgent: a memory adapter for conversations/messages/working memory/workflow state, and a vector adapter for embedding storage and cosine-similarity search. Both are backed by a `pg` connection pool and create their own tables on first use.
+
+---
+
+## Install
+
+```bash
+npm install @voltagent/postgres pg
+# or
+yarn add @voltagent/postgres pg
+# or
+pnpm add @voltagent/postgres pg
+```
+
+## Memory Adapter
+
+`PostgreSQLMemoryAdapter` implements VoltAgent's `StorageAdapter` interface, storing conversations, messages, working memory, and workflow state in PostgreSQL.
+
+```typescript
+import { Agent, Memory } from "@voltagent/core";
+import { PostgreSQLMemoryAdapter } from "@voltagent/postgres";
+import { openai } from "@ai-sdk/openai";
+
+const memory = new Memory({
+ storage: new PostgreSQLMemoryAdapter({
+ connection: process.env.DATABASE_URL,
+ // or: { host, port, database, user, password, ssl }
+ }),
+});
+
+const agent = new Agent({
+ name: "my-agent",
+ instructions: "A helpful assistant",
+ model: openai("gpt-4o-mini"),
+ memory,
+});
+```
+
+### Memory Options
+
+| Option | Type | Default | Description |
+| ---------------- | ------------------ | -------------------- | -------------------------------------------------------------------- |
+| `connection` | `string \| object` | — | Connection string or `{ host, port, database, user, password, ssl }` |
+| `maxConnections` | `number` | `10` | Maximum connections in the pool |
+| `tablePrefix` | `string` | `"voltagent_memory"` | Prefix used for all created tables |
+| `schema` | `string` | `undefined` | PostgreSQL schema to use for all tables |
+| `debug` | `boolean` | `false` | Enable debug logging |
+
+## Vector Adapter
+
+`PostgreSQLVectorAdapter` implements VoltAgent's `VectorAdapter` interface, providing persistent vector storage with cosine-similarity search for RAG and retriever use cases.
+
+```typescript
+import { PostgreSQLVectorAdapter } from "@voltagent/postgres";
+
+const vectorStore = new PostgreSQLVectorAdapter({
+ connection: process.env.DATABASE_URL,
+});
+```
+
+### Vector Options
+
+| Option | Type | Default | Description |
+| --------------------- | ------------------ | -------------------- | -------------------------------------------------------------------- |
+| `connection` | `string \| object` | — | Connection string or `{ host, port, database, user, password, ssl }` |
+| `tablePrefix` | `string` | `"voltagent_vector"` | Prefix used for the created table |
+| `maxVectorDimensions` | `number` | `1536` | Maximum allowed vector dimensions |
+| `cacheSize` | `number` | `100` | LRU cache size for fetched vectors |
+| `batchSize` | `number` | `100` | Batch size for bulk operations |
+| `maxRetries` | `number` | `3` | Maximum retry attempts for database operations |
+| `retryDelayMs` | `number` | `100` | Initial retry delay (ms) for exponential backoff |
+| `searchPath` | `string` | `undefined` | Optional search path to set for each connection |
+| `maxConnections` | `number` | `10` | Maximum connections in the pool |
+| `debug` | `boolean` | `false` | Enable verbose logging |
+
+## Testing
+
+See [README.integration.md](./README.integration.md) for running the integration test suite against a real PostgreSQL instance via Docker.
+
+## Documentation
+
+- [VoltAgent Documentation](https://voltagent.dev/docs/)
+- [Memory Overview](https://voltagent.dev/docs/agents/memory/overview/)
+- [RAG Overview](https://voltagent.dev/docs/rag/overview/)
+
+## License
+
+Licensed under the MIT License, Copyright © 2026-present VoltAgent.