PostgreSQL + Apache AGE operator guide (ai-memory v0.8.0)

Audience. Operators running ai-memory who want PostgreSQL as the live storage backend, with Apache AGE for graph queries and pgvector for semantic recall. As-of v0.7.0, postgres+AGE is a first-class backend — ai-memory serve --store-url postgres://… is the supported production deployment shape.

If you only want sqlite, you don’t need any of this — the default ai-memory serve continues to work exactly as it did in v0.6.x. The postgres path is opt-in.

See also: migration-v0.7.0-postgres.md for the sqlite → postgres migration runbook, and RUNBOOK-adapter-selection.md for the adapter-selection design notes.

Why postgres+AGE

ai-memory’s sqlite path is fast, simple, and has zero operational overhead — for a single workstation or a single daemon, it is the right choice. Switch to postgres+AGE when one or more of these is true:

• Multi-tenant scale. A single sqlite file behind a single Mutex<Connection> becomes the bottleneck once you cross ~5 concurrent writers. Postgres’ MVCC removes that ceiling.
• Larger than RAM. sqlite + HNSW keeps the full vector index in memory. pgvector’s HNSW lives on disk and pages on demand — practical for 10M+ memory corpora.
• AGE Cypher KG. ai-memory’s KG operations (kg_query, kg_timeline, kg_invalidate, find_paths) compile to native Cypher on AGE, which beats the sqlite recursive-CTE fallback by ≥30% at depth=5 on the canonical 1k-entity / 5k-edge corpus (S76 perf gate). The deeper the graph, the wider the gap.
• Multi-daemon A2A. Two or more ai-memory serve processes sharing the same store. Postgres is the supported topology; sqlite-over-NFS is not.

The two backends have schema parity at v78 (CURRENT_SCHEMA_VERSION = 78 on both ladders — the postgres upgrade ladder ends at migrate_v78()) — every feature that works on sqlite works on postgres.

Prerequisites

Bundled Dockerfile (Apache AGE + pgvector on PG18, #1065)

The upstream apache/age:release_PG18_1.7.0 image ships AGE but not pgvector. Because the ai-memory v0.7 SAL postgres adapter REQUIRES pgvector (the sal-postgres Cargo feature pulls dep:pgvector which maps Rust vectors to Postgres vector columns), the repo ships a ready-made stacked image at deploy/docker-1461/Dockerfile.pg-age-vector (#1065). It layers pgvector 0.8.2 (precompiled .deb from the pgdg apt repo) onto the apache/age:release_PG18_1.7.0 base — no source build needed. Use this image for any deployment that backs ai-memory onto Postgres+AGE. (The infra/lan-parity-test/ image — PG 16 + AGE 1.6.0 + pgvector 0.8.2 — remains as a tested alternate matrix.)

Cypher parameter binding. ai-memory’s production code interpolates parameters into the Cypher string through the AGE-recommended cypher() SQL-function form, which is portable across AGE releases — if you write your own SQL probes, prefer the SQL-function form. (A historical AGE 1.5.0 + PG 16 quirk could emit “could not find parameter $N” for some bind shapes against the raw prepare-path; the SQL-function form sidesteps it entirely and AGE 1.7.0 on PG 18 is unaffected. Wave 1 Stream C fixed our equivalence test harness to use the safe form; production code never needed the fix.)

Install — Ubuntu 24.04 example

# 1. PostgreSQL 18 from PGDG.
sudo apt install -y curl ca-certificates gnupg lsb-release
sudo install -d /usr/share/postgresql-common/pgdg
sudo curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc \
     -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc
echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] \
     https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" \
     | sudo tee /etc/apt/sources.list.d/pgdg.list
sudo apt update
sudo apt install -y postgresql-18 postgresql-server-dev-18 \
                    postgresql-contrib-18 build-essential bison flex git

# 2. pgvector 0.8.2 from the upstream release tag.
git clone --depth 1 --branch v0.8.2 https://github.com/pgvector/pgvector.git
cd pgvector
sudo make USE_PGXS=1 PG_CONFIG=/usr/lib/postgresql/18/bin/pg_config install
cd ..

# 3. Apache AGE 1.7.0 from source against PG 18.
git clone --depth 1 --branch PG18/v1.7.0 https://github.com/apache/age.git
cd age
sudo make PG_CONFIG=/usr/lib/postgresql/18/bin/pg_config install
cd ..

# 4. Restart postgres to pick up the shared libraries.
sudo systemctl restart postgresql@18-main

For RHEL / Fedora / Amazon Linux: replace the apt lines with the PGDG yum repo equivalents and ensure postgresql18-devel / postgresql18-contrib are installed before building AGE.

Docker — pgvector is required, not optional (#1065)

The popular apache/age:release_PG18_* Docker images do not bundle pgvector. The SAL postgres adapter’s init schema step calls CREATE EXTENSION IF NOT EXISTS vector and fails-fast on missing extension with the message extension "vector" is not available — restarting the daemon container indefinitely on Plan C and any Compose / K8s deploy.

The canonical fix is a 2-line Dockerfile that layers pgvector on top of the upstream Apache AGE image:

# Dockerfile.pg-age-vector — see deploy/docker-1461/Dockerfile.pg-age-vector
FROM apache/age:release_PG18_1.7.0
USER root
RUN apt-get update \
 && apt-get install -y --no-install-recommends postgresql-18-pgvector \
 && rm -rf /var/lib/apt/lists/*
USER postgres

The ai-memory repo ships this Dockerfile at deploy/docker-1461/Dockerfile.pg-age-vector; the lan-parity compose file uses its PG 16 + AGE 1.6.0 counterpart via:

services:
  pg-age:
    build:
      context: .
      dockerfile: Dockerfile.pg-age-vector

Plan C operators running on K8s / ECS / Cloud Run build this image once, tag it (pg-age-vector:PG18.4-1.7.0-pgvector0.8.2), and reference the tag from their workload manifests instead of the bare upstream image.

Database setup

sudo -u postgres psql <<'SQL'
CREATE ROLE aimemory WITH LOGIN PASSWORD 'changeme-please';
CREATE DATABASE aimemory OWNER aimemory;
\c aimemory
CREATE EXTENSION IF NOT EXISTS age;
CREATE EXTENSION IF NOT EXISTS vector;
GRANT USAGE ON SCHEMA ag_catalog TO aimemory;
GRANT ALL ON ALL TABLES IN SCHEMA public TO aimemory;
ALTER DATABASE aimemory SET search_path = ag_catalog, "$user", public;
SQL

Notes:

• aimemory is the role the daemon runs as. Pick a strong password and store it in your secret manager — the daemon reads it from the --store-url URL only (the AI_MEMORY_STORE_URL env fallback was deliberately dropped; commit 1e8ad69b).
• ag_catalog must be on the search path so AGE’s cypher() SQL function resolves without a schema prefix on every call.
• The role only needs USAGE on ag_catalog (read of the AGE function definitions); the AGE projection objects ai-memory creates live in the aimemory schema by default.

Bootstrap the schema

ai-memory schema-init (Wave 1 Stream B deliverable) is the supported way to bootstrap a fresh postgres backend:

ai-memory schema-init --store-url postgres://aimemory:changeme-please@localhost:5432/aimemory

What it does (see src/cli/schema_init.rs):

1. Connects to the --store-url via the same open_store factory the migrate verb uses — the open itself runs INIT_SCHEMA (the bundled src/store/postgres_schema.sql, idempotent CREATE TABLE IF NOT EXISTS throughout) plus the in-process upgrade ladder up to schema v78 (the current CURRENT_SCHEMA_VERSION) as a side effect. The vector (pgvector) extension is required — CREATE EXTENSION IF NOT EXISTS vector failing aborts the bootstrap.
2. If the age extension is installed, additionally bootstraps the AGE memory_graph projection via SELECT create_graph('memory_graph') (idempotent — “graph already exists” is treated as success). AGE is opt-in: a missing extension is NOT fatal; the JSON report just carries age_projection_created: false and KG queries use the recursive-CTE fallback.
3. Applies the --embedding-dim contract (default 384): a fresh schema is initialised with vector(<dim>) columns; an existing schema whose dim differs is converted in place (HNSW indexes dropped + recreated, existing embedding values NULLed — re-embed afterwards; embedding_dim_migrated: true in the JSON report).
4. Enumerates the resulting catalog and prints the human summary (tables / indices / views / functions / extensions / schema_version: 71) or the --json report.

Idempotent on rerun — safe to invoke from a deploy script. Exit code 0 on success, non-zero on connection / bootstrap failure.

There is no --skip-age flag — AGE is auto-detected; when absent the recursive-CTE fallback serves kg_query/kg_timeline/etc.

Daemon configuration

Pass the store URL as a CLI flag on serve (this is the supported shape in v0.7.0; env-var and config-file forms are tracked for a follow-on release):

ai-memory serve --store-url postgres://aimemory:PASSWORD@HOST:5432/aimemory

URL shapes accepted by --store-url:

• postgres://user:pass@host:port/dbname
• postgresql://user:pass@host:port/dbname (alias)
• sqlite:///absolute/path/to/file.db (also valid — same semantics as --db)

--db and --store-url are mutually exclusive. Passing both when --db is explicit (set on the command line OR via the AI_MEMORY_DB env var) errors at startup:

Error: --db and --store-url are mutually exclusive. Pass exactly one.
       Got --db=/var/lib/ai-memory/db.sqlite and
       --store-url=postgres://aimemory:...@10.20.0.4:5432/aimemory

When --store-url is unset, the daemon falls back to its sqlite path (AI_MEMORY_DB or --db’s default). This preserves byte-for-byte v0.6.x behavior on the default build.

The daemon logs the resolved backend at startup. For postgres:

INFO  ai_memory::daemon_runtime: Wave-3: opening Postgres SAL store at postgres://aimemory:...
WARN  ai_memory::daemon_runtime: v0.7.0 Wave-3: postgres-backed daemon — handlers
       that have not yet migrated to the SAL trait surface 501 Not Implemented.

A second probe of /api/v1/capabilities confirms it:

curl -s http://HOST:9077/api/v1/capabilities | jq .storage_backend
# "postgres"

If AGE is detected, KG queries dispatch through the Cypher path; if not, the fallback recursive-CTE path runs against the memory_links table on postgres exactly as it does on sqlite.

HTTPS / mTLS configuration

ai-memory serve ships with two-layer transport security:

Layer 1 alone gives you HTTPS — peers verify the server’s identity through the supplied cert chain. Layer 2 layers mTLS on top: the server requires every client to present a certificate whose SHA-256 DER fingerprint matches an entry in --mtls-allowlist. Combined, they implement the SSH known_hosts pin model — the cert chain is not the trust anchor; the fingerprint pin is.

Step 1 — generate a CA, server certs, and client certs

The campaign repo ships a one-shot generator at /tmp/a2a-v07-tls/regen.sh; the underlying openssl invocations look like:

# 1. test CA (10y, ECDSA P-256). Substitute a stronger key + a real
#    DN for production deployments.
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out ca.key
openssl req -x509 -new -nodes -key ca.key -days 3650 \
    -subj "/CN=my-ai-memory-fleet" -out ca.pem

# 2. server cert. SANs MUST cover every IP/DNS the daemon listens on.
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out server.key
cat > server.cnf <<EOF
[req]
distinguished_name = dn
req_extensions = v3_req
prompt = no
[dn]
CN = ai-memory.internal
[v3_req]
basicConstraints = CA:FALSE
keyUsage = digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names
[alt_names]
DNS.1 = ai-memory.internal
IP.1 = 10.20.0.2
IP.2 = 127.0.0.1
EOF
openssl req -new -key server.key -out server.csr -config server.cnf
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca.key -CAcreateserial \
    -out server.pem -days 3650 -extfile server.cnf -extensions v3_req

# 3. client cert(s). Repeat per agent identity; the server allowlist
#    pins each client's fingerprint.
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out client-alice.key
# ... same shape as server.cnf with `extendedKeyUsage = clientAuth`.

# 4. compute each client cert's SHA-256 DER fingerprint.
for c in client-*.pem; do
    fp=$(openssl x509 -in "$c" -noout -fingerprint -sha256 \
         | sed 's/.*=//' | tr -d ':' | tr 'A-F' 'a-f')
    echo "$fp"
done > mtls-allowlist.txt

Allowlist format (src/tls.rs::load_fingerprint_allowlist):

• one fingerprint per line, hex digits, optional : separators
• sha256: prefix is accepted
• # comments (full-line + inline) are stripped before parsing
• empty lines are ignored

Step 2 — wire the daemon’s systemd unit

Edit /etc/systemd/system/ai-memory.service (or its drop-in equivalent) and append the three flags to the ExecStart= line:

[Service]
ExecStart=/usr/local/bin/ai-memory serve \
    --store-url postgres://aimemory:PWD@10.20.0.4:5432/aimemory \
    --tls-cert /etc/ai-memory/tls/server.pem \
    --tls-key  /etc/ai-memory/tls/server.key \
    --mtls-allowlist /etc/ai-memory/tls/mtls-allowlist.txt

Reload + restart:

systemctl daemon-reload
systemctl restart ai-memory

The deploy_wave4.sh helper in the campaign repo does this automatically when invoked with DEPLOY_TLS=1 (and, for mTLS, DEPLOY_MTLS=1 which is the default when DEPLOY_TLS=1):

DEPLOY_TLS=1 DEPLOY_MTLS=1 \
TLS_LOCAL_DIR=/tmp/a2a-v07-tls \
TLS_REMOTE_DIR=/etc/ai-memory-a2a/tls \
scripts/deploy_wave4.sh

Step 3 — verify with curl

# (from the same VPC; --resolve picks the right SAN)
curl -sS \
    --cacert /etc/ai-memory/tls/ca.pem \
    --cert   /etc/ai-memory/tls/client-alice.pem \
    --key    /etc/ai-memory/tls/client-alice.key \
    https://ai-memory.internal:9077/api/v1/capabilities | jq .storage_backend
# "postgres"

A failed handshake (wrong CA, missing client cert, fingerprint not on allowlist) surfaces as a curl (35) error:0A000412:SSL routines::sslv3 alert bad certificate — the server log carries the structured reason.

Step 4 — wire the campaign harness

The harness picks a per-agent client cert from env vars:

export TLS_MODE=mtls
export TLS_CA_PEM=/etc/ai-memory-a2a/tls/ca.pem
export TLS_CLIENT_CERT_ALICE=/etc/ai-memory-a2a/tls/client-alice.pem
export TLS_CLIENT_KEY_ALICE=/etc/ai-memory-a2a/tls/client-alice.key
export TLS_CLIENT_CERT_BOB=/etc/ai-memory-a2a/tls/client-bob.pem
export TLS_CLIENT_KEY_BOB=/etc/ai-memory-a2a/tls/client-bob.key
# ... per-agent pairs for every identity the campaign uses.
# Optional process-wide default (used when no per-agent var matches):
export TLS_DEFAULT_CLIENT_CERT=/etc/ai-memory-a2a/tls/client-default.pem
export TLS_DEFAULT_CLIENT_KEY=/etc/ai-memory-a2a/tls/client-default.key

The agent suffix is the upper-cased agent_id with non-alphanumerics collapsed to _ (so ai:alice@nyc3-droplet-1 becomes AI_ALICE_NYC3_DROPLET_1). The Python campaign harness (scripts/a2a_harness.py, Harness.client_cert_for) that implemented this lookup has been retired from the repo; the live mTLS leg checks are the shell harness at deploy/do-1461/test/encrypted_legs.sh (MTLS_CLIENT_CERT / MTLS_CLIENT_KEY convention — see deploy/docker-1461/provision/lib.sh).

Each scenario report now carries a tls_handshake block:

{
    "scenario": "20",
    "tls_mode": "mtls",
    "tls_handshake": {
        "count": 17,
        "min_seconds": 0.013,
        "mean_seconds": 0.022,
        "max_seconds": 0.054,
        "total_seconds": 0.379
    }
}

Plain-HTTP runs omit the block. The orchestrator’s perf-vs-baseline diff (Phase 7 of the cert closure) reads tls_handshake.total_seconds to compute the per-scenario TLS overhead.

Cert closure run reference

The Continuation-6 cert closure run (commit <orchestrator-fills-in>) exercises this configuration end-to-end against the wave-4 droplet fleet. Compare its runs/<id>/aggregate.json against the plain-HTTP baseline at runs/v0.7.0-a2a-wave4r2-r1-20260509-1858/ to read the perf overhead.

Operator surfaces that “just work” identically on both backends

The point of the SAL trait is that no caller needs to know which backend is mounted. As of v0.7.0 Wave-3 + Wave-3 Continuation the following HTTP endpoints route through the SAL trait identically on sqlite and postgres:

Core CRUD (Wave-3 Phase 3 — commit c049500)

Wave-3 Continuation (Phase 4 + 5)

Wave-3 Continuation 2 (Phase 8 + 9 + 10 + 11)

The four critical surfaces gated for v0.7.0 land here. After Continuation 2, postgres-backed daemons run as first-class peers in federation, fire the same audit chain as sqlite, run the full hybrid recall pipeline, and accept governance write paths.

Wave-3 Continuation 3 (Phase 13 + 14 + 15 + 16 + 17 + 18 + 19 + 20)

The eight remaining sqlite-only surfaces land here. After Continuation 3, every HTTP endpoint that works on a sqlite-backed daemon also works on a postgres-backed daemon — there is no residual 501 envelope on standard endpoints (the route gate keeps the 501 envelope as a safety net for unknown / future endpoints).

Wave-3 Continuation 6 — F7 closure (S52, S61, S65)

Three new HTTP endpoints close the Wave 4 cert-harness gaps surfaced post-Continuation-5. Each routes through the SAL trait so postgres-backed and sqlite-backed daemons project byte-identical wire shapes.

Phase 20 — full governance pipeline

Postgres-backed daemons now run the full governance pipeline that sqlite-backed daemons run:

• MemoryStore::build_namespace_chain walks namespace_meta for explicit-parent ancestors (bounded by 8 hops + cycle-safe) + /-derived hierarchy.
• MemoryStore::resolve_governance_policy walks leaf-first and returns the most-specific policy with inherit=true honored.
• MemoryStore::enforce_governance_action evaluates Any / Registered / Owner / Approve levels; Approve queues a pending_actions row and returns the canonical pending id.
• MemoryStore::governance_approve_with_consensus runs the full multi-vote state machine: Human accepts any caller, Agent requires the named id, Consensus requires registered-agent voters with case-insensitive duplicate-vote dedup; threshold transition stamps decided_by + decided_at and returns Approved.

The post-approval execute_pending_action payload-replay path remains sqlite-only — postgres operators on Approved actions re-issue the underlying write via the standard CRUD path. This is the only residual scope difference between sqlite and postgres for governance.

Federation fanout for governance decisions / archive / restore / purge stays sqlite-only (the broadcast_*_quorum paths use sqlite-coupled fed-tracker state); postgres operators relying on multi-node consistency for these subcollections should poll peers or pin to sqlite for v0.7.0.

The audit module is file-based with no SQLite coupling, so ai-memory audit verify --audit-dir <path> works on a postgres-backed daemon’s log unchanged. The F2 fix (cross-restart sequence persistence via the chain-tail walk in audit::init) lights up for postgres through the new emit sites in create_memory / delete_memory / create_link / approve_pending / reject_pending / sync_push.

The full hybrid recall pipeline mirrors db::recall_hybrid (sqlite path) over pgvector + tsvector + ts_rank: 6-factor FTS sub-score (priority * 0.5 + min(access_count, 50) * 0.1 + confidence * 2.0

• tier_bonus + recency_factor), 0.2 cosine gate, adaptive blend (semantic_weight = 0.50 for ≤500 chars, lerp to 0.15 at ≥5000 chars), atomic touch ops (++access_count + TTL extension + mid→long auto-promotion at 5 accesses + ++priority every 10 accesses).

Postgres route gate

Wave-3 Continuation also installs a route-gate middleware at the router layer (handlers::postgres_route_gate). On a postgres-backed daemon, any (method, path) tuple not in the supported list above is short-circuited with a structured 501 envelope before reaching the legacy SQLite handler — closing the silent-corruption gap where un-migrated handlers would otherwise read from / write to the empty in-memory scratch SQLite database that bootstrap_serve opens against --db. On sqlite-backed daemons the gate is a pure pass-through.

What still returns 501 on postgres

After Wave-3 Continuation 3, no standard HTTP endpoint returns 501 on a postgres-backed daemon. Every endpoint listed in the router (92 production .route(...) registrations in src/lib.rs — 78 unique URL paths, surfaced through /api/v1/capabilities) dispatches through the SAL trait or is handled directly by the postgres adapter.

The route gate retains its 501 envelope as a safety net for:

• Unknown / future endpoints not yet in the allow-list.
• Operator-installed handlers (custom plugins) that have not been classified.

Two degraded-mode behaviors remain documented but do not block endpoint availability:

• execute_pending_action payload-replay (the post-Approved write fanout) — sqlite-only. Postgres-backed daemons return 200 + {approved: true, executed: false} on consensus threshold; the approving caller re-issues the underlying write via the standard CRUD path. The full state machine runs identically on both backends — only the auto-replay step is gated.
• Federation fanout subcollections that ride sqlite-only fed-tracker state: archive / restore / purge / pending-decision broadcast. Memories / deletions / links / sync_push core round-trip through the trait. Postgres operators relying on multi-node consistency for these subcollections should poll peers or pin sqlite for v0.7.0.

Schema parity at v71 means ai-memory migrate sqlite → postgres carries every row across cleanly.

The recall score breakdown is the same 6-factor formula on both backends:

score = semantic_weight * cosine
      + (1 - semantic_weight) * fts_norm
      + priority * 0.05
      + access_count * 0.01
      + confidence * 0.20
      + tier_bonus
      + recency_factor

(Wave 1 Stream A’s tests/recall_scoring_parity.rs pins this contract — same query, same top-K, same per-factor breakdown within FP tolerance.)

Performance notes

pgvector HNSW

The postgres adapter creates an HNSW index on memories.embedding during schema-init:

CREATE INDEX IF NOT EXISTS memories_embedding_hnsw
    ON memories USING hnsw (embedding vector_cosine_ops);

Default tuning is the pgvector default (m=16, ef_construction=64). For corpora >1M memories, raising ef_construction to 128 at index build time and hnsw.ef_search to 80 at query time is the standard recommendation; the v0.7.0 release does not yet expose these as ai-memory schema-init flags — set them via SQL post-bootstrap.

AGE Cypher vs CTE fallback

The four KG operations dispatch on the KgBackend tag the postgres adapter probes at connect time:

The S76 perf gate fires if AGE is reported as engaged but the AGE p95 is not at least 30% faster than CTE p95 on the canonical 1k-entity / 5k-edge corpus. That gate is honest about the AGE-vs-CTE comparison on the same postgres host — comparing AGE-on-postgres to CTE-on-sqlite is a different question and not the speedup we claim.

AGE projection mode (sync vs deferred) — #1735

Postgres link writes project edges into the AGE memory_graph so Cypher traversals see them. AI_MEMORY_AGE_PROJECTION_MODE selects the posture (postgres-only; SQLite ignores it):

• sync (default) runs the inline project_link_into_age Cypher MERGE inside the link-write transaction — byte-identical to the pre-#1735 behaviour.
• deferred enqueues a kg_projection_outbox row (schema v69) in the same transaction as the relational memory_links INSERT and skips the inline MERGE; a cold drainer worker (spawned by serve, with a drain-once boot-recovery pass plus an interval loop) projects the pending rows into memory_graph out-of-band, taking the synchronous AGE round-trips off the link-write hot path. Failed projections retry up to MAX_AGE_PROJECTION_ATTEMPTS then quarantine.

Under deferred, postgres find_paths routes through the always-current relational recursive-CTE so reads stay read-your-own-write correct during the projection window; kg_query / kg_timeline may observe a bounded staleness window until the drainer catches up. Observability: ai_memory_age_projection_{pending_depth,failed_total,quarantined_total}. Resolved via AppConfig::resolve_storage() (env > [storage].age_projection_mode

compiled sync).

Connection pool

The postgres adapter uses sqlx’s connection pool. The defaults are min=2, max=16, with a 30-second connection-acquire timeout. For high-fanout multi-tenant deployments, raise max to 32-64; for single-daemon deployments the defaults are appropriate. Pool sizing and the acquire timeout are exposed via three env vars (each resolved by AppConfig::resolve_pg_pool(), env > [storage]-adjacent config field

compiled default):

Non-positive / unparseable values fall through to the compiled default.

Troubleshooting

AGE not installed

A missing age extension is non-fatal — ai-memory schema-init completes, reports age_projection_created: false in its --json output, and the daemon serves KG queries through the recursive-CTE fallback. Install AGE (see “Install” above) and re-run schema-init to enable the Cypher path. The vector extension is not optional — pgvector is required for embeddings, and its absence aborts the bootstrap.

Old postgres schema version detected

If you’re pointing at a v0.7-alpha postgres database (schema v15), run ai-memory schema-init --store-url postgres://… with a current (v0.8.1) binary — opening the store applies the upgrade ladder to v71 idempotently. (See migration-v0.7.0-postgres.md for the full migration guide.)

“could not find parameter $N” against a Cypher query

This is the historical AGE 1.5.0 + PG 16 binding quirk mentioned above (AGE 1.7.0 on PG 18 is unaffected). ai-memory’s production code never hits it — if you see it, you’re running a custom psql probe. Use the AGE-recommended SQL-function shape:

SELECT * FROM cypher('memory_graph', $$
  MATCH (a)-[r:RELATED_TO]->(b)
  WHERE a.id = $node_id
  RETURN b
$$, $$ {"node_id": "abc123"} $$) AS (b agtype);

“permission denied for schema ag_catalog”

The aimemory role needs USAGE on ag_catalog. The “Database setup” section above grants it; if you bootstrapped by hand, run GRANT USAGE ON SCHEMA ag_catalog TO aimemory; as the postgres superuser.

Recall scores differ between sqlite and postgres

If you observe this, file an issue and reference tests/recall_scoring_parity.rs (Wave 1 Stream A). The contract is that the same query returns the same top-K with the same per-factor score breakdown within FP tolerance. Drift is a regression — the parity test is the gate that prevents it.

What’s in scope vs out of scope (v0.7.0)

References

• Apache AGE 1.7.0 docs: https://age.apache.org/
• pgvector 0.8.2 docs: https://github.com/pgvector/pgvector
• ai-memory v0.7.0 release notes: v0.7.0/release-notes.md
• A2A campaign Pages: https://alphaonedev.github.io/ai-memory-a2a-v0.7.0/
• Adapter-selection design: RUNBOOK-adapter-selection.md
• Migration runbook: migration-v0.7.0-postgres.md
• F6 issue (in-flight Wave 1 closure): https://github.com/alphaonedev/ai-memory-mcp/issues/646