Skip to main content

Kubernetes / Helm — OSS recipe

Production-shape OSS deployment of memledger on Kubernetes via the Helm chart. The chart bundles a Postgres + pgvector StatefulSet, a schema-migration Job, and the memledger configuration.

What gets deployed​

ComponentShape
memledger-pgvector-0StatefulSet — Postgres 17 + pgvector
memledger-migration-*Job — runs the SQL migration that creates agent_memory, indexes, and the HNSW vector index
Service: memledger-pgvectorClusterIP DNS for the agent pods
Secret: kagent-db-credentialsPostgres user / password (auto-generated when database.deploy=true)

A single Helm release is enough to write and search governed memories from any pod in the cluster.

Prerequisites​

  • kubectl ≥ 1.30
  • helm ≥ 3.14
  • A Kubernetes cluster with a default StorageClass (the Postgres StatefulSet provisions one PVC per replica)
Helm chart access

The Helm chart ships in the memledger-core repository under charts/memledger. Repository access is on the launch roadmap; until then, contact the maintainers for the chart tarball or use the values reference below to build an equivalent manifest.

Install​

Set $MEMLEDGER_CHART to the local path of the chart, then:

helm upgrade --install memledger "$MEMLEDGER_CHART" \
  --namespace <your-namespace> --create-namespace \
  --set database.deploy=true \
  --set database.migration.enabled=true \
  --set database.migration.tableName=agent_memory \
  --set database.migration.vectorDimensions=1024 \
  --set embeddings.provider=local \
  --set memledger.defaultBackend=pgvector \
  --wait --timeout 5m

Expected: STATUS: deployed.

Verify the schema​

kubectl exec -n <your-namespace> memledger-pgvector-0 -- \
  psql -U memledger -d memledger -c "\d agent_memory"

You should see the agent_memory table with columns including embedding vector(1024), confidence, hedged, derived_from text[], supersedes, created_by, workflow_id, triggered_by, plus an HNSW index on embedding.

Connect your agent​

From inside the cluster, the DSN is:

postgresql://memledger:<password>@memledger-pgvector.<your-namespace>.svc.cluster.local:5432/memledger

The password lives in the auto-generated kagent-db-credentials Secret. Mount it on your agent pod and read it from the environment:

import os
from memledger import Memledger
from memledger.models import EmbeddingConfig

ml = await Memledger.create(
    backend_name="pgvector",
    connection_string=os.environ["MEMLEDGER_PG_DSN"],
    embedding_config=EmbeddingConfig(provider="local"),
)

For Bedrock embeddings instead of local fastembed, set --set embeddings.provider=bedrock --set embeddings.model=amazon.titan-embed-text-v2:0 at install time and use EmbeddingConfig(provider="bedrock", model="amazon.titan-embed-text-v2:0", dimensions=1024) from the SDK.

External Postgres alternative​

If you already operate Postgres (RDS, Crunchy, Cloud SQL, anything with pgvector ≥ 0.5), set database.deploy=false and point at the existing instance:

helm upgrade --install memledger "$MEMLEDGER_CHART" \
  --namespace <your-namespace> --create-namespace \
  --set database.deploy=false \
  --set database.host=<your-pg-host> \
  --set database.port=5432 \
  --set database.existingSecret=<your-pg-secret> \
  --set database.secretKey=password \
  --set database.migration.enabled=true \
  --set database.migration.tableName=agent_memory \
  --set database.migration.vectorDimensions=1024 \
  --wait --timeout 5m

For Aurora PostgreSQL with IAM authentication (no static password), see Aurora PostgreSQL.

Rollback​

helm uninstall memledger -n <your-namespace>
kubectl delete pvc -n <your-namespace> -l app.kubernetes.io/name=memledger

The migration Job is idempotent on re-install; the PVCs are not, which is why the second kubectl delete is explicit.

Next steps​