Skip to content
 
 

Repository files navigation

mem9

Persistent Memory for AI Agents.
Your agents forget everything between sessions. mem9 fixes that.

Powered by TiDB Cloud Starter Go Report Card License Stars


🚀 Quick Start

Server-based memory via mem9-server.

  1. Deploy mnemo-server.

    cd server && MNEMO_DSN="user:pass@tcp(host:4000)/mnemos?parseTime=true" go run ./cmd/mnemo-server
  2. Install the plugin for your agent (pick one).

    Platform Install
    Claude Code /plugin marketplace add mem9-ai/mem9 then /plugin install mem9@mem9
    OpenCode Add "plugin": ["@mem9/opencode"] to opencode.json
    OpenClaw Add mnemo to openclaw.json plugins (see openclaw-plugin/README)
  3. Provision a tenant and set credentials.

    curl -s -X POST localhost:8080/v1alpha1/mem9s
    # → {"id":"..."}
    
    export MEM9_API_URL="http://localhost:8080"
    export MEM9_API_KEY="..."

    All agents pointing at the same tenant ID share one memory pool.


The Problem

AI coding agents — Claude Code, OpenCode, OpenClaw, and others — often maintain separate local memory files. As a result:

  • 🧠 Amnesia — Agents forget everything when a session ends
  • 🏝️ Silos — One agent can't access what another learned yesterday
  • 📁 Local files — Memory is tied to a single machine, lost when you switch devices
  • 🚫 No team sharing — Your teammate's agent can't benefit from your agent's discoveries

mnemos gives every agent a shared, cloud-persistent memory with hybrid vector + keyword search — powered by TiDB Cloud Starter.

Why TiDB Cloud Starter?

mnemos uses TiDB Cloud Starter (formerly TiDB Cloud Serverless) as the backing store for mnemo-server:

Feature What it means for you
Free tier 25 GiB storage, 250M Request Units/month — enough for most individual and small team use
TiDB Cloud Zero Instant database provisioning via API — no signup required for first 30 days
Native VECTOR type Hybrid search (vector + keyword) without a separate vector database
Auto-embedding (EMBED_TEXT) TiDB generates embeddings server-side — no OpenAI key needed for semantic search
Zero ops No servers to manage, no scaling to worry about, automatic backups
MySQL compatible Migrate to self-hosted TiDB or MySQL anytime

This architecture keeps agent plugins stateless — all state lives in mnemo-server, backed by TiDB.

Supported Agents

mnemos provides native plugins for major AI coding agent platforms:

Platform Plugin How It Works Install Guide
Claude Code Hooks + Skills Auto-loads memories on session start, auto-saves on stop claude-plugin/README.md
OpenCode Plugin SDK system.transform injects memories, session.idle auto-captures opencode-plugin/README.md
OpenClaw Memory Plugin Replaces built-in memory slot (kind: "memory"), framework manages lifecycle openclaw-plugin/README.md
Any HTTP client REST API curl to mnemo-server API Reference

All plugins expose the same 5 tools: memory_store, memory_search, memory_get, memory_update, memory_delete.

Note

🤖 For AI Agents: Use the Quick Start above to deploy mnemo-server and provision an API key, then follow the platform-specific README for configuration details.

Stateless Agents, Cloud Memory

A key design principle: agent plugins carry zero state. All memory lives in mnemo-server, backed by TiDB/MySQL. This means:

  • Agent plugins stay stateless — deploy any number of agent instances freely; they all share the same memory pool via mnemo-server
  • Switch machines freely — your agent's memory follows you, not your laptop
  • Multi-agent collaboration — Claude Code, OpenCode, OpenClaw, and any HTTP client share memories when pointed at the same server
  • Centralized control — rate limits and audit live in one place

API Reference

Agent identity: X-Mnemo-Agent-Id header.

Method Path Description
POST /v1alpha1/mem9s Provision tenant (no auth). Returns { "id" }.
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.
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.

Self-Hosting

Environment Variables

Variable Required Default Description
MNEMO_DSN Yes Database connection string
MNEMO_PORT No 8080 HTTP listen port
MNEMO_RATE_LIMIT No 100 Requests/sec per IP
MNEMO_RATE_BURST No 200 Burst size
MNEMO_EMBED_API_KEY No Embedding provider API key
MNEMO_EMBED_BASE_URL No OpenAI Custom embedding endpoint
MNEMO_EMBED_MODEL No text-embedding-3-small Model name
MNEMO_EMBED_DIMS No 1536 Vector dimensions

Build & Run

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

Docker

docker build -t mnemo-server ./server
docker run -e MNEMO_DSN="..." -p 8080:8080 mnemo-server

Project Structure

mnemos/
├── server/                     # Go API server
│   ├── cmd/mnemo-server/       # Entry point
│   ├── internal/
│   │   ├── config/             # Env var config loading
│   │   ├── domain/             # Core types, errors, token generation
│   │   ├── embed/              # Embedding provider (OpenAI/Ollama/any)
│   │   ├── handler/            # HTTP handlers + chi router
│   │   ├── middleware/         # Auth + rate limiter
│   │   ├── repository/         # Interface + TiDB SQL implementation
│   │   └── service/            # Business logic (upsert, LWW, hybrid search)
│   ├── schema.sql
│   └── Dockerfile
│
├── opencode-plugin/            # OpenCode agent plugin (TypeScript)
│   └── src/                    # Plugin SDK tools + hooks + server backend
│
├── openclaw-plugin/            # OpenClaw agent plugin (TypeScript)
│   ├── index.ts                # Tool registration
│   └── server-backend.ts       # Server: fetch → mnemo API
│
├── claude-plugin/              # Claude Code plugin (Hooks + Skills)
│   ├── hooks/                  # Lifecycle hooks (bash + curl)
│   └── skills/                 # memory-recall + memory-store + mnemos-setup
│
├── skills/                     # Shared skills (OpenClaw ClawHub format)
│   └── mnemos-setup/           # Setup skill
│
├── docs/DESIGN.md              # Full design document
└── docs/BENCHMARK.md           # A/B benchmark pipeline guide

Roadmap

Phase What Status
Phase 1 Core server + CRUD + auth + hybrid search + upsert + plugins ✅ Done
Phase 3 LLM-assisted conflict merge, auto-tagging 🔜 Planned
Phase 4 Web dashboard, bulk import/export, CLI wizard 📋 Planned

Vector Clock CRDT was deferred and removed from the roadmap.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

Apache-2.0


TiDB Starter
Built with TiDB Starter — zero-ops database with native vector search.

About

Unlimited memory for OpenClaw

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages