mem0-postgres-store
PostgreSQL history and recent-message persistence for Mem0 OSS 2.2.1, with transaction-scoped tenant isolation across history, messages, vector memories, and entity vectors. Python 3.12+; SQLAlchemy 2.0 and psycopg 3.
- Replaces SQLite history and recent-message storage with PostgreSQL.
- Enforces row-level security with transaction-scoped tenant context on both pools.
- Ships Alembic migrations, including pgvector tables and tenant policies.
- Tests storage and SDK integration against real PostgreSQL with Testcontainers.
The problem this solves
Mem0's Python SDK writes history and extraction context to SQLite even when its main memories use pgvector. That leaves local files and an additional persistence system to manage across application replicas. Its pgvector connection pool also does not carry an application's authenticated tenant context into PostgreSQL RLS.
This library keeps those records in PostgreSQL and enforces tenant context on
both connection pools. It does not fork Mem0, overwrite installed source files,
shadow the mem0 package, or open SQLite during initialization. It is a library,
not an HTTP server. Existing SQLite data is not automatically imported.
Install
Install the published package from PyPI:
uv add mem0-postgres-store
To use the current repository source instead:
uv add 'mem0-postgres-store @ git+https://github.com/Mg30/mem0-postgres-store.git'
Requires Python 3.12 or newer (Python 3). The dependency pins mem0ai==2.2.1;
other SDK versions are rejected.
Prepare PostgreSQL
Local development uses the supplied Compose example:
docker compose up -d --wait
export MEM0_MIGRATION_URL='postgresql+psycopg://mem0_migrator:local-migration-only@localhost:55432/mem0'
export MEM0_DATABASE_URL='postgresql+psycopg://mem0_runtime:local-runtime-only@localhost:55432/mem0'
uv run python -m mem0_postgres_store.migrate --dimensions 1536
uv run python examples/minimal.py
The example credentials are for local development only. The initialization script
runs only on an empty Compose volume. In production, the DBA installs the
vector extension in public, provisions separate migration and runtime roles,
and supplies credentials through the application's configuration boundary.
Use TLS options in the URL where required by your deployment.
Role provisioning gives the migrator permission to
create the schema and Alembic version table. The runtime role is a non-superuser,
non-owner with NOBYPASSRLS, no privileged role memberships, and no schema CREATE,
TRUNCATE, DROP, or migration privileges. Do not grant it membership in the owner
role. Never supply the migration URL to an application.
The packaged Alembic revisions create:
Table in mem0_store |
Purpose |
|---|---|
history |
Append-only SDK audit events, scoped by tenant and memory ID |
messages |
Most recent 10 messages per tenant/session scope |
mem0_vectors |
Mem0's pgvector memory payloads and embeddings |
mem0_vectors_entities |
Mem0's lazy entity-vector collection |
All tables have indexed, explicit tenant_id columns, enabled and forced RLS,
and policies with both USING and WITH CHECK for all DML. A restrictive tenant
guard prevents additional permissive policies from broadening access. The runtime
role has only SELECT, INSERT, and DELETE (for tenant reset) on history and
messages, so audit rows cannot be rewritten; vector tables also allow UPDATE.
Runtime startup verifies role attributes, owner membership, RLS flags, destructive
and UPDATE-on-history privileges (so an un-upgraded database fails clearly), and
embedding dimensions. DBAs remain responsible for policy integrity.
Migrations are packaged in the wheel. The migration command above is a small
configuration wrapper around Alembic upgrade head. For direct Alembic usage:
import os
from alembic import command
from mem0_postgres_store.migrate import migration_config
config = migration_config(
os.environ["MEM0_MIGRATION_URL"], dimensions=1536, runtime_role="mem0_runtime"
)
command.upgrade(config, "head")
command.current(config)
Alternatively, configure sqlalchemy.url in a local, uncommitted Alembic
configuration and run uv run alembic -x dimensions=1536 -x runtime_role=mem0_runtime upgrade head. Never commit database passwords. The first migration fixes the
embedding dimension; changing the argument later does not resize existing columns.
Use an explicit new migration and re-embedding plan. Downgrade deletes data and is
an administrative operation, not an application reset.
Synchronous Mem0
Set telemetry configuration before importing Mem0:
export MEM0_TELEMETRY=false
# Set credentials/model names for your chosen providers in application config.
import os
from mem0 import Memory
from mem0_postgres_store import Database, database_vector_config, install, tenant_scope
# One Database per worker process; construct after migrations, before serving requests.
database = Database(os.environ["MEM0_DATABASE_URL"], embedding_dimensions=1536)
install(database) # Explicit, process-global, idempotent for this Database instance.
memory = Memory.from_config(
{
"history_db_path": "postgresql://mem0-postgres-store",
"vector_store": database_vector_config(database),
"llm": {"provider": "openai", "config": {"model": os.environ["MEM0_LLM_MODEL"]}},
"embedder": {
"provider": "openai",
"config": {
"model": os.environ["MEM0_EMBEDDING_MODEL"],
"embedding_dims": 1536,
},
},
}
)
# Values must come from verified authentication/authorization, not request parameters.
with tenant_scope(authenticated_principal.tenant_id):
added = memory.add("I enjoy hiking", user_id=authenticated_principal.user_id)
results = memory.search("hobbies", filters={"user_id": authenticated_principal.user_id})
history = memory.history(added["results"][0]["id"])
memory.close()
database.close() # At application shutdown, after all requests have finished.
Provider configuration and credentials belong to your application. The example
uses the SDK's OpenAI providers; other SDK model providers can be configured.
infer=False avoids LLM extraction but still requires an embedder.
history_db_path is an explicit binding marker, not a filesystem path or DSN.
database_vector_config() binds the SDK to the pools owned by Database.
Passing another history path, connection pool, collection, or vector DSN fails.
For direct storage use, see the minimal runnable example.
PostgresHistoryStore(database) exposes add_history, batch_add_history,
get_history, save_messages, get_last_messages, reset, and close.
Asynchronous Mem0
Use the same bootstrap and config with AsyncMemory:
from mem0 import AsyncMemory
from mem0_postgres_store import tenant_scope
memory = AsyncMemory.from_config(config)
with tenant_scope(authenticated_principal.tenant_id):
added = await memory.add("I enjoy hiking", user_id=authenticated_principal.user_id)
results = await memory.search("hobbies", filters={"user_id": authenticated_principal.user_id})
history = await memory.history(added["results"][0]["id"])
memory.close() # Mem0 2.2.1 close() is synchronous, including on AsyncMemory.
Mem0 offloads synchronous storage calls using asyncio.to_thread. ContextVars
propagate through those calls. Its synchronous entity search uses a thread pool;
the bootstrap installs a context-copying executor only in Mem0's main module.
The global Python executor implementation is unchanged. Application-created worker
threads must copy context themselves or establish a new authenticated scope.
FastAPI integration
Construct pools and install the integration in each worker's lifespan, never before forking. Keep the tenant scope inside the endpoint/service function so scope-exit errors occur before a response is returned. The authentication dependency below is owned by your application and must verify identity and tenant membership.
import os
from contextlib import asynccontextmanager
from fastapi import Depends, FastAPI, Request
from mem0 import AsyncMemory
from mem0_postgres_store import Database, database_vector_config, install, tenant_scope
from your_app.auth import authenticate, AuthenticatedPrincipal
from your_app.config import model_config
@asynccontextmanager
async def lifespan(app: FastAPI):
database = Database(os.environ["MEM0_DATABASE_URL"], embedding_dimensions=1536)
install(database)
memory = AsyncMemory.from_config(
{
**model_config,
"history_db_path": "postgresql://mem0-postgres-store",
"vector_store": database_vector_config(database),
}
)
app.state.memory = memory
try:
yield
finally:
memory.close()
database.close()
app = FastAPI(lifespan=lifespan)
@app.get("/memories")
async def memories(request: Request, principal: AuthenticatedPrincipal = Depends(authenticate)):
with tenant_scope(principal.tenant_id):
result = await request.app.state.memory.get_all(filters={"user_id": principal.user_id})
return result
FastAPI is intentionally not a dependency of this library. See also the service-function example. Do not reuse a tenant scope across requests or start detached work inside one. A copied context becomes invalid once its owning scope exits. Each background job needs its own verified identity and scope.
Tenant security and reset
Each history session and vector cursor transaction executes parameterized
set_config('app.tenant_id', tenant_id, true) on the same connection as the
queries. Commit or rollback clears the setting before pooled reuse. Missing
application context raises TenantContextError; direct SQL with no setting sees
no rows and cannot insert tenant data. A JSON payload's tenant_id, user_id
filters, or a known memory UUID cannot override the relational tenant column/RLS.
RLS protects tenants from other application requests, including accidentally
missing SQL filters. It does not protect against a compromised application,
arbitrary SQL execution with the runtime credentials, privileged administrators,
or untrusted code calling tenant_scope with another tenant's identity. PostgreSQL
custom settings can be set by the runtime role. Authentication is the trust boundary.
Within a tenant, Mem0 user/agent/run filters remain application-level scoping;
this package does not provide separate user-level authorization inside that tenant.
Reset is explicitly authorized for one tenant:
with tenant_scope(authenticated_tenant_id, allow_reset=True):
memory.reset() # await memory.reset() for AsyncMemory
It deletes that tenant's history, messages, memories, and entity vectors, retains the shared schema, and supports SDK reinitialization. There is no runtime global reset or DDL. Quiesce that tenant's requests during reset: the SDK performs it as multiple transactions, so reset is not atomic across all stores. Other tenants remain protected by RLS.
Architecture and compatibility
The explicit bootstrap changes three process-local integration points, described in the design note:
mem0.memory.main.SQLiteManagerbecomes a factory forPostgresHistoryStore.- The pgvector provider registry points at
TenantPGVector, which inherits upstream queries and overrides transaction, collection, and reset boundaries. - Mem0's module-local executor binding copies ContextVars for entity search.
Package import alone changes none of them. Install before creating any SDK
instances: existing objects are not retrofitted, and their existence cannot be
reliably detected. One open Database binding is supported per process. Repeated
install with the same instance is safe; conflicting patches are rejected. Installing
a different Database is rejected while the current one is open, and allowed once it
is closed, so repeated application lifespans in one process (for example several
FastAPI TestClient blocks in a test suite) work. SDK instances created against the
closed Database keep failing closed; create new Memory/AsyncMemory instances
after rebinding. There is no uninstall.
All ordinary Mem0 pgvector instances in that process use this registration.
Other vector providers are outside the security guarantee and must not be used.
| Component | Supported / verified |
|---|---|
| Python | CPython 3.12, 3.13, 3.14, 3.15 |
| Mem0 SDK | Exactly mem0ai==2.2.1, audited source fingerprints |
| PostgreSQL / pgvector | PostgreSQL 17, pgvector/pgvector:pg17, real Testcontainers tests |
| SQLAlchemy / driver | SQLAlchemy 2.0, psycopg 3; SQLAlchemy history pool + psycopg vector pool |
| SDK operations | Sync/async add, extraction, get, search, get_all, update, delete, history, reset |
| Isolation | History, recent messages, main vectors, lazy entity vectors |
| Other Mem0 versions/backends | Unsupported; require separate audit and tests |
Limitations and operational details
- No cross-store atomic commit. Mem0 commits vectors and history separately.
A history failure can leave a vector without its audit row. All our database
operations propagate errors;
tenant_scopealso records errors that Mem0 catches and raisesStorageOperationErroron otherwise successful exit. A caught error still marks the scope failed, even if an SDK fallback later succeeds. Inspect and reconcile partial writes; blind retries can duplicate memories. - Process-global coupling. The integration checks the installed version and
fingerprints of audited source modules before patching. Modified wheels and
upgrades fail clearly. It does not detect arbitrary in-memory method replacement
by other code; do not combine it with unrelated Mem0 patches. Existing SDK
instances, alternative providers, telemetry, and custom external pools are not
covered.
MEM0_TELEMETRY=falseis mandatory before Mem0 import. Mem0 can still create its ordinary local configuration directory; this is not SQLite persistence. - One fixed collection pair/schema. Multiple applications may share the database when they deliberately share the same authenticated tenant namespace, embedding model and dimension. Separate logical datasets need separate databases or a future explicit namespace migration. There is no arbitrary collection DDL.
- Compatibility choices. Timestamps round-trip as supplied strings/None;
history orders by created-at text, UTC updated-at to whole seconds, then insertion
sequence. SDK ISO timestamps are supported; exotic SQLite date expressions
(for example Julian day numbers or
now) are not emulated. Equal timestamps are deterministic. Deletion markers return bool. Actor/role and message names are retained; arbitrary vector metadata remains JSONB. The upstream history interface has no arbitrary metadata field. Unknown dictionary fields are ignored as in SQLiteManager. Empty calls still require tenant context. PostgreSQL rejects NUL text. Reset intentionally deletes tenant rows instead of dropping tables. - Concurrency/lifecycle. An advisory transaction lock serializes message
insertion and pruning per tenant/session across processes. At most 10 committed
messages remain; higher read limits cannot recover evicted context. History
batches are atomic.
store.close()is idempotent and invalidates that manager; onlyDatabase.close()owns pool shutdown. Finish all work before closing. Reusing closed objects is unsupported.timeoutbounds connection/pool waits, not query execution; configure statement/lock timeouts with your DBA as needed. - Performance. Vector queries reuse Mem0's pgvector implementation and currently
use exact similarity scans. No HNSW/DiskANN index is created; the helper disables
HNSW. Benchmark production workloads and add appropriate indexes through explicit
migrations. Pool capacity is up to twice
pool_sizeper process (two pools). - Migration scope. Fresh installations are supported. Existing SQLite or pgvector collections need an audited export/import assigning verified tenant ownership. No automatic backfill, historical-data reconstruction, memory decay, temporal reasoning, or consolidation is included.
Development
Development uses uv 0.13.6 and requires Docker. Database tests use Testcontainers and never substitute SQLite or mocks for PostgreSQL. Missing Docker is a failure, not a silent skip. No OpenAI key or model download is required.
git clone https://github.com/Mg30/mem0-postgres-store.git
cd mem0-postgres-store
uv sync --frozen
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv build --no-sources
CI runs the PostgreSQL suite and checks wheel installation on Python 3.12, 3.13,
3.14, and 3.15. To run locally with a specific version, use
uv run --python 3.14 --frozen pytest. Lint and type checks target Python 3.12,
the minimum supported version.
License
MIT. Depends on Mem0 (Apache-2.0); no Mem0 source is vendored.
Metadata
Release files for mem0-postgres-store 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mem0_postgres_store-0.1.1.tar.gz | 135.2 kB | Without provenance | Details for mem0_postgres_store-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mem0_postgres_store-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for mem0_postgres_store-0.1.1-py3-none-any.whl |
Total release size: 157.6 kB
Release files / mem0_postgres_store-0.1.1.tar.gz
| Download URL | mem0_postgres_store-0.1.1.tar.gz |
|---|---|
| Size | 135.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b22b19aacca4333a8d4e97044c0a16339148238ab39833e7c798af5bea29f01e
|
|
BLAKE2b-256 checksum How to use checksums |
01ecea1a424a4082fc4939448f9dc3b7514d9dbb56f83cf47a4c7118e6de1c43
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / mem0_postgres_store-0.1.1-py3-none-any.whl
| Download URL | mem0_postgres_store-0.1.1-py3-none-any.whl |
|---|---|
| Size | 22.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bfb11fce9763d40ce1b269f0e92b5bebcd02516f01b224eceee137686a80d2fe
|
|
BLAKE2b-256 checksum How to use checksums |
b75723f6f7ee6228814edcba9c142ef562fefcb9768a60b41c2dc344fdb2cce1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for mem0-postgres-store 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.