mem9

---

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.

2. Pick your integration guide.

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

3. 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