mem9

Persistent Memory for AI Agents. Your agents forget everything between sessions. mem9 fixes that with persistent memory across sessions and machines, shared memory for multi-agent workflows, and hybrid recall with a visual dashboard.

For OpenClaw and ClawHub installs, start here: mem9.ai/openclaw-memory Hermes Agent, Claude Code, OpenCode, Codex, DeepSeek Harness, and Dify guides are below.

Quick Start

1. Choose your mem9 endpoint.

• Hosted API: https://api.mem9.ai
• Self-hosted: apply the matching control-plane schema, then start mnemo-server:

cd server
     MNEMO_DSN="user:pass@tcp(host:4000)/mnemos?parseTime=true" go run ./cmd/mnemo-server

See Self-Hosting for backend-specific setup details, and API Reference for provisioning.

1. Pick your integration guide.

• OpenClaw / ClawHub
• Hermes Agent
• Claude Code
• OpenCode
• Codex
• DeepSeek Harness
• Dify
• Any HTTP client / custom runtime

1. Set your credentials.

# Hosted API
   export MEM9_API_URL="https://api.mem9.ai"
   export MEM9_API_KEY="<mem9-api-key>"

   # Self-hosted
   export MEM9_API_URL="http://localhost:8080"
   export MEM9_API_KEY="<mem9-api-key>"

For self-hosted deployments, use your server URL and the mem9 API key returned or configured by your provisioning flow.

Why mem9

mem9 gives coding agents one shared memory layer instead of separate local notebooks and one-off prompt files.

What mem9 gives you · Why it matters Persistent memory across sessions and machines · Your context survives restarts, laptop switches, and long-running projects Shared memory across agents and workflow platforms · OpenClaw, Hermes Agent, Claude Code, OpenCode, Codex, DeepSeek Harness, Dify apps, and custom clients can recall the same facts Stateless integrations · Runtime plugins stay thin because storage, search, ingest, and policy live in the server Hybrid recall and a visual dashboard · Semantic search, keyword search, and inspection workflows stay in one system

Supported Platforms and Agent Runtimes

Platform · Integration shape · Install / docs OpenClaw · kind: "memory" plugin for server-backed shared memory · OpenClaw / ClawHub install guide Hermes Agent · Memory provider plugin with setup and activation flow · mem9-hermes-plugin README Claude Code · Marketplace plugin with hooks and skills · claude-plugin/README.md OpenCode · Plugin SDK integration loaded from opencode.json · opencode-plugin/README.md Codex · Marketplace plugin with managed hooks and project overrides · codex-plugin/README.md DeepSeek Harness · Native DSH/Cordis bundle with recall, smart ingest, and memory tools · dsh-plugin/README.md Dify · Tool plugin for Dify Agent apps and Workflow apps, with single-space and multi-space authorization · mem9-dify-plugin README Any HTTP client / custom runtime · Direct REST API integration · API Reference

All supported runtimes and platform integrations expose the same core memory flow: store, search, get, update, and delete against the mem9 server API.

Why the Hosted API

The hosted mem9 API is the fastest way to put persistent memory behind an agent fleet while keeping the option to self-host later.

Hosted API capability · Why teams start here Hosted mem9 API with instant space provisioning · You can install an agent integration first and skip standing up infrastructure on day one Shared memory across runtimes and platforms · One space can serve OpenClaw, Hermes Agent, Claude Code, OpenCode, Codex, DeepSeek Harness, Dify apps, and custom clients together Managed search and storage · Hybrid recall works out of the box without a separate vector stack or sync layer TiDB Cloud Starter foundation · The hosted path benefits from instant provisioning, native vector search, full-text search, server-side auto-embedding, hybrid search, and MySQL-compatible operational semantics Same API contract as self-hosted mem9 · Moving to your own deployment is a base-URL and credential change, not a plugin rewrite Visual dashboard and product onboarding · Teams can inspect and manage memory without building internal tooling first

Under the hood, the hosted mem9 API runs the same mem9 server model surfaced in this repository, with TiDB Cloud Starter providing managed provisioning, native vector search, full-text search, server-side auto-embedding, hybrid search, and MySQL-compatible storage semantics.

API Reference

Set X-Mnemo-Agent-Id on authenticated memory, import, and session-message requests when you want the server to distinguish which runtime or agent instance is writing and recalling memories inside the same mem9 space. This works on both the tenant-path v1alpha1 routes and the v1alpha2 API-key routes.

Provisioning

Use this endpoint when you want mem9 to auto-provision a new TiDB-backed space.

Method · Path · Description POST · /v1alpha1/mem9s · TiDB auto-provision endpoint when a provisioner is configured. TiDB Zero enables this path by default on tidb; TiDB Cloud Pool uses MNEMO_TIDB_ZERO_ENABLED=false with MNEMO_TIDBCLOUD_API_KEY and MNEMO_TIDBCLOUD_API_SECRET. Manual-bootstrap deployments use pre-existing tenants instead of this path. Returns { "id" }. Accepts optional utm_* query params for attribution logging

Prefer v1alpha2 for all new integrations. It uses X-API-Key and is the primary API surface for current runtimes.

Preferred API (v1alpha2)

Method · Path · Description POST · /v1alpha2/mem9s/memories · Preferred unified write endpoint. Requires X-API-Key header GET · /v1alpha2/mem9s/memories · Preferred search endpoint. Requires X-API-Key header GET · /v1alpha2/mem9s/memories/{id} · Preferred get-by-id endpoint. Requires X-API-Key header PUT · /v1alpha2/mem9s/memories/{id} · Preferred update endpoint. Requires X-API-Key header DELETE · /v1alpha2/mem9s/memories/{id} · Preferred delete endpoint. Requires X-API-Key header GET/POST · /v1alpha2/mem9s/webhooks · Space webhook management. Requires a Space X-API-Key GET/PATCH/DELETE · /v1alpha2/mem9s/webhooks/{webhookID} · Get, update, or delete a Space webhook POST · /v1alpha2/mem9s/webhooks/{webhookID}/test · Queue a signed test delivery POST · /v1alpha2/mem9s/webhooks/{webhookID}/rotate-secret · Rotate the webhook signing secret. The new secret is returned once GET · /v1alpha2/mem9s/webhook-deliveries · List recent Space webhook deliveries GET/POST · /v1alpha2/space-chains/{chainID}/webhooks · Space Chain webhook management. Requires the chain_ management key in X-API-Key GET · /v1alpha2/space-chains/{chainID}/webhook-deliveries · List recent Space Chain webhook deliveries

Webhook events and delivery behavior are documented in docs/webhooks-api-design.md. v1 emits memory.added, memory.deleted, and space_chain.fact_routed.

Space Chain Management

Space Chains let you compose ordered multi-space recall and routing pipelines. Use the chain_ management key returned at creation time as the X-API-Key for all management endpoints below. Read nodes via their own Space X-API-Key.

Method · Path · Description POST · /v1alpha2/space-chains · Create a Space Chain. No X-API-Key required — the management key (chain_ prefix) is returned in the response body. All subsequent management endpoints require this key GET · /v1alpha2/space-chains/by-key · Look up a Space Chain by its management key. Requires the chain_ key in X-API-Key GET · /v1alpha2/space-chains/{chainID} · Get Space Chain details. Requires chain_ management key PATCH · /v1alpha2/space-chains/{chainID} · Update Space Chain name/description. Requires chain_ management key DELETE · /v1alpha2/space-chains/{chainID} · Soft-delete a Space Chain. Requires chain_ management key GET · /v1alpha2/space-chains/{chainID}/nodes · List all nodes in the chain (ordered by position). Requires chain_ management key PUT · /v1alpha2/space-chains/{chainID}/nodes · Replace all nodes in the chain (full replacement). Requires chain_ management key PUT · /v1alpha2/space-chains/{chainID}/nodes/{nodeID}/routing-policy · Update routing policy for a specific chain node. Requires chain_ management key GET · /v1alpha2/space-chains/{chainID}/bindings · List all API key bindings for the chain. Requires chain_ management key POST · /v1alpha2/space-chains/{chainID}/bindings · Create a new API key binding for the chain. Requires chain_ management key PATCH · /v1alpha2/space-chains/{chainID}/bindings/{bindingID} · Disable an API key binding. Requires chain_ management key

Additional v1alpha2 Endpoints

Method · Path · Description POST · /v1alpha2/mem9s/memories/batch-delete · Bulk soft-delete memories (max 1000). Accepts {"ids": ["..."]}. Requires X-API-Key GET · /v1alpha2/mem9s/session-messages · List persisted session messages. Requires X-API-Key. Query: session_id, limit_per_session POST · /v1alpha2/mem9s/imports · Upload a JSON file for async ingest (multipart, 50MB max). file_type: memory or session. Requires X-API-Key GET · /v1alpha2/mem9s/imports · List upload tasks with aggregate status. Requires X-API-Key GET · /v1alpha2/mem9s/imports/{id} · Get single upload task detail. Requires X-API-Key GET · /v1alpha2/status · Validate the X-API-Key header. Returns key status (active/inactive) without resolving a tenant

Legacy Tenant-Path API (v1alpha1)

Use these endpoints only when you need compatibility with older tenant-ID-in-path clients.

Method · Path · Description POST · /v1alpha1/mem9s/{tenantID}/memories · Legacy unified write endpoint. Tenant key travels in the URL path GET · /v1alpha1/mem9s/{tenantID}/memories · Legacy search endpoint for tenantID-configured clients GET · /v1alpha1/mem9s/{tenantID}/memories/{id} · Legacy get-by-id endpoint PUT · /v1alpha1/mem9s/{tenantID}/memories/{id} · Legacy update endpoint. Optional If-Match for version check DELETE · /v1alpha1/mem9s/{tenantID}/memories/{id} · Legacy delete endpoint

Self-Hosting

Before first start, apply the control-plane schema that matches your backend: server/schema.sql, server/schema_pg.sql, or server/schema_db9.sql.

mem9 server supports multiple storage backends. Set MNEMO_DB_BACKEND to tidb, postgres, or db9, point MNEMO_DSN at that backend, and the rest of the runtime contract stays the same for your agents. TiDB supports three tenant flows: TiDB Zero auto-provisioning is enabled by default on tidb; TiDB Cloud Pool auto-provisioning uses MNEMO_TIDB_ZERO_ENABLED=false with MNEMO_TIDBCLOUD_API_KEY and MNEMO_TIDBCLOUD_API_SECRET; manual bootstrap uses pre-existing tenants mode. postgres and db9 use the advanced manual-bootstrap path, which requires an active tenant row in the control-plane DB plus a live tenant database and schema behind it. In v1alpha2, X-API-Key resolves tenants by ID lookup.

Build & Run

make build
cd server
MNEMO_DSN="user:pass@tcp(host:4000)/mnemos?parseTime=true" ./bin/mnemo-server

For local development with automatic rebuild and restart on server source changes:

MNEMO_DSN="user:pass@tcp(host:4000)/mnemos?parseTime=true" make dev

For PostgreSQL or db9 deployments, export MNEMO_DB_BACKEND=postgres or MNEMO_DB_BACKEND=db9 before launching the server.

Docker

make docker tags the image as ${REGISTRY}/mnemo-server:${COMMIT}. This local example builds local/mnemo-server:dev:

make docker REGISTRY=local COMMIT=dev
docker run -e MNEMO_DSN="..." -e MNEMO_DB_BACKEND="tidb" -p 8080:8080 local/mnemo-server:dev

Environment Variables

Minimal runtime config is MNEMO_DSN. Everything else is optional or only applies to specific deployment modes.

Core Server

Variable · Required · Default · Description MNEMO_DSN · Yes · — · Database connection string MNEMO_PORT · No · 8080 · HTTP listen port MNEMO_DB_BACKEND · No · tidb · Database backend: tidb, postgres, or db9 MNEMO_RATE_LIMIT · No · 100 · Requests/sec per IP MNEMO_RATE_BURST · No · 200 · Burst size MNEMO_UPLOAD_DIR · No · ./uploads · Directory used for uploaded file storage MNEMO_WORKER_CONCURRENCY · No · 5 · Parallelism for async upload ingest workers MNEMO_UTM_ENABLED · No · false · Enable UTM campaign tracking. When enabled, utm_* query params on provisioning requests are stored in the control-plane DB. Requires the tenant_utm table to exist MNEMO_ENV · No · development · Deployment environment. Controls the default CORS origin set (https://mem9.ai in production; https://mem9.ai,http://localhost:4321,http://127.0.0.1:4321 in development). Also settable via APP_ENV MNEMO_CORS_ALLOWED_ORIGINS · No · https://mem9.ai in production; https://mem9.ai,http://localhost:4321,http://127.0.0.1:4321 in development · Comma-separated allowed CORS origins. Overrides the MNEMO_ENV-based defaults

Embedding And Ingest

For built-in multilingual embeddings on TiDB Cloud Starter (AWS), configure:

export MNEMO_EMBED_AUTO_MODEL=tidbcloud_free/cohere/embed-multilingual-v3
export MNEMO_EMBED_AUTO_DIMS=1024

New memory and session tables use Cohere's search_document input type and search_query for searches through TiDB's input_type@search option. The model has a 512-token / 2,048-character input limit; overlong inputs return an error rather than silently truncating stored facts. Existing generated columns keep their original model; use fresh Spaces for model comparisons or explicitly migrate/re-embed existing tables. VEC_EMBED_COSINE_DISTANCE follows each column's stored model/options, so changing this setting does not re-embed old Spaces. See TiDB Cohere Auto Embedding.

Variable · Required · Default · Description MNEMO_EMBED_AUTO_MODEL · No · — · TiDB/db9 EMBED_TEXT() model name. When set, it takes precedence over client-side embeddings MNEMO_EMBED_AUTO_DIMS · No · 1024 · Vector dimensions for MNEMO_EMBED_AUTO_MODEL MNEMO_EMBED_API_KEY · No · — · Client-side embedding provider API key. Optional for local OpenAI-compatible endpoints when MNEMO_EMBED_BASE_URL is set MNEMO_EMBED_BASE_URL · No · https://api.openai.com/v1 when client-side embeddings are enabled · Custom OpenAI-compatible embedding endpoint MNEMO_EMBED_MODEL · No · text-embedding-3-small · Client-side embedding model name MNEMO_EMBED_DIMS · No · 1536 · Client-side embedding vector dimensions MNEMO_LLM_API_KEY · No · — · LLM provider API key. If unset, smart ingest falls back to raw ingest behavior MNEMO_LLM_BASE_URL · No · https://api.openai.com/v1 when LLM ingest is enabled · Custom OpenAI-compatible chat endpoint MNEMO_LLM_MODEL · No · gpt-4o-mini · LLM model for smart ingest MNEMO_LLM_TEMPERATURE · No · 0.1 · LLM temperature for smart ingest MNEMO_INGEST_MODE · No · smart · Ingest mode: smart or raw MNEMO_FACT_EXTRACTION_INCLUDE_ASSISTANT · No · false · Include durable facts asserted in assistant turns during smart ingest; system and tool turns remain excluded MNEMO_DISABLE_SESSION_SAVE · No · false · Disable raw session row persistence for message ingest while still extracting and reconciling facts MNEMO_FTS_ENABLED · No · false · Enable TiDB full-text search path. Only set this on clusters that support TiDB FTS

Search Source Turns

The MEM9_SOURCE_TURN_* variables control how many source turn conversations are attached to search results as contextual decorations.

Variable · Required · Default · Description MEM9_SOURCE_TURN_MIN_SCORE · No · 2 · Minimum term-frequency relevance score for a source turn to be included in search result decorations MEM9_SOURCE_TURN_PER_MEMORY_LIMIT · No · 2 · Maximum source turns attached to a single memory in search results MEM9_SOURCE_TURN_TOTAL_LIMIT · No · 12 · Maximum total source turns across all memories in a single search response

Space Chain Recall

Variable · Required · Default · Description MNEMO_CHAIN_RECALL_STOP_SCORE · No · 0.8 · Stop querying later Space Chain nodes only when an eligible query has a top normalized confidence at or above this threshold. Raw search score values do not trigger chain stop. Must be between 0 and 1 MNEMO_RECALL_REQUEST_TIMEOUT · No · 1m · Total server-owned Recall request budget, including response assembly and write time MNEMO_RECALL_RESPONSE_RESERVE · No · 5s · Time reserved inside the Recall request budget for response assembly and write; must be shorter than MNEMO_RECALL_REQUEST_TIMEOUT

Provisioning And Pooling

Variable · Required · Default · Description MNEMO_TIDB_ZERO_ENABLED · No · true · Enable TiDB Zero auto-provisioning for tidb backend. When enabled, it takes precedence over TiDB Cloud Pool provisioning MNEMO_TIDB_ZERO_API_URL · No · https://zero.tidbapi.com/v1alpha1 · TiDB Zero API base URL MNEMO_TIDBCLOUD_API_URL · No · https://serverless.tidbapi.com · TiDB Cloud Pool API base URL MNEMO_TIDBCLOUD_POOL_ID · No · 2 · TiDB Cloud Pool ID used for cluster takeover MNEMO_TIDBCLOUD_API_KEY · No · — · TiDB Cloud Pool API key. Used only when MNEMO_TIDB_ZERO_ENABLED=false, MNEMO_DB_BACKEND=tidb, and pool takeover is desired MNEMO_TIDBCLOUD_API_SECRET · No · — · TiDB Cloud Pool API secret for digest auth. Same conditions as MNEMO_TIDBCLOUD_API_KEY MNEMO_TIDBCLOUD_PREFER_PRIVATELINK · No · false · Prefer the TiDB Cloud private endpoint during Pool provisioning when its AWS PrivateLink service name is configured below MNEMO_TIDBCLOUD_PRIVATELINK_SERVICE_NAMES · No · — · Comma-separated AWS PrivateLink service names that this mem9-server can reach. Provisioning falls back to the public endpoint when the returned service name is absent MNEMO_TENANT_POOL_MAX_IDLE · No · 5 · Max idle tenant database connections kept in the in-process tenant pool MNEMO_TENANT_POOL_MAX_OPEN · No · 10 · Max open connections per tenant database handle MNEMO_TENANT_POOL_CONNECT_TIMEOUT · No · 3s · Timeout for tenant pool cold-connect ping/open attempts MNEMO_TENANT_POOL_IDLE_TIMEOUT · No · 10m · Idle timeout for tenant database handles MNEMO_TENANT_POOL_TOTAL_LIMIT · No · 200 · Total tenant database handles allowed across the process MNEMO_CLUSTER_BLACKLIST · No · — · Comma-separated TiDB cluster IDs whose spend-limit errors should be translated to HTTP 429 instead of 503

Auto Spend Limit

These variables control automatic spend-limit increases for TiDB Cloud clusters that hit their cap. The feature progressively raises the limit up to MNEMO_AUTO_SPEND_LIMIT_MAX with a configurable cooldown between increments.

Variable · Required · Default · Description MNEMO_AUTO_SPEND_LIMIT_ENABLED · No · false · Enable automatic spend-limit increases for TiDB Cloud clusters. Requires valid MNEMO_TIDBCLOUD_API_KEY and MNEMO_TIDBCLOUD_API_SECRET MNEMO_AUTO_SPEND_LIMIT_INCREMENT · No · 500 · Amount to increase the spend limit by each step (in USD cents: 500 = $5.00) MNEMO_AUTO_SPEND_LIMIT_MAX · No · 10000 · Maximum spend limit allowed (in USD cents: 10000 = $100.00). Must be greater than the increment MNEMO_AUTO_SPEND_LIMIT_COOLDOWN · No · 1h · Minimum time between consecutive spend-limit increases for the same cluster

Metering

These variables configure the legacy server-side API metering writer. It emits mem9-api events for successful recall and ingest operations and is separate from runtime usage quota metering.

Metering location is configured as a single destination URL. Supported schemes are:

• s3://// for compressed JSON batches in S3
• http://... or https://... for JSON batch webhooks

Variable · Required · Default · Description MNEMO_METERING_ENABLED · No · false · Enable the metering writer. When false, the writer is a no-op MNEMO_METERING_URL · No · — · Metering destination URL. Supported forms: s3:////, http://..., or https://.... If empty, the writer stays disabled even when MNEMO_METERING_ENABLED=true MNEMO_METERING_FLUSH_INTERVAL · No · 10s · In-memory batch flush interval for the metering writer

Runtime Usage Quota And Metering

Runtime usage is disabled by default. When enabled, the server reserves quota before memory recall/write operations, releases reservations after failed operations, commits reservations after successful operations, and sends console metering events to the runtime usage service. This path uses MNEMO_RUNTIME_USAGE_BASE_URL and does not use MNEMO_METERING_URL.

The runtime usage outbox uses the control-plane runtime_usage_outbox table for pending reservation finalization and metering delivery. It is enabled by default when runtime usage is enabled.

Reservation retries require one of these exact responses with details.retryable: true: 409 registry_conflict; 429 operation_in_progress, 429 registry_busy, or 429 reservation_concurrency_limited with a positive decimal integer-